xparse-cli 0.0.0 → 2.2.1-beta.1

package/README.md

@@ -1,9 +1,381 @@
-# xparse-cli
+# xParser CLI
 
-The stable npm channel is reserved but not released yet.
+Textin xParser 文档解析命令行工具，基于 [TextIn xParse API](https://docs.textin.com/api-reference/endpoint/xparse/v1/parse-sync) 实现。
 
-To opt in to the beta, install it explicitly:
+支持将 PDF、图片、Office 文档等 20+ 格式转换为 Markdown 及结构化数据。
+
+## 安装
+
+### npm Beta
+
+需要 Node.js 18 或更高版本。Beta 版本必须显式安装，不会被普通安装或升级自动选中：
+
+```bash
+npm install -g xparse-cli@2.2.1-beta.1
+```
+
+安装后可运行 `xparse-cli version` 检查版本。
+
+### 一键安装
+
+**Linux / macOS**
+
+```bash
+source <(curl -fsSL https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.sh)
+```
+
+**Windows (PowerShell)**
+
+```powershell
+irm https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.ps1 | iex
+```
+
+### 从源码构建
+
+> 要求 Go 1.23+
+
+**单平台构建（当前系统）：**
+
+```bash
+go build -o xparse-cli .
+```
+
+**带版本信息构建：**
+
+```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 .
+```
+
+**交叉编译全平台：**
+
+```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 .
+```
+
+产物位于 `dist/` 目录，共 6 个二进制文件：
+
+| 平台 | 文件 |
+|------|------|
+| 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` |
+
+## 快速开始
+
+### 1. 零配置解析（自动使用免费额度）
+
+```bash
+# 输出 Markdown 到终端
+xparse-cli parse report.pdf
+
+# JSON 视图
+xparse-cli parse report.pdf --view json
+
+# 保存到目录
+xparse-cli parse report.pdf --output ./output/
+
+# 指定页码范围
+xparse-cli parse report.pdf --page-range "1-5"
+
+# 加密 PDF
+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`），然后运行：
+
+```bash
+xparse-cli auth
+```
+
+按提示输入 App ID 和 Secret Code，凭证将保存至 `~/.xparse-cli/config.yaml`。
+
+也可通过环境变量配置（适合 CI/CD）：
+
+```bash
+export XPARSE_APP_ID=your_app_id
+export XPARSE_SECRET_CODE=your_secret_code
+```
 
 ```bash
-npm install -g xparse-cli@beta
+# 显式使用付费 API
+xparse-cli parse report.pdf --api paid
 ```
+
+也可以使用 OAuth。正式二进制默认使用无 Secret 的 public client
+`cli_textin_xparse`；私有部署可以通过 flag、环境变量或配置文件覆盖：
+
+```bash
+# 终端中进入 AppKey / OAuth / 状态 / 登出选单
+xparse-cli auth
+
+export XPARSE_OAUTH_CLIENT_ID=cli_your_registered_client
+
+# Device Flow（SSH、服务器、Agent 推荐）
+xparse-cli auth device --open-browser=never
+
+# 本地桌面 Authorization Code + PKCE；默认使用系统分配的可用回调端口
+xparse-cli auth browser
+
+# 强制重新展示授权确认页
+xparse-cli auth browser --prompt=consent
+
+# 显式使用 OAuth 调用 paid API
+xparse-cli parse report.pdf --api paid --auth-method oauth
+```
+
+认证选单使用方向键或 `j`/`k` 移动，`Enter` 确认，`Esc` 或 `Ctrl+C` 取消。
+菜单会显示当前环境、OAuth/AppKey 配置状态和当前生效的认证方式。需要屏幕阅读器兼容的
+线性提示时，可设置 `XPARSE_TUI_ACCESSIBLE=1`。
+
+WorkBuddy Connector 使用显式 Profile，避免依赖任务进程是否继承 Connector 环境变量：
+
+```bash
+xparse-cli --profile workbuddy auth device --open-browser=always
+xparse-cli --profile workbuddy parse report.pdf --api paid --auth-method oauth
+```
+
+该 Profile 的凭证保存在 `~/.xparse-cli/profiles/workbuddy/`，其登录和登出不会影响
+终端中默认的 `~/.xparse-cli` 凭证；请求会自动携带 `X-From: workbuddy`。
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| `xparse-cli parse` | 解析文档，输出 Markdown / JSON |
+| `xparse-cli auth` | TTY 中进入认证选单；非 TTY 保持旧版 AppKey 输入流程 |
+| `xparse-cli auth app-key` | 配置 AppKey 凭证 |
+| `xparse-cli auth device` | OAuth Device Flow 登录 |
+| `xparse-cli auth browser` | OAuth Authorization Code + PKCE 登录 |
+| `xparse-cli auth status` | 只读查看登录状态 |
+| `xparse-cli auth logout` | 删除指定认证方式的本地凭证 |
+| `xparse-cli config` | 管理配置（show / set / reset / path） |
+| `xparse-cli quota` | 查看免费 API 额度 |
+| `xparse-cli download` | 下载解析结果中 elements 的图片 |
+| `xparse-cli update` | 自更新 CLI 到最新版本 |
+| `xparse-cli version` | 显示版本信息 |
+
+全局参数 `--profile workbuddy` 可放在子命令前后，用于选择 WorkBuddy 的隔离凭证。
+
+## parse 命令参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--view` | `markdown` | 输出视图：`markdown`、`json` |
+| `--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` 时关闭 |
+| `--include-inline-objects` | `true` | 内嵌对象：公式、手写、复选框、嵌入图片，默认开启。为 `false` 时关闭 |
+| `--include-image-data` | `true` | 图片 URL 及 Base64 数据，默认开启。为 `false` 时关闭 |
+| `--include-table-structure` | `true` | 表格单元格结构与坐标，默认开启。为 `false` 时关闭 |
+| `--include-pages` | `true` | 分页元数据与预览图 |
+| `--include-title-tree` | `true` | 文档标题层级目录树 |
+| `--include-char-details` | `false` | 返回字符级坐标和置信度 |
+| `--table-view` | `html` | 表格视图：`html`、`markdown` |
+| `--list` | | 从文件读取输入列表（需配合 `--output`） |
+| `--output` | _(stdout)_ | 输出文件路径或目录（目录须已存在） |
+
+**全局参数（所有命令均支持）：**
+
+| 参数 | 说明 |
+|------|------|
+| `--app-id` | Textin App ID（覆盖环境变量和配置文件） |
+| `--secret-code` | Textin Secret Code（覆盖环境变量和配置文件） |
+| `--base-url` | API 地址（私有化部署时使用） |
+| `--verbose` | 调试模式，打印 HTTP 请求详情 |
+
+### API capabilities 默认值
+
+CLI 默认开启以下能力，Agent 无需额外配置：
+
+| 能力 | 默认 |
+|------|------|
+| 标题层级 | 开启 |
+| 内嵌对象（图片） | 开启 |
+| 图片数据 | 开启 |
+| 表格视图 | `html` |
+| 表格结构 | 开启 |
+| 分页结果 | 开启 |
+| 目录树 | 开启 |
+| 字符级详情 | **关闭**（`--include-char-details` 开启） |
+
+## 使用示例
+
+### 管道组合
+
+```bash
+# 解析并搜索
+xparse-cli parse report.pdf | grep "revenue"
+
+# 解析并喂给 LLM
+xparse-cli parse paper.pdf | llm "summarize this paper"
+```
+
+### 批量处理
+
+```bash
+# 从文件列表读取
+xparse-cli parse --list files.txt --output ./results/
+```
+
+### 下载图片
+
+```bash
+# 从解析结果 JSON 中提取 elements 图片并下载
+xparse-cli download --from result.json --output ./images/
+
+# 直接下载图片 URL
+xparse-cli download https://web-api.textin.com/ocr_image/external/abc123.jpg --output ./images/
+```
+
+### 配置管理
+
+```bash
+xparse-cli config show
+xparse-cli config set base_url https://your-server.com
+xparse-cli config reset
+xparse-cli config path
+```
+
+### 自更新
+
+```bash
+xparse-cli update
+```
+
+### 调试模式
+
+```bash
+xparse-cli parse report.pdf --verbose
+```
+
+## 凭证管理
+
+| 优先级 | 方式 | 说明 |
+|--------|------|------|
+| 1 | 命令行参数 | `--app-id` 和 `--secret-code` |
+| 2 | 环境变量 | `XPARSE_APP_ID` 和 `XPARSE_SECRET_CODE` |
+| 3 | 配置文件 | `~/.xparse-cli/config.yaml` |
+
+AppKey 与 OAuth Token 分开保存：
+
+```text
+~/.xparse-cli/config.yaml       # AppKey 和非敏感 OAuth 偏好
+~/.xparse-cli/oauth-token.json  # OAuth Access/Refresh Token
+```
+
+目录权限固定为 `0700`，凭证文件固定为 `0600`，更新通过 fsync + rename 原子替换。
+`xparse-cli config reset` 只重置 YAML，不会删除 OAuth Token；请使用
+`xparse-cli auth logout --method oauth|app-key|all` 精确登出。
+OAuth 登出会先尝试通过 `/oauth21/revoke` 撤销 Refresh Token（没有时撤销 Access
+Token），随后始终删除本地 Token。远端暂时不可用只会产生警告，不会阻止本地登出；
+登出不会删除服务端记住的 consent。
+
+OAuth 参数优先级：
+
+| 参数 | 优先级 |
+|------|--------|
+| Client ID | `--client-id` > `XPARSE_OAUTH_CLIENT_ID` > `oauth.client_id` > public default `cli_textin_xparse` |
+| Scope | `--scope` > `XPARSE_OAUTH_SCOPE` > `oauth.scope` > `ocr:*` |
+| 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 先读取现有 quota 接口，在匿名每日免费额度与登录
+用户的免费套餐额度之间制定执行计划。显式 `--api free` 固定调用免费 Agent 接口，
+显式 `--api paid` 固定调用现有付费接口，不参与自动额度路由。
+
+认证选择顺序为：显式 `--auth-method` / 环境或配置选择 > OAuth > 完整 AppKey >
+匿名（仅可选认证接口）。自动选择 OAuth 时若刷新失败，会先回退完整 AppKey；两者都
+不可用时，quota、免费解析与 telemetry 才匿名继续。显式选择 OAuth 失败不会切换身份。
+
+本地 PDF 会使用服务端返回的 `max_pages_per_request` 和 `max_file_size_mb` 预检。
+仅页数超限且原文件体积合规时使用页范围分段；文件体积超限时生成真实临时 PDF
+片段，按可重试错误最多重试一次，并按原始页码顺序合并结果。临时片段执行后删除。
+
+## 退出码与错误处理
+
+| 码 | 含义 | stderr 格式 |
+|----|------|-------------|
+| 0 | 成功 | — |
+| 1 | 一般错误 / 网络异常 | 纯文本 + `> [tag] suggestion` |
+| 2 | 参数错误 | 纯文本 + `> [tag] suggestion` |
+| 3 | API 返回错误 | `api_code：message` + `> [tag] suggestion` |
+
+每条错误输出到 stderr，格式：
+
+```
+<错误信息>
+> <建议操作>
+  (request_id: xxx, contact Textin support if unresolved)   ← 部分 API 错误额外输出
+```
+
+第二行以 `>` 开头，包含 `[tag]` 标签指示处理方式：
+
+| 标签 | 含义 |
+|------|------|
+| `[fix]` | 修正参数后重新执行 |
+| `[retry]` | 自动重试（带退避） |
+| `[fallback]` | 尝试替代方案 |
+| `[ask human]` | 需要人工介入 |
+
+示例：
+
+```
+invalid --view value, must be 'markdown' or 'json'
+> [fix] use --view markdown or --view json
+```
+
+```
+40306：服务暂时不可用
+> [retry] wait 3s then retry, max 2 retries
+  (request_id: 644e2efdb..., contact Textin support if unresolved)
+```
+
+> stdout 仅输出文档内容，stderr 仅输出错误信息，exit code 严格为 0/1/2/3。
+> 完整的错误和建议枚举见 [suggestion.txt](suggestion.txt)。
+
+## 支持的文件格式
+
+| 类型 | 格式 |
+|------|------|
+| 文档 | PDF, DOC, DOCX, TXT, RTF, OFD |
+| 图片 | PNG, JPG, JPEG, BMP, TIFF, WebP |
+| 表格 | XLS, XLSX, CSV |
+| 演示 | PPT, PPTX |
+| 网页 | HTML, MHTML |
+
+限制：
+
+| 限制项 | 免费 API | 付费 API |
+|--------|----------|----------|
+| 文件大小 | 由 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/bin/xparse-cli.js

@@ -1,8 +1,30 @@
 #!/usr/bin/env node
 "use strict";
 
-console.error(
-  "xparse-cli does not have a stable npm release yet. " +
-    "Install the beta explicitly with: npm install -g xparse-cli@beta",
-);
-process.exit(1);
+const { spawnSync } = require("node:child_process");
+const { resolveBinaryPath } = require("../lib/platform.js");
+
+let binaryPath;
+try {
+  binaryPath = resolveBinaryPath();
+} catch (error) {
+  console.error(`xparse-cli: ${error.message}`);
+  process.exit(1);
+}
+
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  windowsHide: false,
+});
+
+if (result.error) {
+  console.error(`xparse-cli: unable to start ${binaryPath}: ${result.error.message}`);
+  process.exit(1);
+}
+
+if (result.signal) {
+  console.error(`xparse-cli: process terminated by ${result.signal}`);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/lib/platform.js

@@ -0,0 +1,68 @@
+"use strict";
+
+const path = require("node:path");
+
+const PLATFORM_PACKAGES = Object.freeze({
+  "darwin-x64": {
+    packageName: "xparse-cli-darwin-amd64",
+    binary: "xparse-cli-darwin-amd64",
+  },
+  "darwin-arm64": {
+    packageName: "xparse-cli-darwin-arm64",
+    binary: "xparse-cli-darwin-arm64",
+  },
+  "linux-x64": {
+    packageName: "xparse-cli-linux-amd64",
+    binary: "xparse-cli-linux-amd64",
+  },
+  "linux-arm64": {
+    packageName: "xparse-cli-linux-arm64",
+    binary: "xparse-cli-linux-arm64",
+  },
+  "win32-x64": {
+    packageName: "xparse-cli-windows-amd64",
+    binary: "xparse-cli-windows-amd64.exe",
+  },
+  "win32-arm64": {
+    packageName: "xparse-cli-windows-arm64",
+    binary: "xparse-cli-windows-arm64.exe",
+  },
+});
+
+function getPlatformSpec(platform = process.platform, arch = process.arch) {
+  const spec = PLATFORM_PACKAGES[`${platform}-${arch}`];
+  if (!spec) {
+    throw new Error(
+      `Unsupported platform: ${platform}/${arch}. ` +
+        "Supported platforms are macOS, Linux, and Windows on x64 or arm64.",
+    );
+  }
+  return spec;
+}
+
+function resolveBinaryPath(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const arch = options.arch ?? process.arch;
+  const resolve = options.resolve ?? require.resolve;
+  const spec = getPlatformSpec(platform, arch);
+
+  let manifestPath;
+  try {
+    manifestPath = resolve(`${spec.packageName}/package.json`);
+  } catch (error) {
+    const wrapped = new Error(
+      `The optional package ${spec.packageName} is missing. ` +
+        "Reinstall xparse-cli without omitting optional dependencies.",
+    );
+    wrapped.cause = error;
+    throw wrapped;
+  }
+
+  return path.join(path.dirname(manifestPath), "bin", spec.binary);
+}
+
+module.exports = {
+  PLATFORM_PACKAGES,
+  getPlatformSpec,
+  resolveBinaryPath,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "xparse-cli",
-  "version": "0.0.0",
-  "description": "Stable-channel placeholder for xparse-cli",
+  "version": "2.2.1-beta.1",
+  "description": "TextIn xParse command-line client for document parsing",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -12,13 +12,22 @@
     "xparse-cli": "bin/xparse-cli.js"
   },
   "files": [
-    "bin/"
+    "bin/",
+    "lib/"
   ],
   "engines": {
     "node": ">=18"
   },
+  "optionalDependencies": {
+    "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",
-    "tag": "latest"
+    "tag": "beta"
   }
 }