前言¶
Agent 接到 PDF、扫描件或 Office 附件时，常见做法是手写 PyMuPDF、pdfplumber 或 OCR 脚本，再自己拼 Markdown。单文件还能凑合，一旦要按章节检索、抽表格、处理加密 PDF，或批量多文档并跟踪任务状态，脚本会迅速变长，且和计费、配额、错误恢复缠在一起。
下面介绍 SkillHub 上的 TextIn xParse Document Parse（坐标 @user_2e25d6a2/xparse-parser，当前版本 1.0.4）。它把 xparse-cli 作为唯一执行内核，指导 Agent 完成解析、导航、摘要与结构化抽取，并覆盖可持久化的多文档 Task Runtime 流程。Skill 标签为 requires_api_key=false；付费路由与 AppKey/OAuth 仍按 CLI 文档单独配置。
这是什么¶
TextIn xParse Document Parse 是社区发布的办公效率类 Skill（分类 office-efficiency，发布者 user_2e25d6a2）。定位很直接：通过 xparse-cli 将 PDF、图片、Office、HTML、OFD 等本地文件或文档 URL 解析为干净的 Markdown 或结构化 JSON，供后续阅读、搜索、汇总或抽取表格与证据。
Skill 本身不重复实现 HTTP、OAuth、配额或结果合并逻辑；所有操作落在已安装的 xparse-cli 上。在需要从原始文件迈出第一步、且希望结果对 Agent 友好时，应优先选用本 Skill，而不是直接读裸 PDF 或自写 OCR。
核心功能¶
以下能力均来自官方 SKILL.md 与配套 reference，可按需组合使用。
单文档解析与输出¶
- 支持本地路径或 URL 输入，默认路由
--api auto（先查配额，以服务端为准做免费/套餐路由）。 - 输出 Markdown（默认）或 JSON（
--view json），可指定目录落盘（--output <DIR>，目录不存在时 CLI 会创建）。 - PDF 支持页范围（
--page-range）、加密文档（--password）、字符级细节（--include-char-details，需显式开启）。
定向阅读与导航（本地文档）¶
对本地文件推荐链路：
get_doc_info -> 完整 parse -> navigate -> extract
get_doc_info <FILE>取得doc_id。- 对同一文件执行完整
parse（不要带--page-range），以写入导航缓存。 - 使用
get_outline、search_text、read_pages定位内容。 - 批量调用
read_content抽取所需段落。
仅页范围解析不会替代完整文档的导航缓存；URL 解析无稳定本地 doc_id，应直接使用 parse 输出而非本地导航命令。
多文档 Task Runtime¶
两份及以上本地文件，或用户明确要求持久 Task ID、状态查询、选择性读取、导出与调试时，使用 Task 而非并行多个 parse：
xparse-cli task run --files '<GLOB>' --api auto
后续可用 task status、task read、task export、task debug、task continue（加密续跑）、task resume（付费或充值后继续）等子命令。--api auto 对 Task 为「免费优先、失败则关闭」，不会静默切到付费；需 --api paid 时必须事先征得用户同意。
配额与路由¶
xparse-cli quota --output json查看当日免费页数、重置时间、认证状态及套餐剩余等。--api free仅走免费端点；--api paid显式付费。免费端点支持 PDF 与图片；Office、HTML、OFD 等格式可能需要付费 API，应先说明并获批准再切换。
结构化错误与重试¶
失败时解析 stderr 中 schema_version 为 xparse_error.v1 的对象；retryable=false 时不得重试同一逻辑操作。每条 xparse-cli 命令应独立执行，不要用管道截断输出或掩盖退出码。
安装与启用¶
1. 安装 xparse-cli¶
Skill 要求 Node.js 18+，全局安装 CLI：
xparse-cli version
若未安装：
npm i -g xparse-cli
国内可使用 npmmirror：
npm i -g xparse-cli --registry=https://registry.npmmirror.com
在 TextIn xParse WorkBuddy Connector 环境中，Connector 会安装固定版本 CLI，文档任务内应使用：
xparse-cli --profile workbuddy <command> ...
勿在 Connector 托管的任务中自行覆盖该版本。
2. 通过 SkillHub 安装 Skill¶
先确认 SkillHub CLI（参见 SkillHub 安装说明）：
command -v skillhub && skillhub --version
未安装时可执行官方脚本（完整安装或 --cli-only 仅 CLI）。安装 Skill 时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 且可能不被识别。
Cursor 常用路径为 ~/.cursor/skills/：
skillhub install @user_2e25d6a2/xparse-parser --dir ~/.cursor/skills/
Claude Code 对应 ~/.claude/skills/；Codex 可为 ~/.codex/skills/ 或项目下 .agents/skills/。安装后按各客户端要求重启或刷新 Skill 列表。
SkillHub 页面亦提供给 AI 的安装提示：根据 https://skillhub.cn/install/skillhub.md 安装 @user_2e25d6a2/xparse-parser。
3. 认证（按需）¶
- WorkBuddy：依赖 Connector 的 Device OAuth 与
workbuddy配置档，断开时提示用户重连，不要索要 Secret/Token。 - 独立 CLI：支持
xparse-cli auth交互菜单、AppKey、Device OAuth、浏览器 PKCE 等；非交互可设置XPARSE_APP_ID与XPARSE_SECRET_CODE环境变量。细节见 Skill 内references/authentication.md。
Skill 商店元数据不要求预置 API Key；使用付费路由或部分配额能力时仍需按 CLI 完成认证。
典型用法¶
整份 PDF 转 Markdown 并落盘¶
长文档建议写入目录，避免终端截断：
xparse-cli parse report.pdf --api auto --output ./result/
读取生成目录中的 <basename>.md 后再做摘要或问答。
结构化 JSON（含表格、层级）¶
xparse-cli parse report.pdf --api auto --view json --output ./result/
需要坐标级字符信息时追加 --include-char-details。
指定页与加密¶
xparse-cli parse doc.pdf --api auto --page-range 1-5
xparse-cli parse doc.pdf --api auto --password secret123
本地文档内搜索再抽取¶
xparse-cli get_doc_info ./contract.pdf
xparse-cli parse ./contract.pdf --api auto --output ./result/
xparse-cli search_text <DOC_ID> "违约责任"
根据 outline 或搜索结果再调用 read_content（单任务建议控制在约八次以内，可合并独立读取）。
多文件批处理¶
xparse-cli task run --files './invoices/*.pdf' --api auto
xparse-cli task status <TASK_ID> --run-id <RUN_ID>
xparse-cli task export <TASK_ID> --run-id <RUN_ID> --output ./export/
保留返回的 operation_id、task_id、run_id；状态为 waiting_paid_authorization 或 waiting_funds 时应停止并等待用户确认，再用 task resume 继续。
查看配额¶
xparse-cli quota --output json
在用户询问剩余额度、路由失败或提议付费重试前，应先读取当前配额事实。
适用场景与注意¶
适合：
- 用户给出单文件或 URL，第一步要把内容变成 Markdown/JSON 供 Agent 使用。
- 需要在一份本地 PDF 内按关键词、目录或页码定向抽取，而非通读全文。
- 多文档批处理、需要 Task ID 与后续
status/read/export/debug的可恢复流程。 - 希望统一走 TextIn xParse 的配额与计费规则，而不是维护多套自研解析脚本。
注意：
- 免费路由主要覆盖 PDF 与图片；其他格式常需
--api paid与用户明确同意。 parse与task run选型看输入份数与是否要持久 Task，不要因为配额失败就把已接受的 Task 拆成多次parse。- 每条 CLI 命令单独执行；失败时以结构化错误对象的
next_action为准。 - SkillHub 页面统计（截至资料抓取）：评分约 100000，下载约 2799 次，安装约 11 次；以 SkillHub 技能页 实时数据为准。
结尾¶
TextIn xParse Document Parse 把文档解析、导航、批处理任务和配额路由收敛到 xparse-cli 一条命令线，让 Agent 从「读文件」起步时就有可复现的步骤与错误边界。若你的工作流经常从 PDF/Office/图片出发，值得在 SkillHub 安装该 Skill 并配好 CLI。
