feat: add uniparser CLI with auth, parse, fetch, health, version, and user docs

README.md

@@ -44,22 +44,59 @@ UniParser Tools 是一个强大的文档解析工具包，支持对 PDF 文件
 
 ## 安装
 
+安装 Python 依赖：
+
 ```bash
 pip install -r requirements.txt
 ```
 
-或者安装为可编辑包：
+使用 **`uniparser` 命令行工具**时，还需将本仓库安装为可编辑包（入口在 `pyproject.toml` 中注册）：
 
 ```bash
 pip install -e .
 ```
 
+> **说明：** 仅执行 `pip install -r requirements.txt` **不会**注册 `uniparser` 命令；SDK 开发用前者即可，CLI 必须执行 `pip install -e .`。
+
+安装后验证：
+
+```bash
+uniparser --help
+```
+
+CLI 完整说明见 [`cli/README.md`](./cli/README.md)。
+
+## CLI 命令行
+
+`uniparser` 提供 `auth`、`parse`、`fetch`、`health`、`version` 等子命令。
+
+| 命令 | 说明 |
+|------|------|
+| `uniparser auth` | 交互式配置 API Key（写入 `~/.uniparser/config.yaml`） |
+| `uniparser parse INPUT` | 解析本地 PDF/图片或公网 PDF URL |
+| `uniparser fetch --token TOKEN` | 用已有 token 轮询并下载结果 |
+| `uniparser health` | 检查服务健康状态（需要 API Key） |
+| `uniparser version` | 查看本地包版本（无 API Key 时跳过远端查询） |
+
+**API Key 优先级：** `--api-key` > `UNIPARSER_API_KEY` > `~/.uniparser/config.yaml`
+
+**`--json` 须写在子命令之前：** `uniparser --json parse paper.pdf`
+
+参数、输出文件、错误码等详见 [`cli/README.md`](./cli/README.md)。
+
+首次使用：
+
+```bash
+uniparser auth
+uniparser parse report.pdf
+```
+
 ## API-Key 配置
 
 所有请求都通过 `X-API-Key` 请求头认证，`UniParserClient` 会自动注入。
 
 - **获取方式**：在 UniParser 服务首页（如 `https://uniparser.dp.tech/`）注册访客账号，或向运维/业务方申请长期 API-Key。
-- **推荐存储**：使用环境变量 `UNIPARSER_API_KEY`，避免在代码中硬编码。
+- **推荐存储**：运行 `uniparser auth`，或设置环境变量 `UNIPARSER_API_KEY`，避免在代码中硬编码。
 - **错误处理**：Key 缺失/过期、限流等情况都会被客户端统一包装成 `{"status": "error", ...}` 返回，详见下方 [错误处理](#错误处理)。
 
 ```python
@@ -452,6 +489,10 @@ uv run python -m uniparser_mcp   # 启动 MCP 服务（stdio 模式）
 ## 项目结构
 
 ```
+cli/                  # uniparser 命令行工具（见 cli/README.md）
+├── commands/         # auth, parse, fetch, health, version
+└── core/             # 配置、凭证、pipeline、输出
+
 uniparser_tools/
 ├── api/              # API 客户端
 ├── common/           # 通用常量和数据类
@@ -477,6 +518,7 @@ playground/
 
 项目提供了丰富的示例和教程，位于 `playground/` 目录下：
 
+- **CLI 命令行**：[`cli/README.md`](./cli/README.md) - `uniparser` 安装、子命令与参数说明
 - **快速开始**：`playground/01.quick_start.ipynb` - 基础用法教程，包括 PDF 和图片解析、多种格式输出
 - **高级用法**：`playground/02.advance.ipynb` - 高级功能教程，包括图片+图题+图注、表格+表题+表注、分子+分子索引、公式+公式索引的提取
 - **异步回调**：`playground/04.use_callbacks.py` - 异步回调演示，用于在异步解析任务完成后自动接收通知和结果

cli/README.md

@@ -0,0 +1,277 @@
+# UniParser CLI 使用说明
+
+`uniparser` 是 UniParser 的命令行工具，用于把 PDF、图片或公网 PDF 链接解析成 Markdown，并保存到本地目录。
+
+官网与 API Key 申请：[https://uniparser.dp.tech/](https://uniparser.dp.tech/)
+
+---
+
+## 安装
+
+在仓库根目录执行（**必须**用这一条，才会安装 `uniparser` 命令）：
+
+```bash
+cd /path/to/UniParser-Tools
+pip install -e .
+```
+
+> 只运行 `pip install -r requirements.txt` **不会**出现 `uniparser` 命令。
+
+检查是否安装成功：
+
+```bash
+uniparser --help
+```
+
+---
+
+## 快速开始
+
+**第一次使用：配置 API Key**
+
+```bash
+uniparser auth
+```
+
+按提示在 [https://uniparser.dp.tech/](https://uniparser.dp.tech/) 获取 Key 并粘贴保存。配置会写入 `~/.uniparser/config.yaml`，下次无需重复输入。
+
+**解析一个 PDF**
+
+```bash
+uniparser parse /path/to/report.pdf
+```
+
+默认把结果保存到：
+
+```text
+~/Uni-Parser-Skill/report/
+├── report.md           # 解析后的 Markdown
+├── pages_tree.json     # 文档版面结构（可选查阅）
+└── trigger_meta.json   # 任务信息（含 token，便于中断后恢复）
+```
+
+终端会显示 `Parsing... report.pdf`，完成后打印 Markdown 与输出目录路径。
+
+---
+
+## 命令一览
+
+| 命令 | 作用 |
+|------|------|
+| `uniparser auth` | 配置 / 查看 API Key |
+| `uniparser parse INPUT` | 解析文件或 PDF 链接 |
+| `uniparser fetch --token TOKEN` | 用已有任务 token 重新下载结果 |
+| `uniparser health` | 检查服务是否可用 |
+| `uniparser version` | 查看工具版本 |
+
+---
+
+## 配置 API Key
+
+### 交互式配置（推荐）
+
+```bash
+uniparser auth
+```
+
+已有 Key 时直接回车可保留当前配置。
+
+### 其他方式
+
+也可任选其一（优先级从高到低）：
+
+1. 命令行临时指定：`uniparser --api-key YOUR_KEY parse file.pdf`
+2. 环境变量：`export UNIPARSER_API_KEY="YOUR_KEY"`
+3. 配置文件：`~/.uniparser/config.yaml`（由 `uniparser auth` 写入）
+
+### 查看与检查
+
+```bash
+uniparser auth --show      # 查看 Key 来源与脱敏后的 Key
+uniparser auth --verify    # 检查是否已配置（不联网校验）
+```
+
+---
+
+## 解析文档：`parse`
+
+### 基本用法
+
+```bash
+# 本地 PDF
+uniparser parse paper.pdf
+
+# 本地图片（png、jpg、webp 等）
+uniparser parse figure.png
+
+# 公网 PDF 链接
+uniparser parse https://example.com/paper.pdf
+```
+
+### 常用选项
+
+| 选项 | 说明 |
+|------|------|
+| `-o` / `--output-dir DIR` | 指定输出目录（默认 `~/Uni-Parser-Skill/<文件名>/`） |
+| `--overwrite` | 输出目录已存在时，先清空再写入 |
+| `--async` | 异步提交任务（适合较大文档） |
+
+### 解析配置（7 类语义）
+
+未指定的字段使用 **scientific-paper** 默认值（与网站推荐科学文献配置一致）。只写你关心的 `--xxx` 即可覆盖对应项。
+
+| 选项 | 含义 | 可选值 | 默认值 |
+|------|------|--------|--------|
+| `--textual` | 普通文本 | `disable` / `ocr-fast` / `ocr-hq` / `digital` / `base64` | `ocr-hq` |
+| `--equation` | 数学公式 | `disable` / `ocr-fast` / `ocr-hq` / `base64` | `ocr-hq` |
+| `--table` | 表格 | 同上 | `ocr-hq` |
+| `--chart` | 图表 | 同上 | `base64` |
+| `--figure` | 插图 | 同上 | `base64` |
+| `--expression` | 化学反应式 | 同上 | `base64` |
+| `--molecule` | 化学分子 | 同上 | `ocr-fast` |
+
+示例：
+
+```bash
+# 全部默认（scientific-paper）
+uniparser parse paper.pdf
+
+# 数字 PDF 直接抽文本，其余保持默认
+uniparser parse paper.pdf --textual digital
+
+# 关闭分子解析
+uniparser parse paper.pdf --molecule disable
+
+# 多项覆盖
+uniparser parse paper.pdf --textual digital --table ocr-fast --molecule disable
+
+# 与输出目录、异步组合
+uniparser parse paper.pdf -o ./results/ --overwrite --async
+```
+
+`trigger_meta.json` 会记录本次实际提交的 `trigger_kwargs`，便于复现配置。
+
+### 输出目录示例
+
+```bash
+uniparser parse paper.pdf -o ./results/
+uniparser parse paper.pdf -o ./results/ --overwrite
+```
+
+### 输出说明
+
+解析成功后，输出目录中通常包含：
+
+| 文件 | 用途 |
+|------|------|
+| `<文件名>.md` | 完整 Markdown 正文（主要结果） |
+| `pages_tree.json` | 版面结构树，便于按章节/块定位 |
+| `trigger_meta.json` | 任务 token、输入信息及 `trigger_kwargs`，供 `fetch` 恢复使用 |
+
+解析过程中终端会显示一行 `Parsing... <文件名>`。大文档可能需要等待数分钟。
+
+---
+
+## 恢复下载：`fetch`
+
+若解析中断，或你已有任务 token，可用 `fetch` 继续拉取结果（不会重新上传文件）：
+
+```bash
+uniparser fetch --token YOUR_TOKEN
+```
+
+token 可在上次 `parse` 输出目录的 `trigger_meta.json` 中找到。
+
+| 选项 | 说明 |
+|------|------|
+| `-o` / `--output-dir DIR` | 指定输出目录（默认 `~/Uni-Parser-Skill/token_<前8位>/`） |
+| `--overwrite` | 输出目录已存在时，先清空再写入 |
+
+```bash
+uniparser fetch --token abcdef1234567890 -o ./out/
+```
+
+---
+
+## 其他命令
+
+### 检查服务
+
+```bash
+uniparser health
+```
+
+需要已配置 API Key。
+
+### 查看版本
+
+```bash
+uniparser version
+```
+
+未配置 API Key 时仍会显示本地工具版本；配置后可同时查看远端服务版本。
+
+---
+
+## 脚本与自动化：`--json`
+
+在命令**最前面**加上 `--json`，成功时会在标准输出打印 JSON，便于脚本解析：
+
+```bash
+uniparser --json parse paper.pdf
+uniparser --json fetch --token YOUR_TOKEN
+```
+
+注意：`--json` 必须写在子命令**之前**：
+
+```bash
+uniparser --json parse paper.pdf    # 正确
+uniparser parse paper.pdf --json    # 错误
+```
+
+---
+
+## 常见问题
+
+**提示 `No API key found`**
+
+运行 `uniparser auth`，或设置环境变量 `UNIPARSER_API_KEY`。
+
+**提示 `File not found`**
+
+检查 `parse` 后的文件路径是否正确（建议使用绝对路径）。
+
+**提示输出目录已存在**
+
+加上 `--overwrite`，或换用 `-o` 指定新目录。
+
+**命令 `uniparser` 找不到**
+
+确认已执行 `pip install -e .`，且与当前终端使用的是同一 Python 环境。
+
+**解析时间较长**
+
+属正常现象；请等待 `Parsing...` 出现后保持终端不要关闭。若中断，用 `trigger_meta.json` 中的 token 执行 `uniparser fetch`。
+
+---
+
+## 推荐使用流程
+
+```bash
+# 1. 安装并配置
+pip install -e .
+uniparser auth
+
+# 2. 解析
+uniparser parse ~/Documents/paper.pdf
+
+# 3. 打开结果
+open ~/Uni-Parser-Skill/paper/paper.md
+```
+
+若需中断后恢复：
+
+```bash
+# 从 trigger_meta.json 复制 token
+uniparser fetch --token <token>
+```

cli/__init__.py

@@ -0,0 +1 @@
+"""UniParser command-line interface."""

cli/__main__.py

@@ -0,0 +1,5 @@
+from cli.main import cli
+
+
+if __name__ == "__main__":
+    cli()

cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI subcommands."""