Metadata-Version: 2.4
Name: law-cn-cli
Version: 0.2.10
Summary: Unified CLI for official Chinese legal information sources
License-Expression: PolyForm-Noncommercial-1.0.0
Keywords: china-law,legal-research,regulations,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Legal Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: certifi>=2024.0
Requires-Dist: cryptography>=42.0
Requires-Dist: httpx[socks]>=0.27
Requires-Dist: pypdf>=5.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# law-cn-cli

`law-cn-cli` 将 49 个中国境内官方法律、法规、规章、政策和交易规则来源，以及 1 个需回到制定机关核验的商务部承载聚合库，统一为一套命令语法。发行包名称是 `law-cn-cli`，安装后的命令为 `law-cn`：

```text
law-cn search <source-code> <keyword> [统一检索选项]
law-cn search auto <keyword> [--sources code,...] [--view grouped|raw]
law-cn search all <keyword> [--view grouped|raw]
law-cn info <source-code> <document-id-or-official-url>
law-cn article npc <document-id> <条号>
law-cn preview npc <document-id>
law-cn article-search npc <keyword> [--max-laws N]
law-cn download <source-code> <document-id> --format doc|docx|pdf
law-cn skill install|update|status|path|uninstall
```

这是一个从各官网当前实际请求重新验证、独立实现的项目。项目会明确区分公开开发 API、官网前端内部 JSON 接口和 HTML 检索端点；“能被官网调用”不等于“有公开开发文档或稳定性承诺”。

49 个来源均实现了 `info`。国家法律法规数据库使用结构化详情接口；其他来源按各站当前详情接口或官方详情 HTML 解析。URL 型输入会校验来源官方域名，不允许把任意 URL 当成请求目标。

`law-cn article npc` 会调用国家法律法规数据库的官方 DOCX 下载接口，解析后输出完整条文。可用条号（如 `第二十八条`、`第28条`、`28`）或 `--grep` 检索单篇法规内的所有命中条文。短期签名 URL 不会写入输出或缓存；原始官方文件默认进入本地持久化缓存，避免后续条文检索重复下载。

## 安装

需要 Python 3.11 或更高版本。

推荐通过 `uv` 安装为隔离的全局命令：

```bash
uv tool install law-cn-cli
law-cn --version
law-cn sources
```

命令自身带完整帮助，可逐层查看：

```bash
law-cn --help
law-cn search --help
law-cn article-search --help
law-cn skill --help
```

升级或卸载：

```bash
uv tool upgrade law-cn-cli
uv tool uninstall law-cn-cli
```

也可以使用 `pip`：

```bash
python3 -m pip install law-cn-cli
law-cn sources
```

从源码参与开发时，在项目根目录运行：

```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/law-cn --version
```

## 基本用法

所有来源默认正常校验 HTTPS 证书；仅遇到证书过期（X509 错误码 10）时，对当前域名跳过证书校验重试，并输出域名和原因。后续请求仍先尝试正常校验，证书续期后自动恢复。域名不匹配、不受信任的证书及其他网络错误不会触发该例外；无需设置环境变量。

```bash
# 查看全部来源
law-cn sources

# 查看单个来源原生支持的检索能力
law-cn capabilities npc

# 查看该来源经官网请求核验过的额外检索字段及请求字段名
law-cn parameters tax --format json

# 国家法律法规数据库：标题检索
law-cn search npc '劳动合同法' --format json

# 国家法律法规数据库：读取官方详情
law-cn info npc 2c909fdd678bf17901678bf74d7106b3

# 国家法律法规数据库：提取完整条文
law-cn article npc 2c909fdd678bf17901678bf74d7106b3 '第二十八条'
law-cn article npc 2c909fdd678bf17901678bf74d7106b3 --grep '劳动报酬'

# 返回完整目录、总条数和全部条号（不抽样）
law-cn preview npc 2c909fdd678bf17901678bf74d7106b3

# 跨法规条文检索；默认处理全部候选法规
law-cn article-search npc '民法典第三百一十一条'

# 只有用户明确希望截断时才设置候选法规数量
law-cn article-search npc '民法典第三百一十一条' --max-laws 20

# 显式下载；格式参数决定官网实际请求的文件格式
law-cn download npc 2c909fdd678bf17901678bf74d7106b3 \
  --format pdf \
  --output './劳动合同法.pdf'

# 检查持久化文件缓存
law-cn cache stats

# 国家法律法规数据库：正文检索具体条文引用
law-cn search npc '民法典第三百一十一条' \
  --scope content \
  --format jsonl

# 国家规章库
law-cn search gov-rules '管理办法' --scope title --sort newest

# 上交所规则
law-cn search sse '信息披露' --scope all

# 金融监管总局，完整写入可审计目录
law-cn search nfra '善意取得' \
  --scope all \
  --output './runs/nfra-good-faith'

# 国家法律法规数据库：搜索建议
law-cn suggest npc '劳动合同'

# 国家法律法规数据库：查看单篇文件中的关键词命中位置
law-cn highlight npc 2c909fdd678bf17901678bf74d7106b3 '劳动报酬'

# 国家法律法规数据库：读取关联资料
law-cn related npc 2c909fdd678bf17901678bf74d7106b3 '劳动合同'

# 国家法律法规数据库：批量下载；所有 ID 都会处理，失败项单独列出
law-cn batch-download npc \
  2c909fdd678bf17901678bf74d7106b3 \
  ANOTHER_DOCUMENT_ID \
  --format docx \
  --output-dir './downloads'

# 网信办高级检索：连续关键词按官网语义作顺序敏感的短语检索
law-cn search cac '生成式人工智能服务管理暂行办法' \
  --scope title \
  --match exact \
  --source-param required_phrase=生成式人工智能 \
  --source-param exclude_terms=征求意见 \
  --source-param directory=网信政务

# 网信办法规栏目 JSON 接口：枚举该分类的全部记录并保存审计清单
law-cn catalog cac \
  --category 部门规章 \
  --format jsonl \
  --output './cac-department-rules'
```

如果没有指定 `--scope`，CLI 默认使用 `auto`，而不是机械地做标题＋正文双检索。`auto` 会先根据检索词判断意图：找法规/专题（如“人工智能”“宪法”）优先检索标题；出现“全文、条文、具体规定、是否规定、提及”等线索时检索正文；明确要求“关键词/综合检索”时使用原站关键词域。每个来源的 manifest 都会写入 `scope_decision`，说明实际范围和原因。

`keyword` 表示原站自身的关键词域，字段可能是标题、正文、摘要或其组合，不能宣称等于全文检索；`all` 是 `keyword` 的兼容别名。只有显式传 `--scope both` 时，CLI 才分别请求标题和正文；某来源缺少其中一域时会标为 `partial`，原站关键词域最多作为补充，不能冒充双域覆盖。显式指定了来源不支持的筛选项时，命令会报错，不会悄悄忽略条件。

`suggest`、`highlight`、`related`、`article`、`preview`、`article-search` 和 `batch-download` 当前只支持 `npc`。`catalog` 当前支持 `cac`。批量下载会处理命令中给出的全部 ID；任一项目失败时仍保留其他成功结果，并以非零退出码和 `failures` 字段明确报告。

## 统一检索选项

```text
--scope auto|title|keyword|content|both|all
                                   默认 auto；all 是 keyword 的兼容别名
--match fuzzy|exact
--format table|json|jsonl|envelope-json
                                   envelope-json 把 status、skipped_sources、
                                   source_failures 和 source_query_overrides
                                   包进 stdout 的包裹对象；普通 json/jsonl
                                   只含记录本身，不完整状态在退出码、stderr
                                   和 --output 的 manifest 里
--status VALUE                  可重复
--document-type VALUE           可重复
--authority VALUE               可重复
--publish-from YYYY-MM-DD
--publish-to YYYY-MM-DD
--effective-from YYYY-MM-DD
--effective-to YYYY-MM-DD
--sort relevance|newest|oldest
--limit N                        覆盖默认的每来源 100 条
--all                            取消默认限制，处理全部官方分页
--source-param KEY=VALUE        单站来源特有字段
--source-param SOURCE:KEY=VALUE auto/all 中按来源限定的特有字段
--format table|json|jsonl
--output DIRECTORY
```

不同官网原生能力不同。先运行 `law-cn sources` 看每站的已接线检索域、详情能力和 `official_entry_url`，再运行 `law-cn capabilities <source>` 查看字段级能力。`official_entry_url` 是该来源的官方数据库入口：接口失败时可交给浏览器人工复核，但打开入口不等于已核验具体文件正文。能力输出中的 `scope:keyword` 对应适配器内部旧键 `scope:all`：它仅表示官网关键词域，可能是标题、正文、摘要或其组合，绝不能直接表述为“全文”。`detail=supported` 只表示可以取得官方详情；仍必须检查 `info` 返回的 `body_availability`，确认是否真的拿到了可读正文。

`mofcom-claw` 是商务部网站承载的“中国商务法规”聚合库，只用于补充发现**部门规章、部门规范性文件、部门工作文件**；地方政府规章由各地方官方库覆盖，不在这个来源检索。必须显式指定其中一类 `--document-type`，且每条记录仍须回到制定机关官网核验。详情页会保留来源标签和该库的免责声明边界。为保证结果确属这三类文件，CLI 只开放该站可带效力级别的标题检索；其综合关键词/全文接口不提供可验证的文件类型筛选，因此不开放。例如：

```bash
law-cn search mofcom-claw '人工智能' --scope title \
  --document-type 部门规章 --status 现行有效 \
  --source-param law_topic=社会管理 \
  --source-param industry=信息通信 \
  --source-param publish_year=2026
```

`auto` 不再把所有中央和专项来源铺开查询，而是先按法律层级选最小来源集：法律、行政法规和一般法规问题用 `npc`；司法解释追加 `court`、`spp`；国务院文件/公报用 `gov-policy` 的相应栏目；部门规章、部门规范性文件、部门工作文件用 `gov-policy` 的“国务院部门文件”栏目，并以 `mofcom-claw` 的对应类型作补漏候选。地域词只在该计划后追加相应省级官方库，不会扩大到所有省份；专项部门库留给第二轮有依据的补查。`--document-type 部门规章|部门规范性文件|部门工作文件` 可明确给出路由层级，`--sources` 仍可显式覆盖自动路由。`auto` 对已选来源顺序执行，`all` 才并发全部官方来源。`auto/all` 的 manifest 通过 `source_coverage` 逐源记录实际查询范围、缺失范围、能力等级、页数、截断和失败；任一来源只有部分覆盖时整体状态为 `partial`，CLI 返回非零退出码。

`--sort` 与 `--match exact` 的降级语义一致：来源不支持所请求的排序时，不再整源跳过，而是退回原站相关性顺序继续检索，并在 manifest 的 `source_query_overrides` 中按源记录 `requested`/`applied` 及原因（如 `court`、`samr` 等无原生时间排序的源）；该来源的结果不得表述为按时间排序。`--scope` 的语义不同：显式指定的检索范围与来源能力不匹配时仍整源跳过并记入 `skipped_sources`，因为换范围会歪曲覆盖语义。

多源检索的 `--sort newest/oldest` 由 CLI 对合并结果做全局归并排序（按 `publish_date`，无日期记录排在有日期记录之后），不是按源分块排序；被降级的源也参与归并，其记录按自身日期排位。

NPC 的 `--document-type` 和 `--authority` 接受官网数值代码或当前官网枚举中的名称；名称会在请求前通过官方 `enumData` 解析。NPC 当前不再提供可用的原生日期排序，`newest/oldest` 会先处理全部官方分页，再在本地按公布日期排序，最后才应用用户显式的 `--limit`。

NPC 的官方标题检索按词元 OR 命中：搜“善意取得”会返回标题只含“取得”的文件（如《关于香港律师取得内地执业资质试点工作的决定》）。每条记录的 `raw_metadata.title_match` 标注 `full`（标题完整包含关键词）或 `token`（仅命中部分词元）。加 `--match exact` 时，CLI 在客户端丢弃仅词元命中的记录——`searchType` 两种模式在官网返回相同结果，精确匹配由 CLI 保证；但 `total_reported` 仍是官方词元 OR 总数，可能大于实际返回条数。找已知文件用官方全称；找“善意取得”“无权处分”这类制度词用 `--scope content` 或 `article-search`。

运行 `law-cn parameters <source>` 可查看该站的高级字段、对应官网请求字段、类型、可重复性和已知枚举。单站检索用 `--source-param KEY=VALUE`；`auto/all` 用 `--source-param SOURCE:KEY=VALUE`，避免把一个网站的字段错误广播到其他网站。未知字段、错误枚举和不允许重复的字段会直接报错。

### 网信办接口说明

网信办适配器使用两条不同的官网数据路径，避免把栏目枚举错误包装成全文检索：

- `law-cn search cac KEYWORD` 调用高级检索 JSP。支持 `title`、`content`、`all`，公布日期区间，相关度/最新/最早排序，以及 `required_phrase`、`exclude_terms`、`directory`。`directory` 只接受官网高级检索表单实际可用的顶层栏目：`全站`、`热点专题`、`要闻`、`网信政务`、`互动服务`。
- `law-cn catalog cac --category CATEGORY` 调用 `/cms/JsonList`，支持 `全部`、`法律`、`行政法规`、`部门规章`、`司法解释`、`规范性文件`、`政策文件`、`政策解读`。该命令返回目录元数据（标题、摘要、日期和官方详情页链接），不把摘要冒充法规全文。

网信办高级检索中，连续关键词具有顺序敏感的短语效果；`--match exact` 表示这一官网“完整连续短语”语义，不表示标题必须与关键词逐字完全相等。中文逗号分隔的主关键词按官网行为表示任一短语命中。官网表单虽存在 `inpro` 字段，但在线验证中该字段未产生可靠结果，因此 CLI 不将它宣称为可用参数。法规深层分类代码也不能由高级检索接口可靠过滤，所以由 `catalog` 命令通过 JSON 栏目接口提供。

`catalog` 的内部每页数量只用于请求分批，不是输出上限。命令根据官网 `totalRec` 持续翻页，默认保留全部原始记录，不抽样、不去重；输出清单中的 `pages_fetched`、`records_written`、`total_reported` 和 `truncated` 可用于核验完整性。

维护仓库中的 49 站请求审计还记录了 CLI 自动维护、但不允许用户覆写的分页、回调、站点范围和动态鉴权字段。该维护档案不属于 wheel/sdist 的公开运行时内容；公开用户应以 `law-cn capabilities` 和 `law-cn parameters` 的实际输出为准。

CLI 默认对每个来源返回前 100 条；官网单页不足 100 条时会继续翻页，达到 100 条或官网终止页后停止。`--limit N` 可显式覆盖默认值，`--all` 则取消默认限制并处理全部官方分页；二者不能同时使用。输出清单分别记录 `default_limit`、`explicit_limit` 和 `truncated`，不会把默认限制伪装成用户明确指定。

## 跨来源规则路由

`law-cn search auto KEYWORD` 使用可审计的确定性分层路由，而不是在 CLI 内调用大模型。中央核心固定为国家法律法规数据库 `npc`、国家规章库 `gov-rules` 和国务院政策文件库 `gov-policy`，并且不根据地域词给这三个来源添加分类或地域限制。随后按省级行政区追加地方官方来源；涉及司法解释时追加 `court` 和 `spp`，涉及法院或检察专门事项时追加相应司法来源；最后按网信、金融、市场监管、税务、生态环境、交易所、条约等主题追加专项来源。政策材料在结果中保留来源和文件类型，不冒充法律法规。

```bash
# 查看路由计划，不发出搜索请求
law-cn search auto '上海市生成式人工智能管理规定' --explain-routing

# 执行规则路由并按同一文件聚类展示
law-cn search auto '生成式人工智能服务管理暂行办法' --format json

# 显式限定参与的来源
law-cn search auto '量刑建议' --sources npc,gov-rules,gov-policy,spp

# 在跨来源检索中覆盖某一站的原生字段
law-cn search auto '北京市人工智能' \
  --source-param gov-rules:category=地方政府规章

# 请求全部 49 个来源
law-cn search all '善意取得' --all --view raw --format jsonl
```

实际网络请求会按来源并发执行，结果仍按路由计划中的来源顺序稳定汇总。一个来源
失败不会阻塞其他来源。

`auto/all` 的默认 `grouped` 视图只用于减少视觉重复。每个聚类的 `records`
字段仍保留全部来源记录；`--view raw` 直接输出所有原始记录。标准化标题一致的
记录归入同一文件族；发布日期、文号或发布机关存在冲突时，在族内拆为 `versions`
并标记 `version_conflict=true`，不会把冲突版本当成同一份文本。

跨源相关度分数不直接相加。聚类选择展示记录时按文件类型优先规范文本或制定机关
官网，但不会删除其他官方来源。输出 `manifest.json` 记录所选来源、路由理由、
逐源检索清单、跳过原因、来源失败、原始记录数和聚类数。一个来源失败时保留其他
来源结果并以非零退出码明确报告，不静默吞掉失败。

`auto/all` 默认对每个来源最多返回 100 条，并写入 `default_limit_per_source`；
`--limit N` 显式覆盖每来源上限，`--all` 取消上限并处理全部分页。来源特有参数必须写成
`SOURCE:KEY=VALUE`；未限定来源的写法会直接报错。

## 安装 Agent Skill

包内自带 `law-cn-search` Skill，用于让支持 Skills 的 Agent 在运行 CLI 前进行实时
查询规划、全网候选发现、官方回查、效力核验和证据分级。它不会自动写入用户目录；
安装必须由用户显式执行：

```bash
law-cn skill install --agent auto
law-cn skill status --agent auto
law-cn skill path --agent auto
```

`auto` 会优先识别 Codex 的 Skills 目录，其次识别通用 `~/.agents/skills`。也可以
用 `--agent codex|agents` 或 `--target-root PATH` 明确指定位置。升级包后运行：

```bash
law-cn skill update --agent auto
```

安装器通过文件哈希记录自身写入的文件。若用户修改了 Skill，更新和卸载会拒绝
覆盖或删除；只有显式传入 `--force` 才会处理修改过的已登记文件。卸载命令为
`law-cn skill uninstall`。

Skill 由一个入口 `SKILL.md`、Agent 元数据和六份按需读取的 reference 组成：
研究流程、实时查询规划、来源路由、CLI 命令、证据核验和输出契约。宽泛概念不会
依赖无法穷尽的本地同义词表；Agent 实时生成候选查询，并保留用户原始检索词。
网页搜索或 AI 记忆只能产生候选，最终法源仍须回到 CLI 或制定机关官网核验。

## 原文文件缓存

NPC 的 `article`、`preview`、`article-search` 和 `download` 默认复用持久化的官方 DOCX/PDF：

- 默认目录：`~/.cache/law_cn/documents`
- 默认有效期：7 天，命令帮助和缓存元数据均明确记录为 `604800` 秒
- 缓存键：来源 + 官方 document ID + 文件格式
- 缓存内容：原始公开文件及哈希、大小、缓存时间；不保存短期签名 URL
- `--refresh`：强制重新获取并更新缓存
- `--no-cache`：本次既不读取也不写入缓存
- `--cache-dir PATH`、`--cache-max-age-days N`：显式调整位置和有效期
- `law-cn cache stats`：查看条目、大小、路径和有效期
- `law-cn cache clear`：仅清理由 law-cn 标记并拥有的缓存目录

`article`、`preview` 输出 `file_cache_hit`；`article-search` 输出 `cache_hits` 和 `files_downloaded`；显式下载输出 `cache_hit`，因此是否发生重复下载可以直接审计。

## 输出与审计

### 检索输出

每条记录统一包含：

- `source`、`source_name`、`source_document_id`
- `title`、`official_url`
- `document_type`、`issuing_authority`、`document_number`
- `publish_date`、`effective_date`
- `validity_status`、`validity_explicit`
- `summary`、`content`、`download_urls`
- `retrieved_at`、`source_rank`
- `raw_metadata`

### 详情输出（`law-cn info`）

结构化 JSON，至少包含：

- `official_url`、`title`、`source_document_id`
- `body`、`body_availability`、`body_note`、`content_outline`
- `document_type`、`issuing_authority`、`publish_date`、`effective_date`、`validity_status`
- `attachments`（官方 `ossFile` 路径及不含签名的 `download_endpoint` 模板）
- `retrieved_at`、`raw_metadata`

当详情接口只返回目录/条文标题而无正文时，`body_availability` 为 `outline_only`；当接口未返回正文结构、仅列出可下载附件时为 `download_only`。CLI 不会下载或解析附件内容。

### 条文输出（`law-cn article npc`）

`article` 使用官方 DOCX 下载接口取得原文并解析。输出包含官方详情页、法规标题、检索条件、完整命中条文和 `file_cache_hit`。原始文件按上文规则进入持久化缓存，但不输出带签名的临时下载 URL。

`article-search` 的每条命中都携带所属法规 ID、标题、官方详情页、条号和条文文本；任何下载或解析失败都会进入 `failures`，不会静默丢弃。未传 `--max-laws` 时处理全部候选法规；显式设置后，输出会记录候选总数、本批偏移、明确请求的法规数、实际解析数和下一批偏移。

使用 `--output` 时生成：

```text
DIRECTORY/
├── records.jsonl
└── manifest.json
```

`manifest.json` 记录抓取页数、写入条数、官网报告总数、显式限制以及是否截断。已有同名文件时命令拒绝覆盖。

## 来源与能力

| code | 官方来源 | 传输方式 | 检索范围 | 其他原生筛选 |
|---|---|---|---|---|
| `npc` | 国家法律法规数据库 | JSON | title, content | exact, status, 类型, 制定机关；newest/oldest（完整分页后本地排序） |
| `gov-rules` | 国家规章库 | JSON + 官网动态鉴权 | title, all | newest |
| `gov-policy` | 国务院政策文件库 | JSON | title, content, all | newest；文件库、分类、标签、文号、年份、部门、日期 |
| `court` | 最高人民法院 | HTML | all | — |
| `spp` | 最高人民检察院法律法规库 | 官方静态 HTML 栏目 | title | exact, 公布日期, newest/oldest；宪法、法律、司法解释、规范文件 |
| `party` | 党内法规库 | JSONP | title, content | newest |
| `treaty` | 外交部条约数据库 | HTML | title | 施行日期；条约分类、缔约国、领域、签署日期、港澳分类 |
| `tax` | 国家税务总局政策法规库 | JSON | title, all | exact, 公布日期, status, newest；效力级别、税种及二级分类、文号、行业、制定年份 |
| `mee` | 生态环境部法规标准 | HTML | title, content, all | 公布日期, newest/oldest |
| `csrc` | 证监会证券期货法规数据库 | JSON | title, content（可组合） | exact, authority, status, 公布日期, newest；标题/正文各三词 AND/OR、法规体系 |
| `samr` | 市场监管法律法规规章数据库 | JSON | title, content | 类型（可多选）, status, 公布/施行日期 |
| `miit` | 工业和信息化部政策法规 | JSON | title, content, all, 文号 | 公布日期, newest；文件类型、部门、主题 |
| `nfra` | 国家金融监督管理总局 | JSON | title, content, all | 公布日期, newest/oldest；栏目、机构、相对时间 |
| `cac` | 国家互联网信息办公室 | HTML 高级检索 + JSON 法规栏目 | title, content, all | 连续短语, 排除词, 顶层栏目, 公布日期, newest/oldest；法规七分类全量枚举 |
| `sse` | 上海证券交易所规则 | JSONP | title, content, all | exact, 公布日期, newest |
| `szse` | 深圳证券交易所规则 | JSON | title, content, all | exact, newest |
| `bse` | 北京证券交易所规则 | JSONP | all | 公布日期, newest |
| `neeq` | 全国股转系统规则 | JSONP | all | 公布日期, newest |
| `beijing` | 北京市法规规章规范性文件数据库 | 表单 JSON + 官方详情 HTML | title, all（全文） | 完整短语, 7 类文件, authority, 公布日期, relevance/newest/oldest；21 个主题、79 个来源单位、18 个区域、9 个层级、文号 |
| `tianjin` | 天津市法规规章规范性文件数据库 | JSON | title, content | exact, 类型, authority, status, 公布/施行日期, newest/oldest |
| `hebei` | 河北省法规规章规范性文件数据库 | HTTP JSON | title, content | exact, 类型, status, 公布/施行日期；效力层级、机关、文号、年份 |
| `hunan` | 湖南省法规规章规范性文件数据库 | HTTP JSON | title, content | exact, 类型, status, authority, 公布日期 |
| `guangdong` | 广东省法规规章规范性文件数据库 | JSON | title, content, all | exact, 类型；制定形式、地域 |
| `chongqing` | 重庆市法规规章规范性文件数据库 | JSON | title, content, all | exact, 类型, status, authority, 公布日期；层级、地域、主题、文号 |
| `fujian` | 福建省法规规章规范性文件数据库 | HTTPS JSON | title, content, all | exact, 类型, status, authority, 公布日期, newest；机关名称、文号、地域、领域、制定形式 |
| `shanxi` | 山西省法规规章规范性文件数据库 | HTTPS JSON | title, content, all | exact, 类型, status, authority, 公布/施行日期, newest；文号、制定形式、年份、区域 |
| `inner-mongolia` | 内蒙古自治区法规规章规范性文件数据库 | HTTPS JSON | title, content, all | exact, 类型, status, authority, 公布/施行日期, newest；部门分类、行政区划、文件层级、文号 |
| `liaoning` | 辽宁省法规规章规范性文件数据库 | HTTPS JSON | title, content, all | exact, 类型, status, authority, 公布/施行日期, newest；机关层级、通过日期、区域 |
| `jilin` | 吉林省法规规章规范性文件数据库 | HTTPS 查询 + 官方 HTML | title, content, all | 类型, status, authority, 公布/施行日期；文件层级、主题、制定形式 |
| `heilongjiang` | 黑龙江省法规规章规范性文件数据库 | HTTPS JSON + 官方文件 | title, content, all | exact, 类型, status, authority, 公布/施行日期, newest/oldest；层级、区域、标签 |
| `shanghai` | 上海市法规规章规范性文件库 | HTTPS 表单 + 官方 HTML | title | exact, 类型, status, authority, 公布日期；文号 |
| `jiangsu` | 江苏省法规规章规范性文件数据库 | HTTPS JSON | title, content | exact, 类型, status, authority, 公布/施行日期；层级、地区、年份、文号 |
| `zhejiang` | 浙江省法规规章规范性文件库 | HTTPS 表单 + 官方 HTML | title | 类型, status, 公布日期；层级、主题、发布单位、区域、文号、服务对象 |
| `anhui` | 安徽省法规规章规范性文件数据库 | HTTPS JSON | title | 类型, status, authority, 公布/施行日期；层级、主题、城市、文号 |
| `jiangxi` | 江西省法规规章规范性文件数据库 | HTTPS 签名表单 | title, content, all | exact, 类型, status, 公布日期, newest/oldest；效力层级、区域、主题 |
| `shandong` | 山东省法规规章规范性文件数据库 | HTTP JSON | title, content | exact, 类型, status, authority, 公布/施行日期；分类、年份、文号 |
| `henan` | 河南省法规规章规范性文件库 | HTTPS JSON | title, content, all | exact, 类型, status, 公布/施行日期；机关、区域、制定形式、文号 |
| `hubei` | 湖北人大旧法规库 + 国家规章库（湖北过滤） | HTTP HTML + 国家规章库 JSON | title（本地后置）, all | 地方性法规/自治条例/政府规章；地域、通过日期、施行日期、newest |
| `guangxi` | 广西壮族自治区法规规章规范性文件数据库 | HTTPS JSON | title, content | exact, 类型, status, authority, 公布/施行日期；区域、文号 |
| `hainan` | 海南自由贸易港法规政策文件库 | HTTPS JSON | title, content, all | exact, 类型, status, authority, 公布/施行日期；效力位阶、区域、层级、特色分类 |
| `sichuan` | 四川省法规规章规范性文件数据库 | HTTPS JSON | title, content, all | 类型, status, authority, 公布/施行日期, newest/oldest；文件分类、区域 |
| `guizhou` | 贵州省法规规章规范性文件数据库 | HTTPS JSON | title, content | exact, 类型, status, authority, 公布/施行日期, newest/oldest；层级、主题、区域、年份 |
| `yunnan` | 云南省法规规章规范性文件数据库 | HTTP JSON | title, content, all | exact, 类型, status, authority, 公布/施行日期, newest；区域、文号、制定形式 |
| `tibet` | 西藏自治区法规规章规范性文件数据库 | HTTP JSON | title | 类型, status, authority, 公布日期；文号、层级、区域 |
| `shaanxi` | 陕西省法规规章规范性文件数据库 | HTTPS JSON | title, content | exact, 类型, status, authority, 公布/施行日期, newest/oldest；文号、年份 |
| `gansu` | 甘肃省法规规章规范性文件数据库 | HTTPS JSON | title, content | exact, 类型, status, authority, 公布/施行日期；区域、年份、文号 |
| `qinghai` | 青海省法规规章规范性文件数据库 | HTTPS JSON | title, content, all | exact, 类型, status, authority, 公布日期, newest/oldest；效力层级、主题、文号 |
| `ningxia` | 宁夏回族自治区法规规章规范性文件数据库 | HTTPS JSON | title, content | exact, 类型, status, authority, 公布/施行日期, newest/oldest；效力位阶、制定机关树、文号 |
| `xinjiang` | 新疆维吾尔自治区法规规章规范性文件库 | HTTP JSON | title, content, all | 类型, status, authority, 公布/施行日期；层级、制定形式、区域、年份 |

北京站按照官网展开筛选区提供完整的人类可读选项；运行 `law-cn parameters beijing` 可查看主题、来源单位、区域和文件层级的当前完整值表。文件类型使用官网七个分组名称，日期和排序使用统一参数：

```bash
# 标题检索；北京默认就是标题域
law-cn search beijing '环境保护规划' --scope title

# 全文检索
law-cn search beijing '责任范围划分导则' --scope all

# 不输入关键词，仅按多个官网筛选条件组合检索
law-cn search beijing '' \
  --document-type 行政规范性文件 \
  --authority 北京市生态环境局 \
  --publish-from 2025-01-01 \
  --publish-to 2025-12-31 \
  --source-param topic=城乡建设、环境保护 \
  --source-param region=北京市 \
  --source-param document_level=市级政府部门 \
  --sort newest

# 官网展示的括号文号可直接输入；CLI 会转换成其后端实际可命中的形式
law-cn search beijing '' \
  --source-param document_number='京管发〔2026〕2号'
```

北京当前官网没有显示“有效性”值表，因此 CLI 不再把隐藏的 `yxx` 字段宣称为已完整支持。文件类型与文件层级均为单选；组合检索会把每个筛选条件保留到后续官方分页。

湖北使用两个可直连的官方来源组合检索，不请求当前返回 412 的湖北省法规规章规范性文件数据库。默认同时检索湖北人大旧库的现行有效地方性法规/自治法规，以及国家规章库中省份为湖北的地方政府规章：

```bash
# 两个来源合并检索
law-cn search hubei '工伤保险' --scope all

# 仅查湖北人大旧库，组合地域、通过日期和施行日期
law-cn search hubei '' \
  --document-type 地方性法规 \
  --source-param region=武汉市 \
  --source-param passage_from=2025-01-01 \
  --effective-from 2025-01-01 \
  --scope all

# 仅查国家规章库中的湖北政府规章
law-cn search hubei '' \
  --document-type 政府规章 \
  --source-param region=省本级 \
  --source-param government_granularity=LAST_YEAR \
  --scope all --sort newest

# 详情 ID 带来源前缀，CLI 会自动路由正文
law-cn info hubei 'rd:1:875'
law-cn info hubei 'rules:https://www.gov.cn/zhengce/202603/content_7063585.htm'
```

湖北人大旧库的关键词框同时检索标题和正文，没有标题/正文切换；因此 `--scope title` 对该分支是全文检索后的标题后置筛选，`--scope all` 才是原生能力。旧库固定只列出“有效”文件，不支持历史失效状态、文号、制定机关或公布日期筛选。国家规章库当前的地方规章“年份”和“制定部门”字段实测无法产生湖北命中，故 `hubei` 不宣称支持这两项。

最高法官网的检索接口是全站索引，结果会保留官网返回的栏目分类；不应被误解为只包含司法解释。最高检站内搜索跳转至第三方开普云服务，当前直连稳定性不足，因此 `spp` 使用最高检官方四类静态栏目全量分页并在本地执行标题匹配；不会把第三方服务宣称为最高检公开 API。网信办、最高法、最高检等 HTML 来源通常比 JSON 来源更容易受页面结构和 WAF 变化影响。

## 已知限制与在线巡检

自动化测试用于固定请求和解析契约，不能替代官网在线状态。历史巡检覆盖加入最高检之前的 18 个非 NPC 来源；最高检已于 2026-07-25 单独完成官方栏目全分页与详情在线验证。下一次全来源巡检将覆盖 19 个非 NPC 来源。此前详情严格校验中有 14 个完整通过，以下 4 个存在官网侧或文件形态限制：

- 证监会详情接口偶发超时或返回 504。
- 工信部部分官方详情页返回站点配置错误。
- 市场监管总局部分文件只提供 PDF/DOCX 附件，结构化接口中的 `content` 为 `null`。
- 上交所部分完整规则正文只通过官方 DOCX 附件提供。

因此，调用 `info` 后应检查 `body_availability`、`body_note` 和 `attachments`，不能只凭 HTTP 成功就认定已取得全文。官网接口、WAF 和页面结构可能随时变化；具体研究任务仍应核对 `official_url` 指向的官方页面。

## 数据保留规则

- CLI 搜索默认每来源 100 条；`--all` 明确取消该限制，适配器 SDK 直接调用仍默认处理全部分页。
- 不静默去重。工信部搜索返回相似结果分组时，会逐条保留每个组成员；最高检同一文件出现在多个官方栏目时，也逐条保留并标记栏目。
- 不根据标题自行推定文件效力。仅在官网明确提供效力状态时设置 `validity_explicit=true`。
- 不把 Cookie、动态接口凭据或令牌写入源码、输出和清单。
- 国家规章库需要的官网前端鉴权值在运行时读取，只在内存中使用。
- 对官网硬性分页限制或异常字段采用显式适配，并在维护档案中记录证据和处理方式。

## 隐私与网络行为

- 安装包不包含维护者或用户的浏览器 Cookie、访问令牌、API Key、个人 IP 地址或本机路径。
- CLI 没有中心服务器、账户系统或遥测上报；检索请求由用户本机直接发往所选官方来源。
- 与任何网络访问一样，目标官网会看到请求出口的公网 IP；如果配置代理，则通常看到代理出口 IP。
- 少数官网会在请求过程中下发临时 Cookie 或动态鉴权值。适配器只在当前 HTTP 客户端内存中使用，不写入源码、输出、清单或持久化缓存。
- NPC 原始公开文件默认缓存在 `~/.cache/law_cn/documents`；可用 `--no-cache` 禁用，或用 `law-cn cache clear` 显式清理。

## 故障排查

- 先运行 `law-cn --version`、`law-cn sources`、`law-cn capabilities <source>` 和 `law-cn parameters <source>`，确认版本、来源代码和支持参数。
- PyPI 已发布但本地版本较旧时，运行 `uv tool upgrade law-cn-cli`，再用 `law-cn --version` 核对。
- 官网超时、WAF 拦截或 HTML 结构变化时，CLI 会返回非零退出码。不要把失败当成“没有检索结果”，可稍后重试并核对官方页面。
- 搜索默认每来源 100 条；需要穷尽时使用 `--all`，输出清单会记录默认或显式限制及截断状态。

## 开发与验证

```bash
.venv/bin/python -m pytest
.venv/bin/python -m pytest --cov=law_cn --cov-report=term-missing
uv build
uvx twine check dist/*
```

维护仓库中的来源研究档案记录官网入口、检索端点、分页字段、支持能力、验证日期及稳定性说明，但不会打入面向用户的 wheel/sdist。

## 许可证

本项目采用 [PolyForm Noncommercial License 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0)，SPDX 标识为 `PolyForm-Noncommercial-1.0.0`。

允许个人研究、学习、测试以及该许可证列明的非商业组织使用；不授权商业使用。企业内部使用、商业产品或服务集成、收费服务等商业用途应事先另行取得商业授权。完整法律条款以随安装包分发的 [`LICENSE`](LICENSE) 为准。
