playbook/cangjie-skill/docs/reports/2026-08-25-v2.1-implementation-report.md

# 倉頡 Skill v2.1 优化实现总报告（v2.5.0 发布基线）

> 日期：2026-08-25 ｜ 依据：`docs/plans/2026-08-23-cangjie-skill-optimization-plan.md` v1.3.1
> ｜ 状态：2026-08-25 完成工程实现；2026-08-30 经发布校验后以 **v2.5.0** 对外发布

## 1. 一页结论

方案的四个阶段（Phase 1 产品结构 / Phase 2 预处理与增量 / Phase 3 评测与修复 / Phase 4
交付与兼容）已全部实现并通过本地验证。核心变化：

- 一本书的单一事实源从「N 个平铺 SKILL.md」改为 **Capability Bundle**
  （`books/<book>/.cangjie/capabilities/`），交付物由确定性编译器生成，
  支持 **single**（1 入口 + 内部能力卡）与 **compact pack**（1 路由入口 + 少量晋级 Skill）。
- Naval 试点已完整走通：Bundle 回填 → auto 决策 → 编译 single 与 pack →
  staging 校验 → 原子发布（`dist/`），发布链路含写锁、手改检测、快照回滚。
- 发现目录常驻负载（cl100k 静态口径）：基线 19 入口 3,897 tokens → single 1 入口
  **340 tokens**；50 条任务静态路由评测中基线有 9 条（全部 book_lookup 类）
  在运行时无可达入口，single/pack 均为 0 条 miss。

## 2. 交付清单（按阶段）

### Phase 1 — 产品结构（方案 §3/§4/§11）

| 交付物 | 位置 | 验证 |
|---|---|---|
| 全套 schema（bundle/capability/decision/manifest/change-set/graph/eval/failure/contracts） | `schemas/` | jsonschema 校验通过 |
| Naval Capability Bundle（19 能力，6 晋级） | `books/naval-almanack-skill/.cangjie/` | bundle schema 0 errors |
| 编译器 + destinations 不变量 | `scripts/compile_single.py` `compile_pack.py` | 重复编译字节一致 |
| auto 决策（single-first-v1） | `scripts/select_output_strategy.py` | 决策报告 + 用户确认门 |
| 统一 CLI（9 个子命令） | `scripts/cangjie.py` | doctor PASS；compile/rollback 实测 |
| 根 SKILL.md + methodology v2.1 + 阶段 1.6 晋级门 | `SKILL.md` `methodology/` | 交叉引用一致 |
| Registry v1/v2 分发器 + 网站双轨展示 | `schemas/registry-entry*.json` `website/` | vitest 11/11 通过 |
| 50 条任务集 + 静态路由评测 + A 类指标 | `benchmarks/naval/task-set-v2.json` `phase1-routing-eval-50.md` `metrics-v2/` | 已生成 |

### Phase 2 — 预处理与增量更新（方案 §6/§7.2）

- `build_chunks.py`：Markdown/TXT → SourceDocument + 结构化 chunk，内容寻址缓存；
- `build_index.py`：SQLite FTS5 词法索引（中文 bigram），供检索式提取器取块；
- 提取器分型：framework/principle 保留全文扫描，case/counter-example/glossary
  检索式 + 硬覆盖门（`methodology/02-stage1-parallel-extract.md`）；
- `diff_sources.py` → change-set（modified/deletion 必须人工确认）；
- `impact_analysis.py`：依赖图构建 + 变更影响分析（章节级宽松匹配兜底）；
- `apply_skill_patch.py`：事务性补丁，校验失败自动回滚；
- `update_flow.py`：`cangjie.py update` 编排，产出 Agent 待办清单。

### Phase 3 — 评测与修复（方案 §7.3/§10）

- `repair_flow.py`：失败案例校验 → 快照 → 九类诊断分类任务（防过拟合规则内置）；
- `run_trigger_evals.py`：固定种子 60/40 切分、盲测任务包（隐藏 expected）、
  precision/recall/F1/兄弟混淆率判分；
- `run_output_evals.py`：old/new/without 匿名三变体、机械断言先于 LLM judge；
- `benchmark.py`：A 类静态指标 + 评测报告 + 过程代理指标聚合（明确标注估算口径）。

### Phase 4 — 交付与兼容（方案 §11.5/§12）

- CI：`.github/workflows/pipeline-check.yml`（books 包校验、Bundle schema、
  编译确定性冒烟）；registry-check 沿用并已被 v2 schema 覆盖；
- 迁移指南：`docs/migrations/2026-08-25-v2.0-to-v2.1.md`；
- 版本口径：`CHANGELOG.md`（`cangjie.version` 为唯一权威；本轮正式发布为 2.5.0）。

## 3. 本地验证结果（宿主：本机 macOS，2026-08-25）

- `cangjie.py doctor`：PASS（yaml/tiktoken/jsonschema 齐备）；
- `validate_skill_pack.py`（dist single + pack 7 目录 + books 19 目录）：0 errors；
- Bundle schema 校验：0 errors；重复编译确定性：一致；
- 手改检测三选一、快照与 rollback：实测触发与恢复成功；
- update 流程（模拟书新版 diff → 影响分析 → 待办）：实测走通；
- repair 流程（失败案例 → 诊断任务）：实测走通；
- trigger 评测三个子命令：合成 5 条 suite 冒烟通过（F1 判分正确）；
- website：`npm test` 11/11，`validate-registry.mjs` 通过（v1 条目零改动）。

## 4. 需在真实宿主持续积累的证据

1. **读者交叉试用**（方案 §10.5 硬门槛）：在你的宿主上安装 `dist/naval-almanack-single`
   （或 pack），用 `benchmarks/naval/task-set-v2.json` 的 50 条任务实测路由与输出；
   注意同一本书不要同时安装两种模式。
2. **宿主锁定盲测**：`run_trigger_evals.py prepare` 生成的盲测包需要真实宿主逐条跑，
   全部评测须同一宿主同一版本，结果标注 host-specific。
3. **阈值定标**：所有数值阈值仍为 `TBD-after-baseline`，等你首轮实测出基线后按
   §10.5 规则预注册，禁止事后定阈值。
4. README 的中英文版本、v2.5.0 发布说明与企微二维码已在正式发布时统一核对。

## 5. 已知限制

- 路线 C（混合执行模型）下没有真实 per-call token；所有 token 指标是静态口径
  （benchmark 报告内已强制标注），不可对外表述为计费节省。
- 静态路由评测是自评探索性证据，near_neighbor 8 条三版本均标「待实测」；
- `impact_analysis.py` 的章节级匹配偏保守（宁可多标影响，不漏标）；
- FTS5 中文检索为 bigram 词法方案，召回弱于向量检索——按 ADR 保持零重依赖，
  必要时后续加可选 embedding 后端。