# 迁移指南：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. 老书目录迁移（三条命令）

```bash
# 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 用出问题后，不再重跑全流水线：

```bash
# 书出新版：登记新版本 → 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 行为。