480 lines
18 KiB
TypeScript
480 lines
18 KiB
TypeScript
/**
|
||
* Task Orchestrator — 任务编排器
|
||
*
|
||
* 支持父子委派模式：主 Agent 委派子任务给 SubAgent。
|
||
* 每个 SubAgent 运行在**独立的 AgentLoopEngine 实例**中，避免状态污染。
|
||
*
|
||
* 安全保障：
|
||
* 1. 独立引擎实例 — SubAgent 不共享主 Agent 的引擎状态
|
||
* 2. 递归深度限制 — 默认最大 3 层，防止无限递归
|
||
* 3. 工具白名单隔离 — SubAgent 默认不继承 delegate_task（防止递归）
|
||
* 4. 真正的 abort — 通过引擎引用调用 engine.abort()
|
||
* 5. 事件隔离 — SubAgent 的流式事件不直接转发到前端，仅通过 orchestrator 事件通知
|
||
*
|
||
* P2-10 改造：
|
||
* - 依赖 EngineProvider（AgentEngineManager）而非单个 mainEngine：
|
||
* SubAgent 通过工厂获取独立 adapter 实例，彻底消除 abort 信号互踩问题
|
||
* （原实现 SubEngine 共享主引擎 adapter，setAbortSignal 单槽位会互相覆盖）
|
||
* - 新增 abortByParent(parentSessionId)：用户中断会话时联动中断其派生的 SubAgent
|
||
*
|
||
* @see docs/生产级通用 AI Agent 智能体桌面应用：完整设计与构建指南.html — 第五章
|
||
*/
|
||
|
||
import { EventEmitter } from 'events';
|
||
import { nanoid } from 'nanoid';
|
||
import { AgentLoopEngine } from '../agent-loop/engine';
|
||
import type { AgentLoopConfig } from '../agent-loop/types';
|
||
import type {
|
||
MetonaMessage,
|
||
MetonaSystemPrompt,
|
||
MetonaToolDef,
|
||
IMetonaProviderAdapter,
|
||
} from '../types';
|
||
import type { ToolRegistry } from '../tools/registry';
|
||
import type { PreToolHook } from '../hooks/pre-tool';
|
||
import type { PostToolHook } from '../hooks/post-tool';
|
||
import log from 'electron-log';
|
||
|
||
export interface SubAgentResult {
|
||
taskId: string;
|
||
/** v0.5.0: 委派方（父会话）ID — 供事件消费者按会话过滤 */
|
||
parentSessionId: string;
|
||
result: string;
|
||
success: boolean;
|
||
durationMs: number;
|
||
iterations: number;
|
||
}
|
||
|
||
/**
|
||
* v0.5.0: SubAgent 生命周期事件载荷（统一广播给前端 AgentMonitor 展示）
|
||
*/
|
||
export interface SubAgentEvent {
|
||
taskId: string;
|
||
parentSessionId: string;
|
||
description: string;
|
||
status: 'delegated' | 'running' | 'completed' | 'error';
|
||
depth: number;
|
||
durationMs?: number;
|
||
iterations?: number;
|
||
error?: string;
|
||
}
|
||
|
||
/**
|
||
* P2-10: 引擎供给接口（由 AgentEngineManager 实现）
|
||
* orchestrator 不再持有单个引擎引用，而是按需创建独立实例。
|
||
*/
|
||
export interface EngineProvider {
|
||
/** 主 adapter（读取 contextWindow 等元信息） */
|
||
getAdapter(): IMetonaProviderAdapter;
|
||
/** 创建独立 adapter 实例（SubAgent 专用，隔离 abort 信号） */
|
||
createAdapter(): IMetonaProviderAdapter;
|
||
/** 故障转移 Provider（可为 null） */
|
||
getFallbackAdapter(): IMetonaProviderAdapter | null;
|
||
/** 工作空间路径 */
|
||
getWorkspacePath(): string;
|
||
}
|
||
|
||
interface SubAgentHandle {
|
||
taskId: string;
|
||
parentSessionId: string;
|
||
description: string;
|
||
status: 'pending' | 'running' | 'completed' | 'error';
|
||
depth: number;
|
||
engine?: AgentLoopEngine;
|
||
result?: SubAgentResult;
|
||
abort: () => void;
|
||
getStatus: () => { taskId: string; status: string; description: string; depth: number };
|
||
}
|
||
|
||
/** 默认并发委派上限（每会话同时活跃的 SubAgent 数） */
|
||
const MAX_DELEGATION_DEPTH = 3;
|
||
|
||
export class TaskOrchestrator extends EventEmitter {
|
||
private activeSubAgents = new Map<string, SubAgentHandle>();
|
||
/** 追踪每个 session 的当前委派深度 */
|
||
private sessionDepth = new Map<string, number>();
|
||
|
||
constructor(
|
||
private engines: EngineProvider,
|
||
private toolRegistry?: ToolRegistry,
|
||
private preToolHooks: PreToolHook[] = [],
|
||
private postToolHooks: PostToolHook[] = [],
|
||
private defaultConfig?: Partial<AgentLoopConfig>,
|
||
) {
|
||
super();
|
||
}
|
||
|
||
/**
|
||
* L-18 修复: 热更新 SubAgent 的默认配置
|
||
*
|
||
* 主 Agent 的配置变更（thinkingEnabled/thinkingEffort/contextLength 等）通过
|
||
* engine.updateConfig() 即时生效；但 SubAgent 在 delegate() 时从 defaultConfig
|
||
* 复制配置，若 defaultConfig 不同步，新创建的 SubAgent 仍使用旧配置。
|
||
*
|
||
* 此方法供 IPC 层在 config:set 时同步调用，确保后续 SubAgent 使用最新配置。
|
||
*/
|
||
updateDefaultConfig(partial: Partial<AgentLoopConfig>): void {
|
||
this.defaultConfig = { ...this.defaultConfig, ...partial };
|
||
}
|
||
|
||
/**
|
||
* 委派子任务
|
||
*
|
||
* 创建一个独立的 AgentLoopEngine 实例执行子任务。
|
||
* SubAgent 不共享主 Agent 的引擎状态，安全隔离。
|
||
*/
|
||
async delegate(params: {
|
||
taskId?: string;
|
||
description: string;
|
||
parentSessionId: string;
|
||
maxIterations?: number;
|
||
tools?: string[];
|
||
/**
|
||
* v0.8.0 P1-2: 引擎级取消信号 —— delegate_task 工具透传 context.signal，
|
||
* 用户中断父会话时 SubEngine 联动终止（此前工具被 registry 兜底超时杀掉，
|
||
* SubEngine 仍在后台跑满剩余轮次）。
|
||
*/
|
||
signal?: AbortSignal;
|
||
}): Promise<SubAgentResult> {
|
||
const taskId = params.taskId ?? `sub_${nanoid(8)}`;
|
||
const startMs = Date.now();
|
||
|
||
// ===== 并发委派上限检查 =====
|
||
// v0.8.2 P3-2 根治（语义对齐）：sessionDepth 实际计数的是"该会话当前活跃的
|
||
// 委派数"（finally 中恢复/清除），且 delegate_task 已从 SubAgent 工具集排除、
|
||
// 真实嵌套递归不可能发生 —— 旧文案"depth limit reached"误导排障方向
|
||
// （测试 engine-toolchain/orchestrator 按并发 3 层锁定该行为）。现文案与
|
||
// 注释如实描述为并发委派上限；README 的"3 层深度"措辞同步对齐。
|
||
const currentDepth = this.sessionDepth.get(params.parentSessionId) ?? 0;
|
||
if (currentDepth >= MAX_DELEGATION_DEPTH) {
|
||
log.warn(
|
||
`[Orchestrator] Concurrent delegation limit reached (${currentDepth}) for session ${params.parentSessionId}`,
|
||
);
|
||
return {
|
||
taskId,
|
||
parentSessionId: params.parentSessionId,
|
||
result: `SubAgent concurrency limit reached (${MAX_DELEGATION_DEPTH} concurrent delegations per session). Wait for an active subtask to finish before delegating more.`,
|
||
success: false,
|
||
durationMs: 0,
|
||
iterations: 0,
|
||
};
|
||
}
|
||
const depth = currentDepth + 1;
|
||
this.sessionDepth.set(params.parentSessionId, depth);
|
||
|
||
this.emit('taskDelegated', {
|
||
taskId,
|
||
description: params.description,
|
||
parentSessionId: params.parentSessionId,
|
||
depth,
|
||
});
|
||
|
||
// ===== 创建独立的引擎实例（P2-10: 独立 adapter，隔离 abort 信号） =====
|
||
const subEngine = new AgentLoopEngine(
|
||
{
|
||
maxIterations: params.maxIterations ?? 10,
|
||
totalTimeoutMs: 300_000, // 子任务总超时 5 分钟
|
||
thinkingEnabled: this.defaultConfig?.thinkingEnabled ?? true,
|
||
thinkingEffort: this.defaultConfig?.thinkingEffort ?? 'medium',
|
||
contextLength: this.defaultConfig?.contextLength,
|
||
contextWindow: this.defaultConfig?.contextWindow,
|
||
// v0.7.3 P3-1: SubAgent 与主引擎同源消费 enableReflection（REFLECTING 状态开关）
|
||
enableReflection: this.defaultConfig?.enableReflection ?? false,
|
||
// v0.7.4 P3-2 修正: SubAgent 继承主引擎的 temperature/maxTokens ——
|
||
// 旧实现不读这两个键导致"热生效"对子任务不完整。
|
||
// v0.8.1 硬性契约: 不携带任何写死兜底值 —— 与主引擎同源继承设置面板配置
|
||
temperature: this.defaultConfig?.temperature ?? 0.0,
|
||
maxTokens: this.defaultConfig?.maxTokens,
|
||
},
|
||
this.engines.createAdapter(),
|
||
this.toolRegistry,
|
||
this.preToolHooks,
|
||
this.postToolHooks,
|
||
);
|
||
subEngine.setFallbackAdapter(this.engines.getFallbackAdapter());
|
||
subEngine.setWorkspacePath(this.engines.getWorkspacePath());
|
||
|
||
// v0.8.0 P1-2: 外部取消信号联动 —— signal 已中止或运行中触发 abort 时
|
||
// 终止 SubEngine；finally 中解除监听防泄漏
|
||
let onExternalAbort: (() => void) | null = null;
|
||
if (params.signal) {
|
||
if (params.signal.aborted) {
|
||
subEngine.abort();
|
||
} else {
|
||
onExternalAbort = () => subEngine.abort();
|
||
params.signal.addEventListener('abort', onExternalAbort, { once: true });
|
||
}
|
||
}
|
||
|
||
// v0.5.0: 转发 SubEngine 的流式/状态事件（供 TRACE 录制与前端可观测）
|
||
// 事件以 taskId 为 sessionId，录制到独立 JSONL 文件，不污染父会话的流
|
||
this.forwardSubEngineEvents(subEngine, taskId);
|
||
|
||
// ===== 工具白名单设置 =====
|
||
const allowedTools = this.resolveTools(params.tools);
|
||
subEngine.setTools(allowedTools);
|
||
|
||
const handle: SubAgentHandle = {
|
||
taskId,
|
||
parentSessionId: params.parentSessionId,
|
||
description: params.description,
|
||
status: 'running',
|
||
depth,
|
||
engine: subEngine,
|
||
abort: () => {
|
||
subEngine.abort();
|
||
handle.status = 'error';
|
||
this.activeSubAgents.delete(taskId);
|
||
},
|
||
getStatus: () => ({
|
||
taskId,
|
||
status: handle.status,
|
||
description: handle.description,
|
||
depth: handle.depth,
|
||
}),
|
||
};
|
||
|
||
this.activeSubAgents.set(taskId, handle);
|
||
this.emit('taskStarted', {
|
||
taskId,
|
||
description: params.description,
|
||
parentSessionId: params.parentSessionId,
|
||
depth,
|
||
});
|
||
|
||
try {
|
||
// 构建用户消息
|
||
const userMessage: MetonaMessage = {
|
||
role: 'user',
|
||
content: params.description,
|
||
timestamp: Date.now(),
|
||
};
|
||
|
||
// 构建 System Prompt（子 Agent 专用）
|
||
const systemPrompt = this.buildSubAgentPrompt(params.description, depth);
|
||
|
||
// 运行 Agent Loop（同步等待完成）
|
||
const output = await subEngine.runStream(
|
||
userMessage,
|
||
taskId,
|
||
[], // 子 Agent 无历史
|
||
systemPrompt,
|
||
);
|
||
|
||
const durationMs = Date.now() - startMs;
|
||
const success = output.terminationReason === 'completed';
|
||
const result: SubAgentResult = {
|
||
taskId,
|
||
parentSessionId: params.parentSessionId,
|
||
result: output.finalAnswer,
|
||
success,
|
||
durationMs,
|
||
iterations: output.iterations.length,
|
||
};
|
||
|
||
handle.status = success ? 'completed' : 'error';
|
||
handle.result = result;
|
||
this.emit('taskCompleted', result);
|
||
|
||
log.info(
|
||
`[Orchestrator] SubAgent "${taskId}" (depth=${depth}) ${success ? 'completed' : 'failed'} in ${durationMs}ms, ${output.iterations.length} iterations`,
|
||
);
|
||
|
||
return result;
|
||
} catch (error) {
|
||
const durationMs = Date.now() - startMs;
|
||
const errMsg = (error as Error).message;
|
||
const result: SubAgentResult = {
|
||
taskId,
|
||
parentSessionId: params.parentSessionId,
|
||
result: errMsg,
|
||
success: false,
|
||
durationMs,
|
||
iterations: 0,
|
||
};
|
||
|
||
handle.status = 'error';
|
||
handle.result = result;
|
||
this.emit('taskError', {
|
||
taskId,
|
||
parentSessionId: params.parentSessionId,
|
||
description: params.description,
|
||
error: errMsg,
|
||
});
|
||
|
||
log.error(`[Orchestrator] SubAgent "${taskId}" (depth=${depth}) error: ${errMsg}`);
|
||
|
||
return result;
|
||
} finally {
|
||
// v0.8.0 P1-2: 解除外部取消信号监听（防事件循环泄漏）
|
||
if (params.signal && onExternalAbort) {
|
||
params.signal.removeEventListener('abort', onExternalAbort);
|
||
}
|
||
// #5 修复: 统一在 finally 块恢复 sessionDepth，覆盖正常完成/异常/abort 所有路径
|
||
// 审查修复: 如果 abortAll 已 clear sessionDepth，不再恢复（避免覆盖紧急清理）。
|
||
// 场景：用户紧急中断时 abortAll 先 clear，若 SubEngine 随后才返回执行 finally，
|
||
// 不应把已清空的 sessionDepth 又 set 回 currentDepth。
|
||
if (this.sessionDepth.has(params.parentSessionId)) {
|
||
if (currentDepth === 0) {
|
||
this.sessionDepth.delete(params.parentSessionId);
|
||
} else {
|
||
this.sessionDepth.set(params.parentSessionId, currentDepth);
|
||
}
|
||
}
|
||
this.activeSubAgents.delete(taskId);
|
||
// P2-10: SubEngine 使用独立 adapter 实例，无需恢复主引擎的 abort signal
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 解析工具白名单
|
||
*
|
||
* - 如果指定了 tools，使用白名单（自动排除 delegate_task 防止递归）
|
||
* - 如果未指定，使用所有已启用工具（同样排除 delegate_task）
|
||
*/
|
||
private resolveTools(toolNames?: string[]): MetonaToolDef[] {
|
||
if (!this.toolRegistry) return [];
|
||
|
||
// v0.6.4 修正注释与实现漂移：delegate_task 在所有深度下无条件排除
|
||
// （resolveTools 不感知 depth，旧注释中的"除非深度为 1 且显式要求"从未实现）
|
||
const EXCLUDE_TOOLS = new Set(['delegate_task']);
|
||
|
||
if (toolNames && toolNames.length > 0) {
|
||
// 使用白名单模式
|
||
const resolved: MetonaToolDef[] = [];
|
||
const notFound: string[] = [];
|
||
|
||
for (const name of toolNames) {
|
||
if (EXCLUDE_TOOLS.has(name)) continue; // 静默排除
|
||
const tool = this.toolRegistry.get(name);
|
||
if (tool) {
|
||
resolved.push(tool.definition);
|
||
} else {
|
||
notFound.push(name);
|
||
}
|
||
}
|
||
|
||
if (notFound.length > 0) {
|
||
log.warn(`[Orchestrator] Tools not found: ${notFound.join(', ')}`);
|
||
}
|
||
|
||
return resolved;
|
||
}
|
||
|
||
// 未指定白名单 — 使用所有已启用工具（排除 delegate_task）
|
||
return this.toolRegistry.listTools().filter((t) => !EXCLUDE_TOOLS.has(t.name));
|
||
}
|
||
|
||
/**
|
||
* 构建 SubAgent 的 System Prompt
|
||
*/
|
||
private buildSubAgentPrompt(description: string, depth: number): MetonaSystemPrompt {
|
||
return {
|
||
roleDefinition: `You are a SubAgent (delegation depth: ${depth}) executing a specific sub-task delegated by the parent Agent.\nYour goal is to complete the assigned task efficiently and return a clear, concise result.\nFocus only on the task at hand. Do not delegate further.`,
|
||
outputConstraints: `Complete the task and provide a clear summary of your findings or actions.\nRespond in the same language as the task description.\nKeep your response focused and relevant — the parent Agent will use your result to continue its work.`,
|
||
safetyGuidelines: `Do not access files outside the workspace.\nDo not execute dangerous commands.\nIf the task cannot be completed, explain why clearly.`,
|
||
};
|
||
}
|
||
|
||
/**
|
||
* 中断指定子任务
|
||
*/
|
||
abortTask(taskId: string): boolean {
|
||
const handle = this.activeSubAgents.get(taskId);
|
||
if (handle && handle.status === 'running') {
|
||
handle.abort();
|
||
return true;
|
||
}
|
||
return false;
|
||
}
|
||
|
||
/**
|
||
* P2-10: 中断指定父会话派生的所有 SubAgent
|
||
* （用户中断会话时由 IPC abort handler 联动调用，消除"会话停了子任务还在跑"）
|
||
*
|
||
* v0.5.1: 返回值从数量改为被中止的 taskId 列表 — 调用方需据此清理这些
|
||
* SubAgent 的 pending 工具确认（SubEngine 以 taskId 为 sessionId 写入
|
||
* ConfirmationHook，父会话的 clearPending(sessionId) 清不到它们；不清理
|
||
* 会导致中止后孤儿工具在用户补批时执行副作用）
|
||
*/
|
||
abortByParent(parentSessionId: string): string[] {
|
||
const abortedTaskIds: string[] = [];
|
||
for (const handle of this.activeSubAgents.values()) {
|
||
if (handle.parentSessionId === parentSessionId && handle.status === 'running') {
|
||
handle.abort();
|
||
abortedTaskIds.push(handle.taskId);
|
||
}
|
||
}
|
||
if (abortedTaskIds.length > 0) {
|
||
log.info(
|
||
`[Orchestrator] Aborted ${abortedTaskIds.length} SubAgent(s) of session ${parentSessionId}`,
|
||
);
|
||
}
|
||
return abortedTaskIds;
|
||
}
|
||
|
||
/**
|
||
* 完成子任务（外部触发，保留接口兼容）
|
||
*/
|
||
completeTask(taskId: string, result: string, success: boolean): void {
|
||
const handle = this.activeSubAgents.get(taskId);
|
||
if (handle && handle.status === 'running') {
|
||
handle.status = success ? 'completed' : 'error';
|
||
handle.result = {
|
||
taskId,
|
||
parentSessionId: handle.parentSessionId,
|
||
result,
|
||
success,
|
||
durationMs: 0,
|
||
iterations: 0,
|
||
};
|
||
this.activeSubAgents.delete(taskId);
|
||
this.emit('taskCompleted', handle.result);
|
||
}
|
||
}
|
||
|
||
getActiveAgentsStatus(): Array<{
|
||
taskId: string;
|
||
status: string;
|
||
description: string;
|
||
depth: number;
|
||
}> {
|
||
return Array.from(this.activeSubAgents.values()).map((a) => a.getStatus());
|
||
}
|
||
|
||
/**
|
||
* 中断所有子任务
|
||
*/
|
||
abortAll(): void {
|
||
for (const agent of this.activeSubAgents.values()) {
|
||
agent.abort();
|
||
}
|
||
this.activeSubAgents.clear();
|
||
// 审查修复: 恢复 sessionDepth.clear()，保留紧急清理能力。
|
||
// #5 修复曾移除此行，但若 SubEngine 卡死不返回，delegate 的 finally 永远不会执行，
|
||
// sessionDepth 将永久残留。此处 clear 确保紧急路径能立即恢复状态。
|
||
// 配合 delegate finally 块的 has() 检查：若已被 clear，finally 不再恢复（避免覆盖）。
|
||
this.sessionDepth.clear();
|
||
}
|
||
|
||
/**
|
||
* v0.5.0: 转发 SubEngine 的事件到 orchestrator 事件总线
|
||
*
|
||
* SubEngine 不经过 AgentEngineManager 的转发管道（刻意隔离，避免污染父会话流），
|
||
* 此处将其流式/状态事件重新包装为 subStreamEvent / subStateChange 广播：
|
||
* - IPC 层监听后录制到独立 TRACE 文件（sessionId = taskId）
|
||
* - 生命周期事件（taskDelegated 等）另行广播给前端 AgentMonitor
|
||
*
|
||
* @param engine SubAgent 的独立引擎实例
|
||
* @param taskId 子任务 ID（SubEngine runStream 的 sessionId）
|
||
*/
|
||
private forwardSubEngineEvents(engine: AgentLoopEngine, taskId: string): void {
|
||
engine.on('streamEvent', (event: Record<string, unknown>) => {
|
||
this.emit('subStreamEvent', { taskId, event });
|
||
});
|
||
engine.on('stateChange', (data: Record<string, unknown>) => {
|
||
this.emit('subStateChange', { taskId, data });
|
||
});
|
||
}
|
||
}
|