dev_harness/docs/04-local-development-and-verification.md

<!-- gitea-wiki-mirror:start -->
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
<!-- gitea-wiki-mirror:end -->

# 本地开发与验证

## 本页用途

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

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