kc-beta 0.1.0

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

@@ -0,0 +1,168 @@
+---
+name: document-parsing
+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.
+---
+
+# 文档解析
+
+解析是核查工作的地基。文本提取有误，后续所有判定都将失去意义。但解析同时也是成本中心——简单文本提取能解决的问题，绝不要动用视觉模型。
+
+## 最小可用解析器原则
+
+从最简单的解析器开始，仅在质量不达标时逐级升级。这不是为了省钱，而是因为简单解析器的失败模式更少、输出更稳定。复杂工具引入的变量越多，排查问题越困难。
+
+把解析器想象成一架梯子：你需要够到的是那个高度，而不是梯子的最高一级。
+
+### Level 1：直接文本提取
+
+- **工具**：pymupdf（PyMuPDF）或同类 PDF 文本提取库。
+- **适用场景**：内嵌文字层的数字原生 PDF。覆盖绝大多数现代金融文档——年报、招股说明书、贷款合同、监管报告。
+- **输出**：带基础段落结构的原始文本。
+- **局限**：表格可能被拆散为凌乱文本；图表和扫描页无法处理。
+- **成本**：零 API 调用，毫秒级速度。
+
+这是默认起点。只有当输出质量不合格时才考虑升级。
+
+### Level 2：版面感知提取
+
+- **工具**：pdfplumber 或同类版面感知解析器。
+- **适用场景**：Level 1 的表格输出混乱、多栏排版文档、表单类文档（贷款申请表、尽调清单等）。
+- **输出**：保留空间布局的文本，支持单元格级别的表格提取。
+- **局限**：仍基于文本层，无法处理扫描件。
+- **典型触发条件**：当 Level 1 提取的财务报表数字与列头错位、合并单元格导致数据串行时，升级到此级别。
+
+### Level 3：OCR 识别
+
+- **工具**：`.env` 中 `OCR_MODEL_TIER` 配置的视觉识别模型（PaddleOCR、GLM-4V 等）。
+- **适用场景**：扫描件 PDF、影印版监管文件、历史档案（2010年以前的银行文件很多是扫描件）。
+- **输出**：从图像中识别出的文字。
+- **局限**：速度慢、消耗 API 调用、可能引入识别错误（繁体/简体混淆、表格线干扰等）。
+- **注意事项**：OCR 对中文竖排文本、印章遮盖区域、手写批注的处理能力有限。遇到这些情况要做额外质量检查。
+
+### Level 4：视觉模型解读
+
+- **工具**：高能力视觉模型（`OCR_MODEL_TIER1`）。
+- **适用场景**：
+  - 复杂表格：跨页表格、不规则合并单元格、嵌套表头（银行资本充足率报表常见此类结构）。
+  - 图表数据提取：柱状图、折线图、饼图中包含核查所需的关键数值。
+  - 混合排版：文字与图像交织的页面。
+- **输出**：对视觉内容的结构化解读（表格转 markdown、图表数据转 JSON）。
+- **局限**：成本高、速度慢。只在视觉内容确实需要语义理解时使用。
+
+## 质量检测
+
+解析完成后，不要直接进入下一步。先跑一遍质量检查，判断是否需要升级解析器。
+
+### 检测指标
+
+- **字符数过少**：文档有 200 页但提取文本不到 5000 字——大概率是扫描件，Level 1 只拿到了页眉页脚。
+- **乱码检测**：出现大量连续非常用字符、编码错误符号（□、■、?）、或无意义字符序列。常见于编码不匹配或字体嵌入异常的 PDF。
+- **章节缺失**：目录显示有"第五章 风险管理"，但提取文本中找不到对应内容。可能该章节是扫描插页或图片格式。
+- **表格异常**：
+  - 数字列缺少对齐，数值与表头无法对应。
+  - 单元格内容与相邻单元格混合。
+  - 表格线字符（|、+、-）出现在文本中。
+  - 关键财务数据缺失（资本充足率、不良贷款率、净利润等数字在文本中找不到）。
+- **页码断裂**：连续页码中有跳跃，说明某些页面可能未被提取。
+
+### 质量检查流程
+
+```
+解析完成 → 检查字符数 → 检查乱码比例 → 检查章节完整性 → 检查关键表格
+    ↓ 任一项不合格
+升级到下一级解析器 → 重新解析 → 再次检查
+```
+
+在工作流中实现此逻辑时，记录每次升级的原因（哪个指标触发了升级）。这些日志对演进循环有价值。
+
+### 解析质量评分
+
+将上述检测指标量化为一个综合评分（0.0–1.0），让升级决策从主观判断变为系统化流程。
+
+**推荐信号与参考权重：**
+- **字符密度**（~0.3）：实际提取字符数 / 按页数估算的预期字符数。远低于预期说明大量内容未被提取。
+- **乱码比例**（~0.2）：常用字符占比与异常序列占比的对比。编码问题在此暴露。
+- **章节完整性**（~0.3）：目录条目在正文中有对应内容的比例。缺失章节是解析失败的强信号。
+- **表格完整性**（~0.2）：关键数值（如总资产、净利润、资本充足率）在提取文本中是否可检索到。
+
+**升级阈值（推荐默认值）：**
+- ≥ 0.7：接受当前解析器级别，进入下一步。
+- 0.4–0.7：升级一级解析器，重新解析后再评分。
+- < 0.4：跳过中间级别，直接使用 OCR 或视觉模型。
+
+**锁定机制：** 一旦评分达标，记录当前解析器级别。仅在下游核查失败且回溯至解析质量时重新评估，避免反复试探。
+
+**重要提示：** 以上权重、阈值和评分方式本身都是起点，不是定论。编程智能体应根据实际文档特征自由调整、增删参数。真正重要的是这个框架——度量质量 → 对比阈值 → 做出决策——而非具体公式。公式会随着业务数据的积累不断演化。
+
+这套"评分 → 阈值 → 分级处理"的模式与 `skill-to-workflow` 中的模型层级选择逻辑完全同构。如果你已经理解了模型层级的逐级升级机制，这里的解析器升级遵循相同范式。
+
+## 表格处理
+
+金融文档的核心信息大量存在于表格中：资产负债表、利润表、资本充足率明细表、贷款五级分类表、关联交易汇总表。表格处理不好，核查就无法开展。
+
+### 四步流程
+
+1. **检测**：识别表格区域。寻找网格模式、一致的列间距、或显式的表格标记。对金融文档而言，数字密集且纵向对齐的区域几乎都是表格。
+
+2. **提取**：逐单元格提取内容。关键是保持行列关系——第三行第二列的数字必须对应正确的行标题和列标题。
+   - 常见陷阱：合并单元格导致行列错位；跨页表格的表头在第一页、数据在第二页；千分位逗号与单元格分隔符混淆。
+
+3. **重建**：转换为结构化格式。
+   - 首选 markdown 表格（人可读、LLM 可理解）。
+   - 复杂表格可用 JSON 行数组（便于程序处理）。
+   - 保留原始表头层级（如"期末余额"下分"本期"和"上期"两个子列）。
+
+4. **验证**：抽检重建后的表格与原文档是否一致。
+   - 选取 3-5 个关键数值，对照原 PDF 页面确认。
+   - 检查行数和列数是否匹配。
+   - 验证合计行是否等于明细行之和（财务报表通常有此约束）。
+
+### 表格提取失败时
+
+当 Level 1-2 无法正确提取表格：
+- 从 PDF 中裁剪表格区域的图片。
+- 发送给视觉模型，提示词要求输出 markdown 表格。
+- 对视觉模型的输出做与上述相同的验证步骤。
+
+不要因为一页表格提取失败就对整份文档使用 Level 4。只对出问题的表格页面升级。
+
+## 图表处理
+
+图表（柱状图、折线图、饼图、散点图）偶尔包含核查所需的数据：
+
+- 从文档中提取图表图片（按页面或按区域裁剪）。
+- 发送给视觉模型，提示词示例：
+  ```
+  请提取此图表中的所有数据点、标签和数值。
+  返回 JSON 数组格式，每个元素包含 label 和 value 字段。
+  如有多个系列，请分别标注系列名称。
+  ```
+- 将提取的数据与文档中其他位置的文本或表格交叉验证——图表的数据通常在正文或附表中也能找到。
+
+这是高成本操作。只在核查规则明确要求图表中的数据、且该数据无法从文本中获取时才执行。
+
+## 输出格式
+
+解析后的文档应保存为干净的 markdown 文件：
+
+- **保留标题层级**：`# 第一章 总则`、`## 第一节 定义`、`### 一、适用范围`。与原文档的层级结构一一对应。
+- **保留列表**：有序列表和无序列表保持原有编号方式。
+- **表格转换**：转为 markdown 表格格式。复杂表格保留足够的上下文说明。
+- **页码标注**：在页面边界处标注 `<!-- Page X -->`。部分核查规则引用特定页码。
+- **清除噪声**：页眉、页脚、页码、水印一律去除（除非某条规则专门检查这些内容）。
+- **保留原文措辞**：不要改写原文语句。解析是忠实转录，不是翻译或摘要。
+
+文件命名建议：原文件名加 `.parsed.md` 后缀，存放在同一目录下。
+
+## 缓存与复用
+
+解析是耗时操作（尤其 Level 3-4），必须缓存结果以避免重复劳动：
+
+- 将解析后的 markdown 文件保存在原文件旁边，供所有规则复用。
+- 记录解析器级别：在 markdown 文件开头或配套的元数据文件中注明使用了哪个级别的解析器。
+- 仅在以下情况重新解析：
+  - 原始文件被替换或更新。
+  - 某条规则的核查失败被追溯到解析质量问题，需要升级解析器。
+  - 缓存文件损坏或丢失。
+
+跨规则共享解析结果是效率的关键。一份 300 页的年报可能被 50 条规则引用——解析一次，使用 50 次。

package/template/skills/zh/meta/document-parsing/references/parser-catalog.md

@@ -0,0 +1,40 @@
+# Parser Catalog
+
+## Text-Based Parsers (No LLM Required)
+
+| Parser | Type | Strengths | Limitations | Install |
+|--------|------|-----------|-------------|---------|
+| PyMuPDF (fitz) | Text extraction | Fast, reliable, basic structure | No table awareness, no OCR | `pip install pymupdf` |
+| pdfplumber | Layout-aware | Good table detection, spatial layout | Text-only, no OCR | `pip install pdfplumber` |
+| python-docx | DOCX parser | Native DOCX support, preserves structure | DOCX only | `pip install python-docx` |
+| openpyxl | XLSX parser | Full spreadsheet support | XLSX only | `pip install openpyxl` |
+| MarkItDown | Multi-format | Handles PDF, DOCX, PPTX, XLSX → markdown | Basic parsing, may miss complex layouts | `pip install markitdown` |
+
+## OCR / Vision Models (Via SiliconFlow API)
+
+| Model | Tier | Strengths | Best For |
+|-------|------|-----------|----------|
+| zai-org/GLM-4.6V | OCR_TIER1 | Best accuracy, strong Chinese OCR | Complex tables, mixed layouts |
+| Qwen/Qwen3.5-397B-A17B | OCR_TIER2 | Good general vision, large model | Tables with context-dependent interpretation |
+| PaddlePaddle/PaddleOCR-VL-1.5 | OCR_TIER3 | Fast, lightweight | Standard text, simple tables |
+
+## Local Deployment Options
+
+For developer users who prefer local processing:
+
+| Tool | Type | Notes |
+|------|------|-------|
+| PaddleOCR | Local OCR | Open source, supports Chinese/English |
+| Surya | Local OCR | Modern OCR with table detection |
+| pdf2md-local | PDF → Markdown | Reference: github.com/Ruilin-mmwa/pdf2md-local |
+
+## Selection Decision Tree
+
+```
+Is the PDF text-based (not scanned)?
+├─ Yes → PyMuPDF or pdfplumber
+│   └─ Are tables parsed correctly?
+│       ├─ Yes → Done
+│       └─ No → Try pdfplumber → If still bad → Vision model on table regions
+└─ No (scanned) → OCR_TIER3 → If quality insufficient → OCR_TIER1
+```

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

@@ -0,0 +1,276 @@
+---
+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.
+---
+
+# 实体提取
+
+实体是核查的对象。一个数字、一个日期、一个金额、一个比率、一段条款。规则告诉你要检查什么，实体提取是你把这个"什么"从文档中拿出来的过程。
+
+## 实体是什么
+
+在文档核查语境下，实体不是 NLP 教科书中的"命名实体"。实体是**规则所关心的任何可提取信息片段**：
+
+- 资本充足率：12.5%
+- 贷款到期日：2025年6月30日
+- 借款人名称：某某股份有限公司
+- 贷款金额：人民币伍仟万元整
+- 担保方式：抵押+保证
+- 风险披露段落（整段文本）
+- 签字页是否存在（布尔值）
+
+实体的类型和粒度由规则决定，不是预先定义的。
+
+## 提取类型分类
+
+不同的提取场景需要不同的策略：
+
+### 单章单实体
+
+最简单的情况。一条规则需要从一个章节中提取一个值。
+
+- **示例**："从关键指标表中提取资本充足率。"
+- **方法**：定位到章节，用正则或 LLM 提取。
+- **这是最常见的情况**，优先为此场景优化工作流。
+
+### 单章多实体
+
+一条规则需要从同一位置提取若干相关值。
+
+- **示例**："从贷款协议摘要中提取借款人名称、贷款金额、利率、到期日。"
+- **方法**：设计一次提取调用返回所有值。比分别调用更高效，也更容易保持值之间的关系一致性。
+- **注意**：如果用 LLM 提取，在提示词中一次性要求所有字段。如果用正则，对同一文本段逐个匹配。
+
+### 多章单实体
+
+一个值分散在多个位置，或需要交叉核对。
+
+- **示例**："提取总担保物价值，可能出现在担保章节或附录 A 中。"
+- **方法**：从所有相关章节收集内容，然后统一提取。记录值的来源位置——如果同一实体在不同位置出现不同值，这本身就是一个需要判定的问题。
+- **金融文档中的典型场景**：净利润可能出现在"主要财务指标"、"利润表"、"董事长致辞"等多处。
+
+### 全文实体
+
+值可能在任何位置，或规则适用于整份文档。
+
+- **示例**："检查文档是否包含有效的签字页。"
+- **方法**：
+  - 编程智能体执行时：扫描全文。
+  - 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 原则）：
+
+```json
+{
+  "entity_name": "capital_adequacy_ratio",
+  "value": 12.5,
+  "unit": "%",
+  "raw_text": "本行资本充足率为12.50%",
+  "source_location": "第二章 > 第一节 主要财务指标 > 表1 第3行",
+  "confidence": 0.93,
+  "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%"
+```
+
+将后处理函数写成独立的 Python 工具，放在规则技能的 `scripts/` 目录中。它们是确定性的、可复用的。
+
+## 置信度标注
+
+每次提取都应附带一个置信度估计。这不是模型的自信程度，而是对提取结果正确概率的预判：
+
+### 初始先验值
+
+| 提取方法 | 置信度范围 | 说明 |
+|---------|-----------|------|
+| 正则匹配+格式验证 | 0.90-0.95 | 格式对了，值大概率对 |
+| LLM 提取，高确定性 | 0.80-0.85 | 模型明确找到了值 |
+| LLM 提取，有歧义 | 0.60-0.75 | 模型不太确定或有多个候选 |
+| 回退/推断值 | 0.40-0.60 | 非直接提取，有猜测成分 |
+| 未找到值 | 0.0 | 标记为 MISSING |
+
+这些是起始值。通过实际的质量控制审查校准（参见 `confidence-system`）。
+
+### 置信度调整因素
+
+- **原文验证**：提取的值能在原文中找到完全匹配 → 置信度 +0.05。
+- **多处一致**：同一值在文档多处出现且一致 → 置信度 +0.05。
+- **格式异常**：值的格式与预期不符（如百分比用小数表示）→ 置信度 -0.10。
+- **边缘案例匹配**：文档匹配已知边缘案例模式 → 置信度 -0.10。
+
+## 适配 Worker LLM 上下文窗口
+
+为 Worker LLM 工作流设计提取步骤时，做好 token 预算：
+
+1. **计算提示词大小**：系统提示 + 提取指令 + 输出格式说明 + 示例 = N tokens。
+2. **可用文档内容空间** = 模型上下文窗口 - N - 回复预留。
+3. 如果章节内容超出可用空间，通过文档树进一步缩小范围。
+4. 始终为模型回复留出足够空间（至少 1K-2K tokens）。
+5. **用实际模型测试**——编程智能体的 token 计数可能与Worker LLM 的分词器不同。中文文本在不同分词器间的 token 数差异可达 30%。
+
+### Worker LLM 提取提示词模板
+
+```
+你是一个金融文档实体提取助手。
+
+任务：从以下文档内容中提取指定实体。
+
+要提取的实体：{entity_description}
+
+文档位置：{document_path}
+
+文档内容：
+---
+{section_content}
+---
+
+输出格式（JSON）：
+{
+  "value": <提取的值>,
+  "unit": "<单位>",
+  "raw_text": "<原文中包含该值的完整句子>",
+  "found": true/false
+}
+
+注意：
+- 如果找不到该实体，将 found 设为 false，value 设为 null。
+- 不要猜测或推断，只提取文档中明确存在的信息。
+- raw_text 必须是文档中的原文，不要改写。
+```
+
+根据实际测试结果调整提示词。不同的 Worker LLM 对提示词格式的敏感度不同。