迁移指南：Cangjie Skill v2.0（一书一堆 Skill）→ v2.1（Capability Bundle + 双输出模式）

适用对象：已经用 v2.0 蒸馏过书、手里有 books/<book>/ 一书 N Skill 目录的用户，以及维护 registry / website 的贡献者。对应方案：docs/plans/2026-08-23-cangjie-skill-optimization-plan.md v1.3.1。

1. 变了什么（一句话版）

v2.0 的产物是「一本书 = N 个平铺的原子 Skill 目录」；v2.1 的单一事实源改为 Capability Bundle（books/<book>/.cangjie/capabilities/），交付物由编译器从 Bundle 生成，有两种模式：

模式	产物	适用
`single`（默认）	1 个可发现入口 + `references/capabilities/` 内部能力卡	通读吸收、低安装成本
`pack`（compact pack）	1 个路由入口 + 少量通过晋级门（阶段 1.6）的独立 Skill	高频独立任务意图明确

老的 19-Skill 平铺结构被称为 legacy pack，仍被 registry v1 schema 和网站兼容展示，但新蒸馏不再产出这种结构。

2. 老书目录迁移（三条命令）

# 1. 自检环境（Python ≥3.9，pyyaml；tiktoken/jsonschema 可选）
python3 scripts/cangjie.py doctor

# 2. 把 v2.0 平铺包转成 Capability Bundle（需要一份 capability-map.yaml，
#    列出每个能力的 slug/importance/intents/晋级意见；参考 benchmarks/naval/capability-map.yaml）
python3 scripts/cangjie.py migrate-legacy --pack books/<book> --map <capability-map.yaml>

# 3. 从 Bundle 编译交付物（auto 会按 single-first-v1 策略决策并要求确认）
python3 scripts/cangjie.py compile --pack books/<book> --output auto --dist dist/<book>

迁移注意：

migrate-legacy 只读老目录，不会删除它；老目录保留为基线（建议打 tag）。
每个能力必须且只能有一个去处（晋级 Skill 或 router 能力卡）， capability-destinations.json 是审计凭证，编译时自动校验。
编译产物不要手改。compile 发布时会做本地手改检测，检测到偏离上次发布哈希会停下来给三选一（丢弃手改 / 回灌 Bundle 再编译 / 中止）。改内容请改 Bundle 里的能力卡（.cangjie/capabilities/cards/*.md）与 verified.yaml。
同一本书不要同时安装 single 与 pack 两种产物到宿主，会造成路由竞争。

3. 新蒸馏流程的差异（给跑流水线的 Agent/用户）

阶段 2–5 的产出对象从「SKILL.md 文件」改为「Bundle 里的能力卡 + 元数据」，见根 SKILL.md 与 methodology/00-overview.md（v2.1 Bundle Edition）。
新增阶段 1.6 晋级门（methodology/03b-stage1.6-promotion-gate.md）：五条判据（独立意图/契约/运行/复用/评测）决定候选能力晋级独立 Skill 还是留作 router 能力卡；不强行合并，未晋级能力经 router 在运行时仍可达。
阶段 0 需要询问用户目的（通读吸收 / 高频任务），作为输出模式 auto 决策输入。
长文本处理：framework/principle 提取器保留全文扫描；case/counter-example/ glossary 改用 build_chunks.py + build_index.py（FTS5）检索式取块，且有硬覆盖门。

4. Registry / Website 迁移（给注册表贡献者）

schemas/registry-entry.schema.json 现在是 v1/v2 的 oneOf 分发器：
- 老条目（schema_version: 1）继续按 registry-entry-v1.schema.json 校验，无需改动；
- 新条目用 schema_version: 2，必填 output_mode（single|pack）、 entrypoint_count、capability_count，pack 模式另需 router_entrypoint。
约束：single 必须 entrypoint_count = 1；v2 条目 skill_count 必须等于 entrypoint_count（validate-registry.mjs 强制）。
网站展示：single 显示「1 entry · N capabilities」，pack 显示「M entries · N capabilities」， legacy 维持「N Skills」；安装提示按模式生成（src/lib/install.ts）。

5. 增量更新与修复（v2.1 新能力）

书出新版 / Skill 用出问题后，不再重跑全流水线：

# 书出新版：登记新版本 → chunk 级 diff → 依赖图影响分析 → 生成待办给 Agent 复核
python3 scripts/cangjie.py update --pack books/<book> --source <new-edition.md> --source-id <id>

# 单点失败修复：校验失败案例 → 快照 → 生成诊断任务（九类分类表）→ Agent 出最小补丁
python3 scripts/cangjie.py repair --pack books/<book> --case <failure-case.yaml>

# 任何发布/补丁都有快照，可回滚
python3 scripts/cangjie.py rollback --pack books/<book> --list

modified/deletion 类变更一律需要人工确认后才能落盘；additive 且不影响现有能力的变更会被标记为「新知识候选」，走增量蒸馏而非全量重跑。

6. 回滚整个迁移

v2.1 的所有新产物都在新增路径（.cangjie/、dist/、新 schema 文件），老目录未被修改。不想用了：删掉 books/<book>/.cangjie/ 与 dist/<book>*，registry 条目保持 schema_version: 1 即可完全回到 v2.0 行为。

5.0 KiB Raw Blame History Unescape Escape