xparse-cli 2.2.4 → 2.3.0-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +134 -61
  2. package/package.json +8 -8
package/README.md CHANGED
@@ -1,90 +1,55 @@
1
- # xParser CLI
1
+ # TextIn xParse CLI
2
2
 
3
- Textin xParser 文档解析命令行工具，基于 [TextIn xParse API](https://docs.textin.com/api-reference/endpoint/xparse/v1/parse-sync) 实现。
3
+ TextIn xParse 文档解析命令行工具，基于 [TextIn xParse API](https://docs.textin.com/api-reference/endpoint/xparse/v1/parse-sync) 实现。
4
4
 
5
5
  支持将 PDF、图片、Office 文档等 20+ 格式转换为 Markdown 及结构化数据。
6
6
 
7
7
  ## 安装
8
8
 
9
- ### npm
10
-
11
9
  需要 Node.js 18 或更高版本：
12
10
 
11
+ ### 安装正式版
12
+
13
13
  ```bash
14
- npm install -g xparse-cli
14
+ npm install --global xparse-cli
15
15
  ```
16
16
 
17
- 安装后可运行 `xparse-cli version` 检查版本。
18
-
19
- WorkBuddy 集成、国内/海外 Connector 区别、beta 命名规则及完整发版步骤见
20
- [WorkBuddy Connector 概念与发版流程](docs/workbuddy_connector_release.md)。
21
-
22
- ### 一键安装
23
-
24
- **Linux / macOS**
17
+ 国内网络可以显式使用 npmmirror：
25
18
 
26
19
  ```bash
27
- source <(curl -fsSL https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.sh)
20
+ npm install --global --registry=https://registry.npmmirror.com xparse-cli
28
21
  ```
29
22
 
30
- **Windows (PowerShell)**
23
+ 安装后运行以下命令检查版本：
31
24
 
32
- ```powershell
33
- irm https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.ps1 | iex
25
+ ```bash
26
+ xparse-cli version
34
27
  ```
35
28
 
36
- ### 从源码构建
37
-
38
- > 要求 Go 1.23+
29
+ ### 安装 beta 或精确版本
39
30
 
40
- **单平台构建（当前系统）：**
31
+ 跟随当前 beta：
41
32
 
42
33
  ```bash
43
- go build -o xparse-cli .
34
+ npm install --global xparse-cli@beta
44
35
  ```
45
36
 
46
- **带版本信息构建：**
37
+ 为了获得可复现的测试环境，应安装精确版本：
47
38
 
48
39
  ```bash
49
- VERSION=v0.0.1
50
- COMMIT=$(git rev-parse --short HEAD)
51
- DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
52
- PKG=github.com/intsig-textin/xparse-skills/cli/cmd/parse
53
-
54
- go build -ldflags "-s -w \
55
- -X ${PKG}.version=${VERSION} \
56
- -X ${PKG}.commit=${COMMIT} \
57
- -X ${PKG}.date=${DATE}" \
58
- -o xparse-cli .
40
+ npm install --global xparse-cli@2.3.0-beta.5
59
41
  ```
60
42
 
61
- **交叉编译全平台：**
43
+ ### 升级
62
44
 
63
45
  ```bash
64
- VERSION=v0.0.1
65
- COMMIT=$(git rev-parse --short HEAD)
66
- DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
67
- PKG=github.com/intsig-textin/xparse-skills/cli/cmd/parse
68
- LDFLAGS="-s -w -X ${PKG}.version=${VERSION} -X ${PKG}.commit=${COMMIT} -X ${PKG}.date=${DATE}"
69
-
70
- GOOS=linux GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-linux-amd64 .
71
- GOOS=linux GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-linux-arm64 .
72
- GOOS=darwin GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-darwin-amd64 .
73
- GOOS=darwin GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-darwin-arm64 .
74
- GOOS=windows GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-windows-amd64.exe .
75
- GOOS=windows GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-windows-arm64.exe .
46
+ npm install --global xparse-cli@latest
76
47
  ```
77
48
 
78
- 产物位于 `dist/` 目录，共 6 个二进制文件：
49
+ beta、精确版本以及国内镜像同样通过 `npm install --global` 管理。CLI 不再单独下载或替换二进制文件。
79
50
 
80
- | 平台 | 文件 |
81
- |------|------|
82
- | Linux x86_64 | `xparse-cli-linux-amd64` |
83
- | Linux ARM64 | `xparse-cli-linux-arm64` |
84
- | macOS Intel | `xparse-cli-darwin-amd64` |
85
- | macOS Apple Silicon | `xparse-cli-darwin-arm64` |
86
- | Windows x86_64 | `xparse-cli-windows-amd64.exe` |
87
- | Windows ARM64 | `xparse-cli-windows-arm64.exe` |
51
+ WorkBuddy 集成、国内/海外 Connector 区别、beta 命名规则及完整发版步骤见
52
+ [WorkBuddy Connector 概念与发版流程](docs/workbuddy_connector_release.md)。
88
53
 
89
54
  ## 快速开始
90
55
 
@@ -109,7 +74,7 @@ xparse-cli parse secret.pdf --password mypassword
109
74
 
110
75
  ### 2. 付费 API（可选）
111
76
 
112
- 前往 [Textin 控制台](https://www.textin.com/user/login?redirect=%252Fconsole%252Fdashboard%252Fsetting&from=xparse-parse-skill) 获取凭证（`x-ti-app-id` 和 `x-ti-secret-code`），然后运行：
77
+ 前往 [TextIn 控制台](https://www.textin.com/user/login?redirect=%252Fconsole%252Fdashboard%252Fsetting&from=xparse-parse-skill) 获取凭证（`x-ti-app-id` 和 `x-ti-secret-code`），然后运行：
113
78
 
114
79
  ```bash
115
80
  xparse-cli auth
@@ -129,6 +94,96 @@ export XPARSE_SECRET_CODE=your_secret_code
129
94
  xparse-cli parse report.pdf --api paid
130
95
  ```
131
96
 
97
+ ### 3. 多文件 Task Runtime（Agent 推荐）
98
+
99
+ Task Runtime 把上传、执行状态和结果交给服务端持久化。`task run` 默认在提交 Run
100
+ 成功后立即返回 `operation_id`、`task_id` 和 `run_id`；Agent 后续锁定该 Run 查看进度，完成后再按需读取或导出结果，不需要把全部结果放进上下文。WorkBuddy 下 stderr 输出 `xparse_event.v1` JSONL：服务端接受 Run 后立即输出 `run_accepted`，后续状态变化输出 `run_status`；stdout 始终只输出一份最终提交 JSON。
101
+
102
+ ```bash
103
+ xparse-cli task run --files 'contracts/*.pdf'
104
+ xparse-cli task status <task-id> --run-id <run-id>
105
+ xparse-cli task export <task-id> --run-id <run-id> --output ./task-output
106
+ xparse-cli task read <task-id> contract-a.pdf --run-id <run-id>
107
+ xparse-cli task debug <task-id> --run-id <run-id>
108
+ ```
109
+
110
+ 需要在同一个 Task 下创建新 Run 时，显式选择重跑范围：
111
+
112
+ ```bash
113
+ # 重跑 Task 已绑定的全部 Resource
114
+ xparse-cli task rerun <task-id> --mode all
115
+
116
+ # 上传新文件、绑定到现有 Task，并仅处理新 Resource
117
+ xparse-cli task rerun <task-id> --mode new-files --files 'new-docs/*.pdf'
118
+
119
+ # 只重跑指定的已有 Resource；--resource-id 可重复
120
+ xparse-cli task rerun <task-id> --mode selected-files \
121
+ --resource-id <resource-id> --resource-id <resource-id>
122
+ ```
123
+
124
+ `new-files` 不创建替代 Task；返回结果沿用原 `task_id` 并生成新的 `run_id`。
125
+ 若新文件受密码保护，使用可重复的 `--password`，多文件时按
126
+ `selector=password` 绑定。
127
+
128
+ 若提交响应丢失，使用进度事件或错误详情中的同一 `operation_id` 重试：
129
+
130
+ ```bash
131
+ xparse-cli task run --files 'contracts/*.pdf' --operation-id <operation-id>
132
+ ```
133
+
134
+ 同一操作 ID 会生成 Task 与 Run 两层幂等键；改了文件、模式或配置后必须使用新的操作 ID。
135
+
136
+ 需要在一个终端命令中等待完成并导出时，显式使用 `--wait`：
137
+
138
+ ```bash
139
+ xparse-cli task run --files 'contracts/*.pdf' --wait --output ./task-output
140
+ ```
141
+
142
+ `--wait` 只是在客户端持续轮询同一个 `run_id`，不会把服务端 Task 变成同步任务。达到
143
+ `--timeout` 时 CLI 正常退出并返回当前状态、原 `task_id` / `run_id`、
144
+ `wait_timed_out: true` 和 `next_action: "POLL_STATUS"`；它不会取消或重建 Run。之后使用
145
+ `task status` 继续查询同一个 Run。Agent 流程默认不使用 `--wait`，也不要自动附加较短的固定超时。
146
+
147
+ 单个文件的密码与 `parse` 一样直接使用 `--password`，CLI 会在第一次上传时携带密码：
148
+
149
+ ```bash
150
+ xparse-cli task run secret.pdf --password open-password
151
+ ```
152
+
153
+ 多个输入中只有部分文件有密码时，只为受保护文件重复传入 `selector=password` 绑定。selector
154
+ 可使用精确路径、唯一文件名，或 `PASSWORD_INPUT_REQUIRED` 返回的稳定 selector：
155
+
156
+ ```bash
157
+ xparse-cli task run a.pdf b.jpg c.pdf \
158
+ --password a.pdf=open-a \
159
+ --password c.pdf=open-c
160
+ ```
161
+
162
+ 如果上传阶段返回 `PASSWORD_INPUT_REQUIRED`，CLI 会扫描完本批次并一次性返回所有缺失或错误
163
+ 密码文件。使用返回的 selector 和同一 `operation_id` 补充 `--password selector=password`，然后
164
+ 重放原始命令：首次提交重放 `task run`，`task rerun --mode new-files` 增加文件时则重放原 rerun。
165
+ 显式复用同一 `operation_id` 时，CLI 会复用已 ready 的上传资产。此时即使错误中已有 `task_id`，
166
+ 尚未成功上传的新文件也不是 Task Resource，不能使用 `task continue`。
167
+
168
+ 只有 Task Run 已经接受、`task debug` 确认现有 Resource 在执行阶段返回密码错误时，才更新该
169
+ Resource 的访问密码并创建 selected-files Run：
170
+
171
+ ```bash
172
+ xparse-cli task continue <task-id> \
173
+ --password <resource-id>=open-password
174
+ ```
175
+
176
+ `continue` 同样默认提交即返回；保存新的 `run_id`，完成后再单独执行 `task export`。只有显式添加 `--wait` 时才能同时使用 `--output`。
177
+
178
+ 等待人工付费授权或充值后，必须恢复精确 Run：
179
+
180
+ ```bash
181
+ xparse-cli task resume <task-id> --run-id <run-id> --approve-paid
182
+ xparse-cli task resume <task-id> --run-id <run-id> --after-funding
183
+ ```
184
+
185
+ 文件资源只保存加密的文件访问密码；`force_engine`、页范围和 capabilities 属于具体 Run。Runtime 的 MinerU 恢复只覆盖当前失败 RunItem，不会写回可复用资源。`--api auto/free` 不会自动授权付费；需要付费时会停在可见状态并要求人工批准。
186
+
132
187
  也可以使用 OAuth。正式二进制默认使用无 Secret 的 public client
133
188
  `cli_textin_xparse`；私有部署可以通过 flag、环境变量或配置文件覆盖：
134
189
 
@@ -184,6 +239,14 @@ xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
184
239
  | 命令 | 说明 |
185
240
  |------|------|
186
241
  | `xparse-cli parse` | 解析文档，输出 Markdown / JSON |
242
+ | `xparse-cli task run` | 上传并执行多文件持久化 Task |
243
+ | `xparse-cli task rerun` | 在现有 Task 下按 all/new-files/selected-files 创建新 Run |
244
+ | `xparse-cli task status` | 查询 Task 和最新 Run 状态 |
245
+ | `xparse-cli task export` | 批量导出成功结果和 manifest |
246
+ | `xparse-cli task read` | 读取单个文件结果 |
247
+ | `xparse-cli task debug` | 查看逐文件错误与恢复证据 |
248
+ | `xparse-cli task continue` | 补充逐文件密码并选择性续跑 |
249
+ | `xparse-cli task resume` | 在付费授权或充值确认后恢复精确 Run |
187
250
  | `xparse-cli auth` | TTY 中进入认证选单；非 TTY 保持旧版 AppKey 输入流程 |
188
251
  | `xparse-cli auth app-key` | 配置 AppKey 凭证 |
189
252
  | `xparse-cli auth device` | OAuth Device Flow 登录 |
@@ -193,7 +256,14 @@ xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
193
256
  | `xparse-cli config` | 管理配置（show / set / reset / path） |
194
257
  | `xparse-cli quota` | 查看免费 API 额度 |
195
258
  | `xparse-cli download` | 下载解析结果中 elements 的图片 |
196
- | `xparse-cli update` | 自更新 CLI 到最新版本 |
259
+ | `xparse-cli cache` | 查看或清理本地文档缓存 |
260
+ | `xparse-cli get_doc_info` | 读取本地 PDF 基础信息 |
261
+ | `xparse-cli get_outline` | 读取缓存文档的目录结构 |
262
+ | `xparse-cli read_content` | 按元素 ID 读取缓存内容 |
263
+ | `xparse-cli read_pages` | 按页码范围读取缓存内容 |
264
+ | `xparse-cli search_text` | 搜索缓存文档文本 |
265
+ | `xparse-cli get_confidence` | 查询元素或页面的 OCR 置信度 |
266
+ | `xparse-cli completion` | 生成 shell 自动补全脚本 |
197
267
  | `xparse-cli version` | 显示版本信息 |
198
268
 
199
269
  全局参数 `--profile workbuddy` 或 `--profile easyclaw` 可放在子命令前后，用于选择隔离凭证。
@@ -217,14 +287,17 @@ xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
217
287
  | `--table-view` | `html` | 表格视图：`html`、`markdown` |
218
288
  | `--list` | | 从文件读取输入列表（需配合 `--output`） |
219
289
  | `--output` | _(stdout)_ | 输出文件路径或目录（目录不存在时自动创建） |
290
+ | `--error-format` | `json` | 错误输出格式：`json`、`text` |
220
291
 
221
292
  **全局参数（所有命令均支持）：**
222
293
 
223
294
  | 参数 | 说明 |
224
295
  |------|------|
225
- | `--app-id` | Textin App ID（覆盖环境变量和配置文件） |
226
- | `--secret-code` | Textin Secret Code（覆盖环境变量和配置文件） |
296
+ | `--app-id` | TextIn App ID（覆盖环境变量和配置文件） |
297
+ | `--secret-code` | TextIn Secret Code（覆盖环境变量和配置文件） |
227
298
  | `--base-url` | API 地址（私有化部署时使用） |
299
+ | `--profile` | 凭证 Profile：`workbuddy`、`easyclaw` |
300
+ | `--task-context` | Agent 任务上下文 JSON 文件路径 |
228
301
  | `--verbose` | 调试模式，打印 HTTP 请求详情 |
229
302
 
230
303
  ### API capabilities 默认值
@@ -280,10 +353,10 @@ xparse-cli config reset
280
353
  xparse-cli config path
281
354
  ```
282
355
 
283
- ### 自更新
356
+ ### 升级 CLI
284
357
 
285
358
  ```bash
286
- xparse-cli update
359
+ npm install --global xparse-cli@latest
287
360
  ```
288
361
 
289
362
  ### 调试模式
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xparse-cli",
3
- "version": "2.2.4",
3
+ "version": "2.3.0-beta.10",
4
4
  "description": "TextIn xParse command-line client for document parsing",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -19,15 +19,15 @@
19
19
  "node": ">=18"
20
20
  },
21
21
  "optionalDependencies": {
22
- "xparse-cli-darwin-amd64": "2.2.4",
23
- "xparse-cli-darwin-arm64": "2.2.4",
24
- "xparse-cli-linux-amd64": "2.2.4",
25
- "xparse-cli-linux-arm64": "2.2.4",
26
- "xparse-cli-windows-amd64": "2.2.4",
27
- "xparse-cli-windows-arm64": "2.2.4"
22
+ "xparse-cli-darwin-amd64": "2.3.0-beta.10",
23
+ "xparse-cli-darwin-arm64": "2.3.0-beta.10",
24
+ "xparse-cli-linux-amd64": "2.3.0-beta.10",
25
+ "xparse-cli-linux-arm64": "2.3.0-beta.10",
26
+ "xparse-cli-windows-amd64": "2.3.0-beta.10",
27
+ "xparse-cli-windows-arm64": "2.3.0-beta.10"
28
28
  },
29
29
  "publishConfig": {
30
30
  "access": "public",
31
- "tag": "latest"
31
+ "tag": "beta"
32
32
  }
33
33
  }