# ADR-0024 Bot API 与独立的 Bot Key

- 状态：Accepted · 日期：2026-10-26 · 补充 ADR-0015、ADR-0019 · 设计见 [13-bot-teams](../design/13-bot-teams.md)

## 背景
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` 的行为不变