agent-scene-toolkit 0.1.2 → 0.1.4

package/dist/index.d.cts

@@ -2,6 +2,7 @@ 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 { EmbeddingsInterface } from '@langchain/core/embeddings';
 import { RequestHandler } from 'express';
 import * as _langchain_core_utils_stream from '@langchain/core/utils/stream';
 import * as langchain from 'langchain';
@@ -72,6 +73,40 @@ interface Scene {
     /** 工具调用完成后的生命周期回调 */
     readonly onToolEnd?: (toolName: string, result: any) => void;
 }
+/**
+ * 知识库 — 纯文本数据 + 语义检索描述。
+ *
+ * 库内部自动将文本向量化并包装为 LangChain Tool，AI 根据 `description` 自主决定何时检索。
+ *
+ * @example
+ * ```ts
+ * const faqKB = defineKnowledgeBase({
+ *   name: 'faq',
+ *   description: '产品常见问题，当用户问功能、价格、退款等问题时检索',
+ *   documents: ['7天内无理由退款', '基础版99元/月'],
+ * })
+ *
+ * // 也支持异步加载
+ * const dynamicKB = defineKnowledgeBase({
+ *   name: 'dynamic-docs',
+ *   description: '从数据库动态加载的文档',
+ *   documents: async () => {
+ *     const res = await fetch('/api/docs')
+ *     return res.json()
+ *   },
+ * })
+ * ```
+ */
+interface KnowledgeBase {
+    /** 知识库唯一标识，也作为 Tool 名称 */
+    readonly name: string;
+    /** 描述知识库用途，AI 据此判断何时检索 */
+    readonly description: string;
+    /** 纯文本数据：静态数组或异步加载函数 */
+    readonly documents: string[] | (() => Promise<string[]>);
+    /** 返回最相关的前 K 条结果（默认 3） */
+    readonly topK?: number;
+}
 /**
  * `createAgent()` 配置项。
  *
@@ -106,6 +141,10 @@ interface AgentOptions {
     maxMessages?: number;
     /** LangChain Callbacks */
     callbacks?: BaseCallbackHandler[];
+    /** 知识库列表，有值则启用 RAG（检索增强生成） */
+    knowledgeBases?: KnowledgeBase[];
+    /** 嵌入模型实例，当 knowledgeBases 存在时必填 */
+    embeddings?: EmbeddingsInterface;
     /** OpenAI 兼容网关配置（如中转商） */
     llm?: {
         /** 兼容 OpenAI 的 base URL，例如 https://api.bltcy.ai */
@@ -223,6 +262,38 @@ declare function defineToolKit(input: ToolKit): Readonly<ToolKit>;
  */
 declare function defineScene(input: Scene): Readonly<Scene>;
 
+/**
+ * 定义一个知识库。
+ *
+ * 校验必填字段后返回不可变对象。
+ * 库内部自动将文本向量化并包装为 LangChain Tool，AI 根据 `description` 自主决定何时检索。
+ *
+ * @param input - 知识库配置
+ * @returns 冻结的 KnowledgeBase 对象
+ *
+ * @example
+ * ```ts
+ * // 静态文本
+ * const faqKB = defineKnowledgeBase({
+ *   name: 'faq',
+ *   description: '产品常见问题，当用户问功能、价格、退款等问题时检索',
+ *   documents: ['7天内无理由退款', '基础版99元/月', '支持微信支付宝付款'],
+ *   topK: 3,
+ * })
+ *
+ * // 从数据库/API 动态加载
+ * const dynamicKB = defineKnowledgeBase({
+ *   name: 'dynamic-docs',
+ *   description: '从数据库动态加载的文档',
+ *   documents: async () => {
+ *     const res = await fetch('/api/docs')
+ *     return res.json()
+ *   },
+ * })
+ * ```
+ */
+declare function defineKnowledgeBase(input: KnowledgeBase): Readonly<KnowledgeBase>;
+
 /**
  * Agent 实例的内部已解析配置类型。
  *
@@ -243,7 +314,18 @@ interface ResolvedOptions extends AgentOptions {
 declare class Agent {
     /** @internal */
     readonly options: ResolvedOptions;
+    /** RAG 知识库转换而来的 DynamicTool 列表 */
+    private knowledgeTools;
+    /** 异步初始化 Promise（向量化知识库等） */
+    private readyPromise;
     constructor(options: AgentOptions);
+    /**
+     * 异步初始化 — 向量化知识库并构建检索 Tool。
+     *
+     * 在构造函数中启动，chat() 首次调用时 await 确保完成。
+     * 若无 knowledgeBases，立即 resolve。
+     */
+    private init;
     /**
      * 发起对话，返回标准化 SSE 事件的异步生成器。
      *
@@ -314,13 +396,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 字符串。
@@ -460,4 +541,4 @@ declare function transformStream(stream: AsyncIterable<any>, onToolEnd?: (toolNa
  */
 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 };
+export { Agent, type AgentOptions, type AgentProfile, type ChatOptions, type KnowledgeBase, type SSEEvent, type Scene, type ToolKit, buildPromptChain, buildSingleGraph, buildSupervisorGraph, createAgent, createExpressHandler, defineKnowledgeBase, defineProfile, defineScene, defineToolKit, formatSSE, transformStream };

package/dist/index.d.ts

@@ -2,6 +2,7 @@ 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 { EmbeddingsInterface } from '@langchain/core/embeddings';
 import { RequestHandler } from 'express';
 import * as _langchain_core_utils_stream from '@langchain/core/utils/stream';
 import * as langchain from 'langchain';
@@ -72,6 +73,40 @@ interface Scene {
     /** 工具调用完成后的生命周期回调 */
     readonly onToolEnd?: (toolName: string, result: any) => void;
 }
+/**
+ * 知识库 — 纯文本数据 + 语义检索描述。
+ *
+ * 库内部自动将文本向量化并包装为 LangChain Tool，AI 根据 `description` 自主决定何时检索。
+ *
+ * @example
+ * ```ts
+ * const faqKB = defineKnowledgeBase({
+ *   name: 'faq',
+ *   description: '产品常见问题，当用户问功能、价格、退款等问题时检索',
+ *   documents: ['7天内无理由退款', '基础版99元/月'],
+ * })
+ *
+ * // 也支持异步加载
+ * const dynamicKB = defineKnowledgeBase({
+ *   name: 'dynamic-docs',
+ *   description: '从数据库动态加载的文档',
+ *   documents: async () => {
+ *     const res = await fetch('/api/docs')
+ *     return res.json()
+ *   },
+ * })
+ * ```
+ */
+interface KnowledgeBase {
+    /** 知识库唯一标识，也作为 Tool 名称 */
+    readonly name: string;
+    /** 描述知识库用途，AI 据此判断何时检索 */
+    readonly description: string;
+    /** 纯文本数据：静态数组或异步加载函数 */
+    readonly documents: string[] | (() => Promise<string[]>);
+    /** 返回最相关的前 K 条结果（默认 3） */
+    readonly topK?: number;
+}
 /**
  * `createAgent()` 配置项。
  *
@@ -106,6 +141,10 @@ interface AgentOptions {
     maxMessages?: number;
     /** LangChain Callbacks */
     callbacks?: BaseCallbackHandler[];
+    /** 知识库列表，有值则启用 RAG（检索增强生成） */
+    knowledgeBases?: KnowledgeBase[];
+    /** 嵌入模型实例，当 knowledgeBases 存在时必填 */
+    embeddings?: EmbeddingsInterface;
     /** OpenAI 兼容网关配置（如中转商） */
     llm?: {
         /** 兼容 OpenAI 的 base URL，例如 https://api.bltcy.ai */
@@ -223,6 +262,38 @@ declare function defineToolKit(input: ToolKit): Readonly<ToolKit>;
  */
 declare function defineScene(input: Scene): Readonly<Scene>;
 
+/**
+ * 定义一个知识库。
+ *
+ * 校验必填字段后返回不可变对象。
+ * 库内部自动将文本向量化并包装为 LangChain Tool，AI 根据 `description` 自主决定何时检索。
+ *
+ * @param input - 知识库配置
+ * @returns 冻结的 KnowledgeBase 对象
+ *
+ * @example
+ * ```ts
+ * // 静态文本
+ * const faqKB = defineKnowledgeBase({
+ *   name: 'faq',
+ *   description: '产品常见问题，当用户问功能、价格、退款等问题时检索',
+ *   documents: ['7天内无理由退款', '基础版99元/月', '支持微信支付宝付款'],
+ *   topK: 3,
+ * })
+ *
+ * // 从数据库/API 动态加载
+ * const dynamicKB = defineKnowledgeBase({
+ *   name: 'dynamic-docs',
+ *   description: '从数据库动态加载的文档',
+ *   documents: async () => {
+ *     const res = await fetch('/api/docs')
+ *     return res.json()
+ *   },
+ * })
+ * ```
+ */
+declare function defineKnowledgeBase(input: KnowledgeBase): Readonly<KnowledgeBase>;
+
 /**
  * Agent 实例的内部已解析配置类型。
  *
@@ -243,7 +314,18 @@ interface ResolvedOptions extends AgentOptions {
 declare class Agent {
     /** @internal */
     readonly options: ResolvedOptions;
+    /** RAG 知识库转换而来的 DynamicTool 列表 */
+    private knowledgeTools;
+    /** 异步初始化 Promise（向量化知识库等） */
+    private readyPromise;
     constructor(options: AgentOptions);
+    /**
+     * 异步初始化 — 向量化知识库并构建检索 Tool。
+     *
+     * 在构造函数中启动，chat() 首次调用时 await 确保完成。
+     * 若无 knowledgeBases，立即 resolve。
+     */
+    private init;
     /**
      * 发起对话，返回标准化 SSE 事件的异步生成器。
      *
@@ -314,13 +396,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 字符串。
@@ -460,4 +541,4 @@ declare function transformStream(stream: AsyncIterable<any>, onToolEnd?: (toolNa
  */
 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 };
+export { Agent, type AgentOptions, type AgentProfile, type ChatOptions, type KnowledgeBase, type SSEEvent, type Scene, type ToolKit, buildPromptChain, buildSingleGraph, buildSupervisorGraph, createAgent, createExpressHandler, defineKnowledgeBase, defineProfile, defineScene, defineToolKit, formatSSE, transformStream };

package/dist/index.js

@@ -4,6 +4,7 @@ import { createAgent, createMiddleware } from 'langchain';
 import { HumanMessage, AIMessageChunk, ToolMessage } from '@langchain/core/messages';
 import { createReactAgent } from '@langchain/langgraph/prebuilt';
 import { createSupervisor } from '@langchain/langgraph-supervisor';
+import { DynamicTool } from '@langchain/core/tools';
 
 // src/profile.ts
 function defineProfile(input) {
@@ -29,26 +30,29 @@ function defineScene(input) {
   return Object.freeze({ ...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.
+// src/knowledge.ts
+function defineKnowledgeBase(input) {
+  if (!input.name) throw new Error("KnowledgeBase name is required");
+  if (!input.description) throw new Error("KnowledgeBase description is required");
+  if (!input.documents) throw new Error("KnowledgeBase documents is required");
+  if (typeof input.documents !== "function" && !Array.isArray(input.documents)) {
+    throw new Error("KnowledgeBase documents must be a string[] or () => Promise<string[]>");
+  }
+  if (Array.isArray(input.documents) && input.documents.length === 0) {
+    throw new Error("KnowledgeBase documents must not be empty");
+  }
+  if (input.topK !== void 0 && (typeof input.topK !== "number" || input.topK < 1)) {
+    throw new Error("KnowledgeBase topK must be a positive number");
+  }
+  return Object.freeze({ ...input });
+}
 
-## 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.`;
+// src/prompt.ts
 function buildPromptChain(params) {
   const layers = [
-    // ① Base — 库内置固定指令
-    BASE_PROMPT,
-    // ② Profile — 角色身份提示词
+    // ① Profile — 角色身份提示词
     params.profile.systemPrompt,
-    // ③ ToolKit — 当前场景激活的能力包提示词
+    // ② ToolKit — 当前场景激活的能力包提示词
     ...params.toolkitPrompts
   ];
   if (params.scene) {
@@ -401,11 +405,81 @@ function createExpressHandler(agent) {
     }
   };
 }
+function cosineSimilarity(a, b) {
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}
+async function initVectorStores(knowledgeBases, embeddings) {
+  const stores = [];
+  for (const kb of knowledgeBases) {
+    try {
+      const docs = typeof kb.documents === "function" ? await kb.documents() : kb.documents;
+      if (!docs.length) {
+        console.warn(`[initVectorStores] "${kb.name}" has no documents, skipping`);
+        continue;
+      }
+      console.log(`[initVectorStores] Embedding "${kb.name}" (${docs.length} documents)...`);
+      const vectors = await embeddings.embedDocuments(docs);
+      const records = docs.map((text, i) => ({
+        text,
+        vector: vectors[i]
+      }));
+      stores.push({ kb, records });
+      console.log(`[initVectorStores] "${kb.name}" ready (${records.length} vectors, dim=${vectors[0]?.length ?? 0})`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`[initVectorStores] Failed to embed "${kb.name}":`, message);
+      throw new Error(`Failed to initialize knowledge base "${kb.name}": ${message}`);
+    }
+  }
+  return stores;
+}
+async function searchVectorStore(store, query, embeddings) {
+  const topK = store.kb.topK ?? 3;
+  const queryVector = await embeddings.embedQuery(query);
+  const scored = store.records.map((record) => ({
+    text: record.text,
+    score: cosineSimilarity(queryVector, record.vector)
+  }));
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, topK).map((item) => item.text);
+}
+function buildKnowledgeTools(stores, embeddings) {
+  return stores.map((store) => new DynamicTool({
+    name: store.kb.name,
+    description: store.kb.description,
+    func: async (query) => {
+      try {
+        const results = await searchVectorStore(store, query, embeddings);
+        if (results.length === 0) {
+          return "No relevant information found.";
+        }
+        return results.join("\n\n---\n\n");
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[buildKnowledgeTools] Search failed for "${store.kb.name}":`, message);
+        return `Search failed: ${message}`;
+      }
+    }
+  }));
+}
 
 // src/agent.ts
 var Agent = class {
   /** @internal */
   options;
+  /** RAG 知识库转换而来的 DynamicTool 列表 */
+  knowledgeTools = [];
+  /** 异步初始化 Promise（向量化知识库等） */
+  readyPromise;
   constructor(options) {
     this.options = {
       maxMessages: 50,
@@ -414,6 +488,26 @@ var Agent = class {
       ...options
     };
     this.validate();
+    this.readyPromise = this.init();
+  }
+  /**
+   * 异步初始化 — 向量化知识库并构建检索 Tool。
+   *
+   * 在构造函数中启动，chat() 首次调用时 await 确保完成。
+   * 若无 knowledgeBases，立即 resolve。
+   */
+  async init() {
+    const { knowledgeBases, embeddings } = this.options;
+    if (!knowledgeBases?.length || !embeddings) return;
+    try {
+      const stores = await initVectorStores(knowledgeBases, embeddings);
+      this.knowledgeTools = buildKnowledgeTools(stores, embeddings);
+      console.log(`[Agent] ${this.knowledgeTools.length} knowledge tool(s) ready`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error("[Agent] Knowledge base initialization failed:", message);
+      throw error;
+    }
   }
   /**
    * 发起对话，返回标准化 SSE 事件的异步生成器。
@@ -431,6 +525,7 @@ var Agent = class {
    */
   async *chat(chatOptions) {
     try {
+      await this.readyPromise;
       if (!chatOptions.message) {
         yield { type: "error", message: "message is required" };
         yield { type: "done" };
@@ -443,7 +538,11 @@ var Agent = class {
       }
       const scene = this.options.scene;
       const activeToolkits = scene ? this.options.toolkits.filter((tk) => scene.toolkits.includes(tk.name)) : this.options.toolkits;
-      const tools = activeToolkits.flatMap((tk) => tk.tools);
+      const tools = [
+        ...activeToolkits.flatMap((tk) => tk.tools),
+        ...this.knowledgeTools
+        // RAG 知识库 Tool 注入
+      ];
       const toolkitPrompts = activeToolkits.map((tk) => tk.prompt);
       const isMultiAgent = this.options.agents.length > 1 && !!this.options.supervisor;
       let stream;
@@ -546,12 +645,15 @@ ${err.stack}` : ""}` : String(err);
         }
       }
     }
+    if (this.options.knowledgeBases?.length && !this.options.embeddings) {
+      throw new Error("embeddings is required when knowledgeBases is provided");
+    }
   }
 };
 function createAgent2(options) {
   return new Agent(options);
 }
 
-export { Agent, buildPromptChain, buildSingleGraph, buildSupervisorGraph, createAgent2 as createAgent, createExpressHandler, defineProfile, defineScene, defineToolKit, formatSSE, transformStream };
+export { Agent, buildPromptChain, buildSingleGraph, buildSupervisorGraph, createAgent2 as createAgent, createExpressHandler, defineKnowledgeBase, defineProfile, defineScene, defineToolKit, formatSSE, transformStream };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map