kc-beta 0.8.1 → 0.8.3

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

@@ -1,54 +1,54 @@
-# 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 |
+| 姓名 | 模糊 | 缩写、空格、敬称 | Critical | "Zhang Wei" 与 "Zhang W." 属于模糊匹配；"Zhang Wei" 与 "Li Ming" 则为硬不通过 |
+| 身份证号 | 精确 | 无（零容忍） | Critical | 一位数字之差 = 不同的人或誊抄错误——两者都是 critical |
+| 出生日期 | 精确 | 无 | Critical | 在适用情况下与身份证号编码进行交叉核对 |
+| 地址 | 模糊 | 缩写、楼层/单元的格式差异 | Medium | "Rm 1201, Bldg A" 与 "Room 1201, Building A" 可接受 |
+| 电话号码 | 精确 | 国家代码前缀 | Medium | +86 前缀的有无可容忍 |
+| 公司名称 | 模糊 | Ltd/Co/Inc 等后缀、标点 | High | 核心名称必须匹配；后缀差异可容忍 |
 
-## 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 |
+| 申报收入 | 跨文档 | 10% 相对值 | High | 申请表 vs 收入证明 vs 征信报告 |
+| 银行平均存款 | 收入可信度 | 申报收入的 50%（下限） | High | 若平均存款 < 申报收入的 50%，则标记 |
+| 贷款金额 | 跨文档精确比对 | 0.1% 相对值 | Critical | 申请表与合同中必须完全一致 |
+| 资产估值 | 评估一致性 | 5% 相对值 | High | 申请表估值 vs 正式评估报告 |
+| 现有负债 | 跨来源 | 20% 相对值 | Medium | 自报 vs 征信报告 |
+| 净资产 | 计算一致性 | 各部分之和 vs 申报总额 | High | 资产 - 负债必须等于申报的净值 |
+| 合同总额 vs 明细项 | 求和核对 | 0.01 绝对值 | Critical | 主合同总额必须等于附件明细项之和 |
 
-## 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 |
+| 入职日期 | 跨文档匹配 | 90 天 | Medium | 申请表 vs 收入证明 vs 征信报告 |
+| 合同签订日期 | 序列合理性 | 必须晚于申请日期 | High | 不能在申请前签约 |
+| 文档出具日期 | 时效与序列 | 按业务规则（通常 30-90 天） | Medium | 6 个月前出具的收入证明可能已失效 |
+| 贷款到期日 | 合同一致性 | 跨文档精确匹配 | High | 申请表 vs 合同 vs 还款计划表 |
+| 评估日期 | 序列合理性 | 必须早于贷款审批 | Medium | 放款之后才做评估属于红旗信号 |
 
-## 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.
+- **LTV 比率一致性**：资产价值 × LTV % 应等于或大于贷款金额。在评估报告、申请表与合同之间交叉核查。
+- **DTI 比率合理性**：月负债（来自征信报告）+ 拟议月供）/ 月收入（来自收入证明）不应超过申报的 DTI 或监管上限。
+- **时间线合理性**：入职日期 < 收入证明出具日期 < 申请日期 < 合同签订日期 < 放款日期。任何违反此序列的情况都是一项发现。
+- **附件完整性**：主合同中引用的每一份附件都必须出现在案件资料中；案件中每一份附件也都必须被主合同引用。
+- **担保人交叉核查**：若列有担保人，其身份字段也必须与担保人专项材料进行跨文档核查通过。
+- **金额分解**：若合同规定本金 + 利息 + 费用，三者之和必须等于其他位置列出的总义务金额。
 
-## Comparison Matrix Template
+## 比对矩阵模板
 
-Output schema for the case-level comparison matrix:
+案件级比对矩阵的输出 schema：
 
 ```json
 {

package/template/skills/zh/dashboard-reporting/SKILL.md

@@ -1,282 +1,132 @@
 ---
 name: dashboard-reporting
 tier: meta-meta
-description: Generate HTML dashboards for developer users to visualize verification results, system progress, and quality metrics. Use when a testing round completes, when production batches finish processing, when the developer user wants to see the system's status, or at any point where visual reporting would help communicate progress. Dashboards should be self-contained HTML files that can be opened by double-clicking. Also use when the developer user asks about results, accuracy, or system health.
+description: 生成 HTML 仪表盘，让开发者用户可视化核查结果、系统进度、质量指标。在测试轮次完成、生产批次跑完、开发者用户想看可视化报告，或他们明确要求时使用。仪表盘是自包含的 HTML 文件。**仅在确实有"值得可视化的东西"时使用** —— 不要当成默认交付物。日常状态汇报用 KC 的 TUI 即可。HTML 仪表盘是对直接汇报的补充，不是替代。
 ---
 
-# 可视化仪表盘生成
+# Dashboard Reporting
 
-## 仪表盘的定位
+仪表盘只是众多渠道之一 —— 而且并不总是最经济的那个 —— 让开发者用户了解情况。KC 在 TUI 里已经能直接汇报状态；HTML 仪表盘存在的理由是**值得可视化看的东西**：分布、时间线、热力图、并列对比、可钻取的表格。
 
-仪表盘是开发者用户了解系统运行状态的唯一窗口。开发者用户不应该需要打开 JSON 文件、翻阅日志目录、或者向你询问「现在准确率多少了」。一切关键信息，打开仪表盘就能看到。
+不要把生成仪表盘当成"满足这条 skill"的打卡项。把它当成开发者用户真要的交付物，或者一张图确实比读 TUI 输出 / JSON 更省时间的场景。
 
-仪表盘生成是一个服务性技能——在其他技能完成工作后，由你主动生成或由开发者用户按需要求生成。
+## 最低限 vs 锦上添花
 
-## 三类仪表盘
+开发者用户要仪表盘时，**先做到最低限，能真带来价值再扩展**。
 
-### 一、核查结果仪表盘（Results Dashboard）
+### 最低限
 
-展示某一批次或某一时间段的单据核查结果。
+一份够用的仪表盘的底线：
+- 一个汇总头：总文档数，顶层 通过 / 失败 / 缺失 数。
+- 一张按规则汇总的表：rule_id、准确率、pass / fail / NA 计数，可选的置信度列。
+- 一份失败 case 的列表，用户能点开看详情（规则、抽取值、期望值、 comment）。
 
-#### 必须包含的内容
+够发了。开发者用户能在 3 秒内回答"这一批健不健康，哪些规则出了问题"，最低限就达成。
 
-**总览区域**：
-- 本批次处理的单据总数
-- 各规则的通过率、不通过率、无法核查率
-- 高置信度/中置信度/低置信度的分布
+### 锦上添花
 
-**按规则明细**：
-- 每条规则的独立准确率
-- 每条规则最常见的不通过原因（Top 3）
-- 每条规则的平均置信度
+下面这些只在数据或用户需求确实证明合理时才加：
+- 置信度分布直方图（在置信度已经校准、用户在意分布形状时才有用）。
+- 准确率随时间的折线图（只有累积了足够的历史能画出有意义曲线时才有用）。
+- 按产品类型 / 按签发方的分项（语料有明显分群时才用）。
+- 成本指标（成本是当下关切时才用，否则跳过）。
+- 钻取导航（汇总 → 规则 → 文档）。
+- 内嵌反馈控件（点击改值、一键标记错误）。
 
-**失败案例清单**：
-- 判定为「不通过」的案例列表
-- 每个案例的关键字段摘要、不通过原因、置信度
-- 可按规则、按置信度、按不通过原因筛选
+不要为了显得周到而加一节。一张空的"置信度分布"图（背后根本没有校准过的数据）比没有图更糟。
 
-**置信度分析**：
-- 置信度分布直方图
-- 低置信度案例的高亮标注
-- 置信度与实际准确率的校准分析（如有质控数据）
+## 仪表盘类型（什么时候用哪种）
 
-### 二、系统进展仪表盘（Progress Dashboard）
+### 结果仪表盘
+处理完一批文档后。上面的最低限通常就够了。
 
-展示整个核查系统的建设进度，覆盖从规则提取到生产部署的全生命周期。
+### 进度仪表盘
+按需生成，展示系统跨阶段演化。每条规则的生命周期状态、规则目录表、演化时间线。多在开发者用户想要"现在到哪了"的中段快照时有用。
 
-#### 必须包含的内容
+### 质量仪表盘
+QC 复核周期结束后。准确率趋势、抽样率走势、待处理标记、成本。在 QC 已经跑了足够多周期、能画出趋势时才有用。
 
-**生命周期总览**：
-- 规则总数及各阶段分布（已提取、技能已编写、技能已测试、工作流已蒸馏、工作流已测试、已投产）
-- 用进度条或甘特图形式展示
+如果当下只有一种对开发者用户真正有帮助，就只做那一种。不要默认三种都生成。
 
-**演化循环时间线**：
-- 每条规则的迭代轮次和当前准确率
-- 从第一轮到最新一轮的准确率变化趋势
-- 标注关键事件（如「达到阈值」「触发回退」「开发者用户确认」）
+## 反馈采集（在适用时是锦上添花）
 
-**阻塞事项**：
-- 达到 `MAX_ITERATIONS` 仍未达标的规则
-- 等待开发者用户确认的模糊事项
-- 缺少测试样本的规则
-
-### 三、质量监控仪表盘（Quality Dashboard）
-
-展示生产环境中的质量指标趋势。
-
-#### 必须包含的内容
-
-**准确率趋势**：
-- 每条规则的准确率随时间的变化曲线
-- 阈值线的标注（`WORKFLOW_ACCURACY`）
-- 低于阈值的时间段高亮
-
-**抽样率变化**：
-- 各规则当前的质控抽样比例
-- 抽样比例的变化历史（体现从全量到抽样的信心积累过程）
-
-**成本追踪**：
-- 每条规则的平均核查成本
-- 按模型层级的成本分布
-- 总成本趋势
-
-**异常警报**：
-- 准确率下降的规则（红色标注）
-- 置信度漂移的规则（黄色标注）
-- 成本异常的规则
-
-## 用户反馈收集
-
-每个仪表盘必须内置用户反馈机制，让用户可以直接在核查结果上报告错误和添加评论。用户反馈是系统中最有价值的数据来源，不是可选功能。
+当仪表盘要给会真去复核结果的人看时（开发者用户、终端用户、领域专家），加上反馈控件。当仪表盘只是开发者用户构建过程中的自查工具时，反馈控件通常多余 —— 它假装存在一个用户根本不打算走的流程。
 
 ### 开发者用户反馈
 
-开发者用户能看到完整的结果明细。他们的反馈界面应支持：
-- **字段级修正**：点击某个提取值，输入正确的值。
-- **结果覆盖**：将通过改为不通过（或反之），并附理由。
-- **规则重评估请求**：标记某条结果，要求用不同方式重新处理。
-- **自由评论**：对任何结果添加文本注释。
+能看到完整结果细节。有用的控件：
+- 字段级修正：点抽取值，给出正确值。
+- 结果覆盖：把 pass 改为 fail（或反过来），带理由。
+- comment：自由文本注释。
 
 ### 终端用户反馈
 
-核查应用的终端用户看到的是简化结果。他们的反馈界面应支持：
-- **一键标记错误**：一次点击即可报告他们认为不正确的结果。
-- **添加评论**：简要文字说明他们认为哪里有误。
-- **严重程度**：这个错误的影响有多大？（严重 / 重要 / 轻微）
-
-### 反馈即基准真值
-
-用户报告的错误即基准真值。它们的优先级高于编程智能体的判断和 Worker LLM 的输出。反馈数据流转如下：
-
-1. 用户在仪表盘上提交反馈 → 存储为结构化记录。
-2. 记录格式：`{result_id, trace_id, reporter_role, feedback_type, original_result, corrected_value, comment, timestamp}`。
-3. 反馈记录作为已确认的失败案例，输入 `evolution-loop` 演化循环。
-4. 仪表盘展示反馈趋势：修正率随时间变化、最常被报告的问题、用户修正率最高的规则。
-
-例如：信贷审批场景中，业务人员发现某笔贷款的担保物估值被提取错误，一键标记后，该修正自动进入下一轮演化循环的失败案例池，驱动规则改进。
-
-反馈收集机制与仪表盘生成是一体的，不是独立功能。每个生成的 HTML 仪表盘都应包含反馈 UI，即使最初只是将反馈写入本地 JSON 文件，由编程智能体在下次迭代时读取。
-
-## 技术规范
-
-### 自包含 HTML
-
-仪表盘必须是单个 HTML 文件，不依赖任何外部资源：
-
-- CSS 内联（`<style>` 标签）
-- JavaScript 内联（`<script>` 标签）
-- 不引用任何 CDN 资源
-- 不需要启动任何服务器
-- 双击文件即可在浏览器中打开
-
-### 不依赖第三方库
-
-所有图表和可视化使用原生 HTML/CSS/JavaScript 实现：
+只能看到简化结果。有用的控件：
+- 一键标记错误。
+- comment：简要文本说明。
+- 严重性指示：关键 / 重要 / 次要。
 
-- 进度条：CSS `width` 百分比
-- 柱状图/条形图：CSS Flexbox 或 Grid + `div` 高度百分比
-- 折线图：SVG `<polyline>` 或 `<path>`
-- 饼图：SVG `<circle>` 的 `stroke-dasharray`
-- 表格：原生 `<table>` + CSS 样式
+### 反馈即 ground truth
 
-不要引入 Chart.js、D3.js、ECharts 等库。保持零依赖。
+用户报错就是 ground truth，覆盖 agent 判定和 worker LLM 的输出。流转：
 
-### 响应式布局
+1. 通过仪表盘提交 → 存为结构化记录。
+2. Schema：`{result_id, trace_id, reporter_role, feedback_type, original_result, corrected_value, comment, timestamp}`。
+3. 记录喂入 `evolution-loop` 作为已确认的失败。
+4. 后续仪表盘里呈现反馈趋势（纠正率随时间变化、最被报错的问题、纠正率最高的规则）。
 
-仪表盘应在不同屏幕尺寸下可用：
+## 技术约束
 
-- 桌面端（1200px+）：多列布局
-- 平板端（768px - 1200px）：两列布局
-- 手机端（< 768px）：单列布局
+自包含的 HTML，内嵌 CSS / JavaScript。
+- **零外部依赖**。无 CDN、无 npm、无服务器。全部内联。
+- **不依赖服务器**。开发者用户双击 HTML 文件即可打开。
+- **响应式布局**。桌面和移动端都能用。
+- **暗 / 亮模式**：遵循系统偏好或提供切换。
 
-使用 CSS Media Query 实现响应式。
-
-### 深色/浅色模式
-
-支持系统级的深色/浅色模式切换：
-
-```css
-@media (prefers-color-scheme: dark) {
-  :root {
-    --bg-primary: #1a1a2e;
-    --bg-secondary: #16213e;
-    --text-primary: #e8e8e8;
-    --text-secondary: #a0a0a0;
-    --accent-green: #4ade80;
-    --accent-red: #f87171;
-    --accent-yellow: #fbbf24;
-  }
-}
-
-@media (prefers-color-scheme: light) {
-  :root {
-    --bg-primary: #ffffff;
-    --bg-secondary: #f3f4f6;
-    --text-primary: #1f2937;
-    --text-secondary: #6b7280;
-    --accent-green: #16a34a;
-    --accent-red: #dc2626;
-    --accent-yellow: #d97706;
-  }
-}
-```
+图表用内联 SVG，或把轻量图表库以 `<script>` 标签内联。
 
 ## 数据来源
 
-仪表盘的数据从以下位置读取（由生成脚本在生成时内嵌到 HTML 中）：
-
-| 数据类型 | 来源路径 |
-|---------|---------|
-| 核查结果 | `Output/*/results.json` |
-| 质控评审 | `logs/qc/reviews/*.json` |
-| 演化日志 | `logs/evolution/*/iteration_*.json` |
-| 版本信息 | `versions.json` |
-| 准确率趋势 | `logs/qc/trends.json` |
-| 规则目录 | `rule-catalog.json` |
-| 成本数据 | 从工作流日志中汇总 |
-
-数据以 JavaScript 变量的形式嵌入到 HTML 文件头部：
-
-```html
-<script>
-const DASHBOARD_DATA = {
-  generated_at: "2025-04-01T20:00:00Z",
-  batch_id: "BATCH-2025-04-01",
-  results: [...],
-  qc_reviews: [...],
-  trends: {...}
-};
-</script>
-```
-
-## 生成触发时机
-
-### 自动触发
-
-- 每轮测试完成后（演化循环中）→ 生成进展仪表盘
-- 每批次处理完成后 → 生成结果仪表盘
-- 每次质控评审完成后 → 更新质量监控仪表盘
+仪表盘读取：
+- `Output/` 的核查结果。
+- `logs/` 的演化与测试历史。
+- `versions.json`（或 git log）的当前系统状态。
+- QC 复核记录（与 `Output/` 并列存放）。
 
-### 手动触发
+生成脚本应接收输入路径，输出单个 HTML 文件。
 
-开发者用户随时可以要求生成仪表盘。常见的请求方式：
-- 「给我看一下现在的进展」
-- 「生成一下结果报告」
-- 「准确率怎么样了」
+## 生成时机
 
-无论请求如何措辞，都应生成对应类型的仪表盘。
+什么时候生成：
+- 测试轮次完成，并且有足够数据值得可视化时。
+- 生产批次结束，并且开发者用户想看可视化时。
+- QC 复核周期完成时。
+- 开发者用户明确要求时。
 
-## 仪表盘文件命名与存放
+不要在每个小事件后都自动生成 —— 仪表盘会迅速堆积，用户大部分都不会打开。不确定时，**问一下用户**（"要不要我生成一份仪表盘？"），而不是不问就生成。
 
-```
-dashboards/
-├── results_2025-04-01_batch01.html
-├── progress_2025-04-01.html
-├── quality_2025-04-01.html
-└── latest/
-    ├── results.html          # 最新结果仪表盘的软链接/副本
-    ├── progress.html         # 最新进展仪表盘的软链接/副本
-    └── quality.html          # 最新质量仪表盘的软链接/副本
-```
-
-`latest/` 目录下始终保留最新版本，方便开发者用户快速访问。
+生成的仪表盘存到 `Output/dashboards/`，文件名带时间戳留作历史。
 
 ## 设计原则
 
-### 先总后分
-
-仪表盘打开后，开发者用户首先看到的是一句话总结：
-
-```
-本批次共处理 50 份单据，综合准确率 92.3%，全部规则均达标。
-```
-
-或者：
-
-```
-⚠ 本批次 R003 规则准确率 (78%) 低于阈值 (85%)，已触发演化循环。
-```
-
-总结之后再展开细节。
-
-### 色彩编码
-
-- 绿色：达标、通过、正常
-- 黄色：接近阈值、需关注、中等置信度
-- 红色：低于阈值、不通过、异常
-
-### 可操作性
+- **汇总在前**。开发者用户应能在 3 秒内看清健康状况。
+- **按需钻取**。汇总 → 规则级 → 文档级。不要一次性堆细节。
+- **配色**：绿色 = 通过/健康，红色 = 失败/严重，黄色 = 警告/需关注。简单且通用。
+- **可行动**。每条标记的问题都建议下一步该做什么。
 
-仪表盘不只是展示数据，还应提供操作建议：
+`scripts/generate_dashboard.py` 是一个起步脚本。按具体场景改写 —— 当一半 section 都没有内容可放时，删掉那一半。一份能回答用户问题的小仪表盘，胜过一份用户不需要的"全面"仪表盘。
 
-- 「R003 建议重新运行演化循环」
-- 「R001 已连续 5 个批次达标，建议将抽样比例从 50% 降至 20%」
-- 「3 条模糊规则待确认，请查看详情」
+## 与 TUI 汇报的分工
 
-### 生成时间戳
+KC 的 TUI 本身就支持在运行时做丰富的状态汇报。TUI 用来：
+- 持续的进度叙述。
+- 每个阶段的小结。
+- 快速的"刚才发生了什么"。
+- 一切能用几行文字说清楚的事。
 
-每个仪表盘底部显示生成时间，避免开发者用户看到过时的数据而不自知：
+HTML 仪表盘用来：
+- TUI 容纳不了的视觉产物（分布、图表、可筛选表格）。
+- 交付给非 KC 用户（开发者用户事后复核、终端用户群体）。
+- 需要持久保留、回头再看的记录。
 
-```
-仪表盘生成时间：2025-04-01 20:00:00 | 数据范围：2025-04-01 批次 #01
-```
+不确定时优先用 TUI。一条用户已经在读的简短状态消息，胜过一份还要他去打开的仪表盘。

package/template/skills/zh/dashboard-reporting/scripts/generate_dashboard.py

@@ -107,7 +107,7 @@ def generate_html(summary: dict, per_rule: dict, failed_cases: list[dict]) -> st
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>KC Reborn — Verification Dashboard</title>
+<title>KC — Verification Dashboard</title>
 <style>
     :root {{ --bg: #1a1a2e; --surface: #16213e; --text: #e0e0e0; --accent: #4caf50; --warn: #ff9800; --err: #f44336; }}
     @media (prefers-color-scheme: light) {{

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

@@ -224,6 +224,19 @@ debug/
 
 当出问题时，你可以独立检查每个阶段：章节切分错了？看 `_02`。提取对了但判定错了？对比 `_03` 和 `_04`。原始文本就是乱码？看 `_01`。没有中间结果，你只能盯着最终输出猜测。保留至少当前迭代的中间结果。
 
+## 当语料装不进你的脑子时
+
+要预先规划的一个根本约束：你有有限的上下文窗口。连着读几十份样本文档，会在你读完之前就把早期的观察挤出工作记忆，留给你"我看过整套语料"的印象但其实没有归纳能力。
+
+把语料当成统计学家眼中的总体来对待：抽样、汇总、不要试图把整个总体塞进脑子里。几种在实践中有效的做法：
+
+- **把文件系统当记忆用**。一边扫一边写 `notes/data_observations.md` （或者按规则维度写 `notes/<rule_id>_observations.md`）。记录字段命名变体、格式怪癖、缺失章节的模式、出人意料的取值。下一次会话打开笔记重读，而不是重新扫一遍文档。
+- **每条规则一个 notepad / memory.md**。为每条规则维护一份简短的 `memory.md`，记录"我在样本集里就这条规则看到了什么" —— 哪些文档会触发它、出现了哪些取值、有哪些边缘情形。增量更新，而不是每次看这条规则都从头推导一遍。
+- **派 subagent 去扫样本**。语料规模较大时，让一个 subagent（通过 `agent_tool`）去扫某个目录，回来给你一份汇总统计或一份简短的 markdown 报告。subagent 把完整的文件读取留在自己的上下文里，你只收到摘要。这个工具用得正是时候 —— 否则你会为了一个观察消耗大量上下文去读几十份文件。
+- **统计 / 元视图优先于逐份阅读**。与其去读 20 份收入证明，不如对它们跑一遍正则统计格式变体。与其打开每份年报，不如先列文件名按签发方 / 年份分组。先建好元视图，再深入有代表性的几份。
+
+原则：目标是**足够多的样本来刻画分布**，而不是足够多的样本来背诵语料。前者装得进脑子也装得进笔记。后者装不下。
+
 ## 集成
 
 数据体感的观察结果应直接输入下游技能：

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

@@ -2,39 +2,115 @@
 name: document-chunking
 tier: meta
 description: >
-  Fast, cheap chunking for processing batches of sample and input documents.
-  Use when you need to split documents into manageable pieces for initial observation,
-  data sensibility checks, or feeding to extraction workflows. Not for production
-  verification chunking — for that, use tree-processing to design a tailored chunking script.
+  把文档切成块供下游处理。在批量观察样本、给抽取工作流喂数据、或把长篇监管文档
+  切成 worker LLM 装得下的块时使用。涵盖：用于快速探索的便宜方法（按页 / 定长 /
+  按标题），以及用于结构化长文档生产级分块的"洋葱剥离"层次策略 + "楔入法"兜底
+  （借鉴 pdf2skills）。也涵盖最核心的平衡问题：块太大 —— 关键信息淹没在一堆草料里；
+  块太小 —— 语义连续性被打断。
 ---
 
 # 文档分块处理
 
-将文档切分为若干块，供下游环节使用。本技能提供的是快速、低成本的版本，面向样本和输入文档的批量处理，不适用于追求精度的核查工作流。
+把文档切成块供下游处理，分两套：
 
-文档分块是 KC 工作流的常见前置步骤。原始文档往往超出单次调用的上下文窗口，或包含大量与当前任务无关的内容；恰当的分块既能控制 token 消耗，又能让后续的规则匹配、抽取、合规核查在更小、更聚焦的单元上进行。本技能给出三种成本最低、最易复用的分块策略，并说明各自的适用场景。
+- **便宜分块** —— 探索性、批量处理样本时用的快速方法。
+- **层次分块** —— 长结构化文档用的"洋葱剥离"策略（借鉴 pdf2skills 方法论），加上对无标题段落的"楔入法"兜底。
 
-## 分块方法
+跨两套都最关键的问题：**块应该多大？** 见下文"找到平衡"一节再决定具体尺寸。
 
-**按页切分（Page-level splits）** — 最简单的方式。每页即为一个块。适用于大多数需要遍历文档内容的处理场景，例如初步观察样本、统计页数分布、或为每页生成摘要。这种方式不依赖文档内部结构，鲁棒性最高。
+## 便宜方法
 
-**定长分块（Fixed-size chunks）** — 按字符数或 token 数切分，相邻块之间保留重叠区域。适合构建检索索引或进行初步观察。常见参数：每块 2000–4000 字符，相邻块之间保留 200 字符重叠。重叠的作用是避免边界处的语义被切断，导致后续匹配漏检。
+**按页切分** —— 最简单的方式。每页即为一个块。适用于大多数遍历文档的场景，例如初步观察样本、统计页数分布。不依赖文档内部结构，鲁棒性最高。
 
-**按标题切分（Header-based splits）** — 识别章节标题，在标题边界处切分。这种方式能保留语义完整的章节单元，便于按条款、按章节进行规则核查。具体实现上，应根据目标文档的标题格式编写正则表达式，例如「第X条」「附录X」「X.X.X」等编号规则。
+**定长分块** —— 按字符数或 token 数切分，相邻块之间保留少量重叠。适合构建检索索引或做初步观察。重叠的作用是避免边界处的语义被切断导致后续匹配漏检。
 
-## 何时使用哪一种
+**按标题切分** —— 识别章节标题、在标题边界处切分。能保留语义完整的章节单元。前提是文档有一致的标题约定，能用正则表达。
 
-按任务复杂度选择最简单可行的方法：
+## 洋葱剥离法 —— 层次策略（长结构化文档的首选）
 
-- 批量观察样本文档 → 按页切分
-- 构建全文检索索引 → 定长分块加重叠
-- 按章节抽取条款或要点 → 按标题切分
-- 文档自带目录 → 直接解析目录得到结构
+基于标题层级的分级分解。叫"洋葱剥离"是因为你从最外层结构一层层向内剥。
 
-选择策略时要兼顾下游消费方的需求。若下游是 `worker_llm_call` 进行规则抽取，块的粒度应与单条规则的承载单元对齐；若下游是关键词检索，则块越小越精确，但召回率可能下降，需在两者之间取得平衡。
+### 工作方式
 
-## 与 tree-processing 的关系
+1. **解析文档的标题层级。** 按级别识别所有标题（H1、H2、H3 —— 或文档自身格式中的等价物："第一编"、"第一章"、"第 1.1 节"、 "第一条"）。
+2. **构建一棵树。** 每个标题是一个节点。标题之间的内容归属于最近一个上级标题所在节点。
+3. **检查大小。** 遍历整棵树。若某个节点的内容（包括其所有子节点）在处理上限以内，就停在这里 —— 这个节点就是一个分块。
+4. **必要时才拆分。** 若某节点超出上限，向下进入其子节点。只有当节点过大且确实有子标题可拆时才拆。
+5. **仍然过大的叶子节点**交给"楔入法"兜底（见下文）。
+
+### 为什么有效
+
+- 尊重文档自身的语义结构。"第三章：风险揭示"分块严格对应作者本来的章节意图。
+- 将信息损失降到最低。绝不会在一个意思的中间一刀切。
+- 产出的分块大小不一致 —— 而这是好事。一个短章节作为一个完整分块，远胜于被强行劈成两半。
+
+### 模式发现的捷径
+
+在搭建完整解析器之前，先在几份样本文档上探索结构模式：
+- 所有章节标题是否都以 "Chapter X" 或 "第X章" 开头？
+- 节号是否一致编号（1.1、1.2、1.3）？
+- 是否存在视觉标记（粗体、特定字体、横线分隔）？
+
+如果你发现了稳定的模式，基于正则的分块器比基于 LLM 的结构识别更快、更可靠。例如：
+- `^第[一二三四五六七八九十百]+章` 匹配中文章节标题
+- `^Chapter \d+` 匹配英文章节标题
+- `^\d+\.\d+` 匹配编号小节
+
+在投入使用前，对多份文档验证正则的正确性。
+
+## 楔入法 —— 兜底（无清晰标题结构时）
+
+适用于密集的法律文本、连绵的散文，或洋葱剥离后仍然过大、又没有可用子标题可拆的叶子节点。
+
+### 工作方式
+
+使用**滚动上下文窗口**，让算法对任意长度的文档都能伸缩。
+
+1. **窗口化内容。** 将剩余未处理文本中的至多 MAX_TOKENS 载入一个窗口（数值可配置；选你的 LLM 能舒服读完的大小）。
+2. **让 LLM 标出切分点。** 提示 LLM 在窗口里识别 1–3 个主题或议题发生变化的自然断点。对每个切分点，LLM 返回：
+ - `tokens_before`：切分点之前约 K 个 token（默认 K=50），逐字摘自原文。
+   - `tokens_after`：切分点之后约 K 个 token，逐字摘自原文。
+   - `chunk_title`：为切分点之前的分块写一句 5–10 字的标题。
+3. **通过模糊匹配定位切点。** LLM 引用的 tokens 与原文不会完全一致（轻微改写、空白差异、编码痕迹）。用 Levenshtein 距离找最佳匹配位置；如果 `tokens_after` 匹配不上，退回仅依据 `tokens_before` 推出的位置。
+4. **滑动并重复。** 把第一个已确认切点之前的文本切出作为一个分块。向前滑动窗口：新窗口从最后一个切点开始。重复，直到剩余文本可作为单一分块为止。
 
-本技能仅用于探索阶段和批量处理阶段的快速、低成本分块。当你需要为合规核查工作流构建生产级分块——即分块机制必须精确、稳定、可复现并以脚本形式落地时，应改用 `tree-processing` 技能。后者会根据文档的具体结构设计专门的分块脚本，并把切分逻辑沉淀为可重复运行的工件，便于在 production_qc 阶段对结果进行回溯和审计。
+### 为什么有效
+
+- LLM 识别的是语义边界，而不是任意字符位置。
+- LLM 不重新生成文本 —— 它只引用位置。没有幻觉风险。
+- 基于 K-token 引用 + Levenshtein 匹配的方法与语言无关。对中文、英文及多语种混合文档都同样适用。
+- 滚动窗口意味着任意长度的文档都能增量处理 —— 算法不受上下文窗口大小限制。
+- 模糊匹配能处理 LLM 引用文本与真实原文之间不可避免的小差异。
+
+### 何时使用
+
+- 仅在洋葱剥离法无法继续拆分（没有可用子标题）时使用。
+- 用于完全没有结构化标记的文档。
+- 成本考量：本方法需要调用 LLM。选用能完成主题边界识别的最便宜的模型即可。
+
+## 找到平衡 —— 何时停止切分
+
+两种失败模式：
+
+- **分块过大**：相关信息淹没在 LLM 上下文里的一堆草料中。即便在 LLM 的窗口之内，注意力也会在长输入上稀释 —— 块越长，真正的证据越容易被忽略。
+- **分块过小**：语义连续性断裂。一条需要"公司是银行" + "贷款额超阈值 X"两个事实合在一起才能触发的规则，可能看到它们被切到不同分块里，丢掉了关键合取关系。
+
+如何找到平衡：
+
+1. **以下游任务为锚，而非以 LLM 上下文窗口为锚。** 分块要足够大，能把下游规则所需证据完整放在一处。一条要比较两个条款的规则，这两个条款必须落在同一分块里。
+2. **优先用语义边界，而不是固定大小。** 在章节边界切的块比硬撞 target token 数中途断句的块更有用。洋葱剥离在文档自然结束的地方停止 —— 利用这一点。
+3. **用真实下游消费方做测试。** 在分块输出上跑一段抽取或判定。如果消费方漏掉了源文档里存在的证据，你的分块形状不对 —— 通常是太大或在错的地方切了。
+4. **关注方差，不止平均尺寸。** 在一堆小块里夹几个巨型块比所有块均匀分布更糟，因为信息丢失就发生在那几个巨型块里。
+5. **别盲目朝 LLM 上下文窗口尺寸去优化。** 一个 128K 上下文的模型技术上能吞 100K 的块；但能不能从这个块里精准取出证据是另一个问题。更小、边界更清晰的分块通常更胜一筹。
+
+## 实践要点
+
+- **分块大小取决于下游任务。** 给编程智能体做规则抽取时，分块可以很大。给 worker LLM 处理时，分块必须能舒服装进它的上下文，再留出 prompt + 响应的空间。
+- **保留上下文。** 拆分时把父级标题链作为上下文带上。来自"第二编
+ > 第三章 > 第 3.2 节"的分块应包含这些标题，让下游处理知道内容所处的位置。
+- **缓存分块树。** 一旦文档结构已被解析，把树保存下来。多条规则可能需要同一文档的内容，重复解析就是浪费。
+- **记录分块决策。** 使用了哪种策略、产出多少分块、各自的大小。有助于排查下游问题。
+
+## 与 tree-processing 的关系
 
-两者的分工原则：本技能服务于「先看一眼数据」的快速判断，`tree-processing` 服务于「正式核查每一份文档」的工程化交付。在 KC 的 bootstrap 和 rule_extraction 阶段优先使用本技能；进入 skill_authoring 之后，若分块逻辑将被反复调用，应及时迁移到 `tree-processing`，并把对应的脚本和参数固化到技能目录下，避免每次运行得到不一致的切分结果，影响后续违规判定的可追溯性与置信度评估。
+本技能讲分块方法。`tree-processing` 讲为生产核查工作流设计精确、可编码的分块脚本 —— 在那里分块必须确定性、可复现、可测试。当上面的便宜方法满足不了生产路径的控制需求时，转用 `tree-processing`。