xparse-cli 2.6.0-beta.1 → 2.6.0

package/README.md

@@ -1,723 +1,25 @@
-# TextIn xParse CLI
+# xparse-cli
 
-TextIn xParse 文档解析命令行工具，基于 [TextIn xParse API](https://docs.textin.com/api-reference/endpoint/xparse/v1/parse-sync) 实现。
+TextIn xParse command-line client for document parsing, image correction and manipulation detection.
 
-支持将 PDF、图片、Office 文档等 20+ 格式转换为 Markdown 及结构化数据。
+## Install
 
-## 安装
-
-需要 Node.js 18 或更高版本：
-
-### 安装正式版
-
-```bash
+```sh
 npm install --global xparse-cli
-```
-
-国内网络可以显式使用 npmmirror：
-
-```bash
-npm install --global --registry=https://registry.npmmirror.com xparse-cli
-```
-
-安装后运行以下命令检查版本：
-
-```bash
 xparse-cli version
 ```
 
-### 安装 beta 或精确版本
-
-跟随当前 beta：
-
-```bash
-npm install --global xparse-cli@beta
-```
-
-为了获得可复现的测试环境，应安装精确版本：
-
-```bash
-npm install --global xparse-cli@2.6.0-beta.1
-```
-
-### 升级
-
-```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}}
-```
+Node.js 18 or later is required. Supports macOS, Linux and Windows on x64 and ARM64.
 
-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):
+## Usage
 
-```json
-{"client_message_id":"reply-unique-id","kind":"confirm_and_rerun","text":"","expected_version":7,"draft_id":"draft-id","draft_revision":2}
+```sh
+xparse-cli parse document.pdf --api free
+xparse-cli auth --help
+xparse-cli crop-enhance --help
+xparse-cli detect-manipulation --help
 ```
 
-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.
+Use `xparse-cli --help` for all commands. Paid operations require explicit approval.
 
-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.
+[TextIn](https://www.textin.com/) · [Agent Skills](https://github.com/intsig-textin/xparse-skills)

package/package.json

@@ -1,12 +1,8 @@
 {
   "name": "xparse-cli",
-  "version": "2.6.0-beta.1",
+  "version": "2.6.0",
   "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"
@@ -19,15 +15,15 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "xparse-cli-darwin-amd64": "2.6.0-beta.1",
-    "xparse-cli-darwin-arm64": "2.6.0-beta.1",
-    "xparse-cli-linux-amd64": "2.6.0-beta.1",
-    "xparse-cli-linux-arm64": "2.6.0-beta.1",
-    "xparse-cli-windows-amd64": "2.6.0-beta.1",
-    "xparse-cli-windows-arm64": "2.6.0-beta.1"
+    "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"
   },
   "publishConfig": {
     "access": "public",
-    "tag": "beta"
+    "tag": "latest"
   }
 }