From 3f86864cecb0600e3b20631b6677446dbc259927 Mon Sep 17 00:00:00 2001 From: ila Date: Sat, 8 Aug 2026 08:56:28 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BB=BA=E7=AB=8B=E6=9E=B6=E6=9E=84?= =?UTF-8?q?=E4=B8=8E=E4=BB=A3=E7=A0=81=E5=9C=B0=E5=9B=BE=20(#2)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Architecture-and-Code-Map.-.md | 80 ++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 Architecture-and-Code-Map.-.md diff --git a/Architecture-and-Code-Map.-.md b/Architecture-and-Code-Map.-.md new file mode 100644 index 0000000..71f3f2c --- /dev/null +++ b/Architecture-and-Code-Map.-.md @@ -0,0 +1,80 @@ +# 架构与代码地图 + +## 本页用途 + +帮助第一次接触项目的人回答三个问题： + +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、工单、日志或镜像。