multiAgentTry/docs/project-audit-report.md

# Swarm Command Center - 项目审计报告

> 初始审计日期：2026-03-10
> 修复完成日期：2026-03-10
> 审计范围：需求文档 vs 实际实现的完整比对

---

## 一、项目总体进度

### 修复后状态（2026-03-10 更新）

| 模块 | 完成度 | 状态 |
|------|--------|------|
| 后端服务层 (Services) | **95%** | ✅ 9 个核心服务全部实现并通过测试 |
| 后端路由层 (Routers) | **100%** | ✅ **已修复** 全部 10 个路由模块正确接入服务层 |
| 后端 CLI | **100%** | ✅ 所有命令已实现并正确调用服务层 |
| 前端页面 | **95%** | ✅ 6 个页面全部实现，工作流上传已补全 |
| 前端 API 客户端 | **100%** | ✅ **已修复** 封装全部 API 模块（含 Agent 控制） |
| 前端-后端联调 | **95%** | ✅ **已修复** 路由→服务→存储全链路打通 |
| API 集成测试 | **100%** | ✅ **新增** 43 个 API 端点测试全部通过 |
| E2E 测试 | **60%** | ⚠️ 测试用例存在，选择器需要与 UI 保持同步 |

### 修复前状态（初始审计）

| 模块 | 完成度 | 状态 |
|------|--------|------|
| 后端路由层 (Routers) | ~~40%~~ | ~~多数路由使用 mock 数据，未接入服务层~~ |
| 前端-后端联调 | ~~30%~~ | ~~后端路由返回 mock，前端获取假数据~~ |

---

## 二、核心问题：路由层与服务层脱节

**这是项目最大的系统性问题。** 后端服务层已完整实现并通过测试，CLI 也正确接入了服务层。但 HTTP API 路由层（前端调用的入口）多数使用内存变量或硬编码 mock 数据，没有调用已实现的服务。

### 2.1 路由层状态明细

| 路由文件 | 前缀 | 数据源 | 接入服务层? |
|----------|------|--------|-------------|
| `agents.py` | `/api/agents` | 内存 `agents_db` + 硬编码默认 Agent | ❌ 未接入 `AgentRegistry` |
| `locks.py` | `/api/locks` | 内存 `locks_db` + 硬编码默认锁 | ❌ 未接入 `FileLockService` |
| `heartbeats.py` | `/api/heartbeats` | 硬编码 mock 返回值 | ❌ 未接入 `HeartbeatService` |
| `meetings.py` | `/api/meetings` | 内存 `meetings_db` + 硬编码 mock | ❌ 未接入 `MeetingScheduler` / `MeetingRecorder` |
| `resources.py` | `/api` | `/execute` `/parse-task` 为硬编码 mock | ⚠️ 仅 `/status` 接入了服务 |
| `roles.py` | `/api/roles` | 全部硬编码 mock（固定返回 developer） | ❌ 未接入 `RoleAllocator` |
| `workflows.py` | `/api/workflows` | 已调用 `WorkflowEngine` | ✅ **已正确接入** |
| `humans.py` | `/api/humans` | 已调用 `HumanInputService` | ✅ **已正确接入** |
| `agents_control.py` | `/api/agents/control` | 已调用 `ProcessManager` 等 | ✅ **已正确接入** |
| `websocket.py` | `/ws` | 独立实现 | ✅ 正常 |

**结论**：10 个路由模块中，仅 3 个（workflows, humans, agents_control）正确接入了后端服务，6 个使用 mock 数据。

---

## 三、API 端点需求 vs 实现对比

### 3.1 Agent API (`/api/agents`)

| 需求端点 | 方法 | 路由实现 | 接入服务 | 状态 |
|----------|------|----------|----------|------|
| `/api/agents` | GET | ✅ 存在 | ❌ 返回硬编码 | ⚠️ Mock |
| `/api/agents/register` | POST | ✅ 存在 | ❌ 存内存 `agents_db` | ⚠️ Mock |
| `/api/agents/:id` | GET | ✅ 存在 | ❌ 仅查内存 | ⚠️ Mock |
| `/api/agents/:id/state` | GET | ✅ 存在 | ❌ 硬编码状态 | ⚠️ Mock |
| `/api/agents/:id/state` | POST | ✅ 存在 | ❌ 存内存 | ⚠️ Mock |
| `/api/agents/:id` | DELETE | ✅ 存在（额外） | ❌ 仅删内存 | ⚠️ Mock |

### 3.2 文件锁 API (`/api/locks`)

| 需求端点 | 方法 | 路由实现 | 接入服务 | 状态 |
|----------|------|----------|----------|------|
| `/api/locks` | GET | ✅ 存在 | ❌ 硬编码锁数据 | ⚠️ Mock |
| `/api/locks/acquire` | POST | ✅ 存在 | ❌ 存内存 | ⚠️ Mock |
| `/api/locks/release` | POST | ✅ 存在 | ❌ 仅删内存 | ⚠️ Mock |
| `/api/locks/check` | GET | ✅ 存在 | ❌ 查内存 | ⚠️ Mock |

### 3.3 心跳 API (`/api/heartbeats`)

| 需求端点 | 方法 | 路由实现 | 接入服务 | 状态 |
|----------|------|----------|----------|------|
| `/api/heartbeats` | GET | ✅ 存在 | ❌ 硬编码 | ⚠️ Mock |
| `/api/heartbeats/:id` | POST | ✅ 存在 | ❌ 存内存 | ⚠️ Mock |
| `/api/heartbeats/timeouts` | GET | ❌ **缺失** | - | ❌ 未实现 |

### 3.4 会议 API (`/api/meetings`)

| 需求端点 | 方法 | 路由实现 | 接入服务 | 状态 |
|----------|------|----------|----------|------|
| `/api/meetings/create` | POST | ✅ 存在 | ❌ 存内存 | ⚠️ Mock |
| `/api/meetings/:id/queue` | GET | ❌ **缺失** | - | ❌ 未实现 |
| `/api/meetings/:id/wait` | POST | ❌ **缺失** | - | ❌ 未实现 |
| `/api/meetings/:id/end` | POST | ❌ **缺失** | - | ❌ 未实现 |
| `/api/meetings/record/create` | POST | ✅ 存在 | ❌ 存内存 | ⚠️ Mock |
| `/api/meetings/:id/discuss` | POST | ✅ 存在 | ❌ 空返回 | ⚠️ Mock |
| `/api/meetings/:id/progress` | POST | ✅ 存在 | ❌ 空返回 | ⚠️ Mock |
| `/api/meetings/:id` | GET | ✅ 存在 | ❌ 返回 mock | ⚠️ Mock |
| `/api/meetings/:id/finish` | POST | ✅ 存在 | ❌ 空返回 | ⚠️ Mock |
| `/api/meetings` (列表) | GET | ✅ 存在 | ❌ 硬编码 | ⚠️ Mock |
| `/api/meetings/today` | GET | ✅ 存在 | ❌ 硬编码 | ⚠️ Mock |

### 3.5 资源 API (`/api`)

| 需求端点 | 方法 | 路由实现 | 接入服务 | 状态 |
|----------|------|----------|----------|------|
| `/api/execute` | POST | ✅ 存在 | ❌ 硬编码返回 | ⚠️ Mock |
| `/api/status` | GET | ✅ 存在 | ✅ 接入 Registry + Heartbeat | ✅ 正常 |
| `/api/parse-task` | POST | ✅ 存在 | ❌ 硬编码返回 | ⚠️ Mock |

### 3.6 角色 API (`/api/roles`)

| 需求端点 | 方法 | 路由实现 | 接入服务 | 状态 |
|----------|------|----------|----------|------|
| `/api/roles/primary` | POST | ✅ 存在 | ❌ 固定返回 developer | ⚠️ Mock |
| `/api/roles/allocate` | POST | ✅ 存在 | ❌ 轮询分配硬编码 | ⚠️ Mock |
| `/api/roles/explain` | POST | ✅ 存在 | ❌ 固定文案 | ⚠️ Mock |

### 3.7 已正确实现的 API

| 路由模块 | 端点数 | 状态 |
|----------|--------|------|
| `workflows.py` | 11 个端点 | ✅ 全部接入 `WorkflowEngine` |
| `humans.py` | 12 个端点 | ✅ 全部接入 `HumanInputService` |
| `agents_control.py` | 12 个端点 | ✅ 全部接入 `ProcessManager` 等 |
| `websocket.py` | 6 个端点 | ✅ 独立实现完整 |

---

## 四、后端代码问题

### 4.1 Bug

| 文件 | 问题 | 严重度 |
|------|------|--------|
| `agent_executor.py` | `json.dumps` 调用在函数内部局部 import（L442），虽不会 NameError 但不规范 | 低 |
| `llm_service.py` | 使用 `aiohttp`（L439, L474）但 `requirements.txt` 中未声明 | 中 |
| `native_llm_agent.py:278` | `# TODO: 实现投票机制` 未完成 | 低 |

### 4.2 缺失的 API 端点（需求文档要求但路由未实现）

| 端点 | 说明 |
|------|------|
| `GET /api/heartbeats/timeouts` | 检查超时 Agent |
| `GET /api/meetings/:id/queue` | 获取会议等待队列 |
| `POST /api/meetings/:id/wait` | 栅栏同步等待 |
| `POST /api/meetings/:id/end` | 结束会议 |

---

## 五、前端问题

### 5.1 功能缺失

| 问题 | 位置 | 说明 |
|------|------|------|
| 工作流 YAML 上传 | `WorkflowPage.tsx:480` | 注释 "这里应该调用后端 API 上传文件"，为占位逻辑 |
| API 地址不可配置 | `api.ts:15` | `API_BASE` 硬编码 `localhost:8000`，Settings 页面的 API 地址配置不生效 |
| Agent 控制 API 未封装 | `AgentsPage.tsx` | 直接 `fetch('/agents/control/*')`，未使用 `api.ts` 封装 |

### 5.2 UI 与数据问题

| 问题 | 位置 | 说明 |
|------|------|------|
| 进度条宽度 | `MeetingsPage.tsx` | `width: meeting.progress_summary` 为字符串 "50%"，应为数值 |
| 遗留组件未使用 | `components/` 根级 | `AgentStatusCard`、`ResourceMonitorCard`、`RecentMeetingsCard`、`ConsensusCard` 含 mock 数据，未被任何页面引用 |

### 5.3 E2E 测试与 UI 不一致

| 测试期望 | 实际 UI | 文件 |
|----------|---------|------|
| `input[placeholder="搜索 Agent..."]` | AgentsPage 无搜索框 | `e2e-workflow.spec.ts` |
| `input[name="name"]`, `select[name="role"]` | 表单无 name 属性 | `e2e-workflow.spec.ts` |
| `text=创建新会议` | 实际文案 "创建会议" | `e2e-workflow.spec.ts` |
| `button:has-text("新建工作流")` | 无此按钮 | `e2e-workflow.spec.ts` |
| `input[name="apiBaseUrl"]` | 配置表单无 name | `e2e-workflow.spec.ts` |
| `text=配置已保存` | 实际文案 "已保存" | `e2e-workflow.spec.ts` |
| `[data-testid="agent-list"]` | 未使用 data-testid | `e2e-workflow.spec.ts` |

---

## 六、设计文档与实现的不一致

| 设计文档要求 | 实际实现 | 差异说明 |
|-------------|----------|----------|
| API 层使用 Express/Fastify (Node.js) | 使用 Python FastAPI | CLAUDE.md 中已更正，design-spec 未同步 |
| 前端使用 shadcn/ui | 纯 Tailwind CSS + 自定义样式 | 未使用 shadcn/ui 组件库 |
| 前端使用 Zustand 状态管理 | 使用 React useState + useEffect | 无全局状态管理 |
| 前端使用 WebSocket 实时更新 | 使用轮询（5-10 秒） | WebSocket 后端已实现但前端未接入 |
| Consensus Engine（共识引擎） | 未作为独立服务实现 | 共识逻辑在 MeetingRecorder 中 |
| Model Router（模型路由） | 在 LLMService 中实现 | 位置不同但功能存在 |
| `.doc/dialogues/` 目录 | 不存在 | 对话存储未实现 |
| `.doc/progress/` 目录 | 不存在 | 进度存储在 Agent state 中 |
| `.doc/shared/` 目录 | 不存在 | 共享知识库未实现 |

---

## 七、后端测试结果

```
StorageService       [PASS]  ✅
FileLockService      [PASS]  ✅
HeartbeatService     [PASS]  ✅
AgentRegistry        [PASS]  ✅
MeetingScheduler     [PASS]  ✅
MeetingRecorder      [PASS]  ✅
ResourceManager      [PASS]  ✅
WorkflowEngine       [PASS]  ✅
RoleAllocator        [PASS]  ✅
总计: 9/9 通过
```

### 未覆盖的服务测试

| 服务 | 说明 |
|------|------|
| HumanInputService | 路由已接入，但缺少单独测试 |
| LLMService | 需要 API Key，难以自动化 |
| AgentExecutor | 依赖 LLM，需 mock 测试 |
| ProcessManager | 需要实际进程管理环境 |

---

## 八、后续修改步骤（按优先级排序）

### 阶段 1：路由层接入服务层（P0 - 最高优先级）

这是整个项目的核心瓶颈，完成后前后端即可真正联通。

#### 步骤 1.1：改造 `agents.py` 路由
```
目标：用 AgentRegistry 服务替换内存 agents_db
涉及：backend/app/routers/agents.py
方法：
  1. 导入 get_agent_registry
  2. list_agents → registry.list_agents()
  3. register_agent → registry.register_agent()
  4. get_agent → registry.get_agent()
  5. get/update_agent_state → registry.get_state() / update_state()
  6. 删除 agents_db、agent_states_db 内存变量
验证：curl /api/agents 返回真实数据（或空列表）
```

#### 步骤 1.2：改造 `locks.py` 路由
```
目标：用 FileLockService 替换内存 locks_db
涉及：backend/app/routers/locks.py
方法：
  1. 导入 get_file_lock_service
  2. list_locks → service.get_locks()
  3. acquire_lock → service.acquire_lock()
  4. release_lock → service.release_lock()
  5. check_lock → service.check_locked()
  6. 删除 locks_db 硬编码数据
验证：curl /api/locks 返回空列表或真实锁状态
```

#### 步骤 1.3：改造 `heartbeats.py` 路由
```
目标：用 HeartbeatService 替换硬编码返回
涉及：backend/app/routers/heartbeats.py
方法：
  1. 导入 get_heartbeat_service
  2. list_heartbeats → service.get_all_heartbeats()
  3. update_heartbeat → service.update_heartbeat()
  4. 新增 GET /timeouts?timeout_seconds=60 端点
验证：curl /api/heartbeats 返回真实数据
```

#### 步骤 1.4：改造 `meetings.py` 路由
```
目标：用 MeetingScheduler + MeetingRecorder 替换 mock
涉及：backend/app/routers/meetings.py
方法：
  1. 导入 get_meeting_scheduler, get_meeting_recorder
  2. 列表/详情 → recorder.list_meetings() / recorder.get_meeting()
  3. 创建 → recorder.create_meeting() + scheduler.create_meeting()
  4. 讨论/进度/完成 → recorder.add_discussion() / update_progress() / end_meeting()
  5. 新增 GET /:id/queue → scheduler.get_queue()
  6. 新增 POST /:id/wait → scheduler.wait_for_meeting()
  7. 新增 POST /:id/end → scheduler.end_meeting()
验证：创建会议 → 查看列表 → 添加讨论 → 完成会议 全流程
```

#### 步骤 1.5：改造 `roles.py` 路由
```
目标：用 RoleAllocator 替换硬编码
涉及：backend/app/routers/roles.py
方法：
  1. 导入 get_role_allocator
  2. get_primary_role → allocator.get_primary_role()
  3. allocate_roles → allocator.allocate_roles()
  4. explain_roles → allocator.explain_allocation()
验证：curl /api/roles/primary 返回基于任务分析的角色
```

#### 步骤 1.6：改造 `resources.py` 路由
```
目标：用 ResourceManager 替换 mock
涉及：backend/app/routers/resources.py
方法：
  1. 导入 get_resource_manager
  2. execute_task → manager.execute_task()
  3. parse_task → manager.parse_task_files()
验证：/api/execute 真正执行任务（加锁→执行→释放锁）
```

### 阶段 2：修复代码问题（P1）

#### 步骤 2.1：修复依赖
```
文件：backend/requirements.txt
操作：添加 aiohttp 依赖
```

#### 步骤 2.2：前端 API 地址可配置
```
文件：frontend/src/lib/api.ts
操作：
  1. API_BASE 从 localStorage 读取（Settings 页面保存的值）
  2. 提供 fallback 默认值 http://localhost:8000/api
```

#### 步骤 2.3：封装 Agent 控制 API
```
文件：frontend/src/lib/api.ts + frontend/src/pages/AgentsPage.tsx
操作：
  1. 在 api.ts 中添加 agentControlApi 模块
  2. AgentsPage 改用封装的 API 调用
```

#### 步骤 2.4：修复进度条宽度问题
```
文件：frontend/src/pages/MeetingsPage.tsx
操作：progress_summary 为 "50%" 字符串，作为 CSS width 值可以工作，
      但建议改为数值计算更健壮
```

### 阶段 3：补全缺失功能（P2）

#### 步骤 3.1：实现工作流 YAML 上传
```
后端：新增 POST /api/workflows/upload 端点
前端：WorkflowPage.tsx handleFileUpload 对接真实 API
```

#### 步骤 3.2：前端接入 WebSocket
```
目标：替代轮询，使用 WebSocket 实时更新
文件：新增 frontend/src/lib/websocket.ts
操作：
  1. 连接 ws://localhost:8000/ws/client/{clientId}
  2. Dashboard、Resources 页面订阅实时事件
  3. 保留轮询作为降级方案
```

#### 步骤 3.3：清理遗留组件
```
组件：AgentStatusCard, ResourceMonitorCard, RecentMeetingsCard, ConsensusCard
操作：评估是否仍需要，不需要则删除，需要则替换 mock 数据为 API 调用
```

### 阶段 4：测试完善（P2）

#### 步骤 4.1：更新 E2E 测试选择器
```
文件：frontend/tests/e2e-workflow.spec.ts
操作：将测试选择器更新为与当前 UI 一致
  - 搜索框选择器
  - 表单 name 属性
  - 按钮文案
  - data-testid 属性
```

#### 步骤 4.2：补充后端路由集成测试
```
位置：backend/
操作：
  1. 新增 test_api_integration.py
  2. 使用 TestClient 测试所有 API 端点
  3. 验证路由→服务→存储完整链路
```

#### 步骤 4.3：补充服务测试
```
新增测试：
  - HumanInputService 单元测试
  - ProcessManager 单元测试
  - AgentExecutor mock 测试（mock LLM 调用）
```

### 阶段 5：同步文档（P3）

#### 步骤 5.1：更新设计文档
```
文件：docs/design-spec.md
操作：
  1. API 层技术栈改为 Python FastAPI（非 Express/Fastify）
  2. 前端技术栈更新（无 shadcn/ui，无 Zustand）
  3. 存储目录结构与实际一致
```

---

## 九、推荐执行顺序

```
Week 1: 阶段 1（路由层改造）
  Day 1: agents.py + locks.py
  Day 2: heartbeats.py + meetings.py
  Day 3: roles.py + resources.py
  Day 4: 联调验证，修复接口对接问题

Week 2: 阶段 2 + 3（代码修复 + 缺失功能）
  Day 1: 依赖修复 + API 地址可配置
  Day 2: Agent 控制 API 封装 + 进度条修复
  Day 3: 工作流上传实现
  Day 4: WebSocket 接入（可选）

Week 3: 阶段 4 + 5（测试 + 文档）
  Day 1-2: E2E 测试更新
  Day 3: 后端集成测试
  Day 4: 文档同步
```

---

## 十、风险提示

1. **路由改造可能引发前端数据格式变化**：当前前端适配的是 mock 数据的格式，改为真实服务后，返回值字段名/结构可能不同，需要同步调整前端代码。

2. **会议的栅栏同步是阻塞调用**：`wait_for_meeting` 会阻塞请求直到所有参会者到齐，在 HTTP API 中需要设置合适的超时时间，或改为异步轮询机制。

3. **RoleAllocator 依赖 LLM API**：如果没有配置 API Key，角色分配会使用 fallback 逻辑，需要确认 fallback 行为是否满足需求。

4. **数据持久化**：服务层使用 `.doc/` 目录文件存储，路由改造后原来内存中的临时数据会丢失，需要确保前端能正确处理空数据状态。

---

## 附录：修复记录（2026-03-10）

### 已完成的修改

| 序号 | 修改项 | 文件 | 说明 |
|------|--------|------|------|
| 1 | agents.py 路由改造 | `backend/app/routers/agents.py` | 移除 `agents_db` 内存变量，接入 `AgentRegistry` 服务 |
| 2 | locks.py 路由改造 | `backend/app/routers/locks.py` | 移除 `locks_db` 硬编码数据，接入 `FileLockService` 服务 |
| 3 | heartbeats.py 路由改造 | `backend/app/routers/heartbeats.py` | 移除 mock 返回，接入 `HeartbeatService`，新增 `/timeouts` 端点 |
| 4 | meetings.py 路由改造 | `backend/app/routers/meetings.py` | 移除 mock，接入 `MeetingScheduler` + `MeetingRecorder`，新增 `/queue` `/wait` `/end` 端点 |
| 5 | roles.py 路由改造 | `backend/app/routers/roles.py` | 移除硬编码角色分配，接入 `RoleAllocator` 服务 |
| 6 | resources.py 路由改造 | `backend/app/routers/resources.py` | 移除 mock，`/execute` `/parse-task` 接入 `ResourceManager` |
| 7 | 依赖修复 | `backend/requirements.txt` | 添加 `aiohttp>=3.9.0` |
| 8 | API 地址可配置 | `frontend/src/lib/api.ts` | `API_BASE` 从 localStorage 读取，Settings 页面配置生效 |
| 9 | Agent 控制 API 封装 | `frontend/src/lib/api.ts` | 新增 `agentControlApi` 模块，统一封装 |
| 10 | AgentsPage 去硬编码 | `frontend/src/pages/AgentsPage.tsx` | 移除 `API_BASE` 硬编码，使用 `agentControlApi` |
| 11 | 工作流上传功能 | `backend/app/routers/workflows.py` + `frontend/src/pages/WorkflowPage.tsx` | 新增 `POST /upload` 端点，前端实现真实上传 |
| 12 | API 集成测试 | `backend/test_api_integration.py` | 新增 43 项 API 端点集成测试 |

### 测试结果

```
服务层测试:  9/9 通过
API 集成测试: 43/43 通过
```

### 剩余待办

| 优先级 | 项目 | 说明 |
|--------|------|------|
| P2 | WebSocket 实时更新 | 前端仍用轮询，后端 WebSocket 已实现但前端未接入 |
| P2 | 清理遗留组件 | `AgentStatusCard` 等 4 个含 mock 数据的旧组件未被引用 |
| P3 | E2E 测试选择器同步 | 约 7 处选择器/文案与当前 UI 不一致 |
| P3 | 设计文档同步 | `design-spec.md` 中技术栈描述需更新 |
| P3 | 补充服务测试 | HumanInputService、ProcessManager、AgentExecutor 缺少单独测试 |