本地开发与验证

本页用途

让维护者能够安装、运行、检查和验证项目。所有命令默认在仓库根目录执行，示例以 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 dev_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

无法执行的命令必须写入工单“未验证部分”。