/yuandian-law-search

变更日志

[1.10.0] - 2026-09-22

改进

• 默认改为 MCP 优先的薄中间层：普通单争点含案件事实也直接检索，不再强制完整涵摄矩阵、计划／精选 JSON、MCP ingest 或正反双查询。复杂研究合同按需加载，报告时才文件化精选来源。
• 停用 aggressive/balanced/economical 的自动编排及隐式检索参数；CLI 语义请求仅发送显式设置的 rewrite_flag/return_num，关键词不再自动增加 top_k。保留用户已有配置，不修改密钥。
• 新增 schema 1.1 focused 报告记录；保留 schema 1.0 深度研究兼容。普通报告四节、轨迹折叠，避免重复矩阵与门禁表；低相关、未核验、错误映射和原始召回仍不能进入正式报告。
• 将“主题相关”与“规范／事实适用”区分，补充四类真实 API 检索观察；案例语义整理文本不再等同原判逐字全文。删除无证据的平台领域覆盖断言。

修复

• 修复多层归档根目录不存在时写入失败；yd-run 转发 YD_ARCHIVE_DIR，consolidate 遵循自定义归档根。
• 将报告“原始检索调用数”改为“附带底稿数”，避免缺少 Markdown 时误报零调用。
• 校正本地两个语义接口文档的 rewrite_flag 默认值（官方当前为 false）；显式改写开关互斥，候选数接受正整数。

验证边界

• 四类去身份化法律问题完成8次真实 API 调用，按标价估算80积分，未核平台账单；未传客户案卷。用真实详情及官方文本复核生成两条精选依据报告；4组离线回归通过。
• 本轮未进行真实 MCP 端到端、无旧上下文 Agent 多轮 A/B 或 token 测量，不宣称整体耗时／token 已实证下降。历史法源作核心依据的脚本限制、CLI 大候选输出仍留待后续处理。

[1.9.2] - 2026-09-19

修复

• 缓存命中不再误报积分消耗：_print_footer 新增 cached 参数，命中本地归档缓存时统一显示"命中本地归档缓存，本次调用消耗 0 积分"，覆盖调用方传入的固定成本标签（50/10/1 积分）。此前缓存命中仍打印"本次调用消耗 10 积分"，导致按终端输出估算成本时系统性高估。

文档

• references/03-report-consolidation.md 增补"--include 与第七节调用轨迹的两个坑"：--no-report 与缓存命中都不会产生 per-call .md，并给出从归档 .json 重建轨迹报告的可行做法。

[1.9.1] - 2026-09-18

修复（issue #158：--no-report 语义与归档耦合）

• 归档失败不再吞掉已取得的响应：api_post / api_get 改经 _archive_save_guarded 写归档，目录不可写等 OSError 只降级为 stderr 告警（附 --archive-dir / --no-archive 修复出口提示）并返回 None，不再以异常中断交付；告警明确"本次响应已保留、不会自动重试"，杜绝调用方误判失败重试造成重复扣积分。
• SKILL.md 语义修正：--no-report 实际仅跳过 .md 报告（archive 与 CWD 两份），此前文档宣称"完全跳过"失实；同步修正命令帮助文本。

新增

• --no-archive：关闭全部本地留存（archive JSON 与 .md 都不写）；查重仍读取已有归档（命中即免请求），帮助文本明示"新查询不再入缓存、下次同查询可能重复消耗积分"的取舍。
• --archive-dir / 环境变量 YD_ARCHIVE_DIR：自定义归档目录，优先级 CLI > 环境变量 > 默认 <skill>/archive；须在首个检索命令前生效（_apply_archive_settings 于 main 统一应用）。

技术优化

• 新增 scripts/verify-archive-failure-contracts.py 无网络故障注入回归（4 项契约）：归档 PermissionError 不吞 POST/GET 响应且零重试、--no-archive 零写入且查重可命中已有归档、目录解析三级优先级、SKILL.md 无失实表述；存量 verify-runtime-contracts.py / verify-research-delivery-contracts.py 全部保持 PASS。

[1.9.0] - 2026-08-30

新增

• 新增涵摄式 research-plan.json 合同，将案件拆为争点、候选大前提、法律要件／例外／后果、法律化事实、证明状态、暂定涵摄和 research_gap；只有法律检索缺口可派生正反命题与查询。
• 新增 Agent 生成的 selected-sources.json 精选交付合同，强制命题／查询映射、HIGH/MEDIUM 对位度、来源核验、时效说明、适用理由和可追溯引用。
• 新增 validate-research-contract.py 统一门禁和 verify-research-delivery-contracts.py 无网络故障注入回归，覆盖空清单、LOW、未核验、未知命题、重复来源、事实缺口误检索和原始召回泄漏。

改进

• 将主流程固化为“涵摄为骨架、假设验证为检索方法、正反对抗为质量控制”；明确 MCP 仅是调用协议，向量用于候选发现，关键词、结构化字段和详情接口用于复检与核验。
• 区分对话研究答复、精选研究包和正式报告；默认交付结论与少量精选依据，只在用户明确要求时生成落盘报告。
• 语义候选默认数量收紧为 economical 8／balanced 12／aggressive 20；正式报告与候选规模解耦，最多纳入 12 条精选来源，core 依据必须为 HIGH。

修复

• 重写 consolidate：必须消费有效研究计划和 Agent 精选清单；--include 仅归档并列示 per-call 轨迹，不再把原始召回正文按 endpoint 整体复制进报告。
• 将规范性法律依据与司法案例分组，依据先按 core／supplementary、再按法律位阶确定性排序；被排除候选只在正文显示统计，不重复暴露无关标题。

验证边界

• 已完成 Python 编译、原有 runtime contract 回归和新增合同／报告隔离回归；未运行需消耗积分的 live API/MCP 检索，不声称已验证真实召回质量。

[1.8.9] - 2026-08-09

修复

• 修复普通案例、权威案例和案例向量检索的日期参数映射：CLI 继续使用 --jarq-start/end，请求 payload 改为接口要求的 ja_start/end，避免日期筛选被忽略或拒绝。
• 重写 validate-query-filters.py 的校验内核：字段集合直接来自 yd_search.py 的真实 argparse 定义，覆盖 21 个 CLI 子命令中的 15 个可规划 API 接口（其余为归档、报告、调试等本地操作），移除仅含 8 个接口的硬编码回退；未知接口、错误 filters 类型和非法字段归属一律失败关闭。
• 修正文档中的密钥来源、网络域名和运行权限说明：支持环境变量或 .env，补充 ydzk.chineselaw.com 仅用于连通性检查，删除不必要的宽权限启动建议。

改进

• 新增 scripts/verify-runtime-contracts.py 无网络回归，直接捕获 mock 请求体并覆盖案例日期映射、合法查询、字段误挂、未知接口和错误数据类型。
• 将检索前字段门禁接入案件主流程；非零退出码不得继续调用 API/MCP。
• 统一“轻量案件研判—正反命题—查询矩阵—对位复核”的中间层定位；关键词扩展改为零命中或低对位后的诊断式改写，不再默认广撒网。
• 明确 economical/balanced/aggressive 只控制调用预算与深度，不得改变争点、正反命题、近邻排除和字段适配。
• 收紧 aggressive 边界：需求歧义仍先最小补问，hall-detect 因 50 积分与待查文本外传仍须用户明确要求，不以激进预算策略替代授权。
• MCP 工作流明确数据接入与研究中间层的边界；已有法律分析报告仍作为线索和待验证假设使用。
• API Key 门禁仅阻断真实元典调用；缺少密钥时仍可完成轻量研判、查询计划与离线校验，便于 Agent Eval Lab 做无 API 评测。

技术优化

• 删除已失效的 scripts/MANIFEST.json，接口权威索引统一为 endpoints/MANIFEST.json。
• 精简 SKILL.md 的 35 行接口明细表，改由清单渐进披露，主文件恢复到 500 行以内。
• 按项目规范统一 LICENSE.txt 版权行为 Copyright (c) 2025 杨卫薪律师（微信ywxlaw）。

验证边界

• 已完成 Python 编译、无网络 mock payload 和查询门禁回归；平台 live smoke 尚未执行，不声称日期筛选已经过真实接口验证。

[1.8.8] - 2026-08-05

修复

• validate-query-filters.py 动态自省 exec_module 改为默认关闭（静态扫描器误判为动态代码执行 Critical）：默认使用 _HARDCODED 硬编码字段表，仅设 YD_VALIDATE_DYNAMIC=1 时才动态加载 yd_search.py 自省。功能不变，消除 suspicious.dynamic_code_execution 命中
• SKILL.md 检测示例占位符写法调整，避免静态扫描器误判 suspicious.exposed_secret_literal

说明

纯文档与校验脚本改动，不影响检索/归档/接口功能。企业信息与幻觉检测接口保持不变。

[1.8.7] - 2026-08-05

文档完善

• README 删除已废弃的「自更新机制」章节（自更新代码此前已移除，消除供应链审计项）
• SKILL.md 新增「数据留存与隐私警示」：明示 archive 落盘、CWD 报告副本、外部传输至 open.chineselaw.com、敏感内容最小化建议
• SKILL.md 新增「所需权限」：网络/文件读写/环境变量/本地执行范围声明

说明

纯文档改动，不影响脚本与接口功能。企业信息与幻觉检测接口保持不变。

[1.8.6] - 2026-08-02

新增（references/07，评测 R6 发现回写）

• §9.2 平台覆盖边界意识：元典法源以民商/刑事为主，行政诉讼/部门规章/国家赔偿等覆盖可能有限。案件落入这些领域时，brief 标注 platform_coverage_note + 相关 query 的 fallback_path 指明外部渠道（flk.npc.gov.cn / 北大法宝 / 裁判文书网），不得用民商法源强行替代。源自评测 R6（worker 自发产出该意识，Claude judge 评为「通用方法的高阶工具边界意识」）。
• §5 fallback_path 字段补充「超平台领域 fallback 外部渠道」选项。

纯文档，不影响脚本/接口。

[1.8.5] - 2026-08-02

改进（references/07 通用化 + 补通用方法）

按「skill 是通用法律检索方法论、不固化特定领域案例」原则（用户反馈），清理具体案型举例 + 补通用方法。纯文档，不影响脚本/接口。

补通用方法：

• §3.2 新增「已有法律分析报告」三栏规则：prior_report_sources 拆为 report_facts / report_conclusions / hypotheses_to_verify；区分「报告援引的法源」（客观引用，不降级）vs「报告作者的法律判断」（主观，必降级为待验证假设）。
• §6 明确「1 轮 = 1 次交互回合，单回合最多 3 个会改变检索路径的核心问题」，不得套用 5 字段争点识别表全字段追问。
• §3 legal_elements.covered 用法：covered=false 要件必须落 facts_to_supplement，非装饰字段。
• §8 must_exclude_neighbor_types 写法：每项一个独立近邻 + 表述排除理由。
• §3 prior_report_sources 指向修正（见 §3.2，原误指 §5 query_matrix）。

通用化（删特定法律领域举例）：

• §8 删典型近邻清单（原列商业秘密/竞业、商业诋毁/名誉权、达人/商家、高管/员工等具体案型），改为通用识别方向（请求权基础不同 / 主体角色不同 / 行为链条或决定性事实不同）。
• §3.1 role_comparison_matrix 示例从「高管/普通员工」泛化为「主体角色 A/B」占位。
• §3 / §3.2 删具体举例（客户名单、特定法条号等），改为通用描述。

[1.8.4] - 2026-08-02

新增

• scripts/validate-query-filters.py：把 references/07 §9.1「字段归属接口速查表」从软约束（worker 自觉读）升级为硬门禁（脚本校验）。校验 research-plan / 单条 query 的 filter×interface 合法性（如 --wenshu-type 挂 case 关键词会被拦截，并提示正确归属 case-semantic）。退出码 0 合法 / 1 有违规，可接 CI / pre-commit / hook。字段表动态自省自 yd_search.py 的 build_parser()（零漂移，自动覆盖全部子命令含双别名/store_false，自省失败时回退硬编码）；覆盖 21 个子命令。源自 Round 3 worker 执行方差发现（12/67 filter 误挂）的工程闭环。

[1.8.3] - 2026-08-02

移除

• 移除内置自动更新机制：删除 scripts/updater.py（SkillUpdater，334 行）、yd_search.py 中每次检索自动联网检测远程版本的触发逻辑、check-update / do-update 子命令，以及 SKILL.md 的「版本更新」段。原机制每次检索时联网检测新版（≥7 天一次）且 do-update 会联网下载覆盖本地文件——移除以消除自动联网与文件覆盖的风险。更新改由 git pull / clawhub-sync 等外部通道处理。
• 清理死代码：yd_search.py 中无任何引用的 CURRENT_VERSION = "1.7.5" 常量。

[1.8.2] - 2026-08-02

新特性 — 检索机制感知型法律研究中间层（DEC-006 / Task-001）

把 Skill 从"元典 API/MCP 包装 + 归档 + 报告"升级为"检索机制感知型法律研究中间层"：案件检索（综合检索 / 类案对标 / 已有报告复盘）默认先完成"理解案件 — 形成命题 — 查询矩阵 — 对位复核"，再调用接口。

• 新增 references/07-research-middleware.md：
  • research_brief schema：争点 / 要件 / 决定性事实 / 待补事实 / 必须排除的近邻案型 / 已有报告来源，外加 key_decisive_facts 与 key_exclusions 两个置顶短摘要（便于快速复核）。
  • propositions schema：每条单一判断，区分规范 / 事实结构 / 裁判规则 / 反向；每个 decisive 争点至少 1 条正向 + 1 条反向。
  • query_matrix schema：一争点一查询、单一接口；带 exclusion_criteria 与零命中 fallback_path；case 关键词不构造后端无法表达的长 AND。
  • 多主体角色案件 role_comparison_matrix（如高管竞业禁止 vs 普通员工保密义务）。
  • 已有法律分析报告使用规则：区分 report_facts / report_conclusions / hypotheses_to_verify 三栏，把报告结论降级为待验证假设，不跳过轻量研判。
  • 前置门禁（最小必要补问，最多 1 轮）、近邻案型排除清单、HIGH/MEDIUM/LOW/MISMATCH 对位度标签、机器可读导出骨架。
  • §9 接口路由按真实后端机制选择 + §9.1 字段归属接口速查表（防 filter 误挂，以 scripts/yd_search.py 源码为权威）。
• SKILL.md 新增精简"检索机制感知主流程（案件检索默认）"6 步段，详细 schema 放入单层 reference（主文档不膨胀）；简单法条 / 案号 / 纯概念检索仍直接走接口速查，不启动本流程。
• --expand 全局 OR 行为保留兼容，仅降级为查询矩阵内部的一条改写手段（不再作案件检索默认主路径）。

评测（agent-eval-lab，evals/yuandian-middleware-260802）

• candidate 97 vs baseline 82.75（6 场景无 API 检索规划盲评）。
• 跨家族 3 judge（glm-5.2 / DeepSeek-V3.2 / Qwen3.5-35B）：2/3 判 candidate 胜；case-03「已有报告三栏区分」三家一致 candidate pass / baseline fail。
• worker n=2：关键结构决策 100% 可复现。
• 接口路由教义经 yd_search.py 源码验证一致（含确认 case-semantic 支持 --jarq-start/end）。

[1.7.5] - 2026-07-20

新特性

• 归档按检索目的分文件夹：新增 YD_PROJECT 环境变量，AI/用户在研究任务开始时设定（如 export YD_PROJECT=0713-商标在先使用权），该任务所有检索自动归到 archive/<project>/ 一个文件夹，便于追溯；未设时按日期 archive/YYYYMMDD/ 兜底，不再平铺根目录。缓存查重全局跨 project 生效（_archive_lookup 改 rglob），同一问题在不同任务命中已有归档、不重复消耗积分。archive-list 输出带 project 相对路径、按时间倒序。
• 默认剔除办案无关条目（五类效力级别）：search / keyword / regulation 默认过滤 effect1 ∈ {行业/团体规范, 地方律协规定, 行政机关工作文件, 党内法规, 军事法规规章}（律协指引、课题公告/答复函、党纪规定、军队规定等——非法律渊源或与一般民商事/刑事办案无关）。基于 archive 实测样本定位字段特征；footer 提示剔除数量，涉党纪/涉军等特殊案件加 --keep-industry 保留。archive/ 原始数据完整保留。

修复

• 修复 skill 根目录堆积检索副本问题：_archive_write_report 写 CWD 副本前判断 cwd == SKILL_ROOT，相等则跳过（主归档仍在 archive/，不丢数据）。根因是 yd-run 捕获的 YD_USER_CWD 若等于 skill 根，副本直接堆根目录。
• 清理 skill 根目录 22 个历史检索副本 .md（archive/ 内均有同名备份，逐个 diff 一致）。
• 新增 skill 根 .gitignore，兜底忽略检索副本文件名模式，防止未来污染 git status。

[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 调试输出