@aipack-ai/multi-agent 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,523 @@
+import { Result, Tool, Request, Runtime, RuntimeOptions } from '@aipack-ai/agent';
+
+/**
+ * core/types.ts - 多Agent编排核心类型
+ *
+ * 定义 AgentNode, AgentEdge, SharedContext, AgentGraph 等核心抽象。
+ * P0 范围：AgentGraph + Pipeline + Router。
+ */
+
+/** 事件总线监听器 */
+type EventListener<T = unknown> = (event: T) => void;
+/** 事件总线：Agent间异步通知 */
+interface EventBus {
+    /** 订阅事件 */
+    on(event: string, listener: EventListener): this;
+    /** 取消订阅 */
+    off(event: string, listener: EventListener): this;
+    /** 发射事件 */
+    emit(event: string, data?: unknown): this;
+}
+/** 工具注册表：跨Agent工具共享 */
+interface ToolRegistry {
+    /** 注册工具 */
+    register(tool: Tool): this;
+    /** 批量注册 */
+    registerAll(tools: Tool[]): this;
+    /** 获取工具 */
+    get(name: string): Tool | undefined;
+    /** 获取所有工具 */
+    getAll(): Tool[];
+    /** 检查工具是否存在 */
+    has(name: string): boolean;
+}
+/** Agent间共享上下文 */
+interface SharedContext {
+    /** 黑板：键值共享存储 */
+    blackboard: Map<string, unknown>;
+    /** 事件总线：Agent间异步通知 */
+    bus: EventBus;
+    /** 全局工具注册表 */
+    toolRegistry: ToolRegistry;
+    /** 运行元数据（traceId, startTime, etc.） */
+    meta: Record<string, unknown>;
+}
+/** Agent节点：图中的执行单元 */
+interface AgentNode {
+    /** 唯一标识 */
+    id: string;
+    /** 节点显示名 */
+    name: string;
+    /** Agent描述（注入到systemPrompt） */
+    description: string;
+    /** Runtime实例（或创建选项） */
+    runtime: Runtime | RuntimeOptions;
+    /** 该Agent专有的工具（除了共享工具外） */
+    tools?: Tool[];
+    /** 输入转换：从SharedContext提取该Agent需要的上下文 */
+    inputMapping?: (ctx: SharedContext) => string | Request;
+    /** 输出转换：将Agent结果写入SharedContext */
+    outputMapping?: (result: Result, ctx: SharedContext) => void;
+}
+/** Agent间流转边 */
+interface AgentEdge {
+    /** 源Agent ID */
+    from: string;
+    /** 目标Agent ID */
+    to: string;
+    /** 条件：决定是否走这条边（默认always true） */
+    condition?: (result: Result, ctx: SharedContext) => boolean;
+    /** 边上的转换：修改传递给下一个Agent的输入 */
+    transform?: (result: Result, ctx: SharedContext) => string | Request;
+}
+/** 单个Agent的执行状态 */
+type NodeExecutionState = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+/** 图执行状态快照 */
+interface GraphExecutionState {
+    /** 当前执行到哪个节点 */
+    currentAgentId?: string;
+    /** 各节点执行状态 */
+    nodeStates: Map<string, NodeExecutionState>;
+    /** 各节点的执行结果 */
+    nodeResults: Map<string, Result>;
+    /** 已完成的步数 */
+    stepsCompleted: number;
+    /** 总步数（预估） */
+    totalSteps?: number;
+    /** 是否已完成 */
+    finished: boolean;
+    /** 是否出错 */
+    error?: string;
+}
+/** 多Agent运行结果 */
+interface MultiAgentResult {
+    /** 最终输出文本 */
+    content: string;
+    /** 最后一个执行的Agent ID */
+    lastAgentId: string;
+    /** 各Agent执行结果 */
+    agentResults: Map<string, Result>;
+    /** 累计token用量 */
+    totalUsage: Record<string, number>;
+    /** 执行步数 */
+    stepsCompleted: number;
+    /** 停止原因 */
+    stopReason: string;
+    /** 共享上下文快照 */
+    context: SharedContext;
+    /** 是否成功 */
+    success: boolean;
+    /** 错误信息 */
+    error?: string;
+}
+/** 多Agent流式事件类型 */
+type MultiAgentEvent = {
+    type: 'agent_start';
+    agentId: string;
+    agentName: string;
+} | {
+    type: 'agent_result';
+    agentId: string;
+    agentName: string;
+    result: Result;
+} | {
+    type: 'agent_error';
+    agentId: string;
+    agentName: string;
+    error: string;
+} | {
+    type: 'edge_traversed';
+    from: string;
+    to: string;
+} | {
+    type: 'parallel_start';
+    agentIds: string[];
+} | {
+    type: 'parallel_done';
+    results: Map<string, Result>;
+} | {
+    type: 'round_start';
+    round: number;
+} | {
+    type: 'converged';
+    round: number;
+    reason: string;
+} | {
+    type: 'graph_done';
+    result: MultiAgentResult;
+} | {
+    type: 'graph_error';
+    error: string;
+};
+/** AgentGraph: 编排核心 */
+interface AgentGraph {
+    /** 添加Agent节点 */
+    addNode(node: AgentNode): this;
+    /** 添加流转边 */
+    addEdge(edge: AgentEdge): this;
+    /** 设置入口Agent */
+    setEntry(agentId: string): this;
+    /** 设置终止条件 */
+    setFinish(condition: (ctx: SharedContext) => boolean): this;
+    /** 执行图 */
+    run(input: string | Request): Promise<MultiAgentResult>;
+    /** 流式执行 */
+    stream(input: string | Request): AsyncGenerator<MultiAgentEvent>;
+    /** 获取执行状态 */
+    getState(): GraphExecutionState;
+    /** 中止执行 */
+    abort(): void;
+    /** 事件监听 */
+    on(event: string, listener: EventListener): this;
+}
+/** Pipeline 配置选项 */
+interface PipelineOpts {
+    /** 是否传递前一个Agent的完整Result到下一个Agent（默认只传content文本） */
+    passFullResult?: boolean;
+    /** 节点间输出转换（全局，优先级低于AgentNode.outputMapping） */
+    outputTransform?: (result: Result, ctx: SharedContext) => string;
+}
+/** Router 配置选项 */
+interface RouterOpts {
+    /** 从路由Agent输出中解析目标Agent ID */
+    resolve: (routerResult: Result) => string;
+    /** 未匹配到目标时的默认路由Agent ID */
+    defaultTarget?: string;
+    /** 是否将原始输入传递给目标Agent（默认true），否则传递路由Agent的输出 */
+    passOriginalInput?: boolean;
+}
+/** 执行调度策略 */
+type ScheduleMode = 'auto' | 'sequential' | 'parallel';
+/** Supervisor 配置选项 */
+interface SupervisorOpts {
+    /**
+     * 执行调度策略：
+     * - 'parallel': 所有工作者并行执行
+     * - 'sequential': 工作者按顺序依次执行
+     * - 'auto': 根据工作者 inputMapping 的 blackboard 依赖自动推导执行顺序
+     *   （仅读 supervisor 输出的并行，依赖其他工作者结果的串行在后）
+     * 默认 'parallel'
+     */
+    schedule?: ScheduleMode;
+    /**
+     * 并行执行时的最大并发数（默认 Infinity，不限制）
+     * 用于避免 API 限流
+     */
+    concurrency?: number;
+    /** Supervisor 输出后，是否将原始用户输入也传递给工作者（通过 blackboard.__original_input__）
+     * 默认 true
+     */
+    passOriginalInput?: boolean;
+}
+/** Debate 配置选项 */
+interface DebateOpts {
+    /** 最大辩论轮数（默认 3） */
+    maxRounds?: number;
+    /** 收敛条件：当 reviewer 的输出满足此条件时提前结束 */
+    convergeWhen: (reviewerResult: Result) => boolean;
+    /** 将 reviewer 的反馈如何转换为 proposer 的输入（默认：将 reviewer 输出拼接为修复指令） */
+    feedbackTransform?: (reviewerResult: Result, proposerResult: Result) => string;
+}
+/** MapReduce 配置选项 */
+interface MapReduceOpts {
+    /** 将输入拆分为多个子任务的函数 */
+    split: (input: string) => string[];
+    /** 并行执行时的最大并发数（默认 Infinity） */
+    concurrency?: number;
+    /** Reducer 的输入格式化（默认将所有 mapper 结果用分隔符连接） */
+    reduceInputFormat?: (mapperResults: Map<number, Result>) => string;
+}
+/** MCPBridge 配置选项 */
+interface MCPBridgeOpts {
+    /** MCP Server 名称（默认 'aipack-multi-agent'） */
+    serverName?: string;
+    /** MCP Server 版本（默认 '1.0.0'） */
+    serverVersion?: string;
+    /** 将 AgentGraph 注册为 MCP 工具时的工具名前缀 */
+    toolPrefix?: string;
+}
+/** 单步追踪记录 */
+interface TraceStep {
+    /** 步骤序号（从 1 开始） */
+    step: number;
+    /** 执行的 Agent ID */
+    agentId: string;
+    /** Agent 名称 */
+    agentName: string;
+    /** 执行开始时间（ms 时间戳） */
+    startTime: number;
+    /** 执行耗时（ms） */
+    duration: number;
+    /** 输入摘要 */
+    input: string;
+    /** 输出摘要 */
+    output: string;
+    /** 执行状态 */
+    state: NodeExecutionState;
+    /** 错误信息（仅失败时有） */
+    error?: string;
+}
+/** 图执行追踪记录 */
+interface GraphTrace {
+    /** 追踪 ID */
+    traceId: string;
+    /** 图开始时间（ms 时间戳） */
+    startTime: number;
+    /** 图总耗时（ms） */
+    duration: number;
+    /** 各步骤记录 */
+    steps: TraceStep[];
+    /** 最终结果摘要 */
+    result: {
+        success: boolean;
+        content: string;
+        stopReason: string;
+        stepsCompleted: number;
+    };
+}
+
+/**
+ * core/context.ts - SharedContext 实现
+ *
+ * 提供 EventBus、ToolRegistry 和 SharedContext 的默认实现。
+ */
+
+/** 简单同步事件总线实现 */
+declare class SimpleEventBus implements EventBus {
+    private listeners;
+    on(event: string, listener: EventListener): this;
+    off(event: string, listener: EventListener): this;
+    emit(event: string, data?: unknown): this;
+}
+/** 简单工具注册表实现 */
+declare class SimpleToolRegistry implements ToolRegistry {
+    private tools;
+    register(tool: Tool): this;
+    registerAll(tools: Tool[]): this;
+    get(name: string): Tool | undefined;
+    getAll(): Tool[];
+    has(name: string): boolean;
+}
+/** 创建默认 SharedContext */
+declare function createSharedContext(init?: Partial<SharedContext>): SharedContext;
+
+/**
+ * core/graph.ts - AgentGraph 实现
+ *
+ * 基于声明式 API（addNode/addEdge/setEntry/setFinish）构建图，
+ * 委托 GraphExecutor 执行。
+ */
+
+/** 创建空的 AgentGraph，通过链式调用定义图结构 */
+declare function createAgentGraph(): AgentGraph;
+
+/**
+ * patterns/pipeline.ts - Pipeline 顺序链模式
+ *
+ * 将多个 Agent 按顺序串联：A → B → C → ...
+ * 前一个 Agent 的输出作为后一个 Agent 的输入。
+ */
+
+/**
+ * 创建 Pipeline 顺序链
+ *
+ * @param agents - 按顺序排列的 Agent 节点列表
+ * @param opts - Pipeline 配置选项
+ * @returns AgentGraph 实例
+ */
+declare function createPipeline(agents: AgentNode[], opts?: PipelineOpts): AgentGraph;
+
+/**
+ * patterns/router.ts - Router 条件路由模式
+ *
+ * 路由器 Agent 根据输入选择目标 Agent 执行。
+ * 结构：Router → (条件匹配) → Target Agent
+ */
+
+/**
+ * 创建 Router 条件路由
+ *
+ * @param router - 路由器 Agent（负责意图识别）
+ * @param targets - 目标 Agent 列表
+ * @param opts - Router 配置选项（必须提供 resolve 函数）
+ * @returns AgentGraph 实例
+ */
+declare function createRouter(router: AgentNode, targets: AgentNode[], opts: RouterOpts): AgentGraph;
+
+/**
+ * patterns/supervisor.ts - Supervisor 层级委派模式
+ *
+ * Supervisor Agent 拆解任务分配给 Worker Agents，
+ * 根据调度策略执行（parallel / sequential / auto）。
+ */
+
+/**
+ * 创建 Supervisor 层级委派模式
+ *
+ * @param supervisor - Supervisor Agent（负责拆解任务并分配）
+ * @param workers - Worker Agent 列表（负责执行具体任务）
+ * @param opts - Supervisor 配置选项
+ * @returns AgentGraph 实例
+ */
+declare function createSupervisor(supervisor: AgentNode, workers: AgentNode[], opts?: SupervisorOpts): AgentGraph;
+
+/**
+ * patterns/debate.ts - Debate 对抗评审模式
+ *
+ * Proposer 和 Reviewer 循环辩论，直到收敛或达最大轮次。
+ */
+
+/**
+ * 创建 Debate 对抗评审模式
+ *
+ * @param proposer - 生成/修复方 Agent
+ * @param reviewer - 审查方 Agent
+ * @param opts - Debate 配置选项（必须提供 convergeWhen）
+ * @returns AgentGraph 实例
+ */
+declare function createDebate(proposer: AgentNode, reviewer: AgentNode, opts: DebateOpts): AgentGraph;
+
+/**
+ * patterns/map-reduce.ts - MapReduce 并行聚合模式
+ *
+ * 将输入拆分为子任务，用 mapper 并行处理，再用 reducer 汇总。
+ */
+
+/**
+ * 创建 MapReduce 并行聚合模式
+ *
+ * @param mapper - 映射方 Agent（处理单个子任务）
+ * @param reducer - 汇总方 Agent（合并所有 mapper 结果）
+ * @param opts - MapReduce 配置选项（必须提供 split 函数）
+ * @returns AgentGraph 实例
+ */
+declare function createMapReduce(mapper: AgentNode, reducer: AgentNode, opts: MapReduceOpts): AgentGraph;
+
+/**
+ * extensions/mcp-bridge.ts - MCPBridge Extension
+ *
+ * 将 AgentGraph 暴露为 MCP (Model Context Protocol) 工具，
+ * 使外部 MCP 客户端可以直接调用多 Agent 编排图。
+ *
+ * 设计原则：不依赖外部 MCP SDK，仅输出符合 MCP 规范的 JSON 结构，
+ * 由宿主环境（如 aipack CLI）负责实际的 MCP 传输层。
+ */
+
+/** MCP 工具参数定义 */
+interface MCPToolParameter {
+    name: string;
+    description: string;
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    required?: boolean;
+}
+/** MCP 工具定义 */
+interface MCPToolDefinition {
+    /** 工具名 */
+    name: string;
+    /** 工具描述 */
+    description: string;
+    /** 参数 schema */
+    parameters: MCPToolParameter[];
+}
+/** MCP 工具调用请求 */
+interface MCPToolCallRequest {
+    /** 工具名 */
+    name: string;
+    /** 参数 */
+    arguments: Record<string, unknown>;
+}
+/** MCP 工具调用结果 */
+interface MCPToolCallResult {
+    /** 是否错误 */
+    isError?: boolean;
+    /** 结果内容列表 */
+    content: Array<{
+        type: 'text' | 'image' | 'resource';
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+}
+/**
+ * MCPBridge：将 AgentGraph 注册为 MCP 工具
+ *
+ * 用法：
+ * ```typescript
+ * const bridge = new MCPBridge(graph, { toolPrefix: 'ma_' });
+ *
+ * // 获取工具列表（供 MCP Server 注册）
+ * const tools = bridge.listTools();
+ *
+ * // 处理工具调用
+ * const result = await bridge.handleCall({ name: 'ma_run', arguments: { input: '...' } });
+ * ```
+ */
+declare class MCPBridge {
+    private graph;
+    private opts;
+    constructor(graph: AgentGraph, opts?: MCPBridgeOpts);
+    /** 获取 MCP Server 信息 */
+    getServerInfo(): {
+        name: string;
+        version: string;
+    };
+    /** 列出所有可用 MCP 工具 */
+    listTools(): MCPToolDefinition[];
+    /** 处理 MCP 工具调用 */
+    handleCall(request: MCPToolCallRequest): Promise<MCPToolCallResult>;
+}
+/** 创建 MCPBridge */
+declare function createMCPBridge(graph: AgentGraph, opts?: MCPBridgeOpts): MCPBridge;
+
+/**
+ * extensions/debug.ts - 可视化调试扩展
+ *
+ * 提供：
+ * 1. DOT 格式图结构导出（可用 Graphviz 渲染）
+ * 2. 执行 Trace 记录（GraphTrace）
+ * 3. 执行过程日志
+ */
+
+/**
+ * GraphDebugger：图可视化调试工具
+ *
+ * 用法：
+ * ```typescript
+ * const debugger_ = new GraphDebugger(graph);
+ *
+ * // 导出 DOT 格式
+ * const dot = debugger_.toDOT();
+ *
+ * // 运行并记录 trace
+ * const trace = await debugger_.trace('用户输入');
+ *
+ * // 导出 trace 为 JSON
+ * const json = debugger_.traceToJSON(trace);
+ * ```
+ */
+declare class GraphDebugger {
+    private graph;
+    private nodes;
+    private edges;
+    private entryId?;
+    constructor(graph: AgentGraph, nodes?: AgentNode[], edges?: AgentEdge[], entryId?: string);
+    /** 设置图元数据（供无法直接访问内部结构的场景使用） */
+    setGraphMeta(nodes: AgentNode[], edges: AgentEdge[], entryId?: string): void;
+    /** 导出为 DOT 格式 */
+    toDOT(): string;
+    /** 执行图并记录 Trace */
+    trace(input: string): Promise<GraphTrace>;
+    /** 将 Trace 转为 JSON 字符串 */
+    traceToJSON(trace: GraphTrace): string;
+    /** 将 Trace 转为可读的执行日志 */
+    traceToLog(trace: GraphTrace): string;
+    private truncate;
+    /** 找最后一个匹配 agentId 且状态为 running 的 step */
+    private findLastRunning;
+    /** 找最后一个匹配 agentId 的 step（不管状态） */
+    private findLastById;
+}
+/** 创建 GraphDebugger */
+declare function createDebugger(graph: AgentGraph): GraphDebugger;
+
+export { type AgentEdge, type AgentGraph, type AgentNode, type DebateOpts, type EventBus, type EventListener, GraphDebugger, type GraphExecutionState, type GraphTrace, MCPBridge, type MCPBridgeOpts, type MCPToolCallRequest, type MCPToolCallResult, type MCPToolDefinition, type MCPToolParameter, type MapReduceOpts, type MultiAgentEvent, type MultiAgentResult, type NodeExecutionState, type PipelineOpts, type RouterOpts, type ScheduleMode, type SharedContext, SimpleEventBus, SimpleToolRegistry, type SupervisorOpts, type ToolRegistry, type TraceStep, createAgentGraph, createDebate, createDebugger, createMCPBridge, createMapReduce, createPipeline, createRouter, createSharedContext, createSupervisor };