前言¶
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。
