agent-scene-toolkit 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,463 @@
+import { StructuredToolInterface } from '@langchain/core/tools';
+import * as _langchain_langgraph from '@langchain/langgraph';
+import { BaseCheckpointSaver } from '@langchain/langgraph';
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import { RequestHandler } from 'express';
+import * as _langchain_core_utils_stream from '@langchain/core/utils/stream';
+import * as langchain from 'langchain';
+import * as _langchain_core_messages from '@langchain/core/messages';
+
+/**
+ * 静态能力包 — 按领域分组的工具集 + 使用策略提示词。
+ *
+ * @example
+ * ```ts
+ * const canvasToolKit = defineToolKit({
+ *   name: 'canvas',
+ *   tools: [bindElementTool, bindTrackTool],
+ *   prompt: '画面调整时优先使用 canvas 工具...',
+ * })
+ * ```
+ */
+interface ToolKit {
+    /** 唯一标识（如 `'canvas'`、`'ai'`） */
+    readonly name: string;
+    /** LangChain Tool 数组 */
+    readonly tools: StructuredToolInterface[];
+    /** 使用策略提示词，告诉 LLM 何时/如何使用这组工具 */
+    readonly prompt: string;
+}
+/**
+ * 角色身份 — 极简声明：名字 + 系统提示词 + 模型。
+ *
+ * @example
+ * ```ts
+ * const director = defineProfile({
+ *   name: '导演',
+ *   systemPrompt: '你是一位视频导演...',
+ *   model: 'gpt-4o',
+ * })
+ * ```
+ */
+interface AgentProfile {
+    /** 角色名称，多 Agent 时作为唯一标识 */
+    readonly name: string;
+    /** 角色系统提示词 */
+    readonly systemPrompt: string;
+    /** 模型标识（如 `'gpt-4o'`、`'gpt-4o-mini'`） */
+    readonly model: string;
+}
+/**
+ * 运行时场景 — 声明当前需要的工具集 + 动态上下文提示词 + 生命周期回调。
+ *
+ * @example
+ * ```ts
+ * const timelineScene = defineScene({
+ *   name: 'timeline-editing',
+ *   toolkits: ['canvas', 'ai'],
+ *   prompt: (ctx) => `视频时长: ${ctx.duration}秒`,
+ *   onToolEnd: (toolName, result) => {
+ *     if (toolName === 'bindTrack') refreshTimeline()
+ *   },
+ * })
+ * ```
+ */
+interface Scene {
+    /** 场景名称 */
+    readonly name: string;
+    /** 当前场景需要的 ToolKit 名称列表，从全局能力池中过滤 */
+    readonly toolkits: string[];
+    /** 动态提示词模板，接收运行时上下文数据（来自 `chat()` 的 `sceneContext`） */
+    readonly prompt: (ctx: Record<string, any>) => string;
+    /** 工具调用完成后的生命周期回调 */
+    readonly onToolEnd?: (toolName: string, result: any) => void;
+}
+/**
+ * `createAgent()` 配置项。
+ *
+ * @example
+ * ```ts
+ * const agent = createAgent({
+ *   toolkits: [canvasToolKit, aiToolKit],
+ *   agents: [director, screenwriter],
+ *   supervisor: '导演',
+ *   scene: timelineScene,
+ *   checkpointer: new MemorySaver(),
+ *   maxMessages: 50,
+ *   llm: {
+ *     baseURL: 'https://api.bltcy.ai',
+ *     apiKey: 'sk-xxx',
+ *   },
+ * })
+ * ```
+ */
+interface AgentOptions {
+    /** 全局能力池，所有可用的 ToolKit */
+    toolkits: ToolKit[];
+    /** Agent 列表 */
+    agents: AgentProfile[];
+    /** Supervisor 的 Agent name，有值则启用多 Agent 模式 */
+    supervisor?: string;
+    /** 运行时场景，决定工具集过滤和动态 Prompt */
+    scene?: Scene;
+    /** LangGraph Checkpointer 实例（默认 MemorySaver） */
+    checkpointer?: BaseCheckpointSaver;
+    /** 滑动窗口大小（默认 50） */
+    maxMessages?: number;
+    /** LangChain Callbacks（如 LangFuse） */
+    callbacks?: BaseCallbackHandler[];
+    /** OpenAI 兼容网关配置（如中转商） */
+    llm?: {
+        /** 兼容 OpenAI 的 base URL，例如 https://api.bltcy.ai */
+        baseURL?: string;
+        /** API Key，优先级高于环境变量 OPENAI_API_KEY */
+        apiKey?: string;
+    };
+}
+/**
+ * `agent.chat()` 调用参数。
+ */
+interface ChatOptions {
+    /** 用户消息 */
+    message: string;
+    /** 对话线程 ID，用于记忆隔离 */
+    threadId: string;
+    /** 传给 `scene.prompt(ctx)` 的动态运行时数据 */
+    sceneContext?: Record<string, any>;
+}
+/**
+ * 标准化 SSE 事件联合类型。
+ *
+ * | 类型 | 触发时机 |
+ * |------|---------|
+ * | `text` | LLM 输出文本 token |
+ * | `tool_start` | 工具调用开始 |
+ * | `tool_end` | 工具调用结束 |
+ * | `handoff` | Agent 切换（多 Agent） |
+ * | `agent` | 当前回答的 Agent 身份 |
+ * | `error` | 执行出错 |
+ * | `done` | 流结束 |
+ */
+type SSEEvent = {
+    type: 'text';
+    content: string;
+} | {
+    type: 'tool_start';
+    toolName: string;
+    input: Record<string, any>;
+} | {
+    type: 'tool_end';
+    toolName: string;
+    output: any;
+} | {
+    type: 'handoff';
+    from: string;
+    to: string;
+} | {
+    type: 'agent';
+    name: string;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'done';
+};
+
+/**
+ * 定义一个 Agent 角色身份。
+ *
+ * 校验必填字段后返回不可变对象。
+ *
+ * @param input - 角色配置
+ * @returns 冻结的 AgentProfile 对象
+ *
+ * @example
+ * ```ts
+ * const director = defineProfile({
+ *   name: '导演',
+ *   systemPrompt: '你是一位视频导演...',
+ *   model: 'gpt-4o',
+ * })
+ * ```
+ */
+declare function defineProfile(input: AgentProfile): Readonly<AgentProfile>;
+
+/**
+ * 定义一个静态能力包。
+ *
+ * 校验必填字段后返回不可变对象。
+ *
+ * @param input - 能力包配置
+ * @returns 冻结的 ToolKit 对象
+ *
+ * @example
+ * ```ts
+ * const canvasToolKit = defineToolKit({
+ *   name: 'canvas',
+ *   tools: [bindElementTool, bindTrackTool],
+ *   prompt: '画面调整时优先使用 canvas 工具...',
+ * })
+ * ```
+ */
+declare function defineToolKit(input: ToolKit): Readonly<ToolKit>;
+
+/**
+ * 定义一个运行时场景。
+ *
+ * 校验必填字段后返回不可变对象。
+ *
+ * @param input - 场景配置
+ * @returns 冻结的 Scene 对象
+ *
+ * @example
+ * ```ts
+ * const timelineScene = defineScene({
+ *   name: 'timeline-editing',
+ *   toolkits: ['canvas', 'ai'],
+ *   prompt: (ctx) => `视频时长: ${ctx.duration}秒`,
+ *   onToolEnd: (toolName, result) => {
+ *     if (toolName === 'bindTrack') refreshTimeline()
+ *   },
+ * })
+ * ```
+ */
+declare function defineScene(input: Scene): Readonly<Scene>;
+
+/**
+ * Agent 实例的内部已解析配置类型。
+ *
+ * 将可选字段填充为默认值后的完整配置。
+ */
+interface ResolvedOptions extends AgentOptions {
+    maxMessages: number;
+    callbacks: BaseCallbackHandler[];
+    checkpointer: BaseCheckpointSaver;
+}
+/**
+ * Agent 核心类。
+ *
+ * 串联完整流程：参数校验 → ToolKit 过滤 → Prompt 拼接 → 图构建 → 流式输出。
+ *
+ * 不直接 new，通过 `createAgent()` 工厂函数创建。
+ */
+declare class Agent {
+    /** @internal */
+    readonly options: ResolvedOptions;
+    constructor(options: AgentOptions);
+    /**
+     * 发起对话，返回标准化 SSE 事件的异步生成器。
+     *
+     * 完整流程：
+     * 1. ToolKit 过滤（Scene.toolkits 决定）
+     * 2. Prompt 4 层拼接（Base → Profile → ToolKit → Scene）
+     * 3. 构建 LangGraph 图 + stream
+     * 4. 转换流事件 → 标准化 SSEEvent
+     *
+     * 任何异常均以 `error` + `done` 事件正常结束流，不崩溃。
+     *
+     * @param chatOptions - 对话参数
+     * @yields 标准化 SSE 事件序列
+     */
+    chat(chatOptions: ChatOptions): AsyncGenerator<SSEEvent>;
+    /**
+     * 返回 Express RequestHandler，直接用于路由挂载。
+     *
+     * @example
+     * ```ts
+     * app.post('/chat', agent.handleRequest())
+     * ```
+     */
+    handleRequest(): RequestHandler;
+    /**
+     * 参数校验 — 在构造时执行，快速失败。
+     */
+    private validate;
+}
+/**
+ * 创建 Agent 实例。
+ *
+ * @param options - Agent 配置项
+ * @returns Agent 实例
+ *
+ * @example
+ * ```ts
+ * const agent = createAgent({
+ *   toolkits: [canvasToolKit],
+ *   agents: [director],
+ *   scene: timelineScene,
+ * })
+ *
+ * for await (const event of agent.chat({ message: '你好', threadId: 'thread-001' })) {
+ *   console.log(event)
+ * }
+ * ```
+ */
+declare function createAgent(options: AgentOptions): Agent;
+
+/**
+ * 为 Agent 创建 Express SSE 处理器。
+ *
+ * 请求体格式：
+ * {
+ *   "message": "...",
+ *   "threadId": "...",
+ *   "sceneContext": { ... }
+ * }
+ *
+ * ## 错误处理
+ *
+ * - **请求体解析异常**：parseChatOptions 失败时返回 `error` 事件
+ * - **agent.chat() 异常**：流迭代过程中的异常会被捕获并转换为 `error` 事件
+ * - **响应写入异常**：res.write() 失败时（客户端断开连接）静默捕获，避免服务器崩溃
+ * - **所有异常路径**：确保最终都会发送 `done` 事件并关闭响应
+ */
+declare function createExpressHandler(agent: Agent): RequestHandler;
+
+/**
+ * 构建 4 层 Prompt 拼接链。
+ *
+ * ```
+ * ① Base       — 库内置固定指令（通用行为约束、防御性指令）
+ * ② Profile    — agent.systemPrompt（角色身份）
+ * ③ ToolKit    — 当前场景激活的 ToolKit.prompt（0~N 个）
+ * ④ Scene      — scene.prompt(sceneContext)（仅绑定 Scene 时）
+ * ```
+ *
+ * 各层以 `\n\n` 拼接，合并为单条 SystemMessage 字符串。
+ *
+ * @param params - 拼接所需的各层数据
+ * @returns 完整的 system prompt 字符串
+ */
+declare function buildPromptChain(params: {
+    /** 当前 Agent 角色 */
+    profile: AgentProfile;
+    /** 当前场景激活的 ToolKit prompt 列表 */
+    toolkitPrompts: string[];
+    /** 运行时场景（可选） */
+    scene?: Scene;
+    /** 传给 scene.prompt(ctx) 的动态数据（可选） */
+    sceneContext?: Record<string, any>;
+}): string;
+
+/**
+ * 构建单 Agent 图并返回双模式流。
+ *
+ * 使用 `createAgent` 创建 ReAct Agent，
+ * 通过 `streamMode: ['messages', 'updates']` 同时获取：
+ * - 逐 token 的文本流（messages 模式）
+ * - 节点级别的完整更新（updates 模式，用于工具调用结果）
+ *
+ * Callbacks 在 LLM 层和 graph.stream() 层双重透传，
+ * 确保 LangFuse 等观测工具能追踪完整 Agent 执行链路。
+ *
+ * ## 错误处理策略
+ *
+ * - **LLM 初始化异常**：ChatOpenAI 构造函数会在无效配置时抛出异常（如无效 API Key），
+ *   由调用方（agent.ts）的顶层 try-catch 捕获并转换为 `error` 事件
+ * - **Checkpointer 异常**：LangGraph 内部处理 checkpointer 加载/保存失败，
+ *   失败时会降级为无记忆模式继续执行，不会中断流
+ * - **工具执行异常**：LangGraph 内置异常处理，工具失败时会将错误信息作为 ToolMessage 返回给 LLM，
+ *   由 LLM 决定如何处理（重试、跳过或报告用户）
+ * - **流式输出异常**：stream() 过程中的网络异常或 LLM API 异常会抛出，
+ *   由调用方的 try-catch 捕获
+ *
+ * @param params - 图构建参数
+ * @returns 双模式流的异步可迭代对象
+ * @throws 当 LLM 初始化失败或 stream() 执行失败时抛出异常
+ */
+declare function buildSingleGraph(params: {
+    /** 完整的 system prompt（4 层拼接后） */
+    systemPrompt: string;
+    /** 当前场景激活的工具列表 */
+    tools: StructuredToolInterface[];
+    /** Agent 模型标识 */
+    model: string;
+    /** 用户消息 */
+    message: string;
+    /** 对话线程 ID */
+    threadId: string;
+    /** LangGraph Checkpointer */
+    checkpointer: BaseCheckpointSaver;
+    /** 滑动窗口大小 */
+    maxMessages: number;
+    /** LangChain Callbacks */
+    callbacks: BaseCallbackHandler[];
+    /** 底层 LLM 网关配置（OpenAI 兼容） */
+    llm?: AgentOptions['llm'];
+}): Promise<_langchain_core_utils_stream.IterableReadableStream<["updates", Record<string, any>] | ["messages", [langchain.BaseMessage<_langchain_core_messages.MessageStructure<_langchain_core_messages.MessageToolSet>, _langchain_core_messages.MessageType>, Record<string, any>]]>>;
+
+/**
+ * 构建多 Agent Supervisor 图并返回双模式流。
+ *
+ * 使用 `@langchain/langgraph-supervisor` 的 `createSupervisor` 构建：
+ * - Supervisor 负责任务分析与分派
+ * - Workers 为各 AgentProfile 对应的 ReAct Agent
+ *
+ * 工具在 Supervisor 级别不注入（Supervisor 只负责路由），
+ * 所有工具注入到 Worker Agent 中，由 Scene 过滤后的工具集共享。
+ *
+ * ## 错误处理策略
+ *
+ * - **LLM 初始化异常**：任一 LLM（Supervisor / Worker）初始化失败时抛出异常，
+ *   由调用方（agent.ts）的顶层 try-catch 捕获
+ * - **Worker 创建异常**：单个 Worker 创建失败时记录错误并跳过该 Worker，
+ *   至少保证 1 个 Worker 可用才继续执行
+ * - **Checkpointer 异常**：同单 Agent 模式，LangGraph 内部降级处理
+ * - **流式输出异常**：stream() 过程中的异常会抛出，由调用方捕获
+ *
+ * @param params - 图构建参数
+ * @returns 双模式流的异步可迭代对象
+ * @throws 当 LLM 初始化失败、Worker 全部创建失败或 stream() 执行失败时抛出异常
+ */
+declare function buildSupervisorGraph(params: {
+    /** Supervisor 的 Prompt（4 层拼接后，用于 Supervisor Agent） */
+    supervisorPrompt: string;
+    /** 所有 AgentProfile 列表 */
+    agents: AgentProfile[];
+    /** Supervisor 的 agent name */
+    supervisorName: string;
+    /** 当前场景激活的工具列表（所有 Worker 共享） */
+    tools: StructuredToolInterface[];
+    /** 各 Worker 的 Prompt 映射（profile.name → 4 层拼接后的 prompt） */
+    workerPrompts: Map<string, string>;
+    /** 用户消息 */
+    message: string;
+    /** 对话线程 ID */
+    threadId: string;
+    /** LangGraph Checkpointer */
+    checkpointer: BaseCheckpointSaver;
+    /** 滑动窗口大小 */
+    maxMessages: number;
+    /** LangChain Callbacks */
+    callbacks: BaseCallbackHandler[];
+    /** 底层 LLM 网关配置（OpenAI 兼容） */
+    llm?: AgentOptions['llm'];
+}): Promise<_langchain_core_utils_stream.IterableReadableStream<["messages", [langchain.BaseMessage<_langchain_core_messages.MessageStructure<_langchain_core_messages.MessageToolSet>, _langchain_core_messages.MessageType>, Record<string, any>]] | ["updates", Record<string, _langchain_langgraph.UpdateType<_langchain_langgraph.StateDefinition> | _langchain_langgraph.UpdateType<any>>]>>;
+
+/**
+ * 将 LangGraph `stream()` 的双模式流（messages + updates）
+ * 转换为标准化 SSEEvent 序列。
+ *
+ * 事件映射逻辑：
+ * - `messages` 模式的 AIMessageChunk（含 content）→ `text` 事件
+ * - `messages` 模式的 AIMessageChunk（含 tool_call_chunks）→ `tool_start` 事件
+ * - `updates` 模式的 tools 节点输出（ToolMessage）→ `tool_end` 事件
+ * - `messages` 模式的 metadata.langgraph_node 变化 → `agent` + `handoff` 事件（多 Agent）
+ *
+ * ## 错误处理
+ *
+ * - **流迭代异常**：stream 本身抛出异常时（网络中断、LLM API 异常），
+ *   由调用方（agent.ts）的 try-catch 捕获并转换为 `error` 事件
+ * - **chunk 解析异常**：单个 chunk 解析失败时记录错误并跳过该 chunk，不中断流
+ * - **生命周期回调异常**：onToolEnd 抛出异常时静默捕获，不影响流
+ *
+ * @param stream - LangGraph stream() 返回的异步可迭代对象
+ * @param onToolEnd - Scene.onToolEnd 生命周期回调（可选）
+ */
+declare function transformStream(stream: AsyncIterable<any>, onToolEnd?: (toolName: string, result: any) => void): AsyncGenerator<SSEEvent>;
+/**
+ * 将 SSEEvent 格式化为 SSE 协议字符串 `data: JSON\n\n`。
+ */
+declare function formatSSE(event: SSEEvent): string;
+
+export { Agent, type AgentOptions, type AgentProfile, type ChatOptions, type SSEEvent, type Scene, type ToolKit, buildPromptChain, buildSingleGraph, buildSupervisorGraph, createAgent, createExpressHandler, defineProfile, defineScene, defineToolKit, formatSSE, transformStream };