kc-beta 0.7.1 → 0.7.3

package/template/skills/zh/meta-meta/rule-extraction/SKILL.md

@@ -132,6 +132,53 @@ existing catalog. Therefore, when composing the brief:
   catalog.json.** rule_catalog uses workspace file locking (B9);
   sandbox_exec bypasses it and races with other writers.
 
+## 如何读取规则文件 (默认整本读取)
+
+法规文件是审核的权威依据。你为每条规则记录的 `source_ref` 都要能在
+原文中复核。对于绝大多数规则文件 (单个文件 < 50 KB / < ~100 页),
+**用 `workspace_file` (operation=read) 一次性整本读取**:
+
+```js
+workspace_file({ operation: "read", scope: "project", path: "Rules/01_某某办法.md" })
+```
+
+`workspace_file.read` 单次上限 50,000 字符, 足以覆盖几乎所有单个法规
+文件。这是默认行为: **在抽取规则之前, 把每一份法规文件都整本读一遍。**
+
+### 工具选择 — `workspace_file` 还是 `sandbox_exec`
+
+| 工具 | 单次上限 | 适用 |
+|---|---:|---|
+| `workspace_file` (read) | 50,000 字符 | **整本读取法规/规则文件** |
+| `sandbox_exec` (cat/head) | 10,000 字符 | 短命令, 不适合整文件读取 |
+
+`sandbox_exec` 是为执行 shell 命令设计的, 10K 上限对绝大多数法规太小。
+`cat rules/01_*.md` 只会返回前 ~10 KB, 后面被截断为 `\n[truncated]`。
+反复用 `head -N` / `tail -M` 滑动窗口会丢失行号位置信息, 也浪费交互
+回合。**遇到截断, 别和上限较劲——换工具。**
+
+### 法规与样本的不对称 — 法规整本读, 样本按需抽样
+
+法规通常只有 1–10 份, 权威性强, 只需读一次。每一份法规都整本读取,
+作为后续所有规则抽取与引用的基础。
+
+样本文档可能 30 份甚至 1000+ 份, 异质性强, 在测试阶段会被多次读取。
+**不要试图把每个样本都整本读一遍**——用规则适用性过滤、抽样子集来
+聚焦注意力。
+
+### 例外 — 单个法规超过 200K 字符时
+
+实践中极少见。test_data_4 中最大的法规 42 KB; 银行业 资管新规 +
+信披办法 等典型法规也都在 50 KB 以内。但如果你确实遇到一份超大法规,
+读取整本会挤压上下文窗口 (启发式: 单文件超过 ~200,000 字符 或超过你
+上下文预算的 ~25%), 此时由你判断:
+
+- 按章 (`第X章`) 分段读, 用 `document_parse` 或分页的 `workspace_file`
+- 或建立工作区内的索引文件, 标注每章的偏移位置, 抽取规则时按需读取
+
+50 KB 的上限已经足够高, 上述例外情形几乎不会触发。**默认就是整本读;
+只有当文件确实太大时才偏离这一默认。**
+
 ## Extraction Strategies
 
 ### Strategy 1: Structured Input (Developer User Provides Rules)
@@ -222,6 +269,24 @@ Regulations are often ambiguous. When you encounter ambiguity:
 
 Do not skip ambiguous rules. They are often the most important ones.
 
+## Sanity-check applicability against the sample corpus
+
+After extracting your rule catalog and before authoring skills, do this 5-minute check: project each rule's applicability filter against the sample corpus.
+
+For every rule:
+1. Walk `samples/`, classify each by product type / report type / document format
+2. For each rule, count how many samples it would apply to (per the rule's `applicability` field, scope filter, or whatever shape your catalog uses)
+3. Flag rules that apply to **0 samples** — they're either genuinely test-corpus-irrelevant (acceptable) or over-constrained (bug)
+
+E2E #7 GLM produced a 97-rule catalog where 36 rules (37%) had `PASS=0 FAIL=0 NOT_APPLICABLE=90` across all 90 documents — they never fired. Some were legit (rules for cash-management products with no cash-management samples in corpus), but 36 inactive of 97 was high enough to suggest scope-too-narrow drift.
+
+If many rules are 0-sample, either:
+- **Reframe their applicability** — broaden product types, look for evidence in headers/footers not just body, relax the scope filter
+- **Document them as "future scope"** and remove from this iteration's catalog (still capture them in a `rules/future_scope.md` so they're not forgotten)
+- **Update the test corpus** to include matching samples (work with the developer user)
+
+Catching this in `rule_extraction` is much cheaper than authoring 36 skills that then test as inactive in `skill_testing`. The cheap projection here is worth the time it saves later.
+
 ## When Rules Change
 
 Regulations evolve. When the developer user adds new or updated regulation documents:

package/template/skills/zh/meta-meta/skill-to-workflow/SKILL.md

@@ -45,6 +45,32 @@ If yes, design a worker LLM prompt. Use the smallest model tier that maintains a
 ### The hybrid approach (most common)
 Most rules are a mix: regex extracts the number, Python compares it to the threshold, LLM handles the exceptional cases. Design the workflow as a pipeline where cheap steps run first and expensive steps run only when needed.
 
+### When regex alone isn't enough — decision rubric
+
+Before declaring distillation complete, audit each rule's `verification_type` / `metric` / `evidence_type` (or equivalent fields in your catalog). For rules where the required verification is one of:
+
+- **Semantic** ("is this a positive guarantee or a disclaimer?")
+- **Contextual** ("interpret this in light of the document's product type")
+- **Counterfactual** ("what should this value be, given the other fields?")
+- **Cross-field arithmetic** ("does 期初 + 收益 - 分配 = 期末?")
+
+regex alone rarely suffices. Three acceptable forms:
+
+1. **Pure regex with documented limits** — write the regex check, include a comment explaining the fragility (e.g., "matches syntactic pattern only; cannot detect semantic guarantees")
+2. **Hybrid regex + LLM** — regex baseline catches obvious cases, `worker_llm_call` (tier1-2) handles ambiguous ones. The hybrid workflow declares which rule_ids escalate.
+3. **Pure LLM via `worker_llm_call`** — for fully semantic rules where no regex baseline is meaningful.
+
+Don't ship pure regex for a rule whose `verification_type` is `judgment` / `semantic` without the documented-limits note. Future-you or a colleague will assume the regex is sufficient and that bug will hide for months.
+
+### Worker LLM cost-aware tier choice
+
+If you do escalate to LLM:
+- **tier1** (most capable, ~¥0.001-0.002/doc): cross-field reasoning, ambiguity resolution, rules that benefit from chain-of-thought
+- **tier2-3**: bulk extraction with simple semantic checks
+- **tier4** (cheapest): high-volume keyword-spotting that regex can't handle. Note: tier4 models on SiliconFlow are Qwen3.5 thinking-mode — `content` can return empty if `reasoning_content` consumes max_tokens. Test with realistic prompts before relying. If you see empty responses, either bump max_tokens to ≥8192, shorten your prompt, or fall back to tier1-2.
+
+Both v0.7.1 audit conductors (DS and GLM) defaulted to all-regex distillation and only added LLM escalation when the human user explicitly asked for "V2 with worker LLM". If your rule catalog has any rules where the verification is genuinely semantic, you should reach for `worker_llm_call` yourself — don't wait to be asked.
+
 ## Workflow Structure
 
 A workflow is a Python file (or small set of files) in `workflows/`:

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

@@ -85,7 +85,7 @@ KC 的 main agent 是指挥者。指挥者决定下一步做什么——而这
 - 一条规则的判断逻辑是另一条的子串或近似变体
 - 一次失败通常意味着多条规则同时失败（R013 不可能在 R015 失败的情况下通过）
 
-例：R013 / R015 / R017 都在检查报告第 3 页那张表是否包含某些必填字段。同一个 chunk、同一次 parse、同一种 verdict 形状。合并为 `check_r013_r015_r017.py`，并创建一个 TaskCreate 任务 `R013/R015/R017 — 必填字段表`。引擎从文件系统推导里程碑时会识别这个合并 check.py，给三个 rule_id 都计入覆盖。
+例：R013 / R015 / R017 都在检查报告第 3 页那张表是否包含某些必填字段。同一个 chunk、同一次 parse、同一种 verdict 形状。合并为 `check_r013_r015_r017.py`，并创建一个任务：`TaskCreate({id: "R013-R015-R017-skill_authoring", title: "R013/R015/R017 — 必填字段表", phase: "skill_authoring"})`。引擎从文件系统推导里程碑时会识别这个合并 check.py，给三个 rule_id 都计入覆盖。
 
 ### 何时保持独立
 
@@ -144,6 +144,39 @@ E2E #6 v070 暴露了这个反模式（DS 把所有 bundled skill 的 check.py
 都写成 `{"pass": null, "method": "stub"}` 推给 workflows/）。
 v0.7.1 把这个反模式显式写进 skill。
 
+E2E #7 v071 显示这个反 stub 的引导在两个 conductor 上都生效（两条 run
+里都没有 `{"pass": null}` 这种 stub 模式），但是 **DS 仍然把"正典 vs
+蒸馏"的关系搞反了**：DS 写了 6 个主题分组的 skill 文件夹，每个只有
+SKILL.md（没有 check.py），真正的验证代码却在
+`workflows/<skill>/check.py` 里。没有 stub 是好事；关系搞反不是 ——
+要修改一条规则的逻辑就得同时改 SKILL.md（文档）和 workflow check.py
+（代码），单一信息源就丢了。
+
+GLM v071 反而把正典模式落地了：97/97 个 skill 都同时有 SKILL.md 和
+真正的 `check.py`（regex + 适用性判断的代码，中位 143 行），而
+`workflows/<id>/workflow_v1.py` 是一个 50 行的薄壳，只是 import 并
+调用 skill 的 check.py：
+
+```python
+# workflows/D01-01/workflow_v1.py — 薄壳，52 行
+import importlib.util, json
+from pathlib import Path
+
+def run(doc_text: str, meta: dict = None) -> dict:
+    check_path = Path(__file__).parent.parent.parent / "rule_skills" / "D01-01" / "check.py"
+    spec = importlib.util.spec_from_file_location("check", check_path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    result = mod.check(doc_text, meta)
+    result["_workflow"] = "D01-01_v1"
+    return result
+```
+
+这是 v0.7.2+ 的正典模式：workflow 是个壳，指向 skill 的 check.py。
+迭代规则验证逻辑时，编辑 `rule_skills/<id>/check.py`，workflow 不用动。
+v0.7.2 把引导说得更清楚：既不要 stub，也要保留正典关系（skill 是
+正典，workflow 是蒸馏过的薄壳）。
+
 ### 合并 check 的命名约定
 
 确实需要合并时，文件名要把范围写明：
@@ -304,18 +337,50 @@ PATTERNS.md 全文控制在约 5 KB 之内。超过时，剪掉最不可执行
 5. **挑第一个任务**。做到完整（skill + check + 至少一次本地测试）。把学到的写进 PATTERNS.md。换下一个任务。
 6. **任务做到第 5 个、第 10 个时**：停下来重读 PATTERNS.md。如果新积累的 pattern 暗示要重构早期工作，**现在做**（便宜）而不是更晚（昂贵）。
 
-### 为什么 PATTERNS.md 要先写、写在 skill 代码之前
+### 调用 TaskCreate / TaskUpdate / TaskComplete
+
+引擎注册了三个任务面板工具（v0.7.3+）：
+
+- `TaskCreate({id, title, phase, ruleId?})` —— 在 `tasks.json` 中新增一条任务。`id` 在本会话内必须唯一；per-rule 任务建议用 `<rule_id>-<phase>` 这种稳定形状，分组 / 非规则任务用 `<group-name>-<phase>`。`phase` 是该任务所属的阶段（当前阶段或你预先排好的未来阶段）。`ruleId` 可选 —— 设上之后，引擎在里程碑推导时能把这个 rule_id 计入覆盖。
+- `TaskUpdate({id, status?, summary?})` —— 把任务状态改为 `pending` / `in_progress` / `completed` / `failed`，可选附一行简要 summary。
+- `TaskComplete({id, summary?})` —— `TaskUpdate({id, status:"completed", summary})` 的语法糖。完成一个工作单元后走这条最常用的路径。
+
+调用 `TaskCreate` 把你的拆分写进面板、本回合结束之后，Ralph 循环会取下一条 pending 任务执行。完成工作、调 `TaskComplete`，循环再前进。如果一条任务无法完成（不可恢复的错误），调 `TaskUpdate({id, status:"failed", summary:"原因"})`，让队列继续推进而不是被堵在那里。
+
+示例：
+
+```
+TaskCreate({ id: "R001-skill_authoring", title: "为 R001 撰写 skill",
+             phase: "skill_authoring", ruleId: "R001" })
+
+TaskCreate({ id: "trust-bundle-skill_authoring",
+             title: "R013/R015/R017 — 必填字段表",
+             phase: "skill_authoring" })
+
+TaskComplete({ id: "R001-skill_authoring",
+               summary: "正则核查在 89/90 通过；R001 完成" })
+```
+
+### 持久化方法论 —— PATTERNS.md 或 phase 日志 或 AGENT.md decisions
+
+原则：在每次 phase 推进之前，把框架级的决定写到磁盘。对话会被 compact、agent 会重启、下一个 phase 会失去上下文。不管你选哪种格式，**写到磁盘** —— 不要依赖会消失的对话上下文。
+
+三种格式都站得住，挑一种坚持下去：
+
+- **`rules/PATTERNS.md`** —— 简洁，只装框架级内容，随项目推进而更新。适合假设可以前置、结构清晰的全新项目。上限 ~5 KB；条目是可迁移的形状 / 项目级约束 / 反模式加原因（参考上面"该写什么"一节）。
 
-如果你在 PATTERNS.md 还不存在的时候就开始写 skill 代码（rule_skills/<id>/check.py），**停**。哪怕只是 200 字节的初始 PATTERNS.md（"决定走 Shannon-Huffman；第一条难规则 R028 决定 verdict 形状；样本语料表头中英双语"）也能搭起框架。后续每条规则少重新推导一次同样的形状，整体能省 4 倍时间。
+- **每阶段写 `logs/phase_<name>_complete.md`** —— 增量式，记录每个 phase 产出了什么、做了哪些决定、下个 phase 继承什么。适合"边发现边定型"的迭代式工作。E2E #7 GLM 用了这个模式：6 篇 phase 文档 + `evolution_summary_v1.2.md`，方法论照样捕获了，只是没写 PATTERNS.md。
 
-❌ "我先把 skill 写完，等有洞察再写 PATTERNS.md。"
+- **`AGENT.md` decisions 段 + 领域笔记** —— 叙事风格，是关于"我们知道什么"和"为什么"的活文档。适合需要捕获丰富领域上下文的项目（法规、边缘案例、阈值、样本格式分布）。E2E #7 GLM 的 AGENT.md 里有法规生效日期、产品类型分类、阈值数值、样本格式数量 —— 完全 OK，是相同目标的不同惯用法。
 
-到你写完 N 个 skill 时，你已经做了 N 个隐式决定（verdict 形状、chunker 边界、worker tier）——每条规则都是从零推导。重构需要碰 N 个文件，而不是一个。
+不该做的事：跳过持久化、只靠对话上下文活着。等你写到第 N 条 skill 还没把方法论写到磁盘时，你已经做了 N 个关于 verdict 形状、chunker 边界、worker tier 的隐式决定 —— 每条规则都从零推导，重构要碰 N 个文件而不是一个。
 
-✅ "先写 PATTERNS.md（哪怕是初步的），写每条新规则之前先重读，发现新东西就回头更新。"
+❌ "等我有空再来记录这些洞察。"
 
-PATTERNS.md 是项目的索引卡片。工作之前搭好它、工作中更新它、工作之后从中收割。
+✅ "每次 phase 推进之前，把这一阶段学到的东西写到适合本项目惯用法的那个持久化文件里 —— 哪怕只是初稿。"
 
-E2E #6 v070 暴露了这个：DS 在用户介入回退之后才写 PATTERNS.md，而那之前每条 skill 的设计决定都已经各自固化、之后还要再碰一遍。v0.7.1 把这个引导写得更明确。
+E2E 历史：
+- E2E #6 v070 DS 在用户介入回退之后才写 PATTERNS.md。那之前每条 skill 的设计决定都各自固化，之后还要再碰一遍。v0.7.1 加了"PATTERNS.md FIRST"的引导。
+- E2E #7 v071 DS 和 GLM 都没写 PATTERNS.md，但 GLM 写了 6 篇 phase 完成日志和一份内容详尽的 AGENT.md —— 方法论 *捕获了*，只是放在了不同文件里。v0.7.2 把更宽的原则写进 skill：推进之前先持久化，格式灵活。
 
-引擎从文件系统推导里程碑（v0.7.0 Group A）会按磁盘事实核验覆盖率，无论你怎么切分工作。TaskBoard 是你的草稿；磁盘才是契约。
+引擎从文件系统推导里程碑（v0.7.0 Group A）会按磁盘事实核验覆盖率，无论你怎么切分工作。TaskBoard 是你的草稿；磁盘才是契约；持久化文件是项目的记忆。