90 lines
3.9 KiB
Markdown
90 lines
3.9 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
|
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
|
wiki_page: Architecture-and-Code-Map
|
|
wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Architecture-and-Code-Map.-
|
|
wiki_revision: 06542b54af9954c186b10ba8cd5f923d501c6018
|
|
synchronized_at: 2026-08-25T00:40:31Z
|
|
<!-- 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` | 页面名、本地路径 | `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 镜像
|
|
|
|
```text
|
|
wiki-docs.json
|
|
→ WikiClient 列出并解析页面
|
|
→ 读取 Markdown 与 last_commit.sha
|
|
→ 检查本地镜像是否有未提交修改
|
|
→ 写入来源、URL、revision、同步时间
|
|
→ --check 对照正文和 revision
|
|
```
|
|
|
|
### 可选任务快照
|
|
|
|
```text
|
|
用户或项目专用规则明确要求专项快照
|
|
→ 读取 Wiki 归档模板
|
|
→ 创建 Task-<编号>-<标题> 页面并链接原工单
|
|
→ 按需 export 到 docs/task
|
|
```
|
|
|
|
默认任务流程不调用这条路径。单次任务的需求、实现、测试、提交和验收保存在 Gitea 工单；既有归档和导出功能仅用于历史兼容或明确的专项快照。
|
|
|
|
## 修改影响判断
|
|
|
|
| 修改内容 | 通常还要检查 |
|
|
|---|---|
|
|
| 修改 Agent 工作流 | `README.md`、`CLAUDE.md`、Development-Workflow、工单模板 |
|
|
| 修改 Wiki 页面名称 | `wiki-docs.json`、Home 链接、同步测试；必须人工确认 |
|
|
| 修改镜像格式 | 解析器、检查器、已有镜像、单元测试 |
|
|
| 增加核心文档 | Wiki、显式映射、Home、Harness 必需页面检查 |
|
|
| 修改归档字段 | Wiki 归档模板、归档脚本、归档检查和测试 |
|
|
|
|
## 不可破坏的边界
|
|
|
|
- 工单管理单次任务，Wiki 管理长期文档，Git 管理代码和版本绑定资料；可选任务快照不是默认事实来源。
|
|
- `docs/` 不是长期文档编辑入口。
|
|
- 同步只允许写入 `docs/` 下的 Markdown。
|
|
- 页面删除、重命名和本地脏镜像不能被静默处理。
|
|
- 凭据不得进入代码、Wiki、工单、日志或镜像。
|