把模型、智能体与工作成果
接入你的应用

选择接入方式

工作流可按依赖顺序运行多个智能体任务，Skills 可同步到全局或指定会话。模型与智能体的可用范围以当前部署返回的清单为准。

地址与鉴权

部署后的 API 前缀为 https://YOUR_SITE/api；本地后端默认使用 http://localhost:3001/api。将示例中的 YOUR_SITE 替换为你的站点域名。

1. 登录控制台，在 API Key 管理中创建专用密钥。
2. 在服务端环境变量中保存密钥，通过以下任一种请求头传入。

Authorization: Bearer YOUR_API_KEY
# 或
X-API-Key: YOUR_API_KEY

密钥关联当前账号的会话、任务与用量。不要将密钥写入公开前端代码。缺少、无效或已撤销的密钥返回 401；未创建密钥不会关闭鉴权。

首次调用：模型补全

先请求 GET /api/models，从响应 data 数组中选择模型的 name，作为补全请求的 model。模型清单无需鉴权；展示名称 displayName 不能代替模型代码。

curl "https://YOUR_SITE/api/models"

# 将 YOUR_API_KEY 和 MODEL_NAME 替换为实际值（POSIX shell 示例）
curl "https://YOUR_SITE/api/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_NAME","messages":[{"role":"user","content":"用三句话介绍这个项目"}],"stream":false}'

请求字段

响应结构示意

{
  "success": true,
  "data": {
    "id": "chatcmpl-...",
    "object": "chat.completion",
    "model": "MODEL_NAME",
    "provider": "PROVIDER",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "模型生成的回复"
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 20,
      "completion_tokens": 40,
      "total_tokens": 60
    },
    "cost": 0.001
  }
}

读取 data.choices[0].message.content 获取正文，data.usage 获取本次 token 用量。该接口由调用方提供 messages 上下文，不会自动创建网站会话。

带历史的对话与会话

适合需要网站会话记录与知识上下文的应用。首次调用不传 session_id 会自动创建会话；后续传回同一个 ID 继续对话。回复位于 data.responses，会话 ID 位于 data.session_id。

curl "https://YOUR_SITE/api/chat/proxy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"根据已积累的知识整理一份项目摘要","knowledge_base":true}'

with_history: false 仅关闭本次历史上下文加载，消息仍会保存到会话。数据归属由 API Key 所属账号决定，不使用自定义 user_id 建立独立用户或共享 QQ 记忆。

会话管理端点

以下端点支持 API Key 或 JWT。普通对话消息通过会话详情读取；智能体任务记录和产物通过 Bridge 的 session_read、task_events、artifacts_list 读取。

创建会话请求为 { "title": "项目调研", "model": "MODEL_NAME" }，model 可省略；修改标题传 { "title": "新的标题" }。所有路径中的 ID 均须属于当前账号。

智能体任务：从执行到交付

通过 REST 调用 Bridge 工具，请求体直接传工具参数，响应为 { success: true, data: ... }。也可通过 MCP 调用同一组工具。支持 API Key、JWT 或有效的配对凭据。

1. agents_list：发现智能体及真实运行时可用状态，选取可用的 agentId。
2. session_create：创建会话；传入稳定的 sessionId 与 title。
3. session_send：发送任务，立即取得 taskId。
4. task_events：增量读取进度；同时通过 task_read 判断任务状态。
5. artifacts_list / artifact_read：读取产物列表与内容。

# 1. 发现可用智能体
curl "https://YOUR_SITE/api/bridge/tools/agents_list" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

# 2. 创建会话（同一次创建重试时保持 sessionId 和 title 不变）
curl "https://YOUR_SITE/api/bridge/tools/session_create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"demo-project-001","title":"项目调研"}'

# 3. 将 AGENT_ID 替换为第一步返回的可用智能体 ID
curl "https://YOUR_SITE/api/bridge/tools/session_send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"demo-project-001","agentId":"AGENT_ID","message":"整理项目调研报告并生成文件","requestId":"demo-request-001"}'

将返回的 data.taskId 用于后续请求。task_events 的 data.nextCursor 作为下一次 after；当 hasMore 为 true 时继续读取，直到读完当前事件。任务结束后再读取产物，不能把“提交成功”当作“执行完成”。

curl "https://YOUR_SITE/api/bridge/tools/task_events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"taskId":"TASK_ID","after":0,"limit":100}'

# 完成后，将工具名换为 artifacts_list，请求体为 {"taskId":"TASK_ID"}
# 读取文件：artifact_read，请求体为 {"taskId":"TASK_ID","artifactId":"ARTIFACT_ID"}

工作流与 Skills

完整参数可通过 MCP 的 tools/list 查询；工作流接入说明见 MCP 资源 shuliu://skills/workflow。

MCP 与本地双向连接

MCP 入口为 https://YOUR_SITE/api/mcp，使用无状态 Streamable HTTP，通过请求头携带凭据。GET / DELETE 返回 405 属于当前传输实现的预期行为；它不是旧式 SSE 连接地址。

推荐前往 智能体连接，按客户端下载连接程序、完成配对并生成配置。也可以在支持 HTTP MCP 的客户端中使用以下配置格式；具体字段以客户端支持的格式为准。

{
  "mcpServers": {
    "shuliu": {
      "type": "http",
      "url": "https://YOUR_SITE/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

local_dispatch 使用设备返回的 deviceId、profile，并传 prompt、requestId；返回的 data.id 作为 local_read 的 jobId。读取时保存 data.nextCursor，可设置 waitMs: 25000 并传 knownStatus 等待变化。

连接器仅发起出站请求，本地无需开放端口。本地任务还需通过设备访问权限检查；等待授权时请在网站处理。MCP 连通不代表已登录本地模型，也不会自动接管现有桌面聊天。配对凭据有效期为 24 小时，过期后需重新配对。调用 bridge_status 可检查连接能力，无需启动模型。

响应、用量与排错

普通 REST 接口通常返回 { success: true, data: ... }。MCP 使用协议规定的工具结果格式，不套用 REST 的读取方式。代理对话额外返回 _rateLimit，其中 limit / remaining 是 credits 额度，不是每分钟请求次数。

实际可用模型、额度和并行工作数取决于当前部署与账号。请查看 用量页面；不要写死模型名单或套餐额度。智能体执行与工作流运行可能产生模型用量。

客户端应接受成功的 2xx 状态，而非只判断 200。失败时结合响应中的错误信息处理；对可能产生任务或用量的操作，先查询状态再决定是否重试。

接口范围与迁移

此页面向外部应用接入。网页使用的 /api/chat/ask-stream 与 /api/chat/upload 需要 JWT，不能直接用 API Key 替代。需要流式智能体进度时，使用 Bridge 的任务事件接口。

旧版独立 Bot 的 /api/v1/chat、memory、person、decision 及 bot_config.toml 配置不属于当前平台公开接入方式。请迁移至本页的模型、会话与 Bridge 接口。

Swagger 接口索引只在本地开发环境开放（http://localhost:3001/api/docs），生产环境不对外提供，以本页说明为准。Bridge 工具的完整参数以 MCP tools/list 为准。健康检查为后端 GET /health，不带 /api 前缀。