3.0 KiB
3.0 KiB
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 不使用生产数据，也不需要固定业务测试数据。命令输出是主要诊断信息，不应包含令牌。如果复制到业务项目，应在本节写明：
- 合成或脱敏测试数据的创建方式；
- 日志路径和日志级别；
- 请求或任务标识如何追踪；
- 禁止使用的数据来源。
完成修改前
依次执行：
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
无法执行的命令必须写入工单“未验证部分”。