AI 代理程式操作指南¶

本節專為 AI 代理程式設計師 和 Bot 整合工程師 撰寫，說明如何讓 AI 代理程式安全、正確地使用 NextPDF 的 MCP 工具集。

設計哲學¶

NextPDF MCP 工具集遵循以下設計哲學，AI 代理程式的使用方式也應對齊：

1. 宣告意圖，不假設後果¶

AI 代理程式在呼叫任何 MCP 工具前，應向使用者明確宣告即將執行的操作及其預期後果，特別是 medium 和 high 風險操作。

✓ "我將把 report.pdf 中的所有影像壓縮至 85% JPEG 品質，這會稍微降低影像清晰度。"
✗ 直接呼叫 compress_images 而不告知使用者

2. 最小操作原則¶

AI 代理程式應只執行完成任務所需的最小操作集，不主動擴大操作範圍。

使用者：「幫我提取這份合約的文字」
✓ 只呼叫 extract_text
✗ 呼叫 extract_text + parse_pdf + extract_metadata（超出需求）

3. 不可逆操作的 HITL 閘門¶

風險等級為 high 的操作必須設置人工確認閘門。AI 代理程式不得自主決定執行這些操作：

操作	HITL 要求
`protect_pdf`	確認密碼已備份
`sign_pdf`	確認法律效力與簽章身份
`redact_pdf`	展示預覽並確認塗黑範圍
`generate_invoice`	確認發票金額與收受方
`apply_policy`	確認政策影響範圍
`hsm_sign`	確認企業簽章授權

4. 失敗應安全¶

當 MCP 工具返回錯誤時，AI 代理程式應： 1. 向使用者解釋錯誤的原因（以人類可讀的語言） 2. 提供可操作的解決建議 3. 不自動重試（特別是 high 風險操作） 4. 不嘗試繞過安全限制

操作指南章節¶

章節	內容	適合對象
機器可讀安裝指令	結構化的 Composer 安裝步驟	AI 助理需要設定環境時
常見任務 Prompt 範本	任務導向的操作模式範例	設計 Bot 任務流程
安全最佳實踐	HITL 設計、錯誤處理、安全邊界	所有 Bot 設計師
Moltbot 整合	Moltbot 專屬 System Prompt 與 Skills	Moltbot 整合工程師

快速決策樹¶

使用者請求涉及 PDF 操作？
├── 是 → 確認操作類型
│   ├── 唯讀分析（parse/extract/compare）→ 直接執行，告知結果
│   ├── 可逆修改（compress/watermark/merge）→ 告知操作內容，確認後執行
│   └── 不可逆/法律效力（sign/redact/protect）→ 展示詳細說明 → HITL 確認 → 執行
└── 否 → 使用其他工具

工具選擇指引¶

使用者想「了解」PDF¶

→ 使用 parse_pdf（獲取結構概覽） → 使用 extract_text（獲取文字內容） → 使用 extract_metadata（獲取文件屬性）

使用者想「修改」PDF¶

→ 評估風險等級 → low 到 medium：告知後執行 → high：明確 HITL 確認

使用者想「分析比較」PDF¶

→ 使用 compare_pdfs（Pro） → 使用 forensic_analyze（Enterprise，鑑識需求）

使用者想「建立 RAG 知識庫」¶

→ 使用 embed_documents（Enterprise）建立索引 → 使用 semantic_search（Enterprise）執行查詢

通用錯誤處理範本¶

當 MCP 工具返回錯誤時，AI 代理程式應使用以下溝通模式：

錯誤：file_not_found
回應範本：「我無法找到您指定的 PDF 文件（路徑：{path}）。
請確認：
1. 檔案路徑是否正確（區分大小寫）
2. 檔案是否在允許的工作目錄（{workspace}）內
3. 您是否有此文件的讀取權限」

錯誤：license_required
回應範本：「您請求的功能（{tool_name}）需要 NextPDF {tier} 授權。
Core 工具（免費）可以執行基本操作。如需解鎖 {tier} 功能，請聯絡 NextPDF 銷售團隊。」

錯誤：malicious_content
回應範本：「安全掃描發現此 PDF 包含可能有害的內容（{content_type}）。
為保護您的系統安全，此文件已被拒絕處理。請確認此文件的來源可信度。」

參見¶

MCP 工具目錄 — 所有工具的完整清單
MCP 安裝指南 — 伺服器設定
安全最佳實踐 — HITL 設計模式詳細說明