302 lines
10 KiB
Markdown
302 lines
10 KiB
Markdown
# 核心模块设计 — 多代理协调器 (Coordinator)
|
||
|
||
> 所属项目: free-code .NET 10 重写
|
||
> 文档类型: 核心模块设计
|
||
> 原始代码来源: `../../src/coordinator/`、`../../src/assistant/`
|
||
> 原始设计意图: 将单轮 LLM 交互扩展为多代理编排，负责 worker 生成、消息路由、团队管理与协调模式切换
|
||
> 上级文档: [核心模块设计总览](核心模块设计.md)
|
||
> 交叉参考: [工具系统](核心模块设计-工具系统.md) | [后台任务管理](../基础设施设计/基础设施设计-后台任务管理.md)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
多代理协调器是 free-code 中用于“把工作拆给多个 worker”的编排层。它不是简单的工具调用器，而是面向复杂任务的调度中枢：当用户问题可被拆分为研究、实现、验证等多个并行分支时，协调器负责创建 worker、下发上下文、接收回传结果，并在需要时继续同一 worker 的上下文。
|
||
|
||
原始源码中，`../../src/coordinator/coordinatorMode.ts` 承担了本模块的核心语义：定义 coordinator mode 的开关、worker 可用工具集合、系统提示词、session mode 匹配逻辑，以及 worker 结果的消息协议。`../../src/assistant/` 则提供与会话历史、会话筛选和辅助选择相关的配套能力，可视为协调器在“恢复旧会话”和“读取历史事件”场景下的支撑模块。
|
||
|
||
在 .NET 10 重写中，本模块应被抽象为独立服务层，避免与 QueryEngine、工具系统、后台任务管理直接耦合，同时保留原有行为：
|
||
|
||
- 允许 coordinator 生成 worker 并并发分发任务
|
||
- 允许 worker 通过消息队列继续执行
|
||
- 允许在会话恢复时自动匹配 coordinator/normal 模式
|
||
- 允许读取会话历史以重建协作上下文
|
||
|
||
---
|
||
|
||
## 设计职责
|
||
|
||
### 1. 多代理任务编排
|
||
|
||
协调器负责将一个高层目标拆解为多个子任务，并为每个子任务创建独立 worker。worker 适合执行以下类型工作：
|
||
|
||
- 代码库研究
|
||
- 定向实现
|
||
- 验证与测试
|
||
- 失败修复
|
||
|
||
### 2. worker 生命周期管理
|
||
|
||
协调器需掌握 worker 的创建、继续、停止与结果归档。worker 不是一次性调用；其价值在于保留已加载上下文后继续推进。
|
||
|
||
### 3. 代理间消息路由
|
||
|
||
worker 的结果以结构化任务通知返回，协调器再据此向用户总结，或把后续指令发回同一个 worker。
|
||
|
||
### 4. 团队协作管理
|
||
|
||
协调器支持 team create / delete / send-message 这类“代理团队”操作，用于将多个 worker 视为一个协作单元管理。
|
||
|
||
### 5. 会话模式同步
|
||
|
||
当用户恢复旧会话时，协调器需要根据保存的 session mode 自动切换当前环境变量，确保继续运行时处于正确的 coordinator/normal 模式。
|
||
|
||
---
|
||
|
||
## 原始实现要点
|
||
|
||
### `../../src/coordinator/coordinatorMode.ts`
|
||
|
||
该文件是本模块的语义核心，包含以下能力：
|
||
|
||
#### coordinator 模式开关
|
||
|
||
`isCoordinatorMode()` 通过 feature gate `COORDINATOR_MODE` 和环境变量 `CLAUDE_CODE_COORDINATOR_MODE` 判断当前是否进入协调模式。
|
||
|
||
#### 会话模式匹配
|
||
|
||
`matchSessionMode(sessionMode)` 会比较当前模式与已恢复会话记录的模式：
|
||
|
||
- 若一致，直接返回
|
||
- 若不一致，自动翻转环境变量
|
||
- 同时记录 analytics 事件
|
||
|
||
这说明 coordinator 是“会话状态敏感”的，而不是一个纯工具注册器。
|
||
|
||
#### worker 工具上下文
|
||
|
||
`getCoordinatorUserContext(mcpClients, scratchpadDir)` 会为 worker 注入可用工具说明：
|
||
|
||
- 简化模式下仅暴露 Bash / Read / Edit
|
||
- 常规模式下暴露 async agent 允许工具集
|
||
- 追加 MCP 服务名
|
||
- 在 scratchpad gate 开启时暴露 scratchpad 目录
|
||
|
||
#### coordinator 系统提示词
|
||
|
||
`getCoordinatorSystemPrompt()` 描述了 coordinator 的核心职责：
|
||
|
||
- 直接回答能答的问题
|
||
- 用 worker 处理适合并行化的工作
|
||
- 只能把新信息总结给用户，不能把 worker 当作对话对象
|
||
- 通过 `Agent`、`SendMessage`、`TaskStop` 管理 worker 生命周期
|
||
|
||
同时它还明确了 worker 结果的 `<task-notification>` 协议格式。
|
||
|
||
### `../../src/coordinator/workerAgent.ts`
|
||
|
||
当前快照中该文件为占位实现，但从模块命名可知，它原本承载 worker agent 的启动入口或 worker 代理适配层。在 .NET 重写里，这一职责应由 worker 启动器与任务执行器拆分承接。
|
||
|
||
### `../../src/assistant/*`
|
||
|
||
`../../src/assistant/sessionHistory.ts` 提供了会话事件分页读取：
|
||
|
||
- 先构造 OAuth 请求上下文
|
||
- 再按 `anchor_to_latest` / `before_id` 拉取分页事件
|
||
- 返回历史事件、游标与是否还有更旧内容
|
||
|
||
`sessionDiscovery.ts`、`gate.ts`、`index.ts`、`AssistantSessionChooser.tsx` 在本快照中多为占位或轻量 UI 适配，但它们体现出 assistant 模块的定位：用于发现、筛选、恢复与展示历史会话。
|
||
|
||
---
|
||
|
||
## .NET 10 接口设计
|
||
|
||
### ICoordinatorService
|
||
|
||
```csharp
|
||
public interface ICoordinatorService
|
||
{
|
||
bool IsCoordinatorMode { get; }
|
||
|
||
string? MatchSessionMode(SessionMode? sessionMode);
|
||
|
||
string BuildCoordinatorSystemPrompt(CoordinatorPromptContext context);
|
||
|
||
CoordinatorUserContext BuildWorkerContext(
|
||
IReadOnlyList<McpClientDescriptor> mcpClients,
|
||
string? scratchpadDirectory = null);
|
||
|
||
Task<WorkerHandle> SpawnWorkerAsync(
|
||
SpawnWorkerRequest request,
|
||
CancellationToken cancellationToken = default);
|
||
|
||
Task SendMessageAsync(
|
||
string workerId,
|
||
string message,
|
||
CancellationToken cancellationToken = default);
|
||
|
||
Task StopWorkerAsync(
|
||
string workerId,
|
||
CancellationToken cancellationToken = default);
|
||
|
||
Task<WorkerResult?> GetWorkerResultAsync(string workerId);
|
||
|
||
Task<TeamHandle> CreateTeamAsync(CreateTeamRequest request,
|
||
CancellationToken cancellationToken = default);
|
||
|
||
Task DeleteTeamAsync(string teamId,
|
||
CancellationToken cancellationToken = default);
|
||
|
||
Task SendTeamMessageAsync(string teamId, string message,
|
||
CancellationToken cancellationToken = default);
|
||
}
|
||
```
|
||
|
||
### IAgentWorker
|
||
|
||
```csharp
|
||
public interface IAgentWorker
|
||
{
|
||
string WorkerId { get; }
|
||
string Description { get; }
|
||
WorkerStatus Status { get; }
|
||
|
||
Task StartAsync(CancellationToken cancellationToken);
|
||
Task ContinueAsync(string message, CancellationToken cancellationToken);
|
||
Task StopAsync(CancellationToken cancellationToken);
|
||
Task<WorkerSnapshot> CaptureSnapshotAsync();
|
||
}
|
||
```
|
||
|
||
### 支撑模型
|
||
|
||
```csharp
|
||
public enum SessionMode { Normal, Coordinator }
|
||
|
||
public sealed record CoordinatorPromptContext(
|
||
string WorkingDirectory,
|
||
string? ScratchpadDirectory,
|
||
IReadOnlyList<string> AllowedTools,
|
||
IReadOnlyList<string> McpServerNames);
|
||
|
||
public sealed record CoordinatorUserContext(
|
||
string WorkerToolsContext,
|
||
string SystemPrompt);
|
||
|
||
public sealed record SpawnWorkerRequest(
|
||
string Description,
|
||
string Prompt,
|
||
string WorkerType,
|
||
string? Model = null,
|
||
string? TeamId = null);
|
||
```
|
||
|
||
这些类型遵循 .NET 命名习惯，使用 PascalCase，并把“提示词构建”和“worker 运行实例”分离，避免协调器直接依赖底层 LLM 调用细节。
|
||
|
||
---
|
||
|
||
## Worker 生成与生命周期
|
||
|
||
### 生成流程
|
||
|
||
1. 协调器接收高层目标
|
||
2. 判断是否适合并行拆分
|
||
3. 为每个分支构造自包含 prompt
|
||
4. 通过 worker 工厂创建 `IAgentWorker`
|
||
5. 记录 worker 到会话/任务存储
|
||
|
||
### 生命周期阶段
|
||
|
||
| 阶段 | 说明 |
|
||
|------|------|
|
||
| Created | worker 已创建但未启动 |
|
||
| Running | worker 正在执行 |
|
||
| Waiting | worker 暂停等待继续指令 |
|
||
| Completed | worker 已完成任务 |
|
||
| Failed | worker 执行失败 |
|
||
| Stopped | worker 被协调器主动停止 |
|
||
|
||
### 生命周期原则
|
||
|
||
- worker 应保留自己的上下文快照
|
||
- 继续 worker 时优先复用旧上下文，而不是重新启动新 worker
|
||
- 停止 worker 应保留最后状态，供后续诊断或继续执行
|
||
|
||
---
|
||
|
||
## 消息路由
|
||
|
||
### 结果回传协议
|
||
|
||
原始实现定义了 `<task-notification>` XML 作为 worker 结果消息格式。.NET 重写可保留相同语义，但建议使用结构化模型解析后再渲染给终端：
|
||
|
||
```csharp
|
||
public sealed record WorkerNotification(
|
||
string TaskId,
|
||
string Status,
|
||
string Summary,
|
||
string? Result,
|
||
WorkerUsage? Usage);
|
||
```
|
||
|
||
### 路由规则
|
||
|
||
- worker → coordinator：上报任务完成、失败、暂停、进度
|
||
- coordinator → worker：发送续作指令、修正指令、停止指令
|
||
- coordinator → 用户：仅输出总结，不暴露内部通知原文
|
||
|
||
### 设计约束
|
||
|
||
- 不能用一个 worker 检查另一个 worker
|
||
- 不能把低价值文件内容回读任务交给 worker
|
||
- 继续 worker 时必须使用其原始 task id
|
||
|
||
---
|
||
|
||
## Agent Team 管理
|
||
|
||
team 机制用于把多个 worker 归入一个协作单元，常见场景是“研究组 + 实现组 + 验证组”。
|
||
|
||
### TeamCreate
|
||
|
||
创建 team 时应生成团队 ID，并维护成员 worker、目标、状态与消息历史。
|
||
|
||
### TeamDelete
|
||
|
||
删除 team 应清理团队元数据，但不能无条件销毁已完成 worker 的结果记录。
|
||
|
||
### SendMessage
|
||
|
||
team message 应广播到 team 成员，或按策略路由给主 worker。 .NET 设计应把广播规则显式化，避免隐式分支。
|
||
|
||
---
|
||
|
||
## 关联 `../../src/assistant/` 的 .NET 设计
|
||
|
||
`../../src/assistant/` 更适合映射为“会话访问与恢复辅助服务”，建议拆为：
|
||
|
||
- `IAssistantSessionHistoryService`：读取会话事件分页
|
||
- `IAssistantSessionDiscoveryService`：发现可恢复会话
|
||
- `IAssistantSessionChooser`：会话选择 UI 适配层
|
||
|
||
其中 `sessionHistory.ts` 的分页逻辑适合直接迁移为可测试的基础设施服务，而非放进协调器主服务中。
|
||
|
||
---
|
||
|
||
## 设计要点
|
||
|
||
- coordinator 是编排层，不是 worker 执行层
|
||
- worker 适合做局部自治，coordinator 负责全局收敛
|
||
- 会话模式必须可恢复、可切换、可记录
|
||
- worker prompt 必须自包含，不能依赖隐式上下文
|
||
- 协调器输出面向用户，内部通知面向系统
|
||
|
||
---
|
||
|
||
## 参考资料
|
||
|
||
- [核心模块设计总览](核心模块设计.md)
|
||
- [工具系统](核心模块设计-工具系统.md)
|
||
- [后台任务管理](../基础设施设计/基础设施设计-后台任务管理.md)
|
||
- [总体概述与技术选型](../总体概述与技术选型/总体概述与技术选型.md)
|