kc-beta 0.7.5 → 0.8.3

package/template/skills/zh/skill-creator/references/schemas.md

@@ -1,12 +1,12 @@
 # JSON Schemas
 
-This document defines the JSON schemas used by skill-creator.
+本文档定义 skill-creator 使用的各类 JSON schema。
 
 ---
 
 ## evals.json
 
-Defines the evals for a skill. Located at `evals/evals.json` within the skill directory.
+定义某个技能的评估项。位于该技能目录下的 `evals/evals.json`。
 
 ```json
 {
@@ -26,19 +26,19 @@ Defines the evals for a skill. Located at `evals/evals.json` within the skill di
 }
 ```
 
-**Fields:**
-- `skill_name`: Name matching the skill's frontmatter
-- `evals[].id`: Unique integer identifier
-- `evals[].prompt`: The task to execute
-- `evals[].expected_output`: Human-readable description of success
-- `evals[].files`: Optional list of input file paths (relative to skill root)
-- `evals[].expectations`: List of verifiable statements
+**字段：**
+- `skill_name`：与技能 frontmatter 中的 name 一致
+- `evals[].id`：唯一的整数标识
+- `evals[].prompt`：要执行的任务
+- `evals[].expected_output`：以人类可读方式描述的成功标准
+- `evals[].files`：可选的输入文件路径列表（相对于技能根目录）
+- `evals[].expectations`：可被核验的断言列表
 
 ---
 
 ## history.json
 
-Tracks version progression in Improve mode. Located at workspace root.
+跟踪 Improve 模式下的版本演进。位于工作区根目录。
 
 ```json
 {
@@ -71,21 +71,21 @@ Tracks version progression in Improve mode. Located at workspace root.
 }
 ```
 
-**Fields:**
-- `started_at`: ISO timestamp of when improvement started
-- `skill_name`: Name of the skill being improved
-- `current_best`: Version identifier of the best performer
-- `iterations[].version`: Version identifier (v0, v1, ...)
-- `iterations[].parent`: Parent version this was derived from
-- `iterations[].expectation_pass_rate`: Pass rate from grading
-- `iterations[].grading_result`: "baseline", "won", "lost", or "tie"
-- `iterations[].is_current_best`: Whether this is the current best version
+**字段：**
+- `started_at`：改进流程启动时间的 ISO 时间戳
+- `skill_name`：正在改进的技能名
+- `current_best`：当前表现最好的版本标识
+- `iterations[].version`：版本标识（v0、v1、…）
+- `iterations[].parent`：本版本派生自哪个父版本
+- `iterations[].expectation_pass_rate`：评分得出的通过率
+- `iterations[].grading_result`："baseline"、"won"、"lost" 或 "tie"
+- `iterations[].is_current_best`：本版本是否是当前最佳版本
 
 ---
 
 ## grading.json
 
-Output from the grader agent. Located at `<run-dir>/grading.json`.
+由评分智能体输出。位于 `<run-dir>/grading.json`。
 
 ```json
 {
@@ -149,20 +149,20 @@ Output from the grader agent. Located at `<run-dir>/grading.json`.
 }
 ```
 
-**Fields:**
-- `expectations[]`: Graded expectations with evidence
-- `summary`: Aggregate pass/fail counts
-- `execution_metrics`: Tool usage and output size (from executor's metrics.json)
-- `timing`: Wall clock timing (from timing.json)
-- `claims`: Extracted and verified claims from the output
-- `user_notes_summary`: Issues flagged by the executor
-- `eval_feedback`: (optional) Improvement suggestions for the evals, only present when the grader identifies issues worth raising
+**字段：**
+- `expectations[]`：评过分的期望，附证据
+- `summary`：通过/失败的汇总计数
+- `execution_metrics`：工具使用与输出体量（来自 executor 的 metrics.json）
+- `timing`：墙钟时间（来自 timing.json）
+- `claims`：从输出中抽取并核实的论断
+- `user_notes_summary`：executor 标记的问题
+- `eval_feedback`：（可选）针对评估项的改进建议，仅当评分智能体发现值得提出的问题时才出现
 
 ---
 
 ## metrics.json
 
-Output from the executor agent. Located at `<run-dir>/outputs/metrics.json`.
+由执行智能体输出。位于 `<run-dir>/outputs/metrics.json`。
 
 ```json
 {
@@ -183,22 +183,22 @@ Output from the executor agent. Located at `<run-dir>/outputs/metrics.json`.
 }
 ```
 
-**Fields:**
-- `tool_calls`: Count per tool type
-- `total_tool_calls`: Sum of all tool calls
-- `total_steps`: Number of major execution steps
-- `files_created`: List of output files created
-- `errors_encountered`: Number of errors during execution
-- `output_chars`: Total character count of output files
-- `transcript_chars`: Character count of transcript
+**字段：**
+- `tool_calls`：按工具类型计数
+- `total_tool_calls`：所有工具调用之和
+- `total_steps`：主要执行步骤数
+- `files_created`：创建的输出文件列表
+- `errors_encountered`：执行期间的错误数
+- `output_chars`：输出文件的总字符数
+- `transcript_chars`：transcript 的字符数
 
 ---
 
 ## timing.json
 
-Wall clock timing for a run. Located at `<run-dir>/timing.json`.
+一次运行的墙钟计时。位于 `<run-dir>/timing.json`。
 
-**How to capture:** When a subagent task completes, the task notification includes `total_tokens` and `duration_ms`. Save these immediately — they are not persisted anywhere else and cannot be recovered after the fact.
+**如何记录：** 当一个子智能体任务结束时，任务通知中会包含 `total_tokens` 与 `duration_ms`。请立即保存——它们不会持久化到其他地方，事后无法恢复。
 
 ```json
 {
@@ -218,7 +218,7 @@ Wall clock timing for a run. Located at `<run-dir>/timing.json`.
 
 ## benchmark.json
 
-Output from Benchmark mode. Located at `benchmarks/<timestamp>/benchmark.json`.
+Benchmark 模式的输出。位于 `benchmarks/<timestamp>/benchmark.json`。
 
 ```json
 {
@@ -285,30 +285,30 @@ Output from Benchmark mode. Located at `benchmarks/<timestamp>/benchmark.json`.
 }
 ```
 
-**Fields:**
-- `metadata`: Information about the benchmark run
-  - `skill_name`: Name of the skill
-  - `timestamp`: When the benchmark was run
-  - `evals_run`: List of eval names or IDs
-  - `runs_per_configuration`: Number of runs per config (e.g. 3)
-- `runs[]`: Individual run results
-  - `eval_id`: Numeric eval identifier
-  - `eval_name`: Human-readable eval name (used as section header in the viewer)
-  - `configuration`: Must be `"with_skill"` or `"without_skill"` (the viewer uses this exact string for grouping and color coding)
-  - `run_number`: Integer run number (1, 2, 3...)
-  - `result`: Nested object with `pass_rate`, `passed`, `total`, `time_seconds`, `tokens`, `errors`
-- `run_summary`: Statistical aggregates per configuration
-  - `with_skill` / `without_skill`: Each contains `pass_rate`, `time_seconds`, `tokens` objects with `mean` and `stddev` fields
-  - `delta`: Difference strings like `"+0.50"`, `"+13.0"`, `"+1700"`
-- `notes`: Freeform observations from the analyzer
-
-**Important:** The viewer reads these field names exactly. Using `config` instead of `configuration`, or putting `pass_rate` at the top level of a run instead of nested under `result`, will cause the viewer to show empty/zero values. Always reference this schema when generating benchmark.json manually.
+**字段：**
+- `metadata`：本次 benchmark 运行的信息
+  - `skill_name`：技能名
+  - `timestamp`：benchmark 运行的时间
+  - `evals_run`：评估名或 ID 列表
+  - `runs_per_configuration`：每种配置下的运行次数（如 3）
+- `runs[]`：单次运行的结果
+  - `eval_id`：评估的数字标识
+  - `eval_name`：人类可读的评估名（在 viewer 中作为分节标题）
+  - `configuration`：必须为 `"with_skill"` 或 `"without_skill"`（viewer 用该字符串做分组和配色）
+  - `run_number`：整数运行编号（1、2、3…）
+  - `result`：嵌套对象，含 `pass_rate`、`passed`、`total`、`time_seconds`、`tokens`、`errors`
+- `run_summary`：按配置的统计聚合
+  - `with_skill` / `without_skill`：各包含 `pass_rate`、`time_seconds`、`tokens`，每项含 `mean` 与 `stddev`
+  - `delta`：差值字符串，如 `"+0.50"`、`"+13.0"`、`"+1700"`
+- `notes`：分析智能体的自由格式观察
+
+**重要：** viewer 严格按这些字段名读取。把 `config` 写成 `configuration` 之外的形式，或把 `pass_rate` 放在 run 的顶层而非嵌套于 `result` 之下，都会导致 viewer 显示为空或为零值。在手工生成 benchmark.json 时务必参照此 schema。
 
 ---
 
 ## comparison.json
 
-Output from blind comparator. Located at `<grading-dir>/comparison-N.json`.
+由盲比较器输出。位于 `<grading-dir>/comparison-N.json`。
 
 ```json
 {
@@ -383,7 +383,7 @@ Output from blind comparator. Located at `<grading-dir>/comparison-N.json`.
 
 ## analysis.json
 
-Output from post-hoc analyzer. Located at `<grading-dir>/analysis.json`.
+由事后分析器输出。位于 `<grading-dir>/analysis.json`。
 
 ```json
 {

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/ 下每篇文档：
@@ -188,3 +199,64 @@ Worker LLM 通过 SiliconFlow API 访问。连接信息在 `.env` 里：
 - `TIER1` 到 `TIER4` —— 各层级的模型名称
 
 各模型当前的能力与上下文窗口大小，见 `references/worker-llm-catalog.md`。
+
+## 两条访问路径：`worker_llm_call` 工具（优先）vs 直接 HTTP
+
+KC 自带一个 `worker_llm_call` 工具。能用就用 —— 引擎能看到每次调用，能统计成本和 token、做限流、并把数据进入审计。它支持批量模式：
+
+```
+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`（作为模板文件随包发布）
+
+对于一个 **独立运行** 的 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**。一种值得警惕的失败模式：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 超时设置（已知耗时长的命令）
+
+`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/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 环节。