398 lines
16 KiB
Markdown
398 lines
16 KiB
Markdown
# 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）
|
||
|
||
```bash
|
||
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](frontend/src/pages/DashboardPage.tsx) - 仪表盘（概览、Agent 状态、最近会议）
|
||
- [AgentsPage.tsx](frontend/src/pages/AgentsPage.tsx) - Agent 管理
|
||
- [MeetingsPage.tsx](frontend/src/pages/MeetingsPage.tsx) - 会议管理
|
||
- [ResourcesPage.tsx](frontend/src/pages/ResourcesPage.tsx) - 资源监控
|
||
- [WorkflowPage.tsx](frontend/src/pages/WorkflowPage.tsx) - 工作流
|
||
- [SettingsPage.tsx](frontend/src/pages/SettingsPage.tsx) - 配置
|
||
|
||
**前端 API 层**：
|
||
- [api.ts](frontend/src/lib/api.ts) - 封装所有后端 API 调用
|
||
|
||
### 后端（Python + FastAPI）
|
||
|
||
```bash
|
||
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/` 目录下执行）：
|
||
|
||
```bash
|
||
# 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` 自动管理文件锁：
|
||
|
||
```python
|
||
# Agent 代码 - 无需手动处理锁
|
||
result = executor.execute("修改 src/main.py 修复登录 bug")
|
||
# 内部自动: 1)解析文件 2)获取锁 3)执行 4)释放锁
|
||
```
|
||
|
||
### 2. 栅栏同步（会议驱动）
|
||
|
||
```python
|
||
# 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 调用方式（优先级从高到低）：
|
||
|
||
1. **CLI 工具**（本地安装）：
|
||
- `claude` - Claude Code CLI
|
||
- `kimi` - Kimi CLI
|
||
- `opencode` - OpenCode CLI
|
||
|
||
2. **LLM API**（环境变量配置）：
|
||
- `ANTHROPIC_API_KEY` - Claude API
|
||
- `OPENAI_API_KEY` - OpenAI API
|
||
- `DEEPSEEK_API_KEY` - DeepSeek API
|
||
- `GOOGLE_API_KEY` - Google Gemini API
|
||
|
||
CLI 调用实现见 [cli_invoker.py](backend/app/services/cli_invoker.py)，Provider API 见 [providers.py](backend/app/routers/providers.py)。
|
||
|
||
### 5. 工作流自动编排
|
||
|
||
[WorkflowOrchestrator](backend/app/services/workflow_orchestrator.py) 自动驱动工作流执行：
|
||
|
||
```python
|
||
# 启动自动编排
|
||
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](backend/app/services/storage.py) | 统一文件存储（JSON读写、存在检查） |
|
||
| FileLockService | [file_lock.py](backend/app/services/file_lock.py) | 文件锁管理（获取、释放、超时检测） |
|
||
| HeartbeatService | [heartbeat.py](backend/app/services/heartbeat.py) | Agent 心跳检测与活跃状态 |
|
||
| AgentRegistry | [agent_registry.py](backend/app/services/agent_registry.py) | Agent 注册、状态管理 |
|
||
| MeetingScheduler | [meeting_scheduler.py](backend/app/services/meeting_scheduler.py) | 栅栏同步、会议等待队列 |
|
||
| MeetingRecorder | [meeting_recorder.py](backend/app/services/meeting_recorder.py) | 会议记录、讨论、共识 |
|
||
| ResourceManager | [resource_manager.py](backend/app/services/resource_manager.py) | 资源协调、任务执行 |
|
||
| WorkflowEngine | [workflow_engine.py](backend/app/services/workflow_engine.py) | YAML 工作流加载与执行 |
|
||
| WorkflowOrchestrator | [workflow_orchestrator.py](backend/app/services/workflow_orchestrator.py) | 自动驱动工作流执行 |
|
||
| RoleAllocator | [role_allocator.py](backend/app/services/role_allocator.py) | AI 驱动的角色分配 |
|
||
| HumanInputService | [human_input.py](backend/app/services/human_input.py) | 人类参与者输入管理 |
|
||
| CLIInvoker | [cli_invoker.py](backend/app/services/cli_invoker.py) | 调用本地 CLI 工具 |
|
||
| LLMService | [llm_service.py](backend/app/services/llm_service.py) | LLM API 路由与调用 |
|
||
|
||
### 路由层（`backend/app/routers/`）
|
||
|
||
- [agents.py](backend/app/routers/agents.py) - Agent 管理 API
|
||
- [agents_control.py](backend/app/routers/agents_control.py) - Agent 控制 API（启动/停止）
|
||
- [locks.py](backend/app/routers/locks.py) - 文件锁 API
|
||
- [meetings.py](backend/app/routers/meetings.py) - 会议 API
|
||
- [heartbeats.py](backend/app/routers/heartbeats.py) - 心跳 API
|
||
- [workflows.py](backend/app/routers/workflows.py) - 工作流 API
|
||
- [resources.py](backend/app/routers/resources.py) - 资源 API
|
||
- [roles.py](backend/app/routers/roles.py) - 角色 API
|
||
- [humans.py](backend/app/routers/humans.py) - 人类输入 API
|
||
- [websocket.py](backend/app/routers/websocket.py) - WebSocket 实时通信
|
||
- [orchestrator.py](backend/app/routers/orchestrator.py) - 工作流编排 API
|
||
- [providers.py](backend/app/routers/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` - 参考项目
|
||
|
||
## 测试
|
||
|
||
### 后端测试
|
||
|
||
运行完整的服务测试套件：
|
||
|
||
```bash
|
||
cd backend
|
||
python test_all_services.py
|
||
```
|
||
|
||
这会测试所有 9 个核心服务：
|
||
- StorageService - 文件读写
|
||
- FileLockService - 文件锁
|
||
- HeartbeatService - 心跳
|
||
- AgentRegistry - Agent 注册
|
||
- MeetingScheduler - 会议调度（栅栏同步）
|
||
- MeetingRecorder - 会议记录
|
||
- ResourceManager - 资源管理
|
||
- WorkflowEngine - 工作流引擎
|
||
- RoleAllocator - 角色分配
|
||
|
||
运行 API 集成测试：
|
||
|
||
```bash
|
||
cd backend
|
||
python test_api_integration.py
|
||
```
|
||
|
||
### 前端测试
|
||
|
||
Playwright E2E 测试配置在 [playwright.config.ts](frontend/playwright.config.ts)：
|
||
|
||
```bash
|
||
cd frontend
|
||
npm run test # 运行测试（headless）
|
||
npm run test:ui # 运行测试（UI 模式）
|
||
```
|
||
|
||
测试文件位于 `frontend/tests/` 目录。
|
||
|
||
## 开发提示
|
||
|
||
### Windows 环境注意事项
|
||
|
||
- 使用 `venv\Scripts\activate` 激活 Python 虚拟环境
|
||
- 路径使用正斜杠 `/` 或双反斜杠 `\\`
|
||
- 使用 PowerShell 或 Git Bash 执行 shell 命令
|
||
|
||
### 单例服务
|
||
|
||
所有后端服务通过单例模式获取：
|
||
|
||
```python
|
||
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
|
||
|
||
1. **CLI 工具**：在 [cli_invoker.py](backend/app/services/cli_invoker.py) 的 `CLI_REGISTRY` 中添加映射
|
||
2. **API Provider**：在 [providers.py](backend/app/routers/providers.py) 的 `API_PROVIDERS` 中添加配置
|
||
3. **模型映射**：在 `_build_command()` 中实现 CLI 特定的参数构造
|