contract-archive-cli 0.2.7__tar.gz

contract_archive_cli-0.2.7/.claude/commands/release.md

@@ -0,0 +1,25 @@
+---
+description: 发版到 PyPI（推 tag 触发 GitHub Action 经 Trusted Publishing 发布，验证 PyPI 200）
+---
+
+执行本项目发版，跑 `scripts/release.sh`。
+
+**发版机制：GitHub Action（`.github/workflows/release.yml`）经 PyPI Trusted Publishing 发布。**
+推送 `v<version>` tag 触发 CI：测试 → 构建 → OIDC 可信发布。本地、仓库、secret 里都不存 token。
+
+**核心纪律：发布成功与否以 PyPI 的实际 HTTP 200 为准，绝不相信任何命令/CI 回显。**
+本项目曾因误信回显「以为发了其实没发」（PyPI 实则 404）。`scripts/release.sh` 第 5 步会轮询
+`https://pypi.org/pypi/<pkg>/<version>/json` 直到 200 才算成功，没到就报错并提示去查 CI 日志。
+
+步骤：
+
+1. 确认要发的版本已提交干净：`pyproject.toml` 的 `version` 已 bump、`CHANGELOG.md` 已定版、
+   `uv.lock` 已同步、`git status` 干净。若有未提交改动，先帮用户提交
+   （**精准 `git add <file>`，禁止 `git add -A/.`**）——脚本要求干净工作树且不会自动 commit。
+2. 跑 `scripts/release.sh`（先演练可用 `DRY_RUN=1 scripts/release.sh`，只测试+构建+校验、不推 tag）。
+   它会：干净树检查 → 防重复发布 → 测试 → 构建+twine check → 推 main+tag → 轮询 PyPI 至 200。
+3. 若 PyPI 迟迟不到 200：`gh run list` / `gh run view --log-failed` 看 CI 失败原因，别当成功。
+4. 报告时，「发布成功」的依据必须是 PyPI 200，而不是 publish/CI 的输出。
+
+前置（一次性，已配好则跳过）：PyPI 项目需配置 Trusted Publisher，绑定
+owner=`crhan`、repo=`contract-archive-cli`、workflow=`release.yml`。版本号一旦发布不可覆盖，重发先 bump。

contract_archive_cli-0.2.7/.env.example

@@ -0,0 +1,41 @@
+# 本地合同档案库 CLI - 环境变量模板
+# 复制为 .env 后填入真实 key；.env 已被 gitignore，不会泄露
+#
+# 推荐：secret/常用配置改用 `contract-archive config set`（落 ~/.config，文件 0600），
+# 比项目目录的 .env 更安全。优先级：环境变量(含本 .env) > config 文件 > 默认值——
+# 即本 .env 仍随时可用，且会压过 config 文件。下列变量都可用 config set 等价配置：
+#   DASHSCOPE_API_KEY  → config set dashscope.api_key  <值>
+#   DASHSCOPE_BASE_URL → config set dashscope.base_url <值>
+#   DASHSCOPE_LLM_MODEL→ config set dashscope.model    <值>
+#   CONTRACT_ARCHIVE_DIR→config set archive.dir        <值>
+# （COMPUTE_DEVICE / LOG_LEVEL 是运行时旋钮，仅 env，不进 config 文件。）
+
+# ===== DashScope (阿里百炼) =====
+# 用于合同字段抽取（qwen3.7-max LLM）。不调 OCR；OCR 走 MinerU。
+DASHSCOPE_API_KEY=
+
+# 端点：默认国内站；如用国际站改为 https://dashscope-intl.aliyuncs.com/api/v1
+DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/api/v1
+
+# LLM 模型 ID
+# 注意：qwen3.7-max 是用户在百炼控制台开通的特定别名。
+# 公网用户调用 404 时改成账户能用的：qwen-max / qwen-max-latest / qwen3-max。
+DASHSCOPE_LLM_MODEL=qwen3.7-max
+
+# 多模态签章核查（看落款页图判甲乙方有无章/签字）所用的视觉模型，走 OpenAI 兼容接口。
+# 默认 qwen3.6-flash（实测判得准且省）；要更准用 qwen3.6-plus。
+# 注意 qwen3-vl-flash 实测会把空白落款误判成"有章"，勿用。
+DASHSCOPE_VL_MODEL=qwen3.6-flash
+
+# ===== 档案库 =====
+# 档案库根目录；优先级：CLI --archive > 此变量 > XDG 默认
+# 不设则默认 $XDG_DATA_HOME/contract-archive（即 ~/.local/share/contract-archive）
+# 想自定义再取消注释，例如：
+# CONTRACT_ARCHIVE_DIR=~/Documents/contract-archive
+
+# ===== 通用 =====
+# 计算设备：auto 会依次试 MPS → CUDA → CPU；可硬编码 mps / cuda / cpu
+COMPUTE_DEVICE=auto
+
+# 日志级别
+LOG_LEVEL=INFO

contract_archive_cli-0.2.7/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: release
+
+# 推送 v* tag 触发：测试通过后，经 PyPI Trusted Publishing（OIDC）发布。
+# 不用任何长期 token —— 凭证由 GitHub OIDC 与 PyPI 的可信发布绑定换取。
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv run --extra dev pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Trusted Publishing 必需：换取 OIDC 令牌
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: |
+          rm -rf dist
+          uv build
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

contract_archive_cli-0.2.7/.gitignore

@@ -0,0 +1,47 @@
+# Secrets
+.env
+.env.local
+*.pem
+*.key
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.uv/
+
+# OCR runtime（前置 / 仅匹配根目录，避免误伤 src/archive 代码）
+/archive/
+/output/
+/output.legacy/
+input/*.pdf
+!input/.gitkeep
+models/
+*.onnx
+.mineru_cache/
+huggingface_cache/
+modelscope_cache/
+
+# IDE / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Logs
+*.log
+logs/
+
+# 评测产物（每次跑 evals.run 生成）+ 本地脱敏真实样例（绝不入库，见 evals/README PII 红线）
+evals/results/
+evals/cases/**/private/
+# make_gold 从真实合同生成的脱敏 draft case（未经人工核对脱敏完整性前一律不入库）
+evals/cases_private/
+# 盲标草稿（evals.review 生成的 reviewer scratch，不入库）
+evals/cases/**/blind.json
+
+# 主体身份基准库（含真实 PII：身份证/电话/银行账号）。默认在 XDG 数据目录，
+# 此条仅防档案库被设到 repo 内时误提交——known_parties.json 绝不入库。
+known_parties.json

contract_archive_cli-0.2.7/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+本项目变更记录。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/)，
+版本号语义化（单用户本地工具，破坏性变更会在此显著标注）。
+
+## [0.2.7] — 2026-06-13
+
+### 变更
+- **OCR 阶段改用专用 OCR 模型 `qwen-vl-ocr`，逐页调用**（此前用通用 VL 模型 `qwen3.6-flash`
+  把整份 PDF 全部页塞进一个请求）。新增配置键 `dashscope.ocr_model`（env `DASHSCOPE_OCR_MODEL`，
+  默认 `qwen-vl-ocr-latest`）；签章核查仍用 `dashscope.vl_model`，互不影响。
+  - 动机：旧实现只有上下文极大的通用 VL 才扛得住"一次塞全部页"，慢且易超时；专用 OCR 模型
+    `qwen-vl-ocr` maxInput 仅 30000，必须逐页。实测 91 页保单：572s（旧 923s，快 38%）、
+    91/91 页成功、输出更完整（91984 vs 85157 字符）、单价更低（0.3/0.5 元每百万 token）。
+  - `vl_ocr_max_pages` 默认从 10 放宽到 500：逐页后它不再是单请求页数上限，退化为"防超大 PDF
+    烧太多次调用"的安全阀；保单条款全文普遍 90+ 页，旧默认 10 会让前置 VL 跳过、回退 mineru。
+- **逐页 OCR 健壮性加固**（逐页后单份要发几十上百个请求，失败点随页数累积）：
+  - 单页异常态分标，不再都塞 `[看不清]`——`[本页 OCR 调用失败]`（请求级失败）/
+    `[本页输出达模型上限被截断]`（`finish_reason==length`，单页输出硬上限 8192 token）/
+    `[看不清]`（模型正常返回但本页无文本）。把"技术失败"与"原文模糊"分开，前者可事后审计/补跑。
+  - SDK 重试由默认 2 调高到 4（env `CONTRACT_ARCHIVE_VL_OCR_RETRIES`）：429/超时/5xx 由 openai
+    SDK 自动指数退避（读 `Retry-After`），避免偶发抖动直接丢一整页内容。
+  - 补 `tests/test_vl_ocr.py`（单页失败隔离 / 全失败回退 / 截断标记 / 空输入 / 缺凭证 / 重试旋钮）
+    与 config 层 `dashscope.ocr_model` 覆盖。
+
+## [0.2.0] — 2026-05-29
+
+按 [clig.dev](https://clig.dev/) 做的一轮 human-first 打磨（均为非破坏增量）。
+
+### 新增
+- `config show --format json`：机器可发现配置旋钮（key/env/secret/default/value/source）。
+- `party list` / `party show` 增 `--format json`。
+- `show` / `extract` / `party show` 在 `--format json` 下未命中时吐合法 `{"error":"not_found",...}`
+  信封到 stdout（此前 stdout 全空，破坏 `| jq`），仍以非零退出。
+- 顶层异常钩子：未预期异常翻成一行人话错误，`-v`/`--verbose` 才展开完整 traceback。
+- 无参数运行 `contract-archive` / `config` / `party` 展示帮助（含命令清单），不再报 `Missing command`。
+- `seals` 增 `--seal-owner` / `--seal-type` 别名（与 `search` 词汇统一；旧 `--owner`/`--type` 保留）。
+- `party rm` 删整个主体时增 `--yes` + 非交互守卫（比照 `delete`）。
+- 超时旋钮：`DASHSCOPE_TIMEOUT_S`（默认 300s）、`CONTRACT_ARCHIVE_MINERU_TIMEOUT_S`（默认 1800s）。
+
+### 修复
+- **MinerU 子进程 / LLM / VL 调用此前全无 timeout**：畸形/超大 PDF 可永久挂死整条 ingest，
+  上游 hang 时静默等近 10 分钟。现均有显式上限。
+- `LOG_LEVEL` 非法值（如 `bogus`）此前让所有命令崩 traceback；现降级 INFO + warning。
+- `extract` 失败（空抽取/LLM 异常）此前一律 exit 0，shell 无法靠 `$?` 发现失败；现 exit 1。
+- `--no-color` / `NO_COLOR` 此前对 `raw` 高亮和 `config`/`party` 命令无效；现全命令树一致生效。
+- `ingest` 批量 Ctrl-C 此前跳过末尾 checkpoint；现 try/finally 保证清理。
+- `describe <未知命令>` 现列出全部可选命令。
+- 文案对齐现实：`--no-llm` 不再谎称「只跑 rule」（rule 已退役）；README 项目结构/设计纪律/
+  配置/命令清单全面订正；`--limit` 补 help。
+
+### 变更
+- 命令入口 `contract_archive.cli:app` → `contract_archive.cli:main_entry`（包顶层异常钩子）。
+  **全局安装需 `uv tool install ... --reinstall` 才更新入口脚本。**
+- 自称从「合同档案库」统一为「文档档案库」（工具早已支持合同/证明/发票/报告等）。
+
+## [0.1.x] — 历史（未单独发版）
+
+- **Phase 2**：退役 rule 抽取与 rule/LLM hybrid 合并，合同与通用文档抽取统一为纯 LLM。
+- **Phase 1**（agent-ready 加固）：结构化错误模型（`code`/`category`/`retryable`）；
+  `capabilities`/`describe`/`schema` 机器发现命令；`ingest --progress ndjson` 流式进度；
+  `ingest --dry-run` + `--max-files` 成本闸；XDG 配置 + `config` 子命令组。
+- 初始：MinerU 解析 + qwen3.7-max 字段抽取 + SQLite 索引 + list/search/show/raw/stats/todo/seals。

contract_archive_cli-0.2.7/CLAUDE.md

@@ -0,0 +1,30 @@
+# contract-archive-cli — Agent 须知
+
+记录本项目里容易踩的坑与约定。遇到反直觉的地方，更新这里，帮后来的 agent 少走弯路。
+
+## DashScope 平台接口：优先用 OpenAI 兼容接口
+
+调用阿里云百炼（DashScope）平台的模型，**一律走 OpenAI 兼容接口**
+（`base_url` 用 `https://dashscope.aliyuncs.com/compatible-mode/v1`，`openai` SDK 的
+`chat.completions.create`），**不用原生 `dashscope.Generation.call`**。
+
+为什么：
+- **原生端点不认部分模型 id**：实测 `qwen3.6-flash` 经原生 `/api/v1` 报
+  `400 InvalidParameter: url error`，而经 `/compatible-mode/v1` 正常。第三方托管模型
+  （`deepseek-v4-*`、`glm-5.1` 等）也只在兼容口稳定。
+- **统一一条 transport**：VL 签章线本来就走兼容口；文本线也统一过去后，全项目一个 SDK、
+  一种响应结构，少一类"原生 vs 兼容"的隐藏分叉。
+- **可移植**：OpenAI 标准接口，换供应商/自建网关成本低。
+
+实践要点（JSON 抽取场景）：
+- `base_url` 由配置的 `/api/v1` 做 `.replace("/api/v1", "/compatible-mode/v1")` 得到。
+- 开 `response_format={"type":"json_object"}`；**别设 max_tokens**（否则 JSON 可能被截断成非法串）；
+  prompt 里必须出现 "JSON" 字样；**关思考模式**（思考模型不支持 json_object）。
+- usage 从 `resp.usage`（`prompt_tokens`/`completion_tokens`/`total_tokens`）读，归一化成
+  `input_tokens`/`output_tokens`/`total_tokens`。
+
+## 换模型评测
+
+`evals/` 是离线评测脚手架，判断能否用更便宜模型替换抽取主力模型。两阶段：
+`evals.run`（跑模型→`results.jsonl` 增量累积）+ `evals.report`（读全量→gate 决策报告）。
+换模型走 `extract_document(text, model=m)`，测的是整条生产链路而非裸 JSON。详见 `evals/README.md`。

contract_archive_cli-0.2.7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 crhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

contract_archive_cli-0.2.7/PKG-INFO

@@ -0,0 +1,386 @@
+Metadata-Version: 2.4
+Name: contract-archive-cli
+Version: 0.2.7
+Summary: 本地文档档案库 CLI：OCR 解析 + qwen3.7-max 字段抽取 + SQLite 索引（合同/证明/发票等）
+Author: crhan
+License: MIT
+License-File: LICENSE
+Requires-Python: <3.13,>=3.10
+Requires-Dist: click<9,>=8.0
+Requires-Dist: dashscope>=1.22.2
+Requires-Dist: openai>=1.40
+Requires-Dist: pillow>=10.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.7
+Requires-Dist: socksio>=1.0
+Requires-Dist: tenacity>=8.2
+Requires-Dist: typer<0.26,>=0.12
+Provides-Extra: dev
+Requires-Dist: ipython>=8.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: mineru
+Requires-Dist: mineru[core]<4.0,>=3.1; extra == 'mineru'
+Requires-Dist: scipy>=1.10; extra == 'mineru'
+Description-Content-Type: text/markdown
+
+# 本地文档档案库 CLI
+
+> 把各类文档 PDF 批量入库、归档、可追溯——合同、协议、证明、发票、报告……
+> MinerU 解析版面文本，qwen3.7-max LLM 判类型 + 抽字段，索引到本地 SQLite，
+> 支持按类型/字段过滤检索。
+
+**LLM-first**：文档类型与字段抽取都交给 LLM，统一归一化到一个「通用信封」
+（doc_type / title / summary / 主体 / 金额 / 日期 / 柔性字段）。加新文档类型
+**无需写代码**——LLM 自行决定抽什么。死代码 rule 仅保留为确定性数值归一化
+（中文大写金额→数值、日期→ISO）。合同另有一份调校过的专属 prompt（同样纯 LLM），
+仍保留全部合同字段与查询（甲乙方/到期日/自动续约/风险条款/义务清单）。
+
+历史：本项目最初是 DashScope / PaddleOCR / MinerU 三路 OCR 对比 playground，
+选定 MinerU 后重构为档案库 CLI；再从「合同专用」扩展为「通用文档档案库」。
+
+## ✦ 数据流
+
+```
+PDF ─► sha256 去重 ─► MinerU 解析 ─► LLM 判类型 + 抽字段（合同走专属 prompt，纯 LLM）
+                                          │
+              ┌───────────────────────────┴──┐
+              ▼                              ▼
+   db.sqlite (通用信封 + 索引)     documents/<sha-12>/
+                                    ├── source.pdf  (硬链接)
+                                    ├── mineru/markdown.md ...
+                                    ├── extraction_result.json  (通用信封)
+                                    └── ingest.log
+
+档案库默认在 XDG 数据目录：~/.local/share/contract-archive/
+```
+
+## ✦ 安装
+
+```bash
+# 1) 装 uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 2) 装依赖（mineru extras 会拉 MinerU 包，首次跑 ingest 还会从 modelscope 下模型 >1GB）
+./scripts/setup.sh mineru
+```
+
+> **uv hardlink 坑**：uv 默认 `UV_LINK_MODE=hardlink` 偶发只装包的一部分文件
+> （实测 `cv2`/`pptx` 会丢，触发 `module 'cv2' has no attribute 'INTER_NEAREST'`
+> 或 `cannot import name 'Presentation' from 'pptx'`）。`scripts/setup.sh` 已
+> 显式 `export UV_LINK_MODE=copy` 规避。手动 `uv sync` 时建议也带上。
+> 已损坏的包可以 `uv pip install --force-reinstall --no-deps <包名>` 修。
+
+如果只想用 list/search/show 查已有的档案库（机器上有别的人 ingest 好的 db.sqlite），
+跳过 mineru extras 也可以：
+
+```bash
+./scripts/setup.sh base
+```
+
+## ✦ 全局安装（可选）
+
+如果想在任意目录用 `contract-archive`（不必 `cd` 项目目录或 `uv run`），用 `uv tool install`：
+
+```bash
+# 注意是 ".[mineru]"（项目的 mineru extra = mineru[core]，含 torch 等模型依赖）。
+# 不要用 `--with mineru`——裸 mineru 不带 [core]，装出来的工具跑 ingest 会
+# ModuleNotFoundError: No module named 'torch'。
+# 用 --reinstall 而非 --force：版本号没变时 --force 会命中 uv 缓存里的旧 wheel，
+# 把过时代码装进去（实测会停在旧版本）；--reinstall 强制重建，更新才可靠。
+UV_LINK_MODE=copy uv tool install --reinstall "/path/to/contract-archive-cli[mineru]"
+```
+
+`uv tool install` 会在 `~/.local/bin/contract-archive` 装独立 venv（与项目 venv 隔离）。
+然后从任意目录：
+
+```bash
+# 用环境变量指定档案库
+CONTRACT_ARCHIVE_DIR=~/contracts contract-archive list
+
+# 或显式 --archive（per-command 选项，放在子命令之后）
+contract-archive list --archive ~/contracts
+contract-archive ingest ~/Documents/new_contract.pdf --archive ~/contracts
+```
+
+`DASHSCOPE_API_KEY` 需通过 shell env 提供（建议放进 `~/.zshrc` 或专用 shell wrapper）。
+
+**开发者（改了源码要即时生效）**：加 `--editable`，全局命令指向本仓库源码而非快照——
+改完 `.py` 直接生效，不必每次重装：
+
+```bash
+UV_LINK_MODE=copy uv tool install --editable --reinstall "/path/to/contract-archive-cli[mineru]"
+```
+
+> 不加 `--editable` 装的是「当下代码的快照」：之后改了源码、或仓库升了版本，都得
+> 重新 `--reinstall` 才更新。如果发现 `contract-archive --version` 跟仓库 `pyproject.toml`
+> 对不上，多半就是装了旧快照——重装即可。
+
+卸载：
+
+```bash
+uv tool uninstall contract-archive-cli
+# 数据/配置不随之删除，需手动清理：
+#   ~/.local/share/contract-archive   档案库数据（db.sqlite + documents/）
+#   ~/.config/contract-archive        config.json
+```
+
+## ✦ 配置
+
+两种方式，优先级 **环境变量(含 .env) > config 文件 > 默认值**：
+
+```bash
+# 方式一：config 命令（落 ~/.config/contract-archive/config.json，权限 0600，比项目 .env 更安全）
+contract-archive config set dashscope.api_key sk-xxx
+contract-archive config show              # 看各项当前生效值与来源（secret 默认掩码）
+contract-archive config show --format json   # 机读：含 key/env/secret/default/value/source
+contract-archive config unset dashscope.api_key
+
+# 方式二：项目 .env（老方式，仍支持）
+cp .env.example .env
+$EDITOR .env   # 填入 DASHSCOPE_API_KEY
+```
+
+| 环境变量 | config 键 | 说明 |
+| --- | --- | --- |
+| `DASHSCOPE_API_KEY` | `dashscope.api_key` | 必填。[百炼控制台](https://dashscope.console.aliyun.com/) 申请 |
+| `DASHSCOPE_LLM_MODEL` | `dashscope.model` | 默认 `qwen3.7-max`（用户百炼账户的特定别名；若 404 换 `qwen-max` / `qwen3-max`） |
+| `DASHSCOPE_BASE_URL` | `dashscope.base_url` | 默认 `https://dashscope.aliyuncs.com/api/v1`；海外换 `https://dashscope-intl.aliyuncs.com/api/v1` |
+| `DASHSCOPE_VL_MODEL` | `dashscope.vl_model` | 签章核查视觉模型，默认 `qwen3.6-flash` |
+| `CONTRACT_ARCHIVE_DIR` | `archive.dir` | 档案库根目录，默认 XDG `~/.local/share/contract-archive`；CLI `--archive` 优先 |
+| `COMPUTE_DEVICE` | — | `auto` / `mps` / `cuda` / `cpu`（MinerU 走子进程，主要影响其内部 backend 选择） |
+| `LOG_LEVEL` | — | `DEBUG`/`INFO`/`WARNING`/...，默认 `INFO`；`--verbose`/`--quiet` 覆盖之 |
+| `DASHSCOPE_TIMEOUT_S` | — | LLM/VL 调用超时秒数，默认 `300` |
+| `CONTRACT_ARCHIVE_MINERU_TIMEOUT_S` | — | MinerU 子进程解析超时秒数，默认 `1800` |
+| `MINERU_MODEL_SOURCE` | — | MinerU 模型源，默认 `modelscope`（国内快）；海外可 export `huggingface` |
+
+> 标 `—` 的是运行时旋钮，保持 env-only、不进 config 文件层。
+
+## ✦ 用法
+
+```bash
+# 入库单个 PDF
+uv run contract-archive ingest path/to/合同.pdf
+
+# 批量入库整个目录（递归扫 *.pdf，sha256 去重）
+uv run contract-archive ingest ~/Documents/contracts/
+
+# 跳过 LLM（无 API key 时也用）：仅入库 MinerU 产物，抽取字段留空，可后续 extract 补抽
+uv run contract-archive ingest path/to/合同.pdf --no-llm
+
+# 强制重跑（已 ingest 过的也再跑一遍，覆盖旧记录）
+uv run contract-archive ingest path/to/合同.pdf --reingest
+
+# 试跑前 3 个
+uv run contract-archive ingest ~/Documents/contracts/ --limit 3
+
+# 成本/进度（agent 友好）
+uv run contract-archive ingest ~/Documents/contracts/ --dry-run        # 只预览扫到几个、预计几次 API 调用，不建库不烧钱
+uv run contract-archive ingest ~/Documents/contracts/ --max-files 20   # 超 20 个直接报错退出，防误喂大目录
+uv run contract-archive ingest ~/Documents/contracts/ --progress ndjson  # 每文件一行 JSON 事件，供 agent 流式消费
+```
+
+### 查询
+
+```bash
+# 列出全部（按入库时间倒序，默认 50 条）
+uv run contract-archive list
+
+# 按签订日排序，只看 partial 的
+uv run contract-archive list --order-by sign_date --status partial
+
+# 输出 JSON 供脚本消费
+uv run contract-archive list --format json | jq '.[] | .contract_name'
+
+# 多字段过滤（全部 AND）
+uv run contract-archive search --party 张三 --amount-min 100000 --signed-after 2024-01-01
+uv run contract-archive search --expire-before 2026-12-31 --has-risk
+uv run contract-archive search --name 车位 --auto-renewal
+
+# 看单条详情（id 或 sha 前缀 ≥4 字符）
+uv run contract-archive show 5
+uv run contract-archive show a3f9c2b1
+
+# 看原文：show 看 LLM 抽出的字段，raw 看抽取依据的 OCR 原始文本（同一份喂给 LLM 的内容）
+# 交互终端下按抽取来源给命中关键字着色（当事人/金额/日期/风险/字段），一眼看出哪些被识别到
+uv run contract-archive raw 5
+uv run contract-archive raw a3f9c2b1 | grep 违约           # 管道时自动纯文本，不破坏 grep
+uv run contract-archive raw 5 --color always | less -R     # 强制上色配 less -R
+```
+
+### 待办看板（义务清单）
+
+每份合同抽取时会拆出双方"动作"（递交资料/付款/交付/签字等）作为
+独立的 `obligations` 表，每条带 `actor` (甲方/乙方/双方) + `deadline`：
+
+```bash
+# 跨合同列出所有待办（按 deadline 升序，NULL 排最后）
+contract-archive todo --include-undated
+
+# 未来 30 天内要做的事
+contract-archive todo --within-days 30
+
+# 只看甲方任务 / 只看乙方任务
+contract-archive todo --actor party_a
+contract-archive todo --actor party_b --before 2026-12-31
+
+# 找"近 30 天内有截止动作的合同"（不是单条 obligation，而是合同列）
+contract-archive search --deadline-before 2026-06-30 --actor party_b
+```
+
+`contract-archive show <id>` 会按甲方/乙方/双方分组展示该合同所有义务，
+与原本的 `risk_clauses`（违约罚则）严格区分。
+
+### 身份核对（known_parties 基准库）
+
+抽取时把每个主体（自然人/机构）与其固有标识（身份证号/电话/银行账号/开户行/税号…）
+**精确绑定到人**（`person_identities`），不像扁平字段那样把多人号码混成一条。
+入库时与 `known_parties` 基准库比对，采用「首见入库、再见校对」：
+
+- **首见**：某主体的某标识第一次出现 → 录入为基准（记首见出处）。
+- **再见**：同主体同标识再出现 → 与基准比对，不一致即在 `show` 的「身份核对」块报
+  `identity` 缺陷（疑似 OCR 读错或信息被改），**不覆盖基准**。
+- 比较前归一化剥离分隔符噪声（空格/；/：不误报），但多/少/错位的真实数字差异会被抓出。
+- 不分自然人/机构——身份证、电话、银行账号、开户行一律核对。
+
+```bash
+contract-archive party list                       # 列出所有已知主体及标识
+contract-archive party show 张三                   # 查看某主体的标识基准
+contract-archive party set 张三 身份证号 1101...   # 手动修正基准（纠正被 OCR 读错的首见值）
+contract-archive party rm 张三 电话                # 删除某标识；省略标识则删整个主体
+```
+
+> 基准库 `known_parties.json` 存档案库根目录，**含真实 PII**（身份证/电话/账号），
+> 文件权限 0600、列入 `.gitignore`，绝不入库或分享。
+
+### 抽取层管理
+
+LLM 跑挂或想升级 prompt 后批量再抽取——不重跑 MinerU：
+
+```bash
+uv run contract-archive extract 5            # 复跑 id=5 的抽取
+uv run contract-archive extract 5 --no-llm   # 跳过 LLM（抽取字段留空，rule 已退役）
+```
+
+### 统计与维护
+
+```bash
+uv run contract-archive stats                # 总数 / status 分布 / 按月签订 / 近 30 天到期
+uv run contract-archive delete 5             # 默认仅删 DB 行，交互确认
+uv run contract-archive delete 5 --purge-files -y    # 同时删 archive/documents/<sha>/，无确认
+uv run contract-archive vacuum               # 大批量 ingest 后整理碎片
+```
+
+> **注意**：`delete` 不会删用户原 PDF 文件——`source_path` 字段记录的是入库时
+> 的源路径，源文件归用户所有。
+
+### 印章总览
+
+```bash
+uv run contract-archive seals                      # 跨文档列全部印章
+uv run contract-archive seals --seal-owner 示例公司   # 某主体的章（--owner 同义）
+uv run contract-archive seals --seal-type 合同专用章   # 按印章类型（--type 同义）
+```
+
+### 机器发现 / agent 接入
+
+把本 CLI 包成 MCP / OpenAI tool，或让 agent 自动调用时，用这几个命令免去硬编码——输出皆 JSON：
+
+```bash
+uv run contract-archive capabilities          # 全部命令 + 副作用/破坏性/幂等元数据
+uv run contract-archive describe ingest       # 单命令参数 schema（名称/类型/必填/默认/可选值）
+uv run contract-archive schema document        # 核心数据结构 JSON Schema（document/contract/confidence/error）
+```
+
+数据命令（list/search/show/stats/todo/seals/party/extract/ingest）都支持 `--format json`，
+stdout 纯净可 `| jq`；失败结果带结构化 `error`（`code`/`category`/`retryable`），供 agent 判是否重试。
+
+## ✦ 档案库目录结构
+
+```
+archive/
+├── db.sqlite                     # 索引表
+├── db.sqlite-wal / -shm          # WAL 模式产物（运行时）
+├── ingest.jsonl                  # 总日志（每次 ingest 一行 JSON）
+└── documents/
+    └── a3f9c2b1/                 # sha256 前 12 位
+        ├── source.pdf            # 硬链接源 PDF（跨盘 fallback copy）
+        ├── mineru/
+        │   ├── markdown.md
+        │   ├── layout.json       # bbox 已归一到 PDF point
+        │   ├── structured.json
+        │   ├── raw_text.txt
+        │   ├── pipeline_meta.json
+        │   └── preview_images/
+        ├── extraction_result.json    # 抽取字段（通用信封）
+        ├── extraction_confidence.json
+        └── ingest.log            # 单合同 stderr
+```
+
+## ✦ Docker
+
+```bash
+docker build -t contract-archive -f docker/Dockerfile .
+docker run --rm -it \
+  -v $PWD/archive:/app/archive \
+  -v $PWD/input:/app/input \
+  -v ~/.cache/modelscope:/root/.cache/modelscope \
+  --env-file .env \
+  contract-archive uv run contract-archive ingest /app/input
+```
+
+挂载 modelscope 缓存复用本机 MinerU 模型。Mac 容器不直通 GPU，强烈推荐 native venv 跑。
+
+## ✦ 项目结构
+
+```
+contract-archive-cli/
+├── pyproject.toml          # uv 依赖管理（extras: mineru）
+├── docker/Dockerfile
+├── .env.example
+├── scripts/
+│   └── setup.sh
+├── contract_archive/
+│   ├── cli.py              # 入口 main_entry + 写命令 ingest/extract/delete/vacuum + 组装
+│   ├── cli_common.py       # app 实例 + 全局 callback + 参数 Enum + 双 console + 路径/ident 解析
+│   ├── cli_query.py        # 只读命令 list/search/show/raw/stats/todo/seals
+│   ├── cli_config.py       # config show/set/unset 子命令组
+│   ├── cli_party.py        # party list/show/set/rm（known_parties PII 基准库）
+│   ├── cli_introspect.py   # capabilities/describe/schema 机器发现命令
+│   ├── cli_render.py       # 纯渲染层（Table / JSON dict / raw 高亮）
+│   ├── schemas/            # pydantic schema（BBox/LayoutBlock/DocumentExtraction 等）
+│   ├── pipelines/
+│   │   └── mineru_pipeline.py   # MinerU subprocess 调用 + 坐标归一化 + markdown 清洗
+│   ├── extraction/              # 纯 LLM 抽取（rule/hybrid 自 Phase 2 退役）
+│   │   ├── document_extractor.py  # 通用文档判类型 + 抽信封
+│   │   ├── contract_extractor.py  # 合同专属字段（专属 prompt）
+│   │   ├── llm_extractor.py        # DashScope OpenAI 兼容口调用
+│   │   ├── vision_seal.py          # 落款页 VL 签章核查
+│   │   ├── normalize.py / amount_check.py / evidence_page_fix.py / property_fee.py
+│   ├── archive/
+│   │   ├── db.py                # SQLite 连接 + migrations 引擎
+│   │   ├── repository.py        # DAO + 搜索查询构造
+│   │   ├── ingest.py            # 入库流水线（hash → MinerU → extract → rename → DB）
+│   │   ├── party_registry.py    # known_parties 身份基准库
+│   │   ├── paths.py             # 档案库路径约定 + 硬链接工具
+│   │   └── migrations/          # 001_init … 005_completeness（5 个）
+│   ├── errors.py               # 结构化错误模型（code/category/retryable）
+│   ├── config.py               # XDG 配置 + env>file>default
+│   └── utils/                   # 设备选择 / PyMuPDF PDF 渲染
+├── archive/                # 档案库数据（gitignored）
+├── input/                  # 用户放待处理 PDF
+└── output.legacy/          # 旧 pipeline 历史产物（重构前的对比数据，可删）
+```
+
+## ✦ 设计纪律
+
+- **统一 schema**：MinerU 的 0-1000 归一化坐标全部反算成 PDF point；markdown 反斜杠转义在喂给抽取层前清洗
+- **纯 LLM 抽取**：自 Phase 2 退役 rule/hybrid，字段全由 LLM 抽取；每字段附 `value_source`（仅 `llm`/`missing`）+ 置信度。死代码 rule 仅保留为确定性数值归一化（中文大写金额→数值、日期→ISO）
+- **API key 不出包**：仅从 env 读，日志不打印响应体
+- **sha256 去重**：流式 hash 后查 UNIQUE 索引；命中即 skip 避免 MinerU 跑一次几分钟才发现重复
+- **事务边界**：tmp 目录跑全 → `os.rename` 到 documents/ → DB INSERT；任一阶段失败回滚干净，DB 不留半成品
+- **partial 状态可修复**：MinerU OK 但 LLM 挂时 markdown 仍可用，`extract <id>` 命令只重跑抽取层
+- **不并发 MinerU**：每个 subprocess 会加载 GB 级模型，并发反而 OOM；默认 workers=1