Files

Claude Code dc398d7c7b 完整实现 Swarm 多智能体协作系统

- 新增 CLIPluginAdapter 统一接口 (backend/app/core/agent_adapter.py)
- 新增 LLM 服务层，支持 Anthropic/OpenAI/DeepSeek/Ollama (backend/app/services/llm_service.py)
- 新增 Agent 执行引擎，支持文件锁自动管理 (backend/app/services/agent_executor.py)
- 新增 NativeLLMAgent 原生 LLM 适配器 (backend/app/adapters/native_llm_agent.py)
- 新增进程管理器 (backend/app/services/process_manager.py)
- 新增 Agent 控制 API (backend/app/routers/agents_control.py)
- 新增 WebSocket 实时通信 (backend/app/routers/websocket.py)
- 更新前端 AgentsPage，支持启动/停止 Agent
- 测试通过：Agent 启动、批量操作、栅栏同步

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-09 17:32:11 +08:00

13 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

Swarm Command Center 是一个多智能体协作系统，支持 Claude Code、Kimi CLI、OpenCode 等多种 AI CLI 工具的协同工作。

当前状态：前端 UI 已完成，后端协调引擎已完整实现并通过测试。

开发命令

前端（React 18 + TypeScript + Vite + Tailwind CSS v4）

cd frontend
npm install          # 安装依赖
npm run dev          # 启动开发服务器（端口 3000）
npm run build        # 构建生产版本（tsc && vite build）
npm run preview      # 预览生产构建
npm run lint         # ESLint 代码检查
npm run test         # 运行 Playwright E2E 测试
npm run test:ui      # 运行 Playwright 测试（UI 模式）

前端页面：

DashboardPage.tsx - 仪表盘（概览、Agent 状态、最近会议）
AgentsPage.tsx - Agent 管理
MeetingsPage.tsx - 会议管理
ResourcesPage.tsx - 资源监控
WorkflowPage.tsx - 工作流
SettingsPage.tsx - 配置

后端（Python + FastAPI）

cd backend
python -m venv venv
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate
pip install -r requirements.txt

# 启动服务
python -m uvicorn main:app --reload --port 8000
# 或直接运行
python -m app.main

# 运行所有服务测试
python test_all_services.py

后端 CLI 命令（在 backend/ 目录下执行）：

# Agent 管理
python cli.py agent list                                          # 列出所有 Agent
python cli.py agent register <id> --name <名称> --role <角色> --model <模型>
python cli.py agent info <id>                                     # 查看 Agent 详情
python cli.py agent state <id> get                                # 获取 Agent 状态
python cli.py agent state <id> set --task <任务> --progress <进度>

# 文件锁
python cli.py lock status                                          # 查看所有锁
python cli.py lock acquire <file_path> <agent_id>                 # 获取锁
python cli.py lock release <file_path> <agent_id>                 # 释放锁
python cli.py lock check <file_path>                              # 检查文件是否被锁定

# 心跳
python cli.py heartbeat list                                       # 查看所有心跳
python cli.py heartbeat ping <agent_id> --status <状态> --task <任务> --progress <进度>
python cli.py heartbeat check-timeout <秒数>                      # 检查超时的 Agent

# 会议调度（栅栏同步）
python cli.py meeting create <id> --title <标题> --attendees <id1,id2,...>
python cli.py meeting wait <meeting_id> --agent <agent_id>        # 栅栏同步等待（阻塞）
python cli.py meeting queue <meeting_id>                          # 查看等待队列
python cli.py meeting end <meeting_id>                            # 结束会议

# 会议记录
python cli.py meeting record-create <id> --title <标题> --attendees <ids> --steps <步骤>
python cli.py meeting discuss <id> --agent <agent_id> --content <内容> --step <步骤>
python cli.py meeting progress <id> <步骤>                        # 更新会议进度
python cli.py meeting show <id> [--date <日期>]                   # 显示会议详情
python cli.py meeting list [--date <日期>]                        # 列出会议
python cli.py meeting finish <id> --consensus <共识>              # 完成会议

# 工作流
python cli.py workflow show <path>                                # 显示工作流详情
python cli.py workflow load <path>                                # 加载工作流
python cli.py workflow next <workflow_id>                         # 获取下一个会议
python cli.py workflow status <workflow_id>                       # 获取工作流状态
python cli.py workflow complete <workflow_id> <meeting_id>        # 标记会议完成
python cli.py workflow list-files                                 # 列出可用工作流文件
python cli.py workflow detail <workflow_id>                       # 获取工作流详细信息
python cli.py workflow execution-status <workflow_id> <meeting_id> # 获取执行节点状态

# 角色分配
python cli.py role allocate <任务描述> <agent1,agent2,...>        # AI 分配角色
python cli.py role primary <任务描述>                             # 获取主要角色
python cli.py role explain <任务描述> <agents>                    # 解释角色分配原因

# 人类输入
python cli.py human register <user_id> --name <名称> --role <角色>
python cli.py human add-task <内容> --from <用户> --priority <优先级>
python cli.py human pending-tasks                                 # 查看待处理任务
python cli.py human urgent-tasks                                  # 查看紧急任务

系统架构

四层架构

┌─────────────────────────────────────────┐
│   用户界面层 (React SPA)                │
│   - DashboardPage    仪表盘             │
│   - AgentsPage       Agent 管理         │
│   - MeetingsPage     会议管理           │
│   - ResourcesPage    资源监控           │
│   - WorkflowPage     工作流             │
│   - SettingsPage     配置               │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│   协调层 (Python FastAPI)               │
│   - WorkflowEngine     工作流编排        │
│   - MeetingScheduler   栅栏同步          │
│   - MeetingRecorder    会议记录          │
│   - ResourceManager    资源管理          │
│   - FileLockService    文件锁            │
│   - HeartbeatService   心跳检测          │
│   - AgentRegistry      Agent 注册        │
│   - RoleAllocator      AI 角色分配       │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│   Agent 适配层                          │
│   - CLIPluginAdapter 统一接口            │
│   - ClaudeCode / KimiCLI / OpenCode     │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│   模型层 (Anthropic / OpenAI / Ollama)  │
└─────────────────────────────────────────┘

共享存储结构 (`.doc/`)

.doc/
├── agents/              # Agent 注册与状态
│   └── {agent_id}/
│       ├── info.json
│       └── state.json
├── meetings/            # 会议记录与共识
│   └── {YYYY-MM-DD}/
│       ├── {meeting_id}.json
│       └── {meeting_id}.md
├── resources/           # 资源分配
├── cache/               # 实时缓存
│   ├── file_locks.json
│   ├── heartbeats.json
│   └── meeting_queue.json
├── workflow/            # 工作流定义 (YAML)
└── humans.json          # 人类参与者输入

核心设计模式

1. 声明式资源管理

Agent 只需声明任务意图，系统通过 TaskExecutor 自动管理文件锁：

# Agent 代码 - 无需手动处理锁
result = executor.execute("修改 src/main.py 修复登录 bug")
# 内部自动: 1)解析文件 2)获取锁 3)执行 4)释放锁

2. 栅栏同步（会议驱动）

# Agent 调用 wait_for_meeting 进入等待
status = scheduler.wait_for_meeting(agent_id, meeting_id)
# 最后一个到达的 Agent 触发会议开始，所有等待者返回

3. 角色权重系统

角色	权重	职责
pm	1.5	需求分析、优先级排序
architect	1.5	系统设计、技术选型
reviewer	1.3	代码审查、安全检查
qa	1.2	测试用例、自动化测试
developer	1.0	编码实现

前端样式系统

颜色体系

主色：Cyan #00f0ff
辅助：Purple #8b5cf6
成功：Green #00ff9d
警告：Amber #ff9500
错误：Pink #ff006e
背景：Dark #0a0a0a / #111111

字体

标题：Orbitron（未来感）
中文：Noto Sans SC
代码：JetBrains Mono

动画效果

Agent 卡片：呼吸光晕动画（3s infinite）
状态指示器：脉动效果
边框：渐变发光

后端服务架构

服务层（`backend/app/services/`）

服务	文件	职责
StorageService	storage.py	统一文件存储（JSON读写、存在检查）
FileLockService	file_lock.py	文件锁管理（获取、释放、超时检测）
HeartbeatService	heartbeat.py	Agent 心跳检测与活跃状态
AgentRegistry	agent_registry.py	Agent 注册、状态管理
MeetingScheduler	meeting_scheduler.py	栅栏同步、会议等待队列
MeetingRecorder	meeting_recorder.py	会议记录、讨论、共识
ResourceManager	resource_manager.py	资源协调、任务执行
WorkflowEngine	workflow_engine.py	YAML 工作流加载与执行
RoleAllocator	role_allocator.py	AI 驱动的角色分配
HumanInputService	human_input.py	人类参与者输入管理

路由层（`backend/app/routers/`）

agents.py - Agent 管理 API
locks.py - 文件锁 API
meetings.py - 会议 API
heartbeats.py - 心跳 API
workflows.py - 工作流 API
resources.py - 资源 API
roles.py - 角色 API
humans.py - 人类输入 API

API 接口

基础地址: http://localhost:8000/api
健康检查: GET /health 或 GET /api/health

主要端点:

GET /api/agents - Agent 列表
GET /api/locks - 文件锁状态
GET /api/heartbeats - 心跳状态
POST /api/meetings/create - 创建会议
GET /api/meetings/:id - 会议详情
POST /api/workflows/load - 加载工作流

详见 docs/api-reference.md

文档索引

docs/design-spec.md - 完整系统设计文档
docs/api-reference.md - API 接口文档
docs/backend-steps.md - 后端开发步骤
docs/frontend-steps.md - 前端开发步骤
docs/reference-projects.md - 参考项目

测试

后端测试

运行完整的服务测试套件：

cd backend
python test_all_services.py

这会测试所有 9 个核心服务：

StorageService - 文件读写
FileLockService - 文件锁
HeartbeatService - 心跳
AgentRegistry - Agent 注册
MeetingScheduler - 会议调度（栅栏同步）
MeetingRecorder - 会议记录
ResourceManager - 资源管理
WorkflowEngine - 工作流引擎
RoleAllocator - 角色分配

前端测试

Playwright E2E 测试配置在 playwright.config.ts：

cd frontend
npm run test          # 运行测试（headless）
npm run test:ui       # 运行测试（UI 模式）

测试文件位于 frontend/tests/ 目录。

开发提示

Windows 环境注意事项

使用 venv\Scripts\activate 激活 Python 虚拟环境
路径使用正斜杠 / 或双反斜杠 \\
使用 PowerShell 或 Git Bash 执行 shell 命令

单例服务

所有后端服务通过单例模式获取：

from app.services.storage import get_storage
from app.services.file_lock import get_file_lock_service
# ...

storage = get_storage()  # 自动初始化并缓存

13 KiB Raw Blame History Unescape Escape