OPC/dev_harness
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

增加 DevHarness 后续升级与基线记录规范 #16

New Issue
Closed
opened 2026-08-16 23:07:02 +08:00 by ila · 1 comment
ila commented 2026-08-16 23:07:02 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：单元任务
  • 状态：已完成
  • 所属 Epic：无
  • 所属 MVP / 版本：无

依赖与并行

  • 前置工单：#12
  • 是否允许与其他工单并行：是
  • 原因：“已有项目接入 DevHarness 指南”已由 #12 建立并验收；#14、#15 已完成并关闭。

原始需求

  • 来源：用户与 Agent 对话
  • 提出时间：2026-08-16
  • 关键原话或脱敏摘要：“在‘已有项目接入 DevHarness 指南’中增加‘后续升级’章节，并要求每个项目记录 DevHarness 来源和基线提交”
  • 已确认方案：增加可重复执行的后续升级流程；每个接入项目必须在项目档案记录 DevHarness 来源仓库和不可变的基线提交。

要解决什么

已有项目完成首次接入后，缺少从旧 DevHarness 基线安全升级到新基线的统一步骤，也缺少可追溯的来源和基线记录，导致 Agent 无法可靠判断应比较哪些变更、哪些项目定制必须保留。

做什么 / 不做什么

做

  • 在 Existing-Project-Adoption-Guide 增加“后续升级”章节。
  • 明确升级前读取目标项目记录的来源与当前基线，并选择明确的新基线提交。
  • 明确比较规则、冲突处理、目标项目建单、Wiki 优先、验证、提交和验收后更新基线的顺序。
  • 在 Project-Profile 增加“DevHarness 来源与基线”必填记录区。
  • 要求每个采用 DevHarness 的项目记录来源仓库和完整基线提交；升级完成后更新。
  • 更新 Harness 文档结构检查和单元测试。
  • 先更新 Wiki，再导出核心文档镜像。

不做

  • 不开发自动升级、自动合并或远端拉取脚本。
  • 不替目标项目自动执行升级。
  • 不覆盖目标项目的业务规则、安全规则、文档历史或未提交改动。
  • 不复制 DevHarness 的工单、任务归档或项目事实到目标项目。
  • 不建立发布、标签或版本管理系统。

已确认方案

  1. Project-Profile 增加固定章节，至少记录 DevHarness 来源仓库、当前基线完整提交哈希和最后升级日期；源模板仓库说明自身为上游，业务项目初始化时必须替换示例值。
  2. Existing-Project-Adoption-Guide 增加“后续升级”，按“读取现有记录 → 选择明确目标提交 → 比较 Harness 文件与规则 → 分类冲突 → 在目标项目建工单 → 最小合并 → 更新目标 Wiki 并同步镜像 → 验证提交 → 验收后更新基线”的顺序执行。
  3. 升级时保留目标项目更具体的业务和安全规则；无法判断的冲突停止并等待确认。
  4. 基线必须使用不可变的完整提交哈希，不使用“最新版本”等动态描述。
  5. Harness 严格检查验证两个新章节存在。

文档影响

  • 不影响长期文档，原因：
  • 更新项目档案：增加 DevHarness 来源与基线记录
  • 更新架构与代码地图
  • 更新业务规则与术语
  • 更新常见修改或故障排查
  • 更新其他 Wiki：Existing-Project-Adoption-Guide

交付文档影响

  • 无交付文档影响，原因：本任务只调整内部开发流程文档。
  • 更新已有交付文档：
  • 新增交付文档：
  • 需要目标岗位或客户代表验证：否；由项目维护者验证流程可执行。

验收标准

  • Existing-Project-Adoption-Guide 包含“后续升级”章节。
  • 升级步骤明确读取旧基线、选择新基线、差异分类、目标项目建单、最小合并、验证和验收后更新记录。
  • Project-Profile 包含“DevHarness 来源与基线”章节。
  • 明确每个接入项目必须记录来源仓库和完整基线提交。
  • 明确冲突停止条件及不得覆盖的目标项目内容。
  • 未增加自动升级脚本或新的流程框架。
  • Wiki 已读取确认并与核心镜像一致。
  • Harness strict check and 34 unit tests passed.
  • 实现提交已推送，任务归档已更新 Wiki。
  • 工单保持待验收，等待用户明确验收。

验证方式

  • python dev_scripts/check_harness.py --strict
  • python -m unittest discover -s tests -v
  • python dev_scripts/sync_wiki_docs.py --check
  • 人工检查：以一个已接入旧基线的项目代入流程，确认能定位比较范围、冲突处理和基线更新时点。
  • git diff --check
  • git status --short --branch

风险和回退

  • 风险：把模板升级误当成整仓覆盖；通过明确比较边界和保留目标项目规则控制。
  • 风险：在验证前更新基线造成错误记录；规定仅在升级提交完成且验收通过后更新。
  • 风险：动态版本描述不可复现；强制完整提交哈希。
  • 回退：撤销新增章节和对应检查，不影响既有项目代码或数据。

实施结果与证据

  • Project-Profile revision：16456d6ed083197759d553b1033e3e5c8a6b8932。
  • Existing-Project-Adoption-Guide revision：2ef3d7cd26874f652e9bfab2a5c2f6c8273ab7ac。
  • 实现提交：947a068，已推送至 origin/main。
  • 任务归档 Wiki：Task-16-DevHarness-后续升级与基线记录。
  • 任务归档 revision：7234d17b9567f82d67aedc67c9fa1f877574c744。
  • 严格检查：通过。
  • 单元测试：34 项全部通过。
  • 核心镜像检查：13 个页面全部一致。
  • 人工场景：已确认能从旧基线定位比较范围、分类差异并明确更新时点。
  • 未验证：未在具体业务项目执行真实升级；本任务只定义和校验流程文档。
  • 按 #14 规则，任务归档只更新 Wiki，未自动导出到 docs/task/。
## 基本信息 - 类型：单元任务 - 状态：已完成 - 所属 Epic：无 - 所属 MVP / 版本：无 ## 依赖与并行 - 前置工单：#12 - 是否允许与其他工单并行：是 - 原因：“已有项目接入 DevHarness 指南”已由 #12 建立并验收；#14、#15 已完成并关闭。 ## 原始需求 - 来源：用户与 Agent 对话 - 提出时间：2026-08-16 - 关键原话或脱敏摘要：“在‘已有项目接入 DevHarness 指南’中增加‘后续升级’章节，并要求每个项目记录 DevHarness 来源和基线提交” - 已确认方案：增加可重复执行的后续升级流程；每个接入项目必须在项目档案记录 DevHarness 来源仓库和不可变的基线提交。 ## 要解决什么 已有项目完成首次接入后，缺少从旧 DevHarness 基线安全升级到新基线的统一步骤，也缺少可追溯的来源和基线记录，导致 Agent 无法可靠判断应比较哪些变更、哪些项目定制必须保留。 ## 做什么 / 不做什么 ### 做 - 在 Existing-Project-Adoption-Guide 增加“后续升级”章节。 - 明确升级前读取目标项目记录的来源与当前基线，并选择明确的新基线提交。 - 明确比较规则、冲突处理、目标项目建单、Wiki 优先、验证、提交和验收后更新基线的顺序。 - 在 Project-Profile 增加“DevHarness 来源与基线”必填记录区。 - 要求每个采用 DevHarness 的项目记录来源仓库和完整基线提交；升级完成后更新。 - 更新 Harness 文档结构检查和单元测试。 - 先更新 Wiki，再导出核心文档镜像。 ### 不做 - 不开发自动升级、自动合并或远端拉取脚本。 - 不替目标项目自动执行升级。 - 不覆盖目标项目的业务规则、安全规则、文档历史或未提交改动。 - 不复制 DevHarness 的工单、任务归档或项目事实到目标项目。 - 不建立发布、标签或版本管理系统。 ## 已确认方案 1. Project-Profile 增加固定章节，至少记录 DevHarness 来源仓库、当前基线完整提交哈希和最后升级日期；源模板仓库说明自身为上游，业务项目初始化时必须替换示例值。 2. Existing-Project-Adoption-Guide 增加“后续升级”，按“读取现有记录 → 选择明确目标提交 → 比较 Harness 文件与规则 → 分类冲突 → 在目标项目建工单 → 最小合并 → 更新目标 Wiki 并同步镜像 → 验证提交 → 验收后更新基线”的顺序执行。 3. 升级时保留目标项目更具体的业务和安全规则；无法判断的冲突停止并等待确认。 4. 基线必须使用不可变的完整提交哈希，不使用“最新版本”等动态描述。 5. Harness 严格检查验证两个新章节存在。 ## 文档影响 - [ ] 不影响长期文档，原因： - [x] 更新项目档案：增加 DevHarness 来源与基线记录 - [ ] 更新架构与代码地图 - [ ] 更新业务规则与术语 - [ ] 更新常见修改或故障排查 - [x] 更新其他 Wiki：Existing-Project-Adoption-Guide ## 交付文档影响 - [x] 无交付文档影响，原因：本任务只调整内部开发流程文档。 - [ ] 更新已有交付文档： - [ ] 新增交付文档： - [x] 需要目标岗位或客户代表验证：否；由项目维护者验证流程可执行。 ## 验收标准 - [x] Existing-Project-Adoption-Guide 包含“后续升级”章节。 - [x] 升级步骤明确读取旧基线、选择新基线、差异分类、目标项目建单、最小合并、验证和验收后更新记录。 - [x] Project-Profile 包含“DevHarness 来源与基线”章节。 - [x] 明确每个接入项目必须记录来源仓库和完整基线提交。 - [x] 明确冲突停止条件及不得覆盖的目标项目内容。 - [x] 未增加自动升级脚本或新的流程框架。 - [x] Wiki 已读取确认并与核心镜像一致。 <!-- encoding-padding-0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 --> - [x] Harness strict check and 34 unit tests passed. - [x] 实现提交已推送，任务归档已更新 Wiki。 - [x] 工单保持待验收，等待用户明确验收。 ## 验证方式 - `python dev_scripts/check_harness.py --strict` - `python -m unittest discover -s tests -v` - `python dev_scripts/sync_wiki_docs.py --check` - 人工检查：以一个已接入旧基线的项目代入流程，确认能定位比较范围、冲突处理和基线更新时点。 - `git diff --check` - `git status --short --branch` ## 风险和回退 - 风险：把模板升级误当成整仓覆盖；通过明确比较边界和保留目标项目规则控制。 - 风险：在验证前更新基线造成错误记录；规定仅在升级提交完成且验收通过后更新。 - 风险：动态版本描述不可复现；强制完整提交哈希。 - 回退：撤销新增章节和对应检查，不影响既有项目代码或数据。 ## 实施结果与证据 - Project-Profile revision：`16456d6ed083197759d553b1033e3e5c8a6b8932`。 - Existing-Project-Adoption-Guide revision：`2ef3d7cd26874f652e9bfab2a5c2f6c8273ab7ac`。 - 实现提交：`947a068`，已推送至 `origin/main`。 - 任务归档 Wiki：`Task-16-DevHarness-后续升级与基线记录`。 - 任务归档 revision：`7234d17b9567f82d67aedc67c9fa1f877574c744`。 - 严格检查：通过。 - 单元测试：34 项全部通过。 - 核心镜像检查：13 个页面全部一致。 - 人工场景：已确认能从旧基线定位比较范围、分类差异并明确更新时点。 - 未验证：未在具体业务项目执行真实升级；本任务只定义和校验流程文档。 - 按 #14 规则，任务归档只更新 Wiki，未自动导出到 `docs/task/`。
ila commented 2026-08-25 10:24:35 +08:00
Author
Owner
Copy Link
Copy Source

验收结论

  • 验收时间：2026-08-25（Asia/Shanghai）
  • 结论：用户明确表示 #16 验收通过。
  • 长期需求状态：已在 Product-Requirements-Overview 更新为“已交付”，revision e9e0ebafd9189ae911094e615595a5e464e5e59b。
  • 镜像提交：19fb64b，已推送到 origin/main。
  • Wiki 镜像检查：15 个核心页面一致。
  • 父工单：无。
  • 任务快照：未新建、未导出；已有历史快照继续作为兼容证据，单次任务事实以本工单为准。

验收闭环完成，关闭工单。

## 验收结论 - 验收时间：2026-08-25（Asia/Shanghai） - 结论：用户明确表示 #16 验收通过。 - 长期需求状态：已在 Product-Requirements-Overview 更新为“已交付”，revision `e9e0ebafd9189ae911094e615595a5e464e5e59b`。 - 镜像提交：`19fb64b`，已推送到 `origin/main`。 - Wiki 镜像检查：15 个核心页面一致。 - 父工单：无。 - 任务快照：未新建、未导出；已有历史快照继续作为兼容证据，单次任务事实以本工单为准。 验收闭环完成，关闭工单。
ila closed this issue 2026-08-25 10:24:35 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/dev_harness#16