Skip to content

接口与配置契约.md

Latest commit

 

History

History
147 lines (108 loc) · 15.6 KB

接口与配置契约.md

File metadata and controls

147 lines (108 loc) · 15.6 KB
Raw

BubblePilot 接口与配置契约

权威来源

本文解释接口边界，不重复抄写每个请求字段。机器可校验合同是：

文件 权威内容
contracts/openapi.yaml HTTP 路径、认证、参数、请求和响应
contracts/bluebubbles-webhook.schema.json BlueBubbles 原始 Webhook
contracts/message-envelope.schema.json 统一消息信封
contracts/workflow.schema.json 可发布工作流图

运行时路由、OpenAPI、环境变量和 Schema 由 pnpm contracts:check 交叉检查。

API 分区与认证

分区 入口示例 认证
健康检查 /health/live、/health/ready 无
Web 登录 /api/v1/auth/session、/api/v1/auth/sensitive 登录密码或当前管理会话
BlueBubbles Webhook /api/v1/webhooks/bluebubbles 查询参数 Token 或 X-BubblePilot-Webhook-Secret
消息与监听 /api/v1/chats、/api/v1/chats/{chatId}/participants、/api/v1/messages/search、/api/v1/chat-monitoring 管理会话或 Bearer；正文、成员映射和监听变更需二次验证
工作流与触发器 /api/v1/workflows、/api/v1/triggers 管理会话或 Bearer
AI Provider、路由与搜索 /api/v1/ai/providers、/api/v1/ai/routes、/api/v1/ai/search/settings 管理会话或 Bearer
执行与运行状态 /api/v1/executions、/api/v1/operations/status 管理会话或 Bearer；人工恢复需二次验证
审计与导出 /api/v1/audit-events、/api/v1/exports 管理会话或 Bearer；敏感读取、确认和下载需二次验证
BlueBubbles 设置 /api/v1/integrations/bluebubbles 查询需登录，修改和测试需二次验证

浏览器使用服务端管理会话。Cookie 为 HttpOnly、SameSite=Strict，SESSION_COOKIE_SECURE=auto 时按 HTTPS/反向代理协议决定 Secure；数据库只保存随机会话 Token 的 SHA-256。二次授权绑定当前会话并短时有效，前端到期收起内容不能替代服务端逐请求校验。

API_ACCESS_TOKEN 是兼容受控自动化的高熵 Bearer Token，视为已经具备实例管理权限，应像管理员凭据一样保护。新用户操作优先使用 Web 会话，不把 Bearer Token 暴露给浏览器脚本或不可信客户端。

分页列表使用不透明 cursor 和 limit，limit 为 1-100。错误响应包含稳定 code、可读 message 和 UUID correlationId。调用方不得解析错误文案决定重试。

管理 API 与 Webhook 分别限流，超过上限返回 429 RATE_LIMITED。执行容量不足返回 503 WORKFLOW_QUEUE_FULL 或 503 WORKFLOW_QUEUE_WAIT_TIMEOUT；只能退避重试，不能通过并发重放绕过上限。

Webhook 合同

  • URL：/api/v1/webhooks/bluebubbles?token=<secret>；Secret 至少 32 字符并使用常量时间比较。
  • 当前处理 new-message；其他合法事件以 ignored 进入幂等事件表。
  • 稳定事件键为 new-message:<message-guid>。
  • 成功返回 202，接入状态为 archived、ignored 或 duplicate。
  • automationOutcome 区分 unsupported-event、chat-not-monitored、evaluation-pending、not-evaluated、no-active-triggers、no-trigger-match 和 matched。
  • 只有 evaluation-pending 允许同键重投继续调度；其他最终判定不按当前配置补跑。
  • 未监听聊天只保存发现所需元数据，不保存正文。
  • 入站事件查询不返回消息正文、原始 Webhook、Payload 哈希、Prompt 或凭据。

详细字段映射和供应商行为见 BlueBubbles 集成说明。

对话成员身份合同

GET /api/v1/chats/{chatId}/participants 聚合该聊天历史中实际出现的非本人 sender ID，返回消息数量、最后出现时间、本名、昵称和独立映射版本。PUT 使用 expectedVersion 全量替换映射；最多 100 项，同一 sender ID 不能重复，本名或昵称至少填写一项，空数组用于清除全部映射。提交不在该聊天历史中的 ID 返回 CHAT_PARTICIPANT_NOT_DISCOVERED，版本过期返回 CHAT_PARTICIPANT_IDENTITIES_CONFLICT。

两个接口都需要二次验证并写入 chat.participants.view 或 chat.participants.update 审计。审计只保存动作、聊天 ID、结果和 HTTP 状态，不保存本名、昵称或请求正文。映射按聊天隔离；运行时只能按本次加载历史和当前消息中的 sender ID 定向解析，不能读取整张成员表注入 AI。

工作流与 AI 合同

已发布工作流版本不可原地修改。编辑会创建新的已校验候选版本；发布和切换在事务中完成，已开始执行继续引用原版本。生产触发器拒绝 isFromMe，冲突提示只表示潜在重叠，不阻止启用。

动作目录只返回可以创建且具备运行时实现的节点。render-text@1 使用白名单 Context Token 渲染字符串并提供 text 输出；load-context@1 提供 messages、count 和经过当前窗口过滤的 participants 输出；未知路径、未知动作输出和不完整模板语法在候选版本校验时拒绝。set-variable@1 只保留历史版本运行兼容，不再由动作目录返回。

AI Provider 支持 Chat Completions 或 Responses 接口类型、Base URL、模型、参数、超时、启停、排序和只写 secret。Secret 使用 SETTINGS_ENCRYPTION_KEY 加密；编辑时省略 Secret 表示保留原值，任何读接口都不回显。

连通性测试分别返回基础连接、Function Calling 和托管搜索探测，互不覆盖。测试使用固定虚构输入，不读取归档消息、不触发生产 Fallback，也不计入生产降级。

GET/PUT /api/v1/ai/search/settings 读取和更新实例级联网搜索参数。参数包括 HTTP 尝试次数、单次请求超时、重试退避、最大结果数和失败策略；PUT 必须携带 expectedVersion 防止旧页面覆盖新配置。未保存时 GET 返回系统默认值和 version=0，首次保存后以数据库配置为准，并对新的 Agent 执行立即生效。工作流节点不保存这些参数，也不存在独立的工具总时间预算。

路由响应同时区分：

  • configuredProviderIds：管理员保存的固定顺序；
  • effectiveProviderIds：当前运行时可选择的候选；
  • unavailableProviderIds：停用、缺少 Secret 或仍在冷却的候选。

执行详情返回脱敏节点、Provider Attempt、工具调用和出站轨迹。它可以包含实际搜索词、规范化有限结果、请求 ID、HTTP 状态、哈希、大小和 Token 计数，但不得包含完整 Prompt、聊天正文、AI 输出、Secret 或原始外部响应。

完整执行语义见事件与工作流设计。

受控导出

导出使用“冻结预览 → 二次验证 → 显式确认 → 短时下载”：

  1. 单个任务只允许一个当前监听聊天、明确时间范围，以及消息或执行摘要中的至少一种。
  2. 时间最长 31 天，最多 10,000 条，预计不超过 25 MB；预览 5 分钟有效。
  3. 确认必须回传预览的 expectedRecordCount 和 expectedSnapshotAt。
  4. 确认后下载窗口 10 分钟；服务端按冻结快照流式生成 JSON Lines，不写临时正文文件。
  5. 任务按当前管理会话或 Bearer 所有者隔离，下载时再次检查监听状态和有效期。

第一行为 manifest，之后为 message 或 execution。导出不包含 AI Key、Secret、secretRef、完整 Prompt、节点输入输出、原始 Webhook 或内部错误详情。预览、确认、下载和取消分别审计。

消息中的 contentRedactedAt 区分“原本没有正文”和“已按保留策略清理”；清理后 body=null、attachments=[]，必要元数据与执行关联仍可查询。

必填运行时配置

名称 必填 敏感性 说明
DATABASE_URL 是 Secret PostgreSQL 连接串
API_ACCESS_TOKEN 是 Secret 至少 32 字符的受控自动化 Bearer Token
APP_LOGIN_PASSWORD_HASH 是 Secret Web 登录密码的 BubblePilot scrypt 哈希
SENSITIVE_OPERATION_PASSWORD_HASH 是 Secret 不同于登录密码的敏感操作哈希
BLUEBUBBLES_WEBHOOK_SECRET 是 Secret 至少 32 字符的首次启动/Webhook 回退密钥
BLUEBUBBLES_SERVER_URL 是 敏感 BlueBubbles 根 URL，数据库未配置时使用
BLUEBUBBLES_ACCESS_TOKEN 是 Secret BlueBubbles REST API Password，数据库未配置时使用

正式部署还应显式设置 SETTINGS_ENCRYPTION_KEY。代码为兼容旧实例允许回退到 API_ACCESS_TOKEN，但新的正式实例不应依赖该回退。

可选运行时配置

名称 必填 默认值 范围或说明
NODE_ENV 否 development development、test、production；Compose 强制应用为 production
APP_HOST 否 0.0.0.0 HTTP 监听地址
APP_PORT 否 8080 1-65535
SETTINGS_ENCRYPTION_KEY 否 API_ACCESS_TOKEN 加密数据库运行时凭据；必须在重启和升级间保持稳定
SESSION_COOKIE_SECURE 否 auto auto、true、false
ADMIN_SESSION_TTL_SECONDS 否 43200 900-604800 秒
SENSITIVE_OPERATION_TTL_SECONDS 否 300 60-3600 秒
BLUEBUBBLES_SEND_METHOD 否 private-api private-api 或 apple-script
BLUEBUBBLES_REQUEST_TIMEOUT_MS 否 30000 1000-120000 毫秒
DATABASE_QUERY_TIMEOUT_MS 否 30000 1000-120000 毫秒；单条 PostgreSQL 查询及连接获取超时
MONITORED_CHAT_IDS 否 空 尚未发现聊天的初始监听 GUID，逗号分隔
MESSAGE_RETENTION_DAYS 否 90 0-36500；0 明确关闭内容自动清理
ENABLE_WEB_SEARCH 否 false 实例级搜索总开关
SEARXNG_BASE_URL 否 http://searxng:8080 AgentRunner 的 SearXNG 根 URL
SEARXNG_ENGINES 否 空 可选引擎白名单，逗号分隔
SEARXNG_LANGUAGE 否 zh-CN 搜索语言参数
WEBHOOK_BODY_LIMIT_BYTES 否 1048576 1024-10485760 字节
RATE_LIMIT_WINDOW_SECONDS 否 60 1-3600 秒
ADMIN_RATE_LIMIT_MAX 否 600 每个客户端指纹每窗口 10-100000 次
WEBHOOK_RATE_LIMIT_MAX 否 300 每个客户端指纹每窗口 10-100000 次
WORKFLOW_MAX_CONCURRENCY 否 4 当前进程 1-256 条并发执行
WORKFLOW_QUEUE_CAPACITY 否 64 0-10000 条等待执行
WORKFLOW_QUEUE_WAIT_MS 否 30000 100-300000 毫秒
STALE_RETRY_SECONDS 否 300 30-86400 秒；逾期 Retry 可人工接管
LOG_LEVEL 否 info Pino 日志级别

Compose 配置

名称 必填 默认值 说明
BUBBLEPILOT_IMAGE 否 ghcr.io/shigella520/bubblepilot:dev 本地构建时作为镜像名；正式环境固定 X.Y.Z
POSTGRES_DB 否 bubblepilot PostgreSQL 数据库名
POSTGRES_USER 否 bubblepilot PostgreSQL 用户
POSTGRES_PASSWORD 是 无 必须与 DATABASE_URL 对应
SEARXNG_SECRET 是 无 只由 SearXNG 容器消费，至少 32 字符

密码哈希包含 $，写入 .env 时必须使用单引号。所有 Secret 都必须在日志、诊断和错误响应中脱敏。新增、重命名或废弃环境变量时，需要在同一个变更中更新本表、.env.example、compose.yaml、配置 Schema 和回归测试。