docs: 同步 DevHarness 4bbacf4 工作流 (#108)

2026-08-27 17:02:56 +08:00
parent 66d63c1e43
commit 54e7c774b6
1 changed files with 41 additions and 6 deletions
@@ -15,7 +15,7 @@
 | 文档 | 创建核心主题页 | 逐页判断保留、迁移、合并或停止维护 |
 | 工单和 Wiki | 新建并开始使用 | 先检查已有工单、Wiki 和状态体系 |
 | Git 历史 | 允许一次引导提交 | 保留全部历史，不使用引导提交例外 |
-| 任务归档 | 从新项目任务开始 | 不复制 DevHarness 或其他项目的历史归档 |
+| 任务证据 | Gitea 工单；任务快照仅显式按需创建 | 保留已有工单；不复制 DevHarness 或其他项目的历史归档 |
 | 接入方式 | 一次建立最小骨架 | 分阶段增量接入并逐步验收 |

 从模板创建全新仓库时使用[新项目文档初始化](New-Project-Documentation-Setup.-)；项目已有业务提交、用户或维护历史时使用本页。
@@ -63,7 +63,7 @@ Agent 在提出方案前只读检查：
 - 多个应用共同完成一条产品或业务链路；
 - 由同一团队维护，仓库权限基本一致；
 - 接口变更需要在一个工单中同步修改或验证多端；
- 共享契约、业务规则和任务归档放在一起更容易保持一致；
+- 共享契约和业务规则由同一项目维护并指定唯一事实来源；
 - 仓库体积、测试时间和工具性能尚未明显影响开发；
 - 初级维护者和 Agent 能通过目录、子目录 `AGENTS.md` 和文档入口清楚定位。

@@ -123,7 +123,42 @@ Agent 在提出方案前只读检查：

 ### 7. 提交和验收

-提交只包含当前接入工单相关文件。记录测试、未验证部分、Wiki revision 和提交哈希，创建任务归档并保持工单“待验收”，等待用户明确验收后再关闭。
+提交只包含当前接入工单相关文件。在工单评论集中记录测试、未验证部分、提交哈希，以及真实变化的 Wiki revision 或“无长期文档影响”；保持工单“待验收”，等待用户明确验收后再关闭。默认不创建任务归档。
+
+## 后续升级
+
+已接入的项目必须以 Project-Profile 中记录的 DevHarness 来源和当前基线为起点升级，不得重新复制整个模板，也不得用“最新版本”代替可复现的目标提交。
+
+### 升级步骤
+
+1. 读取目标项目的 Project-Profile，确认 DevHarness 来源仓库、当前基线完整提交、最后升级日期和项目适配说明；字段缺失时先补齐可验证事实，无法确认则停止。
+2. 选择一个明确、已审阅的 DevHarness 目标提交，记录旧基线和新基线。先比较两个上游提交之间的变化，再判断这些变化如何作用于目标项目。
+3. 只读比较与 Harness 有关的 `AGENTS.md`、`CLAUDE.md`、工单模板、`dev_scripts/`、Harness 测试和核心 Wiki 结构，把差异分为“直接采用、按项目改写、冲突待确认、不采用”。不得把 DevHarness 的项目事实、工单或任务归档带入目标项目。
+4. 在目标项目建立单元任务工单，写明升级范围、差异分类、项目专用规则、风险、回退、验证和文档影响。会改变产品行为的内容必须拆成独立任务。
+5. 按工单最小合并，保留目标项目更具体的业务、安全、权限和目录规则，以及 Git 历史和无关工作区修改。无法判断哪一方规则有效时停止并等待负责人确认。
+6. 长期文档先更新目标项目 Wiki，读取确认后再同步目标项目的核心 `docs/` 镜像；不得用 DevHarness 的本地镜像覆盖目标项目文档。
+7. 执行目标项目规定的必要检查和受影响测试，提交并回写证据。工单保持“待验收”。
+8. 用户验收通过后，确认目标项目 Project-Profile 已记录新 DevHarness 基线完整提交和升级日期，再关闭工单。升级失败或回退时保留旧基线。
+
+### 升级停止条件
+
+除本页已有的冲突停止条件外，来源仓库与记录不一致、旧基线不存在、目标提交未明确、差异跨越过大而无法可靠分类，或升级需要覆盖项目专用安全规则时，都必须停止并请求确认。可以把升级拆成多个单元任务，但每个任务都要声明最终采用的同一目标基线。
+
+### 可复制升级指令
+
+```text
+请把当前项目从 Project-Profile 记录的 DevHarness 基线升级到
+<DevHarness 目标完整提交哈希>。
+
+先只读比较来源仓库中“旧基线..目标基线”的 Harness 变化和当前项目
+适配，列出直接采用、按项目改写、冲突待确认和不采用的内容，以及
+风险、回退、验证和文档影响。不要覆盖项目专用规则、业务文档、Git
+历史或无关改动，不复制 DevHarness 工单和任务归档。方案确认后在
+当前项目建单并实施；长期文档先改当前项目 Wiki，再同步本地镜像。
+工单保持待验收，验收通过后确认 Project-Profile 已记录新基线。
+```
+
+路径和目标完整提交哈希必须替换为真实值；目标提交未明确时只分析，不实施。

 ## 冲突处理和停止条件

@@ -167,8 +202,8 @@ Agent 在提出方案前只读检查：

 严格按工单范围增量接入 DevHarness，保留当前项目已有规则、历史、
 任务状态和无关改动。长期文档先更新 Gitea Wiki，读取确认后再导出
-本地 docs 镜像。执行必要测试，提交实现和任务归档，然后把工单保持
-为“待验收”；未经我明确验收，不关闭工单。
+本地 docs 镜像。执行必要测试，提交实现并把最终证据回写工单，然后
+保持“待验收”；默认不创建任务归档，未经我明确验收不关闭工单。
 ```

 路径、仓库地址和项目名称必须替换为当前环境的真实值。第二段指令只有在第一段方案已经明确确认后使用。
@@ -184,7 +219,7 @@ Agent 在提出方案前只读检查：
 - [ ] 已为每类长期文档明确事实来源和迁移状态。
 - [ ] Wiki-first 页面已经读取确认并具有显式镜像映射。
 - [ ] Harness 检查已按目标项目调整并通过。
- [ ] 必要测试、未验证部分、提交和归档证据已记录。
+- [ ] 必要测试、未验证部分、提交和最终证据已记录。
 - [ ] 工单处于待验收，未提前关闭。

 ## 回退原则