開放接口文檔

把 TjAgentForge 接入你自己的系統與 AI 客戶端：REST 開放 API（只讀 + 受控寫）與 MCP Server。兩者共用同一套密鑰、同一條執行路徑與同一份審計。

1. 認證

在控制台「API 密鑰」頁創建密鑰，請求時放進 Authorization 頭。密鑰只存指紋（不可逆），明文僅在創建時顯示一次；吊銷立即生效。

Authorization: Bearer tjaf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

作用域：read（只讀）/ write（受控寫）/ admin（管理本租戶密鑰）；allow_high_risk 是獨立開關，不對應 scope。

2. REST 調用

只讀接口（需 read 作用域）：

curl -s https://tjagentforge.com/api/open/v1/projects \
  -H "Authorization: Bearer $TJAF_KEY"

寫接口（需 write 作用域）：

curl -s -X POST "https://tjagentforge.com/api/open/v1/tunings/$TUNING_ID/apply" \
  -H "Authorization: Bearer $TJAF_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

所有響應統一為 {code, message, data} 信封，code=0 表示成功。

3. 受控寫：對外開放不提升自動化等級

預設檔位下寫操作不會立即執行，而是返回 needs_confirmation 與 confirm_url；密鑰創建者在控制台確認後才真正執行。僅當租戶檔位為 full_auto 時才直接執行；不可回滾的高危動作對外一律拒絕。

{
  "code": 0,
  "message": "ok",
  "data": {
    "status": "needs_confirmation",
    "action_id": "…",
    "confirm_url": "https://tjagentforge.com/dashboard/chat?s=…",
    "expires_at": "2026-01-01T00:15:00Z"
  }
}

4. MCP 接入

MCP 為 Streamable HTTP 單端點、JSON-RPC 2.0，任何支援 MCP 的客戶端都可接入（與 REST 同一套 API Key 鑒權）。

握手與工具列表：

curl -s https://tjagentforge.com/api/open/mcp \
  -H "Authorization: Bearer $TJAF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

# 列出可用工具（按密钥作用域过滤）
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

調用工具（寫工具同樣返回「待確認」）：

curl -s https://tjagentforge.com/api/open/mcp \
  -H "Authorization: Bearer $TJAF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"project.list","arguments":{}}}'

5. 錯誤碼

• 40103 —— 密鑰無效或已吊銷
• 40302 —— 作用域不足
• 40303 —— 需 allow_high_risk；或該高危動作不可回滾，對外拒絕
• 42901 —— 限流或任務額度用盡（看 message 區分）

6. 機器可讀契約

OpenAPI 描述可直接導入 Postman / 客戶端生成器（需帶一個有效密鑰）：

curl -s https://tjagentforge.com/api/open/v1/openapi.json \
  -H "Authorization: Bearer $TJAF_KEY"