技能 Skills

技能是 LoopAgent 專屬的能力：一份讓模型「讀」而不是「呼叫」的說明書（SOP）。它由一份 SKILL.md 正文，加可選的參考檔案、腳本組成。模型在需要時把正文讀進來，照著裡面的步驟辦事。

技能是什麼、怎麼被用

• 一個技能包 = 必需的 SKILL.md + 可選的文字檔案、腳本。整包不超過 20MB、單檔案不超過 5MB。
• 系統每輪只給模型一份「可用技能清單」，只有名字和簡介，不含正文。模型判斷某個技能相關後，才把它的完整 SKILL.md 正文讀進來。
• 技能包裡的檔案只能透過技能機制讀取，不在任何本地檔案系統裡（詳見下文沙箱說明）。
• 一個 LoopAgent 最多掛載 10 個技能。

三種來源

「移除」的含義按來源不同：組織 / 平台技能點「移除」= 只解綁，技能本體還在；Agent 私有技能點刪除 = 連本體一起刪。要徹底刪除組織技能本體，需去「工具 › 技能」頁操作。

草稿、Debug 與 Production

技能正文（SKILL.md）的生效過程和身分提示一樣分三態。要注意：技能編輯器只有「儲存」按鈕、沒有「發布」按鈕——發布動作在別處。

上線方式按技能來源分兩種：

• Agent 私有技能：正文隨 LoopAgent 發布。編輯器點儲存只對偵錯版生效，必須再發布這個 LoopAgent，最後儲存的版本才帶上線（與身分提示同邏輯）。
• 組織 / 平台技能：正文即時全域。點儲存後，對所有引用它的智慧體（偵錯版 + 線上）立即生效，無需發布智慧體。

最常見的坑：編輯中的草稿連偵錯聊天都讀不到。想在偵錯聊天裡驗證改動，必須先點「儲存」，否則讀到的還是上次儲存的正文。

另一個坑：Agent 私有技能只點儲存也只到偵錯版，客戶看到的仍是發布版——要上線記得回去發布 LoopAgent。

兩個補充：

• 新建即可讀：新建技能時會自動寫入最小正文（表單新建 = 名稱 + 簡介合成，帶包上傳 = 讀包裡的 SKILL.md），所以首次發布之前就能被模型讀到。
• 多人編輯衝突：多人或多分頁同時改同一個技能，儲存時可能提示「技能內容已被他人更新」，重新整理重新載入後再儲存即可。

Python 腳本與執行沙箱

技能包裡可以帶 Python 腳本（放在 scripts/ 目錄只是慣例、不強制），把需要精確計算、格式轉換、呼叫特定庫的步驟寫成程式碼，交給模型按需執行。

執行機制：

• 腳本在隔離沙箱裡執行（獨立的 Linux 環境 + Python 3.11），不在你的伺服器、也不在模型本地跑——天然隔離、互不影響。
• 模型在需要時把包內腳本丟進沙箱執行、拿回結果；技能包裡的檔案也只能經技能機制讀取，不能用 bash 去 cat / find（技能包不在本地檔案系統裡）。

編輯器裡的「執行測試」= 真實沙箱執行：

• 在技能編輯器裡對 .py 腳本點「執行測試」，是真實的後端沙箱執行，不是前端模擬；它和模型執行時用的是同一個沙箱——編輯器裡測通了，模型執行時也能跑通。
• 腳本自身報錯 ≠ 介面失敗：腳本內部拋錯時，會帶著輸出和錯誤堆疊正常返回（方便排查），並不代表執行介面掛了；只有沙箱層出問題（如該環境未部署沙箱）才是介面失敗。
• 測試時渠道 / 會話變數取不到：編輯期沒有真實對話上下文，渠道屬性（如 WhatsApp / Telegram 相關）、會話屬性會是空值，只有真實對話執行時才有值。所以測試裡這些變數為空是正常的。

bash 工具：每個 LoopAgent 都會帶一個 bash 工具，用來驅動技能文件裡描述的 API 呼叫（按 SKILL.md 的說明拼命令）；但技能包內的 Python 腳本走沙箱執行，不是 bash。

技能不生效怎麼排查

技能要被模型讀到，需要逐層過關，按順序自查：

1. 技能模組總開關是否打開；
2. 該技能的掛載條目是否啟用；
3. 技能本身是否啟用；
4. 技能正文是否非空（空正文會被丟棄，模型讀不到）；
5. 是否與另一個技能同名（技能名區分大小寫，同名只保留先掛載的那個）。

改技能掛載開關後，下一條訊息就會在可用技能清單裡出現 / 消失，不需要重新儲存智慧體。