架构与代码地图

本页用途

帮助第一次接触项目的人回答三个问题：

阅读代码前先看本页；目录、入口或主要数据流变化时必须更新本页。

DevHarness 不是业务应用，而是一套开发工作流模板。它约束 Agent 和维护者如何讨论需求、建立工单、修改代码、更新 Wiki、测试、提交和验收，并在明确需要时创建专项快照。

用户确认方案
→ Gitea 单元任务工单
→ Agent 修改代码与测试
→ 长期结论更新 Wiki
→ Wiki 单向导出 docs 镜像
→ Git 提交并回写工单
→ 用户验收

能力	路径	阅读入口	主要对象或函数	验证位置	风险
Agent 工作规则	`AGENTS.md`	“需求到实施”	工作流条款	人工审查、Harness 检查	高
工单结构	`.gitea/issue_template/`	`task.md`	Epic、MVP、Task 模板	创建测试工单或检查模板	中
Wiki 页面映射	`wiki-docs.json`	`mappings`	页面名、本地路径	`harness.py sync --check`	中
Wiki API 和镜像生成	`dev_scripts/wiki_docs.py`	`WikiClient`、`sync_all`	配置、页面、镜像元数据	`tests/test_wiki_docs.py`	中
同步与校验	`dev_scripts/harness.py`	`run_sync()`	`sync [--check] [--verify]`	线上 Wiki 对照检查	低
可选任务快照	`dev_scripts/harness.py`	`run_archive()`	`archive <编号> <短标题>`	单元测试和显式专项归档	中
Harness 结构检查	`dev_scripts/harness.py`	`run_check()`	必需文件、镜像和已有快照检查	`check --strict`	中
本地文档镜像	`docs/`	`docs/README.md`	生成元数据和 Wiki 正文	同步检查	低
自动化测试	`tests/`	`test_wiki_docs.py`	映射、同步和安全边界	`unittest discover`	低

wiki-docs.json
→ WikiClient 列出并解析页面
→ 读取 Markdown 与 last_commit.sha
→ 检查本地镜像是否有未提交修改
→ 写入来源、URL、revision、同步时间
→ --check 对照正文和 revision

用户或项目专用规则明确要求专项快照
→ 读取 Wiki 归档模板
→ 创建 Task-<编号>-<标题> 页面并链接原工单
→ 按需 export 到 docs/task

默认任务流程不调用这条路径。单次任务的需求、实现、测试、提交和验收保存在 Gitea 工单；既有归档和导出功能仅用于历史兼容或明确的专项快照。

修改内容	通常还要检查
修改 Agent 工作流	`README.md`、`CLAUDE.md`、Development-Workflow、工单模板
修改 Wiki 页面名称	`wiki-docs.json`、Home 链接、同步测试；必须人工确认
修改镜像格式	解析器、检查器、已有镜像、单元测试
增加核心文档	Wiki、显式映射、Home、Harness 必需页面检查
修改归档字段	Wiki 归档模板、归档脚本、归档检查和测试