Table of Contents

DevHarness 文档中心

第一次阅读
五分钟开始
简单修改从哪里开始
事实来源
项目入口
同步原则

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

DevHarness 文档中心

DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期开发文档、以 Git 记录代码变更的 AI 辅助开发模板。目标是让初级程序员能够理解项目、运行验证，并在 Claude/Codex Agent 协助下处理简单 Bug 和需求。

第一次阅读

建议按以下顺序，用 10～20 分钟建立整体认识：

项目档案：项目目标、环境、命令和目录边界。
架构与代码地图：功能从哪里开始读、测试在哪里。
业务规则与术语：重要名词、状态和不能破坏的规则。
本地开发与验证：怎样运行、测试和排错。
常见修改指南：简单修改的步骤和停止条件。
故障排查：遇到错误时按什么顺序检查。
开发工作流：完整建单、实施、验收和归档流程。

从模板创建新项目时先阅读新项目文档初始化；向已有项目增量接入本流程时阅读已有项目接入 DevHarness 指南。需要为客户或其他岗位准备说明时，阅读交付文档指南，再按需使用岗位文档模板。

五分钟开始

在仓库根目录执行：

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 同步检查
接入已有项目	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，读取确认后再导出镜像。

项目入口

同步原则

修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像

核心页面和本地路径通过仓库中的 wiki-docs.json 显式映射；普通同步不处理任务归档。
任务归档默认只保存在 Wiki，只有用户明确提出时才增量或全量导出到 docs/task/。
镜像头记录来源页面、Wiki revision 和同步时间。
已映射镜像存在未提交修改时同步必须停止。
页面删除、重命名和映射变更必须人工确认。
核心 Wiki 或必要同步失败时，相关任务不能标记为完成；未请求任务归档导出不阻止任务完成。
凭据、个人数据和生产数据不得进入 Wiki 或镜像。