{"id":"1048fa63-673f-405b-a3b6-a2b55bd63420","entityType":"agent","slug":"clawhub-cat-xierluo-yuandian-law-search","name":"元典法条与案例检索","canonicalUrl":"https://www.xpersona.co/agent/clawhub-cat-xierluo-yuandian-law-search","canonicalPath":"/agent/clawhub-cat-xierluo-yuandian-law-search","generatedAt":"2026-10-10T09:08:49.040Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T21:53:39.032Z","emptyReason":null},"description":"元典法条与案例检索。本技能应在需要查询中国法律法规条文、检索相关案例、为法律分析提供数据支撑时使用。 Skill: 元典法条与案例检索 Owner: cat-xierluo Summary: 元典法条与案例检索。本技能应在需要查询中国法律法规条文、检索相关案例、为法律分析提供数据支撑时使用。 Tags: latest:1.8.8 Version history: v1.8.8 | 2026-08-05T13:37:51.237Z | user 修复：validate-query-filters 动态自省默认关闭（消除动态代码执行误报）；SKILL.md 占位符调整（消除密钥字面量误报） v1.8.7 | 2026-08-05T13:29:12.502Z | user 文档完善：README 删除已废弃自更新章节；SKILL.md 新增数据留存与隐私警示、所需权限声明（纯文档，不影响功能） v1.8.6 | 2026-08-04T07:53:59.346Z | user v1.8.6 升级（原 1.7.5） v1.7.5 | 20","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s179ghx665dhgcsrdzyss2am0x83g7nf:yuandian-law-search","sourceUrl":"https://clawhub.ai/cat-xierluo/yuandian-law-search","homepage":"https://clawhub.ai/cat-xierluo/skills/yuandian-law-search","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/cat-xierluo/yuandian-law-search","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/cat-xierluo/skills/yuandian-law-search","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":40,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"元典法条与案例检索。本技能应在需要查询中国法律法规条文、检索相关案例、为法律分析提供数据支撑时使用。 Skill: 元典法条与案例检索 Owner: cat-xierluo Summary: 元典法条与案例检索。本技能应在需要查询中国法律法规条文、检索相关案例、为法律分析提供数据支撑时使用。 Tags: latest:"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:53:39.032Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:53:39.032Z","emptyReason":null},"stars":null,"forks":null,"downloads":1959,"packageName":null,"latestVersion":"1.8.8","tractionLabel":"2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:53:39.032Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T21:53:39.032Z","lastCrawledAt":"2026-10-09T21:53:39.032Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T21:53:39.032Z","lastVerifiedAt":null,"highlights":[{"version":"1.8.8","createdAt":"2026-08-05T13:37:51.237Z","changelog":"修复：validate-query-filters 动态自省默认关闭（消除动态代码执行误报）；SKILL.md 占位符调整（消除密钥字面量误报）","fileCount":53,"zipByteSize":113728},{"version":"1.8.7","createdAt":"2026-08-05T13:29:12.502Z","changelog":"文档完善：README 删除已废弃自更新章节；SKILL.md 新增数据留存与隐私警示、所需权限声明（纯文档，不影响功能）","fileCount":53,"zipByteSize":113593},{"version":"1.8.6","createdAt":"2026-08-04T07:53:59.346Z","changelog":"v1.8.6 升级（原 1.7.5）","fileCount":53,"zipByteSize":113377},{"version":"1.7.5","createdAt":"2026-07-20T12:33:19.811Z","changelog":"v1.7.5: 归档按检索目的分文件夹(YD_PROJECT 环境变量+日期兜底，缓存全局跨project不重复耗积分)；默认剔除办案无关条目(律协指引/行政机关工作文件/党内法规/军事法规规章五类)；修复skill根目录堆积检索副本","fileCount":52,"zipByteSize":101554},{"version":"1.7.4","createdAt":"2026-06-15T14:10:49.788Z","changelog":"修复 --expand 自动 OR 失效（参数层 search-mode 默认改为 None，统一由 _resolve_keyword_search_mode 处理函数判定）；强化案件综合/标杆类案检索的 case-semantic 优先、短关键词复检与零命中复检规则","fileCount":54,"zipByteSize":101506},{"version":"1.6.0","createdAt":"2026-06-11T06:07:11.710Z","changelog":"v1.6.0: 新增 ingest 子命令消费元典 MCP 输出（自动识别 jsonrpc 包装），INGEST_ROUTING 覆盖 36 个 endpoint；提供 scripts/.mcp.json.example 模板供客户端接入元典 MCP（law/case/company 3 servers × 33 data tools）。本 skill 价值从 API 包装转向归档 + 法律检索报告生成。","fileCount":45,"zipByteSize":81341},{"version":"1.5.1","createdAt":"2026-06-11T03:17:57.640Z","changelog":"v1.4.0: 每次检索自动落盘结构化 .md 到 archive/ 和用户 CWD；新增 --no-report / --no-cwd-report 开关。v1.5.0: 新增 consolidate 子命令生成 6 节标准法律检索报告（案情/目的/思路/结果/分析/结论）。v1.5.1: consolidate 加 --project 参数，按案件归类到 archive/<project>/ 子目录。","fileCount":45,"zipByteSize":76713},{"version":"1.3.4","createdAt":"2026-05-28T06:56:08.062Z","changelog":"新增 yd-run 干净环境运行入口和 --network-check 网络预检，SKILL.md 和 README 推荐使用 yd-run 降低 Codex 沙箱和代理环境影响","fileCount":214,"zipByteSize":1809543}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s179ghx665dhgcsrdzyss2am0x83g7nf:yuandian-law-search","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cat-xierluo-yuandian-law-search/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cat-xierluo-yuandian-law-search/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cat-xierluo-yuandian-law-search/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cat-xierluo-yuandian-law-search/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cat-xierluo-yuandian-law-search/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cat-xierluo-yuandian-law-search/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T09:08:49.036Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cat-xierluo-yuandian-law-search/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cat-xierluo-yuandian-law-search/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cat-xierluo-yuandian-law-search/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cat-xierluo-yuandian-law-search/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T21:53:39.032Z","emptyReason":null},"readme":"Skill: 元典法条与案例检索\n\nOwner: cat-xierluo\n\nSummary: 元典法条与案例检索。本技能应在需要查询中国法律法规条文、检索相关案例、为法律分析提供数据支撑时使用。\n\nTags: latest:1.8.8\n\nVersion history:\n\nv1.8.8 | 2026-08-05T13:37:51.237Z | user\n\n修复：validate-query-filters 动态自省默认关闭（消除动态代码执行误报）；SKILL.md 占位符调整（消除密钥字面量误报）\n\nv1.8.7 | 2026-08-05T13:29:12.502Z | user\n\n文档完善：README 删除已废弃自更新章节；SKILL.md 新增数据留存与隐私警示、所需权限声明（纯文档，不影响功能）\n\nv1.8.6 | 2026-08-04T07:53:59.346Z | user\n\nv1.8.6 升级（原 1.7.5）\n\nv1.7.5 | 2026-07-20T12:33:19.811Z | user\n\nv1.7.5: 归档按检索目的分文件夹(YD_PROJECT 环境变量+日期兜底，缓存全局跨project不重复耗积分)；默认剔除办案无关条目(律协指引/行政机关工作文件/党内法规/军事法规规章五类)；修复skill根目录堆积检索副本\n\nv1.7.4 | 2026-06-15T14:10:49.788Z | user\n\n修复 --expand 自动 OR 失效（参数层 search-mode 默认改为 None，统一由 _resolve_keyword_search_mode 处理函数判定）；强化案件综合/标杆类案检索的 case-semantic 优先、短关键词复检与零命中复检规则\n\nv1.6.0 | 2026-06-11T06:07:11.710Z | user\n\nv1.6.0: 新增 ingest 子命令消费元典 MCP 输出（自动识别 jsonrpc 包装），INGEST_ROUTING 覆盖 36 个 endpoint；提供 scripts/.mcp.json.example 模板供客户端接入元典 MCP（law/case/company 3 servers × 33 data tools）。本 skill 价值从 API 包装转向归档 + 法律检索报告生成。\n\nv1.5.1 | 2026-06-11T03:17:57.640Z | user\n\nv1.4.0: 每次检索自动落盘结构化 .md 到 archive/ 和用户 CWD；新增 --no-report / --no-cwd-report 开关。v1.5.0: 新增 consolidate 子命令生成 6 节标准法律检索报告（案情/目的/思路/结果/分析/结论）。v1.5.1: consolidate 加 --project 参数，按案件归类到 archive/<project>/ 子目录。\n\nv1.3.4 | 2026-05-28T06:56:08.062Z | user\n\n新增 yd-run 干净环境运行入口和 --network-check 网络预检，SKILL.md 和 README 推荐使用 yd-run 降低 Codex 沙箱和代理环境影响\n\nv1.3.3 | 2026-05-13T07:16:22.846Z | user\n\narchive 归档新增 source_urls 字段，自动补全法条/案例/法规/企业来源链接；新增 backfill-urls 回填命令\n\nv1.3.2 | 2026-05-10T13:18:43.166Z | user\n\n适配 24 个新 API 接口（幻觉检测+企业信息系列），新增 5 个子命令，新增策略行为矩阵，版本从 v1.2.0 升至 v1.3.2\n\nv1.2.0 | 2026-05-09T05:23:08.586Z | user\n\n新增可配置检索策略（balanced/economical/aggressive），strategy 子命令，策略感知默认返回数量\n\nv0.3.1 | 2026-04-08T05:14:44.958Z | user\n\n移除跨技能引用章节，保持技能描述独立聚焦\n\nv0.3.0 | 2026-04-06T03:17:48.545Z | user\n\n元典法条与案例检索，支持法条语义/关键词/详情检索和案例关键词/向量语义检索\n\nArchive index:\n\nArchive v1.8.8: 53 files, 113728 bytes\n\nFiles: CHANGELOG.md (32763b), endpoints/01-law-vector-search.md (2620b), endpoints/02-law-keyword-search.md (3804b), endpoints/03-law-detail.md (675b), endpoints/04-case-semantic-search.md (2073b), endpoints/05-case-keyword-search.md (2640b), endpoints/06-case-keyword-search-authority.md (1044b), endpoints/07-case-detail.md (1141b), endpoints/08-regulation-search.md (1031b), endpoints/09-regulation-detail.md (569b), endpoints/10-enterprise-search.md (1014b), endpoints/11-enterprise-detail.md (606b), endpoints/12-hall-detect.md (2877b), endpoints/13-enterprise-search-lightweight.md (1102b), endpoints/14-enterprise-base-info.md (794b), endpoints/15-enterprise-aggregation-summary.md (584b), endpoints/16-enterprise-out-invest.md (643b), endpoints/17-enterprise-brand.md (618b), endpoints/18-enterprise-patent.md (619b), endpoints/19-enterprise-soft-right.md (658b), endpoints/20-enterprise-works-right.md (656b), endpoints/21-enterprise-icp.md (624b), endpoints/22-enterprise-change-info.md (650b), endpoints/23-enterprise-writ-agg.md (660b), endpoints/24-enterprise-writ-list.md (646b), endpoints/25-enterprise-court-session-notice.md (652b), endpoints/26-enterprise-court-notice.md (642b), endpoints/27-enterprise-executions.md (680b), endpoints/28-enterprise-executed-person.md (666b), endpoints/29-enterprise-frozen-equity.md (646b), endpoints/30-enterprise-punishment.md (647b), endpoints/31-enterprise-pledge.md (649b), endpoints/32-enterprise-guaranty.md (648b), endpoints/33-enterprise-abnormal-operation.md (672b), endpoints/34-enterprise-corporate-tax.md (646b), endpoints/35-enterprise-serious-illegal.md (654b), endpoints/MANIFEST.json (10975b), LICENSE.txt (1090b), README.md (7826b), references/01-keyword-expansion.md (4133b), references/02-typical-workflows.md (9640b), references/03-report-consolidation.md (5655b), references/04-report-design-notes.md (2361b), references/05-mcp-workflow.md (3150b), references/06-enterprise-portrait.md (2011b), references/07-research-middleware.md (19580b), scripts/MANIFEST.json (2081b), scripts/validate-query-filters.py (8281b), scripts/yd_search.py (94978b), skill-card.md (2921b), SKILL.md (29603b), templates/legal-research-report.md (1613b), _meta.json (138b)\n\nFile v1.8.8:SKILL.md\n\n---\nname: yuandian-law-search\nhomepage: https://github.com/cat-xierluo/legal-skills\nauthor: 杨卫薪律师（微信ywxlaw）\nversion: \"1.8.8\"\nlicense: MIT\ndescription: 元典法条与案例检索。本技能应在需要查询中国法律法规条文、检索相关案例、为法律分析提供数据支撑时使用。\n---\n\n# 元典法条与案例检索\n\n通过元典开放平台 API 检索中国法律法规条文和案例。**每次 API 调用消耗 1-50 积分**（视接口而定）。所有检索结果会自动归档到本地，方便后续回溯。\n\n## 数据留存与隐私警示\n\n本技能在提供便利的同时会产生本地留存与外部传输，使用前请知悉：\n\n- **本地归档**：每次检索的原始响应与结构化报告会自动写入 `archive/`（按 `YD_PROJECT` 或日期归类），并默认在您运行命令的工作目录生产一份 `.md` 副本（便于附卷；当工作目录恰为 skill 根目录时自动跳过）。可用 `--no-report` 完全跳过、`--no-cwd-report` 仅跳过工作目录副本。这些文件可能包含案由、当事人、裁判文书正文等敏感内容，**请勿将其提交至公开仓库或随意分享**。\n- **外部传输**：检索请求与（如幻觉检测）待查文本会发送至元典开放平台 `open.chineselaw.com`。提交给 `hall-detect` 等接口的文本可能包含案卷事实、合同或客户信息，**建议先脱敏再提交**。平台侧的留存策略以其服务条款为准。\n- **敏感内容最小化**：案例文书、企业信息含个人或商业敏感数据，引用与归档时遵循\"最小必要\"原则，避免大段全文外泄。\n\n## 所需权限\n\n本技能运行需要以下本地能力，均限定在检索与归档目的内：\n\n- **网络访问**：仅访问元典开放平台 `open.chineselaw.com`（HTTPS），用于检索与归档查重。\n- **文件系统读写**：读取 `scripts/.env`（API Key）、`scripts/MANIFEST.json`；写入 `archive/` 与当前工作目录的报告副本（可经 `--no-report`/`--no-cwd-report` 关闭）。\n- **环境变量**：读取 `YD_API_KEY`（鉴权）、`YD_STRATEGY`/`YD_PROJECT`（检索策略与归类）等；`yd-run` 以干净环境启动 Python，仅保留必要变量。\n- **本地代码执行**：通过 `scripts/yd-run` 调用 Python 检索脚本；不安装第三方运行时、不执行自动更新。\n\n## 前置要求（每次调用前自动检测）\n\n每次使用本技能前，**必须先执行以下检测流程**，确认 API Key 已就绪：\n\n### 检测步骤\n\n1. **检测 `.env` 文件**：检查 `scripts/.env` 是否存在\n2. **检测 API Key**：读取文件中 `YD_API_KEY` 的值，确认非空且不是占位符 `your-api-key-here`\n3. **若检测失败**，向用户提示以下引导信息并终止：\n\n```\n⚠️ 元典 API Key 未配置。请按以下步骤获取并配置：\n\n1. 注册/登录：访问 https://open.chineselaw.com ，使用手机号注册\n2. 创建 API Key：登录后在个人中心创建 Key\n3. 配置密钥：将 Key 填入以下文件\n\n   scripts/.env\n   ─────────────\n   YD_API_KEY=sk-你的密钥(此处替换为真实 Key)\n   # YD_STRATEGY=balanced\n   ─────────────\n\n每次调用消耗 10 积分，需在平台充值。\n配置完成后重新发起检索即可。\n```\n\n4. **若检测通过**，继续执行用户请求的检索命令\n\n### 检测命令\n\n```bash\n# 检测 .env 文件和 API Key\nif [ -f \"scripts/.env\" ]; then\n  KEY=$(grep '^YD_API_KEY=' scripts/.env | cut -d'=' -f2-)\n  if [ -n \"$KEY\" ] && [ \"$KEY\" != \"your-api-key-here\" ]; then\n    echo \"API Key 已就绪\"\n  else\n    echo \"API Key 未配置\"\n  fi\nelse\n  echo \".env 文件不存在\"\nfi\n\n# 读取检索策略\nSTRATEGY=$(grep '^YD_STRATEGY=' scripts/.env 2>/dev/null | cut -d'=' -f2)\necho \"当前策略：${STRATEGY:-balanced}\"\n```\n\n## 网络环境与推荐调用入口\n\n默认使用 `scripts/yd-run` 执行检索，而不是直接调用底层 `yd_search.py`。`yd-run` 会以干净环境启动 Python：清除 Codex/代理相关环境变量，保留 `HOME`、`PATH`、语言环境、`YD_API_KEY`、`YD_STRATEGY`，并继续读取 `scripts/.env` 和 `archive/` 缓存。\n\n```bash\nscripts/yd-run search \"正当防卫的限度\" --sxx 现行有效\n```\n\n若遇到 `nodename nor servname provided, or not known` 或其他网络错误，先执行无积分消耗的网络检查：\n\n```bash\nscripts/yd-run --network-check\n```\n\n注意：`yd-run` 只能避免 Codex 进程环境变量、代理变量和 PATH 漂移造成的影响；如果 Codex 本身以网络沙箱启动，或系统代理/VPN 接管 DNS，子进程仍会受到系统级网络策略影响。终端 Codex 应使用 `--sandbox danger-full-access --ask-for-approval never` 启动。\n\n## 检索机制感知主流程（案件检索默认）\n\n当用户描述事实结构、争议焦点、诉讼立场，或问\"类似案件怎么判\"\"能不能主张 XX\"\"对方抗辩怎么办\"时，**先完成案件检索主流程，再调用接口**（DEC-006）。简单法条/案号/纯概念检索（`detail` / `case-detail` / 单条 `search`）不启动本流程，直接看下方接口速查。\n\n1. **轻量案件研判** → 产出检索简报（争点、要件、决定性事实、待补事实、必须排除的近邻案型、已有报告来源）。\n2. **派生检索命题** → 每个命题只验证一项判断，区分规范 / 事实结构 / 裁判规则 / 反向；每个 decisive 争点至少 1 条正向 + 1 条反向。\n3. **派生查询矩阵** → 一争点一查询、单一接口；案例关键词只放 4-6 个高信息密度词，不构造后端无法表达的长 AND。\n4. **小样本试检** → 1-2 条命题先验证接口与表达是否有效。\n5. **对位复核** → 按 HIGH / MEDIUM / LOW / MISMATCH 复核；只有诊断出偏差原因（接口误选 / 表达不适配 / 近邻混入）后才扩展查询或换接口。\n6. **正式检索** → 结论—依据—查询可追溯报告。\n\n信息不足时按\"最小必要\"补问（最多 1 轮，只问会改变检索路径的最关键问题），不空跑查询；事实不足但不影响查询方向的，标注假设继续。\n\n完整字段定义、接口路由规则、近邻案型排除清单、前置门禁判定与机器可读导出骨架见：[`references/07-research-middleware.md`](references/07-research-middleware.md)。\n\n> 下方「接口速查」是执行第 3 步查询矩阵时\"按机制选接口\"的依据，不是检索的起点。\n\n## 接口速查\n\n本技能共 35 个接口，分为四层。选择规则：\n\n1. 用户问\"XX法怎么规定的\" → 先用 `search` 语义检索\n2. 用户问\"关于XX的法律条文\" → 用 `keyword` 关键词检索\n3. 用户问\"民法典第XX条\" → 用 `detail` 精确获取\n4. 用户给出明确案由/关键词并要求精确筛选案例 → 用 `case` 关键词检索（默认普通案例）\n5. 用户描述事实结构、争议焦点或问\"类似案件怎么判\" → 优先用 `case-semantic` 语义检索\n6. 用户要求更深入了解某案例 → 提醒用户将消耗积分，确认后用 `case-detail`\n7. 用户要求企业背景调查 → 先用 `enterprise-search` 定位，再用 `enterprise-base`/`enterprise-summary` 获取详情\n8. 用户要求查询企业分项信息（涉诉、商标、专利等） → 用 `enterprise-list --type TYPE`\n9. 用户要求检测文本中法规/案例是否准确 → 用 `hall-detect`\n\n**核心接口（默认使用）：** `search` · `keyword` · `detail` · `case` · `case-semantic`\n**扩展接口（需确认）：** `regulation` · `regulation-detail` · `case-detail` · `case --authority-only`\n**附属接口（仅限明确要求）：** `enterprise` · `enterprise-detail` · `enterprise-search` · `enterprise-base` · `enterprise-summary` · `enterprise-list`\n**专项接口（仅限明确要求）：** `hall-detect`\n\n## 调用策略\n\n读取 `scripts/.env` 中的 `YD_STRATEGY` 配置（默认 `balanced`）。三种策略决定了 AI 的接口使用、确认流程和补充检索行为。\n\n**用户的明确指令始终优先于策略默认行为。**\n\n### 通用规则（所有策略共享）\n\n每次 API 调用消耗 1-50 积分（视接口而定）。以下规则不受策略影响：\n\n1. **必须调用 API**：需要引用具体法条文号 / 需要确认时效性 / 用户明确要求检索 / 案例检索 / AI 对自身记忆不确定\n2. **可以不调用**：纯概念性问题 / 对话中已检索过相同内容 / 用户未要求查找 / 用户明确说不需要查\n3. **积分消耗模式**：大部分接口每次 5-10 积分，幻觉检测 50 积分，轻量企业检索 1 积分。法条检索通常一次足够。案例检索是两阶段消耗（摘要 10 + 详情 每个 10）\n4. **接口分层**：核心（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）\n\n### 均衡策略（balanced，默认）\n\n即当前\"正确性优先\"策略，不改变现有行为。\n\n- **核心接口**：直接使用，无需确认\n- **扩展接口**：调用前告知用户将消耗积分，等待确认\n- **附属接口**：仅当用户明确要求时使用\n- **case-detail**：先展示摘要，由用户主动选择感兴趣的案例后再调用\n- **补充检索**：不主动运行语义+关键词双检索，选择最合适的一种\n- **积分报告**：每次检索后说明消耗和累计\n\n### 省钱策略（economical）\n\n在 balanced 基础上进一步收紧，最大限度减少积分消耗。\n\n- **核心接口**：直接使用，但应先检查归档缓存是否有类似结果\n- **扩展接口**：需用户二次确认（第一次只展示摘要和积分提醒，等用户再次确认后才调用）\n- **附属接口**：仅当用户明确要求时使用，同样需确认\n- **case-detail**：仅当用户指定具体案例编号时才调用，不主动提供\"是否查看详情\"选项\n- **补充检索**：不运行补充检索，一次只用一种模式\n- **积分报告**：每次检索后详细报告，并提醒可用的节约手段\n\n### 激进策略（aggressive）\n\n不考虑积分消耗，最大化检索精度和覆盖面。\n\n- **所有接口**：直接使用，无需确认\n- **case-detail**：自动获取最相关的 2-3 个案例的完整判决书，不需用户逐一选择\n- **补充检索**：对同一问题同时运行语义+关键词双检索，合并去重后展示\n- **积分报告**：简要说明消耗即可，不强调节约\n- **额外行为**：法条检索后发现相关法规（如司法解释），主动追加 regulation 检索；用户需求模糊时，宁可多查也不漏查\n\n### 接口策略速查\n\n部分接口在通用规则之上有特殊行为约束（按积分成本或权限敏感度划分）：\n\n| 接口 | 积分 | balanced | economical | aggressive |\n|------|------|----------|-----------|------------|\n| **hall-detect** | 50 | 用户明确要求时才使用，需确认\"检测需要 50 积分\" | 二次确认（第一次仅展示积分提醒，等用户再次确认才调用） | 可主动对用户引用的法条/案例做幻觉核验 |\n| **enterprise-search** | 1 | 直接使用，无需确认 | 优先检查缓存，未命中时直接使用（仅 1 积分） | 直接使用 |\n| **enterprise-base / enterprise-summary** | 10 | 用户明确要求时使用，告知积分消耗 | 需二次确认 | 直接使用 |\n| **enterprise-list** | 5-10/次 | 用户指定类型时调用，提醒多种类型会累积积分 | 每次只查一种类型，展示全部可用类型让用户选择 | 企业尽调场景可一次性查询多个相关类型（如涉诉+行政处罚+失信） |\n\n## 关键词扩展与典型工作流\n\nAI 在执行检索前应主动扩展关键词（上位概念 / 并列概念 / 程序-实体关联），\n并在多场景下遵循典型工作流与积分反馈原则。详见：\n\n- [`references/01-keyword-expansion.md`](references/01-keyword-expansion.md) — 关键词扩展三原则、`--expand` 参数、分阶段检索示例、策略兼容性\n- [`references/02-typical-workflows.md`](references/02-typical-workflows.md) — 法条 / 案例 / 关键词精确 / 企业尽调 / 幻觉检测 / 企业风险排查六大场景 + AI 向用户反馈的 8 条原则（含 per-call 报告落盘与禁止复制到目标目录的硬规则）\n\n## 检索模式选择\n\n每个领域有**语义检索**和**关键词检索**两种模式。\n\n| | 语义检索 | 关键词检索 |\n|---|---|---|\n| **子命令** | `search`（法条）/ `case-semantic`（案例） | `keyword`（法条）/ `case`（案例） |\n| **输入** | 自然语言问题或描述 | 精确关键词组合 |\n| **匹配** | 语义相似度，概念关联 | 字面匹配，AND/OR 逻辑 |\n| **返回量** | 默认 45 条 | 默认 10 条 |\n\n**用语义检索**：用户提出法律问题 / 描述场景 / 不确定关键词 / 需要广覆盖 → 不确定时默认用\n**用关键词检索**：用户给出明确关键词 / 需要 AND/OR 逻辑 / 需按日期、效力级别、法院等精确筛选 / 语义检索结果不够聚焦\n**案例检索红线**：综合案件和类案对标的第一轮优先 `case-semantic`；`case` 只放 4-6 个高信息密度关键词，避免长事实结构默认 AND 导致零命中。\n\n此外需区分检索法条还是案例：\"XX的法律依据\" → 法条检索；\"有没有相关案例\" → 案例检索；兼要法条和案例 → 先法条后案例，两次调用。\n\n## 核心接口用法\n\n### 1. 法条语义检索（search）\n\n```bash\nscripts/yd-run search \"正当防卫的限度\" --sxx 现行有效\n```\n\n### 2. 法条关键词检索（keyword）\n\n```bash\nscripts/yd-run keyword \"人工智能 监管\" \\\n  --effect1 法律 --sxx 现行有效 \\\n  --fbrq-start 2022-01-01 --fbrq-end 2026-03-01\n```\n\n### 3. 法条详情检索（detail）\n\n```bash\nscripts/yd-run detail \"民法典\" --ft-name \"第十五条\"\n```\n\n### 4. 案例关键词检索（case）\n\n```bash\n# 普通案例（默认）\nscripts/yd-run case \"买卖合同纠纷\" --province 广西\n\n# 权威案例（扩展，需确认）\nscripts/yd-run case \"买卖合同纠纷\" --province 广西 --authority-only\n```\n\n### 5. 案例语义检索（case-semantic）\n\n```bash\nscripts/yd-run case-semantic \"正当防卫的限度\" --jarq-start 2020-01-01\n```\n\n## 扩展接口用法\n\n### 6. 法规关键词检索（regulation）\n\n```bash\nscripts/yd-run regulation \"数据安全\" --effect1 法律 --sxx 现行有效\n```\n\n### 7. 法规详情（regulation-detail）\n\n```bash\nscripts/yd-run regulation-detail --name \"中华人民共和国数据安全法\"\n```\n\n### 8. 案例详情（case-detail）\n\n```bash\nscripts/yd-run case-detail --type ptal --ah \"（2025）桂09民终192号\"\n```\n\n### 9. 企业检索（enterprise）\n\n```bash\nscripts/yd-run enterprise \"华为\" --num 5\n```\n\n### 10. 企业详情（enterprise-detail）\n\n```bash\nscripts/yd-run enterprise-detail --credit-code \"9144030071526726XG\"\n```\n\n## 幻觉检测\n\n### 11. 法规/法条/案例幻觉检测（hall-detect）\n\n检测文本中引用的法规、法条、案例是否存在幻觉（是否真实存在、内容是否准确）。**每次调用消耗 50 积分**。\n\n```bash\nscripts/yd-run hall-detect \"根据《中华人民共和国数据保护法》第35条规定，数据处理者应当...\"\n```\n\n返回结果包含：\n- **法规检测**：每条法规是否真实存在（law_exists），语义比对结论和相似度\n- **案例检测**：每条案例是否真实存在，基本事实和裁判要点\n- **高亮文本**：标注了检测结果的原文本\n\n## 企业全息画像\n\n企业信息类接口（`enterprise-search` / `enterprise-base` / `enterprise-summary` / `enterprise-list`）的完整用法、`--type` 可选维度（涉诉、商标、专利、对外投资、股权冻结等 20 类）与积分消耗表见：\n\n[`references/06-enterprise-portrait.md`](references/06-enterprise-portrait.md)\n\n## 通用参数说明\n\n### 法条检索通用筛选\n\n| 参数 | 说明 | 可选值 |\n|------|------|--------|\n| `--effect1` | 效力级别（可多次指定） | 宪法、法律、司法解释、行政法规、部门规章、地方性法规 等 |\n| `--sxx` | 时效性（可多次指定） | 现行有效、失效、已被修改、部分失效、尚未生效 |\n| `--keep-industry` | 保留默认剔除的办案无关条目 | 无需取值（flag） |\n\n> **默认剔除办案无关条目**：`search` / `keyword` / `regulation` 默认过滤 `effect1 ∈ {行业/团体规范, 地方律协规定, 行政机关工作文件, 党内法规, 军事法规规章}` 的条目（律协指引、课题公告/答复函、党纪规定、军队规定等——非法律渊源或与一般民商事/刑事办案无关）。footer 提示剔除数量；涉党纪/涉军等特殊案件需要时加 `--keep-industry` 保留。`archive/` 原始数据仍完整，仅过滤显示与 `.md` 报告。\n\n### 案例检索通用筛选\n\n| 参数 | 说明 |\n|------|------|\n| `--province` / `--xzqh-p` | 省份筛选 |\n| `--jarq-start / --jarq-end` | 结案日期范围 |\n| `--cj` | 法院层级：最高/高级/中级/基层 |\n| `--wenshu-type` | 案件类型：刑事案件/民事案件/行政案件 |\n\n## Reference 文档索引\n\n### 工作流指南\n\n- [关键词扩展与分阶段检索](references/01-keyword-expansion.md)\n- [典型工作流与用户引导](references/02-typical-workflows.md)\n- [法律检索报告与目标目录归档](references/03-report-consolidation.md)\n- [法律检索报告 7 节设计原理](references/04-report-design-notes.md)\n- [MCP 协同工作流](references/05-mcp-workflow.md)\n- [企业全息画像](references/06-enterprise-portrait.md)\n- [检索机制感知型中间层执行合同](references/07-research-middleware.md)\n\n### 接口清单与 API 端点文档\n\n`endpoints/MANIFEST.json` 记录全部已适配接口的元数据（端点、子命令、分层、分类），以及平台接口排查历史。下次排查新增接口时，更新该文件的 `check_history` 即可。\n\n| # | 文件 | 接口 |\n|---|------|------|\n| 01 | [law-vector-search.md](endpoints/01-law-vector-search.md) | 法条语义检索 |\n| 02 | [law-keyword-search.md](endpoints/02-law-keyword-search.md) | 法条关键词检索 |\n| 03 | [law-detail.md](endpoints/03-law-detail.md) | 法条详情 |\n| 04 | [case-semantic-search.md](endpoints/04-case-semantic-search.md) | 案例语义检索 |\n| 05 | [case-keyword-search.md](endpoints/05-case-keyword-search.md) | 普通案例关键词检索 |\n| 06 | [case-keyword-search-authority.md](endpoints/06-case-keyword-search-authority.md) | 权威案例关键词检索 |\n| 07 | [case-detail.md](endpoints/07-case-detail.md) | 案例详情 |\n| 08 | [regulation-search.md](endpoints/08-regulation-search.md) | 法规关键词检索 |\n| 09 | [regulation-detail.md](endpoints/09-regulation-detail.md) | 法规详情 |\n| 10 | [enterprise-search.md](endpoints/10-enterprise-search.md) | 企业名称检索 |\n| 11 | [enterprise-detail.md](endpoints/11-enterprise-detail.md) | 企业详情 |\n| 12 | [hall-detect.md](endpoints/12-hall-detect.md) | 幻觉检测 |\n| 13 | [enterprise-search-lightweight.md](endpoints/13-enterprise-search-lightweight.md) | 企业检索（轻量） |\n| 14 | [enterprise-base-info.md](endpoints/14-enterprise-base-info.md) | 企业基本信息 |\n| 15 | [enterprise-aggregation-summary.md](endpoints/15-enterprise-aggregation-summary.md) | 企业聚合总览 |\n| 16 | [enterprise-out-invest.md](endpoints/16-enterprise-out-invest.md) | 对外投资 |\n| 17 | [enterprise-brand.md](endpoints/17-enterprise-brand.md) | 商标 |\n| 18 | [enterprise-patent.md](endpoints/18-enterprise-patent.md) | 专利 |\n| 19 | [enterprise-soft-right.md](endpoints/19-enterprise-soft-right.md) | 软件著作权 |\n| 20 | [enterprise-works-right.md](endpoints/20-enterprise-works-right.md) | 作品著作权 |\n| 21 | [enterprise-icp.md](endpoints/21-enterprise-icp.md) | 网站备案 |\n| 22 | [enterprise-change-info.md](endpoints/22-enterprise-change-info.md) | 变更记录 |\n| 23 | [enterprise-writ-agg.md](endpoints/23-enterprise-writ-agg.md) | 涉诉信息统计 |\n| 24 | [enterprise-writ-list.md](endpoints/24-enterprise-writ-list.md) | 涉诉文书 |\n| 25 | [enterprise-court-session-notice.md](endpoints/25-enterprise-court-session-notice.md) | 开庭公告 |\n| 26 | [enterprise-court-notice.md](endpoints/26-enterprise-court-notice.md) | 法院公告 |\n| 27 | [enterprise-executions.md](endpoints/27-enterprise-executions.md) | 失信被执行人 |\n| 28 | [enterprise-executed-person.md](endpoints/28-enterprise-executed-person.md) | 被执行人 |\n| 29 | [enterprise-frozen-equity.md](endpoints/29-enterprise-frozen-equity.md) | 股权冻结 |\n| 30 | [enterprise-punishment.md](endpoints/30-enterprise-punishment.md) | 行政处罚 |\n| 31 | [enterprise-pledge.md](endpoints/31-enterprise-pledge.md) | 股权出质 |\n| 32 | [enterprise-guaranty.md](endpoints/32-enterprise-guaranty.md) | 对外担保 |\n| 33 | [enterprise-abnormal-operation.md](endpoints/33-enterprise-abnormal-operation.md) | 经营异常 |\n| 34 | [enterprise-corporate-tax.md](endpoints/34-enterprise-corporate-tax.md) | 欠税公告 |\n| 35 | [enterprise-serious-illegal.md](endpoints/35-enterprise-serious-illegal.md) | 严重违法 |\n\n## 历史检索记录\n\n每次 API 调用的完整结果会自动归档到 `archive/` 目录。当用户提到\"之前查过什么\"时，AI 可以直接从归档中提取历史结果，无需重新调用 API。\n\n**按检索目的归类（`YD_PROJECT`）**：每个研究任务开始时，AI/用户设 `YD_PROJECT` 环境变量（如 `export YD_PROJECT=0713-商标在先使用权`，或行内 `YD_PROJECT=0713-商标案 scripts/yd-run search ...`），该任务的所有检索自动归到 `archive/<YD_PROJECT>/` 一个文件夹下，便于追溯。未设时按日期 `archive/YYYYMMDD/` 兜底，不再平铺根目录。**缓存查重全局生效**——同一问题在不同 project 下会命中已有归档，不重复消耗积分。\n\n`archive/<project>/<ts>_<query>.json` 是机器可读版（response/query/fingerprint/source_urls 全字段），同名 `.md` 是人类可读版（结构化报告），两者一一对应。同一份报告的副本会同步写入用户运行命令时的工作目录（`<CWD>/<ts>_<query>.md`），便于附卷；当 CWD 恰为 skill 根目录时自动跳过（避免污染 skill 目录）。\n\n浏览历史记录：\n\n```bash\nscripts/yd-run archive-list\nscripts/yd-run archive-list --keyword \"正当防卫\"\n```\n\n如果用户说\"之前查正当防卫的时候看到一个案例\"，AI 应先用 `archive-list --keyword \"正当防卫\"` 找到对应的归档文件，然后直接读取其中的 `response` 字段返回给用户。这不需要消耗积分。\n\n## 调试\n\n```bash\nscripts/yd-run raw /open/law_vector_search \"正当防卫\" --extra '{\"fatiao_filter\":{\"sxx\":[\"现行有效\"]}}'\n```\n\n## 法律检索报告（consolidate）\n\n多次检索之后，把 per-call 报告汇总成一份完整的法律检索报告。**这是律师/客户看的交付物**，per-call 报告是数据底稿。\n\n### 7 节\"结论先行\"标准结构\n\n**核心原则**：用户最想知道的是**最终结论**（能不能做、怎么做、风险在哪），法条和案例只是用来核实结论的支撑材料。所以结构应是 **结论先行 → 分析支撑 → 检索底稿垫后**。\n\n模板文件位于 `templates/legal-research-report.md`；`scripts/yd-run consolidate` 会按同一结构自动生成报告。\n\n1. **案情简介** — 当事人、争议焦点、当前阶段（最少必要）\n2. **检索目的与问题** — 本次检索要回答的法律问题（1-3 个核心 Q）\n3. **检索结论** ⭐ — **最先读到的内容**：\n   - 3.1 一句话定性（\"能做/不能做\" + 法律依据）\n   - 3.2 核心论点的判例支撑速查（用表格/列表，让用户 30 秒内 get 到）\n   - 3.3 风险点（诚实告知，不要只说好的）\n   - 3.4 后续行动（具体可执行的步骤）\n4. **分析与判断** — 抗辩应对、法条适用、诉讼请求结构、赔偿酌定、证据准备\n5. **检索思路与方法** — 关键词组合、筛选条件、检索顺序（备查）\n6. **检索结果** — 按 endpoint 分组：6.1 法律依据 / 6.2 司法案例 / 6.3 行政法规 / 6.4 其他（核实材料）\n7. **检索明细** — 表格，链接到每条 per-call 报告（末尾，使用可回溯本地链接）\n\n### 检索报告质量要求\n\n- **结论区必须能独立阅读**：3.1-3.4 应让律师、客户或法官先得到答案，再决定是否看底稿\n- **核心依据用表格速查**：不要让读者从几十条法条/案例中自行拼结论\n- **方法区保留检索痕迹**：写清关键词、筛选条件、平台、时间、纳入规则\n- **结果区只放支撑材料**：法条、案例、法规按类型分组，不替代第四节分析\n- **风险必须明示**：包括不利类案、法律适用分歧、地域差异、时效或证据缺口\n- **无法确认的信息标注待补充**：不要把检索不到或材料未提及的事实写成确定结论\n\n> **节号从 1 重新编号**（案情=1，结论=3，结果=6，明细=7），不沿用 1-6 顺序编号；体现\"结论在第 3 节\"的视觉位置。\n\n**反例**（曾出现过的旧版结构）：\n- 案情 → 目的 → 思路 → 检索结果 → 分析 → 结论\n- 用户反馈：检索结果（法条案例）全是\"核实材料\"，要翻到最后才看到结论 → 太累\n- 新版：结论放到第 3 节，用户看完 3.1-3.4 就能得到 80% 答案\n\n末尾附\"本次检索明细\"表格，链接到每条 per-call 报告。\n\n### 调用方式\n\n```bash\nscripts/yd-run consolidate \\\n    --title \"张某买卖合同违约金调整\" \\\n    --project \"case-2024-zhangsan\" \\\n    --case \"案情：...\" \\\n    --strategy \"检索思路：...\" \\\n    --analysis \"分析与判断：...\" \\\n    --conclusion \"一句话结论：...\" \\\n    --risks \"主要风险：...\" \\\n    --next-actions \"后续行动：...\" \\\n    --include \"违约金,高空抛物\"\n```\n\n- `--case` / `--strategy` / `--analysis` 必填：AI 显式传本次任务的案情/思路/判断\n- `--include` 必填：逗号分隔的查询子串，明确指定\"本次任务范围\"（不取最近 N 条）\n  - 匹配规则：CWD 中所有符合 `<8位时间戳>_<6位时间戳>_<查询>.md` 命名的 .md 文件，文件名包含任一子串即被纳入\n- `--project` 可选：项目子目录名。默认从 `--title` slugify（如 \"张某买卖合同违约金调整\" → \"张某买卖合同违约金调整\"）。用于 `archive/<project>/` 归类\n- `--title` / `--purpose` / `--conclusion` / `--risks` / `--next-actions` / `--output` 可选\n  - `--purpose` 不传则基于检索词自动生成\n  - `--conclusion` 强烈建议传入；不传会在 3.1 保留补写提示\n  - `--risks` / `--next-actions` 不传会保留补写提示\n  - `--output` 默认同时写 CWD 和 `archive/<project>/`；指定则只写到指定路径\n\n### 项目子目录组织\n\nconsolidate 会把这次任务的所有文件归类到 `archive/<project>/` 子目录：\n\n```\narchive/\n  case-2024-zhangsan/\n    20260610_192031_货款逾期违约金_司法实践.json   ← 从 archive/ 根目录移入\n    20260610_192031_货款逾期违约金_司法实践.md    ← 从 CWD 复制\n    20260610_192032_逾期付款_违约金_调整.json\n    20260610_192032_逾期付款_违约金_调整.md\n    20260610_192058_法律检索报告.md                ← 主交付物\n```\n\n- **.md 复制**（CWD 保留工作副本）：用户的工作目录不被破坏\n- **.json 移动**（archive 根目录已清理）：避免根目录重复积累，扁平区只放\"in-flight 暂存\"\n- 重复运行 consolidate 同一项目：idempotent，文件已在子目录则跳过\n\n### 与 per-call 报告的关系\n\n```\n多次 yd-run 检索（自动写 per-call .md 到 archive + CWD）\n       ↓\nAI 汇总判断后调 consolidate --project \"case-x\"\n       ↓\n创建 archive/case-x/，.md 复制进来，.json 移进来，法律检索报告写进去\n       ↓\nCWD 也有法律检索报告副本，per-call .md 仍在 CWD（工作副本）\n       ↓\n报告末尾的\"检索明细表\"链接回 archive/case-x/ 里的副本\n```\n\nper-call .md 是数据底稿，可独立查看；session 报告是主交付物，附案情/思路/判断；项目子目录是组织容器。\n\n## 目标目录归档规范（强制）\n\n目标目录（通常是案件文件夹 `02 - 案件分析` / `03 - 法律研究` 等）与 AI 进程的 CWD 是不同的两个位置。\n目标目录只允许出现：整合后的法律检索报告 + 外部素材 + 基于整合报告再生成的下游文件；\n**禁止** per-call 检索记录、检索明细 JSON、AI 进程 CWD 的工作副本。\n\n完整规则（标准工作流 4 步、反例、验证清单 4 条）见：\n\n[`references/03-report-consolidation.md`](references/03-report-consolidation.md#目标目录归档规范强制)\n\n## MCP 协同工作流（v1.6.0+）\n\n元典官方 MCP（https://open.chineselaw.com/mcp-config）已发布，3 个 servers：yuandian-law（法律法规）、yuandian-case（案例文书）、yuandian-company（企业信息）。本 skill 的价值现在转向\"**归档 + 法律检索报告生成**\"——数据接入由 MCP 负责，本 skill 负责沉淀。\n\n完整工作流（元典 MCP 接入配置、Agent 三步法、ingest 子命令、模式选型表）见：\n\n[`references/05-mcp-workflow.md`](references/05-mcp-workflow.md)\n\nFile v1.8.8:README.md\n\n# 元典法条与案例检索 (yuandian-law-search)\n\n通过 [元典开放平台](https://open.chineselaw.com) 检索中国法律法规条文和案例，为法律分析和研究提供数据支撑。\n\nv1.6.1 起，本 Skill 的核心交付能力从单次 API 包装扩展为\"检索归档 + 法律检索报告生成\"：多次检索后可用 `consolidate` 汇总为 7 节结论先行报告，适合律师内部复核、客户沟通和类案检索留痕。v1.7.4 修复关键词扩展的自动 OR 行为，并强化案件综合检索的语义优先策略。\n\n## 快速开始\n\n### 1. 获取 API Key\n\n访问 [open.chineselaw.com](https://open.chineselaw.com)，用手机号注册后在个人中心创建 API Key。每次调用消耗 10 积分，需在平台充值。\n\n### 2. 配置密钥\n\n将 API Key 填入 `scripts/.env`：\n\n```\nYD_API_KEY=sk-你的密钥\n```\n\n### 3. 执行检索\n\n```bash\nscripts/yd-run search \"正当防卫的限度\" --sxx 现行有效\n```\n\n`scripts/yd-run` 会用干净环境启动 Python，避免 Codex 进程环境、代理变量或 PATH 漂移影响元典接口访问。网络排查可先运行：\n\n```bash\nscripts/yd-run --network-check\n```\n\n### 4. 生成法律检索报告\n\n多次检索后，用 `consolidate` 生成主交付物。报告结构为：案情简介、检索目的与问题、检索结论、分析与判断、检索思路与方法、检索结果、检索明细。\n\n```bash\nscripts/yd-run consolidate \\\n  --title \"张某买卖合同违约金调整\" \\\n  --project \"case-2024-zhangsan\" \\\n  --case \"案情：...\" \\\n  --strategy \"检索思路：...\" \\\n  --analysis \"分析与判断：...\" \\\n  --conclusion \"一句话结论：...\" \\\n  --risks \"主要风险：...\" \\\n  --next-actions \"后续行动：...\" \\\n  --include \"违约金,逾期付款\"\n```\n\n## 设计理念：为什么这样设计这个 Skill\n\n### 背景\n\n元典开放平台提供 11 个 API 端点，覆盖法条、案例、法规、企业四个领域。**每次 API 调用消耗 10 积分**，这意味着一个\"检索 5 个案例并逐一查看详情\"的简单场景，实际消耗为 10 + 5×10 = 60 积分。\n\n因此，整个 Skill 的设计围绕一个核心问题：**如何在保证正确性的前提下，用最少的 API 调用完成任务？**\n\n### 原则一：正确性优先于积分节约\n\nAI 的记忆可能存在幻觉或过时。涉及法律条文的精确引用时，宁可多查一次，不可引用错误法条。\n\n**必须调用 API 的情况：**\n- 需要引用具体法条文号（AI 可能记错条文内容或条号对应）\n- 需要确认时效性（法律修订频繁，AI 训练数据可能已过时）\n- 用户明确要求检索\n- AI 对自身记忆不确定\n\n**可以不调用的情况：**\n- 纯概念解释（如\"什么是善意取得\"）\n- 对话中已检索过相同内容\n- 用户未要求查找\n\n### 原则二：三级接口分层\n\n不是所有接口都应该被同等对待。我们将 11 个端点分为三层：\n\n| 层级 | 接口 | 设计意图 |\n|------|------|----------|\n| **核心层**（5 个） | `search` · `keyword` · `detail` · `case` · `case-semantic` | 覆盖 90% 的日常法律检索需求，默认直接使用 |\n| **扩展层**（4 个） | `regulation` · `regulation-detail` · `case-detail` · `case --authority-only` | 非日常需求，调用前需告知用户额外积分消耗 |\n| **附属层**（2 个） | `enterprise` · `enterprise-detail` | 仅在用户明确要求企业信息时才使用 |\n\n这样设计是因为：法条语义检索（`search`）返回结果已包含法条全文，通常一次调用即可满足需求，无需再调 `detail`；而案例详情（`case-detail`）是额外消耗，必须让用户知情。\n\n### 原则三：语义检索优先\n\n每个领域提供语义和关键词两种检索模式，默认优先使用语义检索：\n\n| 模式 | 适用场景 | 典型返回量 |\n|------|----------|-----------|\n| **语义检索**（`search` / `case-semantic`） | 自然语言问题，不确定用什么关键词 | 45 条 |\n| **关键词检索**（`keyword` / `case`） | 明确关键词 + 需要精确筛选条件 | 10 条 |\n\n语义检索覆盖面更广，一次调用往往足够。只有当用户提供了明确关键词或需要日期/法院/级别等筛选条件时，才切换到关键词检索。\n\n### 原则四：本地缓存零成本\n\n脚本内置归档缓存机制：每次 API 调用的查询和响应会自动存入 `archive/` 目录，以 SHA-256 指纹匹配。相同查询自动命中缓存，**不消耗积分**。\n\n这意味着在同一个对话中多次讨论同一个法律问题时，只有第一次会产生积分消耗。\n\n### 六条积分节省策略\n\n这些策略写入了 SKILL.md，指导 AI 代理在调用时做出正确判断：\n\n1. **一查多用** — 一次检索结果充分引用，避免重复检索同一问题\n2. **优先语义检索** — `search` 返回最全面的结果，一次通常够用\n3. **避免法条链式调用** — 不要先 `search` 再逐条 `detail`，语义检索已含全文\n4. **案例详情谨慎调用** — 先用摘要筛选 1-2 个最相关案例，再调 `case-detail`\n5. **善用筛选参数** — `--sxx 现行有效`、`--effect1 法律` 等缩小范围，避免无效结果\n6. **信任归档缓存** — 相同查询自动命中本地归档，零积分消耗\n\n## 接口概览\n\n| 命令 | 用途 | 端点 | 层级 |\n|------|------|------|------|\n| `search` | 法条语义检索 | `/open/law_vector_search` | 核心 |\n| `keyword` | 法条关键词检索 | `/open/rh_ft_search` | 核心 |\n| `detail` | 法条详情 | `/open/rh_ft_detail` | 核心 |\n| `case` | 案例关键词检索 | `/open/rh_ptal_search` | 核心 |\n| `case --authority-only` | 权威案例检索 | `/open/rh_qwal_search` | 扩展 |\n| `case-semantic` | 案例语义检索 | `/open/case_vector_search` | 核心 |\n| `case-detail` | 案例详情 | `/open/rh_case_details` | 扩展 |\n| `regulation` | 法规关键词检索 | `/open/rh_fg_search` | 扩展 |\n| `regulation-detail` | 法规详情 | `/open/rh_fg_detail` | 扩展 |\n| `enterprise` | 企业名称检索 | `/open/rh_company_info` | 附属 |\n| `enterprise-detail` | 企业详情 | `/open/rh_company_detail` | 附属 |\n\n每个端点的完整参数说明和响应结构见 `endpoints/01~35-*.md`。\n\n## 版本演进\n\n| 版本 | 日期 | 关键变化 |\n|------|------|----------|\n| v0.1.0 | 2026-04-03 | 初始版本，封装 5 个 API 端点 |\n| v0.2.0 | 2026-04-05 | 改名 `yuandian-law-search`，MIT 许可证，新增注册引导 |\n| v1.0.0 | 2026-04-17 | **迁移至开放平台**，新增 6 个端点，引入归档缓存和三级分层 |\n| v1.1.0 | 2026-04-17 | 策略抽取至 `references/00-*.md`，核心理念调整为\"正确性优先\" |\n| v1.6.1 | 2026-06-15 | 优化 `consolidate` 法律检索报告模板为 7 节结论先行结构，新增模板文件和风险/后续行动参数 |\n| v1.7.0 | 2026-06-15 | 目录结构重构：35 个 API 文档迁入 `endpoints/`，`references/` 仅留工作流指南，新增 `templates/legal-research-report.md`；SKILL.md 由 809 行压到 494 行 |\n| v1.7.2 | 2026-06-15 | `references/` 6 个 `00-*.md` 改为 `01-06` 顺序编号；\"新接口策略矩阵\"小节去重话术（保留表格，去掉新/旧接口区分） |\n| v1.7.4 | 2026-06-15 | 修复 `--expand` 未能自动切换 OR 的脚本问题；强化案件综合/标杆类案检索的 `case-semantic` 优先、短关键词复检和零命中复检规则；同步版本与发布索引 |\n\nv1.0.0 是最重要的里程碑：API 从旧平台 `aiapi.ailaw.cn:8319` 整体迁移至开放平台 `open.chineselaw.com`，认证方式从 URL 参数改为 `X-API-Key` 请求头，同时新增了法规、案例详情、企业三大领域的端点。\n\n## 许可证\n\nMIT License — 详见 [LICENSE.txt](LICENSE.txt)。\n\n## 作者\n\n杨卫薪律师（微信 ywxlaw）\n\nFile v1.8.8:_meta.json\n\n{\n  \"ownerId\": \"kn7bn9h1qxa9ja48qkmaxtfjgx81ksex\",\n  \"slug\": \"yuandian-law-search\",\n  \"version\": \"1.8.8\",\n  \"publishedAt\": 1785937071237\n}\n\nFile v1.8.8:references/01-keyword-expansion.md\n\n## 关键词扩展与分阶段检索\n\n关键词检索默认是精确匹配，用户搜索\"刑事案件管辖权\"不会自动命中\"知识产权管辖权\"等相关概念。本节说明 AI 应如何主动扩展检索范围、分阶段提炼精准结果。\n\n### 关键词扩展原则\n\nAI 在执行关键词检索前，应先分析用户查询是否涉及可扩展的法律概念：\n\n1. **上位概念扩展**：将具体概念扩展到上位概念。例如\"商标侵权\"→ 同时检索\"知识产权侵权\"\n2. **并列概念扩展**：关联同一层级的平行概念。例如\"管辖权异议\"→ 同时考虑\"管辖权转移\"\"指定管辖\"\n3. **程序-实体关联**：从实体法关键词关联到程序法关键词。例如\"正当防卫\"→ 也关注\"防卫过当\"\"紧急避险\"\n\n### 扩展关键词工作流\n\n当 AI 判断用户查询涉及可扩展概念时，按以下流程操作：\n\n1. **识别核心关键词**：从用户查询中提取核心法律概念\n2. **生成扩展词列表**：基于上述原则，列出 2-5 个相关关键词\n3. **分阶段检索**：\n   - **第一阶段（广撒网）**：用核心关键词执行一次检索（使用 `--search-mode or` 扩大命中范围）\n   - **第二阶段（精提炼）**：根据第一阶段结果，提炼更精准的关键词组合再检索一次\n4. **结果合并与去重**：将两次检索结果合并，按相关性排序展示\n5. **扩展方向提示**：检索完成后，向用户建议可能相关的扩展检索方向\n\n### 脚本参数支持\n\n关键词检索、案例检索和法规检索新增 `--expand` 参数，用于一次性传入多个扩展关键词：\n\n```bash\n# 法条关键词扩展检索\nscripts/yd-run keyword \"刑事案件 管辖权\" --expand \"知识产权管辖,级别管辖,专门管辖\" --search-mode or\n\n# 案例关键词扩展检索\nscripts/yd-run case \"买卖合同 瑕疵担保\" --expand \"质量纠纷,违约责任\" --search-mode or\n\n# 法规关键词扩展检索\nscripts/yd-run regulation \"民法典 合同\" --expand \"买卖合同,租赁合同\" --search-mode or\n```\n\n`--expand` 参数的行为：\n- 将扩展关键词追加到原始查询中；未显式传入 `--search-mode` 时，自动使用 `or` 模式检索\n- 如果显式传入 `--search-mode and`，尊重用户指定，仍按 AND 模式检索\n- 等效于将原始关键词与扩展关键词用空格连接后以 OR 模式检索\n- 不带 `--expand` 时保持原有的精确匹配行为（默认 `and`）\n\n### 分阶段检索示例\n\n用户问：\"关于刑事案件管辖权有哪些规定？\"\n\n**第一阶段（广撒网）**：\n```bash\nscripts/yd-run keyword \"刑事案件 管辖权 级别管辖 地域管辖 专门管辖\" --search-mode or --sxx 现行有效\n```\n\n**分析第一阶段结果**：发现大量结果涉及\"级别管辖\"和\"地域管辖\"两个核心分支\n\n**第二阶段（精提炼）**：\n```bash\nscripts/yd-run keyword \"级别管辖 中级法院\" --search-mode and --sxx 现行有效\nscripts/yd-run keyword \"地域管辖 犯罪地\" --search-mode and --sxx 现行有效\n```\n\n### 扩展方向提示\n\n检索完成后，AI 应根据检索结果向用户建议相关的扩展方向。提示格式：\n\n```\n本次检索完成了对\"刑事案件管辖权\"的查询，消耗 XX 积分。\n\n💡 相关的扩展检索方向：\n1. 级别管辖 —— 中级/高级/最高法院的管辖分工\n2. 地域管辖 —— 犯罪地、被告人居住地的管辖规则\n3. 专门管辖 —— 军事法院、知识产权法院等专门管辖\n如需深入了解某个方向，请告诉我。\n```\n\n### 策略兼容性\n\n关键词扩展行为与三种检索策略的关系：\n\n| 策略 | 扩展行为 | 分阶段检索 | 积分控制 |\n|------|----------|-----------|----------|\n| **balanced** | AI 判断是否需要扩展，主动执行 | 可执行两阶段检索 | 第二阶段前告知用户将额外消耗积分 |\n| **economical** | 不主动扩展，仅用户要求时执行 | 不执行，一次检索完成 | 仅扩展时提示积分消耗 |\n| **aggressive** | 自动扩展所有相关概念，不等待确认 | 自动执行多阶段检索 | 不限制，追求最大覆盖面 |\n\nFile v1.8.8:references/02-typical-workflows.md\n\n## 典型工作流与用户引导\n\nAI 在完成检索后，应**主动告知用户检索结果摘要和积分消耗**，并根据场景推荐后续操作。\n\n### 法条研究场景\n\n用户问：\"关于股东出资瑕疵的法律规定有哪些？\"\n\n1. 先调 search 语义检索（10 积分），覆盖全部相关法条\n2. 展示摘要 + 关键条文引用 + 总积分\n3. 主动建议扩展方向（如\"公司法\"\"破产法\"）\n\n### 案例研究场景\n\n用户问：\"最近几年类似案件怎么判的？\"\n\n1. 调 case-semantic 语义检索（10 积分），覆盖近 5 年案例\n2. 展示相关度排序的案例摘要\n3. **不主动调 case-detail**，由用户选择感兴趣的案例后调详情\n4. 主动告知\"如需查看完整判决书请告知，每个案例 10 积分\"\n\n### 案件综合分析场景\n\n用户问：\"这个案件我们能不能主张 XX？\"\n\n1. 多轮检索：先 search 法条、再 case-semantic 案例、可能补 regulation 法规\n2. 汇总法条 + 案例 + 法规 + AI 分析判断\n3. 给出可执行的法律意见\n4. **总积分可能 30-50**，在最终回复开头明示\n\n**案例检索执行约束**：\n\n- 第一轮案例检索优先用 `case-semantic` 承接案情事实结构，不要把长事实描述直接丢给 `case` 关键词 AND 检索。\n- 只有在需要锁定若干高信息密度词时才补 `case`；关键词控制在 4-6 个，优先选择平台/行业行为词、交易链条词和责任焦点词。\n- `case` 默认是 AND 精确匹配；如果使用 `--expand` 扩展同义词、上位词或并列场景，未显式指定时脚本会自动切到 OR。\n- 一轮关键词检索零命中时，不要据此判断\"没有类案\"；应立即改用 `case-semantic` 或缩短关键词后 OR 复检。\n\n### 争议焦点识别优先场景（v1.6.1+ 强制前置步骤）\n\n**问题**：很多 AI 跳过\"识别用户原话里的争议焦点\"这一步，直接根据用户问题的\"法律概念包装\"展开检索（\"短视频带货\"\"电商平台\"\"间接侵权\"），结果命中大量\"被告自己动手\"的案型，与用户实际争议焦点偏差很大。\n\n**强制前置：争议焦点识别表**\n\n收到\"这个案件我们能不能主张 XX\"或类似案件综合分析请求时，**第一轮检索前**先在对话/笔记中明确以下 5 个字段，再据此生成检索词：\n\n| 字段 | 用户问题中提取 | 检索词应反映 |\n|------|--------------|-------------|\n| **行为主体** | 谁实施了侵权？（如\"达人\"/\"商家\"/\"平台\"） | 用具体主体词，不要用泛化的\"被告\" |\n| **角色定位** | 用户/原告的主张对象处于什么位置？（如\"被挂车商家\"vs\"自营商家\"） | 区分\"被关联\"和\"主动实施\"两种身份 |\n| **行为模式** | 侵权内容如何产生、传播、变现？（如\"达人发布→挂车→商家团购\"） | 用**行业术语**（挂车、探店、团购）而非法律术语 |\n| **抗辩点** | 被告可能怎么抗辩？（如\"视频非我发、我无法控制达人\"） | 围绕抗辩点搜\"法院如何回应\" |\n| **用户已明确的论点** | 用户主张的几个核心点是什么？ | **直接用用户原话作为检索词**（见下方\"红线\"） |\n\n**红线（重要）**：\n\n> **用户的争议焦点 ≠ 用户问题的法律概念包装**\n> **用户的争议焦点 = 用户原话里已经明确给出的几个核心论点**\n\n例：\n- 用户原话：\"视频是达人发的，不是被告发的，但挂在被告商品链接上。被告商品页能看到达人视频 → 被告有筛选过程。被告因此获利 → 反不正当竞争法兜底。\"\n- 用户已明确的论点 = [1] 视频非被告发布但挂被告商品链接；[2] 被告对视频有筛选过程；[3] 被告因此获利；[4] 反不正当竞争法兜底\n- v1 错搜：用\"短视频带货 电商平台 间接侵权\"（用户问题的法律概念包装）→ 偏差\n- v1 正搜：用\"视频不是商家发布 商家对达人视频有筛选过程 商家因视频获利 反不正当竞争法兜底\"（用户原话级别）→ 命中对位案\n\n**反例（曾发生过的偏差）**：\n\n> 用户问：\"达人发的短视频侵权了，挂到商家商品链接上，商家要负责吗？\"\n>\n> v1 错误：直接搜\"短视频带货 电商平台 间接侵权\" → 命中\"商家自己搬运/制作\"案例 → 全部跑偏\n>\n> v1 正确（如果当时识别到位）：用户已经明确 4 个信息——\n> ① 视频由达人发布（非被告）② 视频→挂车→被告商品 ③ 被告对视频有筛选过程 ④ 被告因此获利+反不正当竞争法兜底\n> 直接把这 4 个用户原话作为检索词，**第一轮**就能命中对位案。\n>\n> 不需要等\"检索后再提炼二分法\"——用户原话已经够具体了。\n\n**关键提示**：\n- **行业术语 > 法律术语**：用户说\"挂车\"就用\"挂车\"，不要说\"信息网络传播\"\n- **用户原话级别 > 法律概念包装**：用户原话里给的论点直接作为检索词\n- **抗辩点对称搜索**：被告可能怎么抗辩 → 搜\"法院如何否定该抗辩\" 的判例\n- **二分法是结果不是起点**：如果检索后才识别出二分法（如\"营销合作 vs 精选联盟\"），说明第一轮关键词就有问题——应该在第一轮就用更精确的词\n- **长事实结构走语义，短关键词走精确**：自然语言事实结构用 `case-semantic`；`case` 只放少量关键字，避免 6 个以上词的 AND 零命中。\n\n### 标杆案例对标检索场景（v1.6.1+ 强制流程）\n\n**问题**：用户第一轮就提供了标杆案例（如星云VR案、微信文章），但 v1 没把它作为\"对标模板\"去搜同类，导致错失场景最对位的案例。\n\n**强制流程**：\n\n1. **提取标杆案例的\"事实结构骨架\"**（5-7 个关键事实）\n   - 例：星云VR案 = {店主联系达人 + 多个探店账号发布 + 视频含侵权片段 + 视频挂团购链接 + 商家根据链接成交向达人结算佣金 + 商家未审核 + 法院判决商家赔偿}\n\n2. **把\"事实结构骨架\"作为查询模板**生成检索词\n   - 关键词版：`探店达人 + 团购链接 + 商家 + 营销合作 + 审查义务`\n   - 语义版（更优）：用一段自然语言描述这个事实结构\n\n3. **首选 case-semantic**（关键词检索对\"达人\"\"挂车\"识别差）\n   - 关键词检索易命中\"被告自己动手\"的偏差案例\n   - 语义检索对场景描述识别更好\n   - 如果补关键词检索，先用 4-6 个高密度词，例如 `短视频 推广 团购 商家 责任 著作权`\n   - 避免第一轮使用 `探店达人 团购链接 商家 著作权 责任`、`推广视频 挂车 商家 责任 审查 注意义务` 等长 AND 组合；这类组合容易因字面差异零命中\n\n4. **每轮命中后回检\"对标度\"**：命中案例的\"事实结构\"是否覆盖标杆案例的 5-7 个关键事实\n   - 覆盖 ≥ 5/7 → 高度对位，纳入\"主要类案\"\n   - 覆盖 3-4/7 → 一般类案，辅助参考\n   - 覆盖 ≤ 2/7 → 偏差案例，谨慎援引（可能论证方向不同）\n\n**反例（曾发生过的偏差）**：\n\n> 用户第一轮给了星云VR案（江苏高院公众号文章），明确场景是\"达人探店+挂团购+商家担责\"\n>\n> v1：忽略标杆案例，直接搜\"短视频带货 电商平台 间接侵权\" → 命中偏差案例\n>\n> v2 正确：把星云VR案的事实结构作为查询模板 → 命中 (2023)京0491民初5073 号等高度对位案\n\n### 法规全景场景\n\n用户问：\"数据安全相关的所有规定\"\n\n1. regulation 关键词检索（10 积分）+ 必要的 regulation-detail\n2. 展示法规清单 + 效力级别 + 关联法条\n3. 主动建议进一步细化方向\n\n### 企业风险排查场景\n\n用户问：\"这家公司有没有什么风险？\"\n\n1. enterprise-summary 快速总览（10 积分），识别风险分布\n2. 针对高风险项用 enterprise-list 深挖（如涉诉文书、失信被执行人、行政处罚）\n3. 汇总风险画像\n\n### AI 向用户反馈的原则\n\n1. **每次检索后主动说明积分消耗**：\"本次检索消耗 10 积分\"\n2. **多步检索时告知累计消耗**：\"本次检索消耗 10 积分（本次对话累计 30 积分）\"\n3. **完整判决书的触发取决于策略**：balanced/economical 由用户主动触发；aggressive 由 AI 自动获取最相关的 2-3 个\n4. **案例语义检索的摘要通常已够用**：只有用户明确要求查看完整判决书时才深入（aggressive 除外）\n5. **法条语义检索已含全文**：不需要额外补充\n6. **用自然语言与用户沟通**：不要向用户暴露命令行语法，AI 后台执行脚本即可\n7. **补充检索取决于策略**：balanced/economical 一次只用一种检索模式；aggressive 对重要问题自动同时运行语义+关键词检索，合并去重\n8. **检索报告 .md 自动落盘**：每次实际检索（cache miss 时）会同时落盘两份结构化 Markdown 报告：\n   - `archive/<ts>_<query>.md`：与 archive JSON 配对，技能内部归档，便于复盘\n   - `<CWD>/<ts>_<query>.md`：用户当前工作目录（AI 进程 CWD）副本，**仅供 AI 后台处理用，不应被复制到目标目录**\n   - 报告内容包含元信息（时间/接口/关键词/积分/原始数据路径/工作目录副本）+ 检索结果 + 引用来源\n   - footer 会输出报告路径，AI 应在对话中告知用户\n   - 默认双副本写入；可用 `--no-report` 完全跳过、`--no-cwd-report` 仅跳过工作目录副本\n   - **重要**：per-call 工作副本不是最终交付物，**禁止 AI 把它们复制到用户的案件文件夹等目标目录**（详见 `03-report-consolidation.md`）\n\nFile v1.8.8:references/03-report-consolidation.md\n\n## 法律检索报告（consolidate）\n\n多次检索之后，把 per-call 报告汇总成一份完整的法律检索报告。**这是律师/客户看的交付物**，per-call 报告是数据底稿。\n\n### 7 节\"结论先行\"标准结构\n\n报告骨架（7 节结构、设计动机、反例、节号逻辑）见：\n\n[`04-report-design-notes.md`](04-report-design-notes.md)\n\n调用 consolidate 时使用该骨架作为输出格式约定。\n\n### 调用方式\n\n```bash\nscripts/yd-run consolidate \\\n    --title \"张某买卖合同违约金调整\" \\\n    --project \"case-2024-zhangsan\" \\\n    --case \"案情：...\" \\\n    --strategy \"检索思路：...\" \\\n    --analysis \"分析与判断：...\" \\\n    --conclusion \"一句话结论：...\" \\\n    --risks \"主要风险：...\" \\\n    --next-actions \"后续行动：...\" \\\n    --include \"违约金,高空抛物\"\n```\n\n- `--case` / `--strategy` / `--analysis` 必填：AI 显式传本次任务的案情/思路/判断\n- `--include` 必填：逗号分隔的查询子串，明确指定\"本次任务范围\"（不取最近 N 条）\n  - 匹配规则：CWD 中所有符合 `<8位时间戳>_<6位时间戳>_<查询>.md` 命名的 .md 文件，文件名包含任一子串即被纳入\n- `--project` 可选：项目子目录名。默认从 `--title` slugify（如 \"张某买卖合同违约金调整\" → \"张某买卖合同违约金调整\"）。用于 `archive/<project>/` 归类\n- `--title` / `--purpose` / `--conclusion` / `--risks` / `--next-actions` / `--output` 可选\n  - `--purpose` 不传则基于检索词自动生成\n  - `--conclusion` 强烈建议传入；不传会在 3.1 保留补写提示\n  - `--risks` / `--next-actions` 不传会保留补写提示\n  - `--output` 默认同时写 CWD 和 `archive/<project>/`；指定则只写到指定路径\n\n### 项目子目录组织\n\nconsolidate 会把这次任务的所有文件归类到 `archive/<project>/` 子目录：\n\n```\narchive/\n  case-2024-zhangsan/\n    20260610_192031_货款逾期违约金_司法实践.json   ← 从 archive/ 根目录移入\n    20260610_192031_货款逾期违约金_司法实践.md    ← 从 CWD 复制\n    20260610_192032_逾期付款_违约金_调整.json\n    20260610_192032_逾期付款_违约金_调整.md\n    20260610_192058_法律检索报告.md                ← 主交付物\n```\n\n- **.md 复制**（CWD 保留工作副本）：用户的工作目录不被破坏\n- **.json 移动**（archive 根目录已清理）：避免根目录重复积累，扁平区只放\"in-flight 暂存\"\n- 重复运行 consolidate 同一项目：idempotent，文件已在子目录则跳过\n\n### 与 per-call 报告的关系\n\n```\n多次 yd-run 检索（自动写 per-call .md 到 archive + CWD）\n       ↓\nAI 汇总判断后调 consolidate --project \"case-x\"\n       ↓\n创建 archive/case-x/，.md 复制进来，.json 移进来，法律检索报告写进去\n       ↓\nCWD 也有法律检索报告副本，per-call .md 仍在 CWD（工作副本）\n       ↓\n报告末尾的\"检索明细表\"链接回 archive/case-x/ 里的副本\n```\n\nper-call .md 是数据底稿，可独立查看；session 报告是主交付物，附案情/思路/判断；项目子目录是组织容器。\n\n## 目标目录归档规范（强制）\n\n**用户的目标目录（通常是案件文件夹 `02 - 案件分析` / `03 - 法律研究` 等）≠ AI 进程的 CWD**。AI 进程运行 `scripts/yd-run` 时所在的 CWD 是临时工作区，**不是**用户的案件文件夹。\n\n### 目标目录只放什么\n\n目标目录（用户指定的文件夹）只允许出现以下文件：\n\n1. **整合后的法律检索报告**（`法律检索报告.md`，7 节标准结构）—— **唯一必需**\n2. **外部素材**：用户单独提供的微信文章、PDF、链接笔记等\n3. **基于整合报告再生成的下游文件**：证据清单、代理词大纲、抗辩应对清单、应诉策略等\n\n### 目标目录不允许出现\n\n- ❌ per-call 检索记录（`<ts>_<query>.md` × N 份）\n- ❌ 检索明细 JSON\n- ❌ 任何中间过程的临时文件\n- ❌ AI 进程 CWD 下的 per-call 工作副本\n\n### 标准工作流\n\n```\nStep 1：AI 在自己的 CWD 多次 yd-run 检索\n        → archive/<ts>_<query>.json + .md（skill 内部）\n        → <CWD>/<ts>_<query>.md（AI 进程工作副本，仅供 AI 读）\n\nStep 2：AI 汇总判断后，**手动**写一份整合报告到目标目录\n        → <用户目标目录>/<日期>_<主题>-法律检索报告.md\n\nStep 3：清理 AI 进程 CWD 下的 per-call 工作副本\n        → 不复制到目标目录\n        → 仍可在 archive/<ts>_<query>.md 留底\n\nStep 4：用户后续若要\"基于检索结果生成证据清单/代理词\"\n        → 读取整合报告（含检索明细表），生成新文件\n        → 新文件**也只放目标目录**，不污染 archive\n```\n\n### 反例（曾发生过的错误）\n\n```bash\n# ❌ 错误：把 8 份 per-call 工作副本复制到目标目录\ncp /Users/.../yuandian-law-search/20260615_163256_*.md \\\n   \"/案件文件夹/03 - 法律研究/\"\n# → 用户被迫手工清理，因为目标目录被检索底稿污染\n```\n\n正确做法：\n\n```bash\n# ✅ 正确：只把整合报告写到目标目录\n# 整合报告由 AI 在对话中直接 Write 到目标目录\n# per-call 工作副本留在 skill 内部 archive/\n```\n\n### 验证清单\n\nAI 完成法律检索任务后，自查：\n\n- [ ] 目标目录里**只有**整合报告 + 外部素材 + 下游生成文件\n- [ ] 目标目录里**没有** per-call `<ts>_<query>.md` × N\n- [ ] per-call 报告可在 `archive/` 里查到（不丢数据）\n- [ ] 整合报告末尾的\"检索明细表\"指向 `archive/` 路径（而非 CWD 路径）\n\nFile v1.8.8:references/04-report-design-notes.md\n\n## 法律检索报告 · 7 节设计原理（\"结论先行\"规约）\n\n> 本文件是 consolidate 报告生成的**格式约定 + 设计原理**，供 AI 在手动整合时遵循。\n> 注意：`templates/legal-research-report.md` 是可维护的模板参考；`yd_search.py` 当前用代码内 f-string 渲染。\n> 本文件描述的是**结构与设计动机**，与运行时具体格式解耦。\n\n### 设计原则\n\n- 用户最想知道最终结论 → 结论提前到第 3 节\n- 法条和案例只是核实材料 → 放到第 6 节\n- 节号从 1 重新编号（案情=1，结论=3，结果=6，明细=7），\n  体现\"结论在第 3 节\"的视觉位置\n\n### 反例（曾出现过的旧版结构，避免回退）\n\n- 案情 → 目的 → 思路 → 检索结果 → 分析 → 结论\n- 用户反馈：检索结果（法条案例）全是\"核实材料\"，要翻到最后才看到结论 → 太累\n- 新版：结论放到第 3 节，用户看完 3.1-3.4 就能得到 80% 答案\n\n### 7 节标准骨架\n\n#### 1. 案情简介\n\n当事人 / 争议焦点 / 当前阶段（最少必要）\n\n#### 2. 检索目的与问题\n\n本次检索要回答的法律问题（1-3 个核心 Q）\n\n#### 3. 检索结论 ⭐\n\n**用户最先读到的内容**：\n\n- 3.1 一句话定性（\"能做/不能做\" + 法律依据）\n- 3.2 核心论点的判例支撑速查（表格，30 秒内 get）\n- 3.3 风险点（诚实告知，不要只说好的）\n- 3.4 后续行动（具体可执行的步骤）\n\n#### 4. 分析与判断\n\n抗辩应对 / 法条适用 / 诉讼请求结构 / 赔偿酌定 / 证据准备\n\n#### 5. 检索思路与方法\n\n关键词组合 / 筛选条件 / 检索顺序（备查）\n\n#### 6. 检索结果（按 endpoint 分组）\n\n- 6.1 法律依据\n- 6.2 司法案例\n- 6.3 行政法规\n- 6.4 其他（核实材料）\n\n#### 7. 检索明细\n\n表格，链接到每条 per-call 报告（末尾）\n\n### 质量要求\n\n- 结论区必须能独立阅读：3.1-3.4 应先回答问题，再引导读者看底稿\n- 核心依据用表格速查：避免把法条和案例堆给读者自行归纳\n- 方法区保留检索痕迹：写清关键词、筛选条件、平台、时间、纳入规则\n- 结果区只放支撑材料：法条、案例、法规按类型分组，不替代第四节分析\n- 风险必须明示：包括不利类案、法律适用分歧、地域差异、时效或证据缺口\n\nFile v1.8.8:references/05-mcp-workflow.md\n\n## MCP 协同工作流（v1.6.0+）\n\n元典已发布官方 MCP（https://open.chineselaw.com/mcp-config），3 个 servers：yuandian-law（法律法规）、yuandian-case（案例文书）、yuandian-company（企业信息）。本 skill 的价值现在转向\"**归档 + 法律检索报告生成**\"——数据接入由 MCP 负责，本 skill 负责沉淀。\n\n### 接入元典 MCP\n\n模板在 `scripts/.mcp.json.example`（与 `scripts/.env.example` 同目录）。把它复制为客户端能识别位置的 `.mcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"yuandian-law\":    { \"url\": \"https://open.chineselaw.com/mcp/law/stream\",    \"headers\": {\"Authorization\": \"Bearer ${YD_API_KEY}\"} },\n    \"yuandian-case\":   { \"url\": \"https://open.chineselaw.com/mcp/case/stream\",   \"headers\": {\"Authorization\": \"Bearer ${YD_API_KEY}\"} },\n    \"yuandian-company\":{ \"url\": \"https://open.chineselaw.com/mcp/company/stream\",\"headers\": {\"Authorization\": \"Bearer ${YD_API_KEY}\"} }\n  }\n}\n```\n\n设置环境变量后重启客户端，agent 即可自动获得 `mcp__yuandian_law__*`、`mcp__yuandian_case__*`、`mcp__yuandian_company__*` 工具。\n\n### AI Agent 三步工作流\n\n```\nStep 1: 调 MCP 拿数据（agent 直接调，不经 yd-run）\n  mcp__yuandian_law__yuandian_law_vector_search(\"违约金\", sxx=\"现行有效\")\n  → 拿到 API 响应 JSON\n\nStep 2: 喂给 yd-run ingest 归档 + 生成 .md\n  echo \"<上一步的 JSON>\" | yd-run ingest \\\n      --query \"违约金 调整\" \\\n      --endpoint \"/open/law_vector_search\"\n  → archive/<ts>_违约金_调整.json + .md（同直接 API 模式）\n  → CWD/<ts>_违约金_调整.md 工作副本\n\nStep 3: 多次 ingest 后，调 yd-run consolidate 生成法律检索报告\n  yd-run consolidate --project \"case-2024-xxx\" \\\n      --case \"...\" --strategy \"...\" --analysis \"...\" \\\n      --conclusion \"一句话结论：...\" \\\n      --risks \"主要风险：...\" \\\n      --next-actions \"后续行动：...\" \\\n      --include \"违约金\"\n  → archive/case-2024-xxx/ 项目包 + 7 节结论先行报告（详见 templates/legal-research-report.md）\n```\n\n### ingest 子命令详细\n\n```bash\n# 方式 1: 文件输入\nyd-run ingest --query \"<Q>\" --endpoint \"/open/<E>\" --input <file.json>\n\n# 方式 2: stdin pipe（agent 友好）\ncat result.json | yd-run ingest --query \"<Q>\" --endpoint \"/open/<E>\"\n\n# 必填\n#   --query:     用于生成文件名 + 元信息\n#   --endpoint:  对应 API 路径，用于 routing 到 formatter（见 INGEST_ROUTING）\n# 可选\n#   --cost:        成本标签（默认 \"10 积分\"）\n#   --no-report:   跳过 .md 报告生成\n#   --no-cwd-report: 跳过 CWD 副本\n```\n\n`--endpoint` 取值见 INGEST_ROUTING 路由表（36 个 endpoint 全部覆盖，包括元典 MCP 暴露的全部 24 个数据 tools）。\n\n### 何时用哪种模式\n\n| 场景 | 推荐模式 |\n|---|---|\n| agent 调 mcp__yuandian__* | 走 MCP + yd-run ingest（v1.6.0 推荐）|\n| 客户端没装 MCP / 单次脚本 | 走 yd-run search/case/... 直接 API（v1.5.x 兼容）|\n| 调试 / 看 raw JSON | 走 yd-run raw |\n\n两种模式产出完全一致（archive/ 格式、.md 元信息、consolidate 路由），可混用。\n\nFile v1.8.8:references/06-enterprise-portrait.md\n\n## 企业全息画像\n\n### 12. 企业检索（轻量候选列表，enterprise-search）\n\n**每次调用消耗 1 积分**。按名称检索企业，返回候选列表（仅含 ID、名称、信用代码），用于定位目标企业后调用其他企业接口。\n\n```bash\nscripts/yd-run enterprise-search \"华为\" --top-k 5\n```\n\n### 13. 企业基本信息（enterprise-base）\n\n根据企业 ID 或统一社会信用代码获取企业完整信息（含股东、核心成员、分支机构等）。\n\n```bash\nscripts/yd-run enterprise-base --uscc \"9144030071526726XG\"\n```\n\n### 14. 企业聚合总览（enterprise-summary）\n\n一次调用获取企业各维度数据的统计摘要。\n\n```bash\nscripts/yd-run enterprise-summary --id \"企业ID\"\n```\n\n### 15. 企业分项列表（enterprise-list）\n\n查询企业各维度详细记录，支持分页。**每次调用消耗 5-10 积分**（涉诉统计和涉诉文书 10 积分，其余 5 积分）。\n\n```bash\n# 查询企业涉诉文书\nscripts/yd-run enterprise-list --type writ-list --uscc \"9144030071526726XG\"\n\n# 查询企业对外投资\nscripts/yd-run enterprise-list --type invest --uscc \"9144030071526726XG\" --page 1 --size 10\n\n# 查询企业商标\nscripts/yd-run enterprise-list --type brand --uscc \"9144030071526726XG\"\n```\n\n#### 可用类型\n\n| TYPE | 名称 | 积分 |\n|------|------|------|\n| invest | 对外投资 | 5 |\n| brand | 商标 | 5 |\n| patent | 专利 | 5 |\n| soft-right | 软件著作权 | 5 |\n| works-right | 作品著作权 | 5 |\n| icp | 网站备案 | 5 |\n| change-info | 变更记录 | 5 |\n| writ-agg | 涉诉信息统计 | 10 |\n| writ-list | 涉诉文书 | 10 |\n| court-session | 开庭公告 | 5 |\n| court-notice | 法院公告 | 5 |\n| execution | 失信被执行人 | 5 |\n| executed-person | 被执行人 | 5 |\n| frozen-equity | 股权冻结 | 5 |\n| punishment | 行政处罚 | 5 |\n| pledge | 股权出质 | 5 |\n| guaranty | 对外担保 | 5 |\n| abnormal | 经营异常 | 5 |\n| tax | 欠税公告 | 5 |\n| serious-illegal | 严重违法 | 5 |\n\nFile v1.8.8:references/07-research-middleware.md\n\n# 检索机制感知型法律研究中间层（执行合同）\n\n> 本 reference 落地 [DEC-006]：把 Skill 从\"元典 API/MCP 包装 + 归档 + 报告\"升级为\"检索机制感知型法律研究中间层\"。\n> 案件检索（综合检索 / 类案对标 / 已有报告复盘）**默认走本主流程**；简单法条或案号检索（`detail` / `case-detail`）不启动本流程。\n> 评测定位见 [DEC-007]：本文定义的是**第 1 层「检索方案评测」**的产物——可在不调用元典接口时完整产出。\n\n## 1. 与既有约定的关系\n\n- v1.6.1+ 已有的「5 字段争点识别表」（见 [`02-typical-workflows.md`](02-typical-workflows.md) 场景 4：行为主体 / 角色定位 / 行为模式 / 抗辩点 / 用户已明确的论点）是本流程 `research_brief` 的**子集**，不重复执行。\n- 本流程把争点识别扩展为：`research_brief`（检索简报）→ `propositions`（检索命题）→ `query_matrix`（查询矩阵）→ 对位复核。\n- 关键词扩展三原则（[`01-keyword-expansion.md`](01-keyword-expansion.md)）仍适用，但降级为查询矩阵**内部**的一条改写手段，不再是案件检索的默认主路径（[DEC-006] pt 5）。\n\n## 2. 执行合同（调用任何检索接口前必须完成）\n\n案件检索必须按以下顺序推进；任一步信息不足时按 §6 前置门禁处理，不得跳步直接调用接口。\n\n```\n① 轻量案件研判 ─► research_brief\n② 由 brief 派生 ─► propositions（正向支持 + 反向排除）\n③ 由 propositions 派生 ─► query_matrix（一争点一查询，单一接口）\n④ 小样本试检（1-2 条命题先验证接口与表达是否有效）\n⑤ 对位复核（HIGH / MEDIUM / LOW / MISMATCH）─► 策略修正\n⑥ 正式检索 ─► 结论—依据—查询可追溯报告\n```\n\n> 简单检索（用户给出明确法条名+条号、或明确案号、或问\"XX 法怎么规定\"且无案件事实）走 [`SKILL.md` 接口速查](../SKILL.md#接口速查)即可，**不启动本流程**。判定边界见 §7。\n\n## 3. research_brief（检索简报）schema\n\n| 字段 | 类型 | 必填 | 说明 |\n|---|---|---|---|\n| `research_goal` | string | 是 | 本次研究要回答的法律问题（用户真正要求裁判/判断的命题，不是案由复述） |\n| `party_stance` | object | 是 | 当事人立场：`role`（原告/被告/被申请人/代理人…）+ `claim_or_defense`（核心诉求或抗辩） |\n| `procedure_stage` | string | 否 | 程序阶段（一审/二审/再审/仲裁/执行/诉前） |\n| `dispute_focus` | string[] | 是 | 争议焦点：用户原话里已明确的核心论点（来自 5 字段表的\"用户已明确论点\"） |\n| `claim_or_defense_path` | string[] | 是 | 请求权/抗辩路径——由本案事实推导，用于区分主题相近但请求权基础不同的近邻案型（不预设特定法律领域） |\n| `legal_elements` | object[] | 是 | 法律要件：`element`（要件名）+ `source`（法源线索，待检索验证）+ `covered`（brief 是否已覆盖该要件的事实）。`covered` **不是装饰字段**：`covered=false` 的要件必须落入 `facts_to_supplement` 并标注是否阻断路径，驱动补问/假设继续——若全员 `covered=true` 却仍要检索，说明要件拆解流于形式 |\n| `decisive_facts` | string[] | 是 | 决定性事实（must_match）：检索简报和查询表达必须覆盖的事实 |\n| `background_facts` | string[] | 否 | 背景事实（影响裁判尺度但不决定争点定性） |\n| `facts_to_supplement` | object[] | 否 | 待补事实：`fact` + `blocks_path`（是否改变检索路径）+ `action`（补问/标注假设继续） |\n| `must_exclude_neighbor_types` | string[] | 是 | 必须排除的近邻案型（must_not_match），见 §8 |\n| `key_decisive_facts` | string[] | 否（建议） | `decisive_facts` 的**置顶短摘要**（3-5 条精简版），放在 brief 顶部便于人/judge 快速复核，不得与 `decisive_facts` 矛盾 |\n| `key_exclusions` | string[] | 否（建议） | `must_exclude_neighbor_types` 的**置顶短摘要**，同上 |\n| `role_comparison_matrix` | object | 否（仅同主题多角色场景） | 多主体角色对比矩阵，见 §3.1 |\n| `prior_report_sources` | object | 否 | 已有法律分析报告（见 §3.2），无则留空 |\n| `platform_coverage_note` | string | 否 | 若案件领域超出平台主要覆盖（如行政诉讼），标注哪些法源覆盖不足，见 §9.2 |\n\n**硬约束**：`dispute_focus`、`decisive_facts`、`must_exclude_neighbor_types` 三项不得为空；任一为空说明案件研判未完成，退回 §6 前置门禁。\n\n### 3.1 scan-friendly 摘要与多角色对比矩阵\n\n- **置顶摘要**：`key_decisive_facts` 与 `key_exclusions` 是 `decisive_facts` / `must_exclude_neighbor_types` 的精简镜像，放在 brief 顶部，让复核者（人或自动 judge）无需翻查嵌套字段即可定位关键事实与近邻排除。底层详细字段仍是权威来源；摘要不得与之矛盾，也不得只写摘要而省略底层字段。目的：避免 dense 结构化输出被快速浏览时漏看关键排除项。\n- **多角色对比矩阵**：当一个案件含 2+ 主体角色且请求权基础不同，除为每个角色产出独立的 propositions/queries 外，还应输出 `role_comparison_matrix` 汇总差异：\n\n  ```json\n  {\n    \"axes\": [\"主体角色\", \"请求权基础/规范\", \"决定性事实\", \"必须排除的近邻\"],\n    \"rows\": [\n      {\"role\": \"主体角色 A\", \"claim_basis\": \"（该角色的请求权基础/规范，由本案推导）\", \"decisive_facts\": [\"...\"], \"exclusions\": [\"...\"]},\n      {\"role\": \"主体角色 B\", \"claim_basis\": \"（与 A 不同的请求权基础/规范）\", \"decisive_facts\": [\"...\"], \"exclusions\": [\"...\"]}\n    ]\n  }\n  ```\n  矩阵是汇总视图，**不替代**各角色的独立 query_matrix（一争点一查询仍按角色分别落）。\n\n### 3.2 已有法律分析报告（`prior_report_sources`）\n\n输入含既有法律分析报告时，`prior_report_sources` 必须拆成**三栏**，把\"事实/结论/假设\"分层（反 inflation 关键防线）：\n\n| 子字段 | 含义 | 处置 |\n|---|---|---|\n| `report_facts` | string[] | 报告**援引的、可定位来源的客观事实**（报告中有出处、可回查的事实陈述）。可作检索线索直接使用 |\n| `report_conclusions` | string[] | 报告的**法律结论/定性**（报告作者的主观判断）。**必须降级为待验证假设**，不得当已证事实写入 `decisive_facts` |\n| `hypotheses_to_verify` | object[] | 由结论转化的、必须独立检索验证的判断：`hypothesis` + `verifies_conclusion`（关联 report_conclusions）+ `proposition_id`（对应验证命题） |\n\n**法源 vs 法律判断的区分**（易错点）：\n\n- 报告**援引的法源**（具体法条名称+条号，属客观引用）→ 可直接作 `queries[].filters`（`--yyft`）或法条检索线索，**无需降级**。\n- 报告**作者的法律评价/定性**（对要件是否成立、是否构成某行为的判断）→ 属主观判断，**必须降级为 `hypotheses_to_verify`**，配独立验证命题。\n\n**硬约束**：不得因报告存在而跳过 §2 轻量研判；每条 `report_conclusions` 都应有对应 `hypotheses_to_verify` 条目；报告结论不得直接出现在 `decisive_facts`（那是 must_match 事实位）。\n\n## 4. propositions（检索命题）schema\n\n每个命题只验证**一项**可被法条或案例支持/否定的判断。\n\n| 字段 | 取值 |\n|---|---|\n| `id` | `P-NN` |\n| `statement` | 单一判断陈述（\"……构成/不构成……\"\"……要件需要/不需要……\"） |\n| `type` | `normative`（规范命题：法条如何规定）/ `fact-structure`（事实结构命题：此类事实是否落入该规范）/ `adjudication-rule`（裁判规则命题：裁判者如何认定）/ `reverse`（反向命题：对方抗辩或不利类案的裁判路径） |\n| `direction` | `support`（支持我方立场）/ `oppose`（对方抗辩、不利类案、否定要件） |\n| `importance` | `decisive`（决定争点定性）/ `supportive`（影响尺度或佐证） |\n| `parent_element` | 关联的 `legal_elements[].element` 或 `dispute_focus` |\n\n**正反向必生成**：每个 decisive 争点至少生成 1 条 `support` + 1 条 `reverse` 命题（[DEC-006] pt 3）。反向命题是\"近邻陷阱\"的主要防线——它显式表达\"什么情况下我方命题不成立\"，对应到查询就是排除条件。\n\n## 5. query_matrix（查询矩阵）schema\n\n| 字段 | 说明 |\n|---|---|\n| `id` | `Q-NN` |\n| `proposition_id` | 承载的单一命题（`P-NN`） |\n| `interface` | `search` / `keyword` / `detail` / `case` / `case-semantic` / `regulation` / `case-detail` |\n| `routing_rationale` | 为何选此接口（基于接口的真实匹配机制，见 §9） |\n| `query_field` | 主查询字段（自然语言问题 / 关键词组合 / 结构化字段） |\n| `query_expression` | 实际查询表达 |\n| `filters` | 筛选条件（`--sxx`/`--effect1`/`--province`/`--jarq-*`/`--ay`/`--yyft` 等） |\n| `allow_rewrite` | 是否允许后端改写（向量接口默认 true；关键词接口不适用） |\n| `expected_hit` | 预期命中类型（法源/类案/裁判规则） |\n| `exclusion_criteria` | 排除标准（来自 `must_exclude_neighbor_types`，对应反向命题） |\n| `fallback_path` | 零命中或低对位时的降级路径（换接口 / 缩短关键词 / 切 OR / 换语义 / 超平台领域 fallback 外部渠道，见 §9.2） |\n\n**一争点多小查询**（[DEC-006] pt 4，硬约束）：\n\n- 每个 `query` 只承载**一个争点 + 一组决定性事实**。\n- `case` / `keyword` 接口的后端只支持**全局 AND/OR**，**不得**把多个争点或一长串事实压成嵌套布尔串。\n- 一个争点通常对应 2-4 条 query（不同接口、不同方向、正反各一），而不是 1 条巨查询。\n- `--expand` 全局 OR 仅作为单条 query **内部**的改写手段保留兼容，不再作为案件检索主路径。\n\n## 6. 检索前门禁（pre-door gate）\n\n信息不足时按\"最小必要\"处理，不得空跑查询，也不得一次性追问十几个问题：\n\n| 情形 | 处理 |\n|---|---|\n| 事实不足但**不影响查询方向**（如赔偿具体数额未定） | 在 brief 标注假设继续，不影响命题与查询生成 |\n| 主体 / 行为链条 / 待解决问题缺失到**会改变检索路径** | 只补问会改变检索路径的最关键问题（**最多 3 个核心**，通常含\"合同/法律关系类型+违约形态\"或\"当事人角色\"），其余标注假设继续 |\n| 完全无法判断争点（用户只说\"帮我查相关案例\"） | 触发最小补问：合同/法律关系类型 + 诉求方向；不补问不生成 query_matrix |\n| 明确法条名+条号 / 明确案号 / 纯概念问答 | **不启动本流程**，直接走接口速查 |\n\n补问结果回填 brief 后再继续；补问不超过 **1 轮**——**1 轮 = 1 次交互回合**（不限制该回合内问几个，但单回合最多 3 个会改变检索路径的核心问题），**不得套用 5 字段争点识别表的全字段逐一追问**（那是案件研判输入表，不是补问清单）；仍不足则按假设推进并标注 `待补充`。\n\n## 7. 何时不启动本流程（边界）\n\n- 用户给出明确法条名 + 条号 → `detail`。\n- 用户给出明确案号 → `case-detail --ah`。\n- 用户问\"XX 法怎么规定的\"且无案件事实 → `search`。\n- 用户问\"关于 XX 的法律条文\" → `keyword`。\n- 以上属\"简单检索\"，直接走 [`SKILL.md` 接口速查](../SKILL.md#接口速查)，不产出 research_brief。\n\n只要用户描述了事实结构、争议焦点、诉讼立场，或问\"类似案件怎么判\"\"能不能主张 XX\"\"对方抗辩怎么办\"——即触发本流程。\n\n## 8. 近邻案型排除（must_not_match）\n\n近邻陷阱 = 主题、案由或行业相近，但**主体角色、行为链条或决定性事实**不同，混入会污染主要依据。brief 必须在查询前显式写出 `must_exclude_neighbor_types`（由本案事实推导，**不预设特定法律领域的清单**），并映射到对应 query 的 `exclusion_criteria`。\n\n识别方向（非穷举，按本案事实判断，不列举具体案型）：\n\n- **请求权基础不同**：主题相近但落入不同规范路径（主体身份 / 客体 / 行为要件不同），各路径要件不能互替。\n- **主体角色不同**：同一主题下行为主体身份不同，导致责任路径或注意义务标准不同。\n- **行为链条/决定性事实不同**：主题或行业相近，但关键事实缺失或不同，不能直接类推。\n\n**`must_exclude_neighbor_types` 写法**：每项写**一个独立近邻案型**（不合并多项），并表述具体到\"为什么排除\"（缺哪个要件 / 主体 / 事实），便于复核；`key_exclusions` 置顶摘要同样逐项独立。\n\n对位复核时，命中近邻案型应标 `LOW` 或 `MISMATCH`，不得纳入主要依据。\n\n## 9. 接口路由规则（按机制，不按\"统一搜索\"抽象）\n\n基于已知后端能力（完整审计见 Task-002，本节为当前已知能力的路由）：\n\n| 检索目标 | 首选接口 | 理由 |\n|---|---|---|\n| 规范发现（\"XX 的法律规定\"） | `search`（法条向量） | 语义匹配，广覆盖概念关联 |\n| 精确核法（已知法条名+条号） | `detail` | 直接定位，无歧义 |\n| 关键词精确 + 效力/日期筛选 | `keyword` | 字面 AND/OR + 结构化过滤 |\n| 事实结构类案（\"类似案件怎么判\"） | `case-semantic`（案例向量） | 长事实结构语义匹配，关键词会丢事实 |\n| 裁判用语 / 援引法条 / 案由复检 | `case`（结构化字段） | `--ay`/`--fxgc`/`--yyft`/`--jbdw` 精确过滤 |\n| 标杆案例对标 | 先 `case-semantic`（事实骨架），再 `case` 结构化复检 | 见 [`02-typical-workflows.md`](02-typical-workflows.md) 场景 5 |\n\n**硬约束**：\n\n- `case` 关键词默认放 4-6 个高信息密度词，不构造后端无法表达的长 AND（[DEC-002]、[DEC-006] pt 4）。\n- `case` 一轮零命中 ≠ \"无类案\"：立即切 `case-semantic` 或缩短关键词换 OR 复检（[DEC-002]）。\n- 后端 `score`/`_score` 只在**同一接口同一查询内部**作排序信号，不跨查询、不跨接口、不替代法律对位度。\n\n### 9.1 字段归属接口速查表（防 filter 误挂）\n\nfilter 必须挂在**真正支持它**的接口上，否则会被忽略或报错（实测 worker 易把案例语义字段误挂到案例关键词）。下表以 `scripts/yd_search.py` 源码为权威（`case` 子命令定义见源码 `add_parser(\"case\")`，`case-semantic` 见 `add_parser(\"case-semantic\")`）：\n\n| filter | `case` 关键词 | `case-semantic` | `search`/`keyword` 法条 |\n|---|:---:|:---:|:---:|\n| `--ay`/`--fxgc`/`--yyft`/`--jbdw`/`--ah`/`--ajlb`/`--title` | ✓ | ✗ | ✗ |\n| `--wenshu-type`/`--fayuan` | ✗ | ✓ | ✗ |\n| `--wszl` | ✓ | ✓ | ✗ |\n| `--cj`（法院层级） | ✗ | ✓ | ✗ |\n| `--jarq-start`/`--jarq-end`（结案日期） | ✓ | ✓ | ✗ |\n| `--sxx`/`--effect1`/`--fgmc`（法条时效/效力/法规名称） | ✗ | ✗ | ✓ |\n| `--province`/`--xzqh-p` | ✓ | ✓ | ✗ |\n| `--authority-only` | ✓ | ✓ | ✗ |\n\n易错点提醒：\n\n- **`--wenshu-type`（案件类型，如民事案件）属于 `case-semantic`**，不要挂到 `case` 关键词（`case` 用 `--ajlb` 表达案件类别，无 `--wenshu-type`）。\n- **`--ay`/`--fxgc`/`--yyft`（案由/分析过程/援引法条）属于 `case` 关键词**，`case-semantic` 不支持——想用这些结构化字段精确复检就切到 `case`。\n- **`--jarq-start/end` 两个案例接口都支持**（源码确认），可放心用于日期范围。\n- 法条接口（`search`/`keyword`）的 `--sxx`/`--effect1` 不得挪到案例接口。\n\n**硬校验**：用 `scripts/validate-query-filters.py <research-plan.json>` 自动校验 filter×interface 合法性（退出码 0 合法 / 1 有违规，可接 CI 或 pre-commit hook）。单条 query 可用 `--query '{\"interface\":\"case\",\"filters\":{...}}'`。字段表与本节一致，以 `yd_search.py` 各 subparser 为权威。\n\n### 9.2 平台覆盖边界意识\n\n元典开放平台法源以**民商事 / 刑事**为主，案例库含民事 / 刑事 / 行政案件分类（`--wenshu-type`）。但**部分领域的法源覆盖可能有限**：行政诉讼法 / 行政处罚法 / 行政复议法、市场监督管理等部门规章、国家赔偿、部分专项法规等。案件检索时若本案主要落入这些领域，必须**显式标注平台边界**，不得用民商事法源 / 案例强行替代（避免误导）：\n\n- 在 brief 顶层标注 `platform_coverage_note`：说明哪些法源 / 案例元典可能覆盖不足（如\"《行政诉讼法》/ 处罚程序规章覆盖可能有限\"）。\n- 相关 query 的 `fallback_path` 指明替代渠道：先试 `detail` 接口按法条名查（元典若收录），未命中则提示用户需外部专门检索（如国家法律法规数据库 flk.npc.gov.cn、北大法宝、中国裁判文书网）。\n- 案例侧仍可用 `case-semantic` / `case --wenshu-type 行政案件` 查行政案例（元典案例库有该分类），但**法条层面**的行政法覆盖需单独验证，不要假设与民商法同等完整。\n- 该字段是**对用户透明的边界声明**，不是跳过检索的借口——能查的仍照常查，查不到的如实标注并给替代渠道。\n\n> 该意识由评测 R6 发现并固化：worker 在行政诉讼场景自发产出 `platform_coverage_note` + fallback，被 judge 评为\"通用方法的高阶工具边界意识\"。\n\n## 10. 策略与法律检索解耦（[DEC-006] pt 6）\n\n`economical` / `balanced` / `aggressive` 只控制**调用预算与深度**（试几条 query、是否自动跑语义+关键词双检索、是否自动拉 case-detail），**不得**改变：\n\n- 争点识别与要件拆解；\n- 接口路由与字段适配；\n- 对位度门槛（HIGH/MEDIUM/LOW/MISMATCH）；\n- 反向检索与近邻排除。\n\n## 11. 对位度标签（结果复核）\n\n| 标签 | 含义 |\n|---|---|\n| `HIGH` | 法律问题相同，主体关系、行为链条、决定性事实基本覆盖，可作主要类案/主要法源 |\n| `MEDIUM` | 法律问题相同，但缺一项决定性事实或程序背景不同，仅作辅助 |\n| `LOW` | 仅主题/行业/案由相近，不能直接支撑核心结论 |\n| `MISMATCH` | 争点、主体角色、行为模式或裁判命题不同，应排除 |\n\n首轮结果按此标签复核；只有诊断出偏差原因（接口误选 / 表达不适配 / 近邻混入）后，才允许扩展查询或换接口。\n\n## 12. 机器可读导出骨架（Task-004 预留）\n\n为支持 Agent Eval Lab 与人工复盘，案件检索建议导出以下结构（字段稳定，不绑定特定评测平台格式）：\n\n```json\n{\n  \"research_brief\": { /* §3 字段 */ },\n  \"propositions\": [ /* §4 */ ],\n  \"queries\": [ /* §5 */ ],\n  \"results\": [\n    { \"result_id\": \"\", \"backend_score\": null, \"relevance_label\": \"HIGH|MEDIUM|LOW|MISMATCH\",\n      \"include\": true, \"reason\": \"\" }\n  ],\n  \"conclusion_links\": [\n    { \"conclusion\": \"\", \"proposition_id\": \"\", \"query_id\": \"\", \"result_ids\": [] }\n  ],\n  \"run_meta\": { \"skill_version\": \"\", \"strategy_version\": \"\", \"model\": \"\", \"live\": false, \"credits\": 0 }\n}\n```\n\n脱敏要求：导出对象不得包含未脱敏案件全文、API Key 或 live 响应原文；冻结响应的版本策略见 Task-004。\n\nFile v1.8.8:scripts/MANIFEST.json\n\n{\n  \"version\": \"1.7.5\",\n  \"files\": [\n    \"SKILL.md\",\n    \"README.md\",\n    \"CHANGELOG.md\",\n    \"templates/legal-research-report.md\",\n    \"scripts/yd-run\",\n    \"scripts/yd_search.py\",\n    \"scripts/updater.py\",\n    \"scripts/.env.example\",\n    \"references/06-enterprise-portrait.md\",\n    \"references/01-keyword-expansion.md\",\n    \"references/05-mcp-workflow.md\",\n    \"references/04-report-design-notes.md\",\n    \"references/03-report-consolidation.md\",\n    \"references/02-typical-workflows.md\",\n    \"endpoints/01-law-vector-search.md\",\n    \"endpoints/02-law-keyword-search.md\",\n    \"endpoints/03-law-detail.md\",\n    \"endpoints/04-case-semantic-search.md\",\n    \"endpoints/05-case-keyword-search.md\",\n    \"endpoints/06-case-keyword-search-authority.md\",\n    \"endpoints/07-case-detail.md\",\n    \"endpoints/08-regulation-search.md\",\n    \"endpoints/09-regulation-detail.md\",\n    \"endpoints/10-enterprise-search.md\",\n    \"endpoints/11-enterprise-detail.md\",\n    \"endpoints/12-hall-detect.md\",\n    \"endpoints/13-enterprise-search-lightweight.md\",\n    \"endpoints/14-enterprise-base-info.md\",\n    \"endpoints/15-enterprise-aggregation-summary.md\",\n    \"endpoints/16-enterprise-out-invest.md\",\n    \"endpoints/17-enterprise-brand.md\",\n    \"endpoints/18-enterprise-patent.md\",\n    \"endpoints/19-enterprise-soft-right.md\",\n    \"endpoints/20-enterprise-works-right.md\",\n    \"endpoints/21-enterprise-icp.md\",\n    \"endpoints/22-enterprise-change-info.md\",\n    \"endpoints/23-enterprise-writ-agg.md\",\n    \"endpoints/24-enterprise-writ-list.md\",\n    \"endpoints/25-enterprise-court-session-notice.md\",\n    \"endpoints/26-enterprise-court-notice.md\",\n    \"endpoints/27-enterprise-executions.md\",\n    \"endpoints/28-enterprise-executed-person.md\",\n    \"endpoints/29-enterprise-frozen-equity.md\",\n    \"endpoints/30-enterprise-punishment.md\",\n    \"endpoints/31-enterprise-pledge.md\",\n    \"endpoints/32-enterprise-guaranty.md\",\n    \"endpoints/33-enterprise-abnormal-operation.md\",\n    \"endpoints/34-enterprise-corporate-tax.md\",\n    \"endpoints/35-enterprise-serious-illegal.md\",\n    \"endpoints/MANIFEST.json\"\n  ]\n}\n\nFile v1.8.8:CHANGELOG.md\n\n# 变更日志\n\n## [1.8.8] - 2026-08-05\n\n### 修复\n\n- `validate-query-filters.py` 动态自省 `exec_module` 改为默认关闭（静态扫描器误判为动态代码执行 Critical）：默认使用 `_HARDCODED` 硬编码字段表，仅设 `YD_VALIDATE_DYNAMIC=1` 时才动态加载 `yd_search.py` 自省。功能不变，消除 `suspicious.dynamic_code_execution` 命中\n- SKILL.md 检测示例占位符写法调整，避免静态扫描器误判 `suspicious.exposed_secret_literal`\n\n### 说明\n\n纯文档与校验脚本改动，不影响检索/归档/接口功能。企业信息与幻觉检测接口保持不变。\n\n## [1.8.7] - 2026-08-05\n\n### 文档完善\n\n- README 删除已废弃的「自更新机制」章节（自更新代码此前已移除，消除供应链审计项）\n- SKILL.md 新增「数据留存与隐私警示」：明示 archive 落盘、CWD 报告副本、外部传输至 open.chineselaw.com、敏感内容最小化建议\n- SKILL.md 新增「所需权限」：网络/文件读写/环境变量/本地执行范围声明\n\n### 说明\n\n纯文档改动，不影响脚本与接口功能。企业信息与幻觉检测接口保持不变。\n\n## [1.8.6] - 2026-08-02\n\n### 新增（references/07，评测 R6 发现回写）\n\n- **§9.2 平台覆盖边界意识**：元典法源以民商/刑事为主，行政诉讼/部门规章/国家赔偿等覆盖可能有限。案件落入这些领域时，brief 标注 `platform_coverage_note` + 相关 query 的 `fallback_path` 指明外部渠道（flk.npc.gov.cn / 北大法宝 / 裁判文书网），不得用民商法源强行替代。源自评测 R6（worker 自发产出该意识，Claude judge 评为「通用方法的高阶工具边界意识」）。\n- §5 `fallback_path` 字段补充「超平台领域 fallback 外部渠道」选项。\n\n纯文档，不影响脚本/接口。\n\n## [1.8.5] - 2026-08-02\n\n### 改进（references/07 通用化 + 补通用方法）\n\n按「skill 是通用法律检索方法论、不固化特定领域案例」原则（用户反馈），清理具体案型举例 + 补通用方法。纯文档，不影响脚本/接口。\n\n**补通用方法**：\n\n- §3.2 新增「已有法律分析报告」三栏规则：`prior_report_sources` 拆为 `report_facts` / `report_conclusions` / `hypotheses_to_verify`；区分「报告援引的法源」（客观引用，不降级）vs「报告作者的法律判断」（主观，必降级为待验证假设）。\n- §6 明确「1 轮 = 1 次交互回合，单回合最多 3 个会改变检索路径的核心问题」，不得套用 5 字段争点识别表全字段追问。\n- §3 `legal_elements.covered` 用法：`covered=false` 要件必须落 `facts_to_supplement`，非装饰字段。\n- §8 `must_exclude_neighbor_types` 写法：每项一个独立近邻 + 表述排除理由。\n- §3 `prior_report_sources` 指向修正（见 §3.2，原误指 §5 query_matrix）。\n\n**通用化（删特定法律领域举例）**：\n\n- §8 删典型近邻清单（原列商业秘密/竞业、商业诋毁/名誉权、达人/商家、高管/员工等具体案型），改为通用识别方向（请求权基础不同 / 主体角色不同 / 行为链条或决定性事实不同）。\n- §3.1 `role_comparison_matrix` 示例从「高管/普通员工」泛化为「主体角色 A/B」占位。\n- §3 / §3.2 删具体举例（客户名单、特定法条号等），改为通用描述。\n\n## [1.8.4] - 2026-08-02\n\n### 新增\n\n- **`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 误挂）的工程闭环。\n\n## [1.8.3] - 2026-08-02\n\n### 移除\n\n- **移除内置自动更新机制**：删除 `scripts/updater.py`（SkillUpdater，334 行）、`yd_search.py` 中每次检索自动联网检测远程版本的触发逻辑、`check-update` / `do-update` 子命令，以及 `SKILL.md` 的「版本更新」段。原机制每次检索时联网检测新版（≥7 天一次）且 `do-update` 会联网下载覆盖本地文件——移除以消除自动联网与文件覆盖的风险。更新改由 `git pull` / `clawhub-sync` 等外部通道处理。\n- 清理死代码：`yd_search.py` 中无任何引用的 `CURRENT_VERSION = \"1.7.5\"` 常量。\n\n## [1.8.2] - 2026-08-02\n\n### 新特性 — 检索机制感知型法律研究中间层（DEC-006 / Task-001）\n\n把 Skill 从\"元典 API/MCP 包装 + 归档 + 报告\"升级为\"检索机制感知型法律研究中间层\"：案件检索（综合检索 / 类案对标 / 已有报告复盘）默认先完成\"理解案件 — 形成命题 — 查询矩阵 — 对位复核\"，再调用接口。\n\n- 新增 [`references/07-research-middleware.md`](references/07-research-middleware.md)：\n  - `research_brief` schema：争点 / 要件 / 决定性事实 / 待补事实 / 必须排除的近邻案型 / 已有报告来源，外加 `key_decisive_facts` 与 `key_exclusions` 两个**置顶短摘要**（便于快速复核）。\n  - `propositions` schema：每条单一判断，区分规范 / 事实结构 / 裁判规则 / 反向；每个 decisive 争点至少 1 条正向 + 1 条反向。\n  - `query_matrix` schema：一争点一查询、单一接口；带 `exclusion_criteria` 与零命中 `fallback_path`；`case` 关键词不构造后端无法表达的长 AND。\n  - 多主体角色案件 `role_comparison_matrix`（如高管竞业禁止 vs 普通员工保密义务）。\n  - **已有法律分析报告使用规则**：区分 `report_facts` / `report_conclusions` / `hypotheses_to_verify` 三栏，把报告结论降级为待验证假设，不跳过轻量研判。\n  - 前置门禁（最小必要补问，最多 1 轮）、近邻案型排除清单、HIGH/MEDIUM/LOW/MISMATCH 对位度标签、机器可读导出骨架。\n  - §9 接口路由按真实后端机制选择 + **§9.1 字段归属接口速查表**（防 filter 误挂，以 `scripts/yd_search.py` 源码为权威）。\n- `SKILL.md` 新增精简\"检索机制感知主流程（案件检索默认）\"6 步段，详细 schema 放入单层 reference（主文档不膨胀）；简单法条 / 案号 / 纯概念检索仍直接走接口速查，**不启动本流程**。\n- `--expand` 全局 OR 行为保留兼容，仅降级为查询矩阵内部的一条改写手段（不再作案件检索默认主路径）。\n\n### 评测（agent-eval-lab，`evals/yuandian-middleware-260802`）\n\n- candidate 97 vs baseline 82.75（6 场景无 API 检索规划盲评）。\n- 跨家族 3 judge（glm-5.2 / DeepSeek-V3.2 / Qwen3.5-35B）：2/3 判 candidate 胜；case-03「已有报告三栏区分」三家一致 candidate pass / baseline fail。\n- worker n=2：关键结构决策 100% 可复现。\n- 接口路由教义经 `yd_search.py` 源码验证一致（含确认 `case-semantic` 支持 `--jarq-start/end`）。\n\n## [1.7.5] - 2026-07-20\n\n### 新特性\n\n- **归档按检索目的分文件夹**：新增 `YD_PROJECT` 环境变量，AI/用户在研究任务开始时设定（如 `export YD_PROJECT=0713-商标在先使用权`），该任务所有检索自动归到 `archive/<project>/` 一个文件夹，便于追溯；未设时按日期 `archive/YYYYMMDD/` 兜底，不再平铺根目录。**缓存查重全局跨 project 生效**（`_archive_lookup` 改 `rglob`），同一问题在不同任务命中已有归档、不重复消耗积分。`archive-list` 输出带 project 相对路径、按时间倒序。\n- **默认剔除办案无关条目（五类效力级别）**：`search` / `keyword` / `regulation` 默认过滤 `effect1 ∈ {行业/团体规范, 地方律协规定, 行政机关工作文件, 党内法规, 军事法规规章}`（律协指引、课题公告/答复函、党纪规定、军队规定等——非法律渊源或与一般民商事/刑事办案无关）。基于 archive 实测样本定位字段特征；footer 提示剔除数量，涉党纪/涉军等特殊案件加 `--keep-industry` 保留。`archive/` 原始数据完整保留。\n\n### 修复\n\n- 修复 skill 根目录堆积检索副本问题：`_archive_write_report` 写 CWD 副本前判断 `cwd == SKILL_ROOT`，相等则跳过（主归档仍在 `archive/`，不丢数据）。根因是 `yd-run` 捕获的 `YD_USER_CWD` 若等于 skill 根，副本直接堆根目录。\n- 清理 skill 根目录 22 个历史检索副本 `.md`（`archive/` 内均有同名备份，逐个 diff 一致）。\n- 新增 skill 根 `.gitignore`，兜底忽略检索副本文件名模式，防止未来污染 git status。\n\n## [1.7.4] - 2026-06-15\n\n### 修复\n\n- 修复 `keyword` / `case` / `regulation` 的 `--expand` 自动 OR 逻辑：参数解析层不再把 `--search-mode` 默认填成 `and`，处理函数可正确识别\"用户未显式指定\"并在扩展检索时切换为 OR。\n- 修复 `references/03-report-consolidation.md` 与 `references/02-typical-workflows.md` 中重命名后的旧文件链接。\n- 统一版本号：`SKILL.md`、`scripts/yd_search.py`、`scripts/MANIFEST.json`、根 `README.md` 与 marketplace 条目同步到 `1.7.4`。\n\n### 改进\n\n- 强化案件综合分析和标杆类案场景的检索执行约束：第一轮优先 `case-semantic`，关键词检索只保留 4-6 个高信息密度词，零命中时必须改用语义检索或 OR 复检。\n- 补充 marketplace 条目，便于插件市场按当前版本发现和分发 `yuandian-law-search`。\n- 调整 `.gitignore` 例外，使本技能的 `DECISIONS.md` 与 `TASKS.md` 可纳入版本控制。\n\n## [1.7.3] - 2026-06-15\n\n### 修正（v1.7.1 反思有误）\n\n- v1.7.1 在\"争议焦点识别\"小节中错误地将二分法归入\"用户原始争议焦点\"——二分法实际是 AI **检索之后**才提炼出来的分析工具，不是用户最初提问的内容\n- 真实情况：用户最初就已明确给出关键事实要素和法条抓手，**第一轮**应该直接用这些用户原话作为检索词，不需要先等\"检索后再提炼二分法\"\n- **修正 `references/02-typical-workflows.md`**：\n  - 删除\"关键区分点\"字段（避免诱导 AI 自己去找二分法）\n  - 新增\"用户已明确的论点\"字段（强调直接用用户原话作检索词）\n  - 关键提示新增\"二分法是结果不是起点\"\n- 路径修正：因 v1.7.2 重命名 `00-typical-workflows.md` → `02-typical-workflows.md`，编辑目标相应更新\n\n## [1.7.2] - 2026-06-15\n\n### 整理\n- **`references/` 序号重编**：6 个 `00-*.md` 工作流指南改为 `01-06` 顺序编号（按 SKILL.md Reference 文档索引的引用顺序），便于按序阅读和稳定排序\n  - `01-keyword-expansion.md`（基础：关键词怎么扩）\n  - `02-typical-workflows.md`（应用：典型场景）\n  - `03-report-consolidation.md`（专题：报告整合）\n  - `04-report-design-notes.md`（专题：报告设计原理）\n  - `05-mcp-workflow.md`（专题：MCP 协同）\n  - `06-enterprise-portrait.md`（专题：企业全息画像）\n  - 同步更新 `SKILL.md`、`scripts/MANIFEST.json` 中所有引用\n\n### 简化\n- **\"新接口策略矩阵\"小节去重话术**：`SKILL.md` 调用策略章节尾部表格本身保留（hall-detect / enterprise-search / enterprise-base+summary / enterprise-list 四个接口在三种策略下的具体行为），仅去掉\"新/旧接口\"区分话术——所有接口统一视为同一层级，按其分层套用对应策略\n\n## [1.7.1] - 2026-06-15\n\n### 工作流补充（基于近期案件检索偏差复盘）\n\n- **`references/00-typical-workflows.md` 新增 2 节强制工作流**：\n  - **争议焦点识别优先场景**：第一轮检索前必须先填 5 字段识别表（行为主体 / 角色定位 / 行为模式 / 关键区分点 / 抗辩点），避免直接按泛化法律概念展开检索\n  - **标杆案例对标检索场景**：用户第一轮提供标杆案例时，必须提取其\"事实结构骨架\"作为查询模板，并用\"对标度评分\"过滤命中案例\n- **核心理念沉淀**：\n  - 行业术语 > 法律术语（用户用什么行业说法就用什么行业说法作检索词，不要预先翻译成法律术语）\n  - 二分法思维：争议焦点背后往往有关键二分，二分点决定结论方向\n  - 主动找反面案例：搜完正面后专门搜一次\"被告不担责\"\"被告无过错\"等反面表述，反面案例能反向锚定争议焦点的关键区分\n- **典型反例**：错搜泛化法律概念 → 命中与案情不匹配的偏差案型；正搜基于用户原话 + 行业术语描述事实结构（语义检索）→ 命中对位案\n\n## [1.7.0] - 2026-06-15\n\n### 重构\n- **目录结构重构**（按 skill-lint 审查建议解耦）：\n  - 35 个 API 端点文档（`01-law-vector-search.md` ~ `35-enterprise-serious-illegal.md`）从 `references/` 迁入新建的 `endpoints/`\n  - `references/MANIFEST.json` 同步迁入 `endpoints/MANIFEST.json`\n  - `references/` 仅保留工作流指南，新增 6 个 `00-*.md`：\n    - `00-keyword-expansion.md` — 关键词扩展三原则、`--expand` 参数、分阶段检索、策略兼容性\n    - `00-typical-workflows.md` — 五大场景 + AI 向用户反馈的 8 条原则\n    - `00-enterprise-portrait.md` — 企业信息类 4 个接口（`enterprise-search` / `base` / `summary` / `list`）的完整用法与 20 类 `--type` 维度\n    - `00-report-consolidation.md` — consolidate 调用方式、项目子目录组织、目标目录归档规范\n    - `00-report-design-notes.md` — 7 节\"结论先行\"的设计动机、反例、节号逻辑、质量要求\n    - `00-mcp-workflow.md` — 元典 MCP 接入配置、Agent 三步法、ingest 子命令、模式选型表\n- `templates/legal-research-report.md` 保留并明确为可维护的模板参考（`yd_search.py` 当前仍用代码内 f-string 渲染，模板作为格式约定）\n- SKILL.md 由 809 行压到 494 行（-39%）：4 个大章节（关键词扩展、典型工作流、企业全息、MCP 协同）拆到 references/，7 节报告与目标目录归档保留短引用\n\n### 发布治理\n- `scripts/MANIFEST.json` 同步升到 1.7.0，完整覆盖 endpoints/ + references/ + templates/ 全部文件（之前仅列了 11 个 references，updater 实际未更新 12-35）\n- README.md 中 `references/01~11-*.md` 改为 `endpoints/01~35-*.md`，`MANIFEST.txt` 改为 `MANIFEST.json`\n- \"版本演进\"表格新增 v1.7.0 行\n\n## [1.6.1] - 2026-06-15\n\n### 改进\n- 优化 `consolidate` 法律检索报告模板：从旧的\"检索结果在前、结论在后\"调整为 7 节结论先行结构，先呈现一句话定性、核心依据速查、风险与后续行动，再展示分析、方法、检索结果和明细。\n- 新增 `templates/legal-research-report.md`，沉淀可维护的法律检索报告模板，便于后续单独调整报告结构。\n- `consolidate` 报告头新增检索主体、检索平台、项目包等可核查信息；第七节检索明细改用可回溯本地链接。\n- `consolidate` 新增 `--risks` 和 `--next-actions` 参数，用于填充结论区的风险与后续行动；`--conclusion` 未传时保留明确补写提示。\n\n### 修复\n- 修复 `consolidate` 将 per-call JSON 移入项目子目录后，后续分组读取仍指向旧路径，导致法律依据/案例/法规分组可能丢失的问题。\n\n### 文档完善\n- SKILL.md 同步更新 7 节报告结构、质量要求、调用方式和目标目录归档口径。\n\n## [1.6.0] - 2026-06-11\n\n### 战略转向\n- 元典官方已发布 MCP（https://open.chineselaw.com/mcp-config），3 个 servers：yuandian-law / yuandian-case / yuandian-company\n- 本 skill 价值从\"API 包装\"转向\"**归档 + 法律检索报告生成**\"——agent 用 MCP 调数据，本 skill 负责沉淀\n- v1.6.0 起，本 skill 同时支持两种调用模式：\n  1. **直接 API 模式**（原有 `search/case/...` 子命令，保留兼容）\n  2. **MCP 协同模式**（新增 `ingest` 子命令，消费 MCP 输出 JSON）\n\n### 新增\n- **`ingest` 子命令**（v1.6.0 核心）：\n  - 用法：`yd-run ingest --query \"<Q>\" --endpoint \"/open/<E>\" --input <file.json>`（或 stdin pipe）\n  - 必填：`--query`、`--endpoint`\n  - 可选：`--cost`（默认 \"10 积分\"）、`--no-report`、`--no-cwd-report`\n  - 消费外部 JSON（来自 MCP 或其他源），路由到对应 formatter，**走与直接 API 相同的归档 + .md 流程**\n  - 归档记录额外加 `\"ingest\": true` 标记，便于区分数据来源\n- **`INGEST_ROUTING` 表**（36 个 endpoint 覆盖）：\n  - 法条 4 个（law_vector_search / rh_ft_search / rh_ft_detail + 1）\n  - 法规 2 个（rh_fg_search / rh_fg_detail）\n  - 案例 4 个（case_vector_search / rh_ptal_search / rh_qwal_search / rh_case_details）\n  - 企业主接口 4 个（rh_enterpriseSearch / rh_company_info / rh_company_detail / rh_enterpriseBaseInfo）\n  - 企业分项列表 21 个（OutInvest/Brand/Patent/SoftRight/WorksRight/Icp/ChangeInfo/WritAgg/WritList/CourtSessionNotice/CourtNotice/Executions/ExecutedPerson/FrozenEquity/Punishment/Pledge/Guaranty/AbnormalOperation/CorporateTax/SeriousIllegal/AnnualReport）\n  - 特殊 2 个（hall_detect 用对应 formatter；rh_enterpriseAggregationSummary 用 raw JSON 包装）\n  - 未知 endpoint 走 raw JSON 兜底（包装为 ```json ... ``` 代码块）\n- **`.mcp.json.example` 模板**（skill 根目录）：\n  - 3 个 yuandian-* MCP servers 配置（law/case/company）\n  - `Authorization: Bearer ${YD_API_KEY}` 鉴权\n  - 用户复制为 `.mcp.json` 后让 Claude Code / Cursor / Codex 等客户端自动加载\n- **企业分项列表 endpoint 自动 label 推断**（如 `/open/rh_enterpriseOutInvest` → \"对外投资\"），无需 --label 参数\n\n### 改进\n- SKILL.md 新增\"MCP 协同工作流\"章节，描述 agent 如何同时使用 `mcp__yuandian__*` 工具 + `yd-run ingest` + `yd-run consolidate`\n- INGEST_ROUTING 路由表覆盖元典 MCP 暴露的全部 24 个数据 tools（不含 2 个 meta tools）\n\n### 架构关系\n```\nagent 调用流程:\n1. mcp__yuandian_law__yuandian_law_vector_search(\"违约金\")  ← MCP 直接调元典\n2. 把响应 JSON 喂给 yd-run ingest                             ← 本 skill 归档\n3. 多次 ingest 后, yd-run consolidate --project \"...\"        ← 生成 6 节法律检索报告\n```\n\n向后兼容：原有 `search/case/detail/...` 直接 API 子命令完全保留，YD_API_KEY 用户可继续用。\n\n## [1.5.1] - 2026-06-10\n\n### 新增\n- **consolidate 项目子目录组织**（用户反馈：一次研究任务会产生多个 .json + .md，平铺在 archive/ 不便按项目查找）\n  - 新增 `--project \"<name>\"` 参数（可选，默认从 `--title` 自动 slugify）\n  - consolidate 创建 `archive/<project>/` 子目录作为\"项目包\"\n  - per-call .md 从 CWD **复制**到项目子目录（CWD 保留工作副本）\n  - per-call .json 从 `archive/` 根目录**移动**到项目子目录（archive 根保持清爽，不重复）\n  - 法律检索报告双写：`archive/<project>/<ts>_法律检索报告.md`（项目包）+ CWD（工作副本）\n  - 报告末尾\"项目包\"标识：`> 项目包：archive/<project>/`\n  - 重复运行 consolidate 同一项目：idempotent，文件已在子目录则跳过移动/复制\n\n### 改进\n- consolidate 报告头增加项目包路径引用，方便用户定位\n\n## [1.5.0] - 2026-06-10\n\n### 新增\n- **session-level 法律检索报告**（`consolidate` 子命令）：把多次检索的 per-call 报告汇总成一份标准结构的法律检索报告\n  - 调用方显式传 `--case` / `--strategy` / `--analysis` 三个核心字段（AI 填）\n  - `--include` 必填，逗号分隔的查询子串，明确指定\"本次任务范围\"（不取最近 N 条）\n  - 6 节标准结构：案情简介 / 检索目的与问题 / 检索思路与方法 / 检索结果（4.1 法条 + 4.2 案例 + 4.3 法规 + 4.4 其他，按 endpoint 自动分组）/ 分析与判断 / 检索结论\n  - 附录\"本次检索明细\"表格：时间/检索词/接口/积分/[md](CWD相对路径)·[json](file://绝对路径)\n  - 4.4 其他：自动收纳未归类到法律/案例/法规的检索（如 hall-detect、enterprise-*）\n  - `--purpose` 可选：不传则基于检索词自动推断\n  - `--conclusion` 可选：不传则提示\"详见第五节\"\n  - `--output` 可选：默认 `<cwd>/<ts>_法律检索报告.md`\n\n### 改进\n- per-call .md 报告元信息移除\"检索接口\"字段（用户反馈：API 端点太技术化，不属于报告内容）\n\n### 架构关系\n- per-call .md = 检索明细（数据底稿，每次检索自动写 archive + CWD）\n- session 报告 = 主交付物（法律检索报告，按任务粒度由 AI 触发 consolidate 生成）\n- session 报告的\"检索明细表\"链接到 per-call .md，整套形成完整溯源链\n\n## [1.4.0] - 2026-06-10\n\n### 新增\n- 检索报告 .md 自动落盘：每次实际检索（cache miss 时）落盘两份结构化 Markdown 报告\n  - `archive/<ts>_<query>.md`：与 archive JSON 配对，技能内部归档\n  - `<CWD>/<ts>_<query>.md`：用户运行命令时的工作目录副本，方便附卷/分享\n- 报告模板：元信息（时间/接口/关键词/积分/原始数据路径/工作目录副本）+ 检索结果（与 stdout 一致）+ 引用来源（按类型分组）+ 数据来源声明\n- 复用现有 5 个 formatter（format_law_results / format_case_results / format_regulation_results / format_enterprise_results / format_hall_detect_results）填充\"检索结果\"段，零行为变化\n- 新增 `--no-report` 全局 flag：跳过 .md 报告生成（archive + CWD），仅写 archive JSON\n- 新增 `--no-cwd-report` 全局 flag：仅跳过 CWD 副本，仍写 archive/ 报告\n- 调用结束后 footer 追加报告路径提示（archive + CWD，CWD 失败时不显示第二行）\n- CWD 副本写入失败时 stderr 警告但不中断（archive 副本是主落点，best-effort 容错）\n\n### 改进\n- `api_post` / `api_get` 返回值从 2-tuple 改为 3-tuple `(result, cached, archive_path)`，让 cmd_* 能拿到 archive 路径以驱动报告生成\n- 5 个有自定义成本的端点（hall-detect 50、enterprise-search 1、enterprise-base 10、enterprise-summary 10、enterprise-list 5/10）准确把成本传递到报告元信息头\n\n## [1.3.4] - 2026-05-27\n\n### 新增\n- 新增 `scripts/yd-run` 干净环境运行入口，默认清理 Codex/代理相关环境变量后再调用 `yd_search.py`。\n- 新增 `scripts/yd-run --network-check` 网络预检，用于无积分消耗地检查 `open.chineselaw.com` 和 `ydzk.chineselaw.com` 的 DNS 与 TLS 连通性。\n\n### 文档完善\n- SKILL.md 和 README.md 改为推荐使用 `scripts/yd-run`，降低 Codex 网络沙箱、PATH 漂移和代理环境变量对元典检索的影响。\n\n## [1.3.3] - 2026-05-13\n\n### 新增\n- archive 归档记录新增 `source_urls` 字段：自动提取/构造法条、案例、法规、企业的来源链接，方便后续检索时提供核实出处\n- `backfill-urls` 子命令：一次性回填现有 archive 的 source_urls（已回填 36 个文件）\n\n### 改进\n- 法条语义检索（law_vector_search）和案例语义检索（case_vector_search）等无 URL 的接口，根据 fgid/scid 自动构造完整链接\n- 法条详情（rh_ft_detail）、案例关键词（rh_ptal_search）等返回相对 URL 的接口，归档时自动转为完整 URL\n\n## [1.3.2] - 2026-05-10\n\n### 新增\n- 新接口策略矩阵：为 hall-detect、enterprise-search、enterprise-base/summary、enterprise-list 四类新增接口补充 balanced/economical/aggressive 三种策略下的具体行为指导\n- 企业尽调工作流：enterprise-search → enterprise-base → enterprise-summary → enterprise-list 四步尽调流程\n- 幻觉检测工作流：引用识别 → AI 建议 → 用户确认 → hall-detect 检测 → 结果展示\n- 企业风险排查工作流：enterprise-summary 总览 → enterprise-list 深挖高风险项 → 风险画像汇总\n\n### 改进\n- enterprise-list 子命令新增策略感知默认 size：economical 模式默认 10 条，aggressive 模式默认 50 条，balanced 保持 30 条\n\n## [1.3.1] - 2026-05-10\n\n### 新增\n- 关键词扩展检索：`keyword`、`case`、`regulation` 子命令新增 `--expand` 参数，支持传入逗号分隔的扩展关键词，自动追加到原始查询并以 OR 模式检索\n- 分阶段检索指引：SKILL.md 新增「关键词扩展与分阶段检索」章节，说明 AI 应如何主动扩展法律概念、执行广撒网+精提炼的两阶段检索\n- 扩展方向提示：检索完成后 AI 应向用户建议可能相关的扩展检索方向\n- 策略兼容矩阵：明确关键词扩展行为与 balanced/economical/aggressive 三种策略的兼容关系\n\n## [1.3.0] - 2026-05-10\n\n### 新增\n- 适配 24 个元典开放平台新接口（从 11 个扩展至 35 个）\n- 新增 5 个子命令：\n  - `hall-detect`：法规/法条/案例幻觉检测（50 积分）\n  - `enterprise-search`：企业轻量检索（1 积分），返回候选列表\n  - `enterprise-base`：企业基本信息查询（含股东、核心成员、分支机构）\n  - `enterprise-summary`：企业聚合总览\n  - `enterprise-list`：企业分项列表查询，支持 20 种类型（对外投资、商标、专利、涉诉文书、行政处罚等）\n- 新增 `format_hall_detect_results`：幻觉检测结果格式化（法规存在性、语义比对、案例核实）\n- 新增 `format_enterprise_list_results`：企业分项列表通用格式化函数\n- 新增 24 个 Reference 文档（12-35），覆盖幻觉检测和企业全息画像系列接口\n- 所有新子命令支持 `--no-cache` 选项\n- MANIFEST.json 全部 35 个接口标记为已适配（`adapted` 字段移除，改为完整元数据）\n- SKILL.md 接口清单从 11 个扩展至 35 个，新增幻觉检测和企业全息画像使用说明\n\n### 改进\n- 接口分层新增\"专项\"层（hall-detect）\n- 附属接口层扩展：新增 enterprise-search·enterprise-base·enterprise-summary·enterprise-list\n- 积分消耗说明从\"每次 10 积分\"更新为\"1-50 积分（视接口而定）\"\n- CLI 帮助示例新增 5 个新子命令用法\n\n## [1.2.1] - 2026-05-10\n\n### 改进\n- 新增 `references/MANIFEST.json`：接口清单元数据文件，记录全部 11 个已适配接口的端点、子命令、分层和分类信息\n- MANIFEST.json 包含 `check_history` 字段，记录每次平台接口排查的时间、方法和结论\n- 排查元典开放平台（2026-05-10）：通过 Playwright 浏览器实际访问接口广场，发现平台从 11 个 API 扩展到了 35 个，新增 24 个未适配接口（1 个幻觉检测 + 23 个企业信息），已记录到 MANIFEST.json，待后续适配\n\n## [1.2.0] - 2026-05-09\n\n### 新增\n- 可配置检索策略（`YD_STRATEGY`）：balanced（均衡，默认）、economical（省钱）、aggressive（激进）\n- `strategy` 子命令：显示当前检索策略\n- 策略感知的默认返回数量：economical 模式下语义检索默认 20 条，aggressive 模式下关键词检索默认 20 条\n\n### 改进\n- SKILL.md 调用策略章节重构为三策略矩阵，清晰区分接口确认要求、案例详情触发方式、补充检索行为\n- .env.example 新增 YD_STRATEGY 配置说明\n\n## [1.1.1] - 2026-04-18\n\n### 修复\n\n- `datetime` import 在 updater.py 重构时被误删，导致归档函数 `NameError`\n- `detail` 子命令：API 返回单个 dict 而非列表，格式化函数崩溃\n- `case` 子命令：API 返回 `{total, lst}` 结构而非裸列表，需从 `data.lst` 提取\n- `format_law_results` 兼容 `ftmc`/`tid` 字段（detail 端点返回）\n- `format_case_results` 兼容 `cprq` 字段（关键词检索返回的裁判日期）\n- `format_enterprise_results` 兼容中文字段名（`企业名称`、`统一社会信用代码`、`企业类型` 等）\n- 移除 `_print_footer` 中的缓存命中提示，归档重新定位为\"历史检索记录\"\n- 新增 `archive-list` 子命令，支持按关键词浏览历史检索记录\n- Reference 文档修正：05 案例关键词检索补充 `cprq`/`type`/`url`/`llm_content` 字段、07 案例详情补充返回结构、10 企业检索补充中英文字段映射\n- 权威案例关键词检索（06）返回结构说明更新为 `{total, lst}` 包装格式\n\n## [1.1.0] - 2026-04-17\n\n### 重大变更\n- SKILL.md 大幅精简（~260 行 → ~170 行），策略内容抽取至 `references/00-*.md`\n- Reference 文件按前缀分层：`00-` 策略指南、`01-11` API 端点文档\n\n### 新增\n- 策略指南：检索模式选择指南（`references/00-retrieval-mode-guide.md`）\n- 策略指南：接口优先级与选择规则（`references/00-interface-priority.md`）\n- 积分节约策略合并回 SKILL.md，核心理念调整为\"正确性优先于积分节约\"\n- SKILL.md 新增\"积分消耗模式\"小节，明确案例检索的两阶段消耗（摘要 10 积分 + 详情 10 积分/个）\n- `case` 子命令新增 `--fxgc`、`--yyft`、`--ft-search-mode` 参数\n- `format_law_results` 新增输出字段：发布日期、发布部门、发文字号、二级效力级别\n- Reference 文件补充响应结构文档（02-law-keyword-search 完整 20 字段）\n- `archive/.gitkeep` 确保归档目录不会被 git 忽略\n- `check-update` 新增最近提交记录展示（通过 Atom feed，不依赖 GitHub API）\n- `check-update` 新增 CHANGELOG 差异展示（读取远程 CHANGELOG.md 中本地版本之后的变更）\n- `do-update` 子命令：仅下载本 skill 目录下的文件更新，不碰其他目录和 .env/归档\n- 更新逻辑拆分为通用模块 `scripts/updater.py`（`SkillUpdater` 类），可被其他 skill 复用\n- `MANIFEST.txt` 移至 `scripts/` 目录，列出所有可更新文件\n\n### 修复\n- `--rewrite-flag` 参数使用 `type=bool` 导致任何字符串均为 `True` 的 bug，改为 `store_true`/`--no-rewrite`\n- 移除所有旧 API（aiapi.ailaw.cn）中文字段名 fallback 死代码\n- SKILL.md 注册地址更新为 `https://open.chineselaw.com`\n\n## [1.0.0] - 2026-04-17\n\n### 重大变更\n- API 平台迁移：从旧平台 (`aiapi.ailaw.cn:8319`) 迁移至开放平台 (`open.chineselaw.com`)\n- 认证方式从 URL 查询参数改为 `X-API-Key` 请求头\n- 语义检索请求体改为嵌套结构（`fatiao_filter` / `wenshu_filter`）\n- 语义检索响应格式更新（`extra.fatiao` / `extra.wenshu`）\n- 接口文档拆分为独立文件（`references/01~11-*.md`）\n\n### 新增\n- 法规关键词检索（`regulation` 子命令）\n- 法规详情查询（`regulation-detail` 子命令）\n- 案例详情查询（`case-detail` 子命令）\n- 企业名称检索（`enterprise` 子命令）\n- 企业详情查询（`enterprise-detail` 子命令）\n- 语义检索新增 `--rewrite-flag` 和 `--return-num` 参数\n- `raw` 子命令新增 `--get` 和 `--no-cache` 选项\n- 归档机制：每次 API 调用自动归档至 `archive/`，相同查询命中归档不消耗积分\n- 接口优先级分层：核心接口（5个）、扩展接口（4个）、附属接口（2个）\n\n### 改进\n- 案例关键词检索拆分为普通案例和权威案例两个端点\n- 格式化函数兼容新旧字段名\n- 超时时间从 30 秒提升至 60 秒\n\n## [0.3.1] - 2026-04-07\n\n### 改进\n\n- 移除「与其他技能配合」章节，保持技能描述独立聚焦\n\n## [0.3.0] - 2026-04-06\n\n### 改进\n\n- Front Matter 规范化：补充 homepage、author、version 字段\n\n## [0.2.0] - 2026-04-05\n\n### 改进\n- skill name 从 `yd-law-search` 改为 `yuandian-law-search`，提升辨识度\n- 目录同步重命名为 `yuandian-law-search`\n- 标题从\"元典法条检索\"改为\"元典法条与案例检索\"，准确反映 API 覆盖范围\n- 许可证从 CC BY-NC-SA 4.0 改为 MIT\n- 前置要求新增注册登录指引（账号注册 → API Key 创建 → 配置 .env → 验证连接）\n\n## [0.1.0] - 2026-04-03\n\n### 设计缘由\n- 元典法条检索 API 提供了法律条文和案例的语义/关键词检索能力，适合封装为 Skill 供法律分析场景使用。\n\n### 思路演进\n1. 分析 API 文档，梳理 5 个端点的功能和参数\n2. 设计统一的 CLI 工具，用子命令区分不同检索模式\n3. 输出格式化为 Markdown，方便 AI 直接引用\n\n### 新增\n- 初始版本，封装 5 个 API 端点\n- 支持法条语义检索、关键词检索、详情检索\n- 支持案例关键词检索、语义检索\n- 输出 Markdown 格式化\n- 支持原始 JSON 调试输出\n\nArchive v1.8.7: 53 files, 113593 bytes\n\nFiles: CHANGELOG.md (32160b), endpoints/01-law-vector-search.md (2620b), endpoints/02-law-keyword-search.md (3804b), endpoints/03-law-detail.md (675b), endpoints/04-case-semantic-search.md (2073b), endpoints/05-case-keyword-search.md (2640b), endpoints/06-case-keyword-search-authority.md (1044b), endpoints/07-case-detail.md (1141b), endpoints/08-regulation-search.md (1031b), endpoints/09-regulation-detail.md (569b), endpoints/10-enterprise-search.md (1014b), endpoints/11-enterprise-detail.md (606b), endpoints/12-hall-detect.md (2877b), endpoints/13-enterprise-search-lightweight.md (1102b), endpoints/14-enterprise-base-info.md (794b), endpoints/15-enterprise-aggregation-summary.md (584b), endpoints/16-enterprise-out-invest.md (643b), endpoints/17-enterprise-brand.md (618b), endpoints/18-enterprise-patent.md (619b), endpoints/19-enterprise-soft-right.md (658b), endpoints/20-enterprise-works-right.md (656b), endpoints/21-enterprise-icp.md (624b), endpoints/22-enterprise-change-info.md (650b), endpoints/23-enterprise-writ-agg.md (660b), endpoints/24-enterprise-writ-list.md (646b), endpoints/25-enterprise-court-session-notice.md (652b), endpoints/26-enterprise-court-notice.md (642b), endpoints/27-enterprise-executions.md (680b), endpoints/28-enterprise-executed-person.md (666b), endpoints/29-enterprise-frozen-equity.md (646b), endpoints/30-enterprise-punishment.md (647b), endpoints/31-enterprise-pledge.md (649b), endpoints/32-enterprise-guaranty.md (648b), endpoints/33-enterprise-abnormal-operation.md (672b), endpoints/34-enterprise-corporate-tax.md (646b), endpoints/35-enterprise-serious-illegal.md (654b), endpoints/MANIFEST.json (10975b), LICENSE.txt (1090b), README.md (7826b), references/01-keyword-expansion.md (4133b), references/02-typical-workflows.md (9640b), references/03-report-consolidation.md (5655b), references/04-report-design-notes.md (2361b), references/05-mcp-workflow.md (3150b), references/06-enterprise-portrait.md (2011b), references/07-research-middleware.md (19580b), scripts/MANIFEST.json (2081b), scripts/validate-query-filters.py (7970b), scripts/yd_search.py (94978b), skill-card.md (3183b), SKILL.md (29575b), templates/legal-research-report.md (1613b), _meta.json (138b)\n\nFile v1.8.7:SKILL.md\n\n---\nname: yuandian-law-search\nhomepage: https://github.com/cat-xierluo/legal-skills\nauthor: 杨卫薪律师（微信ywxlaw）\nversion: \"1.8.7\"\nlicense: MIT\ndescription: 元典法条与案例检索。本技能应在需要查询中国法律法规条文、检索相关案例、为法律分析提供数据支撑时使用。\n---\n\n# 元典法条与案例检索\n\n通过元典开放平台 API 检索中国法律法规条文和案例。**每次 API 调用消耗 1-50 积分**（视接口而定）。所有检索结果会自动归档到本地，方便后续回溯。\n\n## 数据留存与隐私警示\n\n本技能在提供便利的同时会产生本地留存与外部传输，使用前请知悉：\n\n- **本地归档**：每次检索的原始响应与结构化报告会自动写入 `archive/`（按 `YD_PROJECT` 或日期归类），并默认在您运行命令的工作目录生产一份 `.md` 副本（便于附卷；当工作目录恰为 skill 根目录时自动跳过）。可用 `--no-report` 完全跳过、`--no-cwd-report` 仅跳过工作目录副本。这些文件可能包含案由、当事人、裁判文书正文等敏感内容，**请勿将其提交至公开仓库或随意分享**。\n- **外部传输**：检索请求与（如幻觉检测）待查文本会发送至元典开放平台 `open.chineselaw.com`。提交给 `hall-detect` 等接口的文本可能包含案卷事实、合同或客户信息，**建议先脱敏再提交**。平台侧的留存策略以其服务条款为准。\n- **敏感内容最小化**：案例文书、企业信息含个人或商业敏感数据，引用与归档时遵循\"最小必要\"原则，避免大段全文外泄。\n\n## 所需权限\n\n本技能运行需要以下本地能力，均限定在检索与归档目的内：\n\n- **网络访问**：仅访问元典开放平台 `open.chineselaw.com`（HTTPS），用于检索与归档查重。\n- **文件系统读写**：读取 `scripts/.env`（API Key）、`scripts/MANIFEST.json`；写入 `archive/` 与当前工作目录的报告副本（可经 `--no-report`/`--no-cwd-report` 关闭）。\n- **环境变量**：读取 `YD_API_KEY`（鉴权）、`YD_STRATEGY`/`YD_PROJECT`（检索策略与归类）等；`yd-run` 以干净环境启动 Python，仅保留必要变量。\n- **本地代码执行**：通过 `scripts/yd-run` 调用 Python 检索脚本；不安装第三方运行时、不执行自动更新。\n\n## 前置要求（每次调用前自动检测）\n\n每次使用本技能前，**必须先执行以下检测流程**，确认 API Key 已就绪：\n\n### 检测步骤\n\n1. **检测 `.env` 文件**：检查 `scripts/.env` 是否存在\n2. **检测 API Key**：读取文件中 `YD_API_KEY` 的值，确认非空且不是占位符 `your-api-key-here`\n3. **若检测失败**，向用户提示以下引导信息并终止：\n\n```\n⚠️ 元典 API Key 未配置。请按以下步骤获取并配置：\n\n1. 注册/登录：访问 https://open.chineselaw.com ，使用手机号注册\n2. 创建 API Key：登录后在个人中心创建 Key\n3. 配置密钥：将 Key 填入以下文件\n\n   scripts/.env\n   ─────────────\n   YD_API_KEY=sk-你的密钥\n   # YD_STRATEGY=balanced\n   ─────────────\n\n每次调用消耗 10 积分，需在平台充值。\n配置完成后重新发起检索即可。\n```\n\n4. **若检测通过**，继续执行用户请求的检索命令\n\n### 检测命令\n\n```bash\n# 检测 .env 文件和 API Key\nif [ -f \"scripts/.env\" ]; then\n  KEY=$(grep '^YD_API_KEY=' scripts/.env | cut -d'=' -f2)\n  if [ -n \"$KEY\" ] && [ \"$KEY\" != \"your-api-key-here\" ]; then\n    echo \"API Key 已就绪\"\n  else\n    echo \"API Key 未配置\"\n  fi\nelse\n  echo \".env 文件不存在\"\nfi\n\n# 读取检索策略\nSTRATEGY=$(grep '^YD_STRATEGY=' scripts/.env 2>/dev/null | cut -d'=' -f2)\necho \"当前策略：${STRATEGY:-balanced}\"\n```\n\n## 网络环境与推荐调用入口\n\n默认使用 `scripts/yd-run` 执行检索，而不是直接调用底层 `yd_search.py`。`yd-run` 会以干净环境启动 Python：清除 Codex/代理相关环境变量，保留 `HOME`、`PATH`、语言环境、`YD_API_KEY`、`YD_STRATEGY`，并继续读取 `scripts/.env` 和 `archive/` 缓存。\n\n```bash\nscripts/yd-run search \"正当防卫的限度\" --sxx 现行有效\n```\n\n若遇到 `nodename nor servname provided, or not known` 或其他网络错误，先执行无积分消耗的网络检查：\n\n```bash\nscripts/yd-run --network-check\n```\n\n注意：`yd-run` 只能避免 Codex 进程环境变量、代理变量和 PATH 漂移造成的影响；如果 Codex 本身以网络沙箱启动，或系统代理/VPN 接管 DNS，子进程仍会受到系统级网络策略影响。终端 Codex 应使用 `--sandbox danger-full-access --ask-for-approval never` 启动。\n\n## 检索机制感知主流程（案件检索默认）\n\n当用户描述事实结构、争议焦点、诉讼立场，或问\"类似案件怎么判\"\"能不能主张 XX\"\"对方抗辩怎么办\"时，**先完成案件检索主流程，再调用接口**（DEC-006）。简单法条/案号/纯概念检索（`detail` / `case-detail` / 单条 `search`）不启动本流程，直接看下方接口速查。\n\n1. **轻量案件研判** → 产出检索简报（争点、要件、决定性事实、待补事实、必须排除的近邻案型、已有报告来源）。\n2. **派生检索命题** → 每个命题只验证一项判断，区分规范 / 事实结构 / 裁判规则 / 反向；每个 decisive 争点至少 1 条正向 + 1 条反向。\n3. **派生查询矩阵** → 一争点一查询、单一接口；案例关键词只放 4-6 个高信息密度词，不构造后端无法表达的长 AND。\n4. **小样本试检** → 1-2 条命题先验证接口与表达是否有效。\n5. **对位复核** → 按 HIGH / MEDIUM / LOW / MISMATCH 复核；只有诊断出偏差原因（接口误选 / 表达不适配 / 近邻混入）后才扩展查询或换接口。\n6. **正式检索** → 结论—依据—查询可追溯报告。\n\n信息不足时按\"最小必要\"补问（最多 1 轮，只问会改变检索路径的最关键问题），不空跑查询；事实不足但不影响查询方向的，标注假设继续。\n\n完整字段定义、接口路由规则、近邻案型排除清单、前置门禁判定与机器可读导出骨架见：[`references/07-research-middleware.md`](references/07-research-middleware.md)。\n\n> 下方「接口速查」是执行第 3 步查询矩阵时\"按机制选接口\"的依据，不是检索的起点。\n\n## 接口速查\n\n本技能共 35 个接口，分为四层。选择规则：\n\n1. 用户问\"XX法怎么规定的\" → 先用 `search` 语义检索\n2. 用户问\"关于XX的法律条文\" → 用 `keyword` 关键词检索\n3. 用户问\"民法典第XX条\" → 用 `detail` 精确获取\n4. 用户给出明确案由/关键词并要求精确筛选案例 → 用 `case` 关键词检索（默认普通案例）\n5. 用户描述事实结构、争议焦点或问\"类似案件怎么判\" → 优先用 `case-semantic` 语义检索\n6. 用户要求更深入了解某案例 → 提醒用户将消耗积分，确认后用 `case-detail`\n7. 用户要求企业背景调查 → 先用 `enterprise-search` 定位，再用 `enterprise-base`/`enterprise-summary` 获取详情\n8. 用户要求查询企业分项信息（涉诉、商标、专利等） → 用 `enterprise-list --type TYPE`\n9. 用户要求检测文本中法规/案例是否准确 → 用 `hall-detect`\n\n**核心接口（默认使用）：** `search` · `keyword` · `detail` · `case` · `case-semantic`\n**扩展接口（需确认）：** `regulation` · `regulation-detail` · `case-detail` · `case --authority-only`\n**附属接口（仅限明确要求）：** `enterprise` · `enterprise-detail` · `enterprise-search` · `enterprise-base` · `enterprise-summary` · `enterprise-list`\n**专项接口（仅限明确要求）：** `hall-detect`\n\n## 调用策略\n\n读取 `scripts/.env` 中的 `YD_STRATEGY` 配置（默认 `balanced`）。三种策略决定了 AI 的接口使用、确认流程和补充检索行为。\n\n**用户的明确指令始终优先于策略默认行为。**\n\n### 通用规则（所有策略共享）\n\n每次 API 调用消耗 1-50 积分（视接口而定）。以下规则不受策略影响：\n\n1. **必须调用 API**：需要引用具体法条文号 / 需要确认时效性 / 用户明确要求检索 / 案例检索 / AI 对自身记忆不确定\n2. **可以不调用**：纯概念性问题 / 对话中已检索过相同内容 / 用户未要求查找 / 用户明确说不需要查\n3. **积分消耗模式**：大部分接口每次 5-10 积分，幻觉检测 50 积分，轻量企业检索 1 积分。法条检索通常一次足够。案例检索是两阶段消耗（摘要 10 + 详情 每个 10）\n4. **接口分层**：核心（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）\n\n### 均衡策略（balanced，默认）\n\n即当前\"正确性优先\"策略，不改变现有行为。\n\n- **核心接口**：直接使用，无需确认\n- **扩展接口**：调用前告知用户将消耗积分，等待确认\n- **附属接口**：仅当用户明确要求时使用\n- **case-detail**：先展示摘要，由用户主动选择感兴趣的案例后再调用\n- **补充检索**：不主动运行语义+关键词双检索，选择最合适的一种\n- **积分报告**：每次检索后说明消耗和累计\n\n### 省钱策略（economical）\n\n在 balanced 基础上进一步收紧，最大限度减少积分消耗。\n\n- **核心接口**：直接使用，但应先检查归档缓存是否有类似结果\n- **扩展接口**：需用户二次确认（第一次只展示摘要和积分提醒，等用户再次确认后才调用）\n- **附属接口**：仅当用户明确要求时使用，同样需确认\n- **case-detail**：仅当用户指定具体案例编号时才调用，不主动提供\"是否查看详情\"选项\n- **补充检索**：不运行补充检索，一次只用一种模式\n- **积分报告**：每次检索后详细报告，并提醒可用的节约手段\n\n### 激进策略（aggressive）\n\n不考虑积分消耗，最大化检索精度和覆盖面。\n\n- **所有接口**：直接使用，无需确认\n- **case-detail**：自动获取最相关的 2-3 个案例的完整判决书，不需用户逐一选择\n- **补充检索**：对同一问题同时运行语义+关键词双检索，合并去重后展示\n- **积分报告**：简要说明消耗即可，不强调节约\n- **额外行为**：法条检索后发现相关法规（如司法解释），主动追加 regulation 检索；用户需求模糊时，宁可多查也不漏查\n\n### 接口策略速查\n\n部分接口在通用规则之上有特殊行为约束（按积分成本或权限敏感度划分）：\n\n| 接口 | 积分 | balanced | economical | aggressive |\n|------|------|----------|-----------|------------|\n| **hall-detect** | 50 | 用户明确要求时才使用，需确认\"检测需要 50 积分\" | 二次确认（第一次仅展示积分提醒，等用户再次确认才调用） | 可主动对用户引用的法条/案例做幻觉核验 |\n| **enterprise-search** | 1 | 直接使用，无需确认 | 优先检查缓存，未命中时直接使用（仅 1 积分） | 直接使用 |\n| **enterprise-base / enterprise-summary** | 10 | 用户明确要求时使用，告知积分消耗 | 需二次确认 | 直接使用 |\n| **enterprise-list** | 5-10/次 | 用户指定类型时调用，提醒多种类型会累积积分 | 每次只查一种类型，展示全部可用类型让用户选择 | 企业尽调场景可一次性查询多个相关类型（如涉诉+行政处罚+失信） |\n\n## 关键词扩展与典型工作流\n\nAI 在执行检索前应主动扩展关键词（上位概念 / 并列概念 / 程序-实体关联），\n并在多场景下遵循典型工作流与积分反馈原则。详见：\n\n- [`references/01-keyword-expansion.md`](references/01-keyword-expansion.md) — 关键词扩展三原则、`--expand` 参数、分阶段检索示例、策略兼容性\n- [`references/02-typical-workflows.md`](references/02-typical-workflows.md) — 法条 / 案例 / 关键词精确 / 企业尽调 / 幻觉检测 / 企业风险排查六大场景 + AI 向用户反馈的 8 条原则（含 per-call 报告落盘与禁止复制到目标目录的硬规则）\n\n## 检索模式选择\n\n每个领域有**语义检索**和**关键词检索**两种模式。\n\n| | 语义检索 | 关键词检索 |\n|---|---|---|\n| **子命令** | `search`（法条）/ `case-semantic`（案例） | `keyword`（法条）/ `case`（案例） |\n| **输入** | 自然语言问题或描述 | 精确关键词组合 |\n| **匹配** | 语义相似度，概念关联 | 字面匹配，AND/OR 逻辑 |\n| **返回量** | 默认 45 条 | 默认 10 条 |\n\n**用语义检索**：用户提出法律问题 / 描述场景 / 不确定关键词 / 需要广覆盖 → 不确定时默认用\n**用关键词检索**：用户给出明确关键词 / 需要 AND/OR 逻辑 / 需按日期、效力级别、法院等精确筛选 / 语义检索结果不够聚焦\n**案例检索红线**：综合案件和类案对标的第一轮优先 `case-semantic`；`case` 只放 4-6 个高信息密度关键词，避免长事实结构默认 AND 导致零命中。\n\n此外需区分检索法条还是案例：\"XX的法律依据\" → 法条检索；\"有没有相关案例\" → 案例检索；兼要法条和案例 → 先法条后案例，两次调用。\n\n## 核心接口用法\n\n### 1. 法条语义检索（search）\n\n```bash\nscripts/yd-run search \"正当防卫的限度\" --sxx 现行有效\n```\n\n### 2. 法条关键词检索（keyword）\n\n```bash\nscripts/yd-run keyword \"人工智能 监管\" \\\n  --effect1 法律 --sxx 现行有效 \\\n  --fbrq-start 2022-01-01 --fbrq-end 2026-03-01\n```\n\n### 3. 法条详情检索（detail）\n\n```bash\nscripts/yd-run detail \"民法典\" --ft-name \"第十五条\"\n```\n\n### 4. 案例关键词检索（case）\n\n```bash\n# 普通案例（默认）\nscripts/yd-run case \"买卖合同纠纷\" --province 广西\n\n# 权威案例（扩展，需确认）\nscripts/yd-run case \"买卖合同纠纷\" --province 广西 --authority-only\n```\n\n### 5. 案例语义检索（case-semantic）\n\n```bash\nscripts/yd-run case-semantic \"正当防卫的限度\" --jarq-start 2020-01-01\n```\n\n## 扩展接口用法\n\n### 6. 法规关键词检索（regulation）\n\n```bash\nscripts/yd-run regulation \"数据安全\" --effect1 法律 --sxx 现行有效\n```\n\n### 7. 法规详情（regulation-detail）\n\n```bash\nscripts/yd-run regulation-detail --name \"中华人民共和国数据安全法\"\n```\n\n### 8. 案例详情（case-detail）\n\n```bash\nscripts/yd-run case-detail --type ptal --ah \"（2025）桂09民终192号\"\n```\n\n### 9. 企业检索（enterprise）\n\n```bash\nscripts/yd-run enterprise \"华为\" --num 5\n```\n\n### 10. 企业详情（enterprise-detail）\n\n```bash\nscripts/yd-run enterprise-detail --credit-code \"9144030071526726XG\"\n```\n\n## 幻觉检测\n\n### 11. 法规/法条/案例幻觉检测（hall-detect）\n\n检测文本中引用的法规、法条、案例是否存在幻觉（是否真实存在、内容是否准确）。**每次调用消耗 50 积分**。\n\n```bash\nscripts/yd-run hall-detect \"根据《中华人民共和国数据保护法》第35条规定，数据处理者应当...\"\n```\n\n返回结果包含：\n- **法规检测**：每条法规是否真实存在（law_exists），语义比对结论和相似度\n- **案例检测**：每条案例是否真实存在，基本事实和裁判要点\n- **高亮文本**：标注了检测结果的原文本\n\n## 企业全息画像\n\n企业信息类接口（`enterprise-search` / `enterprise-base` / `enterprise-summary` / `enterprise-list`）的完整用法、`--type` 可选维度（涉诉、商标、专利、对外投资、股权冻结等 20 类）与积分消耗表见：\n\n[`references/06-enterprise-portrait.md`](references/06-enterprise-portrait.md)\n\n## 通用参数说明\n\n### 法条检索通用筛选\n\n| 参数 | 说明 | 可选值 |\n|------|------|--------|\n| `--effect1` | 效力级别（可多次指定） | 宪法、法律、司法解释、行政法规、部门规章、地方性法规 等 |\n| `--sxx` | 时效性（可多次指定） | 现行有效、失效、已被修改、部分失效、尚未生效 |\n| `--keep-industry` | 保留默认剔除的办案无关条目 | 无需取值（flag） |\n\n> **默认剔除办案无关条目**：`search` / `keyword` / `regulation` 默认过滤 `effect1 ∈ {行业/团体规范, 地方律协规定, 行政机关工作文件, 党内法规, 军事法规规章}` 的条目（律协指引、课题公告/答复函、党纪规定、军队规定等——非法律渊源或与一般民商事/刑事办案无关）。footer 提示剔除数量；涉党纪/涉军等特殊案件需要时加 `--keep-industry` 保留。`archive/` 原始数据仍完整，仅过滤显示与 `.md` 报告。\n\n### 案例检索通用筛选\n\n| 参数 | 说明 |\n|------|------|\n| `--province` / `--xzqh-p` | 省份筛选 |\n| `--jarq-start / --jarq-end` | 结案日期范围 |\n| `--cj` | 法院层级：最高/高级/中级/基层 |\n| `--wenshu-type` | 案件类型：刑事案件/民事案件/行政案件 |\n\n## Reference 文档索引\n\n### 工作流指南\n\n- [关键词扩展与分阶段检索](references/01-keyword-expansion.md)\n- [典型工作流与用户引导](references/02-typical-workflows.md)\n- [法律检索报告与目标目录归档](references/03-report-consolidation.md)\n- [法律检索报告 7 节设计原理](references/04-report-design-notes.md)\n- [MCP 协同工作流](references/05-mcp-workflow.md)\n- [企业全息画像](references/06-enterprise-portrait.md)\n- [检索机制感知型中间层执行合同](references/07-research-middleware.md)\n\n### 接口清单与 API 端点文档\n\n`endpoints/MANIFEST.json` 记录全部已适配接口的元数据（端点、子命令、分层、分类），以及平台接口排查历史。下次排查新增接口时，更新该文件的 `check_history` 即可。\n\n| # | 文件 | 接口 |\n|---|------|------|\n| 01 | [law-vector-search.md](endpoints/01-law-vector-search.md) | 法条语义检索 |\n| 02 | [law-keyword-search.md](endpoints/02-law-keyword-search.md) | 法条关键词检索 |\n| 03 | [law-detail.md](endpoints/03-law-detail.md) | 法条详情 |\n| 04 | [case-semantic-search.md](endpoints/04-case-semantic-search.md) | 案例语义检索 |\n| 05 | [case-keyword-search.md](endpoints/05-case-keyword-search.md) | 普通案例关键词检索 |\n| 06 | [case-keyword-search-authority.md](endpoints/06-case-keyword-search-authority.md) | 权威案例关键词检索 |\n| 07 | [case-detail.md](endpoints/07-case-detail.md) | 案例详情 |\n| 08 | [regulation-search.md](endpoints/08-regulation-search.md) | 法规关键词检索 |\n| 09 | [regulation-detail.md](endpoints/09-regulation-detail.md) | 法规详情 |\n| 10 | [enterprise-search.md](endpoints/10-enterprise-search.md) | 企业名称检索 |\n| 11 | [enterprise-detail.md](endpoints/11-enterprise-detail.md) | 企业详情 |\n| 12 | [hall-detect.md](endpoints/12-hall-detect.md) | 幻觉检测 |\n| 13 | [enterprise-search-lightweight.md](endpoints/13-enterprise-search-lightweight.md) | 企业检索（轻量） |\n| 14 | [enterprise-base-info.md](endpoints/14-enterprise-base-info.md) | 企业基本信息 |\n| 15 | [enterprise-aggregation-summary.md](endpoints/15-enterprise-aggregation-summary.md) | 企业聚合总览 |\n| 16 | [enterprise-out-invest.md](endpoints/16-enterprise-out-invest.md) | 对外投资 |\n| 17 | [enterprise-brand.md](endpoints/17-enterprise-brand.md) | 商标 |\n| 18 | [enterprise-patent.md](endpoints/18-enterprise-patent.md) | 专利 |\n| 19 | [enterprise-soft-right.md](endpoints/19-enterprise-soft-right.md) | 软件著作权 |\n| 20 | [enterprise-works-right.md](endpoints/20-enterprise-works-right.md) | 作品著作权 |\n| 21 | [enterprise-icp.md](endpoints/21-enterprise-icp.md) | 网站备案 |\n| 22 | [enterprise-change-info.md](endpoints/22-enterprise-change-info.md) | 变更记录 |\n| 23 | [enterprise-writ-agg.md](endpoints/23-enterprise-writ-agg.md) | 涉诉信息统计 |\n| 24 | [enterprise-writ-list.md](endpoints/24-enterprise-writ-list.md) | 涉诉文书 |\n| 25 | [enterprise-court-session-notice.md](endpoints/25-enterprise-court-session-notice.md) | 开庭公告 |\n| 26 | [enterprise-court-notice.md](endpoints/26-enterprise-court-notice.md) | 法院公告 |\n| 27 | [enterprise-executions.md](endpoints/27-enterprise-executions.md) | 失信被执行人 |\n| 28 | [enterprise-executed-person.md](endpoints/28-enterprise-executed-person.md) | 被执行人 |\n| 29 | [enterprise-frozen-equity.md](endpoints/29-enterprise-frozen-equity.md) | 股权冻结 |\n| 30 | [enterprise-punishment.md](endpoints/30-enterprise-punishment.md) | 行政处罚 |\n| 31 | [enterprise-pledge.md](endpoints/31-enterprise-pledge.md) | 股权出质 |\n| 32 | [enterprise-guaranty.md](endpoints/32-enterprise-guaranty.md) | 对外担保 |\n| 33 | [enterprise-abnormal-operation.md](endpoints/33-enterprise-abnormal-operation.md) | 经营异常 |\n| 34 | [enterprise-corporate-tax.md](endpoints/34-enterprise-corporate-tax.md) | 欠税公告 |\n| 35 | [enterprise-serious-illegal.md](endpoints/35-enterprise-serious-illegal.md) | 严重违法 |\n\n## 历史检索记录\n\n每次 API 调用的完整结果会自动归档到 `archive/` 目录。当用户提到\"之前查过什么\"时，AI 可以直接从归档中提取历史结果，无需重新调用 API。\n\n**按检索目的归类（`YD_PROJECT`）**：每个研究任务开始时，AI/用户设 `YD_PROJECT` 环境变量（如 `export YD_PROJECT=0713-商标在先使用权`，或行内 `YD_PROJECT=0713-商标案 scripts/yd-run search ...`），该任务的所有检索自动归到 `archive/<YD_PROJECT>/` 一个文件夹下，便于追溯。未设时按日期 `archive/YYYYMMDD/` 兜底，不再平铺根目录。**缓存查重全局生效**——同一问题在不同 project 下会命中已有归档，不重复消耗积分。\n\n`archive/<project>/<ts>_<query>.json` 是机器可读版（response/query/fingerprint/source_urls 全字段），同名 `.md` 是人类可读版（结构化报告），两者一一对应。同一份报告的副本会同步写入用户运行命令时的工作目录（`<CWD>/<ts>_<query>.md`），便于附卷；当 CWD 恰为 skill 根目录时自动跳过（避免污染 skill 目录）。\n\n浏览历史记录：\n\n```bash\nscripts/yd-run archive-list\nscripts/yd-run archive-list --keyword \"正当防卫\"\n```\n\n如果用户说\"之前查正当防卫的时候看到一个案例\"，AI 应先用 `archive-list --keyword \"正当防卫\"` 找到对应的归档文件，然后直接读取其中的 `response` 字段返回给用户。这不需要消耗积分。\n\n## 调试\n\n```bash\nscripts/yd-run raw /open/law_vector_search \"正当防卫\" --extra '{\"fatiao_filter\":{\"sxx\":[\"现行有效\"]}}'\n```\n\n## 法律检索报告（consolidate）\n\n多次检索之后，把 per-call 报告汇总成一份完整的法律检索报告。**这是律师/客户看的交付物**，per-call 报告是数据底稿。\n\n### 7 节\"结论先行\"标准结构\n\n**核心原则**：用户最想知道的是**最终结论**（能不能做、怎么做、风险在哪），法条和案例只是用来核实结论的支撑材料。所以结构应是 **结论先行 → 分析支撑 → 检索底稿垫后**。\n\n模板文件位于 `templates/legal-research-report.md`；`scripts/yd-run consolidate` 会按同一结构自动生成报告。\n\n1. **案情简介** — 当事人、争议焦点、当前阶段（最少必要）\n2. **检索目的与问题** — 本次检索要回答的法律问题（1-3 个核心 Q）\n3. **检索结论** ⭐ — **最先读到的内容**：\n   - 3.1 一句话定性（\"能做/不能做\" + 法律依据）\n   - 3.2 核心论点的判例支撑速查（用表格/列表，让用户 30 秒内 get 到）\n   - 3.3 风险点（诚实告知，不要只说好的）\n   - 3.4 后续行动（具体可执行的步骤）\n4. **分析与判断** — 抗辩应对、法条适用、诉讼请求结构、赔偿酌定、证据准备\n5. **检索思路与方法** — 关键词组合、筛选条件、检索顺序（备查）\n6. **检索结果** — 按 endpoint 分组：6.1 法律依据 / 6.2 司法案例 / 6.3 行政法规 / 6.4 其他（核实材料）\n7. **检索明细** — 表格，链接到每条 per-call 报告（末尾，使用可回溯本地链接）\n\n### 检索报告质量要求\n\n- **结论区必须能独立阅读**：3.1-3.4 应让律师、客户或法官先得到答案，再决定是否看底稿\n- **核心依据用表格速查**：不要让读者从几十条法条/案例中自行拼结论\n- **方法区保留检索痕迹**：写清关键词、筛选条件、平台、时间、纳入规则\n- **结果区只放支撑材料**：法条、案例、法规按类型分组，不替代第四节分析\n- **风险必须明示**：包括不利类案、法律适用分歧、地域差异、时效或证据缺口\n- **无法确认的信息标注待补充**：不要把检索不到或材料未提及的事实写成确定结论\n\n> **节号从 1 重新编号**（案情=1，结论=3，结果=6，明细=7），不沿用 1-6 顺序编号；体现\"结论在第 3 节\"的视觉位置。\n\n**反例**（曾出现过的旧版结构）：\n- 案情 → 目的 → 思路 → 检索结果 → 分析 → 结论\n- 用户反馈：检索结果（法条案例）全是\"核实材料\"，要翻到最后才看到结论 → 太累\n- 新版：结论放到第 3 节，用户看完 3.1-3.4 就能得到 80% 答案\n\n末尾附\"本次检索明细\"表格，链接到每条 per-call 报告。\n\n### 调用方式\n\n```bash\nscripts/yd-run consolidate \\\n    --title \"张某买卖合同违约金调整\" \\\n    --project \"case-2024-zhangsan\" \\\n    --case \"案情：...\" \\\n    --strategy \"检索思路：...\" \\\n    --analysis \"分析与判断：...\" \\\n    --conclusion \"一句话结论：...\" \\\n    --risks \"主要风险：...\" \\\n    --next-actions \"后续行动：...\" \\\n    --include \"违约金,高空抛物\"\n```\n\n- `--case` / `--strategy` / `--analysis` 必填：AI 显式传本次任务的案情/思路/判断\n- `--include` 必填：逗号分隔的查询子串，明确指定\"本次任务范围\"（不取最近 N 条）\n  - 匹配规则：CWD 中所有符合 `<8位时间戳>_<6位时间戳>_<查询>.md` 命名的 .md 文件，文件名包含任一子串即被纳入\n- `--project` 可选：项目子目录名。默认从 `--title` slugify（如 \"张某买卖合同违约金调整\" → \"张某买卖合同违约金调整\"）。用于 `archive/<project>/` 归类\n- `--title` / `--purpose` / `--conclusion` / `--risks` / `--next-actions` / `--output` 可选\n  - `--purpose` 不传则基于检索词自动生成\n  - `--conclusion` 强烈建议传入；不传会在 3.1 保留补写提示\n  - `--risks` / `--next-actions` 不传会保留补写提示\n  - `--output` 默认同时写 CWD 和 `archive/<project>/`；指定则只写到指定路径\n\n### 项目子目录组织\n\nconsolidate 会把这次任务的所有文件归类到 `archive/<project>/` 子目录：\n\n```\narchive/\n  case-2024-zhangsan/\n    20260610_192031_货款逾期违约金_司法实践.json   ← 从 archive/ 根目录移入\n    20260610_192031_货款逾期违约金_司法实践.md    ← 从 CWD 复制\n    20260610_192032_逾期付款_违约金_调整.json\n    20260610_192032_逾期付款_违约金_调整.md\n    20260610_192058_法律检索报告.md                ← 主交付物\n```\n\n- **.md 复制**（CWD 保留工作副本）：用户的工作目录不被破坏\n- **.json 移动**（archive 根目录已清理）：避免根目录重复积累，扁平区只放\"in-flight 暂存\"\n- 重复运行 consolidate 同一项目：idempotent，文件已在子目录则跳过\n\n### 与 per-call 报告的关系\n\n```\n多次 yd-run 检索（自动写 per-call .md 到 archive + CWD）\n       ↓\nAI 汇总判断后调 consolidate --project \"case-x\"\n       ↓\n创建 archive/case-x/，.md 复制进来，.json 移进来，法律检索报告写进去\n       ↓\nCWD 也有法律检索报告副本，per-call .md 仍在 CWD（工作副本）\n       ↓\n报告末尾的\"检索明细表\"链接回 archive/case-x/ 里的副本\n```\n\nper-call .md 是数据底稿，可独立查看；session 报告是主交付物，附案情/思路/判断；项目子目录是组织容器。\n\n## 目标目录归档规范（强制）\n\n目标目录（通常是案件文件夹 `02 - 案件分析` / `03 - 法律研究` 等）与 AI 进程的 CWD 是不同的两个位置。\n目标目录只允许出现：整合后的法律检索报告 + 外部素材 + 基于整合报告再生成的下游文件；\n**禁止** per-call 检索记录、检索明细 JSON、AI 进程 CWD 的工作副本。\n\n完整规则（标准工作流 4 步、反例、验证清单 4 条）见：\n\n[`references/03-report-consolidation.md`](references/03-report-consolidation.md#目标目录归档规范强制)\n\n## MCP 协同工作流（v1.6.0+）\n\n元典官方 MCP（https://open.chineselaw.com/mcp-config）已发布，3 个 servers：yuandian-law（法律法规）、yuandian-case（案例文书）、yuandian-company（企业信息）。本 skill 的价值现在转向\"**归档 + 法律检索报告生成**\"——数据接入由 MCP 负责，本 skill 负责沉淀。\n\n完整工作流（元典 MCP 接入配置、Agent 三步法、ingest 子命令、模式选型表）见：\n\n[`references/05-mcp-workflow.md`](references/05-mcp-workflow.md)\n\nFile v1.8.7:README.md\n\n# 元典法条与案例检索 (yuandian-law-search)\n\n通过 [元典开放平台](https://open.chineselaw.com) 检索中国法律法规条文和案例，为法律分析和研究提供数据支撑。\n\nv1.6.1 起，本 Skill 的核心交付能力从单次 API 包装扩展为\"检索归档 + 法律检索报告生成\"：多次检索后可用 `consolidate` 汇总为 7 节结论先行报告，适合律师内部复核、客户沟通和类案检索留痕。v1.7.4 修复关键词扩展的自动 OR 行为，并强化案件综合检索的语义优先策略。\n\n## 快速开始\n\n### 1. 获取 API Key\n\n访问 [open.chineselaw.com](https://open.chineselaw.com)，用手机号注册后在个人中心创建 API Key。每次调用消耗 10 积分，需在平台充值。\n\n### 2. 配置密钥\n\n将 API Key 填入 `scripts/.env`：\n\n```\nYD_API_KEY=sk-你的密钥\n```\n\n### 3. 执行检索\n\n```bash\nscripts/yd-run search \"正当防卫的限度\" --sxx 现行有效\n```\n\n`scripts/yd-run` 会用干净环境启动 Python，避免 Codex 进程环境、代理变量或 PATH 漂移影响元典接口访问。网络排查可先运行：\n\n```bash\nscripts/yd-run --network-check\n```\n\n### 4. 生成法律检索报告\n\n多次检索后，用 `consolidate` 生成主交付物。报告结构为：案情简介、检索目的与问题、检索结论、分析与判断、检索思路与方法、检索结果、检索明细。\n\n```bash\nscripts/yd-run consolidate \\\n  --title \"张某买卖合同违约金调整\" \\\n  --project \"case-2024-zhangsan\" \\\n  --case \"案情：...\" \\\n  --strategy \"检索思路：...\" \\\n  --analysis \"分析与判断：...\" \\\n  --conclusion \"一句话结论：...\" \\\n  --risks \"主要风险：...\" \\\n  --next-actions \"后续行动：...\" \\\n  --include \"违约金,逾期付款\"\n```\n\n## 设计理念：为什么这样设计这个 Skill\n\n### 背景\n\n元典开放平台提供 11 个 API 端点，覆盖法条、案例、法规、企业四个领域。**每次 API 调用消耗 10 积分**，这意味着一个\"检索 5 个案例并逐一查看详情\"的简单场景，实际消耗为 10 + 5×10 = 60 积分。\n\n因此，整个 Skill 的设计围绕一个核心问题：**如何在保证正确性的前提下，用最少的 API 调用完成任务？**\n\n### 原则一：正确性优先于积分节约\n\nAI 的记忆可能存在幻觉或过时。涉及法律条文的精确引用时，宁可多查一次，不可引用错误法条。\n\n**必须调用 API 的情况：**\n- 需要引用具体法条文号（AI 可能记错条文内容或条号对应）\n- 需要确认时效性（法律修订频繁，AI 训练数据可能已过时）\n- 用户明确要求检索\n- AI 对自身记忆不确定\n\n**可以不调用的情况：**\n- 纯概念解释（如\"什么是善意取得\"）\n- 对话中已检索过相同内容\n- 用户未要求查找\n\n### 原则二：三级接口分层\n\n不是所有接口都应该被同等对待。我们将 11 个端点分为三层：\n\n| 层级 | 接口 | 设计意图 |\n|------|------|----------|\n| **核心层**（5 个） | `search` · `keyword` · `detail` · `case` · `case-semantic` | 覆盖 90% 的日常法律检索需求，默认直接使用 |\n| **扩展层**（4 个） | `regulation` · `regulation-detail` · `case-detail` · `case --authority-only` | 非日常需求，调用前需告知用户额外积分消耗 |\n| **附属层**（2 个） | `enterprise` · `enterprise-detail` | 仅在用户明确要求企业信息时才使用 |\n\n这样设计是因为：法条语义检索（`search`）返回结果已包含法条全文，通常一次调用即可满足需求，无需再调 `detail`；而案例详情（`case-detail`）是额外消耗，必须让用户知情。\n\n### 原则三：语义检索优先\n\n每个领域提供语义和关键词两种检索模式，默认优先使用语义检索：\n\n| 模式 | 适用场景 | 典型返回量 |\n|------|----------|-----------|\n| **语义检索**（`search` / `case-semantic`） | 自然语言问题，不确定用什么关键词 | 45 条 |\n| **关键词检索**（`keyword` / `case`） | 明确关键词 + 需要精确筛选条件 | 10 条 |\n\n语义检索覆盖面更广，一次调用往往足够。只有当用户提供了明确关键词或需要日期/法院/级别等筛选条件时，才切换到关键词检索。\n\n### 原则四：本地缓存零成本\n\n脚本内置归档缓存机制：每次 API 调用的查询和响应会自动存入 `archive/` 目录，以 SHA-256 指纹匹配。相同查询自动命中缓存，**不消耗积分**。\n\n这意味着在同一个对话中多次讨论同一个法律问题时，只有第一次会产生积分消耗。\n\n### 六条积分节省策略\n\n这些策略写入了 SKILL.md，指导 AI 代理在调用时做出正确判断：\n\n1. **一查多用** — 一次检索结果充分引用，避免重复检索同一问题\n2. **优先语义检索** — `search` 返回最全面的结果，一次通常够用\n3. **避免法条链式调用** — 不要先 `search` 再逐条 `detail`，语义检索已含全文\n4. **案例详情谨慎调用** — 先用摘要筛选 1-2 个最相关案例，再调 `case-detail`\n5. **善用筛选参数** — `--sxx 现行有效`、`--effect1 法律` 等缩小范围，避免无效结果\n6. **信任归档缓存** — 相同查询自动命中本地归档，零积分消耗\n\n## 接口概览\n\n| 命令 | 用途 | 端点 | 层级 |\n|------|------|------|------|\n| `search` | 法条语义检索 | `/open/law_vector_search` | 核心 |\n| `keyword` | 法条关键词检索 | `/open/rh_ft_search` | 核心 |\n| `detail` | 法条详情 | `/open/rh_ft_detail` | 核心 |\n| `case` | 案例关键词检索 | `/open/rh_ptal_search` | 核心 |\n| `case --authority-only` | 权威案例检索 | `/open/rh_qwal_search` | 扩展 |\n| `case-semantic` | 案例语义检索 | `/open/case_vector_search` | 核心 |\n| `case-detail` | 案例详情 | `/open/rh_case_details` | 扩展 |\n| `regulation` | 法规关键词检索 | `/open/rh_fg_search` | 扩展 |\n| `regulation-detail` | 法规详情 | `/open/rh_fg_detail` | 扩展 |\n| `enterprise` | 企业名称检索 | `/open/rh_company_info` | 附属 |\n| `enterprise-detail` | 企业详情 | `/open/rh_company_detail` | 附属 |\n\n每个端点的完整参数说明和响应结构见 `endpoints/01~35-*.md`。\n\n## 版本演进\n\n| 版本 | 日期 | 关键变化 |\n|------|------|----------|\n| v0.1.0 | 2026-04-03 | 初始版本，封装 5 个 API 端点 |\n| v0.2.0 | 2026-04-05 | 改名 `yuandian-law-search`，MIT 许可证，新增注册引导 |\n| v1.0.0 | 2026-04-17 | **迁移至开放平台**，新增 6 个端点，引入归档缓存和三级分层 |\n| v1.1.0 | 2026-04-17 | 策略抽取至 `references/00-*.md`，核心理念调整为\"正确性优先\" |\n| v1.6.1 | 2026-06-15 | 优化 `consolidate` 法律检索报告模板为 7 节结论先行结构，新增模板文件和风险/后续行动参数 |\n| v1.7.0 | 2026-06-15 | 目录结构重构：35 个 API 文档迁入 `endpoints/`，`references/` 仅留工作流指南，新增 `templates/legal-research-report.md`；SKILL.md 由 809 行压到 494 行 |\n| v1.7.2 | 2026-06-15 | `references/` 6 个 `00-*.md` 改为 `01-06` 顺序编号；\"新接口策略矩阵\"小节去重话术（保留表格，去掉新/旧接口区分） |\n| v1.7.4 | 2026-06-15 | 修复 `--expand` 未能自动切换 OR 的脚本问题；强化案件综合/标杆类案检索的 `case-semantic` 优先、短关键词复检和零命中复检规则；同步版本与发布索引 |\n\nv1.0.0 是最重要的里程碑：API 从旧平台 `aiapi.ailaw.cn:8319` 整体迁移至开放平台 `open.chineselaw.com`，认证方式从 URL 参数改为 `X-API-Key` 请求头，同时新增了法规、案例详情、企业三大领域的端点。\n\n## 许可证\n\nMIT License — 详见 [LICENSE.txt](LICENSE.txt)。\n\n## 作者\n\n杨卫薪律师（微信 ywxlaw）\n\nFile v1.8.7:_meta.json\n\n{\n  \"ownerId\": \"kn7bn9h1qxa9ja48qkmaxtfjgx81ksex\",\n  \"slug\": \"yuandian-law-search\",\n  \"version\": \"1.8.7\",\n  \"publishedAt\": 1785936552502\n}\n\nFile v1.8.7:references/01-keyword-expansion.md\n\n## 关键词扩展与分阶段检索\n\n关键词检索默认是精确匹配，用户搜索\"刑事案件管辖权\"不会自动命中\"知识产权管辖权\"等相关概念。本节说明 AI 应如何主动扩展检索范围、分阶段提炼精准结果。\n\n### 关键词扩展原则\n\nAI 在执行关键词检索前，应先分析用户查询是否涉及可扩展的法律概念：\n\n1. **上位概念扩展**：将具体概念扩展到上位概念。例如\"商标侵权\"→ 同时检索\"知识产权侵权\"\n2. **并列概念扩展**：关联同一层级的平行概念。例如\"管辖权异议\"→ 同时考虑\"管辖权转移\"\"指定管辖\"\n3. **程序-实体关联**：从实体法关键词关联到程序法关键词。例如\"正当防卫\"→ 也关注\"防卫过当\"\"紧急避险\"\n\n### 扩展关键词工作流\n\n当 AI 判断用户查询涉及可扩展概念时，按以下流程操作：\n\n1. **识别核心关键词**：从用户查询中提取核心法律概念\n2. **生成扩展词列表**：基于上述原则，列出 2-5 个相关关键词\n3. **分阶段检索**：\n   - **第一阶段（广撒网）**：用核心关键词执行一次检索（使用 `--search-mode or` 扩大命中范围）\n   - **第二阶段（精提炼）**：根据第一阶段结果，提炼更精准的关键词组合再检索一次\n4. **结果合并与去重**：将两次检索结果合并，按相关性排序展示\n5. **扩展方向提示**：检索完成后，向用户建议可能相关的扩展检索方向\n\n### 脚本参数支持\n\n关键词检索、案例检索和法规检索新增 `--expand` 参数，用于一次性传入多个扩展关键词：\n\n```bash\n# 法条关键词扩展检索\nscripts/yd-run keyword \"刑事案件 管辖权\" --expand \"知识产权管辖,级别管辖,专门管辖\" --search-mode or\n\n# 案例关键词扩展检索\nscripts/yd-run case \"买卖合同 瑕疵担保\" --expand \"质量纠纷,违约责任\" --search-mode or\n\n# 法规关键词扩展检索\nscripts/yd-run regulation \"民法典 合同\" --expand \"买卖合同,租赁合同\" --search-mode or\n```\n\n`--expand` 参数的行为：\n- 将扩展关键词追加到原始查询中；未显式传入 `--search-mode` 时，自动使用 `or` 模式检索\n- 如果显式传入 `--search-mode and`，尊重用户指定，仍按 AND 模式检索\n- 等效于将原始关键词与扩展关键词用空格连接后以 OR 模式检索\n- 不带 `--expand` 时保持原有的精确匹配行为（默认 `and`）\n\n### 分阶段检索示例\n\n用户问：\"关于刑事案件管辖权有哪些规定？\"\n\n**第一阶段（广撒网）**：\n```bash\nscripts/yd-run keyword \"刑事案件 管辖权 级别管辖 地域管辖 专门管辖\" --search-mode or --sxx 现行有效\n```\n\n**分析第一阶段结果**：发现大量结果涉及\"级别管辖\"和\"地域管辖\"两个核心分支\n\n**第二阶段（精提炼）**：\n```bash\nscripts/yd-run keyword \"级别管辖 中级法院\" --search-mode and --sxx 现行有效\nscripts/yd-run keyword \"地域管辖 犯罪地\" --search-mode and --sxx 现行有效\n```\n\n### 扩展方向提示\n\n检索完成后，AI 应根据检索结果向用户建议相关的扩展方向。提示格式：\n\n```\n本次检索完成了对\"刑事案件管辖权\"的查询，消耗 XX 积分。\n\n💡 相关的扩展检索方向：\n1. 级别管辖 —— 中级/高级/最高法院的管辖分工\n2. 地域管辖 —— 犯罪地、被告人居住地的管辖规则\n3. 专门管辖 —— 军事法院、知识产权法院等专门管辖\n如需深入了解某个方向，请告诉我。\n```\n\n### 策略兼容性\n\n关键词扩展行为与三种检索策略的关系：\n\n| 策略 | 扩展行为 | 分阶段检索 | 积分控制 |\n|------|----------|-----------|----------|\n| **balanced** | AI 判断是否需要扩展，主动执行 | 可执行两阶段检索 | 第二阶段前告知用户将额外消耗积分 |\n| **economical** | 不主动扩展，仅用户要求时执行 | 不执行，一次检索完成 | 仅扩展时提示积分消耗 |\n| **aggressive** | 自动扩展所有相关概念，不等待确认 | 自动执行多阶段检索 | 不限制，追求最大覆盖面 |\n\nFile v1.8.7:references/02-typical-workflows.md\n\n## 典型工作流与用户引导\n\nAI 在完成检索后，应**主动告知用户检索结果摘要和积分消耗**，并根据场景推荐后续操作。\n\n### 法条研究场景\n\n用户问：\"关于股东出资瑕疵的法律规定有哪些？\"\n\n1. 先调 search 语义检索（10 积分），覆盖全部相关法条\n2. 展示摘要 + 关键条文引用 + 总积分\n3. 主动建议扩展方向（如\"公司法\"\"破产法\"）\n\n### 案例研究场景\n\n用户问：\"最近几年类似案件怎么判的？\"\n\n1. 调 case-semantic 语义检索（10 积分），覆盖近 5 年案例\n2. 展示相关度排序的案例摘要\n3. **不主动调 case-detail**，由用户选择感兴趣的案例后调详情\n4. 主动告知\"如需查看完整判决书请告知，每个案例 10 积分\"\n\n### 案件综合分析场景\n\n用户问：\"这个案件我们能不能主张 XX？\"\n\n1. 多轮检索：先 search 法条、再 case-semantic 案例、可能补 regulation 法规\n2. 汇总法条 + 案例 + 法规 + AI 分析判断\n3. 给出可执行的法律意见\n4. **总积分可能 30-50**，在最终回复开头明示\n\n**案例检索执行约束**：\n\n- 第一轮案例检索优先用 `case-semantic` 承接案情事实结构，不要把长事实描述直接丢给 `case` 关键词 AND 检索。\n- 只有在需要锁定若干高信息密度词时才补 `case`；关键词控制在 4-6 个，优先选择平台/行业行为词、交易链条词和责任焦点词。\n- `case` 默认是 AND 精确匹配；如果使用 `--expand` 扩展同义词、上位词或并列场景，未显式指定时脚本会自动切到 OR。\n- 一轮关键词检索零命中时，不要据此判断\"没有类案\"；应立即改用 `case-semantic` 或缩短关键词后 OR 复检。\n\n### 争议焦点识别优先场景（v1.6.1+ 强制前置步骤）\n\n**问题**：很多 AI 跳过\"识别用户原话里的争议焦点\"这一步，直接根据用户问题的\"法律概念包装\"展开检索（\"短视频带货\"\"电商平台\"\"间接侵权\"），结果命中大量\"被告自己动手\"的案型，与用户实际争议焦点偏差很大。\n\n**强制前置：争议焦点识别表**\n\n收到\"这个案件我们能不能主张 XX\"或类似案件综合分析请求时，**第一轮检索前**先在对话/笔记中明确以下 5 个字段，再据此生成检索词：\n\n| 字段 | 用户问题中提取 | 检索词应反映 |\n|------|--------------|-------------|\n| **行为主体** | 谁实施了侵权？（如\"达人\"/\"商家\"/\"平台\"） | 用具体主体词，不要用泛化的\"被告\" |\n| **角色定位** | 用户/原告的主张对象处于什么位置？（如\"被挂车商家\"vs\"自营商家\"） | 区分\"被关联\"和\"主动实施\"两种身份 |\n| **行为模式** | 侵权内容如何产生、传播、变现？（如\"达人发布→挂车→商家团购\"） | 用**行业术语**（挂车、探店、团购）而非法律术语 |\n| **抗辩点** | 被告可能怎么抗辩？（如\"视频非我发、我无法控制达人\"） | 围绕抗辩点搜\"法院如何回应\" |\n| **用户已明确的论点** | 用户主张的几个核心点是什么？ | **直接用用户原话作为检索词**（见下方\"红线\"） |\n\n**红线（重要）**：\n\n> **用户的争议焦点 ≠ 用户问题的法律概念包装**\n> **用户的争议焦点 = 用户原话里已经明确给出的几个核心论点**\n\n例：\n- 用户原话：\"视频是达人发的，不是被告发的，但挂在被告商品链接上。被告商品页能看到达人视频 → 被告有筛选过程。被告因此获利 → 反不正当竞争法兜底。\"\n- 用户已明确的论点 = [1] 视频非被告发布但挂被告商品链接；[2] 被告对视频有筛选过程；[3] 被告因此获利；[4] 反不正当竞争法兜底\n- v1 错搜：用\"短视频带货 电商平台 间接侵权\"（用户问题的法律概念包装）→ 偏差\n- v1 正搜：用\"视频不是商家发布 商家对达人视频有筛选过程 商家因视频获利 反不正当竞争法兜底\"（用户原话级别）→ 命中对位案\n\n**反例（曾发生过的偏差）**：\n\n> 用户问：\"达人发的短视频侵权了，挂到商家商品链接上，商家要负责吗？\"\n>\n> v1 错误：直接搜\"短视频带货 电商平台 间接侵权\" → 命中\"商家自己搬运/制作\"案例 → 全部跑偏\n>\n> v1 正确（如果当时识别到位）：用户已经明确 4 个信息——\n> ① 视频由达人发布（非被告）② 视频→挂车→被告商品 ③ 被告对视频有筛选过程 ④ 被告因此获利+反不正当竞争法兜底\n> 直接把这 4 个用户原话作为检索词，**第一轮**就能命中对位案。\n>\n> 不需要等\"检索后再提炼二分法\"——用户原话已经够具体了。\n\n**关键提示**：\n- **行业术语 > 法律术语**：用户说\"挂车\"就用\"挂车\"，不要说\"信息网络传播\"\n- **用户原话级别 > 法律概念包装**：用户原话里给的论点直接作为检索词\n- **抗辩点对称搜索**：被告可能怎么抗辩 → 搜\"法院如何否定该抗辩\" 的判例\n- **二分法是结果不是起点**：如果检索后才识别出二分法（如\"营销合作 vs 精选联盟\"），说明第一轮关键词就有问题——应该在第一轮就用更精确的词\n- **长事实结构走语义，短关键词走精确**：自然语言事实结构用 `case-semantic`；`case` 只放少量关键字，避免 6 个以上词的 AND 零命中。\n\n### 标杆案例对标检索场景（v1.6.1+ 强制流程）\n\n**问题**：用户第一轮就提供了标杆案例（如星云VR案、微信文章），但 v1 没把它作为\"对标模板\"去搜同类，导致错失场景最对位的案例。\n\n**强制流程**：\n\n1. **提取标杆案例的\"事实结构骨架\"**（5-7 个关键事实）\n   - 例：星云VR案 = {店主联系达人 + 多个探店账号发布 + 视频含侵权片段 + 视频挂团购链接 + 商家根据链接成交向达人结算佣金 + 商家未审核 + 法院判决商家赔偿}\n\n2. **把\"事实结构骨架\"作为查询模板**生成检索词\n   - 关键词版：`探店达人 + 团购链接 + 商家 + 营销合作 + 审查义务`\n   - 语义版（更优）：用一段自然语言描述这个事实结构\n\n3. **首选 case-semantic**（关键词检索对\"达人\"\"挂车\"识别差）\n   - 关键词检索易命中\"被告自己动手\"的偏差案例\n   - 语义检索对场景描述识别更好\n   - 如果补关键词检索，先用 4-6 个高密度词，例如 `短视频 推广 团购 商家 责任 著作权`\n   - 避免第一轮使用 `探店达人 团购链接 商家 著作权 责任`、`推广视频 挂车 商家 责任 审查 注意义务` 等长 AND 组合；这类组合容易因字面差异零命中\n\n4. **每轮命中后回检\"对标度\"**：命中案例的\"事实结构\"是否覆盖标杆案例的 5-7 个关键事实\n   - 覆盖 ≥ 5/7 → 高度对位，纳入\"主要类案\"\n   - 覆盖 3-4/7 → 一般类案，辅助参考\n   - 覆盖 ≤ 2/7 → 偏差案例，谨慎援引（可能论证方向不同）\n\n**反例（曾发生过的偏差）**：\n\n> 用户第一轮给了星云VR案（江苏高院公众号文章），明确场景是\"达人探店+挂团购+商家担责\"\n>\n> v1：忽略标杆案例，直接搜\"短视频带货 电商平台 间接侵权\" → 命中偏差案例\n>\n> v2 正确：把星云VR案的事实结构作为查询模板 → 命中 (2023)京0491民初5073 号等高度对位案\n\n### 法规全景场景\n\n用户问：\"数据安全相关的所有规定\"\n\n1. regulation 关键词检索（10 积分）+ 必要的 regulation-detail\n2. 展示法规清单 + 效力级别 + 关联法条\n3. 主动建议进一步细化方向\n\n### 企业风险排查场景\n\n用户问：\"这家公司有没有什么风险？\"\n\n1. enterprise-summary 快速总览（10 积分），识别风险分布\n2. 针对高风险项用 enterprise-list 深挖（如涉诉文书、失信被执行人、行政处罚）\n3. 汇总风险画像\n\n### AI 向用户反馈的原则\n\n1. **每次检索后主动说明积分消耗**：\"本次检索消耗 10 积分\"\n2. **多步检索时告知累计消耗**：\"本次检索消耗 10 积分（本次对话累计 30 积分）\"\n3. **完整判决书的触发取决于策略**：balanced/economical 由用户主动触发；aggressive 由 AI 自动获取最相关的 2-3 个\n4. **案例语义检索的摘要通常已够用**：只有用户明确要求查看完整判决书时才深入（aggressive 除外）\n5. **法条语义检索已含全文**：不需要额外补充\n6. **用自然语言与用户沟通**：不要向用户暴露命令行语法，AI 后台执行脚本即可\n7. **补充检索取决于策略**：balanced/economical 一次只用一种检索模式；aggressive 对重要问题自动同时运行语义+关键词检索，合并去重\n8. **检索报告 .md 自动落盘**：每次实际检索（cache miss 时）会同时落盘两份结构化 Markdown 报告：\n   - `archive/<ts>_<query>.md`：与 archive JSON 配对，技能内部归档，便于复盘\n   - `<CWD>/<ts>_<query>.md`：用户当前工作目录（AI 进程 CWD）副本，**仅供 AI 后台处理用，不应被复制到目标目录**\n   - 报告内容包含元信息（时间/接口/关键词/积分/原始数据路径/工作目录副本）+ 检索结果 + 引用来源\n   - footer 会输出报告路径，AI 应在对话中告知用户\n   - 默认双副本写入；可用 `--no-report` 完全跳过、`--no-cwd-report` 仅跳过工作目录副本\n   - **重要**：per-call 工作副本不是最终交付物，**禁止 AI 把它们复制到用户的案件文件夹等目标目录**（详见 `03-report-consolidation.md`）\n\nFile v1.8.7:references/03-report-consolidation.md\n\n## 法律检索报告（consolidate）\n\n多次检索之后，把 per-call 报告汇总成一份完整的法律检索报告。**这是律师/客户看的交付物**，per-call 报告是数据底稿。\n\n### 7 节\"结论先行\"标准结构\n\n报告骨架（7 节结构、设计动机、反例、节号逻辑）见：\n\n[`04-report-design-notes.md`](04-report-design-notes.md)\n\n调用 consolidate 时使用该骨架作为输出格式约定。\n\n### 调用方式\n\n```bash\nscripts/yd-run consolidate \\\n    --title \"张某买卖合同违约金调整\" \\\n    --project \"case-2024-zhangsan\" \\\n    --case \"案情：...\" \\\n    --strategy \"检索思路：...\" \\\n    --analysis \"分析与判断：...\" \\\n    --conclusion \"一句话结论：...\" \\\n    --risks \"主要风险：...\" \\\n    --next-actions \"后续行动：...\" \\\n    --include \"违约金,高空抛物\"\n```\n\n- `--case` / `--strategy` / `--analysis` 必填：AI 显式传本次任务的案情/思路/判断\n- `--include` 必填：逗号分隔的查询子串，明确指定\"本次任务范围\"（不取最近 N 条）\n  - 匹配规则：CWD 中所有符合 `<8位时间戳>_<6位时间戳>_<查询>.md` 命名的 .md 文件，文件名包含任一子串即被纳入\n- `--project` 可选：项目子目录名。默认从 `--title` slugify（如 \"张某买卖合同违约金调整\" → \"张某买卖合同违约金调整\"）。用于 `archive/<project>/` 归类\n- `--title` / `--purpose` / `--conclusion` / `--risks` / `--next-actions` / `--output` 可选\n  - `--purpose` 不传则基于检索词自动生成\n  - `--conclusion` 强烈建议传入；不传会在 3.1 保留补写提示\n  - `--risks` / `--next-actions` 不传会保留补写提示\n  - `--output` 默认同时写 CWD 和 `archive/<project>/`；指定则只写到指定路径\n\n### 项目子目录组织\n\nconsolidate 会把这次任务的所有文件归类到 `archive/<project>/` 子目录：\n\n```\narchive/\n  case-2024-zhangsan/\n    20260610_192031_货款逾期违约金_司法实践.json   ← 从 archive/ 根目录移入\n    20260610_192031_货款逾期违约金_司法实践.md    ← 从 CWD 复制\n    20260610_192032_逾期付款_违约金_调整.json\n    20260610_192032_逾期付款_违约金_调整.md\n    20260610_192058_法律检索报告.md                ← 主交付物\n```\n\n- **.md 复制**（CWD 保留工作副本）：用户的工作目录不被破坏\n- **.json 移动**（archive 根目录已清理）：避免根目录重复积累，扁平区只放\"in-flight 暂存\"\n- 重复运行 consolidate 同一项目：idempotent，文件已在子目录则跳过\n\n### 与 per-call 报告的关系\n\n```\n多次 yd-run 检索（自动写 per-call .md 到 archive + CWD）\n       ↓\nAI 汇总判断后调 consolidate --project \"case-x\"\n       ↓\n创建 archive/case-x/，.md 复制进来，.json 移进来，法律检索报告写进去\n       ↓\nCWD 也有法律检索报告副本，per-call .md 仍在 CWD（工作副本）\n       ↓\n报告末尾的\"检索明细表\"链接回 archive/case-x/ 里的副本\n```\n\nper-call .md 是数据底稿，可独立查看；session 报告是主交付物，附案情/思路/判断；项目子目录是组织容器。\n\n## 目标目录归档规范（强制）\n\n**用户的目标目录（通常是案件文件夹 `02 - 案件分析` / `03 - 法律研究` 等）≠ AI 进程的 CWD**。AI 进程运行 `scripts/yd-run` 时所在的 CWD 是临时工作区，**不是**用户的案件文件夹。\n\n### 目标目录只放什么\n\n目标目录（用户指定的文件夹）只允许出现以下文件：\n\n1. **整合后的法律检索报告**（`法律检索报告.md`，7 节标准结构）—— **唯一必需**\n2. **外部素材**：用户单独提供的微信文章、PDF、链接笔记等\n3. **基于整合报告再生成的下游文件**：证据清单、代理词大纲、抗辩应对清单、应诉策略等\n\n### 目标目录不允许出现\n\n- ❌ per-call 检索记录（`<ts>_<query>.md` × N 份）\n- ❌ 检索明细 JSON\n- ❌ 任何中间过程的临时文件\n- ❌ AI 进程 CWD 下的 per-call 工作副本\n\n### 标准工作流\n\n```\nStep 1：AI 在自己的 CWD 多次 yd-run 检索\n        → archive/<ts>_<query>.json + .md（skill 内部）\n        → <CWD>/<ts>_<query>.md（AI 进程工作副本，仅供 AI 读）\n\nStep 2：AI 汇总判断后，**手动**写一份整合报告到目标目录\n        → <用户目标目录>/<日期>_<主题>-法律检索报告.md\n\nStep 3：清理 AI 进程 CWD 下的 per-call 工作副本\n        → 不复制到目标目录\n        → 仍可在 archive/<ts>_<query>.md 留底\n\nStep 4：用户后续若要\"基于检索结果生成证据清单/代理词\"\n        → 读取整合报告（含检索明细表），生成新文件\n        → 新文件**也只放目标目录**，不污染 archive\n```\n\n### 反例（曾发生过的错误）\n\n```bash\n# ❌ 错误：把 8 份 per-call 工作副本复制到目标目录\ncp /Users/.../yuandian-law-search/20260615_163256_*.md \\\n   \"/案件文件夹/03 - 法律研究/\"\n# → 用户被迫手工清理，因为目标目录被检索底稿污染\n```\n\n正确做法：\n\n```bash\n# ✅ 正确：只把整合报告写到目标目录\n# 整合报告由 AI 在对话中直接 Write 到目标目录\n# per-call 工作副本留在 skill 内部 archive/\n```\n\n### 验证清单\n\nAI 完成法律检索任务后，自查：\n\n- [ ] 目标目录里**只有**整合报告 + 外部素材 + 下游生成文件\n- [ ] 目标目录里**没有** per-call `<ts>_<query>.md` × N\n- [ ] per-call 报告可在 `archive/` 里查到（不丢数据）\n- [ ] 整合报告末尾的\"检索明细表\"指向 `archive/` 路径（而非 CWD 路径）\n\nFile v1.8.7:references/04-report-design-notes.md\n\n## 法律检索报告 · 7 节设计原理（\"结论先行\"规约）\n\n> 本文件是 consolidate 报告生成的**格式约定 + 设计原理**，供 AI 在手动整合时遵循。\n> 注意：`templates/legal-research-report.md` 是可维护的模板参考；`yd_search.py` 当前用代码内 f-string 渲染。\n> 本文件描述的是**结构与设计动机**，与运行时具体格式解耦。\n\n### 设计原则\n\n- 用户最想知道最终结论 → 结论提前到第 3 节\n- 法条和案例只是核实材料 → 放到第 6 节\n- 节号从 1 重新编号（案情=1，结论=3，结果=6，明细=7），\n  体现\"结论在第 3 节\"的视觉位置\n\n### 反例（曾出现过的旧版结构，避免回退）\n\n- 案情 → 目的 → 思路 → 检索结果 → 分析 → 结论\n- 用户反馈：检索结果（法条案例）全是\"核实材料\"，要翻到最后才看到结论 → 太累\n- 新版：结论放到第 3 节，用户看完 3.1-3.4 就能得到 80% 答案\n\n### 7 节标准骨架\n\n#### 1. 案情简介\n\n当事人 / 争议焦点 / 当前阶段（最少必要）\n\n#### 2. 检索目的与问题\n\n本次检索要回答的法律问题（1-3 个核心 Q）\n\n#### 3. 检索结论 ⭐\n\n**用户最先读到的内容**：\n\n- 3.1 一句话定性（\"能做/不能做\" + 法律依据）\n- 3.2 核心论点的判例支撑速查（表格，30 秒内 get）\n- 3.3 风险点（诚实告知，不要只说好的）\n- 3.4 后续行动（具体可执行的步骤）\n\n#### 4. 分析与判断\n\n抗辩应对 / 法条适用 / 诉讼请求结构 / 赔偿酌定 / 证据准备\n\n#### 5. 检索思路与方法\n\n关键词组合 / 筛选条件 / 检索顺序（备查）\n\n#### 6. 检索结果（按 endpoint 分组）\n\n- 6.1 法律依据\n- 6.2 司法案例\n- 6.3 行政法规\n- 6.4 其他（核实材料）\n\n#### 7. 检索明细\n\n表格，链接到每条 per-call 报告（末尾）\n\n### 质量要求\n\n- 结论区必须能独立阅读：3.1-3.4 应先回答问题，再引导读者看底稿\n- 核心依据用表格速查：避免把法条和案例堆给读者自行归纳\n- 方法区保留检索痕迹：写清关键词、筛选条件、平台、时间、纳入规则\n- 结果区只放支撑材料：法条、案例、法规按类型分组，不替代第四节分析\n- 风险必须明示：包括不利类案、法律适用分歧、地域差异、时效或证据缺口\n\nFile v1.8.7:references/05-mcp-workflow.md\n\n## MCP 协同工作流（v1.6.0+）\n\n元典已发布官方 MCP（https://open.chineselaw.com/mcp-config），3 个 servers：yuandian-law（法律法规）、yuandian-case（案例文书）、yuandian-company（企业信息）。本 skill 的价值现在转向\"**归档 + 法律检索报告生成**\"——数据接入由 MCP 负责，本 skill 负责沉淀。\n\n### 接入元典 MCP\n\n模板在 `scripts/.mcp.json.example`（与 `scripts/.env.example` 同目录）。把它复制为客户端能识别位置的 `.mcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"yuandian-law\":    { \"url\": \"https://open.chineselaw.com/mcp/law/stream\",    \"headers\": {\"Authorization\": \"Bearer ${YD_API_KEY}\"} },\n    \"yuandian-case\":   { \"url\": \"https://open.chineselaw.com/mcp/case/stream\",   \"headers\": {\"Authorization\": \"Bearer ${YD_API_KEY}\"} },\n    \"yuandian-company\":{ \"url\": \"https://open.chineselaw.com/mcp/company/stream\",\"headers\": {\"Authorization\": \"Bearer ${YD_API_KEY}\"} }\n  }\n}\n```\n\n设置环境变量后重启客户端，agent 即可自动获得 `mcp__yuandian_law__*`、`mcp__yuandian_case__*`、`mcp__yuandian_company__*` 工具。\n\n### AI Agent 三步工作流\n\n```\nStep 1: 调 MCP 拿数据（agent 直接调，不经 yd-run）\n  mcp__yuandian_law__yuandian_law_vector_search(\"违约金\", sxx=\"现行有效\")\n  → 拿到 API 响应 JSON\n\nStep 2: 喂给 yd-run ingest 归档 + 生成 .md\n  echo \"<上一步的 JSON>\" | yd-run ingest \\\n      --query \"违约金 调整\" \\\n      --endpoint \"/open/law_vector_search\"\n  → archive/<ts>_违约金_调整.json + .md（同直接 API 模式）\n  → CWD/<ts>_违约金_调整.md 工作副本\n\nStep 3: 多次 ingest 后，调 yd-run consolidate 生成法律检索报告\n  yd-run consolidate --project \"case-2024-xxx\" \\\n      --case \"...\" --strategy \"...\" --analysis \"...\" \\\n      --conclusion \"一句话结论：...\" \\\n      --risks \"主要风险：...\" \\\n      --next-actions \"后续行动：...\" \\\n      --include \"违约金\"\n  → archive/case-2024-xxx/ 项目包 + 7 节结论先行报告（详见 templates/legal-research-report.md）\n```\n\n### ingest 子命令详细\n\n```bash\n# 方式 1: 文件输入\nyd-run ingest --query \"<Q>\" --endpoint \"/open/<E>\" --input <file.json>\n\n# 方式 2: stdin pipe（agent 友好）\ncat result.json | yd-run ingest --query \"<Q>\" --endpoint \"/open/<E>\"\n\n# 必填\n#   --query:     用于生成文件名 + 元信息\n#   --endpoint:  对应 API 路径，用于 routing 到 formatter（见 INGEST_ROUTING）\n# 可选\n#   --cost:        成本标签（默认 \"10 积分\"）\n#   --no-report:   跳过 .md 报告生成\n#   --no-cwd-report: 跳过 CWD 副本\n```\n\n`--endpoint` 取值见 INGEST_ROUTING 路由表（36 个 endpoint 全部覆盖，包括元典 MCP 暴露的全部 24 个数据 tools）。\n\n### 何时用哪种模式\n\n| 场景 | 推荐模式 |\n|---|---|\n| agent 调 mcp__yuandian__* | 走 MCP + yd-run ingest（v1.6.0 推荐）|\n| 客户端没装 MCP / 单次脚本 | 走 yd-run search/case/... 直接 API（v1.5.x 兼容）|\n| 调试 / 看 raw JSON | 走 yd-run raw |\n\n两种模式产出完全一致（archive/ 格式、.md 元信息、consolidate 路由），可混用。\n\nFile v1.8.7:references/06-enterprise-portrait.md\n\n## 企业全息画像\n\n### 12. 企业检索（轻量候选列表，enterprise-search）\n\n**每次调用消耗 1 积分**。按名称检索企业，返回候选列表（仅含 ID、名称、信用代码），用于定位目标企业后调用其他企业接口。\n\n```bash\nscripts/yd-run enterprise-search \"华为\" --top-k 5\n```\n\n### 13. 企业基本信息（enterprise-base）\n\n根据企业 ID 或统一社会信用代码获取企业完整信息（含股东、核心成员、分支机构等）。\n\n```bash\nscripts/yd-run enterprise-base --uscc \"9144030071526726XG\"\n```\n\n### 14. 企业聚合总览（enterprise-summary）\n\n一次调用获取企业各维度数据的统计摘要。\n\n```bash\nscripts/yd-run enterprise-summary --id \"企业ID\"\n```\n\n### 15. 企业分项列表（enterprise-list）\n\n查询企业各维度详细记录，支持分页。**每次调用消耗 5-10 积分**（涉诉统计和涉诉文书 10 积分，其余 5 积分）。\n\n```bash\n# 查询企业涉诉文书\nscripts/yd-run enterprise-list --type writ-list --uscc \"9144030071526726XG\"\n\n# 查询企业对外投资\nscripts/yd-run enterprise-list --type invest --uscc \"9144030071526726XG\" --page 1 --size 10\n\n# 查询企业商标\nscripts/yd-run enterprise-list --type brand --uscc \"9144030071526726XG\"\n```\n\n#### 可用类型\n\n| TYPE | 名称 | 积分 |\n|------|------|------|\n| invest | 对外投资 | 5 |\n| brand | 商标 | 5 |\n| patent | 专利 | 5 |\n| soft-right | 软件著作权 | 5 |\n| works-right | 作品著作权 | 5 |\n| icp | 网站备案 | 5 |\n| change-info | 变更记录 | 5 |\n| writ-agg | 涉诉信息统计 | 10 |\n| writ-list | 涉诉文书 | 10 |\n| court-session | 开庭公告 | 5 |\n| court-notice | 法院公告 | 5 |\n| execution | 失信被执行人 | 5 |\n| executed-person | 被执行人 | 5 |\n| frozen-equity | 股权冻结 | 5 |\n| punishment | 行政处罚 | 5 |\n| pledge | 股权出质 | 5 |\n| guaranty | 对外担保 | 5 |\n| abnormal | 经营异常 | 5 |\n| tax | 欠税公告 | 5 |\n| serious-illegal | 严重违法 | 5 |\n\nFile v1.8.7:references/07-research-middleware.md\n\n# 检索机制感知型法律研究中间层（执行合同）\n\n> 本 reference 落地 [DEC-006]：把 Skill 从\"元典 API/MCP 包装 + 归档 + 报告\"升级为\"检索机制感知型法律研究中间层\"。\n> 案件检索（综合检索 / 类案对标 / 已有报告复盘）**默认走本主流程**；简单法条或案号检索（`detail` / `case-detail`）不启动本流程。\n> 评测定位见 [DEC-007]：本文定义的是**第 1 层「检索方案评测」**的产物——可在不调用元典接口时完整产出。\n\n## 1. 与既有约定的关系\n\n- v1.6.1+ 已有的「5 字段争点识别表」（见 [`02-typical-workflows.md`](02-typical-workflows.md) 场景 4：行为主体 / 角色定位 / 行为模式 / 抗辩点 / 用户已明确的论点）是本流程 `research_brief` 的**子集**，不重复执行。\n- 本流程把争点识别扩展为：`research_brief`（检索简报）→ `propositions`（检索命题）→ `query_matrix`（查询矩阵）→ 对位复核。\n- 关键词扩展三原则（[`01-keyword-expansion.md`](01-keyword-expansion.md)）仍适用，但降级为查询矩阵**内部**的一条改写手段，不再是案件检索的默认主路径（[DEC-006] pt 5）。\n\n## 2. 执行合同（调用任何检索接口前必须完成）\n\n案件检索必须按以下顺序推进；任一步信息不足时按 §6 前置门禁处理，不得跳步直接调用接口。\n\n```\n① 轻量案件研判 ─► research_brief\n② 由 brief 派生 ─► propositions（正向支持 + 反向排除）\n③ 由 propositions 派生 ─► query_matrix（一争点一查询，单一接口）\n④ 小样本试检（1-2 条命题先验证接口与表达是否有效）\n⑤ 对位复核（HIGH / MEDIUM / LOW / MISMATCH）─► 策略修正\n⑥ 正式检索 ─► 结论—依据—查询可追溯报告\n```\n\n> 简单检索（用户给出明确法条名+条号、或明确案号、或问\"XX 法怎么规定\"且无案件事实）走 [`SKILL.md` 接口速查](../SKILL.md#接口速查)即可，**不启动本流程**。判定边界见 §7。\n\n## 3. research_brief（检索简报）schema\n\n| 字段 | 类型 | 必填 | 说明 |\n|---|---|---|---|\n| `research_goal` | string | 是 | 本次研究要回答的法律问题（用户真正要求裁判/判断的命题，不是案由复述） |\n| `party_stance` | object | 是 | 当事人立场：`role`（原告/被告/被申请人/代理人…）+ `claim_or_defense`（核心诉求或抗辩） |\n| `procedure_stage` | string | 否 | 程序阶段（一审/二审/再审/仲裁/执行/诉前） |\n| `dispute_focus` | string[] | 是 | 争议焦点：用户原话里已明确的核心论点（来自 5 字段表的\"用户已明确论点\"） |\n| `claim_or_defense_path` | string[] | 是 | 请求权/抗辩路径——由本案事实推导，用于区分主题相近但请求权基础不同的近邻案型（不预设特定法律领域） |\n| `legal_elements` | object[] | 是 | 法律要件：`element`（要件名）+ `source`（法源线索，待检索验证）+ `covered`（brief 是否已覆盖该要件的事实）。`covered` **不是装饰字段**：`covered=false` 的要件必须落入 `facts_to_supplement` 并标注是否阻断路径，驱动补问/假设继续——若全员 `covered=true` 却仍要检索，说明要件拆解流于形式 |\n| `decisive_facts` | string[] | 是 | 决定性事实（must_match）：检索简报和查询表达必须覆盖的事实 |\n| `background_facts` | string[] | 否 | 背景事实（影响裁判尺度但不决定争点定性） |\n| `facts_to_supplement` | object[] | 否 | 待补事实：`fact` + `blocks_path`（是否改变检索路径）+ `action`（补问/标注假设继续） |\n| `must_exclude_neighbor_types` | string[] | 是 | 必须排除的近邻案型（must_not_match），见 §8 |\n| `key_decisive_facts` | string[] | 否（建议） | `decisive_facts` 的**置顶短摘要**（3-5 条精简版），放在 brief 顶部便于人/judge 快速复核，不得与 `decisive_facts` 矛盾 |\n| `key_exclusions` | string[] | 否（建议） | `must_exclude_neighbor_types` 的**置顶短摘要**，同上 |\n| `role_comparison_matrix` | object | 否（仅同主题多角色场景） | 多主体角色对比矩阵，见 §3.1 |\n| `prior_report_sources` | object | 否 | 已有法律分析报告（见 §3.2），无则留空 |\n| `platform_coverage_note` | string | 否 | 若案件领域超出平台主要覆盖（如行政诉讼），标注哪些法源覆盖不足，见 §9.2 |\n\n**硬约束**：`dispute_focus`、`decisive_facts`、`must_exclude_neighbor_types` 三项不得为空；任一为空说明案件研判未完成，退回 §6 前置门禁。\n\n### 3.1 scan-friendly 摘要与多角色对比矩阵\n\n- **置顶摘要**：`key_decisive_facts` 与 `key_exclusions` 是 `decisive_facts` / `must_exclude_neighbor_types` 的精简镜像，放在 brief 顶部，让复核者（人或自动 judge）无需翻查嵌套字段即可定位关键事实与近邻排除。底层详细字段仍是权威来源；摘要不得与之矛盾，也不得只写摘要而省略底层字段。目的：避免 dense 结构化输出被快速浏览时漏看关键排除项。\n- **多角色对比矩阵**：当一个案件含 2+ 主体角色且请求权基础不同，除为每个角色产出独立的 propositions/queries 外，还应输出 `role_comparison_matrix` 汇总差异：\n\n  ```json\n  {\n    \"axes\": [\"主体角色\", \"请求权基础/规范\", \"决定性事实\", \"必须排除的近邻\"],\n    \"rows\": [\n      {\"role\": \"主体角色 A\", \"claim_basis\": \"（该角色的请求权基础/规范，由本案推导）\", \"decisive_facts\": [\"...\"], \"exclusions\": [\"...\"]},\n      {\"role\": \"主体角色 B\", \"claim_basis\": \"（与 A 不同的请求权基础/规范）\", \"decisive_facts\": [\"...\"], \"exclusions\": [\"...\"]}\n    ]\n  }\n  ```\n  矩阵是汇总视图，**不替代**各角色的独立 query_matrix（一争点一查询仍按角色分别落）。\n\n### 3.2 已有法律分析报告（`prior_report_sources`）\n\n输入含既有法律分析报告时，`prior_report_sources` 必须拆成**三栏**，把\"事实/结论/假设\"分层（反 inflation 关键防线）：\n\n| 子字段 | 含义 | 处置 |\n|---|---|---|\n| `report_facts` | string[] | 报告**援引的、可定位来源的客观事实**（报告中有出处、可回查的事实陈述）。可作检索线索直接使用 |\n| `report_conclusions` | string[] | 报告的**法律结论/定性**（报告作者的主观判断）。**必须降级为待验证假设**，不得当已证事实写入 `decisive_facts` |\n| `hypotheses_to_verify` | object[] | 由结论转化的、必须独立检索验证的判断：`hypothesis` + `verifies_conclusion`（关联 report_conclusions）+ `proposition_id`（对应验证命题） |\n\n**法源 vs 法律判断的区分**（易错点）：\n\n- 报告**援引的法源**（具体法条名称+条号，属客观引用）→ 可直接作 `queries[].filters`（`--yyft`）或法条检索线索，**无需降级**。\n- 报告**作者的法律评价/定性**（对要件是否成立、是否构成某行为的判断）→ 属主观判断，**必须降级为 `hypotheses_to_verify`**，配独立验证命题。\n\n**硬约束**：不得因报告存在而跳过 §2 轻量研判；每条 `report_conclusions` 都应有对应 `hypotheses_to_verify` 条目；报告结论不得直接出现在 `decisive_facts`（那是 must_match 事实位）。\n\n## 4. propositions（检索命题）schema\n\n每个命题只验证**一项**可被法条或案例支持/否定的判断。\n\n| 字段 | 取值 |\n|---|---|\n| `id` | `P-NN` |\n| `statement` | 单一判断陈述（\"……构成/不构成……\"\"……要件需要/不需要……\"） |\n| `type` | `normative`（规范命题：法条如何规定）/ `fact-structure`（事实结构命题：此类事实是否落入该规范）/ `adjudication-rule`（裁判规则命题：裁判者如何认定）/ `reverse`（反向命题：对方抗辩或不利类案的裁判路径） |\n| `direction` | `support`（支持我方立场）/ `oppose`（对方抗辩、不利类案、否定要件） |\n| `importance` | `decisive`（决定争点定性）/ `supportive`（影响尺度或佐证） |\n| `parent_element` | 关联的 `legal_elements[].element` 或 `dispute_focus` |\n\n**正反向必生成**：每个 decisive 争点至少生成 1 条 `support` + 1 条 `reverse` 命题（[DEC-006] pt 3）。反向命题是\"近邻陷阱\"的主要防线——它显式表达\"什么情况下我方命题不成立\"，对应到查询就是排除条件。\n\n## 5. query_matrix（查询矩阵）schema\n\n| 字段 | 说明 |\n|---|---|\n| `id` | `Q-NN` |\n| `proposition_id` | 承载的单一命题（`P-NN`） |\n| `interface` | `search` / `keyword` / `detail` / `case` / `case-semantic` / `regulation` / `case-detail` |\n| `routing_rationale` | 为何选此接口（基于接口的真实匹配机制，见 §9） |\n| `query_field` | 主查询字段（自然语言问题 / 关键词组合 / 结构化字段） |\n| `query_expression` | 实际查询表达 |\n| `filters` | 筛选条件（`--sxx`/`--effect1`/`--province`/`--jarq-*`/`--ay`/`--yyft` 等） |\n| `allow_rewrite` | 是否允许后端改写（向量接口默认 true；关键词接口不适用） |\n| `expected_hit` | 预期命中类型（法源/类案/裁判规则） |\n| `exclusion_criteria` | 排除标准（来自 `must_exclude_neighbor_types`，对应反向命题） |\n| `fallback_path` | 零命中或低对位时的降级路径（换接口 / 缩短关键词 / 切 OR / 换语义 / 超平台领域 fallback 外部渠道，见 §9.2） |\n\n**一争点多小查询**（[DEC-006] pt 4，硬约束）：\n\n- 每个 `query` 只承载**一个争点 + 一组决定性事实**。\n- `case` / `keyword` 接口的后端只支持**全局 AND/OR**，**不得**把多个争点或一长串事实压成嵌套布尔串。\n- 一个争点通常对应 2-4 条 query（不同接口、不同方向、正反各一），而不是 1 条巨查询。\n- `--expand` 全局 OR 仅作为单条 query **内部**的改写手段保留兼容，不再作为案件检索主路径。\n\n## 6. 检索前门禁（pre-door gate）\n\n信息不足时按\"最小必要\"处理，不得空跑查询，也不得一次性追问十几个问题：\n\n| 情形 | 处理 |\n|---|---|\n| 事实不足但**不影响查询方向**（如赔偿具体数额未定） | 在 brief 标注假设继续，不影响命题与查询生成 |\n| 主体 / 行为链条 / 待解决问题缺失到**会改变检索路径** | 只补问会改变检索路径的最关键问题（**最多 3 个核心**，通常含\"合同/法律关系类型+违约形态\"或\"当事人角色\"），其余标注假设继续 |\n| 完全无法判断争点（用户只说\"帮我查相关案例\"） | 触发最小补问：合同/法律关系类型 + 诉求方向；不补问不生成 query_matrix |\n| 明确法条名+条号 / 明确案号 / 纯概念问答 | **不启动本流程**，直接走接口速查 |\n\n补问结果回填 brief 后再继续；补问不超过 **1 轮**——**1 轮 = 1 次交互回合**（不限制该回合内问几个，但单回合最多 3 个会改变检索路径的核心问题），**不得套用 5 字段争点识别表的全字段逐一追问**（那是案件研判输入表，不是补问清单）；仍不足则按假设推进并标注 `待补充`。\n\n## 7. 何时不启动本流程（边界）\n\n- 用户给出明确法条名 + 条号 → `detail`。\n- 用户给出明确案号 → `case-detail --ah`。\n- 用户问\"XX 法怎么规定的\"且无案件事实 → `search`。\n- 用户问\"关于 XX 的法律条文\" → `keyword`。\n- 以上属\"简单检索\"，直接走 [`SKILL.md` 接口速查](../SKILL.md#接口速查)，不产出 research_brief。\n\n只要用户描述了事实结构、争议焦点、诉讼立场，或问\"类似案件怎么判\"\"能不能主张 XX\"\"对方抗辩怎么办\"——即触发本流程。\n\n## 8. 近邻案型排除（must_not_match）\n\n近邻陷阱 = 主题、案由或行业相近，但**主体角色、行为链条或决定性事实**不同，混入会污染主要依据。brief 必须在查询前显式写出 `must_exclude_neighbor_types`（由本案事实推导，**不预设特定法律领域的清单**），并映射到对应 query 的 `exclusion_criteria`。\n\n识别方向（非穷举，按本案事实判断，不列举具体案型）：\n\n- **请求权基础不同**：主题相近但落入不同规范路径（主体身份 / 客体 / 行为要件不同），各路径要件不能互替。\n- **主体角色不同**：同一主题下行为主体身份不同，导致责任路径或注意义务标准不同。\n- **行为链条/决定性事实不同**：主题或行业相近，但关键事实缺失或不同，不能直接类推。\n\n**`must_exclude_neighbor_types` 写法**：每项写**一个独立近邻案型**（不合并多项），并表述具体到\"为什么排除\"（缺哪个要件 / 主体 / 事实），便于复核；`key_exclusions` 置顶摘要同样逐项独立。\n\n对位复核时，命中近邻案型应标 `LOW` 或 `MISMATCH`，不得纳入主要依据。\n\n## 9. 接口路由规则（按机制，不按\"统一搜索\"抽象）\n\n基于已知后端能力（完整审计见 Task-002，本节为当前已知能力的路由）：\n\n| 检索目标 | 首选接口 | 理由 |\n|---|---|---|\n| 规范发现（\"XX 的法律规定\"） | `search`（法条向量） | 语义匹配，广覆盖概念关联 |\n| 精确核法（已知法条名+条号） | `detail` | 直接定位，无歧义 |\n| 关键词精确 + 效力/日期筛选 | `keyword` | 字面 AND/OR + 结构化过滤 |\n| 事实结构类案（\"类似案件怎么判\"） | `case-semantic`（案例向量） | 长事实结构语义匹配，关键词会丢事实 |\n| 裁判用语 / 援引法条 / 案由复检 | `case`（结构化字段） | `--ay`/`--fxgc`/`--yyft`/`--jbdw` 精确过滤 |\n| 标杆案例对标 | 先 `case-semantic`（事实骨架），再 `case` 结构化复检 | 见 [`02-typical-workflows.md`](02-typical-workflows.md) 场景 5 |\n\n**硬约束**：\n\n- `case` 关键词默认放 4-6 个高信息密度词，不构造后端无法表达的长 AND（[DEC-002]、[DEC-006] pt 4）。\n- `case` 一轮零命中 ≠ \"无类案\"：立即切 `case-semantic` 或缩短关键词换 OR 复检（[DEC-002]）。\n- 后端 `score`/`_score` 只在**同一接口同一查询内部**作排序信号，不跨查询、不跨接口、不替代法律对位度。\n\n### 9.1 字段归属接口速查表（防 filter 误挂）\n\nfilter 必须挂在**真正支持它**的接口上，否则会被忽略或报错（实测 worker 易把案例语义字段误挂到案例关键词）。下表以 `scripts/yd_search.py` 源码为权威（`case` 子命令定义见源码 `add_parser(\"case\")`，`case-semantic` 见 `add_parser(\"case-semantic\")`）：\n\n| filter | `case` 关键词 | `case-semantic` | `search`/`keyword` 法条 |\n|---|:---:|:---:|:---:|\n| `--ay`/`--fxgc`/`--yyft`/`--jbdw`/`--ah`/`--ajlb`/`--title` | ✓ | ✗ | ✗ |\n| `--wenshu-type`/`--fayuan` | ✗ | ✓ | ✗ |\n| `--wszl` | ✓ | ✓ | ✗ |\n| `--cj`（法院层级） | ✗ | ✓ | ✗ |\n| `--jarq-start`/`--jarq-end`（结案日期） | ✓ | ✓ | ✗ |\n| `--sxx`/`--effect1`/`--fgmc`（法条时效/效力/法规名称） | ✗ | ✗ | ✓ |\n| `--province`/`--xzqh-p` | ✓ | ✓ | ✗ |\n| `--authority-only` | ✓ | ✓ | ✗ |\n\n易错点提醒：\n\n- **`--wenshu-type`（案件类型，如民事案件）属于 `case-semantic`**，不要挂到 `case` 关键词（`case` 用 `--ajlb` 表达案件类别，无 `--wenshu-type`）。\n- **`--ay`/`--fxgc`/`--yyft`（案由/分析过程/援引法条）属于 `case` 关键词**，`case-semantic` 不支持——想用这些结构化字段精确复检就切到 `case`。\n- **`--jarq-start/end` 两个案例接口都支持**（源码确认），可放心用于日期范围。\n- 法条接口（`search`/`keyword`）的 `--sxx`/`--effect1` 不得挪到案例接口。\n\n**硬校验**：用 `scripts/validate-query-filters.py <research-plan.json>` 自动校验 filter×interface 合法性（退出码 0 合法 / 1 有违规，可接 CI 或 pre-commit hook）。单条 query 可用 `--query '{\"interface\":\"case\",\"filters\":{...}}'`。字段表与本节一致，以 `yd_search.py` 各 subparser 为权威。\n\n### 9.2 平台覆盖边界意识\n\n元典开放平台法源以**民商事 / 刑事**为主，案例库含民事 / 刑事 / 行政案件分类（`--wenshu-type`）。但**部分领域的法源覆盖可能有限**：行政诉讼法 / 行政处罚法 / 行政复议法、市场监督管理等部门规章、国家赔偿、部分专项法规等。案件检索时若本案主要落入这些领域，必须**显式标注平台边界**，不得用民商事法源 / 案例强行替代（避免误导）：\n\n- 在 brief 顶层标注 `platform_coverage_note`：说明哪些法源 / 案例元典可能覆盖不足（如\"《行政诉讼法》/ 处罚程序规章覆盖可能有限\"）。\n- 相关 query 的 `fallback_path` 指明替代渠道：先试 `detail` 接口按法条名查（元典若收录），未命中则提示用户需外部专门检索（如国家法律法规数据库 flk.npc.gov.cn、北大法宝、中国裁判文书网）。\n- 案例侧仍可用 `case-semantic` / `case --wenshu-type 行政案件` 查行政案例（元典案例库有该分类），但**法条层面**的行政法覆盖需单独验证，不要假设与民商法同等完整。\n- 该字段是**对用户透明的边界声明**，不是跳过检索的借口——能查的仍照常查，查不到的如实标注并给替代渠道。\n\n> 该意识由评测 R6 发现并固化：worker 在行政诉讼场景自发产出 `platform_coverage_note` + fallback，被 judge 评为\"通用方法的高阶工具边界意识\"。\n\n## 10. 策略与法律检索解耦（[DEC-006] pt 6）\n\n`economical` / `balanced` / `aggressive` 只控制**调用预算与深度**（试几条 query、是否自动跑语义+关键词双检索、是否自动拉 case-detail），**不得**改变：\n\n- 争点识别与要件拆解；\n- 接口路由与字段适配；\n- 对位度门槛（HIGH/MEDIUM/LOW/MISMATCH）；\n- 反向检索与近邻排除。\n\n## 11. 对位度标签（结果复核）\n\n| 标签 | 含义 |\n|---|---|\n| `HIGH` | 法律问题相同，主体关系、行为链条、决定性事实基本覆盖，可作主要类案/主要法源 |\n| `MEDIUM` | 法律问题相同，但缺一项决定性事实或程序背景不同，仅作辅助 |\n| `LOW` | 仅主题/行业/案由相近，不能直接支撑核心结论 |\n| `MISMATCH` | 争点、主体角色、行为模式或裁判命题不同，应排除 |\n\n首轮结果按此标签复核；只有诊断出偏差原因（接口误选 / 表达不适配 / 近邻混入）后，才允许扩展查询或换接口。\n\n## 12. 机器可读导出骨架（Task-004 预留）\n\n为支持 Agent Eval Lab 与人工复盘，案件检索建议导出以下结构（字段稳定，不绑定特定评测平台格式）：\n\n```json\n{\n  \"research_brief\": { /* §3 字段 */ },\n  \"propositions\": [ /* §4 */ ],\n  \"queries\": [ /* §5 */ ],\n  \"results\": [\n    { \"result_id\": \"\", \"backend_score\": null, \"relevance_label\": \"HIGH|MEDIUM|LOW|MISMATCH\",\n      \"include\": true, \"reason\": \"\" }\n  ],\n  \"conclusion_links\": [\n    { \"conclusion\": \"\", \"proposition_id\": \"\", \"query_id\": \"\", \"result_ids\": [] }\n  ],\n  \"run_meta\": { \"skill_version\": \"\", \"strategy_version\": \"\", \"model\": \"\", \"live\": false, \"credits\": 0 }\n}\n```\n\n脱敏要求：导出对象不得包含未脱敏案件全文、API Key 或 live 响应原文；冻结响应的版本策略见 Task-004。\n\nFile v1.8.7:scripts/MANIFEST.json\n\n{\n  \"version\": \"1.7.5\",\n  \"files\": [\n    \"SKILL.md\",\n    \"README.md\",\n    \"CHANGELOG.md\",\n    \"templates/legal-research-report.md\",\n    \"scripts/yd-run\",\n    \"scripts/yd_search.py\",\n    \"scripts/updater.py\",\n    \"scripts/.env.example\",\n    \"references/06-enterprise-portrait.md\",\n    \"references/01-keyword-expansion.md\",\n    \"references/05-mcp-workflow.md\",\n    \"references/04-report-design-notes.md\",\n    \"references/03-report-consolidation.md\",\n    \"references/02-typical-workflows.md\",\n    \"endpoints/01-law-vector-search.md\",\n    \"endpoints/02-law-keyword-search.md\",\n    \"endpoints/03-law-detail.md\",\n    \"endpoints/04-case-semantic-search.md\",\n    \"endpoints/05-case-keyword-search.md\",\n    \"endpoints/06-case-keyword-search-authority.md\",\n    \"endpoints/07-case-detail.md\",\n    \"endpoints/08-regulation-search.md\",\n    \"endpoints/09-regulation-detail.md\",\n    \"endpoints/10-enterprise-search.md\",\n    \"endpoints/11-enterprise-detail.md\",\n    \"endpoints/12-hall-detect.md\",\n    \"endpoints/13-enterprise-search-lightweight.md\",\n    \"endpoints/14-enterprise-base-info.md\",\n    \"endpoints/15-enterprise-aggregation-summary.md\",\n    \"endpoints/16-enterprise-out-invest.md\",\n    \"endpoints/17-enterprise-brand.md\",\n    \"endpoints/18-enterprise-patent.md\",\n    \"endpoints/19-enterprise-soft-right.md\",\n    \"endpoints/20-enterprise-works-right.md\",\n    \"endpoints/21-enterprise-icp.md\",\n    \"endpoints/22-enterprise-change-info.md\",\n    \"endpoints/23-enterprise-writ-agg.md\",\n    \"endpoints/24-enterprise-writ-list.md\",\n    \"endpoints/25-enterprise-court-session-notice.md\",\n    \"endpoints/26-enterprise-court-notice.md\",\n    \"endpoints/27-enterprise-executions.md\",\n    \"endpoints/28-enterprise-executed-person.md\",\n    \"endpoints/29-enterprise-frozen-equity.md\",\n    \"endpoints/30-enterprise-punishment.md\",\n    \"endpoints/31-enterprise-pledge.md\",\n    \"endpoints/32-enterprise-guaranty.md\",\n    \"endpoints/33-enterprise-abnormal-operation.md\",\n    \"endpoints/34-enterprise-corporate-tax.md\",\n    \"endpoints/35-enterprise-serious-illegal.md\",\n    \"endpoints/MANIFEST.json\"\n  ]\n}\n\nFile v1.8.7:CHANGELOG.md\n\n# 变更日志\n\n## [1.8.7] - 2026-08-05\n\n### 文档完善\n\n- README 删除已废弃的「自更新机制」章节（自更新代码此前已移除，消除供应链审计项）\n- SKILL.md 新增「数据留存与隐私警示」：明示 archive 落盘、CWD 报告副本、外部传输至 open.chineselaw.com、敏感内容最小化建议\n- SKILL.md 新增「所需权限」：网络/文件读写/环境变量/本地执行范围声明\n\n### 说明\n\n纯文档改动，不影响脚本与接口功能。企业信息与幻觉检测接口保持不变。\n\n## [1.8.6] - 2026-08-02\n\n### 新增（references/07，评测 R6 发现回写）\n\n- **§9.2 平台覆盖边界意识**：元典法源以民商/刑事为主，行政诉讼/部门规章/国家赔偿等覆盖可能有限。案件落入这些领域时，brief 标注 `platform_coverage_note` + 相关 query 的 `fallback_path` 指明外部渠道（flk.npc.gov.cn / 北大法宝 / 裁判文书网），不得用民商法源强行替代。源自评测 R6（worker 自发产出该意识，Claude judge 评为「通用方法的高阶工具边界意识」）。\n- §5 `fallback_path` 字段补充「超平台领域 fallback 外部渠道」选项。\n\n纯文档，不影响脚本/接口。\n\n## [1.8.5] - 2026-08-02\n\n### 改进（references/07 通用化 + 补通用方法）\n\n按「skill 是通用法律检索方法论、不固化特定领域案例」原则（用户反馈），清理具体案型举例 + 补通用方法。纯文档，不影响脚本/接口。\n\n**补通用方法**：\n\n- §3.2 新增「已有法律分析报告」三栏规则：`prior_report_sources` 拆为 `report_facts` / `report_conclusions` / `hypotheses_to_verify`；区分「报告援引的法源」（客观引用，不降级）vs「报告作者的法律判断」（主观，必降级为待验证假设）。\n- §6 明确「1 轮 = 1 次交互回合，单回合最多 3 个会改变检索路径的核心问题」，不得套用 5 字段争点识别表全字段追问。\n- §3 `legal_elements.covered` 用法：`covered=false` 要件必须落 `facts_to_supplement`，非装饰字段。\n- §8 `must_exclude_neighbor_types` 写法：每项一个独立近邻 + 表述排除理由。\n- §3 `prior_report_sources` 指向修正（见 §3.2，原误指 §5 query_matrix）。\n\n**通用化（删特定法律领域举例）**：\n\n- §8 删典型近邻清单（原列商业秘密/竞业、商业诋毁/名誉权、达人/商家、高管/员工等具体案型），改为通用识别方向（请求权基础不同 / 主体角色不同 / 行为链条或决定性事实不同）。\n- §3.1 `role_comparison_matrix` 示例从「高管/普通员工」泛化为「主体角色 A/B」占位。\n- §3 / §3.2 删具体举例（客户名单、特定法条号等），改为通用描述。\n\n## [1.8.4] - 2026-08-02\n\n### 新增\n\n- **`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 误挂）的工程闭环。\n\n## [1.8.3] - 2026-08-02\n\n### 移除\n\n- **移除内置自动更新机制**：删除 `scripts/updater.py`（SkillUpdater，334 行）、`yd_search.py` 中每次检索自动联网检测远程版本的触发逻辑、`check-update` / `do-update` 子命令，以及 `SKILL.md` 的「版本更新」段。原机制每次检索时联网检测新版（≥7 天一次）且 `do-update` 会联网下载覆盖本地文件——移除以消除自动联网与文件覆盖的风险。更新改由 `git pull` / `clawhub-sync` 等外部通道处理。\n- 清理死代码：`yd_search.py` 中无任何引用的 `CURRENT_VERSION = \"1.7.5\"` 常量。\n\n## [1.8.2] - 2026-08-02\n\n### 新特性 — 检索机制感知型法律研究中间层（DEC-006 / Task-001）\n\n把 Skill 从\"元典 API/MCP 包装 + 归档 + 报告\"升级为\"检索机制感知型法律研究中间层\"：案件检索（综合检索 / 类案对标 / 已有报告复盘）默认先完成\"理解案件 — 形成命题 — 查询矩阵 — 对位复核\"，再调用接口。\n\n- 新增 [`references/07-research-middleware.md`](references/07-research-middleware.md)：\n  - `research_brief` schema：争点 / 要件 / 决定性事实 / 待补事实 / 必须排除的近邻案型 / 已有报告来源，外加 `key_decisive_facts` 与 `key_exclusions` 两个**置顶短摘要**（便于快速复核）。\n  - `propositions` schema：每条单一判断，区分规范 / 事实结构 / 裁判规则 / 反向；每个 decisive 争点至少 1 条正向 + 1 条反向。\n  - `query_matrix` schema：一争点一查询、单一接口；带 `exclusion_criteria` 与零命中 `fallback_path`；`case` 关键词不构造后端无法表达的长 AND。\n  - 多主体角色案件 `role_comparison_matrix`（如高管竞业禁止 vs 普通员工保密义务）。\n  - **已有法律分析报告使用规则**：区分 `report_facts` / `report_conclusions` / `hypotheses_to_verify` 三栏，把报告结论降级为待验证假设，不跳过轻量研判。\n  - 前置门禁（最小必要补问，最多 1 轮）、近邻案型排除清单、HIGH/MEDIUM/LOW/MISMATCH 对位度标签、机器可读导出骨架。\n  - §9 接口路由按真实后端机制选择 + **§9.1 字段归属接口速查表**（防 filter 误挂，以 `scripts/yd_search.py` 源码为权威）。\n- `SKILL.md` 新增精简\"检索机制感知主流程（案件检索默认）\"6 步段，详细 schema 放入单层 reference（主文档不膨胀）；简单法条 / 案号 / 纯概念检索仍直接走接口速查，**不启动本流程**。\n- `--expand` 全局 OR 行为保留兼容，仅降级为查询矩阵内部的一条改写手段（不再作案件检索默认主路径）。\n\n### 评测（agent-eval-lab，`evals/yuandian-middleware-260802`）\n\n- candidate 97 vs baseline 82.75（6 场景无 API 检索规划盲评）。\n- 跨家族 3 judge（glm-5.2 / DeepSeek-V3.2 / Qwen3.5-35B）：2/3 判 candidate 胜；case-03「已有报告三栏区分」三家一致 candidate pass / baseline fail。\n- worker n=2：关键结构决策 100% 可复现。\n- 接口路由教义经 `yd_search.py` 源码验证一致（含确认 `case-semantic` 支持 `--jarq-start/end`）。\n\n## [1.7.5] - 2026-07-20\n\n### 新特性\n\n- **归档按检索目的分文件夹**：新增 `YD_PROJECT` 环境变量，AI/用户在研究任务开始时设定（如 `export YD_PROJECT=0713-商标在先使用权`），该任务所有检索自动归到 `archive/<project>/` 一个文件夹，便于追溯；未设时按日期 `archive/YYYYMMDD/` 兜底，不再平铺根目录。**缓存查重全局跨 project 生效**（`_archive_lookup` 改 `rglob`），同一问题在不同任务命中已有归档、不重复消耗积分。`archive-list` 输出带 project 相对路径、按时间倒序。\n- **默认剔除办案无关条目（五类效力级别）**：`search` / `keyword` / `regulation` 默认过滤 `effect1 ∈ {行业/团体规范, 地方律协规定, 行政机关工作文件, 党内法规, 军事法规规章}`（律协指引、课题公告/答复函、党纪规定、军队规定等——非法律渊源或与一般民商事/刑事办案无关）。基于 archive 实测样本定位字段特征；footer 提示剔除数量，涉党纪/涉军等特殊案件加 `--keep-industry` 保留。`archive/` 原始数据完整保留。\n\n### 修复\n\n- 修复 skill 根目录堆积检索副本问题：`_archive_write_report` 写 CWD 副本前判断 `cwd == SKILL_ROOT`，相等则跳过（主归档仍在 `archive/`，不丢数据）。根因是 `yd-run` 捕获的 `YD_USER_CWD` 若等于 skill 根，副本直接堆根目录。\n- 清理 skill 根目录 22 个历史检索副本 `.md`（`archive/` 内均有同名备份，逐个 diff 一致）。\n- 新增 skill 根 `.gitignore`，兜底忽略检索副本文件名模式，防止未来污染 git status。\n\n## [1.7.4] - 2026-06-15\n\n### 修复\n\n- 修复 `keyword` / `case` / `regulation` 的 `--expand` 自动 OR 逻辑：参数解析层不再把 `--search-mode` 默认填成 `and`，处理函数可正确识别\"用户未显式指定\"并在扩展检索时切换为 OR。\n- 修复 `references/03-report-consolidation.md` 与 `references/02-typical-workflows.md` 中重命名后的旧文件链接。\n- 统一版本号：`SKILL.md`、`scripts/yd_search.py`、`scripts/MANIFEST.json`、根 `README.md` 与 marketplace 条目同步到 `1.7.4`。\n\n### 改进\n\n- 强化案件综合分析和标杆类案场景的检索执行约束：第一轮优先 `case-semantic`，关键词检索只保留 4-6 个高信息密度词，零命中时必须改用语义检索或 OR 复检。\n- 补充 marketplace 条目，便于插件市场按当前版本发现和分发 `yuandian-law-search`。\n- 调整 `.gitignore` 例外，使本技能的 `DECISIONS.md` 与 `TASKS.md` 可纳入版本控制。\n\n## [1.7.3] - 2026-06-15\n\n### 修正（v1.7.1 反思有误）\n\n- v1.7.1 在\"争议焦点识别\"小节中错误地将二分法归入\"用户原始争议焦点\"——二分法实际是 AI **检索之后**才提炼出来的分析工具，不是用户最初提问的内容\n- 真实情况：用户最初就已明确给出关键事实要素和法条抓手，**第一轮**应该直接用这些用户原话作为检索词，不需要先等\"检索后再提炼二分法\"\n- **修正 `references/02-typical-workflows.md`**：\n  - 删除\"关键区分点\"字段（避免诱导 AI 自己去找二分法）\n  - 新增\"用户已明确的论点\"字段（强调直接用用户原话作检索词）\n  - 关键提示新增\"二分法是结果不是起点\"\n- 路径修正：因 v1.7.2 重命名 `00-typical-workflows.md` → `02-typical-workflows.md`，编辑目标相应更新\n\n## [1.7.2] - 2026-06-15\n\n### 整理\n- **`references/` 序号重编**：6 个 `00-*.md` 工作流指南改为 `01-06` 顺序编号（按 SKILL.md Reference 文档索引的引用顺序），便于按序阅读和稳定排序\n  - `01-keyword-expansion.md`（基础：关键词怎么扩）\n  - `02-typical-workflows.md`（应用：典型场景）\n  - `03-report-consolidation.md`（专题：报告整合）\n  - `04-report-design-notes.md`（专题：报告设计原理）\n  - `05-mcp-workflow.md`（专题：MCP 协同）\n  - `06-enterprise-portrait.md`（专题：企业全息画像）\n  - 同步更新 `SKILL.md`、`scripts/MANIFEST.json` 中所有引用\n\n### 简化\n- **\"新接口策略矩阵\"小节去重话术**：`SKILL.md` 调用策略章节尾部表格本身保留（hall-detect / enterprise-search / enterprise-base+summary / enterprise-list 四个接口在三种策略下的具体行为），仅去掉\"新/旧接口\"区分话术——所有接口统一视为同一层级，按其分层套用对应策略\n\n## [1.7.1] - 2026-06-15\n\n### 工作流补充（基于近期案件检索偏差复盘）\n\n- **`references/00-typical-workflows.md` 新增 2 节强制工作流**：\n  - **争议焦点识别优先场景**：第一轮检索前必须先填 5 字段识别表（行为主体 / 角色定位 / 行为模式 / 关键区分点 / 抗辩点），避免直接按泛化法律概念展开检索\n  - **标杆案例对标检索场景**：用户第一轮提供标杆案例时，必须提取其\"事实结构骨架\"作为查询模板，并用\"对标度评分\"过滤命中案例\n- **核心理念沉淀**：\n  - 行业术语 > 法律术语（用户用什么行业说法就用什么行业说法作检索词，不要预先翻译成法律术语）\n  - 二分法思维：争议焦点背后往往有关键二分，二分点决定结论方向\n  - 主动找反面案例：搜完正面后专门搜一次\"被告不担责\"\"被告无过错\"等反面表述，反面案例能反向锚定争议焦点的关键区分\n- **典型反例**：错搜泛化法律概念 → 命中与案情不匹配的偏差案型；正搜基于用户原话 + 行业术语描述事实结构（语义检索）→ 命中对位案\n\n## [1.7.0] - 2026-06-15\n\n### 重构\n- **目录结构重构**（按 skill-lint 审查建议解耦）：\n  - 35 个 API 端点文档（`01-law-vector-search.md` ~ `35-enterprise-serious-illegal.md`）从 `references/` 迁入新建的 `endpoints/`\n  - `references/MANIFEST.json` 同步迁入 `endpoints/MANIFEST.json`\n  - `references/` 仅保留工作流指南，新增 6 个 `00-*.md`：\n    - `00-keyword-expansion.md` — 关键词扩展三原则、`--expand` 参数、分阶段检索、策略兼容性\n    - `00-typical-workflows.md` — 五大场景 + AI 向用户反馈的 8 条原则\n    - `00-enterprise-portrait.md` — 企业信息类 4 个接口（`enterprise-search` / `base` / `summary` / `list`）的完整用法与 20 类 `--type` 维度\n    - `00-report-consolidation.md` — consolidate 调用方式、项目子目录组织、目标目录归档规范\n    - `00-report-design-notes.md` — 7 节\"结论先行\"的设计动机、反例、节号逻辑、质量要求\n    - `00-mcp-workflow.md` — 元典 MCP 接入配置、Agent 三步法、ingest 子命令、模式选型表\n- `templates/legal-research-report.md` 保留并明确为可维护的模板参考（`yd_search.py` 当前仍用代码内 f-string 渲染，模板作为格式约定）\n- SKILL.md 由 809 行压到 494 行（-39%）：4 个大章节（关键词扩展、典型工作流、企业全息、MCP 协同）拆到 references/，7 节报告与目标目录归档保留短引用\n\n### 发布治理\n- `scripts/MANIFEST.json` 同步升到 1.7.0，完整覆盖 endpoints/ + references/ + templates/ 全部文件（之前仅列了 11 个 references，updater 实际未更新 12-35）\n- README.md 中 `references/01~11-*.md` 改为 `endpoints/01~35-*.md`，`MANIFEST.txt` 改为 `MANIFEST.json`\n- \"版本演进\"表格新增 v1.7.0 行\n\n## [1.6.1] - 2026-06-15\n\n### 改进\n- 优化 `consolidate` 法律检索报告模板：从旧的\"检索结果在前、结论在后\"调整为 7 节结论先行结构，先呈现一句话定性、核心依据速查、风险与后续行动，再展示分析、方法、检索结果和明细。\n- 新增 `templates/legal-research-report.md`，沉淀可维护的法律检索报告模板，便于后续单独调整报告结构。\n- `consolidate` 报告头新增检索主体、检索平台、项目包等可核查信息；第七节检索明细改用可回溯本地链接。\n- `consolidate` 新增 `--risks` 和 `--next-actions` 参数，用于填充结论区的风险与后续行动；`--conclusion` 未传时保留明确补写提示。\n\n### 修复\n- 修复 `consolidate` 将 per-call JSON 移入项目子目录后，后续分组读取仍指向旧路径，导致法律依据/案例/法规分组可能丢失的问题。\n\n### 文档完善\n- SKILL.md 同步更新 7 节报告结构、质量要求、调用方式和目标目录归档口径。\n\n## [1.6.0] - 2026-06-11\n\n### 战略转向\n- 元典官方已发布 MCP（https://open.chineselaw.com/mcp-config），3 个 servers：yuandian-law / yuandian-case / yuandian-company\n- 本 skill 价值从\"API 包装\"转向\"**归档 + 法律检索报告生成**\"——agent 用 MCP 调数据，本 skill 负责沉淀\n- v1.6.0 起，本 skill 同时支持两种调用模式：\n  1. **直接 API 模式**（原有 `search/case/...` 子命令，保留兼容）\n  2. **MCP 协同模式**（新增 `ingest` 子命令，消费 MCP 输出 JSON）\n\n### 新增\n- **`ingest` 子命令**（v1.6.0 核心）：\n  - 用法：`yd-run ingest --query \"<Q>\" --endpoint \"/open/<E>\" --input <file.json>`（或 stdin pipe）\n  - 必填：`--query`、`--endpoint`\n  - 可选：`--cost`（默认 \"10 积分\"）、`--no-report`、`--no-cwd-report`\n  - 消费外部 JSON（来自 MCP 或其他源），路由到对应 formatter，**走与直接 API 相同的归档 + .md 流程**\n  - 归档记录额外加 `\"ingest\": true` 标记，便于区分数据来源\n- **`INGEST_ROUTING` 表**（36 个 endpoint 覆盖）：\n  - 法条 4 个（law_vector_search / rh_ft_search / rh_ft_detail + 1）\n  - 法规 2 个（rh_fg_search / rh_fg_detail）\n  - 案例 4 个（case_vector_search / rh_ptal_search / rh_qwal_search / rh_case_details）\n  - 企业主接口 4 个（rh_enterpriseSearch / rh_company_info / rh_company_detail / rh_enterpriseBaseInfo）\n  - 企业分项列表 21 个（OutInvest/Brand/Patent/SoftRight/WorksRight/Icp/ChangeInfo/WritAgg/WritList/CourtSessionNotice/CourtNotice/Executions/ExecutedPerson/FrozenEquity/Punishment/Pledge/Guaranty/AbnormalOperation/CorporateTax/SeriousIllegal/AnnualReport）\n  - 特殊 2 个（hall_detect 用对应 formatter；rh_enterpriseAggregationSummary 用 raw JSON 包装）\n  - 未知 endpoint 走 raw JSON 兜底（包装为 ```json ... ``` 代码块）\n- **`.mcp.json.example` 模板**（skill 根目录）：\n  - 3 个 yuandian-* MCP servers 配置（law/case/company）\n  - `Authorization: Bearer ${YD_API_KEY}` 鉴权\n  - 用户复制为 `.mcp.json` 后让 Claude Code / Cursor / Codex 等客户端自动加载\n- **企业分项列表 endpoint 自动 label 推断**（如 `/open/rh_enterpriseOutInvest` → \"对外投资\"），无需 --label 参数\n\n### 改进\n- SKILL.md 新增\"MCP 协同工作流\"章节，描述 agent 如何同时使用 `mcp__yuandian__*` 工具 + `yd-run ingest` + `yd-run consolidate`\n- INGEST_ROUTING 路由表覆盖元典 MCP 暴露的全部 24 个数据 tools（不含 2 个 meta tools）\n\n### 架构关系\n```\nagent 调用流程:\n1. mcp__yuandian_law__yuandian_law_vector_search(\"违约金\")  ← MCP 直接调元典\n2. 把响应 JSON 喂给 yd-run ingest                             ← 本 skill 归档\n3. 多次 ingest 后, yd-run consolidate --project \"...\"        ← 生成 6 节法律检索报告\n```\n\n向后兼容：原有 `search/case/detail/...` 直接 API 子命令完全保留，YD_API_KEY 用户可继续用。\n\n## [1.5.1] - 2026-06-10\n\n### 新增\n- **consolidate 项目子目录组织**（用户反馈：一次研究任务会产生多个 .json + .md，平铺在 archive/ 不便按项目查找）\n  - 新增 `--project \"<name>\"` 参数（可选，默认从 `--title` 自动 slugify）\n  - consolidate 创建 `archive/<project>/` 子目录作为\"项目包\"\n  - per-call .md 从 CWD **复制**到项目子目录（CWD 保留工作副本）\n  - per-call .json 从 `archive/` 根目录**移动**到项目子目录（archive 根保持清爽，不重复）\n  - 法律检索报告双写：`archive/<project>/<ts>_法律检索报告.md`（项目包）+ CWD（工作副本）\n  - 报告末尾\"项目包\"标识：`> 项目包：archive/<project>/`\n  - 重复运行 consolidate 同一项目：idempotent，文件已在子目录则跳过移动/复制\n\n### 改进\n- consolidate 报告头增加项目包路径引用，方便用户定位\n\n## [1.5.0] - 2026-06-10\n\n### 新增\n- **session-level 法律检索报告**（`consolidate` 子命令）：把多次检索的 per-call 报告汇总成一份标准结构的法律检索报告\n  - 调用方显式传 `--case` / `--strategy` / `--analysis` 三个核心字段（AI 填）\n  - `--include` 必填，逗号分隔的查询子串，明确指定\"本次任务范围\"（不取最近 N 条）\n  - 6 节标准结构：案情简介 / 检索目的与问题 / 检索思路与方法 / 检索结果（4.1 法条 + 4.2 案例 + 4.3 法规 + 4.4 其他，按 endpoint 自动分组）/ 分析与判断 / 检索结论\n  - 附录\"本次检索明细\"表格：时间/检索词/接口/积分/[md](CWD相对路径)·[json](file://绝对路径)\n  - 4.4 其他：自动收纳未归类到法律/案例/法规的检索（如 hall-detect、enterprise-*）\n  - `--purpose` 可选：不传则基于检索词自动推断\n  - `--conclusion` 可选：不传则提示\"详见第五节\"\n  - `--output` 可选：默认 `<cwd>/<ts>_法律检索报告.md`\n\n### 改进\n- per-call .md 报告元信息移除\"检索接口\"字段（用户反馈：API 端点太技术化，不属于报告内容）\n\n### 架构关系\n- per-call .md = 检索明细（数据底稿，每次检索自动写 archive + CWD）\n- session 报告 = 主交付物（法律检索报告，按任务粒度由 AI 触发 consolidate 生成）\n- session 报告的\"检索明细表\"链接到 per-call .md，整套形成完整溯源链\n\n## [1.4.0] - 2026-06-10\n\n### 新增\n- 检索报告 .md 自动落盘：每次实际检索（cache miss 时）落盘两份结构化 Markdown 报告\n  - `archive/<ts>_<query>.md`：与 archive JSON 配对，技能内部归档\n  - `<CWD>/<ts>_<query>.md`：用户运行命令时的工作目录副本，方便附卷/分享\n- 报告模板：元信息（时间/接口/关键词/积分/原始数据路径/工作目录副本）+ 检索结果（与 stdout 一致）+ 引用来源（按类型分组）+ 数据来源声明\n- 复用现有 5 个 formatter（format_law_results / format_case_results / format_regulation_results / format_enterprise_results / format_hall_detect_results）填充\"检索结果\"段，零行为变化\n- 新增 `--no-report` 全局 flag：跳过 .md 报告生成（archive + CWD），仅写 archive JSON\n- 新增 `--no-cwd-report` 全局 flag：仅跳过 CWD 副本，仍写 archive/ 报告\n- 调用结束后 footer 追加报告路径提示（archive + CWD，CWD 失败时不显示第二行）\n- CWD 副本写入失败时 stderr 警告但不中断（archive 副本是主落点，best-effort 容错）\n\n### 改进\n- `api_post` / `api_get` 返回值从 2-tuple 改为 3-tuple `(result, cached, archive_path)`，让 cmd_* 能拿到 archive 路径以驱动报告生成\n- 5 个有自定义成本的端点（hall-detect 50、enterprise-search 1、enterprise-base 10、enterprise-summary 10、enterprise-list 5/10）准确把成本传递到报告元信息头\n\n## [1.3.4] - 2026-05-27\n\n### 新增\n- 新增 `scripts/yd-run` 干净环境运行入口，默认清理 Codex/代理相关环境变量后再调用 `yd_search.py`。\n- 新增 `scripts/yd-run --network-check` 网络预检，用于无积分消耗地检查 `open.chineselaw.com` 和 `ydzk.chineselaw.com` 的 DNS 与 TLS 连通性。\n\n### 文档完善\n- SKILL.md 和 README.md 改为推荐使用 `scripts/yd-run`，降低 Codex 网络沙箱、PATH 漂移和代理环境变量对元典检索的影响。\n\n## [1.3.3] - 2026-05-13\n\n### 新增\n- archive 归档记录新增 `source_urls` 字段：自动提取/构造法条、案例、法规、企业的来源链接，方便后续检索时提供核实出处\n- `backfill-urls` 子命令：一次性回填现有 archive 的 source_urls（已回填 36 个文件）\n\n### 改进\n- 法条语义检索（law_vector_search）和案例语义检索（case_vector_search）等无 URL 的接口，根据 fgid/scid 自动构造完整链接\n- 法条详情（rh_ft_detail）、案例关键词（rh_ptal_search）等返回相对 URL 的接口，归档时自动转为完整 URL\n\n## [1.3.2] - 2026-05-10\n\n### 新增\n- 新接口策略矩阵：为 hall-detect、enterprise-search、enterprise-base/summary、enterprise-list 四类新增接口补充 balanced/economical/aggressive 三种策略下的具体行为指导\n- 企业尽调工作流：enterprise-search → enterprise-base → enterprise-summary → enterprise-list 四步尽调流程\n- 幻觉检测工作流：引用识别 → AI 建议 → 用户确认 → hall-detect 检测 → 结果展示\n- 企业风险排查工作流：enterprise-summary 总览 → enterprise-list 深挖高风险项 → 风险画像汇总\n\n### 改进\n- enterprise-list 子命令新增策略感知默认 size：economical 模式默认 10 条，aggressive 模式默认 50 条，balanced 保持 30 条\n\n## [1.3.1] - 2026-05-10\n\n### 新增\n- 关键词扩展检索：`keyword`、`case`、`regulation` 子命令新增 `--expand` 参数，支持传入逗号分隔的扩展关键词，自动追加到原始查询并以 OR 模式检索\n- 分阶段检索指引：SKILL.md 新增「关键词扩展与分阶段检索」章节，说明 AI 应如何主动扩展法律概念、执行广撒网+精提炼的两阶段检索\n- 扩展方向提示：检索完成后 AI 应向用户建议可能相关的扩展检索方向\n- 策略兼容矩阵：明确关键词扩展行为与 balanced/economical/aggressive 三种策略的兼容关系\n\n## [1.3.0] - 2026-05-10\n\n### 新增\n- 适配 24 个元典开放平台新接口（从 11 个扩展至 35 个）\n- 新增 5 个子命令：\n  - `hall-detect`：法规/法条/案例幻觉检测（50 积分）\n  - `enterprise-search`：企业轻量检索（1 积分），返回候选列表\n  - `enterprise-base`：企业基本信息查询（含股东、核心成员、分支机构）\n  - `enterprise-summary`：企业聚合总览\n  - `enterprise-list`：企业分项列表查询，支持 20 种类型（对外投资、商标、专利、涉诉文书、行政处罚等）\n- 新增 `format_hall_detect_results`：幻觉检测结果格式化（法规存在性、语义比对、案例核实）\n- 新增 `format_enterprise_list_results`：企业分项列表通用格式化函数\n- 新增 24 个 Reference 文档（12-35），覆盖幻觉检测和企业全息画像系列接口\n- 所有新子命令支持 `--no-cache` 选项\n- MANIFEST.json 全部 35 个接口标记为已适配（`adapted` 字段移除，改为完整元数据）\n- SKILL.md 接口清单从 11 个扩展至 35 个，新增幻觉检测和企业全息画像使用说明\n\n### 改进\n- 接口分层新增\"专项\"层（hall-detect）\n- 附属接口层扩展：新增 enterprise-search·enterprise-base·enterprise-summary·enterprise-list\n- 积分消耗说明从\"每次 10 积分\"更新为\"1-50 积分（视接口而定）\"\n- CLI 帮助示例新增 5 个新子命令用法\n\n## [1.2.1] - 2026-05-10\n\n### 改进\n- 新增 `references/MANIFEST.json`：接口清单元数据文件，记录全部 11 个已适配接口的端点、子命令、分层和分类信息\n- MANIFEST.json 包含 `check_history` 字段，记录每次平台接口排查的时间、方法和结论\n- 排查元典开放平台（2026-05-10）：通过 Playwright 浏览器实际访问接口广场，发现平台从 11 个 API 扩展到了 35 个，新增 24 个未适配接口（1 个幻觉检测 + 23 个企业信息），已记录到 MANIFEST.json，待后续适配\n\n## [1.2.0] - 2026-05-09\n\n### 新增\n- 可配置检索策略（`YD_STRATEGY`）：balanced（均衡，默认）、economical（省钱）、aggressive（激进）\n- `strategy` 子命令：显示当前检索策略\n- 策略感知的默认返回数量：economical 模式下语义检索默认 20 条，aggressive 模式下关键词检索默认 20 条\n\n### 改进\n- SKILL.md 调用策略章节重构为三策略矩阵，清晰区分接口确认要求、案例详情触发方式、补充检索行为\n- .env.example 新增 YD_STRATEGY 配置说明\n\n## [1.1.1] - 2026-04-18\n\n### 修复\n\n- `datetime` import 在 updater.py 重构时被误删，导致归档函数 `NameError`\n- `detail` 子命令：API 返回单个 dict 而非列表，格式化函数崩溃\n- `case` 子命令：API 返回 `{total, lst}` 结构而非裸列表，需从 `data.lst` 提取\n- `format_law_results` 兼容 `ftmc`/`tid` 字段（detail 端点返回）\n- `format_case_results` 兼容 `cprq` 字段（关键词检索返回的裁判日期）\n- `format_enterprise_results` 兼容中文字段名（`企业名称`、`统一社会信用代码`、`企业类型` 等）\n- 移除 `_print_footer` 中的缓存命中提示，归档重新定位为\"历史检索记录\"\n- 新增 `archive-list` 子命令，支持按关键词浏览历史检索记录\n- Reference 文档修正：05 案例关键词检索补充 `cprq`/`type`/`url`/`llm_content` 字段、07 案例详情补充返回结构、10 企业检索补充中英文字段映射\n- 权威案例关键词检索（06）返回结构说明更新为 `{total, lst}` 包装格式\n\n## [1.1.0] - 2026-04-17\n\n### 重大变更\n- SKILL.md 大幅精简（~260 行 → ~170 行），策略内容抽取至 `references/00-*.md`\n- Reference 文件按前缀分层：`00-` 策略指南、`01-11` API 端点文档\n\n### 新增\n- 策略指南：检索模式选择指南（`references/00-retrieval-mode-guide.md`）\n- 策略指南：接口优先级与选择规则（`references/00-interface-priority.md`）\n- 积分节约策略合并回 SKILL.md，核心理念调整为\"正确性优先于积分节约\"\n- SKILL.md 新增\"积分消耗模式\"小节，明确案例检索的两阶段消耗（摘要 10 积分 + 详情 10 积分/个）\n- `case` 子命令新增 `--fxgc`、`--yyft`、`--ft-search-mode` 参数\n- `format_law_results` 新增输出字段：发布日期、发布部门、发文字号、二级效力级别\n- Reference 文件补充响应结构文档（02-law-keyword-search 完整 20 字段）\n- `archive/.gitkeep` 确保归档目录不会被 git 忽略\n- `check-update` 新增最近提交记录展示（通过 Atom feed，不依赖 GitHub API）\n- `check-update` 新增 CHANGELOG 差异展示（读取远程 CHANGELOG.md 中本地版本之后的变更）\n- `do-update` 子命令：仅下载本 skill 目录下的文件更新，不碰其他目录和 .env/归档\n- 更新逻辑拆分为通用模块 `scripts/updater.py`（`SkillUpdater` 类），可被其他 skill 复用\n- `MANIFEST.txt` 移至 `scripts/` 目录，列出所有可更新文件\n\n### 修复\n- `--rewrite-flag` 参数使用 `type=bool` 导致任何字符串均为 `True` 的 bug，改为 `store_true`/`--no-rewrite`\n- 移除所有旧 API（aiapi.ailaw.cn）中文字段名 fallback 死代码\n- SKILL.md 注册地址更新为 `https://open.chineselaw.com`\n\n## [1.0.0] - 2026-04-17\n\n### 重大变更\n- API 平台迁移：从旧平台 (`aiapi.ailaw.cn:8319`) 迁移至开放平台 (`open.chineselaw.com`)\n- 认证方式从 URL 查询参数改为 `X-API-Key` 请求头\n- 语义检索请求体改为嵌套结构（`fatiao_filter` / `wenshu_filter`）\n- 语义检索响应格式更新（`extra.fatiao` / `extra.wenshu`）\n- 接口文档拆分为独立文件（`references/01~11-*.md`）\n\n### 新增\n- 法规关键词检索（`regulation` 子命令）\n- 法规详情查询（`regulation-detail` 子命令）\n- 案例详情查询（`case-detail` 子命令）\n- 企业名称检索（`enterprise` 子命令）\n- 企业详情查询（`enterprise-detail` 子命令）\n- 语义检索新增 `--rewrite-flag` 和 `--return-num` 参数\n- `raw` 子命令新增 `--get` 和 `--no-cache` 选项\n- 归档机制：每次 API 调用自动归档至 `archive/`，相同查询命中归档不消耗积分\n- 接口优先级分层：核心接口（5个）、扩展接口（4个）、附属接口（2个）\n\n### 改进\n- 案例关键词检索拆分为普通案例和权威案例两个端点\n- 格式化函数兼容新旧字段名\n- 超时时间从 30 秒提升至 60 秒\n\n## [0.3.1] - 2026-04-07\n\n### 改进\n\n- 移除「与其他技能配合」章节，保持技能描述独立聚焦\n\n## [0.3.0] - 2026-04-06\n\n### 改进\n\n- Front Matter 规范化：补充 homepage、author、version 字段\n\n## [0.2.0] - 2026-04-05\n\n### 改进\n- skill name 从 `yd-law-search` 改为 `yuandian-law-search`，提升辨识度\n- 目录同步重命名为 `yuandian-law-search`\n- 标题从\"元典法条检索\"改为\"元典法条与案例检索\"，准确反映 API 覆盖范围\n- 许可证从 CC BY-NC-SA 4.0 改为 MIT\n- 前置要求新增注册登录指引（账号注册 → API Key 创建 → 配置 .env → 验证连接）\n\n## [0.1.0] - 2026-04-03\n\n### 设计缘由\n- 元典法条检索 API 提供了法律条文和案例的语义/关键词检索能力，适合封装为 Skill 供法律分析场景使用。\n\n### 思路演进\n1. 分析 API 文档，梳理 5 个端点的功能和参数\n2. 设计统一的 CLI 工具，用子命令区分不同检索模式\n3. 输出格式化为 Markdown，方便 AI 直接引用\n\n### 新增\n- 初始版本，封装 5 个 API 端点\n- 支持法条语义检索、关键词检索、详情检索\n- 支持案例关键词检索、语义检索\n- 输出 Markdown 格式化\n- 支持原始 JSON 调试输出\n\nArchive v1.8.6: 53 files, 113377 bytes\n\nFiles: CHANGELOG.md (31627b), endpoints/01-law-vector-search.md (2620b), endpoints/02-law-keyword-search.md (3804b), endpoints/03-law-detail.md (675b), endpoints/04-case-semantic-search.md (2073b), endpoints/05-case-keyword-search.md (2640b), endpoints/06-case-keyword-search-authority.md (1044b), endpoints/07-case-detail.md (1141b), endpoints/08-regulation-search.md (1031b), endpoints/09-regulation-detail.md (569b), endpoints/10-enterprise-search.md (1014b), endpoints/11-enterprise-detail.md (606b), endpoints/12-hall-detect.md (2877b), endpoints/13-enterprise-search-lightweight.md (1102b), endpoints/14-enterprise-base-info.md (794b), endpoints/15-enterprise-aggregation-summary.md (584b), endpoints/16-enterprise-out-invest.md (643b), endpoints/17-enterprise-brand.md (618b), endpoints/18-enterprise-patent.md (619b), endpoints/19-enterprise-soft-right.md (658b), endpoints/20-enterprise-works-right.md (656b), endpoints/21-enterprise-icp.md (624b), endpoints/22-enterprise-change-info.md (650b), endpoints/23-enterprise-writ-agg.md (660b), endpoints/24-enterprise-writ-list.md (646b), endpoints/25-enterprise-court-session-notice.md (652b), endpoints/26-enterprise-court-notice.md (642b), endpoints/27-enterprise-executions.md (680b), endpoints/28-enterprise-executed-person.md (666b), endpoints/29-enterprise-frozen-equity.md (646b), endpoints/30-enterprise-punishment.md (647b), endpoints/31-enterprise-pledge.md (649b), endpoints/32-enterprise-guaranty.md (648b), endpoints/33-enterprise-abnormal-operation.md (672b), endpoints/34-enterprise-corporate-tax.md (646b), endpoints/35-enterprise-serious-illegal.md (654b), endpoints/MANIFEST.json (10975b), LICENSE.txt (1090b), README.md (9170b), references/01-keyword-expansion.md (4133b), references/02-typical-workflows.md (9640b), references/03-report-consolidation.md (5655b), references/04-report-design-notes.md (2361b), references/05-mcp-workflow.md (3150b), references/06-enterprise-portrait.md (2011b), references/07-research-middleware.md (19580b), scripts/MANIFEST.json (2081b), scripts/validate-query-filters.py (7970b), scripts/yd_search.py (94978b), skill-card.md (3368b), SKILL.md (27756b), templates/legal-research-report.md (1613b), _meta.json (138b)\n\nFile v1.8.6:SKILL.md\n\n---\nname: yuandian-law-search\nhomepage: https://github.com/cat-xierluo/legal-skills\nauthor: 杨卫薪律师（微信ywxlaw）\nversion: \"1.8.6\"\nlicense: MIT\ndescription: 元典法条与案例检索。本技能应在需要查询中国法律法规条文、检索相关案例、为法律分析提供数据支撑时使用。\n---\n\n# 元典法条与案例检索\n\n通过元典开放平台 API 检索中国法律法规条文和案例。**每次 API 调用消耗 1-50 积分**（视接口而定）。所有检索结果会自动归档到本地，方便后续回溯。\n\n## 前置要求（每次调用前自动检测）\n\n每次使用本技能前，**必须先执行以下检测流程**，确认 API Key 已就绪：\n\n### 检测步骤\n\n1. **检测 `.env` 文件**：检查 `scripts/.env` 是否存在\n2. **检测 API Key**：读取文件中 `YD_API_KEY` 的值，确认非空且不是占位符 `your-api-key-here`\n3. **若检测失败**，向用户提示以下引导信息并终止：\n\n```\n⚠️ 元典 API Key 未配置。请按以下步骤获取并配置：\n\n1. 注册/登录：访问 https://open.chineselaw.com ，使用手机号注册\n2. 创建 API Key：登录后在个人中心创建 Key\n3. 配置密钥：将 Key 填入以下文件\n\n   scripts/.env\n   ─────────────\n   YD_API_KEY=sk-你的密钥\n   # YD_STRATEGY=balanced\n   ─────────────\n\n每次调用消耗 10 积分，需在平台充值。\n配置完成后重新发起检索即可。\n```\n\n4. **若检测通过**，继续执行用户请求的检索命令\n\n### 检测命令\n\n```bash\n# 检测 .env 文件和 API Key\nif [ -f \"scripts/.env\" ]; then\n  KEY=$(grep '^YD_API_KEY=' scripts/.env | cut -d'=' -f2)\n  if [ -n \"$KEY\" ] && [ \"$KEY\" != \"your-api-key-here\" ]; then\n    echo \"API Key 已就绪\"\n  else\n    echo \"API Key 未配置\"\n  fi\nelse\n  echo \".env 文件不存在\"\nfi\n\n# 读取检索策略\nSTRATEGY=$(grep '^YD_STRATEGY=' scripts/.env 2>/dev/null | cut -d'=' -f2)\necho \"当前策略：${STRATEGY:-balanced}\"\n```\n\n## 网络环境与推荐调用入口\n\n默认使用 `scripts/yd-run` 执行检索，而不是直接调用底层 `yd_search.py`。`yd-run` 会以干净环境启动 Python：清除 Codex/代理相关环境变量，保留 `HOME`、`PATH`、语言环境、`YD_API_KEY`、`YD_STRATEGY`，并继续读取 `scripts/.env` 和 `archive/` 缓存。\n\n```bash\nscripts/yd-run search \"正当防卫的限度\" --sxx 现行有效\n```\n\n若遇到 `nodename nor servname provided, or not known` 或其他网络错误，先执行无积分消耗的网络检查：\n\n```bash\nscripts/yd-run --network-check\n```\n\n注意：`yd-run` 只能避免 Codex 进程环境变量、代理变量和 PATH 漂移造成的影响；如果 Codex 本身以网络沙箱启动，或系统代理/VPN 接管 DNS，子进程仍会受到系统级网络策略影响。终端 Codex 应使用 `--sandbox danger-full-access --ask-for-approval never` 启动。\n\n## 检索机制感知主流程（案件检索默认）\n\n当用户描述事实结构、争议焦点、诉讼立场，或问\"类似案件怎么判\"\"能不能主张 XX\"\"对方抗辩怎么办\"时，**先完成案件检索主流程，再调用接口**（DEC-006）。简单法条/案号/纯概念检索（`detail` / `case-detail` / 单条 `search`）不启动本流程，直接看下方接口速查。\n\n1. **轻量案件研判** → 产出检索简报（争点、要件、决定性事实、待补事实、必须排除的近邻案型、已有报告来源）。\n2. **派生检索命题** → 每个命题只验证一项判断，区分规范 / 事实结构 / 裁判规则 / 反向；每个 decisive 争点至少 1 条正向 + 1 条反向。\n3. **派生查询矩阵** → 一争点一查询、单一接口；案例关键词只放 4-6 个高信息密度词，不构造后端无法表达的长 AND。\n4. **小样本试检** → 1-2 条命题先验证接口与表达是否有效。\n5. **对位复核** → 按 HIGH / MEDIUM / LOW / MISMATCH 复核；只有诊断出偏差原因（接口误选 / 表达不适配 / 近邻混入）后才扩展查询或换接口。\n6. **正式检索** → 结论—依据—查询可追溯报告。\n\n信息不足时按\"最小必要\"补问（最多 1 轮，只问会改变检索路径的最关键问题），不空跑查询；事实不足但不影响查询方向的，标注假设继续。\n\n完整字段定义、接口路由规则、近邻案型排除清单、前置门禁判定与机器可读导出骨架见：[`references/07-research-middleware.md`](references/07-research-middleware.md)。\n\n> 下方「接口速查」是执行第 3 步查询矩阵时\"按机制选接口\"的依据，不是检索的起点。\n\n## 接口速查\n\n本技能共 35 个接口，分为四层。选择规则：\n\n1. 用户问\"XX法怎么规定的\" → 先用 `search` 语义检索\n2. 用户问\"关于XX的法律条文\" → 用 `keyword` 关键词检索\n3. 用户问\"民法典第XX条\" → 用 `detail` 精确获取\n4. 用户给出明确案由/关键词并要求精确筛选案例 → 用 `case` 关键词检索（默认普通案例）\n5. 用户描述事实结构、争议焦点或问\"类似案件怎么判\" → 优先用 `case-semantic` 语义检索\n6. 用户要求更深入了解某案例 → 提醒用户将消耗积分，确认后用 `case-detail`\n7. 用户要求企业背景调查 → 先用 `enterprise-search` 定位，再用 `enterprise-base`/`enterprise-summary` 获取详情\n8. 用户要求查询企业分项信息（涉诉、商标、专利等） → 用 `enterprise-list --type TYPE`\n9. 用户要求检测文本中法规/案例是否准确 → 用 `hall-detect`\n\n**核心接口（默认使用）：** `search` · `keyword` · `detail` · `case` · `case-semantic`\n**扩展接口（需确认）：** `regulation` · `regulation-detail` · `case-detail` · `case --authority-only`\n**附属接口（仅限明确要求）：** `enterprise` · `enterprise-detail` · `enterprise-search` · `enterprise-base` · `enterprise-summary` · `enterprise-list`\n**专项接口（仅限明确要求）：** `hall-detect`\n\n## 调用策略\n\n读取 `scripts/.env` 中的 `YD_STRATEGY` 配置（默认 `balanced`）。三种策略决定了 AI 的接口使用、确认流程和补充检索行为。\n\n**用户的明确指令始终优先于策略默认行为。**\n\n### 通用规则（所有策略共享）\n\n每次 API 调用消耗 1-50 积分（视接口而定）。以下规则不受策略影响：\n\n1. **必须调用 API**：需要引用具体法条文号 / 需要确认时效性 / 用户明确要求检索 / 案例检索 / AI 对自身记忆不确定\n2. **可以不调用**：纯概念性问题 / 对话中已检索过相同内容 / 用户未要求查找 / 用户明确说不需要查\n3. **积分消耗模式**：大部分接口每次 5-10 积分，幻觉检测 50 积分，轻量企业检索 1 积分。法条检索通常一次足够。案例检索是两阶段消耗（摘要 10 + 详情 每个 10）\n4. **接口分层**：核心（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）\n\n### 均衡策略（balanced，默认）\n\n即当前\"正确性优先\"策略，不改变现有行为。\n\n- **核心接口**：直接使用，无需确认\n- **扩展接口**：调用前告知用户将消耗积分，等待确认\n- **附属接口**：仅当用户明确要求时使用\n- **case-detail**：先展示摘要，由用户主动选择感兴趣的案例后再调用\n- **补充检索**：不主动运行语义+关键词双检索，选择最合适的一种\n- **积分报告**：每次检索后说明消耗\n\nArchive v1.7.5: 52 files, 101554 bytes\n\nFiles: CHANGELOG.md (25493b), endpoints/01-law-vector-search.md (2620b), endpoints/02-law-keyword-search.md (3804b), endpoints/03-law-detail.md (675b), endpoints/04-case-semantic-search.md (2073b), endpoints/05-case-keyword-search.md (2640b), endpoints/06-case-keyword-search-authority.md (1044b), endpoints/07-case-detail.md (1141b), endpoints/08-regulation-search.md (1031b), endpoints/09-regulation-detail.md (569b), endpoints/10-enterprise-search.md (1014b), endpoints/11-enterprise-detail.md (606b), endpoints/12-hall-detect.md (2877b), endpoints/13-enterprise-search-lightweight.md (1102b), endpoints/14-enterprise-base-info.md (794b), endpoints/15-enterprise-aggregation-summary.md (584b), endpoints/16-enterprise-out-invest.md (643b), endpoints/17-enterprise-brand.md (618b), endpoints/18-enterprise-patent.md (619b), endpoints/19-enterprise-soft-right.md (658b), endpoints/20-enterprise-works-right.md (656b), endpoints/21-enterprise-icp.md (624b), endpoints/22-enterprise-change-info.md (650b), endpoints/23-enterprise-writ-agg.md (660b), endpoints/24-enterprise-writ-list.md (646b), endpoints/25-enterprise-court-session-notice.md (652b), endpoints/26-enterprise-court-notice.md (642b), endpoints/27-enterprise-executions.md (680b), endpoints/28-enterprise-executed-person.md (666b), endpoints/29-enterprise-frozen-equity.md (646b), endpoints/30-enterprise-punishment.md (647b), endpoints/31-enterprise-pledge.md (649b), endpoints/32-enterprise-guaranty.md (648b), endpoints/33-enterprise-abnormal-operation.md (672b), endpoints/34-enterprise-corporate-tax.md (646b), endpoints/35-enterprise-serious-illegal.md (654b), endpoints/MANIFEST.json (10975b), LICENSE.txt (1090b), README.md (9170b), references/01-keyword-expansion.md (4133b), references/02-typical-workflows.md (9640b), references/03-report-consolidation.md (5655b), references/04-report-design-notes.md (2361b), references/05-mcp-workflow.md (3150b), references/06-enterprise-portrait.md (2011b), scripts/MANIFEST.json (2081b), scripts/updater.py (13463b), scripts/yd_search.py (96011b), skill-card.md (2832b), SKILL.md (26375b), templates/legal-research-report.md (1613b), _meta.json (138b)\n\nArchive v1.7.4: 54 files, 101506 bytes\n\nFiles: CHANGELOG.md (23837b), DECISIONS.md (2671b), endpoints/01-law-vector-search.md (2620b), endpoints/02-law-keyword-search.md (3804b), endpoints/03-law-detail.md (675b), endpoints/04-case-semantic-search.md (2073b), endpoints/05-case-keyword-search.md (2640b), endpoints/06-case-keyword-search-authority.md (1044b), endpoints/07-case-detail.md (1141b), endpoints/08-regulation-search.md (1031b), endpoints/09-regulation-detail.md (569b), endpoints/10-enterprise-search.md (1014b), endpoints/11-enterprise-detail.md (606b), endpoints/12-hall-detect.md (2877b), endpoints/13-enterprise-search-lightweight.md (1102b), endpoints/14-enterprise-base-info.md (794b), endpoints/15-enterprise-aggregation-summary.md (584b), endpoints/16-enterprise-out-invest.md (643b), endpoints/17-enterprise-brand.md (618b), endpoints/18-enterprise-patent.md (619b), endpoints/19-enterprise-soft-right.md (658b), endpoints/20-enterprise-works-right.md (656b), endpoints/21-enterprise-icp.md (624b), endpoints/22-enterprise-change-info.md (650b), endpoints/23-enterprise-writ-agg.md (660b), endpoints/24-enterprise-writ-list.md (646b), endpoints/25-enterprise-court-session-notice.md (652b), endpoints/26-enterprise-court-notice.md (642b), endpoints/27-enterprise-executions.md (680b), endpoints/28-enterprise-executed-person.md (666b), endpoints/29-enterprise-frozen-equity.md (646b), endpoints/30-enterprise-punishment.md (647b), endpoints/31-enterprise-pledge.md (649b), endpoints/32-enterprise-guaranty.md (648b), endpoints/33-enterprise-abnormal-operation.md (672b), endpoints/34-enterprise-corporate-tax.md (646b), endpoints/35-enterprise-serious-illegal.md (654b), endpoints/MANIFEST.json (10975b), LICENSE.txt (1090b), README.md (9170b), references/01-keyword-expansion.md (4133b), references/02-typical-workflows.md (9640b), references/03-report-consolidation.md (5655b), references/04-report-design-notes.md (2361b), references/05-mcp-workflow.md (3150b), references/06-enterprise-portrait.md (2011b), scripts/MANIFEST.json (2081b), scripts/updater.py (13463b), scripts/yd_search.py (91734b), skill-card.md (3036b), SKILL.md (25177b), TASKS.md (1022b), templates/legal-research-report.md (1613b), _meta.json (138b)\n\nArchive v1.6.0: 45 files, 81341 bytes\n\nFiles: CHANGELOG.md (17007b), LICENSE.txt (1090b), README.md (7418b), references/01-law-vector-search.md (2620b), references/02-law-keyword-search.md (3804b), references/03-law-detail.md (675b), references/04-case-semantic-search.md (2073b), references/05-case-keyword-search.md (2640b), references/06-case-keyword-search-authority.md (1044b), references/07-case-detail.md (1141b), references/08-regulation-search.md (1031b), references/09-regulation-detail.md (569b), references/10-enterprise-search.md (1014b), references/11-enterprise-detail.md (606b), references/12-hall-detect.md (2877b), references/13-enterprise-search-lightweight.md (1102b), references/14-enterprise-base-info.md (794b), references/15-enterprise-aggregation-summary.md (584b), references/16-enterprise-out-invest.md (643b), references/17-enterprise-brand.md (618b), references/18-enterprise-patent.md (619b), references/19-enterprise-soft-right.md (658b), references/20-enterprise-works-right.md (656b), references/21-enterprise-icp.md (624b), references/22-enterprise-change-info.md (650b), references/23-enterprise-writ-agg.md (660b), references/24-enterprise-writ-list.md (646b), references/25-enterprise-court-session-notice.md (652b), references/26-enterprise-court-notice.md (642b), references/27-enterprise-executions.md (680b), references/28-enterprise-executed-person.md (666b), references/29-enterprise-frozen-equity.md (646b), references/30-enterprise-punishment.md (647b), references/31-enterprise-pledge.md (649b), references/32-enterprise-guaranty.md (648b), references/33-enterprise-abnormal-operation.md (672b), references/34-enterprise-corporate-tax.md (646b), references/35-enterprise-serious-illegal.md (654b), references/MANIFEST.json (10975b), scripts/MANIFEST.json (666b), scripts/updater.py (13463b), scripts/yd_search.py (87533b), skill-card.md (3210b), SKILL.md (34006b), _meta.json (138b)\n\nArchive v1.5.1: 45 files, 76713 bytes\n\nFiles: CHANGELOG.md (14034b), LICENSE.txt (1090b), README.md (7418b), references/01-law-vector-search.md (2620b), references/02-law-keyword-search.md (3804b), references/03-law-detail.md (675b), references/04-case-semantic-search.md (2073b), references/05-case-keyword-search.md (2640b), references/06-case-keyword-search-authority.md (1044b), references/07-case-detail.md (1141b), references/08-regulation-search.md (1031b), references/09-regulation-detail.md (569b), references/10-enterprise-search.md (1014b), references/11-enterprise-detail.md (606b), references/12-hall-detect.md (2877b), references/13-enterprise-search-lightweight.md (1102b), references/14-enterprise-base-info.md (794b), references/15-enterprise-aggregation-summary.md (584b), references/16-enterprise-out-invest.md (643b), references/17-enterprise-brand.md (618b), references/18-enterprise-patent.md (619b), references/19-enterprise-soft-right.md (658b), references/20-enterprise-works-right.md (656b), references/21-enterprise-icp.md (624b), references/22-enterprise-change-info.md (650b), references/23-enterprise-writ-agg.md (660b), references/24-enterprise-writ-list.md (646b), references/25-enterprise-court-session-notice.md (652b), references/26-enterprise-court-notice.md (642b), references/27-enterprise-executions.md (680b), references/28-enterprise-executed-person.md (666b), references/29-enterprise-frozen-equity.md (646b), references/30-enterprise-punishment.md (647b), references/31-enterprise-pledge.md (649b), references/32-enterprise-guaranty.md (648b), references/33-enterprise-abnormal-operation.md (672b), references/34-enterprise-corporate-tax.md (646b), references/35-enterprise-serious-illegal.md (654b), references/MANIFEST.json (10975b), scripts/MANIFEST.json (666b), scripts/updater.py (13463b), scripts/yd_search.py (75486b), skill-card.md (3121b), SKILL.md (31034b), _meta.json (138b)\n\nArchive v1.3.4: 214 files, 1809543 bytes\n\nFiles: archive/20260419_152314_民法典.json (1639b), archive/20260419_152346_买卖合同纠纷_违约损害赔偿.json (74779b), archive/20260419_152523_正当防卫超过必要限度如何认定.json (67643b), archive/20260419_152551_数据安全.json (16786b), archive/20260419_153540_刑法.json (1750b), archive/20260419_153603_股权代持协议的效力如何认定.json (106891b), archive/20260419_153641_个人信息保护的法律规定.json (13281b), archive/20260427_143420_公司股权纠纷_股东资格确认_股权转让_代持.json (142900b), archive/20260506_145941_刑事案件管辖权_异地执法_趋利性执法_违规异地管辖.json (67801b), archive/20260506_145942_网络犯罪案件管辖_犯罪地_被害人所在地_网络接入地.json (57802b), archive/20260506_145944_侵犯知识产权犯罪_管辖_犯罪地_销售地_服务器所在地.json (66477b), archive/20260506_145956_趋利性执法_异地执法_专项监督.json (4287b), archive/20260506_145959_侵犯知识产权刑事案件_犯罪地_立案侦查_管辖连接点.json (66366b), archive/20260506_150000_侵犯著作权罪_管辖权异议_异地管辖_移送管辖.json (65101b), archive/20260506_150009_公安机关_异地办案协作_六个严禁.json (70657b), archive/20260506_150011_禁止逐利执法_七项规定.json (71611b), archive/20260506_150013_侵犯知识产权_刑事案件_法律适用_管辖_犯罪地.json (539b), archive/20260506_150021_侵犯知识产权刑事案件_适用法律_意见_犯罪地_立案侦查.json (533b), archive/20260506_150023_跨省_涉企犯罪_管辖规定_公安机关.json (40018b), archive/20260506_150033_办理侵犯知识产权刑事案件适用法律若干问题的意见_犯罪地.json (62460b), archive/20260506_151043_最高人民法院、最高人民检察院关于办理侵犯知识产权刑事案件适用法律若干问题的解释.json (2735b), archive/20260506_151044_最高人民法院、最高人民检察院关于办理侵犯知识产权刑事案件适用法律若干问题的解释.json (27475b), archive/20260506_151054_最高人民法院、最高人民检察院关于办理侵犯知识产权刑事案件适用法律若干问题的解释.json (2169b), archive/20260506_151056_最高人民法院、最高人民检察院关于办理侵犯知识产权刑事案件适用法律若干问题的解释.json (2044b), archive/20260506_151108_最高人民法院、最高人民检察院关于办理侵犯知识产权刑事案件适用法律若干问题的解释.json (2394b), archive/20260506_151109_最高人民法院、最高人民检察院关于办理侵犯知识产权刑事案件适用法律若干问题的解释.json (2259b), archive/20260506_151110_最高人民法院、最高人民检察院关于办理侵犯知识产权刑事案件适用法律若干问题的解释.json (2298b), archive/20260506_151111_最高人民法院、最高人民检察院关于办理侵犯知识产权刑事案件适用法律若干问题的解释.json (3022b), archive/20260506_151250_侵犯著作权罪_管辖权异议_异地管辖_犯罪地_移送管辖_侵犯知识产权犯罪.json (53960b), archive/20260506_151327_犯罪地_管辖权_被告人居住地_不在受诉法院辖区_无管辖权_移送.json (96029b), archive/20260506_152028_（2025）兵02...","readmeExcerpt":"Skill: 元典法条与案例检索 Owner: cat-xierluo Summary: 元典法条与案例检索。本技能应在需要查询中国法律法规条文、检索相关案例、为法律分析提供数据支撑时使用。 Tags: latest:1.8.8 Version history: v1.8.8 | 2026-08-05T13:37:51.237Z | user 修复：validate-query-filters 动态自省默认关闭（消除动态代码执行误报）；SKILL.md 占位符调整（消除密钥字面量误报） v1.8.7 | 2026-08-05T13:29:12.502Z | user 文档完善：README 删除已废弃自更新章节；SKILL.md 新增数据留存与隐私警示、所需权限声明（纯文档，不影响功能） v1.8.6 | 2026-08-04T07:53:59.346Z | user v1.8.6 升级（原 1.7.5） v1.7.5 | 20","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"⚠️ 元典 API Key 未配置。请按以下步骤获取并配置：\n\n1. 注册/登录：访问 https://open.chineselaw.com ，使用手机号注册\n2. 创建 API Key：登录后在个人中心创建 Key\n3. 配置密钥：将 Key 填入以下文件\n\n   scripts/.env\n   ─────────────\n   YD_API_KEY=sk-你的密钥(此处替换为真实 Key)\n   # YD_STRATEGY=balanced\n   ─────────────\n\n每次调用消耗 10 积分，需在平台充值。\n配置完成后重新发起检索即可。"},{"language":"bash","snippet":"# 检测 .env 文件和 API Key\nif [ -f \"scripts/.env\" ]; then\n  KEY=$(grep '^YD_API_KEY=' scripts/.env | cut -d'=' -f2-)\n  if [ -n \"$KEY\" ] && [ \"$KEY\" != \"your-api-key-here\" ]; then\n    echo \"API Key 已就绪\"\n  else\n    echo \"API Key 未配置\"\n  fi\nelse\n  echo \".env 文件不存在\"\nfi\n\n# 读取检索策略\nSTRATEGY=$(grep '^YD_STRATEGY=' scripts/.env 2>/dev/null | cut -d'=' -f2)\necho \"当前策略：${STRATEGY:-balanced}\""},{"language":"bash","snippet":"scripts/yd-run search \"正当防卫的限度\" --sxx 现行有效"},{"language":"bash","snippet":"scripts/yd-run --network-check"},{"language":"bash","snippet":"scripts/yd-run search \"正当防卫的限度\" --sxx 现行有效"},{"language":"bash","snippet":"scripts/yd-run keyword \"人工智能 监管\" \\\n  --effect1 法律 --sxx 现行有效 \\\n  --fbrq-start 2022-01-01 --fbrq-end 2026-03-01"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: yuandian-law-search\nhomepage: https://github.com/cat-xierluo/legal-skills\nauthor: 杨卫薪律师（微信ywxlaw）\nversion: \"1.8.8\"\nlicense: MIT\ndescription: 元典法条与案例检索。本技能应在需要查询中国法律法规条文、检索相关案例、为法律分析提供数据支撑时使用。\n---\n\n# 元典法条与案例检索\n\n通过元典开放平台 API 检索中国法律法规条文和案例。**每次 API 调用消耗 1-50 积分**（视接口而定）。所有检索结果会自动归档到本地，方便后续回溯。\n\n## 数据留存与隐私警示\n\n本技能在提供便利的同时会产生本地留存与外部传输，使用前请知悉：\n\n- **本地归档**：每次检索的原始响应与结构化报告会自动写入 `archive/`（按 `YD_PROJECT` 或日期归类），并默认在您运行命令的工作目录生产一份 `.md` 副本（便于附卷；当工作目录恰为 skill 根目录时自动跳过）。可用 `--no-report` 完全跳过、`--no-cwd-report` 仅跳过工作目录副本。这些文件可能包含案由、当事人、裁判文书正文等敏感内容，**请勿将其提交至公开仓库或随意分享**。\n- **外部传输**：检索请求与（如幻觉检测）待查文本会发送至元典开放平台 `open.chineselaw.com`。提交给 `hall-detect` 等接口的文本可能包含案卷事实、合同或客户信息，**建议先脱敏再提交**。平台侧的留存策略以其服务条款为准。\n- **敏感内容最小化**：案例文书、企业信息含个人或商业敏感数据，引用与归档时遵循\"最小必要\"原则，避免大段全文外泄。\n\n## 所需权限\n\n本技能运行需要以下本地能力，均限定在检索与归档目的内：\n\n- **网络访问**：仅访问元典开放平台 `open.chineselaw.com`（HTTPS），用于检索与归档查重。\n- **文件系统读写**：读取 `scripts/.env`（API Key）、`scripts/MANIFEST.json`；写入 `archive/` 与当前工作目录的报告副本（可经 `--no-report`/`--no-cwd-report` 关闭）。\n- **环境变量**：读取 `YD_API_KEY`（鉴权）、`YD_STRATEGY`/`YD_PROJECT`（检索策略与归类）等；`yd-run` 以干净环境启动 Python，仅保留必要变量。\n- **本地代码执行**：通过 `scripts/yd-run` 调用 Python 检索脚本；不安装第三方运行时、不执行自动更新。\n\n## 前置要求（每次调用前自动检测）\n\n每次使用本技能前，**必须先执行以下检测流程**，确认 API Key 已就绪：\n\n### 检测步骤\n\n1. **检测 `.env` 文件**：检查 `scripts/.env` 是否存在\n2. **检测 API Key**：读取文件中 `YD_API_KEY` 的值，确认非空且不是占位符 `your-api-key-here`\n3. **若检测失败**，向用户提示以下引导信息并终止：\n\n```\n⚠️ 元典 API Key 未配置。请按以下步骤获取并配置：\n\n1. 注册/登录：访问 https://open.chineselaw.com ，使用手机号注册\n2. 创建 API Key：登录后在个人中心创建 Key\n3. 配置密钥：将 Key 填入以下文件\n\n   scripts/.env\n   ─────────────\n   YD_API_KEY=sk-你的密钥(此处替换为真实 Key)\n   # YD_STRATEGY=balanced\n   ─────────────\n\n每次调用消耗 10 积分，需在平台充值。\n配置完成后重新发起检索即可。\n```\n\n4. **若检测通过**，继续执行用户请求的检索命令\n\n### 检测命令\n\n```bash\n# 检测 .env 文件和 API Key\nif [ -f \"scripts/.env\" ]; then\n  KEY=$(grep '^YD_API_KEY=' scripts/.env | cut -d'=' -f2-)\n  if [ -n \"$KEY\" ] && [ \"$KEY\" != \"your-api-key-here\" ]; then\n    echo \"API Key 已就绪\"\n  else\n    echo \"API Key 未配置\"\n  fi\nelse\n  echo \".env 文件不存在\"\nfi\n\n# 读取检索策略\nSTRATEGY=$(grep '^YD_STRATEGY=' scripts/.env 2>/dev/null | cut -d'=' -f2)\necho \"当前策略：${STRATEGY:-balanced}\"\n```\n\n## 网络环境与推荐调用入口\n\n默认使用 `scripts/yd-run` 执行检索，而不是直接调用底层 `yd_search.py`。`yd-run` 会以干净环境启动 Python：清除 Codex/代理相关环境变量，保留 `HOME`、`PATH`、语言环境、`YD_API_KEY`、`YD_STRATEGY`，并继续读取 `scripts/.env` 和 `archive/` 缓存。\n\n```bash\nscripts/yd-run search \"正当防卫的限度\" --sxx 现行有效\n```\n\n若遇到 `nodename nor servname provided, or not known` 或其他网络错误，先执行无积分消耗的网络检查：\n\n```bash\nscripts/yd-run --network-check\n```\n\n注意：`yd-run` 只能避免 Codex 进程环境变量、代理变量和 PATH 漂移造成的影响；如果 Codex 本身以网络沙箱启动，或系统代理/VPN 接管 DNS，子进程仍会受到系统级网络策略影响。终端 Codex 应使用 `--sandbox danger-full-access --ask-for-approval never` 启动。\n\n## 检索机制感知主流程（案件检索默认）\n\n当用户描述事实结构、争议焦点、诉讼立场，或问\"类似案件怎么判\"\"能不能主张 XX\"\"对方抗辩怎么办\"时，**先完成案件检索主流程，再调用接口**（DEC-006）。简单法条/案号/纯概念检索（`detail` / `case-detail` / 单条 `search`）不启动本流程，直接看下方接口速查。\n\n1. **轻量案件研判** → 产出检索简报（争点、要件、决定性事实、待补事实、必须排除的近邻案型、已有报告来源）。\n2. **派生检索命题** → 每个命题只验证一项判断，区分规范 / 事实结构 / 裁判规则 / 反向；每个 decisive 争点至少 1 条正向 + 1 条反向。\n3. **派生查询矩阵** → 一争点一查询、单一接口；案例关键词只"},{"path":"README.md","content":"# 元典法条与案例检索 (yuandian-law-search)\n\n通过 [元典开放平台](https://open.chineselaw.com) 检索中国法律法规条文和案例，为法律分析和研究提供数据支撑。\n\nv1.6.1 起，本 Skill 的核心交付能力从单次 API 包装扩展为\"检索归档 + 法律检索报告生成\"：多次检索后可用 `consolidate` 汇总为 7 节结论先行报告，适合律师内部复核、客户沟通和类案检索留痕。v1.7.4 修复关键词扩展的自动 OR 行为，并强化案件综合检索的语义优先策略。\n\n## 快速开始\n\n### 1. 获取 API Key\n\n访问 [open.chineselaw.com](https://open.chineselaw.com)，用手机号注册后在个人中心创建 API Key。每次调用消耗 10 积分，需在平台充值。\n\n### 2. 配置密钥\n\n将 API Key 填入 `scripts/.env`：\n\n```\nYD_API_KEY=sk-你的密钥\n```\n\n### 3. 执行检索\n\n```bash\nscripts/yd-run search \"正当防卫的限度\" --sxx 现行有效\n```\n\n`scripts/yd-run` 会用干净环境启动 Python，避免 Codex 进程环境、代理变量或 PATH 漂移影响元典接口访问。网络排查可先运行：\n\n```bash\nscripts/yd-run --network-check\n```\n\n### 4. 生成法律检索报告\n\n多次检索后，用 `consolidate` 生成主交付物。报告结构为：案情简介、检索目的与问题、检索结论、分析与判断、检索思路与方法、检索结果、检索明细。\n\n```bash\nscripts/yd-run consolidate \\\n  --title \"张某买卖合同违约金调整\" \\\n  --project \"case-2024-zhangsan\" \\\n  --case \"案情：...\" \\\n  --strategy \"检索思路：...\" \\\n  --analysis \"分析与判断：...\" \\\n  --conclusion \"一句话结论：...\" \\\n  --risks \"主要风险：...\" \\\n  --next-actions \"后续行动：...\" \\\n  --include \"违约金,逾期付款\"\n```\n\n## 设计理念：为什么这样设计这个 Skill\n\n### 背景\n\n元典开放平台提供 11 个 API 端点，覆盖法条、案例、法规、企业四个领域。**每次 API 调用消耗 10 积分**，这意味着一个\"检索 5 个案例并逐一查看详情\"的简单场景，实际消耗为 10 + 5×10 = 60 积分。\n\n因此，整个 Skill 的设计围绕一个核心问题：**如何在保证正确性的前提下，用最少的 API 调用完成任务？**\n\n### 原则一：正确性优先于积分节约\n\nAI 的记忆可能存在幻觉或过时。涉及法律条文的精确引用时，宁可多查一次，不可引用错误法条。\n\n**必须调用 API 的情况：**\n- 需要引用具体法条文号（AI 可能记错条文内容或条号对应）\n- 需要确认时效性（法律修订频繁，AI 训练数据可能已过时）\n- 用户明确要求检索\n- AI 对自身记忆不确定\n\n**可以不调用的情况：**\n- 纯概念解释（如\"什么是善意取得\"）\n- 对话中已检索过相同内容\n- 用户未要求查找\n\n### 原则二：三级接口分层\n\n不是所有接口都应该被同等对待。我们将 11 个端点分为三层：\n\n| 层级 | 接口 | 设计意图 |\n|------|------|----------|\n| **核心层**（5 个） | `search` · `keyword` · `detail` · `case` · `case-semantic` | 覆盖 90% 的日常法律检索需求，默认直接使用 |\n| **扩展层**（4 个） | `regulation` · `regulation-detail` · `case-detail` · `case --authority-only` | 非日常需求，调用前需告知用户额外积分消耗 |\n| **附属层**（2 个） | `enterprise` · `enterprise-detail` | 仅在用户明确要求企业信息时才使用 |\n\n这样设计是因为：法条语义检索（`search`）返回结果已包含法条全文，通常一次调用即可满足需求，无需再调 `detail`；而案例详情（`case-detail`）是额外消耗，必须让用户知情。\n\n### 原则三：语义检索优先\n\n每个领域提供语义和关键词两种检索模式，默认优先使用语义检索：\n\n| 模式 | 适用场景 | 典型返回量 |\n|------|----------|-----------|\n| **语义检索**（`search` / `case-semantic`） | 自然语言问题，不确定用什么关键词 | 45 条 |\n| **关键词检索**（`keyword` / `case`） | 明确关键词 + 需要精确筛选条件 | 10 条 |\n\n语义检索覆盖面更广，一次调用往往足够。只有当用户提供了明确关键词或需要日期/法院/级别等筛选条件时，才切换到关键词检索。\n\n### 原则四：本地缓存零成本\n\n脚本内置归档缓存机制：每次 API 调用的查询和响应会自动存入 `archive/` 目录，以 SHA-256 指纹匹配。相同查询自动命中缓存，**不消耗积分**。\n\n这意味着在同一个对话中多次讨论同一个法律问题时，只有第一次会产生积分消耗。\n\n### 六条积分节省策略\n\n这些策略写入了 SKILL.md，指导 AI 代理在调用时做出正确判断：\n\n1. **一查多用** — 一次检索结果充分引用，避免重复检索同一问题\n2. **优先语义检索** — `search` 返回最全面的结果，一次通常够用\n3. **避免法条链式调用** — 不要先 `search` 再逐条 `detail`，语义检索已含全文\n4. **案例详情谨慎调用** — 先用摘要筛选 1-2 个最相关案例，再调 `case-detail`\n5. **善用筛选参数** — `--sxx 现行有效`、`--effect1 法律` 等缩小范围，避免无效结果\n6. **信任归档缓存** — 相同查询自动命中本地归档，零积分消耗\n\n## 接口概览\n\n| 命令 | 用途 | 端点 | 层级 |\n|------|------|------|------|\n| `search` | 法条语义检索 | `/open/law_vector_search` | 核心 |\n| `keyword` | 法条关键词检索 | `/open/rh_ft_search` | 核心 |\n| `detail` | 法条详情 | `/open/rh_ft_detail` | 核心 |\n| `case` | 案例关键词检索 | `/open/rh_ptal_search` | 核心 |\n| `case --aut"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7bn9h1qxa9ja48qkmaxtfjgx81ksex\",\n  \"slug\": \"yuandian-law-search\",\n  \"version\": \"1.8.8\",\n  \"publishedAt\": 1785937071237\n}"},{"path":"references/01-keyword-expansion.md","content":"## 关键词扩展与分阶段检索\n\n关键词检索默认是精确匹配，用户搜索\"刑事案件管辖权\"不会自动命中\"知识产权管辖权\"等相关概念。本节说明 AI 应如何主动扩展检索范围、分阶段提炼精准结果。\n\n### 关键词扩展原则\n\nAI 在执行关键词检索前，应先分析用户查询是否涉及可扩展的法律概念：\n\n1. **上位概念扩展**：将具体概念扩展到上位概念。例如\"商标侵权\"→ 同时检索\"知识产权侵权\"\n2. **并列概念扩展**：关联同一层级的平行概念。例如\"管辖权异议\"→ 同时考虑\"管辖权转移\"\"指定管辖\"\n3. **程序-实体关联**：从实体法关键词关联到程序法关键词。例如\"正当防卫\"→ 也关注\"防卫过当\"\"紧急避险\"\n\n### 扩展关键词工作流\n\n当 AI 判断用户查询涉及可扩展概念时，按以下流程操作：\n\n1. **识别核心关键词**：从用户查询中提取核心法律概念\n2. **生成扩展词列表**：基于上述原则，列出 2-5 个相关关键词\n3. **分阶段检索**：\n   - **第一阶段（广撒网）**：用核心关键词执行一次检索（使用 `--search-mode or` 扩大命中范围）\n   - **第二阶段（精提炼）**：根据第一阶段结果，提炼更精准的关键词组合再检索一次\n4. **结果合并与去重**：将两次检索结果合并，按相关性排序展示\n5. **扩展方向提示**：检索完成后，向用户建议可能相关的扩展检索方向\n\n### 脚本参数支持\n\n关键词检索、案例检索和法规检索新增 `--expand` 参数，用于一次性传入多个扩展关键词：\n\n```bash\n# 法条关键词扩展检索\nscripts/yd-run keyword \"刑事案件 管辖权\" --expand \"知识产权管辖,级别管辖,专门管辖\" --search-mode or\n\n# 案例关键词扩展检索\nscripts/yd-run case \"买卖合同 瑕疵担保\" --expand \"质量纠纷,违约责任\" --search-mode or\n\n# 法规关键词扩展检索\nscripts/yd-run regulation \"民法典 合同\" --expand \"买卖合同,租赁合同\" --search-mode or\n```\n\n`--expand` 参数的行为：\n- 将扩展关键词追加到原始查询中；未显式传入 `--search-mode` 时，自动使用 `or` 模式检索\n- 如果显式传入 `--search-mode and`，尊重用户指定，仍按 AND 模式检索\n- 等效于将原始关键词与扩展关键词用空格连接后以 OR 模式检索\n- 不带 `--expand` 时保持原有的精确匹配行为（默认 `and`）\n\n### 分阶段检索示例\n\n用户问：\"关于刑事案件管辖权有哪些规定？\"\n\n**第一阶段（广撒网）**：\n```bash\nscripts/yd-run keyword \"刑事案件 管辖权 级别管辖 地域管辖 专门管辖\" --search-mode or --sxx 现行有效\n```\n\n**分析第一阶段结果**：发现大量结果涉及\"级别管辖\"和\"地域管辖\"两个核心分支\n\n**第二阶段（精提炼）**：\n```bash\nscripts/yd-run keyword \"级别管辖 中级法院\" --search-mode and --sxx 现行有效\nscripts/yd-run keyword \"地域管辖 犯罪地\" --search-mode and --sxx 现行有效\n```\n\n### 扩展方向提示\n\n检索完成后，AI 应根据检索结果向用户建议相关的扩展方向。提示格式：\n\n```\n本次检索完成了对\"刑事案件管辖权\"的查询，消耗 XX 积分。\n\n💡 相关的扩展检索方向：\n1. 级别管辖 —— 中级/高级/最高法院的管辖分工\n2. 地域管辖 —— 犯罪地、被告人居住地的管辖规则\n3. 专门管辖 —— 军事法院、知识产权法院等专门管辖\n如需深入了解某个方向，请告诉我。\n```\n\n### 策略兼容性\n\n关键词扩展行为与三种检索策略的关系：\n\n| 策略 | 扩展行为 | 分阶段检索 | 积分控制 |\n|------|----------|-----------|----------|\n| **balanced** | AI 判断是否需要扩展，主动执行 | 可执行两阶段检索 | 第二阶段前告知用户将额外消耗积分 |\n| **economical** | 不主动扩展，仅用户要求时执行 | 不执行，一次检索完成 | 仅扩展时提示积分消耗 |\n| **aggressive** | 自动扩展所有相关概念，不等待确认 | 自动执行多阶段检索 | 不限制，追求最大覆盖面 |"},{"path":"references/02-typical-workflows.md","content":"## 典型工作流与用户引导\n\nAI 在完成检索后，应**主动告知用户检索结果摘要和积分消耗**，并根据场景推荐后续操作。\n\n### 法条研究场景\n\n用户问：\"关于股东出资瑕疵的法律规定有哪些？\"\n\n1. 先调 search 语义检索（10 积分），覆盖全部相关法条\n2. 展示摘要 + 关键条文引用 + 总积分\n3. 主动建议扩展方向（如\"公司法\"\"破产法\"）\n\n### 案例研究场景\n\n用户问：\"最近几年类似案件怎么判的？\"\n\n1. 调 case-semantic 语义检索（10 积分），覆盖近 5 年案例\n2. 展示相关度排序的案例摘要\n3. **不主动调 case-detail**，由用户选择感兴趣的案例后调详情\n4. 主动告知\"如需查看完整判决书请告知，每个案例 10 积分\"\n\n### 案件综合分析场景\n\n用户问：\"这个案件我们能不能主张 XX？\"\n\n1. 多轮检索：先 search 法条、再 case-semantic 案例、可能补 regulation 法规\n2. 汇总法条 + 案例 + 法规 + AI 分析判断\n3. 给出可执行的法律意见\n4. **总积分可能 30-50**，在最终回复开头明示\n\n**案例检索执行约束**：\n\n- 第一轮案例检索优先用 `case-semantic` 承接案情事实结构，不要把长事实描述直接丢给 `case` 关键词 AND 检索。\n- 只有在需要锁定若干高信息密度词时才补 `case`；关键词控制在 4-6 个，优先选择平台/行业行为词、交易链条词和责任焦点词。\n- `case` 默认是 AND 精确匹配；如果使用 `--expand` 扩展同义词、上位词或并列场景，未显式指定时脚本会自动切到 OR。\n- 一轮关键词检索零命中时，不要据此判断\"没有类案\"；应立即改用 `case-semantic` 或缩短关键词后 OR 复检。\n\n### 争议焦点识别优先场景（v1.6.1+ 强制前置步骤）\n\n**问题**：很多 AI 跳过\"识别用户原话里的争议焦点\"这一步，直接根据用户问题的\"法律概念包装\"展开检索（\"短视频带货\"\"电商平台\"\"间接侵权\"），结果命中大量\"被告自己动手\"的案型，与用户实际争议焦点偏差很大。\n\n**强制前置：争议焦点识别表**\n\n收到\"这个案件我们能不能主张 XX\"或类似案件综合分析请求时，**第一轮检索前**先在对话/笔记中明确以下 5 个字段，再据此生成检索词：\n\n| 字段 | 用户问题中提取 | 检索词应反映 |\n|------|--------------|-------------|\n| **行为主体** | 谁实施了侵权？（如\"达人\"/\"商家\"/\"平台\"） | 用具体主体词，不要用泛化的\"被告\" |\n| **角色定位** | 用户/原告的主张对象处于什么位置？（如\"被挂车商家\"vs\"自营商家\"） | 区分\"被关联\"和\"主动实施\"两种身份 |\n| **行为模式** | 侵权内容如何产生、传播、变现？（如\"达人发布→挂车→商家团购\"） | 用**行业术语**（挂车、探店、团购）而非法律术语 |\n| **抗辩点** | 被告可能怎么抗辩？（如\"视频非我发、我无法控制达人\"） | 围绕抗辩点搜\"法院如何回应\" |\n| **用户已明确的论点** | 用户主张的几个核心点是什么？ | **直接用用户原话作为检索词**（见下方\"红线\"） |\n\n**红线（重要）**：\n\n> **用户的争议焦点 ≠ 用户问题的法律概念包装**\n> **用户的争议焦点 = 用户原话里已经明确给出的几个核心论点**\n\n例：\n- 用户原话：\"视频是达人发的，不是被告发的，但挂在被告商品链接上。被告商品页能看到达人视频 → 被告有筛选过程。被告因此获利 → 反不正当竞争法兜底。\"\n- 用户已明确的论点 = [1] 视频非被告发布但挂被告商品链接；[2] 被告对视频有筛选过程；[3] 被告因此获利；[4] 反不正当竞争法兜底\n- v1 错搜：用\"短视频带货 电商平台 间接侵权\"（用户问题的法律概念包装）→ 偏差\n- v1 正搜：用\"视频不是商家发布 商家对达人视频有筛选过程 商家因视频获利 反不正当竞争法兜底\"（用户原话级别）→ 命中对位案\n\n**反例（曾发生过的偏差）**：\n\n> 用户问：\"达人发的短视频侵权了，挂到商家商品链接上，商家要负责吗？\"\n>\n> v1 错误：直接搜\"短视频带货 电商平台 间接侵权\" → 命中\"商家自己搬运/制作\"案例 → 全部跑偏\n>\n> v1 正确（如果当时识别到位）：用户已经明确 4 个信息——\n> ① 视频由达人发布（非被告）② 视频→挂车→被告商品 ③ 被告对视频有筛选过程 ④ 被告因此获利+反不正当竞争法兜底\n> 直接把这 4 个用户原话作为检索词，**第一轮**就能命中对位案。\n>\n> 不需要等\"检索后再提炼二分法\"——用户原话已经够具体了。\n\n**关键提示**：\n- **行业术语 > 法律术语**：用户说\"挂车\"就用\"挂车\"，不要说\"信息网络传播\"\n- **用户原话级别 > 法律概念包装**：用户原话里给的论点直接作为检索词\n- **抗辩点对称搜索**：被告可能怎么抗辩 → 搜\"法院如何否定该抗辩\" 的判例\n- **二分法是结果不是起点**：如果检索后才识别出二分法（如\"营销合作 vs 精选联盟\"），说明第一轮关键词就有问题——应该在第一轮就用更精确的词\n- **长事实结构走语义，短关键词走精确**：自然语言事实结构用 `case-semantic`；`case` 只放少量关键字，避免 6 个以上词的 AND 零命中。\n\n### 标杆案例对标检索场景（v1.6.1+ 强制流程）\n\n**问题**：用户第一轮就提供了标杆案例（如星云VR案、微信文章），但 v1 没把它作为\"对标模板\"去搜同类，导致错失场景最对位的案例。\n\n**强制流程**：\n\n1. **提取标杆案例的\"事实结构骨架\"**（5-7 个关键事实）\n   - 例：星云VR案 = {店主联系达人 + 多个探店账号发布 + 视频含侵权片段 + 视频挂团购链接 + 商家根据链接成交向达人结算佣金 + 商家未审核 + 法院判决商家赔偿}\n\n2. **把\"事实结构骨架\"作为查询模板**生成检索词\n   - 关键词版：`探店达人 + 团购链接 + 商家 + 营销合作 + 审查义务`\n   - 语义版（更优）：用一段自然语言描述这个事实结构\n\n3. **首选 case-semantic**（关键词检索对\"达人\"\"挂车\"识别差）\n   - 关键词检索易命中\"被告自己动手\"的偏差案例\n   - 语义检索对场景描述识别更好\n   - 如果补关键词检索，先用 4-6 个高密度词，例如 `短视频 推广 团购 商家 责任 著作权`\n   - 避免第一轮使用 `探店达人 团购链接 商家 著作权 责任`、`推广视频 挂车 商家 责任 审查 注意义务` 等长 AND 组合；这类组合容易因字面差异零命中\n\n4. **每轮命中后回检\"对标度\"**：命中案例的\"事实结构\"是否覆盖标杆案例的 5-7 个关键事实\n   - 覆盖 ≥ 5/7 → 高度对位，纳入\"主要类案\"\n   - 覆盖 3-4/7 →"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"元典法条与案例检索。本技能应在需要查询中国法律法规条文、检索相关案例、为法律分析提供数据支撑时使用。 Skill: 元典法条与案例检索 Owner: cat-xierluo Summary: 元典法条与案例检索。本技能应在需要查询中国法律法规条文、检索相关案例、为法律分析提供数据支撑时使用。 Tags: latest:1.8.8 Version history: v1.8.8 | 2026-08-05T13:37:51.237Z | user 修复：validate-query-filters 动态自省默认关闭（消除动态代码执行误报）；SKILL.md 占位符调整（消除密钥字面量误报） v1.8.7 | 2026-08-05T13:29:12.502Z | user 文档完善：README 删除已废弃自更新章节；SKILL.md 新增数据留存与隐私警示、所需权限声明（纯文档，不影响功能） v1.8.6 | 2026-08-04T07:53:59.346Z | user v1.8.6 升级（原 1.7.5） v1.7.5 | 20","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":729,"uniquenessScore":51,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T21:53:39.032Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T21:53:39.032Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:08:49.040Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}