xparse-cli 2.4.4-beta.1 → 2.4.4-beta.3

package/README.md

@@ -166,6 +166,29 @@ xparse-cli parse report.pdf --api paid
 
 ### 3. 多文件 Task Runtime（Agent 推荐）
 
+解析与抽取统一使用 `task run`：省略 `--task-type` 时仍为解析，原有参数兼容。
+
+```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，解析专用参数不能用于抽取。
+追加根据服务端类型分发；解析会追加输入并请求新一轮处理，抽取沿用既有任务要求。
+解析追加若绑定后启动失败，应保留 `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。
 
@@ -260,35 +283,6 @@ xparse-cli task resume <task-id> --run-id <run-id> --after-funding
 
 文件资源只保存加密的文件访问密码；`force_engine`、页范围和 capabilities 属于具体 Run。Runtime 的 MinerU 恢复只覆盖当前失败 RunItem，不会写回可复用资源。`--api auto/free` 不会自动授权付费；需要付费时会停在可见状态并要求人工批准。
 
-### 4. 从已完成解析创建语义抽取 Task
-
-已有异步 Parse Job 或 Parse Task Run 时，可以直接复用服务端解析结果创建抽取任务，不需要下载 JSON、重新上传文件或再次解析：
-
-```bash
-xparse-cli extract create \
-  --instruction '提取店名与实付金额' \
-  --parse-job <job-id>
-
-xparse-cli extract create \
-  --instruction '提取付款户名、付款账号、付款金额' \
-  --parse-task-run <task-id>:<run-id>
-```
-
-`--parse-job` 和 `--parse-task-run` 都可以重复。命令在服务端接受任务后立即返回
-`task_id`、`run_id` 和 `result_page_url`；结果页持续展示逐份进度、字段、证据与人工修改结果。
-同一次创建响应不明确时，用原 `--operation-id` 原样重试，避免创建重复任务。
-
-后续有新的已解析文件时，追加到原 Task/Run。服务端沿用首次抽取形成的共享语义上下文，
-只处理新增文档，并返回新的结果页链接：
-
-```bash
-xparse-cli extract add <extraction-task-id> \
-  --run-id <extraction-run-id> \
-  --parse-job <new-job-id>
-```
-
-MCP 对应使用 `create_extraction_task` 和 `add_extraction_task_sources`；两个工具都会返回可直接打开的 HTML `resource_link`。
-
 也可以使用 OAuth。正式二进制默认使用无 Secret 的 public client
 `cli_textin_xparse`；私有部署可以通过 flag、环境变量或配置文件覆盖：
 
@@ -352,7 +346,6 @@ xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
 | `xparse-cli task debug` | 查看逐文件错误与恢复证据 |
 | `xparse-cli task continue` | 补充逐文件密码并选择性续跑 |
 | `xparse-cli task resume` | 在付费授权或充值确认后恢复精确 Run |
-| `xparse-cli extract create` | 从已完成 Parse Job 或 Parse Task Run 创建语义抽取 Task |
 | `xparse-cli auth` | TTY 中进入认证选单；非 TTY 保持旧版 AppKey 输入流程 |
 | `xparse-cli auth app-key` | 配置 AppKey 凭证 |
 | `xparse-cli auth device` | OAuth Device Flow 登录 |
@@ -584,3 +577,18 @@ OAuth 参数优先级：
 | 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`
+re-extracts the one resource; do not blindly replay an ambiguous response.

package/package.json

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