kc-beta 0.7.5 → 0.8.1

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

@@ -15,6 +15,14 @@ This skill is the conductor's playbook for that decision. It's tagged `tier: met
 - **Entering rule_extraction.** Read the regulation, decompose into rules, then decide how those rules will be ordered and grouped before declaring the phase done. Coverage audit + chunk refs are downstream of these decisions.
 - **Entering skill_authoring.** TaskBoard is empty (engine no longer auto-populates per-rule tasks). Read the rule list from `describeState`, decide grouping + order, then call `TaskCreate` for each unit of work.
 - **Mid-run re-decomposition.** If the TaskBoard feels wrong (rules accumulating in the wrong order, an obviously-bundled pair across two tasks), stop adding work and re-decompose. The cost of pausing 5 minutes to re-plan is recovered within 2 rules of better-shaped work.
+- **Any phase with 3+ parallel sub-goals.** If you find yourself juggling multiple parallel sub-goals in working memory (3+ rules × docs, multiple deliverable-prep items in finalization, several QC batches in production_qc), drop them into the TaskBoard and work serially. v0.7.5 audits showed distillation + production_qc benefit from explicit tasks even when the registry didn't expose this skill there — v0.8 P2-E makes the skill available in every phase.
+
+## Quick rule: when does the TaskBoard belong?
+
+- Touching N+ rules or docs in parallel? → `TaskCreate` one task per rule/doc before starting.
+- Single 1-step request? → Skip; just do it.
+- Subagent internal coordination? → Skip; subagents don't get the TaskBoard.
+- Anything you'd otherwise need to remember "I'll come back to that"? → TaskCreate it now. Working memory loses partial completions over long turns.
 
 ## Locked principles
 
@@ -402,3 +410,29 @@ E2E history:
 - E2E #7 v071 neither DS nor GLM wrote PATTERNS.md, but GLM wrote 6 rich phase-completion logs and a comprehensive AGENT.md — the methodology WAS captured, just in different files. v0.7.2 blesses the broader principle: persist before you advance, format flexible.
 
 The engine's filesystem-derived milestones (Group A v0.7.0) verify coverage on disk regardless of how you split the work. The TaskBoard is your scratchpad; the disk is the contract; the persistence file is your project's memory.
+
+## Subagent batch work: rolling-window writes
+
+When you dispatch N subagents to do batch work (regression tests, batch verification, parallel rule processing), DO NOT have them write to a shared coordination file. v0.7.5 audits found subagents racing on `tasks.json` / `rules/catalog.json` / `output/results/summary.json` — one took the workspace lock for 5+ minutes while others waited silently.
+
+The right pattern: each subagent writes to its OWN file under a known prefix. The parent aggregates after all subagents finish.
+
+```
+sub_agents/
+  batch-001-regression/
+    output/results/v2_regression.json       # ❌ shared — races other subagents
+  batch-002-regression/
+    output/results/v2_regression.json       # ❌ same path, race
+
+# vs:
+
+output/
+  batch_regression_001.json                 # ✓ each subagent owns one file
+  batch_regression_002.json                 # ✓
+  batch_regression_003.json                 # ✓
+# Parent agent reads all batch_regression_*.json and writes the aggregate.
+```
+
+Engine signal: if you see `lock_blocked` events in events.jsonl during subagent work, that's the symptom. v0.8 P4-C added the event emission so the parent has visibility into contention before the subagent times out. If the pattern shows up, refactor to rolling-window writes.
+
+Don't write a "coordinate via file locking" subagent batch. The locking primitives exist for safety against accidental concurrent writes, not as a queue. Use the filesystem layout as the coordination mechanism.

package/template/skills/phase_skills.yaml

@@ -23,6 +23,7 @@ phases:
     always_loaded:
       - bootstrap-workspace
     available:
+      - work-decomposition       # v0.8 P2-E
       - auto-model-selection
       - data-sensibility
       - document-parsing
@@ -60,6 +61,7 @@ phases:
     always_loaded:
       - evolution-loop
     available:
+      - work-decomposition       # v0.8 P2-E
       - skill-authoring
       - skill-to-workflow
       - tree-processing
@@ -74,6 +76,7 @@ phases:
       - skill-to-workflow
       - evolution-loop
     available:
+      - work-decomposition       # v0.8 P2-E
       - skill-authoring
       - task-decomposition
       - corner-case-management
@@ -87,6 +90,7 @@ phases:
       - quality-control
       - evolution-loop
     available:
+      - work-decomposition       # v0.8 P2-E
       - skill-authoring
       - skill-to-workflow
       - confidence-system
@@ -100,6 +104,7 @@ phases:
     always_loaded:
       - quality-control
     available:
+      - work-decomposition       # v0.8 P2-E
       - skill-authoring
       - skill-to-workflow
       - dashboard-reporting

package/template/skills/zh/bootstrap-workspace/SKILL.md

@@ -134,6 +134,20 @@ versions.json           # 版本清单（工作空间根目录）
 
 在初始化阶段就和开发者用户讨论这个节奏 —— 生产侧文档输入节奏直接决定 skill 和工作流的写法（批处理 vs 流式、幂等性要求等等）。
 
+## 持续维护 AGENT.md 的项目记忆
+
+工作区根目录的 `AGENT.md` 有几段「项目记忆」（`Project`、`Decisions`、`Domain Notes`、`User Preferences`）。它们在 bootstrap 阶段是占位注释 —— 你的任务是随着工作推进往里填东西，让跨阶段或跨会话的人能直接读出上下文。
+
+应该写什么：
+- **Project**：语料身份（法规名称 + 范围）、语言、主规则与辅助规则、样本文档集组成。
+- **Decisions**：从代码看不出来的设计决定 —— 比如「非标 35% 限制是银行级合计而非单产品限制，所以单文档报告给 WARNING 而非 FAIL」「R02-06/R02-08 对季报判 NOT_APPLICABLE，依据是法规 §39」。
+- **Domain Notes**：值得显式记下来的法规或业务领域细节 —— 比如「PT/RT/LZ 是三种不同产品类型，披露模板不同」、术语消歧。
+- **User Preferences**：开发者用户希望你在本项目上的协作风格 —— 详略偏好、命名约定、什么时候问、什么时候直接做。
+
+更新 `AGENT.md` 的自然时机：开发者用户给出实质性澄清之后、阶段结束之后、发现会影响后续阶段的设计约束之后。不要等用户发 `/remember` —— 这份记忆是你自己维护的。
+
+未来会话恢复时会先读 `AGENT.md`。它越充实，开发者用户需要重复解释的内容就越少。
+
 ## 何时需要重新初始化
 
 以下情况需要重新运行本技能：

package/template/skills/zh/compliance-judgment/SKILL.md

@@ -4,27 +4,27 @@ tier: meta
 description: Determine whether extracted entities comply with verification rules. Use after entity extraction to make the pass/fail judgment for each rule on each document. Covers translating natural language rules into executable logic, choosing between Python calculation and LLM semantic judgment, and producing actionable comments on failures. Also use when designing the judgment step of a workflow or when a rule's judgment logic needs debugging.
 ---
 
-# Compliance Judgment
+# 合规判定
 
-Judgment is the moment of truth. You have the extracted entity. You have the rule. Do they comply? The answer must be clear, correct, and — when the answer is no — accompanied by a concise, actionable comment.
+判定是真相到来的时刻。你已经拿到抽取出来的实体，也有规则在手。它们是否合规？答案必须清晰、正确，并且——当答案为否时——附带一条简洁、可执行的说明。判定环节直接决定整个核查工作流的最终产出质量：抽取做得再细，如果判定阶段含糊或前后不一，下游的合规报告就难以使用。
 
-## The Judgment Spectrum
+## 判定光谱
 
-Rules range from trivially deterministic to deeply semantic. Pick the right tool for each rule.
+规则的复杂度跨度很大，从纯粹的确定性检查到深度语义判断都有。要为每条规则挑选合适的工具，不能一刀切。
 
-**Deterministic** — threshold checks, format validation, date arithmetic, cross-field consistency. Pure Python: free, instant, deterministic.
+**确定性判定** —— 阈值核查、格式校验、日期运算、跨字段一致性。纯 Python 就够：免费、即时、可复现，并且同一份输入永远给出同一份结果，便于审计与回溯。
 
-**Semantic** — adequacy, completeness, consistency, compliance with templates, detecting misleading or suggestive language, assessing whether a description is fair and balanced. These require language understanding — use worker LLM.
+**语义判定** —— 是否充分披露、是否完整、前后是否一致、是否符合模板、是否存在误导性或暗示性表述、描述是否公允平衡。这类判断需要语言理解能力，规则关键词法或模式匹配无法胜任，应直接使用 worker LLM 完成。
 
-Many real compliance rules require semantic judgment. "The risk disclosure must adequately describe the key risks" cannot be checked with regex or Python. "The contract description must not be misleading or suggestive" requires deep language understanding. Use worker LLM for these without hesitation.
+很多真实的合规规则都需要语义判定。"风险揭示必须充分描述主要风险"无法用正则或 Python 核查；"合同描述不得具有误导性或暗示性"需要深层的语言理解；"资产管理产品的宣传材料不得含有承诺收益的暗示"同样如此。这类场景应毫不犹豫地调用 worker LLM，强行用规则匹配反而会牺牲准确率。
 
-Some rules combine both: extract a number (deterministic), compare to threshold (deterministic), then assess the explanation if borderline (semantic). The mix depends on the rule.
+也有些规则会两者并用：先抽取数值（确定性），再与阈值比较（确定性），如果结果处于临界区间，再对其解释做语义评估。这种"Python 主跑、LLM 兜底"的组合往往是性价比最高的方案。具体如何组合，取决于规则本身。
 
-The right method is whatever achieves accuracy at lowest cost. Simple threshold checks don't need LLM. Semantic assessments don't benefit from Python. Most projects will have a mix — let the nature of each rule determine the method.
+正确的方法，是以最低成本达到所需准确率的那一个。简单的阈值核查不需要 LLM，语义评估也无法靠 Python 完成。多数项目都会两者混用——让每条规则的性质决定其判定方法，而不是反过来用方法去硬套规则。
 
-## Output Format
+## 输出格式
 
-For each rule × document combination:
+对每个"规则 × 文档"的组合：
 
 ```json
 {
@@ -38,26 +38,26 @@ For each rule × document combination:
 }
 ```
 
-**Result values:**
-- **pass**: Entity complies with the rule.
-- **fail**: Entity does not comply. Comment is required.
-- **missing**: The entity could not be found in the document. This is different from fail — the information is absent, not non-compliant.
-- **error**: Something went wrong during extraction or judgment (parsing failure, API error). Needs investigation.
-- **uncertain**: The judgment is ambiguous. May need human review.
+**结果取值：**
+- **pass**：实体符合规则要求。
+- **fail**：实体不符合规则要求。必须填写 comment。
+- **missing**：文档中未找到该实体。这与 fail 不同——信息缺失，并不代表违规。
+- **error**：抽取或判定过程出现异常（解析失败、API 错误等）。需要排查。
+- **uncertain**：判定结果存在歧义，可能需要人工复核。
 
-**Design exit criteria first:** Before writing judgment logic for a rule, define the exit conditions: what constitutes pass, what constitutes fail, what triggers escalation to human, how to handle empty/missing values, what value ranges are valid. Explicit exit criteria prevent ambiguous or inconsistent judgment.
+**先设计退出条件：** 在为一条规则编写判定逻辑前，先把退出条件定义清楚：什么算 pass、什么算 fail、什么情况下需要升级到人工、空值/缺失值如何处理、合法的取值范围是什么。显式的退出条件能避免判定模糊或前后不一致，也方便后续在进化循环中复盘判定逻辑的盲区。
 
-**Prompt design:** Design prompts for what you want, not against what you don't want. "Don't include reasoning" is less reliable than extracting the verdict from structured output in postprocessing. Use output filtering instead of prompt negation.
+**Prompt 设计：** 提示词要正向描述你想要什么，而不是反向描述你不想要什么。"不要包含推理过程"远不如在结构化输出里抽取判定结果可靠。模型对否定指令的遵循度普遍偏低，不如直接约束输出字段、再用后处理过滤把多余内容去掉。
 
-**Comments:**
-- Required only when result is `fail`. Skip for `pass` unless the developer user specifically requests pass comments.
-- Be concise and factual: "Capital adequacy ratio is 7.2%, below the regulatory minimum of 8.0%."
-- Do not editorialize: not "This is a serious violation that could result in penalties." Just state the facts.
-- Include the extracted value and the expected value/condition for context.
+**Comment 写法：**
+- 仅在 result 为 `fail` 时必须填写。`pass` 时不写，除非开发者用户明确要求记录通过项的说明。
+- 简洁、陈述事实："资本充足率为 7.2%，低于 8.0% 的监管最低要求。"
+- 不做评论性发挥：不要写"这是严重违规，可能招致处罚"。只陈述事实即可。
+- 在 comment 中给出抽取值和期望值/条件，便于读者理解上下文。
 
-### Lightweight Annotation Markup
+### 轻量标注语法
 
-For human review, token-efficient logging, and clean diff comparisons, results can also be expressed in compact text markup:
+为了便于人工复核、节省日志 token、做干净的 diff 比对，结果也可以用紧凑的文本标注形式表达：
 
 ```
 [PASS] capital_adequacy <- 12.5% (>= 8.0%) | conf:0.95 | src:p3-s2
@@ -65,19 +65,19 @@ For human review, token-efficient logging, and clean diff comparisons, results c
 [MISSING] collateral_value | conf:0.60 | note:Collateral valuation not found in document
 ```
 
-This format is losslessly convertible to and from the JSON format above. Use it when presenting results to the developer user for quick review, logging to evolution iteration summaries where token economy matters, or computing diffs between verification runs. See `references/output-format.md` for the full specification and conversion rules.
+这一格式与上面的 JSON 格式可无损互转。在以下场景使用：向开发者用户展示结果以便快速过目、写入进化迭代摘要等对 token 经济敏感的日志、在多次核查运行之间计算 diff 以发现回归。完整规范和转换规则参见 `references/output-format.md`。
 
-## Judgment Ordering
+## 判定执行顺序
 
-Some rules depend on the results of other rules:
-- Rule B might only apply if Rule A passes. "If the borrower is a new customer (Rule A), then additional documentation is required (Rule B)."
-- Rule C might use a value computed by Rule A. "The risk-weighted capital ratio (Rule A) determines the required reserve level (Rule C)."
+部分规则会依赖其他规则的结果：
+- 规则 B 可能只在规则 A 通过时才适用。"如果借款人是新客户（规则 A），则需要额外的文件资料（规则 B）。"
+- 规则 C 可能要复用规则 A 计算出的数值。"风险加权资本充足率（规则 A）决定了所需的准备金水平（规则 C）。"
 
-Map these dependencies in the rule catalog. Execute rules in dependency order. Pass upstream results as context to downstream rules.
+把这类依赖关系登记在规则目录中，最好以显式的依赖图形式维护。按依赖顺序执行规则，把上游规则的结果作为上下文传给下游规则，避免下游规则在缺少前置真值时拿到错误的输入。
 
-## Handling Edge Cases
+## 边界情况处理
 
-- **Null extraction**: The entity was not found. Default to `missing`, not `fail`. A missing value is an extraction problem, not a compliance problem.
-- **Multiple values**: The document contains the entity in multiple places with different values. Flag as `uncertain`. Report all found values.
-- **Conditional rules**: "If the loan exceeds 1M, then collateral is required." Check the condition before applying the rule. If the condition is not met, the rule does not apply — result is `pass` (or `not_applicable` if you add that category).
-- **Negative results**: Some rules check for absence. "The document must NOT contain guarantees to related parties." Searching for absence is harder than searching for presence. Be thorough in the search, then be confident in the negative.
+- **抽取为空**：实体未找到。默认归为 `missing`，而不是 `fail`。值缺失属于抽取问题，不是合规问题。
+- **多值情况**：文档在多处出现同一实体，但取值不一致。标记为 `uncertain`，并把所有找到的值连同各自的位置都报出来，便于人工复核时定位差异源头。
+- **条件规则**："如果贷款金额超过 100 万，则必须有担保。"先核查条件再套用规则。条件不成立时规则不适用——结果记为 `pass`（如果你额外引入了 `not_applicable` 类别，也可以使用）。
+- **否定型规则**：有些规则核查的是"不存在"。"文档中不得存在向关联方提供的担保。"搜索"不存在"比搜索"存在"难，因为要先证伪所有可能的命中位置才能下结论。先把搜索做彻底，再对否定结论保持信心。

package/template/skills/zh/document-chunking/SKILL.md

@@ -8,26 +8,33 @@ description: >
   verification chunking — for that, use tree-processing to design a tailored chunking script.
 ---
 
-# Document Chunking
+# 文档分块处理
 
-Split documents into pieces for downstream processing. This is the fast, cheap version — for batch processing of samples and inputs, not for precision verification workflows.
+将文档切分为若干块，供下游环节使用。本技能提供的是快速、低成本的版本，面向样本和输入文档的批量处理，不适用于追求精度的核查工作流。
 
-## Methods
+文档分块是 KC 工作流的常见前置步骤。原始文档往往超出单次调用的上下文窗口，或包含大量与当前任务无关的内容；恰当的分块既能控制 token 消耗，又能让后续的规则匹配、抽取、合规核查在更小、更聚焦的单元上进行。本技能给出三种成本最低、最易复用的分块策略，并说明各自的适用场景。
 
-**Page-level splits** — simplest. Each page is a chunk. Works for most document processing where you need to iterate over content.
+## 分块方法
 
-**Fixed-size chunks** — split by character/token count with overlap. Good for search and initial observation. Typical: 2000-4000 chars with 200 char overlap.
+**按页切分（Page-level splits）** — 最简单的方式。每页即为一个块。适用于大多数需要遍历文档内容的处理场景，例如初步观察样本、统计页数分布、或为每页生成摘要。这种方式不依赖文档内部结构，鲁棒性最高。
 
-**Header-based splits** — detect section headers and split at boundaries. Preserves semantic units. Use regex patterns for the document's header convention.
+**定长分块（Fixed-size chunks）** — 按字符数或 token 数切分，相邻块之间保留重叠区域。适合构建检索索引或进行初步观察。常见参数：每块 2000–4000 字符，相邻块之间保留 200 字符重叠。重叠的作用是避免边界处的语义被切断，导致后续匹配漏检。
 
-## When to Use What
+**按标题切分（Header-based splits）** — 识别章节标题，在标题边界处切分。这种方式能保留语义完整的章节单元，便于按条款、按章节进行规则核查。具体实现上，应根据目标文档的标题格式编写正则表达式，例如「第X条」「附录X」「X.X.X」等编号规则。
 
-Pick the simplest method that serves the task:
-- Batch document observation → page-level
-- Full-text search index → fixed-size with overlap
-- Section-level extraction → header-based
-- Table of contents available → parse TOC for structure
+## 何时使用哪一种
 
-## Relationship to tree-processing
+按任务复杂度选择最简单可行的方法：
 
-This skill is for quick, cheap chunking during exploration and batch processing. When you need production-grade chunking for verification workflows — where the chunking mechanism must be precise, consistent, and coded as a script — use `tree-processing` instead.
+- 批量观察样本文档 → 按页切分
+- 构建全文检索索引 → 定长分块加重叠
+- 按章节抽取条款或要点 → 按标题切分
+- 文档自带目录 → 直接解析目录得到结构
+
+选择策略时要兼顾下游消费方的需求。若下游是 `worker_llm_call` 进行规则抽取，块的粒度应与单条规则的承载单元对齐；若下游是关键词检索，则块越小越精确，但召回率可能下降，需在两者之间取得平衡。
+
+## 与 tree-processing 的关系
+
+本技能仅用于探索阶段和批量处理阶段的快速、低成本分块。当你需要为合规核查工作流构建生产级分块——即分块机制必须精确、稳定、可复现并以脚本形式落地时，应改用 `tree-processing` 技能。后者会根据文档的具体结构设计专门的分块脚本，并把切分逻辑沉淀为可重复运行的工件，便于在 production_qc 阶段对结果进行回溯和审计。
+
+两者的分工原则：本技能服务于「先看一眼数据」的快速判断，`tree-processing` 服务于「正式核查每一份文档」的工程化交付。在 KC 的 bootstrap 和 rule_extraction 阶段优先使用本技能；进入 skill_authoring 之后，若分块逻辑将被反复调用，应及时迁移到 `tree-processing`，并把对应的脚本和参数固化到技能目录下，避免每次运行得到不一致的切分结果，影响后续违规判定的可追溯性与置信度评估。

package/template/skills/zh/document-parsing/SKILL.md

@@ -4,99 +4,99 @@ tier: meta
 description: Parse source documents into machine-readable text with maximum fidelity. Use when processing any document in Samples/ or Input/ for the first time, when parsed text quality is poor, or when tables and charts need special handling. Covers multi-level parser selection from simple text extraction to OCR and vision models. Also use when a verification rule fails due to parsing issues (garbled text, missing tables, mangled layouts) and the parser needs to be upgraded for that document type.
 ---
 
-# Document Parsing
+# 文档解析
 
-Parsing is the foundation. If the text is wrong, everything downstream is wrong. But parsing is also a cost center — do not use expensive vision models when simple text extraction works.
+解析是整个工作流的根基。一旦文本提取错了,下游的所有规则判断、对账、合规核查都会跟着一起错,而且这种错误往往很难在后续环节里被发现——因为下游看到的只是"一段文字",并不知道这段文字其实已经丢失了关键数字或错位了表头。但解析同时也是一个明显的成本中心——能用简单文本抽取解决的事情,就不要轻易动用昂贵的视觉模型或重型 OCR 流水线,这只会拖慢整体节奏并消耗预算。
 
-## The Minimum Viable Parser Principle
+## 最小可用解析器原则
 
-Start with the simplest parser. Escalate only when necessary. This is not about saving money — it is about producing the most reliable output. Simple parsers have fewer failure modes.
+从最简单的解析器开始。只有在确有必要时才向上升级。这条原则并不是单纯为了省钱——更重要的是为了产出最可靠、最稳定的结果。简单的解析器失败模式更少、更可控,排查起来也更直接;一旦堆叠了过多的处理层,出问题时几乎无法定位究竟是哪一层引入了偏差,调试成本会指数级上升。优先选择能用就用的最低层级,把复杂性留给真正需要的文档类型。
 
-### Level 1: Direct Text Extraction
-- Tool: pdfjs-dist or similar PDF text extraction.
-- When: Well-formed digital PDFs with embedded text. This covers most modern business documents.
-- Output: Raw text with basic structure preserved (paragraphs, basic formatting).
-- Limitations: Tables may come out as messy text. Charts and images are invisible. Scanned PDFs produce nothing.
+### Level 1: 直接文本抽取
+- 工具:pdfjs-dist,或其它类似的 PDF 文本抽取库。
+- 适用场景:结构良好、内嵌文本的数字版 PDF。绝大多数现代商业文档(年报、招股说明书、合同、技术手册)都属于这一类。
+- 输出:保留基本结构(段落、基础格式)的原始文本。
+- 局限:表格往往会被拉平成杂乱的文字流,行列关系丢失。图表与图片完全不可见。扫描件 PDF 抽不出任何内容,加密 PDF 也会直接失败。
 
-### Level 2: Provider VLM (Vision Language Model)
-- Tool: VLM models from configured provider (VLM_TIER3 for cheap OCR, VLM_TIER1 for complex interpretation).
-- When: Level 1 produces garbled/incomplete text, scanned PDFs, image-based PDFs.
-- Output: Recognized text from page images, or structured interpretation (table as markdown, chart data as JSON).
-- Calling a provider VLM is more convenient and reliable than deploying local OCR. Use the cheapest VLM tier first; escalate to a more capable tier for complex tables/charts.
+### Level 2: Provider VLM(视觉语言模型)
+- 工具:已配置 provider 的 VLM 模型(VLM_TIER3 用于低成本 OCR,VLM_TIER1 用于复杂内容的语义解读)。
+- 适用场景:Level 1 产出乱码或文本残缺、扫描件 PDF、图像型 PDF,以及版式高度复杂、列布局或注脚混乱的报告。
+- 输出:从页面图像中识别出的文本,或更进一步的结构化解读结果(表格转成 markdown、图表数据转成 JSON)。
+- 调用 provider VLM 通常比自行部署本地 OCR 更便捷、更稳定,也省去了维护模型权重、显卡资源与推理环境的整套开销。优先使用最便宜的 VLM 层级把内容先拿到手并完成基本评估;只有遇到复杂的表格、密集的图表,或更低层级在测试样本上确实不够用时,再升级到更强的层级,而不是一开始就用旗舰模型把所有页面跑一遍。
 
-### Level 3: MineRU API or Local Tools (Optional)
-- Tool: MineRU API, pdfplumber, or locally deployed OCR — if configured.
-- When: Provider VLM is unavailable or too expensive for batch processing.
-- These are optional fallbacks. Most users will use Level 1 + Level 2.
+### Level 3: MineRU API 或本地工具(可选)
+- 工具:MineRU API、pdfplumber,或本地部署的 OCR——前提是已经配置好。
+- 适用场景:provider VLM 不可用,或批量处理时整体费用过高。
+- 这些属于可选的兜底方案,并不是默认路径。大多数用户使用 Level 1 + Level 2 的组合就已经足够覆盖日常需求。
 
-## Quality Detection
+## 质量检测
 
-How to know when to escalate:
+如何判断当前层级该不该向上升级:
 
-- **Low character count**: The document has pages but extracted text is very short. Likely a scanned PDF.
-- **Garbled text**: Unusual character sequences, encoding errors, or meaningless text patterns.
-- **Missing expected sections**: The table of contents mentions Chapter 5 but no Chapter 5 text was extracted.
-- **Table artifacts**: Columns of numbers without alignment, cell content mixed with headers, or table borders appearing as characters.
-- **Missing numbers in financial tables**: If a financial document's key metrics are not in the extracted text, the tables were probably not parsed.
+- **字符数过低**:文档有多页,但抽取出的文本极短。大概率是扫描件 PDF,或者是带有大量图像内容的 PDF。
+- **乱码文本**:出现异常的字符序列、明显的编码错误,或一眼看上去毫无意义的文字模式。
+- **预期章节缺失**:目录中提到了第 5 章,但抽取结果里完全没有第 5 章的正文,这通常意味着排版方式让文本抽取器卡住了。
+- **表格残骸**:成列的数字没有对齐、单元格内容与表头混在一起、表格边框被识别成无意义的字符流。
+- **财务表格中关键数字缺失**:如果一份财务文档的关键指标没有出现在抽取文本里,那大概率就是表格没有被正确解析,而不是它们本身就不存在。
 
-Write a quick quality check after parsing and before proceeding. If quality is insufficient, escalate to the next parser level.
+在解析之后、继续后续处理之前,写一个快速的质量检查脚本。如果质量不达标,就升级到下一层解析器,而不是带病往下走。
 
-### Parse Quality Score
+### 解析质量分数
 
-Compute a quality score (0.0 to 1.0) from weighted heuristics to make escalation decisions systematic rather than ad-hoc. A recommended starting framework:
+通过加权启发式规则计算一个 0.0 到 1.0 的质量分数,让升级决策有据可依,而不是单纯凭感觉做判断。一个推荐的初始框架如下:
 
-- **Character density** (weight ~0.3): actual character count / expected characters for the document's page count. A 10-page PDF that yields only 200 characters likely failed.
-- **Garble ratio** (weight ~0.2): fraction of characters that are common CJK/Latin vs control characters, unusual sequences, or encoding artifacts.
-- **Section completeness** (weight ~0.3): if the document has a table of contents, what fraction of TOC entries have matching content in the extracted text?
-- **Table integrity** (weight ~0.2): for financial documents, are key numeric values that should appear in tables actually present in the extracted text?
+- **字符密度**(权重约 0.3):实际字符数 / 该文档页数下的预期字符数。一份 10 页的 PDF 如果只抽出 200 个字符,基本可以直接判定为失败。
+- **乱码比例**(权重约 0.2):常见中英文字符占总字符的比例,相对于控制字符、异常序列或编码残留物的比例。
+- **章节完整度**(权重约 0.3):如果文档自带目录,目录条目中有多少比例能在抽取文本里找到对应内容?
+- **表格完整性**(权重约 0.2):对于财务类文档,本应出现在表格中的关键数值,是否真的出现在抽取文本中?
 
-**Escalation thresholds** (recommended defaults — adjust freely):
-- Score >= 0.7: accept this parser level, proceed to downstream processing.
-- Score 0.4-0.7: escalate to the next parser level, re-parse, re-score.
-- Score < 0.4: skip directly to Level 3 (OCR) or Level 4 (vision) depending on document characteristics.
+**升级阈值**(推荐默认值——可根据实际情况自由调整):
+- 分数 >= 0.7:接受当前解析器层级,进入下游处理。
+- 分数 0.4-0.7:升级到下一层解析器,重新解析,重新打分。
+- 分数 < 0.4:直接跳过中间层级,根据文档特征跳到 Level 3(OCR)或 Level 4(视觉模型)。
 
-**Lock-in**: once a parser level produces an acceptable score for a document type, record that level. Do not re-evaluate unless a downstream verification failure is traced back to a parsing issue.
+**层级锁定**:一旦某个解析器层级在某类文档上跑出可接受的分数,就把这个层级记录下来。除非下游某次验证失败被追溯到解析环节,否则不要再花时间重复评估,这能避免在已经稳定的链路上反复折腾。
 
-These weights, thresholds, and the scoring approach itself are starting points. The coding agent should design whatever quality assessment works for the specific document types at hand — a simple pass/fail heuristic may be sufficient for some scenarios; a more nuanced scoring function may be needed for others. The important pattern is: **measure quality → compare to threshold → decide whether to escalate**.
+上述权重、阈值,乃至打分思路本身,都只是一个起点。编码 agent 应当为手头的具体文档类型设计真正合适的质量评估方案——某些场景下简单的通过/失败启发式就完全够用,另一些场景则可能需要更精细的分项打分函数。真正关键的模式是:**度量质量 → 与阈值比较 → 决定是否升级**,而不是某一组具体的权重数字。
 
-This follows the same tier-transition pattern as model tier selection in `skill-to-workflow`: a quality/accuracy score drives the decision to stay, escalate, or skip tiers.
+这与 `skill-to-workflow` 中模型层级选择遵循的层级跃迁模式是一致的:都由一个质量或准确率分数,来驱动"停留在当前层级、升级到下一层级、还是跳过中间层直接进入更高层"这三种决策。
 
-## Table Handling
+## 表格处理
 
-Tables are critical in financial documents (balance sheets, ratio tables, compliance metrics). They deserve special attention:
+表格在财务文档中至关重要(资产负债表、比率表、合规指标表、监管披露表),它们承载了规则验证最常引用的数值,因此值得专门对待:
 
-1. **Detection**: Identify table regions. Look for grid patterns, consistent column spacing, or explicit table markers.
-2. **Extraction**: Extract cell-by-cell content. Preserve the row-column relationship.
-3. **Reconstruction**: Convert to a structured format (markdown table, JSON array of rows, or CSV).
-4. **Validation**: Spot-check that key values in the reconstructed table match what is visible in the document.
+1. **检测**:识别出页面中的表格区域。寻找规则的网格模式、稳定的列间距,或文档自身的显式表格标记。
+2. **抽取**:逐单元格提取内容。严格保留行列对应关系,不要把多列合并成一行长字符串。
+3. **重建**:把抽取结果转换成结构化格式(markdown 表格、JSON 行数组,或 CSV),便于下游程序消费。
+4. **校验**:对重建后的表格抽查若干关键单元格,确认其数值与文档中肉眼可见的值一致,以此尽早发现错位或漏行。
 
-When the standard parser fails on tables, try the vision model approach: send the table image (cropped from the PDF page) to a vision model and ask it to produce a markdown table.
+如果标准解析器在表格上失手,可以尝试视觉模型路线:把表格图像(从 PDF 页面上精确裁剪出来)发送给视觉模型,让它直接产出一个 markdown 表格。这种方式对带合并单元格、跨页延续的复杂表格尤其有效。
 
-## Chart Handling
+## 图表处理
 
-Charts (bar charts, line charts, pie charts) occasionally contain data needed for verification:
+图表(柱状图、折线图、饼图、雷达图)偶尔也会承载验证所需的数据:
 
-- Extract the chart image from the document.
-- Send to a vision model with a prompt: "Extract the data points, labels, and values from this chart. Return as a JSON array."
-- Validate the extracted data against any nearby text or table that might contain the same numbers.
+- 从文档中抽出图表图像,保留必要的坐标轴与图例区域。
+- 发送给视觉模型,prompt 类似:"Extract the data points, labels, and values from this chart. Return as a JSON array."
+- 用图表附近的文字段落或表格(它们经常会以另一种形式呈现相同的数字)对抽取结果进行交叉校验。
 
-This is expensive. Only do it when a verification rule specifically requires data from a chart and that data is not available in text elsewhere in the document.
+这一步代价相对昂贵,而且图表识别的准确率天然低于纯文本抽取。只有当某条验证规则明确要求使用图表中的数据,且该数据无法从文档其他文字或表格中获得时,才动用它,而不是默认对所有图表都跑一遍视觉模型。优先尝试在邻近文字中找到相同的数字,这通常是更经济也更可信的路径。
 
-## Output Format
+## 输出格式
 
-Parsed documents should be saved as clean markdown:
+解析后的文档应当保存为干净、规范的 markdown:
 
-- Preserve the document's heading hierarchy (# Chapter, ## Section, ### Subsection).
-- Preserve lists, numbered or bulleted.
-- Convert tables to markdown table format.
-- Note page boundaries if relevant (some rules reference specific pages).
-- Strip noise: headers, footers, page numbers, watermarks (unless a rule specifically checks for them).
+- 保留文档原有的标题层级(# 章、## 节、### 小节),不要把所有标题压平到同一层。
+- 保留列表结构,无论是有序列表还是无序列表。
+- 把表格转换成 markdown 表格格式,而不是用纯文字描述。
+- 在有需要时标注页边界(部分规则会引用具体页码,这种位置信息必须保留)。
+- 剔除噪声:页眉、页脚、页码、水印——除非某条规则专门要检查它们。
 
-Save parsed output alongside the original document for reuse across rules.
+把解析输出与原始文档保存在一起,方便跨规则、跨技能复用同一份解析结果。
 
-## Caching
+## 缓存
 
-Parsing is expensive (especially Level 3-4). Cache parsed output:
-- Store the parsed markdown alongside the original file.
-- Track which parser level produced it.
-- Re-parse only when: the original file changes, a rule requires higher-quality parsing than what is cached, or a verification failure is traced back to a parsing issue.
+解析这一步本身很昂贵(尤其是 Level 3-4),在迭代规则、反复跑验证流程时尤其明显。务必把解析结果缓存下来,而不是每次都从原始 PDF 重新跑一遍:
+- 把解析后的 markdown 与原始文件保存在同一目录,命名约定要稳定、可预测,便于程序化查找。
+- 同时记录是哪一层解析器产出的,以及该层级当时拿到的质量分数,方便日后回溯与对比。
+- 仅在以下情况重新解析:原始文件发生变化、某条规则要求比当前缓存更高质量的解析结果,或某次验证失败被追溯到了解析问题本身。