5.9 KiB
5.9 KiB
倉頡 Skill v2.1 优化实现总报告（v2.5.0 发布基线）
日期：2026-08-25 ｜ 依据：
docs/plans/2026-08-23-cangjie-skill-optimization-plan.mdv1.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 test11/11，validate-registry.mjs通过（v1 条目零改动）。
4. 需在真实宿主持续积累的证据
- 读者交叉试用（方案 §10.5 硬门槛）：在你的宿主上安装
dist/naval-almanack-single（或 pack），用benchmarks/naval/task-set-v2.json的 50 条任务实测路由与输出； 注意同一本书不要同时安装两种模式。 - 宿主锁定盲测：
run_trigger_evals.py prepare生成的盲测包需要真实宿主逐条跑， 全部评测须同一宿主同一版本，结果标注 host-specific。 - 阈值定标：所有数值阈值仍为
TBD-after-baseline，等你首轮实测出基线后按 §10.5 规则预注册，禁止事后定阈值。 - README 的中英文版本、v2.5.0 发布说明与企微二维码已在正式发布时统一核对。
5. 已知限制
- 路线 C（混合执行模型）下没有真实 per-call token；所有 token 指标是静态口径 （benchmark 报告内已强制标注），不可对外表述为计费节省。
- 静态路由评测是自评探索性证据，near_neighbor 8 条三版本均标「待实测」；
impact_analysis.py的章节级匹配偏保守（宁可多标影响，不漏标）；- FTS5 中文检索为 bigram 词法方案，召回弱于向量检索——按 ADR 保持零重依赖， 必要时后续加可选 embedding 后端。