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

package/README.md

@@ -1,87 +1,55 @@
-# xParser CLI
+# TextIn xParse CLI
 
-Textin xParser 文档解析命令行工具，基于 [TextIn xParse API](https://docs.textin.com/api-reference/endpoint/xparse/v1/parse-sync) 实现。
+TextIn xParse 文档解析命令行工具，基于 [TextIn xParse API](https://docs.textin.com/api-reference/endpoint/xparse/v1/parse-sync) 实现。
 
 支持将 PDF、图片、Office 文档等 20+ 格式转换为 Markdown 及结构化数据。
 
 ## 安装
 
-### npm
-
 需要 Node.js 18 或更高版本：
 
+### 安装正式版
+
 ```bash
-npm install -g xparse-cli
+npm install --global xparse-cli
 ```
 
-安装后可运行 `xparse-cli version` 检查版本。
-
-### 一键安装
-
-**Linux / macOS**
+国内网络可以显式使用 npmmirror：
 
 ```bash
-source <(curl -fsSL https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.sh)
+npm install --global --registry=https://registry.npmmirror.com xparse-cli
 ```
 
-**Windows (PowerShell)**
+安装后运行以下命令检查版本：
 
-```powershell
-irm https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.ps1 | iex
+```bash
+xparse-cli version
 ```
 
-### 从源码构建
-
-> 要求 Go 1.23+
+### 安装 beta 或精确版本
 
-**单平台构建（当前系统）：**
+跟随当前 beta：
 
 ```bash
-go build -o xparse-cli .
+npm install --global xparse-cli@beta
 ```
 
-**带版本信息构建：**
+为了获得可复现的测试环境，应安装精确版本：
 
 ```bash
-VERSION=v0.0.1
-COMMIT=$(git rev-parse --short HEAD)
-DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-PKG=github.com/intsig-textin/xparse-skills/cli/cmd/parse
-
-go build -ldflags "-s -w \
-  -X ${PKG}.version=${VERSION} \
-  -X ${PKG}.commit=${COMMIT} \
-  -X ${PKG}.date=${DATE}" \
-  -o xparse-cli .
+npm install --global xparse-cli@2.3.0-beta.5
 ```
 
-**交叉编译全平台：**
+### 升级
 
 ```bash
-VERSION=v0.0.1
-COMMIT=$(git rev-parse --short HEAD)
-DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-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 .
-GOOS=linux   GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-linux-arm64 .
-GOOS=darwin  GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-darwin-amd64 .
-GOOS=darwin  GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-darwin-arm64 .
-GOOS=windows GOARCH=amd64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-windows-amd64.exe .
-GOOS=windows GOARCH=arm64 go build -ldflags "$LDFLAGS" -o dist/xparse-cli-windows-arm64.exe .
+npm install --global xparse-cli@latest
 ```
 
-产物位于 `dist/` 目录，共 6 个二进制文件：
+beta、精确版本以及国内镜像同样通过 `npm install --global` 管理。CLI 不再单独下载或替换二进制文件。
 
-| 平台 | 文件 |
-|------|------|
-| Linux x86_64 | `xparse-cli-linux-amd64` |
-| Linux ARM64 | `xparse-cli-linux-arm64` |
-| macOS Intel | `xparse-cli-darwin-amd64` |
-| macOS Apple Silicon | `xparse-cli-darwin-arm64` |
-| Windows x86_64 | `xparse-cli-windows-amd64.exe` |
-| Windows ARM64 | `xparse-cli-windows-arm64.exe` |
+WorkBuddy 集成、国内/海外 Connector 区别、beta 命名规则及完整发版步骤见
+[WorkBuddy Connector 概念与发版流程](docs/workbuddy_connector_release.md)。
 
 ## 快速开始
 
@@ -106,7 +74,7 @@ xparse-cli parse secret.pdf --password mypassword
 
 ### 2. 付费 API（可选）
 
-前往 [Textin 控制台](https://www.textin.com/user/login?redirect=%252Fconsole%252Fdashboard%252Fsetting&from=xparse-parse-skill) 获取凭证（`x-ti-app-id` 和 `x-ti-secret-code`），然后运行：
+前往 [TextIn 控制台](https://www.textin.com/user/login?redirect=%252Fconsole%252Fdashboard%252Fsetting&from=xparse-parse-skill) 获取凭证（`x-ti-app-id` 和 `x-ti-secret-code`），然后运行：
 
 ```bash
 xparse-cli auth
@@ -134,7 +102,7 @@ Task Runtime 把上传、执行状态和结果交给服务端持久化。`task r
 ```bash
 xparse-cli task run --files 'contracts/*.pdf'
 xparse-cli task status <task-id> --run-id <run-id>
-xparse-cli task export <task-id> --run-id <run-id> --out-dir ./task-output
+xparse-cli task export <task-id> --run-id <run-id> --output ./task-output
 xparse-cli task read <task-id> contract-a.pdf --run-id <run-id>
 xparse-cli task debug <task-id> --run-id <run-id>
 ```
@@ -150,24 +118,34 @@ xparse-cli task run --files 'contracts/*.pdf' --operation-id <operation-id>
 需要在一个终端命令中等待完成并导出时，显式使用 `--wait`：
 
 ```bash
-xparse-cli task run --files 'contracts/*.pdf' --wait --out-dir ./task-output
+xparse-cli task run --files 'contracts/*.pdf' --wait --output ./task-output
+```
+
+单个文件的密码与 `parse` 一样直接使用 `--password`，CLI 会在第一次上传时携带密码：
+
+```bash
+xparse-cli task run secret.pdf --password open-password
 ```
 
-某些文件需要密码时，从 stdin 提供按路径或文件名映射的 JSON，避免密码进入进程参数和 shell 历史：
+多个输入中只有部分文件有密码时，只为受保护文件重复传入 `selector=password` 绑定。selector
+可使用精确路径、唯一文件名，或 `PASSWORD_INPUT_REQUIRED` 返回的稳定 selector：
 
 ```bash
-printf '%s' '{"secret.pdf":"open-password"}' | \
-  xparse-cli task run secret.pdf --passwords-stdin
+xparse-cli task run a.pdf b.jpg c.pdf \
+  --password a.pdf=open-a \
+  --password c.pdf=open-c
 ```
 
-若服务端返回 `40423`，补充失败文件的密码并只重跑对应 Resource：
+若服务端仍返回 `40423`，CLI 会扫描完本批次并一次性返回所有缺失或错误密码文件；使用返回的
+selector 和同一 `operation_id` 补充 `--password selector=password` 后重试。已经知道的密码不依赖
+`40423` 发现。对于已经创建的 Task，可只更新失败 Resource 并新建一个 selected-files Run：
 
 ```bash
-printf '%s' '{"<resource-id>":"open-password"}' | \
-  xparse-cli task continue <task-id> --passwords-stdin
+xparse-cli task continue <task-id> \
+  --password <resource-id>=open-password
 ```
 
-`continue` 同样默认提交即返回；保存新的 `run_id`，完成后再单独执行 `task export`。只有显式添加 `--wait` 时才能同时使用 `--out-dir`。
+`continue` 同样默认提交即返回；保存新的 `run_id`，完成后再单独执行 `task export`。只有显式添加 `--wait` 时才能同时使用 `--output`。
 
 等待人工付费授权或充值后，必须恢复精确 Run：
 
@@ -249,7 +227,14 @@ xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
 | `xparse-cli config` | 管理配置（show / set / reset / path） |
 | `xparse-cli quota` | 查看免费 API 额度 |
 | `xparse-cli download` | 下载解析结果中 elements 的图片 |
-| `xparse-cli update` | 自更新 CLI 到最新版本 |
+| `xparse-cli cache` | 查看或清理本地文档缓存 |
+| `xparse-cli get_doc_info` | 读取本地 PDF 基础信息 |
+| `xparse-cli get_outline` | 读取缓存文档的目录结构 |
+| `xparse-cli read_content` | 按元素 ID 读取缓存内容 |
+| `xparse-cli read_pages` | 按页码范围读取缓存内容 |
+| `xparse-cli search_text` | 搜索缓存文档文本 |
+| `xparse-cli get_confidence` | 查询元素或页面的 OCR 置信度 |
+| `xparse-cli completion` | 生成 shell 自动补全脚本 |
 | `xparse-cli version` | 显示版本信息 |
 
 全局参数 `--profile workbuddy` 或 `--profile easyclaw` 可放在子命令前后，用于选择隔离凭证。
@@ -272,15 +257,18 @@ xparse-cli --profile easyclaw parse report.pdf --api paid --auth-method oauth
 | `--include-char-details` | `false` | 返回字符级坐标和置信度 |
 | `--table-view` | `html` | 表格视图：`html`、`markdown` |
 | `--list` | | 从文件读取输入列表（需配合 `--output`） |
-| `--output` | _(stdout)_ | 输出文件路径或目录（目录须已存在） |
+| `--output` | _(stdout)_ | 输出文件路径或目录（目录不存在时自动创建） |
+| `--error-format` | `json` | 错误输出格式：`json`、`text` |
 
 **全局参数（所有命令均支持）：**
 
 | 参数 | 说明 |
 |------|------|
-| `--app-id` | Textin App ID（覆盖环境变量和配置文件） |
-| `--secret-code` | Textin Secret Code（覆盖环境变量和配置文件） |
+| `--app-id` | TextIn App ID（覆盖环境变量和配置文件） |
+| `--secret-code` | TextIn Secret Code（覆盖环境变量和配置文件） |
 | `--base-url` | API 地址（私有化部署时使用） |
+| `--profile` | 凭证 Profile：`workbuddy`、`easyclaw` |
+| `--task-context` | Agent 任务上下文 JSON 文件路径 |
 | `--verbose` | 调试模式，打印 HTTP 请求详情 |
 
 ### API capabilities 默认值
@@ -336,10 +324,10 @@ xparse-cli config reset
 xparse-cli config path
 ```
 
-### 自更新
+### 升级 CLI
 
 ```bash
-xparse-cli update
+npm install --global xparse-cli@latest
 ```
 
 ### 调试模式
@@ -414,7 +402,10 @@ OAuth 参数优先级：
 
 稳定错误码至少包括：`FILE_NOT_FOUND`、`EMPTY_FILE`、`UNSUPPORTED_FILE_TYPE`、
 `FILE_TOO_LARGE`、`PAGE_LIMIT_EXCEEDED`、`PAID_QUOTA_REQUIRED`、
-`CAPABILITY_QUERY_FAILED`、`SPLIT_FAILED`、`MERGE_FAILED` 和 `RETRY_EXHAUSTED`。
+`AUTHENTICATION_FAILED`、`CAPABILITY_QUERY_FAILED`、`OUTPUT_FAILED`、`SPLIT_FAILED`、
+`MERGE_FAILED` 和 `RETRY_EXHAUSTED`。服务端返回 `40422` 时仍包装为
+`SERVICE_ERROR`，`message` 保留服务端给出的直接原因；程序判断使用 `next_action`，
+诊断时可读取 `details.api_code` 和 `request_id`。
 
 人工调试或兼容旧脚本时可使用 `--error-format=text`，恢复原有的多行文本与建议格式。
 其他子命令继续使用原有文本错误格式。

package/package.json

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