docs: 精简单人任务事实来源并分级工程基线 (#25)
This commit is contained in:
+34
-29
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Development-Workflow
|
||||
wiki_url: https://git.ilapage.cn/OPC/dev_harness/wiki/Development-Workflow.-
|
||||
wiki_revision: 98acbf90ebad7a515f1a805defe6d963e5153e48
|
||||
synchronized_at: 2026-08-19T01:51:50Z
|
||||
wiki_revision: 5a79c3a71235e802484c8f5bd19bda37ccde8e46
|
||||
synchronized_at: 2026-08-24T08:55:25Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 开发工作流
|
||||
@@ -11,7 +11,7 @@ synchronized_at: 2026-08-19T01:51:50Z
|
||||
## 事实来源边界
|
||||
|
||||
- Gitea 工单记录任务状态、讨论、阻塞、方案变化、验证和验收。
|
||||
- Gitea Wiki 保存架构说明、开发规范、操作手册和完成后的任务归档。
|
||||
- Gitea Wiki 保存长期架构、契约、业务规则、开发规范、操作手册和稳定需求；默认不重复保存单次任务归档。
|
||||
- Git 保存源码、与特定代码版本强绑定的文档，以及 Wiki 的本地镜像。
|
||||
- 本地 `docs/` 仅供浏览和审查，不是长期文档编辑入口。
|
||||
|
||||
@@ -133,41 +133,45 @@ Agent 检查分支和工作区，只修改工单范围内的文件。发现新
|
||||
- Git 提交哈希；
|
||||
- 相关 Wiki 页面及 revision。
|
||||
|
||||
长期核心文档遵循唯一顺序：
|
||||
工单正文保存用户确认的任务基线；根因、范围、方案、风险或阻塞发生重要变化时追加评论。完成实现后用一条评论集中记录最终差异、测试、未验证内容、提交哈希和长期文档影响，保留可追溯时间线，不在 Wiki 重抄同一份任务结果。
|
||||
|
||||
只有长期事实发生变化时才执行核心文档闭环：
|
||||
|
||||
```text
|
||||
修改 Wiki → 读取确认 → 导出核心 docs → 校验差异 → 提交镜像
|
||||
```
|
||||
|
||||
任务归档默认只更新 Wiki，不自动导出到 `docs/task/`。不得先编辑本地镜像再反向覆盖 Wiki。
|
||||
没有长期文档影响时，在工单写明原因并跳过 Wiki 更新、核心镜像同步和任务归档。长期文档仍不得先编辑本地镜像再反向覆盖 Wiki。
|
||||
|
||||
### 4. 待验收
|
||||
|
||||
实现和测试完成后，Agent 提交实现代码并将工单更新为“待验收”。用户验收前工单保持开启。
|
||||
|
||||
### 5. 归档和关闭
|
||||
### 5. 待验收和关闭
|
||||
|
||||
使用以下命令只在 Wiki 创建任务归档页：
|
||||
实现、必要测试和提交完成后，在工单追加一条最终证据评论并保持“待验收”。评论至少记录最终差异、测试结果、未验证内容、提交哈希，以及长期 Wiki 页面和 revision，或“无长期文档影响”及原因。
|
||||
|
||||
用户明确验收通过后：
|
||||
|
||||
1. 在工单追加验收时间和结论，不重复抄写已有测试与提交证据；
|
||||
2. 关闭单元工单并勾选所属 MVP/Epic 子任务；
|
||||
3. 只有验收结论改变长期需求状态或其他 Wiki 事实时，才更新 Wiki 并执行同步闭环；没有变化时不重复检查 Wiki；
|
||||
4. 默认不创建或导出任务归档。
|
||||
|
||||
任务归档只保留为显式兼容能力。只有用户明确要求专项快照，或项目专用规则明确要求时才运行：
|
||||
|
||||
```powershell
|
||||
python dev_scripts/harness.py archive 123 "修复登录超时"
|
||||
python dev_scripts/harness.py export # 增量导出已有归档
|
||||
python dev_scripts/harness.py export --all # 全量导出已有归档
|
||||
```
|
||||
|
||||
归档内容以 Wiki 页面为事实来源。默认不修改 `wiki-docs.json`，也不写入 `docs/task/`。把 Wiki 页面、revision 和实现提交哈希写回工单；用户明确验收通过后，关闭单元工单并勾选父工单中的任务。
|
||||
|
||||
只有用户明确提出时才导出任务归档：
|
||||
|
||||
```powershell
|
||||
python dev_scripts/harness.py export # 增量：新增或 revision 变化
|
||||
python dev_scripts/harness.py export --all # 全量：读取全部线上任务归档
|
||||
```
|
||||
|
||||
导出不得自动删除本地文件。`docs/task/` 只是人工按需生成的只读快照，可能不是完整或最新的任务历史。
|
||||
可选归档不得成为第二个日常维护入口；创建时以工单中的最终证据为来源，并记录工单链接。既有 Wiki 归档和 `docs/task/` 快照不自动删除、重命名或补齐。
|
||||
|
||||
## 文档同步规则
|
||||
|
||||
- 核心页面映射保存在 `wiki-docs.json`；普通同步只处理这些核心长期文档。
|
||||
- 任务归档不逐页登记映射，由按需导出工具根据 `Task-<编号>-<标题>` 动态发现；已有镜像优先按镜像头匹配原页面。
|
||||
- 可选任务归档不逐页登记映射；显式执行归档导出时，工具根据 `Task-<编号>-<标题>` 动态发现，已有镜像优先按镜像头匹配原页面。
|
||||
- 所有同步和导出只实现 Wiki → `docs/`，不提供反向同步。
|
||||
- 镜像头必须记录页面名、页面地址、revision 和同步时间。
|
||||
- 已跟踪镜像存在未提交改动时，同步必须停止；确认改动来源后再处理。
|
||||
@@ -228,20 +232,20 @@ python dev_scripts/harness.py export --all # 全量：读取全部线上任务
|
||||
| 关键原始需求、确认后的单次任务需求 | Gitea 单元任务工单 | 无 |
|
||||
| 讨论、决定和需求变化 | Gitea 工单正文或评论 | 无 |
|
||||
| 长期有效的产品需求、业务规则和系统边界 | 对应 Gitea Wiki 主题页 | `docs/` |
|
||||
| 完成后的实现、验证和遗留问题 | Wiki 任务归档 | 人工按需导出的 `docs/task/` 快照（可能不完整） |
|
||||
| 完成后的实现、验证、遗留问题和验收 | Gitea 单元任务工单正文与评论 | 无；用户明确要求时可创建专项 Wiki 快照 |
|
||||
|
||||
任务产生长期结论时，先更新对应 Wiki 主题页，再导出本地镜像。Gitea 工单全文不导出到仓库，避免形成第二份任务过程记录。
|
||||
|
||||
## 稳定文档与任务归档
|
||||
## 稳定文档与可选历史快照
|
||||
|
||||
- Home、项目档案、代码地图、业务规则、开发验证、常见修改和故障排查描述项目现在怎样工作。
|
||||
- 工单和 Wiki 任务归档解释某次为什么修改、实际改了什么以及如何验证；本地任务快照不是完整历史。
|
||||
- 新人先读稳定主题页，只有追查历史原因时才读任务归档。
|
||||
- 任务产生的长期结论必须合并到主题页，不能只留在归档。
|
||||
- 工单正文和评论解释某次为什么修改、实际改了什么、如何验证以及怎样验收。
|
||||
- 新人先读稳定主题页，只有追查历史原因时才读工单；可选 Wiki 快照和本地任务快照只是专项或历史兼容资料，不是默认事实来源。
|
||||
- 任务产生的长期结论必须合并到对应主题页，不能只留在工单或可选快照。
|
||||
|
||||
## 效率与范围控制
|
||||
|
||||
本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、Wiki 同步、Git 提交和验收归档要求。
|
||||
本节用于减少无关工作和重复检查，不得削弱安全规则、已确认方案、工单范围、必要测试、必要的长期文档同步、Git 提交和人工验收要求。
|
||||
|
||||
### 严格控制范围
|
||||
|
||||
@@ -279,14 +283,14 @@ python dev_scripts/harness.py export --all # 全量：读取全部线上任务
|
||||
|---|---|---|
|
||||
| `只分析` | 只读检查需求、代码、日志和文档，区分事实与假设并给出方案 | 输出方案并等待确认；不建单、不修改 |
|
||||
| `建工单` | 根据已经确认的方案创建单元任务工单 | 工单创建并记录完成；不修改代码 |
|
||||
| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交、更新 Wiki、导出镜像、推送并回写证据 | 工单保持“待验收” |
|
||||
| `执行工单 #N` | 读取工单和前置依赖，实施、测试、提交并回写证据；仅有长期文档影响时更新 Wiki 和镜像 | 工单保持“待验收” |
|
||||
| `建工单并做` | 依次执行“建工单”和“执行工单”；`建工单，做`、`建工单,做` 含义相同 | 工单保持“待验收” |
|
||||
| `继续工单 #N` | 核对工单、Git 和 Wiki 证据，从首个未完成步骤继续，不重复仍然有效的检查 | 到达该工单当前流程的停止条件 |
|
||||
| `检查工单 #N` | 只读对照范围、验收标准、测试和证据，报告通过项、缺失项及未验证部分 | 输出检查报告；不自动修复 |
|
||||
| `同步文档` | 读取 Wiki，导出核心长期文档镜像并检查一致性，不处理任务归档 | 显示结果和差异；不修改 Wiki、不自动提交 |
|
||||
| `导出任务归档` | 人工触发增量导出，只写入新增或 revision 已变化的任务归档 | 显示导出或跳过结果；不删除本地文件、不自动提交 |
|
||||
| `导出全部任务归档` | 人工触发全量读取并导出线上全部任务归档 | 显示导出结果；不删除本地文件、不自动提交 |
|
||||
| `#N 验收通过` | 记录明确验收，更新 Wiki 归档为“已完成”，同步必要的核心文档，推送、同步父工单并关闭任务；不自动导出任务归档 | 工单“已完成”并关闭 |
|
||||
| `#N 验收通过` | 在工单追加验收结论，按需更新真实变化的长期 Wiki，推送、同步父工单并关闭任务；不创建或导出任务归档 | 工单“已完成”并关闭 |
|
||||
|
||||
补充边界：
|
||||
|
||||
@@ -295,7 +299,7 @@ python dev_scripts/harness.py export --all # 全量：读取全部线上任务
|
||||
- `#N 验收通过` 必须来自用户明确表达；其他快捷指令不得关闭待验收工单。
|
||||
- `同步文档` 或任务归档导出发现目标镜像有未提交改动时停止，不覆盖现有修改。
|
||||
- `导出任务归档` 和 `导出全部任务归档` 必须由用户明确提出，其他快捷指令不隐式执行。
|
||||
- Gitea 工单保留讨论和过程，不把工单全文导出到本地；`docs/task/` 只保存人工按需导出的 Wiki 最终任务归档快照。
|
||||
- Gitea 工单是单次任务唯一事实来源，不导出全文；`docs/task/` 只保存人工明确要求的专项或历史兼容快照。
|
||||
|
||||
## 什么时候重新确认方案
|
||||
|
||||
@@ -317,6 +321,7 @@ python dev_scripts/harness.py export --all # 全量：读取全部线上任务
|
||||
| 讨论过程和临时方案 | 是 | 否 | 否 |
|
||||
| 实施进度和阻塞 | 是 | 否 | 否 |
|
||||
| 长期有效的最终方案 | 链接 | 是 | 镜像 |
|
||||
| 测试结果与未验证内容 | 是 | 任务归档 | 按需镜像 |
|
||||
| 提交哈希 | 是 | 任务归档 | 按需镜像 |
|
||||
| 测试结果与未验证内容 | 是 | 否 | 否 |
|
||||
| 提交哈希和验收结论 | 是 | 否 | 否 |
|
||||
| 用户明确要求的任务专项快照 | 提供来源 | 可选 | 可选导出 |
|
||||
| 与具体代码版本绑定的说明 | 可链接 | 提供入口 | 是 |
|
||||
|
||||
Reference in New Issue
Block a user