AgentChat

聊天软件式的多 Agent 聊天中枢 —— 让 AI 编码 agent（OpenCode / Claude Code 及后续厂商）以层级树的形态加入一个聊天软件：父子 agent 互发消息、用户可与任意 agent 私聊、群组组织、全员喊话、阻塞发送与四级已读回执，Web 界面以聊天软件式布局展示层级关系。

状态

Hub 核心 + Web UI + 两个厂商适配器（OpenCode / Claude Code）均已实现（Hub：HTTP/WS/MCP、ask 批示、通知中心、审批闸门；Web UI：聊天软件式三栏界面；适配器：进程外插件/hooks + 一键安装器）。spec 见 docs/superpowers/specs/。

Related MCP server: Multiplayer MCP Server

Web UI

人经 Web UI 使用，agent 经 MCP 接入（见下节）——两个入口，同一 Hub。

npm install
npm run build && npm start   # 构建前端 + 拉起生产入口 → 浏览器打开 http://localhost:4646

界面为聊天软件式三栏：左图标栏（聊天 / 通讯录 / 通知 / 喊话）｜中会话列表（折叠层级 + 双层未读）｜右视图 （聊天流 + 四级回执 + 审批/批示卡、Agent 组织树 + 资料卡、通知中心、喊话投递汇总）。

容器节点：实例（root agent）注册时标记 role_tag="container"，显示为「容器」徽标， 仅用于 Agent 层级分组，不是聊天实体：以容器为收件方的 DM 由服务端拒绝 （container_not_chat_target，POST /api/conversations 4xx；shout 收件方也不含容器）， 聊天栏（会话列表）过滤与容器之间的会话、其未读不计；通讯录仍保留为可展开的分组标题。

开发热更（前端 Vite，/api、/mcp、/internal 代理到 Hub）：

npm start    # 终端 A：Hub（http://localhost:4646）
npm run dev  # 终端 B：Vite 开发服务器（热更）

npm start 从 client/dist 托管静态页，故首次运行前需 npm run build（Playwright 的 webServer 已自动执行）。

运行

npm install
npm start        # = tsx server/main.ts：拉起 HTTP 服务 + 2s 唤醒 dispatcher

npm start 是生产入口：server/main.ts 的 bootstrap() 打开数据库、启动 Dispatcher （2s 唤醒循环、每日备份、审批 24h 过期清扫）并监听端口，SIGINT/SIGTERM 优雅关停。 dispatcher 不在 createApp()/start() 内部启动（测试反复调用会把 interval 与备份打进临时库）。

一行命令（agentchat CLI）

npm link（或 npm i -g .）后可直接用 agentchat 启动——它会在前端产物缺失时先构建， 再拉起同一生产入口，因此无需手动 npm run build / npm start：

npm link      # 把 bin/agentchat.mjs 链入 PATH
agentchat     # 按需构建前端 → 拉起 Hub → 交互式终端自动打开浏览器

npm start 与 npm run build 保持不变。

恢复出厂设置（清除全部数据）

• CLI：agentchat reset [--yes] [--keep-backups] [--uninstall-adapters] [--force]。默认先把整个数据目录 复制为 <home>.bak-<时间戳>（失败即中止、保留原状），再清空 agentchat.db(+wal/shm)、tokens/、 agents/、logs/、backups/（--keep-backups 时保留）、config.json、hub_token 等；出厂态不含 config.json（由安装器/首次运行再生成）。检测到 Hub 正在运行会拒绝（--force 才继续，有风险）； 非交互环境必须显式 --yes。退出码：0 成功、1 运行错误、2 参数错误、3 Hub 运行中、4 缺少 --yes、5 交互确认中放弃（未做任何改动）。 agentchat reset 不支持 --home（--home 是上面 agentchat 启动命令的参数）：其数据目录只认 AGENTCHAT_HOME（未设则默认 ~/.agentchat）。

• Web UI：rail 第 5 个 tab「设置」→「恢复出厂设置」需手工逐字输入 RESET 才可提交；成功后清 localStorage 的 agentchat: 键并提示重启 Hub。「设置」面板同时展示数据/日志位置、可「清除本地状态」， 并提供「保留 backups/ 目录」复选框（默认不勾 → 请求体省略 keepBackups，即连同 backups/ 一并清除）。

• 端点：POST /api/admin/reset（body {confirm:"RESET"}，可选 {keepBackups:true}）——仅回环来源可调用； Hub 运行中不能删 DB 文件（Windows 锁），故先 VACUUM INTO 一致性快照、再就地清空并重建全部表， 返回 {ok:true, restartRequired:true, snapshotPath}。GET /api/admin/info 返回数据目录与日志目录。

残余风险（务必知悉）：回环上任何本地进程都能调用该端点（与既有「本机单用户信任模型」一致， 不构成对本地恶意进程的防护）；且删除 hub_token 后运行中的 Hub 仍持内存里的旧 token， 窗口期内旧 token 依然可用——必须重启 Hub 才彻底生效。

自动打开浏览器：仅当交互式终端（stdout.isTTY）且未被显式关闭时才开； CI / 管道 / 脚本一律不开。--no-open 与 AGENTCHAT_NO_OPEN 是同一开关的两条路径 （CLI 的 --no-open 即设置 AGENTCHAT_NO_OPEN），显式关闭优先于 AGENTCHAT_OPEN 与 config.json 的 openBrowser。打开失败只 warn，绝不影响 Hub。

适配器

把 OpenCode / Claude Code 接入 Hub —— 两者都是进程外 pull 适配器：Hub 不主动推送，由适配器在 agent 空闲时主动拉取待投递内容（agent 侧无长驻连接可被 Hub 推送）。 发送时 Hub 一律为合格收件方建 wake_job（不依赖厂商登记），pull 适配器在认领时投递； OpenCode 插件在空闲期间还会周期轮询（AGENTCHAT_POLL_MS，默认 10s）补拉，故「已经 idle 之后」到达的消息也能被投递。

厂商登记免手动配置：厂商列表按 env AGENTCHAT_ADAPTERS > <AGENTCHAT_HOME>/config.json 的 adapters 字段 > 空 解析（env 为空串 = 显式清空并压过文件；只有未设才回落到文件）。两个安装器安装时会把本厂商 id 自动合并进 config.json（幂等、保留其它键、 --uninstall 精确移除），因此无需再手动 $env:AGENTCHAT_ADAPTERS。即便完全未登记，Hub 在首次收到 某厂商的 POST /internal/wake 时会自动识别为 pull 适配器（此后 dispatcher 不再对该厂商的到期消息做退避）； 未登记的真实代价只是 dispatcher 对到期消息做有界重试（每 ≤30s 一次），消息不会丢失。 config.json 其它可选键：port（env AGENTCHAT_PORT 覆盖）、openBrowser（env AGENTCHAT_NO_OPEN / AGENTCHAT_OPEN 覆盖）。

一条命令安装（在仓库根目录执行；先 npm start 让 Hub 写出 hub_token。安装器不读 HUB_TOKEN； OpenCode 适配器运行时无需手动 export —— 插件与本地桥都自动读 <AGENTCHAT_HOME>/hub_token （HUB_TOKEN 非空时覆盖）；Claude Code 适配器的 hooks 仍需 HUB_TOKEN 对其进程可见。见各文档）：

两安装器均幂等、改动前自动备份、支持 --dry-run（只打印不落盘）与 --uninstall（精确移除本适配器条目）。 OpenCode 的 MCP 条目是本地 stdio 桥（adapters/opencode/mcp-bridge.mjs），配置里不含 {file:} 引用 与 token 明文 —— 身份与 token 由桥逐请求从磁盘读取；旧版会砖的 {file:} 结构会被安装器自动迁移。 桥对每次 tools/call 会把插件（tool.execute.before）注入的 x-agentchat-session 剥离并转请求头， 使 Hub 按会话节点（task_ref）解析出站身份 —— 故会话回复不再从容器（实例节点）发出。

Claude Code 有两个落点（务必区分）：hooks 落 settings.json；MCP 配置落 ~/.claude.json 顶层 mcpServers（或 --mcp-config 指向项目 .mcp.json；设 CLAUDE_CONFIG_DIR 时随其重定位）——两个不同文件。 这两个文件的落点是官方事实，安装器从机制上拒绝把二者写成同一文件。

MCP 工具面与通知端点

Agent 经 POST /mcp（Bearer HUB_TOKEN 传输门）调用 MCP 工具；根首次 register 生成 join_token（连接握手）。工具契约的单一来源是 shared/contracts.ts 的 MCP_TOOLS。 除握手 register 外共十一项：

通知页数据面（用户侧 UI 消费）：

• GET /api/notifications?scope=actionable|all — 通知列表（actionable = 待用户处理；all = 全部，含已决与 agent↔agent），每条带深链锚点 cardMessageId / conversationId。

• POST /api/asks/:id/respond — 以用户身份答复某条批示（{choice?|text?}）。

• POST /api/notifications/:id/read — 标记某条通知已读（幂等）。

安全模型（MVP 本地信任）

MVP 是本机单用户模型，安全边界是「进程与本地文件系统」，不是网络或身份层：

• HUB_TOKEN（$AGENTCHAT_HOME/hub_token）只作传输门：/mcp 与 /internal/* 的 Bearer 校验； loopback 本机进程可读，故不构成对本地恶意进程的防护。

• x-agent-id 是建议性身份：连接时声明、register 后可写，服务端不校验其与 join_token 的绑定。

• x-agentchat-session（适配器逐调用注入的会话节点 task_ref）同属建议性身份：命中会话节点即以其为身份 （忽略 x-agent-id），未命中则省略身份（绝不回落容器）；同样不做与 join_token 的绑定校验。

• 审批闸门（建群/拉人/喊话）不是安全边界：它约束「谁以根 agent 名义发起受限动作」的产品语义， 不抵御伪造 x-agent-id 的本地调用方。

• LAN / Plan 2 将把 join_token 逐 agent 绑定到连接凭证（真实身份认证），届时审批闸门与 x-agent-id 才具备安全语义；在此之前请勿把 Hub 暴露到非可信网络。

许可证

MIT —— 见 LICENSE。第三方参考实现的使用规范见 spec 第 3 节（仅复用 MIT 项目源码）。