API 與 MCP

API 金鑰

給程式與 AI 代理用的長效權杖，跟使用者帳號分開——機器沒辦法做一次性密碼， 也不該借用某個人的密碼。

格式是 walis_<前綴>_<祕密>；資料庫只存 PBKDF2 雜湊，明文只在建立時回傳一次。 金鑰帶有角色（admin、operator、viewer），而且不能建立其他金鑰—— 一把外洩的金鑰不該自我繁殖。

curl -H "Authorization: Bearer walis_..." http://127.0.0.1:11120/api/jobs

MCP

API 本身在 /mcp 提供 MCP，代理只要一個網址加一把金鑰，本機什麼都不用裝：

# Claude Code
claude mcp add --transport http walis http://127.0.0.1:11120/mcp \
  --header "Authorization: Bearer walis_..."

# Codex CLI——權杖讀環境變數，不落在設定檔裡
codex mcp add walis --url http://127.0.0.1:11120/mcp --bearer-token-env-var WALIS_API_KEY

工具有：list_jobs、get_job、trigger_build、wait_for_build、get_build、 get_build_log、list_builds。任務可以直接用名稱指定，不必先查識別碼。

設定、帳號與金鑰管理刻意不開放。那些操作不可逆或牽涉憑證，應該由人在管理介面上做； 金鑰即使外流，能造成的損害也侷限在「觸發建置與讀取紀錄」。

/mcp 跟 /api 走同一套認證——它能觸發建置，不會因為不在 /api 底下就被放行。

指標

GET /metrics 輸出 Prometheus 格式：任務數、佇列深度、各狀態的建置數、平均耗時與排隊時間、 各狀態的執行器數。它放在 /api 之外且不需要金鑰——同一台機器上的抓取端不該為此發金鑰， 而且內容只有彙總數字。

設定可攜

GET /api/portability/export 匯出所有任務與自訂動作，不帶識別碼、統計與時間戳—— 那些描述的是這台機器，不是定義本身。匯入以名稱比對：同名的預設略過， 選擇覆寫時是就地更新，所以建置紀錄不會斷。