📦 deps(thirdparty): update snapshots

2026-08-31 05:00:46 +08:00
parent 8fea3d18fe
commit 0b2b056032
347 changed files with 38446 additions and 136 deletions
@@ -0,0 +1,89 @@
+# 迁移指南：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 行为。