kc-beta 0.7.5 → 0.8.3

package/template/skills/zh/corner-case-management/SKILL.md

@@ -1,22 +1,35 @@
 ---
 name: corner-case-management
 tier: meta
-description: Identify, catalog, and handle corner cases that do not fit the mainstream verification workflow. Use when the evolution loop classifies a failure as a corner case (affecting less than ~10% of documents), when adding a new edge case to the registry, or when deciding whether a corner case should be promoted to a systemic fix. Also use when designing the corner case detection mechanism for a workflow.
+description: 识别、登记、处理那些不符合主工作流的边缘案例。**在经过若干轮 skill/workflow 迭代之后**——确实出现了适应不了的文档、且把它塞进主流程的代价不划算——才使用本 skill。涵盖：什么算边缘案例（vs 系统性问题），如何登记，如何用"检测 + 解决"机制把边缘案例留在冷路径上、只有当类似文档再次出现时才取出来用，以及何时把边缘案例提升为常规规则。
 ---
 
 # 边缘案例管理
 
-好的工作流处理 90% 的文档。边缘案例处理剩下的 10%。它们单独看出现率低，但累积起来影响显著。关键认知：**不要为了边缘案例给主工作流打补丁**。补丁导致逻辑混乱、代码脆弱、回归风险。
+好的工作流处理绝大多数文档。边缘案例是剩下那一小撮 —— 单独看出现率低，累积起来又不能忽略。关键认知：**不要为了边缘案例给主工作流打补丁**。补丁导致逻辑混乱、代码脆弱、回归风险。
 
 正确做法：把边缘案例从主流程中分离出来，单独管理。
 
+## 什么时候才用这个 skill
+
+边缘案例是在**测试迭代之后**识别的，不是在初次设计阶段。典型路径：
+
+1. 你为某条规则建好了 skill / workflow。
+2. 在样本集上跑过一遍。大多数通过，少数失败。
+3. 你迭代 —— 改代码、改 prompt、跑回测。
+4. 跑了若干轮之后，仍有少数 case 死活不合 —— 要么是：
+ - 当前工作流抓不住它们；让工作流去适应它们的代价又太大（破坏无关 case、徒增复杂度、需要架构重构）。
+   - 这些 case 在反复"摇摆"—— 这一轮改对了，下一轮又坏，振荡持续。
+
+这时候才使用本 skill。**第一轮就遇上不合的 case 不用。**能在工作流里合理修复的不用。只有当把这个 case 塞进主流程的成本超过这个 case 本身价值的时候，才登记成边缘案例。
+
 ## 理念
 
-文档核查中边缘案例是必然存在的。金融文档由数千家不同机构出具，每家都有自己的排版习惯、模板风格、对法规的不同理解。没有任何工作流能覆盖所有变体。
+边缘案例在文档核查里是必然存在的。金融文档由数千家不同机构出具，每家都有自己的排版习惯、模板风格、对法规的不同理解。没有任何工作流能覆盖所有变体。
 
-问题不是"怎么消灭边缘案例"，而是"怎么高效管理它们"。
+问题不是"怎么消灭边缘案例"，而是"怎么在不污染主流程的前提下高效管理它们"。
 
-答案是：**分离它们，保持主工作流干净，保持边缘案例可追踪、可检测、可解决**。
+答案是：**分离它们**。主工作流保持干净。边缘案例可追踪、可检测、再次出现时可取出来用。
 
 ### 主工作流 vs 边缘案例处理的分工
 
@@ -55,106 +68,76 @@ description: Identify, catalog, and handle corner cases that do not fit the main
       "action": "在阈值比较前将提取值乘以100",
       "code_snippet": "if value < 1.0: value *= 100"
     },
-    "discovered_at": "2026-04-01",
+    "discovered_at": "<日期>",
     "iteration": 3,
     "status": "active"
-  },
-  {
-    "id": "CC002",
-    "rule_id": "R005",
-    "description": "2020年以前出具的公募基金年报使用旧版信息披露格式，风险指标表格结构与现行模板不同",
-    "affected_documents": ["fund_abc_annual_2019.pdf", "fund_abc_annual_2018.pdf"],
-    "detection_pattern": {
-      "type": "keyword",
-      "keywords": ["基金年度报告", "2019年", "2018年"],
-      "additional_check": "报告日期早于2020-07-01"
-    },
-    "resolution": {
-      "type": "prompt",
-      "action": "使用旧版模板的提取提示词",
-      "prompt_variant": "extraction_prompt_legacy_format"
-    },
-    "discovered_at": "2026-04-01",
-    "iteration": 5,
-    "status": "active"
-  },
-  {
-    "id": "CC003",
-    "rule_id": "R012",
-    "description": "某省农商行贷款合同使用方言化表述，'借款期限'写作'借期'",
-    "affected_documents": ["loan_contract_rural_bank_001.pdf"],
-    "detection_pattern": {
-      "type": "regex",
-      "pattern": "借期[：:]\\s*\\d+",
-      "confidence_threshold": 0.7
-    },
-    "resolution": {
-      "type": "regex",
-      "action": "在提取时将'借期'等同于'借款期限'",
-      "alias_map": {"借期": "借款期限", "借额": "借款金额"}
-    },
-    "discovered_at": "2026-04-01",
-    "iteration": 7,
-    "status": "active"
   }
 ]
 ```
 
 每条记录应包含：
+
 - **描述（description）**：用人话说清楚这是什么情况。开发者用户需要能看懂。
 - **检测模式（detection_pattern）**：如何在执行前识别此类文档。类型可以是：
   - `regex`：正则匹配文档内容。
   - `keyword`：关键词组合匹配。
   - `structural`：文档结构特征（如缺少某个章节、表格格式异常）。
-  - `model`：需要 LLM 判断（成本高，仅在无法用简单方法检测时使用）。
+  - `model`：需要 LLM 判断（成本高，仅在简单方法无法检测时使用）。
 - **解决方案（resolution）**：如何处理匹配的文档。类型可以是：
   - `code`：Python 代码修正（如单位转换）。
   - `regex`：正则替换或别名映射。
   - `prompt`：使用不同的 LLM 提示词。
   - `parser`：使用不同级别的解析器。
   - `manual`：标记为需人工处理，不自动判定。
-- **发现时间和迭代轮次**：什么时候发现的，在哪轮演进中。
-- **状态（status）**：`active`（使用中）、`promoted`（已提升到主工作流）、`deprecated`（已废弃）。
+- **发现时间和迭代轮次**。
+- **状态（status）**：`active`、`promoted`（已提升到主工作流）、 `deprecated`（已废弃）。
+
+## 怎么处理边缘案例 —— 懒加载，高检索阈值
+
+边缘案例**只活在注册表里**，不进主核查路径。它们是**懒加载、高阈值检索的**，意思是：
+
+- 主工作流先在每份文档上跑。
+- 注册表只有当一份新进文档**强烈地像**某条已收录的边缘案例时才被调用，这条记录的解决方案才被取出来用。
+- "强烈地像"这条线要划得高 —— 误匹配会把一个不相干的解决方案套上来，污染主结果。宁可漏匹配（主工作流接管，哪怕处理得不完美），也不要把无关的边缘补丁错套上去。
+
+两种检测模式都行：
 
-## 检测机制
+- **便宜的确定性匹配**：基于文档文本的正则或关键词指纹。快，每份文档都能跑。
+- **基于 embedding 的相似度**：对文档里规则相关的区域算 embedding，和已登记的边缘案例 embedding 做相似度比对。能抓住正则抓不到的语义相似性，但成本高。
 
-在标准工作流执行**之前**，对每份文档运行边缘案例检测：
+早期规则、注册表条目少时，确定性检测足够。注册表大了之后，基于 embedding 的相似度更可扩展。
 
-1. 加载当前规则对应的边缘案例注册表。
-2. 对每个 `active` 状态的边缘案例，检查文档是否匹配其检测模式。
-3. 如果匹配置信度超过阈值，执行该边缘案例的特定解决方案（替代或补充标准工作流）。
-4. 记录触发了哪个边缘案例。
+匹配触发时：
 
-这个流程类似 RAG 的渐进式披露：
-- 注册表是知识库。
-- 检测模式是检索查询。
-- 置信度阈值防止误匹配。
-- 只有相关的边缘案例被加载到执行上下文中。
+1. 记录"触发了哪条边缘案例"（审计可见性）。
+2. 应用登记的解决方案。
+3. 按解决方案的指示跳过 / 补充 / 覆盖标准工作流。
 
 ### 检测效率
 
-检测必须轻量。对每份文档跑 50 个正则匹配的成本可以忽略不计，但跑 50 个 LLM 调用就不可接受了。
+检测必须轻量。每份文档跑很多个正则检查是可以接受的；跑很多个 LLM 调用就不行。
 
-优先级排序：
-1. 正则/关键词检测（毫秒级）→ 优先使用。
-2. 结构检测（秒级，需解析）→ 在解析完成后顺带检查。
-3. LLM 检测（秒级+成本）→ 仅在无法用上述方法时使用。
+优先级：
+
+1. 正则 / 关键词检测（毫秒级）→ 优先使用。
+2. 结构检测（秒级，需解析）→ 解析完成后顺带检查。
+3. LLM 检测（秒级+成本）→ 仅在前两种无法识别时使用。
 
 ## 何时添加边缘案例
 
-在演进循环中，当一个失败案例被分析后，需要决定它是系统性问题还是边缘案例。
+在演进循环里，当一个失败案例被分析后，需要决定它是系统性问题、边缘案例、还是数据质量问题。
 
 **添加为边缘案例的条件**（三个条件同时满足）：
 
-1. **非系统性**：影响不到 10% 的文档。如果影响面更广，那是工作流本身的问题，应该修复工作流。
-2. **有可辨识模式**：能描述出这类文档的共同特征，能写出检测规则。如果失败看起来是随机的、无规律的，那可能是数据质量问题，需要升级给开发者用户。
-3. **有明确解决方案**：知道怎么处理。不是"不确定"或"需要更多调查"。
+1. **标准工作流的迭代无法以合理代价容纳这份文档**。
+2. **有可辨识模式**：能描述这类文档的共同特征，能写出下次再识别它的检测规则。
+3. **解决方案明确且自包含**：知道怎么处理，不是"待调查"。
 
 **不应添加为边缘案例的情况**：
 
-- 失败影响大量文档（系统性问题，修工作流）。
-- 失败无可辨识模式（数据质量问题，报告给开发者用户）。
-- 解决方案需要改变核心判定逻辑（属于主工作流的范畴）。
+- 失败影响很多文档 —— 那不是边缘案例，是一种模式，主工作流该改。
+- 失败无可辨识规律 —— 可能是数据质量问题，升级给开发者用户。
+- 解决方案需要改变核心判定逻辑 —— 属于主工作流的范畴。
 
 ## 何时提升边缘案例
 
@@ -162,57 +145,46 @@ description: Identify, catalog, and handle corner cases that do not fit the main
 
 **提升条件**：
 
-- **出现率超过 10%**：在最近的文档批次中，超过 10% 的文档触发了该边缘案例。它已经不是"边缘"了，而是一种常见模式。
-- **模式聚类**：多个相似的边缘案例指向同一个底层问题。与其维护 5 个类似的边缘案例，不如合并为一个通用的工作流改进。
-- **开发者用户确认**："这就是常态，所有XX类型的文档都是这样"——开发者用户的领域知识是最权威的提升依据。
+- **大量文档都触发**：在最近的文档批次里，许多文档都触发了这条边缘案例。它已经不是"边缘"了，而是一种常见模式。
+- **模式聚类**：多条相似的边缘案例指向同一个底层问题。与其维护几条相似条目，不如合并为一次通用的工作流改进。
+- **开发者用户确认**："这就是常态，所有 XX 类型的文档都是这样" —— 开发者用户的领域知识是最权威的提升依据。
 
 **提升操作**：
-1. 将解决方案整合到主工作流中。
-2. 在注册表中将状态改为 `promoted`。
-3. 对两个变更做版本记录。
+
+1. 把解决方案整合到主工作流里。
+2. 注册表中状态改为 `promoted`。
+3. 对两个变更都做版本记录。
 4. 在下一批文档上验证提升后的工作流仍然正确。
 
 ## 人类可见性
 
 边缘案例注册表必须对开发者用户透明可读：
 
-### 可读性要求
-
 - **格式清晰**：JSON 或 markdown 表格，人可读。
 - **上下文充分**：领域专家无需阅读代码就能理解每条记录。
 - **在仪表板中展示**：新发现的边缘案例应出现在报告中。
 
 ### 开发者用户可添加
 
-开发者用户往往掌握编程智能体尚未遇到的边缘案例知识。他们应该能够添加类似这样的条目：
+开发者用户往往掌握编程智能体尚未遇到的边缘案例知识。他们应能添加类似条目：
 
-- "XX银行的 Q4 报告总是使用不同的模板。"
-- "2020年以前的公募基金文档遵循旧版信息披露规定。"
+- "XX 银行的 Q4 报告总是用不同模板。"
+- "2020 年以前的公募基金文档遵循旧版信息披露规定。"
 - "小型农商行的贷款合同经常缺少标准条款编号。"
 - "境外分行的报告中金额以美元计，不是人民币。"
 
-这些输入是宝贵的预防性信息，能避免未来的核查失败。在注册表中为手动添加的条目标注来源为"开发者用户"。
+这些输入是宝贵的预防性信息。注册表里给手动添加的条目标注来源为 "开发者用户"。
 
 ## 成本控制
 
-每个边缘案例都有运行时成本：检测逻辑在每份文档上都要执行。保持注册表精简：
-
-### 精简原则
+每条边缘案例都有运行时成本：检测逻辑在每份文档上都要执行。保持注册表精简：
 
-- **清理废弃条目**：已提升或不再出现的边缘案例，将状态改为 `deprecated`。定期清理。
-- **合并相似条目**：如果有 5 个边缘案例都在处理"日期格式变体"，合并为一个带更广泛检测模式的条目。
-- **检测模式高效化**：优先用正则而非 LLM 检测。一个正则匹配耗时微秒，一个 LLM 调用耗时秒级。
-- **监控规模**：如果单条规则的边缘案例超过 50 个，这说明工作流本身需要改进。大量边缘案例是工作流不够健壮的信号。
+- **清理废弃条目**：已提升或不再出现的边缘案例，状态改为 `deprecated`，定期清理。
+- **合并相似条目**：若有多条边缘案例都在处理"日期格式变体"之类的事，合并为一条更宽泛的检测模式。
+- **检测模式高效化**：优先用正则而非 LLM 检测。
+- **监控规模**：当单条规则的边缘案例数量明显变大时，这其实是工作流本身需要改进的信号 —— 这些"边缘"里可能很多该被提升到主流程。
 
-### 定期审查
-
-每隔若干个演进周期，审查一次边缘案例注册表：
-- 还有哪些是活跃的？
-- 有没有可以合并的？
-- 有没有应该提升的？
-- 有没有已经过时的？
-
-保持注册表的"新陈代谢"。一个不断膨胀的注册表和一个从不更新的注册表一样有害。
+定期审查注册表：还在活跃的有哪些？有可合并的吗？有可提升的吗？有过时的吗？保持注册表的新陈代谢。一个不断膨胀的注册表和一个从不更新的注册表一样有害。
 
 ## 与演进循环的协作
 
@@ -228,9 +200,4 @@ description: Identify, catalog, and handle corner cases that do not fit the main
   └─ 数据质量问题 → 报告给开发者用户
 ```
 
-每次演进循环运行后，检查是否有新的边缘案例需要添加，以及现有边缘案例是否需要状态变更。
-
-边缘案例注册表的增长曲线本身就是系统健康度的指标：
-- 初期快速增长是正常的（你在发现文档的多样性）。
-- 中期增速放缓说明工作流趋于稳定。
-- 后期仍在快速增长则说明工作流可能存在根本性设计问题。
+每次演进循环跑完，检查是否有新的边缘案例需要添加，以及现有边缘案例是否需要状态变更。

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

@@ -1,242 +1,137 @@
 ---
 name: cross-document-verification
 tier: meta
-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.
+description: 建立"跨文档核查的 rule-skill / workflow"——即判定依赖于多份文档中事实的规则。在编写或蒸馏一条需要跨文档比对实体/数值的规则时使用（主合同 + 附件、贷款申请 + 收入证明 + 银行流水 + 征信报告等）。涵盖：规则定义里必须明确的几个锚点（源文档 → 实体 → 目标文档 → 实体 → 一致性等级）、由此生成的 check.py / workflow 怎么遍历一个 case、要处理的矛盾类型、严重性分级。和 `compliance-judgment`（单文档规则）区分——KC 是 builder，不是 executor。
 ---
 
-# 跨文档交叉核验——案件级分析
+# Cross-Document Verification —— 构建跨文档规则
 
-单文档核查回答的是「这份文件合不合规」。跨文档交叉核验回答的是一个完全不同的问题：**这笔交易的所有文件，讲的是不是同一个故事？**
+KC 在这个阶段的工作是**构建**跨文档核查规则，**不是**在运行时执行跨文档检查。最终交付物是一条 rule-skill / workflow，将来可以被 KC 或下游系统应用到任何 case。
 
-这是文件检查员和案件分析师的区别。检查员一份一份看文件，每份独立判定。分析师把这笔交易的全部材料摊在桌上，找到贯穿其中的线索——或者找到相互矛盾的破绽。启用跨文档核验，就是把系统从「逐文件检查」升级为「案件级分析」。
+如果一条规则的判定依赖多份文档中的事实，这一事实就必须显式编码到规则本身。你不能写一个单文档 check.py，然后期望跨文档核查在生产时凭空发生。
 
-在实际信贷业务中，三查制度（贷前调查、贷中审查、贷后检查）的每一个环节都涉及多文档交叉比对。贷前调查要交叉验证借款人提供的各项材料是否一致；贷中审查要核实合同条款与审批条件是否吻合；贷后检查要比对实际用途与贷款申请书中的声明。跨文档核验是三查制度在自动化系统中的落地。
+## 规则定义里必须写清楚什么
 
-## 案件概念
+对一条跨文档规则来说，目录条目仅有 description + falsifiability_statement 不够。它需要一条**显式的跨文档路径**：
 
-案件是指同一笔交易、同一个借款人或同一笔业务相关的全部文档集合。案件中的文档共享实体：姓名、日期、金额、证件号码。这些共享实体就是交叉比对的锚点。
+1. **起始文档类型**：从哪类文档开始？怎么把一份文档判定为这类？（比如"贷款申请表"、"主合同"、"年度信息披露报告"）
+2. **起始文档中的锚点实体**：先抽什么？（申请人 ID、借款人姓名、合同编号、申报总金额等）
+3. **目标文档类型**：要跨核到哪类文档？在同一个 case 里怎么定位目标文档？（共享 anchor、命名模式、起始文档里的显式引用）
+4. **每个目标文档中的目标实体**：从目标文档里抽什么来比？字段名不一定相同 —— "月收入"在申请表上、"月均存款"在银行流水上。
+5. **PASS 的一致性等级**：在什么条件下我们判定为一致？精确相等？容差内相等？合理性检查（在另一个值的某个倍数范围内）？互引存在？
+6. **FAIL 是什么样**：硬冲突、软矛盾、还是缺失互引 —— 各自带什么严重性。
 
-### 模式一：主合同 + 补充协议 + 附件
+少了这五个锚点，规则就只是个愿望。有了这些，生成的 check.py 才能确定性地遍历 case。
 
-同一出具方，有正式的交叉引用关系。这是团队经验最丰富的场景。
+## 与 `compliance-judgment` 的分工
 
-典型文档集：
-- 主合同（借款合同/授信合同）
-- 补充协议（利率调整、还款方式变更）
-- 附件 A：抵押物清单
-- 附件 B：还款计划表
-- 附件 C：担保函
+`compliance-judgment` 处理单文档规则：读一份文档，应用规则，给出 verdict。判定可以是正则、确定性 Python、或 LLM 增强 —— 但输入是 **一份**文档。
 
-常见问题：
-- 主合同约定贷款总额 500 万，但附件 B 还款计划表的本金合计为 485 万
-- 主合同引用「详见附件 D」，但附件 D 不存在或已替换为其他版本
-- 补充协议修改了利率，但附件 B 的还款计划未同步更新
-- 主合同甲方名称「深圳XX有限公司」，附件中写成「深圳XX有限责任公司」
+本 skill 处理**输入是一个 case**（一组相关文档）的规则。这类规则的 check.py：
 
-### 模式二：多来源材料包
+- 接收 case 级结构（文档列表 + 元数据），不是单份文档。
+- 在相关文档上跑实体抽取。
+- 为这条规则构建必要的对比矩阵（只包含这条规则关心的字段，不是 "所有实体 × 所有文档"的通用矩阵）。
+- 应用规则定义里写明的一致性检查。
+- 返回 verdict 加上驱动结论的矩阵单元（证据）。
 
-不同出具方、不同格式，指向同一借款人。
+KC 是**构建者**，构建这个 check.py / workflow，不是运行时执行者。下面的内容讲的是要设计什么，不是运行时要做什么。
 
-典型文档集：
-- 贷款申请书（借款人填写）
-- 收入证明（用人单位出具）
-- 银行流水（银行出具，6个月或12个月）
-- 征信报告（人民银行征信中心）
-- 房产评估报告（评估机构出具）
-- 营业执照/统一社会信用代码证（市场监管部门）
+## 要面向的 case 模式
 
-常见问题：
-- 申请书填写月收入 8.5 万，收入证明写 8.2 万，银行流水月均入账仅 4.3 万
-- 申请书上的身份证号与征信报告中的不一致（一位数字之差）
-- 收入证明的入职日期与征信报告中的雇主信息时间线不吻合
-- 房产评估报告中的产权人与贷款申请人不是同一人
+两种模式覆盖了大多数跨文档规则：
 
-两种模式中，共享实体都是锚点。每个在两份以上文档中出现的实体，都是交叉核验的候选对象。
+1. **主合同 + 附件**。同一签发方，正式互相引用。主合同写总额，附件列明分项。要预期的问题：总额和分项加总不一致、引用的附件缺失或过期、主文与附件版本不匹配。
 
-## 构建比对矩阵
+2. **多源捆绑**。贷款申请 + 收入证明 + 银行流水 + 征信报告 + 评估报告。不同签发方、不同格式、同一借款人/case。要预期的问题：身份信息在多份文档间漂移（姓名拼写、雇主名变体）、数值矛盾（申报收入 vs 实际收入）、可疑的一致性（多份文档版式 / 用语一致 → 可能是伪造）。
 
-比对矩阵是跨文档核验的核心工件。行是共享字段，列是来源文档，单元格是该文档中该字段的提取值。
+编写规则时点明它针对的是哪种模式。两种模式下 check.py 的形状不同 —— 主合同 + 附件这种期望正式引用和互引；多源捆绑这种期望做归一化（跨格式的实体协调）。
 
-### 贷款案件示例矩阵
+## 矛盾分类（规则可能需要检测的）
 
-| 字段 | 贷款申请书 | 收入证明 | 银行流水 | 征信报告 | 房产评估 |
-|------|-----------|---------|---------|---------|---------|
-| 申请人姓名 | 张伟 | 张伟 | 张伟 | 张伟 | 张伟（产权人）|
-| 身份证号 | 310101199001011234 | 310101199001011234 | — | 310101199001011234 | 310101199001011234 |
-| 月收入 | 85,000 | 82,000 | 月均入账 43,000 | — | — |
-| 工作单位 | ABC科技有限公司 | ABC科技有限责任公司 | — | ABC科技 | — |
-| 入职时间 | 2019年3月 | 2019年6月 | — | 2019年 | — |
-| 贷款金额 | 350万 | — | — | — | — |
-| 房产估值 | 约500万 | — | — | — | 512万 |
+跨文档规则可能需要标记其中一类或多类：
 
-### 合同案件示例矩阵
+### 硬冲突
+应跨文档完全一致的字段出现精确不匹配。
+- 身份字段不匹配（姓名、ID、出生日期）。
+- 容差以外的金额不匹配（总额、分项、申报收入）。
+- 应一致的日期不匹配（生效日期、签署日期）。
 
-| 字段 | 主合同 | 补充协议 | 附件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` 的输出填充矩阵。空白单元格表示该文档中未找到该字段——这是缺失，不一定是错误。但应该存在却缺失的字段本身就是一个发现。
+### 软矛盾
+没有直接冲突，但**放在一起看不合理**的数值。
+- 申报月收入是某水平，但银行流水月均存款显著低于此。
+- 评估价接近贷款金额（高 LTV —— 技术上可行，但是信号）。
+- 不同文档间出现多月的就业起始日差距。
 
-### 身份证号18位校验
+软矛盾需要阈值和判断。它们是**发现**，不是判定 —— 规则需要明确：触发 FAIL，还是 WARNING，还是仅作为证据收集供下游复核。
 
-中国居民身份证号码为18位，最后一位为校验码。提取后应进行校验码验证：
-- 如果校验码不正确，标记为 error（可能是OCR识别错误或伪造）
-- 跨文档比对时要求18位完全一致，零容差
+### 互引失败
+正式联结文档内部的结构完整性问题。
+- 主合同引用"附件 B —— 还款计划"，但附件 B 缺失或标题不同。
+- 附件引用主合同某个不存在的条款。
+- 缺失互引：附件引用了主合同，但主合同里没列附件。
+- 版本不匹配：主合同某日期签署，附件晚得多的日期签署且条款不同。
 
-### 统一社会信用代码
+字段级分类（带容差和严重性模板）见 `references/contradiction-taxonomy.md`，规则设计者可以借用。
 
-企业法人的统一社会信用代码为18位字母数字组合。跨文档比对时：
-- 要求18位完全一致
-- 注意区分大写字母O和数字0，大写字母I和数字1（OCR常见错误）
-- 可通过校验位验证代码合法性
+## 严重性分级（由规则决定）
 
-## 矛盾类型
+不是所有矛盾权重相同。规则必须说明它的发现如何映射到严重性：
 
-### 硬矛盾（Hard Contradiction）
+| 严重性 | 典型例子 |
+|--------|----------|
+| Critical | 身份字段不匹配（多份文档间 ID 不同） |
+| High | 显著的金额数值差异 |
+| Medium | 日期或就业细节不匹配 |
+| Low | 格式 / 缩写差异（"ABC Corp" vs "ABC Corporation"） |
 
-必须完全一致的字段出现了不一致：
+具体阈值取决于业务领域。开发者用户按字段配置；规则设计应给配置留出空间，而不是把百分比写死在规则里。
 
-- **身份信息不一致**：姓名拼写不同、身份证号位数不对、出生日期矛盾。在中国信贷业务中，身份证号是最核心的锚点——一个数字的差异就意味着不是同一个人，或者存在录入/OCR错误。
-- **金额不一致**：主合同载明贷款金额 500 万，但还款计划表本金合计 485 万。收入证明写月薪 8.2 万，但申请书填了 8.5 万。
-- **日期不一致**：主合同生效日期为 2024-01-15，但某附件标注生效日期为 2024-02-01。
+## 规则可以揭示的欺诈信号
 
-硬矛盾是二元的——在定义的容差范围内，要么一致，要么不一致。
+有些模式只有在 case 层面才能看到：
 
-### 软矛盾（Soft Contradiction）
+- **跨文档的一致小幅差异**：每份文档都"夸大约 5%"、每个日期都精确平移一个月。这种一致性错误暗示有协调的伪造，不是诚实的笔误。
+- **可疑的文档一致性**：声称来自不同签发方的多份文档，使用相同版式、相同措辞、甚至相同的错别字。
+- **数值卡在监管阈值上**：LTV 正好压着上限，DTI 正好压着上限。一次是巧合；case 上的模式就是信号。
+- **时间上的不可能**：收入证明早于就业起始日；银行流水覆盖账户开立之前的期间；评估报告日期晚于贷款发放。
 
-数值没有直接矛盾，但放在一起看不合理：
+如果规则的工作包含这些之一，就编码进去。这些是**升级信号**，不是结论 —— 规则应输出"已标记"加证据，由开发者用户或下游复核流程做最终判定。
 
-- 收入证明月薪 10 万，但银行流水月均入账只有 5 千——技术上可能（工资发到别的账户），但高度可疑。
-- 房产评估价 300 万，贷款金额 280 万（LTV 93%）——没超过上限，但接近极限。
-- 申请书写入职时间 2019 年 3 月，收入证明写 2019 年 6 月——3 个月的差异可能是四舍五入，也可能是编造。
-- 征信报告显示负债率 48%，而本次贷款如获批将把负债率推到 52%——审批时在红线以下，放款后突破红线。
+## 在 check.py 里怎么"走" case
 
-软矛盾需要阈值和判断。它们是发现，不是结论。
+一条跨文档规则的 check.py 通常这样工作：
 
-### 交叉引用失败
+1. 接收 case（文档路径/句柄列表 + 分类元数据）。
+2. 选出规则声明的**起始文档类型**对应的文档。
+3. 用 entity-extraction 抽出**锚点实体**。
+4. 通过锚点或正式引用在 case 中定位**目标文档**。
+5. 从每份目标文档抽出**目标实体**。
+6. 应用规则写明的一致性检查。
+7. 返回：
+   - verdict（PASS / FAIL / WARNING / NOT_APPLICABLE）
+   - 证据（驱动结论的对比矩阵单元，带来源文档 + 页码引用）
+   - confidence（按 `confidence-system`）
 
-正式关联文档之间的结构性完整性问题：
+对比矩阵是规则专属的 —— 只放这条规则需要的字段。建一个通用的 "所有实体 × 所有文档"矩阵又贵又会污染证据。
 
-- 主合同引用「详见附件 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 判定）
+**规则 check.py 的运行时输入：**
+- case 结构（一组相关文档 + 标识）。
+- 单文档实体抽取结果（skill：`entity-extraction`）。
+- 单文档判定结果可能已经由 `compliance-judgment` 产出，可作为本规则输入的一部分。
 
 **输出：**
-- 案件级一致性报告：比对矩阵、所有发现的矛盾、严重程度分级、伪造信号标记
+- case 级 verdict + 对应的对比矩阵切片作为证据。
+
+**对接：**
+- `confidence-system`：跨文档矛盾是强信号，通常降低相关字段的置信度。
+- `evolution-loop`：规则没预见到的矛盾模式反复出现时，触发工作流改进。
+- `dashboard-reporting`：case 级视图与单文档结果并列展示。
 
-**下游衔接：**
-- `confidence-system`：跨文档矛盾降低相关字段的置信度
-- `evolution-loop`：反复出现的矛盾模式触发工作流优化
-- `dashboard-reporting`：案件视图与文档视图并列展示
+## Ground-truth 原则
 
-**基准真值原则：用户和终端用户的矛盾报告是基准真值，优先于智能体自身判断。** 当用户或终端用户报告了系统遗漏的跨文档不一致，该报告自动成为最高优先级的反馈。记录它、从中学习、据此调整检测阈值。系统的目标是捕获人类能捕获的所有问题——然后更进一步。
+当开发者用户或终端用户反馈本规则漏掉的跨文档不一致时，那条反馈优先于 agent 判定。把它记下来，作为 corner case （`corner-case-management`）或规则改进的触发点，并相应调整检测阈值。规则的工作是抓住人能抓住的 —— 然后再走远一步。