> ## Documentation Index
> Fetch the complete documentation index at: https://adp-doc.laiye.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ADP CLI

> Laiye ADP 官方开源命令行工具，一句命令完成文档解析与关键字段抽取

## 概述

ADP 是来也科技基于大模型通用理解能力的**智能体文档处理产品（Agentic Document Processing，简称 ADP）**：不依赖规则与标注，具备多语种、多模态、多场景的通用理解能力；智能体自主规划与执行，能理解任务目标、自主拆解步骤、调用工具、完成复杂任务；从文档输入到业务决策再到人机协同，形成端到端的业务自动化闭环。

**agentic-doc-parse-and-extract**（简称 ADP CLI）是 ADP 的官方开源命令行工具，同时支持手动终端调用与 AI Skill 自动调用。一句命令即可完成：结构化文档解析 + 关键字段智能抽取，覆盖发票、订单、证件、票据、通用文档等全场景，输出标准 JSON，无缝接入自动化与 AI 工作流。

<CardGroup cols="2">
  <Card title="GitHub" icon="github" href="https://github.com/laiye-ai/adp-cli">
    laiye-ai/adp-cli
  </Card>

  <Card title="NPM" icon="npm" href="https://www.npmjs.com/package/@laiye-adp/agentic-doc-parse-and-extract-cli">
    @laiye-adp/agentic-doc-parse-and-extract-cli
  </Card>

  <Card title="PyPI" icon="python" href="https://pypi.org/project/agentic-doc-parse-and-extract/">
    agentic-doc-parse-and-extract
  </Card>

  <Card title="Releases" icon="download" href="https://github.com/laiye-ai/adp-cli/releases">
    预编译二进制包
  </Card>
</CardGroup>

## 核心功能

agentic-doc-parse-and-extract 专注于文档全流程的智能化处理，兼顾手动终端调用与 AI Agent 自动调用。核心功能覆盖解析、抽取、批处理全场景，无需复杂配置，一句命令即可完成：

| 功能                            | 描述                                                                          | 适用场景                         |
| ----------------------------- | --------------------------------------------------------------------------- | ---------------------------- |
| **Document Parsing**          | 自动识别 PDF、图片等多格式文档，将杂乱的非结构化内容（扫描件、手写本、复杂版面）转为标准化结构化数据，同时保留原始层级与关键关系          | 将非结构化文档转为 LLM 可读的结构化数据，供后续抽取 |
| **Out-of-the-Box Extraction** | 基于 ADP 大模型原生 AI 能力，内置发票/收据/订单/中国常用证件等标准化抽取模型，无需配置规则或人工标注，一键抽取关键字段并输出标准 JSON | AP 自动化、费用管理、采购自动化、卡证信息快速入库   |
| **Custom Extraction**         | 支持自主创建、编辑与管理个性化抽取应用，为企业专属文档与行业定制表单配置专属字段与识别逻辑                               | 企业专属/行业定制/非标准化文档的私有抽取需求      |
| **Task Query**                | 支持异步任务提交与状态查询，快速查看任务执行进度、成功/失败状态与最终处理结果                                     | 批量任务处理、异步文档处理、问题追溯与记录追踪      |
| **Application Management**    | 提供完整的应用管理能力，可查看全部可用抽取应用（系统内置 + 自定义）、查询应用详情、管理应用标签                           | 多场景业务切换、应用全生命周期管理、自定义应用管理    |

## 安装与更新

<CodeGroup>
  ```bash Agent 集成 theme={null}
  npx skills add laiye-ai/adp-cli -y -g
  ```

  ```bash NPM theme={null}
  npm install -g @laiye-adp/agentic-doc-parse-and-extract-cli
  ```

  ```text Windows theme={null}
  irm https://raw.githubusercontent.com/laiye-ai/adp-cli/main/scripts/adp-init.ps1 | iex
  ```

  ```text Mac os/Linux theme={null}
  curl -fsSL https://raw.githubusercontent.com/laiye-ai/adp-cli/main/scripts/adp-init.sh | bash
  ```

  ```text PYPI theme={null}
  pip install agentic_doc_parse_and_extract
  ```
</CodeGroup>

<Note>
  PyPI 平台包截止v1.10, 并且后续不再维护，请通过 npm 更新到最新版本。
</Note>

## 配置

在 [adp.laiye.com](https://adp.laiye.com/) 获取 API Key（新用户每月 100 免费 credits）。

```bash theme={null}
adp config set --api-key <your-api-key>
adp config set --api-base-url https://adp-global.laiye.com
adp config get
```

## 快速示例

```bash theme={null}
# 列出可用应用
adp app-id list

# 解析本地文档
adp parse local ./invoice.pdf --app-id <app-id>

# 抽取关键字段
adp extract local ./invoice.pdf --app-id <app-id>

# 异步批量处理目录
adp parse local ./documents/ --app-id <app-id> --async

# 远程 URL 处理
adp extract url https://example.com/file.pdf --app-id <app-id>

# 查询异步任务
adp parse query <task-id>

# 两阶段异步（提交与查询分离，可恢复）
adp extract local ./documents/ --app-id <app-id> --async --no-wait --export tasks.json
adp extract query --watch --file tasks.json

# 失败自动重试（最多 2 次）
adp parse local ./documents/ --app-id <app-id> --retry 2

# 查看剩余额度
adp credit
```

## 命令列表

<Note>
  AI Agent 应调用 `adp schema` 获取机器可读的权威命令规范。下表为人类友好的速查摘要。
</Note>

| 命令                               | 说明                           |
| -------------------------------- | ---------------------------- |
| `adp version`                    | 输出版本                         |
| `adp config set`                 | 设置 API key / base URL        |
| `adp config get`                 | 显示当前配置                       |
| `adp config clear`               | 清除配置                         |
| `adp app-id list`                | 列出可用应用                       |
| `adp app-id cache`               | 从本地缓存读取应用列表                  |
| `adp parse local <path>`         | 解析本地文件/目录                    |
| `adp parse url <url>`            | 解析远程文件（支持 URL 列表文件）          |
| `adp parse base64 <data>`        | 解析 Base64 内容                 |
| `adp parse query <task-id...>`   | 查询异步解析任务（支持多个 ID 或 `--file`） |
| `adp extract local <path>`       | 抽取本地文件/目录                    |
| `adp extract url <url>`          | 抽取远程文件                       |
| `adp extract base64 <data>`      | 抽取 Base64 内容                 |
| `adp extract query <task-id...>` | 查询异步抽取任务（支持多个 ID 或 `--file`） |
| `adp custom-app create`          | 创建自定义抽取应用                    |
| `adp custom-app update`          | 更新自定义应用配置                    |
| `adp custom-app get-config`      | 显示应用配置                       |
| `adp custom-app delete`          | 删除自定义应用                      |
| `adp custom-app delete-version`  | 删除指定配置版本                     |
| `adp custom-app ai-generate`     | AI 推荐抽取字段                    |
| `adp credit`                     | 显示剩余额度                       |
| `adp schema`                     | 输出命令 schema（供 AI Agent 使用）   |

## Flags

| Flag                  | 说明                                     |
| --------------------- | -------------------------------------- |
| `--json`              | JSON 输出                                |
| `--quiet`             | 静默模式，仅输出结果                             |
| `--lang <en\|zh >`    | 界面语言                                   |
| `--app-id`            | 应用 ID（parse / extract 必填）              |
| `--async`             | 异步模式                                   |
| `--no-wait`           | 仅提交任务、不等待结果（与 `--async` 配合）            |
| `--export <path>`     | 导出结果到文件（单文件）或目录（批量）                    |
| `--timeout <seconds>` | 超时（默认 900s）                            |
| `--concurrency <n>`   | 并发数（免费版最大 1，付费版最大 2）                   |
| `--retry <n>`         | 可重试错误的重试次数（默认 0）                       |
| `--file <path>`       | 从 JSON 文件读取任务 ID（`--no-wait` 的输出，仅查询用） |

## 异步工作流

对于大文件或批量任务，使用 `--async` 提交，CLI 返回 `task-id`，再通过 `parse query` / `extract query` 轮询结果：

```bash theme={null}
adp parse local ./big.pdf --app-id <app-id> --async
# 返回 task-id

adp parse query <task-id>
```

### 两阶段异步（`--no-wait`）

默认情况下 `--async` 会提交并轮询直到完成——适合 AI Agent。对于可恢复的工作流，使用两阶段模式：

**Phase 1 提交任务：**

```bash theme={null}
adp extract local ./documents/ --app-id <app-id> --async --no-wait --export tasks.json
```

输出为带任务 ID 的 JSON 数组：

```json theme={null}
[
  { "path": "invoice.pdf", "task_id": "task_abc123" },
  { "path": "contract.pdf", "task_id": "task_def456" }
]
```

**Phase 2 查询结果：**

```bash theme={null}
adp extract query --watch --file tasks.json
adp extract query --watch --file tasks.json --export ./results/
```

<Tip>
  即使 CLI 中途崩溃，`tasks.json` 中的任务 ID 仍保留——随时可用 `query --file` 恢复。
</Tip>

## 批处理

处理多个文件/URL 时，CLI 会将每个结果写入独立文件：

```text theme={null}
adp_results_20250417_153020/
├── _summary.json              # 汇总：总数、成功、失败、逐件状态
├── invoice_01.pdf.json        # 成功结果
├── contract_02.docx.json
└── report_03.pdf.error.json   # 错误详情
```

* `--export <dir>` — 指定输出目录
* 不带 `--export` — 自动创建 `adp_results_<timestamp>/`
* 单文件 — 输出到 stdout 或 `--export` 指定的文件路径

## Exit Codes

| Code | 含义              |
| ---- | --------------- |
| `0`  | 全部成功            |
| `1`  | 全部失败 / 系统错误     |
| `2`  | 参数错误            |
| `3`  | 资源不存在           |
| `4`  | 权限不足            |
| `5`  | 冲突              |
| `6`  | 部分失败（批量中部分任务失败） |

## 环境变量

| 变量                 | 说明                                        |
| ------------------ | ----------------------------------------- |
| `ADP_API_KEY`      | API key（覆盖配置文件）                           |
| `ADP_API_BASE_URL` | 服务 URL                                    |
| `ADP_LANG`         | 界面语言（`en` / `zh`）                         |
| `ADP_LOG_LEVEL`    | 日志级别（`debug` / `info` / `warn` / `error`） |

## 配置存储

* 配置目录：`~/.adp/`
* 配置文件：`~/.adp/config.json`
* 加密 API key：`~/.adp/key.enc`（AES-256-GCM）
* 应用缓存：`~/.adp/app_cache.json`
* 版本检查缓存：`~/.adp/version_check.json`（每 24 小时刷新）

## 许可证

采用开源工具 + 付费服务的组合模式：CLI 工具完全免费开源，便于快速集成；核心 ADP 智能解析能力为公有云商业服务，按实际用量计费，旨在提供高准确率、稳定的文档处理体验。

* **CLI 工具**：MIT 开源，可自由使用、修改与分发
* **ADP 服务**：基于公有云的 AI 文档处理服务，按使用量计费

免费额度：新用户注册后每月可获得 **100 免费 credits**，体验全部功能。

## 支持与联系

* **问题反馈：** [GitHub Issues](https://github.com/laiye-ai/adp-cli/issues)
* **邮箱：** [mkt@laiye.com](mailto:mkt@laiye.com)
* **官网：** [Laiye Technology](https://laiye.com/en/)