95 lines
4.8 KiB
Markdown
95 lines
4.8 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||
wiki_page: Home
|
||
wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Home
|
||
wiki_revision: 52e9a6f8fe4fe03db8c65792ef500cc9a5084384
|
||
synchronized_at: 2026-08-16T11:18:48Z
|
||
<!-- gitea-wiki-mirror:end -->
|
||
|
||
# DevHarness 文档中心
|
||
|
||
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.-)；向已有项目增量接入本流程时阅读[已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-)。需要为客户或其他岗位准备说明时，阅读[交付文档指南](Delivery-Documentation-Guide.-)，再按需使用[岗位文档模板](Audience-Document-Template.-)。
|
||
|
||
## 五分钟开始
|
||
|
||
在仓库根目录执行：
|
||
|
||
```powershell
|
||
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 映射显示“一致”。
|
||
|
||
如果失败，先看[故障排查](Troubleshooting)，不要直接重置工作区或覆盖本地文档。
|
||
|
||
## 简单修改从哪里开始
|
||
|
||
| 想做什么 | 先读哪里 | 主要验证 |
|
||
|---|---|---|
|
||
| 修改文档 | 对应 Wiki 页面、Common-Changes | Wiki 同步检查 |
|
||
| 接入已有项目 | Existing-Project-Adoption-Guide | 只读盘点、差异确认和分阶段验证 |
|
||
| 准备交付文档 | Delivery-Documentation-Guide、Audience-Document-Template | 目标岗位验证和 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 镜像 |
|
||
| 完整任务归档 | Gitea Wiki；`docs/task/` 仅是人工按需导出的快照 |
|
||
|
||
本地 `docs/` 不是编辑入口。长期文档必须先修改 Wiki，读取确认后再导出镜像。
|
||
|
||
## 项目入口
|
||
|
||
- [Gitea 工单](http://ilaer.eicp.net:8418/opc/dev_harness/issues)
|
||
- [代码仓库](http://ilaer.eicp.net:8418/opc/dev_harness)
|
||
- [已有项目接入 DevHarness 指南](Existing-Project-Adoption-Guide.-)
|
||
- [交付文档指南](Delivery-Documentation-Guide.-)
|
||
- [岗位文档模板](Audience-Document-Template.-)
|
||
- [任务归档模板](Task-Archive-Template.-)
|
||
|
||
## 同步原则
|
||
|
||
```text
|
||
修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像
|
||
```
|
||
|
||
- 核心页面和本地路径通过仓库中的 `wiki-docs.json` 显式映射；普通同步不处理任务归档。
|
||
- 任务归档默认只保存在 Wiki，只有用户明确提出时才增量或全量导出到 `docs/task/`。
|
||
- 镜像头记录来源页面、Wiki revision 和同步时间。
|
||
- 已映射镜像存在未提交修改时同步必须停止。
|
||
- 页面删除、重命名和映射变更必须人工确认。
|
||
- 核心 Wiki 或必要同步失败时，相关任务不能标记为完成；未请求任务归档导出不阻止任务完成。
|
||
- 凭据、个人数据和生产数据不得进入 Wiki 或镜像。
|