xparse-cli 2.3.0-beta.5 → 2.3.0-beta.8

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 +87 -70
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -1,87 +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
- ### 一键安装
20
-
21
- **Linux / macOS**
17
+ 国内网络可以显式使用 npmmirror：
22
18
 
23
19
  ```bash
24
- 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
25
21
  ```
26
22
 
27
- **Windows (PowerShell)**
23
+ 安装后运行以下命令检查版本：
28
24
 
29
- ```powershell
30
- irm https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.ps1 | iex
25
+ ```bash
26
+ xparse-cli version
31
27
  ```
32
28
 
33
- ### 从源码构建
29
+ ### 安装 beta 或精确版本
34
30
 
35
- > 要求 Go 1.23+
36
-
37
- **单平台构建（当前系统）：**
31
+ 跟随当前 beta：
38
32
 
39
33
  ```bash
40
- go build -o xparse-cli .
34
+ npm install --global xparse-cli@beta
41
35
  ```
42
36
 
43
- **带版本信息构建：**
37
+ 为了获得可复现的测试环境，应安装精确版本：
44
38
 
45
39
  ```bash
46
- VERSION=v0.0.1
47
- COMMIT=$(git rev-parse --short HEAD)
48
- DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
49
- PKG=github.com/intsig-textin/xparse-skills/cli/cmd/parse
50
-
51
- go build -ldflags "-s -w \
52
- -X ${PKG}.version=${VERSION} \
53
- -X ${PKG}.commit=${COMMIT} \
54
- -X ${PKG}.date=${DATE}" \
55
- -o xparse-cli .
40
+ npm install --global xparse-cli@2.3.0-beta.5
56
41
  ```
57
42
 
58
- **交叉编译全平台：**
43
+ ### 升级
59
44
 
60
45
  ```bash
61
- VERSION=v0.0.1
62
- COMMIT=$(git rev-parse --short HEAD)
63
- DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
64
- PKG=github.com/intsig-textin/xparse-skills/cli/cmd/parse
65
- LDFLAGS="-s -w -X ${PKG}.version=${VERSION} -X ${PKG}.commit=${COMMIT} -X ${PKG}.date=${DATE}"
66
-
67
- GOOS=linux GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-linux-amd64 .
68
- GOOS=linux GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-linux-arm64 .
69
- GOOS=darwin GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-darwin-amd64 .
70
- GOOS=darwin GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-darwin-arm64 .
71
- GOOS=windows GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-windows-amd64.exe .
72
- GOOS=windows GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-windows-arm64.exe .
46
+ npm install --global xparse-cli@latest
73
47
  ```
74
48
 
75
- 产物位于 `dist/` 目录，共 6 个二进制文件：
49
+ beta、精确版本以及国内镜像同样通过 `npm install --global` 管理。CLI 不再单独下载或替换二进制文件。
76
50
 
77
- | 平台 | 文件 |
78
- |------|------|
79
- | Linux x86_64 | `xparse-cli-linux-amd64` |
80
- | Linux ARM64 | `xparse-cli-linux-arm64` |
81
- | macOS Intel | `xparse-cli-darwin-amd64` |
82
- | macOS Apple Silicon | `xparse-cli-darwin-arm64` |
83
- | Windows x86_64 | `xparse-cli-windows-amd64.exe` |
84
- | Windows ARM64 | `xparse-cli-windows-arm64.exe` |
51
+ WorkBuddy 集成、国内/海外 Connector 区别、beta 命名规则及完整发版步骤见
52
+ [WorkBuddy Connector 概念与发版流程](docs/workbuddy_connector_release.md)。
85
53
 
86
54
  ## 快速开始
87
55
 
@@ -106,7 +74,7 @@ xparse-cli parse secret.pdf --password mypassword
106
74
 
107
75
  ### 2. 付费 API（可选）
108
76
 
109
- 前往 [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`），然后运行：
110
78
 
111
79
  ```bash
112
80
  xparse-cli auth
@@ -129,16 +97,34 @@ xparse-cli parse report.pdf --api paid
129
97
  ### 3. 多文件 Task Runtime（Agent 推荐）
130
98
 
131
99
  Task Runtime 把上传、执行状态和结果交给服务端持久化。`task run` 默认在提交 Run
132
- 成功后立即返回 `operation_id`、`task_id` 和 `run_id`；Agent 后续锁定该 Run 查看进度，完成后再按需读取或导出结果，不需要把全部结果放进上下文。WorkBuddy 下 stderr 输出 `xparse_event.v1` JSONL 文件数进度，stdout 只输出一份最终提交 JSON。
100
+ 成功后立即返回 `operation_id`、`task_id` 和 `run_id`；Agent 后续锁定该 Run 查看进度，完成后再按需读取或导出结果，不需要把全部结果放进上下文。WorkBuddy 下 stderr 输出 `xparse_event.v1` JSONL：服务端接受 Run 后立即输出 `run_accepted`，后续状态变化输出 `run_status`；stdout 始终只输出一份最终提交 JSON。
133
101
 
134
102
  ```bash
135
103
  xparse-cli task run --files 'contracts/*.pdf'
136
104
  xparse-cli task status <task-id> --run-id <run-id>
137
- xparse-cli task export <task-id> --run-id <run-id> --out-dir ./task-output
105
+ xparse-cli task export <task-id> --run-id <run-id> --output ./task-output
138
106
  xparse-cli task read <task-id> contract-a.pdf --run-id <run-id>
139
107
  xparse-cli task debug <task-id> --run-id <run-id>
140
108
  ```
141
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
+
142
128
  若提交响应丢失，使用进度事件或错误详情中的同一 `operation_id` 重试：
143
129
 
144
130
  ```bash
@@ -150,24 +136,41 @@ xparse-cli task run --files 'contracts/*.pdf' --operation-id <operation-id>
150
136
  需要在一个终端命令中等待完成并导出时，显式使用 `--wait`：
151
137
 
152
138
  ```bash
153
- xparse-cli task run --files 'contracts/*.pdf' --wait --out-dir ./task-output
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
154
151
  ```
155
152
 
156
- 某些文件需要密码时，从 stdin 提供按路径或文件名映射的 JSON，避免密码进入进程参数和 shell 历史：
153
+ 多个输入中只有部分文件有密码时，只为受保护文件重复传入 `selector=password` 绑定。selector
154
+ 可使用精确路径、唯一文件名，或 `PASSWORD_INPUT_REQUIRED` 返回的稳定 selector：
157
155
 
158
156
  ```bash
159
- printf '%s' '{"secret.pdf":"open-password"}' | \
160
- xparse-cli task run secret.pdf --passwords-stdin
157
+ xparse-cli task run a.pdf b.jpg c.pdf \
158
+ --password a.pdf=open-a \
159
+ --password c.pdf=open-c
161
160
  ```
162
161
 
163
- 若服务端返回 `40423`，补充失败文件的密码并只重跑对应 Resource：
162
+ 若服务端仍返回 `40423`，CLI 会扫描完本批次并一次性返回所有缺失或错误密码文件；使用返回的
163
+ selector 和同一 `operation_id` 补充 `--password selector=password` 后重试。已经知道的密码不依赖
164
+ `40423` 发现。显式复用同一 `operation_id` 时，CLI 会先解析已 ready 的上传资产，仅重新传输尚未
165
+ 成功的文件；旧服务端不支持解析接口时自动回退到原上传流程。对于已经创建的 Task，可只更新失败
166
+ Resource 并新建一个 selected-files Run：
164
167
 
165
168
  ```bash
166
- printf '%s' '{"<resource-id>":"open-password"}' | \
167
- xparse-cli task continue <task-id> --passwords-stdin
169
+ xparse-cli task continue <task-id> \
170
+ --password <resource-id>=open-password
168
171
  ```
169
172
 
170
- `continue` 同样默认提交即返回；保存新的 `run_id`，完成后再单独执行 `task export`。只有显式添加 `--wait` 时才能同时使用 `--out-dir`。
173
+ `continue` 同样默认提交即返回；保存新的 `run_id`，完成后再单独执行 `task export`。只有显式添加 `--wait` 时才能同时使用 `--output`。
171
174
 
172
175
  等待人工付费授权或充值后，必须恢复精确 Run：
173
176
 
@@ -234,6 +237,7 @@ xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
234
237
  |------|------|
235
238
  | `xparse-cli parse` | 解析文档，输出 Markdown / JSON |
236
239
  | `xparse-cli task run` | 上传并执行多文件持久化 Task |
240
+ | `xparse-cli task rerun` | 在现有 Task 下按 all/new-files/selected-files 创建新 Run |
237
241
  | `xparse-cli task status` | 查询 Task 和最新 Run 状态 |
238
242
  | `xparse-cli task export` | 批量导出成功结果和 manifest |
239
243
  | `xparse-cli task read` | 读取单个文件结果 |
@@ -249,7 +253,14 @@ xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
249
253
  | `xparse-cli config` | 管理配置（show / set / reset / path） |
250
254
  | `xparse-cli quota` | 查看免费 API 额度 |
251
255
  | `xparse-cli download` | 下载解析结果中 elements 的图片 |
252
- | `xparse-cli update` | 自更新 CLI 到最新版本 |
256
+ | `xparse-cli cache` | 查看或清理本地文档缓存 |
257
+ | `xparse-cli get_doc_info` | 读取本地 PDF 基础信息 |
258
+ | `xparse-cli get_outline` | 读取缓存文档的目录结构 |
259
+ | `xparse-cli read_content` | 按元素 ID 读取缓存内容 |
260
+ | `xparse-cli read_pages` | 按页码范围读取缓存内容 |
261
+ | `xparse-cli search_text` | 搜索缓存文档文本 |
262
+ | `xparse-cli get_confidence` | 查询元素或页面的 OCR 置信度 |
263
+ | `xparse-cli completion` | 生成 shell 自动补全脚本 |
253
264
  | `xparse-cli version` | 显示版本信息 |
254
265
 
255
266
  全局参数 `--profile workbuddy` 或 `--profile easyclaw` 可放在子命令前后，用于选择隔离凭证。
@@ -272,15 +283,18 @@ xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
272
283
  | `--include-char-details` | `false` | 返回字符级坐标和置信度 |
273
284
  | `--table-view` | `html` | 表格视图：`html`、`markdown` |
274
285
  | `--list` | | 从文件读取输入列表（需配合 `--output`） |
275
- | `--output` | _(stdout)_ | 输出文件路径或目录（目录须已存在） |
286
+ | `--output` | _(stdout)_ | 输出文件路径或目录（目录不存在时自动创建） |
287
+ | `--error-format` | `json` | 错误输出格式：`json`、`text` |
276
288
 
277
289
  **全局参数（所有命令均支持）：**
278
290
 
279
291
  | 参数 | 说明 |
280
292
  |------|------|
281
- | `--app-id` | Textin App ID（覆盖环境变量和配置文件） |
282
- | `--secret-code` | Textin Secret Code（覆盖环境变量和配置文件） |
293
+ | `--app-id` | TextIn App ID（覆盖环境变量和配置文件） |
294
+ | `--secret-code` | TextIn Secret Code（覆盖环境变量和配置文件） |
283
295
  | `--base-url` | API 地址（私有化部署时使用） |
296
+ | `--profile` | 凭证 Profile：`workbuddy`、`easyclaw` |
297
+ | `--task-context` | Agent 任务上下文 JSON 文件路径 |
284
298
  | `--verbose` | 调试模式，打印 HTTP 请求详情 |
285
299
 
286
300
  ### API capabilities 默认值
@@ -336,10 +350,10 @@ xparse-cli config reset
336
350
  xparse-cli config path
337
351
  ```
338
352
 
339
- ### 自更新
353
+ ### 升级 CLI
340
354
 
341
355
  ```bash
342
- xparse-cli update
356
+ npm install --global xparse-cli@latest
343
357
  ```
344
358
 
345
359
  ### 调试模式
@@ -414,7 +428,10 @@ OAuth 参数优先级：
414
428
 
415
429
  稳定错误码至少包括：`FILE_NOT_FOUND`、`EMPTY_FILE`、`UNSUPPORTED_FILE_TYPE`、
416
430
  `FILE_TOO_LARGE`、`PAGE_LIMIT_EXCEEDED`、`PAID_QUOTA_REQUIRED`、
417
- `CAPABILITY_QUERY_FAILED`、`SPLIT_FAILED`、`MERGE_FAILED` 和 `RETRY_EXHAUSTED`。
431
+ `AUTHENTICATION_FAILED`、`CAPABILITY_QUERY_FAILED`、`OUTPUT_FAILED`、`SPLIT_FAILED`、
432
+ `MERGE_FAILED` 和 `RETRY_EXHAUSTED`。服务端返回 `40422` 时仍包装为
433
+ `SERVICE_ERROR`，`message` 保留服务端给出的直接原因；程序判断使用 `next_action`，
434
+ 诊断时可读取 `details.api_code` 和 `request_id`。
418
435
 
419
436
  人工调试或兼容旧脚本时可使用 `--error-format=text`，恢复原有的多行文本与建议格式。
420
437
  其他子命令继续使用原有文本错误格式。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xparse-cli",
3
- "version": "2.3.0-beta.5",
3
+ "version": "2.3.0-beta.8",
4
4
  "description": "TextIn xParse command-line client for document parsing",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -19,12 +19,12 @@
19
19
  "node": ">=18"
20
20
  },
21
21
  "optionalDependencies": {
22
- "xparse-cli-darwin-amd64": "2.3.0-beta.5",
23
- "xparse-cli-darwin-arm64": "2.3.0-beta.5",
24
- "xparse-cli-linux-amd64": "2.3.0-beta.5",
25
- "xparse-cli-linux-arm64": "2.3.0-beta.5",
26
- "xparse-cli-windows-amd64": "2.3.0-beta.5",
27
- "xparse-cli-windows-arm64": "2.3.0-beta.5"
22
+ "xparse-cli-darwin-amd64": "2.3.0-beta.8",
23
+ "xparse-cli-darwin-arm64": "2.3.0-beta.8",
24
+ "xparse-cli-linux-amd64": "2.3.0-beta.8",
25
+ "xparse-cli-linux-arm64": "2.3.0-beta.8",
26
+ "xparse-cli-windows-amd64": "2.3.0-beta.8",
27
+ "xparse-cli-windows-arm64": "2.3.0-beta.8"
28
28
  },
29
29
  "publishConfig": {
30
30
  "access": "public",