dev_harness/docs/01-workflow.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Development-Workflow wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Development-Workflow.- wiki_revision: ae9f9aac5df77f1e3e1c2a34bd00c849c1f63cbf synchronized_at: 2026-08-07T15:54:03Z

开发工作流

事实来源边界

• Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。
• Gitea Wiki 保存架构说明、开发规范、操作手册和完成后的任务归档。
• Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
• 本地 docs/ 仅供浏览和审查，不是长期文档编辑入口。

一次任务怎样完成

1. 讨论

用户描述需求或故障。Agent 先检查现状，再给出目标、非目标、方案、风险、回退和验证方法。存在不同实现方向时，说明取舍并等待用户确认。

2. 建单

方案确认后，使用 .gitea/issue_template/task.md 创建单元任务工单。没有工单号之前不修改产品代码或正式文档。

新产品或较大版本先建立 Epic，再建立 MVP：

[Epic] 产品或长期目标
└── [MVP] 第一个可交付版本
    ├── #101 单元任务
    ├── #102 单元任务
    └── #103 单元任务

每个单元任务都应目标单一，能够独立测试、提交和回退。

3. 实施

Agent 检查分支和工作区，只修改工单范围内的文件。发现新问题时先记录到工单；如果不影响当前验收，则另建工单，不扩大当前任务。

重要进度及时写回工单：

• 已确认的根因；
• 方案或范围变化；
• 测试结果；
• 阻塞和未验证内容；
• Git 提交哈希；
• 相关 Wiki 页面及 revision。

长期文档遵循唯一顺序：

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

不得先编辑 docs/ 再反向覆盖 Wiki。

4. 待验收

实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。

5. 归档和关闭

使用以下命令在 Wiki 创建任务归档页、登记显式映射并导出本地镜像：

python scripts/new_task_archive.py 123 "修复登录超时"

归档内容以 Wiki 页面为主源；本地 docs/task/<编号>-<短标题>.md 是镜像。归档镜像单独提交，再把 Wiki 页面、revision、镜像路径和提交哈希写回工单。用户明确验收通过后，关闭单元工单并勾选父工单中的任务。

文档同步规则

• 映射保存在 wiki-docs.json，每个 Wiki 页面对应唯一仓库路径。
• 同步脚本只实现 Wiki → docs/，不提供反向同步。
• 镜像头必须记录页面名、页面地址、revision 和同步时间。
• 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。
• --check 只检查，不写文件；页面缺失、revision 不一致或正文不一致均失败。
• 页面删除和重命名不会自动传播，必须先更新工单并人工确认映射变化。
• Wiki 更新成功而导出失败时，在工单记录部分完成状态，不得把任务标为完成。
• 与具体代码版本强绑定的接口或迁移资料可直接随代码维护，但必须在 Wiki 提供入口或适用版本说明。

什么时候重新确认方案

以下变化必须先更新工单，再由用户确认：

• 交付结果或用户操作发生变化；
• 增加或删除接口、数据库字段或迁移；
• 安全边界、权限或不可逆操作发生变化；
• 原方案不可行，需要更换主要技术路线；
• 任务范围明显扩大；
• Wiki 页面删除、重命名或事实源边界改变。

普通内部实现细节不需要反复确认，但重要取舍应记录在工单中。

工单、Wiki 与 Git 分别写什么

信息	Gitea 工单	Gitea Wiki	Git / docs 镜像
讨论过程和临时方案	是	否	否
实施进度和阻塞	是	否	否
长期有效的最终方案	链接	是	镜像
测试结果与未验证内容	是	任务归档	镜像
提交哈希	是	任务归档	镜像
与具体代码版本绑定的说明	可链接	提供入口	是