3.7 KiB
3.7 KiB
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Home wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Home wiki_revision: f1baf5947fe4e8f08cfc3ccc129946964fbbc3e5 synchronized_at: 2026-08-08T01:16:46Z
DevHarness 文档中心
DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期开发文档、以 Git 记录代码变更的 AI 辅助开发模板。目标是让初级程序员能够理解项目、运行验证，并在 Claude/Codex Agent 协助下处理简单 Bug 和需求。
第一次阅读
建议按以下顺序，用 10～20 分钟建立整体认识：
- 项目档案：项目目标、环境、命令和目录边界。
- 架构与代码地图：功能从哪里开始读、测试在哪里。
- 业务规则与术语：重要名词、状态和不能破坏的规则。
- 本地开发与验证：怎样运行、测试和排错。
- 常见修改指南：简单修改的步骤和停止条件。
- 故障排查：遇到错误时按什么顺序检查。
- 开发工作流：完整建单、实施、验收和归档流程。
从模板创建新项目时先阅读新项目文档初始化。
五分钟开始
在仓库根目录执行：
git status --short --branch
python dev_scripts/check_harness.py --strict
python -m unittest discover -s tests -v
python dev_scripts/sync_wiki_docs.py --check
预期结果：
- 工作区没有不属于当前任务的修改；
- Harness 输出“DevHarness 检查通过”；
- 所有单元测试通过；
- 所有 Wiki 映射显示“一致”。
如果失败，先看故障排查，不要直接重置工作区或覆盖本地文档。
简单修改从哪里开始
| 想做什么 | 先读哪里 | 主要验证 |
|---|---|---|
| 修改文档 | 对应 Wiki 页面、Common-Changes | Wiki 同步检查 |
| 调整工单字段 | .gitea/issue_template/、Development-Workflow |
Harness 严格检查 |
| 修改同步行为 | dev_scripts/wiki_docs.py、Architecture-and-Code-Map |
单元测试和真实 Wiki 检查 |
| 增加结构检查 | dev_scripts/check_harness.py |
成功与失败测试 |
| 排查运行错误 | Troubleshooting、项目档案 | 最小复现命令 |
权限、安全、并发、迁移、支付、删除数据或不可逆操作不属于简单修改，必须停止并交给 Agent 分析、等待人工确认。
事实来源
| 信息 | 事实来源 |
|---|---|
| 任务状态、讨论、阻塞、验收过程 | Gitea 工单 |
| 架构、业务规则、开发规范、操作手册、任务归档 | Gitea Wiki |
| 源码和与特定代码版本强绑定的文档 | Git 仓库 |
| 离线浏览副本 | Git 仓库中的 docs/ Wiki 镜像 |
本地 docs/ 不是编辑入口。长期文档必须先修改 Wiki，读取确认后再导出镜像。
项目入口
同步原则
修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像
- 页面和本地路径通过仓库中的
wiki-docs.json显式映射。 - 镜像头记录来源页面、Wiki revision 和同步时间。
- 已映射镜像存在未提交修改时同步必须停止。
- 页面删除、重命名和映射变更必须人工确认。
- Wiki 或导出失败时，相关任务不能标记为完成。
- 凭据、个人数据和生产数据不得进入 Wiki 或镜像。