Loop Engineering Engine — Let AI Agent Teams Deliver Verifiable Software
Agent Team 是一个开源的 Loop Engineering 引擎——你用它组建 AI Agent 团队，给团队下一个目标，Agent 们自主完成需求分析、任务拆解、编码、Code Review、测试验证和知识沉淀的全过程，交付经过独立验证的可运行软件。
与主流多 Agent 框架不同的是，Agent Team 的核心设计哲学是 "写完不算完，验证通过才算完"。每一个子任务都要经过独立 Reviewer 的结构化审查，每一轮交付都要通过质量门禁检查。这不是 Demo——它经过了 196 项系统化测试的真实验证，可以在你的项目、你的服务器、甚至你朋友的电脑（通过 SSH 远程执行）上跑真活儿。
当前的多 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 兼容接口）
# 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：
- 进入 设置 → 配置模型提供商
- 进入 团队模板 → 选择"工程交付团队"
- 新建团队 → 绑定工作区 → 下发使命 → 启动
- 在 团队详情 页实时查看 Agent 们的执行过程
不想用 Web 界面？ 引擎可以直接 import，也可以纯 CLI 操作：
node src/cli.js list # 查看团队 node src/cli.js team mission <id> --goal "实现用户登录" # 下发使命 node src/cli.js team run <id> --watch # 执行并观察详见 ENGINE.md。
传统的 Plan → Execute → Done 线性流程无法处理"验证失败需要返工"的基本场景。Agent Team 采用的是 Discover → Plan → Execute → Verify → Iterate 的循环模型：
┌─────────────────────────────────────────┐
│ │
▼ │
Discover ──→ Plan ──→ Execute ──→ Verify │
▲ │ │ │
│ NOT DONE ◄┘ │ │
│ │ │
└─────────────────────────────────┘ │
DONE ↓ │
交付 │
每一个环节失败都不是整体失败，而是触发下一轮迭代——这是"循环"的意义。
写代码的 Agent 和做审查的 Agent 必须是不同的实例。这不是"不信任"——而是软件工程的基本原则：确认偏差（confirmation bias）会让自测形同虚设。
Agent Team 的 Reviewer 会从六个维度独立审查：
- 代码正确性
- 需求对齐度
- 安全性
- 测试覆盖率
- 代码风格
- 性能影响
核心逻辑是纯粹的 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 控制台 | 可选，需构建前端 | 可视化操作 |
Agent Team 支持 5 种执行后端，覆盖从本地开发到远程生产的所有场景：
| 执行后端 | 适用场景 | 安全隔离 |
|---|---|---|
| native | 本地快速迭代 | 环境变量白名单 |
| docker | 标准容器部署 | --network none + --read-only + --cap-drop=ALL |
| kubernetes | 大规模集群 | NetworkPolicy + securityContext |
| ssh | 远程服务器（无预装环境） | strictHostKeyChecking + 私钥权限检查 |
| service | 远程常驻 HTTP 服务 | Token 认证 |
SSH 后端最具"空降"能力：Agent 登录一台什么环境都没有的机器 → 自动检测并安装缺失工具 → 同步源码 → 修复问题 → 验证通过 → 提交产物。全程不需要远程机器上有人操作。
Skill 不是代码插件，而是一份结构化 Markdown 文档，在 Agent 执行时注入到系统提示中。每个 Skill 包含：
- 意图匹配（何时激活）
- 输入/输出格式
- 执行步骤
- 约束规则（
required_files、forbidden_patterns、test_command等）
Reviewer 审查时会逐条硬校验这些约束。Coder 漏了某个必输出文件？Reviewer 直接 REJECT。团队中多个 Skill 同时激活时，通过 produces/consumes 契约自动声明上下游依赖关系。
内置 36 个 Skill 覆盖 Express REST API、安全编码、代码审查、API 测试等领域。你可以随时创建新 Skill——不需要改任何代码。
这一能力在同类框架中极为罕见。
作为"手脚" — 让外部 AI 成为团队正式成员。支持 4 种接入通道（HTTP 回调、A2A 协议、MCP 协议、Service 后端），接入后被分配子任务、注入上下文、接收审查，和其他 Agent 完全一样。
作为"大脑" — 让外部 AI 操控平台。通过 35 个 MCP 工具或 A2A 扩展方法，外部 AI 可以创建团队、下发使命、与 LEAD 对话、审批 Plan、中途注入补充消息。最极端的情况：人类用自然语言对企业微信说话 → 机器人调用 Agent Team → 团队自主完成全套开发 → 结果自动返回。全程人类没打开任何界面。
Agent Team 在运行中自动沉淀三类知识：
- ERRORS.md — 记录错误类型、触发条件和解决方案
- LEARNINGS.md — 从成功任务中提取可复用的经验
- 避坑卡片（Pitfall Cards） — 失败教训自动记录，下次同类任务自动注入警告
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/ │
└──────────────────────────────────────────────────────────────────┘
| 角色 | ID | 职责 |
|---|---|---|
| 调度官 | orchestrator |
集群调度中枢，任务拆解与分配 |
| 架构师 | architect |
方案设计，验收标准制定 |
| 编码员 | coder |
Worktree 内编码，最小改动原则 |
| 审查员 | reviewer |
6 维度独立审查，默认 REJECT |
| 测试员 | tester |
独立验证，强制运行测试命令 |
| 文档员 | documenter |
文档与 Changelog |
| 检索员 | researcher |
信息检索，联网搜索 |
| 探索员 | searcher |
项目结构扫描，技术栈识别 |
| Bridge Agent | pm |
用户与团队的中继，需求澄清和进度汇报 |
Agent Team 不是封闭系统。它通过标准协议与外部世界深度互操作：
覆盖团队、Agent、任务、工作区、知识、质量、成本、容器、审批、模板、Token、MCP/A2A、飞书集成等全部领域。每一个端点都有完整的请求/响应文档和 curl 示例。详见 API 参考。
实现了完整的 MCP Server（协议版本 2025-06-18），工具分为两大类别：
- 工作区操作（10 个）：文件读写、命令执行、代码搜索、网页抓取
- 平台管理（25 个）：团队管理、使命下发、Agent 管理、对话协作、监控日志、知识搜索、成本估算
每个工具都有 scope 权限映射，受限 Token 只能调用权限范围内的工具。外部 AI 客户端（Claude Desktop、Cursor、飞书机器人）可以直接连接 http://host:3001/mcp 来控制平台。
支持 JSON-RPC 2.0 标准 A2A 协议（tasks/send、tasks/get），并在 Agent Card 中声明 4 个扩展方法：
tasks/questions— 查询 LEAD 待回答的提问tasks/answer— 回答指定提问tasks/confirm— 审批 Plantasks/message— 注入补充消息
外部 AI 大脑可以仅通过 A2A 一种协议完成完整的"下发使命 → 回答提问 → 审批 → 观察"全流程。
团队执行过程中的关键事件通过 Server-Sent Events 实时推送：agent.started、agent.completed、agent.failed、subtask.started、subtask.completed、team.completed 等。前端控制台和外部系统均可订阅。
| 接入通道 | 适合场景 | 外部需实现 |
|---|---|---|
| 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 直接调用引擎，无需启动 Server，80+ 子命令覆盖全部 14 个核心模块：
# 全局安装后可使用 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 参考
cd deploy/docker
docker build -t agent-team:latest -f Dockerfile ../..
docker-compose up -dcd deploy/k8s
kubectl apply -f configmap.yaml
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml# 部署完整平台到远程服务器
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 | 引擎使用手册：import core.js 编程集成 + 引擎与 Server/CLI/MCP/A2A 的关系 |
| API 参考 | 187 个 REST 端点 + MCP/A2A 协议完整参考 |
| CLI 参考 | 80+ 子命令，覆盖 14 个核心模块 |
| 用户手册 | 名词概念解释 + 完整操作指南 |
| 技术博客 | 项目背景、设计思路和开发过程（~16,000 字） |
| 外部 Agent Skill | 外部 AI 大脑操控平台的 MCP 指南 |
| 开源策略 | 差异化定位与社区运营路线图 |
| 测试计划 | 10 维度 / 50 场景 / 215 用例测试设计 |
| 测试报告 | 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) MCP (2025-06-18) 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 了解开发流程和代码规范。
感谢所有为这个项目做出贡献的人 ✨
MIT © 2026 Agent Team Contributors
Built with ❤️ for the AI Engineering community