AI Teams

AI Teams 是一个三方协作系统：人类 Leader 通过 Web 控制台或 REST API 向 Server 提交任务，Server 将任务智能调度给多个 AI Agent（运行 Claude CLI）执行。支持任务队列、负载均衡、标签路由、优先级调度、端到端加密和实时监控。

快速开始

1. 安装依赖

需要 Node.js ≥ 22 和 pnpm ≥ 9。

git clone <your-repo> ai-teams
cd ai-teams
pnpm install

2. 一键启动（开发模式）

pnpm dev:all

这将同时启动 Server（:3789）、Agent Alice 和 Web 控制台（:5173），使用 dev-token 自动认证。

3. 访问控制台

浏览器打开 http://localhost:5173，输入 token dev-token 即可进入。

架构概览

  ┌──────────────┐     WebSocket      ┌──────────────┐     WebSocket     ┌──────────────┐
  │   Web 控制台   │ ◄──────────────► │    Server     │ ◄─────────────► │  Agent (N)   │
  │  (Leader)     │    /ws/leader     │   Fastify     │    /ws/agent    │  Claude CLI  │
  │  React SPA    │                   │  SQLite / PG  │                 │  Heartbeat   │
  └──────────────┘                    └──────┬───────┘                 └──────────────┘
        │                                    │
        │         REST API (/api/*)          │
        └────────────────────────────────────┘

核心组件

任务生命周期

终态（completed / failed / cancelled / timeout）不可变更，后续事件将被忽略。

调度模式

部署指南

环境要求

• Node.js ≥ 22（需要 node:sqlite 支持）
• pnpm ≥ 9
• Claude CLI（Agent 执行任务所需）
• 可选：PostgreSQL（替代 SQLite）

构建

# 构建顺序：shared → server → agent
pnpm build

# Web 独立构建
cd apps/web && pnpm build

生产启动

# 设置认证 Token（必填）
export AI_TEAMS_AUTH_TOKEN="your-secret-token"

# 启动 Server（守护进程模式）
ai-teams-server start --token "your-secret-token" --port 3789

# 启动 Agent（守护进程模式）
ai-teams-agent start --server ws://localhost:3789 --token "your-secret-token" \
  --id alice --name "Alice"

# 或使用 pnpm（开发模式）
pnpm start:server
pnpm start:agent:alice

# 启动 Web 控制台
pnpm start:web

一键全部启动

AI_TEAMS_AUTH_TOKEN="your-secret-token" pnpm start:all

Agent 交互式配置

首次运行 Agent 会自动进入配置向导：

node apps/agent/dist/index.js

也可使用 --config 重新配置。配置保存在 ~/.ai-teams/config.json。

通过 npm 安装

Server 和 Agent 已发布到 npm，无需克隆仓库即可使用。

全局安装

# 安装 Server
npm install -g @csdwd/ai-teams-server

# 安装 Agent
npm install -g @csdwd/ai-teams-agent

安装后即可直接使用 CLI 命令：

# 以守护进程方式启动 Server（推荐）
ai-teams-server start --token "your-secret-token" --port 3789

# 以守护进程方式启动 Agent（首次运行自动进入配置向导）
ai-teams-agent start

使用 npx（无需安装）

# 直接运行 Server
npx @csdwd/ai-teams-server start --token "your-secret-token"

# 直接运行 Agent
npx @csdwd/ai-teams-agent start

CLI 命令

多 Agent 部署示例

# 启动 Server（后台守护进程）
ai-teams-server start --token "my-secret"

# 启动 Agent Alice（后台守护进程）
ai-teams-agent start --server ws://localhost:3789 --token "my-secret" \
  --id alice --name "Alice" --workspace ~/projects/project-a

# 启动 Agent Bob
ai-teams-agent start --server ws://localhost:3789 --token "my-secret" \
  --id bob --name "Bob" --workspace ~/projects/project-b \
  --labels "backend,python"

# 查看运行状态
ai-teams-server status
ai-teams-agent status

# 更新到最新版本
ai-teams-agent update
ai-teams-agent restart  # 应用更新

环境变量

REST API

所有 API 需要认证（Authorization: Bearer <token> 或 ?token=<token>）。Swagger UI：/docs。

{
  "status": "ok",
  "timestamp": "2026-05-12T10:00:00.000Z",
  "dbPath": "./data/ai-teams.db",
  "employees": 2,
  "leaders": 1,
  "tasks": 42
}

{
  "employees": [{ "id": "alice", "name": "Alice", "status": "online", ... }],
  "tasks": [{ "id": "...", "prompt": "...", "status": "completed", ... }],
  "logs": { "task-id": [{ "content": "...", "seq": 1 }] }
}

{
  "prompt": "分析这段代码的性能问题",
  "atAgents": "queue",
  "workspace": "/path/to/project",
  "timeoutSec": 600,
  "priority": 2,
  "requiredLabels": ["backend"],
  "cliConfig": {
    "model": "claude-sonnet-4-6",
    "maxTurns": 10,
    "systemPrompt": "你是一个代码审查专家",
    "allowedTools": ["Read", "Grep", "Bash"]
  },
  "webhook": "https://your-server.com/callback"
}

{
  "status": "accepted",
  "leaderCommandId": "cmd_xxx",
  "tasks": [{ "id": "task_xxx", "status": "queued", ... }]
}

{ "tasks": [...] }

定时任务 API

完整的 CRUD + 手动触发接口，详见定时任务章节。

WebSocket 协议

两个 WebSocket 通道均需要 Token 认证（Header 或 ?token= 参数）。未授权连接将被关闭（code 1008）。

/ws/agent — Agent 通道

Agent 连接此通道，双向通信：接收任务、上报状态。

Server → Agent 消息

Agent → Server 消息

/ws/leader — Leader 通道

Web 控制台连接此通道。连接后 Server 立即推送完整 snapshot。

Server → Leader 消息

Leader → Server 消息

数据模型

TaskRecord

EmployeeSnapshot

TaskCliConfig

Agent 使用

守护进程命令

ai-teams-agent <command> [选项]

命令:
  start [选项]          后台启动守护进程
  stop                  停止守护进程
  restart [选项]        重启守护进程
  status                查看运行状态
  update                更新到最新版本

选项:
  --server <url>       Server WebSocket 地址
  --token <token>      认证 Token
  --id <id>            Agent 唯一标识
  --name <name>        显示名称
  --workspace <dir>    默认工作目录
  --runner <mode>      执行模式 (claude | fake)
  --config             重新运行配置向导
  -h, --help           显示帮助

标签系统

通过 EMPLOYEE_LABELS 环境变量为 Agent 设置标签（逗号分隔）：

EMPLOYEE_LABELS="backend,python,review" node dist/index.js

提交任务时可通过 requiredLabels 筛选匹配的 Agent：

{ "prompt": "审查 Python 代码", "atAgents": "queue", "requiredLabels": ["python"] }

双槽位并行

每个 Agent 有两个任务槽位：

• Main 槽 — 接收 direct / broadcast 任务，使用持久化会话
• Queue 槽 — 接收 queue 任务，使用独立会话

两个槽位可以同时运行，实现并行执行。

Fake Runner 模式

用于测试，无需安装 Claude CLI：

RUNNER_MODE=fake node dist/index.js

模拟 Agent 会定时输出步骤信息，最终返回成功结果。

Agent 文件结构

.ai-teams/agents/<EMPLOYEE_ID>/
├── session-state.json      # 持久化会话 ID
├── daily/
│   └── 2026-05-12.md       # 每日活动日志
└── hooks/
    └── claude-hooks.settings.json  # Claude hooks 配置

Web 控制台

六个功能页面

命令面板

右侧命令面板支持：

• 目标选择 — 任务队列 / @所有员工 / 指定 Agent
• 工作目录 — 可选覆盖
• @ 提及 — 输入 @Alice 自动解析为直接调度
• 群聊视图 — 历史命令和 Agent 回复按时间线展示

移动端适配

Web 控制台完全适配移动端：

• 固定全屏布局，仅聊天区域滚动
• 底部 Agent 状态快捷栏
• 点击 Agent 名称弹出终端输出浮层
• 自动重连 + 断线提示按钮

高级功能

任务优先级

任务支持 4 级优先级（默认 1 = 普通）：

{ "prompt": "紧急修复线上 Bug", "priority": 3 }

标签调度

结合 Agent 标签和任务 requiredLabels 实现精准路由：

# Agent 端设置标签
EMPLOYEE_LABELS="frontend,react" node dist/index.js

# 任务端要求标签
{ "prompt": "重构组件", "requiredLabels": ["frontend"] }

调度逻辑：在匹配标签的 Agent 中选择负载最低的，同等负载时 round-robin 轮转。

端到端加密

设置 AI_TEAMS_ENCRYPTION_KEY（64 位 hex = 32 字节 AES 密钥）后，所有 WebSocket 消息使用 AES-256-GCM 加密。

# 生成随机密钥
openssl rand -hex 32

# 三端设置相同密钥
export AI_TEAMS_ENCRYPTION_KEY="生成的密钥"

不设置密钥时，所有通信为明文 JSON（向后兼容）。

Webhook 回调

提交任务时可指定 Webhook URL，Server 会在任务生命周期事件时向该 URL 发送 POST 请求。支持三种字段名：webhook、webhookUrl 或 webHook。

{ "prompt": "部署到生产环境", "webhook": "https://your-server.com/hooks/ai-teams" }

事件类型

回调示例

queue.updated — 队列位置通知

{
  "event": "queue.updated",
  "timestamp": "2026-05-19T03:37:07.000Z",
  "task": { "id": "task_xxx", "status": "queued", ... },
  "queuePosition": 2,
  "queueLength": 5
}

task.started — 任务开始

{
  "event": "task.started",
  "timestamp": "2026-05-19T03:38:01.132Z",
  "task": {
    "id": "task_xxx",
    "status": "running",
    "employeeId": "alice",
    "startedAt": "2026-05-19T03:38:01.132Z",
    ...
  }
}

task.output — 工具调用

{
  "event": "task.output",
  "timestamp": "2026-05-19T03:40:14.572Z",
  "task": { "id": "task_xxx", "status": "running", ... },
  "chunk": {
    "taskId": "task_xxx",
    "employeeId": "alice",
    "stream": "stdout",
    "seq": 1,
    "content": "[tool] WebSearch\n",
    "createdAt": "2026-05-19T03:40:14.571Z"
  }
}

task.output — 最终结果

{
  "event": "task.output",
  "timestamp": "2026-05-19T03:40:39.611Z",
  "task": { "id": "task_xxx", "status": "running", ... },
  "chunk": {
    "taskId": "task_xxx",
    "employeeId": "alice",
    "stream": "stdout",
    "seq": 109,
    "content": "\n[done] Claude result\n[done] subtype: success\n[done] session_id: xxx\n[done] duration_ms: 30139\n[done] duration_api_ms: 29859\n[done] num_turns: 2\n[done] total_cost_usd: 0.0767\n[done] result: 天津今天阴天，气温17~24℃...",
    "createdAt": "2026-05-19T03:40:39.611Z"
  }
}

task.completed — 任务完成

{
  "event": "task.completed",
  "timestamp": "2026-05-19T03:40:39.705Z",
  "task": {
    "id": "task_xxx",
    "status": "completed",
    "employeeId": "alice",
    "exitCode": 0,
    "summary": "天津今天阴天，气温17~24℃...",
    "finishedAt": "2026-05-19T03:40:39.704Z",
    ...
  }
}

安全验证

每个回调请求包含签名头，用于验证请求来源：

x-ai-teams-signature: sha256=<HMAC-SHA256>

签名密钥为 AI_TEAMS_AUTH_TOKEN，对请求 body 做 HMAC-SHA256 签名。验证示例：

import hmac, hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

投递保证

• 失败自动重试，最多 3 次，间隔 1 秒
• 请求超时 10 秒，超时后触发重试
• 任务进入终态后自动清理内存中的 webhook 记录

数据库

默认使用 SQLite（node:sqlite），设置 DATABASE_URL 可切换到 PostgreSQL。

Server 启动时从数据库恢复状态，标记所有 Agent 为 offline，重新入队未完成任务。

守护进程

Server 和 Agent 均支持守护进程模式，使用三阶段进程模型确保稳定性：

  用户执行 start
       │
       ▼
  ┌──────────┐   fork (detached)   ┌──────────┐   fork (env: WORKER=1)   ┌──────────┐
  │ Launcher │ ──────────────────► │ Watchdog │ ───────────────────────► │  Worker  │
  │ (退出)    │                    │ 写 PID    │                         │ 业务逻辑  │
  └──────────┘                    │ 监控存活  │                         │ connect()│
                                  │ 自动重启  │                         └──────────┘
                                  └──────────┘

常用命令

# 启动（后台运行）
ai-teams-server start --token "your-token"
ai-teams-agent start --server ws://localhost:3789 --token "your-token"

# 查看状态
ai-teams-server status    # → running (PID 12345)
ai-teams-agent status

# 重启
ai-teams-server restart
ai-teams-agent restart

# 停止
ai-teams-server stop
ai-teams-agent stop

# 更新版本
ai-teams-server update    # npm 全局更新
ai-teams-agent update     # 更新后提示 restart

自动恢复

Watchdog 进程监控 Worker，异常退出时自动重启（每分钟最多 10 次）。PID 文件位于工作目录下：

• Server：<data-dir>/.ai-teams/server/server.pid
• Agent：<workspace>/.ai-teams/agents/<id>/agent.pid

日志输出到各守护进程的 logs/ 目录，可用 status 命令查看路径。

容错机制

断线任务恢复

当 Agent 意外断开连接时，Server 执行以下恢复流程：

1. 宽限期等待（默认 15 秒）— 如果 Agent 在宽限期内重连，任务继续执行
2. 自动重新入队 — 宽限期过后，未完成任务重新进入队列
3. 重试次数限制 — 每个任务最多重试 3 次，超过后标记为 failed

重试策略

心跳检测

Server 为每个在线 Agent 维护 30 秒心跳超时：

• Agent 每 10 秒发送 agent.heartbeat
• 超过 30 秒无心跳自动标记为 offline
• 回收未执行的队列任务到共享队列

Server 重启恢复

Server 重启时从数据库恢复全部状态：

• 所有 Agent 标记为 offline，等待重新注册
• 未完成的任务重新入队（不受重试次数限制）
• Agent 重连后可恢复原有任务（通过 activeMainTaskId / activeQueueTaskId）

定时任务

通过 REST API 创建 cron 定时任务，Server 会按计划自动执行。支持所有任务调度模式（queue / direct / broadcast）。

创建定时任务

POST /api/schedules
{
  "name": "每日代码审查",
  "cron": "0 9 * * 1-5",
  "enabled": true,
  "targetMode": "queue",
  "prompt": "检查最近的代码变更并生成审查报告",
  "workspace": "/path/to/project",
  "priority": 1,
  "requiredLabels": ["backend"]
}

返回包含 nextRunAt 字段，表示下次执行时间。

Schedule REST API

Schedule 数据模型