kc-beta 0.7.5 → 0.8.1

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

@@ -188,3 +188,56 @@ Worker LLM 通过 SiliconFlow API 访问。连接信息在 `.env` 里：
 - `TIER1` 到 `TIER4` —— 各层级的模型名称
 
 各模型当前的能力与上下文窗口大小，见 `references/worker-llm-catalog.md`。
+
+## 两条访问路径：`worker_llm_call` 工具（优先）vs 直接 HTTP
+
+KC 自带一个 `worker_llm_call` 工具。能用就用 —— 引擎能看到每次调用，能统计成本和 token、做限流、并把数据进入审计。v0.8 P2-B 增加了批量模式：
+
+```
+worker_llm_call({
+  tier: "tier1",
+  prompts: ["核查文档 A...", "核查文档 B...", "核查文档 C..."],
+  system_prompt: "你是合规助手。返回 JSON {verdict, evidence, confidence}。",
+  concurrency: 5    // 1-10，默认 5
+})
+```
+
+返回 `{n_total, n_succeeded, n_failed, total_tokens_in, total_tokens_out, results: [...]}` 摘要。部分失败不会让整批失败。
+
+### 规范的 `workflows/common/llm_client.py`（v0.8.1 起作为模板文件随包发布）
+
+对于一个 **独立运行** 的 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
+
+result = call(
+    tier="tier2",
+    prompt=user_prompt,
+    system_prompt="你是合规助手。返回 JSON。",
+    max_tokens=2048,
+)
+# result = {"response": "...", "model_used": "...", "tier": "tier2",
+#          "tokens_in": N, "tokens_out": N}
+```
+
+shim 做的事：
+- 从 `.env` 读 `LLM_API_KEY` + `LLM_BASE_URL` + `TIER1..4`（多 provider 友好 —— SiliconFlow、OpenAI、Anthropic、阿里、火山等都能用）
+- 以 OpenAI 兼容的 chat completions 格式发请求到配置好的 base URL
+- 每次调用往 `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` 事件）。
+
+## sandbox_exec 超时设置（已知耗时长的命令）
+
+`sandbox_exec` 默认超时是 120 秒。对于你预期会跑得更久的命令 —— LLM 批处理、大型回归测试、文档解析 —— 显式传 `timeout_ms`（最大 600000ms = 10 分钟）。不要靠把任务切成不必要的小块来绕开默认值；那只会浪费回合数并模糊意图。
+
+```
+sandbox_exec({
+  command: "python scripts/v2_full_test.py",
+  timeout_ms: 480000   // 14 条规则 × 6 篇文档走 worker LLM，预留 8 分钟
+})
+```
+
+如果已经顶到 10 分钟上限还在超时，把工作拆成多次调用，或者交给子代理（子代理的超时和父进程相互独立）。

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

@@ -12,62 +12,65 @@ description: >
 
 # Tree Processing
 
-Most verification rules do not need the entire document. They need a specific section, a specific table, a specific disclosure. The tree is your map for navigating large documents efficiently.
+绝大多数验证规则并不需要整篇文档。它们只需要某个特定的章节、某张特定的表格、或某条特定的披露内容。树就是你在大型文档中高效导航的地图。把一份动辄数百页、上千页的法规摊在工作 LLM 面前,既装不进上下文窗口,也会被无关内容稀释关键事实。建好树之后,验证就从"在整片汪洋里捞针",收敛为"先按图找到房间,再在房间里翻箱倒柜"。
 
-## Production Chunking Methodology
+## 生产级分块方法论
 
-For verification workflows that process many documents, the chunking mechanism must be precise, consistent, and fast. The approach:
+对于需要处理大量文档的验证工作流而言,分块机制必须做到精确、一致且快速。"精确"意味着同一份文档被切出的边界总是落在正确的位置;"一致"意味着今天切和明天切的结果一模一样;"快速"意味着不会成为流水线里的瓶颈。要同时满足这三点,几乎只有"用代码固化结构规律"这一条路径。基本路径如下:
 
-1. **Observe**: Read 3-5 sample documents. Note their structure — headers, numbering, section patterns.
-2. **Find patterns**: Identify what's consistent (header format, numbering convention, TOC structure).
-3. **Write code**: Design a chunking script (regex-based splitter, header detector, TOC parser) that captures the pattern.
-4. **Test**: Run the script on samples. Verify it produces correct, consistent chunks.
-5. **Deploy**: The script runs in production workflows. It's deterministic, free, and fast.
+1. **观察**:阅读 3 到 5 份样本文档。记录其结构特征——标题样式、编号方式、章节划分规律。不要只看一份就动手,小样本的偶然格式会把你引向一段过拟合的脆弱正则。
+2. **找出模式**:识别那些保持一致的元素(标题格式、编号约定、目录结构)。同时把不一致的部分单独列出来,这些就是后续脚本需要兜底处理的边缘情形。
+3. **编写代码**:设计一段分块脚本(基于正则的切分器、标题检测器、目录解析器),用代码固化所发现的模式。脚本应当是确定性的、可重入的,并且对输入文本的小幅扰动具有鲁棒性。
+4. **测试**:在样本上运行脚本。验证它产出的分块结果与你人工标注的边界一致。如果出现错切、漏切或越切,先回到第 1 步补充观察样本,再来调整规则。
+5. **部署**:脚本在生产工作流中正式运行。它是确定性的、零成本的、且执行迅速。一份脚本写好,就可以服务于同类型文档的全部后续处理。
 
-This is different from `document-chunking` (quick, cheap splits for exploration). Production chunking is a one-time design effort that pays off across all documents of the same type.
+这与 `document-chunking` 不同(后者用于探索阶段的快速、低成本切分)。生产级分块是一次性的设计投入,但其收益会在同类型文档的所有处理过程中持续兑现。换言之,前者是面向"我先粗略看看这文档大致长什么样"的临时手段,后者是面向"我每天都要处理一千份这种文档"的工程资产。
 
-## Why Trees
+## 为什么要使用树
 
-Two reasons:
+两条理由,都很硬:
 
-1. **Rules have scope.** "The risk disclosure in Chapter 5 must contain..." — you need to find Chapter 5, not read 1000 pages.
-2. **Worker LLMs have limits.** A 16K-32K context window cannot hold a 1000-page document. You must narrow to the relevant section.
+1. **规则带有作用域。**"第 5 章中的风险披露必须包含……"——你需要定位第 5 章,而不是把 1000 页全部读一遍。验证类规则几乎天生就是带作用域的:它要么针对某个章节,要么针对某张表,要么针对某条具体的条款。把规则原原本本喂给一份完整文档,等于在让 LLM 自己先承担"找位置"这件本不该由它承担的工作。
+2. **工作 LLM 有上下文上限。**16K 到 32K 的上下文窗口装不下一份 1000 页的文档。你必须把范围收窄到相关章节。即便是更大的上下文窗口,只要你把无关内容也一起喂进去,准确率就会被稀释,延迟会上升,Token 成本也会随之上涨。
 
-The tree structure solves both: it tells you WHERE things are, and lets you extract JUST what you need.
+树结构同时解决了这两个问题:它告诉你"东西在哪里",并让你只抽取"你真正需要的那部分"。从工程视角看,树是文档的索引;从语义视角看,树是规则与文本之间的桥梁。把这座桥建好,后续每一条规则的验证都会变得简单、可靠、可解释。
 
-## Building the Tree
+## 构建树
 
-### Step 1: Discover the Structure
+### 步骤 1:发现结构
 
-Before building a tree parser, explore several sample documents to find structural patterns. Look for:
+在动手实现树解析器之前,先去探查几份样本文档,找出其结构上的规律。这一步看似只是"翻一翻文档",但它直接决定了后续所有工程决策的下限。请把它当作严肃的需求调研来做,而不是顺手扫一眼。关注以下要素:
 
-- **Header conventions**: Do chapters start with "Chapter X"? "第X章"? "Part X"? A Roman numeral?
-- **Numbering systems**: "1.1.2", "Article 3", "(a)(i)", hierarchical numbering?
-- **Visual markers**: Bold text, larger font, horizontal rules, page breaks before chapters?
-- **Table of contents**: Most formal documents have one. It is the document's own tree.
+- **标题约定**:章是以 "Chapter X" 开头?"第X章"?"Part X"?还是罗马数字?同一份文档中,顶层与子层的标题格式是否一致?中英混排的文档是否两种约定并存?
+- **编号体系**:"1.1.2"、"Article 3"、"(a)(i)"、还是层级化的编号?编号是否每章重置?是否存在跨章共享的全局编号?编号缺位或跳号的情况是个例还是规律?
+- **视觉标记**:加粗字体、更大的字号、水平分隔线、章节前的分页符?这些信息在转成纯文本以后是否还能保留?如果输入是 PDF 解析后的文本,是否需要先在更早的环节注入这些标记?
+- **目录(TOC)**:大多数正式文档都带有目录。它本身就是这份文档自带的树。目录还能告诉你页码区间、官方的层级深度、以及哪些标题是法定的、哪些是排版插入的。
 
-Spend time here. The patterns you find determine whether the tree builder is a simple regex or a complex parser.
+在这一步多花点时间。你找到的模式将直接决定:树构建器是一段简单的正则,还是一个复杂的解析器。经验上,凡是受监管发布的法规文档,几乎都遵循同一套排版规范;凡是来自不同机构的合并文档,则常常需要把多套规则同时纳入解析器的考量。
 
-### Step 2: Choose the Parser
+### 步骤 2:选择解析器
 
-**If patterns are consistent** (they usually are in regulated documents):
-- Write a regex-based splitter. For example:
-  - `^第[一二三四五六七八九十百千]+章` for Chinese chapter headers
-  - `^Chapter \d+` for English
-  - `^\d+\.\d+(\.\d+)*\s` for numbered sections
-- This is fast, deterministic, and reliable. Prefer this when it works.
+**如果模式足够一致**(在受监管的法规类文档中通常都是一致的):
+- 写一个基于正则的切分器。例如:
+  - `^第[一二三四五六七八九十百千]+章` 用于匹配中文的章标题
+  - `^Chapter \d+` 用于匹配英文章标题
+  - `^\d+\.\d+(\.\d+)*\s` 用于匹配带编号的小节
+- 这种方案快速、确定、可靠。只要正则跑得通,优先选它。不要因为追求"看起来更智能"就放弃确定性的方案——确定性本身就是生产环境最稀缺、最值钱的属性。
+- 在调试阶段,记得为正则写一组小型的单元测试:包括典型的命中样例、明确不应命中的反例,以及容易混淆的边界样例(比如标题中混入的全角空格、不可见控制字符)。
 
-**If patterns are inconsistent or absent**:
-- Use the LLM-guided wedge-driving approach (see `rule-extraction/references/chunking-strategies.md` for the full algorithm: rolling context window, K-token quoting, Levenshtein fuzzy matching).
-- This is slower and costs LLM calls, but handles unstructured documents. The rolling window means even very large unstructured leaf nodes can be chunked incrementally.
+**如果模式不一致或根本不存在**:
+- 使用 LLM 引导的"楔入式"切分方法(完整算法见 `rule-extraction/references/chunking-strategies.md`:滚动上下文窗口、K-token 引用比对、Levenshtein 模糊匹配)。
+- 这种方式较慢,且要消耗 LLM 调用,但能处理非结构化的文档。滚动窗口的意义在于:即便是非常巨大的非结构化叶子节点,也可以逐段递进地完成切分。
+- 一个务实的折中是混合策略:能用正则切到的层级先用正则切,正则啃不动的子节点再交给 LLM 引导式切分。这样可以把昂贵的 LLM 调用集中投放在真正需要语义判断的地方。
 
-**If the document has a table of contents**:
-- Parse the TOC first. It gives you the tree structure and page numbers for free.
-- Then use the TOC-derived structure to split the document body.
+**如果文档自带目录**:
+- 先解析目录。它免费地给了你一棵树的结构,外加每个节点的页码。
+- 然后再用从目录派生出的结构去切分文档正文。
+- 需要注意目录与正文之间偶尔会出现不一致(目录漏列了某节、或正文新增了目录里没有的小节)。把这些差异当作日志输出,便于后续人工核对,而不是默默吞掉。
 
-### Step 3: Build the Tree
+### 步骤 3:构建树
 
-The tree is a simple nested structure:
+树本身是一种简单的嵌套结构:
 
 ```
 Document
@@ -83,40 +86,41 @@ Document
     └── Chapter 5: Risk Disclosure (pages 79-120)
 ```
 
-Each node stores: the header text, the level, the start/end positions in the document, and the content size (in tokens or characters).
+每个节点都需要存储:标题文本、所在层级、在文档中的起止位置、以及内容规模(以 token 数或字符数计)。在工程实现上,建议同时保留一个稳定的节点 ID(例如从根到当前节点的编号路径),便于后续的引用追踪、缓存命中以及跨规则的复用。父节点和子节点之间通过显式的指针或 ID 关联,这样无论是自顶向下遍历还是自底向上追溯祖先,代价都是常数级的。
 
-### Step 4: Use the Tree
+### 步骤 4:使用树
 
-Given a rule that says "check the risk disclosure section":
+假设有一条规则要求"检查风险披露章节":
 
-1. **Search the tree** for the relevant node. Match the rule's scope description against node headers.
-   - Exact match: "Chapter 5" → find node with "Chapter 5" header.
-   - Semantic match: "risk disclosure section" → find node whose header or content relates to risk disclosure. May need fuzzy matching or LLM classification.
-2. **Extract the content** of that node (and optionally its children).
-3. **Check the size.** If the content fits in the worker LLM's context window, use it directly. If not, descend to child nodes and find the specific subsection needed.
+1. **在树中检索**目标节点。把规则中描述的作用域与节点标题做匹配。
+   - 精确匹配:"Chapter 5" → 找到标题为 "Chapter 5" 的节点。这种命中是最理想的情况,可以直接落点,不留歧义。
+   - 语义匹配:"风险披露章节" → 查找其标题或内容与"风险披露"相关的节点。这一步可能需要模糊匹配,或者用 LLM 做分类判断。在大型文档中,语义匹配应当先在标题层面尝试命中,只有标题不足以判断时,才下沉到摘要或正文。
+2. **抽取该节点的内容**(必要时也包括其子节点的内容)。抽取时同时记录这次抽取的来源节点 ID,这样验证结论就能反向追溯到文档中的具体位置,而不是悬空于"模型说"。
+3. **检查规模。**如果内容能够塞进工作 LLM 的上下文窗口,就直接使用。如果塞不下,则向下进入子节点,定位到真正需要的那个小节。在下沉过程中,记得保留祖先节点的标题链,使得 LLM 始终知道它正在阅读的是文档中的哪个位置。
 
-## The Full Context → Chapter → Entity Pipeline
+## "全文 → 章 → 实体" 流水线
 
-This is the standard narrowing funnel for extracting entities for verification:
+这是从文档中抽取待验证实体的标准漏斗式收窄过程,也是 KC 推荐的默认验证编排方式。每一步都把范围进一步收紧,把验证任务交给一个能力恰好匹配、上下文恰好够用的环节去完成:
 
-1. **Full context**: Use the tree to understand the document structure. Know where everything is.
-2. **Chapter**: Navigate to the specific section that the rule targets. Extract its content.
-3. **Entity**: Within the chapter content, extract the specific entity (number, text, clause) using the techniques from `entity-extraction`.
+1. **全文上下文**:借助树来理解整份文档的结构。知道每样东西分别在哪里。这一步不需要 LLM 真的去读全文,只需要让规则与树之间建立索引关系。
+2. **章节**:导航到这条规则所针对的具体章节。抽取其内容。注意章节边界要严格按照树上的起止位置来,不要凭印象多取或少取,否则验证准确率会被边界噪声拖累。
+3. **实体**:在章节内容内,使用 `entity-extraction` 中的方法,把具体的实体(数字、文本片段、条款)抽取出来。这是最贴近规则原子比对单元的一步。
 
-For worker LLMs with 16K-32K context:
-- The chapter content + the extraction prompt must fit in the context window.
-- If a chapter is too large, descend further in the tree.
-- Always include the parent header chain for context: "Part II > Chapter 3 > Section 3.1" so the LLM knows where this content sits in the document.
+对于上下文窗口为 16K–32K 的工作 LLM:
+- 章节内容加上抽取提示词必须能够装进上下文窗口。把这两部分的预估 Token 数加起来,留出至少 10% 余量给输出。
+- 如果某一章过大,就继续向下进入树的更深层。优先选择能完整覆盖规则作用域的最小子节点。
+- 始终把父级标题链一并附带上,作为定位上下文:例如 "Part II > Chapter 3 > Section 3.1",这样 LLM 才知道这段内容在整份文档中处于什么位置。缺少这条标题链,LLM 容易把同名的小节弄混,尤其是在带有"通则—分则"结构的法规中。
 
-## Caching and Reuse
+## 缓存与复用
 
-Build the tree once per document, reuse across all rules:
-- Save the tree structure as JSON alongside the parsed document.
-- Multiple rules may need different sections of the same document. The tree lets each rule navigate directly to its section without re-parsing.
+每份文档只需构建一次树,然后在所有规则上复用:
+- 把树结构以 JSON 形式与解析后的文档一同保存下来。文件名可以采用 `<doc_id>_tree.json` 这样的稳定模式,便于后续按文档 ID 直接读取。
+- 同一份文档常常会被多条规则命中不同的章节。树让每条规则都能直接跳转到自己关心的位置,而无需重新解析文档。这一点在批量验证场景下尤其重要,它把"O(规则数 × 文档解析)"的代价降到了"O(文档解析)+O(规则数 × 树检索)"。
+- 当文档版本发生变化时,把新旧两版的树做对比,可以快速看出新增、删除、合并、重排的章节,从而决定哪些旧的验证结论需要重跑、哪些可以延续。
 
-## Edge Cases
+## 边界情况
 
-- **Flat documents**: Some documents have no structural hierarchy. Treat the entire document as one node. Use LLM-guided chunking if it exceeds the context window.
-- **Deeply nested structures**: Some legal documents have 6+ nesting levels. Build all levels but typically only navigate 2-3 levels deep for any given rule.
-- **Cross-section references**: A section might reference "as defined in Section 1.2." When extracting, you may need content from multiple tree nodes. Collect them into a single context for the LLM.
-- **Appendices and annexes**: Often contain critical tables and data. Include them as top-level nodes in the tree.
+- **扁平文档**:有些文档完全没有结构化的层级。把整份文档当作一个节点处理。如果其规模超出上下文窗口,则改用 LLM 引导式分块。在这种情形下,要特别注意保留一份原文的连续性索引,以便后续把抽取结果回贴到正确的字符偏移上。
+- **嵌套很深的结构**:某些法律文档有 6 层及以上的嵌套层级。构建时把所有层级都建起来,但对任何一条具体规则,通常只需向下导航 2 到 3 层即可。过度下钻反而会让规则失去其应有的上下文,使得 LLM 看不到关键的限定性表述。
+- **跨章节的交叉引用**:某节可能写有"如第 1.2 节所定义"这样的字样。在抽取时,你可能需要同时从树上多个节点取内容。把它们拼成一个统一的上下文,再交给 LLM。在记录验证依据时,要分别标注每段来源节点,避免把"第 5 章的结论"与"第 1.2 节的定义"混为一谈。
+- **附录与附件**:附录和附件中往往承载着关键的表格和数据。要把它们作为顶层节点纳入树中,不要遗漏。许多披露类规则的"数字真相"恰恰躲在附录的表格里,正文反而只是导引性的描述。

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

@@ -15,6 +15,14 @@ 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 把它对所有阶段都开放。
+
+## 简明判断：什么时候用 TaskBoard
+
+- 同时处理 N+ 条规则或 N+ 份文档？→ 开工之前先 `TaskCreate` 每个为一个任务。
+- 一步就能干完的小请求？→ 跳过，直接做。
+- 子代理内部协调？→ 跳过，子代理不暴露 TaskBoard。
+- 任何你心里要靠"待会儿再回来"才能撑住的事？→ 现在就 TaskCreate 出来。长回合下工作记忆会漏掉半成品。
 
 ## 锁定原则
 
@@ -395,3 +403,29 @@ E2E 历史：
 - E2E #7 v071 DS 和 GLM 都没写 PATTERNS.md，但 GLM 写了 6 篇 phase 完成日志和一份内容详尽的 AGENT.md —— 方法论 *捕获了*，只是放在了不同文件里。v0.7.2 把更宽的原则写进 skill：推进之前先持久化，格式灵活。
 
 引擎从文件系统推导里程碑（v0.7.0 Group A）会按磁盘事实核验覆盖率，无论你怎么切分工作。TaskBoard 是你的草稿；磁盘才是契约；持久化文件是项目的记忆。
+
+## 子代理批处理：滚动窗口写入（rolling-window）
+
+当你派发 N 个子代理做批量工作（回归测试、批量核查、并行规则处理）时，**不要**让它们写同一个协调文件。v0.7.5 审计发现：子代理在 `tasks.json` / `rules/catalog.json` / `output/results/summary.json` 上互相抢锁 —— 一个占着工作区锁 5 分钟以上，其他在静默等待。
+
+正确的模式：每个子代理写到**自己**专属的、有已知前缀的文件。父代理在所有子代理完成后再做聚合。
+
+```
+sub_agents/
+  batch-001-regression/
+    output/results/v2_regression.json       # ❌ 多个子代理共用 — 抢锁
+  batch-002-regression/
+    output/results/v2_regression.json       # ❌ 同一路径，竞争
+
+# 改为：
+
+output/
+  batch_regression_001.json                 # ✓ 每个子代理一个文件
+  batch_regression_002.json                 # ✓
+  batch_regression_003.json                 # ✓
+# 父代理读所有 batch_regression_*.json，写汇总。
+```
+
+引擎信号：如果你在 events.jsonl 里看到 `lock_blocked` 事件出现在子代理工作期间，那就是症状。v0.8 P4-C 加了这个事件发射，让父代理在子代理超时之前就看见冲突。出现就立刻改成滚动窗口写。
+
+不要写"用文件锁协调"的子代理批处理。锁原语是用来防止意外并发写入的安全机制，不是队列。用文件系统布局作为协调机制。

package/template/workflows/common/llm_client.py

@@ -0,0 +1,168 @@
+"""KC worker-LLM client (v0.8.1 P10-A canonical shim).
+
+Distilled workflows use this module to call worker LLMs. Provider-agnostic:
+reads connection info from workspace `.env` so the same workflow can run
+against SiliconFlow, OpenAI, Anthropic, Aliyun, Volcanocloud, etc.
+
+Two modes:
+  - Inside a KC session: the engine's `worker_llm_call` tool is preferred
+    for new code (it tracks cost, applies rate limiting, and writes to
+    events.jsonl). This shim is fine if the workflow needs to be
+    portable to standalone (no-KC) deployment.
+  - Standalone (deployed release bundle): this shim is the only LLM
+    access path. Every call writes a line to `output/llm_ledger.jsonl`
+    so post-hoc analysis can reconstruct cost and traffic.
+
+Required `.env` fields:
+  LLM_API_KEY     API key for the provider
+  LLM_BASE_URL    Provider base URL (e.g. https://api.siliconflow.cn/v1)
+  TIER1..TIER4    Comma-separated model names per tier
+
+Optional:
+  LLM_AUTH_TYPE   "bearer" (default) | "x-api-key" (Anthropic native)
+  LLM_API_FORMAT  "openai" (default) — only OpenAI-format chat completions
+                  are supported by this shim. Use worker_llm_call for
+                  non-OpenAI-format providers (e.g. Anthropic native).
+
+If LLM_BASE_URL is missing, the shim raises explicitly — no silent
+fallback to a hardcoded vendor URL. This avoids accidentally sending
+traffic to siliconflow.cn from an OpenAI-configured workspace.
+
+Migration aliases:
+  SILICONFLOW_API_KEY → falls back to LLM_API_KEY if the canonical
+  name is missing (for workspaces predating v0.8.1).
+"""
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+
+_LEDGER_PATH = os.path.join("output", "llm_ledger.jsonl")
+
+
+def call(tier="tier2", prompt="", system_prompt=None, max_tokens=4096, timeout_s=120):
+    """Single-prompt chat-completions call.
+
+    Returns: {response, model_used, tier, tokens_in, tokens_out}.
+    Raises: RuntimeError on missing config; urllib HTTPError on transport.
+    """
+    if not prompt:
+        raise RuntimeError("call() requires a non-empty `prompt`")
+
+    api_key = _env("LLM_API_KEY") or _env("SILICONFLOW_API_KEY")
+    if not api_key:
+        raise RuntimeError(
+            "LLM_API_KEY not configured. Set it in .env or run `kc-beta onboard`."
+        )
+
+    base_url = _env("LLM_BASE_URL") or _env("SILICONFLOW_BASE_URL")
+    if not base_url:
+        raise RuntimeError(
+            "LLM_BASE_URL not configured. Set the canonical name in .env "
+            "(e.g. https://api.openai.com/v1 for OpenAI; "
+            "https://api.siliconflow.cn/v1 for SiliconFlow). "
+            "Run `kc-beta onboard` to configure interactively."
+        )
+    base_url = base_url.rstrip("/")
+
+    auth_type = (_env("LLM_AUTH_TYPE") or "bearer").lower()
+    api_format = (_env("LLM_API_FORMAT") or "openai").lower()
+    if api_format != "openai":
+        raise RuntimeError(
+            f"LLM_API_FORMAT={api_format} not supported by this shim. "
+            f"Only `openai` chat-completions wire format is implemented. "
+            f"Use the engine's `worker_llm_call` tool for native non-OpenAI providers."
+        )
+
+    tier_models = _load_tier_models(tier)
+    if not tier_models:
+        raise RuntimeError(f"No models configured for {tier.upper()}; check .env TIER1-TIER4")
+
+    messages = []
+    if system_prompt:
+        messages.append({"role": "system", "content": system_prompt})
+    messages.append({"role": "user", "content": prompt})
+
+    body = json.dumps(
+        {"model": tier_models[0], "messages": messages, "max_tokens": max_tokens}
+    ).encode("utf-8")
+
+    headers = {"Content-Type": "application/json"}
+    if auth_type == "x-api-key":
+        headers["x-api-key"] = api_key
+        headers["anthropic-version"] = "2023-06-01"
+    else:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    req = urllib.request.Request(f"{base_url}/chat/completions", data=body, headers=headers)
+    t0 = time.time()
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as resp:
+            data = json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        # Preserve the body for debugging — providers often return useful errors
+        err_body = e.read().decode("utf-8", errors="replace")[:500] if e.fp else ""
+        raise RuntimeError(f"LLM call HTTP {e.code} from {base_url}: {err_body}") from e
+
+    usage = data.get("usage") or {}
+    result = {
+        "response": data["choices"][0]["message"]["content"],
+        "model_used": tier_models[0],
+        "tier": tier,
+        "tokens_in": usage.get("prompt_tokens", 0),
+        "tokens_out": usage.get("completion_tokens", 0),
+    }
+    _write_ledger({
+        **result,
+        "duration_s": round(time.time() - t0, 3),
+        "ts": time.time(),
+        "base_url": base_url,
+        "auth_type": auth_type,
+    })
+    return result
+
+
+def _env(key):
+    """Read `key` from process env first, then workspace .env file."""
+    v = os.environ.get(key)
+    if v:
+        return v
+    if os.path.exists(".env"):
+        try:
+            with open(".env", "r", encoding="utf-8") as f:
+                for raw in f:
+                    line = raw.strip()
+                    if not line or line.startswith("#"):
+                        continue
+                    if "=" not in line:
+                        continue
+                    k, val = line.split("=", 1)
+                    if k.strip() == key:
+                        val = val.strip()
+                        if (val.startswith('"') and val.endswith('"')) or (
+                            val.startswith("'") and val.endswith("'")
+                        ):
+                            val = val[1:-1]
+                        return val
+        except OSError:
+            return None
+    return None
+
+
+def _load_tier_models(tier):
+    raw = _env(tier.upper()) or ""
+    return [m.strip() for m in raw.split(",") if m.strip()]
+
+
+def _write_ledger(record):
+    try:
+        os.makedirs(os.path.dirname(_LEDGER_PATH), exist_ok=True)
+        with open(_LEDGER_PATH, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except OSError:
+        # Ledger is best-effort; never break the workflow over a write failure.
+        pass
+
+
+__all__ = ["call"]

package/template/workflows/common/utils.py

@@ -0,0 +1,132 @@
+"""KC workflow helpers (v0.8.1 P10-B).
+
+Common utilities for distilled workflows. Provider-agnostic, no
+external dependencies. Reusable across rule check.py / workflow.py
+files so that per-rule scripts stay focused on rule-specific logic.
+
+Currently:
+  strip_annotations(text)     — drop reviewer-annotation footers
+                                from sample documents so per-rule
+                                check.py regex doesn't false-positive
+                                on the annotation itself
+
+  detect_report_type(text)    — light-touch report-type classifier
+                                (年报 / 季报 / 月报 / 周报 / 其他)
+                                used by rules that gate on report type
+
+  make_result(rule_id, verdict, evidence, confidence, **kwargs)
+                              — standardized result dict factory
+"""
+import re
+
+
+# Annotation prefixes that mark reviewer-added footers in sample docs.
+# These should be stripped before keyword/regex matching so per-rule
+# check.py doesn't match the annotation as if it were document content.
+#
+# Added based on E2E #11 贷款 v0.8 audit § 9: 4/14 spot-checks
+# false-positive PASS because samples contain `预期命中点: ...年化利率`
+# footers that the rule's keyword regex matches.
+_ANNOTATION_PREFIXES = (
+    "预期命中点",
+    "预期结果",
+    "预期判定",
+    "预期验证",
+    "标注",
+    "审核标注",
+    "Expected",
+    "expected",
+    "EXPECTED",
+    "Annotation",
+    "annotation",
+)
+
+
+def strip_annotations(text, extra_prefixes=None):
+    """Remove reviewer-annotation footers from document text.
+
+    A line is dropped if it starts with one of the recognized
+    annotation prefixes followed by `:` or `：` (Chinese full-width
+    colon). All subsequent lines until a blank line or end of text
+    are also dropped (annotations are typically multi-line trailing
+    blocks).
+
+    Pass `extra_prefixes` (iterable of strings) to add project-specific
+    annotation labels.
+
+    Returns the cleaned text. Input is never mutated.
+    """
+    if not text:
+        return text
+    prefixes = tuple(_ANNOTATION_PREFIXES)
+    if extra_prefixes:
+        prefixes = prefixes + tuple(extra_prefixes)
+    # Build a pattern matching `<prefix>` + colon (half or full-width)
+    pattern = "|".join(re.escape(p) for p in prefixes)
+    anno_start = re.compile(rf"^\s*(?:{pattern})\s*[::]")
+
+    out_lines = []
+    in_anno_block = False
+    for line in text.split("\n"):
+        if anno_start.match(line):
+            in_anno_block = True
+            continue
+        if in_anno_block:
+            # End block on a blank line OR a line that doesn't look
+            # like annotation continuation (no leading whitespace).
+            if not line.strip() or not line.startswith((" ", "\t", "-", "*", "·")):
+                in_anno_block = False
+                if line.strip():
+                    out_lines.append(line)
+            # Otherwise still inside the annotation block — drop.
+            continue
+        out_lines.append(line)
+    return "\n".join(out_lines)
+
+
+_REPORT_TYPE_PATTERNS = [
+    ("年报", re.compile(r"年报|年度报告|annual report", re.IGNORECASE)),
+    ("半年报", re.compile(r"半年报|半年度报告|interim report", re.IGNORECASE)),
+    ("季报", re.compile(r"季报|季度报告|quarterly report", re.IGNORECASE)),
+    ("月报", re.compile(r"月报|月度报告|monthly report", re.IGNORECASE)),
+    ("周报", re.compile(r"周报|周度报告|weekly report", re.IGNORECASE)),
+]
+
+
+def detect_report_type(text):
+    """Light-touch report-type classifier.
+
+    Returns one of: "年报", "半年报", "季报", "月报", "周报", "其他".
+    Scans only the first 2000 chars (report-type identifiers usually
+    appear in the title or cover page). Used by rules that gate on
+    report type (e.g. R02-06/R02-08 are NOT_APPLICABLE for 季报).
+    """
+    if not text:
+        return "其他"
+    head = text[:2000]
+    for kind, pattern in _REPORT_TYPE_PATTERNS:
+        if pattern.search(head):
+            return kind
+    return "其他"
+
+
+def make_result(rule_id, verdict, evidence, confidence=0.7, **kwargs):
+    """Build a standardized check result dict.
+
+    Required: rule_id, verdict ("PASS" / "FAIL" / "WARNING" / "NOT_APPLICABLE"),
+    evidence (string explaining the verdict).
+
+    Optional: confidence (0.0-1.0), plus any extra fields the rule
+    needs (model_used, llm_calls, llm_tokens, comment, etc.).
+    """
+    result = {
+        "rule_id": rule_id,
+        "verdict": verdict,
+        "evidence": evidence,
+        "confidence": confidence,
+    }
+    result.update(kwargs)
+    return result
+
+
+__all__ = ["strip_annotations", "detect_report_type", "make_result"]