xparse-cli 2.6.0 → 2.6.1-beta.2

package/README.md

@@ -1,25 +1,723 @@
-# xparse-cli
+# TextIn xParse CLI
 
-TextIn xParse command-line client for document parsing, image correction and manipulation detection.
+TextIn xParse 文档解析命令行工具，基于 [TextIn xParse API](https://docs.textin.com/api-reference/endpoint/xparse/v1/parse-sync) 实现。
 
-## Install
+支持将 PDF、图片、Office 文档等 20+ 格式转换为 Markdown 及结构化数据。
 
-```sh
+## 安装
+
+需要 Node.js 18 或更高版本：
+
+### 安装正式版
+
+```bash
 npm install --global xparse-cli
+```
+
+国内网络可以显式使用 npmmirror：
+
+```bash
+npm install --global --registry=https://registry.npmmirror.com xparse-cli
+```
+
+安装后运行以下命令检查版本：
+
+```bash
 xparse-cli version
 ```
 
-Node.js 18 or later is required. Supports macOS, Linux and Windows on x64 and ARM64.
+### 安装 beta 或精确版本
+
+跟随当前 beta：
+
+```bash
+npm install --global xparse-cli@beta
+```
+
+为了获得可复现的测试环境，应安装精确版本：
+
+```bash
+npm install --global xparse-cli@2.6.0
+```
+
+### 升级
+
+```bash
+npm install --global xparse-cli@latest
+```
+
+beta、精确版本以及国内镜像同样通过 `npm install --global` 管理。CLI 不再单独下载或替换二进制文件。
+
+WorkBuddy 集成、国内/海外 Connector 区别、beta 命名规则及完整发版步骤见
+[WorkBuddy Connector 概念与发版流程](docs/workbuddy_connector_release.md)。
+
+## Remote MCP 服务
+
+同一 Go module 还提供 `cmd/xparse-mcp`。它与 CLI 复用 `internal/client` 和
+`internal/parseflow`，因此解析参数、额度路由、顺序执行、一次重试和多段结果合并使用
+同一份实现。MCP 只接受服务端可访问的 `file_url` 或已上传的 `file_id`；本地文件由
+MCP Host 先调用 `prepare_file_upload`，按返回的通用上传会话直接上传到 TextIn。
+
+国内 MCP 新增 `detect_manipulation`，接受 `file_url` 或 `file_id`，支持可选的
+`tamper_threshold`、`aigc_threshold`。本地文件先调用
+`prepare_file_upload`，设置 `operation=detect_manipulation`，上传后逐个检测。
+`get_quota` 可指定 `service=manipulation_detection`。额度不足或未知时，须取得
+用户对本次可能付费调用的同意后设置 `approve_paid=true`，不自动重试计费请求。
+结果包含风险元数据和可选 JPEG 热力图内容块；`image_index` 按图片内容块从零编号。
+图片展示与保存取决于 Host 能力；服务端不缩图，不通过普通文本返回 Base64。
+
+国内切边增强矫正通过 CLI `crop-enhance`、MCP `crop_enhance` 调用。
+MCP 同样接受 `file_url` 或 `file_id`；本地上传指定 `operation=crop_enhance`。
+查询独立额度使用 `quota --service crop_enhance_image` 或
+`get_quota` 的同名 `service`。未传参数时保持服务默认值：开启切边、形变矫正，
+关闭增强和方向校正。CLI 保存结果 JSON 和全部 JPEG；MCP 按顺序返回原始图片内容块。
+仅坐标模式 `only_position=1` 无图片属于正常结果。
+
+```bash
+xparse-cli crop-enhance scan.jpg --enhance-mode 5 --view json
+xparse-cli crop-enhance scan.jpg --crop-image 0 --dewarp-image 0 --enhance-mode 2
+```
+
+两类图像服务共用请求、鉴权头、额度判断和结果拆图；CLI 负责落盘，MCP 负责
+协议输出。接口及改造边界见 [图像工具实现说明](docs/image-tools.md)。
+
+MCP 是独立容器产物，不进入 npm CLI 包：
+
+```bash
+make mcp-build
+make mcp-image MCP_IMAGE=registry.example/xparse-mcp:tag
+```
+
+服务通过 OAuth 验证 audience 绑定的 MCP Token，再使用通用 OAuth Token Exchange
+取得短时委托 Token 调用公开 xParse API；不会调用 workflow-backend 内部 MCP 路由，
+也不识别平台或维护 T币确认状态。
+
+MCP 服务使用 `gopkg/tlog` 输出 JSON 日志，通过 `gopkg/ttrace` 将请求 trace
+发送到 OTLP HTTP 采集器。部署时配置 `OTEL_PROVIDER_ENDPOINT`，值为 `host:port`
+（不带协议和路径）；国内 TEST/PRE 与现有后端一致，使用 `jaeger-collector:4318`。
+本地调试可指向本机采集器，例如 `OTEL_PROVIDER_ENDPOINT=localhost:4318`。
+trace 服务名为 `xparse-mcp`；请求日志和后台遥测发送日志保留同一 `trace_id`，
+请求取消不影响后台发送原有的超时和关闭逻辑。退出时先等待遥测发送，再刷新 trace。
+
+构建依赖私有模块 `gitlab.intsig.net/ke_wang/gopkg`。本地 Go 开发需配置
+`GOPRIVATE=gitlab.intsig.net` 和 GitLab 读取权限；镜像构建通过 BuildKit secret
+`gitlab_token` 传入可读取该模块的 `CI_JOB_TOKEN`，令牌不写入镜像或源码。
+`make mcp-image` 同样读取该环境变量；GitLab 的 `gopkg` 项目需允许此项目的 Job Token
+读取仓库。
+
+## 开发与发布 Make 命令
+
+仓库根目录的 `Makefile` 统一管理 WorkBuddy Connector 组包和 npm 发布。
+`REGION` 未设置或为空时默认生成国内包。
+
+生成国内、海外或双区域的 Connector 正式审核包：
+
+```bash
+make connector-review
+make connector-review REGION=global
+make connector-review-all
+```
+
+生成指定环境的 Connector 测试安装包。`VERSION` 为需要测试的精确 CLI 版本，
+`ENVIRONMENT` 支持 `test`、`pre` 和 `prod`：
+
+```bash
+make connector-test VERSION=2.3.1-beta.1 ENVIRONMENT=test
+```
+
+如需使用其他通用 xParse Skill 目录，可显式传入：
+
+```bash
+make connector-test \
+  VERSION=2.3.1-beta.1 \
+  ENVIRONMENT=test \
+  SKILL_DIR=/path/to/xparse-skills/skills/xparse-parse
+```
+
+同步 npm 持久版本。该命令会更新主包版本、六个平台依赖版本、npm tag 和
+`release-lock.json` 的基础版本：
+
+```bash
+make set-version VERSION=2.3.1-beta.1
+```
+
+执行七个 npm 包的完整打包与发布 dry-run，不会上传包：
+
+```bash
+make npm-publish-dry-run VERSION=2.3.1-beta.1
+```
+
+正式发布七个 npm 包必须同时指定精确版本和确认开关：
+
+```bash
+make npm-publish VERSION=2.3.1-beta.1 CONFIRM_PUBLISH=1
+```
+
+`npm-publish` 和 `npm-publish-dry-run` 都会先同步版本，并校验命令版本、源码
+manifest、staging 目录和七个待发布包完全一致。stable 版本发布到 `latest`，
+`-beta.*` 版本发布到 `beta`。
+
+## 快速开始
+
+### 1. 零配置解析（自动使用免费额度）
+
+```bash
+# 输出 Markdown 到终端
+xparse-cli parse report.pdf
+
+# JSON 视图
+xparse-cli parse report.pdf --view json
+
+# 保存到目录
+xparse-cli parse report.pdf --output ./output/
+
+# 指定页码范围
+xparse-cli parse report.pdf --page-range "1-5"
+
+# 加密 PDF
+xparse-cli parse secret.pdf --password mypassword
+```
+
+### 2. 付费 API（可选）
+
+前往 [TextIn 控制台](https://www.textin.com/user/login?redirect=%252Fconsole%252Fdashboard%252Fsetting&from=xparse-parse-skill) 获取凭证（`x-ti-app-id` 和 `x-ti-secret-code`），然后运行：
+
+```bash
+xparse-cli auth
+```
+
+按提示输入 App ID 和 Secret Code，凭证将保存至 `~/.xparse-cli/config.yaml`。
+
+也可通过环境变量配置（适合 CI/CD）：
+
+```bash
+export XPARSE_APP_ID=your_app_id
+export XPARSE_SECRET_CODE=your_secret_code
+```
+
+```bash
+# 显式使用付费 API
+xparse-cli parse report.pdf --api paid
+```
+
+### 3. 多文件 Task Runtime（Agent 推荐）
+
+解析与抽取统一使用 `task run`：省略 `--task-type` 时仍为解析，原有参数兼容。
+
+独立上传可先取得原始 File Asset ID，不会启动解析或抽取；同一操作重试请保留 `--operation-id`：
+
+```bash
+xparse-cli upload contract.pdf --operation-id <OPERATION_ID>
+xparse-cli task run --task-type extract --instruction '抽取甲乙方' --file-id <UPLOADED_FILE_ID>
+```
+
+创建抽取任务时，服务端复用已有解析结果；尚未解析的文件进入现有付费托管解析。解析费与抽取费分别按现有规则结算。创建响应的 `document_count` 仅计已接入抽取的文件，未解析文件可能尚未计入；CLI 的 `submitted_file_count` 是本次提交的 ID 数。
+
+```bash
+xparse-cli task run --task-type parse a.pdf
+xparse-cli task run --task-type extract --instruction '抽取编号与金额' --file-id <FILE_ID>
+xparse-cli task add <PARSE_TASK_ID> b.pdf
+xparse-cli task add <EXTRACTION_TASK_ID> --file-id <FILE_ID>
+xparse-cli task status <TASK_ID>
+xparse-cli task result <TASK_ID> --limit 50
+xparse-cli task export <EXTRACTION_TASK_ID> --format json --output ./results
+```
+
+顶层 `extract` 已移除。创建抽取接受刚上传或已解析的 File Asset，解析专用参数不能用于抽取；追加文件的 `task add --file-id` 仍只接受已解析文件。
+追加根据服务端类型分发；解析会追加输入并请求新一轮处理，抽取沿用既有任务要求。
+解析追加若绑定后启动失败，应保留 `operation_id`、`task_id` 并按错误提示恢复。
+
+抽取分页返回 `snapshot`，后续页使用 `--offset` 和同一个 `--snapshot`；快照变化应重取。
+抽取 JSON/CSV 导出分别写入目录内 `results.json` / `results.csv`，只含就绪文档的业务结果；
+命令响应单独返回完整性、未完成/失败文件和需复核字段，不能将部分导出视为全量成功。
+标量保留字符串（不把编号转换为数字），对象/数组保持结构，未找到的值为 null。
+旧解析 `--view markdown|json`、`--output` 目录及 `task read/rerun` 保持兼容。
+新服务端提供抽取类型及结果投影后才能使用新查询与导出命令。
+
+Task Runtime 把上传、执行状态和结果交给服务端持久化。`task run` 默认在提交 Run
+成功后立即返回 `operation_id`、`task_id` 和 `run_id`；Agent 后续锁定该 Run 查看进度，完成后再按需读取或导出结果，不需要把全部结果放进上下文。WorkBuddy 下 stderr 输出 `xparse_event.v1` JSONL：服务端接受 Run 后立即输出 `run_accepted`，后续状态变化输出 `run_status`；stdout 始终只输出一份最终提交 JSON。
+
+```bash
+xparse-cli task run --files 'contracts/*.pdf'
+xparse-cli task status <task-id> --run-id <run-id>
+xparse-cli task export <task-id> --run-id <run-id> --output ./task-output
+xparse-cli task export <task-id> --run-id <run-id> --view json --output ./task-json
+xparse-cli task read <task-id> contract-a.pdf --run-id <run-id>
+xparse-cli task debug <task-id> --run-id <run-id>
+```
+
+`task export` 默认导出 Markdown；需要消费完整 xParse 结构化结果时显式使用
+`--view json`。两种视图都会生成 `task-manifest.json`，其中包含
+`total_count`、`completed_count`、`failed_count`、`exported_count` 以及每个文件的
+状态、输出文件名和失败恢复信息，调用方不得把部分成功静默当作全量完成。
+
+需要在同一个 Task 下创建新 Run 时，显式选择重跑范围：
+
+```bash
+# 重跑 Task 已绑定的全部 Resource
+xparse-cli task rerun <task-id> --mode all
+
+# 上传新文件、绑定到现有 Task，并仅处理新 Resource
+xparse-cli task rerun <task-id> --mode new-files --files 'new-docs/*.pdf'
+
+# 只重跑指定的已有 Resource；--resource-id 可重复
+xparse-cli task rerun <task-id> --mode selected-files \
+  --resource-id <resource-id> --resource-id <resource-id>
+```
+
+`new-files` 不创建替代 Task；返回结果沿用原 `task_id` 并生成新的 `run_id`。
+若新文件受密码保护，使用可重复的 `--password`，多文件时按
+`selector=password` 绑定。
+
+若提交响应丢失，使用进度事件或错误详情中的同一 `operation_id` 重试：
+
+```bash
+xparse-cli task run --files 'contracts/*.pdf' --operation-id <operation-id>
+```
+
+同一操作 ID 会生成 Task 与 Run 两层幂等键；改了文件、模式或配置后必须使用新的操作 ID。
+
+需要在一个终端命令中等待完成并导出时，显式使用 `--wait`：
+
+```bash
+xparse-cli task run --files 'contracts/*.pdf' --wait --output ./task-output
+```
+
+`--wait` 只是在客户端持续轮询同一个 `run_id`，不会把服务端 Task 变成同步任务。达到
+`--timeout` 时 CLI 正常退出并返回当前状态、原 `task_id` / `run_id`、
+`wait_timed_out: true` 和 `next_action: "POLL_STATUS"`；它不会取消或重建 Run。之后使用
+`task status` 继续查询同一个 Run。Agent 流程默认不使用 `--wait`，也不要自动附加较短的固定超时。
+
+单个文件的密码与 `parse` 一样直接使用 `--password`，CLI 会在第一次上传时携带密码：
+
+```bash
+xparse-cli task run secret.pdf --password open-password
+```
+
+多个输入中只有部分文件有密码时，只为受保护文件重复传入 `selector=password` 绑定。selector
+可使用精确路径、唯一文件名，或 `PASSWORD_INPUT_REQUIRED` 返回的稳定 selector：
+
+```bash
+xparse-cli task run a.pdf b.jpg c.pdf \
+  --password a.pdf=open-a \
+  --password c.pdf=open-c
+```
+
+如果上传阶段返回 `PASSWORD_INPUT_REQUIRED`，CLI 会扫描完本批次并一次性返回所有缺失或错误
+密码文件。使用返回的 selector 和同一 `operation_id` 补充 `--password selector=password`，然后
+重放原始命令：首次提交重放 `task run`，`task rerun --mode new-files` 增加文件时则重放原 rerun。
+显式复用同一 `operation_id` 时，CLI 会复用已 ready 的上传资产。此时即使错误中已有 `task_id`，
+尚未成功上传的新文件也不是 Task Resource，不能使用 `task continue`。
+
+只有 Task Run 已经接受、`task debug` 确认现有 Resource 在执行阶段返回密码错误时，才更新该
+Resource 的访问密码并创建 selected-files Run：
+
+```bash
+xparse-cli task continue <task-id> \
+  --password <resource-id>=open-password
+```
+
+`continue` 同样默认提交即返回；保存新的 `run_id`，完成后再单独执行 `task export`。只有显式添加 `--wait` 时才能同时使用 `--output`。
+
+等待人工付费授权或充值后，必须恢复精确 Run：
+
+```bash
+xparse-cli task resume <task-id> --run-id <run-id> --approve-paid
+xparse-cli task resume <task-id> --run-id <run-id> --after-funding
+```
+
+文件资源只保存加密的文件访问密码；`force_engine`、页范围和 capabilities 属于具体 Run。Runtime 的 MinerU 恢复只覆盖当前失败 RunItem，不会写回可复用资源。`--api auto/free` 不会自动授权付费；需要付费时会停在可见状态并要求人工批准。
+
+也可以使用 OAuth。正式二进制默认使用无 Secret 的 public client
+`cli_textin_xparse`；私有部署可以通过 flag、环境变量或配置文件覆盖：
+
+```bash
+# 终端中进入 AppKey / OAuth / 状态 / 登出选单
+xparse-cli auth
+
+export XPARSE_OAUTH_CLIENT_ID=cli_your_registered_client
+
+# Device Flow（SSH、服务器、Agent 推荐）
+xparse-cli auth device --open-browser=never
+
+# 本地桌面 Authorization Code + PKCE；默认使用系统分配的可用回调端口
+xparse-cli auth browser
+
+# 强制重新展示授权确认页
+xparse-cli auth browser --prompt=consent
+
+# 显式使用 OAuth 调用 paid API
+xparse-cli parse report.pdf --api paid --auth-method oauth
+```
+
+认证选单使用方向键或 `j`/`k` 移动，`Enter` 确认，`Esc` 或 `Ctrl+C` 取消。
+菜单会显示当前环境、OAuth/AppKey 配置状态和当前生效的认证方式。需要屏幕阅读器兼容的
+线性提示时，可设置 `XPARSE_TUI_ACCESSIBLE=1`。
+
+WorkBuddy Connector 使用显式 Profile，避免依赖任务进程是否继承 Connector 环境变量：
+
+```bash
+xparse-cli --profile workbuddy auth device --open-browser=always
+xparse-cli --profile workbuddy parse report.pdf --api paid --auth-method oauth
+```
+
+该 Profile 的凭证保存在 `~/.xparse-cli/profiles/workbuddy/`，其登录和登出不会影响
+终端中默认的 `~/.xparse-cli` 凭证；请求会自动携带 `X-From: workbuddy`。
+
+Larkoffice 使用相同的认证和 Task 命令行为，凭证保存在独立的
+`~/.xparse-cli/profiles/larkoffice/`。OAuth 默认使用国内公开客户端
+`cli_textin_xparse_larkoffice`，仍遵循 `--client-id`、环境变量和配置文件的覆盖顺序；
+AppKey 回退与 WorkBuddy 相同。请求自动携带 `X-From: larkoffice`。
+
+```bash
+xparse-cli --profile larkoffice auth device --open-browser=always --output=jsonl
+xparse-cli --profile larkoffice auth status --output=json
+xparse-cli --profile larkoffice parse report.pdf
+```
+
+EasyClaw 使用独立的 OAuth-only Profile：
+
+```bash
+xparse-cli --profile easyclaw auth device --output jsonl
+xparse-cli --profile easyclaw auth status --output json
+xparse-cli --profile easyclaw parse report.pdf
+xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
+```
+
+该 Profile 固定使用 OAuth Client `cli_textin_xparse_easyclaw`，凭证保存在
+`~/.xparse-cli/profiles/easyclaw/`，不读取 AppKey 或其他 Profile 的 token。普通解析使用
+`auto` 路由：符合每日免费接口能力时优先使用每日额度，否则使用已有免费套餐；只有两类
+额度都不足时才要求切换付费。请求自动携带 `X-From: easyclaw`。
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| `xparse-cli parse` | 解析文档，输出 Markdown / JSON |
+| `xparse-cli upload` | 单文件上传，返回原始 File Asset ID，不启动解析 |
+| `xparse-cli task run` | 上传并执行多文件持久化 Task |
+| `xparse-cli task rerun` | 在现有 Task 下按 all/new-files/selected-files 创建新 Run |
+| `xparse-cli task status` | 查询 Task 和最新 Run 状态 |
+| `xparse-cli task export` | 按 Markdown/JSON 视图批量导出成功结果和带汇总计数的 manifest |
+| `xparse-cli task read` | 读取单个文件结果 |
+| `xparse-cli task debug` | 查看逐文件错误与恢复证据 |
+| `xparse-cli task continue` | 补充逐文件密码并选择性续跑 |
+| `xparse-cli task resume` | 在付费授权或充值确认后恢复精确 Run |
+| `xparse-cli auth` | TTY 中进入认证选单；非 TTY 保持旧版 AppKey 输入流程 |
+| `xparse-cli auth app-key` | 配置 AppKey 凭证 |
+| `xparse-cli auth device` | OAuth Device Flow 登录 |
+| `xparse-cli auth browser` | OAuth Authorization Code + PKCE 登录 |
+| `xparse-cli auth status` | 只读查看登录状态 |
+| `xparse-cli auth logout` | 删除指定认证方式的本地凭证 |
+| `xparse-cli config` | 管理配置（show / set / reset / path） |
+| `xparse-cli quota` | 查看解析与抽取免费额度 |
+| `xparse-cli quota --service manipulation_detection --output json` | 查看国内篡改检测免费套餐次数；不会发起检测 |
+| `xparse-cli download` | 下载解析结果中 elements 的图片 |
+| `xparse-cli cache` | 查看或清理本地文档缓存 |
+| `xparse-cli get_doc_info` | 读取本地 PDF 基础信息 |
+| `xparse-cli get_outline` | 读取缓存文档的目录结构 |
+| `xparse-cli read_content` | 按元素 ID 读取缓存内容 |
+| `xparse-cli read_pages` | 按页码范围读取缓存内容 |
+| `xparse-cli search_text` | 搜索缓存文档文本 |
+| `xparse-cli get_confidence` | 查询元素或页面的 OCR 置信度 |
+| `xparse-cli completion` | 生成 shell 自动补全脚本 |
+| `xparse-cli version` | 显示版本信息 |
+
+全局参数 `--profile workbuddy` 或 `--profile easyclaw` 可放在子命令前后，用于选择隔离凭证。
+
+文档解析缓存和 `doc_id` 元数据默认保存在 `~/.xparse-cli/cache` 与
+`~/.xparse-cli/docinfo`。Harness 或其他受沙箱管理的宿主可以为每个 session 设置绝对路径
+`XPARSE_STATE_DIR`，此时两类状态分别写入该目录下的 `cache/` 与 `docinfo/`。
+该变量只改变文档状态目录，不改变 AppKey、OAuth 或 CLI 配置位置；相对路径会被拒绝。
+
+## parse 命令参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--view` | `markdown` | 输出视图：`markdown`、`json` |
+| `--api` | `auto` | API 模式：`auto`、`free`、`paid`；`auto` 根据服务端额度快照路由 |
+| `--auth-method` | _(自动)_ | 请求认证：`app-key`、`oauth` |
+| `--page-range` | | 页码范围：`"1-5"` 或 `"1-2,5-10"` |
+| `--password` | | 加密文档密码 |
+| `--include-hierarchy` | `true` | 元素层级关系与父子关联，默认开启。为 `false` 时关闭 |
+| `--include-inline-objects` | `true` | 内嵌对象：公式、手写、复选框、嵌入图片，默认开启。为 `false` 时关闭 |
+| `--include-image-data` | `true` | 图片 URL 及 Base64 数据，默认开启。为 `false` 时关闭 |
+| `--include-table-structure` | `true` | 表格单元格结构与坐标，默认开启。为 `false` 时关闭 |
+| `--include-pages` | `true` | 分页元数据与预览图 |
+| `--include-title-tree` | `true` | 文档标题层级目录树 |
+| `--include-char-details` | `false` | 返回字符级坐标和置信度 |
+| `--table-view` | `html` | 表格视图：`html`、`markdown` |
+| `--export` | | 额外导出格式：`docx`、`pdf`、`xlsx`，支持逗号分隔或重复传递；需配合 `--api paid --output <目录>` |
+| `--list` | | 从文件读取输入列表（需配合 `--output`） |
+| `--output` | _(stdout)_ | 输出文件路径或目录（目录不存在时自动创建） |
+| `--error-format` | `json` | 错误输出格式：`json`、`text` |
+
+**全局参数（所有命令均支持）：**
+
+| 参数 | 说明 |
+|------|------|
+| `--app-id` | TextIn App ID（覆盖环境变量和配置文件） |
+| `--secret-code` | TextIn Secret Code（覆盖环境变量和配置文件） |
+| `--base-url` | API 地址（私有化部署时使用） |
+| `--profile` | 凭证 Profile：`workbuddy`、`easyclaw` |
+| `--task-context` | Agent 任务上下文 JSON 文件路径 |
+| `--verbose` | 调试模式，打印 HTTP 请求详情 |
+
+### API capabilities 默认值
+
+CLI 默认开启以下能力，Agent 无需额外配置：
+
+| 能力 | 默认 |
+|------|------|
+| 标题层级 | 开启 |
+| 内嵌对象（图片） | 开启 |
+| 图片数据 | 开启 |
+| 表格视图 | `html` |
+| 表格结构 | 开启 |
+| 分页结果 | 开启 |
+| 目录树 | 开启 |
+| 字符级详情 | **关闭**（`--include-char-details` 开启） |
+
+## 使用示例
+
+### 导出其他格式
+
+```bash
+# 自动下载 DOCX、PDF 和 XLSX 到输出目录
+xparse-cli parse report.pdf --api paid --export docx,pdf,xlsx --output ./results/
+```
+
+`xlsx` 会自动使用 `config.scope=table`。CLI 使用付费解析的 AppKey 或 OAuth 身份
+下载导出文件，输出为 `<basename>.docx`、`<basename>.pdf` 和 `<basename>.xlsx`。
+若目标文件会覆盖输入原文，则改用 `<basename>.export.<format>`。
+
+### 管道组合
+
+```bash
+# 解析并搜索
+xparse-cli parse report.pdf | grep "revenue"
+
+# 解析并喂给 LLM
+xparse-cli parse paper.pdf | llm "summarize this paper"
+```
+
+### 批量处理
+
+```bash
+# 从文件列表读取
+xparse-cli parse --list files.txt --output ./results/
+```
+
+### 下载图片
+
+```bash
+# 从解析结果 JSON 中提取 elements 图片并下载
+xparse-cli download --from result.json --output ./images/
+
+# 直接下载图片 URL
+xparse-cli download https://web-api.textin.com/ocr_image/external/abc123.jpg --output ./images/
+```
+
+### 配置管理
+
+```bash
+xparse-cli config show
+xparse-cli config set base_url https://your-server.com
+xparse-cli config reset
+xparse-cli config path
+```
+
+### 升级 CLI
+
+```bash
+npm install --global xparse-cli@latest
+```
+
+### 调试模式
+
+```bash
+xparse-cli parse report.pdf --verbose
+```
+
+## 凭证管理
+
+| 优先级 | 方式 | 说明 |
+|--------|------|------|
+| 1 | 命令行参数 | `--app-id` 和 `--secret-code` |
+| 2 | 环境变量 | `XPARSE_APP_ID` 和 `XPARSE_SECRET_CODE` |
+| 3 | 配置文件 | `~/.xparse-cli/config.yaml` |
+
+AppKey 与 OAuth Token 分开保存：
+
+```text
+~/.xparse-cli/config.yaml       # AppKey 和非敏感 OAuth 偏好
+~/.xparse-cli/oauth-token.json  # OAuth Access/Refresh Token
+```
+
+目录权限固定为 `0700`，凭证文件固定为 `0600`，更新通过 fsync + rename 原子替换。
+`xparse-cli config reset` 只重置 YAML，不会删除 OAuth Token；请使用
+`xparse-cli auth logout --method oauth|app-key|all` 精确登出。
+OAuth 登出会先尝试通过 `/oauth21/revoke` 撤销 Refresh Token（没有时撤销 Access
+Token），随后始终删除本地 Token。远端暂时不可用只会产生警告，不会阻止本地登出；
+登出不会删除服务端记住的 consent。
+
+OAuth 参数优先级：
+
+| 参数 | 优先级 |
+|------|--------|
+| Client ID | `--client-id` > `XPARSE_OAUTH_CLIENT_ID` > `oauth.client_id` > public default `cli_textin_xparse` |
+| Scope | `--scope` > `XPARSE_OAUTH_SCOPE` > `oauth.scope` > `ocr:*` |
+| Browser redirect | `--redirect-uri` > `XPARSE_OAUTH_REDIRECT_URI` > `oauth.redirect_uri` > `http://127.0.0.1:0/callback` |
+| Base URL | `--base-url` > `XPARSE_BASE_URL` > `base_url` > `https://api.textin.com` |
+
+不传 `--api` 时使用 `auto`：CLI 先读取现有 quota 接口，在匿名每日免费额度与登录
+用户的免费套餐额度之间制定执行计划。显式 `--api free` 固定调用免费 Agent 接口，
+显式 `--api paid` 固定调用现有付费接口，不参与自动额度路由，但仍会读取 quota 中的
+`standard_max_file_size_mb`，在上传本地文件前执行标准接口大小预检。旧服务端未下发
+该字段时使用 500MB 兼容值；URL 输入仍由服务端检查。
+
+认证选择顺序为：显式 `--auth-method` / 环境或配置选择 > OAuth > 完整 AppKey >
+匿名（仅可选认证接口）。自动选择 OAuth 时若刷新失败，会先回退完整 AppKey；两者都
+不可用时，quota、免费解析与 telemetry 才匿名继续。显式选择 OAuth 失败不会切换身份。
+篡改检测的命名 quota 查询需要认证，返回的 `free_package.free_remain_count`
+与默认 quota 中的解析套餐和抽取每日额度无关；未返回套餐时额度为未知。
+
+本地 PDF 会使用服务端返回的 `max_pages_per_request` 和 `max_file_size_mb` 预检。
+仅页数超限且原文件体积合规时使用页范围分段；文件体积超限时生成真实临时 PDF
+片段，按可重试错误最多重试一次，并按原始页码顺序合并结果。临时片段执行后删除。
+
+## 退出码与错误处理
+
+`xparse-cli parse` 默认向 stderr 输出一行 JSON；stdout 仍只承载解析结果。退出码保持兼容：
+
+| 码 | 含义 |
+|----|------|
+| 0 | 成功 |
+| 1 | 一般错误 / 网络异常 |
+| 2 | 参数错误 |
+| 3 | API 返回错误 |
+
+基础字段为 `schema_version`、`error_code`、`message`、`actual_value`、`limit`、
+`retryable` 和 `next_action`；需要时还会包含 `upgrade_url`、`request_id`、`task_id`
+和 `details`。`actual_value` 与 `limit` 不可确认时为 `null`，不会使用过期的本地固定值。
+
+```json
+{"schema_version":"xparse_error.v1","error_code":"FILE_TOO_LARGE","message":"file exceeds the current service limit","actual_value":{"file_size_mb":12.5},"limit":{"source":"service","max_file_size_mb":8},"retryable":false,"next_action":"REDUCE_FILE","request_id":"644e2efdb..."}
+```
+
+稳定错误码至少包括：`FILE_NOT_FOUND`、`EMPTY_FILE`、`UNSUPPORTED_FILE_TYPE`、
+`FILE_TOO_LARGE`、`PAGE_LIMIT_EXCEEDED`、`PAID_QUOTA_REQUIRED`、
+`AUTHENTICATION_FAILED`、`CAPABILITY_QUERY_FAILED`、`OUTPUT_FAILED`、`SPLIT_FAILED`、
+`MERGE_FAILED` 和 `RETRY_EXHAUSTED`。服务端返回 `40422` 时仍包装为
+`SERVICE_ERROR`，`message` 保留服务端给出的直接原因；程序判断使用 `next_action`，
+诊断时可读取 `details.api_code` 和 `request_id`。
+
+人工调试或兼容旧脚本时可使用 `--error-format=text`，恢复原有的多行文本与建议格式。
+其他子命令继续使用原有文本错误格式。
+
+> stdout 仅输出文档内容，stderr 仅输出错误信息，exit code 严格为 0/1/2/3。
+> 完整的错误和建议枚举见 [suggestion.txt](suggestion.txt)。
+
+## 支持的文件格式
+
+| 类型 | 格式 |
+|------|------|
+| 文档 | PDF, DOC, DOCX, TXT, RTF, OFD |
+| 图片 | PNG, JPG, JPEG, BMP, TIFF, WebP |
+| 表格 | XLS, XLSX, CSV |
+| 演示 | PPT, PPTX |
+| 网页 | HTML, MHTML |
+
+限制：
+
+| 限制项 | 免费 API | 付费 API |
+|--------|----------|----------|
+| 文件大小 | 由 quota 的 `max_file_size_mb` 下发，PDF 可自动分片 | 由 quota 的 `standard_max_file_size_mb` 下发，旧服务端回退 500MB |
+| PDF 页数 | 由 quota 的 `max_pages_per_request` 下发，支持自动分段 | 1000 页 |
+| XLS/XLSX/CSV | — | 每 sheet ≤ 2000 行 × 100 列 |
+| TXT | — | ≤ 100KB |
+| 图片尺寸 | 20～20000 像素 | 20～20000 像素 |
+
+### Extraction recovery
+
+`task status <task-id> --details` shows failed resources and private-result settlement status.
+For `pending_settlement`, retain the candidate identity and run:
+
+```bash
+xparse-cli task retry <task-id> --resource-id <resource-id> --pending-result-id <pending-result-id>
+```
+
+This settles the saved result without another model call. Replaying the same candidate is safe.
+The Task stays suspended; use `task result` or `task export` for delivered files. Explicit
+`task resume <task-id>` continues remaining Agent work and adds execution budget. Preserve its
+`command_id` and `checkpoint_version` for exact replay. Without a saved candidate, `task retry --resource-id RESOURCE_ID`
+re-extracts the one resource; do not blindly replay an ambiguous response.
+
+## Extraction workspace commands
+
+The workspace commands below require a matching CLI build and backend. They do
+not create a replacement Task. Request JSON is read from `--input FILE` or stdin
+with `--input -`; values and version tokens are transmitted without reinterpretation.
+
+```bash
+xparse-cli task retry TASK_ID
+xparse-cli task retry TASK_ID --scope selected --resource-id RESOURCE_ID --field-id FIELD_ID
+xparse-cli task retry TASK_ID --only-outdated
+xparse-cli task spec get TASK_ID
+xparse-cli task spec set TASK_ID --input fields.json
+xparse-cli task spec clarify TASK_ID --input clarification.json
+xparse-cli task field set TASK_ID RESOURCE_ID FIELD_ID --input correction.json
+xparse-cli task field confirm TASK_ID RESOURCE_ID FIELD_ID --input confirmation.json
+xparse-cli task history TASK_ID RESOURCE_ID
+xparse-cli task preview TASK_ID RESOURCE_ID
+xparse-cli task copilot show TASK_ID
+xparse-cli task copilot steps TASK_ID --after 0
+xparse-cli task copilot send TASK_ID --text 'Recheck the contract amount'
+xparse-cli task copilot send TASK_ID --input reply.json
+xparse-cli task memory list TASK_ID
+xparse-cli task memory revoke TASK_ID MEMORY_ID
+xparse-cli task list --search contract --limit 20
+xparse-cli task page TASK_ID
+xparse-cli task add TASK_ID new.pdf
+xparse-cli task add TASK_ID --history-id 123
+xparse-cli task add TASK_ID --uploaded-file-id FILE_ID
+xparse-cli task add TASK_ID --reconcile
+```
+
+`retry TASK_ID` re-extracts every file using the current definition. File and field
+selectors intersect; with a field definition, only active fields are used. A Task
+without a field definition reruns its original instruction and cannot use field
+selectors or `--only-outdated`. Old results remain until replaced by new results.
+Legacy `retry TASK_ID --resource-id RESOURCE_ID` still recovers one failed file or
+settles its saved result; use `--scope selected` to force re-extraction of that file.
+`resume` continues suspended work and remains separate from re-extraction.
+
+`fields.json` is the complete active field list, not a partial patch. Omitting an
+existing field deletes it; use `restore_field_ids` to restore deleted fields:
+
+```json
+{"expected_version":7,"task_rules":"Extract contract data","fields":[{"field_id":"amount","name":"Amount","description":"Total including tax"}],"restore_field_ids":[],"apply_to_existing":false}
+```
+
+For clarification, send `expected_version`, `name`, and `description`.
+For field correction/confirmation, preserve the reviewed result and spec versions:
+
+```json
+{"base_result_version":3,"expected_spec_version":7,"request_id":"review-unique-id","value":{"value":"100.00"},"review":{"apply_to_future":false}}
+```
 
-## Usage
+Copilot supports all page interaction kinds, including edited definitions,
+confirm-only, confirm-and-rerun, answers and dismissals. Preserve the original
+identities and reviewed draft values. Example (replace all identifiers/versions):
 
-```sh
-xparse-cli parse document.pdf --api free
-xparse-cli auth --help
-xparse-cli crop-enhance --help
-xparse-cli detect-manipulation --help
+```json
+{"client_message_id":"reply-unique-id","kind":"confirm_and_rerun","text":"","expected_version":7,"draft_id":"draft-id","draft_revision":2}
 ```
 
-Use `xparse-cli --help` for all commands. Paid operations require explicit approval.
+A conflict is not retried with a silently refreshed version. After an ambiguous
+mutation response, query the same Task before any repeat. Managed local additions
+return upload identities for recovery and use the page's managed import pipeline.
+`task page` requires the backend's `page-session?result_page_url=true` support and
+returns the exact server-issued URL; never build grants in the client.
 
-[TextIn](https://www.textin.com/) · [Agent Skills](https://github.com/intsig-textin/xparse-skills)
+Regional availability follows the page: task list, spec set/clarify, whole-task or scoped retry, preview and version history are domestic-only. Other operations retain their existing regional rules. These additions require a matching CLI/Connector build; check the installed CLI's command help before using them.

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "xparse-cli",
-  "version": "2.6.0",
+  "version": "2.6.1-beta.2",
   "description": "TextIn xParse command-line client for document parsing",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.intsig.net/xparse1/xparse-client.git"
+  },
   "homepage": "https://www.textin.com/",
   "bin": {
     "xparse-cli": "bin/xparse-cli.js"
@@ -15,15 +19,15 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "xparse-cli-darwin-amd64": "2.6.0",
-    "xparse-cli-darwin-arm64": "2.6.0",
-    "xparse-cli-linux-amd64": "2.6.0",
-    "xparse-cli-linux-arm64": "2.6.0",
-    "xparse-cli-windows-amd64": "2.6.0",
-    "xparse-cli-windows-arm64": "2.6.0"
+    "xparse-cli-darwin-amd64": "2.6.1-beta.2",
+    "xparse-cli-darwin-arm64": "2.6.1-beta.2",
+    "xparse-cli-linux-amd64": "2.6.1-beta.2",
+    "xparse-cli-linux-arm64": "2.6.1-beta.2",
+    "xparse-cli-windows-amd64": "2.6.1-beta.2",
+    "xparse-cli-windows-arm64": "2.6.1-beta.2"
   },
   "publishConfig": {
     "access": "public",
-    "tag": "latest"
+    "tag": "beta"
   }
 }