kc-beta 0.1.2 → 0.3.0

package/template/skills/zh/meta-meta/auto-model-selection/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: auto-model-selection
+description: >
+  使用 Context7 CLI 获取最新 LLM 模型信息。当需要了解可用模型、模型能力、价格、
+  上下文窗口大小、或哪个模型适合某项任务时使用——包括分层分配、Worker LLM 工作流设计、
+  模型对比、服务商 API 调用方式等。Context7 提供训练数据中可能没有的最新信息。
+  需要安装 context7 CLI (npm i -g context7)。可选插件。
+---
+
+# 通过 Context7 自动选择模型
+
+## Context7 是什么
+
+Context7 (`c7`) 是一个轻量 CLI 工具，可获取最新的库和 API 文档。安装：`npm i -g context7`。两个命令：
+- `c7 library <查询>` — 按名称搜索库/服务商
+- `c7 docs <libraryId> <查询>` — 获取具体文档和代码示例
+
+## 使用时机
+
+- 用户的 `model-tiers.json` 过期（KC 长时间未更新）
+- 用户切换到新服务商，需要模型发现
+- 用户明确要求更新模型选择
+- 配置向导的 `/models` 端点失败，且内置模型列表过期
+
+## 工作流程
+
+1. 用户选择服务商并提供 API 密钥
+2. 用 `c7 library <服务商名>` 找到对应的 library ID
+3. 用 `c7 docs <id> "available models"` 获取当前模型列表
+4. 从文档中识别：模型名称、能力（推理、编码、视觉）、上下文窗口大小、价格
+5. 按能力和成本分配到分层：
+   - LLM tier1：最强（复杂判断、抽取）
+   - LLM tier2-3：中等（常规抽取、简单判断）
+   - LLM tier4：最便宜（大量简单任务）
+   - VLM tier1-3：视觉模型（文档解析/OCR）
+6. 更新 `model-tiers.json` 或工作区 `.env`
+
+## 分层原则
+
+- 满足准确率阈值的最便宜模型
+- 正则是 tier0 — 比任何 LLM 都小
+- 不需要填满所有分层 — 服务商没有合适模型时留空即可
+- 在 AGENT.md 中记录哪些模型适合哪些任务
+
+## 前置条件
+
+```bash
+npm i -g context7
+```
+
+验证：`c7 library openai` 应返回结果。

package/template/skills/zh/meta-meta/pdf-review-dashboard/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: pdf-review-dashboard
+description: >
+  生成双栏 PDF 审核面板，用于人工核查验证结果。左侧显示原始 PDF 文档，右侧显示验证结果。
+  点击结果条目可跳转至 PDF 对应页面。当开发者用户需要对照源文件审核验证输出、
+  或为演进循环收集真实标注数据时使用。输出为单个自包含 HTML 文件。
+---
+
+## 功能
+
+生成单个自包含 HTML 文件：
+- 左侧：浏览器内渲染的原始 PDF
+- 右侧：可交互的验证结果列表
+- 点击跳转：选中结果后 PDF 滚动到对应页面
+
+开发者用户在浏览器中打开此 HTML 即可人工审核验证质量。
+
+## 技术栈
+
+- 单 HTML 文件，无需服务器
+- PDF 以 base64 内嵌（完全自包含，可分享）
+- 通过 CDN 加载 pdf.js 实现浏览器内 PDF 渲染
+- 纯 JS + 内联 CSS，无框架依赖
+- 深色主题，与 KC 仪表板风格一致
+
+## 布局
+
+- 可拖拽分隔条调整左右面板比例
+- 左侧：PDF 查看器，顶部工具栏含翻页（上一页/下一页/跳转）和缩放（+/-/适应宽度）
+- 右侧：结果列表，带筛选按钮，点击展开详情并跳转 PDF 页面
+- 跳转时页面高亮动画
+
+## 数据格式
+
+生成器脚本读取 PDF 文件和结果 JSON，输出 HTML。
+
+输入：
+- `pdf_path` — 源 PDF 文档路径
+- `results_path` — 验证结果 JSON 文件路径
+
+结果 JSON 为对象数组，每个对象至少包含：
+- 页面引用（对应 PDF 的哪一页）
+- 结果状态（pass/fail/warning 或等效值）
+
+右侧面板的列和详情字段自动适配验证工作流的输出数据。`scripts/generate_review.js` 是参考实现——根据项目输出格式调整数据映射部分。
+
+## 使用时机
+
+- 验证工作流完成后，供开发者用户可视化审核结果
+- 为演进循环收集真实标注修正
+- 向需要查看源文件依据的相关方展示结果
+
+## 生成器脚本
+
+见 `scripts/generate_review.js` — Node.js 脚本，输入 PDF 路径，输出审核 HTML。根据项目验证输出格式调整结果数据映射部分。

package/template/skills/zh/meta-meta/pdf-review-dashboard/scripts/generate_review.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+/**
+ * PDF Review Dashboard Generator
+ *
+ * Generates a single self-contained HTML file with:
+ * - Left: PDF viewer (pdf.js CDN, base64 embedded)
+ * - Right: interactive verification results list
+ * - Click result → jump to PDF page
+ *
+ * Usage:
+ *   node generate_review.js <pdf_path> <results_json_path> [output_html_path]
+ *
+ * The results JSON should be an array of objects. Adapt the DATA MAPPING
+ * section below to match your project's verification output format.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const pdfPath = process.argv[2];
+const resultsPath = process.argv[3];
+const outputPath = process.argv[4] || "review_dashboard.html";
+
+if (!pdfPath || !resultsPath) {
+  console.error("Usage: node generate_review.js <pdf_path> <results_json_path> [output_html_path]");
+  process.exit(1);
+}
+
+// Read inputs
+const pdfBuffer = fs.readFileSync(pdfPath);
+const pdfBase64 = pdfBuffer.toString("base64");
+const pdfFileName = path.basename(pdfPath);
+const rawResults = JSON.parse(fs.readFileSync(resultsPath, "utf-8"));
+
+// ============================================================
+// DATA MAPPING — adapt this section to your verification output
+// ============================================================
+// Map your raw results into the format the dashboard expects.
+// Each item needs at minimum: id, label, result, page.
+// Add any extra fields you want shown in the detail panel.
+const results = Array.isArray(rawResults) ? rawResults : rawResults.results || [];
+const mappedResults = results.map((r, i) => ({
+  id: r.id || r.rule_id || `R${String(i + 1).padStart(3, "0")}`,
+  label: r.rule || r.label || r.name || r.description || `Item ${i + 1}`,
+  result: r.result || r.status || "unknown",
+  confidence: r.confidence ?? r.score ?? null,
+  page: r.page || r.page_ref || 1,
+  // Detail fields — include whatever your workflow outputs
+  detail: r.detail || Object.fromEntries(
+    Object.entries(r).filter(([k]) => !["id","rule_id","rule","label","name","result","status","confidence","score","page","page_ref"].includes(k))
+  ),
+}));
+// ============================================================
+
+console.log(`PDF: ${pdfFileName} (${(pdfBuffer.length / 1024 / 1024).toFixed(1)}MB)`);
+console.log(`Results: ${mappedResults.length} items`);
+
+// Generate HTML
+const html = buildHTML(pdfBase64, pdfFileName, mappedResults);
+fs.writeFileSync(outputPath, html, "utf-8");
+console.log(`Output: ${outputPath} (${(Buffer.byteLength(html) / 1024 / 1024).toFixed(1)}MB)`);
+
+function buildHTML(pdfB64, fileName, items) {
+  const resultsJSON = JSON.stringify(items);
+  return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>KC Review — ${fileName}</title>
+<style>
+* { margin: 0; padding: 0; box-sizing: border-box; }
+:root {
+  --bg: #0a0a0a; --bg2: #141414; --bg3: #1e1e1e;
+  --text: #e5e5e5; --dim: #888; --border: #2a2a2a;
+  --green: #22c55e; --yellow: #eab308; --red: #ef4444;
+  --blue: #3b82f6; --orange: #f97316;
+}
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: var(--bg); color: var(--text); height: 100vh; overflow: hidden; }
+#app { display: flex; height: 100vh; }
+#pdf-panel { flex: 1; display: flex; flex-direction: column; border-right: 1px solid var(--border); min-width: 300px; }
+#pdf-toolbar { display: flex; align-items: center; gap: 8px; padding: 8px 12px; background: var(--bg2); border-bottom: 1px solid var(--border); flex-shrink: 0; }
+#pdf-toolbar button { background: var(--bg3); color: var(--text); border: 1px solid var(--border); border-radius: 4px; padding: 4px 10px; cursor: pointer; font-size: 13px; }
+#pdf-toolbar button:hover { background: var(--border); }
+#pdf-toolbar span { color: var(--dim); font-size: 13px; }
+#pdf-toolbar input[type=number] { width: 50px; background: var(--bg3); color: var(--text); border: 1px solid var(--border); border-radius: 4px; padding: 4px; text-align: center; font-size: 13px; }
+#pdf-container { flex: 1; overflow: auto; display: flex; flex-direction: column; align-items: center; padding: 16px; gap: 8px; }
+.pdf-page-wrapper { position: relative; box-shadow: 0 2px 8px rgba(0,0,0,0.5); }
+.pdf-page-wrapper canvas { display: block; }
+.page-highlight { position: absolute; inset: 0; background: rgba(59,130,246,0.12); border: 2px solid var(--blue); pointer-events: none; opacity: 0; transition: opacity 0.3s; }
+.page-highlight.active { opacity: 1; animation: pulse-border 1.5s ease-out; }
+@keyframes pulse-border { 0% { border-color: var(--orange); box-shadow: 0 0 20px rgba(249,115,22,0.4); } 100% { border-color: var(--blue); box-shadow: none; } }
+#drag-handle { width: 5px; background: var(--border); cursor: col-resize; flex-shrink: 0; transition: background 0.2s; }
+#drag-handle:hover, #drag-handle.dragging { background: var(--blue); }
+#results-panel { flex: 1; display: flex; flex-direction: column; min-width: 350px; }
+#results-toolbar { display: flex; align-items: center; gap: 8px; padding: 8px 12px; background: var(--bg2); border-bottom: 1px solid var(--border); flex-shrink: 0; flex-wrap: wrap; }
+#results-toolbar .filter-btn { background: var(--bg3); color: var(--dim); border: 1px solid var(--border); border-radius: 12px; padding: 3px 10px; cursor: pointer; font-size: 12px; transition: all 0.2s; }
+#results-toolbar .filter-btn.active { color: var(--text); border-color: var(--blue); background: rgba(59,130,246,0.15); }
+#results-toolbar .summary { margin-left: auto; font-size: 12px; color: var(--dim); }
+#results-list { flex: 1; overflow: auto; }
+.result-item { border-bottom: 1px solid var(--border); cursor: pointer; transition: background 0.15s; }
+.result-item:hover { background: var(--bg3); }
+.result-item.selected { background: rgba(59,130,246,0.1); border-left: 3px solid var(--blue); }
+.result-row { display: flex; align-items: center; padding: 10px 12px; gap: 10px; }
+.result-id { font-size: 11px; color: var(--dim); min-width: 40px; font-family: monospace; }
+.result-label { flex: 1; font-size: 13px; }
+.result-badge { font-size: 11px; font-weight: 600; padding: 2px 8px; border-radius: 10px; text-transform: uppercase; }
+.badge-pass { background: rgba(34,197,94,0.15); color: var(--green); }
+.badge-fail { background: rgba(239,68,68,0.15); color: var(--red); }
+.badge-warning { background: rgba(234,179,8,0.15); color: var(--yellow); }
+.badge-unknown { background: rgba(136,136,136,0.15); color: var(--dim); }
+.result-confidence { font-size: 12px; color: var(--dim); min-width: 40px; text-align: right; }
+.result-page { font-size: 11px; color: var(--dim); min-width: 30px; text-align: right; }
+.result-detail { display: none; padding: 8px 12px 14px 62px; font-size: 12px; line-height: 1.6; color: var(--dim); border-top: 1px dashed var(--border); }
+.result-item.expanded .result-detail { display: block; }
+.detail-row { margin-bottom: 4px; }
+.detail-key { color: var(--text); font-weight: 500; }
+</style>
+</head>
+<body>
+<div id="app">
+  <div id="pdf-panel">
+    <div id="pdf-toolbar">
+      <button onclick="prevPage()">◀</button>
+      <span>Page</span>
+      <input type="number" id="page-input" value="1" min="1" onchange="goToPage(this.value)">
+      <span id="page-count">/ ?</span>
+      <button onclick="nextPage()">▶</button>
+      <span style="margin-left:8px">|</span>
+      <button onclick="zoomOut()">−</button>
+      <span id="zoom-label">100%</span>
+      <button onclick="zoomIn()">+</button>
+      <button onclick="fitWidth()">Fit</button>
+    </div>
+    <div id="pdf-container"></div>
+  </div>
+  <div id="drag-handle"></div>
+  <div id="results-panel">
+    <div id="results-toolbar">
+      <span class="summary" id="results-summary"></span>
+    </div>
+    <div id="results-list"></div>
+  </div>
+</div>
+<script type="module">
+const PDF_B64 = "${pdfB64}";
+const RESULTS = ${resultsJSON};
+
+// PDF setup
+const pdfjsLib = await import("https://cdnjs.cloudflare.com/ajax/libs/pdf.js/4.10.38/pdf.min.mjs");
+pdfjsLib.GlobalWorkerOptions.workerSrc = "https://cdnjs.cloudflare.com/ajax/libs/pdf.js/4.10.38/pdf.worker.min.mjs";
+const pdfData = Uint8Array.from(atob(PDF_B64), c => c.charCodeAt(0));
+const pdf = await pdfjsLib.getDocument({ data: pdfData }).promise;
+const totalPages = pdf.numPages;
+document.getElementById("page-count").textContent = "/ " + totalPages;
+document.getElementById("page-input").max = totalPages;
+
+let scale = 1.2, currentPage = 1;
+const container = document.getElementById("pdf-container");
+const pageCanvases = new Map();
+
+async function renderAllPages() {
+  container.innerHTML = ""; pageCanvases.clear();
+  for (let i = 1; i <= totalPages; i++) {
+    const page = await pdf.getPage(i);
+    const vp = page.getViewport({ scale });
+    const w = document.createElement("div");
+    w.className = "pdf-page-wrapper"; w.id = "page-" + i;
+    w.style.width = vp.width + "px"; w.style.height = vp.height + "px";
+    const c = document.createElement("canvas");
+    c.width = vp.width; c.height = vp.height;
+    await page.render({ canvasContext: c.getContext("2d"), viewport: vp }).promise;
+    const hl = document.createElement("div"); hl.className = "page-highlight";
+    w.appendChild(c); w.appendChild(hl); container.appendChild(w);
+    pageCanvases.set(i, w);
+  }
+}
+await renderAllPages();
+
+function goToPage(n) { n = Math.max(1, Math.min(parseInt(n)||1, totalPages)); currentPage = n; document.getElementById("page-input").value = n; const el = document.getElementById("page-"+n); if(el) el.scrollIntoView({behavior:"smooth",block:"start"}); }
+function prevPage() { goToPage(currentPage-1); }
+function nextPage() { goToPage(currentPage+1); }
+function zoomIn() { scale = Math.min(scale+0.2, 3); updateZoom(); }
+function zoomOut() { scale = Math.max(scale-0.2, 0.4); updateZoom(); }
+function fitWidth() { pdf.getPage(1).then(p => { scale = (document.getElementById("pdf-panel").clientWidth-40)/p.getViewport({scale:1}).width; updateZoom(); }); }
+function updateZoom() { document.getElementById("zoom-label").textContent = Math.round(scale*100)+"%"; renderAllPages(); }
+window.goToPage=goToPage; window.prevPage=prevPage; window.nextPage=nextPage;
+window.zoomIn=zoomIn; window.zoomOut=zoomOut; window.fitWidth=fitWidth;
+
+// Detect unique result statuses for filter buttons
+const statuses = [...new Set(RESULTS.map(r => r.result))];
+const toolbar = document.getElementById("results-toolbar");
+const filterHTML = '<button class="filter-btn active" data-filter="all">All</button>' +
+  statuses.map(s => '<button class="filter-btn" data-filter="'+s+'">'+s.charAt(0).toUpperCase()+s.slice(1)+'</button>').join("");
+toolbar.insertAdjacentHTML("afterbegin", filterHTML);
+let activeFilter = "all", selectedId = null;
+toolbar.querySelectorAll(".filter-btn").forEach(b => b.addEventListener("click", () => {
+  activeFilter = b.dataset.filter;
+  toolbar.querySelectorAll(".filter-btn").forEach(x => x.classList.toggle("active", x.dataset.filter===activeFilter));
+  selectedId = null; renderResults();
+}));
+
+function renderResults() {
+  const list = document.getElementById("results-list");
+  const filtered = activeFilter === "all" ? RESULTS : RESULTS.filter(r => r.result === activeFilter);
+  const counts = statuses.map(s => RESULTS.filter(r=>r.result===s).length + " " + s).join(" · ");
+  document.getElementById("results-summary").textContent = counts;
+
+  list.innerHTML = filtered.map(r => {
+    const bc = ["pass","fail","warning"].includes(r.result) ? "badge-"+r.result : "badge-unknown";
+    const sel = r.id === selectedId ? " selected expanded" : "";
+    const conf = r.confidence != null ? Math.round(r.confidence*100)+"%" : "";
+    let detailHTML = "";
+    if (r.detail && typeof r.detail === "object") {
+      detailHTML = Object.entries(r.detail).map(([k,v]) =>
+        '<div class="detail-row"><span class="detail-key">'+k+': </span>'+String(v)+'</div>'
+      ).join("");
+    }
+    return '<div class="result-item'+sel+'" data-id="'+r.id+'" data-page="'+r.page+'">' +
+      '<div class="result-row">' +
+        '<span class="result-id">'+r.id+'</span>' +
+        '<span class="result-label">'+r.label+'</span>' +
+        '<span class="result-badge '+bc+'">'+r.result+'</span>' +
+        (conf ? '<span class="result-confidence">'+conf+'</span>' : '') +
+        '<span class="result-page">p.'+r.page+'</span>' +
+      '</div>' +
+      (detailHTML ? '<div class="result-detail">'+detailHTML+'</div>' : '') +
+    '</div>';
+  }).join("");
+
+  list.querySelectorAll(".result-item").forEach(el => el.addEventListener("click", () => {
+    const id = el.dataset.id, page = parseInt(el.dataset.page);
+    if (selectedId === id) { selectedId = null; el.classList.remove("selected","expanded"); }
+    else { list.querySelectorAll(".result-item").forEach(e=>e.classList.remove("selected","expanded")); selectedId = id; el.classList.add("selected","expanded"); }
+    jumpToPage(page);
+  }));
+}
+
+function jumpToPage(page) {
+  currentPage = page; document.getElementById("page-input").value = page;
+  const el = document.getElementById("page-"+page);
+  if(el) { el.scrollIntoView({behavior:"smooth",block:"center"});
+    const hl = el.querySelector(".page-highlight"); hl.classList.remove("active");
+    void hl.offsetWidth; hl.classList.add("active"); setTimeout(()=>hl.classList.remove("active"),2000); }
+}
+renderResults();
+
+// Drag handle
+const handle = document.getElementById("drag-handle");
+let dragging = false;
+handle.addEventListener("mousedown", e => { dragging=true; handle.classList.add("dragging"); e.preventDefault(); });
+document.addEventListener("mousemove", e => { if(!dragging) return; const r=e.clientX/document.getElementById("app").clientWidth; const c=Math.max(0.2,Math.min(0.8,r)); document.getElementById("pdf-panel").style.flex="0 0 "+(c*100)+"%"; document.getElementById("results-panel").style.flex="1"; });
+document.addEventListener("mouseup", () => { dragging=false; handle.classList.remove("dragging"); });
+
+container.addEventListener("scroll", () => {
+  const cr = container.getBoundingClientRect(); let closest=1, cd=Infinity;
+  pageCanvases.forEach((w,n) => { const d=Math.abs(w.getBoundingClientRect().top-cr.top); if(d<cd){cd=d;closest=n;} });
+  if(closest!==currentPage){currentPage=closest;document.getElementById("page-input").value=closest;}
+});
+</script>
+</body>
+</html>`;
+}

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

@@ -3,206 +3,121 @@ name: rule-extraction
 description: Extract and organize business verification rules from regulation documents into discrete, testable units. Use when processing documents in Rules/ to identify individual verification rules, when decomposing a regulation into atomic checks, or when the developer user adds new regulation files. Covers reading regulation text, identifying rule boundaries, determining granularity, handling cross-references, and producing a rule catalog. Also use when rules are provided in structured formats like xlsx or csv.
 ---
 
-# 法规条文解构与核查规则提取
+# Rule Extraction
 
-## 核心理念
+Rules are the atoms of verification. Each rule you extract will become its own skill folder, its own workflow, and its own production pipeline.
 
-规则是整个核查体系的原子单元。一条规则对应一个技能文件夹，一个技能文件夹对应一个可独立测试的核查逻辑。规则提取的质量直接决定后续所有环节的上限——技能编写、工作流蒸馏、质量监控，全部建立在规则提取的基础之上。
+## How This Differs from Data Extraction
 
-提取得好，后面事半功倍。提取得差，后面反复返工。
+Rule extraction is a **one-off task** at the start of a project. You read regulation documents and decompose them into discrete, testable rules. This is fuzzy, agile work — rules are read by you (a SOTA agent), so the schema can be messy and evolve freely.
 
-## 高质量规则的四个特征
+Data/entity extraction (`entity-extraction`) is the **repeating task** that runs on every document being verified. It must fit a unified, stable schema because it feeds into automated workflows.
 
-### 原子性
+Don't conflate the two. Rule extraction happens once; data extraction happens on every document.
 
-一条规则只做一件事。如果你发现一条规则需要用「并且」「同时」连接两个独立的判断逻辑，大概率应该拆成两条规则。
+## Rule Structure: Location → Extraction → Judgment
 
-反例：「发票日期应在合同有效期内，且发票金额不超过合同总额」——这是两条规则。
+Every verification rule decomposes into three parts:
 
-### 可测试性
+1. **Location**: Where in the document to look (which chapter, section, table, or full document).
+2. **Extraction**: What data to pull from that location (a number, a date, a clause, a description).
+3. **Judgment**: How to determine pass/fail (threshold comparison, semantic assessment, cross-field check).
 
-规则的判定结果必须是明确的：通过、不通过、无法判定。不能出现「大致合理」「基本符合」这种模糊结论。如果一条规则无法给出确定性结论，说明它还没提取到位。
+When extracting a rule, explicitly note all three parts. This determines the downstream pipeline structure:
+- Full-document rules need no location step.
+- Single-section rules need one location step.
+- Cross-section rules (comparing values across chapters) need multiple location steps.
 
-### 自包含性
+Classify each rule's scope accordingly — it affects how the verification workflow is structured.
 
-规则的执行不应依赖于其他规则的执行结果。每条规则应该能独立运行。如果规则A的判定需要先知道规则B的结果，说明存在耦合，需要重新设计。
+## Philosophy
 
-例外：交叉验证类规则（如「发票金额与合同金额一致」）本身就是一条独立规则，它依赖的是数据字段而非其他规则的结论。
+A well-extracted rule is:
+- **Atomic**: it checks one thing. "The borrower's debt-to-income ratio must not exceed 50%" is one rule. "The loan agreement must comply with Regulation X" is not — it is a container for many rules.
+- **Testable**: given a document, you can definitively say whether the rule passes or fails (or is not applicable).
+- **Self-contained**: the rule's meaning does not require reading ten other rules to understand. Cross-references should be resolved into the rule's description.
+- **Scoped**: you know WHERE in the document to look. "Chapter 3, Section 2" or "the risk disclosure section" or "the signature page."
 
-### 明确的作用域
+But perfection is the enemy of progress. Extract rules at the granularity that feels right for the regulation and the business scenario. You will iterate. The developer user will tell you if rules are too coarse or too fine.
 
-规则必须清楚说明它适用于什么类型的单据、什么业务场景、什么前提条件。作用域模糊的规则在实际核查中会产生大量误判。
+## Rule Schema Design Principles
 
-## 规则体系的系统性设计原则
+Individual rules should be atomic and testable (above). The rule catalog as a whole must also satisfy system-level properties:
 
-单条规则应当满足上述四个特征。规则目录作为一个整体，还需要满足系统级属性：
+### Coverage Target
+Extracted rules should cover at least 95% of the regulation's checkable requirements. After initial extraction, perform a coverage audit: read the source regulation end-to-end and mark which paragraphs are covered by at least one rule. Uncovered paragraphs are either non-checkable (definitions, context) or gaps to close.
 
-### 覆盖度目标
-提取的规则应覆盖法规可核查要求的至少 95%。初次提取完成后，执行覆盖度审计：端到端通读原始法规，标注每个段落是否被至少一条规则覆盖。未覆盖的段落要么是非核查性内容（定义、背景），要么是需要补充的空白。
+### Atomicity Test
+One rule = one pass/fail outcome. If a rule can produce two independent pass/fail results, it should be two rules. Ask: "Can this rule partially pass?" If yes, decompose further.
 
-### 原子性测试
-一条规则 = 一个通过/不通过结论。如果一条规则能产出两个独立的通过/不通过结果，它应该被拆为两条规则。自问：「这条规则能部分通过吗？」如果能，继续拆分。
+### Ambiguity Minimization
+No two rules should produce contradictory results on the same document. After extraction, review rule pairs that touch overlapping scope. If Rule A says pass and Rule B says fail for the same entity, their scope boundaries are unclear — fix them.
 
-### 歧义最小化
-不能有两条规则对同一文档的同一实体给出矛盾结论。提取完成后，审查作用域重叠的规则对。如果规则 A 判定通过而规则 B 判定不通过（针对同一实体），说明它们的作用域边界不清——必须修正。
+### Downstream Anticipation
+Rules will be distilled into workflows (see `skill-to-workflow`). Design with distillation in mind: clear input/output boundaries, explicit judgment criteria, minimal reliance on implicit domain knowledge. If a rule requires reading between the lines, make the interpretation explicit. Use `task-decomposition` to identify natural boundaries between rules.
 
-### 下游预判
-规则最终将被蒸馏为工作流（参见 `skill-to-workflow`）。设计时就要考虑蒸馏的需求：清晰的输入/输出边界、显式的判定标准、尽量减少对隐含领域知识的依赖。如果一条规则需要「读出言外之意」，把那个解读显式写出来。使用 `task-decomposition` 来识别规则之间的自然边界。
+### Catalog Versioning
+When rules change (additions, modifications, deprecations), version the entire rule catalog as a unit. Individual rule versions track specific rules; the catalog version tracks the coherent set. Record the catalog version in `versions.json` alongside individual rule versions.
 
-### 目录版本化
-当规则发生变更（新增、修改、废弃）时，将整个规则目录作为一个整体进行版本化。单条规则的版本跟踪的是具体规则；目录版本跟踪的是规则集的一致性状态。在 `versions.json` 中记录目录版本，与单条规则版本并列。
+## Extraction Strategies
 
-## 策略一：结构化输入（开发者用户提供规则表格）
+### Strategy 1: Structured Input (Developer User Provides Rules)
 
-当开发者用户以 xlsx、csv 或其他结构化格式提供规则清单时，这是最理想的情况。
+When the developer user provides rules in xlsx, csv, or a structured document where each row/entry is a distinct rule with clear scope:
+- Follow their structure exactly. Do not re-decompose.
+- Map each row to a rule, preserving the developer user's identifiers.
+- Ask clarifying questions only if entries are ambiguous.
 
-### 处理步骤
+### Strategy 2: Hierarchical Extraction from Regulation Text
 
-1. 读取文件，理解表格结构（列名、分组方式）
-2. 尊重开发者用户的规则划分——他们比你更懂业务
-3. 为每条规则生成标准编号（R001、R002...）
-4. 检查是否存在隐含的复合规则需要进一步拆分
-5. 补充表格中可能缺失的信息：适用范围、前提条件、判定标准
+For raw regulation documents (PDF, DOCX, legal text):
 
-### 注意事项
+1. **Survey the document structure.** Read the table of contents or scan headers. Understand the hierarchy: parts, chapters, sections, articles, clauses.
+2. **Identify rule-bearing sections.** Not every section contains a verification rule. Some are definitions, some are procedural, some are context. Focus on sections that impose obligations, prohibitions, thresholds, or requirements.
+3. **Peel the onion.** Start at the highest structural level and work downward:
+   - Level 1: What major areas does the regulation cover? (e.g., capital adequacy, risk disclosure, governance)
+   - Level 2: Within each area, what are the specific chapters or sections?
+   - Level 3: Within each section, what are the individual requirements?
+   - Stop peeling when you reach atomic rules.
+4. **Handle cross-references.** Regulations love to say "as defined in Section X" or "subject to the conditions in Article Y." Resolve these by including the referenced content in the rule's description, not just the reference.
+5. **Handle compound rules.** "The report must include (a) risk factors, (b) financial projections, and (c) management discussion" — this is three rules, not one. Decompose unless the developer user specifically wants them grouped.
 
-- 不要擅自合并开发者用户已经拆分的规则
-- 如果表格中某条规则的描述过于笼统，标记为「待细化」，向开发者用户确认
-- 保留原始表格的引用关系（如行号），便于回溯
+For long documents (100+ pages), use the onion-peeler approach described in `references/chunking-strategies.md`. Do not try to read the entire document in one pass.
 
-## 策略二：从法规原文层层剥解
+### Strategy 3: Expert Notes
 
-当输入是法规文件、监管通知、内部制度等非结构化文本时，采用「洋葱剥皮法」逐层提取。
+Sometimes rules come from the developer user's domain expertise rather than formal regulations:
+- "We always check that the guarantor's signature matches the name on page 1."
+- "If the collateral value is below 120% of the loan amount, flag it."
 
-### 第一层：通览全文结构
+Capture these with the same rigor as formal regulation rules. They are equally important in the verification app.
 
-快速阅读，识别文件的组织方式：
-- 章节编号体系（第X条、第X款、第X项）
-- 哪些章节是定义性条款（不含核查规则）
-- 哪些章节是实质性要求（包含核查规则）
-- 哪些章节是程序性条款（审批流程，可能包含时限类规则）
-- 附则、附件中是否有补充规则
+## Rule Catalog
 
-### 第二层：识别规则承载段落
+Maintain a lightweight catalog of all extracted rules. This is your index, not the rules themselves (those live in skill folders). The catalog should track:
 
-聚焦于实质性要求章节，逐段判断：
-- 该段落是否包含「应当」「必须」「不得」「需要」等规范性用语？
-- 该段落是否描述了可以被验证的具体要求？
-- 该段落是叙述性说明还是操作性要求？
+- Rule ID (simple sequential: R001, R002, ...)
+- Rule title (one line)
+- Source (which regulation document, which section)
+- Status (extracted / skill-written / skill-tested / workflow-written / workflow-tested / production)
+- Dependencies (rules that must be checked before this one)
 
-只有包含可核查要求的段落才进入下一层处理。
+Format: a simple markdown table or JSON file. Do not over-engineer this. The catalog exists to give you and the developer user an overview of progress.
 
-### 第三层：逐段提取规则
+## Handling Ambiguity
 
-对每个规则承载段落：
+Regulations are often ambiguous. When you encounter ambiguity:
+1. Extract the rule as you understand it.
+2. Note the ambiguity explicitly in the rule description.
+3. Ask the developer user for clarification.
+4. Update the rule after receiving clarification.
 
-1. 提取核查对象（哪个字段、哪份单据）
-2. 提取核查标准（什么条件、什么阈值）
-3. 提取适用范围（什么业务场景、什么前提条件）
-4. 提取例外情形（什么情况下不适用）
-5. 标注原文位置（法规名称 + 条款编号）
+Do not skip ambiguous rules. They are often the most important ones.
 
-### 第四层：处理交叉引用
+## When Rules Change
 
-法规文本中常见的交叉引用模式：
-- 「依据本办法第X条规定」——需要找到被引用条款，整合上下文
-- 「参照XX法规执行」——需要确认外部法规是否在 `Rules/` 中，如果没有则标记为待补充
-- 「前款所述情形」——需要回溯上文，明确指代
-
-处理原则：将交叉引用解析为自包含的规则描述，在规则的 `references/` 中保留原始引用关系。
-
-### 第五层：拆解复合规则
-
-识别并拆分以下模式：
-
-- 并列条件：「A且B」→ 拆为规则A、规则B
-- 条件分支：「若X则A，若Y则B」→ 拆为规则A（前提X）、规则B（前提Y）
-- 阶梯条件：「金额≤10万执行A流程，金额>10万执行B流程」→ 拆为规则A（阈值条件）、规则B（阈值条件）
-
-不需要拆分的情形：
-- 规则本身就是一个条件判断：「发票日期应在合同有效期内」——这就是一条原子规则
-- 规则包含多个字段但逻辑统一：「收款单位名称、账号应与合同约定一致」——可以保留为一条规则，因为核查逻辑相同
-
-## 策略三：开发者用户口述的专家经验
-
-有时候开发者用户不会给你法规文件，而是直接告诉你业务经验和核查要点。这种输入同样有效。
-
-### 处理方式
-
-1. 完整记录开发者用户的口述内容
-2. 将口述转化为结构化规则（编号、名称、核查逻辑、判定标准）
-3. 回读给开发者用户确认，特别注意：
-   - 是否遗漏了隐含的前提条件
-   - 阈值和标准是否准确
-   - 是否有例外情况没提到
-4. 在规则来源中标注「专家经验」而非法规条文
-
-## 规则目录管理
-
-所有提取的规则汇总为一份轻量级目录，存放在工作空间根目录的 `rule-catalog.json` 中：
-
-```json
-{
-  "rules": [
-    {
-      "id": "R001",
-      "name": "发票日期有效性",
-      "source": "《增值税发票管理办法》第十五条",
-      "status": "extracted",
-      "priority": "high",
-      "skill_folder": "rule-skills/R001-invoice-date-validity/",
-      "notes": ""
-    }
-  ],
-  "total": 1,
-  "extracted": 1,
-  "skill_authored": 0,
-  "workflow_distilled": 0,
-  "last_updated": "<时间戳>"
-}
-```
-
-### 状态流转
-
-每条规则的生命周期状态：
-
-```
-extracted → skill_authored → skill_tested → workflow_distilled → workflow_tested → production
-```
-
-目录中实时跟踪每条规则所处的阶段。
-
-## 处理模糊与歧义
-
-法规条文中经常存在模糊表述，如「合理期限内」「必要时」「视情况而定」。处理原则：
-
-1. **先提取，不要跳过**——模糊不等于不重要
-2. **在规则中标注歧义**——明确指出哪个部分存在解读空间
-3. **向开发者用户确认**——提供你的理解，请开发者用户裁定
-4. **确认后更新规则**——将开发者用户的裁定写入规则描述
-
-绝对不要自行决定模糊条款的含义。你对业务的理解不如开发者用户。
-
-## 法规变更时的处理
-
-当 `Rules/` 中新增或修改了法规文件时：
-
-1. 对比新旧版本，识别变更点
-2. 定位受影响的已有规则
-3. 判断影响程度：
-   - 措辞调整但核查逻辑不变——更新引用文本，无需重新测试
-   - 阈值或标准变更——更新规则参数，需要重新测试
-   - 新增核查要求——提取新规则
-   - 废止原有要求——将规则标记为 `deprecated`，不删除
-4. 更新规则目录
-5. 通知开发者用户变更影响范围
-
-## 输出交付物
-
-规则提取阶段完成后，应产出：
-
-1. `rule-catalog.json`——规则总目录
-2. 每条规则的初始描述文档（存放在对应技能文件夹的草稿中）
-3. 模糊与歧义清单（待开发者用户确认）
-4. 交叉引用映射（规则之间、规则与法规之间的引用关系）
-5. 向开发者用户汇报提取结果的摘要
+Regulations evolve. When the developer user adds new or updated regulation documents:
+1. Identify which existing rules are affected.
+2. Extract new rules or update existing ones.
+3. Mark affected workflows for re-testing.
+4. Use `version-control` to track the change.