agent-scene-toolkit 0.1.3 → 0.1.6

package/dist/index.d.cts

@@ -152,6 +152,8 @@ interface AgentOptions {
         /** API Key，优先级高于环境变量 OPENAI_API_KEY */
         apiKey?: string;
     };
+    /** LangGraph 递归调用限制（单 Agent 默认 25，多 Agent 默认 50） */
+    recursionLimit?: number;
 }
 /**
  * `agent.chat()` 调用参数。
@@ -396,13 +398,12 @@ declare function createAgent(options: AgentOptions): Agent;
 declare function createExpressHandler(agent: Agent): RequestHandler;
 
 /**
- * 构建 4 层 Prompt 拼接链。
+ * 构建 3 层 Prompt 拼接链。
  *
  * ```
- * ① Base       — 库内置固定指令（通用行为约束、防御性指令）
- * ② Profile    — agent.systemPrompt（角色身份）
- * ③ ToolKit    — 当前场景激活的 ToolKit.prompt（0~N 个）
- * ④ Scene      — scene.prompt(sceneContext)（仅绑定 Scene 时）
+ * ① Profile    — agent.systemPrompt（角色身份）
+ * ② ToolKit    — 当前场景激活的 ToolKit.prompt（0~N 个）
+ * ③ Scene      — scene.prompt(sceneContext)（仅绑定 Scene 时）
  * ```
  *
  * 各层以 `\n\n` 拼接，合并为单条 SystemMessage 字符串。
@@ -448,7 +449,7 @@ declare function buildPromptChain(params: {
  * @throws 当 LLM 初始化失败或 stream() 执行失败时抛出异常
  */
 declare function buildSingleGraph(params: {
-    /** 完整的 system prompt（4 层拼接后） */
+    /** 完整的 system prompt（3 层拼接后） */
     systemPrompt: string;
     /** 当前场景激活的工具列表 */
     tools: StructuredToolInterface[];
@@ -466,7 +467,15 @@ declare function buildSingleGraph(params: {
     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>]]>>;
+    /** 递归调用限制（默认 25） */
+    recursionLimit?: number;
+    /** 运行时场景（可选），有值时启用动态 scene prompt 刷新 */
+    scene?: Scene;
+    /** 传给 scene.prompt(ctx) 的动态数据（可选） */
+    sceneContext?: Record<string, any>;
+    /** Profile + ToolKit prompt 的静态拼接（不含 scene prompt），用于 middleware 重新拼接 */
+    staticPromptParts?: string;
+}): 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, any>]>>;
 
 /**
  * 构建多 Agent Supervisor 图并返回双模式流。
@@ -492,7 +501,7 @@ declare function buildSingleGraph(params: {
  * @throws 当 LLM 初始化失败、Worker 全部创建失败或 stream() 执行失败时抛出异常
  */
 declare function buildSupervisorGraph(params: {
-    /** Supervisor 的 Prompt（4 层拼接后，用于 Supervisor Agent） */
+    /** Supervisor 的 Prompt（3 层拼接后，用于 Supervisor Agent） */
     supervisorPrompt: string;
     /** 所有 AgentProfile 列表 */
     agents: AgentProfile[];
@@ -500,7 +509,7 @@ declare function buildSupervisorGraph(params: {
     supervisorName: string;
     /** 当前场景激活的工具列表（所有 Worker 共享） */
     tools: StructuredToolInterface[];
-    /** 各 Worker 的 Prompt 映射（profile.name → 4 层拼接后的 prompt） */
+    /** 各 Worker 的 Prompt 映射（profile.name → 3 层拼接后的 prompt） */
     workerPrompts: Map<string, string>;
     /** 用户消息 */
     message: string;
@@ -514,7 +523,15 @@ declare function buildSupervisorGraph(params: {
     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>>]>>;
+    /** 递归调用限制（默认 50） */
+    recursionLimit?: number;
+    /** 运行时场景（可选），有值时启用动态 scene prompt 刷新 */
+    scene?: Scene;
+    /** 传给 scene.prompt(ctx) 的动态数据（可选） */
+    sceneContext?: Record<string, any>;
+    /** 各角色的静态 prompt 部分映射（profile.name → Profile + ToolKit prompt 的拼接，不含 scene prompt） */
+    staticPromptPartsMap?: Map<string, string>;
+}): 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<any> | _langchain_langgraph.UpdateType<_langchain_langgraph.StateDefinition>>]>>;
 
 /**
  * 将 LangGraph `stream()` 的双模式流（messages + updates）

package/dist/index.d.ts

@@ -152,6 +152,8 @@ interface AgentOptions {
         /** API Key，优先级高于环境变量 OPENAI_API_KEY */
         apiKey?: string;
     };
+    /** LangGraph 递归调用限制（单 Agent 默认 25，多 Agent 默认 50） */
+    recursionLimit?: number;
 }
 /**
  * `agent.chat()` 调用参数。
@@ -396,13 +398,12 @@ declare function createAgent(options: AgentOptions): Agent;
 declare function createExpressHandler(agent: Agent): RequestHandler;
 
 /**
- * 构建 4 层 Prompt 拼接链。
+ * 构建 3 层 Prompt 拼接链。
  *
  * ```
- * ① Base       — 库内置固定指令（通用行为约束、防御性指令）
- * ② Profile    — agent.systemPrompt（角色身份）
- * ③ ToolKit    — 当前场景激活的 ToolKit.prompt（0~N 个）
- * ④ Scene      — scene.prompt(sceneContext)（仅绑定 Scene 时）
+ * ① Profile    — agent.systemPrompt（角色身份）
+ * ② ToolKit    — 当前场景激活的 ToolKit.prompt（0~N 个）
+ * ③ Scene      — scene.prompt(sceneContext)（仅绑定 Scene 时）
  * ```
  *
  * 各层以 `\n\n` 拼接，合并为单条 SystemMessage 字符串。
@@ -448,7 +449,7 @@ declare function buildPromptChain(params: {
  * @throws 当 LLM 初始化失败或 stream() 执行失败时抛出异常
  */
 declare function buildSingleGraph(params: {
-    /** 完整的 system prompt（4 层拼接后） */
+    /** 完整的 system prompt（3 层拼接后） */
     systemPrompt: string;
     /** 当前场景激活的工具列表 */
     tools: StructuredToolInterface[];
@@ -466,7 +467,15 @@ declare function buildSingleGraph(params: {
     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>]]>>;
+    /** 递归调用限制（默认 25） */
+    recursionLimit?: number;
+    /** 运行时场景（可选），有值时启用动态 scene prompt 刷新 */
+    scene?: Scene;
+    /** 传给 scene.prompt(ctx) 的动态数据（可选） */
+    sceneContext?: Record<string, any>;
+    /** Profile + ToolKit prompt 的静态拼接（不含 scene prompt），用于 middleware 重新拼接 */
+    staticPromptParts?: string;
+}): 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, any>]>>;
 
 /**
  * 构建多 Agent Supervisor 图并返回双模式流。
@@ -492,7 +501,7 @@ declare function buildSingleGraph(params: {
  * @throws 当 LLM 初始化失败、Worker 全部创建失败或 stream() 执行失败时抛出异常
  */
 declare function buildSupervisorGraph(params: {
-    /** Supervisor 的 Prompt（4 层拼接后，用于 Supervisor Agent） */
+    /** Supervisor 的 Prompt（3 层拼接后，用于 Supervisor Agent） */
     supervisorPrompt: string;
     /** 所有 AgentProfile 列表 */
     agents: AgentProfile[];
@@ -500,7 +509,7 @@ declare function buildSupervisorGraph(params: {
     supervisorName: string;
     /** 当前场景激活的工具列表（所有 Worker 共享） */
     tools: StructuredToolInterface[];
-    /** 各 Worker 的 Prompt 映射（profile.name → 4 层拼接后的 prompt） */
+    /** 各 Worker 的 Prompt 映射（profile.name → 3 层拼接后的 prompt） */
     workerPrompts: Map<string, string>;
     /** 用户消息 */
     message: string;
@@ -514,7 +523,15 @@ declare function buildSupervisorGraph(params: {
     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>>]>>;
+    /** 递归调用限制（默认 50） */
+    recursionLimit?: number;
+    /** 运行时场景（可选），有值时启用动态 scene prompt 刷新 */
+    scene?: Scene;
+    /** 传给 scene.prompt(ctx) 的动态数据（可选） */
+    sceneContext?: Record<string, any>;
+    /** 各角色的静态 prompt 部分映射（profile.name → Profile + ToolKit prompt 的拼接，不含 scene prompt） */
+    staticPromptPartsMap?: Map<string, string>;
+}): 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<any> | _langchain_langgraph.UpdateType<_langchain_langgraph.StateDefinition>>]>>;
 
 /**
  * 将 LangGraph `stream()` 的双模式流（messages + updates）

package/dist/index.js

@@ -1,7 +1,7 @@
 import { MemorySaver } from '@langchain/langgraph';
 import { ChatOpenAI } from '@langchain/openai';
-import { createAgent, createMiddleware } from 'langchain';
-import { HumanMessage, AIMessageChunk, ToolMessage } from '@langchain/core/messages';
+import { createMiddleware, createAgent } from 'langchain';
+import { HumanMessage, SystemMessage, AIMessageChunk, ToolMessage } from '@langchain/core/messages';
 import { createReactAgent } from '@langchain/langgraph/prebuilt';
 import { createSupervisor } from '@langchain/langgraph-supervisor';
 import { DynamicTool } from '@langchain/core/tools';
@@ -48,30 +48,44 @@ function defineKnowledgeBase(input) {
 }
 
 // src/prompt.ts
-var BASE_PROMPT = `You are an autonomous AI agent. You can reason, plan, and take actions using the tools available to you.
-
-## Core Behavior
-- When given a task, break it down into steps, then execute each step using the appropriate tools.
-- After each tool call, observe the result and decide the next action. Continue until the task is fully completed.
-- If no tools are needed, respond directly with your knowledge.
-- Never fabricate uncertain information. If you cannot complete a task, explain why honestly.
-
-## Rules
-- Respond in the same language as the user.
-- Follow tool parameter schemas strictly \u2014 do not invent or omit required fields.
-- When multiple tools are available, choose the most relevant one for the current step.`;
+function removeCircularReferences(obj) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  function clone(value) {
+    if (value === null || typeof value !== "object") {
+      return value;
+    }
+    if (seen.has(value)) {
+      return "[Circular Reference]";
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+      return value.map((item) => clone(item));
+    }
+    const cloned = {};
+    for (const key in value) {
+      if (Object.prototype.hasOwnProperty.call(value, key)) {
+        try {
+          cloned[key] = clone(value[key]);
+        } catch (error) {
+          cloned[key] = "[Unserializable]";
+        }
+      }
+    }
+    return cloned;
+  }
+  return clone(obj);
+}
 function buildPromptChain(params) {
   const layers = [
-    // ① Base — 库内置固定指令
-    BASE_PROMPT,
-    // ② Profile — 角色身份提示词
+    // ① Profile — 角色身份提示词
     params.profile.systemPrompt,
-    // ③ ToolKit — 当前场景激活的能力包提示词
+    // ② ToolKit — 当前场景激活的能力包提示词
     ...params.toolkitPrompts
   ];
   if (params.scene) {
     try {
-      const scenePrompt = params.scene.prompt(params.sceneContext ?? {});
+      const safeContext = removeCircularReferences(params.sceneContext ?? {});
+      const scenePrompt = params.scene.prompt(safeContext);
       layers.push(scenePrompt);
     } catch (error) {
       console.error("[buildPromptChain] Scene.prompt() error:", error);
@@ -102,6 +116,45 @@ async function buildSingleGraph(params) {
   console.log("[buildSingleGraph] tools:", params.tools.map((t) => t.name));
   console.log("[buildSingleGraph] threadId:", params.threadId);
   console.log("[buildSingleGraph] maxMessages:", params.maxMessages);
+  const middlewares = [
+    // 滑动窗口中间件 — beforeModel 阶段裁剪消息，Checkpointer 仍全量存储
+    createMiddleware({
+      name: "sliding-window",
+      beforeModel: (state) => {
+        try {
+          const max = params.maxMessages;
+          if (!state.messages || state.messages.length <= max) return void 0;
+          return { messages: state.messages.slice(-max) };
+        } catch (error) {
+          console.error("[buildSingleGraph] sliding-window middleware error:", error);
+          return void 0;
+        }
+      }
+    })
+  ];
+  if (params.scene && params.staticPromptParts !== void 0) {
+    middlewares.push(
+      createMiddleware({
+        name: "scene-refresh",
+        wrapModelCall: async (request, handler) => {
+          try {
+            const freshSystemPrompt = buildPromptChain({
+              // 使用静态部分 + 最新 scene prompt 重新拼接
+              profile: { name: "", systemPrompt: params.staticPromptParts, model: "" },
+              toolkitPrompts: [],
+              // 已包含在 staticPromptParts 中
+              scene: params.scene,
+              sceneContext: params.sceneContext
+            });
+            return handler({ ...request, systemPrompt: freshSystemPrompt });
+          } catch (error) {
+            console.error("[buildSingleGraph] scene-refresh middleware error:", error);
+            return handler(request);
+          }
+        }
+      })
+    );
+  }
   let graph;
   try {
     graph = createAgent({
@@ -109,22 +162,7 @@ async function buildSingleGraph(params) {
       tools: params.tools,
       checkpointer: params.checkpointer,
       systemPrompt: params.systemPrompt,
-      // 滑动窗口中间件 — beforeModel 阶段裁剪消息，Checkpointer 仍全量存储
-      middleware: [
-        createMiddleware({
-          name: "sliding-window",
-          beforeModel: (state) => {
-            try {
-              const max = params.maxMessages;
-              if (!state.messages || state.messages.length <= max) return void 0;
-              return { messages: state.messages.slice(-max) };
-            } catch (error) {
-              console.error("[buildSingleGraph] sliding-window middleware error:", error);
-              return void 0;
-            }
-          }
-        })
-      ]
+      middleware: middlewares
     });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -136,7 +174,7 @@ async function buildSingleGraph(params) {
       { messages: [new HumanMessage(params.message)] },
       {
         configurable: { thread_id: params.threadId },
-        recursionLimit: 25,
+        recursionLimit: params.recursionLimit ?? 25,
         streamMode: ["messages", "updates"],
         // graph 层透传 callbacks — 追踪完整执行链路（工具调用、节点跳转等）
         callbacks: callbacksOrUndefined
@@ -162,7 +200,27 @@ async function buildSupervisorGraph(params) {
         configuration: params.llm?.baseURL ? { baseURL: params.llm.baseURL } : void 0,
         callbacks: callbacksOrUndefined
       });
-      const workerPrompt = params.workerPrompts.get(profile.name) ?? profile.systemPrompt;
+      const workerStaticPrompt = params.workerPrompts.get(profile.name) ?? profile.systemPrompt;
+      let workerPrompt;
+      const workerStaticParts = params.staticPromptPartsMap?.get(profile.name);
+      if (params.scene && workerStaticParts !== void 0) {
+        workerPrompt = () => {
+          try {
+            const freshPrompt = buildPromptChain({
+              profile: { name: "", systemPrompt: workerStaticParts, model: "" },
+              toolkitPrompts: [],
+              scene: params.scene,
+              sceneContext: params.sceneContext
+            });
+            return [new SystemMessage(freshPrompt)];
+          } catch (error) {
+            console.error(`[buildSupervisorGraph] Worker "${profile.name}" scene-refresh error:`, error);
+            return [new SystemMessage(workerStaticPrompt)];
+          }
+        };
+      } else {
+        workerPrompt = workerStaticPrompt;
+      }
       const worker = createReactAgent({
         llm: workerLLM,
         tools: params.tools,
@@ -204,12 +262,32 @@ async function buildSupervisorGraph(params) {
   console.log("[buildSupervisorGraph] workers:", workers.map((_, i) => workerProfiles[i]?.name));
   console.log("[buildSupervisorGraph] tools:", params.tools.map((t) => t.name));
   console.log("[buildSupervisorGraph] threadId:", params.threadId);
+  const supervisorStaticParts = params.staticPromptPartsMap?.get(params.supervisorName);
+  let supervisorPromptArg;
+  if (params.scene && supervisorStaticParts !== void 0) {
+    supervisorPromptArg = () => {
+      try {
+        const freshPrompt = buildPromptChain({
+          profile: { name: "", systemPrompt: supervisorStaticParts, model: "" },
+          toolkitPrompts: [],
+          scene: params.scene,
+          sceneContext: params.sceneContext
+        });
+        return [new SystemMessage(freshPrompt)];
+      } catch (error) {
+        console.error("[buildSupervisorGraph] Supervisor scene-refresh error:", error);
+        return [new SystemMessage(params.supervisorPrompt)];
+      }
+    };
+  } else {
+    supervisorPromptArg = params.supervisorPrompt;
+  }
   let workflow;
   try {
     workflow = createSupervisor({
       agents: workers,
       llm: supervisorLLM,
-      prompt: params.supervisorPrompt,
+      prompt: supervisorPromptArg,
       // 保留完整消息历史，让前端能追踪 handoff 过程
       outputMode: "full_history",
       // 滑动窗口 — 只裁剪发给 LLM 的消息，Checkpointer 仍全量存储
@@ -247,7 +325,7 @@ async function buildSupervisorGraph(params) {
       { messages: [new HumanMessage(params.message)] },
       {
         configurable: { thread_id: params.threadId },
-        recursionLimit: 50,
+        recursionLimit: params.recursionLimit ?? 50,
         // 多 Agent 需要更高的递归限制
         streamMode: ["messages", "updates"],
         callbacks: callbacksOrUndefined
@@ -584,6 +662,16 @@ var Agent = class {
             );
           }
         }
+        let staticPromptPartsMap;
+        if (scene) {
+          staticPromptPartsMap = /* @__PURE__ */ new Map();
+          for (const profile of this.options.agents) {
+            staticPromptPartsMap.set(
+              profile.name,
+              [profile.systemPrompt, ...toolkitPrompts].filter(Boolean).join("\n\n")
+            );
+          }
+        }
         stream = await buildSupervisorGraph({
           supervisorPrompt,
           agents: this.options.agents,
@@ -595,10 +683,16 @@ var Agent = class {
           checkpointer: this.options.checkpointer,
           maxMessages: this.options.maxMessages,
           callbacks: this.options.callbacks,
-          llm: this.options.llm
+          llm: this.options.llm,
+          recursionLimit: this.options.recursionLimit,
+          // Scene 动态刷新所需参数
+          scene,
+          sceneContext: chatOptions.sceneContext,
+          staticPromptPartsMap
         });
       } else {
         const profile = this.options.agents[0];
+        const staticPromptParts = [profile.systemPrompt, ...toolkitPrompts].filter(Boolean).join("\n\n");
         const systemPrompt = buildPromptChain({
           profile,
           toolkitPrompts,
@@ -614,7 +708,12 @@ var Agent = class {
           checkpointer: this.options.checkpointer,
           maxMessages: this.options.maxMessages,
           callbacks: this.options.callbacks,
-          llm: this.options.llm
+          llm: this.options.llm,
+          recursionLimit: this.options.recursionLimit,
+          // Scene 动态刷新所需参数 — 有 scene 时 middleware 会在每次 LLM 调用前重新执行 scene.prompt()
+          scene,
+          sceneContext: chatOptions.sceneContext,
+          staticPromptParts: scene ? staticPromptParts : void 0
         });
       }
       yield* transformStream(stream, scene?.onToolEnd);