多 Agent 平台

Go + Vue 3 多 Agent 实时协作平台。从零构建，完全可观测的白盒 Agent。 仓库地址： https://github.com/ayanmw/multi-agent-platform 模块路径： github.com/ayanmw/multi-agent-platform 当前版本：v0.16.0 Alpha Phase 状态：0–6 已完成，Skill / TODO / Cron / Case 矩阵(21 个 L1-L5) 与 UI-v2、7-H2 编排闭环已落地；N0 缺陷修复（AgentBus 路由 + 多轮历史自复制）+ N1 企业级核心（多轮历史回读 / AgentBus 双向闭环 / RBAC / Shell 沙箱安全降级 / Agent CRUD 前端 / 全资源审计）+ N2 质量加固（维度化 /metrics + 事件完整性校验 + tracing 串联 + 测试覆盖）均已落地

快速开始

0. MCP（Model Context Protocol）支持

平台支持接入外部 MCP Server，把它们的工具扩展为 Agent 可调用的内置工具。接入方式分为五类：

方式	适用场景	配置位置	持久化
静态配置	启动时必须存在的 server	`MCP_SERVERS` 环境变量	仅内存，重启需重新配置
动态 API	运行时手动增删改	`POST /api/mcp/servers`	写入 `mcp_servers` 表
内置市场安装	使用平台自带的示例 server	`default` static market	写入 `mcp_servers` 表
SSE 远程 Server	远程 HTTP+SSE MCP server	`MCP_SERVERS` 或 API	写入 `mcp_servers` 表
远程 Marketplace	从外部 URL 拉取 catalog	`MCP_MARKETS` 环境变量	市场本身不持久化，安装后的 server 写入 `mcp_servers` 表

工具命名

接入后的 MCP 工具在注册表中统一命名为 mcp__<server>__<tool>。例如 time Server 的 get_current_time 工具对 Agent 可见为 mcp__time__get_current_time。Agent 的 system prompt 或手动调用时均应使用这个全名。

静态配置加载的 Server 不可通过 API 删除，但可启用/禁用。

方式一：静态配置（stdio）

启动时通过环境变量加载，适合随服务必须存在的本地 MCP server：

export MCP_SERVERS='[
  {"name":"time","transport":"stdio","command":"node","args":["examples/mcp/time/mcp-time-server.js"],"enabled":true},
  {"name":"calc","transport":"stdio","command":"node","args":["examples/mcp/calc/mcp-calc-server.js"],"enabled":true}
]'
go run ./cmd/server

方式二：运行时动态 API

# 列出已配置的 server
curl http://localhost:8080/api/mcp/servers

# 添加一个 stdio server（启用并立即连接）
curl -X POST http://localhost:8080/api/mcp/servers \
  -H 'Content-Type: application/json' \
  -d '{"id":"local-time","config":{"name":"local-time","transport":"stdio","command":"node","args":["examples/mcp/time/mcp-time-server.js"]},"enabled":true}'

# 启用 / 禁用 / 删除动态 server
curl -X POST http://localhost:8080/api/mcp/servers/local-time/enable
curl -X POST http://localhost:8080/api/mcp/servers/local-time/disable
curl -X DELETE http://localhost:8080/api/mcp/servers/local-time

方式三：从内置市场安装

启动后会自动注册 default static market，包含 local-time 和 local-calc 两个示例。市场 catalog 通过 go:embed 内嵌在二进制中，无需外部 markets/default.json 文件：

# 列出已注册市场
curl http://localhost:8080/api/mcp/markets

# 查看 default 市场里的包
curl http://localhost:8080/api/mcp/markets/default/servers

# 安装 local-time 到本地并启用
curl -X POST http://localhost:8080/api/mcp/markets/default/servers/local-time/install

方式四：SSE transport 远程 MCP server

适合接入远程 MCP server（例如用 Python/Node 部署在另一台机器或容器中的服务）：

# 静态配置
export MCP_SERVERS='[
  {"name":"remote-time","transport":"sse","endpoint":"http://localhost:3001/sse","enabled":true}
]'
go run ./cmd/server

# 或运行时用 API 添加
curl -X POST http://localhost:8080/api/mcp/servers \
  -H 'Content-Type: application/json' \
  -d '{"id":"remote-time","config":{"name":"remote-time","transport":"sse","endpoint":"http://localhost:3001/sse"},"enabled":true}'

SSE 握手流程：平台先向 /sse 发起 GET，等待 event: endpoint 返回 JSON-RPC POST URL，之后所有请求 POST 到该 endpoint，响应通过 SSE event: message 返回。

方式五：从远程 Marketplace 安装

通过 MCP_MARKETS 注册任意符合 catalog 格式的 JSON URL：

export MCP_MARKETS='[
  {"name":"opencode","url":"https://example.com/opencode-mcp-catalog.json"}
]'
go run ./cmd/server

# 查看该市场的包
curl http://localhost:8080/api/mcp/markets/opencode/servers

# 安装
curl -X POST http://localhost:8080/api/mcp/markets/opencode/servers/remote-time/install

远程 market catalog 格式示例：

{
  "version": "1.0.0",
  "markets": [
    {"name": "opencode", "display_name": "OpenCode Market", "description": "社区 MCP server 集合"}
  ],
  "servers": [
    {
      "id": "remote-time",
      "market": "opencode",
      "name": "Remote Time",
      "description": "返回远程服务器时间",
      "transport": "sse",
      "endpoint": "http://example.com/time/sse"
    }
  ]
}

MCP REST API 一览

方法	路径	说明
GET	`/api/mcp/servers`	列出所有 managed server 及加载状态
POST	`/api/mcp/servers`	添加动态 server
POST	`/api/mcp/servers/:id/enable`	启用并连接 server
POST	`/api/mcp/servers/:id/disable`	禁用并断开 server
DELETE	`/api/mcp/servers/:id`	删除动态 server（静态 server 会返回 403）
GET	`/api/mcp/markets`	列出已注册 market
GET	`/api/mcp/markets/:market/servers`	列出 market 中的包
POST	`/api/mcp/markets/:market/servers/:id/install`	安装包为本地 managed server

前端管理

接入的 MCP Server 及其工具在前端 MCP Server 管理 弹窗中可视化：🔄 刷新列表、🏪 从市场安装、➕ 手动添加，以及启用/禁用/删除动态 Server。安装自市场的 Server 会持久化到 mcp_servers 表，重启后仍保留。

Server 启用/禁用或工具数量变化时，平台会通过 WebSocket 发送 mcp_tools_changed 事件，前端会自动刷新可用工具列表。

常见问题

stdio server 启动失败：请确认 command 在 PATH 中，且 args 路径相对于 server 工作目录正确。示例默认从仓库根目录运行。
SSE server 连不上：先直接用浏览器或 curl 访问 SSE endpoint，应返回 Content-Type: text/event-stream 并先输出 event: endpoint 行。
Agent 看不到工具：检查 server 是否处于 loaded=true 状态；工具名称需使用 mcp__<server>__<tool> 全名。
远程 market 加载失败：server 启动日志会输出 warning；MCP_MARKETS 中某个 URL 失败不会影响其他 market 或 server 启动。

1. 配置

# 编辑 .env 文件（LLM endpoint / API key / 模型配置）
# 已有默认值，本地测试通常无需修改
cp .env.example .env

2. 编译运行

cd web && npm run build && cd ..
# v2 前端（默认即 v2，按需构建）：控制室风格 UI
cd web/v2 && npm run build && cd ..
# 单文件部署：前端 web/dist/* (v1) 与 web/v2/dist/* (v2) 均嵌入 Go 二进制
go build -o server.exe ./cmd/server/
./server.exe --port 8080
# 根路径 / 默认服务 v2；/ui/v1/ 访问旧版 v1（无需环境变量，由 web/embed.go 的 UIVersionsRegistry 与 URL 路径分发）

3. 端到端测试（推荐）

# 运行后端冒烟测试
bash scripts/smoke-test.sh

# PowerShell 环境
.\scripts\smoke-test.ps1

# 21 个内置 Case 的 mock 回归（确定性，无需真实 LLM）
bash scripts/cases-regression.sh

# multi-agent 编排端到端（mock）
bash scripts/multi-agent-smoke.sh

# 真实 LLM 冒烟（需配置 .env）
bash scripts/real-llm-smoke.sh
#   可选：SKIP_PARTB=1 只跑 Part A 6 场景（省时省钱）
#         SMOKE_FRESH=1 启动前清空隔离产物目录
#   产物自动落到 workspace/smoke-server/run-<ts>-<pid>/，不污染仓库根目录


# go的sample客户端测试(非最新)
# 编译
go build -o e2e-test.exe ./cmd/e2e-test/

# 启动 server 后运行测试
./e2e-test.exe --scenario all

# 仅测试简单对话
./e2e-test.exe --scenario simple

# 仅测试工具调用
./e2e-test.exe --scenario tool

4. 开发模式

# 前端独立热重载
cd web
npm install
npm run dev

5. 生产部署（认证加固）

⚠️ 生产环境必须开启鉴权。 默认 REQUIRE_AUTH=false 仅用于本地开发，服务启动时会打印强告警（AUTH DISABLED）。任何以默认配置暴露到网络的部署都是不安全的。

# .env —— 生产最小安全配置
REQUIRE_AUTH=true                 # 强制所有受保护路由校验 API key
# PRIVILEGED_ROUTES_REQUIRE_KEY=true  # 默认即 true：即便 REQUIRE_AUTH=false 时，
                                      # 特权写路由(agents/cases/tools/mcp/...)与
                                      # 敏感读(audit/traces)仍要求 API key

认证模型（API key + RBAC）：

平台使用 API key 认证（非密码）。每个用户可拥有多个 key，以 bcrypt 哈希存储，明文 key 仅创建时返回一次。
三角色：admin / developer(=user) / viewer。缺 role 按 viewer fail-closed（只读）。
敏感写路由（agents / cases / tools / mcp / model 价格 / api-keys）仅 admin 可操作；运营类写（sessions 删除、provider/model 同步）admin+developer 可操作。
引导流程：REQUIRE_AUTH=false 时，先 POST /api/auth/api-keys 创建首个 key（该端点刻意保持开放，否则无法建第一个 key），此后特权 mutation 必须携带 Authorization: Bearer <key>。

生产部署清单：

设置 REQUIRE_AUTH=true。
将服务置于反向代理 / 防火墙之后，仅暴露必要端口；不要在公网直接暴露 /api/*。
通过 POST /api/auth/api-keys 为管理员创建 key，并妥善保管（明文仅返回一次）。
保持 PRIVILEGED_ROUTES_REQUIRE_KEY=true（默认），不要让特权写路由在无 key 下可达。
密钥/凭证不入 VCS（.gitignore 已覆盖 *.txt 凭证与 .env）；.env 与 key 文件单独管理。

6. curl 手动验证

# 健康检查
curl http://localhost:8080/healthz

# 指标
curl http://localhost:8080/metrics

# 创建任务
curl -X POST http://localhost:8080/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"action":"chat","input":"1+1=?"}'

# WebSocket 实时事件（运行任务后）
# wscat -c 'ws://localhost:8080/ws?session_id=<session_id>'

项目结构

cmd/
  server/                  # 服务入口：HTTP Server + API 路由 + WS Hub
  server/mcp_api.go        # MCP Server 管理 REST API（新增）
  e2e-test/                # 端到端测试工具（WebSocket 事件着色打印）
internal/
  agent/                   # Agent 类型定义
  auth/                    # API key / 用户 / 角色 / 认证中间件
  cases/                   # 预设 Task Cases（21 个 L1-L5 内置 + 自定义 CRUD）
  config/                  # .env 加载 + 配置管理（含 MCP_SERVERS）
  cost/                    # CostTracker + CostBudgetRule
  cron/                    # Cron / 定时器子系统（4 种 action + robfig/cron 调度）
  harness/                 # PolicyChain / TaskContract / ApprovalRule
  llm/                     # LLM Provider 抽象 + OpenAI/Anthropic/DeepSeek + MockProvider（含 22 个内置 mock 脚本）
  memory/                  # 记忆召回、作用域、上下文压缩
  observability/           # 结构化日志 + Prometheus metrics + /healthz + Tracer
  orchestrator/            # 多 Agent 编排（parallel/sequential/DAG/leader-driven）
  pool/                    # Worker Pool 并发调度
  runtime/                 # ReAct Loop 引擎 + Step 状态机 + 持久化
  skill/                   # 可复用 Skill prompt 包（Registry / Store / Renderer）
  todo/                    # Session 级 TODO 子系统
  tool/                    # Tool 注册表 + 内置工具 + 运行时注册
  tool/mcp/                # MCP Client / Manager / Repository / 示例（新增）
  version/                 # 版本信息 + go:embed
  ws/                      # WebSocket Hub
pkg/
  db/                      # SQLite Schema（28 张表）、迁移 v35、CRUD
  event/                   # 统一事件结构 + 序列化
web/                       # Vue 3 + Vite + TypeScript 前端（v1）
web/v2/                    # Observable Control Room 前端（v2，默认根路径服务）
docs/                      # 历史/未来 Markdown 文档
roadmaps/                  # ROADMAP.md 路线图 + 版本史
doc/                       # HTML 格式项目文档（部分章节可能已过时）
openspec/                  # OpenSpec 变更产物（changes/ + specs/）
scripts/                   # 测试/发布脚本（smoke-test.sh、cases-regression.sh、multi-agent-smoke.sh、real-llm-smoke.sh 等）
data/                      # SQLite 数据库文件
storage/                   # 文件存储
examples/mcp/              # MCP Server 示例（time / calc）

架构概览

用户输入
  → POST /api/tasks 或 POST /api/sessions/:id/chat
  → Router 意图分类 / 模型选择
  → ReAct Engine
      Step 0: think (LLM ChatStream → SSE → llm_delta 事件)
      Step 1: tool_call → PolicyGate (Approval / Budget / Whitelist)
      Step 2: observe → loop
  → 超过 max_steps → task_failed (max_steps_exceeded)
  → 最终答案 → task_completed
  → WebSocket Hub 实时广播

当前状态

v0.16.0 Alpha — Phases 0–6 已完成，Skill / TODO / Cron 子系统、21 个 L1–L5 Case 矩阵、UI-v2 控制室与 multi-agent 编排闭环均已落地；N0 缺陷修复 + N1 企业级核心（多轮历史回读 / AgentBus 双向闭环 / RBAC / Shell 沙箱安全降级 / Agent CRUD 前端 / 全资源审计）+ N2 质量加固（维度化 /metrics + 事件完整性校验 + tracing 串联 + 测试覆盖）均已落地。

功能	状态	说明
WebSocket 实时通信	✅	gorilla/websocket，事件驱动，多客户端广播
ReAct Loop 引擎	✅	think → tool_call → observe，支持 max_steps / timeout
内置工具	✅	run_shell、write_file、read_file + 运行时注册
MCP 工具扩展	✅	stdio / SSE transport + Manager 生命周期 + 动态 API + 远程 marketplace
工具沙箱	✅	Docker 安全隔离 run_shell；无 Docker 环境启用安全降级（危险命令黑名单 + allow/ask/deny 默认 deny + 审计，防御纵深，N1-04）
DB 持久化	✅	modernc.org/sqlite，28 张表，迁移至 v35
Vue 3 + Vite 前端	✅	TypeScript、useTaskStore、useWebSocket；`web/v2/` 控制室风格 UI 为默认（根路径 `/`），`/ui/v1/` 保留旧版
Session / Project	✅	multi-turn chat，Project 分组，Session 历史
多 Agent 并发	✅	并行派发，前端多树渲染；leader-driven dispatch_sub_agent 主链路（Phase 7-H2）+ AgentBus 双向闭环（LLM 经 send_agent_message 工具主动收发 agent message，N1-02）
Memory	✅	scope=session/project/global，向量召回，上下文压缩
Auth	✅	API key + bcrypt，可配置 REQUIRE_AUTH（默认 false，启动强告警）；RBAC 资源-动作矩阵（viewer / developer / admin 三角色，fail-closed，N1-03）；N3-01 认证加固：即便 REQUIRE_AUTH=false，特权写路由（agents/cases/tools/mcp/...）与敏感读（audit/traces）仍要求有效 API key，消除默认无鉴权暴露面
RAG	✅	LocalEmbeddingProvider + InMemoryVectorStore + `/api/memories/recall`
成本 / 可观测性	✅	CostTracker、维度化 /metrics（agent/session/step + per-agent LLM/Tool 延迟直方图）、/healthz、结构化日志、tracing 串联（?task_id/agent_id/limit 过滤）、事件完整性校验（非法事件计入 malformed 不丢数据，N2-01）
Checkpoint / Recovery	✅	任务检查点 + 崩溃恢复
Skill 系统	✅	可复用 prompt 包 + Renderer + Registry + REST API + 前端 SkillPicker
TODO 子系统	✅	session 级 TODO + 6 个 Agent Tools + `/api/todos` + 前端拖拽/嵌套
Cron / 定时器	✅	4 种 action_type + robfig/cron 秒级调度 + 事件化 + 前端管理 UI
Case 矩阵	✅	21 个内置 Case（L1-L5 阶梯）+ mock 回归 21/21 + LLM Judge 验收
可配置 timeout	✅	TaskContract.TimeoutSeconds，0 表示无限制
Provider Router	✅	多厂商 Provider + fallback 降级

文档组织

根 README.md — 当前项目状态摘要与快速开始。
docs/ — 历史实施与未来规划 Markdown：
- API_CHANGELOG.md — API 契约与前端适配建议
- History.md — 每次修复/优化批次的详细记录
- IMPLEMENTATION_PLAN.md — 测试阶段实施计划（已归档）
- PHASE7_PLAN.md — Phase 7 规划
- TEST_REPORT.md / TEST_COVERAGE_REPORT.md — 测试报告
roadmaps/ROADMAP.md — 完整路线图 + 版本历史。
doc/ — HTML 格式的项目文档。部分章节的内容可能已被后续 Markdown 文档覆盖或替代；遇到过时片段请参考 docs/History.md、docs/API_CHANGELOG.md 与 roadmaps/ROADMAP.md 中的最新记录。

设计文档

CLAUDE.md — 项目设计哲学 + 编码约定 + 事件系统 + API 配置
roadmaps/ROADMAP.md — 路线图 + 版本历史
openspec/changes/ — OpenSpec 变更产物（proposal / design / tasks）
doc/chapters/*.html — 早期产品文档（HTML 格式，部分内容已逐步迁移至 docs/）

Navigation Menu

Repository files navigation

多 Agent 平台

快速开始

0. MCP（Model Context Protocol）支持

工具命名

方式一：静态配置（stdio）

方式二：运行时动态 API

方式三：从内置市场安装

方式四：SSE transport 远程 MCP server

方式五：从远程 Marketplace 安装

MCP REST API 一览

前端管理

常见问题

1. 配置

2. 编译运行

3. 端到端测试（推荐）

4. 开发模式

5. 生产部署（认证加固）

6. curl 手动验证

项目结构

架构概览

当前状态

文档组织

设计文档

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 567 Commits
.claude		.claude
.github/workflows		.github/workflows
cmd		cmd
doc		doc
docs		docs
examples/mcp		examples/mcp
internal		internal
openspec		openspec
pkg		pkg
roadmaps		roadmaps
scripts		scripts
web		web
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
version.txt		version.txt

Folders and files

Latest commit

History

Repository files navigation

多 Agent 平台

快速开始

0. MCP（Model Context Protocol）支持

工具命名

方式一：静态配置（stdio）

方式二：运行时动态 API

方式三：从内置市场安装

方式四：SSE transport 远程 MCP server

方式五：从远程 Marketplace 安装

MCP REST API 一览

前端管理

常见问题

1. 配置

2. 编译运行

3. 端到端测试（推荐）

4. 开发模式

5. 生产部署（认证加固）

6. curl 手动验证

项目结构

架构概览

当前状态

文档组织

设计文档

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages