# 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 特定的参数构造