docs: 建立本地开发与验证指南 (#2)

Local-Development-and-Verification.-.md

@@ -0,0 +1,77 @@
+# 本地开发与验证
+
+## 本页用途
+
+让维护者能够安装、运行、检查和验证项目。所有命令默认在仓库根目录执行，示例以 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 scripts/check_harness.py --strict`
+- 预期：输出“DevHarness 检查通过”。
+- 失败检查：按错误提示检查缺失页面、未填占位符或损坏的镜像头。
+
+### 3. 运行测试
+
+- 目的：验证同步、路径和安全保护。
+- 命令：`python -m unittest discover -s tests -v`
+- 预期：所有测试显示 `ok`。
+- 失败检查：先单独运行失败测试，再查看最近修改的对应脚本。
+
+### 4. 对照线上 Wiki
+
+- 目的：确认本地 docs 是最新镜像。
+- 命令：`python scripts/sync_wiki_docs.py --check`
+- 预期：所有映射显示“一致”。
+- 失败检查：先读取线上页面；确认页面名、revision、网络和 `GITEA_URL`。
+
+## 常用调试方式
+
+- 只检查 Python 语法：`python -m py_compile scripts/*.py`。
+- 查看一个脚本帮助：`python 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 scripts/check_harness.py --strict
+python scripts/sync_wiki_docs.py --check
+git diff --check
+git status --short
+```
+
+无法执行的命令必须写入工单“未验证部分”。