xparse-cli 2.2.3 → 2.3.0-beta.2

package/README.md

@@ -126,6 +126,58 @@ export XPARSE_SECRET_CODE=your_secret_code
 xparse-cli parse report.pdf --api paid
 ```
 
+### 3. 多文件 Task Runtime（Agent 推荐）
+
+Task Runtime 把上传、执行状态和结果交给服务端持久化。`task run` 默认在提交 Run
+成功后立即返回 `operation_id`、`task_id` 和 `run_id`；Agent 后续锁定该 Run 查看进度，完成后再按需读取或导出结果，不需要把全部结果放进上下文。WorkBuddy 下 stderr 输出 `xparse_event.v1` JSONL 文件数进度，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> --out-dir ./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>
+```
+
+若提交响应丢失，使用进度事件或错误详情中的同一 `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 --out-dir ./task-output
+```
+
+某些文件需要密码时，从 stdin 提供按路径或文件名映射的 JSON，避免密码进入进程参数和 shell 历史：
+
+```bash
+printf '%s' '{"secret.pdf":"open-password"}' | \
+  xparse-cli task run secret.pdf --passwords-stdin
+```
+
+若服务端返回 `40423`，补充失败文件的密码并只重跑对应 Resource：
+
+```bash
+printf '%s' '{"<resource-id>":"open-password"}' | \
+  xparse-cli task continue <task-id> --passwords-stdin
+```
+
+`continue` 同样默认提交即返回；保存新的 `run_id`，完成后再单独执行 `task export`。只有显式添加 `--wait` 时才能同时使用 `--out-dir`。
+
+等待人工付费授权或充值后，必须恢复精确 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、环境变量或配置文件覆盖：
 
@@ -181,6 +233,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 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 登录 |

package/package.json

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