@langgraph-js/sdk 1.1.6 → 1.1.9

package/src/SpendTime.ts

@@ -1,13 +1,30 @@
+/**
+ * @zh SpendTime 类用于计算和记录操作的耗时。
+ * @en The SpendTime class is used to calculate and record the time spent on operations.
+ */
 export class SpendTime {
     private timeCounter = new Map<string, [Date, Date] | [Date]>();
 
+    /**
+     * @zh 开始计时。
+     * @en Starts timing.
+     */
     start(key: string) {
         this.timeCounter.set(key, [new Date()]);
     }
 
+    /**
+     * @zh 结束计时。
+     * @en Ends timing.
+     */
     end(key: string) {
         this.timeCounter.set(key, [this.timeCounter.get(key)?.[0] || new Date(), new Date()]);
     }
+
+    /**
+     * @zh 设置或更新指定键的耗时记录。如果键已存在，则更新结束时间；否则，开始新的计时。
+     * @en Sets or updates the time spent record for the specified key. If the key already exists, updates the end time; otherwise, starts a new timing.
+     */
     setSpendTime(key: string) {
         if (this.timeCounter.has(key)) {
             this.end(key);
@@ -15,13 +32,27 @@ export class SpendTime {
             this.start(key);
         }
     }
+
+    /**
+     * @zh 获取指定键的开始时间。
+     * @en Gets the start time for the specified key.
+     */
     getStartTime(key: string) {
         return this.timeCounter.get(key)?.[0] || new Date();
     }
+
+    /**
+     * @zh 获取指定键的结束时间。
+     * @en Gets the end time for the specified key.
+     */
     getEndTime(key: string) {
         return this.timeCounter.get(key)?.[1] || new Date();
     }
 
+    /**
+     * @zh 获取指定键的耗时（毫秒）。
+     * @en Gets the time spent (in milliseconds) for the specified key.
+     */
     getSpendTime(key: string) {
         const [start, end = new Date()] = this.timeCounter.get(key) || [new Date(), new Date()];
         return end.getTime() - start.getTime();

package/src/ToolManager.ts

@@ -1,13 +1,17 @@
 import { ToolMessage } from "@langchain/langgraph-sdk";
-import { LangGraphClient } from "./LangGraphClient";
-import { CallToolResult, createJSONDefineTool, UnionTool } from "./tool/createTool";
+import { LangGraphClient } from "./LangGraphClient.js";
+import { CallToolResult, createJSONDefineTool, UnionTool } from "./tool/createTool.js";
 
+/**
+ * @zh ToolManager 类用于管理和执行工具。
+ * @en The ToolManager class is used to manage and execute tools.
+ */
 export class ToolManager {
     private tools: Map<string, UnionTool<any>> = new Map();
 
     /**
-     * 注册一个工具
-     * @param tool 要注册的工具
+     * @zh 注册一个工具。
+     * @en Registers a tool.
      */
     bindTool(tool: UnionTool<any>) {
         if (this.tools.has(tool.name)) {
@@ -17,45 +21,49 @@ export class ToolManager {
     }
 
     /**
-     * 注册多个工具
-     * @param tools 要注册的工具数组
+     * @zh 注册多个工具。
+     * @en Registers multiple tools.
      */
     bindTools(tools: UnionTool<any>[]) {
         tools.forEach((tool) => this.bindTool(tool));
     }
 
     /**
-     * 获取所有已注册的工具
-     * @returns 工具数组
+     * @zh 获取所有已注册的工具。
+     * @en Gets all registered tools.
      */
     getAllTools(): UnionTool<any>[] {
         return Array.from(this.tools.values());
     }
 
     /**
-     * 获取指定名称的工具
-     * @param name 工具名称
-     * @returns 工具实例或 undefined
+     * @zh 获取指定名称的工具。
+     * @en Gets the tool with the specified name.
      */
     getTool(name: string): UnionTool<any> | undefined {
         return this.tools.get(name);
     }
 
     /**
-     * 移除指定名称的工具
-     * @param name 工具名称
-     * @returns 是否成功移除
+     * @zh 移除指定名称的工具。
+     * @en Removes the tool with the specified name.
      */
     removeTool(name: string): boolean {
         return this.tools.delete(name);
     }
 
     /**
-     * 清空所有工具
+     * @zh 清空所有工具。
+     * @en Clears all tools.
      */
     clearTools() {
         this.tools.clear();
     }
+
+    /**
+     * @zh 调用指定名称的工具。
+     * @en Calls the tool with the specified name.
+     */
     async callTool(name: string, args: any, context: { client: LangGraphClient; message: ToolMessage }) {
         const tool = this.getTool(name);
         if (!tool) {
@@ -63,12 +71,22 @@ export class ToolManager {
         }
         return await tool.execute(args, context);
     }
+
+    /**
+     * @zh 将所有工具转换为 JSON 定义格式。
+     * @en Converts all tools to JSON definition format.
+     */
     toJSON() {
         return Array.from(this.tools.values()).map((i) => createJSONDefineTool(i));
     }
 
     // === 专门为前端设计的异步触发结构
     private waitingMap: Map<string, (value: CallToolResult) => void> = new Map();
+
+    /**
+     * @zh 标记指定 ID 的工具等待已完成，并传递结果。
+     * @en Marks the tool waiting with the specified ID as completed and passes the result.
+     */
     doneWaiting(id: string, value: CallToolResult) {
         if (this.waitingMap.has(id)) {
             this.waitingMap.get(id)!(value);
@@ -79,6 +97,11 @@ export class ToolManager {
             return false;
         }
     }
+
+    /**
+     * @zh 等待指定 ID 的工具完成。
+     * @en Waits for the tool with the specified ID to complete.
+     */
     waitForDone(id: string) {
         if (this.waitingMap.has(id)) {
             return this.waitingMap.get(id);
@@ -88,10 +111,10 @@ export class ToolManager {
         });
         return promise;
     }
-    /** 等待用户输入
-     * @example
-     * // 继续 chat 流
-     * client.tools.doneWaiting(message.id!, (e.target as any).value);
+
+    /**
+     * @zh 一个静态方法，用于在前端等待用户界面操作完成。
+     * @en A static method used in the frontend to wait for user interface operations to complete.
      */
     static waitForUIDone<T>(_: T, context: { client: LangGraphClient; message: ToolMessage }) {
         // console.log(context.message);

package/src/index.ts

@@ -1,5 +1,5 @@
-export * from "./LangGraphClient";
-export * from "./tool";
+export * from "./LangGraphClient.js";
+export * from "./tool/index.js";
 export * from "@langchain/langgraph-sdk";
-export * from "./ui-store";
-export * from "./ToolManager";
+export * from "./ui-store/index.js";
+export * from "./ToolManager.js";

package/src/tool/createTool.ts

@@ -1,6 +1,6 @@
-import { actionParametersToJsonSchema, convertJsonSchemaToZodRawShape } from "./utils";
+import { actionParametersToJsonSchema, convertJsonSchemaToZodRawShape } from "./utils.js";
 import { z, ZodRawShape, ZodTypeAny } from "zod";
-import { Action, Parameter } from "./copilotkit-actions";
+import { Action, Parameter } from "./copilotkit-actions.js";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { Message } from "@langchain/langgraph-sdk";
 

package/src/tool/index.ts

@@ -1,2 +1,2 @@
-export * from "./createTool";
-export * from "./copilotkit-actions";
+export * from "./createTool.js";
+export * from "./copilotkit-actions.js";

package/src/tool/utils.ts

@@ -5,7 +5,7 @@
  * MIT License
  */
 import { z, ZodRawShape } from "zod";
-import { Parameter } from "./copilotkit-actions";
+import { Parameter } from "./copilotkit-actions.js";
 
 export type JSONSchemaString = {
     type: "string";

package/src/ui-store/UnionStore.ts

@@ -1,8 +1,17 @@
-import { atom, PreinitializedWritableAtom, StoreValue } from "nanostores";
+import { PreinitializedWritableAtom, StoreValue } from "nanostores";
+
+/**
+ * @zh UnionStore 类型用于合并 store 的 data 和 mutations，使其可以直接访问。
+ * @en The UnionStore type is used to merge the data and mutations of a store, allowing direct access.
+ */
 export type UnionStore<T extends { data: Record<string, PreinitializedWritableAtom<any>>; mutations: Record<string, any> }> = {
     [k in keyof T["data"]]: StoreValue<T["data"][k]>;
 } & T["mutations"];
 
+/**
+ * @zh useUnionStore Hook 用于将 nanostores 的 store 结构转换为更易于在 UI 组件中使用的扁平结构。
+ * @en The useUnionStore Hook is used to transform the nanostores store structure into a flatter structure that is easier to use in UI components.
+ */
 export const useUnionStore = <T extends { data: Record<string, any>; mutations: Record<string, any> }>(
     store: T,
     useStore: (store: PreinitializedWritableAtom<any>) => StoreValue<T["data"][keyof T["data"]]>

package/src/ui-store/createChatStore.ts

@@ -1,13 +1,28 @@
 import { atom } from "nanostores";
-import { LangGraphClient, LangGraphClientConfig, RenderMessage, SendMessageOptions } from "../LangGraphClient";
+import { LangGraphClient, LangGraphClientConfig, RenderMessage, SendMessageOptions } from "../LangGraphClient.js";
 import { Message, Thread } from "@langchain/langgraph-sdk";
+import { rafDebounce } from "./rafDebounce.js";
+
+/**
+ * @zh 格式化日期对象为时间字符串。
+ * @en Formats a Date object into a time string.
+ */
 export const formatTime = (date: Date) => {
     return date.toLocaleTimeString("en-US");
 };
 
+/**
+ * @zh 格式化数字为带千位分隔符的字符串。
+ * @en Formats a number into a string with thousand separators.
+ */
 export const formatTokens = (tokens: number) => {
     return tokens.toLocaleString("en");
 };
+
+/**
+ * @zh 获取消息内容的文本表示，处理不同类型的消息内容。
+ * @en Gets the text representation of message content, handling different types of message content.
+ */
 export const getMessageContent = (content: any) => {
     if (typeof content === "string") return content;
     if (Array.isArray(content)) {
@@ -22,6 +37,11 @@ export const getMessageContent = (content: any) => {
     }
     return JSON.stringify(content);
 };
+
+/**
+ * @zh 获取历史记录中 Thread 内容的文本表示。
+ * @en Gets the text representation of Thread content in history.
+ */
 export const getHistoryContent = (thread: Thread) => {
     const content = (thread?.values as any)?.messages?.[0]?.content;
     if (content && Array.isArray(content)) {
@@ -36,6 +56,11 @@ export const getHistoryContent = (thread: Thread) => {
         return "";
     }
 };
+
+/**
+ * @zh 创建一个用于聊天界面的状态管理器 (store)。
+ * @en Creates a state manager (store) for the chat interface.
+ */
 export const createChatStore = (
     initClientName: string,
     config: LangGraphClientConfig,
@@ -53,12 +78,20 @@ export const createChatStore = (
     const currentAgent = atom<string>(initClientName);
     const currentChatId = atom<string | null>(null);
 
-    const initClient = async () => {
+    const updateUI = rafDebounce((newClient: LangGraphClient) => {
+        renderMessages.set(newClient.renderMessage);
+    });
+    /**
+     * @zh 初始化 LangGraph 客户端。
+     * @en Initializes the LangGraph client.
+     */
+    async function initClient() {
         const newClient = new LangGraphClient(config);
         await newClient.initAssistant(currentAgent.get());
+        currentAgent.set(newClient.getCurrentAssistant()!.graph_id);
         // 不再需要创建，sendMessage 会自动创建
         // await newClient.createThread();
-
+        inChatError.set(null);
         newClient.onStreamingUpdate((event) => {
             if (event.type === "thread" || event.type === "done") {
                 // console.log(event.data);
@@ -67,17 +100,21 @@ export const createChatStore = (
             }
             if (event.type === "error") {
                 loading.set(false);
-                inChatError.set(event.data?.message || "发生错误");
+                inChatError.set(event.data);
             }
             // console.log(newClient.renderMessage);
-            renderMessages.set(newClient.renderMessage);
+
+            updateUI(newClient);
         });
         context.onInit?.(newClient);
-        // newClient.tools.bindTools([fileTool, askUserTool]);
         newClient.graphState = {};
         client.set(newClient);
-    };
+    }
 
+    /**
+     * @zh 发送消息。
+     * @en Sends a message.
+     */
     const sendMessage = async (message?: Message[], extraData?: SendMessageOptions) => {
         if ((!userInput.get().trim() && !message?.length) || loading.get() || !client.get()) return;
 
@@ -90,21 +127,39 @@ export const createChatStore = (
         loading.set(false);
     };
 
+    /**
+     * @zh 停止当前的消息生成。
+     * @en Stops the current message generation.
+     */
     const stopGeneration = () => {
         client.get()?.cancelRun();
     };
 
+    /**
+     * @zh 切换工具消息的折叠状态。
+     * @en Toggles the collapsed state of a tool message.
+     */
     const toggleToolCollapse = (toolId: string) => {
         const prev = collapsedTools.get();
         collapsedTools.set(prev.includes(toolId) ? prev.filter((id) => id !== toolId) : [...prev, toolId]);
     };
 
+    /**
+     * @zh 切换历史记录面板的可见性。
+     * @en Toggles the visibility of the history panel.
+     */
     const toggleHistoryVisible = () => {
         showHistory.set(!showHistory.get());
     };
+
     const historyList = atom<Thread<{ messages: Message[] }>[]>([]);
+
+    /**
+     * @zh 刷新历史记录列表。
+     * @en Refreshes the history list.
+     */
     const refreshHistoryList = async () => {
-        if (!client.get()) return;
+        if (!client.get() || !showHistory.get()) return;
         try {
             const response = await client.get()?.listThreads<{ messages: Message[] }>();
             historyList.set(response || []);
@@ -113,6 +168,10 @@ export const createChatStore = (
         }
     };
 
+    /**
+     * @zh 将一个 Thread 添加到历史记录列表的开头。
+     * @en Adds a Thread to the beginning of the history list.
+     */
     const addToHistory = (thread: Thread<{ messages: Message[] }>) => {
         const prev = historyList.get();
         historyList.set([thread, ...prev]);
@@ -139,18 +198,37 @@ export const createChatStore = (
             toggleHistoryVisible,
             refreshHistoryList,
             addToHistory,
+            /**
+             * @zh 设置用户输入内容。
+             * @en Sets the user input content.
+             */
             setUserInput(input: string) {
                 userInput.set(input);
             },
+            /**
+             * @zh 设置当前的 Agent 并重新初始化客户端。
+             * @en Sets the current Agent and reinitializes the client.
+             */
             setCurrentAgent(agent: string) {
                 currentAgent.set(agent);
                 return initClient().then(() => {
-                    refreshHistoryList();
+                    if (showHistory.get()) {
+                        refreshHistoryList();
+                    }
                 });
             },
+            /**
+             * @zh 创建一个新的聊天会话。
+             * @en Creates a new chat session.
+             */
             createNewChat() {
                 client.get()?.reset();
+                inChatError.set(null);
             },
+            /**
+             * @zh 切换到指定的历史聊天会话。
+             * @en Switches to the specified historical chat session.
+             */
             toHistoryChat(
                 thread: Thread<{
                     messages: Message[];
@@ -158,6 +236,10 @@ export const createChatStore = (
             ) {
                 client.get()?.resetThread(thread.metadata?.graph_id as string, thread.thread_id);
             },
+            /**
+             * @zh 删除指定的历史聊天会话。
+             * @en Deletes the specified historical chat session.
+             */
             async deleteHistoryChat(thread: Thread<{ messages: Message[] }>) {
                 await client.get()?.threads.delete(thread.thread_id);
                 await refreshHistoryList();

package/src/ui-store/index.ts

@@ -1,2 +1,2 @@
-export * from "./createChatStore";
-export * from "./UnionStore";
+export * from "./createChatStore.js";
+export * from "./UnionStore.js";

package/src/ui-store/rafDebounce.ts

@@ -0,0 +1,29 @@
+/**
+ * Creates a debounced function that executes once per animation frame
+ * @param callback - The function to debounce
+ * @returns A function that executes the callback on the next animation frame
+ */
+export function rafDebounce<T extends (...args: any[]) => any>(callback: T): (...args: Parameters<T>) => void {
+    let rafId: number | null = null;
+    let lastArgs: Parameters<T> | null = null;
+
+    // Return the debounced function
+    return function (...args: Parameters<T>): void {
+        // Store the most recent arguments
+        lastArgs = args;
+
+        // Cancel any pending animation frame
+        if (rafId !== null) {
+            cancelAnimationFrame(rafId);
+        }
+
+        // Schedule execution on the next animation frame
+        rafId = requestAnimationFrame(() => {
+            if (lastArgs !== null) {
+                callback(...lastArgs);
+                lastArgs = null;
+            }
+            rafId = null;
+        });
+    };
+}

package/tsconfig.json

@@ -25,9 +25,9 @@
         // "moduleDetection": "auto",                        /* Control what method is used to detect module-format JS files. */
 
         /* Modules */
-        "module": "ESNext" /* Specify what module code is generated. */,
+        "module": "NodeNext" /* Specify what module code is generated. */,
         // "rootDir": "./",                                  /* Specify the root folder within your source files. */
-        "moduleResolution": "node10" /* Specify how TypeScript looks up a file from a given module specifier. */,
+        "moduleResolution": "nodenext" /* Specify how TypeScript looks up a file from a given module specifier. */,
         // "baseUrl": "./",                                  /* Specify the base directory to resolve non-relative module names. */
         // "paths": {},                                      /* Specify a set of entries that re-map imports to additional lookup locations. */
         // "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */

package/index.html

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-    <head>
-        <meta charset="UTF-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <title>Document</title>
-    </head>
-    <body>
-        <div id="message"></div>
-    </body>
-    <script type="module" src="/ui/index.ts"></script>
-</html>