logo
開發者文件
總覽開發空間工作空間API 參考最佳實踐更新日誌
搜尋
繁體中文
工作空間 / APP設定 / 工具管理
工具管理
最新更新：4 個月前

工具管理

概述

工具是 Agent 執行操作的「手腳」。系統提供 19 項內建工具，並支援透過 MCP 協議、OpenAPI 定義和技能擴充工具集。工具管理頁面用於設定和管理所有可用工具。

截圖位置

19 項內建工具

檔案操作類（7 項）

工具 功能 安全級別
Read File 讀取檔案內容，支援行號範圍，上限 5MB P0（自動執行）
Write File 寫入檔案，不存在則自動建立含父目錄 P0
Edit 對已有檔案進行局部修改（搜尋取代模式） P0
MultiEdit 對已有檔案進行多處批次修改 P0
List Directory 列出目錄檔案和子目錄，顯示檔案大小 P0（鎖定）
Glob Files 按萬用字元模式搜尋檔案，最多 100 條結果 P0（鎖定）
Search Files 在檔案內容中按正規表示式搜尋，最多 250 條結果 P0（鎖定）

命令執行類（1 項）

工具 功能 安全級別
Bash 執行 Shell 命令、指令碼、Git 操作，逾時 120 秒，輸出上限 50KB P1（首次確認）

網路類（1 項）

工具 功能 安全級別
Web Fetch 取得 URL 內容轉為 Markdown，自動去噪，15 分鐘快取 P1

任務管理類（1 項）

工具 功能 安全級別
Task Manage 管理結構化任務清單（待辦/進行中/已完成），3 步以上任務自動呼叫 P0（鎖定）

技能呼叫類（1 項）

工具 功能 安全級別
Skill 呼叫已安裝的 Skill 模組執行專項任務 P1

使用者互動類（1 項）

工具 功能 安全級別
AskUserQuestion Agent 向使用者發起提問（最多 4 個問題，每個 2-10 個選項） P0（鎖定）

子代理類（3 項）

工具 功能 安全級別
create_local_sub_agent 在本節點建立臨時子代理，支援 1-3 級巢狀 P0
dispatch_sub_agent 派發任務給已註冊的子代理 P0
dispatch_multi_node_agent 透過 Gateway 派發任務到遠端節點 P0

記憶類（4 項）

工具 功能 安全級別
Conversation Search 按關鍵字搜尋歷史對話，支援時間範圍過濾，最多 10 條 P0（鎖定）
Recent Chats 列出最近 1-20 條對話工作階段，支援時間篩選 P0（鎖定）
Memory Query 搜尋已儲存的使用者記憶（語意搜尋 + 圖譜擴充） P0（鎖定）
Memory Manage 新增、更新或刪除使用者記憶 P1

安全級別說明

級別 含義 行為
P0 安全操作 自動執行，無需使用者確認
P1 需要確認 首次呼叫時彈出權限確認
P2 每次確認 每次呼叫都需要使用者確認
鎖定 不可降級 安全級別固定，不可調整

管理員可在安全護欄中調整非鎖定工具的權限級別（組織下限），個人可在 APP 執行時安全中進一步收緊。

MCP 工具協議

**MCP（Model Context Protocol）**是標準化的 AI 工具通訊協議，支援透過外部服務擴充工具集。

三種傳輸方式

傳輸 說明 適用場景
stdio 本地子程序通訊（command + args） 本地 CLI 工具
SSE Server-Sent Events（HTTP 長連線） 遠端服務
HTTP Streamable HTTP API 遠端服務

五種認證模式

認證 說明
none 無認證
bearer Bearer Token
basic HTTP Basic Auth
service 服務間認證
oauth2 OAuth2 授權碼流程（自動探索 well-known 端點）

MCP 管理介面

透過 McpManager 元件管理 MCP 伺服器：

  • 新增伺服器：設定名稱、傳輸方式、連線參數、認證方式
  • 編輯/刪除：修改或移除已有設定
  • 啟用/停用：切換伺服器可用狀態
  • 工具探索：連線後自動探索伺服器提供的工具清單

安全隔離

MCP 子程序僅傳遞白名單環境變數，防止 API Key 等敏感資訊外洩。

API 工具

支援從 OpenAPI/Swagger 文件自動解析並建立工具：

功能 說明
自動解析 從 OpenAPI 規範擷取端點、參數 Schema
認證設定 五種認證模式
範本變數 {{variable}} 動態取代
HTTP 方法 GET / POST / PUT / DELETE / PATCH

自訂工具目錄 NEW

系統新增 ToolDirectoryManager —— 管理 {dataDir}/TOOLs/{orgId}/_custom/ 目錄下的自訂工具，無需重新啟動 APP即可載入。

目錄結構

{dataDir}/TOOLs/{orgId}/_custom/ ├── my-tool-1/ │ ├── metadata.json │ └── ... └── my-tool-2/ ├── metadata.json └── ...
                      
                      {dataDir}/TOOLs/{orgId}/_custom/
├── my-tool-1/
│   ├── metadata.json
│   └── ...
└── my-tool-2/
    ├── metadata.json
    └── ...
此代碼塊在浮窗中顯示

metadata.json 範例

{ "id": "my-tool-1", "name": "My Custom Tool", "description": "自定义工具说明", "type": "API", "enabled": true, "createdAt": 1776921208476, "updatedAt": 1776921208476 }
                      
                      {
  "id": "my-tool-1",
  "name": "My Custom Tool",
  "description": "自定义工具说明",
  "type": "API",
  "enabled": true,
  "createdAt": 1776921208476,
  "updatedAt": 1776921208476
}
此代碼塊在浮窗中顯示

載入機制

  • 掃描方法：scanAndLoad(orgId)
  • 類型支援：API / MCP
  • 組織隔離：按 orgId 分目錄，互不干擾
  • 熱載入：無需重新啟動 APP

工具載入管線

所有工具按以下順序載入並合併：

① 內建工具（19 項） ↓ ② MCP 工具（從設定的 MCP 伺服器探索） ↓ ③ API 工具（從 OpenAPI 定義解析） ↓ ④ 自訂工具（ToolDirectoryManager 掃描 _custom/ 目錄） ↓ ⑤ 技能工具（從啟用的 Skills 注入 execute_skill_{id}） ↓ ⑥ 合併去重 → 最終工具清單 → 傳送給 LLM
                      
                      ① 內建工具（19 項）
    ↓
② MCP 工具（從設定的 MCP 伺服器探索）
    ↓
③ API 工具（從 OpenAPI 定義解析）
    ↓
④ 自訂工具（ToolDirectoryManager 掃描 _custom/ 目錄）
    ↓
⑤ 技能工具（從啟用的 Skills 注入 execute_skill_{id}）
    ↓
⑥ 合併去重 → 最終工具清單 → 傳送給 LLM
此代碼塊在浮窗中顯示

常用工具的使用場景

使用者請求範例 Agent 呼叫的工具 說明
「幫我看一下 package.json 的內容」 Read File 讀取並返回檔案內容
「把函式名稱從 getData 改為 fetchData」 Edit 精確搜尋取代
「建立一個 README.md」 Write File 建立新檔案
「專案裡有哪些 .tsx 檔案？」 Glob Files 按模式搜尋檔案名稱
「程式碼裡哪裡用到了 useEffect？」 Search Files 在檔案內容中正規表示式搜尋
「幫我執行 npm install」 Bash 執行 Shell 命令
「幫我總結這個網頁的內容：https://...」 Web Fetch 抓取網頁轉 Markdown
「這個任務比較複雜，先列個計畫」 Task Manage 建立結構化任務清單
「幫我搜尋昨天關於資料庫遷移的對話」 Conversation Search 搜尋歷史對話
「記住我偏好用 dark 主題」 Memory Manage 儲存到記憶

操作指南：新增 MCP 工具

  1. 開啟 APP → 設定 → 工具 → MCP 工具區域
  2. 點擊 新增 MCP 伺服器
  3. 填寫設定：
    • 名稱：為這個 MCP 伺服器起一個識別名稱
    • 傳輸方式：選擇 stdio / SSE / HTTP
    • 如果是 stdio：填寫命令（如 npx）和參數（如 @anthropic/mcp-server-filesystem）
    • 如果是 SSE/HTTP：填寫伺服器 URL
  4. 如果需要認證，選擇認證方式並填寫憑證
  5. 點擊 儲存
  6. 系統自動連線伺服器並探索可用工具
  7. 探索到的工具出現在工具清單中，預設啟用

提示：MCP 子程序僅傳遞白名單環境變數。如果 MCP 工具需要 API Key 等環境變數，需要在設定的 env 欄位中明確宣告。

工具停用的影響

停用某個工具後，Agent 在對話中完全不知道該工具的存在。這意味著：

停用的工具 影響
Bash Agent 無法執行任何 Shell 命令（npm、git、編譯等）
Read File / Write File Agent 無法讀取或建立檔案
Web Fetch Agent 無法取得網頁內容，搜尋類技能也受影響
Memory Query / Manage Agent 不會查詢或儲存記憶
Skill Agent 無法呼叫任何技能模組
create_local_sub_agent Agent 無法建立子代理分解任務

建議：除非有明確的安全原因，不建議停用核心檔案操作工具（Read / Write / Edit / Glob / Search），否則 Agent 的任務執行能力會嚴重受限。

常見問題

Agent 說「我無法執行檔案操作」

檢查檔案操作類工具（Read File、Write File、Edit 等）是否被停用。在工具管理頁面確認這些工具處於啟用狀態。

MCP 工具連線失敗

  1. 確認 MCP 伺服器的命令/URL 是否正確
  2. 如果是 stdio 方式，確認對應的命令已安裝（如 npx 需要 Node.js 環境）
  3. 檢查是否需要環境變數（API Key 等）
  4. 查看 APP 日誌取得詳細錯誤資訊

Agent 沒有使用我期望的工具

Agent 基於任務需求自主選擇工具。如果 Agent 選擇了「錯誤」的工具，可以在對話中明確指示：「請使用 Bash 工具執行這個命令」。

相關文件