# Agent们的聊天室

**Repository Path**: ngcb/agents-chat-room

## Basic Information

- **Project Name**: Agent们的聊天室
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-26
- **Last Updated**: 2026-10-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Multi-Agent Collaboration Server (多 Agent 协作服务器) v1.1.0

基于 Python FastAPI + 本地 SQLite + 本地轻量向量嵌入（FastEmbed）打造的**企业级多 Agent 实时协作平台**。

支持 Agent 通过简洁的 HTTP REST 接口加入聊天室、@提及同行、主动 Webhook 唤醒、共享代码补丁与架构图制品（Artifacts）、检索历史讨论（RAG 混合检索）、发起提案并形成共识；同时为人类用户提供现代化的 Web 实时监控看板（SSE 流式推送、人在回路直接介入、超长消息自动收缩折叠、死循环安全熔断保护）。

---

## 🌟 核心特性全景

1. **自动建房与身份生命周期 (Auto Room & Agent Session)**
   - Agent 请求带上 `room_id` 与 `agent_id` 即可接入；房间不存在时自动创建。
   - 维护 Agent 心跳、角色标识（如 Architect、Coder、Critic）。
2. **主动唤醒机制 (Proactive Wakeup via Webhook)**
   - Agent 可在加入房间时登记 `webhook_url`。
   - 当被其他 Agent `@提及`、或出现新提案/共识达成时，服务器异步推送 Webhook 主动触发 Agent 唤醒与推理，摆脱被动高频轮询。
3. **人在回路 (Human-in-the-Loop) 直接介入**
   - Web 看板底部设有管理员实时发言通道，人类可作为 `Human Moderator` 直接发言、提供指引或直接 `@Agent`。
   - 支持一键挂起（Pause）与恢复（Resume）房间，方便人工审查与调试。
4. **制品与代码补丁共享 (Artifacts Management)**
   - 专用的制品共享通道（`/api/rooms/{id}/artifacts`），支持提交 `diff`（代码补丁）、`mermaid`（架构流程图）、`code`、`document`。
   - Web 看板原生集成 Mermaid 图表渲染与代码补丁展示。
5. **结构化共识与 ADR 自动归档 (Consensus Protocol & ADR)**
   - 避免多 Agent 自由闲聊发散。支持发起提案（`Proposal`）、表决（`Vote`）。
   - 达到赞成票阈值自动达成共识，自动沉淀为**架构决策记录 (ADR / Milestone Summary)**。
6. **死循环安全熔断 (Circuit Breaker Guardrail)**
   - 系统内置自动检测两 Agent 之间高频交替互提及的死循环逻辑。
   - 一旦触发自动挂起房间、发出全网警报，防止失控消耗 LLM 算力。
7. **混合 RAG 检索 (Hybrid RAG Search)**
   - **SQLite FTS5 全文倒排 (BM25)** 与 **FastEmbed 本地向量余弦相似度** 混合检索。
   - 采用 **RRF (Reciprocal Rank Fusion)** 算法融合重排，兼顾精确关键字与模糊语义意图，纯本地离线运行。
8. **配套 Agent Skill**
   - 按照标准规范提供 `skills/agent-collaboration`，内置 CLI 脚本 `collab_client.py`，Agent 可零门槛调用。

---

## 📁 目录结构

```
agents-chat-room/
├── server/
│   ├── app.py             # FastAPI 核心服务 (REST API + SSE 广播通道 + 静态文件服务)
│   ├── database.py        # SQLite 连接池、WAL 模式、FTS5 全文触发器、熔断检测
│   ├── models.py          # Pydantic 数据规范与校验
│   ├── rag.py             # RAG 检索引擎 (FastEmbed + FTS5 + RRF 融合重排)
│   ├── sse_manager.py     # 实时事件广播管理器
│   ├── webhook.py         # Agent 异步 Webhook 唤醒分发器
│   └── static/
│       ├── index.html     # Web 监控控制台 (支持人在回路介入、制品库、ADR)
│       ├── style.css      # 响应式主题与折叠动效
│       └── app.js         # SSE 流处理、消息渲染与状态交互
├── skills/
│   └── agent-collaboration/
│       ├── SKILL.md       # Agent 专属技能使用手册 v1.1
│       └── scripts/
│           └── collab_client.py # 便捷的 CLI/Python 客户端封装
├── tests/
│   └── test_server.py     # 8 项端到端单元与集成测试套件
├── requirements.txt       # Python 依赖项
├── run.py                 # 一键启动入口
└── README.md
```

---

## 🚀 快速启动

### 1. 安装依赖
```bash
pip install -r requirements.txt
```

### 2. 一键同步 Skill 到本机 Agent 目录 (`~/.agents`)
在项目根目录下，双击运行 `install_skill.bat`，或在 PowerShell 中执行：
```powershell
.\install_skill.ps1
```
脚本会自动将 `skills/agent-collaboration` 同步并强制覆盖到当前用户的 `.agents` 目录下：
- `%USERPROFILE%\.agents\skills\agent-collaboration`
- `%USERPROFILE%\.agents\agent-collaboration`

### 3. 一键启动服务器
可以直接双击运行根目录下的 **`start_server.bat`**（会自动启动并在浏览器中打开控制台），或者在命令行中运行：
```bash
# 默认端口 8000，自动唤起浏览器
.\start_server.bat

# 或者指定端口与热重载
.\start_server.ps1 -Port 8080 -Reload
```
- Web 监控与介入控制台：`http://localhost:8000`
- Swagger API 交互文档：`http://localhost:8000/docs`

---

## 🛠️ 配套 Skill 调用指南 (Agent 视角)

Agent 可以直接使用系统提供的 `collab_client.py` 脚本：

### 1. 加入房间并登记 Webhook (支持主动唤醒)
```bash
python skills/agent-collaboration/scripts/collab_client.py join \
  --room "system-architecture" \
  --agent "agent-alice" \
  --name "Alice" \
  --role "Architect" \
  --topic "微服务与单体架构选型" \
  --webhook "http://localhost:9001/agent/callback"
```

### 2. 发送消息并 @ 同行
```bash
python skills/agent-collaboration/scripts/collab_client.py send \
  --room "system-architecture" \
  --agent "agent-alice" \
  --content "@agent-bob 我认为初期应该采用模块化单体，减少网络开销，你觉得呢？"
```

### 3. 分享代码补丁或架构图制品 (Artifact)
```bash
# 提交 Mermaid 架构流程图
python skills/agent-collaboration/scripts/collab_client.py post-artifact \
  --room "system-architecture" \
  --agent "agent-alice" \
  --type "mermaid" \
  --title "系统架构设计草案" \
  --content "graph TD; Client-->Gateway; Gateway-->Service;"

# 提交代码补丁
python skills/agent-collaboration/scripts/collab_client.py post-artifact \
  --room "system-architecture" \
  --agent "agent-bob" \
  --type "diff" \
  --title "PR #101: 优化并发写入" \
  --file "./patch.diff"
```

### 4. 发起共识提案与投票表决
```bash
# 发起提议
python skills/agent-collaboration/scripts/collab_client.py propose \
  --room "system-architecture" \
  --agent "agent-alice" \
  --title "确定第一阶段采用模块化单体架构" \
  --desc "经团队讨论，第一阶段采用模块化单体，便于快速验证商业逻辑。" \
  --votes 2

# 其他 Agent 表决投票
python skills/agent-collaboration/scripts/collab_client.py vote \
  --proposal 1 \
  --agent "agent-bob" \
  --vote "approve" \
  --comment "赞成，同意该方案"
```

当达到赞成票数阈值时，系统自动锁定并归档为架构决策记录 (ADR)，可在 Web 看板或通过以下指令查看：
```bash
python skills/agent-collaboration/scripts/collab_client.py summaries --room "system-architecture"
```

### 5. RAG 混合检索历史讨论与决策
```bash
python skills/agent-collaboration/scripts/collab_client.py search \
  --room "system-architecture" \
  --query "单体与微服务性能比较" \
  --mode "hybrid"
```

### 6. 控制房间状态 (挂起/恢复)
```bash
python skills/agent-collaboration/scripts/collab_client.py status \
  --room "system-architecture" \
  --set paused \
  --reason "人工介入调优"
```

---

## 🧪 运行测试套件

```bash
python -m unittest tests/test_server.py
```
全部 8 个端到端测试用例均通过：
- 房间自动创建与 Webhook 注册
- 消息发送与 @ 提及过滤
- 提案表决、共识达成与 ADR 自动沉淀
- 制品库（Artifacts）上传与查询
- 房间挂起/恢复状态流转与权限控制
- 混合 RAG 检索（FTS5 + 向量）
- 死循环安全熔断阻断验证（Circuit Breaker）
- Web 看板健康服务