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

package/README.md

@@ -1,4 +1,4 @@
-# xParse Client
+# xParser CLI
 
 Textin xParser 文档解析命令行工具，基于 [TextIn xParse API](https://docs.textin.com/api-reference/endpoint/xparse/v1/parse-sync) 实现。
 
@@ -11,7 +11,7 @@ Textin xParser 文档解析命令行工具，基于 [TextIn xParse API](https://
 需要 Node.js 18 或更高版本。Beta 版本必须显式安装，不会被普通安装或升级自动选中：
 
 ```bash
-npm install -g xparse-cli@beta
+npm install -g xparse-cli@2.2.1-beta.1
 ```
 
 安装后可运行 `xparse-cli version` 检查版本。
@@ -37,7 +37,6 @@ irm https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.ps1 | iex
 **单平台构建（当前系统）：**
 
 ```bash
-cd xparse-client
 go build -o xparse-cli .
 ```
 
@@ -47,7 +46,7 @@ go build -o xparse-cli .
 VERSION=v0.0.1
 COMMIT=$(git rev-parse --short HEAD)
 DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-PKG=gitlab.intsig.net/xparse/xparse-client/cmd
+PKG=github.com/intsig-textin/xparse-skills/cli/cmd/parse
 
 go build -ldflags "-s -w \
   -X ${PKG}.version=${VERSION} \
@@ -62,7 +61,7 @@ go build -ldflags "-s -w \
 VERSION=v0.0.1
 COMMIT=$(git rev-parse --short HEAD)
 DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-PKG=gitlab.intsig.net/xparse/xparse-client/cmd
+PKG=github.com/intsig-textin/xparse-skills/cli/cmd/parse
 LDFLAGS="-s -w -X ${PKG}.version=${VERSION} -X ${PKG}.commit=${COMMIT} -X ${PKG}.date=${DATE}"
 
 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
 
 ## 快速开始
 
-### 1. 零配置解析（免费 API）
+### 1. 零配置解析（自动使用免费额度）
 
 ```bash
 # 输出 Markdown 到终端
@@ -187,8 +186,8 @@ xparse-cli --profile workbuddy parse report.pdf --api paid --auth-method oauth
 | 参数 | 默认值 | 说明 |
 |------|--------|------|
 | `--view` | `markdown` | 输出视图：`markdown`、`json` |
-| `--api` | `free` | API 模式：`free`、`paid`；`auto` 是 `free` 的兼容别名 |
-| `--auth-method` | _(自动)_ | paid API 认证：`app-key`、`oauth` |
+| `--api` | `auto` | API 模式：`auto`、`free`、`paid`；`auto` 根据服务端额度快照路由 |
+| `--auth-method` | _(自动)_ | 请求认证：`app-key`、`oauth` |
 | `--page-range` | | 页码范围：`"1-5"` 或 `"1-2,5-10"` |
 | `--password` | | 加密文档密码 |
 | `--include-hierarchy` | `true` | 元素层级关系与父子关联，默认开启。为 `false` 时关闭 |
@@ -307,30 +306,26 @@ OAuth 参数优先级：
 | Browser redirect | `--redirect-uri` > `XPARSE_OAUTH_REDIRECT_URI` > `oauth.redirect_uri` > `http://127.0.0.1:0/callback` |
 | Base URL | `--base-url` > `XPARSE_BASE_URL` > `base_url` > `https://api.textin.com` |
 
-不传 `--api` 时使用 `auto`：CLI 查询服务端实时能力，优先使用免费额度，其次使用账户
-已经拥有且不会产生新费用的套餐；需要产生新费用时必须停止并要求用户确认。已有 AppKey、
-OAuth 登录态或上次选择的认证方式都不会被当作新增付费授权。
-只有显式传入 `--api paid` 才允许新付费路径；未同时指定 `--auth-method` 时，付费模式
-优先选择有效 OAuth 会话，没有 OAuth 会话时再使用完整 AppKey。通过 flag、环境变量或
-配置显式选择的 OAuth 或 AppKey 失败时不会切换到另一种凭证。
+不传 `--api` 时使用 `auto`：CLI 先读取现有 quota 接口，在匿名每日免费额度与登录
+用户的免费套餐额度之间制定执行计划。显式 `--api free` 固定调用免费 Agent 接口，
+显式 `--api paid` 固定调用现有付费接口，不参与自动额度路由。
 
-成功执行 `auth app-key` 或 OAuth 登录仍会记录用户最后明确选择的认证方式，但该设置
-仅供显式 `--api paid` 的凭证选择。`--api free` 与 `--api auto` 会在能力查询时携带可用
-身份以读取既有权益；真正执行免费请求时不会发送 AppKey。
-免费解析遇到 OAuth 刷新失败时会输出警告并匿名继续，确保解析可用；该降级仅适用于
-免费接口。付费 OAuth 刷新失败仍会停止请求，也不会回退到 AppKey。
+认证选择顺序为：显式 `--auth-method` / 环境或配置选择 > OAuth > 完整 AppKey >
+匿名（仅可选认证接口）。自动选择 OAuth 时若刷新失败，会先回退完整 AppKey；两者都
+不可用时，quota、免费解析与 telemetry 才匿名继续。显式选择 OAuth 失败不会切换身份。
+
+本地 PDF 会使用服务端返回的 `max_pages_per_request` 和 `max_file_size_mb` 预检。
+仅页数超限且原文件体积合规时使用页范围分段；文件体积超限时生成真实临时 PDF
+片段，按可重试错误最多重试一次，并按原始页码顺序合并结果。临时片段执行后删除。
 
 ## 退出码与错误处理
 
 | 码 | 含义 | stderr 格式 |
 |----|------|-------------|
 | 0 | 成功 | — |
-| 1 | 一般错误 / 网络异常 | 文本或结构化 JSON |
-| 2 | 参数错误 | 文本或结构化 JSON |
-| 3 | API 返回错误 | 文本或含 `api_code`、`request_id` 的结构化 JSON |
-
-普通 CLI 默认使用文本错误；`--profile workbuddy` 的 `--error-format auto` 默认输出
-JSON，也可显式传入 `--error-format json|text`。
+| 1 | 一般错误 / 网络异常 | 纯文本 + `> [tag] suggestion` |
+| 2 | 参数错误 | 纯文本 + `> [tag] suggestion` |
+| 3 | API 返回错误 | `api_code：message` + `> [tag] suggestion` |
 
 每条错误输出到 stderr，格式：
 
@@ -379,8 +374,8 @@ invalid --view value, must be 'markdown' or 'json'
 
 | 限制项 | 免费 API | 付费 API |
 |--------|----------|----------|
-| 文件大小 | 10MB | 500MB |
-| PDF 页数 | — | 1000 页 |
+| 文件大小 | 由 quota 的 `max_file_size_mb` 下发，PDF 可自动分片 | 500MB |
+| PDF 页数 | 由 quota 的 `max_pages_per_request` 下发，支持自动分段 | 1000 页 |
 | XLS/XLSX/CSV | — | 每 sheet ≤ 2000 行 × 100 列 |
 | TXT | — | ≤ 100KB |
 | 图片尺寸 | 20～20000 像素 | 20～20000 像素 |

package/package.json

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