内容
<p align="center">
<h1 align="center">Agent Team</h1>
<p align="center">
<strong>Loop Engineering Engine — Let AI Agent Teams Deliver Verifiable Software</strong>
</p>
<p align="center">
<a href="#license"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node.js"></a>
<a href="https://github.com/PandaKing2021/loop-studio"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
</p>
</p>
---
**Agent Team** 是一个开源的 Loop Engineering 引擎——你用它组建 AI Agent 团队，给团队下一个目标，Agent 们自主完成需求分析、任务拆解、编码、Code Review、测试验证和知识沉淀的全过程，交付经过独立验证的可运行软件。
与主流多 Agent 框架不同的是，Agent Team 的核心设计哲学是 **"写完不算完，验证通过才算完"**。每一个子任务都要经过独立 Reviewer 的结构化审查，每一轮交付都要通过质量门禁检查。这不是 Demo——它经过了 196 项系统化测试的真实验证，可以在你的项目、你的服务器、甚至你朋友的电脑（通过 SSH 远程执行）上跑真活儿。
---
## 目录
- [为什么选择 Agent Team](#为什么选择-agent-team)
- [快速开始](#快速开始)
- [核心概念](#核心概念)
- [关键能力](#关键能力)
- [架构设计](#架构设计)
- [协议与生态](#协议与生态)
- [外部 Agent 接入](#外部-agent-接入)
- [CLI 命令行](#cli-命令行)
- [部署](#部署)
- [文档](#文档)
- [测试覆盖](#测试覆盖)
- [项目结构](#项目结构)
- [技术栈](#技术栈)
- [路线图](#路线图)
- [贡献指南](#贡献指南)
- [License](#license)
---
## 为什么选择 Agent Team
### 我们解决的问题
当前的多 Agent 框架在 Demo 中表现惊艳，但一上真实项目就暴露出共同的问题：
| 痛点 | 典型表现 | Agent Team 的方案 |
|------|---------|-------------------|
| **没有真正的验证** | Agent 写完代码自己说"没问题"就结束了 | **Verify-Separation**：独立 Reviewer + Tester 分离审查，强制跑测试 |
| **上下文断裂** | 跑到第四个子任务就忘了最初的需求 | **三层记忆系统**：近期全文 + 远期摘要 + 共享黑板，持久化不丢失 |
| **并行冲突** | 多 Agent 共享工作区，写入互相覆盖 | **Git Worktree 隔离**：每个 Agent 独立工作副本 + 自动合并 |
| **没有恢复能力** | 中间一步失败，全部进度作废 | **断点恢复**：子任务级事务持久化，重启后从未完成的步骤继续 |
| **交付边界受限** | Agent 只能在本地开发机运行 | **5 种执行后端**：SSH 远程、Docker、K8s、本地、远程服务 |
### 与主流框架的差异化定位
| 维度 | LangGraph | CrewAI | MetaGPT | **Agent Team** |
|------|-----------|--------|---------|----------------|
| Loop Engineering | 部分 | 无 | 部分 | **完整闭环** |
| Verify-Separation | 无 | 无 | 弱 | **强制独立审查** |
| 质量门禁 | 无 | 无 | 无 | **5 维度 Go/No-Go** |
| 外部 Agent 双角色接入 | 无 | 无 | 无 | **员工 + 大脑 两种身份** |
| 远程 SSH 部署执行 | 无 | 无 | 无 | **真实可用** |
| 引擎优先（无 HTTP 依赖） | 无 | 无 | 无 | **`import` 即用** |
| MCP + A2A 双协议 | 无 | 无 | 无 | **完整实现** |
| Skill 约束系统 | 无 | 无 | 无 | **Markdown 文档即能力** |
---
## 快速开始
### 环境要求
- **Node.js** ≥ 18（推荐 20+）
- **npm** ≥ 10
- **Git**
- 一个 **LLM API Key**（支持 DeepSeek、OpenAI、Anthropic、Gemini 及任何 OpenAI 兼容接口）
### 三步跑起来
```bash
# 1. 克隆并安装
git clone https://github.com/PandaKing2021/loop-studio.git
cd loop-studio
npm run install:all
# 2. 配置 API Key
cp .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY 或 LLM_API_KEY
# 3. 启动
npm run dev
```
打开浏览器访问 `http://localhost:5173`：
1. 进入 **设置** → 配置模型提供商
2. 进入 **团队模板** → 选择"工程交付团队"
3. **新建团队** → 绑定工作区 → **下发使命** → **启动**
4. 在 **团队详情** 页实时查看 Agent 们的执行过程
> **不想用 Web 界面？** 引擎可以直接 import，也可以纯 CLI 操作：
> ```bash
> node src/cli.js list # 查看团队
> node src/cli.js team mission <id> --goal "实现用户登录" # 下发使命
> node src/cli.js team run <id> --watch # 执行并观察
> ```
> 详见 [ENGINE.md](ENGINE.md)。
---
## 核心概念
### Loop Engineering — 循环工程
传统的 Plan → Execute → Done 线性流程无法处理"验证失败需要返工"的基本场景。Agent Team 采用的是 **Discover → Plan → Execute → Verify → Iterate** 的循环模型：
```
┌─────────────────────────────────────────┐
│ │
▼ │
Discover ──→ Plan ──→ Execute ──→ Verify │
▲ │ │ │
│ NOT DONE ◄┘ │ │
│ │ │
└─────────────────────────────────┘ │
DONE ↓ │
交付 │
```
每一个环节失败都不是整体失败，而是**触发下一轮迭代**——这是"循环"的意义。
### Verify-Separation — 验证分离
写代码的 Agent 和做审查的 Agent 必须是不同的实例。这不是"不信任"——而是软件工程的基本原则：**确认偏差（confirmation bias）会让自测形同虚设。**
Agent Team 的 Reviewer 会从六个维度独立审查：
- 代码正确性
- 需求对齐度
- 安全性
- 测试覆盖率
- 代码风格
- 性能影响
### Engine-First — 引擎优先
核心逻辑是纯粹的 JavaScript 函数库（`src/core.js`，34 模块，~280 函数），不依赖 HTTP、不依赖前端。四种调用方式共享同一引擎：
| 调用方式 | 入口 | 适用场景 |
|----------|------|---------|
| **引擎直调** | `import { bootstrap } from './src/core.js'` | 编程集成、CI/CD 脚本 |
| **CLI** | `node src/cli.js` | 命令行操作、自动化 |
| **REST API** | `npm start` | 外部系统集成 |
| **Web 控制台** | 可选，需构建前端 | 可视化操作 |
---
## 关键能力
### 1. 可部署性 — Agent 团队"空降"到任何机器
Agent Team 支持 **5 种执行后端**，覆盖从本地开发到远程生产的所有场景：
| 执行后端 | 适用场景 | 安全隔离 |
|----------|---------|---------|
| **native** | 本地快速迭代 | 环境变量白名单 |
| **docker** | 标准容器部署 | `--network none` + `--read-only` + `--cap-drop=ALL` |
| **kubernetes** | 大规模集群 | NetworkPolicy + securityContext |
| **ssh** | 远程服务器（无预装环境） | strictHostKeyChecking + 私钥权限检查 |
| **service** | 远程常驻 HTTP 服务 | Token 认证 |
SSH 后端最具"空降"能力：Agent 登录一台什么环境都没有的机器 → 自动检测并安装缺失工具 → 同步源码 → 修复问题 → 验证通过 → 提交产物。全程不需要远程机器上有人操作。
### 2. Skill 系统 — 能力即文档
Skill 不是代码插件，而是一份结构化 Markdown 文档，在 Agent 执行时注入到系统提示中。每个 Skill 包含：
- 意图匹配（何时激活）
- 输入/输出格式
- 执行步骤
- 约束规则（`required_files`、`forbidden_patterns`、`test_command` 等）
Reviewer 审查时会**逐条硬校验**这些约束。Coder 漏了某个必输出文件？Reviewer 直接 REJECT。团队中多个 Skill 同时激活时，通过 `produces`/`consumes` 契约自动声明上下游依赖关系。
内置 36 个 Skill 覆盖 Express REST API、安全编码、代码审查、API 测试等领域。你可以随时创建新 Skill——不需要改任何代码。
### 3. 外部 Agent 双向接入 — 既是"手脚"也是"大脑"
这一能力在同类框架中极为罕见。
**作为"手脚"** — 让外部 AI 成为团队正式成员。支持 4 种接入通道（HTTP 回调、A2A 协议、MCP 协议、Service 后端），接入后被分配子任务、注入上下文、接收审查，和其他 Agent 完全一样。
**作为"大脑"** — 让外部 AI 操控平台。通过 35 个 MCP 工具或 A2A 扩展方法，外部 AI 可以创建团队、下发使命、与 LEAD 对话、审批 Plan、中途注入补充消息。最极端的情况：人类用自然语言对企业微信说话 → 机器人调用 Agent Team → 团队自主完成全套开发 → 结果自动返回。全程人类没打开任何界面。
### 4. 自进化与知识沉淀
Agent Team 在运行中自动沉淀三类知识：
- **ERRORS.md** — 记录错误类型、触发条件和解决方案
- **LEARNINGS.md** — 从成功任务中提取可复用的经验
- **避坑卡片（Pitfall Cards）** — 失败教训自动记录，下次同类任务自动注入警告
### 5. 质量门禁体系
5 维度 Go/No-Go 质量门禁，包含一票否决项：
- 核心任务质量（成功率红线）
- 性能与并发韧性
- 成本与 Token（预算熔断）
- 安全与沙箱（路径穿越 / 注入检测）
- 交付与回滚
---
## 架构设计
```
┌──────────────────────────────────────────────────────────────────┐
│ Engine-First Architecture │
├──────────────────────────────────────────────────────────────────┤
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Core Engine (src/core.js) │ │
│ │ 34 modules / ~280 functions / Pure JS Library │ │
│ │ Zero HTTP dependency, import & go │ │
│ └────────────────────────────────────────────────────────────┘ │
│ ↑ ↑ ↑ ↑ │
│ ┌──────┴──────┐ ┌─────┴─────┐ ┌──────┴──────┐ ┌─────┴─────┐ │
│ │ CLI │ │ Server │ │ MCP │ │ A2A │ │
│ │ 80+ commands │ │ REST API │ │ 35 Tools │ │ External │ │
│ │ Ops & CI/CD │ │187 Endpts │ │ AI Clients │ │ Agents │ │
│ └─────────────┘ └─────┬─────┘ └─────────────┘ └───────────┘ │
│ ┌──┴──┐ │
│ │ Web │ ← Optional Dashboard │
│ │React│ (works without it) │
│ └─────┘ │
├──────────────────────────────────────────────────────────────────┤
│ Team Orchestrator │ Executor Backend │ Context Engine │
│ (Mission → Plan │ (5 Backends: │ (3-Tier Memory: │
│ → Dispatch │ native/docker │ recent full-text │
│ → Maker-Checker │ /k8s/ssh/service)│ + distant summary │
│ → Verify) │ │ + team blackboard) │
├──────────────────────────────────────────────────────────────────┤
│ Quality Gate │ MCP Protocol │ A2A Protocol │ Knowledge DB │
│ Security │ Smart Router │ Self-Improving│ Skill System │
├──────────────────────────────────────────────────────────────────┤
│ OpenClaw Runtime (Real LLM Agent Execution) │
│ ~/.openclaw/agents/<id>/ (SOUL.md / TOOLS.md / SKILL/) │
├──────────────────────────────────────────────────────────────────┤
│ Data Layer (SQLite WAL + FS) │
│ loop-studio.db │ worktrees/ │ blackboards/ │ sessions/ │
└──────────────────────────────────────────────────────────────────┘
```
### 内置 Agent 团队
| 角色 | ID | 职责 |
|------|----|------|
| 调度官 | `orchestrator` | 集群调度中枢，任务拆解与分配 |
| 架构师 | `architect` | 方案设计，验收标准制定 |
| 编码员 | `coder` | Worktree 内编码，最小改动原则 |
| 审查员 | `reviewer` | 6 维度独立审查，默认 REJECT |
| 测试员 | `tester` | 独立验证，强制运行测试命令 |
| 文档员 | `documenter` | 文档与 Changelog |
| 检索员 | `researcher` | 信息检索，联网搜索 |
| 探索员 | `searcher` | 项目结构扫描，技术栈识别 |
| Bridge Agent | `pm` | 用户与团队的中继，需求澄清和进度汇报 |
---
## 协议与生态
Agent Team 不是封闭系统。它通过标准协议与外部世界深度互操作：
### REST API — 187 个端点
覆盖团队、Agent、任务、工作区、知识、质量、成本、容器、审批、模板、Token、MCP/A2A、飞书集成等全部领域。每一个端点都有完整的请求/响应文档和 curl 示例。详见 [API 参考](docs/API_REFERENCE.md)。
### MCP 协议 — 35 个标准工具
实现了完整的 MCP Server（协议版本 2025-06-18），工具分为两大类别：
- **工作区操作（10 个）**：文件读写、命令执行、代码搜索、网页抓取
- **平台管理（25 个）**：团队管理、使命下发、Agent 管理、对话协作、监控日志、知识搜索、成本估算
每个工具都有 scope 权限映射，受限 Token 只能调用权限范围内的工具。外部 AI 客户端（Claude Desktop、Cursor、飞书机器人）可以直接连接 `http://host:3001/mcp` 来控制平台。
### A2A 协议 — 完整 Server + Client 实现
支持 JSON-RPC 2.0 标准 A2A 协议（tasks/send、tasks/get），并在 Agent Card 中声明 **4 个扩展方法**：
- `tasks/questions` — 查询 LEAD 待回答的提问
- `tasks/answer` — 回答指定提问
- `tasks/confirm` — 审批 Plan
- `tasks/message` — 注入补充消息
外部 AI 大脑可以**仅通过 A2A 一种协议**完成完整的"下发使命 → 回答提问 → 审批 → 观察"全流程。
### SSE 实时事件流
团队执行过程中的关键事件通过 Server-Sent Events 实时推送：`agent.started`、`agent.completed`、`agent.failed`、`subtask.started`、`subtask.completed`、`team.completed` 等。前端控制台和外部系统均可订阅。
---
## 外部 Agent 接入
### 以"员工"身份加入团队
| 接入通道 | 适合场景 | 外部需实现 |
|----------|---------|-----------|
| **HTTP 回调** | 自研脚本、云函数、LangChain | 接收任务的 POST 接口 |
| **A2A 协议** | 另一个 AI Agent 平台 | Agent Card + tasks/send/get |
| **MCP 协议** | 工具型 Agent | initialize + tools/list + tools/call |
| **Service** | 远程部署的常驻服务 | /health + /execute |
### 以"大脑"身份操控平台
```
人类用户 → 飞书/Claude/企业微信 → MCP/A2A/REST → Agent Team → Agent 团队
↑ ↓
└──────── 提问/回答/审批 ──────┘
```
详细接入指南见 `skills/external-agent-platform-control/skill.md`。
---
## CLI 命令行
CLI 直接调用引擎，无需启动 Server，80+ 子命令覆盖全部 14 个核心模块：
```bash
# 全局安装后可使用 agent-team 或 at 命令
npm link
# 团队管理
agent-team list # 列出团队
agent-team team start <id> # 启动
agent-team team mission <id> --goal "实现登录"
agent-team team run <id> --watch # 执行并实时观察
agent-team team pause <id> | resume <id> # 暂停/恢复
# Agent 管理
agent-team agent list # 列出 Agent
agent-team agent create --name "Go Dev" --role coder
agent-team agent clone <id> # 克隆 Agent
# 外部 Agent / MCP / A2A
agent-team a2a list # 列出外部 Agent
agent-team a2a add --name "my-ai" --url "https://..."
agent-team a2a send <id> --message "分析代码"
agent-team mcp sync <id> # 同步 MCP 工具
# 工作区 / 知识 / 质量
agent-team workspace add-url --url "https://github.com/user/repo.git"
agent-team knowledge search --mission "实现认证"
agent-team quality report # 质量门禁报告
agent-team cost estimate --mission "实现登录" --members 5
# 部署
agent-team deploy-platform --host 192.168.1.100 --user root --key ~/.ssh/id_rsa --llm-key sk-xxx
```
完整手册：[CLI 参考](docs/CLI_REFERENCE.md)
---
## 部署
### Docker
```bash
cd deploy/docker
docker build -t agent-team:latest -f Dockerfile ../..
docker-compose up -d
```
### Kubernetes
```bash
cd deploy/k8s
kubectl apply -f configmap.yaml
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml
```
### SSH 远程部署
```bash
# 部署完整平台到远程服务器
agent-team deploy-platform --host <ip> --user <user> --key <ssh-key> --llm-key <api-key>
# 部署轻量级 Agent 执行服务
agent-team deploy-team-service --host <ip> --user <user> --key <ssh-key>
```
---
## 文档
| 文档 | 说明 |
|------|------|
| [ENGINE.md](ENGINE.md) | 引擎使用手册：`import core.js` 编程集成 + 引擎与 Server/CLI/MCP/A2A 的关系 |
| [API 参考](docs/API_REFERENCE.md) | 187 个 REST 端点 + MCP/A2A 协议完整参考 |
| [CLI 参考](docs/CLI_REFERENCE.md) | 80+ 子命令，覆盖 14 个核心模块 |
| [用户手册](USER_MANUAL.md) | 名词概念解释 + 完整操作指南 |
| [技术博客](blog/tech-blog-zh.md) | 项目背景、设计思路和开发过程（~16,000 字） |
| [外部 Agent Skill](skills/external-agent-platform-control/skill.md) | 外部 AI 大脑操控平台的 MCP 指南 |
| [开源策略](OPEN_SOURCE_STRATEGY.md) | 差异化定位与社区运营路线图 |
| [测试计划](TEST_PLAN.md) | 10 维度 / 50 场景 / 215 用例测试设计 |
| [测试报告](TEST_REPORT_FINAL.md) | 196 用例 / 94.4% 通过率 / 生产就绪度评估 |
---
## 测试覆盖
经过系统化的全栈测试：
```
10 维度 / 12 生产场景 / 196 用例
188 PASS | 3 FAIL* | 5 SKIP
通过率 94.4%
*3 个 FAIL 均为测试环境 mock-agent 未运行，非功能缺陷
```
| 测试套件 | 用例数 | 覆盖领域 |
|----------|--------|---------|
| 基础冒烟 | 9 | 核心接口可用性 |
| Plan 解析 | 21 | 结构化方案拆解与质量校验 |
| 安全工具 | 16 | 路径穿越、注入检测、脱敏 |
| 级联删除 | 9 | 外键约束完整性 |
| CLI + API 综合 | 75 | CLI 19 模块 + API 27 端点 |
| 文件传输双向 | 26 | 运行期文件请求、上传、过期清理 |
| 并发安全 | 6 | 竞态、锁、SIGTERM→SIGKILL |
| 灾难恢复 | 16 | 崩溃恢复、Webhook 重试、断点续传 |
| 性能稳定性 | 8 | 响应延迟、内存占用、长时稳定性 |
| 生产场景 | 10 | SSH 跨 OS、多团队并发、大文件上传 |
---
## 项目结构
```
loop-studio/
├── src/ # Core Engine (34 modules)
│ ├── core.js # Unified entry (re-exports all modules)
│ ├── bootstrap.js # Shared init sequence
│ ├── server.js # HTTP server (Express)
│ ├── routes.js # REST API (~187 endpoints)
│ ├── cli.js # CLI (80+ subcommands)
│ ├── team-orchestrator.js # Mission → Plan → Dispatch → Verify
│ ├── executor-backend.js # 5 execution backends
│ ├── external-agent-executor.js# External agent executor (4 channels)
│ ├── a2a-protocol.js # A2A JSON-RPC (Server + Client)
│ ├── mcp-server.js # MCP protocol (35 tools)
│ ├── context-engine.js # 3-tier memory system
│ ├── smart-router.js # Complexity → model assignment
│ ├── self-improving.js # ERRORS/LEARNINGS/Pitfall Cards
│ ├── quality-gate.js # 5-dimension Go/No-Go
│ ├── knowledge.js # Experience reuse + pitfall cards
│ ├── agent-files.js # OpenClaw standard agent files
│ ├── agents.js # Agent definition + instantiation
│ ├── team-manager.js # Team CRUD + deploy + lifecycle
│ ├── team-template.js # Reusable team templates
│ ├── llm.js # LLM adapter (OpenClaw spawn)
│ ├── security.js # Secrets / Token / Sandbox policy
│ ├── safe-utils.js # Path traversal / injection guards
│ ├── cost-management.js # Token budget + cost estimation
│ └── ... # 16 more modules
├── web/ # Web Console (React 18 + Vite)
│ └── src/
│ ├── pages/ # 15 pages
│ ├── components/ # 16 shared components
│ ├── hooks/ # Custom hooks
│ └── lib/ # Status / format / constants
├── deploy/ # Deployment configs
│ ├── docker/ # Dockerfile + docker-compose + Prometheus
│ ├── k8s/ # Deployment/HPA/Ingress/RBAC/NetworkPolicy
│ └── scripts/ # Cross-platform install/bootstrap scripts
├── skills/ # OpenClaw standard Skills
│ ├── express-rest-api/skill.md
│ └── external-agent-platform-control/skill.md
├── docs/ # Documentation
│ ├── API_REFERENCE.md # 187 endpoints reference
│ └── CLI_REFERENCE.md # 80+ subcommands reference
├── test/ # Test suites (10 suites / 196 cases)
├── blog/ # Technical blog posts
├── experiment/ # Performance test data
└── paper/ # Academic paper
```
---
## 技术栈
| 层 | 技术 | 说明 |
|----|------|------|
| **后台** | Node.js 20+ | ESM，事件驱动 |
| **Web 框架** | Express 4 | 轻量 HTTP 包装 |
| **数据库** | better-sqlite3 | SQLite WAL 模式，22 张表 |
| **前端** | React 18 + Vite 5 | 纯 CSS 设计系统，无 UI 框架 |
| **LLM 运行时** | OpenClaw CLI | `spawn openclaw agent --json --local` |
| **协议** | A2A (JSON-RPC 2.0) <br> MCP (2025-06-18) <br> SSE | 三协议完整支持 |
| **容器** | Docker / Kubernetes | 安全加固部署 |
| **模型** | DeepSeek / OpenAI / Anthropic / Gemini / Ollama / 自定义 | 多 Provider + 跨 Provider 降级 |
---
## 路线图
欢迎社区贡献者参与以下方向的开发：
- [ ] **向量化语义搜索** — 将知识沉淀升级为语义匹配，跨任务类型复用经验
- [ ] **DAG 工作流引擎** — 让 Maker-Checker 流程从硬编码变为可配置的有向无环图
- [ ] **动态角色协商** — Agent 自主评估能力、协商分工，取代静态角色分配
- [ ] **更多执行后端** — AWS Lambda、GCP Cloud Run、边缘计算
- [ ] **VSCode 扩展** — 在编辑器中直接管理 Agent 团队
- [ ] **更多团队模板** — 适配更多开发场景的开箱即用模板
---
## 贡献指南
欢迎任何形式的贡献！无论是 Bug 报告、功能建议、代码 PR 还是文档改进。
请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发流程和代码规范。
### 贡献者
感谢所有为这个项目做出贡献的人 ✨
---
## 联系我们
- **GitHub Issues**: [问题报告与功能请求](https://github.com/PandaKing2021/loop-studio/issues)
- **GitHub Discussions**: [讨论与问答](https://github.com/PandaKing2021/loop-studio/discussions)
---
## License
MIT © 2026 Agent Team Contributors
---
<p align="center">
<sub>Built with ❤️ for the AI Engineering community</sub>
</p>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器