kc-beta 0.8.1 → 0.8.3

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

@@ -71,7 +71,7 @@ skill 是 ground truth。workflow 是更便宜、更快的近似。你的工作
 - **tier2-3**：批量抽取 + 简单语义检查
 - **tier4**（最便宜）：正则无法覆盖、量又很大的关键词识别。注意：SiliconFlow 上的 tier4 模型是 Qwen3.5 thinking 模式——如果 `reasoning_content` 把 max_tokens 用光，`content` 可能返回空字符串。在依赖之前先用真实提示词测试。如果出现空响应，要么把 max_tokens 提到 ≥8192，要么缩短提示词，要么回退到 tier1-2。
 
-v0.7.1 两位审计 conductor（DS 和 GLM）默认都走全正则蒸馏，只有当用户显式要求"V2，带 worker LLM"时才加上 LLM 上升路径。如果你的规则目录里有任何一条规则的验证本质上就是语义性的，你应当主动伸手去用 `worker_llm_call`——不要等别人要你才用。
+一种值得警惕的失败模式：agent 默认全正则蒸馏，只有当用户显式要求"V2，带 worker LLM"时才加上 LLM 上升路径。如果你的规则目录里有任何一条规则的验证本质上就是语义性的，你应当主动伸手去用 `worker_llm_call`——不要等别人要你才用。
 
 ## Workflow 结构
 
@@ -149,6 +149,17 @@ worker LLM 的上下文窗口较小（典型 16K-32K token）。设计提示词
 
 这与 `document-parsing` 里 parser 上升的层级转移框架是同一套：由一个质量/精度评分驱动"保留 / 上升 / 跳过"的决定。
 
+### 在 tier 槽位内挑具体模型 —— 速查
+
+上面的 tier 框架回答"这一步该用哪个 tier？"。在某个 tier 槽位内仍然要回答"具体用哪个模型？"。下面几条启发式短期内有效（具体型号请从 `auto-model-selection` 刷新，模型代次的更替以月为单位、不是以年为单位）：
+
+- **Tier 1 / Tier 2 主力 worker**：当代的旗舰 MoE LLM（总量 200-400B、激活 ~20B 专家）是合理的起点基准。Qwen 家族当前的旗舰、DeepSeek 当代的高级模型都是这个形状；任一都行。
+- **Tier 3 / Tier 4 小模型**：30B 以下优先选 Qwen 家族 —— 便宜可靠的选择最多。小尺寸下避开名字里带 `coder` / `code` 的变体（在通用 worker 任务上不可靠）。能选无 thinking 模式的就选无 thinking —— 这些任务不需要反思。
+- **provider 分流**：把 conductor 和 worker 走不同的服务商，可以隔离单一服务商对同一模型的限流暴露（例如 worker 走 DeepSeek、conductor 留在 SiliconFlow）。
+- **VLM / OCR**：字符 / 手写 / 印章 → 专用 OCR 模型（Paddle-OCR、 GLM-OCR、DeepSeek-OCR 或其后继）。复杂图表 / 表格 → 更大的通用 VLM。
+
+具体事实（确切模型名、上下文窗口、定价）用 `auto-model-selection` + Context7 查。上面的启发式过得快，但**形状**（旗舰 MoE 当主力、 30B 以下无 thinking 当便宜底、OCR 专用做字符）稳定得多。
+
 ## 用 Ground Truth 做测试
 
 编码 agent 基于 skill 的结果就是 ground truth。对 Samples/ 下每篇文档：
@@ -191,7 +202,7 @@ Worker LLM 通过 SiliconFlow API 访问。连接信息在 `.env` 里：
 
 ## 两条访问路径：`worker_llm_call` 工具（优先）vs 直接 HTTP
 
-KC 自带一个 `worker_llm_call` 工具。能用就用 —— 引擎能看到每次调用，能统计成本和 token、做限流、并把数据进入审计。v0.8 P2-B 增加了批量模式：
+KC 自带一个 `worker_llm_call` 工具。能用就用 —— 引擎能看到每次调用，能统计成本和 token、做限流、并把数据进入审计。它支持批量模式：
 
 ```
 worker_llm_call({
@@ -204,9 +215,9 @@ worker_llm_call({
 
 返回 `{n_total, n_succeeded, n_failed, total_tokens_in, total_tokens_out, results: [...]}` 摘要。部分失败不会让整批失败。
 
-### 规范的 `workflows/common/llm_client.py`（v0.8.1 起作为模板文件随包发布）
+### 规范的 `workflows/common/llm_client.py`（作为模板文件随包发布）
 
-对于一个 **独立运行** 的 workflow（没有 KC 会话 —— 比如客户把 release 包部署后跑 `python run.py doc.pdf`），workflow 拿不到 `worker_llm_call`。规范的 HTTP 客户端 shim 现在作为模板文件随 kc-beta 一起发布；引擎初始化时会自动把它写入工作区的 `workflows/common/llm_client.py`。**不要自己重写**。直接用这个已经放好的文件：
+对于一个 **独立运行** 的 workflow（没有 KC 会话 —— 比如客户把 release 包部署后跑 `python run.py doc.pdf`），workflow 拿不到 `worker_llm_call`。规范的 HTTP 客户端 shim 作为模板文件随 kc-beta 一起发布；引擎初始化时会自动把它写入工作区的 `workflows/common/llm_client.py`。**不要自己重写**。直接用这个已经放好的文件：
 
 ```python
 from workflows.common.llm_client import call
@@ -227,7 +238,15 @@ shim 做的事：
 - 每次调用往 `output/llm_ledger.jsonl` 写一行，KC 审计即使在你没走 worker_llm_call 时也能还原成本
 - 如果 `LLM_BASE_URL` 缺失，会显式抛错（不会偷偷回退到某个写死的 vendor URL）
 
-**不要自己从零写 llm_client.py**。v0.7.x → v0.8 的三个连续会话里都出现过 agent 自己造轮子 —— 拼出来的版本要么模型 ID 过期、要么写死 SiliconFlow、要么不写 ledger，且对引擎不可见。优先用规范化版本；如果因为某种原因没有，从 kc-beta 安装目录的 `template/workflows/common/llm_client.py` 复制过来（引擎也会在 init 时自动写入 —— 检查 events.jsonl 里的 `workflows_common_populated` 事件）。
+**不要自己从零写 llm_client.py**。一种值得警惕的失败模式：agent 反复自己造轮子 —— 拼出来的版本要么模型 ID 过期、要么写死某个 vendor URL、要么不写 ledger，且对引擎不可见。优先用规范化版本；如果因为某种原因没有，从 kc-beta 安装目录的 `template/workflows/common/llm_client.py` 复制过来（引擎也会在 init 时自动写入 —— 检查 events.jsonl 里的 `workflows_common_populated` 事件）。
+
+### 更糟的反模式：规范化客户端已经存在，agent 同时另写一个并行的
+
+跨多次运行反复出现的一种失败模式：规范化的 `workflows/common/llm_client.py` 已经在工作区里（引擎 init 时已经写入了），**与此同时** agent 又自己写了 `workflows/llm_client.py` 或 `verify_engine_v2.py`，里面用 `requests.post(...)` 发 HTTP。之后所有真正的 LLM 工作都走自己写的那份。两个文件并排躺在工作区里。引擎的成本追踪什么都看不到。
+
+这样会出三件事：(1) provider 路由跑偏。手写的客户端通常读工作区 `.env` 的 `LLM_BASE_URL` —— 那是**conductor**的端点。KC 的 worker 路由（通过 `worker_llm_call` 和引擎的 worker_* 配置）被完全绕开。如果运营方把 worker 配到了另外一个服务商（比如 DeepSeek 当 worker、SiliconFlow 当 conductor），手写客户端就会拿着 worker 的模型名打到 conductor 的服务商上 —— 出 400，或者更糟地，悄悄拿到错模型的结果。(2) 成本 / 审计可见性丢失。引擎看不到这些调用；`output/llm_ledger.jsonl`（规范化客户端写的那份 ledger）也没有记录（手写客户端不写这个）。一场跑下来看起来什么 LLM 工作都没做，但实际账单已经产生。(3) 限流 / 重试 / 超时行为发散。规范化客户端 + `worker_llm_call` 继承引擎层面的健壮性（AbortSignal.timeout、429/5xx 上的 withRetry 等）。手写的 `requests.post` 一概没有 —— 会卡住、会抛各种自定义错误、或者悄悄毁掉这一轮。
+
+**经验法则**：核查规则需要 LLM 判定时，正确选择只有两个 —— `worker_llm_call`（在 KC session 里运行）或 `from workflows.common.llm_client import call`（从 release bundle 脱离 KC 独立运行时）。如果你发现自己在为一个 LLM 调用敲 `import requests` 或者 `urllib.request.urlopen`，停下。这条代码路径会在审计里被点名是反复出现的"该用没用"，然后被重写 —— 省一趟来回，第一次就用对工具。
 
 ## sandbox_exec 超时设置（已知耗时长的命令）
 

package/template/skills/zh/skill-to-workflow/references/worker-llm-catalog.md

@@ -1,36 +1,36 @@
-# Worker LLM Catalog
+# Worker LLM 目录
 
-Models available via SiliconFlow API for worker LLM tasks. Update this catalog as models change.
+通过 SiliconFlow API 可调用的 worker LLM 模型。模型有更新时同步维护此目录。
 
-## Text Models
+## 文本模型
 
-| Tier | Model | Context Window | Strengths | Notes |
+| 等级 | 模型 | 上下文窗口 | 优势 | 备注 |
 |------|-------|---------------|-----------|-------|
-| TIER1 | Pro/zai-org/GLM-5 | 128K | Strong reasoning, Chinese language | Top tier for complex judgment |
-| TIER1 | Pro/moonshotai/Kimi-K2.5 | 128K | Long context, strong extraction | Good for full-document processing |
-| TIER2 | Pro/deepseek-ai/DeepSeek-V3.2 | 64K | Balanced capability/cost | Good general purpose |
-| TIER2 | Pro/MiniMaxAI/MiniMax-M2.5 | 64K | Strong Chinese, fast | Good for Chinese documents |
-| TIER2 | Qwen/Qwen3.5-397B-A17B | 32K | Large MoE, strong reasoning | Cost-effective for complex tasks |
-| TIER3 | Qwen/Qwen3.5-122B-A10B | 32K | Good accuracy, lower cost | Sweet spot for many tasks |
-| TIER4 | Qwen/Qwen3.5-35B-A3B | 16K | Fast, cheap | Best for simple extraction |
+| TIER1 | Pro/zai-org/GLM-5 | 128K | 推理能力强、中文好 | 用于复杂判定的顶级选项 |
+| TIER1 | Pro/moonshotai/Kimi-K2.5 | 128K | 长上下文、抽取能力强 | 适合整篇文档处理 |
+| TIER2 | Pro/deepseek-ai/DeepSeek-V3.2 | 64K | 性价比均衡 | 通用场景表现良好 |
+| TIER2 | Pro/MiniMaxAI/MiniMax-M2.5 | 64K | 中文强、速度快 | 适合中文文档 |
+| TIER2 | Qwen/Qwen3.5-397B-A17B | 32K | 大型 MoE，推理力强 | 复杂任务的高性价比选项 |
+| TIER3 | Qwen/Qwen3.5-122B-A10B | 32K | 准确率良好、成本较低 | 多数任务的甜点位 |
+| TIER4 | Qwen/Qwen3.5-35B-A3B | 16K | 快、便宜 | 简单抽取首选 |
 
-## Vision/OCR Models
+## 视觉 / OCR 模型
 
-| Tier | Model | Strengths | Notes |
+| 等级 | 模型 | 优势 | 备注 |
 |------|-------|-----------|-------|
-| OCR_TIER1 | zai-org/GLM-4.6V | Best OCR accuracy | Use for complex tables/charts |
-| OCR_TIER2 | Qwen/Qwen3.5-397B-A17B | Good general vision | Multimodal version |
-| OCR_TIER3 | PaddlePaddle/PaddleOCR-VL-1.5 | Fast, lightweight OCR | Best for standard text |
+| OCR_TIER1 | zai-org/GLM-4.6V | OCR 准确率最高 | 用于复杂表格/图表 |
+| OCR_TIER2 | Qwen/Qwen3.5-397B-A17B | 通用视觉好 | 多模态版本 |
+| OCR_TIER3 | PaddlePaddle/PaddleOCR-VL-1.5 | 快、轻量 OCR | 标准文本首选 |
 
-## Selection Guidelines
+## 选型要点
 
-- Start with the highest tier that fits your context window needs.
-- For extraction of simple entities (dates, amounts, names): TIER3-4 often sufficient.
-- For semantic judgment (adequacy, compliance): TIER1-2 usually needed.
-- For Chinese financial documents: prefer GLM and Qwen models over DeepSeek for domain terminology.
-- Context window constraint: if the section to process exceeds the model's window, either narrow the context further (tree processing) or use a model with a larger window.
+- 在能满足上下文窗口需求的前提下，优先选择最高等级的模型。
+- 抽取简单实体（日期、金额、姓名）：TIER3-4 通常够用。
+- 语义判定（充分性、合规性）：通常需要 TIER1-2。
+- 中文金融文档：优先选择 GLM 与 Qwen 系列，而非 DeepSeek，以更好处理行业术语。
+- 上下文窗口约束：若待处理段落超出模型窗口，要么进一步收窄上下文（采用树状处理），要么换上下文更大的模型。
 
-## API Configuration
+## API 配置
 
 ```python
 import openai
@@ -47,4 +47,4 @@ response = client.chat.completions.create(
 )
 ```
 
-This catalog should be maintained by the coding agent. Add new models as they become available, remove deprecated models, and update capability assessments based on testing experience.
+本目录由编程智能体负责维护。有新模型时及时加入，模型停服时移除，并基于测试经验更新能力评估。

package/template/skills/zh/task-decomposition/SKILL.md

@@ -225,7 +225,7 @@ KC 偏好的两种模式：
 
 ## 与其他技能的衔接
 
-任务分解在 KC Reborn 生命周期中处于规则提取和技能编写之间。
+任务分解在 KC 生命周期中处于规则提取和技能编写之间。
 
 **输入**：来自 `rule-extraction` 的规则目录。每条规则是一个原子级、可测试的核查要求。如果规则尚未达到原子级别，先退回给规则提取环节做进一步分解，再进入任务分解。
 

package/template/skills/zh/task-decomposition/references/decision-matrix.md

@@ -1,81 +1,81 @@
-# Decision Matrix for Method Selection
+# 方法选择决策矩阵
 
-This reference provides the detailed decision matrix for assigning methods to sub-tasks during task decomposition. Read `task-decomposition` SKILL.md first for the philosophy; this document is the operational reference.
+本文档是任务分解阶段为各子任务分配方法时使用的详细决策矩阵。先阅读 `task-decomposition` SKILL.md 了解方法论；本文档是操作层面的参考。
 
-## The Four Dimensions
+## 四个维度
 
-| Dimension | Definition | 1 (Low) | 3 (Medium) | 5 (High) |
+| 维度 | 定义 | 1（低） | 3（中） | 5（高） |
 |---|---|---|---|---|
-| **Certainty** | Predictability of input format and location | Free-form prose, no fixed structure | Semi-structured with known sections but variable formatting | Fixed template, exact field positions |
-| **Scale** | Number of items to process per document | 1-5 items | 10-100 items | 1,000+ items |
-| **Semantic Depth** | Language understanding required | None — pure pattern or numeric | Moderate — entity recognition, simple context | Deep — judgment, adequacy assessment, intent interpretation |
-| **Cost Sensitivity** | Budget constraint per document | Unlimited (one-off audit) | Moderate (monthly batch of hundreds) | Tight (daily batch of thousands) |
+| **确定性** | 输入格式与位置的可预测程度 | 自由散文，无固定结构 | 半结构化，章节已知但格式多变 | 固定模板，字段位置精确 |
+| **规模** | 每份文档需处理的条目数 | 1-5 项 | 10-100 项 | 1,000+ 项 |
+| **语义深度** | 所需的语言理解程度 | 无——纯模式或数值 | 中等——实体识别、简单上下文 | 深——判断、充分性评估、意图解释 |
+| **成本敏感度** | 每份文档的预算约束 | 无限（一次性审计） | 中等（每月数百件批处理） | 紧（每日数千件批处理） |
 
-## Method Assignment Rules
+## 方法分配规则
 
-Use the highest-priority method whose requirements are met. Priority order: Rule/Regex > Code > LLM > Manual.
+挑选满足条件中优先级最高的方法。优先级顺序：规则/正则 > 代码 > LLM > 人工。
 
-| Certainty | Scale | Semantic Depth | Cost Sensitivity | Assigned Method | Rationale |
+| 确定性 | 规模 | 语义深度 | 成本敏感度 | 分配方法 | 原因 |
 |---|---|---|---|---|---|
-| High (4-5) | Any | Low (1-2) | Any | **Rule / Regex** | Predictable input + no language understanding = deterministic pattern matching |
-| High (4-5) | Any | Low (1-2) | Any | **Code / Python** | Calculations, comparisons, transformations on structured data |
-| Medium (3) | High (4-5) | Low (1-2) | High (4-5) | **Code + Regex** | Volume demands speed; invest in parsing code to avoid per-item LLM cost |
-| Medium (3) | Low (1-2) | Medium (3) | Low (1-2) | **LLM** | Moderate understanding needed, low volume makes LLM cost acceptable |
-| Low (1-2) | Any | High (4-5) | Any | **LLM** | Deep semantic understanding has no cheaper alternative |
-| Low (1-2) | High (4-5) | High (4-5) | High (4-5) | **LLM (low tier) + sampling** | Volume + semantics + budget = use cheapest LLM, sample-verify with higher tier |
-| Any | Any | Any | — | **Manual** | Last resort when automated methods fail accuracy threshold |
+| 高 (4-5) | 任意 | 低 (1-2) | 任意 | **规则 / 正则** | 输入可预测 + 不需语言理解 = 确定性模式匹配 |
+| 高 (4-5) | 任意 | 低 (1-2) | 任意 | **代码 / Python** | 在结构化数据上做计算、比较、转换 |
+| 中 (3) | 高 (4-5) | 低 (1-2) | 高 (4-5) | **代码 + 正则** | 高吞吐要求速度；投入解析代码以避免逐条调 LLM 的成本 |
+| 中 (3) | 低 (1-2) | 中 (3) | 低 (1-2) | **LLM** | 需要中等程度的理解，低吞吐使 LLM 成本可接受 |
+| 低 (1-2) | 任意 | 高 (4-5) | 任意 | **LLM** | 深层语义理解没有更便宜的替代方案 |
+| 低 (1-2) | 高 (4-5) | 高 (4-5) | 高 (4-5) | **低层 LLM + 抽样** | 吞吐 + 语义 + 预算 = 用最便宜的 LLM 跑、用更高层模型抽样校验 |
+| 任意 | 任意 | 任意 | — | **人工** | 自动方法均无法达标时的兜底 |
 
-The table covers common patterns, not every combination. When a sub-task falls between categories, test both candidate methods on a sample and measure accuracy and cost. Let data decide.
+该表覆盖常见情况，并非穷举。当子任务介于两类之间，请在样本上同时测试候选方法，量化准确率与成本，让数据来定。
 
-## Worked Example: Cross-Field Validation
+## 实例：跨字段校验
 
-**Rule**: "The loan amount must not exceed 70% of the appraised collateral value."
+**规则**："贷款金额不得超过资产评估值的 70%。"
 
-Decomposition into sub-tasks with method assignments:
+分解为子任务并分配方法：
 
-| # | Sub-task | Input | Output | Method | Rationale |
+| # | 子任务 | 输入 | 输出 | 方法 | 原因 |
 |---|---|---|---|---|---|
-| 1 | Locate loan amount field | Full document text | Page/section reference | LLM (Tier 3) | Field position varies across document types |
-| 2 | Extract loan amount | Located section text | Numeric value (float) | Regex | Amount follows pattern: ¥/$/digits with commas |
-| 3 | Locate collateral section | Full document text | Page/section reference | LLM (Tier 3) | Section name varies: "Collateral", "Security", "Pledged Assets" |
-| 4 | Extract appraised value | Located section text | Numeric value (float) | Regex + Code | Regex extracts; code handles unit conversion (万/亿) |
-| 5 | Calculate threshold | Loan amount, collateral value | 70% threshold value | Code | Pure arithmetic: `collateral * 0.70` |
-| 6 | Compare | Loan amount, threshold | Pass/Fail | Code | Simple comparison: `loan_amount <= threshold` |
-| 7 | Generate comment | All extracted values | Comment string | Code (template) | Template: "Loan amount {X} is {above/within} 70% of collateral value {Y} (threshold: {Z})" |
+| 1 | 定位贷款金额字段 | 全文 | 页/节定位 | LLM (Tier 3) | 字段位置因文档类型而异 |
+| 2 | 抽取贷款金额 | 已定位段落文本 | 数值 (float) | 正则 | 金额遵循模式：¥/$/带逗号数字 |
+| 3 | 定位抵押物章节 | 全文 | 页/节定位 | LLM (Tier 3) | 章节名称多变："Collateral"、"Security"、"Pledged Assets" |
+| 4 | 抽取评估价值 | 已定位段落文本 | 数值 (float) | 正则 + 代码 | 正则负责抽取；代码处理单位换算（万/亿） |
+| 5 | 计算阈值 | 贷款金额、抵押价值 | 70% 阈值 | 代码 | 纯算术：`collateral * 0.70` |
+| 6 | 比较 | 贷款金额、阈值 | 通过/不通过 | 代码 | 简单比较：`loan_amount <= threshold` |
+| 7 | 生成批注 | 所有抽取值 | 批注字符串 | 代码（模板） | 模板："Loan amount {X} is {above/within} 70% of collateral value {Y} (threshold: {Z})" |
 
-LLM calls: 2 (locate steps only). Everything else is regex or code. Total LLM cost per document: ~0.002 USD at Tier 3 pricing.
+LLM 调用次数：2 次（仅定位环节）。其余全部用正则或代码。每份文档的 LLM 总成本：约 0.002 USD（Tier 3 价格）。
 
-## Worked Example: Large-Scale Filtering
+## 实例：大规模筛选
 
-**Task**: Match 31,800 invoices against 15,940 contracts to find which invoices belong to which contracts.
+**任务**：把 31,800 张发票与 15,940 份合同进行匹配，找出每张发票归属哪份合同。
 
-Naive approach: 507M pairwise LLM comparisons. Estimated cost: $50,000+. Time: weeks.
+朴素做法：5.07 亿次成对 LLM 比较。预估成本：5 万美元以上。耗时：以周计。
 
-Layered decomposition:
+分层分解：
 
-| Layer | Method | Input Size | Output Size | Reduction | Cost |
+| 层 | 方法 | 输入规模 | 输出规模 | 削减比例 | 成本 |
 |---|---|---|---|---|---|
-| 1. Exact match on supplier name + contract number | Rule/Regex | 507M pairs | 25,200 matches | 99.5% eliminated | ~$0 |
-| 2. Fuzzy match on amount range (±5%) + date overlap | Code | Remaining unmatched pairs | 12,400 candidates | 97.6% of remainder eliminated | ~$0 |
-| 3. Semantic comparison of line-item descriptions | LLM (Tier 3) | 12,400 candidates | 7,652 confirmed | Final precision filter | ~$25 |
-| 4. Manual review of low-confidence matches | Manual | ~200 uncertain | ~200 resolved | Edge cases | ~$100 (labor) |
+| 1. 按供应商名 + 合同号精确匹配 | 规则/正则 | 5.07 亿组 | 25,200 组匹配 | 削减 99.5% | 约 $0 |
+| 2. 按金额范围（±5%）+ 日期重叠做模糊匹配 | 代码 | 剩余未匹配组 | 12,400 组候选 | 在剩余中再削减 97.6% | 约 $0 |
+| 3. 对明细项描述做语义对比 | LLM (Tier 3) | 12,400 组候选 | 7,652 组确认匹配 | 最终精度过滤 | 约 $25 |
+| 4. 低置信度匹配的人工复核 | 人工 | 约 200 条不确定 | 约 200 条裁决 | 边界情况 | 约 $100（人力） |
 
-Total cost: ~$125. Time: hours. Same accuracy as the naive approach.
+总成本：约 $125。耗时：以小时计。准确率与朴素做法相当。
 
-The key insight: each layer's method is chosen because it is the cheapest method that can reliably make the distinctions required at that stage.
+关键洞察：每一层使用的方法，都是该阶段能可靠完成区分任务的最便宜方法。
 
-## Cost Estimation Template
+## 成本估算模板
 
-Use this template during decomposition planning to estimate per-document cost.
+在分解规划阶段用此模板估算每份文档的成本。
 
-| Sub-task | Method | Est. Cost/Call | Calls/Document | Subtotal |
+| 子任务 | 方法 | 单次成本估算 | 每文档调用次数 | 小计 |
 |---|---|---|---|---|
-| Locate section | LLM Tier 3 | $0.001 | 2 | $0.002 |
-| Extract fields | Regex | $0.000 | 5 | $0.000 |
-| Normalize values | Python | $0.000 | 5 | $0.000 |
-| Cross-field comparison | Python | $0.000 | 1 | $0.000 |
-| Semantic judgment | LLM Tier 2 | $0.003 | 1 | $0.003 |
-| Comment generation | Template | $0.000 | 1 | $0.000 |
-| **Total per document** | | | | **$0.005** |
-
-Multiply by expected document volume to get batch cost. Compare against the developer user's budget. If total exceeds budget, optimize the most expensive sub-tasks first — usually the LLM calls with the highest per-call cost or the highest call count.
+| 定位章节 | LLM Tier 3 | $0.001 | 2 | $0.002 |
+| 抽取字段 | 正则 | $0.000 | 5 | $0.000 |
+| 规范化数值 | Python | $0.000 | 5 | $0.000 |
+| 跨字段比较 | Python | $0.000 | 1 | $0.000 |
+| 语义判定 | LLM Tier 2 | $0.003 | 1 | $0.003 |
+| 生成批注 | 模板 | $0.000 | 1 | $0.000 |
+| **每文档合计** | | | | **$0.005** |
+
+乘以预期文档量得到批次成本。与开发者用户的预算对比。若总成本超预算，优先优化最贵的子任务——通常是每次调用单价最高、或调用次数最多的 LLM 环节。

package/template/skills/zh/tree-processing/SKILL.md

@@ -59,7 +59,7 @@ description: >
 - 在调试阶段,记得为正则写一组小型的单元测试:包括典型的命中样例、明确不应命中的反例,以及容易混淆的边界样例(比如标题中混入的全角空格、不可见控制字符)。
 
 **如果模式不一致或根本不存在**:
-- 使用 LLM 引导的"楔入式"切分方法(完整算法见 `rule-extraction/references/chunking-strategies.md`:滚动上下文窗口、K-token 引用比对、Levenshtein 模糊匹配)。
+- 使用 LLM 引导的"楔入式"切分方法（完整算法见 `document-chunking` skill：滚动上下文窗口、K-token 引用比对、Levenshtein 模糊匹配）。
 - 这种方式较慢,且要消耗 LLM 调用,但能处理非结构化的文档。滚动窗口的意义在于:即便是非常巨大的非结构化叶子节点,也可以逐段递进地完成切分。
 - 一个务实的折中是混合策略:能用正则切到的层级先用正则切,正则啃不动的子节点再交给 LLM 引导式切分。这样可以把昂贵的 LLM 调用集中投放在真正需要语义判断的地方。
 

package/template/skills/zh/version-control/SKILL.md

@@ -296,3 +296,18 @@ extract_dates_v2.md   # 优化后的提示词
 ```
 
 这些对比数据也是仪表盘展示的重要素材。
+
+## 每条规则的 check.py —— 改写 v2 之前先保留 v1
+
+当你要把某条规则的验证逻辑从 v1（通常是纯 regex）迭代到 v2 （通常引入 LLM 判断或混合方案）时，**改写之前先把 v1 复制为同目录下的同级文件**：
+
+```bash
+cp rule_skills/Rxx/check.py rule_skills/Rxx/check_v1.py
+# 然后再把新版本写到 check.py
+```
+
+约定：
+- `check.py` 永远指向当前最优版本
+- `check_v1.py`、`check_v2.py`、…… 保留各代历史
+
+这样 v1 就和 v2 并排放在同一个目录里，不必再依赖 workspace 的 git 历史去翻找（`git log -- check.py` 能恢复，但每次都翻阅本身就是摩擦）。引擎级别的 `verify_engine_v1.py` / `verify_engine_v2.py` 分别保留各代编排器；每条规则的 check.py 需要自己的命名约定来配合。

package/template/skills/zh/version-control/references/trace-id-spec.md

@@ -1,63 +1,63 @@
-# Trace ID Specification
+# Trace ID 规范
 
-Trace IDs embed source evidence pointers directly inside verification results. This document defines the format, generation rules, and integration points.
+Trace ID 把源头证据指针直接嵌入核查结果中。本文档定义其格式、生成规则与集成点。
 
-## Format
+## 格式
 
 ```
 {rule_id}-{document_id}-P{page}-S{section}-C{char_start}:{char_end}
 ```
 
-| Segment | Description | Example |
+| 段 | 说明 | 示例 |
 |---------|-------------|---------|
-| `rule_id` | The rule that produced this result. Matches the ID in `rule-catalog.json`. | `R001` |
-| `document_id` | A short identifier for the source document. Derived from filename or batch assignment. | `DOC042` |
-| `P{page}` | The 1-indexed page number where the source evidence appears. | `P3` |
-| `S{section}` | The section number within the page, following the document's own numbering. | `S2` |
-| `C{char_start}:{char_end}` | Character offset range within the extracted text block that constitutes the evidence. | `C120:180` |
+| `rule_id` | 产出此结果的规则。匹配 `rule-catalog.json` 中的 ID。 | `R001` |
+| `document_id` | 源文档的简短标识。来自文件名或批次内的指派。 | `DOC042` |
+| `P{page}` | 源证据所在页码（从 1 开始）。 | `P3` |
+| `S{section}` | 页内的小节编号，沿用文档自身的编号体系。 | `S2` |
+| `C{char_start}:{char_end}` | 抽取文本块中构成证据的字符偏移范围。 | `C120:180` |
 
-Full example: `R001-DOC042-P3-S2-C120:180`
+完整示例：`R001-DOC042-P3-S2-C120:180`
 
-When a rule draws evidence from multiple locations, generate one trace ID per location and store them as an array in the result.
+当一条规则的证据来自多个位置时，每个位置生成一条 trace ID，并以数组形式存放在结果中。
 
-## Generation
+## 生成规则
 
-Trace ID generation is **deterministic**: the same rule applied to the same document at the same location always produces the same trace ID. This is achieved by deriving every segment from stable inputs:
+Trace ID 的生成是**确定性的**：同一规则作用于同一文档的同一位置，永远生成相同的 trace ID。这是通过让每一段都来自稳定输入实现的：
 
-- `rule_id` comes from the rule catalog.
-- `document_id` comes from the document's filename or a developer-user-assigned identifier.
-- Page, section, and character range come from the extraction step.
+- `rule_id` 来自规则目录。
+- `document_id` 来自文档文件名或开发者用户指派的标识。
+- 页码、小节、字符范围来自抽取环节。
 
-Trace IDs are generated at verification time, immediately after entity extraction identifies the source location. They are never modified after creation. Re-verifying the same document produces new result records with new timestamps but identical trace IDs (because the source location has not changed). If the document is modified, the new version gets a new `document_id`, producing different trace IDs.
+Trace ID 在核查时生成，紧接实体抽取定位到来源位置之后。生成后永不修改。再次核查同一文档会产出带新时间戳的新结果记录，但 trace ID 不变（因为源位置没变）。如果文档被修改过，新版本应获得新的 `document_id`，从而产生不同的 trace ID。
 
-## Collision Avoidance
+## 避免冲突
 
-The combination of rule ID + document ID + page + section + character range makes collisions astronomically unlikely in practice. Two different pieces of evidence would need to match on all five segments simultaneously.
+规则 ID + 文档 ID + 页 + 节 + 字符范围的组合，使得现实中的冲突概率小到几乎可以忽略。两份不同的证据要在所有五段上同时一致才会冲突。
 
-If document IDs are not guaranteed unique across batches (e.g., multiple batches contain files named `report.pdf`), prefix the document ID with the batch identifier: `B003-DOC042`. This extends the trace ID format to `R001-B003-DOC042-P3-S2-C120:180`.
+如果文档 ID 在跨批次时不能保证唯一（例如多个批次都包含名为 `report.pdf` 的文件），就给文档 ID 加批次前缀：`B003-DOC042`。trace ID 格式因此扩展为 `R001-B003-DOC042-P3-S2-C120:180`。
 
-Do not use random UUIDs. Deterministic trace IDs allow deduplication and comparison across verification runs.
+不要使用随机 UUID。确定性的 trace ID 才能支持跨核查运行的去重与比较。
 
-## Storage Overhead
+## 存储开销
 
-A single trace ID string is approximately 30-50 bytes. The full trace ID object (including `source_location`, `rule_version`, `workflow_version`, and `model_tier`) is approximately 100-200 bytes in JSON.
+单条 trace ID 字符串约 30-50 字节。完整 trace ID 对象（含 `source_location`、`rule_version`、`workflow_version`、`model_tier`）的 JSON 表示约 100-200 字节。
 
-For a typical batch of 1000 verification results, trace IDs add roughly 100-200 KB of storage. This is negligible relative to the result data itself and the source documents.
+按 1000 条核查结果一个批次估算，trace ID 占用大约 100-200 KB 存储——相对于结果数据本身和源文档而言，可以忽略不计。
 
-## Surviving Export/Re-Import
+## 经得起导出与重导入
 
-Trace IDs are embedded in the result JSON structure, not stored in external metadata, sidecar files, or database columns that might be lost during export.
+Trace ID 嵌入在结果 JSON 结构内，而非外部元数据、附属文件、或可能在导出时丢失的数据库列。
 
-Any system that consumes the verification result JSON automatically receives the trace IDs. Specific scenarios:
+任何消费核查结果 JSON 的系统都会自动获得 trace ID。具体场景：
 
-- **CSV export**: The `trace_id` field becomes a column. A developer user reviewing results in a spreadsheet can copy a trace ID and paste it back to locate the source evidence.
-- **Aggregation**: When results from multiple batches are merged, trace IDs remain attached to their individual results. No re-linking is needed.
-- **Downstream APIs**: Systems consuming verification results via API receive trace IDs as part of the payload. They can store, index, or display them without any awareness of the trace ID format.
-- **Archival**: Archived results retain full traceability years later, even if the original verification system has evolved.
+- **CSV 导出**：`trace_id` 字段成为一列。开发者用户在电子表格中复查时，可复制一条 trace ID 并粘贴回工具中以定位证据来源。
+- **聚合**：当多批次结果被合并时，trace ID 仍附着在各自结果上，无需重新关联。
+- **下游 API**：通过 API 消费核查结果的系统会在 payload 中收到 trace ID。它们可以无视格式细节地存储、索引或展示这些 ID。
+- **归档**：归档后的结果在多年之后仍保留完整的可追溯性，即使原核查系统已经演进。
 
-## Integration with Cross-Document Verification
+## 与跨文档核查的集成
 
-When `cross-document-verification` detects a contradiction between two documents, reference trace IDs from both sides:
+当 `cross-document-verification` 在两份文档之间检测到矛盾时，将两侧的 trace ID 同时引用：
 
 ```json
 {
@@ -76,4 +76,4 @@ When `cross-document-verification` detects a contradiction between two documents
 }
 ```
 
-This creates a linked evidence chain: auditors can follow both trace IDs to the exact locations in both documents, verify the extracted values, and determine which document (if either) is correct. Without trace IDs, cross-document contradictions require manual search through both documents to find the relevant passages.
+这构成一条连贯的证据链：审计人员可循两条 trace ID 分别跳到两份文档的精确位置，核对所抽取的值，并判断哪份（若有）文档是正确的。若没有 trace ID，跨文档矛盾就需要在两份文档中手工搜索相关段落。

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

@@ -6,7 +6,7 @@ description: 在 rule_extraction → skill_authoring 过渡阶段决定如何把
 
 # 工作拆分（Work Decomposition）
 
-KC 的 main agent 是指挥者。指挥者决定下一步做什么——而这个决定凌驾于后续所有选择之上。错误的拆分会让整个会话变得昂贵：规则顺序错了，agent 会把同一种结构重新设计三遍；不相关的规则被合并到一个 skill 里，最终 check.py 就会变成 E2E #4 那种"统一执行器"反模式；本应合并的相关规则被分散到不同 skill，agent 会把同样的 chunker 逻辑重新推导 17 次。
+KC 的 main agent 是指挥者。指挥者决定下一步做什么——而这个决定凌驾于后续所有选择之上。错误的拆分会让整个会话变得昂贵：规则顺序错了，agent 会把同一种结构重新设计三遍；不相关的规则被合并到一个 skill 里，最终 check.py 就会漂移成"统一执行器"反模式；本应合并的相关规则被分散到不同 skill，agent 会把同样的 chunker 逻辑反复推导很多次。
 
 这份 skill 是指挥者做这类决定的操作手册。它的层级标记是 `tier: meta-meta`，因为工作拆分是系统级的纪律，不是某条规则的具体技巧。互补的 `task-decomposition`（同样 `tier: meta-meta`）覆盖单条规则**内部**的结构——locate → extract → normalize → judge → comment。本 skill 覆盖的是规则**集合**该如何切分成 TaskBoard 任务。
 
@@ -15,7 +15,7 @@ KC 的 main agent 是指挥者。指挥者决定下一步做什么——而这
 - **进入 rule_extraction 时**。读完法规、拆出规则之后，在宣布该阶段完成之前，先决定这些规则会以什么顺序被处理、是否分组。覆盖审计与 chunk refs 都是这两个决定下游的工作。
 - **进入 skill_authoring 时**。TaskBoard 是空的（引擎不再自动生成 per-rule 任务）。从 `describeState` 读取规则列表，决定分组与顺序，然后为每个工作单元调用 `TaskCreate`。
 - **运行中觉得拆分不对时**。如果 TaskBoard 越走越奇怪（规则按错误顺序累积、明明该合并的两条规则被拆到两个任务里），停下来重新拆分。暂停 5 分钟重新规划的代价，会在接下来 2 条规则里被更合理的形状收回。
-- **任意阶段同时跑 3+ 个并行子目标时**。如果你发现自己在工作记忆里同时拎着多个并行子目标（3+ 条规则 × 文档、finalization 阶段的多份交付物、production_qc 的多个 QC 批次），把它们丢进 TaskBoard 串行处理。v0.7.5 审计显示 distillation 和 production_qc 阶段即便注册表里没显式暴露这个 skill 也能从显式任务化中获益 —— v0.8 P2-E 把它对所有阶段都开放。
+- **任意阶段同时跑 3+ 个并行子目标时**。如果你发现自己在工作记忆里同时拎着多个并行子目标（3+ 条规则 × 文档、finalization 阶段的多份交付物、production_qc 的多个 QC 批次），把它们丢进 TaskBoard 串行处理。从 rule_extraction 到 finalization，任何阶段一旦出现并行子目标，都会从显式任务化中获益 —— distillation 和 production_qc 也不例外。
 
 ## 简明判断：什么时候用 TaskBoard
 
@@ -40,7 +40,7 @@ KC 的 main agent 是指挥者。指挥者决定下一步做什么——而这
 
 先处理**最难**的规则。把这条难规则需要的 chunker、verdict 形状、worker 层级当作设计下限。后续规则按难度递减处理，每一条都是已经搭好的机制的退化形态。
 
-**何时选**：规则集合复杂度不均匀，并且你怀疑少数几条难规则会决定整体形状（合规/监管类工作几乎总是如此）。E2E #5 里 GLM 阴差阳错走的就是这条路，最终在真实 LLM 驱动的 workflow 上拿到了 0.6% ERROR；DS 走自底向上，最终 78% 的 verdict 是 NOT_APPLICABLE。
+**何时选**：规则集合复杂度不均匀，并且你怀疑少数几条难规则会决定整体形状（合规/监管类工作几乎总是如此）。这种方法走对了，在真实 LLM 驱动的 workflow 上能把 ERROR 率压到 1% 以下；走"自底向上"的反向路线则通常会过度产出 NOT_APPLICABLE —— 简单规则的机制无法承受最后那批难 case。
 
 **为何用 "Huffman" 而不是 "Shannon" 来类比**：Huffman 编码先处理低频符号来构造最优前缀码。KC 的对应物是单条成本高、出现频率低的规则——R028 那种类型，数量少但主导整个设计空间。先碰它们，简单规则就能廉价继承框架。
 
@@ -105,10 +105,10 @@ KC 的 main agent 是指挥者。指挥者决定下一步做什么——而这
 - 规则适用于不同文档类型（一条只对公募基金报告生效，另一条只对私募基金报告生效）
 - 一条规则的失败模式是另一条规则的特殊失败模式（不要把父规则和子规则合并——子规则的检查会冗余地重新执行父规则的检查）
 
-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 的粒度单元，这是有原因的。
+一种值得警惕的失败模式：指挥模型写了 2,000+ 行 `unified_qc.py` 一次性跑所有规则。结果是错误级联 —— 每条规则的失败都连带把所有其他规则的判定也带崩了，很容易在生产核查上做出 15%+ 的 ERROR 率。Per-rule skill 是 KC 的粒度单元，这是有原因的。
 
 ### 反模式：check.py 是 stub + workflow.py 才是真逻辑
 
@@ -149,22 +149,13 @@ def run(text, llm_fn=None):
 skill 的迭代（法规解释变化、生产中发现的边缘情形）需要一个**正典
 位置**来更新——也就是 skill——而不是 N 个已经各自漂移的 workflow。
 
-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
-（代码），单一信息源就丢了。
+**纯 stub 失败**：bundled skill 的 check.py 都写成 `{"pass": null, "method": "stub"}` 推给 `workflows/`。方法论写在 SKILL.md 里，但 skill 目录本身没有可执行实现。
 
-GLM v071 反而把正典模式落地了：97/97 个 skill 都同时有 SKILL.md 和
-真正的 `check.py`（regex + 适用性判断的代码，中位 143 行），而
-`workflows/<id>/workflow_v1.py` 是一个 50 行的薄壳，只是 import 并
-调用 skill 的 check.py：
+**正典-蒸馏关系搞反**：agent 避开了 stub（好），但把"正典 vs 蒸馏"的关系搞反了 —— 主题分组的 skill 文件夹只有 SKILL.md（没有 check.py），真正的验证代码在 `workflows/<skill>/check.py` 里。没有 stub 是好事；关系搞反不是 —— 要修改一条规则的逻辑就得同时改 SKILL.md（文档）和 workflow check.py（代码），单一信息源就丢了。
+
+正典落地长这样：每个 skill 都同时有有内容的 SKILL.md 和真正的 `check.py`（regex + 适用性判断的代码），而 `workflows/<id>/workflow_v1.py` 是一个约 50 行的薄壳，只是 import 并调用 skill 的 check.py：
 
 ```python
 # workflows/D01-01/workflow_v1.py — 薄壳，52 行
@@ -181,10 +172,7 @@ def run(doc_text: str, meta: dict = None) -> dict:
     return result
 ```
 
-这是 v0.7.2+ 的正典模式：workflow 是个壳，指向 skill 的 check.py。
-迭代规则验证逻辑时，编辑 `rule_skills/<id>/check.py`，workflow 不用动。
-v0.7.2 把引导说得更清楚：既不要 stub，也要保留正典关系（skill 是
-正典，workflow 是蒸馏过的薄壳）。
+这是正典模式：workflow 是个壳，指向 skill 的 check.py。迭代规则验证逻辑时，编辑 `rule_skills/<id>/check.py`，workflow 不用动。引导有两条：既不要 stub，也要保留正典关系（skill 是正典，workflow 是蒸馏过的薄壳）。
 
 ### 合并 check 的命名约定
 
@@ -348,7 +336,7 @@ PATTERNS.md 全文控制在约 5 KB 之内。超过时，剪掉最不可执行
 
 ### 调用 TaskCreate / TaskUpdate / TaskComplete
 
-引擎注册了三个任务面板工具（v0.7.4）：
+引擎注册了三个任务面板工具：
 
 - `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。
@@ -356,7 +344,7 @@ PATTERNS.md 全文控制在约 5 KB 之内。超过时，剪掉最不可执行
 
 ### Ralph 循环范围 —— 仅限当前阶段
 
-重要契约（v0.7.4 在团队反馈后调整）：
+重要契约：
 
 - **循环范围 = 仅当前阶段**。TaskCreate 只能为当前阶段建任务，Ralph 循环在阶段内逐条处理。
 - **阶段边界 = 循环退出**。当前阶段任务全部完成、或阶段推进（你调 `phase_advance`、或任何其他地方改了 `currentPhase`）时，循环干净退出，控制权回到用户。
@@ -388,9 +376,9 @@ TaskComplete({ id: "R001-skill_authoring",
 
 - **`rules/PATTERNS.md`** —— 简洁，只装框架级内容，随项目推进而更新。适合假设可以前置、结构清晰的全新项目。上限 ~5 KB；条目是可迁移的形状 / 项目级约束 / 反模式加原因（参考上面"该写什么"一节）。
 
-- **每阶段写 `logs/phase_<name>_complete.md`** —— 增量式，记录每个 phase 产出了什么、做了哪些决定、下个 phase 继承什么。适合"边发现边定型"的迭代式工作。E2E #7 GLM 用了这个模式：6 篇 phase 文档 + `evolution_summary_v1.2.md`，方法论照样捕获了，只是没写 PATTERNS.md。
+- **每阶段写 `logs/phase_<name>_complete.md`** —— 增量式，记录每个 phase 产出了什么、做了哪些决定、下个 phase 继承什么。适合"边发现边定型"的迭代式工作。一种真实出现过的模式：6 篇 phase 文档 + 一份 `evolution_summary_vN.md`，方法论照样捕获了，即使 PATTERNS.md 从未写过。
 
-- **`AGENT.md` decisions 段 + 领域笔记** —— 叙事风格，是关于"我们知道什么"和"为什么"的活文档。适合需要捕获丰富领域上下文的项目（法规、边缘案例、阈值、样本格式分布）。E2E #7 GLM 的 AGENT.md 里有法规生效日期、产品类型分类、阈值数值、样本格式数量 —— 完全 OK，是相同目标的不同惯用法。
+- **`AGENT.md` decisions 段 + 领域笔记** —— 叙事风格，是关于"我们知道什么"和"为什么"的活文档。适合需要捕获丰富领域上下文的项目（法规、边缘案例、阈值、样本格式分布）。一份记录了法规生效日期、产品类型分类、阈值数值、样本格式数量的 AGENT.md 完全 OK —— 这是相同目标的不同惯用法。
 
 不该做的事：跳过持久化、只靠对话上下文活着。等你写到第 N 条 skill 还没把方法论写到磁盘时，你已经做了 N 个关于 verdict 形状、chunker 边界、worker tier 的隐式决定 —— 每条规则都从零推导，重构要碰 N 个文件而不是一个。
 
@@ -398,15 +386,15 @@ TaskComplete({ id: "R001-skill_authoring",
 
 ✅ "每次 phase 推进之前，把这一阶段学到的东西写到适合本项目惯用法的那个持久化文件里 —— 哪怕只是初稿。"
 
-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：推进之前先持久化，格式灵活。
+值得警惕的失败模式：
+- agent 在出现回退之后才写 PATTERNS.md。那之前每条 skill 的设计决定都各自固化，之后还要再碰一遍。"PATTERNS.md FIRST"的引导就是因为这个代价存在。
+- agent 完全没写 PATTERNS.md，但写了内容详尽的 phase 完成日志和一份内容详尽的 AGENT.md —— 方法论 *捕获了*，只是放在了不同文件里。这没问题。更宽的原则是：推进之前先持久化，格式灵活。
 
-引擎从文件系统推导里程碑（v0.7.0 Group A）会按磁盘事实核验覆盖率，无论你怎么切分工作。TaskBoard 是你的草稿；磁盘才是契约；持久化文件是项目的记忆。
+引擎从文件系统推导里程碑会按磁盘事实核验覆盖率，无论你怎么切分工作。TaskBoard 是你的草稿；磁盘才是契约；持久化文件是项目的记忆。
 
 ## 子代理批处理：滚动窗口写入（rolling-window）
 
-当你派发 N 个子代理做批量工作（回归测试、批量核查、并行规则处理）时，**不要**让它们写同一个协调文件。v0.7.5 审计发现：子代理在 `tasks.json` / `rules/catalog.json` / `output/results/summary.json` 上互相抢锁 —— 一个占着工作区锁 5 分钟以上，其他在静默等待。
+当你派发 N 个子代理做批量工作（回归测试、批量核查、并行规则处理）时，**不要**让它们写同一个协调文件。一种值得警惕的失败模式：子代理在 `tasks.json` / `rules/catalog.json` / `output/results/summary.json` 上互相抢锁 —— 一个占着工作区锁好几分钟，其他在静默等待。
 
 正确的模式：每个子代理写到**自己**专属的、有已知前缀的文件。父代理在所有子代理完成后再做聚合。
 
@@ -426,6 +414,6 @@ output/
 # 父代理读所有 batch_regression_*.json，写汇总。
 ```
 
-引擎信号：如果你在 events.jsonl 里看到 `lock_blocked` 事件出现在子代理工作期间，那就是症状。v0.8 P4-C 加了这个事件发射，让父代理在子代理超时之前就看见冲突。出现就立刻改成滚动窗口写。
+引擎信号：如果你在 events.jsonl 里看到 `lock_blocked` 事件出现在子代理工作期间，那就是症状 —— 引擎会发出这个事件，让父代理在子代理超时之前就看见冲突。出现就立刻改成滚动窗口写。
 
 不要写"用文件锁协调"的子代理批处理。锁原语是用来防止意外并发写入的安全机制，不是队列。用文件系统布局作为协调机制。