KB 工具安裝指南¶

「工具」頁的「安裝新工具」分頁,體驗類似 Claude Code 幫你建一個 skill:貼上一個 API 的 OpenAPI JSON 文件網址 + 一段指示,AI 自己讀文件、寫程式、測試、裝進工具目錄。裝好之後,「快速捕捉」「AI 補齊」「AI 進度更新」都能呼叫這個新工具。

想了解 AI 呼叫工具背後完整的運作機制(生命週期、安全邊界、為什麼不用 LangChain),見 AI 工具呼叫是怎麼運作的。

操作步驟¶

1. OpenAPI JSON 網址:填目標 API 的 OpenAPI/Swagger JSON 文件網址(必須是 http:// 或 https://,且可公開下載)。文件上限 2MB,抓取總時間上限 60 秒,超過會直接判定失敗(不會截斷後硬塞給 AI)。
2. 給 AI 的指示:描述要建立什麼工具——要查什麼資料、要用 OpenAPI 文件裡的哪個 endpoint、認證方式,以及該 API 自己的 key/token(如果需要)。例如:「建立一個用關鍵字搜尋內部知識庫的工具,使用 /search 端點;認證用標頭 X-Api-Key。」
3. 送出:後端立刻回一個安裝工作,開始背景建置(通常需要數分鐘:AI 要寫檔、用 run_shell 實際呼叫該 API 測試、視結果修正,反覆幾輪直到可用或放棄)。頁面每 2 秒輪詢一次進度,同一時間只能有一個安裝在跑——已有安裝進行中時再次送出,會顯示「已有安裝正在進行中,請等待其完成」。
4. 結果:「安裝完成」或「安裝失敗」。一旦 AI 建置階段真的開始,結果就會附上一個「查看 AI 日誌」連結,跳到 AI 日誌頁並展開這次建置工作的互動紀錄——這是除錯的主要入口:AI 判定「尚未完成」的原因、run_shell 測試時的錯誤輸出都在裡面。若是更早期就失敗(連 OpenAPI 文件都下載不到、或建不出暫存目錄),則連 AI 建置都還沒開始,連結只會帶你到一般的 AI 日誌頁。

instructions 撰寫要領¶

• 講清楚目的(要查什麼、給哪個工作流程用),AI 會自己從 OpenAPI 文件裡挑合適的 endpoint,不需要你先讀文件、指定確切的 schema。
• 認證方式要講清楚:標頭名稱、query 參數、或 bearer token。
• 想要工具回什麼樣的結果(精簡文字?結構化 JSON?)可以順帶說一句,AI 會據此決定怎麼整理 API 回應。
• 一次只描述一個工具的需求;需要多個能力就分次安裝(同一時間本來就只能跑一個安裝工作)。

金鑰怎麼處理:秘密欄位¶

安裝表單有一個選填的秘密欄位(一個名稱 + 一個值),專門用來放目標 API 自己的 key/token。用這個欄位,而不是把 key 直接寫進指示文字裡:

• 值會被注入 run_shell 子行程的環境變數(用你指定的名字),讓 AI 能用真正的 key 實測 API 呼不呼得通。
• 安裝驗證通過、確定要搬進正式工具目錄時,後端直接把這個值寫進這個工具自己的 .env(不是後端的 .env)。
• 值本身不會出現在任何送給 AI 的提示文字裡,AI 只看得到「有一個叫這個名字的秘密可以用」;系統提示也要求它不准印出來、不准寫進檔案。但要誠實講清楚邊界:這個值確實存在於 run_shell 的環境變數裡,而 run_shell 是 AI 能下指令的地方——它若刻意把值分段、編碼後輸出再重組,遮蔽未必攔得住。系統提示的禁令是行為指示,不是強制邊界,所以最終仍回到同一個信任模型:只安裝你信任的來源與指示(詳見 AI 工具呼叫是怎麼運作的)。

.staging 殘留清理¶

建置過程中,AI 是在一個以 . 開頭的暫存目錄裡寫檔測試,成功後才整個搬進正式的工具目錄。清理是 best-effort(清理時的例外都被吞掉):正常結束時通常會清掉暫存目錄,但如果後端在建置途中被中斷(當掉、被強制關閉、主機重開機),或清理本身失敗(例如 run_shell 改動了目錄權限),暫存目錄就可能殘留。這個目錄不會被列成「無效工具」,也不影響任何功能,只是佔一點磁碟空間,可以直接手動刪除。

風險與信任¶

• 沒有容器隔離:AI 用來建置工具的 run_shell 是「以本服務自己的權限」執行的真實 bash,只是預設從暫存目錄開始(工作慣例,不是圍籬)——它能讀寫這個服務的使用者帳號能碰到的任何東西。真正被強制圍住的只有檔案類操作(寫檔／讀檔／列目錄):這三個的路徑一定會被限制在暫存目錄之內。
• 因此:只安裝你信任的 OpenAPI 文件來源與指示內容,就像你只會執行信任的安裝腳本一樣——這是本機單人工具的設計取捨(比照 Claude Code 建 skill 的能力/風險模型),不是尚未做完的安全機制。