跳至主要內容

接口參考

技能

上載與管理技能包。

技能的寫法、打包與在訊息中選用，見技能。

POST/v1/skills

上載技能

權限
skills:write
限流
60 次/分鐘
成功
201

請求體為 multipart/form-data，技能包放在 file 欄位中，最大 50 MiB。技能包可以是：

  • 技能目錄打成的 .zip（或改了副檔名的 .skill）：SKILL.md 在壓縮包根目錄，或在唯一的頂層目錄裡（例如從 GitHub 下載的壓縮包）；
  • 單獨一個 SKILL.md。

技能的名字和描述取自 SKILL.md 的 frontmatter，寫法見 SKILL.md 的寫法。技能上載後內容不會變。要更新，請先刪除舊的，再上載新的；新上載的技能有新的 ID。

表單欄位

filefile必填
技能包：.zip、.skill 或單獨的 SKILL.md。

回應：技能物件

idstring
技能 ID，skill_…。
namestring
來自 frontmatter 的 name，項目內唯一。
descriptionstring
來自 frontmatter 的 description。
size_bytesinteger
平台整理後存儲的壓縮包大小。
created_atstring
建立時間。

錯誤

狀態碼type原因
422invalid_skill_bundle不是可用的技能包：格式不對、找不到 SKILL.md、frontmatter 缺少或寫錯 name、SKILL.md 超過 32 KiB、壓縮包含有不安全的路徑等。message 說明具體原因。
413skill_bundle_too_large技能包超過 50 MiB，或解壓後過大（單個檔案超過 25 MiB、總計超過 200 MiB、壓縮包條目含目錄超過 500 個）。
409skill_name_taken項目中已有同名技能。
請求
curl -s "$AXON_API/skills" -H "Authorization: Bearer $AXON_KEY" -F "file=@pdf-tools.zip"
回應
{
  "id": "skill_4e9a1c7b2d5f4a6e8c0b3d7f9a2e4c6b",
  "name": "pdf-tools",
  "description": "填寫和合併 PDF 表單。用戶需要處理 PDF 時使用。",
  "size_bytes": 18342,
  "created_at": "2026-10-09T03:20:11.512930Z"
}
GET/v1/skills

技能列表

權限
skills:read
成功
200

按建立時間從新到舊返回項目中的技能，分頁方式見分頁。每個元素是技能物件。

查詢參數

limitinteger
每頁條數，1–100，預設 20。
cursorstring
上一頁的 meta.next_cursor。
請求
curl -s "$AXON_API/skills" -H "Authorization: Bearer $AXON_KEY"
回應
{
  "items": [
    {
      "id": "skill_4e9a1c7b2d5f4a6e8c0b3d7f9a2e4c6b",
      "name": "pdf-tools",
      "description": "填寫和合併 PDF 表單。用戶需要處理 PDF 時使用。",
      "size_bytes": 18342,
      "created_at": "2026-10-09T03:20:11.512930Z"
    }
  ],
  "meta": {"next_cursor": null}
}
GET/v1/skills/{skill_id}

查詢技能

權限
skills:read
成功
200

返回技能物件。

路徑參數

skill_idstring必填
技能 ID。

錯誤

狀態碼type原因
404skill_not_found技能不存在、已刪除或屬於其他項目。
請求
curl -s "$AXON_API/skills/$SKILL" -H "Authorization: Bearer $AXON_KEY"
回應
{
  "id": "skill_4e9a1c7b2d5f4a6e8c0b3d7f9a2e4c6b",
  "name": "pdf-tools",
  "description": "填寫和合併 PDF 表單。用戶需要處理 PDF 時使用。",
  "size_bytes": 18342,
  "created_at": "2026-10-09T03:20:11.512930Z"
}
DELETE/v1/skills/{skill_id}

刪除技能

權限
skills:write
限流
60 次/分鐘
成功
204（無回應體）

刪除後，之後的訊息不能再選用它，名字可以給新上載的技能使用。已經發出的事件中的 skills 保持不變。請在沒有輪次在用它時刪除：正在執行、已選用了它的那一輪如果此時才調用 use_skill，會得到「無法載入」的錯誤。

路徑參數

skill_idstring必填
技能 ID。

錯誤

狀態碼type原因
404skill_not_found技能不存在、已刪除或屬於其他項目。
請求
curl -s -X DELETE "$AXON_API/skills/$SKILL" -H "Authorization: Bearer $AXON_KEY"
回應
204 No Content