Yuandian Law Search

元典法条与案例检索

通过元典开放平台 API 检索中国法律法规条文和案例。每次 API 调用消耗 1-50 积分（视接口而定）。所有检索结果会自动归档到本地，方便后续回溯。

前置要求（每次调用前自动检测）

每次使用本技能前，必须先执行以下检测流程，确认 API Key 已就绪：

检测步骤

1. 检测 `.env` 文件：检查 scripts/.env 是否存在 2. 检测 API Key：读取文件中 YD_API_KEY 的值，确认非空且不是占位符 your-api-key-here 3. 若检测失败，向用户提示以下引导信息并终止：

⚠️ 元典 API Key 未配置。请按以下步骤获取并配置：

1. 注册/登录：访问 https://open.chineselaw.com ，使用手机号注册
2. 创建 API Key：登录后在个人中心创建 Key
3. 配置密钥：将 Key 填入以下文件

   scripts/.env
   ─────────────
   YD_API_KEY=sk-你的密钥
   # YD_STRATEGY=balanced
   ─────────────

每次调用消耗 10 积分，需在平台充值。
配置完成后重新发起检索即可。

4. 若检测通过，继续执行用户请求的检索命令

检测命令

# 检测 .env 文件和 API Key
if [ -f "scripts/.env" ]; then
  KEY=$(grep '^YD_API_KEY=' scripts/.env | cut -d'=' -f2)
  if [ -n "$KEY" ] && [ "$KEY" != "your-api-key-here" ]; then
    echo "API Key 已就绪"
  else
    echo "API Key 未配置"
  fi
else
  echo ".env 文件不存在"
fi

# 读取检索策略
STRATEGY=$(grep '^YD_STRATEGY=' scripts/.env 2>/dev/null | cut -d'=' -f2)
echo "当前策略：${STRATEGY:-balanced}"

网络环境与推荐调用入口

默认使用 scripts/yd-run 执行检索，而不是直接调用底层 yd_search.py。yd-run 会以干净环境启动 Python：清除 Codex/代理相关环境变量，保留 HOME、PATH、语言环境、YD_API_KEY、YD_STRATEGY，并继续读取 scripts/.env 和 archive/ 缓存。

scripts/yd-run search "正当防卫的限度" --sxx 现行有效

若遇到 nodename nor servname provided, or not known 或其他网络错误，先执行无积分消耗的网络检查：

scripts/yd-run --network-check

注意：yd-run 只能避免 Codex 进程环境变量、代理变量和 PATH 漂移造成的影响；如果 Codex 本身以网络沙箱启动，或系统代理/VPN 接管 DNS，子进程仍会受到系统级网络策略影响。终端 Codex 应使用 --sandbox danger-full-access --ask-for-approval never 启动。

接口速查

本技能共 35 个接口，分为四层。选择规则：

1. 用户问"XX法怎么规定的" → 先用 search 语义检索 2. 用户问"关于XX的法律条文" → 用 keyword 关键词检索 3. 用户问"民法典第XX条" → 用 detail 精确获取 4. 用户给出明确案由/关键词并要求精确筛选案例 → 用 case 关键词检索（默认普通案例） 5. 用户描述事实结构、争议焦点或问"类似案件怎么判" → 优先用 case-semantic 语义检索 6. 用户要求更深入了解某案例 → 提醒用户将消耗积分，确认后用 case-detail 7. 用户要求企业背景调查 → 先用 enterprise-search 定位，再用 enterprise-base/enterprise-summary 获取详情 8. 用户要求查询企业分项信息（涉诉、商标、专利等） → 用 enterprise-list --type TYPE 9. 用户要求检测文本中法规/案例是否准确 → 用 hall-detect

核心接口（默认使用）： search · keyword · detail · case · case-semantic 扩展接口（需确认）： regulation · regulation-detail · case-detail · case --authority-only 附属接口（仅限明确要求）： enterprise · enterprise-detail · enterprise-search · enterprise-base · enterprise-summary · enterprise-list 专项接口（仅限明确要求）： hall-detect

调用策略

读取 scripts/.env 中的 YD_STRATEGY 配置（默认 balanced）。三种策略决定了 AI 的接口使用、确认流程和补充检索行为。

用户的明确指令始终优先于策略默认行为。

通用规则（所有策略共享）

每次 API 调用消耗 1-50 积分（视接口而定）。以下规则不受策略影响：

1. 必须调用 API：需要引用具体法条文号 / 需要确认时效性 / 用户明确要求检索 / 案例检索 / AI 对自身记忆不确定 2. 可以不调用：纯概念性问题 / 对话中已检索过相同内容 / 用户未要求查找 / 用户明确说不需要查 3. 积分消耗模式：大部分接口每次 5-10 积分，幻觉检测 50 积分，轻量企业检索 1 积分。法条检索通常一次足够。案例检索是两阶段消耗（摘要 10 + 详情 每个 10） 4. 接口分层：核心（search·keyword·detail·case·case-semantic）、扩展（regulation·regulation-detail·case-detail·case --authority-only）、附属（enterprise·enterprise-detail·enterprise-search·enterprise-base·enterprise-summary·enterprise-list）、专项（hall-detect）

均衡策略（balanced，默认）

即当前"正确性优先"策略，不改变现有行为。

• 核心接口：直接使用，无需确认
• 扩展接口：调用前告知用户将消耗积分，等待确认
• 附属接口：仅当用户明确要求时使用
• case-detail：先展示摘要，由用户主动选择感兴趣的案例后再调用
• 补充检索：不主动运行语义+关键词双检索，选择最合适的一种
• 积分报告：每次检索后说明消耗和累计

省钱策略（economical）

在 balanced 基础上进一步收紧，最大限度减少积分消耗。

• 核心接口：直接使用，但应先检查归档缓存是否有类似结果
• 扩展接口：需用户二次确认（第一次只展示摘要和积分提醒，等用户再次确认后才调用）
• 附属接口：仅当用户明确要求时使用，同样需确认
• case-detail：仅当用户指定具体案例编号时才调用，不主动提供"是否查看详情"选项
• 补充检索：不运行补充检索，一次只用一种模式
• 积分报告：每次检索后详细报告，并提醒可用的节约手段

激进策略（aggressive）

不考虑积分消耗，最大化检索精度和覆盖面。

• 所有接口：直接使用，无需确认
• case-detail：自动获取最相关的 2-3 个案例的完整判决书，不需用户逐一选择
• 补充检索：对同一问题同时运行语义+关键词双检索，合并去重后展示
• 积分报告：简要说明消耗即可，不强调节约
• 额外行为：法条检索后发现相关法规（如司法解释），主动追加 regulation 检索；用户需求模糊时，宁可多查也不漏查

接口策略速查

部分接口在通用规则之上有特殊行为约束（按积分成本或权限敏感度划分）：

关键词扩展与典型工作流

AI 在执行检索前应主动扩展关键词（上位概念 / 并列概念 / 程序-实体关联）， 并在多场景下遵循典型工作流与积分反馈原则。详见：

• `references/01-keyword-expansion.md` — 关键词扩展三原则、--expand 参数、分阶段检索示例、策略兼容性
• `references/02-typical-workflows.md` — 法条 / 案例 / 关键词精确 / 企业尽调 / 幻觉检测 / 企业风险排查六大场景 + AI 向用户反馈的 8 条原则（含 per-call 报告落盘与禁止复制到目标目录的硬规则）

检索模式选择

每个领域有语义检索和关键词检索两种模式。

用语义检索：用户提出法律问题 / 描述场景 / 不确定关键词 / 需要广覆盖 → 不确定时默认用 用关键词检索：用户给出明确关键词 / 需要 AND/OR 逻辑 / 需按日期、效力级别、法院等精确筛选 / 语义检索结果不够聚焦 案例检索红线：综合案件和类案对标的第一轮优先 case-semantic；case 只放 4-6 个高信息密度关键词，避免长事实结构默认 AND 导致零命中。

此外需区分检索法条还是案例："XX的法律依据" → 法条检索；"有没有相关案例" → 案例检索；兼要法条和案例 → 先法条后案例，两次调用。

核心接口用法

1. 法条语义检索（search）

scripts/yd-run search "正当防卫的限度" --sxx 现行有效

2. 法条关键词检索（keyword）

scripts/yd-run keyword "人工智能 监管" \
  --effect1 法律 --sxx 现行有效 \
  --fbrq-start 2022-01-01 --fbrq-end 2026-03-01

3. 法条详情检索（detail）

scripts/yd-run detail "民法典" --ft-name "第十五条"

4. 案例关键词检索（case）

# 普通案例（默认）
scripts/yd-run case "买卖合同纠纷" --province 广西

# 权威案例（扩展，需确认）
scripts/yd-run case "买卖合同纠纷" --province 广西 --authority-only

5. 案例语义检索（case-semantic）

scripts/yd-run case-semantic "正当防卫的限度" --jarq-start 2020-01-01

扩展接口用法

6. 法规关键词检索（regulation）

scripts/yd-run regulation "数据安全" --effect1 法律 --sxx 现行有效

7. 法规详情（regulation-detail）

scripts/yd-run regulation-detail --name "中华人民共和国数据安全法"

8. 案例详情（case-detail）

scripts/yd-run case-detail --type ptal --ah "（2025）桂09民终192号"

9. 企业检索（enterprise）

scripts/yd-run enterprise "华为" --num 5

10. 企业详情（enterprise-detail）

scripts/yd-run enterprise-detail --credit-code "9144030071526726XG"

幻觉检测

11. 法规/法条/案例幻觉检测（hall-detect）

检测文本中引用的法规、法条、案例是否存在幻觉（是否真实存在、内容是否准确）。每次调用消耗 50 积分。

scripts/yd-run hall-detect "根据《中华人民共和国数据保护法》第35条规定，数据处理者应当..."

返回结果包含：

• 法规检测：每条法规是否真实存在（law_exists），语义比对结论和相似度
• 案例检测：每条案例是否真实存在，基本事实和裁判要点
• 高亮文本：标注了检测结果的原文本

企业全息画像

企业信息类接口（enterprise-search / enterprise-base / enterprise-summary / enterprise-list）的完整用法、--type 可选维度（涉诉、商标、专利、对外投资、股权冻结等 20 类）与积分消耗表见：

`references/06-enterprise-portrait.md`

通用参数说明

法条检索通用筛选

案例检索通用筛选

Reference 文档索引

工作流指南

• 关键词扩展与分阶段检索
• 典型工作流与用户引导
• 法律检索报告与目标目录归档
• 法律检索报告 7 节设计原理
• MCP 协同工作流
• 企业全息画像

接口清单与 API 端点文档

endpoints/MANIFEST.json 记录全部已适配接口的元数据（端点、子命令、分层、分类），以及平台接口排查历史。下次排查新增接口时，更新该文件的 check_history 即可。

历史检索记录

每次 API 调用的完整结果会自动归档到 archive/ 目录。当用户提到"之前查过什么"时，AI 可以直接从归档中提取历史结果，无需重新调用 API。

archive/<ts>_<query>.json 是机器可读版（response/query/fingerprint/source_urls 全字段），archive/<ts>_<query>.md 是同次检索的人类可读版（结构化报告），两者一一对应。同一份报告的副本会同步写入用户运行命令时的工作目录（<CWD>/<ts>_<query>.md），便于附卷。

浏览历史记录：

scripts/yd-run archive-list
scripts/yd-run archive-list --keyword "正当防卫"

如果用户说"之前查正当防卫的时候看到一个案例"，AI 应先用 archive-list --keyword "正当防卫" 找到对应的归档文件，然后直接读取其中的 response 字段返回给用户。这不需要消耗积分。

调试

scripts/yd-run raw /open/law_vector_search "正当防卫" --extra '{"fatiao_filter":{"sxx":["现行有效"]}}'

法律检索报告（consolidate）

多次检索之后，把 per-call 报告汇总成一份完整的法律检索报告。这是律师/客户看的交付物，per-call 报告是数据底稿。

7 节"结论先行"标准结构

核心原则：用户最想知道的是最终结论（能不能做、怎么做、风险在哪），法条和案例只是用来核实结论的支撑材料。所以结构应是 结论先行 → 分析支撑 → 检索底稿垫后。

模板文件位于 templates/legal-research-report.md；scripts/yd-run consolidate 会按同一结构自动生成报告。

1. 案情简介 — 当事人、争议焦点、当前阶段（最少必要） 2. 检索目的与问题 — 本次检索要回答的法律问题（1-3 个核心 Q） 3. 检索结论 ⭐ — 最先读到的内容：

• 3.1 一句话定性（"能做/不能做" + 法律依据）
• 3.2 核心论点的判例支撑速查（用表格/列表，让用户 30 秒内 get 到）
• 3.3 风险点（诚实告知，不要只说好的）
• 3.4 后续行动（具体可执行的步骤）

4. 分析与判断 — 抗辩应对、法条适用、诉讼请求结构、赔偿酌定、证据准备 5. 检索思路与方法 — 关键词组合、筛选条件、检索顺序（备查） 6. 检索结果 — 按 endpoint 分组：6.1 法律依据 / 6.2 司法案例 / 6.3 行政法规 / 6.4 其他（核实材料） 7. 检索明细 — 表格，链接到每条 per-call 报告（末尾，使用可回溯本地链接）

检索报告质量要求

• 结论区必须能独立阅读：3.1-3.4 应让律师、客户或法官先得到答案，再决定是否看底稿
• 核心依据用表格速查：不要让读者从几十条法条/案例中自行拼结论
• 方法区保留检索痕迹：写清关键词、筛选条件、平台、时间、纳入规则
• 结果区只放支撑材料：法条、案例、法规按类型分组，不替代第四节分析
• 风险必须明示：包括不利类案、法律适用分歧、地域差异、时效或证据缺口
• 无法确认的信息标注待补充：不要把检索不到或材料未提及的事实写成确定结论

节号从 1 重新编号（案情=1，结论=3，结果=6，明细=7），不沿用 1-6 顺序编号；体现"结论在第 3 节"的视觉位置。

反例（曾出现过的旧版结构）：

• 案情 → 目的 → 思路 → 检索结果 → 分析 → 结论
• 用户反馈：检索结果（法条案例）全是"核实材料"，要翻到最后才看到结论 → 太累
• 新版：结论放到第 3 节，用户看完 3.1-3.4 就能得到 80% 答案

末尾附"本次检索明细"表格，链接到每条 per-call 报告。

调用方式

scripts/yd-run consolidate \
    --title "张某买卖合同违约金调整" \
    --project "case-2024-zhangsan" \
    --case "案情：..." \
    --strategy "检索思路：..." \
    --analysis "分析与判断：..." \
    --conclusion "一句话结论：..." \
    --risks "主要风险：..." \
    --next-actions "后续行动：..." \
    --include "违约金,高空抛物"

• --case / --strategy / --analysis 必填：AI 显式传本次任务的案情/思路/判断
• --include 必填：逗号分隔的查询子串，明确指定"本次任务范围"（不取最近 N 条）
• 匹配规则：CWD 中所有符合 <8位时间戳>_<6位时间戳>_<查询>.md 命名的 .md 文件，文件名包含任一子串即被纳入
• --project 可选：项目子目录名。默认从 --title slugify（如 "张某买卖合同违约金调整" → "张某买卖合同违约金调整"）。用于 archive/<project>/ 归类
• --title / --purpose / --conclusion / --risks / --next-actions / --output 可选
• --purpose 不传则基于检索词自动生成
• --conclusion 强烈建议传入；不传会在 3.1 保留补写提示
• --risks / --next-actions 不传会保留补写提示
• --output 默认同时写 CWD 和 archive/<project>/；指定则只写到指定路径

项目子目录组织

consolidate 会把这次任务的所有文件归类到 archive/<project>/ 子目录：

archive/
  case-2024-zhangsan/
    20260610_192031_货款逾期违约金_司法实践.json   ← 从 archive/ 根目录移入
    20260610_192031_货款逾期违约金_司法实践.md    ← 从 CWD 复制
    20260610_192032_逾期付款_违约金_调整.json
    20260610_192032_逾期付款_违约金_调整.md
    20260610_192058_法律检索报告.md                ← 主交付物

• .md 复制（CWD 保留工作副本）：用户的工作目录不被破坏
• .json 移动（archive 根目录已清理）：避免根目录重复积累，扁平区只放"in-flight 暂存"
• 重复运行 consolidate 同一项目：idempotent，文件已在子目录则跳过

与 per-call 报告的关系

多次 yd-run 检索（自动写 per-call .md 到 archive + CWD）
       ↓
AI 汇总判断后调 consolidate --project "case-x"
       ↓
创建 archive/case-x/，.md 复制进来，.json 移进来，法律检索报告写进去
       ↓
CWD 也有法律检索报告副本，per-call .md 仍在 CWD（工作副本）
       ↓
报告末尾的"检索明细表"链接回 archive/case-x/ 里的副本

per-call .md 是数据底稿，可独立查看；session 报告是主交付物，附案情/思路/判断；项目子目录是组织容器。

目标目录归档规范（强制）

目标目录（通常是案件文件夹 02 - 案件分析 / 03 - 法律研究 等）与 AI 进程的 CWD 是不同的两个位置。 目标目录只允许出现：整合后的法律检索报告 + 外部素材 + 基于整合报告再生成的下游文件； 禁止 per-call 检索记录、检索明细 JSON、AI 进程 CWD 的工作副本。

完整规则（标准工作流 4 步、反例、验证清单 4 条）见：

`references/03-report-consolidation.md`

MCP 协同工作流（v1.6.0+）

元典官方 MCP（https://open.chineselaw.com/mcp-config）已发布，3 个 servers：yuandian-law（法律法规）、yuandian-case（案例文书）、yuandian-company（企业信息）。本 skill 的价值现在转向"归档 + 法律检索报告生成"——数据接入由 MCP 负责，本 skill 负责沉淀。

完整工作流（元典 MCP 接入配置、Agent 三步法、ingest 子命令、模式选型表）见：

`references/05-mcp-workflow.md`

版本更新

脚本每 7 天自动检测远程版本。也可手动检查：

# 检查是否有新版本（会显示最近提交记录）
scripts/yd-run check-update

# 执行更新（仅下载本 skill 目录下的文件，不影响其他目录）
scripts/yd-run do-update

do-update 仅更新 yuandian-law-search/ 目录下的文件，不会修改 .env（API Key）和 archive/（历史检索记录）。

变更日志

[1.7.4] - 2026-06-15

修复

• 修复 keyword / case / regulation 的 --expand 自动 OR 逻辑：参数解析层不再把 --search-mode 默认填成 and，处理函数可正确识别"用户未显式指定"并在扩展检索时切换为 OR。
• 修复 references/03-report-consolidation.md 与 references/02-typical-workflows.md 中重命名后的旧文件链接。
• 统一版本号：SKILL.md、scripts/yd_search.py、scripts/MANIFEST.json、根 README.md 与 marketplace 条目同步到 1.7.4。

改进

• 强化案件综合分析和标杆类案场景的检索执行约束：第一轮优先 case-semantic，关键词检索只保留 4-6 个高信息密度词，零命中时必须改用语义检索或 OR 复检。
• 补充 marketplace 条目，便于插件市场按当前版本发现和分发 yuandian-law-search。
• 调整 .gitignore 例外，使本技能的 DECISIONS.md 与 TASKS.md 可纳入版本控制。

[1.7.3] - 2026-06-15

修正（v1.7.1 反思有误）

• v1.7.1 在"争议焦点识别"小节中错误地将二分法归入"用户原始争议焦点"——二分法实际是 AI 检索之后才提炼出来的分析工具，不是用户最初提问的内容
• 真实情况：用户最初就已明确给出关键事实要素和法条抓手，第一轮应该直接用这些用户原话作为检索词，不需要先等"检索后再提炼二分法"
• 修正 `references/02-typical-workflows.md`：
• 删除"关键区分点"字段（避免诱导 AI 自己去找二分法）
• 新增"用户已明确的论点"字段（强调直接用用户原话作检索词）
• 关键提示新增"二分法是结果不是起点"
• 路径修正：因 v1.7.2 重命名 00-typical-workflows.md → 02-typical-workflows.md，编辑目标相应更新

[1.7.2] - 2026-06-15

整理

• `references/` 序号重编：6 个 00-*.md 工作流指南改为 01-06 顺序编号（按 SKILL.md Reference 文档索引的引用顺序），便于按序阅读和稳定排序
• 01-keyword-expansion.md（基础：关键词怎么扩）
• 02-typical-workflows.md（应用：典型场景）
• 03-report-consolidation.md（专题：报告整合）
• 04-report-design-notes.md（专题：报告设计原理）
• 05-mcp-workflow.md（专题：MCP 协同）
• 06-enterprise-portrait.md（专题：企业全息画像）
• 同步更新 SKILL.md、scripts/MANIFEST.json 中所有引用

简化

• "新接口策略矩阵"小节去重话术：SKILL.md 调用策略章节尾部表格本身保留（hall-detect / enterprise-search / enterprise-base+summary / enterprise-list 四个接口在三种策略下的具体行为），仅去掉"新/旧接口"区分话术——所有接口统一视为同一层级，按其分层套用对应策略

[1.7.1] - 2026-06-15

工作流补充（基于近期案件检索偏差复盘）

• `references/00-typical-workflows.md` 新增 2 节强制工作流：
• 争议焦点识别优先场景：第一轮检索前必须先填 5 字段识别表（行为主体 / 角色定位 / 行为模式 / 关键区分点 / 抗辩点），避免直接按泛化法律概念展开检索
• 标杆案例对标检索场景：用户第一轮提供标杆案例时，必须提取其"事实结构骨架"作为查询模板，并用"对标度评分"过滤命中案例
• 核心理念沉淀：
• 行业术语 > 法律术语（用户用什么行业说法就用什么行业说法作检索词，不要预先翻译成法律术语）
• 二分法思维：争议焦点背后往往有关键二分，二分点决定结论方向
• 主动找反面案例：搜完正面后专门搜一次"被告不担责""被告无过错"等反面表述，反面案例能反向锚定争议焦点的关键区分
• 典型反例：错搜泛化法律概念 → 命中与案情不匹配的偏差案型；正搜基于用户原话 + 行业术语描述事实结构（语义检索）→ 命中对位案

[1.7.0] - 2026-06-15

重构

• 目录结构重构（按 skill-lint 审查建议解耦）：
• 35 个 API 端点文档（01-law-vector-search.md ~ 35-enterprise-serious-illegal.md）从 references/ 迁入新建的 endpoints/
• references/MANIFEST.json 同步迁入 endpoints/MANIFEST.json
• references/ 仅保留工作流指南，新增 6 个 00-*.md：
• 00-keyword-expansion.md — 关键词扩展三原则、--expand 参数、分阶段检索、策略兼容性
• 00-typical-workflows.md — 五大场景 + AI 向用户反馈的 8 条原则
• 00-enterprise-portrait.md — 企业信息类 4 个接口（enterprise-search / base / summary / list）的完整用法与 20 类 --type 维度
• 00-report-consolidation.md — consolidate 调用方式、项目子目录组织、目标目录归档规范
• 00-report-design-notes.md — 7 节"结论先行"的设计动机、反例、节号逻辑、质量要求
• 00-mcp-workflow.md — 元典 MCP 接入配置、Agent 三步法、ingest 子命令、模式选型表
• templates/legal-research-report.md 保留并明确为可维护的模板参考（yd_search.py 当前仍用代码内 f-string 渲染，模板作为格式约定）
• SKILL.md 由 809 行压到 494 行（-39%）：4 个大章节（关键词扩展、典型工作流、企业全息、MCP 协同）拆到 references/，7 节报告与目标目录归档保留短引用

发布治理

• scripts/MANIFEST.json 同步升到 1.7.0，完整覆盖 endpoints/ + references/ + templates/ 全部文件（之前仅列了 11 个 references，updater 实际未更新 12-35）
• README.md 中 references/01~11-*.md 改为 endpoints/01~35-*.md，MANIFEST.txt 改为 MANIFEST.json
• "版本演进"表格新增 v1.7.0 行

[1.6.1] - 2026-06-15

改进

• 优化 consolidate 法律检索报告模板：从旧的"检索结果在前、结论在后"调整为 7 节结论先行结构，先呈现一句话定性、核心依据速查、风险与后续行动，再展示分析、方法、检索结果和明细。
• 新增 templates/legal-research-report.md，沉淀可维护的法律检索报告模板，便于后续单独调整报告结构。
• consolidate 报告头新增检索主体、检索平台、项目包等可核查信息；第七节检索明细改用可回溯本地链接。
• consolidate 新增 --risks 和 --next-actions 参数，用于填充结论区的风险与后续行动；--conclusion 未传时保留明确补写提示。

修复

• 修复 consolidate 将 per-call JSON 移入项目子目录后，后续分组读取仍指向旧路径，导致法律依据/案例/法规分组可能丢失的问题。

文档完善

• SKILL.md 同步更新 7 节报告结构、质量要求、调用方式和目标目录归档口径。

[1.6.0] - 2026-06-11

战略转向

• 元典官方已发布 MCP（https://open.chineselaw.com/mcp-config），3 个 servers：yuandian-law / yuandian-case / yuandian-company
• 本 skill 价值从"API 包装"转向"归档 + 法律检索报告生成"——agent 用 MCP 调数据，本 skill 负责沉淀
• v1.6.0 起，本 skill 同时支持两种调用模式：

1. 直接 API 模式（原有 search/case/... 子命令，保留兼容） 2. MCP 协同模式（新增 ingest 子命令，消费 MCP 输出 JSON）

新增

• `ingest` 子命令（v1.6.0 核心）：
• 用法：yd-run ingest --query "<Q>" --endpoint "/open/<E>" --input <file.json>（或 stdin pipe）
• 必填：--query、--endpoint
• 可选：--cost（默认 "10 积分"）、--no-report、--no-cwd-report
• 消费外部 JSON（来自 MCP 或其他源），路由到对应 formatter，走与直接 API 相同的归档 + .md 流程
• 归档记录额外加 "ingest": true 标记，便于区分数据来源
• `INGEST_ROUTING` 表（36 个 endpoint 覆盖）：
• 法条 4 个（law_vector_search / rh_ft_search / rh_ft_detail + 1）
• 法规 2 个（rh_fg_search / rh_fg_detail）
• 案例 4 个（case_vector_search / rh_ptal_search / rh_qwal_search / rh_case_details）
• 企业主接口 4 个（rh_enterpriseSearch / rh_company_info / rh_company_detail / rh_enterpriseBaseInfo）
• 企业分项列表 21 个（OutInvest/Brand/Patent/SoftRight/WorksRight/Icp/ChangeInfo/WritAgg/WritList/CourtSessionNotice/CourtNotice/Executions/ExecutedPerson/FrozenEquity/Punishment/Pledge/Guaranty/AbnormalOperation/CorporateTax/SeriousIllegal/AnnualReport）
• 特殊 2 个（hall_detect 用对应 formatter；rh_enterpriseAggregationSummary 用 raw JSON 包装）
• 未知 endpoint 走 raw JSON 兜底（包装为 ``json ... `` 代码块）
• `.mcp.json.example` 模板（skill 根目录）：
• 3 个 yuandian-* MCP servers 配置（law/case/company）
• Authorization: Bearer ${YD_API_KEY} 鉴权
• 用户复制为 .mcp.json 后让 Claude Code / Cursor / Codex 等客户端自动加载
• 企业分项列表 endpoint 自动 label 推断（如 /open/rh_enterpriseOutInvest → "对外投资"），无需 --label 参数

改进

• SKILL.md 新增"MCP 协同工作流"章节，描述 agent 如何同时使用 mcp__yuandian__* 工具 + yd-run ingest + yd-run consolidate
• INGEST_ROUTING 路由表覆盖元典 MCP 暴露的全部 24 个数据 tools（不含 2 个 meta tools）

架构关系

agent 调用流程:
1. mcp__yuandian_law__yuandian_law_vector_search("违约金")  ← MCP 直接调元典
2. 把响应 JSON 喂给 yd-run ingest                             ← 本 skill 归档
3. 多次 ingest 后, yd-run consolidate --project "..."        ← 生成 6 节法律检索报告

向后兼容：原有 search/case/detail/... 直接 API 子命令完全保留，YD_API_KEY 用户可继续用。

[1.5.1] - 2026-06-10

新增

• consolidate 项目子目录组织（用户反馈：一次研究任务会产生多个 .json + .md，平铺在 archive/ 不便按项目查找）
• 新增 --project "<name>" 参数（可选，默认从 --title 自动 slugify）
• consolidate 创建 archive/<project>/ 子目录作为"项目包"
• per-call .md 从 CWD 复制到项目子目录（CWD 保留工作副本）
• per-call .json 从 archive/ 根目录移动到项目子目录（archive 根保持清爽，不重复）
• 法律检索报告双写：archive/<project>/<ts>_法律检索报告.md（项目包）+ CWD（工作副本）
• 报告末尾"项目包"标识：> 项目包：archive/<project>/
• 重复运行 consolidate 同一项目：idempotent，文件已在子目录则跳过移动/复制

改进

• consolidate 报告头增加项目包路径引用，方便用户定位

[1.5.0] - 2026-06-10

新增

• session-level 法律检索报告（consolidate 子命令）：把多次检索的 per-call 报告汇总成一份标准结构的法律检索报告
• 调用方显式传 --case / --strategy / --analysis 三个核心字段（AI 填）
• --include 必填，逗号分隔的查询子串，明确指定"本次任务范围"（不取最近 N 条）
• 6 节标准结构：案情简介 / 检索目的与问题 / 检索思路与方法 / 检索结果（4.1 法条 + 4.2 案例 + 4.3 法规 + 4.4 其他，按 endpoint 自动分组）/ 分析与判断 / 检索结论
• 附录"本次检索明细"表格：时间/检索词/接口/积分/md·json
• 4.4 其他：自动收纳未归类到法律/案例/法规的检索（如 hall-detect、enterprise-*）
• --purpose 可选：不传则基于检索词自动推断
• --conclusion 可选：不传则提示"详见第五节"
• --output 可选：默认 <cwd>/<ts>_法律检索报告.md

改进

• per-call .md 报告元信息移除"检索接口"字段（用户反馈：API 端点太技术化，不属于报告内容）

架构关系

• per-call .md = 检索明细（数据底稿，每次检索自动写 archive + CWD）
• session 报告 = 主交付物（法律检索报告，按任务粒度由 AI 触发 consolidate 生成）
• session 报告的"检索明细表"链接到 per-call .md，整套形成完整溯源链

[1.4.0] - 2026-06-10

新增

• 检索报告 .md 自动落盘：每次实际检索（cache miss 时）落盘两份结构化 Markdown 报告
• archive/<ts>_<query>.md：与 archive JSON 配对，技能内部归档
• <CWD>/<ts>_<query>.md：用户运行命令时的工作目录副本，方便附卷/分享
• 报告模板：元信息（时间/接口/关键词/积分/原始数据路径/工作目录副本）+ 检索结果（与 stdout 一致）+ 引用来源（按类型分组）+ 数据来源声明
• 复用现有 5 个 formatter（format_law_results / format_case_results / format_regulation_results / format_enterprise_results / format_hall_detect_results）填充"检索结果"段，零行为变化
• 新增 --no-report 全局 flag：跳过 .md 报告生成（archive + CWD），仅写 archive JSON
• 新增 --no-cwd-report 全局 flag：仅跳过 CWD 副本，仍写 archive/ 报告
• 调用结束后 footer 追加报告路径提示（archive + CWD，CWD 失败时不显示第二行）
• CWD 副本写入失败时 stderr 警告但不中断（archive 副本是主落点，best-effort 容错）

改进

• api_post / api_get 返回值从 2-tuple 改为 3-tuple (result, cached, archive_path)，让 cmd_* 能拿到 archive 路径以驱动报告生成
• 5 个有自定义成本的端点（hall-detect 50、enterprise-search 1、enterprise-base 10、enterprise-summary 10、enterprise-list 5/10）准确把成本传递到报告元信息头

[1.3.4] - 2026-05-27

新增

• 新增 scripts/yd-run 干净环境运行入口，默认清理 Codex/代理相关环境变量后再调用 yd_search.py。
• 新增 scripts/yd-run --network-check 网络预检，用于无积分消耗地检查 open.chineselaw.com 和 ydzk.chineselaw.com 的 DNS 与 TLS 连通性。

文档完善

• SKILL.md 和 README.md 改为推荐使用 scripts/yd-run，降低 Codex 网络沙箱、PATH 漂移和代理环境变量对元典检索的影响。

[1.3.3] - 2026-05-13

新增

• archive 归档记录新增 source_urls 字段：自动提取/构造法条、案例、法规、企业的来源链接，方便后续检索时提供核实出处
• backfill-urls 子命令：一次性回填现有 archive 的 source_urls（已回填 36 个文件）

改进

• 法条语义检索（law_vector_search）和案例语义检索（case_vector_search）等无 URL 的接口，根据 fgid/scid 自动构造完整链接
• 法条详情（rh_ft_detail）、案例关键词（rh_ptal_search）等返回相对 URL 的接口，归档时自动转为完整 URL

[1.3.2] - 2026-05-10

新增

• 新接口策略矩阵：为 hall-detect、enterprise-search、enterprise-base/summary、enterprise-list 四类新增接口补充 balanced/economical/aggressive 三种策略下的具体行为指导
• 企业尽调工作流：enterprise-search → enterprise-base → enterprise-summary → enterprise-list 四步尽调流程
• 幻觉检测工作流：引用识别 → AI 建议 → 用户确认 → hall-detect 检测 → 结果展示
• 企业风险排查工作流：enterprise-summary 总览 → enterprise-list 深挖高风险项 → 风险画像汇总

改进

• enterprise-list 子命令新增策略感知默认 size：economical 模式默认 10 条，aggressive 模式默认 50 条，balanced 保持 30 条

[1.3.1] - 2026-05-10

新增

• 关键词扩展检索：keyword、case、regulation 子命令新增 --expand 参数，支持传入逗号分隔的扩展关键词，自动追加到原始查询并以 OR 模式检索
• 分阶段检索指引：SKILL.md 新增「关键词扩展与分阶段检索」章节，说明 AI 应如何主动扩展法律概念、执行广撒网+精提炼的两阶段检索
• 扩展方向提示：检索完成后 AI 应向用户建议可能相关的扩展检索方向
• 策略兼容矩阵：明确关键词扩展行为与 balanced/economical/aggressive 三种策略的兼容关系

[1.3.0] - 2026-05-10

新增

• 适配 24 个元典开放平台新接口（从 11 个扩展至 35 个）
• 新增 5 个子命令：
• hall-detect：法规/法条/案例幻觉检测（50 积分）
• enterprise-search：企业轻量检索（1 积分），返回候选列表
• enterprise-base：企业基本信息查询（含股东、核心成员、分支机构）
• enterprise-summary：企业聚合总览
• enterprise-list：企业分项列表查询，支持 20 种类型（对外投资、商标、专利、涉诉文书、行政处罚等）
• 新增 format_hall_detect_results：幻觉检测结果格式化（法规存在性、语义比对、案例核实）
• 新增 format_enterprise_list_results：企业分项列表通用格式化函数
• 新增 24 个 Reference 文档（12-35），覆盖幻觉检测和企业全息画像系列接口
• 所有新子命令支持 --no-cache 选项
• MANIFEST.json 全部 35 个接口标记为已适配（adapted 字段移除，改为完整元数据）
• SKILL.md 接口清单从 11 个扩展至 35 个，新增幻觉检测和企业全息画像使用说明

改进

• 接口分层新增"专项"层（hall-detect）
• 附属接口层扩展：新增 enterprise-search·enterprise-base·enterprise-summary·enterprise-list
• 积分消耗说明从"每次 10 积分"更新为"1-50 积分（视接口而定）"
• CLI 帮助示例新增 5 个新子命令用法

[1.2.1] - 2026-05-10

改进

• 新增 references/MANIFEST.json：接口清单元数据文件，记录全部 11 个已适配接口的端点、子命令、分层和分类信息
• MANIFEST.json 包含 check_history 字段，记录每次平台接口排查的时间、方法和结论
• 排查元典开放平台（2026-05-10）：通过 Playwright 浏览器实际访问接口广场，发现平台从 11 个 API 扩展到了 35 个，新增 24 个未适配接口（1 个幻觉检测 + 23 个企业信息），已记录到 MANIFEST.json，待后续适配

[1.2.0] - 2026-05-09

新增

• 可配置检索策略（YD_STRATEGY）：balanced（均衡，默认）、economical（省钱）、aggressive（激进）
• strategy 子命令：显示当前检索策略
• 策略感知的默认返回数量：economical 模式下语义检索默认 20 条，aggressive 模式下关键词检索默认 20 条

改进

• SKILL.md 调用策略章节重构为三策略矩阵，清晰区分接口确认要求、案例详情触发方式、补充检索行为
• .env.example 新增 YD_STRATEGY 配置说明

[1.1.1] - 2026-04-18

修复

• datetime import 在 updater.py 重构时被误删，导致归档函数 NameError
• detail 子命令：API 返回单个 dict 而非列表，格式化函数崩溃
• case 子命令：API 返回 {total, lst} 结构而非裸列表，需从 data.lst 提取
• format_law_results 兼容 ftmc/tid 字段（detail 端点返回）
• format_case_results 兼容 cprq 字段（关键词检索返回的裁判日期）
• format_enterprise_results 兼容中文字段名（企业名称、统一社会信用代码、企业类型 等）
• 移除 _print_footer 中的缓存命中提示，归档重新定位为"历史检索记录"
• 新增 archive-list 子命令，支持按关键词浏览历史检索记录
• Reference 文档修正：05 案例关键词检索补充 cprq/type/url/llm_content 字段、07 案例详情补充返回结构、10 企业检索补充中英文字段映射
• 权威案例关键词检索（06）返回结构说明更新为 {total, lst} 包装格式

[1.1.0] - 2026-04-17

重大变更

• SKILL.md 大幅精简（~260 行 → ~170 行），策略内容抽取至 references/00-*.md
• Reference 文件按前缀分层：00- 策略指南、01-11 API 端点文档

新增

• 策略指南：检索模式选择指南（references/00-retrieval-mode-guide.md）
• 策略指南：接口优先级与选择规则（references/00-interface-priority.md）
• 积分节约策略合并回 SKILL.md，核心理念调整为"正确性优先于积分节约"
• SKILL.md 新增"积分消耗模式"小节，明确案例检索的两阶段消耗（摘要 10 积分 + 详情 10 积分/个）
• case 子命令新增 --fxgc、--yyft、--ft-search-mode 参数
• format_law_results 新增输出字段：发布日期、发布部门、发文字号、二级效力级别
• Reference 文件补充响应结构文档（02-law-keyword-search 完整 20 字段）
• archive/.gitkeep 确保归档目录不会被 git 忽略
• check-update 新增最近提交记录展示（通过 Atom feed，不依赖 GitHub API）
• check-update 新增 CHANGELOG 差异展示（读取远程 CHANGELOG.md 中本地版本之后的变更）
• do-update 子命令：仅下载本 skill 目录下的文件更新，不碰其他目录和 .env/归档
• 更新逻辑拆分为通用模块 scripts/updater.py（SkillUpdater 类），可被其他 skill 复用
• MANIFEST.txt 移至 scripts/ 目录，列出所有可更新文件

修复

• --rewrite-flag 参数使用 type=bool 导致任何字符串均为 True 的 bug，改为 store_true/--no-rewrite
• 移除所有旧 API（aiapi.ailaw.cn）中文字段名 fallback 死代码
• SKILL.md 注册地址更新为 https://open.chineselaw.com

[1.0.0] - 2026-04-17

重大变更

• API 平台迁移：从旧平台 (aiapi.ailaw.cn:8319) 迁移至开放平台 (open.chineselaw.com)
• 认证方式从 URL 查询参数改为 X-API-Key 请求头
• 语义检索请求体改为嵌套结构（fatiao_filter / wenshu_filter）
• 语义检索响应格式更新（extra.fatiao / extra.wenshu）
• 接口文档拆分为独立文件（references/01~11-*.md）

新增

• 法规关键词检索（regulation 子命令）
• 法规详情查询（regulation-detail 子命令）
• 案例详情查询（case-detail 子命令）
• 企业名称检索（enterprise 子命令）
• 企业详情查询（enterprise-detail 子命令）
• 语义检索新增 --rewrite-flag 和 --return-num 参数
• raw 子命令新增 --get 和 --no-cache 选项
• 归档机制：每次 API 调用自动归档至 archive/，相同查询命中归档不消耗积分
• 接口优先级分层：核心接口（5个）、扩展接口（4个）、附属接口（2个）

改进

• 案例关键词检索拆分为普通案例和权威案例两个端点
• 格式化函数兼容新旧字段名
• 超时时间从 30 秒提升至 60 秒

[0.3.1] - 2026-04-07

改进

• 移除「与其他技能配合」章节，保持技能描述独立聚焦

[0.3.0] - 2026-04-06

改进

• Front Matter 规范化：补充 homepage、author、version 字段

[0.2.0] - 2026-04-05

改进

• skill name 从 yd-law-search 改为 yuandian-law-search，提升辨识度
• 目录同步重命名为 yuandian-law-search
• 标题从"元典法条检索"改为"元典法条与案例检索"，准确反映 API 覆盖范围
• 许可证从 CC BY-NC-SA 4.0 改为 MIT
• 前置要求新增注册登录指引（账号注册 → API Key 创建 → 配置 .env → 验证连接）

[0.1.0] - 2026-04-03

设计缘由

• 元典法条检索 API 提供了法律条文和案例的语义/关键词检索能力，适合封装为 Skill 供法律分析场景使用。

思路演进

1. 分析 API 文档，梳理 5 个端点的功能和参数 2. 设计统一的 CLI 工具，用子命令区分不同检索模式 3. 输出格式化为 Markdown，方便 AI 直接引用

新增

• 初始版本，封装 5 个 API 端点
• 支持法条语义检索、关键词检索、详情检索
• 支持案例关键词检索、语义检索
• 输出 Markdown 格式化
• 支持原始 JSON 调试输出

法律法规语义检索

POST /open/law_vector_search

计费: 10 积分/次

请求参数（Body）

fatiao_filter 字段说明（以下均为可选）

一级效力级别（effect1）

宪法、法律、司法解释、行政法规、监察法规、部门规章、党内法规、军事法规规章、立法机关工作文件、行政机关工作文件、行业/团体规范、地方性法规、自治条例和单行条例、地方司法文件、地方政府规章、地方规范性文件、地方律协规定

返回结构

{
  "msg": "成功(返回结构化数据)",
  "code": 201,
  "answer": "",
  "extra": {
    "fatiao": [
      {
        "ftid": "法条id",
        "fgid": "法规id",
        "fgtitle": ["法规名称"],
        "num": "法条条目",
        "content": "内容",
        "sxx": "时效性",
        "effect1": "一级效力级别",
        "effect2": "二级效力级别",
        "dy": "地域",
        "location": "地域含市",
        "start": 20180311,
        "end": 99999999,
        "score": 0.306,
        "type": 1
      }
    ]
  }
}

通用返回字段

extra.fatiao[] 字段

法条关键词检索

POST /open/rh_ft_search

计费: 10 积分/次

请求参数（Body）

校验规则

• body 为空 JSON → 返回失败 message = "请求参数不能为空"
• keyword 为空 → 返回 501 message = "keyword 参数不可为空！"
• top_k: 未传或 ≤0 → 10，>50 → 50
• search_mode 未传或为空 → 默认 AND；否则转大写

返回结构

通用返回字段

data[] 单条元素字段

备注：法规回填字段只有在法规概要查询命中且能取到值时才会写入。

示例

请求：

{
  "keyword": "行政处罚",
  "search_mode": "AND",
  "fgmc": "中华人民共和国行政处罚法",
  "sxx": "现行有效",
  "top_k": 10
}

成功响应（200）：

{
  "code": 200,
  "data": [
    {
      "id": "0c15f68cf89e1339125e9f41d5d31c67_59",
      "_score": 52.88,
      "ftmc": "中华人民共和国行政处罚法(2021修订)第五十九条",
      "title": "中华人民共和国行政处罚法(2021修订)第五十九条",
      "fgid": "0c15f68cf89e1339125e9f41d5d31c67",
      "tid": "59",
      "url": "/zxt/statuteDetail/detailPage/0c15f68cf89e1339125e9f41d5d31c67?text=59",
      "content": "行政机关依照本法第五十七条的规定给予行政处罚...",
      "fgmc": "中华人民共和国行政处罚法(2021修订)",
      "ft_num": "第五十九条",
      "llm_content": "- 《中华人民共和国行政处罚法(2021修订)》第五十九条##行政机关...",
      "sxx": "现行有效",
      "xljb_1": "法律",
      "xljb_2": "法律",
      "ssrq": "2021-07-15",
      "fbrq": "2021-01-22",
      "fbbm": "全国人大常委会",
      "fwzh": "中华人民共和国主席令第70号"
    }
  ],
  "message": "请求成功",
  "status": "success"
}

失败响应（501）：

{"data": null, "status": "failed", "code": 501, "message": "keyword 参数不可为空！"}

法条详情

POST /open/rh_ft_detail

计费: 10 积分/次

请求参数（Body）

校验规则

• id 与 fgmc+ftnum 同时为空 → 返回 501 "id与法规名称不可同时为空！"

返回结构

成功时返回 data 对象（或列表），包含法条全文及所属法规元信息。结构类似关键词检索的 data[] 单条元素。

案例语义检索

POST /open/case_vector_search

计费: 10 积分/次

请求参数（Body）

wenshu_filter 字段说明（以下均为可选）

案件类别（wenshu_type）

刑事案件、民事案件、行政案件、执行案件、管辖案件、国家赔偿与司法救助案件、强制清算与破产案件、国际司法协助案件、非诉保全审查案件、其他案件

文书种类编码（wszl）

返回结构

{
  "msg": "成功(返回结构化数据)",
  "code": 201,
  "extra": {
    "wenshu": [
      {
        "scid": "案件id",
        "spcx": "审判程序类型",
        "ajlb": "案件类别",
        "jbdw": "审判单位",
        "title": "案件标题",
        "jand": 2019,
        "jaDate": 20191223,
        "wszl": "文书种类",
        "ah": "案号",
        "content": "案件内容",
        "xzqh_p": "省",
        "cj": "法院层级",
        "score": 1.009,
        "anyou": ["案由"]
      }
    ]
  }
}

普通案例关键词检索

POST /open/rh_ptal_search

计费: 10 积分/次

对"普通案例"库进行多条件/关键词检索。

请求参数（Body）—— 以下字段均为可选，但请求体不能为空

注意： xzqh_p 传中文省份名（如"广西"）时，偶发 API 端 ES 解析错误。若遇到 syntax error，可尝试不带省份筛选，改用 jbdw 限定法院。

校验规则

• body 为空 JSON → 返回失败 "请求参数不能为空"
• search_mode 非法 → 返回失败 "search_mode 不合法"
• top_k: ≤0 → 10，>50 → 50

返回结构

通用返回字段

data 对象

lst[] 单条元素字段

权威案例关键词检索

POST /open/rh_qwal_search

计费: 10 积分/次

对"权威案例"库进行多条件/关键词检索。参数同普通案例关键词检索，但无 fxgc 和 yyft 字段。

请求参数（Body）—— 以下字段均为可选，但请求体不能为空

返回结构

与普通案例关键词检索（05）结构相同：status/code/message/data，其中 data 为 {total, lst} 对象，lst[] 字段与 05 一致。

案例详情

GET /open/rh_case_details

计费: 10 积分/次

按类型获取普通案例或权威案例的详情信息。

请求参数（Query）

校验规则

• id 与 ah 同时为空 → 返回失败 "参数异常！"
• type 非 ptal/qwal → 返回失败 "不支持的type类型"

返回结构

成功时 data 为单个对象（非列表），包含案例完整文书内容。主要字段：

法规关键词检索

POST /open/rh_fg_search

计费: 10 积分/次

对法规进行关键词检索与条件过滤。允许不传 keyword，不传则主要按过滤条件返回法规列表。

请求参数（Body）

返回结构

返回 status/code/message/data[]，结构与法条关键词检索（02）类似，data[] 包含法规元信息。

法规详情

POST /open/rh_fg_detail

计费: 10 积分/次

请求参数（Body）

校验规则

• id 与 fgmc 同时为空 → 返回 501 "id和法规名称不可同时为空！"

返回结构

成功时返回 data 对象（或列表），包含法规完整信息及条文列表。

企业名称检索

GET /open/rh_company_info

计费: 10 积分/次

按名称（含全称、曾用名、股票简称等）查询企业。

请求参数（Query）

num 取值规则

• num < 0 或 num > 50 → 置为 10
• 否则使用传入的 num

返回结构

返回 status/code/message/data，data 为 {total, lst} 对象。lst[] 中每条包含企业基本信息，字段可能为英文名或中文名（API 行为不一致，建议代码同时兼容两种）：

企业详情

GET /open/rh_company_detail

计费: 10 积分/次

请求参数（Query）

校验与查询优先级

• id、tyshxydm 两者不能同时为空 → 否则返回失败 "参数异常！"
• 若 id 非空 → 按文档 ID 查询
• 否则若 tyshxydm 非空 → 按统一社会信用代码查询
• 结果条数：每次检索 size = 1

返回结构

返回 data 对象，包含企业完整详情。

法规/法条/案例幻觉检测

POST /open/hall_detect

计费: 50 积分/次

检测文本中引用的法规、法条、案例是否存在幻觉（即是否真实存在、内容是否准确）。

请求参数（Body）

返回结构

{
  "code": 200,
  "msg": "success",
  "data": {
    "regulations": [
      {
        "name": "法规名称",
        "clause": "法条编号",
        "content": "法条内容",
        "extract_reg_id": "法规ID",
        "url": "法规链接",
        "think_tank_content": "智库内容",
        "source_no_specific_clause": false,
        "law_exists": true,
        "semantic_compare": {
          "结论": "一致/不一致/部分一致",
          "语义相似度": 0.95,
          "说明": "说明文字",
          "要点": ["要点1", "要点2"],
          "skipped": false
        }
      }
    ],
    "cases": [
      {
        "name": "案例名称",
        "case_number": "案号",
        "content": "案例内容",
        "url": "案例链接",
        "think_tank_content": "智库内容",
        "case_type": "案件类型",
        "court": "审理法院",
        "judgment_date": "裁判日期",
        "basic_facts": "基本事实",
        "judgment_key_points": "裁判要点"
      }
    ],
    "highlighted_text": "标注后的文本",
    "semantic_compare_error": null,
    "chat_model": "模型名称",
    "request_id": "请求ID"
  }
}

regulations[] 字段

semantic_compare 字段

cases[] 字段

企业检索（轻量候选列表）

GET /open/rh_enterpriseSearch

计费: 1 积分/次

按企业名称模糊检索，返回候选企业列表（仅含 ID、名称、统一社会信用代码），用于定位目标企业后调用其他企业接口。

请求参数（Query）

top_k 取值规则

• 未传 → 默认 10
• < 1 → 置为 1
• \> 50 → 置为 50

返回结构

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": "企业ID",
      "企业名称": "XXX有限公司",
      "统一社会信用代码": "91110000XXXXXXXXXX"
    }
  ]
}

data[] 字段

注意：此接口返回的是中文字段名。

企业基本信息

GET /open/rh_enterpriseBaseInfo

计费: 10 积分/次

根据企业 ID 或统一社会信用代码获取企业完整基本信息，包含股东、核心成员、分支机构等。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回 data 对象，包含以下扁平化信息：

• 基本信息（企业名称、信用代码、类型、状态、法定代表人等）
• 股东信息
• 十大股东
• 十大流通股东
• 核心成员
• 分支机构

返回为嵌套 JSON 对象，各子模块字段名称以中文为主。

企业聚合总览

POST /open/rh_enterpriseAggregationSummary

计费: 10 积分/次

获取企业各维度数据汇总，一次调用返回多项统计摘要。

请求参数（Body）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回 data 对象，包含企业各维度信息的聚合统计摘要（涉诉数量、投资数量、商标数量等）。

企业对外投资信息列表

GET /open/rh_enterpriseOutInvest

计费: 5 积分/次

查询企业对外投资信息，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含企业对外投资记录（被投资企业名称、投资比例、投资金额等）。

企业商标信息列表

GET /open/rh_enterpriseBrand

计费: 5 积分/次

查询企业商标注册信息，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含企业商标信息（商标名称、注册号、分类、状态等）。

企业专利信息列表

GET /open/rh_enterprisePatent

计费: 5 积分/次

查询企业专利信息，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含企业专利信息（专利名称、专利号、类型、申请日期等）。

企业软件著作权信息列表

GET /open/rh_enterpriseSoftRight

计费: 5 积分/次

查询企业软件著作权登记信息，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含企业软件著作权信息（软件名称、登记号、版本号、登记日期等）。

企业作品著作权信息列表

GET /open/rh_enterpriseWorksRight

计费: 5 积分/次

查询企业作品著作权登记信息，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含企业作品著作权信息（作品名称、登记号、类型、登记日期等）。

企业网站备案信息列表

GET /open/rh_enterpriseIcp

计费: 5 积分/次

查询企业 ICP 网站备案信息，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含企业网站备案信息（域名、备案号、网站名称等）。

企业变更记录信息列表

GET /open/rh_enterpriseChangeInfo

计费: 5 积分/次

查询企业工商变更记录，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含企业变更记录（变更项目、变更前内容、变更后内容、变更日期等）。

企业涉诉信息统计

GET /open/rh_enterpriseWritAgg

计费: 10 积分/次

查询企业涉诉信息的聚合统计数据，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含企业涉诉信息统计（案件类型分布、角色分布、法院分布等聚合数据）。

企业涉诉文书列表

GET /open/rh_enterpriseWritList

计费: 10 积分/次

查询企业涉诉裁判文书列表，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含企业涉诉文书（案号、案件名称、法院、裁判日期、案件类型等）。

企业开庭公告列表

GET /open/rh_enterpriseCourtSessionNotice

计费: 5 积分/次

查询企业作为当事人参与的开庭公告，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含开庭公告（案号、开庭日期、法院、案由、当事人等）。

企业法院公告列表

GET /open/rh_enterpriseCourtNotice

计费: 5 积分/次

查询企业相关的法院公告信息，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含法院公告（公告类型、公告内容、发布法院、发布日期等）。

企业失信被执行人列表

GET /open/rh_enterpriseExecutions

计费: 5 积分/次

查询企业作为失信被执行人的记录，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含失信被执行人记录（被执行人名称、案号、执行法院、立案日期、失信情形等）。

企业被执行人列表

GET /open/rh_enterpriseExecutedPerson

计费: 5 积分/次

查询企业作为被执行人的记录，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含被执行人记录（被执行人名称、案号、执行标的、执行法院、立案日期等）。

企业股权冻结列表

GET /open/rh_enterpriseFrozenEquity

计费: 5 积分/次

查询企业股权冻结记录，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含股权冻结记录（被执行人、冻结股权数额、执行法院、冻结期限等）。

企业行政处罚列表

GET /open/rh_enterprisePunishment

计费: 5 积分/次

查询企业行政处罚记录，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含行政处罚记录（处罚决定书文号、处罚机关、处罚内容、处罚日期等）。

企业股权出质列表

GET /open/rh_enterprisePledge

计费: 5 积分/次

查询企业股权出质登记信息，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含股权出质记录（出质人、质权人、出质股权数额、登记日期、状态等）。

企业对外担保列表

GET /open/rh_enterpriseGuaranty

计费: 5 积分/次

查询企业对外担保信息，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含对外担保记录（担保人、被担保人、担保金额、担保类型、担保期限等）。

企业经营异常记录列表

GET /open/rh_enterpriseAbnormalOperation

计费: 5 积分/次

查询企业经营异常名录记录，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含经营异常记录（列入原因、列入日期、决定机关、移出原因、移出日期等）。

企业欠税公告记录列表

GET /open/rh_enterpriseCorporateTax

计费: 5 积分/次

查询企业欠税公告记录，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含欠税公告记录（欠税税种、欠税余额、发布单位、发布日期等）。

企业严重违法记录列表

GET /open/rh_enterpriseSeriousIllegal

计费: 5 积分/次

查询企业严重违法失信记录，支持分页。

请求参数（Query）

校验规则

• id 和 uscc 至少提供一个
• 若同时提供，以 id 为准

返回结构

返回分页列表，包含严重违法记录（违法行为、处罚决定、决定机关、决定日期等）。

元典法条与案例检索 (yuandian-law-search)

通过 元典开放平台 检索中国法律法规条文和案例，为法律分析和研究提供数据支撑。

v1.6.1 起，本 Skill 的核心交付能力从单次 API 包装扩展为"检索归档 + 法律检索报告生成"：多次检索后可用 consolidate 汇总为 7 节结论先行报告，适合律师内部复核、客户沟通和类案检索留痕。v1.7.4 修复关键词扩展的自动 OR 行为，并强化案件综合检索的语义优先策略。

快速开始

1. 获取 API Key

访问 open.chineselaw.com，用手机号注册后在个人中心创建 API Key。每次调用消耗 10 积分，需在平台充值。

2. 配置密钥

将 API Key 填入 scripts/.env：

YD_API_KEY=sk-你的密钥

3. 执行检索

scripts/yd-run search "正当防卫的限度" --sxx 现行有效

scripts/yd-run 会用干净环境启动 Python，避免 Codex 进程环境、代理变量或 PATH 漂移影响元典接口访问。网络排查可先运行：

scripts/yd-run --network-check

4. 生成法律检索报告

多次检索后，用 consolidate 生成主交付物。报告结构为：案情简介、检索目的与问题、检索结论、分析与判断、检索思路与方法、检索结果、检索明细。

scripts/yd-run consolidate \
  --title "张某买卖合同违约金调整" \
  --project "case-2024-zhangsan" \
  --case "案情：..." \
  --strategy "检索思路：..." \
  --analysis "分析与判断：..." \
  --conclusion "一句话结论：..." \
  --risks "主要风险：..." \
  --next-actions "后续行动：..." \
  --include "违约金,逾期付款"

设计理念：为什么这样设计这个 Skill

背景

元典开放平台提供 11 个 API 端点，覆盖法条、案例、法规、企业四个领域。每次 API 调用消耗 10 积分，这意味着一个"检索 5 个案例并逐一查看详情"的简单场景，实际消耗为 10 + 5×10 = 60 积分。

因此，整个 Skill 的设计围绕一个核心问题：如何在保证正确性的前提下，用最少的 API 调用完成任务？

原则一：正确性优先于积分节约

AI 的记忆可能存在幻觉或过时。涉及法律条文的精确引用时，宁可多查一次，不可引用错误法条。

必须调用 API 的情况：

• 需要引用具体法条文号（AI 可能记错条文内容或条号对应）
• 需要确认时效性（法律修订频繁，AI 训练数据可能已过时）
• 用户明确要求检索
• AI 对自身记忆不确定

可以不调用的情况：

• 纯概念解释（如"什么是善意取得"）
• 对话中已检索过相同内容
• 用户未要求查找

原则二：三级接口分层

不是所有接口都应该被同等对待。我们将 11 个端点分为三层：

这样设计是因为：法条语义检索（search）返回结果已包含法条全文，通常一次调用即可满足需求，无需再调 detail；而案例详情（case-detail）是额外消耗，必须让用户知情。

原则三：语义检索优先

每个领域提供语义和关键词两种检索模式，默认优先使用语义检索：

语义检索覆盖面更广，一次调用往往足够。只有当用户提供了明确关键词或需要日期/法院/级别等筛选条件时，才切换到关键词检索。

原则四：本地缓存零成本

脚本内置归档缓存机制：每次 API 调用的查询和响应会自动存入 archive/ 目录，以 SHA-256 指纹匹配。相同查询自动命中缓存，不消耗积分。

这意味着在同一个对话中多次讨论同一个法律问题时，只有第一次会产生积分消耗。

六条积分节省策略

这些策略写入了 SKILL.md，指导 AI 代理在调用时做出正确判断：

1. 一查多用 — 一次检索结果充分引用，避免重复检索同一问题 2. 优先语义检索 — search 返回最全面的结果，一次通常够用 3. 避免法条链式调用 — 不要先 search 再逐条 detail，语义检索已含全文 4. 案例详情谨慎调用 — 先用摘要筛选 1-2 个最相关案例，再调 case-detail 5. 善用筛选参数 — --sxx 现行有效、--effect1 法律 等缩小范围，避免无效结果 6. 信任归档缓存 — 相同查询自动命中本地归档，零积分消耗

接口概览

每个端点的完整参数说明和响应结构见 endpoints/01~35-*.md。

版本演进

v1.0.0 是最重要的里程碑：API 从旧平台 aiapi.ailaw.cn:8319 整体迁移至开放平台 open.chineselaw.com，认证方式从 URL 参数改为 X-API-Key 请求头，同时新增了法规、案例详情、企业三大领域的端点。

自更新机制

Skill 内置了从 GitHub monorepo 自动检测和下载更新的能力，无需手动替换文件。

工作方式

1. 自动检测：每次执行检索命令时，脚本会检查距上次版本检测是否超过 7 天。若超过，从 GitHub 读取远程 SKILL.md 的版本号，与本地对比 2. 版本比对：基于语义版本号（semver）比较，远程版本更高时打印更新提示 3. 手动检查：可随时执行 scripts/yd-run check-update，显示当前版本、远程版本和最近提交记录 4. 执行更新：scripts/yd-run do-update 从 GitHub 下载 scripts/MANIFEST.json 中列出的所有文件

安全边界

do-update 的设计遵循一个原则：只更新 skill 自身的代码和文档，绝不触碰用户数据。

具体来说：

• 更新范围由 scripts/MANIFEST.json 控制，仅包含 SKILL.md、CHANGELOG.md、脚本、endpoints/、references/、templates/ 文档
• 不会覆盖 .env（用户的 API Key）和 archive/（归档缓存数据）
• 不依赖 GitHub API Token，仅使用公开的 raw.githubusercontent.com 和 Atom feed

检测状态记录

版本检测结果保存在 archive/version_check.json，记录上次检测时间、本地/远程版本号和状态。脚本据此判断是否需要重新检测。

许可证

MIT License — 详见 LICENSE.txt。

作者

杨卫薪律师（微信 ywxlaw）

关键词扩展与分阶段检索

关键词检索默认是精确匹配，用户搜索"刑事案件管辖权"不会自动命中"知识产权管辖权"等相关概念。本节说明 AI 应如何主动扩展检索范围、分阶段提炼精准结果。

关键词扩展原则

AI 在执行关键词检索前，应先分析用户查询是否涉及可扩展的法律概念：

1. 上位概念扩展：将具体概念扩展到上位概念。例如"商标侵权"→ 同时检索"知识产权侵权" 2. 并列概念扩展：关联同一层级的平行概念。例如"管辖权异议"→ 同时考虑"管辖权转移""指定管辖" 3. 程序-实体关联：从实体法关键词关联到程序法关键词。例如"正当防卫"→ 也关注"防卫过当""紧急避险"

扩展关键词工作流

当 AI 判断用户查询涉及可扩展概念时，按以下流程操作：

1. 识别核心关键词：从用户查询中提取核心法律概念 2. 生成扩展词列表：基于上述原则，列出 2-5 个相关关键词 3. 分阶段检索：

• 第一阶段（广撒网）：用核心关键词执行一次检索（使用 --search-mode or 扩大命中范围）
• 第二阶段（精提炼）：根据第一阶段结果，提炼更精准的关键词组合再检索一次

4. 结果合并与去重：将两次检索结果合并，按相关性排序展示 5. 扩展方向提示：检索完成后，向用户建议可能相关的扩展检索方向

脚本参数支持

关键词检索、案例检索和法规检索新增 --expand 参数，用于一次性传入多个扩展关键词：

# 法条关键词扩展检索
scripts/yd-run keyword "刑事案件 管辖权" --expand "知识产权管辖,级别管辖,专门管辖" --search-mode or

# 案例关键词扩展检索
scripts/yd-run case "买卖合同 瑕疵担保" --expand "质量纠纷,违约责任" --search-mode or

# 法规关键词扩展检索
scripts/yd-run regulation "民法典 合同" --expand "买卖合同,租赁合同" --search-mode or

--expand 参数的行为：

• 将扩展关键词追加到原始查询中；未显式传入 --search-mode 时，自动使用 or 模式检索
• 如果显式传入 --search-mode and，尊重用户指定，仍按 AND 模式检索
• 等效于将原始关键词与扩展关键词用空格连接后以 OR 模式检索
• 不带 --expand 时保持原有的精确匹配行为（默认 and）

分阶段检索示例

用户问："关于刑事案件管辖权有哪些规定？"

第一阶段（广撒网）：

scripts/yd-run keyword "刑事案件 管辖权 级别管辖 地域管辖 专门管辖" --search-mode or --sxx 现行有效

分析第一阶段结果：发现大量结果涉及"级别管辖"和"地域管辖"两个核心分支

第二阶段（精提炼）：

scripts/yd-run keyword "级别管辖 中级法院" --search-mode and --sxx 现行有效
scripts/yd-run keyword "地域管辖 犯罪地" --search-mode and --sxx 现行有效

扩展方向提示

检索完成后，AI 应根据检索结果向用户建议相关的扩展方向。提示格式：

本次检索完成了对"刑事案件管辖权"的查询，消耗 XX 积分。

💡 相关的扩展检索方向：
1. 级别管辖 —— 中级/高级/最高法院的管辖分工
2. 地域管辖 —— 犯罪地、被告人居住地的管辖规则
3. 专门管辖 —— 军事法院、知识产权法院等专门管辖
如需深入了解某个方向，请告诉我。

策略兼容性

关键词扩展行为与三种检索策略的关系：

典型工作流与用户引导

AI 在完成检索后，应主动告知用户检索结果摘要和积分消耗，并根据场景推荐后续操作。

法条研究场景

用户问："关于股东出资瑕疵的法律规定有哪些？"

1. 先调 search 语义检索（10 积分），覆盖全部相关法条 2. 展示摘要 + 关键条文引用 + 总积分 3. 主动建议扩展方向（如"公司法""破产法"）

案例研究场景

用户问："最近几年类似案件怎么判的？"

1. 调 case-semantic 语义检索（10 积分），覆盖近 5 年案例 2. 展示相关度排序的案例摘要 3. 不主动调 case-detail，由用户选择感兴趣的案例后调详情 4. 主动告知"如需查看完整判决书请告知，每个案例 10 积分"

案件综合分析场景

用户问："这个案件我们能不能主张 XX？"

1. 多轮检索：先 search 法条、再 case-semantic 案例、可能补 regulation 法规 2. 汇总法条 + 案例 + 法规 + AI 分析判断 3. 给出可执行的法律意见 4. 总积分可能 30-50，在最终回复开头明示

案例检索执行约束：

• 第一轮案例检索优先用 case-semantic 承接案情事实结构，不要把长事实描述直接丢给 case 关键词 AND 检索。
• 只有在需要锁定若干高信息密度词时才补 case；关键词控制在 4-6 个，优先选择平台/行业行为词、交易链条词和责任焦点词。
• case 默认是 AND 精确匹配；如果使用 --expand 扩展同义词、上位词或并列场景，未显式指定时脚本会自动切到 OR。
• 一轮关键词检索零命中时，不要据此判断"没有类案"；应立即改用 case-semantic 或缩短关键词后 OR 复检。

争议焦点识别优先场景（v1.6.1+ 强制前置步骤）

问题：很多 AI 跳过"识别用户原话里的争议焦点"这一步，直接根据用户问题的"法律概念包装"展开检索（"短视频带货""电商平台""间接侵权"），结果命中大量"被告自己动手"的案型，与用户实际争议焦点偏差很大。

强制前置：争议焦点识别表

收到"这个案件我们能不能主张 XX"或类似案件综合分析请求时，第一轮检索前先在对话/笔记中明确以下 5 个字段，再据此生成检索词：

红线（重要）：

用户的争议焦点 ≠ 用户问题的法律概念包装

用户的争议焦点 = 用户原话里已经明确给出的几个核心论点

例：

• 用户原话："视频是达人发的，不是被告发的，但挂在被告商品链接上。被告商品页能看到达人视频 → 被告有筛选过程。被告因此获利 → 反不正当竞争法兜底。"
• 用户已明确的论点 = [1] 视频非被告发布但挂被告商品链接；[2] 被告对视频有筛选过程；[3] 被告因此获利；[4] 反不正当竞争法兜底
• v1 错搜：用"短视频带货 电商平台 间接侵权"（用户问题的法律概念包装）→ 偏差
• v1 正搜：用"视频不是商家发布 商家对达人视频有筛选过程 商家因视频获利 反不正当竞争法兜底"（用户原话级别）→ 命中对位案

反例（曾发生过的偏差）：

用户问："达人发的短视频侵权了，挂到商家商品链接上，商家要负责吗？"

>

v1 错误：直接搜"短视频带货 电商平台 间接侵权" → 命中"商家自己搬运/制作"案例 → 全部跑偏

>

v1 正确（如果当时识别到位）：用户已经明确 4 个信息——

① 视频由达人发布（非被告）② 视频→挂车→被告商品 ③ 被告对视频有筛选过程 ④ 被告因此获利+反不正当竞争法兜底

直接把这 4 个用户原话作为检索词，第一轮就能命中对位案。

>

不需要等"检索后再提炼二分法"——用户原话已经够具体了。

关键提示：

• 行业术语 > 法律术语：用户说"挂车"就用"挂车"，不要说"信息网络传播"
• 用户原话级别 > 法律概念包装：用户原话里给的论点直接作为检索词
• 抗辩点对称搜索：被告可能怎么抗辩 → 搜"法院如何否定该抗辩" 的判例
• 二分法是结果不是起点：如果检索后才识别出二分法（如"营销合作 vs 精选联盟"），说明第一轮关键词就有问题——应该在第一轮就用更精确的词
• 长事实结构走语义，短关键词走精确：自然语言事实结构用 case-semantic；case 只放少量关键字，避免 6 个以上词的 AND 零命中。

标杆案例对标检索场景（v1.6.1+ 强制流程）

问题：用户第一轮就提供了标杆案例（如星云VR案、微信文章），但 v1 没把它作为"对标模板"去搜同类，导致错失场景最对位的案例。

强制流程：

1. 提取标杆案例的"事实结构骨架"（5-7 个关键事实）

• 例：星云VR案 = {店主联系达人 + 多个探店账号发布 + 视频含侵权片段 + 视频挂团购链接 + 商家根据链接成交向达人结算佣金 + 商家未审核 + 法院判决商家赔偿}

2. 把"事实结构骨架"作为查询模板生成检索词

• 关键词版：探店达人 + 团购链接 + 商家 + 营销合作 + 审查义务
• 语义版（更优）：用一段自然语言描述这个事实结构

3. 首选 case-semantic（关键词检索对"达人""挂车"识别差）

• 关键词检索易命中"被告自己动手"的偏差案例
• 语义检索对场景描述识别更好
• 如果补关键词检索，先用 4-6 个高密度词，例如 短视频 推广 团购 商家 责任 著作权
• 避免第一轮使用 探店达人 团购链接 商家 著作权 责任、推广视频 挂车 商家 责任 审查 注意义务 等长 AND 组合；这类组合容易因字面差异零命中

4. 每轮命中后回检"对标度"：命中案例的"事实结构"是否覆盖标杆案例的 5-7 个关键事实

• 覆盖 ≥ 5/7 → 高度对位，纳入"主要类案"
• 覆盖 3-4/7 → 一般类案，辅助参考
• 覆盖 ≤ 2/7 → 偏差案例，谨慎援引（可能论证方向不同）

反例（曾发生过的偏差）：

用户第一轮给了星云VR案（江苏高院公众号文章），明确场景是"达人探店+挂团购+商家担责"

>

v1：忽略标杆案例，直接搜"短视频带货 电商平台 间接侵权" → 命中偏差案例

>

v2 正确：把星云VR案的事实结构作为查询模板 → 命中 (2023)京0491民初5073 号等高度对位案

法规全景场景

用户问："数据安全相关的所有规定"

1. regulation 关键词检索（10 积分）+ 必要的 regulation-detail 2. 展示法规清单 + 效力级别 + 关联法条 3. 主动建议进一步细化方向

企业风险排查场景

用户问："这家公司有没有什么风险？"

1. enterprise-summary 快速总览（10 积分），识别风险分布 2. 针对高风险项用 enterprise-list 深挖（如涉诉文书、失信被执行人、行政处罚） 3. 汇总风险画像

AI 向用户反馈的原则

1. 每次检索后主动说明积分消耗："本次检索消耗 10 积分" 2. 多步检索时告知累计消耗："本次检索消耗 10 积分（本次对话累计 30 积分）" 3. 完整判决书的触发取决于策略：balanced/economical 由用户主动触发；aggressive 由 AI 自动获取最相关的 2-3 个 4. 案例语义检索的摘要通常已够用：只有用户明确要求查看完整判决书时才深入（aggressive 除外） 5. 法条语义检索已含全文：不需要额外补充 6. 用自然语言与用户沟通：不要向用户暴露命令行语法，AI 后台执行脚本即可 7. 补充检索取决于策略：balanced/economical 一次只用一种检索模式；aggressive 对重要问题自动同时运行语义+关键词检索，合并去重 8. 检索报告 .md 自动落盘：每次实际检索（cache miss 时）会同时落盘两份结构化 Markdown 报告：

• archive/<ts>_<query>.md：与 archive JSON 配对，技能内部归档，便于复盘
• <CWD>/<ts>_<query>.md：用户当前工作目录（AI 进程 CWD）副本，仅供 AI 后台处理用，不应被复制到目标目录
• 报告内容包含元信息（时间/接口/关键词/积分/原始数据路径/工作目录副本）+ 检索结果 + 引用来源
• footer 会输出报告路径，AI 应在对话中告知用户
• 默认双副本写入；可用 --no-report 完全跳过、--no-cwd-report 仅跳过工作目录副本
• 重要：per-call 工作副本不是最终交付物，禁止 AI 把它们复制到用户的案件文件夹等目标目录（详见 03-report-consolidation.md）

法律检索报告（consolidate）

多次检索之后，把 per-call 报告汇总成一份完整的法律检索报告。这是律师/客户看的交付物，per-call 报告是数据底稿。

7 节"结论先行"标准结构

报告骨架（7 节结构、设计动机、反例、节号逻辑）见：

`04-report-design-notes.md`

调用 consolidate 时使用该骨架作为输出格式约定。

调用方式

scripts/yd-run consolidate \
    --title "张某买卖合同违约金调整" \
    --project "case-2024-zhangsan" \
    --case "案情：..." \
    --strategy "检索思路：..." \
    --analysis "分析与判断：..." \
    --conclusion "一句话结论：..." \
    --risks "主要风险：..." \
    --next-actions "后续行动：..." \
    --include "违约金,高空抛物"

• --case / --strategy / --analysis 必填：AI 显式传本次任务的案情/思路/判断
• --include 必填：逗号分隔的查询子串，明确指定"本次任务范围"（不取最近 N 条）
• 匹配规则：CWD 中所有符合 <8位时间戳>_<6位时间戳>_<查询>.md 命名的 .md 文件，文件名包含任一子串即被纳入
• --project 可选：项目子目录名。默认从 --title slugify（如 "张某买卖合同违约金调整" → "张某买卖合同违约金调整"）。用于 archive/<project>/ 归类
• --title / --purpose / --conclusion / --risks / --next-actions / --output 可选
• --purpose 不传则基于检索词自动生成
• --conclusion 强烈建议传入；不传会在 3.1 保留补写提示
• --risks / --next-actions 不传会保留补写提示
• --output 默认同时写 CWD 和 archive/<project>/；指定则只写到指定路径

项目子目录组织

consolidate 会把这次任务的所有文件归类到 archive/<project>/ 子目录：

archive/
  case-2024-zhangsan/
    20260610_192031_货款逾期违约金_司法实践.json   ← 从 archive/ 根目录移入
    20260610_192031_货款逾期违约金_司法实践.md    ← 从 CWD 复制
    20260610_192032_逾期付款_违约金_调整.json
    20260610_192032_逾期付款_违约金_调整.md
    20260610_192058_法律检索报告.md                ← 主交付物

• .md 复制（CWD 保留工作副本）：用户的工作目录不被破坏
• .json 移动（archive 根目录已清理）：避免根目录重复积累，扁平区只放"in-flight 暂存"
• 重复运行 consolidate 同一项目：idempotent，文件已在子目录则跳过

与 per-call 报告的关系

多次 yd-run 检索（自动写 per-call .md 到 archive + CWD）
       ↓
AI 汇总判断后调 consolidate --project "case-x"
       ↓
创建 archive/case-x/，.md 复制进来，.json 移进来，法律检索报告写进去
       ↓
CWD 也有法律检索报告副本，per-call .md 仍在 CWD（工作副本）
       ↓
报告末尾的"检索明细表"链接回 archive/case-x/ 里的副本

per-call .md 是数据底稿，可独立查看；session 报告是主交付物，附案情/思路/判断；项目子目录是组织容器。

目标目录归档规范（强制）

用户的目标目录（通常是案件文件夹 `02 - 案件分析` / `03 - 法律研究` 等）≠ AI 进程的 CWD。AI 进程运行 scripts/yd-run 时所在的 CWD 是临时工作区，不是用户的案件文件夹。

目标目录只放什么

目标目录（用户指定的文件夹）只允许出现以下文件：

1. 整合后的法律检索报告（法律检索报告.md，7 节标准结构）—— 唯一必需 2. 外部素材：用户单独提供的微信文章、PDF、链接笔记等 3. 基于整合报告再生成的下游文件：证据清单、代理词大纲、抗辩应对清单、应诉策略等

目标目录不允许出现

• ❌ per-call 检索记录（<ts>_<query>.md × N 份）
• ❌ 检索明细 JSON
• ❌ 任何中间过程的临时文件
• ❌ AI 进程 CWD 下的 per-call 工作副本

标准工作流

Step 1：AI 在自己的 CWD 多次 yd-run 检索
        → archive/<ts>_<query>.json + .md（skill 内部）
        → <CWD>/<ts>_<query>.md（AI 进程工作副本，仅供 AI 读）

Step 2：AI 汇总判断后，**手动**写一份整合报告到目标目录
        → <用户目标目录>/<日期>_<主题>-法律检索报告.md

Step 3：清理 AI 进程 CWD 下的 per-call 工作副本
        → 不复制到目标目录
        → 仍可在 archive/<ts>_<query>.md 留底

Step 4：用户后续若要"基于检索结果生成证据清单/代理词"
        → 读取整合报告（含检索明细表），生成新文件
        → 新文件**也只放目标目录**，不污染 archive

反例（曾发生过的错误）

# ❌ 错误：把 8 份 per-call 工作副本复制到目标目录
cp /Users/.../yuandian-law-search/20260615_163256_*.md \
   "/案件文件夹/03 - 法律研究/"
# → 用户被迫手工清理，因为目标目录被检索底稿污染

正确做法：

# ✅ 正确：只把整合报告写到目标目录
# 整合报告由 AI 在对话中直接 Write 到目标目录
# per-call 工作副本留在 skill 内部 archive/

验证清单

AI 完成法律检索任务后，自查：

• [ ] 目标目录里只有整合报告 + 外部素材 + 下游生成文件
• [ ] 目标目录里没有 per-call <ts>_<query>.md × N
• [ ] per-call 报告可在 archive/ 里查到（不丢数据）
• [ ] 整合报告末尾的"检索明细表"指向 archive/ 路径（而非 CWD 路径）

法律检索报告 · 7 节设计原理（"结论先行"规约）

本文件是 consolidate 报告生成的格式约定 + 设计原理，供 AI 在手动整合时遵循。

注意：templates/legal-research-report.md 是可维护的模板参考；yd_search.py 当前用代码内 f-string 渲染。

本文件描述的是结构与设计动机，与运行时具体格式解耦。

设计原则

• 用户最想知道最终结论 → 结论提前到第 3 节
• 法条和案例只是核实材料 → 放到第 6 节
• 节号从 1 重新编号（案情=1，结论=3，结果=6，明细=7），

体现"结论在第 3 节"的视觉位置

反例（曾出现过的旧版结构，避免回退）

• 案情 → 目的 → 思路 → 检索结果 → 分析 → 结论
• 用户反馈：检索结果（法条案例）全是"核实材料"，要翻到最后才看到结论 → 太累
• 新版：结论放到第 3 节，用户看完 3.1-3.4 就能得到 80% 答案

7 节标准骨架

1. 案情简介

当事人 / 争议焦点 / 当前阶段（最少必要）

2. 检索目的与问题

本次检索要回答的法律问题（1-3 个核心 Q）

3. 检索结论 ⭐

用户最先读到的内容：

• 3.1 一句话定性（"能做/不能做" + 法律依据）
• 3.2 核心论点的判例支撑速查（表格，30 秒内 get）
• 3.3 风险点（诚实告知，不要只说好的）
• 3.4 后续行动（具体可执行的步骤）

4. 分析与判断

抗辩应对 / 法条适用 / 诉讼请求结构 / 赔偿酌定 / 证据准备

5. 检索思路与方法

关键词组合 / 筛选条件 / 检索顺序（备查）

6. 检索结果（按 endpoint 分组）

• 6.1 法律依据
• 6.2 司法案例
• 6.3 行政法规
• 6.4 其他（核实材料）

7. 检索明细

表格，链接到每条 per-call 报告（末尾）

质量要求

• 结论区必须能独立阅读：3.1-3.4 应先回答问题，再引导读者看底稿
• 核心依据用表格速查：避免把法条和案例堆给读者自行归纳
• 方法区保留检索痕迹：写清关键词、筛选条件、平台、时间、纳入规则
• 结果区只放支撑材料：法条、案例、法规按类型分组，不替代第四节分析
• 风险必须明示：包括不利类案、法律适用分歧、地域差异、时效或证据缺口

MCP 协同工作流（v1.6.0+）

元典已发布官方 MCP（https://open.chineselaw.com/mcp-config），3 个 servers：yuandian-law（法律法规）、yuandian-case（案例文书）、yuandian-company（企业信息）。本 skill 的价值现在转向"归档 + 法律检索报告生成"——数据接入由 MCP 负责，本 skill 负责沉淀。

接入元典 MCP

模板在 scripts/.mcp.json.example（与 scripts/.env.example 同目录）。把它复制为客户端能识别位置的 .mcp.json：

{
  "mcpServers": {
    "yuandian-law":    { "url": "https://open.chineselaw.com/mcp/law/stream",    "headers": {"Authorization": "Bearer ${YD_API_KEY}"} },
    "yuandian-case":   { "url": "https://open.chineselaw.com/mcp/case/stream",   "headers": {"Authorization": "Bearer ${YD_API_KEY}"} },
    "yuandian-company":{ "url": "https://open.chineselaw.com/mcp/company/stream","headers": {"Authorization": "Bearer ${YD_API_KEY}"} }
  }
}

设置环境变量后重启客户端，agent 即可自动获得 mcp__yuandian_law__*、mcp__yuandian_case__*、mcp__yuandian_company__* 工具。

AI Agent 三步工作流

Step 1: 调 MCP 拿数据（agent 直接调，不经 yd-run）
  mcp__yuandian_law__yuandian_law_vector_search("违约金", sxx="现行有效")
  → 拿到 API 响应 JSON

Step 2: 喂给 yd-run ingest 归档 + 生成 .md
  echo "<上一步的 JSON>" | yd-run ingest \
      --query "违约金 调整" \
      --endpoint "/open/law_vector_search"
  → archive/<ts>_违约金_调整.json + .md（同直接 API 模式）
  → CWD/<ts>_违约金_调整.md 工作副本

Step 3: 多次 ingest 后，调 yd-run consolidate 生成法律检索报告
  yd-run consolidate --project "case-2024-xxx" \
      --case "..." --strategy "..." --analysis "..." \
      --conclusion "一句话结论：..." \
      --risks "主要风险：..." \
      --next-actions "后续行动：..." \
      --include "违约金"
  → archive/case-2024-xxx/ 项目包 + 7 节结论先行报告（详见 templates/legal-research-report.md）

ingest 子命令详细

# 方式 1: 文件输入
yd-run ingest --query "<Q>" --endpoint "/open/<E>" --input <file.json>

# 方式 2: stdin pipe（agent 友好）
cat result.json | yd-run ingest --query "<Q>" --endpoint "/open/<E>"

# 必填
#   --query:     用于生成文件名 + 元信息
#   --endpoint:  对应 API 路径，用于 routing 到 formatter（见 INGEST_ROUTING）
# 可选
#   --cost:        成本标签（默认 "10 积分"）
#   --no-report:   跳过 .md 报告生成
#   --no-cwd-report: 跳过 CWD 副本

--endpoint 取值见 INGEST_ROUTING 路由表（36 个 endpoint 全部覆盖，包括元典 MCP 暴露的全部 24 个数据 tools）。

何时用哪种模式

两种模式产出完全一致（archive/ 格式、.md 元信息、consolidate 路由），可混用。