开放接口文档

把 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"