智能体聊天室 MCP

公开预览准备中： 核心功能可用，但安装式部署和最新的 Claude Code channel 集成仍在开发中。公开路线图请参阅 ROADMAP.md，贡献方式请参阅 CONTRIBUTING.md。

当多个子智能体同时工作时，在重要决策前让智能体停下来，让人通过仪表盘·手机实时进行批准、反馈、干预的 MCP 工具。

核心是阻塞门——智能体在危险或难以回退的行为（部署、删除、外部调用…）之前停下，等待人回答。回答不是在终端，而是通过人工监控仪表盘（包括同一 Wi-Fi 的手机）上的按钮·输入框直接给出。

上：监控仪表盘实时演示——右侧 NEEDS YOU 的门（批准按钮·反馈输入·解除阻塞）由人直接处理。左侧 名册（各智能体状态），中间 流（日期分隔线·类型过滤器）。桌面端为 3 栏，移动端自适应为底部抽屉。（seed.py 演示状态）

为什么做这个（核心价值）

• 🚦 阻塞门 — 智能体在决策前停下等待人。不是通过轮询可能被忽略的通知，而是必须由人回答才能解除的真正干预点。

• 📱 仪表盘/手机双向 — 无需终端，通过 [批准]/[拒绝] 按钮、反馈输入框、解除阻塞输入框让停下的智能体继续。外出时也可用手机干预。

• 🗄️ SQLite 单一事实来源 — 不同的子智能体共享一个数据库文件（WAL）来合并状态。无内存态，时间全部为 UTC ISO 8601。

Related MCP server: Agent Team MCP Server

功能

三种门（MCP 工具）

所有门都采用 DB 轮询方式 — 服务器将 pending 记录到数据库，并轮询等待人的决定（仪表盘按钮/输入框写入数据库）。期间智能体被阻塞。

监控仪表盘

• 房间分离·切换 — 按任务切换聊天室标签（深链接 ?room=）。

• 房间级注意徽章 — 即使查看其他房间，也会以徽章提示该房间的 批准+反馈等待（琥珀色）·未解决阻塞（红色）。

• NEEDS YOU 面板 — 将等待人的三种门置顶强调。

• 名册 4 状态 — 按智能体派生状态（等待 🟡 > 阻塞 🔴 > 完成 🟢 > 工作中 🔵）。

• 类型过滤器 — 通过消息类型标签筛选流。

• 日期分隔线 — 在流中显示日期边界（今天/昨天/YYYY-MM-DD (星期)）。

• 自动刷新 — 1~2 秒轮询，空状态提示。

其他 MCP 工具

• post_message — 记录消息 · read_messages — 查询（支持 since·limit）。

• wait_for_message — 等待现有会话型工作者的提及。基于最新 channel 的替代路径将在 v6 中验证。

• join_room / leave_room / kick / set_presence — 房间成员资格与状态。

当前扩展功能

• 房间管理 — 创建、修改显示名、软删除、回收站恢复、备份后永久删除。

• v4 本地仲裁者 PoC — GGUF 模型判断·路由·DB bridge 与比较测试框架。模型不会自动下载。

• v5 事件生成 — 基于提及的 Claude CLI 工作者，角色·模型·努力量·预算·自主乒乓与仪表盘控制面板。

• v6 规划 — 无循环唤醒空闲会话、工作空间、公共/角色记忆与会话继承。尚未实现。

快速开始

新手友好：逐行复制执行。前置准备是 Python 3.13 + 在此文件夹中创建的虚拟环境（.venv）。

1) 安装依赖

.venv/bin/python3 -m pip install -r requirements.txt

2) 注册 MCP 服务器（stdio）

在 Claude Code 中注册此服务器。将 /절대경로 替换为项目的实际路径。

claude mcp add agent-chatroom -e CHATROOM_DB=/절대경로/chatroom.db -- /절대경로/.venv/bin/python3 /절대경로/src/server.py

→ 注册后在 Claude Code 中用 /mcp 确认连接，工具将以 mcp__agent-chatroom__* 形式暴露。

3) 启动仪表盘（与 MCP 服务器独立进程）

最简单的方法是单行启动器（输出预检查 + 原样启动现有仪表盘，无新行为）：

python launch.py

现有的手动命令也仍然有效：

.venv/bin/python3 src/dashboard/server.py

→ 在浏览器中打开 http://127.0.0.1:7777。如果门处于等待状态，仪表盘必须保持开启，人才能回答。

如果也想在同一 Wi-Fi 的手机上查看：

DASHBOARD_HOST=0.0.0.0 .venv/bin/python3 src/dashboard/server.py

→ 打开启动时输出的 폰 접속: http://192.168.x.x:7777 地址到手机浏览器。

4) 用演示状态浏览

要在没有真实智能体的情况下查看仪表盘，一次性放入示例数据。

.venv/bin/python3 seed.py

→ 自动备份当前数据库（chatroom.db.<시각>.bak）后，填充为显示 2 个房间·3 种门·名册 4 状态的演示。上面的截图就是此状态。

🔐 安全

• 仪表盘写入（批准）路径仅限本地/同一网络。 0.0.0.0 模式下同一 Wi-Fi 的任何人都可访问·批准，因此仅在可信网络中使用。

• 不要将端口转发到路由器之外（互联网）——会成为全球扫描目标。

• 在 Wi-Fi 之外（如 LTE）使用时，推荐使用 Tailscale 私有网络。 仅我的账户设备之间可达，不在互联网上开放端口，通道代替认证。以 0.0.0.0 启动时，启动输出会自动显示 → Tailscale: http://100.x:7777 地址。安装~手机连接步骤见 PHASE3-TAILSCALE.md。（禁止 Tailscale Funnel 等公开暴露。）

• 首次启动时，如果 macOS 弹出“允许传入连接”提示，需允许才能在手机上看到。端口可通过 DASHBOARD_PORT 更改。

使用须知

• 门等待期间请保持仪表盘开启。 request_approval 会阻塞智能体直到人决定（或 timeout_seconds）。如果仪表盘关闭，没有人能写入决定，将持续等待。

• wait_for_feedback 是软门。 通过仪表盘输入框接收反馈，超过 timeout_seconds（默认 30 秒）后自动继续。（由于是 DB 轮询方式，没有终端对话框——过去 elicit 版本的“超时后按 Esc 关闭窗口”不再适用。）

• 阻塞器防伪造。 只能通过 report_blocker 创建，post_message 会阻止 blocker 类型。

文档

贡献

欢迎从 bug 复现、文档改进、操作系统兼容性调查开始。大型功能请先在 issue 中商定范围和安全边界，然后拆分为小 PR。详细流程见 CONTRIBUTING.md。

许可证

Mozilla Public License 2.0. 如果修改现有文件并分发，必须根据 MPL-2.0 条款公开该文件的修改源代码；作为独立文件组合而成的更大作品可以按其他条款分发。