kc-beta 0.2.1 → 0.3.0

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

@@ -3,274 +3,112 @@ name: entity-extraction
 description: Extract specific entities, values, and text segments from documents as required by verification rules. Use after tree processing has located the relevant section, when a rule needs a specific number, date, name, amount, clause, or any domain-specific entity extracted. Covers extraction method selection (regex vs LLM), schema design, postprocessing, and confidence annotation. Also use when designing the extraction step of a workflow for worker LLMs.
 ---
 
-# 实体提取
+# Entity Extraction
 
-实体是核查的对象。一个数字、一个日期、一个金额、一个比率、一段条款。规则告诉你要检查什么，实体提取是你把这个"什么"从文档中拿出来的过程。
+An entity is the thing you need to check. A number, a date, a name, a clause, a percentage, a statement. The rule says what to check; extraction is how you get the value to check it against.
 
-## 实体是什么
+## Extraction Type Taxonomy
 
-在文档核查语境下，实体不是 NLP 教科书中的"命名实体"。实体是**规则所关心的任何可提取信息片段**：
+Different extraction scenarios call for different approaches:
 
-- 资本充足率：12.5%
-- 贷款到期日：2025年6月30日
-- 借款人名称：某某股份有限公司
-- 贷款金额：人民币伍仟万元整
-- 担保方式：抵押+保证
-- 风险披露段落（整段文本）
-- 签字页是否存在（布尔值）
+### Single Entity from Single Section
+The simplest case. One rule needs one value from one place.
+- Example: "Extract the capital adequacy ratio from the Key Metrics table."
+- Approach: Locate the section, apply regex or LLM extraction.
 
-实体的类型和粒度由规则决定，不是预先定义的。
+### Multiple Entities from Single Section
+One rule needs several related values from the same place.
+- Example: "Extract the borrower's name, loan amount, interest rate, and maturity date from the loan agreement summary."
+- Approach: Design a single extraction call that returns all values. More efficient than multiple calls.
 
-## 提取类型分类
+### Single Entity from Multiple Sections
+One value is scattered across multiple places, or needs cross-referencing.
+- Example: "Extract the total collateral value, which may be listed in the collateral section or in Appendix A."
+- Approach: Collect content from all relevant sections, then extract. Note which source the value came from.
 
-不同的提取场景需要不同的策略：
+### Entity from Full Document
+The value could be anywhere, or the rule applies to the document as a whole.
+- Example: "Check whether the document contains a valid signature page."
+- Approach: For the coding agent, scan the full document. For worker LLM workflows, design a two-pass approach: first pass identifies the location, second pass extracts the value.
 
-### 单章单实体
+## Method Selection
 
-最简单的情况。一条规则需要从一个章节中提取一个值。
+Extraction method selection is a cost-accuracy search. The goal is finding the cheapest method that meets the accuracy threshold. Regex is the smallest, cheapest "model" — zero cost, instant, deterministic. Worker LLM is more capable but costs tokens and time. Any search strategy is valid: try the cheapest first and escalate, try the most capable first and downgrade, bisect, or jump directly to a known-good method based on past experience in AGENT.md.
 
-- **示例**："从关键指标表中提取资本充足率。"
-- **方法**：定位到章节，用正则或 LLM 提取。
-- **这是最常见的情况**，优先为此场景优化工作流。
+### Available Methods
 
-### 单章多实体
+**Regex / Python** — Cost: zero. Speed: instant. Deterministic.
+Works well for: dates, monetary amounts, percentages, identifiers, fixed phrases, any value with a predictable format.
 
-一条规则需要从同一位置提取若干相关值。
+**Worker LLM** — Cost: API tokens. Speed: seconds. Semantic understanding.
+Works well for: contextual interpretation, conditional values, semantic matching, ambiguous structures, suggestive or misleading language detection, table interpretation, anything requiring understanding rather than pattern matching.
 
-- **示例**："从贷款协议摘要中提取借款人名称、贷款金额、利率、到期日。"
-- **方法**：设计一次提取调用返回所有值。比分别调用更高效，也更容易保持值之间的关系一致性。
-- **注意**：如果用 LLM 提取，在提示词中一次性要求所有字段。如果用正则，对同一文本段逐个匹配。
+Many real verification tasks require semantic understanding — "is this description misleading?", "does this clause adequately disclose risk?", "is this guarantor's business description consistent with their stated industry?" — regex cannot handle these. Use worker LLM without hesitation for such tasks.
 
-### 多章单实体
+### The Search
 
-一个值分散在多个位置，或需要交叉核对。
+If a method's results fall below the accuracy threshold, try a different method or a more capable model. If regex works and meets accuracy — keep it, it's free. If regex produces results below threshold, escalate to worker LLM. If a cheap worker LLM isn't accurate enough, try a more capable tier. Record what works for each extraction type in AGENT.md for future reference.
 
-- **示例**："提取总担保物价值，可能出现在担保章节或附录 A 中。"
-- **方法**：从所有相关章节收集内容，然后统一提取。记录值的来源位置——如果同一实体在不同位置出现不同值，这本身就是一个需要判定的问题。
-- **金融文档中的典型场景**：净利润可能出现在"主要财务指标"、"利润表"、"董事长致辞"等多处。
+## Schema Design
 
-### 全文实体
-
-值可能在任何位置，或规则适用于整份文档。
-
-- **示例**："检查文档是否包含有效的签字页。"
-- **方法**：
-  - 编程智能体执行时：扫描全文。
-  - Worker LLM（执行模型）工作流：设计两遍扫描——第一遍定位候选位置，第二遍精确提取。
-- **成本较高**，尽量避免。如果能通过文档树缩小范围（签字页通常在文末），优先使用树导航。
-
-## 方法选择
-
-### 正则/Python（成本：零，速度：瞬时）
-
-当实体具有可预测的格式时，优先使用正则表达式。
-
-**日期提取**：
-```python
-# 中文日期格式
-r'\d{4}年\d{1,2}月\d{1,2}日'
-# ISO 格式
-r'\d{4}[-/]\d{1,2}[-/]\d{1,2}'
-# 混合格式
-r'\d{4}年?\d{1,2}月?\d{1,2}日?'
-```
-
-**金额提取**：
-```python
-# 数字金额
-r'[\d,]+\.?\d*\s*(?:元|万元|亿元|百万元)'
-# 大写金额
-r'人民币[壹贰叁肆伍陆柒捌玖拾佰仟万亿零]+(?:元整?)'
-# 带币种标记
-r'(?:人民币|美元|港币|EUR|USD)\s*[\d,.]+\s*(?:元|万元|亿元)?'
-```
-
-**百分比提取**：
-```python
-# 标准百分比
-r'\d+\.?\d*\s*[%％]'
-# 基点表示
-r'\d+\.?\d*\s*(?:个基点|BP|bps)'
-# 千分比（部分监管指标使用）
-r'\d+\.?\d*\s*[‰]'
-```
-
-**监管编号提取**：
-```python
-# 银保监会发文编号
-r'银保监发〔\d{4}〕\d+号'
-# 证监会发文编号
-r'证监[a-z]*〔\d{4}〕\d+号'
-# 统一社会信用代码
-r'[0-9A-Z]{18}'
-```
-
-好的正则表达式比好的 LLM 提示词更适合结构化值——更快、确定性、免费。在样本文档上构建和测试正则，确认覆盖率后再部署。
-
-### LLM 提取（成本：API 调用，速度：秒级）
-
-当实体需要语义理解时使用 LLM：
-
-- **上下文相关的实体**："担保人的主要经营业务"——需要理解谁是担保人、哪段文字描述了其业务。
-- **条件性值**："含调整后的利率"——需要理解什么构成调整。
-- **语义匹配**："充分的风险披露"——需要判断哪些文本构成风险披露。
-- **不规则表格**：表格结构不统一，正则无法可靠提取单元格。
-- **隐含信息**："是否提及了流动性风险"——可能不是一个明确的章节标题，而是散布在多处的讨论。
-
-设计 LLM 提取提示词的要点：
-1. 包含缩窄后的上下文（来自文档树处理）。
-2. 精确说明要提取什么，不要模糊。
-3. 定义输出格式（JSON，含命名字段）。
-4. 如果提取对象不直观，提供一个示例。
-5. 明确要求：如果找不到，返回 null 而不是猜测。
-
-### 混合方法
-
-最常用的实际策略：
-
-1. 先用正则提取候选值（快速，捕获明显匹配）。
-2. 如果正则找到高置信度匹配，直接使用。
-3. 如果正则失败或不确定，回退到 LLM 提取。
-4. 在置信度要求高的场景，用 LLM 验证正则结果。
-
-混合方法兼顾了成本和准确率。90% 的提取用正则完成（免费），10% 的困难情况用 LLM 兜底。
-
-## 数据模式设计
-
-为每次提取定义期望输出。保持简单，按需扩展（JIT 原则）：
+Define the expected output for each extraction. Keep it simple and JIT:
 
 ```json
 {
   "entity_name": "capital_adequacy_ratio",
   "value": 12.5,
   "unit": "%",
-  "raw_text": "本行资本充足率为12.50%",
-  "source_location": "第二章 > 第一节 主要财务指标 > 表1 第3行",
-  "confidence": 0.93,
+  "raw_text": "资本充足率为12.5%",
+  "source_location": "Chapter 2, Table 1, Row 3",
+  "confidence": 0.95,
   "extraction_method": "regex"
 }
 ```
 
-模式应包含：
-- **value**：提取的值，经标准化处理。数字用数字类型，日期用 ISO 格式，文本保持原文。
-- **unit**：适用时注明单位（%、元、天、个基点等）。单位错误是常见的核查失败原因。
-- **raw_text**：值在原文中的原始文本片段。这是判定步骤的证据，也是人工审查的依据。
-- **source_location**：在文档中的位置（章节路径、表格坐标、页码）。
-- **confidence**：提取置信度（参见下方"置信度标注"和 `confidence-system` 技能）。
-- **extraction_method**：使用的方法（regex、python、LLM-TIER2、LLM-TIER3 等）。对演进循环有用。
-
-不要过度设计模式。在测试过程中发现需要新字段时再添加。
-
-## 后处理
-
-原始提取值通常需要标准化才能用于判定：
-
-### 中文数字转换
-```python
-# 中文大写 → 数字
-"壹仟贰佰叁拾肆万伍仟陆佰柒拾捌元" → 12345678
-"叁拾伍亿零贰仟万元" → 3520000000
-
-# 中文小写 → 数字
-"一百二十万" → 1200000
-"三千五百" → 3500
-"十二点五" → 12.5
-```
-
-这在金融文档中极为常见。贷款合同几乎总是用大写数字书写金额。建一个可靠的中文数字转换函数放在工具库中。
-
-### 日期标准化
-```python
-"2024年3月15日" → "2024-03-15"
-"二〇二四年三月十五日" → "2024-03-15"
-"2024/03/15" → "2024-03-15"
-"2024.3.15" → "2024-03-15"
-```
-
-### 单位换算
-```python
-# 统一到基本单位进行比较
-"1,500万元" → 15000000 元
-"3.5亿元" → 350000000 元
-"150个基点" → 1.5%
-"0.125" → 12.5%  # 小数表示的百分比
-```
-
-单位换算要特别小心。"万元"和"元"差四个数量级——一个换算错误可能让 1500 万的贷款变成 1500 元，核查结果完全失真。在后处理代码中加入合理性检查。
-
-### 格式清理
-```python
-# 去除千分位分隔符
-"12,345,678" → "12345678"
-# 去除多余空格和换行
-"资本充足率\n为 12.5 %" → "资本充足率为12.5%"
-# 全角转半角
-"１２．５％" → "12.5%"
-```
+The schema should capture:
+- **value**: The extracted value, normalized.
+- **unit**: If applicable (%, 元, days, etc.).
+- **raw_text**: The original text fragment where the value was found. This is evidence for the judgment step.
+- **source_location**: Where in the document the value was found.
+- **confidence**: How sure you are (see `confidence-system`).
+- **extraction_method**: What extracted it (regex, LLM-TIER2, etc.).
 
-将后处理函数写成独立的 Python 工具，放在规则技能的 `scripts/` 目录中。它们是确定性的、可复用的。
+Do not over-engineer the schema. Add fields as needed during testing.
 
-## 置信度标注
+## Postprocessing
 
-每次提取都应附带一个置信度估计。这不是模型的自信程度，而是对提取结果正确概率的预判：
+Raw extracted values often need normalization:
 
-### 初始先验值
+- **Chinese numerals → digits**: 一百二十万 → 1200000
+- **Date standardization**: 2024年3月15日 → 2024-03-15
+- **Unit conversion**: 万元 → multiply by 10000 if comparing to a threshold in 元.
+- **Whitespace and noise removal**: Strip extra spaces, line breaks, formatting artifacts.
+- **Percentage normalization**: 0.125 → 12.5% or vice versa, depending on what the rule expects.
 
-| 提取方法 | 置信度范围 | 说明 |
-|---------|-----------|------|
-| 正则匹配+格式验证 | 0.90-0.95 | 格式对了，值大概率对 |
-| LLM 提取，高确定性 | 0.80-0.85 | 模型明确找到了值 |
-| LLM 提取，有歧义 | 0.60-0.75 | 模型不太确定或有多个候选 |
-| 回退/推断值 | 0.40-0.60 | 非直接提取，有猜测成分 |
-| 未找到值 | 0.0 | 标记为 MISSING |
+Build postprocessing as Python functions in the rule skill's `scripts/` directory. They are deterministic and reusable.
 
-这些是起始值。通过实际的质量控制审查校准（参见 `confidence-system`）。
+## Confidence Annotation
 
-### 置信度调整因素
+Every extraction should carry a confidence estimate:
 
-- **原文验证**：提取的值能在原文中找到完全匹配 → 置信度 +0.05。
-- **多处一致**：同一值在文档多处出现且一致 → 置信度 +0.05。
-- **格式异常**：值的格式与预期不符（如百分比用小数表示）→ 置信度 -0.10。
-- **边缘案例匹配**：文档匹配已知边缘案例模式 → 置信度 -0.10。
+- **Regex match, validated format**: 0.90-0.95
+- **LLM extraction, high certainty**: 0.80-0.85
+- **LLM extraction, some ambiguity**: 0.60-0.75
+- **Fallback or inferred value**: 0.40-0.60
+- **No value found**: 0.0 (flag as MISSING)
 
-## 适配 Worker LLM 上下文窗口
+These are starting points. Calibrate based on actual accuracy (see `confidence-system`).
 
-为 Worker LLM 工作流设计提取步骤时，做好 token 预算：
+## Prompt Design: Ask For What You Want
 
-1. **计算提示词大小**：系统提示 + 提取指令 + 输出格式说明 + 示例 = N tokens。
-2. **可用文档内容空间** = 模型上下文窗口 - N - 回复预留。
-3. 如果章节内容超出可用空间，通过文档树进一步缩小范围。
-4. 始终为模型回复留出足够空间（至少 1K-2K tokens）。
-5. **用实际模型测试**——编程智能体的 token 计数可能与Worker LLM 的分词器不同。中文文本在不同分词器间的 token 数差异可达 30%。
+Design prompts for what you want, not against what you don't want. "Don't include explanations" in a prompt is less reliable than stripping non-JSON text from the output in postprocessing. If you need to tell the LLM not to do something, use output filtering instead of prompt negation.
 
-### Worker LLM 提取提示词模板
+## Fitting Worker LLM Context
 
-```
-你是一个金融文档实体提取助手。
-
-任务：从以下文档内容中提取指定实体。
-
-要提取的实体：{entity_description}
-
-文档位置：{document_path}
-
-文档内容：
----
-{section_content}
----
-
-输出格式（JSON）：
-{
-  "value": <提取的值>,
-  "unit": "<单位>",
-  "raw_text": "<原文中包含该值的完整句子>",
-  "found": true/false
-}
-
-注意：
-- 如果找不到该实体，将 found 设为 false，value 设为 null。
-- 不要猜测或推断，只提取文档中明确存在的信息。
-- raw_text 必须是文档中的原文，不要改写。
-```
+When designing extraction for worker LLM workflows:
 
-根据实际测试结果调整提示词。不同的 Worker LLM 对提示词格式的敏感度不同。
+1. Calculate the prompt size: system prompt + instructions + examples + output format = N tokens.
+2. Available context for document content = model's context window - N.
+3. If the section exceeds available context, narrow further via tree processing.
+4. Always leave room for the model's response.
+5. Test with the actual model to verify the context fits — token counts from the coding agent may differ from the worker LLM's tokenizer.

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

@@ -1,233 +1,121 @@
 ---
 name: tree-processing
-description: Build hierarchical document trees and navigate to specific chapters or sections required by verification rules. Use when a rule targets a specific part of a document, when documents are too long for a single LLM context window, or when you need to find where a specific entity lives within a large document. Implements the "onion peeler" approach for chunking. Also use for documents over 100 pages where full-document processing is impractical.
+description: >
+  Design production-grade document chunking mechanisms for verification workflows. Use when
+  building the chunking step of a workflow that will run repeatedly on many documents.
+  The approach: observe sample documents, find structural patterns, write a chunking script
+  in code, that script runs in production. Also use for navigating large documents via
+  hierarchical structure when a rule targets a specific section.
+  For quick, cheap batch chunking during exploration, use document-chunking instead.
 ---
 
-# 文档树处理
+# 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.
 
-## 为什么需要文档树
+## Production Chunking Methodology
 
-两个原因：
+For verification workflows that process many documents, the chunking mechanism must be precise, consistent, and fast. The approach:
 
-1. **规则有作用域。** "第五章风险披露中应包含……"——你需要找到第五章，而不是通读 800 页年报。规则指向文档的特定位置，你的提取和判定也必须在这个位置上进行。
+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.
 
-2. **Worker LLM（执行模型）有上下文限制。** 一个 16K-32K 上下文窗口放不下一份完整的银行年报。你必须把内容缩窄到相关章节，才能喂给 Worker LLM。
+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.
 
-文档树同时解决这两个问题：它告诉你内容在哪里，让你只提取需要的部分。
+## 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.
 
-在构建解析器之前，先浏览若干样本文档，找出结构规律。关注以下模式：
+The tree structure solves both: it tells you WHERE things are, and lets you extract JUST what you need.
 
-- **标题格式**：
-  - 中文监管文档常见：`第一章`、`第二章`……`第一节`、`第二节`……
-  - 中文金融报告常见：`一、`、`二、`……`（一）`、`（二）`……`1.`、`2.`……
-  - 英文文档：`Chapter X`、`Part X`、`Section X.X`
-  - 编号体系：`1.1.2`、`Article 3`、`（a）（i）`
-- **视觉标记**：加粗文本、字号变大、分页符、横线分隔。这些在解析后的文本中可能表现为空行或特殊格式。
-- **目录（TOC）**：大多数正式金融文档都有目录。目录就是文档自己提供的树结构，包含标题和页码。
+## Building the Tree
 
-在这一步多花时间。你发现的模式决定了后续的解析器是一个简单的正则表达式还是一个复杂的解析流程。
+### Step 1: Discover the Structure
 
-### 第二步：选择解析器
+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.
 
-用正则表达式构建分割器。金融文档中常见的中文标题模式：
+Spend time here. The patterns you find determine whether the tree builder is a simple regex or a complex parser.
 
-```python
-# 章标题：第一章、第二章……
-r'^第[一二三四五六七八九十百千]+章\s'
+### Step 2: Choose the Parser
 
-# 节标题：第一节、第二节……
-r'^第[一二三四五六七八九十百千]+节\s'
+**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.
 
-# 编号标题：一、二、三……
-r'^[一二三四五六七八九十]+、'
+**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.
 
-# 子编号：（一）（二）（三）……
-r'^（[一二三四五六七八九十]+）'
+**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.
 
-# 数字编号：1.1、1.2.3……
-r'^\d+\.\d+(\.\d+)*\s'
-```
-
-正则分割器速度快、结果确定、可靠性高。能用正则就用正则。
-
-**如果模式不一致或缺失**：
-
-使用 LLM 辅助的楔入式分割（参见 `rule-extraction/references/chunking-strategies.md`，其中详述了滚动上下文窗口、K-token 引用、Levenshtein 模糊匹配等完整算法）。这种方法速度慢、消耗 API 调用，但能处理结构不清晰的文档。滚动窗口机制意味着即使非常大的无结构叶节点也可以增量分块。
-
-**如果文档有目录**：
-
-优先解析目录。目录直接给出了树结构和页码，省去了你自己构建的工作：
-- 从目录中提取标题文本、层级关系、页码。
-- 用目录得到的结构去分割文档正文。
-- 验证目录与正文是否一致（偶尔会有目录与实际内容不符的情况）。
-
-### 第三步：构建树
-
-文档树是一个简单的嵌套结构：
-
-```
-年度报告
-├── 第一章 公司概况（第1-20页）
-│   ├── 第一节 基本信息
-│   └── 第二节 主要业务
-├── 第二章 财务数据（第21-80页）
-│   ├── 第一节 主要财务指标
-│   │   ├── 一、资本充足率
-│   │   └── 二、资产质量指标
-│   ├── 第二节 资产负债表
-│   └── 第三节 利润表
-├── 第三章 风险管理（第81-150页）
-│   ├── 第一节 信用风险
-│   ├── 第二节 市场风险
-│   └── 第三节 操作风险
-└── 附录
-    ├── 附录一 关联交易明细
-    └── 附录二 监管指标计算说明
-```
-
-每个节点存储：
-- **标题文本**：节点的标题。
-- **层级**：在树中的深度（章=1，节=2，条目=3……）。
-- **位置**：在解析文本中的起止位置（字符偏移或行号）。
-- **内容大小**：该节点内容的 token 数或字符数。这决定了能否直接喂给 Worker LLM。
-
-### 第四步：使用树
-
-当规则说"检查风险披露章节"：
-
-1. **搜索树节点**：将规则的作用域描述与节点标题匹配。
-   - 精确匹配："第三章"→ 找到标题为"第三章 风险管理"的节点。
-   - 语义匹配："风险披露相关内容"→ 需要模糊匹配或 LLM 分类，找到内容与风险披露相关的节点。
-   - 关键词匹配：对标题做关键词搜索，如"风险"+"披露"。
-
-2. **提取内容**：获取该节点（及其子节点）的完整内容。
-
-3. **检查大小**：内容是否能放进 Worker LLM 的上下文窗口？
-   - 能放下 → 直接使用。
-   - 放不下 → 下探到子节点，找到规则所需的具体小节。
-
-## 洋葱剥皮法
-
-这是处理大型文档的核心策略：像剥洋葱一样，一层一层缩小范围，仅在超出大小限制时才进行下一层分割。
-
-### 具体操作
-
-1. **最外层**：整份文档。如果文档在上下文窗口内（罕见），直接使用。
-2. **第一层剥离**：按最高级标题（章）分割。大多数章节在 16K-32K 范围内。
-3. **第二层剥离**：如果某章仍然过大，按次级标题（节）分割。
-4. **继续剥离**：必要时继续，但通常两到三层就够了。
-
-关键原则：**不要预先把文档切碎**。只在某个节点太大时才继续分割。过度分割会丢失上下文——一个段落脱离了它所在的章节，可能会被误解。
+### Step 3: Build the Tree
 
-### 保留上下文链
+The tree is a simple nested structure:
 
-无论下探到多深，始终在提取的内容前附加父节点链：
-
-```
-[文档标题] > 第二章 财务数据 > 第一节 主要财务指标 > 一、资本充足率
-
-（以下是该节内容）
-```
-
-这让 Worker LLM 知道当前内容在文档中的位置，避免脱离上下文的误判。
-
-## 中文文档结构模式
-
-不同类型的金融文档有不同的结构习惯：
-
-### 监管文件（银保监会、证监会发文）
-```
-第一章 总则
-  第一条、第二条、第三条……
-第二章 ……
-  第X条……
-附则
-```
-特点：条文编号连续，跨章不重置。
-
-### 上市公司年度报告
 ```
-第一节 重要提示、目录和释义
-第二节 公司简介和主要财务指标
-第三节 管理层讨论与分析
-……
-第十二节 备查文件目录
+Document
+├── Part I: General Provisions
+│   ├── Chapter 1: Definitions (pages 1-15)
+│   └── Chapter 2: Scope (pages 16-22)
+├── Part II: Capital Requirements
+│   ├── Chapter 3: Minimum Capital (pages 23-45)
+│   │   ├── Section 3.1: Tier 1 Capital
+│   │   └── Section 3.2: Tier 2 Capital
+│   └── Chapter 4: Risk Weighting (pages 46-78)
+└── Part III: Disclosure
+    └── Chapter 5: Risk Disclosure (pages 79-120)
 ```
-特点：以"节"为最高级别，内部用"一、二、三"编号。
 
-### 银行资本充足率报告
-```
-一、核心概况
-二、资本充足率
-  （一）资本构成
-  （二）风险加权资产
-三、杠杆率
-……
-```
-特点：用中文数字编号，层级较浅。
-
-### 贷款合同
-```
-第一条 借款金额
-第二条 借款期限
-第三条 借款利率
-……
-第X条 违约责任
-```
-特点：扁平结构，每条独立。
-
-根据文档类型选择对应的正则模式。
+Each node stores: the header text, the level, the start/end positions in the document, and the content size (in tokens or characters).
 
-## 全文→章节→实体 的渐窄管道
+### Step 4: Use the Tree
 
-这是从文档到可核查数据的标准漏斗：
+Given a rule that says "check the risk disclosure section":
 
-1. **全文层**：用文档树了解整体结构。知道什么在哪里。
-2. **章节层**：导航到规则指向的具体章节。提取其内容。
-3. **实体层**：在章节内容中，使用 `entity-extraction` 技能的方法提取具体实体（数字、日期、条款文本等）。
+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.
 
-对于 16K-32K 上下文窗口的 Worker LLM：
-- 章节内容 + 提取提示词 + 输出格式说明 = 必须在上下文窗口内。
-- 留出足够空间给模型的回复（通常 1K-2K token）。
-- 如果章节仍然过大，继续在树中下探。
+## The Full Context → Chapter → Entity Pipeline
 
-## 上下文窗口管理
-
-为 Worker LLM 设计树导航时，做好 token 预算：
-
-```
-总上下文窗口：32,768 tokens
-- 系统提示词：   ~2,000 tokens
-- 提取指令：     ~500 tokens
-- 输出格式说明：  ~300 tokens
-- 示例（可选）：  ~500 tokens
-- 回复预留：     ~2,000 tokens
----
-可用于文档内容：~27,468 tokens（约 18,000-20,000 中文字符）
-```
+This is the standard narrowing funnel for extracting entities for verification:
 
-中文 token 密度约 1.5 字符/token（取决于分词器）。根据实际使用的模型调整估算。
+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`.
 
-## 缓存和复用
+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.
 
-文档树构建一次，所有规则共享使用：
+## Caching and Reuse
 
-- 将树结构保存为 JSON 文件，存放在解析后文档旁边（如 `report.tree.json`）。
-- 多条规则可能需要同一文档的不同章节。每条规则通过树直接导航到其所需章节，无需重新解析。
-- 树结构文件应包含：节点标题、层级、起止位置、内容大小。不需要包含实际内容——内容从解析后的 markdown 文件中按位置提取。
+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.
 
-## 边缘情况
+## Edge Cases
 
-- **扁平文档**：有些文档没有层级结构（如短篇通知、单页证明）。把整份文档视为一个节点。如超出上下文窗口，使用 LLM 辅助分块。
-- **深层嵌套**：部分法律文件嵌套达 6 层以上。构建所有层级，但对任一规则通常只需导航 2-3 层深。
-- **跨章节引用**："如第 1.2 节所定义"——提取时可能需要从多个树节点收集内容，合并后喂给 LLM。
-- **附录和附件**：经常包含关键表格和数据（关联交易明细、监管指标计算等）。将其作为顶层节点纳入树中，不要遗漏。
-- **目录与正文不一致**：偶尔目录列出的章节在正文中不存在（或反过来）。以正文为准，但记录差异。
+- **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.