0024-bot-api-separate-keys.md 2.0 KB

ADR-0024 Bot API 与独立的 Bot Key

  • 状态:Accepted · 日期:2026-10-26 · 补充 ADR-0015、ADR-0019 · 设计见 13-bot-teams

背景

Bot 工作组(ADR-0023)通过 API 对外提供。它和现有的 Agent API(/v1,会话、消息)是两类能力,使用方和权限范围都不同:Agent API 的 Key 按 Profile 授权,Bot 的 Key 应当按机器人授权。两者不应该互相通用。

决策

  • 独立路径:Bot API 统一使用 /bot/v1/* 前缀,与 /v1/* 分开。
  • 独立的 Key:
    • 新表 bot_api_keys,前缀 bk_(Agent Key 是 ask_)
    • Key 按允许使用的机器人授权(allowedBotIds),不涉及 Profile
    • 后台单独设一个"Bot Keys"页面
  • 鉴权按路径前缀只认一种 Key:/v1 只接受 ask_ 和 Agent 浏览器令牌;/bot/v1 只接受 bk_ 和 Bot 浏览器令牌。拿错类型一律返回 401,不提示另一套 API 的存在。
  • 后台管理员的 Cookie 两边都接受(与现有 Playground 调用 /v1 的方式一致),来源记为 admin。Bot Playground 因此不需要单独的后端;替身组员、逐步执行等调试功能只对来源为 admin 的工作组开放。
  • 浏览器令牌:沿用 ADR-0019 的无状态 HMAC 令牌,载荷里增加 kind(agent / bot),两种令牌不能互换使用。Bot 浏览器令牌由 POST /bot/v1/browser-tokens 签发。
  • 数据隔离:
    • 工作组归属于创建它的 Bot Key
    • 机器人底层的会话来源记为 team:<id>,Agent API 永远看不到
    • Agent Key 创建的会话,Bot API 也看不到
  • CORS:沿用"设置 › 安全 › CORS 来源",同时作用于 /v1 和 /bot/v1。
  • 用量按 Bot Key 和机器人分别统计。

后果

  • 同一个业务平台如果同时使用两类能力,需要持有两个 Key,并分别签发浏览器令牌
  • 鉴权中间件需要按路径前缀分流;现有 api_keys 表和 /v1 的行为不变