16 KiB
16 KiB
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 - 配置
前端 API 层：
- api.ts - 封装所有后端 API 调用
后端（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
# 运行 API 集成测试
python test_api_integration.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 角色分配 │
│ - WorkflowOrchestrator 自动工作流驱动 │
│ - CLIInvoker CLI 工具调用 │
│ - LLMService LLM API 路由 │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 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 | 编码实现 |
4. AI Provider 系统
支持多种 AI 调用方式（优先级从高到低）：
-
CLI 工具（本地安装）：
claude- Claude Code CLIkimi- Kimi CLIopencode- OpenCode CLI
-
LLM API（环境变量配置）：
ANTHROPIC_API_KEY- Claude APIOPENAI_API_KEY- OpenAI APIDEEPSEEK_API_KEY- DeepSeek APIGOOGLE_API_KEY- Google Gemini API
CLI 调用实现见 cli_invoker.py，Provider API 见 providers.py。
5. 工作流自动编排
WorkflowOrchestrator 自动驱动工作流执行：
# 启动自动编排
orchestrator = get_workflow_orchestrator()
run = await orchestrator.start_workflow("dinner-decision.yaml")
# 编排器自动：
# 1. 加载工作流定义
# 2. 逐个节点执行（meeting/execution）
# 3. 调用 Agent 对应的 CLI/API 生成发言
# 4. 记录讨论内容
# 5. 生成会议共识
# 6. 流转到下一个节点
API 端点：
POST /api/orchestrator/start- 启动工作流编排GET /api/orchestrator/runs- 列出所有运行GET /api/orchestrator/runs/{run_id}- 获取运行详情
前端样式系统
颜色体系
- 主色：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 工作流加载与执行 |
| WorkflowOrchestrator | workflow_orchestrator.py | 自动驱动工作流执行 |
| RoleAllocator | role_allocator.py | AI 驱动的角色分配 |
| HumanInputService | human_input.py | 人类参与者输入管理 |
| CLIInvoker | cli_invoker.py | 调用本地 CLI 工具 |
| LLMService | llm_service.py | LLM API 路由与调用 |
路由层（backend/app/routers/）
- agents.py - Agent 管理 API
- agents_control.py - Agent 控制 API（启动/停止）
- locks.py - 文件锁 API
- meetings.py - 会议 API
- heartbeats.py - 心跳 API
- workflows.py - 工作流 API
- resources.py - 资源 API
- roles.py - 角色 API
- humans.py - 人类输入 API
- websocket.py - WebSocket 实时通信
- orchestrator.py - 工作流编排 API
- providers.py - AI Provider 查询 API
API 接口
- 基础地址:
http://localhost:8000/api - 健康检查:
GET /health或GET /api/health
主要端点:
GET /api/agents- Agent 列表GET /api/locks- 文件锁状态GET /api/heartbeats- 心跳状态GET /api/providers- 可用 AI Provider（CLI + API）GET /api/providers/models- 可用模型列表POST /api/meetings/create- 创建会议GET /api/meetings/:id- 会议详情POST /api/workflows/load- 加载工作流POST /api/orchestrator/start- 启动自动工作流编排GET /api/orchestrator/runs/:id- 获取编排运行状态
详见 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 - 角色分配
运行 API 集成测试：
cd backend
python test_api_integration.py
前端测试
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
from app.services.workflow_orchestrator import get_workflow_orchestrator
# ...
storage = get_storage() # 自动初始化并缓存
添加新的 AI Provider
- CLI 工具：在 cli_invoker.py 的
CLI_REGISTRY中添加映射 - API Provider：在 providers.py 的
API_PROVIDERS中添加配置 - 模型映射：在
_build_command()中实现 CLI 特定的参数构造