xparse-cli 2.2.1-beta.0 → 2.2.1-beta.2

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 +36 -54
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # xParse Client
1
+ # xParser CLI
2
2
 
3
3
  Textin xParser 文档解析命令行工具，基于 [TextIn xParse API](https://docs.textin.com/api-reference/endpoint/xparse/v1/parse-sync) 实现。
4
4
 
@@ -11,7 +11,7 @@ Textin xParser 文档解析命令行工具，基于 [TextIn xParse API](https://
11
11
  需要 Node.js 18 或更高版本。Beta 版本必须显式安装，不会被普通安装或升级自动选中：
12
12
 
13
13
  ```bash
14
- npm install -g xparse-cli@beta
14
+ npm install -g xparse-cli@2.2.1-beta.2
15
15
  ```
16
16
 
17
17
  安装后可运行 `xparse-cli version` 检查版本。
@@ -37,7 +37,6 @@ irm https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.ps1 | iex
37
37
  **单平台构建（当前系统）：**
38
38
 
39
39
  ```bash
40
- cd xparse-client
41
40
  go build -o xparse-cli .
42
41
  ```
43
42
 
@@ -47,7 +46,7 @@ go build -o xparse-cli .
47
46
  VERSION=v0.0.1
48
47
  COMMIT=$(git rev-parse --short HEAD)
49
48
  DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
50
- PKG=gitlab.intsig.net/xparse/xparse-client/cmd
49
+ PKG=github.com/intsig-textin/xparse-skills/cli/cmd/parse
51
50
 
52
51
  go build -ldflags "-s -w \
53
52
  -X ${PKG}.version=${VERSION} \
@@ -62,7 +61,7 @@ go build -ldflags "-s -w \
62
61
  VERSION=v0.0.1
63
62
  COMMIT=$(git rev-parse --short HEAD)
64
63
  DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
65
- PKG=gitlab.intsig.net/xparse/xparse-client/cmd
64
+ PKG=github.com/intsig-textin/xparse-skills/cli/cmd/parse
66
65
  LDFLAGS="-s -w -X ${PKG}.version=${VERSION} -X ${PKG}.commit=${COMMIT} -X ${PKG}.date=${DATE}"
67
66
 
68
67
  GOOS=linux GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-linux-amd64 .
@@ -86,7 +85,7 @@ GOOS=windows GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-window
86
85
 
87
86
  ## 快速开始
88
87
 
89
- ### 1. 零配置解析（免费 API）
88
+ ### 1. 零配置解析（自动使用免费额度）
90
89
 
91
90
  ```bash
92
91
  # 输出 Markdown 到终端
@@ -187,8 +186,8 @@ xparse-cli --profile workbuddy parse report.pdf --api paid --auth-method oauth
187
186
  | 参数 | 默认值 | 说明 |
188
187
  |------|--------|------|
189
188
  | `--view` | `markdown` | 输出视图：`markdown`、`json` |
190
- | `--api` | `free` | API 模式：`free`、`paid`；`auto` 是 `free` 的兼容别名 |
191
- | `--auth-method` | _(自动)_ | paid API 认证：`app-key`、`oauth` |
189
+ | `--api` | `auto` | API 模式：`auto`、`free`、`paid`；`auto` 根据服务端额度快照路由 |
190
+ | `--auth-method` | _(自动)_ | 请求认证：`app-key`、`oauth` |
192
191
  | `--page-range` | | 页码范围：`"1-5"` 或 `"1-2,5-10"` |
193
192
  | `--password` | | 加密文档密码 |
194
193
  | `--include-hierarchy` | `true` | 元素层级关系与父子关联，默认开启。为 `false` 时关闭 |
@@ -307,60 +306,43 @@ OAuth 参数优先级：
307
306
  | Browser redirect | `--redirect-uri` > `XPARSE_OAUTH_REDIRECT_URI` > `oauth.redirect_uri` > `http://127.0.0.1:0/callback` |
308
307
  | Base URL | `--base-url` > `XPARSE_BASE_URL` > `base_url` > `https://api.textin.com` |
309
308
 
310
- 不传 `--api` 时使用 `auto`：CLI 查询服务端实时能力，优先使用免费额度，其次使用账户
311
- 已经拥有且不会产生新费用的套餐；需要产生新费用时必须停止并要求用户确认。已有 AppKey、
312
- OAuth 登录态或上次选择的认证方式都不会被当作新增付费授权。
313
- 只有显式传入 `--api paid` 才允许新付费路径；未同时指定 `--auth-method` 时，付费模式
314
- 优先选择有效 OAuth 会话，没有 OAuth 会话时再使用完整 AppKey。通过 flag、环境变量或
315
- 配置显式选择的 OAuth 或 AppKey 失败时不会切换到另一种凭证。
309
+ 不传 `--api` 时使用 `auto`：CLI 先读取现有 quota 接口，在匿名每日免费额度与登录
310
+ 用户的免费套餐额度之间制定执行计划。显式 `--api free` 固定调用免费 Agent 接口，
311
+ 显式 `--api paid` 固定调用现有付费接口，不参与自动额度路由。
316
312
 
317
- 成功执行 `auth app-key` 或 OAuth 登录仍会记录用户最后明确选择的认证方式，但该设置
318
- 仅供显式 `--api paid` 的凭证选择。`--api free` 与 `--api auto` 会在能力查询时携带可用
319
- 身份以读取既有权益；真正执行免费请求时不会发送 AppKey。
320
- 免费解析遇到 OAuth 刷新失败时会输出警告并匿名继续，确保解析可用；该降级仅适用于
321
- 免费接口。付费 OAuth 刷新失败仍会停止请求，也不会回退到 AppKey。
313
+ 认证选择顺序为：显式 `--auth-method` / 环境或配置选择 > OAuth > 完整 AppKey >
314
+ 匿名（仅可选认证接口）。自动选择 OAuth 时若刷新失败，会先回退完整 AppKey；两者都
315
+ 不可用时，quota、免费解析与 telemetry 才匿名继续。显式选择 OAuth 失败不会切换身份。
316
+
317
+ 本地 PDF 会使用服务端返回的 `max_pages_per_request` 和 `max_file_size_mb` 预检。
318
+ 仅页数超限且原文件体积合规时使用页范围分段；文件体积超限时生成真实临时 PDF
319
+ 片段，按可重试错误最多重试一次，并按原始页码顺序合并结果。临时片段执行后删除。
322
320
 
323
321
  ## 退出码与错误处理
324
322
 
325
- | 码 | 含义 | stderr 格式 |
326
- |----|------|-------------|
327
- | 0 | 成功 | — |
328
- | 1 | 一般错误 / 网络异常 | 文本或结构化 JSON |
329
- | 2 | 参数错误 | 文本或结构化 JSON |
330
- | 3 | API 返回错误 | 文本或含 `api_code`、`request_id` 的结构化 JSON |
323
+ `xparse-cli parse` 默认向 stderr 输出一行 JSON；stdout 仍只承载解析结果。退出码保持兼容：
331
324
 
332
- 普通 CLI 默认使用文本错误；`--profile workbuddy` 的 `--error-format auto` 默认输出
333
- JSON，也可显式传入 `--error-format json|text`。
325
+ | 码 | 含义 |
326
+ |----|------|
327
+ | 0 | 成功 |
328
+ | 1 | 一般错误 / 网络异常 |
329
+ | 2 | 参数错误 |
330
+ | 3 | API 返回错误 |
334
331
 
335
- 每条错误输出到 stderr，格式：
332
+ 基础字段为 `schema_version`、`error_code`、`message`、`actual_value`、`limit`、
333
+ `retryable` 和 `next_action`；需要时还会包含 `upgrade_url`、`request_id`、`task_id`
334
+ 和 `details`。`actual_value` 与 `limit` 不可确认时为 `null`，不会使用过期的本地固定值。
336
335
 
336
+ ```json
337
+ {"schema_version":"xparse_error.v1","error_code":"FILE_TOO_LARGE","message":"file exceeds the current service limit","actual_value":{"file_size_mb":12.5},"limit":{"source":"service","max_file_size_mb":8},"retryable":false,"next_action":"REDUCE_FILE","request_id":"644e2efdb..."}
337
338
  ```
338
- <错误信息>
339
- > <建议操作>
340
- (request_id: xxx, contact Textin support if unresolved) ← 部分 API 错误额外输出
341
- ```
342
-
343
- 第二行以 `>` 开头，包含 `[tag]` 标签指示处理方式：
344
-
345
- | 标签 | 含义 |
346
- |------|------|
347
- | `[fix]` | 修正参数后重新执行 |
348
- | `[retry]` | 自动重试（带退避） |
349
- | `[fallback]` | 尝试替代方案 |
350
- | `[ask human]` | 需要人工介入 |
351
339
 
352
- 示例：
340
+ 稳定错误码至少包括：`FILE_NOT_FOUND`、`EMPTY_FILE`、`UNSUPPORTED_FILE_TYPE`、
341
+ `FILE_TOO_LARGE`、`PAGE_LIMIT_EXCEEDED`、`PAID_QUOTA_REQUIRED`、
342
+ `CAPABILITY_QUERY_FAILED`、`SPLIT_FAILED`、`MERGE_FAILED` 和 `RETRY_EXHAUSTED`。
353
343
 
354
- ```
355
- invalid --view value, must be 'markdown' or 'json'
356
- > [fix] use --view markdown or --view json
357
- ```
358
-
359
- ```
360
- 40306：服务暂时不可用
361
- > [retry] wait 3s then retry, max 2 retries
362
- (request_id: 644e2efdb..., contact Textin support if unresolved)
363
- ```
344
+ 人工调试或兼容旧脚本时可使用 `--error-format=text`，恢复原有的多行文本与建议格式。
345
+ 其他子命令继续使用原有文本错误格式。
364
346
 
365
347
  > stdout 仅输出文档内容，stderr 仅输出错误信息，exit code 严格为 0/1/2/3。
366
348
  > 完整的错误和建议枚举见 [suggestion.txt](suggestion.txt)。
@@ -379,8 +361,8 @@ invalid --view value, must be 'markdown' or 'json'
379
361
 
380
362
  | 限制项 | 免费 API | 付费 API |
381
363
  |--------|----------|----------|
382
- | 文件大小 | 10MB | 500MB |
383
- | PDF 页数 | — | 1000 页 |
364
+ | 文件大小 | 由 quota 的 `max_file_size_mb` 下发，PDF 可自动分片 | 500MB |
365
+ | PDF 页数 | 由 quota 的 `max_pages_per_request` 下发，支持自动分段 | 1000 页 |
384
366
  | XLS/XLSX/CSV | — | 每 sheet ≤ 2000 行 × 100 列 |
385
367
  | TXT | — | ≤ 100KB |
386
368
  | 图片尺寸 | 20～20000 像素 | 20～20000 像素 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xparse-cli",
3
- "version": "2.2.1-beta.0",
3
+ "version": "2.2.1-beta.2",
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.2.1-beta.0",
23
- "xparse-cli-darwin-arm64": "2.2.1-beta.0",
24
- "xparse-cli-linux-amd64": "2.2.1-beta.0",
25
- "xparse-cli-linux-arm64": "2.2.1-beta.0",
26
- "xparse-cli-windows-amd64": "2.2.1-beta.0",
27
- "xparse-cli-windows-arm64": "2.2.1-beta.0"
22
+ "xparse-cli-darwin-amd64": "2.2.1-beta.2",
23
+ "xparse-cli-darwin-arm64": "2.2.1-beta.2",
24
+ "xparse-cli-linux-amd64": "2.2.1-beta.2",
25
+ "xparse-cli-linux-arm64": "2.2.1-beta.2",
26
+ "xparse-cli-windows-amd64": "2.2.1-beta.2",
27
+ "xparse-cli-windows-arm64": "2.2.1-beta.2"
28
28
  },
29
29
  "publishConfig": {
30
30
  "access": "public",