docs(rectification): record skill bump identity pitfalls
The registry packagePath points at versions/<version>/, 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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LVapmh2oGNyr6ECHKjPJY8
This commit is contained in:
Jesse_Chen
@@ -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` 验证。**
|
||||
|
||||
|
||||
@@ -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/<version>/` 计算 SHA256。
|
||||
- 根因：Skill 身份分散在五处——版本目录 `SKILL.md` frontmatter、根目录 `SKILL.md` 副本、registry 条目的 `version`/`sha256`/`packagePath`、`RECTIFICATION_SKILL_VERSION` 常量、测试内硬编码 SHA。registry 的 `packagePath` 指向 `versions/<version>/`，但根目录存在同名 `SKILL.md` 副本，容易让人误以为 SHA 应对根目录计算；根目录含 `versions/` 整棵子树，对它计算会把全部历史版本吃进哈希，**且能正常返回一个值、不会立刻报错**。`openRectificationCase`（`v9/case-service.ts`）校验 registry active 版本必须等于 `RECTIFICATION_SKILL_VERSION`，任一处不同步即导致新建 Case 整体失败。
|
||||
- 修复：升版按固定顺序执行——先建 `versions/<new>/` 并改完全部字节（含 frontmatter 与根目录副本），**最后**统一对 `versions/<new>/` 调用 `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`
|
||||
|
||||
Reference in New Issue
Block a user