kc-beta 0.6.1 → 0.7.0

package/template/skills/zh/meta-meta/skill-authoring/SKILL.md

@@ -27,6 +27,25 @@ rule-skills/
 
 Not every rule needs all of these. A simple threshold check might only need SKILL.md and a script. A complex semantic rule might need detailed references and many samples. Start minimal, add as needed during testing.
 
+## 颗粒度：默认 1 条规则 = 1 个技能目录
+
+默认**每条规则一个独立技能目录**。仅当同时满足以下两个条件时，才能把多条规则合并到同一个文件：
+
+1. 共享同一证据（同一章节 / 同一表格 / 同一字段）——找到一条就找到了全部。
+2. 一同成败——一条失败，其他几乎必然失败（例如必填字段表中的同辈规则，表本身缺失则全部失败）。
+
+合并时，用显式范围命名文件，让下游消费者（workflow-run、dashboards、finalization）可以从文件名解析规则覆盖范围：
+- ✅ `check_r013_r017.py`（R013、R014、R015、R016、R017——同一披露表格，一同失败）
+- ❌ `check_r001_r050_r078.py`（不同章节，即使主题相关，也应分开）
+
+### 反模式：统一运行器（unified runner）
+
+如果你发现自己在写一个 `unified_qc.py`（或 `batch_runner.py`、`master_check.py`）把全部 110 条规则塞进一个 Python 文件里，**停下来**。这说明你的单条规则技能写错了，不是架构错了。请修复单条技能。
+
+E2E #4 给出了代价：智能体写了一个 `unified_qc.py` 绕过它不信任的 110 个独立技能。结果是 6,930 条生产检查里出了 1,150 个错误（16.6%），相位计数器卡在 `production_qc`，而真实工作还在 skill_authoring 里进行。统一运行器在局部看起来很高效，全局上是个错误。
+
+如果某些独立技能跑不通，正确的应对是定位并修复出问题的那几条，而不是合并所有技能。整个流水线（extraction → skill_testing → distillation → production_qc）的前提就是「一条规则 = 一个可独立验证的产物」。
+
 ## Writing SKILL.md
 
 ### Frontmatter

package/template/skills/zh/meta-meta/work-decomposition/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: work-decomposition
+description: 在 rule_extraction → skill_authoring 过渡阶段决定如何把规则集拆分为 TaskBoard 任务。涵盖排序方法（难度优先 / Shannon–Huffman、广度优先、深度优先、二分切分）、分组策略（多条规则合并到一个任务 vs. 各自独立的判断标准）、三轴难度评估、以及如何写一份贯穿全流程都能用得上的 PATTERNS.md 项目记忆。当进入 rule_extraction、进入 skill_authoring 或感觉 TaskBoard 走偏想要重新拆分时使用。
+---
+
+# 工作拆分（Work Decomposition）
+
+KC 的 main agent 是指挥者。指挥者决定下一步做什么——而这个决定凌驾于后续所有选择之上。错误的拆分会让整个会话变得昂贵：规则顺序错了，agent 会把同一种结构重新设计三遍；不相关的规则被合并到一个 skill 里，最终 check.py 就会变成 E2E #4 那种"统一执行器"反模式；本应合并的相关规则被分散到不同 skill，agent 会把同样的 chunker 逻辑重新推导 17 次。
+
+这份 skill 是指挥者做这类决定的操作手册。它放在 `meta-meta/` 下，因为工作拆分是系统级的纪律，不是某条规则的具体技巧。互补的 `task-decomposition`（同样在 `meta-meta/` 下）覆盖单条规则**内部**的结构——locate → extract → normalize → judge → comment。本 skill 覆盖的是规则**集合**该如何切分成 TaskBoard 任务。
+
+## 何时使用本 skill
+
+- **进入 rule_extraction 时**。读完法规、拆出规则之后，在宣布该阶段完成之前，先决定这些规则会以什么顺序被处理、是否分组。覆盖审计与 chunk refs 都是这两个决定下游的工作。
+- **进入 skill_authoring 时**。TaskBoard 是空的（引擎不再自动生成 per-rule 任务）。从 `describeState` 读取规则列表，决定分组与顺序，然后为每个工作单元调用 `TaskCreate`。
+- **运行中觉得拆分不对时**。如果 TaskBoard 越走越奇怪（规则按错误顺序累积、明明该合并的两条规则被拆到两个任务里），停下来重新拆分。暂停 5 分钟重新规划的代价，会在接下来 2 条规则里被更合理的形状收回。
+
+## 锁定原则
+
+1. **硬跟踪、软执行（Hard tracking, soft executing）**。无论你怎么分组，引擎都从磁盘事实推导里程碑（`rule_skills/<id>/SKILL.md`、`check_*.py`、`workflows/<id>/...`）。覆盖率由引擎核实；分组由你自己决定。聪明的任务命名绕不过下限，但下限也不规定任务形状。
+2. **最难的规则信息量最大**。难规则会强迫你把 chunker、分类器、verdict 形状、worker LLM 层级都设计到位。简单规则可以廉价地复用这套机制的子集。先把硬 case 落实，简单 case 自然继承。
+3. **PATTERNS.md 是承重的记忆**。没有持续累积的参考文件，每条规则都从空白开始，同一种形状会被反复设计。有了它，工作能复利。
+
+---
+
+## 排序方法
+
+明确选一种，把选择本身写进 PATTERNS.md 的第一条。"我用 Shannon–Huffman，因为 R028 的多方主体 verdict 形状会决定其他规则的 chunker"是合法决定；"我从 catalog.json 顶端开始一条条往下做"不是——那只是没有决定。
+
+### Shannon–Huffman（难度优先）—— 推荐默认
+
+先处理**最难**的规则。把这条难规则需要的 chunker、verdict 形状、worker 层级当作设计下限。后续规则按难度递减处理，每一条都是已经搭好的机制的退化形态。
+
+**何时选**：规则集合复杂度不均匀，并且你怀疑少数几条难规则会决定整体形状（合规/监管类工作几乎总是如此）。E2E #5 里 GLM 阴差阳错走的就是这条路，最终在真实 LLM 驱动的 workflow 上拿到了 0.6% ERROR；DS 走自底向上，最终 78% 的 verdict 是 NOT_APPLICABLE。
+
+**为何用 "Huffman" 而不是 "Shannon" 来类比**：Huffman 编码先处理低频符号来构造最优前缀码。KC 的对应物是单条成本高、出现频率低的规则——R028 那种类型，数量少但主导整个设计空间。先碰它们，简单规则就能廉价继承框架。
+
+**编译器设计上的对应**：在最坏情况被正确处理之前，不要先优化常见情况。常见情况快没用——如果最坏情况要重新设计整个流水线。
+
+### 广度优先（轮询）
+
+先把每条规则都做到浅层（skill 骨架 + 第一遍正则），然后回头逐条加深。适用情景：
+
+- 整体集合的覆盖比单条规则的深度更重要（例如急需一份覆盖报告）
+- 你还不知道哪些规则难
+- 你在试新方法学，想先廉价地在多条规则上验证流水线形状
+
+**陷阱**：你可能在浅层 skill 上宣布 rule_extraction 完成，从此再没回头加深。比深度优先更糟，因为光看覆盖率，门控看上去是过的。
+
+### 深度优先（一次只做一条，做到底）
+
+把规则 1 完整做完（SKILL.md + check.py + 测试通过）再碰规则 2。适用情景：
+
+- 规则之间高度独立（合规工作里少见）
+- 指挥模型 context 较小，规则之间反复加载形状的成本不高
+- 你在跑通端到端流水线，确认能产出之前不去铺规模
+
+**陷阱**：第一条规则的形状被写死；第 5 条之后才发现要重构，意味着 1–4 都要重写。配合 PATTERNS.md 来缓解。
+
+### 二分切分
+
+按一个有意义的轴把规则集分成两半（公募/私募、文档类型、法规章节），然后递归。适用情景：
+
+- 切分轴是结构性的（例如银行类规则 vs 信托类规则）——可以为各分区分别建工具
+- 某些分区可以整块跳过（D6 适用性判断说"这个语料不适用"）
+
+**陷阱**：在切分轴并不真实存在时过早分区。agent 投入两套工具，最后发现需要共同的底座。先用 2–3 条规则在每一侧验证切分再投入。
+
+### "最简单的先做" —— 不要默认选这个
+
+很有诱惑力，因为它能积累信心、能很快出可见的产出。**对监管规则集不要默认选这个**——简单规则不会教给你任何能迁移到难规则上的东西，框架会围绕错误形状结晶。只在你为一个全新项目调试工具链、必须先证明流水线能产出**任何**东西时再用它。
+
+---
+
+## 规则分组
+
+默认是**一条规则 → 一个任务 → 一个 skill 目录**。这样覆盖率可量、TaskBoard 清晰。只有当合并真的能减少总工作量、又不会把不相关的关切耦合起来时，才合并。
+
+### 何时合并
+
+把多条规则合并到一个任务（以及一个 check_r###_r###.py 文件）只有在以下条件**全部**满足时：
+
+- 这些规则共享同一个 source chunk（看的是同一段法规的同一段文字）
+- 它们共享同一种输入形态（例如同一张必填字段表）
+- 一条规则的判断逻辑是另一条的子串或近似变体
+- 一次失败通常意味着多条规则同时失败（R013 不可能在 R015 失败的情况下通过）
+
+例：R013 / R015 / R017 都在检查报告第 3 页那张表是否包含某些必填字段。同一个 chunk、同一次 parse、同一种 verdict 形状。合并为 `check_r013_r015_r017.py`，并创建一个 TaskCreate 任务 `R013/R015/R017 — 必填字段表`。引擎从文件系统推导里程碑时会识别这个合并 check.py，给三个 rule_id 都计入覆盖。
+
+### 何时保持独立
+
+任何**一项**满足时就保持独立：
+
+- 规则引用不同章节——即使概念上相关（例如 R013 的披露内容和 R028 的托管责任都属"报告"，但章节不同、证据链不同）
+- 规则需要不同的 worker LLM 层级（R005 需要旗舰模型做精细判断，R001 是正则）
+- 规则适用于不同文档类型（一条只对公募基金报告生效，另一条只对私募基金报告生效）
+- 一条规则的失败模式是另一条规则的特殊失败模式（不要把父规则和子规则合并——子规则的检查会冗余地重新执行父规则的检查）
+
+v0.6.2 D2 的反模式说法已经把失败情形说得很清楚了：
+> 如果你发现自己在写 unified_qc.py 那种绕过单 rule skill 的大杂烩，那就是说明你的 per-rule skill 是错的。是去修它们，不是去替换它们。
+
+那段话来自 E2E #4：一个指挥模型写了 2,400 行 `unified_qc.py` 一次性跑所有规则。结果出现 1,150 条 ERROR verdict（16.6%），因为每条规则的失败都连带把所有其他规则的判定也带崩了。Per-rule skill 是 KC 的粒度单元，这是有原因的。
+
+### 合并 check 的命名约定
+
+确实需要合并时，文件名要把范围写明：
+
+- `check_r013_r015_r017.py` — 三条具体规则
+- `check_r002_r007.py` — 连续区间（R002 到 R007）
+- `check_r013-r017.py` — 替代写法，也接受
+
+引擎从文件系统推导里程碑时会解析这些文件名，把范围内每条 rule_id 都算进覆盖。合并既是代码组织也是文档——下游消费者（workflow-run、dashboards、release 工具）通过文件名判断覆盖。
+
+---
+
+## 难度评估 —— 三轴评分
+
+在确定顺序之前，对每条提取出来的规则在三个轴上打分。一次快速 worker LLM 调用即可（tier3 足够，不是要做深判断），把结果写到 `rules/difficulty.json`，指挥者随后在排 TaskBoard 顺序时读取。
+
+### 轴 1 — 思维链深度
+
+这条规则需要多少次串联判断？数一下 agent 必须依次完成的操作：
+
+- 1：`text contains "行业统一信息披露渠道"`（正则）
+- 2：先分类产品类型，再检查渠道（两步）
+- 3+：分类产品类型 → 定位披露段落 → 解析表格 → 与另一段的表格做比较（多步）
+
+打分：1 / 2 / 3+。
+
+### 轴 2 — 模块数量
+
+这条规则包含多少个独立子检查？"模块"指逻辑上可分离的谓词。
+
+- 1：单一谓词（"必须提及渠道 A"）
+- 2-3：小型必填列表（"必须提及 A、B、C、D"）
+- 4+：长清单或条件分支（"如果是公募，则渠道 X+Y；如果是私募，则渠道 Z；任何情况下还要包含管理人身份"）
+
+打分：1 / 2-3 / 4+。
+
+### 轴 3 — 跨规则交互
+
+这条规则是否引用其他规则、依赖其输出，或必须与之保持一致性？
+
+- 0：独立（多数规则）
+- 1：交叉引用一条其他规则（例如 R007 引用 R013 的表格存在性）
+- 2+：与多条规则紧耦合，需要跨规则的一致性推理
+
+打分：0 / 1 / 2+。
+
+### 总难度
+
+三轴求和（最低 1+1+0=2，最高 3+3+2=8）。降序排序。前 2-3 条是你的设计下限——先做它们。
+
+70 条规则的语料典型分布大致：
+- 10-15 条难（求和 5-8）
+- 30-40 条中（求和 3-4）
+- 20-30 条易（求和 2）
+
+不要把分级做过头。它是规划辅助，不是契约。如果工作中你发现一条评 2 的实际是 6，更新 PATTERNS.md，把剩余队列重新排序。
+
+---
+
+## PATTERNS.md —— 项目记忆纪律
+
+KC 的 main agent 在阶段之间没有连续记忆。每次 agent 重新读 `describeState`，看到的都是同一份规则列表和同一份里程碑。没有外部累积参考的话，每条规则的设计都从零开始。
+
+`rules/PATTERNS.md` 就是那份参考。Agent 自己拥有它（通过 `workspace_file` 写入，不通过任何 tool wrapper）。引擎在 skill_authoring + skill_testing 阶段的每次系统提示中都会带上它。上限约 5 KB，token 成本可忽略。
+
+### 写什么 —— 能迁移的形状
+
+一条好的 PATTERNS.md 条目记录的是某个能在**下一条**规则上**省工作**的东西。三类合法内容：
+
+✅ **可迁移的形状** —— verdict 形状、chunker 粒度、接口决定，后续规则会复用。
+
+```
+R028（托管责任）需要多方 verdict 形状：
+  { primary_party: PASS|FAIL, secondary_parties: [...], reasons: [...] }
+作为有多个责任主体的规则的默认形状。
+在 R029、R031 上确认可复用。
+```
+
+✅ **项目级约束** —— 关于语料或环境的事实，影响多条规则。
+
+```
+样本语料表头中英双语（EN+ZH）。
+Chunker 必须按 ZH 表头切分，不是 EN —— 5 份样本上验证过。
+不这样做，R013 / R015 / R017 都会少抽。
+```
+
+✅ **反模式 + 原因** —— 你试过、为什么失败、应该怎么改。
+
+```
+试 tier4 出 JSON verdict → 80% 的时候返回空。
+tier3（Qwen3.5）字段名会幻觉。最终选 tier2（DeepSeek-V3.2）
+作为所有结构化输出规则的默认。Tier1 只留给证据模糊时的
+verdict 推理（R005、R024）。
+```
+
+### 不写什么 —— 日志倾倒反模式
+
+下面这些只增加 token 成本、不增加决策价值。未来的你读 PATTERNS.md 是为了搞清楚**接下来怎么做**，不是回放**已经发生了什么**。
+
+❌ **完成日志** —— 已经在 tasks.json + 文件系统里。
+
+```
+R001 完成。R002 完成。R003 部分通过。R004 完成。
+```
+
+❌ **工具调用回声** —— 已经在 events.jsonl 里。
+
+```
+调 workspace_file 写 check_R013.py。再调 sandbox_exec。
+然后把结果交给 worker_llm_call。
+```
+
+❌ **文件系统权威事实** —— 引擎从磁盘自己推导。
+
+```
+Workflows 都在 workflows/R001_workflow.py 这种位置。一共 28 个。
+```
+
+❌ **对话总结** —— PATTERNS.md 不是叙事文档，agent 和用户都不会当故事读。
+
+```
+跟用户讨论之后，决定先做银行类规则。用户提到信托产品不在范围。
+```
+
+如果某个项目级决定来自对话，写成约束而不是叙述：
+
+```
+本次运行排除信托产品（D6 适用性 NO）。
+跳过 R078、R092、R104 —— 它们的 skill 只是占位。
+```
+
+### 何时更新、何时追加
+
+- **追加**：发现了新的、能迁移的东西。
+- **更新已有条目**：在更晚的规则上做事时发现一种更好的抽象。不要被第一条难规则的形状锁死——JIT 编译器在 profile 数据推翻早期假设时会重编译；PATTERNS.md 也应当这样演进。
+- **删除条目**：发现一条之前写的是错的。在文件底部用一行简要原因标记删除：
+
+```
+[DELETED 2026-04-29] "FAIL verdict 一律用 tier1"
+原因：R005 + R007 在 tier2 上工作良好；tier1 只留给证据真正
+歧义的情形（整个集合大概 3 条规则）。
+```
+
+### 容量
+
+PATTERNS.md 全文控制在约 5 KB 之内。超过时，剪掉最不可执行的条目（最近 5 条规则里没影响过任何决定的那些）。记忆是给"正在用"的，不是给"看过"的。
+
+---
+
+## 综合起来 —— 开局序列
+
+进入 skill_authoring、TaskBoard 为空时：
+
+1. **读 `describeState`**。看规则列表、里程碑（哪些规则有 chunk refs / 是否做了覆盖审计），以及现存的 PATTERNS.md。
+2. **如果 PATTERNS.md 为空**：花约 2 个回合定排序方法 + 头 3-5 条 pattern。在写任何 skill 代码之前，PATTERNS.md 是第一份产出。
+3. **如果 `rules/difficulty.json` 已存在**：按难度降序排规则。按本 skill 的规则适当分组。为每个工作单元调 `TaskCreate`。
+4. **如果 `rules/difficulty.json` 不存在**：决定是否花 worker LLM 调用做分级（>20 条规则的语料几乎总是值得）。跑分级（每条规则一次 tier3 调用，可以按 10 条一组批处理），写 `rules/difficulty.json`，再回到第 3 步。
+5. **挑第一个任务**。做到完整（skill + check + 至少一次本地测试）。把学到的写进 PATTERNS.md。换下一个任务。
+6. **任务做到第 5 个、第 10 个时**：停下来重读 PATTERNS.md。如果新积累的 pattern 暗示要重构早期工作，**现在做**（便宜）而不是更晚（昂贵）。
+
+引擎从文件系统推导里程碑（v0.7.0 Group A）会按磁盘事实核验覆盖率，无论你怎么切分工作。TaskBoard 是你的草稿；磁盘才是契约。

package/template/skills/zh/skill-creator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-creator
-description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
+description: Anthropic 官方 skill 脚手架工具——用于迭代/优化已有 skill 或对其运行 evaluation，不是构建 KC per-rule 核查 skill 的首选参考。要写 KC 规则 skill，先读 `meta-meta/skill-authoring`（规范目录结构 + 粒度规则 + KC 特定的 check.py 入口约定）和 `meta-meta/work-decomposition`（排序与分组决策）。本 skill 适用于：per-rule skill 已经存在、agent 想优化其 description/触发或跑正式 evaluation 时。
 ---
 
 # Skill Creator