kc-beta 0.1.0

package/template/skills/zh/meta/compliance-judgment/references/output-format.md

@@ -0,0 +1,151 @@
+# Lightweight Output Format Specification
+
+This document defines the compact text markup format for verification results, its grammar, JSON conversion rules, and edge case handling.
+
+## Grammar
+
+```
+[RESULT] field_name <- value (constraint) | conf:score | src:location | note:text
+```
+
+| Component | Required | Format | Description | Example |
+|-----------|----------|--------|-------------|---------|
+| `[RESULT]` | Yes | One of: PASS, FAIL, MISSING, ERROR, UNCERTAIN | The judgment outcome. | `[FAIL]` |
+| `field_name` | Yes | snake_case identifier | The rule or field being checked. | `capital_adequacy` |
+| `<- value` | No (omit for MISSING) | Free text, no pipes | The extracted value from the document. | `<- 12.5%` |
+| `(constraint)` | No (omit if no constraint) | Parenthesized expression | The expected value or condition. | `(>= 8.0%)` |
+| `conf:score` | Yes | Decimal 0.00-1.00 | Confidence score of the judgment. | `conf:0.95` |
+| `src:location` | No | Page-section reference or trace ID prefix | Source location in the document. | `src:p3-s2` |
+| `note:text` | No | Free text to end of line | Human-readable comment. | `note:Signing overdue by 45 days` |
+
+Components after `field_name` are separated by ` | ` (space-pipe-space). The `<- value` and `(constraint)` components appear before the first pipe, space-separated.
+
+## Field Definitions
+
+### Result Values
+
+| Value | Meaning | When to Use |
+|-------|---------|-------------|
+| `PASS` | Entity complies with the rule. | Deterministic or semantic check confirms compliance. |
+| `FAIL` | Entity does not comply. | Clear non-compliance detected. Note is strongly recommended. |
+| `MISSING` | Entity not found in document. | Extraction could not locate the required field. |
+| `ERROR` | Processing failure. | Parsing error, API timeout, unexpected format. |
+| `UNCERTAIN` | Ambiguous judgment. | Borderline values, conflicting evidence, low confidence. |
+
+### Confidence Score
+
+A decimal between 0.00 and 1.00 representing the system's confidence in the result. For deterministic Python checks, confidence is typically 0.95-1.00. For LLM semantic judgments, confidence reflects the model's self-assessed certainty. Scores below the configured threshold in `.env` trigger human review.
+
+### Source Location
+
+The `src:` component uses a compact reference format: `p{page}-s{section}`. Example: `src:p3-s2` means page 3, section 2. For trace ID integration, use the trace ID prefix: `src:R001-DOC042-P3-S2` (see Integration with Trace IDs below).
+
+## JSON Conversion
+
+### Markup to JSON
+
+```
+Input:  [FAIL] sign_date_gap <- 75d (<= 30d) | conf:0.90 | src:p1-s4 | note:Signing overdue by 45 days
+
+Output:
+{
+  "field": "sign_date_gap",
+  "result": "fail",
+  "extracted_value": "75d",
+  "expected": "<= 30d",
+  "confidence": 0.90,
+  "source": "p1-s4",
+  "comment": "Signing overdue by 45 days"
+}
+```
+
+Pseudocode:
+1. Parse `[RESULT]` -> lowercase -> `result` field.
+2. Parse next token -> `field` field.
+3. If `<-` follows, parse until `(` or `|` -> `extracted_value`.
+4. If `(...)` follows, parse contents -> `expected`.
+5. Split remaining by ` | `. For each segment:
+   - `conf:X` -> `confidence` (parse as float).
+   - `src:X` -> `source`.
+   - `note:X` -> `comment`.
+
+### JSON to Markup
+
+Pseudocode:
+1. `[` + uppercase(`result`) + `] ` + `field`.
+2. If `extracted_value` exists: ` <- ` + `extracted_value`.
+3. If `expected` exists: ` (` + `expected` + `)`.
+4. ` | conf:` + format(`confidence`, 2 decimal places).
+5. If `source` exists: ` | src:` + `source`.
+6. If `comment` exists: ` | note:` + `comment`.
+
+## Diff Example
+
+Comparing two verification runs is where markup shines.
+
+**Markup diff** (clean, scannable):
+```
+  [PASS] capital_adequacy <- 12.5% (>= 8.0%) | conf:0.95 | src:p3-s2
+- [PASS] sign_date_gap <- 28d (<= 30d) | conf:0.92 | src:p1-s4
++ [FAIL] sign_date_gap <- 75d (<= 30d) | conf:0.90 | src:p1-s4 | note:Signing overdue by 45 days
+  [MISSING] collateral_value | conf:0.60 | note:Collateral valuation not found
+```
+
+**JSON diff** (noisy, hard to scan):
+```json
+  {
+    "field": "sign_date_gap",
+-   "result": "pass",
++   "result": "fail",
+-   "extracted_value": "28d",
++   "extracted_value": "75d",
+    "expected": "<= 30d",
+-   "confidence": 0.92,
++   "confidence": 0.90,
+    "source": "p1-s4",
+-   "comment": ""
++   "comment": "Signing overdue by 45 days"
+  }
+```
+
+The markup diff communicates the same information in one changed line vs. five changed lines.
+
+## Edge Cases
+
+### Multi-Value Fields
+When a field has multiple extracted values (e.g., the same metric appears in two places with different values), separate values with semicolons:
+```
+[UNCERTAIN] total_assets <- 1,234,567;1,234,590 | conf:0.50 | src:p3-s1;p7-s2 | note:Conflicting values found
+```
+
+### Long Notes
+In markup, truncate notes longer than 80 characters with `...`. The full text is preserved in JSON. Example:
+```
+[FAIL] risk_disclosure <- (see detail) | conf:0.85 | note:Missing discussion of liquidity risk, market risk, and operational ri...
+```
+
+### Special Characters
+If a value or note contains the pipe character `|`, escape it with a backslash: `\|`. During JSON conversion, unescape back to `|`.
+
+### Fields with No Constraint
+Omit the parenthetical entirely:
+```
+[MISSING] collateral_value | conf:0.60 | note:Collateral valuation not found in document
+```
+
+### Fields with No Extracted Value
+Omit the `<-` component (common for MISSING and ERROR results):
+```
+[ERROR] capital_adequacy | conf:0.00 | note:PDF parsing failed on page 3
+```
+
+## Integration with Trace IDs
+
+The `src:` component can encode trace ID prefixes, linking each result line to the full trace ID defined by `version-control`. Use the trace ID format directly:
+
+```
+[PASS] capital_adequacy <- 12.5% (>= 8.0%) | conf:0.95 | src:R001-DOC042-P3-S2
+[FAIL] sign_date_gap <- 75d (<= 30d) | conf:0.90 | src:R003-DOC042-P1-S4 | note:Signing overdue by 45 days
+```
+
+When converting to JSON, the `src:` value maps to the `trace_id` field in the full result object. The character range (`C{start}:{end}`) can be appended when full precision is needed: `src:R001-DOC042-P3-S2-C120:180`.

package/template/skills/zh/meta/confidence-system/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: confidence-system
+description: Design and calibrate confidence scoring for extraction and verification results. Use when building any workflow that needs to quantify trust in its output, when setting up quality control sampling thresholds, or when calibrating existing confidence scores against actual accuracy. Confidence is the bridge between workflows and quality control. Also use when the quality control skill reports that confidence scores do not correlate with actual correctness.
+---
+
+# 置信度系统
+
+置信度不是模型的自信程度，而是系统准确率的预测值。一个置信度分数应该回答这个问题："当系统给出这个分数时，结果正确的概率是多少？"如果你的 0.90 置信度结果实际准确率为 90%，说明系统校准良好。
+
+## 为什么需要置信度
+
+没有置信度，你只有两个选择：
+1. **全量审查**——成本高昂，自动化的意义荡然无存。
+2. **不审查**——风险高，错误会漏过。
+
+有了置信度，你可以**智能审查**：把有限的审查资源投入到最可能出错的地方。高置信度的结果抽样审查，低置信度的结果全量审查。这是自动化与质量之间的桥梁。
+
+### 经济账
+
+假设一批 1000 份文档，每份人工审查成本 50 元：
+- 全量审查：50,000 元
+- 有置信度系统：高置信度 700 份（抽样 10%）+ 中置信度 200 份（抽样 50%）+ 低置信度 100 份（全量审查）= 70×50 + 100×50 + 100×50 = 13,500 元
+- 节省 73%，同时覆盖了所有高风险结果。
+
+## 复合评分信号
+
+单一信号不足以可靠预测准确率。置信度应该综合多个信号。
+
+### 信号一：提取方法先验
+
+提取方法本身的固有可靠性。
+
+| 提取方法 | 先验置信度 | 理由 |
+|---------|-----------|------|
+| 正则匹配 + 格式验证通过 | 0.90-0.95 | 格式正确的结构化数据，正则提取几乎不会出错 |
+| LLM 结构化输出 | 0.75-0.85 | LLM 理解上下文后提取，有一定幻觉风险 |
+| LLM 自由格式输出 | 0.60-0.75 | 输出格式不受约束，解析可能出错 |
+| 回退/推断值 | 0.40-0.50 | 非直接提取，有猜测成分 |
+
+这是一个先验值——反映方法的一般可靠性，不是这次提取的具体可靠性。
+
+### 信号二：源文本匹配
+
+提取的值是否能在源文本中找到？
+
+- **精确字符串匹配**：提取值 "12.5%" 在源文本中以 "12.5%" 形式出现 → 高信号。
+- **近似匹配**：提取值 "12.5%" 在源文本中以 "12.50%" 或 "一二点五" 形式出现 → 中信号。
+- **无匹配**：源文本中找不到 "12.5" 这个数字 → 低信号，可能是幻觉。
+
+这个信号专门用于捕获幻觉。如果 LLM 声称"资本充足率为 12.5%"，但 "12.5" 在源文档章节中根本不存在，这是一个严重的红旗。
+
+### 信号三：历史准确率
+
+该规则、该文档类型、该提取方法的历史正确率。
+
+- **首轮迭代**（无历史数据）：仅使用方法先验。
+- **经过质控审查后**：计算实际准确率，纳入评分。
+
+这是最有价值的长期信号。它反映的是真实表现，而非假设。随着质控数据积累，历史准确率应逐渐成为主导信号。
+
+### 信号四：边缘案例距离
+
+文档是否匹配已知的边缘案例模式？
+
+- **精确匹配**：文档触发了已知边缘案例 → 降低置信度（标准工作流可能不适用）。
+- **近似匹配**：文档与某个边缘案例有相似特征但未完全匹配 → 略微降低置信度。
+- **无匹配**：正常文档 → 不调整。
+
+## 信号组合
+
+用加权平均组合多个信号：
+
+```
+confidence = w1 × method_prior + w2 × source_match + w3 × historical_accuracy + w4 × corner_case_adj
+```
+
+### 初始权重建议
+
+| 信号 | 权重 | 说明 |
+|-----|------|------|
+| w1（方法先验） | 0.25 | 基础信号，始终可用 |
+| w2（源文本匹配） | 0.25 | 反幻觉信号，始终可用 |
+| w3（历史准确率） | 0.35 | 最重要的信号，但需要数据积累 |
+| w4（边缘案例距离） | 0.15 | 辅助信号 |
+
+### 历史数据不可用时的处理
+
+在系统运行初期，没有历史准确率数据。此时将 w3 的权重重新分配给其他信号：
+
+```
+# 初期（无历史数据）
+confidence = 0.40 × method_prior + 0.40 × source_match + 0.20 × corner_case_adj
+
+# 中期（有部分历史数据）
+confidence = 0.30 × method_prior + 0.30 × source_match + 0.25 × historical_accuracy + 0.15 × corner_case_adj
+
+# 成熟期（充足历史数据）
+confidence = 0.25 × method_prior + 0.25 × source_match + 0.35 × historical_accuracy + 0.15 × corner_case_adj
+```
+
+随着历史数据积累，逐步过渡到完整权重。不要一开始就把权重给到没有数据支撑的信号上。
+
+## 阈值分带
+
+将连续的置信度分数映射为离散的审查行动：
+
+| 分带 | 置信度范围 | 审查行动 | 典型比例 |
+|-----|-----------|---------|---------|
+| 高置信度 | > 0.85（自动接受阈值） | 仅抽样审查（5-10% 随机抽样） | ~70% |
+| 中置信度 | 0.60 - 0.85 | 按 MONITOR_FREQUENCY 频率抽样 | ~20% |
+| 低置信度 | < 0.60（全量审查阈值） | 每条结果都审查 | ~10% |
+
+起始阈值：自动接受 = 0.85，全量审查 = 0.60。这些是默认值，每条规则可以有不同的阈值。
+
+### 阈值调整原则
+
+- **高风险规则**（如资本充足率、不良贷款率等核心监管指标）：提高自动接受阈值到 0.90 或 0.95。宁可多审查，不可漏判。
+- **低风险规则**（如格式检查、日期格式）：可降低自动接受阈值到 0.80。
+- **初期保守**：系统刚上线时，建议将自动接受阈值设为 0.90，全量审查阈值设为 0.70。随着校准数据积累再逐步放宽。
+
+## 校准
+
+校准是验证置信度分数是否真正预测准确率的过程。
+
+### 校准方法
+
+每次质控审查周期结束后：
+
+1. **分组**：按置信度区间（如 0.0-0.2、0.2-0.4、0.4-0.6、0.6-0.8、0.8-1.0）对已审查结果分组。
+2. **统计**：对每个区间，计算实际准确率（质控确认正确的比例）。
+3. **比较**：将实际准确率与置信度区间中点进行对比。
+
+```
+区间        样本数    实际准确率    期望准确率    偏差
+0.8-1.0     150       92%          90%          +2%  ✓ 校准良好
+0.6-0.8     80        73%          70%          +3%  ✓ 校准良好
+0.4-0.6     30        35%          50%          -15% ✗ 置信度偏高
+0.2-0.4     10        40%          30%          +10% ✗ 置信度偏低
+0.0-0.2     5         0%           10%          -10% ✓ 样本太少
+```
+
+### 校准偏差的处理
+
+- **置信度偏高**（实际准确率低于置信度区间）：系统过于乐观。增加 w2（源文本匹配）的权重，或降低方法先验值。
+- **置信度偏低**（实际准确率高于置信度区间）：系统过于保守。可以适当提高先验值，但保守偏差的危害小于乐观偏差——多审查几条比漏掉错误好。
+- **样本不足**：某个区间的样本太少（<20），不具有统计意义。等待更多数据。
+
+### 何时重新校准
+
+- 首次质控审查完成后（建立初始校准基线）。
+- 工作流版本变更后（新代码可能有不同的可靠性特征）。
+- 调整置信度阈值后。
+- 质控报告显示置信度与正确率不相关时。
+
+## 集成点
+
+置信度系统不是孤立运行的，它与核查流程的每个环节对接：
+
+### 实体提取阶段
+
+提取完成后立即分配初始置信度，基于方法先验和源文本匹配两个信号。
+
+```json
+{
+  "value": 12.5,
+  "confidence": 0.92,
+  "confidence_signals": {
+    "method_prior": 0.95,
+    "source_match": 0.90
+  }
+}
+```
+
+### 合规判定阶段
+
+判定可能调整置信度：
+- 确定性判定（Python 阈值比较）→ 不改变置信度。
+- 语义判定（LLM）→ 根据 LLM 的判定确定性调整。
+- 值在阈值边界附近 → 降低置信度（即使提取很可靠，边界值的判定本身不确定）。
+
+### 质量控制阶段
+
+质控使用置信度分带决定审查策略：
+- 高置信度 → 低采样率。
+- 低置信度 → 全量审查。
+- 审查结果反馈到校准流程。
+
+### 演进循环
+
+演进循环监控置信度趋势：
+- 平均置信度持续下降 → 可能有系统性退化。
+- 某条规则的置信度突然下降 → 可能文档格式发生变化。
+- 置信度与准确率的相关性下降 → 需要重新校准。
+
+### 仪表板展示
+
+在开发者用户的仪表板中展示：
+- 置信度分布直方图（当前批次）。
+- 各规则的平均置信度。
+- 校准曲线（置信度 vs 实际准确率）。
+- 低置信度结果列表（需要优先关注的项目）。
+
+## 保持简单
+
+不要在一开始就构建复杂的置信度系统。遵循渐进式复杂度：
+
+### 第一阶段：方法先验
+
+只用提取方法分配置信度：
+- 正则：0.90
+- LLM：0.75
+- 回退：0.50
+
+跑质控，看这些分数是否预测准确率。如果预测得不错，先维持不变。
+
+### 第二阶段：加入源文本匹配
+
+当发现 LLM 幻觉是一个实际问题时（质控发现 LLM 提取的值在原文中找不到），加入源文本匹配信号。
+
+### 第三阶段：加入历史准确率
+
+积累了 3-5 轮质控数据后，有足够的样本计算历史准确率。此时纳入这个信号。
+
+### 第四阶段：加入边缘案例距离
+
+当边缘案例注册表有了一定规模后（>10 条活跃记录），加入边缘案例距离信号。
+
+每一步都要验证：新信号的加入是否确实提高了置信度与准确率的相关性。如果没有，不要加。**置信度系统应该挣得自己的复杂度，而不是一开始就复杂。**

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

@@ -0,0 +1,235 @@
+---
+name: corner-case-management
+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.
+---
+
+# 边缘案例管理
+
+好的工作流处理 90% 的文档。边缘案例处理剩下的 10%。它们单独看出现率低，但累积起来影响显著。关键认知：**不要为了边缘案例给主工作流打补丁**。补丁导致逻辑混乱、代码脆弱、回归风险。
+
+正确做法：把边缘案例从主流程中分离出来，单独管理。
+
+## 理念
+
+文档核查中边缘案例是必然存在的。金融文档由数千家不同机构出具，每家都有自己的排版习惯、模板风格、对法规的不同理解。没有任何工作流能覆盖所有变体。
+
+问题不是"怎么消灭边缘案例"，而是"怎么高效管理它们"。
+
+答案是：**分离它们，保持主工作流干净，保持边缘案例可追踪、可检测、可解决**。
+
+### 主工作流 vs 边缘案例处理的分工
+
+```
+文档进入
+  │
+  ├─ 检查边缘案例注册表 → 匹配？→ 执行特定解决方案
+  │                           │
+  │                        不匹配
+  │                           │
+  └───────────────────────────┤
+                              ▼
+                    执行标准工作流
+```
+
+标准工作流保持简洁、通用、可维护。边缘案例有自己的管理体系。两者独立演进。
+
+## 边缘案例注册表
+
+每条规则技能的 `assets/` 目录下维护一个结构化文件 `corner_cases.json`：
+
+```json
+[
+  {
+    "id": "CC001",
+    "rule_id": "R001",
+    "description": "部分银行年报将资本充足率以小数形式（0.125）而非百分比（12.5%）表示",
+    "affected_documents": ["bank_xyz_annual_2024.pdf"],
+    "detection_pattern": {
+      "type": "regex",
+      "pattern": "资本充足率[：:]*\\s*0\\.\\d+",
+      "confidence_threshold": 0.8
+    },
+    "resolution": {
+      "type": "code",
+      "action": "在阈值比较前将提取值乘以100",
+      "code_snippet": "if value < 1.0: value *= 100"
+    },
+    "discovered_at": "2026-04-01",
+    "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 判断（成本高，仅在无法用简单方法检测时使用）。
+- **解决方案（resolution）**：如何处理匹配的文档。类型可以是：
+  - `code`：Python 代码修正（如单位转换）。
+  - `regex`：正则替换或别名映射。
+  - `prompt`：使用不同的 LLM 提示词。
+  - `parser`：使用不同级别的解析器。
+  - `manual`：标记为需人工处理，不自动判定。
+- **发现时间和迭代轮次**：什么时候发现的，在哪轮演进中。
+- **状态（status）**：`active`（使用中）、`promoted`（已提升到主工作流）、`deprecated`（已废弃）。
+
+## 检测机制
+
+在标准工作流执行**之前**，对每份文档运行边缘案例检测：
+
+1. 加载当前规则对应的边缘案例注册表。
+2. 对每个 `active` 状态的边缘案例，检查文档是否匹配其检测模式。
+3. 如果匹配置信度超过阈值，执行该边缘案例的特定解决方案（替代或补充标准工作流）。
+4. 记录触发了哪个边缘案例。
+
+这个流程类似 RAG 的渐进式披露：
+- 注册表是知识库。
+- 检测模式是检索查询。
+- 置信度阈值防止误匹配。
+- 只有相关的边缘案例被加载到执行上下文中。
+
+### 检测效率
+
+检测必须轻量。对每份文档跑 50 个正则匹配的成本可以忽略不计，但跑 50 个 LLM 调用就不可接受了。
+
+优先级排序：
+1. 正则/关键词检测（毫秒级）→ 优先使用。
+2. 结构检测（秒级，需解析）→ 在解析完成后顺带检查。
+3. LLM 检测（秒级+成本）→ 仅在无法用上述方法时使用。
+
+## 何时添加边缘案例
+
+在演进循环中，当一个失败案例被分析后，需要决定它是系统性问题还是边缘案例。
+
+**添加为边缘案例的条件**（三个条件同时满足）：
+
+1. **非系统性**：影响不到 10% 的文档。如果影响面更广，那是工作流本身的问题，应该修复工作流。
+2. **有可辨识模式**：能描述出这类文档的共同特征，能写出检测规则。如果失败看起来是随机的、无规律的，那可能是数据质量问题，需要升级给开发者用户。
+3. **有明确解决方案**：知道怎么处理。不是"不确定"或"需要更多调查"。
+
+**不应添加为边缘案例的情况**：
+
+- 失败影响大量文档（系统性问题，修工作流）。
+- 失败无可辨识模式（数据质量问题，报告给开发者用户）。
+- 解决方案需要改变核心判定逻辑（属于主工作流的范畴）。
+
+## 何时提升边缘案例
+
+边缘案例不应该永远是边缘案例。当它变得普遍时，应该被提升为主工作流的一部分。
+
+**提升条件**：
+
+- **出现率超过 10%**：在最近的文档批次中，超过 10% 的文档触发了该边缘案例。它已经不是"边缘"了，而是一种常见模式。
+- **模式聚类**：多个相似的边缘案例指向同一个底层问题。与其维护 5 个类似的边缘案例，不如合并为一个通用的工作流改进。
+- **开发者用户确认**："这就是常态，所有XX类型的文档都是这样"——开发者用户的领域知识是最权威的提升依据。
+
+**提升操作**：
+1. 将解决方案整合到主工作流中。
+2. 在注册表中将状态改为 `promoted`。
+3. 对两个变更做版本记录。
+4. 在下一批文档上验证提升后的工作流仍然正确。
+
+## 人类可见性
+
+边缘案例注册表必须对开发者用户透明可读：
+
+### 可读性要求
+
+- **格式清晰**：JSON 或 markdown 表格，人可读。
+- **上下文充分**：领域专家无需阅读代码就能理解每条记录。
+- **在仪表板中展示**：新发现的边缘案例应出现在报告中。
+
+### 开发者用户可添加
+
+开发者用户往往掌握编程智能体尚未遇到的边缘案例知识。他们应该能够添加类似这样的条目：
+
+- "XX银行的 Q4 报告总是使用不同的模板。"
+- "2020年以前的公募基金文档遵循旧版信息披露规定。"
+- "小型农商行的贷款合同经常缺少标准条款编号。"
+- "境外分行的报告中金额以美元计，不是人民币。"
+
+这些输入是宝贵的预防性信息，能避免未来的核查失败。在注册表中为手动添加的条目标注来源为"开发者用户"。
+
+## 成本控制
+
+每个边缘案例都有运行时成本：检测逻辑在每份文档上都要执行。保持注册表精简：
+
+### 精简原则
+
+- **清理废弃条目**：已提升或不再出现的边缘案例，将状态改为 `deprecated`。定期清理。
+- **合并相似条目**：如果有 5 个边缘案例都在处理"日期格式变体"，合并为一个带更广泛检测模式的条目。
+- **检测模式高效化**：优先用正则而非 LLM 检测。一个正则匹配耗时微秒，一个 LLM 调用耗时秒级。
+- **监控规模**：如果单条规则的边缘案例超过 50 个，这说明工作流本身需要改进。大量边缘案例是工作流不够健壮的信号。
+
+### 定期审查
+
+每隔若干个演进周期，审查一次边缘案例注册表：
+- 还有哪些是活跃的？
+- 有没有可以合并的？
+- 有没有应该提升的？
+- 有没有已经过时的？
+
+保持注册表的"新陈代谢"。一个不断膨胀的注册表和一个从不更新的注册表一样有害。
+
+## 与演进循环的协作
+
+边缘案例管理是演进循环的重要输出之一：
+
+```
+演进循环分析失败
+  │
+  ├─ 系统性失败 → 修改工作流
+  │
+  ├─ 边缘案例 → 添加到注册表
+  │
+  └─ 数据质量问题 → 报告给开发者用户
+```
+
+每次演进循环运行后，检查是否有新的边缘案例需要添加，以及现有边缘案例是否需要状态变更。
+
+边缘案例注册表的增长曲线本身就是系统健康度的指标：
+- 初期快速增长是正常的（你在发现文档的多样性）。
+- 中期增速放缓说明工作流趋于稳定。
+- 后期仍在快速增长则说明工作流可能存在根本性设计问题。