serve

用途

serve 是 bro CLI 的策略技能，用于解决瘦客户端（TUI、WebUI、IDE）访问 bro 后端的问题。通过 bro fleet serve 将 agents facade（代理外观层）、fleet 与快照等数据面以 HTTP/JSON 形式托管在 127.0.0.1 上，客户端无需自行调用 bd/gh 等命令。回环绑定即信任边界：仅 127.0.0.1，无 --host 参数，v1 不暴露远程访问。

主要能力

命令

bro fleet serve [--port N]：前台服务器；默认端口为随机端口。绑定 URL 打印并写入 <git-common-dir>/bro/serve.json（权限 0600），客户端据此发现端点与会话令牌。

路由

• GET /：服务索引 {service, routes}
• GET /fleet：fleet WebUI，一个 HTML 仪表盘，轮询下列只读数据面（只读，浏览器打开）
• GET /api/v1/health：{ok, pid, dir, startedAt} 存活检查
• GET /api/v1/snapshot：bro review watch 快照（mols × gates × fleet × loop）
• GET /api/v1/agents：agents board，bro fleet agents status --json 结构，含每后端代理与占用及已武装配额通道，以及注册表从未生成的已发现会话面行（交互/外来会话、acp worker）
• GET /api/v1/queue：beads 队列——已认领（进行中）行与就绪深度
• GET /api/v1/ticks：监督信息——watch 心跳摘要、drive 单例锁（pid+存活+年龄）、待处理 watch 标记
• GET /api/v1/mailbox：{drops} 通知尾部，最新在前，只读（不消费）
• GET /api/v1/agents/<ref>：单个代理，ref 为 agentId 或 molStep
• POST /api/v1/agents：spawn，请求体 {molStep, worktree?, prompt?|promptFile?, connector?, beadsDir?}，返回 201 {agent}；写入必须发送 Authorization: Bearer <token>（serve.json 中的 token 字段，缺失返回 401）与 content-type: application/json（回环 CSRF 防护，缺失返回 415）；409 表示认领冲突，400 表示输入错误，503 表示后端工具缺失/不可用，500 表示服务器配置错误
• DELETE /api/v1/agents/<ref>：stop，200 {agent, stopped, terminal?}；无令牌 401，干净未命中 404，降级后端导致未命中不可验证 503，worker 在停止信号后存活或死亡未确认时 409 {error, agent, stopped:false, verdict}（verdict 为 'still-running' 或 'unverified'）
• POST /api/v1/webhooks/github：GitHub webhook 摄入 → github:* 总线主题。X-Hub-Signature-256 HMAC 即认证，不使用会话令牌，且回环 Host 防护被绕过以便托管隧道公开 Host 可达。仅在设置 BRO_GITHUB_WEBHOOK_SECRET 时武装（未设置→503，签名错误/缺失→401，验证通过→202 {accepted, published}）；武装时 bro fleet serve 还在进程内托管 repo broker
• ALL /v1/*：Messages-API 提供方平面，到环境配置上游的字节代理。将 Claude Code 会话指向 bro fleet serve（ANTHROPIC_BASE_URL=<serve url>）即可通过 bro 与 Anthropic 通信，SSE 帧、tool_use 块与 beta 面均原样传递。仅当服务器环境设置 BRO_PROVIDER_API_KEY（回退 ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN）时接线，未设置→404。BRO_PROVIDER_UPSTREAM 可覆盖上游（默认 https://api.anthropic.com）

使用方式

前提：bro 在 PATH 中或使用 npx -y @broject/bro@0（主版本固定），外加 bd——快照路由与仅 {molStep} 的 spawn 通过共享 beads 存储解析。

发现机制是状态文件而非端口约定：读取 <git-common-dir>/bro/serve.json 中的 {pid, url, token}；默认端口随机，因此两个仓库可同时服务而不冲突。同一仓库上第二个 bro fleet serve 在记录的 pid 仍存活时会拒绝启动。

写入需会话令牌：每个 POST/PUT/PATCH/DELETE 须发送 Authorization: Bearer <token>，token 为 serve.json 中的字段；服务器检查的是持有权而非 UID。文件权限 0600，令牌通常仅属主可读。读取不需要令牌，任何本地用户可通过回环访问 GET 平面（v1 接受此点；受门控的是变更操作）。唯一例外是 /api/v1/webhooks/*——摄入路由基于投递的 HMAC 签名认证，并故意跳过 Host 防护。

提供方平面在每个方法上均以令牌认证：/v1/* 请求将会话令牌作为 API 凭据（Authorization: Bearer 与 x-api-key），包括 GET。客户端接线：env.ANTHROPIC_BASE_URL=<serve url> 加 ANTHROPIC_AUTH_TOKEN=<serve.json token>，或 "apiKeyHelper": "jq -r .token <git-common-dir>/bro/serve.json"。代理将该令牌换为上游真实密钥。

适用场景

适用于需要让 TUI、WebUI、IDE 等瘦客户端通过本地 HTTP/JSON 访问 bro 的 agents、fleet、快照、队列、监督、邮箱等数据，以及需要 spawn/stop 代理、接入 GitHub webhook 或通过 bro 代理转发 Messages-API 请求的本地场景。

限制

v1 仅绑定 127.0.0.1，无 --host 参数，不暴露远程访问；远程编排为独立规范，不得扩大绑定。读取平面降级时不会失败，而是由失败后端在响应中附降级说明，客户端须渲染而非假设 fleet 为空。bro fleet serve 为前台进程，由会话的监督者运行；ctrl-c/SIGTERM 关闭监听并清除 serve.json。

暂未提供

资料未提供定价、收费、平台兼容性、性能指标及具体效果数据。