📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -46,27 +46,32 @@
|
||||
│ candidates/
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 阶段 1.5: 三重验证 │ V1 跨域 / V2 预测力 / V3 独特性
|
||||
│ 阶段 1.5: 三重验证 │ V1 跨域 / V2 预测力 / V3 独特性 (知识验证)
|
||||
└─────────┬─────────┘
|
||||
│ 通过单元 + rejected/
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 阶段 2: RIA++ 构造 │ R / I / A1 / A2 / E / B
|
||||
│ 阶段 1.6: 晋级门 │ 产品化验证: promoted / router 去向
|
||||
└─────────┬─────────┘
|
||||
│ 每个 skill 的 SKILL.md
|
||||
│ destinations.json
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 阶段 3: 链接 │ Zettelkasten + INDEX.md
|
||||
│ 阶段 2: RIA++ 构造 │ R / I / A1 / A2 / E / B 能力卡
|
||||
└─────────┬─────────┘
|
||||
│ .cangjie/capabilities/ (Capability Bundle)
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 阶段 3: 链接 │ Zettelkasten → Bundle 的 also_read
|
||||
└─────────┬─────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 阶段 4: 压力测试 │ test-prompts.json + 盲测 + 回炉
|
||||
│ 阶段 4: 压力测试 │ 触发/路由评测 + 盲测 + 回炉
|
||||
└─────────┬─────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 阶段 5: 交付 │ DIGEST.md 精华长文 + 安装到 skills 目录
|
||||
│ 阶段 5: 编译与交付 │ cangjie.py compile (single/pack) + DIGEST + 安装
|
||||
└───────────────────┘
|
||||
│
|
||||
▼
|
||||
@@ -75,9 +80,11 @@
|
||||
|
||||
## 不变量 (任何迭代都不能违反)
|
||||
|
||||
1. **原子性**: 一个 skill 只做一个方法论单元,不能"大而全"
|
||||
2. **可追溯**: 每个 skill 必须有原文引用,指向源书章节 (视频指向时间戳/分 P)
|
||||
3. **可验证**: 每个 skill 必须通过三重验证 + 压力测试
|
||||
4. **可进化**: 每个 skill 必须附带 darwin 兼容的 test-prompts.json
|
||||
5. **用户参与**: 阶段 0 之后必须让用户确认骨架; 阶段 1.5 之后必须让用户确认入选名单
|
||||
6. **可交付**: 流程终点是"用户能调用"— skill 必须被安装到 skills 目录,读者需求由 DIGEST.md 承接
|
||||
1. **原子性**: 一个能力只做一个方法论单元,不能"大而全"（single 的"一个"指一个发现入口,内部能力仍原子化）
|
||||
2. **可追溯**: 每个能力必须有原文引用,指向源书章节 (视频指向时间戳/分 P)
|
||||
3. **可验证**: 每个能力必须通过三重验证 + 压力测试
|
||||
4. **可进化**: 每个晋级 Skill 必须附带 darwin 兼容的评测用例
|
||||
5. **用户参与**: 阶段 0 之后必须让用户确认骨架; 阶段 1.5 之后必须让用户确认入选名单; 阶段 5 编译前必须让用户轻确认输出模式
|
||||
6. **可交付**: 流程终点是"用户能调用"— 编译产物必须被安装到 skills 目录,读者需求由 DIGEST.md 承接
|
||||
7. **单一事实源** (v2.1, ADR-002): single 与 pack 从同一份 Capability Bundle 编译,引用同一组稳定 capability_id;生成目录只读,检测到本地手改不得静默覆盖
|
||||
8. **能力不失联** (v2.1): 未晋级能力保留为来源路由入口内的能力卡,每个 active 能力在 destinations 中恰好一个去向
|
||||
|
||||
@@ -21,13 +21,35 @@
|
||||
|
||||
**降级方案**: 当前环境不支持并行 sub-agent 时,用同样 5 个 extractor prompt 串行执行 (每次以"干净视角"执行一个 extractor 的职责,不带上一个 extractor 的判断),产出格式不变。
|
||||
|
||||
## 按 extractor 类型分化的上下文策略（v2.2）
|
||||
|
||||
阶段 1 的唯一目标是**覆盖率**（宁错杀,不做筛选）。但 5 类 extractor 查找对象的分布特性不同,
|
||||
不能一刀切全量扫描,也不能一刀切检索式（后者会直接损害覆盖率,方案缺口 B）:
|
||||
|
||||
| extractor | 查找对象的分布特性 | 上下文策略 |
|
||||
|---|---|---|
|
||||
| framework | 思维模型常跨章节隐性分布,需要全局视野 | **保持全量扫描** |
|
||||
| principle | 原则散落全书,且需判断"是否反复出现" | **保持全量扫描** |
|
||||
| case | 案例是局部命中型,有明确文本锚点 | 检索式取块 |
|
||||
| counter-example | 反例是局部命中型,有明确警告性措辞 | 检索式取块 |
|
||||
| glossary | 术语是局部命中型,可先用确定性方法预筛 | 检索式取块 + 脚本预筛 |
|
||||
|
||||
**检索式取块的前置条件**: 先用确定性脚本建好内容地图 —
|
||||
`python3 scripts/build_chunks.py <源文件> --out books/<slug>/.cangjie/` 生成结构感知块,
|
||||
`python3 scripts/build_index.py books/<slug>/.cangjie/chunks/chunks.jsonl` 建 SQLite FTS5 索引。
|
||||
检索式 extractor 的流程: 关键词召回相关块 → 取邻接块防断章取义 → 证据不足时扩大窗口 →
|
||||
候选需回原文核验。五个 extractor 仍使用独立任务上下文,独立判断不变。
|
||||
|
||||
**覆盖率硬门**: 检索式改造后,最终通过三重验证的候选相对全量扫描基线**漏检数必须为 0**。
|
||||
做不到就把该 extractor 退回全量扫描,Token 收益从别处找。每次改动检索策略都要重跑基准集覆盖率对比。
|
||||
|
||||
## 长文本分块策略 (超出单个 sub-agent 上下文时)
|
||||
|
||||
一本大部头 (如全五卷选集) 或几小时视频的转写稿,可能超出单个 sub-agent 能一次读完的上下文。此时:
|
||||
|
||||
1. **切块**: 按章节/卷/分 P 等自然边界切块,每块控制在 sub-agent 能连同 `BOOK_OVERVIEW.md` 一起舒适读完的规模 (经验值: 单块 ≤5 万字)
|
||||
1. **切块**: 优先复用 `build_chunks.py` 的结构感知块（按章节/卷/分 P 等自然边界,单块 ≤5 万字）
|
||||
2. **全局锚点**: 每一块都必须附带 `BOOK_OVERVIEW.md` — 它是 extractor 判断"这段内容在全书中扮演什么角色"的锚点,不能省
|
||||
3. **逐块扫描**: extractor 逐块提取候选,标注每条候选来自哪一块 (source_chapter 字段天然承载)
|
||||
3. **逐块扫描**: 全量扫描型 extractor 逐块提取候选,标注每条候选来自哪一块 (source_chapter 字段天然承载,有 chunk_id 时一并记录)
|
||||
4. **块间汇总**: 全部块扫完后,extractor 自己先做一轮合并 — 同一方法论在多块中出现的,合并成一条并保留所有出处 (这些多出处恰好是阶段 1.5 V1 跨域验证的证据)
|
||||
5. 汇总后的结果才写入 `candidates/<type>.md`
|
||||
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# 阶段 1.6 — 独立 Skill 晋级门（产品化验证）
|
||||
|
||||
## 为什么需要这一步
|
||||
|
||||
阶段 1.5 回答的是"这个候选是否值得保留"（知识验证）。它没有回答第二个问题：
|
||||
**它是否值得成为一个独立、可发现、可安装的 Skill**（产品化验证）。
|
||||
|
||||
把每个通过验证的知识点都变成独立 Skill,会制造安装负担、命名理解成本和相邻能力
|
||||
之间的触发竞争（《纳瓦尔宝典》样本因此产出 19 个 Skill,这是真实读者反馈"Skill
|
||||
太多"的直接来源）。晋级门把"知识保留"和"Skill 数量"解耦：**未晋级的方法完整保留
|
||||
为来源路由入口内的能力卡,不会被删掉,也不会失联。**
|
||||
|
||||
## 五条判据
|
||||
|
||||
一个候选只有同时满足以下条件,才有资格成为晋级 Skill：
|
||||
|
||||
| # | 判据 | 问题 | 要求 |
|
||||
|---|---|---|---|
|
||||
| 1 | 独立意图 | 用户会不提书名、单独提出这个任务吗？ | **必须通过** |
|
||||
| 2 | 独立契约 | 有自己的输入、步骤、输出和完成标准,不只是一个观点或术语？ | **必须通过** |
|
||||
| 3 | 独立运行 | 不加载全书或多个兄弟能力也能正确执行？ | **必须通过** |
|
||||
| 4 | 独立复用 | 预计会在多个任务/项目中重复调用,或需要被其他 Skill 组合？ | 与 5 至少 1 条通过 |
|
||||
| 5 | 独立评测 | 能写出明确的正向、负向、近邻和输出断言？ | 与 4 至少 1 条通过 |
|
||||
|
||||
## 执行步骤
|
||||
|
||||
1. 对 `verified.md` 中每个单元逐条评审五条判据,记录布尔结果与一句话理由;
|
||||
2. 把结果写入 Capability Bundle（`verified.yaml`）中该能力的 `promotion` 字段:
|
||||
- 通过 → `destination: promoted`
|
||||
- 未通过 → `destination: router`（保留为能力卡,经来源路由入口访问）
|
||||
3. 检查预算: 可发现入口总数（1 个来源路由入口 + 晋级 Skill 数）默认软预算 **8**。
|
||||
超出时按预期调用频率、跨场景复用、独特性、证据强度和触发可分性排序,
|
||||
超出预算的候选先降为能力卡;只有用户明确选择 exhaustive 且验证证明不能安全合并时才允许超过;
|
||||
4. 同步 `destinations.json`: 每个 active 能力恰好一个主要去向（`promoted_to` 或 `served_by`）。
|
||||
|
||||
## 硬规则
|
||||
|
||||
- 不能为了卡数量,把输出契约不同的能力强行拼成一个模糊 Skill;
|
||||
- 未晋级候选**不进入 rejected/**,它们通过了知识验证,只是不单独发现;
|
||||
- 晋级 Skill 与来源路由入口必须互有近邻负例（阶段 4 验证）,避免同一请求双触发;
|
||||
- 晋级判定的目标函数是: **用最少的可发现入口覆盖最多的高价值用户意图,同时不让任何能力失联。**
|
||||
|
||||
## split-on-evidence
|
||||
|
||||
single-first 不是单向门。当出现以下证据时,可把能力卡提升为独立 Skill：
|
||||
|
||||
1. 用户显式请求（`cangjie.py replan-output --dry-run` 生成 side-by-side 预览）;
|
||||
2. 用户自愿导出的本地路由记录（默认关闭,只记 capability_id 与时间戳）;
|
||||
3. 社区反馈聚合（issue / 反馈表中"我希望 X 能单独触发"的诉求）。
|
||||
|
||||
任何情况下都不得在用户不知情时上报使用数据。拿不到证据就诚实保持现状,不用猜测代替证据。
|
||||
@@ -1,10 +1,18 @@
|
||||
# 阶段 2 — RIA++ 构造 skill
|
||||
# 阶段 2 — RIA++ 构造能力卡
|
||||
|
||||
## 目标
|
||||
|
||||
把阶段 1.5 通过的每个方法论单元,构造成一个符合 Claude Code skill 规范的 SKILL.md。
|
||||
把阶段 1.5 通过的每个方法论单元,构造成一张 RIA 能力卡,并在 Capability Bundle 中登记。
|
||||
|
||||
使用模板: `templates/SKILL.md.template`
|
||||
**v2.1 产出位置（ADR-002）**:
|
||||
- 能力卡正文（R/I/A1/A2/E/B 六段,**不带 frontmatter**）→ `books/<slug>/.cangjie/capabilities/cards/<slug>.md`
|
||||
- 能力元数据（稳定 `capability_id`、intents、keywords、one_liner、importance + 依据、`frontmatter.description`）→ `verified.yaml` 中该能力的条目（schema: `schemas/capability-bundle.schema.json`）
|
||||
|
||||
最终的 SKILL.md 由 `scripts/cangjie.py compile` 从 Bundle 确定性编译,阶段 2 不再直接写最终 Skill 目录。
|
||||
旧流程（直接按 `templates/SKILL.md.template` 写独立 Skill 目录）仍受支持,产物按 legacy-pack 处理,
|
||||
迁移方法见 `docs/migrations/v2.0-to-v2.1.md`。
|
||||
|
||||
内容结构参考模板: `templates/SKILL.md.template`（六段定义不变）
|
||||
|
||||
## RIA++ 六段
|
||||
|
||||
@@ -67,20 +75,32 @@ E 的作用是让 agent 在调用这个 skill 时有明确的执行路径,不是
|
||||
|
||||
B 的作用是**防止乱调用**。没有 B 的 skill,会在不该用的时候被用,反而帮倒忙。
|
||||
|
||||
## Frontmatter 设计
|
||||
## 能力元数据设计（登记进 verified.yaml,不写在卡片里）
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <skill-slug> # kebab-case, 唯一
|
||||
description: | # A2 的浓缩版, ≤300 字
|
||||
<何时用 + 何时不用 + 关键 trigger>
|
||||
source_book: 《穷查理宝典》 查理·芒格
|
||||
source_chapter: 第三讲
|
||||
tags: [decision, mental-model, cognitive-bias]
|
||||
related_skills: [] # 阶段 3 填充
|
||||
---
|
||||
capability_id: cap.<book>.<slug> # 稳定 ID: 文案润色只加 revision,语义拆分/合并才换 ID
|
||||
revision: 1
|
||||
status: active
|
||||
slug: <skill-slug> # kebab-case, 唯一
|
||||
title: <中文标题>
|
||||
importance: critical|high|medium|low # 必须附 importance_rationale（引用图入度/篇幅占比/任务命中）
|
||||
one_liner: <一句话决策规则> # 进入 cheatsheet
|
||||
intents: [<用户意图>...] # 进入路由表
|
||||
keywords: [<中英关键词>...]
|
||||
also_read: [] # 阶段 3 填充
|
||||
card: cards/<slug>.md
|
||||
frontmatter:
|
||||
description: | # A2 的浓缩版, ≤300 字;晋级 Skill 编译时用作 description
|
||||
<何时用 + 何时不用 + 关键 trigger>
|
||||
tags: [decision, mental-model]
|
||||
source_evidence:
|
||||
- source_id: src-main-book
|
||||
location: 第三讲 # 视频填时间戳/分 P
|
||||
```
|
||||
|
||||
来源信息（source_book/source_chapter）由 `source_evidence` 承载;编译器把它们放进
|
||||
`metadata.cangjie.*`,不再作为顶层 frontmatter 字段（Agent Skills 规范兼容,方案 §11.1）。
|
||||
|
||||
## 常见失败模式
|
||||
|
||||
1. **I 段写成书摘** — 如果读起来像"本章作者说了 X",你在抄书不是在解释。重写。
|
||||
|
||||
@@ -15,28 +15,24 @@
|
||||
3. **组合 (composes-with)**: A 和 B 经常配合使用
|
||||
- 例: "能力圈判断" 组合 "安全边际"
|
||||
|
||||
## 执行步骤
|
||||
## 执行步骤（v2.1 Bundle 版）
|
||||
|
||||
1. 列出阶段 2 产出的所有 skill
|
||||
1. 列出阶段 2 登记进 Capability Bundle 的所有能力
|
||||
2. 两两扫描,识别是否存在上述三类关系
|
||||
3. 在每个 skill 的 frontmatter `related_skills` 字段填入:
|
||||
```yaml
|
||||
related_skills:
|
||||
- slug: multi-mental-models
|
||||
relation: depends-on
|
||||
- slug: forward-reasoning
|
||||
relation: contrasts-with
|
||||
```
|
||||
4. 在每个 skill 的 SKILL.md 末尾追加"相关 skills"段,用自然语言说明关系
|
||||
5. **回填 A2**: 链接关系确定后,回到每个 skill 的 A2 段,把阶段 2 留下的"与相邻 skill 的区分"初稿改成定稿 (同时同步 frontmatter `description`)
|
||||
6. 生成 `books/<slug>/INDEX.md` (模板 `templates/INDEX.md.template`)
|
||||
7. 把 `candidates/glossary.md` 整理提升为 `books/<slug>/GLOSSARY.md` — 它是所有 skill 共享的术语词典,应在产出根目录可见,而不是埋在审计目录里; INDEX.md 中链接它
|
||||
3. 把关系写入 `verified.yaml` 中各能力的 `also_read` 字段（能力卡编译时生成"补读"列）;
|
||||
依赖/对比/组合的语义说明写在能力卡末尾的"相关能力"段
|
||||
4. **回填 A2**: 链接关系确定后,回到每张能力卡的 A2 段,把阶段 2 留下的"与相邻能力的区分"
|
||||
初稿改成定稿 (同时同步 Bundle 中该能力的 `frontmatter.description`)
|
||||
5. 把 `candidates/glossary.md` 整理提升为 `books/<slug>/GLOSSARY.md`,并复制到
|
||||
`.cangjie/capabilities/book/glossary.md`（编译时随产物分发）
|
||||
6. 路由表 / 能力索引（capability-index.md）由 `cangjie.py compile` 从 Bundle 自动生成,
|
||||
**不再手写 INDEX.md**;legacy-pack 流程仍可用 `templates/INDEX.md.template`
|
||||
|
||||
## INDEX.md 必须包含
|
||||
## 编译生成的能力索引必须包含
|
||||
|
||||
- 书的基本信息 (作者/年份/一句话主旨)
|
||||
- 所有 skill 的列表,按主题分组
|
||||
- 引用图 (mermaid flowchart 或 graph)
|
||||
- 所有能力的列表,按主题分组
|
||||
- 意图/关键词 → 能力卡的映射
|
||||
- 推荐学习顺序 (从依赖关系推出)
|
||||
|
||||
## 节制原则
|
||||
|
||||
@@ -2,10 +2,17 @@
|
||||
|
||||
## 目标
|
||||
|
||||
在 skill 真正交付之前,用一批测试 prompt 验证它**被调用的精准度**和**被调用后的输出质量**。
|
||||
在能力真正交付之前,用一批测试 prompt 验证它**被调用的精准度**和**被调用后的输出质量**。
|
||||
|
||||
不通过的必须回炉 — 不是表面修补 `description` 字段,而是重做阶段 2 的 A2 / E / B。
|
||||
|
||||
**v2.1 分层测试对象**:
|
||||
- **晋级能力（promoted）**: 按本文全部要求测触发精度,诱饵中必须含"应由来源路由入口处理"的场景
|
||||
（晋级 Skill 与路由入口互斥的近邻负例,方案 §4.6.3）;
|
||||
- **路由能力（router）**: 测"经来源路由入口可达"——给定意图 prompt,路由表应指向正确的能力卡;
|
||||
- 评测用例格式见 `schemas/eval-suite.schema.json`,可用 `scripts/run_trigger_evals.py` 做机械判分与
|
||||
train/validation 切分（60/40,固定种子,validation 在选版前保持隐藏）。
|
||||
|
||||
## 为什么必须做
|
||||
|
||||
A2 (trigger) 是拆书里最难的环节。一个 skill 做得再漂亮,trigger 不准就等于不存在。压力测试是**唯一**能在发布前发现 trigger 问题的方法。
|
||||
|
||||
@@ -1,14 +1,28 @@
|
||||
# 阶段 5 — 交付 (DIGEST + 安装)
|
||||
# 阶段 5 — 编译与交付 (compile + DIGEST + 安装)
|
||||
|
||||
## 目标
|
||||
|
||||
把流水线的产出真正送到两类使用者手里:
|
||||
|
||||
1. **Agent** — skill 必须被安装到宿主环境的 skills 目录,否则永远不会被调用
|
||||
1. **Agent** — Capability Bundle 必须被编译成 single 或 compact pack,并安装到宿主环境的 skills 目录,否则永远不会被调用
|
||||
2. **人类读者** — 用一篇 `DIGEST.md` 精华长文承接"不想读全书,但想看精华"的需求
|
||||
|
||||
这两件事都不做,前面五个阶段的产出就只是一堆躺在仓库里的文件。
|
||||
|
||||
## 第 0 步 — 从 Bundle 编译产物（v2.1）
|
||||
|
||||
```bash
|
||||
python3 scripts/cangjie.py compile \
|
||||
--bundle books/<slug>/.cangjie/capabilities \
|
||||
--out dist/<slug> --output auto
|
||||
```
|
||||
|
||||
1. auto 决策器按 single-first-v1 策略给出推荐（decision report 一屏展示理由与备选）;
|
||||
2. 把报告给用户轻确认: **按推荐 / 改成 single / 改成 pack** — 默认值只是推荐,不能取消用户显式选择;
|
||||
3. 确认后加 `--yes`（或显式 `--output`）执行。编译器自动做 staging 校验、发布哈希登记与原子发布;
|
||||
4. 编译产物必须通过 `validate_skill_pack.py`（编译器已内置为硬门）。
|
||||
5. `update` / `repair` 默认沿用本次决策,不因新增材料静默改变产物形态;重新选型走 `replan-output --dry-run`。
|
||||
|
||||
## 第 1 步 — 生成 DIGEST.md (面向读者的精华长文)
|
||||
|
||||
### 为什么放在最后而不是阶段 0
|
||||
@@ -41,17 +55,19 @@
|
||||
- [ ] 有批判/局限部分,不是全程吹捧
|
||||
- [ ] 每个方法论小节都有 skill 链接
|
||||
|
||||
## 第 2 步 — 安装 skill 到宿主环境
|
||||
## 第 2 步 — 安装编译产物到宿主环境
|
||||
|
||||
产出目录 `books/<slug>/<skill-slug>/` 只是构建产物,宿主 (Claude Code / Cursor 等) 不会从这里加载 skill。必须安装:
|
||||
编译输出目录（如 `dist/<slug>/`）只是构建产物,宿主 (Claude Code / Cursor 等) 不会从这里加载 skill。必须安装:
|
||||
|
||||
1. **问用户装哪里** (一次性问清,不要逐个 skill 问):
|
||||
- 用户级: `~/.claude/skills/<skill-slug>/` (所有项目可用)
|
||||
- 项目级: `<project>/.claude/skills/<skill-slug>/` 或 `.cursor/skills/<skill-slug>/`
|
||||
- 用户级: `~/.claude/skills/` (所有项目可用)
|
||||
- 项目级: `<project>/.claude/skills/` 或 `.cursor/skills/`
|
||||
- 用户也可能只想要仓库形式 (发布到 GitHub),那就跳过安装
|
||||
2. **只安装通过阶段 4 测试的 skill** — 未通过的留在构建目录里回炉
|
||||
3. 复制 (或 symlink) 整个 skill 目录,含 `SKILL.md` 和 `test-prompts.json`
|
||||
4. 安装后抽 1–2 个 skill 用一句 should_trigger 的 prompt 验证宿主能加载并触发
|
||||
2. **single 模式**: 复制整个入口目录（含 `references/`）,1 个可发现入口;
|
||||
**pack 模式**: 分别复制来源路由入口目录和各晋级 Skill 目录（`capability-destinations.json` 是审计清单,不必安装）
|
||||
3. **只安装通过阶段 4 测试的产物** — 未通过的留在构建目录里回炉
|
||||
4. 安装后抽 1–2 个入口用一句 should_trigger 的 prompt 验证宿主能加载并触发;pack 模式另抽 1 条 router 意图验证路由入口
|
||||
5. **不要同时安装同一本书的 single 和 pack** — 两套 description 会重复覆盖意图,二选一
|
||||
|
||||
## 第 3 步 — 收尾汇报
|
||||
|
||||
|
||||
Reference in New Issue
Block a user