Dashboard 管控面

Dashboard 是 botmux 的浏览器管控面，跨所有 daemon/机器人统一管理。命令行 botmux dashboard 输出当前的轮换式登录 token URL：

botmux dashboard          # 获取当前 URL；尚无 token 时创建第一个
botmux dashboard current  # 同一操作的显式写法
botmux dashboard rotate   # 轮换 token 并输出新 URL
# 输出: http://<lan-ip>:7891/?t=<token>

token 语义要点：

• URL 一直有效，直到 rotate 生成新 token 使旧 URL 失效；token 持久化，botmux restart 后仍有效。
• 成功访问 ?t= 只是把同一 token 写进 cookie，不消费/不作废它——轮换前同一 URL 可重复登录，分享链接 ≈ 分享登录态。
• 默认端口 7891，可用 BOTMUX_DASHBOARD_PORT 修改。

功能面板

• Sessions：跨所有 bot 列出活跃 + 已关闭会话，按 CLI/状态/adopt/文本过滤；detail 页可复制 ID、关闭会话、批量关闭；「定位话题」让机器人在原话题发一条 @会话 owner 的提醒帮助跳回上下文；chat-scope 会话行带飞书群 AppLink 直达群聊。
• Schedules：列出所有定时任务，可 Run now / Pause / Resume（见 schedule）。
• Groups：一键拉新群（自动 @ 通知被邀请人）、拉 bot 入群、自动转让群主；解散群聊、bot 退群（关联会话自动清理）。
• 团队 / Roles / Bot Defaults：团队面板做跨部署协作（邀请别人的部署进团队、跨部署拉群）；Roles 管理按群人设；Bot Defaults 配默认行为（新群 oncall、卡片签名、默认角色等）（见 roles）。
• Workflows 管控面：Run List 轮询；Run Detail 看 summary / dangling 红区 / node-activity / event timeline / 并发执行 timeline；可直接 cancel run（见 workflow）。

两件事在 Dashboard 之外：v3 workflow 的 humanGate 批准/拒绝走飞书审批卡；带参触发 workflow 走**接入点（Webhook）**路径（见 external-trigger）。Dashboard 的 Workflows 面板专注观测与 cancel。

对外只读查询

三个对外观测接口：

• GET /api/dashboard/v1/summary：版本化、强脱敏的 fleet 运行摘要；
• GET /api/sessions：当前聚合的 active + closed session rows；
• GET /events：对外 SSE 流，session.spawned 的 body.session 与 session.update 的 body.patch 携带完整值/变更值。每个 daemon 内部还有仅绑定 loopback 的 /api/events，那是 Dashboard 聚合器的 IPC，不是对外地址。

Summary API

GET /api/dashboard/v1/summary 用于把 botmux fleet 接入外部状态页、监控或编排器。汇总当前在线 daemon 的 live sessions/schedules，只输出正向白名单中的状态和计数；不返回 bot/session ID、标题、群名、工作目录、提示词、排程内容或诊断日志。200/429/503 响应都带 Cache-Control: no-store。

该接口由 botmux start 一同启动的 botmux-dashboard 进程提供（普通 fleet 模式的 Dashboard facade）；botmux serve --api-only 的 core-only 单进程模式不启动 Dashboard，没有此路由（见 api-core-only）。

成功生成快照返回 200（200 只表示快照成功；有配置但不在线的 bot 时 service.status 仍为 degraded）：

{
  "schemaVersion": 1,
  "generatedAt": "2026-08-09T02:30:00.000Z",
  "service": { "status": "healthy" },
  "bots": { "online": 3 },
  "sessions": { "active": 7, "attention": 1 },
  "schedules": { "enabled": 2, "nextRunAt": "2026-08-09T04:00:00.000Z" },
  "dashboard": { "href": "/" }
}

字段	语义
schemaVersion	响应契约版本，当前为 1
service.status	在线 bot 数 = 已配置 bot 数时 healthy，否则 degraded
bots.online	当前在线 daemon/bot 数
sessions.active	状态不是 closed 的会话数
sessions.attention	active 中需处理的数量：待选仓库、TUI 提示、agent attention、limited/stalled 状态
schedules.enabled	已启用的排程数
schedules.nextRunAt	最早的下次运行时间（ISO-8601）；没有时为 null
dashboard.href	Dashboard 根页面相对路径，消费者相对当前 origin 解析

任一 live daemon 的快照超时/报错/格式非法 → HTTP 503，计数字段刻意省略（避免把缺失伪装成零）。匿名请求受 Dashboard 进程全局滚动窗口限流：所有匿名调用方共享配额，任意 10 秒内最多 5 次，第 6 次返回 HTTP 429（body 含 retryAfterSeconds，响应头 Retry-After 同值，通常 1–10 秒）。持当前 token 的请求不计入匿名限流；认证沿用登录态（?t= 先 302 设置 botmux_dashboard_token cookie），纯 API 客户端需保存并回传该 cookie，不接受 Authorization: Bearer。

会话 row 可选字段

以下字段只属于 /api/sessions rows 和 /events 会话 payload，summary 绝不返回；均为可选，消费者必须兼容旧会话/旧 daemon 不返回：

字段	语义
backendType	最近一次 worker spawn 时记录的后端（pty/tmux/herdr/zellij/zmx），cold resume 后可能随配置切换
backendSessionName	仅受管持久后端会话有，规则 bmx-<sessionId 前 8 位>；是确定性定位信息，不代表进程/socket 当前存活（见 tmux）
titleUpdatedAt	标题最后更新的 ISO-8601 时间
titleSource	标题来源：initial/user/agent/cli/dashboard/system；仅供展示，不是可信审计字段

publicReadOnly 与 token 边界

publicReadOnly 默认开启：开启时上述只读白名单接口可无 token 访问（summary 强脱敏；会话名称、标题等元数据按可公开信息对待）。

• 全部 POST/PATCH/DELETE、白名单外的 GET、原始 PTY/诊断日志始终需要当前 token。白名单是 fail-closed 的：新增 GET 不会因公开只读开启就自动暴露。
• 关闭 publicReadOnly 后，无 token 的 summary 返回 401；持 token 不受匿名限流。错误/已轮换的旧 token 在公开只读开启时按匿名请求处理。
• 关闭方式：Dashboard「设置」页，或 BOTMUX_DASHBOARD_PUBLIC_READONLY=false——但设置页一旦保存过该开关，~/.botmux/config.json 的持久值优先于环境变量。
• token 只提供 Dashboard 应用层访问权，不代替主机防火墙、VPN 或反向代理鉴权。

部署细节

Dashboard 走单独 pm2 进程 botmux-dashboard，跟 daemon 一起起停。每个 daemon 在 127.0.0.1 暴露内部 IPC（仅本机），Dashboard 进程做反向代理 + HMAC 鉴权：密钥文件 ~/.botmux/.dashboard-secret（mode 0600），是 daemon↔Dashboard 的内部签名密钥，不下发给浏览器（浏览器侧走轮换登录 token）。

相关页面

• dashboard — Dashboard 聚合器与 IPC 的源码结构分析
• api-core-only — core-only 模式下的健康检查与控制接口
• roles — 团队面板与角色配置入口