# Agent-Gateway

**Repository Path**: cash_soldier_admin/agent-gateway

## Basic Information

- **Project Name**: Agent-Gateway
- **Description**: AGW (Agent Gateway)
AGW 是一个面向未来的通用多智能体协作网关。它旨在打破即时通讯平台（如飞书、微信、Telegram）与异构 AI 智能体（OpenClaw, NanoBot, Hermes 等）之间的壁垒，通过统一的中间件层，实现“人类-平台-智能体”之间的无缝、透明、类人化协作。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AGW - Agent Gateway

**AGW** 是一个通用的多智能体协作网关，连接飞书（Feishu）与异构 AI 智能体后端，通过 @提及实现"一个群聊，多个智能体"的无缝协作。

## 架构

```
┌──────────────────────────────────────────┐
│     飞书群聊         Web UI (SPA)         │
│  (Feishu WS长连接)   (HTTP + WS)         │
└────────┬─────────┬──────────┬────────────┘
         │         │          │
         ▼         ▼          ▼
┌──────────────────────────────────────────┐
│          ChannelManager                  │
│     FeishuChannel · Web API · WS Hub     │
│     (消息收发 · 事件处理 · WS 推送)        │
└──────────────────┬───────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────┐
│           MessageBus (asyncio.Queue)      │
│           入站队列 · 出站队列              │
└──────────┬──────────────────┬────────────┘
           │                  │
           ▼                  ▼
┌──────────────────┐  ┌──────────────────────┐
│   AgentLoop      │  │   HeartbeatService   │
│ (路由 & 命令处理)  │  │  (每 60s 存活检测)   │
│                  │  │                      │
│ DeliveryManager  │  │   SQLite (agw.db)    │
│ (Per-Agent队列)  │  │  bindings/tasks/logs │
└───────┬──────────┘  └──────────────────────┘
        │
        ▼
┌──────────────────────────────────────────┐
│           Provider 层                     │
│  Mock / OpenCode / Nanobot               │
└───────┬──────────┬───────────────┘
        │          │
        ▼          ▼
┌──────────────┐  ┌────────────────┐
│ OpenCode     │  │ Nanobot        │
│ (ServerMode) │  │ (OpenAI 兼容)   │
└──────────────┘  └────────────────┘
```

## 核心特性

- **飞书消息收发**：WebSocket 长连接，无需公网 IP，支持文本/富文本/图片/文件/流式卡片回复
- **@ 提及路由**：`@智能体A` `@智能体B` 自动匹配对应后端智能体
- **Web 管理 UI**：深色主题 SPA，仪表盘/对话/配置/代理/通道管理 + OpenCode/Nanobot 控制台
- **全局 WebSocket 推送**：实时消息推送 + 状态检测，三态指示器（运行中/连接中/离线）
- **Agent Console SSE 实时流式渲染**：后端 SSE 直通前端，`message.updated`/`message.part.updated`/`message.part.delta` 事件驱动，无轮询
- **Slash 命令自动补全**：输入框键入 `/` 弹出指令列表，↑↓ 键盘/鼠标选择
- **看板拖拽调整高度**：看板底部拖拽条（⋮）可调整高度，按任务持久化到 localStorage，页面变化时自动钳制
- **消息全量日志**：SQLite `logs` 表统一存储，飞书/Web 两端实时推送一致
- **Per-agent 串行队列**：每个智能体独立 `asyncio.Queue` + 后台 Worker，消息排队串行执行
- **任务系统**：全局任务管理，创建/切换/暂停/删除，每个任务隔离后端 session
- **Session 持久化**：`(agent_name, task_id)` → session_id 持久化至 SQLite `bindings` 表，跨重启复用
- **Session 存活检测**：OpenCode 轮询期间自动检查 busy 状态，卡住时 abort + recreate
- **语音输入**：点击 🎙️ 按钮实时语音输入（Vosk 离线 ASR，浏览器直连 WebSocket）
- **语音输出**：🔊/🔇 切换自动播放 agent 回复（Edge-TTS，AudioContext 解码播放）
- **插件化 Provider**：Mock / OpenCode / Nanobot 三种后端适配器，可扩展
- **配置即时生效**：Web UI 中保存配置时同时更新内存对象，无需重启

## 三种前端模式

三种模式全部走统一路径，通过 `task_store_id` 区分：

| 模式 | task_store_id | 特点 |
|------|--------------|------|
| **直联模式** | 空字符串 "" | 完整流程，不记录日志和处理状态 |
| **群聊模式** | "default" | 完整流程，记录日志 |
| **任务模式** | 具体 task_id | 完整流程，记录日志和看板 |

> **Human-in-the-Loop 问题功能已取消**：相关的 QuestionManager、问题注册、等待回答、解析回答、取消问题等功能已全部删除。

## 项目结构

```
agw/
├── __main__.py                # 入口：python -m agw
├── agent/                     # 核心消息处理
│   ├── loop.py                # AgentLoop：消息路由与命令处理
│   ├── delivery_manager.py    # Per-Agent 投递队列与生命周期
│   ├── proxy.py               # AgentProxy：统一传输层（新版 1:1 设计）
│   └── commands/              # 飞书指令处理器
├── api/                       # HTTP API + WebSocket 服务
│   ├── server.py              # aiohttp 服务启动
│   ├── auth.py                # Token 认证
│   ├── middleware.py          # 鉴权中间件
│   ├── websocket.py           # WebSocket Hub + 消息推送
│   ├── routes/                # 路由模块
│   │   ├── general.py         # health / login / dashboard / status / chat
│   │   ├── config.py          # 系统配置 + 代理 CRUD
│   │   ├── channels.py        # 通道 CRUD
│   │   ├── tasks.py           # 任务管理
│   │   ├── agents.py          # 统一 Agent Console 路由
│   │   ├── opencode.py        # OpenCode 控制台代理
│   │   ├── nanobot.py         # Nanobot 控制台代理
│   │   └── voice.py           # 语音服务代理
│   └── static/                # SPA 前端
│       ├── index.html
│       ├── css/style.css
│       └── js/
│           ├── app.js
│           ├── core.js         # WebSocket 消息处理和状态管理
│           ├── agent-console.js # 直联模式 Agent Console
│           ├── chat.js         # 任务模式聊天
│           ├── chat-group.js   # 群聊模式聊天
│           ├── chat-common.js  # 通用聊天功能
│           └── console-core.js # 控制台公共核心
├── bus/                       # 消息总线
│   ├── events.py              # InboundMessage / OutboundMessage / SourceInfo
│   └── queue.py               # asyncio.Queue + topic pub/sub
├── channels/
│   ├── base.py                # BaseChannel 抽象基类
│   ├── feishu.py              # 飞书适配器（WS + 卡片 + 流式）
│   ├── manager.py             # 通道生命周期与出站分发
│   └── registry.py            # 通道自动发现
├── config/
│   ├── loader.py              # JSON 配置加载/保存/迁移
│   ├── paths.py               # 运行时路径辅助
│   └── schema.py              # Pydantic 模型
├── heartbeat/
│   └── service.py             # 定时检测智能体在线状态
├── providers/
│   ├── agent.py               # AgentProvider 抽象基类
│   ├── mock.py                # MockProvider（测试用）
│   ├── opencode.py            # OpenCodeProvider（异步触发 + 轮询）
│   ├── nanobot.py             # NanobotProvider（OpenAI 兼容 API）
│   └── registry.py            # Provider 注册表
├── utils/
│   ├── database.py            # SQLite 连接管理
│   ├── agent_store.py         # 代理配置持久化
│   ├── channel_store.py       # 通道配置持久化
│   ├── binding_store.py       # Session 绑定持久化
│   ├── task_store.py          # 任务管理
│   └── helpers.py             # 工具函数
└── voice/                     # 语音子进程（FastAPI）
    ├── server.py              # FastAPI 服务入口
    ├── asr.py                 # Vosk 离线语音识别
    ├── tts.py                 # Edge-TTS 语音合成
    ├── service.py             # 子进程生命周期管理
    └── download_model.py      # Vosk 模型下载
```

## 快速开始

### 1. 安装

```bash
uv venv
source .venv/bin/activate
uv pip install -e .
# 如需语音功能，安装额外依赖：
uv pip install -e ".[voice]"
```

### 2. 配置

编辑 `~/.agw/config.json`（首次启动自动创建），或项目根目录 `config.json`。运行时 agents 和 channels 从 SQLite 加载：

```json
{
  "api": {
    "host": "127.0.0.1",
    "port": 9900
  },
  "admin": {
    "password": "As147258"
  }
}
```

### 3. 启动

```bash
# 启动网关
python -m agw

# 指定地址端口
python -m agw --host 0.0.0.0 --port 9900

# 指定管理员密码
python -m agw --password mypass

# 禁用语音
python -m agw --no-voice

# 查看状态
python -m agw status

# 查看版本
python -m agw --version
```

> **配置优先级**：运行参数 > `config.json` > 代码缺省值。
> 首次运行无配置时自动创建 `~/.agw/config.json`（缺省端口 9900，密码 As147258）。
> 语音服务默认端口 3725，`--voice-port` 指定，`--voice-model-path` 指定模型路径。

### 4. 启动 Mock Agent（测试）

```bash
python test/mock_agent_server.py
```

Mock Agent 默认监听 `http://localhost:9901/v1/chat`，随机回复 + 5-10s 延迟。

## @ 提及路由规则

| 消息内容 | 目标 |
|----------|------|
| `@韩素梅 帮我扫地` | 韩素梅 |
| `@韩素梅 @仙飘飘 你们好` | 韩素梅 + 仙飘飘（并发） |
| `帮我查天气` | Master 智能体 |
| `@张三 你好` | Master（@不存在） |
| `@仙飘飘 帮我` | 离线提示（enabled: false） |

### 看板任务中的 @mention 三路路由

| 发起者 | @目标 | 行为 |
|--------|-------|------|
| MASTER | 其他成员 | 创建子任务卡片（委派） |
| 任意 Agent | 自己 | 创建替换卡片，旧项取消 |
| 任意 Agent | 其他成员 | 仅路由消息，不建卡片（快速沟通） |

### 任务看板（Kanban）

**状态定义**：

| 状态 | 标签 | 含义 |
|------|------|------|
| `pending` | ⏳ 等待中 | 有未完成的前置依赖 |
| `ready` | ▶ 待处理 | 依赖已满足，等待同 Agent 前面的卡片执行完后提交 |
| `running` | 🔄 执行中 | 已发送给 Agent，等待回复 |
| `completed` | ✅ 已完成 | Agent 返回了正常结果 |
| `failed` | ❌ 异常 | 网络超时 / Session 创建失败等可判定错误，需 MASTER 处理 |
| `cancelled` | 🚫 取消 | MASTER 重新分配时旧卡被替换，或用户手动取消 |

**调度器**：全局 `_board_scheduler` 协程每 1.5s tick 一次，只处理 `status=running` 的任务：
- `pending→ready`：依赖已满足的自动激活
- `ready→running`：每个 Agent 一次只提交最早的一张卡片（顺序执行）

**同 Agent 顺序执行**：Agent 有多张 ready 卡时，一次只提交最早的一张，完成后再提交下一张（间隔 1.5s tick）

**重启后**：`running` 卡片不自动恢复（session 丢失），需手动 `/继续任务` → `running` 移入 `ready` → 调度器重新提交

**MASTER 汇总**：所有子任务完成 → 系统拼接结果提交 MASTER 审查 → MASTER 可 `@` 成员继续修正 → 循环直到确认

**子任务版本化**：Agent @自己 创建替换卡片，旧 completed 项自动转入取消列（`replaces` 字段追踪）

## 飞书指令

| 指令 | 别名 | 说明 |
|------|------|------|
| `/成员列表` | `/users` | 显示所有智能体 |
| `/状态` | `/status` | 显示运行状态 |
| `/帮助` | `/help` | 显示指令列表 |
| `/@所有 <内容>` | `/@all <内容>` | 转发给所有启用智能体 |
| `/取消 <名称>` | `/cancel <名称>` | 取消指定智能体 |
| `/取消全部` | `/cancelAll` | 取消所有智能体 |
| `/回答 <名称> <内容>` | `/answer` | 回答智能体的提问 |
| `/新建任务 <名称>` | `/createtask` | 创建新任务 |
| `/任务列表` | `/tasks` | 列出所有任务 |
| `/切换任务 <名称>` | `/switchtask` | 切换任务 |
| `/暂停任务` | `/pausetask` | 回到默认模式 |
| `/删除任务 <名称>` | `/deletetask` | 删除任务 |

> 指令大小写敏感，英文必须小写。

## Web 管理界面

启动后访问 `http://localhost:9900`，使用密码登录（无用户名）。

### 页面

| 页面 | 功能 |
|------|------|
| **仪表盘** | 运行时间、通道/代理/任务统计、在线/离线/禁用计数、异常列表 |
| **对话** | 群聊/任务切换、看板拖拽调整高度、HTTP 拉取历史、WS 实时推送、Markdown 渲染、语音输入/输出 |
| **通道管理** | 飞书通道 CRUD，app_id/app_secret/encrypt_key/domain 分字段配置 |
| **代理管理** | CRUD，类型下拉（Mock/OpenCode/NanoBot），启用/MASTER 切换 |
| **系统配置** | gateway 名称、API 地址、管理员凭证 |

### 控制台

智能体列表中 OpenCode/Nanobot 类型右侧显示 🖥 图标，点击进入：

| 类型 | 功能 |
|------|------|
| **OpenCode Console** | 会话 CRUD、消息发送、SSE 事件流实时渲染（message.updated/part.updated/part.delta）、Question 推送 |
| **Nanobot Console** | 会话 CRUD（WS new_chat + REST）、同步消息发送、reasoning/trace 渲染 |

### 语音功能

| 按钮 | 功能 |
|------|------|
| 🎙️ | 切换录音 → ASR WebSocket（`ws://127.0.0.1:3725/ws/asr`）→ 实时转写填入输入框 |
| 🔊/🔇 | 切换自动播放 agent 回复（`POST /api/voice/tts` → Edge-TTS） |

## Provider 详解

### OpenCodeProvider

使用 opencode server-mode 原生 REST API + SSE：

1. `POST /session` — 创建会话（按 `(agent_name, task_id)` 持久化复用）
2. `POST /session/{id}/prompt_async` — 异步触发（返回 204）
3. `GET /event` — SSE 事件流（`message.updated`/`message.part.updated`/`message.part.delta`），由 AgentProxy 直通前端；无轮询降级

**Session 管理**：
- 持久化至 SQLite `bindings` 表
- 启动时验证 session 有效性（`GET /session/{id}/message`，404 重建）
- 任务切换时 `task_id` 变更，自动加载新任务的 session
- 失败时自动清除缓存，下次重建

**认证**：`user_name` + `password` → Basic Auth；`api_key` → Basic(`opencode:{api_key}`)

### NanobotProvider

双端点架构：
- `channel_endpoint`（REST，默认 8765）：会话 CRUD、Token 获取
- `api_endpoint`（OpenAI，默认 9876）：`POST /v1/chat/completions`

会话通过 WS `new_chat` 创建或 REST `/api/sessions` 发现，消息同步等待。

### MockProvider

本地测试用，`POST {endpoint}/v1/chat` → `{"response": "..."}`。

## HTTP API

| 方法 | 端点 | 说明 |
|------|------|------|
| `POST` | `/api/login` | 登录 → Token |
| `GET` | `/api/status` | 系统状态 |
| `GET` | `/api/dashboard` | 仪表盘概览 |
| `GET` | `/api/tasks` | 任务列表 |
| `GET` | `/api/tasks/{task_id}/messages` | 任务消息历史 |
| `POST` | `/api/tasks` | 创建任务 |
| `DELETE` | `/api/tasks/{task_id}` | 删除任务 |
| `POST` | `/api/chat` | 发送消息 |
| `POST` | `/api/question` | 回答问题 |
| `GET/PUT` | `/api/config` | 系统配置 |
| `GET/POST/PUT/DELETE` | `/api/agents` | 代理 CRUD |
| `GET/POST/PUT/DELETE` | `/api/channels` | 通道 CRUD |
| `GET` | `/api/agents/{name}/config` | 获取代理配置 |
| `GET/POST/DELETE` | `/api/agents/{name}/sessions` | 统一会话管理 |
| `GET` | `/api/agents/{name}/sessions/{sid}/messages` | 消息历史 |
| `POST` | `/api/agents/{name}/sessions/{sid}/prompt` | 发送消息 |
| `GET` | `/api/agents/{name}/events` | SSE 事件流 |
| `POST` | `/api/agents/{name}/questions/{rid}/reply` | 回答问题 |
| `POST` | `/api/agents/{name}/questions/{rid}/reject` | 拒绝问题 |
| `POST` | `/api/voice/tts` | 语音合成 → audio/mpeg |
| `GET` | `/api/voice/health` | 语音服务健康检查 |
| `GET/POST` | `/api/voice/settings/asr` | ASR 设置 |
| `GET/POST` | `/api/voice/settings/tts` | TTS 设置 |
| `GET` | `/ws` | WebSocket 端点（`?token=`） |
| `GET` | `/health` | 健康检查 |

## WebSocket 协议

```
ws://host/ws?token=<token>
```

**Client → Server**:
```json
{"type":"subscribe",         "task_id":"..."}
{"type":"chat",              "content":"...",  "task_id":"..."}
{"type":"question_answer",   "request_id":"...",  "answer":"..."}
{"type":"ping"}
```

**Server → Client**:
```json
{"type":"subscribed"}
{"type":"tasks",   "action":"list|created|switched|deleted|paused",  "data":[...]}
{"type":"log",     "data":{...}}
{"type":"question",  "action":"new|resolved|cancelled|rejected",  "data":{...}}
{"type":"chat_ack",  "ok":true|false}
{"type":"pong"}
```

## 语音服务

ASR + TTS 作为独立 FastAPI 子进程运行（默认 3725 端口）。

### ASR（Vosk）

- 协议：WebSocket `ws://127.0.0.1:3725/ws/asr`
- 音频：16kHz PCM mono 16-bit
- 流程：`config` → 二进制音频帧 → `flush` → 转录结果
- 模型：`vosk-model-small-cn-0.22`（42MB）

### TTS（Edge-TTS）

- 端点：`POST /tts/stream` → audio/mpeg
- 引擎：Microsoft Edge TTS（免费，无需 API Key）
- 支持 19 种语音（中文/英文/日文，男女声）
- 默认：`zh-CN-XiaoxiaoNeural`

### 模型下载

```bash
python -m agw.voice.download_model
```

## 数据文件

数据库 `~/.agw/workspace/data/agw.db`（SQLite，WAL 模式）：

| 表 | 说明 |
|----|------|
| `agents` | 代理配置 |
| `channels` | 通道配置 |
| `bindings` | Session 绑定 |
| `tasks` | 任务元数据 |
| `logs` | 消息日志 + Question 记录 |
| `board_items` | 看板卡片 |

## 优雅退出

- 一次 Ctrl+C：停止接受新连接 → WebSocket 关闭（每连接 3s 超时） → cleanup
- 3s 未完成 → 守护线程强制 `os._exit(0)`
- 二次 Ctrl+C → 立即 `os._exit(1)`

## 依赖

- `aiohttp>=3.8.0` — HTTP 服务
- `lark-oapi>=1.0.0` — 飞书 SDK
- `pydantic>=2.0.0` — 配置模型
- `httpx>=0.25.0` — HTTP 客户端
- `loguru>=0.7.0` — 日志
- `aiosqlite>=0.17.0` — 异步 SQLite
- `rich>=13.0.0` — 终端输出
- （可选）`vosk`, `edge-tts`, `fastapi`, `uvicorn[standard]`, `numpy` — 语音

## 当前开发状态

### 已完成
- ✅ 新版 AgentProxy 1:1 架构设计（每个后端一个实例）
- ✅ 三种模式统一通信路径
- ✅ 统一消息格式（`agent_event`）
- ✅ SSE 事件直通前端
- ✅ 删除 Human-in-the-Loop 问题功能

### 测试中
- ⏳ 直联模式对话流程
- ⏳ 群聊模式日志记录
- ⏳ 任务模式看板功能

### 测试命令

```bash
python test/mock_agent_server.py          # Mock 后端，随机延迟 5-10s
python test/mock_multi_agent.py           # 多 Mock 后端（3 个 agent）
python test/mock_travel_agents.py         # 旅行团建 Mock 后端（4 个 agent）
python test/test_workflow_e2e.py          # 端到端主流程测试
python test/test_workflow_edge_cases.py   # 边界场景测试
python test/test_travel_workflow.py       # 三亚团建计划工作流测试
```