694 lines
25 KiB
Markdown
694 lines
25 KiB
Markdown
|
# Swarm - 多 Agent 协作系统设计文档
|
|||
|
|
|
|||
|
|
> 版本：1.0
|
|||
|
|
> 日期：2026-03-04
|
|||
|
|
> 作者：Swarm Team
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 目录
|
|||
|
|
|
|||
|
|
1. [项目概述](#1-项目概述)
|
|||
|
|
2. [系统架构](#2-系统架构)
|
|||
|
|
3. [插件化 CLI 工具适配](#3-插件化-cli-工具适配)
|
|||
|
|
4. [资源管理与文件锁](#4-资源管理与文件锁)
|
|||
|
|
5. [会议与共识机制](#5-会议与共识机制)
|
|||
|
|
6. [动态角色分配](#6-动态角色分配)
|
|||
|
|
7. [多模型支持](#7-多模型支持)
|
|||
|
|
8. [共享存储结构](#8-共享存储结构)
|
|||
|
|
9. [技术栈](#9-技术栈)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 项目概述
|
|||
|
|
|
|||
|
|
### 1.1 核心目标
|
|||
|
|
|
|||
|
|
构建一个通用的多 Agent 协作框架，支持：
|
|||
|
|
|
|||
|
|
- **多工具接入**：Claude Code CLI、Kimi CLI、OpenCode 等命令行 AI 工具
|
|||
|
|
- **会议驱动协作**：通过会议流程组织 Agent 间的协作
|
|||
|
|
- **资源自动管理**：声明式资源管理，Agent 无需手动处理锁
|
|||
|
|
- **协作共识**：Agent 之间通过讨论达成共识，而非简单投票
|
|||
|
|
- **动态角色**：AI 根据任务自动分析并分配角色
|
|||
|
|
- **多模型支持**：支持多种 LLM，智能路由与故障转移
|
|||
|
|
|
|||
|
|
### 1.2 设计原则
|
|||
|
|
|
|||
|
|
| 原则 | 说明 |
|
|||
|
|
|-----|------|
|
|||
|
|
| 插件化 | CLI 工具通过适配器层接入，实现统一接口 |
|
|||
|
|
| 声明式 | Agent 只声明意图，系统自动管理资源 |
|
|||
|
|
| 会议驱动 | Workflow 定义会议节点，栅栏同步触发 |
|
|||
|
|
| 协作共识 | 多轮讨论、迭代提案、AI 收敛判断 |
|
|||
|
|
| AI 分配 | LLM 分析任务自动分配最优角色 |
|
|||
|
|
| 可靠性 | 超时 + 心跳 + finally + 看门狗多层保障 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 系统架构
|
|||
|
|
|
|||
|
|
### 2.1 整体架构图
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 用户界面层 │
|
|||
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|||
|
|
│ │ Web UI │ │ CLI 工具 │ │ API 接口 │ │ VSCode 插件 │ │
|
|||
|
|
│ │ (React/TS) │ │ (Node.js) │ │ (Express) │ │ (TypeScript)│ │
|
|||
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|||
|
|
↕
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 协调层 (Python) │
|
|||
|
|
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
|
|||
|
|
│ │ Workflow Engine │ │ Meeting Scheduler│ │ Resource Manager │ │
|
|||
|
|
│ │ (工作流编排) │ │ (栅栏同步) │ │ (文件锁+心跳) │ │
|
|||
|
|
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
|
|||
|
|
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
|
|||
|
|
│ │ Role Allocator │ │ Consensus Engine │ │ Model Router │ │
|
|||
|
|
│ │ (AI角色分配) │ │ (协作共识) │ │ (多模型路由) │ │
|
|||
|
|
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|||
|
|
↕
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ Agent 适配层 │
|
|||
|
|
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ CLIPluginAdapter Interface │ │
|
|||
|
|
│ │ + execute() + join_meeting() + write_state() + read_others() │ │
|
|||
|
|
│ └─────────────────────────────────────────────────────────────────────┘ │
|
|||
|
|
│ ↓ │
|
|||
|
|
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
|||
|
|
│ │ ClaudeCode │ │ KimiCLI │ │ OpenCode │ │ 自定义... │ │
|
|||
|
|
│ │ Adapter │ │ Adapter │ │ Adapter │ │ Adapter │ │
|
|||
|
|
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|||
|
|
↕
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 模型层 │
|
|||
|
|
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
|||
|
|
│ │ Anthropic │ │ OpenAI │ │ Google │ │ DeepSeek │ │
|
|||
|
|
│ │ API │ │ API │ │ API │ │ API │ │
|
|||
|
|
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
|
|||
|
|
│ ┌────────────────────────────────────────────────────────────┐ │
|
|||
|
|
│ │ Ollama (本地模型) │ │
|
|||
|
|
│ └────────────────────────────────────────────────────────────┘ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|||
|
|
↕
|
|||
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 共享存储层 (.doc/) │
|
|||
|
|
│ ├── agents/ ├── dialogues/ ├── progress/ │
|
|||
|
|
│ ├── resources/ ├── meetings/ ├── cache/ │
|
|||
|
|
│ └── workflow/ │
|
|||
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 插件化 CLI 工具适配
|
|||
|
|
|
|||
|
|
### 3.1 统一接口设计
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
interface CLIPluginAdapter:
|
|||
|
|
"""CLI 工具适配器统一接口"""
|
|||
|
|
|
|||
|
|
id: str
|
|||
|
|
name: str
|
|||
|
|
version: str
|
|||
|
|
|
|||
|
|
# 核心能力
|
|||
|
|
def execute(task: Task) -> Result:
|
|||
|
|
"""执行任务"""
|
|||
|
|
pass
|
|||
|
|
|
|||
|
|
def join_meeting(meeting_id: str) -> None:
|
|||
|
|
"""加入会议等待队列"""
|
|||
|
|
pass
|
|||
|
|
|
|||
|
|
def write_state(state: dict) -> None:
|
|||
|
|
"""写入自己的状态文件"""
|
|||
|
|
pass
|
|||
|
|
|
|||
|
|
def read_others(agent_id: str) -> dict:
|
|||
|
|
"""读取其他 Agent 的状态"""
|
|||
|
|
pass
|
|||
|
|
|
|||
|
|
def update_heartbeat() -> None:
|
|||
|
|
"""更新心跳"""
|
|||
|
|
pass
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.2 预置适配器
|
|||
|
|
|
|||
|
|
| 适配器 | CLI 工具 | 特点 |
|
|||
|
|
|--------|---------|------|
|
|||
|
|
| ClaudeCodeAdapter | Claude Code CLI | MCP 支持，代码审查强 |
|
|||
|
|
| KimiCLIAdapter | Kimi CLI | ACP 协议，Zsh 集成 |
|
|||
|
|
| OpenCodeAdapter | OpenCode | 快速代码生成 |
|
|||
|
|
| CustomAdapter | 自定义 | 扩展接口 |
|
|||
|
|
|
|||
|
|
### 3.3 适配器实现示例
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
class ClaudeCodeAdapter(CLIPluginAdapter):
|
|||
|
|
def __init__(self, config: dict):
|
|||
|
|
self.id = "claude-code-001"
|
|||
|
|
self.name = "Claude Code"
|
|||
|
|
self.config = config
|
|||
|
|
self.executor = TaskExecutor(self.id, resource_manager)
|
|||
|
|
|
|||
|
|
def execute(self, task: Task) -> Result:
|
|||
|
|
# 通过 TaskExecutor 自动管理资源
|
|||
|
|
return self.executor.execute(task.description)
|
|||
|
|
|
|||
|
|
def join_meeting(self, meeting_id: str):
|
|||
|
|
return meeting_scheduler.wait_for_meeting(self.id, meeting_id)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 资源管理与文件锁
|
|||
|
|
|
|||
|
|
### 4.1 核心设计
|
|||
|
|
|
|||
|
|
**声明式资源管理**：Agent 只需要声明"我要修改这个文件"，系统自动获取锁、执行任务、释放锁。
|
|||
|
|
|
|||
|
|
### 4.2 TaskExecutor 包装层
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
class TaskExecutor:
|
|||
|
|
"""任务执行器 - 自动管理资源生命周期"""
|
|||
|
|
|
|||
|
|
def execute(self, task_description: str) -> str:
|
|||
|
|
# 1. 解析意图，识别需要的文件
|
|||
|
|
required_files = self._parse_required_files(task_description)
|
|||
|
|
|
|||
|
|
# 2. 获取所有需要的锁
|
|||
|
|
self._acquire_all_locks(required_files, task_description)
|
|||
|
|
|
|||
|
|
try:
|
|||
|
|
# 3. 执行实际任务
|
|||
|
|
result = self._do_execute(task_description)
|
|||
|
|
return result
|
|||
|
|
finally:
|
|||
|
|
# 4. 无论发生什么，都释放锁
|
|||
|
|
self._release_all_locks()
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4.3 可靠性保障机制
|
|||
|
|
|
|||
|
|
| 机制 | 解决问题 | 触发方式 |
|
|||
|
|
|-----|---------|---------|
|
|||
|
|
| 超时释放 | 锁忘记释放 | 定时器扫描 |
|
|||
|
|
| 心跳机制 | Agent 挂了检测 | 定时器 + 心跳超时 |
|
|||
|
|
| Lease 上下文管理器 | 代码异常退出 | Python `with` / `finally` |
|
|||
|
|
| 生命周期 Hooks | 进程崩溃清理 | `atexit` + 看门狗 |
|
|||
|
|
| 看门狗进程 | 整个系统挂了 | 独立进程监控 |
|
|||
|
|
| 原子操作 | 并发冲突 | 文件锁 |
|
|||
|
|
|
|||
|
|
### 4.4 Agent 使用方式
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# Agent 代码 - 完全不需要关心锁
|
|||
|
|
|
|||
|
|
class ClaudeCodeAgent:
|
|||
|
|
def fix_login_bug(self):
|
|||
|
|
# 只需要描述任务，锁完全透明
|
|||
|
|
result = self.executor.execute(
|
|||
|
|
"修改 src/main.py 修复登录 bug"
|
|||
|
|
)
|
|||
|
|
return result
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 会议与共识机制
|
|||
|
|
|
|||
|
|
### 5.1 栅栏同步
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
class MeetingScheduler:
|
|||
|
|
"""会议调度器 - 实现栅栏同步"""
|
|||
|
|
|
|||
|
|
def wait_for_meeting(self, agent_id: str, meeting_id: str):
|
|||
|
|
"""
|
|||
|
|
Agent 调用此方法表示"我准备好了，等会议"
|
|||
|
|
最后一个到达的 Agent 触发会议
|
|||
|
|
"""
|
|||
|
|
queue = self._load_queue()
|
|||
|
|
|
|||
|
|
# 加入等待队列
|
|||
|
|
queue[meeting_id]["waiting_agents"].append(agent_id)
|
|||
|
|
|
|||
|
|
# 检查是否所有人都准备好了
|
|||
|
|
if self._is_everyone_ready(meeting_id):
|
|||
|
|
self._start_meeting(meeting_id)
|
|||
|
|
return "meeting_started"
|
|||
|
|
return "waiting"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5.2 协作式共识流程
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌─────────────────────────────────────────────────────────────┐
|
|||
|
|
│ 协作共识流程 │
|
|||
|
|
│ │
|
|||
|
|
│ 第一阶段：收集初步想法 │
|
|||
|
|
│ Agent A: "建议用 JWT，因为..." │
|
|||
|
|
│ Agent B: "我建议用 Session，因为..." │
|
|||
|
|
│ Agent C: "两者结合可能更好..." │
|
|||
|
|
│ │
|
|||
|
|
│ 第二阶段：讨论与迭代（最多5轮） │
|
|||
|
|
│ → Agent 互相质疑、补充、融合 │
|
|||
|
|
│ → 根据讨论更新提案 │
|
|||
|
|
│ → 检查收敛性 │
|
|||
|
|
│ │
|
|||
|
|
│ 第三阶段：生成共识版本 │
|
|||
|
|
│ → 合并相似提案 │
|
|||
|
|
│ → 记录讨论过程 │
|
|||
|
|
│ → 生成会议文件 │
|
|||
|
|
└─────────────────────────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5.3 会议文件结构
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
---
|
|||
|
|
meeting_id: requirement_review_20260304_103000
|
|||
|
|
date: 2026-03-04
|
|||
|
|
attendees: [claude-code-001, kimi-cli-002, opencode-003]
|
|||
|
|
consensus_type: collaborative
|
|||
|
|
iterations: 3
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 需求评审会议
|
|||
|
|
|
|||
|
|
## 参会者
|
|||
|
|
- `claude-code-001` (权重: 1.5)
|
|||
|
|
- `kimi-cli-002` (权重: 1.0)
|
|||
|
|
- `opencode-003` (权重: 1.2)
|
|||
|
|
|
|||
|
|
## 讨论过程
|
|||
|
|
|
|||
|
|
### 第一轮：初步想法
|
|||
|
|
[各 Agent 的初步提案...]
|
|||
|
|
|
|||
|
|
### 第二轮：讨论
|
|||
|
|
[互相质疑、补充的过程...]
|
|||
|
|
|
|||
|
|
### 第三轮：迭代
|
|||
|
|
[根据讨论更新的提案...]
|
|||
|
|
|
|||
|
|
## 最终共识
|
|||
|
|
[达成的共识内容...]
|
|||
|
|
|
|||
|
|
## 贡献记录
|
|||
|
|
| Agent | 主要贡献 |
|
|||
|
|
|-------|---------|
|
|||
|
|
| claude-code-001 | ... |
|
|||
|
|
| kimi-cli-002 | ... |
|
|||
|
|
| opencode-003 | ... |
|
|||
|
|
|
|||
|
|
## 后续行动
|
|||
|
|
1. [ ] ...
|
|||
|
|
2. [ ] ...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. 动态角色分配
|
|||
|
|
|
|||
|
|
### 6.1 AI 驱动的角色分配
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
class AIRoleAllocator:
|
|||
|
|
"""AI 驱动的角色分配器"""
|
|||
|
|
|
|||
|
|
def allocate_roles(self, task: Task, available_agents: List[str]) -> dict:
|
|||
|
|
"""
|
|||
|
|
分析任务，自动分配角色给各 Agent
|
|||
|
|
"""
|
|||
|
|
# 获取所有 Agent 的能力描述
|
|||
|
|
agent_capabilities = self._get_agent_capabilities(available_agents)
|
|||
|
|
|
|||
|
|
# 构造提示词，让 AI 分析
|
|||
|
|
prompt = f"""
|
|||
|
|
你是一个团队协调 AI，需要为以下任务分配角色。
|
|||
|
|
|
|||
|
|
## 任务描述
|
|||
|
|
{task.description}
|
|||
|
|
|
|||
|
|
## 可用的 Agent 及其能力
|
|||
|
|
{self._format_capabilities(agent_capabilities)}
|
|||
|
|
|
|||
|
|
请分析任务需求，为每个 Agent 分配最合适的角色。
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
# 调用 LLM 分析
|
|||
|
|
response = self.llm_client.complete(prompt)
|
|||
|
|
allocation = json.loads(response)
|
|||
|
|
|
|||
|
|
# 应用角色分配
|
|||
|
|
for assignment in allocation["role_assignments"]:
|
|||
|
|
self._apply_role(
|
|||
|
|
assignment["agent_id"],
|
|||
|
|
assignment["role"],
|
|||
|
|
assignment["reason"]
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
return allocation
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 6.2 可用角色
|
|||
|
|
|
|||
|
|
| 角色 | 名称 | 能力 | 权重 |
|
|||
|
|
|-----|------|------|------|
|
|||
|
|
| pm | 产品经理 | 需求分析、优先级排序、用户故事 | 1.5 |
|
|||
|
|
| architect | 架构师 | 系统设计、技术选型、性能规划 | 1.5 |
|
|||
|
|
| developer | 开发者 | 编码、单元测试、代码审查 | 1.0 |
|
|||
|
|
| qa | 测试工程师 | 测试用例、自动化测试、bug报告 | 1.2 |
|
|||
|
|
| reviewer | 代码审查者 | 代码审查、安全检查、性能分析 | 1.3 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. 多模型支持
|
|||
|
|
|
|||
|
|
### 7.1 智能路由策略
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
class MultiModelRouter:
|
|||
|
|
"""多模型路由器"""
|
|||
|
|
|
|||
|
|
def route(self, task: Task, context: dict) -> str:
|
|||
|
|
"""
|
|||
|
|
智能路由：根据任务类型选择最合适的模型
|
|||
|
|
"""
|
|||
|
|
task_type = self._classify_task(task)
|
|||
|
|
|
|||
|
|
routing_rules = {
|
|||
|
|
"complex_reasoning": ("anthropic", "claude-opus-4.6"),
|
|||
|
|
"code_generation": ("anthropic", "claude-sonnet-4.6"),
|
|||
|
|
"simple_task": ("anthropic", "claude-haiku-4.6"),
|
|||
|
|
"cost_sensitive": ("deepseek", "deepseek-chat"),
|
|||
|
|
"local_privacy": ("ollama", "llama3"),
|
|||
|
|
"multimodal": ("google", "gemini-2.5-flash")
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
provider, model = routing_rules.get(task_type, default)
|
|||
|
|
return self.providers[provider].complete(model, task, context)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 7.2 故障转移
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
def route_with_failover(self, task: Task, context: dict) -> str:
|
|||
|
|
"""带故障转移的路由"""
|
|||
|
|
primary_route = self._get_primary_route(task)
|
|||
|
|
fallback_routes = self._get_fallback_routes()
|
|||
|
|
|
|||
|
|
# 尝试主路由
|
|||
|
|
try:
|
|||
|
|
return self._execute_route(primary_route, task, context)
|
|||
|
|
except Exception:
|
|||
|
|
pass
|
|||
|
|
|
|||
|
|
# 尝试备选路由
|
|||
|
|
for route in fallback_routes:
|
|||
|
|
try:
|
|||
|
|
return self._execute_route(route, task, context)
|
|||
|
|
except Exception:
|
|||
|
|
pass
|
|||
|
|
|
|||
|
|
# 全部失败，使用最简单的本地模型
|
|||
|
|
return self._execute_local_fallback(task, context)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. 共享存储结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
.doc/
|
|||
|
|
├── agents/ # Agent 注册与状态
|
|||
|
|
│ ├── registry.json # 所有已注册 Agent 列表
|
|||
|
|
│ ├── claude-code-001/ # 每个 Agent 的独立目录
|
|||
|
|
│ │ ├── config.json # Agent 配置
|
|||
|
|
│ │ ├── state.json # 当前状态
|
|||
|
|
│ │ ├── history.json # 历史记录
|
|||
|
|
│ │ └── capabilities.json # 能力声明
|
|||
|
|
│ └── ...
|
|||
|
|
│
|
|||
|
|
├── dialogues/ # Agent 间对话记录
|
|||
|
|
│ └── [agent_a]_[agent_b]_[timestamp].json
|
|||
|
|
│
|
|||
|
|
├── progress/ # 工程进度
|
|||
|
|
│ ├── project_state.json # 项目整体状态
|
|||
|
|
│ ├── milestones.json # 里程碑
|
|||
|
|
│ └── tasks.json # 任务列表
|
|||
|
|
│
|
|||
|
|
├── resources/ # 资源分配
|
|||
|
|
│ ├── resource_pool.json # 资源池状态
|
|||
|
|
│ ├── file_locks.json # 文件锁
|
|||
|
|
│ └── allocation_log.json # 分配日志
|
|||
|
|
│
|
|||
|
|
├── meetings/ # 会议记录与共识
|
|||
|
|
│ ├── [YYYY-MM-DD]/
|
|||
|
|
│ │ └── [HHMMSS]_[meeting_name].md
|
|||
|
|
│ └── meeting_template.md
|
|||
|
|
│
|
|||
|
|
├── cache/ # 实时缓存
|
|||
|
|
│ ├── meeting_queue.json # 会议等待队列
|
|||
|
|
│ ├── message_bus.json # 消息总线快照
|
|||
|
|
│ ├── lock_state.json # 锁状态缓存
|
|||
|
|
│ └── heartbeats.json # Agent 心跳
|
|||
|
|
│
|
|||
|
|
├── workflow/ # 工作流定义
|
|||
|
|
│ ├── project_workflow.yaml # 项目工作流
|
|||
|
|
│ ├── meeting_definitions.yaml # 会议定义
|
|||
|
|
│ └── consensus_rules.yaml # 共识规则
|
|||
|
|
│
|
|||
|
|
└── shared/ # 共享资源
|
|||
|
|
├── knowledge_base/ # 知识库
|
|||
|
|
├── templates/ # 模板文件
|
|||
|
|
└── conventions/ # 编码规范
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 9. 技术栈
|
|||
|
|
|
|||
|
|
### 9.1 后端 (Python)
|
|||
|
|
|
|||
|
|
| 组件 | 技术选择 |
|
|||
|
|
|-----|---------|
|
|||
|
|
| 核心框架 | Python 3.12+ |
|
|||
|
|
| 异步运行时 | asyncio |
|
|||
|
|
| LLM 调用 | anthropic, openai, langchain |
|
|||
|
|
| 文件操作 | pathlib, aiofiles |
|
|||
|
|
| 进程管理 | subprocess, multiprocessing |
|
|||
|
|
| 定时任务 | APScheduler |
|
|||
|
|
|
|||
|
|
### 9.2 前端 (TypeScript)
|
|||
|
|
|
|||
|
|
| 组件 | 技术选择 |
|
|||
|
|
|-----|---------|
|
|||
|
|
| 框架 | React 18 + TypeScript |
|
|||
|
|
| UI 库 | shadcn/ui + Tailwind CSS |
|
|||
|
|
| 状态管理 | Zustand |
|
|||
|
|
| 实时通信 | WebSocket |
|
|||
|
|
| HTTP 客户端 | fetch / axios |
|
|||
|
|
|
|||
|
|
### 9.3 API 层 (Node.js)
|
|||
|
|
|
|||
|
|
| 组件 | 技术选择 |
|
|||
|
|
|-----|---------|
|
|||
|
|
| 框架 | Express / Fastify |
|
|||
|
|
| 类型检查 | TypeScript |
|
|||
|
|
| 实时通信 | Socket.IO |
|
|||
|
|
| 进程通信 | child_process |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 附录
|
|||
|
|
|
|||
|
|
### A. 参考项目
|
|||
|
|
|
|||
|
|
详见 [reference-projects.md](reference-projects.md)
|
|||
|
|
|
|||
|
|
### B. 更新日志
|
|||
|
|
|
|||
|
|
| 版本 | 日期 | 变更 |
|
|||
|
|
|-----|------|------|
|
|||
|
|
| 1.0 | 2026-03-04 | 初始版本 |
|
|||
|
|
| 1.1 | 2026-03-04 | 添加人类参与系统设计 |
|
|||
|
|
|
|||
|
|
### C. 人类参与系统
|
|||
|
|
|
|||
|
|
#### C.1 设计概述
|
|||
|
|
|
|||
|
|
人类参与者通过 `humans.json` 文件参与协作，无需 API 或 UI 调用。
|
|||
|
|
|
|||
|
|
**核心特点**：
|
|||
|
|
- 单一共享文件 `humans.json`
|
|||
|
|
- 事件驱动通知机制
|
|||
|
|
- 按优先级区分处理
|
|||
|
|
- 自动合并到会议讨论
|
|||
|
|
|
|||
|
|
#### C.2 文件结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
.doc/
|
|||
|
|
├── agents/ # Agent 目录
|
|||
|
|
├── humans.json # 人类输入共享文件
|
|||
|
|
├── meetings/ # 会议文件
|
|||
|
|
├── events/ # 事件通知
|
|||
|
|
└── task_queue.json # 任务队列
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### C.3 humans.json 结构
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"version": "1.0",
|
|||
|
|
"last_updated": "2026-03-04T14:30:00Z",
|
|||
|
|
|
|||
|
|
"participants": {
|
|||
|
|
"user001": {
|
|||
|
|
"name": "张三",
|
|||
|
|
"role": "tech_lead",
|
|||
|
|
"status": "online",
|
|||
|
|
"avatar": "👤"
|
|||
|
|
}
|
|||
|
|
},
|
|||
|
|
|
|||
|
|
// 任务需求
|
|||
|
|
"task_requests": [
|
|||
|
|
{
|
|||
|
|
"id": "req_001",
|
|||
|
|
"from": "user001",
|
|||
|
|
"timestamp": "2026-03-04T14:28:00Z",
|
|||
|
|
"priority": "high", // high | medium | low
|
|||
|
|
"type": "correction",
|
|||
|
|
"title": "登录验证方式调整",
|
|||
|
|
"content": "建议改用 Session + Redis",
|
|||
|
|
"target_files": ["src/auth/login.py"],
|
|||
|
|
"suggested_agent": "claude-code-001",
|
|||
|
|
"urgent": true,
|
|||
|
|
"status": "pending"
|
|||
|
|
}
|
|||
|
|
],
|
|||
|
|
|
|||
|
|
// 会议发言
|
|||
|
|
"meeting_comments": [
|
|||
|
|
{
|
|||
|
|
"id": "comment_001",
|
|||
|
|
"from": "user001",
|
|||
|
|
"meeting_id": "design_review",
|
|||
|
|
"timestamp": "2026-03-04T14:25:00Z",
|
|||
|
|
"type": "proposal",
|
|||
|
|
"priority": "normal",
|
|||
|
|
"content": "建议使用 SQLite，保持简单",
|
|||
|
|
"status": "pending"
|
|||
|
|
}
|
|||
|
|
],
|
|||
|
|
|
|||
|
|
// 人类状态
|
|||
|
|
"human_states": {
|
|||
|
|
"user001": {
|
|||
|
|
"status": "online",
|
|||
|
|
"current_focus": "reviewing",
|
|||
|
|
"preferred_contact": "async"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### C.4 事件驱动流程
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
人类写入 humans.json
|
|||
|
|
↓
|
|||
|
|
文件监听器触发
|
|||
|
|
↓
|
|||
|
|
写入 events/notification_stream.json
|
|||
|
|
↓
|
|||
|
|
┌───────┴────────┐
|
|||
|
|
│ │
|
|||
|
|
↓ ↓
|
|||
|
|
会议通知 任务通知
|
|||
|
|
│ │
|
|||
|
|
↓ ↓
|
|||
|
|
Agent 收到 Agent 收到
|
|||
|
|
会议通知 任务通知
|
|||
|
|
│ │
|
|||
|
|
↓ ↓
|
|||
|
|
读取会议 读取任务
|
|||
|
|
评论部分 requests
|
|||
|
|
│ │
|
|||
|
|
↓ ↓
|
|||
|
|
参与讨论 按优先级
|
|||
|
|
处理任务
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### C.5 任务优先级处理
|
|||
|
|
|
|||
|
|
| 优先级 | 处理方式 | 示例 |
|
|||
|
|
|-------|---------|------|
|
|||
|
|
| **high** + urgent | 立即中断当前任务 | 安全漏洞修复、生产故障 |
|
|||
|
|
| **high** | 尽快处理，完成当前任务后 | 功能调整、架构变更 |
|
|||
|
|
| **medium** | 加入队列，按序处理 | 功能增强、文档补充 |
|
|||
|
|
| **low** | 空闲时处理 | 优化建议、非紧急任务 |
|
|||
|
|
|
|||
|
|
#### C.6 会议中的人类发言显示
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
## 讨论记录
|
|||
|
|
|
|||
|
|
### Agent 提案
|
|||
|
|
**claude-code-001 (14:20)**:
|
|||
|
|
> 建议使用 JWT + Refresh Token...
|
|||
|
|
|
|||
|
|
### 人类发言（高优先级）
|
|||
|
|
**user001 [HUMAN] ⚠️ (14:22)**:
|
|||
|
|
> 我反对使用 JWT。我们的数据量不大，SQLite + Session 就够了。
|
|||
|
|
>
|
|||
|
|
> **优先级：HIGH**
|
|||
|
|
|
|||
|
|
### Agent 响应
|
|||
|
|
**kimi-cli-002 (14:23)**:
|
|||
|
|
> 收到用户反馈，重新评估方案...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### C.7 前端输入实现
|
|||
|
|
|
|||
|
|
前端提供任务输入栏，输入后：
|
|||
|
|
|
|||
|
|
1. 写入 `humans.json` 的 `task_requests`
|
|||
|
|
2. 记录发送时间戳
|
|||
|
|
3. 触发文件监听事件
|
|||
|
|
4. Agent 读取并处理
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
// 提交任务
|
|||
|
|
function submitTask(content, priority = "medium") {
|
|||
|
|
const request = {
|
|||
|
|
id: `req_${Date.now()}`,
|
|||
|
|
from: "user001",
|
|||
|
|
timestamp: new Date().toISOString(),
|
|||
|
|
priority: priority,
|
|||
|
|
type: "user_task",
|
|||
|
|
content: content,
|
|||
|
|
status: "pending"
|
|||
|
|
};
|
|||
|
|
|
|||
|
|
// 写入 humans.json
|
|||
|
|
humans.task_requests.push(request);
|
|||
|
|
// 保存文件...
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
*文档结束*
|