kc-beta 0.1.0

package/template/skills/zh/meta/cross-document-verification/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: cross-document-verification
+description: Perform case-level analysis across multiple documents for the same transaction. Use when documents do not exist in isolation — main contracts have appendices, loan applications come bundled with income certificates, bank statements, credit reports, and property appraisals. Use to build comparison matrices, detect contradictions (hard mismatches and soft implausibilities), classify severity, and flag fraud signals. Also use when user or end-user reports a cross-document inconsistency — these reports are ground truth and take priority over agent judgment.
+---
+
+# 跨文档交叉核验——案件级分析
+
+单文档核查回答的是「这份文件合不合规」。跨文档交叉核验回答的是一个完全不同的问题：**这笔交易的所有文件，讲的是不是同一个故事？**
+
+这是文件检查员和案件分析师的区别。检查员一份一份看文件，每份独立判定。分析师把这笔交易的全部材料摊在桌上，找到贯穿其中的线索——或者找到相互矛盾的破绽。启用跨文档核验，就是把系统从「逐文件检查」升级为「案件级分析」。
+
+在实际信贷业务中，三查制度（贷前调查、贷中审查、贷后检查）的每一个环节都涉及多文档交叉比对。贷前调查要交叉验证借款人提供的各项材料是否一致；贷中审查要核实合同条款与审批条件是否吻合；贷后检查要比对实际用途与贷款申请书中的声明。跨文档核验是三查制度在自动化系统中的落地。
+
+## 案件概念
+
+案件是指同一笔交易、同一个借款人或同一笔业务相关的全部文档集合。案件中的文档共享实体：姓名、日期、金额、证件号码。这些共享实体就是交叉比对的锚点。
+
+### 模式一：主合同 + 补充协议 + 附件
+
+同一出具方，有正式的交叉引用关系。这是团队经验最丰富的场景。
+
+典型文档集：
+- 主合同（借款合同/授信合同）
+- 补充协议（利率调整、还款方式变更）
+- 附件 A：抵押物清单
+- 附件 B：还款计划表
+- 附件 C：担保函
+
+常见问题：
+- 主合同约定贷款总额 500 万，但附件 B 还款计划表的本金合计为 485 万
+- 主合同引用「详见附件 D」，但附件 D 不存在或已替换为其他版本
+- 补充协议修改了利率，但附件 B 的还款计划未同步更新
+- 主合同甲方名称「深圳XX有限公司」，附件中写成「深圳XX有限责任公司」
+
+### 模式二：多来源材料包
+
+不同出具方、不同格式，指向同一借款人。
+
+典型文档集：
+- 贷款申请书（借款人填写）
+- 收入证明（用人单位出具）
+- 银行流水（银行出具，6个月或12个月）
+- 征信报告（人民银行征信中心）
+- 房产评估报告（评估机构出具）
+- 营业执照/统一社会信用代码证（市场监管部门）
+
+常见问题：
+- 申请书填写月收入 8.5 万，收入证明写 8.2 万，银行流水月均入账仅 4.3 万
+- 申请书上的身份证号与征信报告中的不一致（一位数字之差）
+- 收入证明的入职日期与征信报告中的雇主信息时间线不吻合
+- 房产评估报告中的产权人与贷款申请人不是同一人
+
+两种模式中，共享实体都是锚点。每个在两份以上文档中出现的实体，都是交叉核验的候选对象。
+
+## 构建比对矩阵
+
+比对矩阵是跨文档核验的核心工件。行是共享字段，列是来源文档，单元格是该文档中该字段的提取值。
+
+### 贷款案件示例矩阵
+
+| 字段 | 贷款申请书 | 收入证明 | 银行流水 | 征信报告 | 房产评估 |
+|------|-----------|---------|---------|---------|---------|
+| 申请人姓名 | 张伟 | 张伟 | 张伟 | 张伟 | 张伟（产权人）|
+| 身份证号 | 310101199001011234 | 310101199001011234 | — | 310101199001011234 | 310101199001011234 |
+| 月收入 | 85,000 | 82,000 | 月均入账 43,000 | — | — |
+| 工作单位 | ABC科技有限公司 | ABC科技有限责任公司 | — | ABC科技 | — |
+| 入职时间 | 2019年3月 | 2019年6月 | — | 2019年 | — |
+| 贷款金额 | 350万 | — | — | — | — |
+| 房产估值 | 约500万 | — | — | — | 512万 |
+
+### 合同案件示例矩阵
+
+| 字段 | 主合同 | 补充协议 | 附件A | 附件B |
+|------|--------|---------|-------|-------|
+| 贷款总额 | 500万 | 500万 | — | 485万（合计）|
+| 年利率 | 4.35% | 4.10%（调整后）| — | 4.35%（未更新）|
+| 乙方名称 | 深圳XX有限公司 | 深圳XX有限公司 | 深圳XX有限责任公司 | 深圳XX有限公司 |
+| 生效日期 | 2024-01-15 | 2024-03-01 | 2024-01-15 | 2024-02-01 |
+
+使用 `entity-extraction` 的输出填充矩阵。空白单元格表示该文档中未找到该字段——这是缺失，不一定是错误。但应该存在却缺失的字段本身就是一个发现。
+
+### 身份证号18位校验
+
+中国居民身份证号码为18位，最后一位为校验码。提取后应进行校验码验证：
+- 如果校验码不正确，标记为 error（可能是OCR识别错误或伪造）
+- 跨文档比对时要求18位完全一致，零容差
+
+### 统一社会信用代码
+
+企业法人的统一社会信用代码为18位字母数字组合。跨文档比对时：
+- 要求18位完全一致
+- 注意区分大写字母O和数字0，大写字母I和数字1（OCR常见错误）
+- 可通过校验位验证代码合法性
+
+## 矛盾类型
+
+### 硬矛盾（Hard Contradiction）
+
+必须完全一致的字段出现了不一致：
+
+- **身份信息不一致**：姓名拼写不同、身份证号位数不对、出生日期矛盾。在中国信贷业务中，身份证号是最核心的锚点——一个数字的差异就意味着不是同一个人，或者存在录入/OCR错误。
+- **金额不一致**：主合同载明贷款金额 500 万，但还款计划表本金合计 485 万。收入证明写月薪 8.2 万，但申请书填了 8.5 万。
+- **日期不一致**：主合同生效日期为 2024-01-15，但某附件标注生效日期为 2024-02-01。
+
+硬矛盾是二元的——在定义的容差范围内，要么一致，要么不一致。
+
+### 软矛盾（Soft Contradiction）
+
+数值没有直接矛盾，但放在一起看不合理：
+
+- 收入证明月薪 10 万，但银行流水月均入账只有 5 千——技术上可能（工资发到别的账户），但高度可疑。
+- 房产评估价 300 万，贷款金额 280 万（LTV 93%）——没超过上限，但接近极限。
+- 申请书写入职时间 2019 年 3 月，收入证明写 2019 年 6 月——3 个月的差异可能是四舍五入，也可能是编造。
+- 征信报告显示负债率 48%，而本次贷款如获批将把负债率推到 52%——审批时在红线以下，放款后突破红线。
+
+软矛盾需要阈值和判断。它们是发现，不是结论。
+
+### 交叉引用失败
+
+正式关联文档之间的结构性完整性问题：
+
+- 主合同引用「详见附件 B——还款计划」，但附件 B 实际标题是「抵押物清单」，或者附件 B 根本不存在。
+- 附件引用了主合同中某一条款，但在提供的主合同版本中找不到该条款。
+- 缺少双向引用：附件 C 提到了主合同，但主合同的附件列表中没有附件 C。
+- 版本不匹配：主合同日期为1月，附件日期为3月且条款内容不同——可能是补充协议修改后附件未同步更新。
+
+详细的字段级矛盾分类表见 `references/contradiction-taxonomy.md`。
+
+## 严重程度分级
+
+不是所有矛盾都一样严重。按影响分级：
+
+| 严重程度 | 判定标准 | 典型示例 |
+|---------|---------|---------|
+| **致命（Critical）** | 身份类字段不一致 | 两份文件中的身份证号不同；统一社会信用代码不一致 |
+| **高（High）** | 金额类差异 > 10% | 收入证明 8.2 万 vs 银行流水月均 4.3 万 |
+| **中（Medium）** | 日期、任职信息不一致 | 入职时间相差 3 个月；合同日期与附件日期不同 |
+| **低（Low）** | 格式或简称差异 | 「ABC科技有限公司」vs「ABC科技有限责任公司」|
+
+开发者用户在项目配置中按字段设定严重程度阈值。以上是默认起点，需要根据业务场景调整。在某些场景下，5% 的金额差异就是致命问题；在另一些场景下，15% 也可以接受。
+
+关键原则：**严重程度分级要反映业务影响，而不是数学大小**。一个身份证号差一位数，数学上差异极小，但业务影响是致命的。
+
+## 伪造信号识别
+
+跨文档分析能揭示单文档审查发现不了的模式。以下信号需要标记上报——**标记，不是指控**：
+
+### 一致性过高的小偏差
+
+多份文档中的数值都偏高了恰好 5%。日期都恰好偏移了一个月。这种「错误中的一致性」暗示协调伪造，而非无心之失。真实的错误是随机的；伪造的错误是系统性的。
+
+### 文档雷同
+
+来自不同出具方的多份文档使用相同的排版格式、相同的措辞、甚至相同的错别字。不同机构出具的正规文件应该看起来不一样。如果一个人的收入证明和另一个人的收入证明格式完全一致——包括页眉、字体、措辞——值得追查出具方是否真实。
+
+### 数值恰好卡在监管红线
+
+LTV 恰好 69.9%（上限 70%）。DTI 恰好 49.8%（上限 50%）。偿债覆盖率恰好 1.21（下限 1.2）。单独看是巧合，组合在一起就是信号。特别是当这些数值是通过「调整」评估价或收入数字来实现的。
+
+### 时间线不可能
+
+收入证明的出具日期早于入职日期。银行流水覆盖的时间段早于开户日期。房产评估报告日期晚于贷款放款日期。这些不是矛盾——它们在时间上就不可能存在。
+
+### 关键缺失
+
+该有的文件恰好缺失。全套材料中独缺最难伪造的那一份（如银行流水原件、征信报告原件）。多个可选材料中只提供了最容易伪造的组合。
+
+### 信号组合放大
+
+单独一个信号可能只是巧合，但多个信号同时出现时，可信度大幅提高。实践中建议按信号组合分级：
+
+- **单一信号**：记录，不上报。可能是噪声。
+- **两个信号同时出现**：标记为可疑（suspicious），提请关注。
+- **三个及以上信号**：标记为高度可疑（highly suspicious），建议优先人工复核。
+
+不要试图用规则引擎穷举所有组合。信号列表是开放的——开发者用户和终端用户在实际审查中可能发现新的伪造模式，这些新模式应纳入信号库。
+
+这些是上报信号，不是终审结论。附上证据，让开发者用户或下游审查流程做最终判断。
+
+## 工作流顺序
+
+跨文档核验在一个案件中的推荐执行顺序：
+
+1. **确定案件边界。** 哪些文档属于同一案件？用共享标识（借款人姓名、贷款编号、合同引用关系）将文档归组。
+2. **提取锚点。** 对每份文档独立运行 `entity-extraction`，收集共享字段。
+3. **构建比对矩阵。** 填充矩阵，标记空白单元格。
+4. **检测矛盾。** 按 `references/contradiction-taxonomy.md` 的分类执行硬矛盾/软矛盾/交叉引用检查。
+5. **严重程度分级。** 根据配置的阈值分配严重程度。
+6. **扫描伪造信号。** 在矩阵上运行模式检查。
+7. **生成报告。** 输出案件级一致性报告，包含所有发现。
+
+每一步的输出是下一步的输入，但步骤 2（提取锚点）依赖于 `entity-extraction` 技能，如果提取质量不够，后续所有环节都会受影响。因此，在跨文档核验之前，确保单文档的实体提取已经过充分测试。
+
+## 与三查制度的对应关系
+
+跨文档核验在信贷三查制度中的位置：
+
+### 贷前调查阶段
+- 核验借款人提交的各项材料之间是否一致
+- 重点：身份信息交叉验证、收入与流水匹配度、申报信息与征信信息比对
+- 典型交叉核验对：
+  - 贷款申请书 × 收入证明：月收入一致性
+  - 收入证明 × 银行流水：收入与实际入账匹配度
+  - 贷款申请书 × 征信报告：已有负债申报完整性
+  - 身份证 × 所有文件：姓名和证件号一致性
+- 产出：申请材料一致性报告
+
+### 贷中审查阶段
+- 核验合同条款与审批意见是否一致
+- 重点：合同金额/利率/期限与审批批复一致、主合同与附件条款无矛盾、担保文件与主合同对应
+- 典型交叉核验对：
+  - 审批批复 × 主合同：批复金额、利率、期限是否如实写入合同
+  - 主合同 × 附件：条款引用完整性、数值一致性
+  - 担保合同 × 主合同：担保范围是否覆盖主债权
+  - 抵押物评估报告 × 合同约定：抵押物描述一致性
+- 产出：合同审查一致性报告
+
+### 贷后检查阶段
+- 核验实际用途与贷款合同约定是否一致
+- 重点：资金流向与贷款用途声明比对、还款记录与合同约定比对
+- 典型交叉核验对：
+  - 放款凭证 × 合同约定：放款金额、账户一致性
+  - 用途证明材料 × 贷款申请书：实际用途与声明用途比对
+  - 还款记录 × 还款计划表：实际还款与约定还款比对
+- 产出：贷后核查一致性报告
+
+## 集成方式
+
+**输入：**
+- `entity-extraction` 的实体提取结果（每份文档中各字段的原始值）
+- `compliance-judgment` 的合规判定结果（已完成的单文档 pass/fail 判定）
+
+**输出：**
+- 案件级一致性报告：比对矩阵、所有发现的矛盾、严重程度分级、伪造信号标记
+
+**下游衔接：**
+- `confidence-system`：跨文档矛盾降低相关字段的置信度
+- `evolution-loop`：反复出现的矛盾模式触发工作流优化
+- `dashboard-reporting`：案件视图与文档视图并列展示
+
+**基准真值原则：用户和终端用户的矛盾报告是基准真值，优先于智能体自身判断。** 当用户或终端用户报告了系统遗漏的跨文档不一致，该报告自动成为最高优先级的反馈。记录它、从中学习、据此调整检测阈值。系统的目标是捕获人类能捕获的所有问题——然后更进一步。

package/template/skills/zh/meta/cross-document-verification/references/contradiction-taxonomy.md

@@ -0,0 +1,73 @@
+# Contradiction Taxonomy
+
+Field-level reference for cross-document contradiction detection. Use this taxonomy to configure comparison rules per field type.
+
+## Identity Fields
+
+| Field | Match Type | Tolerance | Severity | Notes |
+|-------|-----------|-----------|----------|-------|
+| Full name | Fuzzy | Abbreviation, spacing, honorifics | Critical | "Zhang Wei" vs "Zhang W." is fuzzy match; "Zhang Wei" vs "Li Ming" is hard fail |
+| ID number | Exact | None (zero tolerance) | Critical | Single-digit difference = different person or transcription error — both critical |
+| Date of birth | Exact | None | Critical | Cross-check against ID number encoding where applicable |
+| Address | Fuzzy | Abbreviation, floor/unit formatting | Medium | "Rm 1201, Bldg A" vs "Room 1201, Building A" is acceptable |
+| Phone number | Exact | Country code prefix | Medium | +86 prefix presence/absence is tolerated |
+| Company name | Fuzzy | Ltd/Co/Inc suffix, punctuation | High | Must match on core name; suffix variation tolerated |
+
+## Financial Fields
+
+| Field | Comparison Method | Tolerance | Severity | Notes |
+|-------|------------------|-----------|----------|-------|
+| Stated income | Cross-document | 10% relative | High | Application vs income certificate vs credit report |
+| Bank avg deposits | Income plausibility | 50% of stated income (floor) | High | If avg deposits < 50% of claimed income, flag |
+| Loan amount | Exact across docs | 0.1% relative | Critical | Must be identical in application and contract |
+| Property value | Appraisal consistency | 5% relative | High | Application estimate vs formal appraisal |
+| Existing debt | Cross-source | 20% relative | Medium | Self-reported vs credit report |
+| Net assets | Calculated consistency | Sum of components vs stated total | High | Assets - liabilities must equal stated net |
+| Contract total vs line items | Sum check | 0.01 absolute | Critical | Main contract total must equal appendix line item sum |
+
+## Temporal Fields
+
+| Field | Consistency Check | Tolerance | Severity | Notes |
+|-------|------------------|-----------|----------|-------|
+| Employment start date | Cross-document match | 90 days | Medium | Application vs income cert vs credit report |
+| Contract signing date | Sequence plausibility | Must be after application date | High | Cannot sign before applying |
+| Document issuance date | Freshness and sequence | Per business rule (typically 30-90 days) | Medium | Income cert issued 6 months ago may be stale |
+| Loan maturity date | Contract consistency | Exact match across docs | High | Application vs contract vs amortization schedule |
+| Appraisal date | Sequence plausibility | Must precede loan approval | Medium | Appraisal after disbursement is a red flag |
+
+## Logical Consistency Checks
+
+These are not single-field comparisons but cross-field logical validations:
+
+- **LTV ratio consistency**: Property value x LTV % should equal or exceed loan amount. Check across appraisal, application, and contract.
+- **DTI ratio reasonableness**: Monthly debt payments (from credit report) + proposed payment / monthly income (from income cert) should not exceed the stated DTI or regulatory limit.
+- **Timeline plausibility**: Employment start < income cert issuance < application date < contract signing < disbursement. Any violation of this sequence is a finding.
+- **Appendix completeness**: Every appendix referenced in the main contract must be present in the case file. Every appendix present must be referenced in the main contract.
+- **Guarantor cross-check**: If a guarantor is listed, their identity fields must also pass cross-document verification against any guarantor-specific documents.
+- **Amount decomposition**: If the contract specifies principal + interest + fees, these must sum to the total obligation stated elsewhere.
+
+## Comparison Matrix Template
+
+Output schema for the case-level comparison matrix:
+
+```json
+{
+  "case_id": "CASE-2024-0042",
+  "documents": [
+    {"doc_id": "DOC-001", "type": "loan_application", "source": "applicant"},
+    {"doc_id": "DOC-002", "type": "income_certificate", "source": "employer"}
+  ],
+  "matrix": [
+    {"field": "applicant_name", "category": "identity",
+     "values": {"DOC-001": "Zhang Wei", "DOC-002": "Zhang Wei"},
+     "status": "consistent", "severity": null}
+  ],
+  "contradictions": [
+    {"field": "monthly_income", "documents": ["DOC-001", "DOC-002"],
+     "values": [85000, 82000], "type": "hard_contradiction",
+     "severity": "medium", "detail": "3.5% discrepancy in stated income"}
+  ],
+  "fraud_signals": [],
+  "summary": {"total_fields_compared": 8, "consistent": 6, "soft_mismatch": 1, "hard_mismatch": 1, "absent": 0}
+}
+```

package/template/skills/zh/meta/data-sensibility/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: data-sensibility
+description: Build intuition about document data before writing extraction logic. Use before designing any extraction schema or regex pattern, when onboarding a new document type, or when extraction accuracy is unexpectedly low and you suspect a data assumption is wrong. Covers systematic observation of raw documents, spot-checking extracted results, distribution analysis, and recognizing suspicious patterns. If you are about to write code that touches document data and you have not read at least five documents end-to-end, stop and use this skill first.
+---
+
+# 数据体感培养
+
+数据体感不是一个精确的技术术语，而是一种能力：你对数据质量的直觉判断。看数据和读数据是两件不同的事。看数据是扫一眼字段名、确认有值、继续写代码。读数据是理解每个值是怎么来的、为什么是这个格式、什么时候会出问题。
+
+文档核查中最昂贵的错误不是逻辑写错了——那种错误测试能抓住。最昂贵的错误是对数据的假设不成立。你以为日期格式是 YYYY-MM-DD，因为前三份文档都是这样。第四份文档用了 DD/MM/YYYY，所有提取结果都悄无声息地错了。你以为贷款金额在"贷款要素"表格的第三行，直到遇到一家银行把金额写在合同首段的叙述文字中。
+
+数据体感是"先看后写"的纪律。在写第一行提取代码之前，先真正理解你的数据。
+
+## 前置观察：先读文档再写代码
+
+拿到一类新文档时，打开 3-5 份完整文档从头读到尾。不是浏览——是阅读。打开原始解析文本，从第一页开始，逐页往下。
+
+### 读什么类型的文档
+
+以金融文档核查为例，常见的文档类型包括：
+
+- **贷款合同**：关注金额表述方式（大写/小写）、利率表述（年化/月利率/基点）、签署日期位置、担保条款结构。
+- **增值税发票**：关注发票代码和号码格式、金额和税额的位置、购买方/销售方信息的布局、备注栏内容。
+- **银行流水**：关注日期格式、摘要字段的长度和内容、余额计算方式（实时余额 vs 日终余额）、分页和续页的衔接。
+- **征信报告**：关注查询记录格式、贷款记录的展示方式、逾期信息的编码、特殊交易类型。
+- **房产评估报告**：关注估价结论的位置和表述、面积单位、评估方法描述、有效期表述。
+
+### 读的时候注意什么
+
+一边读一边记录让你意外的地方：
+
+- 你以为金额在表格里，结果它在一段叙述文字中间。
+- 同一份合同里大写金额写的"伍仟万元整"，小写写的"50,000,000.00元"——它们一致吗？
+- 文档有两个签字页，不是一个。
+- 章节标题的编号方式前后不一致（第一章用"一"，第二章用"2"）。
+- 某些字段有时候有，有时候没有——不是固定出现的。
+
+对每种新文档类型都做这件事。当文档来源发生变化时，再做一次。30 分钟的阅读能节省 3 小时的调试时间——那些调试时间会花在修复基于错误假设构建的提取逻辑上。
+
+## 系统观察清单
+
+读完文档后，显式回答以下问题。写下来，不要只在脑子里过一遍：
+
+### 什么是一致的？
+
+所有文档中稳定不变的元素：页头结构、字段位置、术语用法、日期格式。这些是你的锚点，提取逻辑应该围绕它们来设计。
+
+例如：所有贷款合同都在第一页左上角有合同编号，格式为"XX银贷字〔YYYY〕第NNNN号"。这个就可以写正则。
+
+### 什么在变化？
+
+不同文档之间有差异的元素：表格布局、章节顺序、字段是否存在、格式约定。这些是你的风险点，每种变体都需要一个测试用例。
+
+例如：贷款金额有时候在"贷款要素"表格中，有时候在合同正文第一段。两种位置都需要覆盖。
+
+### 什么是令人意外的？
+
+你没有预料到的任何情况：
+
+- 一个应该总是存在的字段偶尔缺失。
+- 同一个值在不同文档中用不同单位表示（万元 vs 元）。
+- 某些模板中存在一个章节，其他模板中没有。
+- 增值税发票的备注栏包含了关键的合同信息。
+
+### 文档子类型？
+
+同一类文档中是否存在不同的模板、不同的出具机构、不同的时间段版本？
+
+- 工商银行的贷款合同和招商银行的贷款合同可能完全不同。
+- 2020 年之前的征信报告和之后的格式不一样。
+- 同一家银行的个人贷款合同和企业贷款合同是两套模板。
+
+尽早识别子类型——它们通常需要独立的提取路径。
+
+### 章节长度？
+
+实际测量。不要猜。
+
+```python
+for section_name, section_text in sections.items():
+    token_count = len(section_text) // 2  # 粗估：中文约2字符/token
+    print(f"{section_name}: ~{token_count} tokens")
+```
+
+一个平均 200 tokens 的章节对任何模型都没问题。一个偶尔膨胀到 8000 tokens 的章节会打爆你的上下文窗口预算。提前知道，提前规划。
+
+### 编码问题？
+
+- **全角 vs 半角**：`１２．５％` vs `12.5%`。人眼看一样，正则匹配不一样。
+- **Unicode 标准化**：`〔` vs `(` vs `（`。同一个括号可能有三种写法。
+- **OCR 伪影**：扫描件转文本后，`0`（零）和 `O`（字母），`1`（一）和 `l`（L），`壹` 和 `㈠`。
+- **空格和换行**：PDF 解析后的文本可能在奇怪的位置插入换行符，把"资本充足率"拆成"资本充足\n率"。
+
+这些问题导致静默的提取失败——文本看起来对了，但正则匹配不到。
+
+## 抽检协议
+
+每次提取运行后，随机挑选 10 个字段手动核验。不挑简单的——要覆盖置信度频谱：3 个高置信度、4 个中置信度、3 个低置信度。
+
+### 核验字段示例
+
+以贷款合同为例，典型的抽检字段：借款人姓名（与合同首页一致吗？）、贷款金额（大写和小写一致吗？单位对吗？）、合同编号（完整提取了吗？）、签署日期（取的是签署日期还是打印日期？）、利率（年化还是月利率？LPR加点还是固定？）、担保方式（抵押/质押/保证/信用——提取对了吗？）。
+
+### 对每个字段检查四个维度
+
+1. **值正确？** 提取的值与文档原文一致吗？
+2. **来源位置正确？** 提取逻辑从正确的位置找到了这个值，还是从文档其他地方抓了一个相似的值？
+3. **标准化正确？** 原文写的"人民币伍仟万元整"，输出的 50000000 对不对？
+4. **类型正确？** 百分比有没有变成小数？日期有没有解析成错误的世纪？
+
+### 判定规则
+
+如果 10 个字段中有超过 1 个错误，**停下来**。不要继续处理这批数据。调查失败原因，识别模式，修复提取逻辑，然后重新运行。
+
+10% 的抽检错误率意味着真实错误率远高于 10%——因为你还没有发现那些看起来正确但实际不对的错误。
+
+## 分布可视化
+
+提取完成后，对关键字段做分布分析。不需要复杂的可视化工具，基本的 Python 就够了。
+
+### 一段代码覆盖三个维度
+
+```python
+from collections import Counter
+
+# 1. 字段长度分布 — 异常长度 = 提取错误
+for field in ["contract_id", "borrower_name"]:
+    lengths = [len(str(r[field])) for r in results if r.get(field)]
+    print(f"{field} 长度分布: {Counter(lengths).most_common(5)}")
+
+# 2. 值频率 — 异常集中 = 抓了表头或默认值
+guarantee_types = [r["guarantee_type"] for r in results if r.get("guarantee_type")]
+for value, count in Counter(guarantee_types).most_common(10):
+    print(f"  {value}: {count} 次")
+
+# 3. 缺失率 — 高缺失 = 提取静默失败
+total = len(results)
+for field in ["borrower_name", "loan_amount", "contract_id", "sign_date"]:
+    missing = sum(1 for r in results if not r.get(field))
+    rate = missing / total * 100
+    print(f"  {field}: 缺失 {rate:.1f}%{' ⚠' if rate > 10 else ''}")
+```
+
+即使是最简单的 `Counter(values).most_common(20)` 也能告诉你很多。不要跳过这一步。
+
+## 异味模式
+
+有些提取值单独看是合理的，但放在一起看就有问题：
+
+### 大写金额与小写金额不一致
+
+```
+文档 A: 大写"伍仟万元整" → 50,000,000    小写"50,000,000.00" → 50,000,000  ✓ 一致
+文档 B: 大写"壹仟万元整" → 10,000,000    小写"1,000,000.00"  → 1,000,000   ✗ 差10倍
+```
+
+大小写金额不一致在真实金融文档中是严重问题。如果你的提取结果中频繁出现不一致，可能是大写金额转换函数有 bug，也可能文档本身有错——但无论如何都需要调查。
+
+### 签章日期集中在月末
+
+所有合同的签署日期都是每月 28、29、30、31 号。可能是真实的业务模式（月末集中签约），但也可能是你提取的不是签署日期，而是合同生效日期或月末报送日期。核验几份原文确认。
+
+### 统一社会信用代码格式异常
+
+标准的统一社会信用代码是 18 位，格式为：登记管理部门代码(1位) + 机构类别代码(1位) + 登记管理机关行政区划码(6位) + 主体标识码(9位) + 校验码(1位)。如果提取结果中出现 15 位（旧版组织机构代码）或长度不等的代码，提取逻辑可能匹配了错误的字段。
+
+### 所有合同金额都是整万
+
+```
+5,000,000.00
+10,000,000.00
+3,000,000.00
+20,000,000.00
+```
+
+银行贷款确实倾向于整万或整百万，但如果每一份都是精确的整万，没有任何零头，值得抽查几份——你可能在提取授信额度而不是实际放款金额。
+
+### 恰好处于监管阈值的值
+
+资本充足率恰好 8.00%。贷款集中度恰好 10.00%。拨备覆盖率恰好 150.00%。金融机构确实会管理到阈值附近，但如果多份文档的同一指标恰好等于监管阈值，你可能提取的是阈值定义本身（"根据规定，资本充足率不得低于8%"），而不是机构的实际指标值。
+
+### 完美一致
+
+每一份文档都通过了每一条规则。100% 合规率。真实数据一定有例外。如果你的系统报告全部合规，你的系统大概率是错的。
+
+## 案例：通过分布分析发现系统性错误
+
+某次银行流水核查，提取"交易摘要"字段。初始结果看起来正常——每条流水都有摘要，字段不为空。
+
+做分布分析时发现问题：
+
+```python
+Counter(len(s) for s in summaries).most_common(5)
+# (2, 1203)  ← 95% 的摘要只有2个字
+# (4, 198)
+# (3, 45)
+```
+
+"转账"、"消费"、"工资"——每个值单独看都是合理的中文词汇。但真实银行流水的摘要通常更丰富："支付宝消费-星巴克"、"跨行转账-张三"、"工资-XX公司"。
+
+原因：PDF 表格解析时摘要列宽不足，长文本被截断。只有前两个中文字符被归入"摘要"列，后续内容被分配到了下一列。不做分布分析，这个错误不会被发现。修复：调整列宽参数。
+
+## 中间输出物化
+
+把每个处理阶段的结果保存到磁盘：
+
+1. **原始解析文本**（来自文档解析阶段）。
+2. **树切分章节**（来自文档树处理阶段）。
+3. **提取的实体**（来自实体提取阶段）。
+4. **判定结果**（来自合规判定阶段）。
+
+将中间结果写为 JSON 文件，放在 `debug/` 目录中，用文档 ID 和阶段命名：
+
+```
+debug/
+  DOC001_01_raw_text.json
+  DOC001_02_tree_sections.json
+  DOC001_03_extracted_entities.json
+  DOC001_04_judgments.json
+```
+
+磁盘很便宜。没有中间结果的调试是猜谜游戏。
+
+当出问题时，你可以独立检查每个阶段：章节切分错了？看 `_02`。提取对了但判定错了？对比 `_03` 和 `_04`。原始文本就是乱码？看 `_01`。没有中间结果，你只能盯着最终输出猜测。保留至少当前迭代的中间结果。
+
+## 集成
+
+数据体感的观察结果应直接输入下游技能：
+
+- `entity-extraction`：数据格式、字段变体、编码问题直接决定数据模式设计和正则模式。大写金额的变体告诉你转换函数需要处理哪些写法。
+- `skill-authoring`：边缘案例和已知变体成为规则技能中的测试用例。某家银行的合同模板与众不同？这应该成为技能中的一个明确分支。
+- `confidence-system`：抽检结果和分布分析校准初始置信度预期。某类字段抽检准确率只有 70%，先验值就不应该设到 0.90。
+- `evolution-loop`：演进循环揭示预期之外的失败时，回来重新做数据体感观察。数据可能已经变化。
+
+数据体感不是一次性活动。每一批新数据、每一个新的文档来源、每一次格式变更，都是重新观察的契机。不要因为"上次看过了"就跳过——上次看的和这次可能不一样。