generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Local-Development-and-Verification wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Local-Development-and-Verification.- wiki_revision: 43ad9c6ee3f4172059133cca05124f4018267c1e synchronized_at: 2026-08-08T01:16:53Z # 本地开发与验证 ## 本页用途 让维护者能够安装、运行、检查和验证项目。所有命令默认在仓库根目录执行，示例以 Windows PowerShell 为主。 ## 环境要求 | 工具 | 用途 | 检查命令 | |---|---|---| | Git | 版本管理和脏文件保护 | `git --version` | | Python 3 | Harness 脚本和测试 | `python --version` | | Gitea 连接 | 工单和 Wiki | 浏览仓库或调用 MCP | | Gitea PAT | 写 Wiki 时使用 | 仅通过 MCP 安全配置或 `GITEA_TOKEN` 提供 | 不要打印或提交 PAT。 ## 第一次运行 ### 1. 检查工作区 - 目的：确认没有混入其他任务的修改。 - 命令：`git status --short --branch` - 预期：显示当前分支；开始新任务时没有无关文件。 - 失败检查：确认变更归属，不要擅自重置或覆盖。 ### 2. 检查 Harness - 目的：验证必需文件、项目档案、Wiki 映射和归档结构。 - 命令：`python dev_scripts/check_harness.py --strict` - 预期：输出“DevHarness 检查通过”。 - 失败检查：按错误提示检查缺失页面、未填占位符或损坏的镜像头。 ### 3. 运行测试 - 目的：验证同步、路径和安全保护。 - 命令：`python -m unittest discover -s tests -v` - 预期：所有测试显示 `ok`。 - 失败检查：先单独运行失败测试，再查看最近修改的对应脚本。 ### 4. 对照线上 Wiki - 目的：确认本地 docs 是最新镜像。 - 命令：`python dev_scripts/sync_wiki_docs.py --check` - 预期：所有映射显示“一致”。 - 失败检查：先读取线上页面；确认页面名、revision、网络和 `GITEA_URL`。 ## 常用调试方式 - 只检查 Python 语法：`python -m compileall -q scripts tests`。 - 查看一个脚本帮助：`python dev_scripts/sync_wiki_docs.py --help`。 - 查看未提交差异：`git diff --check` 和 `git diff`。 - 查看最近提交：`git log -5 --oneline`。 - 调试失败测试时优先运行单个测试文件，不要先修改多个模块。 ## 测试数据与日志 DevHarness 不使用生产数据，也不需要固定业务测试数据。命令输出是主要诊断信息，不应包含令牌。如果复制到业务项目，应在本节写明： - 合成或脱敏测试数据的创建方式； - 日志路径和日志级别； - 请求或任务标识如何追踪； - 禁止使用的数据来源。 ## 完成修改前 依次执行： ```powershell python -m unittest discover -s tests -v python dev_scripts/check_harness.py --strict python dev_scripts/sync_wiki_docs.py --check git diff --check git status --short ``` 无法执行的命令必须写入工单“未验证部分”。