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