架构与代码地图

本页用途

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

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

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`	页面名、本地路径	`sync_wiki_docs.py --check`	中
Wiki API 和镜像生成	`dev_scripts/wiki_docs.py`	`WikiClient`、`sync_all`	配置、页面、镜像元数据	`tests/test_wiki_docs.py`	中
手动同步入口	`dev_scripts/sync_wiki_docs.py`	`main()`	`--check`	线上 Wiki 对照检查	低
任务归档	`dev_scripts/new_task_archive.py`	`main()`	创建页面、登记映射	单元测试和正式归档	中
Harness 结构检查	`dev_scripts/check_harness.py`	`main()`	必需文件、镜像、归档检查	`--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-<编号>-<标题> 页面
→ 追加显式页面映射
→ 导出 docs/task 镜像
→ 提交镜像并回写工单

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