From 857f9dc9b9f6eb3d41fcb80d5345eab528b257d5 Mon Sep 17 00:00:00 2001 From: Jesse_Chen Date: Mon, 31 Aug 2026 18:25:32 +0000 Subject: [PATCH] docs(rectification): record skill bump identity pitfalls The registry packagePath points at versions//, but the root SKILL.md copy makes it easy to hash the package root instead. Hashing the root pulls the entire versions/ subtree into the digest and still returns a value, so the mistake surfaces only as a failing gate later. Records BUG-459 and corrects the task brief's D-2 table, which listed the root SKILL.md as the hash target. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01LVapmh2oGNyr6ECHKjPJY8 --- ...rectification-decision-authority-20260831.md | 17 ++++++++++------- docs/BUG_HISTORY.md | 16 ++++++++++++++++ 2 files changed, 26 insertions(+), 7 deletions(-) diff --git a/TASK-rectification-decision-authority-20260831.md b/TASK-rectification-decision-authority-20260831.md index 3ddf9362..4ae14c54 100644 --- a/TASK-rectification-decision-authority-20260831.md +++ b/TASK-rectification-decision-authority-20260831.md @@ -222,16 +222,19 @@ function deliveryCapability(input: { | # | 位置 | 改什么 | | --- | --- | --- | -| 1 | `skills/jyotish-birth-time-rectification/SKILL.md` | 正文约束 + frontmatter 的 `version: 10.0.14` | -| 2 | `skills/skill-package-registry.json` | 新增 10.0.14 条目 `status: "active"`；10.0.13 改 `"deprecated"` | -| 3 | 同上条目的 `sha256` | 用 `computeSkillPackageSha256()`（`skill-package-registry.ts:289` 已导出）对**整个包目录**重算 | -| 4 | `frontend/src/lib/rectification-agentic/v9/case-status.ts:92` | `RECTIFICATION_SKILL_VERSION = "10.0.14"` | -| 5 | `frontend/tests/skill-registry.test.ts` | 该文件**硬编码了 sha256**，必须同步 | +| 1 | `skills/jyotish-birth-time-rectification/versions/10.0.14/` | 以 `versions/10.0.13/` 为基础新建；改 `SKILL.md` 正文约束 + frontmatter `version: 10.0.14` | +| 2 | `skills/jyotish-birth-time-rectification/SKILL.md` | 根目录是最新版的**副本**，与上一行保持字节一致 | +| 3 | `skills/skill-package-registry.json` | 新增 10.0.14 条目 `status: "active"`、`packagePath` 指向 `versions/10.0.14`；10.0.13 改 `"deprecated"` | +| 4 | 同上条目的 `sha256` | 用 `computeSkillPackageSha256()`（`skill-package-registry.ts:289` 已导出）**只对 `versions/10.0.14/` 计算** | +| 5 | `frontend/src/lib/rectification-agentic/v9/case-status.ts:92` | `RECTIFICATION_SKILL_VERSION = "10.0.14"` | +| 6 | `frontend/tests/skill-registry.test.ts` | 该文件**硬编码了 sha256**，必须同步 | + +**SHA 只对 registry `packagePath` 指向的目录计算，绝不对 Skill 根目录计算。** 根目录含 `versions/` 整棵子树，对它计算会把全部历史版本吃进哈希——而且能正常返回一个值、不会立刻报错，错了也发现不了。 两个坑： -- sha256 覆盖整个目录（递归遍历，每个文件写入长度前缀的 path / executable bit / bytes）。**改 frontmatter 也会改 sha** —— 顺序必须是"先改完所有字节，最后统一重算"。 -- `case-service.ts:301` 校验 `resolveActiveSkillPackage(...).version === RECTIFICATION_SKILL_VERSION`，registry 与常量不一致会让**新建 case 直接抛 `skill_registry_version_mismatch`**。第 2、4 处必须同时改。 +- sha256 覆盖目标目录全部内容（递归遍历，每个文件写入长度前缀的 path / executable bit / bytes）。**改 frontmatter 也会改 sha** —— 顺序必须是"先改完所有字节，最后统一重算"，不得边改边算。 +- `case-service.ts:301` 校验 `resolveActiveSkillPackage(...).version === RECTIFICATION_SKILL_VERSION`，registry 与常量不一致会让**新建 case 直接抛 `skill_registry_version_mismatch`**，功能整个开不了场。上表第 3 与第 5 处必须同时改。 前车之鉴：`797a423a` 就是"改了 skill 字节但忘了刷新 registry hash"的补救提交。**改完务必跑 `npx tsx --test tests/skill-registry.test.ts` 验证。** diff --git a/docs/BUG_HISTORY.md b/docs/BUG_HISTORY.md index 60d82079..d6429573 100644 --- a/docs/BUG_HISTORY.md +++ b/docs/BUG_HISTORY.md @@ -7038,3 +7038,19 @@ - 相关记录：BUG-455、BUG-457 - 复发自：无 - 修复版本：`test(billing): make renewal timing deterministic` + +## BUG-459 | Skill 升版身份同步不完整：SHA 目标目录易错且身份分散在五处 + +- 状态：resolved +- 首次发现：2026-08-31 +- 最近更新：2026-08-31 +- 影响面：`skills/skill-package-registry.json`、`skills/jyotish-birth-time-rectification/**`、`RECTIFICATION_SKILL_VERSION`、`frontend/tests/skill-registry.test.ts`、`openRectificationCase` +- 用户现象：升版后新建 Case 直接失败（`skill_registry_version_mismatch`），或 `skill-registry.test.ts` 在发布门禁处失败。 +- 触发条件：升级 rectification Skill 版本时只改了部分身份位点；或对 Skill 根目录而非 `versions//` 计算 SHA256。 +- 根因：Skill 身份分散在五处——版本目录 `SKILL.md` frontmatter、根目录 `SKILL.md` 副本、registry 条目的 `version`/`sha256`/`packagePath`、`RECTIFICATION_SKILL_VERSION` 常量、测试内硬编码 SHA。registry 的 `packagePath` 指向 `versions//`，但根目录存在同名 `SKILL.md` 副本，容易让人误以为 SHA 应对根目录计算；根目录含 `versions/` 整棵子树，对它计算会把全部历史版本吃进哈希，**且能正常返回一个值、不会立刻报错**。`openRectificationCase`（`v9/case-service.ts`）校验 registry active 版本必须等于 `RECTIFICATION_SKILL_VERSION`，任一处不同步即导致新建 Case 整体失败。 +- 修复：升版按固定顺序执行——先建 `versions//` 并改完全部字节（含 frontmatter 与根目录副本），**最后**统一对 `versions//` 调用 `computeSkillPackageSha256()`，再回填 registry 与测试。10.0.13 → 10.0.14 按此流程完成。 +- 验证：对 `versions/10.0.14/` 实算 SHA 与 registry、`skill-registry.test.ts` 三处一致；registry active 条目唯一；根目录与版本目录 `SKILL.md` 字节一致；`rectification-*` 与 `skill-registry` 套件 730 项 0 失败；`tsc --noEmit` 通过。未进行真实 staging smoke。 +- 防复发：SHA256 只能对 registry `packagePath` 指向的目录计算，绝不对 Skill 根目录计算；改字节与算 SHA 不得交错，必须先定稿再统一重算；升版必须在同一变更内同步全部五处身份位点；`skill-registry.test.ts` 是发布门禁，不得跳过。存量 Case 绑定各自的 `skill_version`，`resolveExact` 对 `deprecated` 放行，因此升版不需要数据迁移，但旧 Case 不会获得新版 prompt 约束。 +- 相关记录：BUG-456 +- 复发自：无（提交 `797a423a` 曾出现同类的"改了 Skill 字节但未刷新 registry hash"，当时未单独立项） +- 修复版本：Skill `10.0.14`