feat: 建立初级维护者文档体系 (#2)

2026-08-08 09:00:44 +08:00
parent 3aa73fcb1e
commit 250b0555e4
16 changed files with 798 additions and 27 deletions
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Project-Profile
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Project-Profile.-
-wiki_revision: 845266496196a4fc33462dfda779d0f899fa4c18
-synchronized_at: 2026-08-07T15:53:58Z
+wiki_revision: df33a1ce9d25d28866e20d942799a5d01fcec935
+synchronized_at: 2026-08-08T00:58:02Z
 <!-- gitea-wiki-mirror:end -->

 # 项目档案
@@ -16,17 +16,31 @@ synchronized_at: 2026-08-07T15:53:58Z
 |---|---|
 | 项目名称 | DevHarness |
 | 一句话目标 | 提供以 Gitea 工单、Wiki 和 Git 为事实来源的 AI 辅助开发工作流模板 |
+| 主要使用者 | 项目负责人、Claude/Codex Agent、接手简单维护的初级程序员 |
 | Gitea 地址 | http://ilaer.eicp.net:8418 |
 | 仓库 | `opc/dev_harness` |
 | 默认分支 | `main` |
 | 主要维护者 | `ila` |
+| 文档适用范围 | 默认分支当前版本；具体镜像 revision 见每个本地文件头 |

-## 技术栈
+## 技术栈与运行环境

 | 部分 | 技术 | 规则文件 |
 |---|---|---|
-| Harness 规则和模板 | Markdown、Gitea | `AGENTS.md` |
+| Harness 规则和模板 | Markdown、Gitea 1.25 | `AGENTS.md` |
 | Wiki 镜像与结构检查 | Python 3 标准库 | `AGENTS.md` |
+| 主要开发环境 | Windows、PowerShell、Git | `AGENTS.md` |
+
+本项目不需要安装第三方 Python 包。复制到业务项目后，必须把真实语言、框架、版本和支持平台写入本节。
+
+## 阅读入口
+
+- 新人入口：Home。
+- 代码入口：[架构与代码地图](Architecture-and-Code-Map.-)。
+- 业务边界：[业务规则与术语](Business-Rules-and-Glossary.-)。
+- 运行验证：[本地开发与验证](Local-Development-and-Verification.-)。
+- 简单维护：[常见修改指南](Common-Changes.-)。
+- 错误定位：[故障排查](Troubleshooting)。

 ## 常用命令

@@ -34,6 +48,7 @@ synchronized_at: 2026-08-07T15:53:58Z

 | 用途 | 命令 | 预期结果 |
 |---|---|---|
+| 查看工作区 | `git status --short --branch` | 显示分支且没有无关修改 |
 | 检查模板结构 | `python scripts/check_harness.py --strict` | 输出“DevHarness 检查通过” |
 | 运行单元测试 | `python -m unittest discover -s tests -v` | 所有测试通过 |
 | 导出 Wiki 镜像 | `python scripts/sync_wiki_docs.py` | 映射页面写入 `docs/` |
@@ -50,19 +65,24 @@ synchronized_at: 2026-08-07T15:53:58Z
 | `scripts/` | Harness 检查、Wiki 同步和归档工具 | 产品功能代码 |
 | `tests/` | Harness 工具自动化测试 | 生产数据 |

-## 环境与凭据
+## 环境、配置与凭据

 - Wiki 同步配置：仓库根目录 `wiki-docs.json`。
 - Gitea 地址可由配置提供，也可通过 `GITEA_URL` 覆盖。
- Gitea Personal Access Token 仅通过 `GITEA_TOKEN` 环境变量提供，不写入仓库。
- Token 至少需要读取仓库权限；创建 Wiki 任务归档时还需要写仓库权限。
- 日志和构建产物：本项目不持久化运行日志；Python 缓存不提交。
+- Gitea PAT 仅通过 `GITEA_TOKEN` 或 MCP 安全配置提供，不写入仓库。
+- Token 至少需要读取仓库权限；创建或更新 Wiki 时还需要写仓库权限。
+- 配置示例：`wiki-docs.json` 只保存非敏感仓库信息。
+- 日志：本项目不持久化运行日志，命令行错误是主要诊断信息。
+- 测试数据：只使用测试构造的字符串、路径和模拟响应，不使用生产数据。
+- 构建产物：Python 缓存和临时文件不提交。

 ## 项目专用验收要求

 - 长期文档必须先更新 Wiki，再导出本地镜像。
 - 镜像必须包含来源页面、revision 和同步时间。
 - 页面删除、重命名和映射变更必须人工确认。
+- 新增核心文档时必须更新 Home、显式映射和 Harness 检查。
+- 代码入口、命令、配置、业务规则或排错方式变化时必须评估文档影响。
 - `python scripts/check_harness.py --strict` 必须通过。
 - `python -m unittest discover -s tests -v` 必须通过。
 - 未执行或无法覆盖的验证必须记录到工单。
@@ -2,8 +2,8 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Development-Workflow
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Development-Workflow.-
-wiki_revision: ae9f9aac5df77f1e3e1c2a34bd00c849c1f63cbf
-synchronized_at: 2026-08-07T15:54:03Z
+wiki_revision: af4c1cbdd73cf9f6df971415487e2664e227ebc9
+synchronized_at: 2026-08-08T00:58:03Z
 <!-- gitea-wiki-mirror:end -->

 # 开发工作流
@@ -83,6 +83,44 @@ python scripts/new_task_archive.py 123 "修复登录超时"
 - Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。
 - 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。

+## 面向初级维护者的修改边界
+
+| 风险 | 示例 | 处理方式 |
+|---|---|---|
+| 低 | 文案、简单校验、查询条件、独立 UI、小范围回归 Bug | 初级程序员可在 Agent 协助下理解、修改和验证 |
+| 中 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员检查差异并执行验证 |
+| 高 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 |
+
+风险由影响范围决定，不按代码行数判断。
+
+## 每个任务的文档影响
+
+单元任务必须明确选择：
+
+- 不影响长期文档，并说明原因；
+- 更新项目档案或运行验证；
+- 更新架构与代码地图；
+- 更新业务规则与术语；
+- 更新常见修改或故障排查；
+- 新增或调整其他 Wiki 页面。
+
+以下变化必须更新相关 Wiki：
+
+- 启动、测试、部署或排错命令变化；
+- 模块入口、目录职责或主要调用路径变化；
+- 配置项、API、数据结构或状态变化；
+- 业务规则、安全边界或权限变化；
+- 日志位置、错误定位或常见处理方式变化。
+
+普通内部重构如果入口、行为、配置和验证方式均未改变，可以记录“不影响长期文档”及原因。
+
+## 稳定文档与任务归档
+
+- Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。
+- 工单和任务归档解释某次为什么修改、实际改了什么以及如何验证。
+- 新人先读稳定主题页，只有追查历史原因时才读任务归档。
+- 任务产生的长期结论必须合并到主题页，不能只留在归档。
+
 ## 什么时候重新确认方案

 以下变化必须先更新工单，再由用户确认：
@@ -0,0 +1,88 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Architecture-and-Code-Map
+wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Architecture-and-Code-Map.-
+wiki_revision: 3f86864cecb0600e3b20631b6677446dbc259927
+synchronized_at: 2026-08-08T00:58:04Z
+<!-- gitea-wiki-mirror:end -->
+
+# 架构与代码地图
+
+## 本页用途
+
+帮助第一次接触项目的人回答三个问题：
+
+1. 项目由哪些部分组成；
+2. 一个功能应该从哪里开始读；
+3. 修改后应该运行哪些验证。
+
+阅读代码前先看本页；目录、入口或主要数据流变化时必须更新本页。
+
+## 项目定位
+
+DevHarness 不是业务应用，而是一套开发工作流模板。它约束 Agent 和维护者如何讨论需求、建立工单、修改代码、更新 Wiki、测试、提交、验收和归档。
+
+```text
+用户确认方案
+→ Gitea 单元任务工单
+→ Agent 修改代码与测试
+→ 长期结论更新 Wiki
+→ Wiki 单向导出 docs 镜像
+→ Git 提交并回写工单
+→ 用户验收
+```
+
+## 代码地图
+
+| 能力 | 路径 | 阅读入口 | 主要对象或函数 | 验证位置 | 风险 |
+|---|---|---|---|---|---|
+| Agent 工作规则 | `AGENTS.md` | “需求到实施” | 工作流条款 | 人工审查、Harness 检查 | 高 |
+| 工单结构 | `.gitea/issue_template/` | `task.md` | Epic、MVP、Task 模板 | 创建测试工单或检查模板 | 中 |
+| Wiki 页面映射 | `wiki-docs.json` | `mappings` | 页面名、本地路径 | `sync_wiki_docs.py --check` | 中 |
+| Wiki API 和镜像生成 | `scripts/wiki_docs.py` | `WikiClient`、`sync_all` | 配置、页面、镜像元数据 | `tests/test_wiki_docs.py` | 中 |
+| 手动同步入口 | `scripts/sync_wiki_docs.py` | `main()` | `--check` | 线上 Wiki 对照检查 | 低 |
+| 任务归档 | `scripts/new_task_archive.py` | `main()` | 创建页面、登记映射 | 单元测试和正式归档 | 中 |
+| Harness 结构检查 | `scripts/check_harness.py` | `main()` | 必需文件、镜像、归档检查 | `--strict` | 中 |
+| 本地文档镜像 | `docs/` | `docs/README.md` | 生成元数据和 Wiki 正文 | 同步检查 | 低 |
+| 自动化测试 | `tests/` | `test_wiki_docs.py` | 映射、同步和安全边界 | `unittest discover` | 低 |
+
+## 两条主要执行路径
+
+### Wiki 镜像
+
+```text
+wiki-docs.json
+→ WikiClient 列出并解析页面
+→ 读取 Markdown 与 last_commit.sha
+→ 检查本地镜像是否有未提交修改
+→ 写入来源、URL、revision、同步时间
+→ --check 对照正文和 revision
+```
+
+### 任务归档
+
+```text
+读取 Wiki 归档模板
+→ 创建 Task-<编号>-<标题> 页面
+→ 追加显式页面映射
+→ 导出 docs/task 镜像
+→ 提交镜像并回写工单
+```
+
+## 修改影响判断
+
+| 修改内容 | 通常还要检查 |
+|---|---|
+| 修改 Agent 工作流 | `README.md`、`CLAUDE.md`、Development-Workflow、工单模板 |
+| 修改 Wiki 页面名称 | `wiki-docs.json`、Home 链接、同步测试；必须人工确认 |
+| 修改镜像格式 | 解析器、检查器、已有镜像、单元测试 |
+| 增加核心文档 | Wiki、显式映射、Home、Harness 必需页面检查 |
+| 修改归档字段 | Wiki 归档模板、归档脚本、归档检查和测试 |
+
+## 不可破坏的边界
+
+- 工单管理过程，Wiki 管理长期文档，Git 管理代码和镜像。
+- `docs/` 不是长期文档编辑入口。
+- 同步只允许写入 `docs/` 下的 Markdown。
+- 页面删除、重命名和本地脏镜像不能被静默处理。
+- 凭据不得进入代码、Wiki、工单、日志或镜像。
@@ -0,0 +1,61 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Business-Rules-and-Glossary
+wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Business-Rules-and-Glossary.-
+wiki_revision: 7534fd60157096dab2c6f06214acfff84d1a5370
+synchronized_at: 2026-08-08T00:58:06Z
+<!-- gitea-wiki-mirror:end -->
+
+# 业务规则与术语
+
+## 本页用途
+
+解释 DevHarness 中容易混淆的术语、状态和不可破坏的流程规则。新项目复制模板后，应把项目自身的业务术语、状态和关键约束补充到本页。
+
+## 核心术语
+
+| 术语 | 含义 | 不要误解为 |
+|---|---|---|
+| Epic | 完整产品目标和长期路线 | 可以直接实施的单个任务 |
+| MVP | 第一个可交付范围及集成边界 | 任意里程碑名称 |
+| 单元任务 | 唯一正式实施单位，可独立测试和回退 | 临时聊天待办 |
+| 事实来源 | 某类信息被正式维护的位置 | 多处内容可以随意覆盖 |
+| Wiki 主源 | 长期开发文档首先修改的位置 | 本地 docs 的备份副本 |
+| docs 镜像 | 从 Wiki 单向生成的浏览副本 | 可以直接编辑并反向同步的文档 |
+| 待验收 | 实现和测试已完成，等待用户确认 | 已完成并可关闭 |
+| 未验证部分 | 本次无法真实覆盖的行为 | 可以省略的测试备注 |
+
+## 工单状态
+
+| 状态 | 含义 | 可以进入下一状态的条件 |
+|---|---|---|
+| 待确认 | 目标或方案仍需用户选择 | 用户明确确认方案 |
+| 待实施 | 方案已确认，尚未修改 | 工作区和范围检查完成 |
+| 进行中 | 正在实现、测试或同步文档 | 验收标准逐项检查完成 |
+| 阻塞 | 满足规则定义的持续阻塞条件 | 阻塞解除并更新工单 |
+| 待验收 | 代码、测试、归档和证据已完成 | 用户明确验收 |
+| 已完成 | 用户已验收并完成父任务同步 | 无 |
+
+## 稳定业务规则
+
+- 没有确认方案和单元任务工单，不修改产品行为。
+- 一个单元任务只解决一个可独立验证和回退的问题。
+- 需求、接口、数据、安全边界或验收标准变化时先更新工单。
+- 长期文档必须先修改 Wiki，再导出本地镜像。
+- 测试结果必须真实；未执行的验证必须明确记录。
+- 用户未明确验收前，工单保持开启。
+- 初级程序员可以理解和验证低风险修改，但高风险决策仍由 Agent 分析并等待人工确认。
+
+## 新项目需要补充什么
+
+复制模板后，至少补充：
+
+- 项目的用户和核心目标；
+- 业务名词及容易混淆的概念；
+- 主要对象和状态；
+- 关键状态流转；
+- 必须始终满足的业务规则；
+- 数据保留、权限和安全边界；
+- 典型输入、输出和失败示例。
+
+业务规则必须由项目负责人确认，Agent 可以整理和举例，但不能根据代码自行臆造。
@@ -0,0 +1,85 @@
+<!-- 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: 537da98a775da39323cb101a717d003705a97761
+synchronized_at: 2026-08-08T00:58:08Z
+<!-- 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 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
+```
+
+无法执行的命令必须写入工单“未验证部分”。
@@ -0,0 +1,78 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Common-Changes
+wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Common-Changes.-
+wiki_revision: 2c41287656577564fc7b78b6cf8554ce81e16003
+synchronized_at: 2026-08-08T00:58:10Z
+<!-- gitea-wiki-mirror:end -->
+
+# 常见修改指南
+
+## 本页用途
+
+帮助初级程序员在 Claude/Codex Agent 协助下处理简单 Bug 和小需求。这里说明常见入口、验证方法和停止条件，不代替工单和方案确认。
+
+## 风险分级
+
+| 等级 | 常见修改 | 处理方式 |
+|---|---|---|
+| 低风险 | 文案、简单校验、查询条件、独立 UI、小范围回归 Bug | 初级程序员可在 Agent 协助下修改和验证 |
+| 中风险 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员理解差异并执行验证 |
+| 高风险 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 |
+
+“代码行数少”不等于低风险。
+
+## 修改 Wiki 文案
+
+1. 在相关工单确认目标。
+2. 读取线上 Wiki 页面和当前 revision。
+3. 修改线上 Wiki，不直接编辑 `docs/`。
+4. 运行 `python scripts/sync_wiki_docs.py`。
+5. 运行 `python scripts/sync_wiki_docs.py --check`。
+6. 审查本地镜像差异并提交。
+
+停止条件：页面需要删除、重命名或改变事实源边界。
+
+## 增加工单字段
+
+1. 阅读 `.gitea/issue_template/task.md` 和 Development-Workflow。
+2. 判断字段是否影响所有任务，避免只为一个任务增加永久字段。
+3. 修改模板和对应流程说明。
+4. 为 Harness 检查增加或调整测试。
+5. 创建一份示例工单草稿检查可读性。
+
+停止条件：字段改变权限、审批或关闭条件。
+
+## 调整 Harness 检查
+
+1. 从 `scripts/check_harness.py` 的 `main()` 开始读。
+2. 新检查应输出具体文件和缺失内容。
+3. 检查结构事实，不声称自动判断文档语义质量。
+4. 在 `tests/` 添加成功和失败用例。
+5. 运行严格检查及全部测试。
+
+停止条件：检查会删除、重写文件或依赖生产环境。
+
+## 修复 Wiki 同步 Bug
+
+1. 从 `scripts/wiki_docs.py` 的 `WikiClient`、`parse_mirror` 和 `sync_all` 开始读。
+2. 先编写能复现问题的测试。
+3. 保持 Wiki → docs 单向关系。
+4. 验证中文、路径编码、revision 和脏文件保护。
+5. 使用测试页面验证时，不删除正式页面。
+
+停止条件：需要自动删除/重命名页面、覆盖本地未提交修改或输出令牌。
+
+## 看懂 Agent 的修改
+
+审查时至少回答：
+
+- 这次解决了哪个工单目标；
+- 修改入口和调用路径在哪里；
+- 有哪些行为变化；
+- 增加或修改了哪些测试；
+- 哪些内容没有验证；
+- 是否更新了受影响的 Wiki 页面；
+- 怎样回退。
+
+回答不了时，让 Agent补充说明，不要仅凭“测试通过”验收。
@@ -0,0 +1,40 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: Troubleshooting
+wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Troubleshooting
+wiki_revision: e1a806bb8c6b6c32a4e271c94a9bcaaed36003db
+synchronized_at: 2026-08-08T00:58:12Z
+<!-- gitea-wiki-mirror:end -->
+
+# 故障排查
+
+## 本页用途
+
+按“现象 → 原因 → 检查 → 处理”定位 DevHarness 常见问题。处理后如果形成稳定结论，应更新本页；临时过程记录在工单。
+
+| 现象 | 常见原因 | 检查方法 | 处理 |
+|---|---|---|---|
+| `--strict` 提示项目档案未填写 | 新项目仍有占位内容 | 搜索 `<填写` | 先在 Wiki 填写真实内容，再导出镜像 |
+| 同步提示镜像有未提交改动 | 有人直接修改 docs，或上次镜像尚未提交 | `git status --short -- docs` | 确认来源；保留人工内容并先更新 Wiki，不要强制覆盖 |
+| Wiki 页面不存在 | 页面未创建、标题或映射错误 | 查看 Wiki 页面列表和 `wiki-docs.json` | 修正明确的页面或映射；不要自动删除本地文件 |
+| API 路径出现重复 `/api/v1` | `GITEA_URL` 已包含 API 后缀 | 查看非敏感 URL 配置 | 同步器会规范化；新工具也应接受两种写法 |
+| 公共仓库读取返回 401/403/404 | 环境令牌失效或属于其他实例 | 不打印令牌；尝试浏览公开页面 | 只读请求可安全降级匿名；写请求必须使用正确 PAT |
+| 中文 Wiki 页面读取 404 | `sub_url` 被重复百分号编码 | 查看页面列表返回的 `sub_url` | 保留已有 `%`，不要再次编码 |
+| Wiki 页面标题多出 `.-` | Gitea 1.25 的页面规范路径或更新时未显式传标题 | 对照页面 title 和 `sub_url` | 更新中文页面时显式保留原 title；不要猜测路径 |
+| `--check` 正文不一致 | Wiki 已更新但镜像未导出，或本地被修改 | 对照 revision 和 Git 差异 | 确认 Wiki 后运行正式同步 |
+| 单元测试能过但真实同步失败 | 测试使用模拟数据，网络或 Gitea 行为不同 | 查看工单“未验证部分” | 增加最小真实验证并记录服务端版本 |
+| Git 工作区包含无关修改 | 同时存在其他任务或人工工作 | `git status --short` | 保留并隔离无关修改，不重置用户工作 |
+
+## 排查顺序
+
+1. 读取完整错误信息，不只看最后一行。
+2. 检查当前工单、分支和工作区。
+3. 检查项目档案中的真实命令和环境。
+4. 用最小命令复现。
+5. 对照最近提交和 Wiki revision。
+6. 修复后增加回归测试或稳定排错条目。
+7. 无法验证的部分写回工单。
+
+## 必须停止的情况
+
+出现凭据泄露、数据损坏风险、权限边界变化、不可逆操作或不明来源的工作区改动时，立即停止并说明影响，不继续尝试破坏性修复。
@@ -0,0 +1,99 @@
+<!-- gitea-wiki-mirror:start -->
+generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
+wiki_page: New-Project-Documentation-Setup
+wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/New-Project-Documentation-Setup.-
+wiki_revision: 1745db81541e94200309dc2136ff15ce4349fa3f
+synchronized_at: 2026-08-08T00:58:14Z
+<!-- gitea-wiki-mirror:end -->
+
+# 新项目文档初始化
+
+## 本页用途
+
+从 DevHarness 创建新项目时，指导 Claude/Codex Agent快速建立可供初级程序员阅读的项目文档。初始化只生成可靠的第一版，不允许 Agent 臆造业务规则、凭据、部署环境或生产数据。
+
+## 初始化顺序
+
+### 1. 建立项目边界
+
+由项目负责人确认：
+
+- 项目名称和一句话目标；
+- 用户和主要使用场景；
+- 技术栈和支持环境；
+- Gitea 仓库、默认分支和维护者；
+- 安全、权限、数据和发布红线。
+
+把项目专用红线写入根目录或子目录 `AGENTS.md`。
+
+### 2. 建立 Gitea
+
+创建远端仓库并完成允许的初始引导提交。开启工单和 Wiki。任何产品功能开发在引导提交后都必须先有单元任务工单。
+
+### 3. 修改镜像配置
+
+把 `wiki-docs.json` 中的地址、owner 和 repository 改成新项目。移除属于 DevHarness 自身的任务归档映射；核心主题映射保留。
+
+不要把 PAT 写入配置。
+
+### 4. Agent 检查项目事实
+
+Agent 只读检查：
+
+- README、配置和依赖文件；
+- 启动入口；
+- 主要模块和目录规则；
+- 测试、格式和静态检查命令；
+- 日志、示例配置和测试数据；
+- 已存在的接口、数据模型和状态。
+
+区分“代码中确认的事实”“负责人确认的业务规则”和“仍待确认的假设”。
+
+### 5. 先创建线上 Wiki
+
+至少创建或填写：
+
+1. Home；
+2. Project-Profile；
+3. Architecture-and-Code-Map；
+4. Business-Rules-and-Glossary；
+5. Local-Development-and-Verification；
+6. Common-Changes；
+7. Troubleshooting；
+8. Development-Workflow；
+9. Task-Archive-Template。
+
+Home 给出建议阅读顺序；每个命令必须有预期结果；代码地图必须指出入口和测试位置。
+
+### 6. 人工确认
+
+项目负责人至少确认：
+
+- 一句话目标和业务术语；
+- 关键业务规则和状态；
+- 权限、安全和数据边界；
+- 真实运行、测试和部署命令；
+- 哪些修改属于高风险。
+
+### 7. 导出镜像并检查
+
+```powershell
+python scripts/sync_wiki_docs.py
+python scripts/check_harness.py --strict
+python scripts/sync_wiki_docs.py --check
+python -m unittest discover -s tests -v
+```
+
+只有线上 Wiki 确认后才导出 `docs/`。旧项目的任务归档不能带入新项目历史。
+
+## 完成标准
+
+初级程序员应能仅依靠 Home 和链接页面回答：
+
+- 项目解决什么问题；
+- 怎样启动和运行测试；
+- 常用功能从哪个目录和入口开始读；
+- 一个简单修改通常要改哪里、验证什么；
+- 哪些情况必须停止并交给 Agent 或负责人。
+
+回答不了的问题应继续补充主题文档，而不是堆入任务归档。
@@ -2,44 +2,86 @@
 generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
 wiki_page: Home
 wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Home
-wiki_revision: 448de2a90fc237f6d5df6a5e8da1f94df2665a30
-synchronized_at: 2026-08-07T15:57:30Z
+wiki_revision: 6cd3fccc78501c8be5bea6cd05d53799be4c6bd7
+synchronized_at: 2026-08-08T00:58:01Z
 <!-- gitea-wiki-mirror:end -->

 # DevHarness 文档中心

-DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期开发文档、以 Git 记录代码变更的 AI 辅助开发模板。
+DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期开发文档、以 Git 记录代码变更的 AI 辅助开发模板。目标是让初级程序员能够理解项目、运行验证，并在 Claude/Codex Agent 协助下处理简单 Bug 和需求。
+
+## 第一次阅读
+
+建议按以下顺序，用 10～20 分钟建立整体认识：
+
+1. [项目档案](Project-Profile.-)：项目目标、环境、命令和目录边界。
+2. [架构与代码地图](Architecture-and-Code-Map.-)：功能从哪里开始读、测试在哪里。
+3. [业务规则与术语](Business-Rules-and-Glossary.-)：重要名词、状态和不能破坏的规则。
+4. [本地开发与验证](Local-Development-and-Verification.-)：怎样运行、测试和排错。
+5. [常见修改指南](Common-Changes.-)：简单修改的步骤和停止条件。
+6. [故障排查](Troubleshooting)：遇到错误时按什么顺序检查。
+7. [开发工作流](Development-Workflow.-)：完整建单、实施、验收和归档流程。
+
+从模板创建新项目时先阅读[新项目文档初始化](New-Project-Documentation-Setup.-)。
+
+## 五分钟开始
+
+在仓库根目录执行：
+
+```powershell
+git status --short --branch
+python scripts/check_harness.py --strict
+python -m unittest discover -s tests -v
+python scripts/sync_wiki_docs.py --check
+```
+
+预期结果：
+
+- 工作区没有不属于当前任务的修改；
+- Harness 输出“DevHarness 检查通过”；
+- 所有单元测试通过；
+- 所有 Wiki 映射显示“一致”。
+
+如果失败，先看[故障排查](Troubleshooting)，不要直接重置工作区或覆盖本地文档。
+
+## 简单修改从哪里开始
+
+| 想做什么 | 先读哪里 | 主要验证 |
+|---|---|---|
+| 修改文档 | 对应 Wiki 页面、Common-Changes | Wiki 同步检查 |
+| 调整工单字段 | `.gitea/issue_template/`、Development-Workflow | Harness 严格检查 |
+| 修改同步行为 | `scripts/wiki_docs.py`、Architecture-and-Code-Map | 单元测试和真实 Wiki 检查 |
+| 增加结构检查 | `scripts/check_harness.py` | 成功与失败测试 |
+| 排查运行错误 | Troubleshooting、项目档案 | 最小复现命令 |
+
+权限、安全、并发、迁移、支付、删除数据或不可逆操作不属于简单修改，必须停止并交给 Agent 分析、等待人工确认。

 ## 事实来源

 | 信息 | 事实来源 |
 |---|---|
 | 任务状态、讨论、阻塞、验收过程 | Gitea 工单 |
-| 架构说明、开发规范、操作手册、任务归档 | Gitea Wiki |
+| 架构、业务规则、开发规范、操作手册、任务归档 | Gitea Wiki |
 | 源码和与特定代码版本强绑定的文档 | Git 仓库 |
 | 离线浏览副本 | Git 仓库中的 `docs/` Wiki 镜像 |

 本地 `docs/` 不是编辑入口。长期文档必须先修改 Wiki，读取确认后再导出镜像。

-## 文档入口
+## 项目入口

- [项目档案](Project-Profile.-)
- [开发工作流](Development-Workflow.-)
- [任务归档模板](Task-Archive-Template.-)
 - [Gitea 工单](http://ilaer.eicp.net:8418/opc/dev_harness/issues)
 - [代码仓库](http://ilaer.eicp.net:8418/opc/dev_harness)
+- [任务归档模板](Task-Archive-Template.-)

 ## 同步原则

-固定顺序：
-
 ```text
 修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像
 ```

 - 页面和本地路径通过仓库中的 `wiki-docs.json` 显式映射。
 - 镜像头记录来源页面、Wiki revision 和同步时间。
- 同步工具发现已跟踪镜像存在未提交修改时必须停止。
- 页面删除、重命名和映射变更必须人工确认，不自动传播。
+- 已映射镜像存在未提交修改时同步必须停止。
+- 页面删除、重命名和映射变更必须人工确认。
 - Wiki 或导出失败时，相关任务不能标记为完成。
 - 凭据、个人数据和生产数据不得进入 Wiki 或镜像。