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

package/README.md

@@ -128,28 +128,52 @@ 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 文件数进度，stdout 只输出一份最终提交 JSON。
 
 ```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'
+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 --out-dir ./task-output
+  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 --out-dir ./task-output
+  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` 不会自动授权付费；需要付费时会停在可见状态并要求人工批准。
@@ -215,6 +239,7 @@ xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
 | `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.3.0-beta.1",
+  "version": "2.3.0-beta.2",
   "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.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",