Metadata-Version: 2.4
Name: doccheck-cli
Version: 0.1.0
Summary: Skill-driven document review CLI
Project-URL: Homepage, https://github.com/Mingyu-Xu-98/doccheck-cli
Project-URL: Repository, https://github.com/Mingyu-Xu-98/doccheck-cli
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: python-docx>=1.1
Requires-Dist: openpyxl>=3.1

# DocCheck CLI

Skill 驱动的合同审核 CLI。用户提供合同文件或目录后，DocCheck 会自动完成文档解析、合同画像、规则适用性判断、规则审核和结果输出。

## 当前能力

- 支持单文件和目录批量审核。
- 每次审核创建独立 Run Workspace，隔离输入文件、解析产物、任务状态和审核结果。
- 内置 5 条已发布审核 Skill，首次配置后可直接审核合同。
- 支持 OpenAI-compatible 模型网关，主 Agent 和规则 Worker 可配置不同模型。
- 支持本地轻量解析、jyppx 本地高精度解析、MinerU/Doc2X/PDF2X 等远程商业解析服务。
- 支持 Excel 审核规则导入，并由主 Agent 深度分析生成可执行 Skill。
- 支持 SQLite Taskboard、失败重试、断点恢复、Run 重命名和 JSON 报告。
- 支持交互式 Shell，提供 `/config`、`/check`、`/resume`、`/rename` 等命令。

## 安装

当前版本还没有发布到 PyPI，推荐从 GitHub 安装：

```bash
pipx install git+https://github.com/Mingyu-Xu-98/doccheck-cli.git
```

更新到最新版：

```bash
pipx install --force git+https://github.com/Mingyu-Xu-98/doccheck-cli.git
```

发布到 PyPI 后，安装命令会变成：

```bash
pipx install doccheck-cli
```

本地开发安装：

```bash
git clone https://github.com/Mingyu-Xu-98/doccheck-cli.git
cd doccheck-cli
pipx install -e .
```

安装后验证：

```bash
doccheck --version
doccheck onboard --help
```

## 快速开始

第一次使用需要配置两类服务：

- 模型服务：主 Agent 和规则审核 Worker 使用。
- 解析服务：PDF/DOCX 等合同文件解析使用。

交互式配置：

```bash
doccheck onboard
```

检查配置：

```bash
doccheck doctor
```

开始审核：

```bash
doccheck check "/路径/合同或合同目录"
```

查看历史任务：

```bash
doccheck runs
doccheck status <run-id>
```

审核结果位于：

```text
$DOCCHECK_HOME/workspaces/<run-id>/results/result.json
```

如果未设置 `DOCCHECK_HOME`，默认使用：

```text
~/.doccheck
```

## 非交互配置示例

### 使用阿里百炼模型

以百炼中国北京区域为例：

```bash
doccheck onboard \
  --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 \
  --api-key "$DASHSCOPE_API_KEY" \
  --deepseek-model qwen-plus \
  --qwen-model qwen-plus \
  --parser-provider mineru_agent
```

说明：当前 CLI 参数名仍保留 `--deepseek-model`，它实际表示“主 Agent 模型”。如果不用 DeepSeek，也可以填写百炼、LiteLLM 或其他 OpenAI-compatible 网关中的模型名。

### 使用自定义 LiteLLM 网关

```bash
doccheck onboard \
  --base-url https://your-litellm.example/v1 \
  --api-key "$MODEL_API_KEY" \
  --deepseek-model deepseek-v4-flash \
  --qwen-model qwen-plus \
  --parser-provider local_docx
```

### 使用 MinerU v4 解析

```bash
doccheck onboard \
  --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 \
  --api-key "$DASHSCOPE_API_KEY" \
  --deepseek-model qwen-plus \
  --qwen-model qwen-plus \
  --parser-provider mineru_v4 \
  --parser-api-key "$MINERU_TOKEN"
```

### 使用 Doc2X/PDF2X 解析

```bash
doccheck onboard \
  --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 \
  --api-key "$DASHSCOPE_API_KEY" \
  --deepseek-model qwen-plus \
  --qwen-model qwen-plus \
  --parser-provider doc2x \
  --parser-api-key "$DOC2X_API_KEY"
```

## 模型与 Key

模型 API Key 和解析服务 API Key 分开保存：

```text
模型 Key:   $DOCCHECK_HOME/credentials/model_api_key
解析 Key:   $DOCCHECK_HOME/credentials/parser_api_key
```

也可以使用环境变量：

```bash
export DEEPSEEK_API_KEY="模型服务 Key"
export QWEN_API_KEY="模型服务 Key"
export DOCCHECK_PARSER_API_KEY="解析服务 Key"
```

配置文件路径：

```text
$DOCCHECK_HOME/config.json
```

关键配置项：

- `models.orchestrator`：主 Agent，用于合同画像、规则分析和必要的复核。
- `models.rule_worker`：规则审核 Worker，用于按 Skill 判断每条规则。
- `parser.provider`：文档解析器。
- `runtime.rule_worker_concurrency`：规则审核并发数。
- `runtime.max_rules_per_document`：单文档同时执行的规则数。

## 解析服务

| Provider | 是否需要安装额外工具 | 是否需要解析 Key | 适用场景 |
| --- | --- | --- | --- |
| `local_docx` | 否 | 否 | 轻量解析 DOCX/Markdown/TXT，不提供 PDF 页码和坐标 |
| `mineru_agent` | 否 | 否 | MinerU 轻量解析，适合快速试用，有文件和访问限制 |
| `mineru_v4` | 否 | 是 | MinerU 商业解析，适合正式 PDF/DOCX 解析 |
| `doc2x` / `pdf2x` | 否 | 是 | Doc2X/PDF2X 商业解析，可获得页级 Markdown |
| `jyppx_tool` | 是 | 否 | 本地高精度解析，适合私有化部署和页码/坐标定位 |
| `pdf_v1` | 否 | 视服务而定 | 已有 V1 解析服务兼容入口 |

执行合同审核时不需要先手工解析。`doccheck check` 会根据当前 `parser.provider` 自动调用解析器。

只想测试解析：

```bash
doccheck parse "/路径/合同.pdf" -o parsed-output
```

## jyppx 本地解析

`jyppx_tool` 是可选能力，适合已经部署 jyppx/PPX 的本地或私有化环境。公开 README 不应写入任何个人机器路径，实际路径应由安装用户在 onboarding 时填写：

```bash
doccheck onboard \
  --parser-provider jyppx_tool \
  --jyppx-python "/path/to/jyppx/.venv/bin/python" \
  --jyppx-runner "/path/to/jyppx/projects/<project>/deliverable/parser.py"
```

也可以通过环境变量提供路径：

```bash
export JYPPX_PYTHON="/path/to/jyppx/.venv/bin/python"
export JYPPX_RUNNER="/path/to/jyppx/projects/<project>/deliverable/parser.py"
doccheck onboard --parser-provider jyppx_tool
```

`jyppx_tool` 会把 jyppx deliverable 作为隔离的本地解析工具调用，并消费其输出的 `doc.json`、`tree.json` 和 chunks。审核结果可以保留页码、坐标、章节路径和对象类型。

DOCX 会优先通过 jyppx 和 LibreOffice 转换为 PDF，以获得页码和坐标定位。如果 LibreOffice 不可用，CLI 会降级为 DOCX 结构解析并继续审核，不会中断任务。

macOS 安装 LibreOffice：

```bash
HOMEBREW_NO_AUTO_UPDATE=1 brew install --cask libreoffice
```

## 内置 Skill 与扩展规则

第一版安装后已经内置 5 条 `published` 正式 Skill。普通用户只需要配置模型和解析服务，然后上传合同即可审核。

后续要扩展规则库时，可以从 Excel 导入：

```bash
doccheck skills import-excel 审核规则.xlsx
doccheck skills analyze --rule 103
doccheck skills validate
doccheck skills publish
```

Skill 生命周期：

```text
pending_deepseek -> deepseek_analyzed -> published
```

正式审核默认只使用 `published` Skill。重新分析规则会生成新的草稿版本，不会覆盖已经发布的版本快照。

## 常用命令

```bash
doccheck onboard
doccheck doctor
doccheck doctor --list-models
doccheck doctor --auto-qwen
doccheck check "/路径/合同或合同目录"
doccheck parse "/路径/合同.pdf" -o parsed-output
doccheck runs
doccheck status <run-id>
doccheck retry <run-id>
doccheck retry <run-id> --rule 57
doccheck resume <run-id>
doccheck rename <run-id> "项目名称"
doccheck config show
doccheck shell
```

Shell 内命令：

```text
/check "/路径/合同或合同目录" --name "批量合同审核"
/parse "/路径/合同.pdf" -o parsed-output
/runs
/status <run-id>
/retry <run-id> --rule 57
/resume <run-id>
/rename <run-id> "项目名称"
/config
/exit
```

## 常见问题

### 为什么现在不是 `pipx install doccheck-cli`？

因为当前包还没有发布到 PyPI。现在应使用 GitHub 安装：

```bash
pipx install git+https://github.com/Mingyu-Xu-98/doccheck-cli.git
```

发布到 PyPI 后才可以使用：

```bash
pipx install doccheck-cli
```

### Base URL 只能用某个固定地址吗？

不是。DocCheck 接受任意 OpenAI-compatible 模型网关地址，例如阿里百炼、LiteLLM、自建网关或其他兼容服务。用户需要填写自己的 Base URL、模型名和 API Key。

### 没有 jyppx 可以用吗？

可以。普通用户可以选择 `local_docx`、`mineru_agent`、`mineru_v4`、`doc2x` 或 `pdf2x`。`jyppx_tool` 只是本地高精度解析的一种可选部署方式。

### 结论里能定位原文吗？

取决于解析器能力。`jyppx_tool`、`mineru_v4`、`doc2x`/`pdf2x` 更适合输出页码、章节和原文来源；`local_docx` 更适合低成本 DOCX 文本审核。
