xparse-cli 2.3.0-beta.1 → 2.3.0-beta.10

package/README.md

@@ -1,87 +1,55 @@
-# xParser CLI
+# TextIn xParse CLI
 
-Textin xParser 文档解析命令行工具，基于 [TextIn xParse API](https://docs.textin.com/api-reference/endpoint/xparse/v1/parse-sync) 实现。
+TextIn xParse 文档解析命令行工具，基于 [TextIn xParse API](https://docs.textin.com/api-reference/endpoint/xparse/v1/parse-sync) 实现。
 
 支持将 PDF、图片、Office 文档等 20+ 格式转换为 Markdown 及结构化数据。
 
 ## 安装
 
-### npm
-
 需要 Node.js 18 或更高版本：
 
+### 安装正式版
+
 ```bash
-npm install -g xparse-cli
+npm install --global xparse-cli
 ```
 
-安装后可运行 `xparse-cli version` 检查版本。
-
-### 一键安装
-
-**Linux / macOS**
+国内网络可以显式使用 npmmirror：
 
 ```bash
-source <(curl -fsSL https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.sh)
+npm install --global --registry=https://registry.npmmirror.com xparse-cli
 ```
 
-**Windows (PowerShell)**
+安装后运行以下命令检查版本：
 
-```powershell
-irm https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.ps1 | iex
+```bash
+xparse-cli version
 ```
 
-### 从源码构建
+### 安装 beta 或精确版本
 
-> 要求 Go 1.23+
-
-**单平台构建（当前系统）：**
+跟随当前 beta：
 
 ```bash
-go build -o xparse-cli .
+npm install --global xparse-cli@beta
 ```
 
-**带版本信息构建：**
+为了获得可复现的测试环境，应安装精确版本：
 
 ```bash
-VERSION=v0.0.1
-COMMIT=$(git rev-parse --short HEAD)
-DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-PKG=github.com/intsig-textin/xparse-skills/cli/cmd/parse
-
-go build -ldflags "-s -w \
-  -X ${PKG}.version=${VERSION} \
-  -X ${PKG}.commit=${COMMIT} \
-  -X ${PKG}.date=${DATE}" \
-  -o xparse-cli .
+npm install --global xparse-cli@2.3.0-beta.5
 ```
 
-**交叉编译全平台：**
+### 升级
 
 ```bash
-VERSION=v0.0.1
-COMMIT=$(git rev-parse --short HEAD)
-DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-PKG=github.com/intsig-textin/xparse-skills/cli/cmd/parse
-LDFLAGS="-s -w -X ${PKG}.version=${VERSION} -X ${PKG}.commit=${COMMIT} -X ${PKG}.date=${DATE}"
-
-GOOS=linux   GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-linux-amd64 .
-GOOS=linux   GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-linux-arm64 .
-GOOS=darwin  GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-darwin-amd64 .
-GOOS=darwin  GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-darwin-arm64 .
-GOOS=windows GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-windows-amd64.exe .
-GOOS=windows GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-windows-arm64.exe .
+npm install --global xparse-cli@latest
 ```
 
-产物位于 `dist/` 目录，共 6 个二进制文件：
+beta、精确版本以及国内镜像同样通过 `npm install --global` 管理。CLI 不再单独下载或替换二进制文件。
 
-| 平台 | 文件 |
-|------|------|
-| Linux x86_64 | `xparse-cli-linux-amd64` |
-| Linux ARM64 | `xparse-cli-linux-arm64` |
-| macOS Intel | `xparse-cli-darwin-amd64` |
-| macOS Apple Silicon | `xparse-cli-darwin-arm64` |
-| Windows x86_64 | `xparse-cli-windows-amd64.exe` |
-| Windows ARM64 | `xparse-cli-windows-arm64.exe` |
+WorkBuddy 集成、国内/海外 Connector 区别、beta 命名规则及完整发版步骤见
+[WorkBuddy Connector 概念与发版流程](docs/workbuddy_connector_release.md)。
 
 ## 快速开始
 
@@ -106,7 +74,7 @@ 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`），然后运行：
+前往 [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
@@ -128,28 +96,90 @@ xparse-cli parse report.pdf --api paid
 
 ### 3. 多文件 Task Runtime（Agent 推荐）
 
-Task Runtime 把上传、执行状态和结果交给服务端持久化。默认流程会等待完成并导出 Markdown；Agent 再用 Grep/Read 选择少量相关文档，不需要把全部结果放进上下文。
+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 read <task-id> contract-a.pdf --run-id <run-id>
+xparse-cli task debug <task-id> --run-id <run-id>
+```
+
+需要在同一个 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' --out-dir ./task-output
-xparse-cli task status <task-id>
-xparse-cli task export <task-id> --out-dir ./task-output
-xparse-cli task read <task-id> contract-a.pdf
-xparse-cli task debug <task-id>
+xparse-cli task run --files 'contracts/*.pdf' --operation-id <operation-id>
 ```
 
-某些文件需要密码时，从 stdin 提供按路径或文件名映射的 JSON，避免密码进入进程参数和 shell 历史：
+同一操作 ID 会生成 Task 与 Run 两层幂等键；改了文件、模式或配置后必须使用新的操作 ID。
+
+需要在一个终端命令中等待完成并导出时，显式使用 `--wait`：
 
 ```bash
-printf '%s' '{"secret.pdf":"open-password"}' | \
-  xparse-cli task run secret.pdf --passwords-stdin --out-dir ./task-output
+xparse-cli task run --files 'contracts/*.pdf' --wait --output ./task-output
 ```
 
-若服务端返回 `40423`，补充失败文件的密码并只重跑对应 Resource：
+`--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
-printf '%s' '{"<resource-id>":"open-password"}' | \
-  xparse-cli task continue <task-id> --passwords-stdin --out-dir ./task-output
+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` 不会自动授权付费；需要付费时会停在可见状态并要求人工批准。
@@ -210,11 +240,13 @@ xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
 |------|------|
 | `xparse-cli parse` | 解析文档，输出 Markdown / JSON |
 | `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` | 批量导出成功结果和 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 登录 |
@@ -224,7 +256,14 @@ xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
 | `xparse-cli config` | 管理配置（show / set / reset / path） |
 | `xparse-cli quota` | 查看免费 API 额度 |
 | `xparse-cli download` | 下载解析结果中 elements 的图片 |
-| `xparse-cli update` | 自更新 CLI 到最新版本 |
+| `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` 可放在子命令前后，用于选择隔离凭证。
@@ -247,15 +286,18 @@ xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
 | `--include-char-details` | `false` | 返回字符级坐标和置信度 |
 | `--table-view` | `html` | 表格视图：`html`、`markdown` |
 | `--list` | | 从文件读取输入列表（需配合 `--output`） |
-| `--output` | _(stdout)_ | 输出文件路径或目录（目录须已存在） |
+| `--output` | _(stdout)_ | 输出文件路径或目录（目录不存在时自动创建） |
+| `--error-format` | `json` | 错误输出格式：`json`、`text` |
 
 **全局参数（所有命令均支持）：**
 
 | 参数 | 说明 |
 |------|------|
-| `--app-id` | Textin App ID（覆盖环境变量和配置文件） |
-| `--secret-code` | Textin Secret Code（覆盖环境变量和配置文件） |
+| `--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 默认值
@@ -311,10 +353,10 @@ xparse-cli config reset
 xparse-cli config path
 ```
 
-### 自更新
+### 升级 CLI
 
 ```bash
-xparse-cli update
+npm install --global xparse-cli@latest
 ```
 
 ### 调试模式
@@ -389,7 +431,10 @@ OAuth 参数优先级：
 
 稳定错误码至少包括：`FILE_NOT_FOUND`、`EMPTY_FILE`、`UNSUPPORTED_FILE_TYPE`、
 `FILE_TOO_LARGE`、`PAGE_LIMIT_EXCEEDED`、`PAID_QUOTA_REQUIRED`、
-`CAPABILITY_QUERY_FAILED`、`SPLIT_FAILED`、`MERGE_FAILED` 和 `RETRY_EXHAUSTED`。
+`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`，恢复原有的多行文本与建议格式。
 其他子命令继续使用原有文本错误格式。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xparse-cli",
-  "version": "2.3.0-beta.1",
+  "version": "2.3.0-beta.10",
   "description": "TextIn xParse command-line client for document parsing",
   "license": "MIT",
   "repository": {
@@ -19,12 +19,12 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "xparse-cli-darwin-amd64": "2.3.0-beta.1",
-    "xparse-cli-darwin-arm64": "2.3.0-beta.1",
-    "xparse-cli-linux-amd64": "2.3.0-beta.1",
-    "xparse-cli-linux-arm64": "2.3.0-beta.1",
-    "xparse-cli-windows-amd64": "2.3.0-beta.1",
-    "xparse-cli-windows-arm64": "2.3.0-beta.1"
+    "xparse-cli-darwin-amd64": "2.3.0-beta.10",
+    "xparse-cli-darwin-arm64": "2.3.0-beta.10",
+    "xparse-cli-linux-amd64": "2.3.0-beta.10",
+    "xparse-cli-linux-arm64": "2.3.0-beta.10",
+    "xparse-cli-windows-amd64": "2.3.0-beta.10",
+    "xparse-cli-windows-arm64": "2.3.0-beta.10"
   },
   "publishConfig": {
     "access": "public",