📦 deps(thirdparty): update snapshots

cangjie-skill/docs/migrations/2026-08-25-v2.0-to-v2.1.md

@@ -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 行为。

cangjie-skill/docs/plans/2026-07-13-agent-install-detail-redesign.md

@@ -0,0 +1,31 @@
+# Agent 自适应安装与 Skill 详情页调整
+
+日期：2026-07-13
+
+## 问题
+
+当前详情页把 `git clone` 和复制目录作为默认安装方式，要求用户理解不同 Agent 的路径，步骤僵硬。详情页的信息层级也更像 Registry 数据展示，而不是帮助用户理解并立即使用 Skill。
+
+## 方案
+
+采用“Agent 安装优先、源码入口次要”的双通道：
+
+1. 每个 Skill 详情页生成一条自然语言安装提示词。
+2. 提示词引用统一的仓颉 Skill 安装规范，并包含准确来源和 slug。
+3. Agent 读取规范后自行识别运行环境、安装目录、Skill 数量和冲突情况。
+4. 源仓库仍然公开可见，但不再把手动命令当作普通用户主流程。
+5. 详情页改为主内容加右侧安装卡：左侧解释用途和调用方式，右侧固定展示安装提示词、复制按钮和 Registry 信息。
+
+## 边界
+
+- 不做 Agent 协议唤起或本地守护进程。
+- 不假设所有 Skill 已收录到 SkillHub。
+- 不在网站服务器端下载或安装任何文件。
+- 对外部来源执行安装前，Agent 必须先检查风险和同名冲突。
+
+## 验证
+
+- 单元测试覆盖 GitHub 来源和仓库内置来源的提示词生成。
+- 详情页不再出现硬编码的 Codex 复制命令。
+- 教程和首页统一使用“复制提示词给 Agent”的安装模型。
+- 桌面和移动端检查右侧安装卡与复制交互。

cangjie-skill/docs/plans/2026-07-13-cangjie-skill-official-website-design.md

@@ -0,0 +1,874 @@
+# Cangjie Skill 官方网站产品与设计方案（第一版）
+
+日期：2026-07-13
+状态：待确认的产品设计草案，不包含前端实现
+项目：Cangjie Skill / 仓颉 Skill
+
+> 当前实施以 [MVP 功能与页面布局规格](./2026-07-13-cangjie-skill-website-mvp-functional-spec.md) 为准；本文保留为后续视觉与完整产品愿景参考。
+
+## 1. 一句话结论
+
+官网不应该只是一个更漂亮的 README，而应该成为一个由 GitHub 驱动的“可验证 Skill 知识库”：用户能在 3 分钟内学会使用，能按真实问题找到合适的 Skill，贡献者能通过一个目录 PR 提交作品，维护者则直接在 GitHub 完成自动检查、人工审核和合并发布。
+
+推荐第一阶段不做独立后台、不做站内账号、不做数据库。GitHub 仓库就是数据库，Pull Request 就是审核后台，Git 历史就是审计日志，GitHub Actions 就是自动质检员，官网只负责学习、发现、生成投稿内容和展示审核结果。
+
+## 2. 当前项目诊断
+
+### 2.1 已经拥有的资产
+
+当前仓库已经具备官网最难得的四类内容资产：
+
+1. 明确的产品主张：把书、长视频、播客、课程等长内容中的方法论蒸馏为可调用的 AI Skills。
+2. 一套可解释的方法论：Adler 整体理解、并行提取、三重验证、RIA++ 构造、Zettelkasten 链接、压力测试和最终交付。
+3. 一批可以直接展示的结果：当前 README 列出了 22 个 Skill Packs，合计约 300 个原子 Skills。
+4. 一套较完整的产物模板：`BOOK_OVERVIEW.md`、`INDEX.md`、`DIGEST.md`、子 Skill 的 `SKILL.md`、`test-prompts.json` 和审计轨迹。
+
+这意味着官网不用从“解释一个概念”开始，而可以直接从“给我一个问题，我帮你找到可用的方法”开始。
+
+### 2.2 当前信息呈现的问题
+
+当前 README 对熟悉 GitHub 和 Agent Skills 的用户很完整，但对新用户存在四个断点：
+
+- 不知道 Skill 和 Prompt、知识库、聊天机器人有什么区别。
+- 看见几十个仓库后，不知道自己该选哪一个。
+- 找到仓库后，不知道安装到 Claude Code、Codex、Cursor 或 Copilot 的哪个位置。
+- 想贡献时，没有统一入口、提交契约、质量等级和审核状态说明。
+
+因此，官网的核心任务不是“讲更多”，而是降低四次决策成本：理解、选择、安装、贡献。
+
+### 2.3 一个需要先解决的规范问题
+
+当前 Cangjie 生成模板把 `source_book`、`source_chapter`、`tags`、`related_skills` 作为 `SKILL.md` 顶层 frontmatter 字段，其中数组使用 YAML flow list。现有 Agent 客户端可能会忽略这些额外字段并正常加载，但按 2026 年当前 Agent Skills 官方规范和 `skills-ref` 校验器，这种写法不是稳定的跨客户端契约。
+
+建议官网上线前把标准拆成两层：
+
+- Agent 执行契约：`SKILL.md` 只使用规范字段，包括 `name`、`description`，以及可选的 `license`、`compatibility`、`metadata`、`allowed-tools`。
+- Cangjie 收录契约：展示、分类、作者、来源、质量等级、仓库地址等信息放在独立的 `entry.yaml` 中，不依赖 Agent 是否理解这些字段。
+
+来源、章节、标签和关联 Skill 若需要留在 `SKILL.md` 内，应放入 `metadata`，并使用字符串值，以获得更好的官方校验兼容性。
+
+## 3. 产品定位
+
+### 3.1 推荐定位
+
+> Cangjie Skill 是一个把高价值内容转化为可调用 Agent Skills 的开源方法与公共知识库。
+
+网站同时承担三个角色：
+
+- 学习站：让新手理解、安装并调用 Skills。
+- Skill Library：展示官方和社区贡献的 Skill Packs 与原子 Skills。
+- 开源贡献门户：让贡献者用 PR 提交，自动校验，公开审核。
+
+### 3.2 不建议的定位
+
+第一阶段不建议把它做成：
+
+- “AI 应用商店”：会让人期待在线运行、付费、评分、账号体系和复杂权限。
+- “内容摘要站”：会弱化可调用、可执行、可测试的核心差异。
+- “上传网盘”：会带来存储、版权、恶意文件和运营责任。
+- “后台 CMS”：在贡献规模尚未验证前，维护成本大于收益。
+
+### 3.3 成功标准
+
+首版上线后，至少能回答以下问题：
+
+- 新用户能否在 3 分钟内完成一次安装和触发测试？
+- 用户能否从“我想解决什么问题”出发找到一个 Skill，而不是只按书名浏览？
+- 外部贡献者能否在 10 分钟内创建一个格式正确的 PR？
+- 维护者能否在 5 分钟内判断一个投稿是格式问题、质量问题还是版权问题？
+- 合并 PR 后，官网和 README 是否能自动更新而不重复维护？
+
+## 4. 三种产品路线
+
+### 路线 A：README 展示站
+
+把当前 README 做成首页、教程页和卡片列表，投稿仍然完全跳转 GitHub。
+
+优点：开发最快、风险最低。
+缺点：只能“看”，没有真正改善发现和投稿体验，未来很快需要重构。
+
+### 路线 B：GitHub 原生 Skill Registry（推荐）
+
+官网从仓库中的结构化目录构建。每个收录项对应一个独立目录；官网提供投稿向导，在浏览器中生成 `entry.yaml` 和 `README.md`，用户最终通过 GitHub fork + PR 提交。GitHub Actions 自动检查，人工审核后合并，网站自动重建。
+
+优点：无独立后台、透明、可审计、贡献者身份保留、可以逐步扩展。
+缺点：投稿者仍需要 GitHub 账号；本地文件夹投稿比纯链接投稿多几步。
+
+### 路线 C：完整 Skill 平台
+
+使用 GitHub OAuth、GitHub App、数据库和对象存储，站内完成登录、上传、状态管理、评论和 PR 创建。
+
+优点：体验最完整，可以做收藏、评分、在线试用和贡献者中心。
+缺点：开发、运维、安全与合规成本显著增加，现阶段缺少足够数据证明这些能力必要。
+
+### 推荐决策
+
+采用路线 B。架构上保留未来接入 GitHub App 的位置，但首版不建设账号、数据库和上传后台。
+
+## 5. 用户与核心任务
+
+### 5.1 第一次听说 Skill 的普通用户
+
+目标：弄懂“它能帮我做什么”，选择一个 Skill，完成安装和首次调用。
+
+官网需要提供：
+
+- 30 秒概念解释。
+- 一个真实的输入、触发和输出演示。
+- 按工具切换的安装命令。
+- 可复制的测试 Prompt。
+- 安装失败的最短排查路径。
+
+### 5.2 已经使用 Agent 的进阶用户
+
+目标：按任务、领域、来源和平台发现高质量 Skills。
+
+官网需要提供：
+
+- 快速搜索与多维筛选。
+- Skill Pack 和原子 Skill 两层结构。
+- 触发场景、反场景、执行步骤和测试状态。
+- GitHub、复制安装命令、查看源材料等快捷动作。
+
+### 5.3 Skill 创作者与内容蒸馏者
+
+目标：提交自己的 Skill 或仓库，获得收录和署名。
+
+官网需要提供：
+
+- 两种提交模式：已有 GitHub 仓库、仅有本地文件夹。
+- 投稿模板和实时预检。
+- 清楚的质量等级、版权要求和审核过程。
+- PR 状态、修改建议和贡献者署名。
+
+### 5.4 维护者
+
+目标：低成本判断投稿是否能收录，并保持品牌质量。
+
+官网和仓库需要提供：
+
+- 自动 schema 校验。
+- Agent Skills 官方格式校验。
+- 文件、链接、许可证、秘密信息和高风险脚本检查。
+- 可重复使用的人工审核清单。
+- 合并后自动生成目录、README 和官网数据。
+
+## 6. 网站信息架构
+
+主导航建议保持六项：
+
+1. 首页
+2. 学会使用
+3. Skill 库
+4. 蒸馏方法
+5. 提交 Skill
+6. GitHub
+
+辅助入口：语言切换、搜索、深色模式、交流群。
+
+建议路由：
+
+```text
+/
+/learn
+/library
+/library/packs/[slug]
+/library/skills/[slug]
+/method
+/contribute
+/contribute/guide
+/quality
+/contributors
+/about
+```
+
+首页不是所有信息的堆叠，而是负责把三类人分流：
+
+- “我想学会使用” → `/learn`
+- “我想找一个 Skill” → `/library`
+- “我想提交作品” → `/contribute`
+
+## 7. 首页详细设计
+
+### 7.1 顶部导航
+
+左侧是 Cangjie 标志与文字，右侧是主导航、全站搜索、GitHub Star 按钮和“提交 Skill”主按钮。
+
+导航采用半透明浅色背景或墨色背景上的细描边，不做常见的厚重 SaaS 胶囊按钮堆叠。
+
+### 7.2 Hero
+
+主标题建议：
+
+> 把读过、看过、听过的知识，变成 Agent 真正会用的能力。
+
+副标题：
+
+> Cangjie Skill 使用 RIA-TV++，把书、课程、访谈和长内容中的方法论蒸馏为可触发、可执行、可测试的 Agent Skills。
+
+两个主要动作：
+
+- 开始使用
+- 浏览 Skill 库
+
+一个次级动作：
+
+- 在 GitHub 查看源码
+
+Hero 右侧不放泛化 AI 插画，建议使用“从长内容到知识节点再到 Agent 行动”的真实动态关系图。节点可使用当前仓库中的真实 Skill 名称，例如 `margin-of-safety`、`economic-moat`、`viral-copywriting`，避免装饰性假数据。
+
+### 7.3 实时成果条
+
+从 registry 自动计算并显示：
+
+- Skill Packs 数量
+- 原子 Skills 数量
+- 贡献者数量
+- 通过测试的比例
+
+当前可作为初始值展示“22 个 Packs / 约 300 个 Skills”，但上线后禁止手工写死。
+
+### 7.4 三步使用演示
+
+用一个真实例子完成闭环：
+
+1. 选择一个 Skill，例如“安全边际”。
+2. 一键复制对应平台安装命令。
+3. 输入一个真实问题，看 Agent 如何触发并执行。
+
+这部分应带工具切换：Claude Code / Codex / GitHub Copilot / 其他兼容客户端。切换后命令、目录和验证方式同步变化。
+
+### 7.5 精选 Skill Packs
+
+首页只展示 6 个，不展示全部：
+
+- 巴菲特致股东信
+- 穷查理宝典
+- 认知红利
+- 爆款文案
+- AI for Everyone
+- 毛泽东选集
+
+卡片信息控制在：封面或主题视觉、名称、来源类型、原子 Skill 数、三条代表性能力、质量徽章、查看详情。
+
+### 7.6 方法论横截面
+
+不在首页完整解释七个阶段，只展示一句话流水线：
+
+> 理解全貌 → 提取候选 → 三重验证 → 构造 Skill → 建立关联 → 压力测试 → 安装交付
+
+点击进入 `/method` 查看详细过程、产物示例和质量门槛。
+
+### 7.7 社区贡献区
+
+展示最近收录、贡献者头像和审核规则，主文案：
+
+> 你贡献的不是一条链接，而是一项能被验证、被署名、被长期维护的 Agent 能力。
+
+动作：
+
+- 提交已有 GitHub 仓库
+- 提交本地 Skill 文件夹
+
+## 8. “学会使用”页面
+
+这个页面应采用交互式教程，而不是长文档。
+
+### 8.1 第一步：先选你的工具
+
+工具卡片：
+
+- Claude Code
+- OpenAI Codex
+- GitHub Copilot
+- Cursor
+- OpenClaw
+- 其他 Agent Skills 兼容客户端
+
+只展示经过验证的目录和命令。对于尚未确认完全兼容的平台，明确标注“实验性”，不要为了平台数量而过度承诺。
+
+### 8.2 第二步：选安装范围
+
+- 个人级：所有项目可用。
+- 项目级：只在当前项目使用。
+
+页面根据选择生成可复制命令，并解释复制的是完整目录而不是单个 Markdown 文件。
+
+### 8.3 第三步：验证是否生效
+
+每个平台提供：
+
+- 查看已发现 Skills 的方式。
+- 一个 `should_trigger` 测试 Prompt。
+- 一个 `should_not_trigger` 反例 Prompt。
+- 常见错误：目录名不匹配、文件名不是大写 `SKILL.md`、frontmatter 无效、描述过宽、会话未刷新。
+
+### 8.4 第四步：理解触发机制
+
+用一个简短的三层图解释渐进加载：
+
+1. Agent 先只看 `name + description`。
+2. 匹配任务后加载 `SKILL.md` 正文。
+3. 真正执行时才读取 `scripts/`、`references/`、`assets/`。
+
+这个解释能让用户理解为什么 `description` 不是普通简介，而是 Skill 能否被调用的核心索引。
+
+## 9. Skill 库
+
+### 9.1 不要把 Pack 和 Skill 混在同一个平面
+
+当前项目中的“巴菲特致股东信”是一个 Pack，内部含 20 个原子 Skills；“安全边际”才是一个具体 Skill。官网应明确两层：
+
+- Packs：由一本书、一套课程或一组材料蒸馏出的完整知识包。
+- Skills：可单独触发和执行的能力单元。
+
+用户可以从 Pack 进入，也可以直接搜索原子 Skill。
+
+### 9.2 筛选维度
+
+首版建议保留真正有区分度的筛选：
+
+- 内容来源：书籍、视频、课程、播客、访谈、资料集、实战经验。
+- 领域：投资、商业、写作、营销、学习、组织、决策、技术等。
+- 类型：Pack / 原子 Skill。
+- 维护方式：官方维护 / 社区维护。
+- 质量等级：官方蒸馏 / 社区认证 / 社区收录。
+- 可用平台：由兼容性与实测结果生成。
+
+不要在首版引入星级评分。样本少时评分没有信息量，也容易把开源贡献变成竞赛。
+
+### 9.3 搜索排序
+
+搜索同时匹配：
+
+- 名称和别名。
+- 用户会说的话，也就是触发语言。
+- 领域和来源。
+- 解决的问题。
+
+默认排序不只看 GitHub Stars，推荐综合：
+
+- 触发场景匹配度。
+- 质量等级。
+- 测试通过情况。
+- 最近维护时间。
+- GitHub 社交信号。
+
+### 9.4 Pack 详情页
+
+信息顺序：
+
+1. 一句话说明这个 Pack 帮用户解决什么。
+2. 来源、作者、年份、维护者、许可证和质量等级。
+3. 代表性使用场景。
+4. Pack 内 Skill 地图。
+5. 推荐学习或调用顺序。
+6. 安装整个 Pack / 选择安装单个 Skill。
+7. DIGEST、BOOK_OVERVIEW、GLOSSARY 和审计轨迹。
+8. GitHub、问题反馈和贡献者。
+
+### 9.5 原子 Skill 详情页
+
+信息顺序：
+
+1. 什么时候用。
+2. 什么时候不要用。
+3. 用户可能会说什么。
+4. Agent 会按什么步骤执行。
+5. 一个过去案例和一个未来案例。
+6. 触发测试、反例测试与最近结果。
+7. 关联 Skills：依赖、对比、组合。
+8. 安装与查看源码。
+
+这会比直接渲染整份 `SKILL.md` 更适合人类阅读，同时保留“查看原始文件”入口。
+
+## 10. GitHub 原生投稿与审核系统
+
+### 10.1 核心原则
+
+用户提交的不是全局 README 的一行，而是一个独立、可校验、可回滚的收录目录。全局 README、网站卡片、搜索索引和贡献者页面全部由这些目录自动生成。
+
+这样可以避免：
+
+- 多个人同时修改同一张 README 表格导致冲突。
+- README、官网和数据文件出现三套不一致信息。
+- 维护者手工复制投稿信息。
+- 删除或撤销一个收录项时难以追踪。
+
+### 10.2 推荐仓库结构
+
+```text
+cangjie-skill/
+├── registry/
+│   ├── buffett-letters-skill/
+│   │   ├── entry.yaml
+│   │   └── README.md
+│   ├── community-scene-skill/
+│   │   ├── entry.yaml
+│   │   ├── README.md
+│   │   └── skill/
+│   │       ├── SKILL.md
+│   │       ├── scripts/
+│   │       ├── references/
+│   │       └── assets/
+│   └── another-pack/
+│       ├── entry.yaml
+│       ├── README.md
+│       └── skills/
+│           ├── skill-a/SKILL.md
+│           └── skill-b/SKILL.md
+├── website/
+├── schemas/
+│   └── registry-entry.schema.json
+├── scripts/
+│   ├── validate-registry.*
+│   ├── build-catalog.*
+│   └── sync-readme.*
+└── .github/
+    ├── workflows/
+    │   ├── validate-submission.yml
+    │   └── deploy-website.yml
+    ├── PULL_REQUEST_TEMPLATE.md
+    └── CODEOWNERS
+```
+
+### 10.3 两种收录模式，共用一个目录模型
+
+#### 模式 A：外部 GitHub 仓库
+
+贡献者已开源。`entry.yaml` 的 `artifact.type` 为 `external`，保存仓库 URL、默认分支和可选的 Skill 路径。Cangjie 仓库不复制对方代码，只保存结构化索引与介绍页。
+
+适合：独立维护、有自己的 release 和 issue 的成熟项目。
+
+#### 模式 B：托管在 Cangjie 仓库中
+
+贡献者没有独立仓库。`entry.yaml` 的 `artifact.type` 为 `bundled`，实际文件放在同一目录的 `skill/` 或 `skills/` 下。
+
+适合：单个场景 Skill、小型 Pack、首次开源的创作者。
+
+两种模式在官网上的详情页结构一致，区别只体现在“源码位置”和“维护方式”。
+
+### 10.4 `entry.yaml` 建议契约
+
+```yaml
+schema_version: 1
+slug: margin-of-safety
+title: 安全边际
+summary: 在估值不确定时，用价值与价格之间的缓冲降低判断错误的代价。
+kind: skill
+language: zh-CN
+
+source:
+  type: book
+  title: 巴菲特致股东的信
+  creator: Warren Buffett
+
+artifact:
+  type: external
+  repository: https://github.com/kangarooking/buffett-letters-skill
+  path: margin-of-safety
+
+authors:
+  - github: kangarooking
+
+taxonomy:
+  domains: [investment, decision-making]
+  use_cases: [valuation, risk-control]
+
+quality:
+  tier: official-distilled
+  methodology: RIA-TV++
+  tests: available
+
+license: MIT
+```
+
+这里的字段是官网 Registry 的数据，不等于 `SKILL.md` frontmatter。两者必须分离，避免为了做官网而破坏 Agent Skills 的可移植性。
+
+### 10.5 投稿向导
+
+页面分为五步：
+
+1. 选择“已有 GitHub 仓库”或“上传本地文件夹”。
+2. 填写名称、解决的问题、典型触发语、反场景、作者、许可证和来源。
+3. 对于外部仓库，输入 URL 并检查公开可访问性；对于本地文件夹，只在浏览器本地读取和预览，不上传到 Cangjie 服务器。
+4. 生成 `entry.yaml`、`README.md`、目标目录名和 PR 检查清单。
+5. 跳转 GitHub 创建新文件或进入个人 fork 上传目录，然后创建 PR。
+
+GitHub 官方支持在无写权限仓库中创建或编辑文件时自动 fork，并引导用户发起 Pull Request；多文件目录投稿则先进入或创建个人 fork，再上传并向上游发 PR。因此首版无需保存 GitHub Token，也不需要自己实现账号体系。
+
+### 10.6 对“本地文件夹提交”的现实处理
+
+纯静态网站无法安全地替用户把文件写入 GitHub，也不应该在前端内嵌长期有效的仓库 Token。
+
+首版建议：
+
+- 浏览器本地读取目录，显示缺失文件和预检结果。
+- 自动生成 `entry.yaml` 与 `README.md`，让用户下载投稿包。
+- 若用户尚无 fork，先创建个人 fork；随后进入个人 fork 的 `registry/` 目录，通过 Add file → Upload files 拖入整个目录。
+- 用户选择新分支并创建 PR。
+
+GitHub Web 当前支持拖入文件夹，但单文件上限 25 MiB、单次最多 100 个文件。超出限制时，页面切换为 Git / GitHub Desktop 指南。
+
+### 10.7 PR 状态机
+
+```mermaid
+flowchart LR
+  A[官网填写投稿] --> B[生成目录与文件]
+  B --> C["GitHub Fork + PR"]
+  C --> D[自动格式校验]
+  D -->|失败| E[贡献者修改]
+  E --> D
+  D -->|通过| F[人工质量审核]
+  F -->|请求修改| E
+  F -->|通过| G[合并到 main]
+  G --> H[重建目录与官网]
+  H --> I[正式收录并署名]
+```
+
+推荐标签：
+
+- `submission:new`
+- `submission:external`
+- `submission:bundled`
+- `checks:failed`
+- `review:needed`
+- `review:changes-requested`
+- `ready-to-merge`
+
+## 11. 自动审核与人工审核
+
+### 11.1 自动审核负责客观事实
+
+自动检查建议分为六组：
+
+1. Registry 结构：目录名、slug、必填字段、唯一性、URL 格式。
+2. Agent Skills 规范：`SKILL.md` 存在、frontmatter 合法、name 与父目录一致、description 长度和字段类型。
+3. Cangjie 质量结构：触发场景、反场景、执行步骤、测试文件和来源信息是否存在。
+4. 安全：秘密信息扫描、符号链接、超大文件、危险二进制文件和异常路径。
+5. 外部链接：仓库可访问、默认分支存在、声明路径中能找到至少一个 `SKILL.md`、许可证可识别。
+6. 构建：目录页、详情页、搜索索引和自动 README 能否生成。
+
+自动检查不得执行投稿中的脚本。对 fork PR 使用权限受限的 `pull_request` 工作流；需要打标签或评论时单独使用受控工作流，不能在高权限上下文中 checkout 后执行投稿代码。
+
+### 11.2 人工审核负责判断价值
+
+人工审核不重复检查 YAML，而判断以下问题：
+
+- 这个 Skill 是否对应一个清晰、重复出现的真实场景？
+- 没有这个 Skill 时，通用 Agent 是否已经能同样好地完成？
+- `description` 是否足够精确，能触发又不会泛滥触发？
+- 执行步骤是否可操作、可判断完成，而不是口号？
+- 是否写清不要使用的情况和失败模式？
+- 来源、作者、许可证和引用是否可信？
+- 测试是否包含正例、诱饵和边界，而不是只证明“它能工作”？
+
+### 11.3 建议质量等级
+
+#### 官方蒸馏
+
+由 Cangjie 项目维护，完成 RIA-TV++ 全流程，有来源、验证、压力测试和审计轨迹。
+
+#### 社区认证
+
+由社区维护，符合 Agent Skills 标准，通过自动检查和人工审核，有明确测试与许可证，但不一定由 Cangjie 全流程生成。
+
+#### 社区收录
+
+格式合格、来源清楚、基本可用，但尚未完成完整压力测试。页面必须明确展示这一状态，避免用户误认为已获官方质量背书。
+
+不建议把所有合并项都标成“Cangjie 认证”。“收录”与“认证”必须是两个概念。
+
+## 12. 视觉设计方向
+
+### 方向一：现代知识档案馆（推荐）
+
+关键词：墨色、暖白、矿物金、朱砂、编辑设计、知识索引、精密网格。
+
+整体像一家当代研究机构或高级出版品牌，而不是古风网站。中文标题有适度书卷感，界面正文保持现代无衬线高可读性。卡片像档案卡，但通过细线、编号、分类章和数据排版体现秩序，不使用卷轴、毛笔、竹简等直白古风素材。
+
+优势：能同时承载“仓颉”的文化感和“Agent Skills”的技术感，适合内容型长页面，也容易形成独特品牌。
+风险：如果金色、印章和纹理使用过多，会变成文创商城。
+
+### 方向二：Agent Knowledge OS
+
+关键词：深海军蓝、冷白、青蓝节点、图谱、终端、实时状态。
+
+首页强调从知识节点到 Agent 行动的动态关系图，Skill 卡片更像开发者工具和 API Registry。
+
+优势：技术感强，开发者一眼能理解这是可执行能力系统。
+风险：容易与大量 AI SaaS 官网同质化，也会弱化内容蒸馏和中文品牌个性。
+
+### 方向三：未来出版物
+
+关键词：高对比黑白、大字号、非对称编辑布局、亮橙或荧光绿、实验性排版。
+
+把官网做成一本不断生长的数字杂志，每个 Pack 像一期专题。
+
+优势：传播截图很有记忆点，适合公众号和社交媒体。
+风险：复杂筛选、安装教程和长文档可能牺牲可用性。
+
+### 推荐融合方式
+
+以方向一作为品牌与内容底座，吸收方向二的知识图谱和状态可视化。不要把三套风格平均混合。
+
+### 12.1 推荐色彩
+
+- 背景暖白：`#F3F0E8`
+- 主墨色：`#151713`
+- 次级墨灰：`#565A50`
+- 矿物金：`#B69042`
+- 朱砂强调：`#C9472D`
+- 成功绿：`#2F7656`
+- 边框米灰：`#D9D3C5`
+
+深色模式使用墨黑而不是纯黑，卡片采用略暖的深灰，金色只用于关键状态和高质量徽章。
+
+### 12.2 字体策略
+
+- 中文标题：优先使用有现代感的宋体或衬线体作为展示字体。
+- 中文正文与 UI：高可读无衬线。
+- 英文、数字、代码：中性 Grotesk + 等宽字体。
+
+网页字体需要控制体积并设置系统字体回退，避免中文首屏因字体文件过大而变慢。
+
+### 12.3 图形语言
+
+- 使用真实 Skill 关系生成的节点图，而不是装饰性星空。
+- 用“编号、索引条、引用线、验证章”建立档案感。
+- 图标使用统一图标库，不用 emoji 作为正式功能图标。
+- 图片优先使用真实书籍、课程或仓库资产，并处理版权和封面使用边界。
+
+### 12.4 动效
+
+动效用于解释状态变化：
+
+- Hero 中长内容逐步压缩为多个 Skill 节点。
+- 鼠标经过 Skill 卡片时显示触发语言和相邻节点。
+- 安装命令复制后有明确反馈。
+- 投稿步骤和 CI 检查显示实时状态。
+
+避免持续漂浮、粒子背景和大面积视差。它们会增加噪音并降低文档阅读效率。
+
+## 13. 技术架构建议
+
+### 13.1 推荐技术栈
+
+- 框架：Astro。
+- 内容：Markdown/MDX + YAML Registry。
+- 交互岛：React、Preact 或 Svelte，仅用于搜索、筛选、安装命令和投稿向导。
+- 样式：CSS Design Tokens + Tailwind 或轻量组件层。
+- 搜索：构建时生成索引，使用 Pagefind 或 Fuse.js；首版不需要搜索服务。
+- Schema：JSON Schema + YAML 解析。
+- Skill 规范校验：官方 `skills-ref` 加项目自定义规则。
+- CI：GitHub Actions。
+- 部署：首版 GitHub Pages；若中国大陆访问质量成为核心指标，再把同一静态产物部署到国内对象存储/CDN。
+
+选择 Astro 的原因：
+
+- 内容页和 SEO 友好。
+- 默认输出静态页面，无服务器成本。
+- 允许局部交互，不必把整个网站做成 SPA。
+- 适合从 Git 仓库内容构建详情页。
+
+### 13.2 数据流
+
+```mermaid
+flowchart TD
+  R[registry 目录] --> V[Schema 与 Skill 校验]
+  V --> J[生成 catalog.json]
+  J --> W[Astro 静态页面]
+  J --> S[搜索索引]
+  J --> M[自动生成 README 列表]
+  W --> P["GitHub Pages / 静态托管"]
+```
+
+Registry 是唯一事实来源。网站不直接解析 README 表格，README 也不再手工维护收录列表。
+
+### 13.3 不需要的首版组件
+
+- 数据库。
+- 后台管理页面。
+- GitHub OAuth。
+- 用户画像和推荐算法。
+- 在线执行陌生 Skill。
+- 评分、评论、收藏和排行榜。
+- 上传原始书籍、视频或受版权保护的全文。
+
+## 14. 安全、版权与治理
+
+### 14.1 安全边界
+
+- 自动校验只能把提交内容当作数据，不能执行投稿中的脚本。
+- PR 工作流使用最小权限和只读 Token。
+- 禁止 secrets、私钥、cookie、访问令牌和个人敏感信息。
+- 禁止符号链接逃逸、超大二进制、构建产物和依赖目录。
+- 外部仓库只做结构与元数据检查，不自动安装或运行。
+
+### 14.2 版权边界
+
+投稿者必须确认：
+
+- 有权提交 Skill 本身及附带素材。
+- 原文引用控制在合理范围，并标注来源。
+- 不上传原书、完整课程、受版权保护字幕全集等材料。
+- 仓库或目录拥有明确许可证。
+- 外部仓库链接不等于 Cangjie 对内容版权做保证。
+
+### 14.3 治理文件
+
+首版建议补齐：
+
+- `CONTRIBUTING.md`
+- `CODE_OF_CONDUCT.md`
+- `SECURITY.md`
+- `PULL_REQUEST_TEMPLATE.md`
+- Registry schema 与示例目录
+- 收录、认证、下架和争议处理规则
+
+## 15. SEO 与传播
+
+每个 Pack 和 Skill 都应该拥有独立、可索引的 URL，并生成：
+
+- 独立 title 与 description。
+- Open Graph 分享图。
+- JSON-LD 中的软件或创意作品信息。
+- canonical URL。
+- sitemap。
+
+适合内容传播的页面模板：
+
+- “这本书被蒸馏成了哪些 Skills？”
+- “当你遇到什么问题时应该调用这个 Skill？”
+- “一个 Skill 如何通过正例、诱饵和边界测试？”
+
+分享图不只展示封面，应突出“解决的问题 + Skill 数量 + 质量等级”，让社交媒体用户在不读正文时也理解价值。
+
+## 16. 国际化与可访问性
+
+仓库已有中文、英文、日文 README，官网架构应从第一天支持多语言字段，但首版可以只完整发布中文。
+
+建议：
+
+- Registry 的 slug 保持语言无关。
+- 标题、摘要、详情正文使用 locale 文件或多语言 Markdown。
+- 缺少翻译时回退到中文并明确标识，而不是隐藏页面。
+- 所有交互支持键盘操作、焦点样式和减少动态效果。
+- 颜色不是唯一状态信号；质量徽章同时提供文字。
+- 正文对比度、字号和行宽优先于视觉实验。
+
+## 17. 分阶段实施
+
+### Phase 0：规范整理（2—3 天）
+
+- 定义 Registry schema。
+- 明确 Pack、Skill、外部链接、仓库托管四个概念。
+- 确定质量等级与人工审核清单。
+- 统一 `SKILL.md` 标准字段策略。
+- 把当前 22 个 Pack 迁移为 Registry 条目。
+
+交付标准：所有现有条目可被脚本读取，统计数字能自动生成。
+
+### Phase 1：官网 MVP（5—8 天）
+
+- 首页。
+- 学会使用。
+- Skill 库与搜索筛选。
+- Pack / Skill 详情页。
+- 方法论页。
+- 投稿说明页。
+- GitHub Pages 部署、SEO、基础统计。
+
+交付标准：用户可以完成“发现 → 安装 → 验证”的闭环。
+
+### Phase 2：GitHub 投稿闭环（4—6 天）
+
+- 投稿向导。
+- 两种模式的文件生成。
+- 浏览器本地目录预检。
+- PR 模板、CODEOWNERS、自动标签。
+- Registry、Skill 规范、安全和构建检查。
+- 合并后自动更新官网与 README。
+
+交付标准：一个外部贡献者不需要维护者代写文件即可完成合格 PR。
+
+### Phase 3：质量与社区（按真实需求）
+
+- 自动生成 PR 预览。
+- 贡献者页面。
+- 质量报告和测试历史。
+- 更完整的平台兼容性矩阵。
+- GitHub App 一键创建 PR，仅在投稿量证明有必要时开发。
+
+## 18. MVP 验收清单
+
+### 使用体验
+
+- 新用户可在 3 分钟内看懂 Skill、选择平台、复制命令并完成验证。
+- 移动端、桌面端均可完成搜索、安装和投稿阅读。
+- 每个可复制动作都有反馈。
+- 安装说明不使用未经验证的平台命令。
+
+### 内容与发现
+
+- 当前所有 Pack 均有独立详情页。
+- Pack 与原子 Skill 不混淆。
+- 搜索能匹配中文标题、英文 slug、触发语言和领域。
+- 所有计数来自 Registry 自动生成。
+
+### 投稿与审核
+
+- 外部链接和托管目录共用一套 entry schema。
+- PR 自动检查失败时给出可操作的错误信息。
+- 合并后无需人工修改 README 和网站数据。
+- 投稿代码不会在高权限 CI 中被执行。
+- 每个收录项都有作者、来源、许可证和质量等级。
+
+### 品牌与视觉
+
+- 视觉不是通用 AI 渐变 SaaS 风格。
+- 真实 Skill 名称和数据出现在视觉表达中。
+- 中文长文阅读体验稳定。
+- 动效可关闭，不影响核心操作。
+
+## 19. 主要风险与应对
+
+### 风险一：把“收录”误解为“官方认证”
+
+应对：建立三层质量徽章，详情页明确维护者、测试和审核范围。
+
+### 风险二：提交规则太重，社区不愿贡献
+
+应对：外部链接投稿只要求一个目录和结构化元数据；完整 RIA-TV++ 仅用于“官方蒸馏”认证，不把所有社区 Skill 强行变成拆书产物。
+
+### 风险三：提交规则太松，品牌质量下降
+
+应对：格式自动化、价值人工化；把反场景、许可证和最小测试作为合并底线。
+
+### 风险四：GitHub 对普通用户门槛较高
+
+应对：官网生成全部内容，用户只完成 GitHub 的 fork、粘贴或上传、创建 PR；用截图和动图把步骤压缩到一条路径。
+
+### 风险五：外部仓库后来失效或变质
+
+应对：定时只读检查链接、许可证和 Skill 路径；失效条目标记为“维护异常”，人工确认后下架，不自动删除。
+
+## 20. 最终推荐
+
+我建议把官网定义为：
+
+> 一个以 GitHub 为治理基础、以可验证 Agent Skills 为内容单位、以“学会使用—发现能力—参与贡献”为核心闭环的开放知识基础设施。
+
+最重要的不是先做一个漂亮首页，而是先确定 Registry 目录和质量规则。只要 Registry 是稳定的，首页、搜索、README、贡献者榜单、API、CLI 甚至未来的 GitHub App 都可以从同一份数据自然生长出来。
+
+## 21. 参考依据
+
+- Agent Skills 官方规范：https://agentskills.io/specification
+- Agent Skills 创建最佳实践：https://agentskills.io/skill-creation/best-practices
+- Agent Skills 评测方法：https://agentskills.io/skill-creation/evaluating-skills
+- Anthropic Skills 示例仓库：https://github.com/anthropics/skills
+- GitHub 创建新文件与自动 fork/PR：https://docs.github.com/en/repositories/working-with-files/managing-files/creating-new-files
+- GitHub 编辑其他仓库并自动 fork/PR：https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files
+- GitHub PR 模板：https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates
+- GitHub Pages 发布：https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
+- GitHub Actions `pull_request_target` 安全说明：https://docs.github.com/en/actions/reference/security/securely-using-pull_request_target

cangjie-skill/docs/plans/2026-07-13-cangjie-skill-website-mvp-functional-spec.md

@@ -0,0 +1,555 @@
+# Cangjie Skill 官网 MVP 功能与页面布局规格
+
+日期：2026-07-13
+状态：待确认的功能设计稿
+原则：功能优先、静态优先、GitHub 原生、暂缓视觉精修
+
+## 1. 产品范围
+
+首版官网只完成两个闭环：
+
+1. 用户找到一个适合自己的 Skill Pack，学会安装并完成一次调用。
+2. 贡献者提交一个外部 GitHub 仓库或本地 Skill 文件夹，并进入 GitHub PR 审核流程。
+
+首版不做：
+
+- 登录、站内账号和独立后台。
+- 收藏、评分、评论和排行榜。
+- 在线运行陌生 Skill。
+- 多语言、深色模式和复杂动效。
+- 独立的贡献者中心。
+- 每个原子 Skill 的独立详情页。
+- 数据库、搜索服务和推荐算法。
+
+当前约 22 个 Pack 直接进入 Registry。Pack 内约 300 个原子 Skills 在 Pack 详情页中列出，并参与搜索，但首版不为每个原子 Skill 生成单独页面。
+
+## 2. MVP 页面地图
+
+首版只有五个核心页面：
+
+```mermaid
+flowchart TD
+  H[首页] --> L[使用教程]
+  H --> S[Skill 库]
+  H --> U[提交 Skill]
+  S --> D[Skill Pack 详情]
+  D --> L
+  U --> G[GitHub PR]
+```
+
+路由：
+
+```text
+/
+/learn
+/skills
+/skills/[slug]
+/submit
+```
+
+GitHub、README、完整 RIA-TV++ 方法论和项目介绍先作为外部链接，不单独建设官网页面。
+
+## 3. 全站公共布局
+
+### 3.1 页头
+
+| 区域 | 内容 | 行为 |
+|---|---|---|
+| 左侧 | Cangjie Skill / 仓颉 Skill | 点击回首页 |
+| 中间 | 使用教程、Skill 库、提交 Skill | 当前页面高亮 |
+| 右侧 | GitHub | 新窗口打开仓库 |
+
+移动端把三个导航项收进简单菜单。首版不做悬浮玻璃效果、搜索弹窗或多层下拉菜单。
+
+### 3.2 页脚
+
+只保留：
+
+- GitHub 仓库。
+- README / 方法论。
+- License。
+- 问题反馈。
+- 公众号和交流群入口。
+
+## 4. 首页 `/`
+
+首页的任务是分流，不承担完整文档功能。
+
+### 4.1 页面顺序
+
+| 顺序 | 模块 | 必须展示的内容 | 主要动作 |
+|---|---|---|---|
+| 1 | Hero | 产品一句话、简短解释 | 开始使用、浏览 Skill 库 |
+| 2 | 数据概览 | Pack 数、原子 Skill 数、RIA-TV++ | 无 |
+| 3 | 三步说明 | 选择、安装、调用 | 查看使用教程 |
+| 4 | 精选 Packs | 6 个代表性 Pack | 查看详情、查看全部 |
+| 5 | 提交入口 | 两种投稿方式说明 | 提交 Skill |
+| 6 | 页脚 | 项目与社区链接 | 外部链接 |
+
+### 4.2 Hero 文案
+
+标题：
+
+> 把读过、看过、听过的知识，变成 Agent 真正会用的能力。
+
+说明：
+
+> Cangjie Skill 把书、课程和长内容中的方法论，蒸馏成可触发、可执行、可测试的 Agent Skills。
+
+按钮：
+
+- 主按钮：开始使用 → `/learn`
+- 次按钮：浏览 Skill 库 → `/skills`
+
+### 4.3 数据概览
+
+数据必须从 Registry 构建时计算，禁止写死：
+
+- `pack_count`
+- `skill_count`
+- `contributor_count`
+
+RIA-TV++ 是方法标签，不作为动态计数。
+
+### 4.4 三步说明
+
+1. 找到适合当前问题的 Pack。
+2. 复制到 Agent 的 Skills 目录。
+3. 用测试 Prompt 确认它能正确触发。
+
+### 4.5 精选 Packs
+
+首版固定展示 6 个，由 `featured: true` 决定。每项只显示：
+
+- 名称。
+- 一句话用途。
+- 来源类型。
+- 原子 Skill 数量。
+- 2—3 个标签。
+- 质量等级。
+- 查看详情。
+
+不在首页显示完整简介、测试报告或全部子 Skills。
+
+## 5. 使用教程 `/learn`
+
+这个页面只解决“怎么安装、怎么验证”。
+
+### 5.1 页面布局
+
+| 区域 | 内容 |
+|---|---|
+| 页面标题 | 3 分钟开始使用 Cangjie Skills |
+| 工具选择 | 经过验证的平台标签页 |
+| 安装范围 | 个人级 / 项目级 |
+| 安装命令 | 可复制命令和目标目录 |
+| 验证步骤 | 查看 Skill、测试正例、测试反例 |
+| 常见问题 | 目录、文件名、frontmatter、会话刷新 |
+| 下一步 | 前往 Skill 库 |
+
+### 5.2 平台配置
+
+平台信息不硬编码在页面组件里，使用一个配置文件：
+
+```yaml
+platforms:
+  - id: claude-code
+    name: Claude Code
+    status: verified
+    user_skill_dir: ~/.claude/skills/
+    project_skill_dir: .claude/skills/
+  - id: codex
+    name: OpenAI Codex
+    status: experimental
+    user_skill_dir: TBD
+    project_skill_dir: TBD
+```
+
+实现前必须逐个平台验证目录和发现方式。未验证的平台显示“实验性”，不能给出看似确定的命令。
+
+### 5.3 安装步骤
+
+1. 用户选择平台。
+2. 用户选择个人级或项目级。
+3. 页面展示目标目录和复制命令。
+4. 页面展示一个来自该 Pack 的 `should_trigger` Prompt。
+5. 页面展示一个 `should_not_trigger` Prompt，帮助确认触发边界。
+
+### 5.4 错误处理
+
+常见错误按优先级展示：
+
+- 目录名与 `name` 不一致。
+- 文件名不是大写 `SKILL.md`。
+- YAML frontmatter 无效。
+- 只复制了 `SKILL.md`，遗漏所需的 `scripts/` 或 `references/`。
+- 安装后没有重新打开会话。
+- 当前客户端尚不支持 Agent Skills 标准。
+
+## 6. Skill 库 `/skills`
+
+### 6.1 页面目标
+
+让用户通过“我要解决什么问题”找到 Pack，而不是只按书名浏览。
+
+### 6.2 页面布局
+
+| 区域 | 内容 | 交互 |
+|---|---|---|
+| 标题区 | 已收录的 Cangjie Skill Packs | 无 |
+| 搜索区 | 单个搜索框 | 输入即时过滤 |
+| 筛选区 | 来源、领域、质量等级 | 可组合、多选 |
+| 结果信息 | 共 N 个结果、清除筛选 | 重置 |
+| 结果列表 | Pack 行或简单卡片 | 进入详情 |
+| 空状态 | 无匹配结果 | 清除筛选、提交新 Skill |
+
+### 6.3 搜索范围
+
+前端搜索索引包含：
+
+- Pack 中文名、英文名和 slug。
+- 一句话用途。
+- 来源名称和作者。
+- 标签和领域。
+- Pack 内原子 Skill 的名称。
+- 典型触发语言。
+
+首版使用构建时 JSON + 浏览器本地搜索，不接外部搜索服务。
+
+### 6.4 首版筛选项
+
+- 来源：书籍、视频、课程、播客、访谈、资料集、实战经验。
+- 领域：投资、商业、写作、营销、学习、组织、决策、技术、其他。
+- 质量：官方蒸馏、社区认证、社区收录。
+
+首版不做平台筛选、更新时间筛选、Star 排序和复杂综合排序。
+
+### 6.5 每个结果项
+
+必须显示：
+
+- Pack 名称。
+- 一句话用途。
+- 来源。
+- 原子 Skill 数量。
+- 质量徽章。
+- 最多 3 个标签。
+- 查看详情。
+
+可选显示 GitHub Stars，但不参与默认排序。
+
+默认排序：`featured` 优先，其余按名称稳定排序。后续有真实使用数据后再设计推荐排序。
+
+## 7. Skill Pack 详情 `/skills/[slug]`
+
+### 7.1 页面布局
+
+| 顺序 | 模块 | 内容 |
+|---|---|---|
+| 1 | 标题区 | 名称、用途、来源、作者、维护者、许可证、质量等级 |
+| 2 | 操作区 | 查看安装方法、打开 GitHub |
+| 3 | 适用场景 | 3—5 个真实使用场景 |
+| 4 | 原子 Skills | 可搜索的子 Skill 列表 |
+| 5 | 推荐使用 | 推荐先安装哪些、测试 Prompt |
+| 6 | 项目资料 | DIGEST、INDEX、GLOSSARY、测试报告等可用链接 |
+| 7 | 贡献信息 | 维护者、贡献者、更新时间、问题反馈 |
+
+### 7.2 原子 Skill 列表
+
+每个子 Skill 只展示：
+
+- `name`
+- 中文标题。
+- `description` 的精简版本。
+- 触发语言。
+- 是否有测试文件。
+- 在 GitHub 查看原始 `SKILL.md`。
+
+首版点击子 Skill 不进入独立详情页，可以展开查看摘要或直接跳 GitHub。
+
+### 7.3 两种来源的差异
+
+外部仓库：
+
+- “打开 GitHub”跳到贡献者仓库。
+- 网站在构建时读取 Registry 中保存的数据。
+- 外部仓库不可访问时显示“来源暂时不可用”，但保留已构建页面。
+
+仓库托管：
+
+- “打开 GitHub”跳到 Cangjie 仓库对应目录。
+- 安装命令直接复制本仓库中的 Skill 路径。
+
+## 8. 提交 Skill `/submit`
+
+### 8.1 页面目标
+
+让贡献者生成一个合格的 Registry 目录并完成 GitHub PR，而不是在网站后台保存投稿。
+
+### 8.2 页面步骤
+
+| 步骤 | 页面内容 | 输出 |
+|---|---|---|
+| 1 | 选择提交方式 | 外部 GitHub / 本地文件夹 |
+| 2 | 填写基本信息 | Registry entry 草稿 |
+| 3 | 自动预检 | 错误、警告、通过项 |
+| 4 | 预览提交内容 | `entry.yaml` 与目录结构 |
+| 5 | 前往 GitHub | 创建文件或上传目录并发 PR |
+
+页面顶部始终显示当前进度。错误未解决前不允许进入最后一步；警告可以继续，但会带入 PR 检查清单。
+
+### 8.3 公共字段
+
+- 名称。
+- slug。
+- 一句话用途。
+- 类型：Pack / 单个 Skill。
+- 来源类型、来源名称、原作者。
+- 投稿者 GitHub 用户名。
+- 许可证。
+- 领域标签，最多 5 个。
+- 典型使用场景，至少 2 个。
+- 版权确认复选框。
+
+贡献者不能自己选择“官方蒸馏”或“社区认证”。投稿时统一为 `pending`，质量等级由维护者审核后设置。
+
+### 8.4 外部 GitHub 模式
+
+额外字段：
+
+- 仓库 URL。
+- 默认分支，可自动发现。
+- Skill 路径。
+
+自动预检：
+
+- URL 是否为公开 GitHub 仓库。
+- 声明路径是否存在。
+- 是否找到至少一个 `SKILL.md`。
+- 是否能识别许可证。
+- `SKILL.md` 基本 frontmatter 是否有效。
+
+输出只有一个必须提交的文件：
+
+```text
+registry/<slug>/entry.yaml
+```
+
+网站生成内容并引导用户在 GitHub 创建新文件。无写权限时，GitHub 完成 fork 和 PR 流程。
+
+### 8.5 本地文件夹模式
+
+浏览器通过目录选择读取文件，仅在本地完成预检，不上传到官网服务器。
+
+自动预检：
+
+- 是否存在 `SKILL.md`。
+- 目录名和 `name` 是否一致。
+- frontmatter 是否可解析。
+- 是否包含秘密信息和异常大文件。
+- 是否存在不安全符号链接或不允许的二进制文件。
+- 文件数是否适合 GitHub Web 上传。
+
+输出：
+
+```text
+registry/<slug>/
+├── entry.yaml
+└── skill/
+    ├── SKILL.md
+    └── optional-resources/
+```
+
+网站提供“下载投稿包”，然后引导用户：fork 仓库 → 上传目录 → 创建 PR。
+
+### 8.6 提交失败与恢复
+
+- 表单内容保存在浏览器本地，刷新后可恢复。
+- GitHub 跳转失败时仍可下载 `entry.yaml` 或投稿包。
+- 文件夹不支持时显示 Git / GitHub Desktop 的替代流程。
+- 验证错误必须指出文件、字段和修复建议，不能只显示“提交失败”。
+
+## 9. Registry 数据结构
+
+### 9.1 最小目录
+
+```text
+registry/<slug>/
+├── entry.yaml
+└── skill/          # 仅仓库托管模式存在
+```
+
+不再强制每个条目额外提交 `README.md`。详情页由 `entry.yaml` 和 Skill 内容生成，减少 PR 文件数量。
+
+### 9.2 最小 `entry.yaml`
+
+```yaml
+schema_version: 1
+slug: buffett-letters-skill
+title: 巴菲特致股东的信
+summary: 用于投资判断、企业分析和资本配置的 20 个方法论 Skills。
+kind: pack
+language: zh-CN
+
+source:
+  type: book
+  title: 巴菲特致股东的信
+  creator: Warren Buffett
+
+artifact:
+  type: external
+  repository: https://github.com/kangarooking/buffett-letters-skill
+  path: .
+
+submitter:
+  github: kangarooking
+
+tags:
+  - investment
+  - decision-making
+
+use_cases:
+  - 评估企业长期竞争优势
+  - 在不确定估值中设置安全边际
+
+license: MIT
+quality: pending
+featured: false
+```
+
+`quality` 与 `featured` 在合并前由维护者确认。
+
+### 9.3 构建产物
+
+构建脚本读取 Registry，生成但不要求手工编辑：
+
+```text
+generated/catalog.json
+generated/search-index.json
+generated/stats.json
+```
+
+这些文件可以作为构建缓存，也可以只存在于 CI 产物中。Registry 始终是唯一事实来源。
+
+## 10. 审核流程
+
+```mermaid
+flowchart LR
+  A[提交目录 PR] --> B[Schema 校验]
+  B --> C[Skill 格式校验]
+  C --> D[安全与链接检查]
+  D --> E[网站构建检查]
+  E --> F[人工质量审核]
+  F --> G[维护者设置质量等级]
+  G --> H[合并]
+  H --> I[自动部署官网]
+```
+
+### 10.1 自动检查
+
+- 目录与 slug 一致。
+- `entry.yaml` 符合 JSON Schema。
+- 外部链接和声明路径存在。
+- 托管 Skill 通过 Agent Skills 格式校验。
+- 无秘密信息、超大文件和危险路径。
+- 新条目不与现有 slug 重复。
+- 全站能够成功构建。
+
+PR 自动检查只读取投稿内容，不能执行投稿中的脚本。
+
+### 10.2 人工检查
+
+- 是否解决明确且重复出现的问题。
+- `description` 是否能准确触发。
+- 执行步骤是否可操作。
+- 是否有明确反场景和边界。
+- 来源和许可证是否可信。
+- 测试是否包含正例、反例和边界。
+
+### 10.3 质量等级
+
+- `official-distilled`：Cangjie 官方按 RIA-TV++ 完整蒸馏。
+- `community-certified`：社区维护，完成格式、质量和测试审核。
+- `community-listed`：满足基本收录标准，尚未完成完整压力测试。
+
+## 11. 技术方案
+
+### 11.1 推荐实现
+
+- Astro：静态页面和内容路由。
+- YAML + JSON Schema：Registry。
+- 构建时脚本：生成目录、统计和搜索索引。
+- 少量浏览器 JavaScript：搜索、筛选、复制、投稿表单和本地目录预检。
+- GitHub Actions：PR 校验和站点部署。
+- GitHub Pages：首版托管。
+
+### 11.2 数据流
+
+```mermaid
+flowchart TD
+  R[Registry] --> V[校验脚本]
+  V --> C[Catalog 与搜索索引]
+  C --> A[Astro 页面]
+  A --> P[静态站点]
+  M[PR 合并] --> R
+```
+
+没有运行时数据库。用户访问的是构建完成的静态页面，投稿表单只在浏览器本地生成文件。
+
+## 12. 基础视觉约束
+
+在功能阶段只使用：
+
+- 白色或暖白背景。
+- 黑色正文。
+- 一个主色用于按钮和链接。
+- 系统字体。
+- 统一的 8px 间距体系。
+- 统一的按钮、输入框、标签和状态提示。
+- 桌面最大内容宽度 1200px。
+- 移动端单列布局。
+
+首版不制作品牌插画、复杂图谱、封面系统和动效。页面信息层级正确后再统一升级视觉。
+
+## 13. 验收标准
+
+### 13.1 用户使用闭环
+
+- 首页两个主按钮路径正确。
+- 用户能搜索并筛选当前全部 Packs。
+- 搜索子 Skill 名称能返回所属 Pack。
+- 每个 Pack 都有可访问详情页。
+- 用户能从详情页进入正确的安装说明和 GitHub 仓库。
+
+### 13.2 投稿闭环
+
+- 外部 GitHub 模式能生成合法 `entry.yaml`。
+- 本地文件夹模式不会把文件上传到官网服务器。
+- 无效 Skill 能得到具体错误信息。
+- 用户能下载投稿包并进入 GitHub PR 流程。
+- 合并新 Registry 条目后，下一次部署自动出现新页面。
+
+### 13.3 安全与稳定性
+
+- PR 校验不执行投稿脚本。
+- 外部仓库失效不会导致整个网站构建失败。
+- Registry 单个条目错误时能定位到具体文件。
+- 无 JavaScript 时仍能浏览首页、列表和详情页。
+- 移动端能完成浏览和阅读；本地文件夹投稿可提示改用桌面端。
+
+## 14. 推荐开发顺序
+
+1. 定义 `entry.yaml` Schema。
+2. 把当前 22 个 Pack 迁入 Registry。
+3. 编写校验与 Catalog 生成脚本。
+4. 完成首页、列表、详情和教程页。
+5. 完成外部 GitHub 投稿。
+6. 完成本地文件夹预检和投稿包下载。
+7. 接入 PR 校验和 GitHub Pages 部署。
+8. 功能验收后再进入统一视觉设计。
+
+## 15. 最终 MVP 决策
+
+首版最重要的产品单位是 Skill Pack，不是每一个原子 Skill。原子 Skills 仍然会被索引、搜索和展示，但不单独建页。这能显著降低内容迁移、路由、SEO 和维护复杂度，又不影响用户发现具体能力。
+
+首版最重要的后台是 GitHub PR，不是自建管理系统。只有当投稿量、非 GitHub 用户比例或维护者协作成本证明现有流程不足时，再考虑 GitHub App 或独立后台。

cangjie-skill/docs/plans/2026-07-13-cangjie-skill-website-mvp-implementation.md

@@ -0,0 +1,118 @@
+# Cangjie Skill Website MVP Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use executing-plans to implement this plan task-by-task.
+
+**Goal:** Build a minimal, functional static website that teaches Skill usage, exposes the current Skill Pack registry, supports search and filtering, and generates GitHub-native submissions for external repositories or local Skill folders.
+
+**Architecture:** Add an Astro static site under `website/` and keep structured catalog data under the repository-level `registry/`. Build-time Node scripts validate YAML entries with JSON Schema and generate all pages without a runtime database. Client JavaScript is limited to search, copy actions, form persistence, local folder validation, and submission bundle generation.
+
+**Tech Stack:** Astro 7, TypeScript, Vitest, js-yaml, Ajv, Fuse.js, JSZip, GitHub Actions, GitHub Pages.
+
+---
+
+### Task 1: Scaffold the Astro application and test harness
+
+**Files:**
+- Create: `website/package.json`
+- Create: `website/astro.config.mjs`
+- Create: `website/tsconfig.json`
+- Create: `website/vitest.config.ts`
+- Create: `website/src/env.d.ts`
+
+**Steps:**
+1. Define production and development scripts for registry validation, tests, Astro checks, builds, and preview.
+2. Install pinned dependencies and generate `website/package-lock.json`.
+3. Add a smoke unit test proving Vitest is operational.
+4. Run `npm test` and confirm PASS.
+
+### Task 2: Define and seed the Registry
+
+**Files:**
+- Create: `schemas/registry-entry.schema.json`
+- Create: `registry/<slug>/entry.yaml` for all 22 current Packs.
+- Create: `website/scripts/validate-registry.mjs`
+- Create: `website/src/lib/catalog.ts`
+- Test: `website/src/lib/catalog.test.ts`
+
+**Steps:**
+1. Write tests for loading entries, rejecting duplicate slugs, and computing 22 Packs / 300 Skills.
+2. Run the tests and confirm they fail before the loader exists.
+3. Implement the schema, YAML loader, validation script, and catalog statistics.
+4. Seed the 22 entries currently listed in `README.md`.
+5. Run `npm run validate:registry` and `npm test`; both must pass.
+
+### Task 3: Build shared layout and the homepage
+
+**Files:**
+- Create: `website/src/layouts/BaseLayout.astro`
+- Create: `website/src/components/Header.astro`
+- Create: `website/src/components/Footer.astro`
+- Create: `website/src/components/PackCard.astro`
+- Create: `website/src/styles/global.css`
+- Create: `website/src/pages/index.astro`
+
+**Steps:**
+1. Implement accessible header, footer, skip link, buttons, cards, and responsive content container.
+2. Render Hero, computed stats, three-step usage explanation, six featured Packs, and submission CTA.
+3. Use restrained white/ink styling with one accent and no visual dependencies.
+4. Run Astro checks and build.
+
+### Task 4: Build tutorial, library, and Pack detail pages
+
+**Files:**
+- Create: `website/src/data/platforms.ts`
+- Create: `website/src/pages/learn.astro`
+- Create: `website/src/pages/skills/index.astro`
+- Create: `website/src/pages/skills/[slug].astro`
+
+**Steps:**
+1. Implement verified/experimental platform guidance and copyable install paths.
+2. Render the complete Pack list with search text and filter metadata.
+3. Add client-side search, source filter, domain filter, quality filter, reset, count, and empty state.
+4. Generate one static detail page per Pack with metadata, use cases, install guidance, and GitHub link.
+5. Run tests, Astro checks, and build.
+
+### Task 5: Implement submission generation and local validation
+
+**Files:**
+- Create: `website/src/lib/submission.ts`
+- Test: `website/src/lib/submission.test.ts`
+- Create: `website/src/pages/submit.astro`
+
+**Steps:**
+1. Write tests for slug normalization, YAML generation, missing fields, frontmatter parsing, and secret detection.
+2. Implement pure submission utilities until tests pass.
+3. Build a five-step form supporting `external` and `bundled` modes.
+4. Persist form values locally, preview generated YAML, and provide copy/download actions.
+5. For local folders, validate client-side and generate a ZIP containing `entry.yaml` plus the Skill folder.
+6. Provide GitHub create-file/fork instructions without storing credentials.
+7. Run tests, Astro checks, and build.
+
+### Task 6: Add contribution guidance and CI
+
+**Files:**
+- Create: `CONTRIBUTING.md`
+- Create: `.github/PULL_REQUEST_TEMPLATE.md`
+- Create: `.github/workflows/website-ci.yml`
+- Create: `.github/workflows/deploy-pages.yml`
+
+**Steps:**
+1. Document external and bundled submission structures.
+2. Add a PR checklist for provenance, license, tests, and secrets.
+3. Add read-only pull request CI that validates Registry data, runs tests/checks, and builds the site without executing contributed scripts.
+4. Add GitHub Pages deployment from `main` with the repository base path.
+5. Validate workflow YAML structure by inspection and run the same CI commands locally.
+
+### Task 7: End-to-end verification
+
+**Files:**
+- Modify only files required to fix verification findings.
+
+**Steps:**
+1. Run `npm run validate:registry`.
+2. Run `npm test`.
+3. Run `npm run check`.
+4. Run `npm run build`.
+5. Start the local site and verify every route returns 200.
+6. Capture desktop and mobile screenshots, inspect hierarchy, overflow, form states, and empty search state.
+7. Fix all visible or functional defects and rerun the complete verification set.

cangjie-skill/docs/releases/v2.5.0.md

@@ -0,0 +1,41 @@
+# 倉頡 Skill v2.5.0 发布说明
+
+> 发布日期：2026-08-30
+
+v2.5.0 把「从长内容中拆出很多平铺 Skill」升级为「先维护一份 Capability Bundle，
+再按场景编译交付形态」。这个版本的重点不是增加更多文档，而是让蒸馏结果更少、
+更容易安装，也更容易更新、修复和评测。
+
+## 核心升级
+
+- **Capability Bundle 单一事实源**：能力卡、元数据、关联和去向集中在
+  `books/<slug>/.cangjie/capabilities/`，避免 single 与 pack 各自演进后产生偏差。
+- **single / compact pack 双输出**：`single` 用一个路由入口承载整本内容；
+  `pack` 保留一个路由入口，只把通过晋级门的少数能力拆成独立 Skill。
+- **统一 CLI**：`scripts/cangjie.py` 提供 `doctor` / `compile` / `replan-output` /
+  `update` / `repair` / `rollback` / `eval` / `benchmark` 等入口。
+- **确定性与可回滚**：引入内容寻址缓存、编译不变量、写锁、staging 校验、
+  手工修改检测、发布前快照和 rollback。
+- **增量更新与修复**：支持源文档 diff、影响分析、事务性补丁、失败案例诊断和防过拟合修复。
+- **评测与基准链路**：包含触发评测、匿名输出对比、静态 A 类指标和 Naval 试点资产。
+- **Registry v2 + 官网**：新 schema 能表达输出模式、入口数和能力数；官网同步展示，
+  原有 Registry v1 条目无需改造。
+- **官网依赖安全升级**：Astro 7.2.9、js-yaml 5.4.1，发布时 `npm audit` 为 0 vulnerabilities。
+
+## 兼容性
+
+- 不破坏现有 Registry v1 条目和 legacy pack。
+- 新产物建议使用 Registry v2；字段迁移见
+  [`docs/migrations/2026-08-25-v2.0-to-v2.1.md`](https://github.com/kangarooking/cangjie-skill/blob/v2.5.0/docs/migrations/2026-08-25-v2.0-to-v2.1.md)。
+- 官网子项目许可证已与根仓库统一为 MIT。
+
+## 文档与社群一致性
+
+- 英文 `README.md` 与中文 `README.zh-CN.md` 均引用同一个
+  `assets/wecom-cangjie-group-qr.png`。
+- 二维码文件以中文 README 当前展示的版本为准，本次发布不使用本地分支中的另一张图覆盖它。
+
+## 验证边界
+
+本版本发布前执行 schema、Bundle、编译确定性、Registry、网站测试与构建校验。
+真实 Agent 宿主上的盲测结果具有 host-specific 属性，不把静态评测误表述为所有宿主的通用效果。

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

@@ -0,0 +1,90 @@
+# 倉頡 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 后端。