@langgraph-js/sdk 1.1.5 → 1.1.8

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,27 @@
 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";
+
+/**
+ * @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 +36,30 @@ 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)) {
+        return content.map((item: any) => {
+            if (item.type === "text") {
+                return item.text;
+            }
+        });
+    } else if (typeof content === "string") {
+        return content;
+    } else {
+        return "";
+    }
+};
+
+/**
+ * @zh 创建一个用于聊天界面的状态管理器 (store)。
+ * @en Creates a state manager (store) for the chat interface.
+ */
 export const createChatStore = (
     initClientName: string,
     config: LangGraphClientConfig,
@@ -39,12 +77,16 @@ export const createChatStore = (
     const currentAgent = atom<string>(initClientName);
     const currentChatId = atom<string | null>(null);
 
-    const initClient = async () => {
+    /**
+     * @zh 初始化 LangGraph 客户端。
+     * @en Initializes the LangGraph client.
+     */
+    async function initClient() {
         const newClient = new LangGraphClient(config);
         await newClient.initAssistant(currentAgent.get());
         // 不再需要创建，sendMessage 会自动创建
         // await newClient.createThread();
-
+        inChatError.set(null);
         newClient.onStreamingUpdate((event) => {
             if (event.type === "thread" || event.type === "done") {
                 // console.log(event.data);
@@ -53,17 +95,20 @@ 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);
         });
         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;
 
@@ -76,21 +121,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 || []);
@@ -99,6 +162,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]);
@@ -125,18 +192,35 @@ 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();
                 });
             },
+            /**
+             * @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[];
@@ -144,6 +228,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/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>

package/ui/index.ts

@@ -1,182 +0,0 @@
-import { LangGraphClient, RenderMessage } from "../src/LangGraphClient";
-/** @ts-ignore */
-import testResponse from "../test/testResponse.json?raw";
-import { createTools } from "./tool";
-const main = async () => {
-    const client = new LangGraphClient({
-        defaultHeaders: {},
-    });
-
-    await client.initAssistant("agent");
-    await client.createThread();
-    client.onStreamingUpdate((event) => {
-        updateMessages(client.renderMessage);
-    });
-    client.tools.bindTools(createTools());
-    const messages = await client.sendMessage("你有什么工具", {
-        _debug: {
-            // streamResponse: JSON.parse(testResponse),
-        },
-    });
-    console.log(client.graphMessages);
-    console.log(client.renderMessage);
-    console.log(client.tokenCounter);
-};
-
-// 声明全局类型
-declare global {
-    interface Window {
-        main: () => Promise<void>;
-    }
-}
-
-window.main = main;
-// main();
-
-function getMessageType(message: RenderMessage): string {
-    if ("type" in message) {
-        return message.type;
-    }
-    return "unknown";
-}
-
-function renderMessage(message: RenderMessage) {
-    const messageDiv = document.createElement("div");
-    const messageType = getMessageType(message);
-    messageDiv.className = `message ${messageType}`;
-
-    const contentDiv = document.createElement("div");
-    contentDiv.className = "message-content";
-
-    const messageContent = `
-        <div class="message-header">
-            <span class="message-role">${getRoleName(messageType)} </span>
-            <span class="message-role">${
-                /** @ts-ignore */
-                message.name || ""
-            }</span>
-            ${renderTokenUsage(message.usage_metadata)}
-        </div>
-        <p class="message-body">
-        
-        <span>
-            ${message.tool_input || ""}
-        </span>
-        <span>
-            ${message.content}
-        </span>
-        </p>
-    `;
-
-    contentDiv.innerHTML = messageContent;
-    messageDiv.appendChild(contentDiv);
-    return messageDiv;
-}
-
-function getRoleName(type: string): string {
-    switch (type) {
-        case "human":
-            return "You";
-        case "ai":
-            return "AI Assistant";
-        case "system":
-            return "System";
-        default:
-            return type;
-    }
-}
-
-function renderTokenUsage(usage?: { input_tokens?: number; output_tokens?: number; total_tokens?: number }) {
-    if (!usage) return "";
-
-    return `
-        <div class="token-usage">
-            ${usage.input_tokens ? `<span class="token-count">Input: ${usage.input_tokens}</span>` : ""}
-            ${usage.output_tokens ? `<span class="token-count">Output: ${usage.output_tokens}</span>` : ""}
-            ${usage.total_tokens ? `<span class="token-count">Total: ${usage.total_tokens}</span>` : ""}
-        </div>
-    `;
-}
-
-function renderMessages(messages: RenderMessage[]) {
-    const container = document.createElement("div");
-    container.className = "messages-container";
-
-    messages.forEach((message) => {
-        container.appendChild(renderMessage(message));
-    });
-
-    return container;
-}
-
-export function updateMessages(messages: RenderMessage[]) {
-    const messageDiv = document.getElementById("message");
-    if (!messageDiv) return;
-
-    messageDiv.innerHTML = "";
-    messageDiv.appendChild(renderMessages(messages));
-}
-
-// 添加样式
-const style = document.createElement("style");
-style.textContent = `
-    .messages-container {
-        display: flex;
-        flex-direction: column;
-        gap: 1rem;
-        padding: 1rem;
-    }
-
-    .message {
-        max-width: 80%;
-        padding: 0.75rem;
-        border-radius: 0.5rem;
-    }
-
-    .message.human {
-        align-self: flex-end;
-        background-color: #e3f2fd;
-    }
-
-    .message.ai {
-        align-self: flex-start;
-        background-color: #f5f5f5;
-    }
-
-    .message.system {
-        align-self: center;
-        background-color: #fff3e0;
-        font-style: italic;
-    }
-
-    .message-header {
-        margin-bottom: 0.5rem;
-        font-size: 0.875rem;
-        color: #666;
-        display: flex;
-        justify-content: space-between;
-        align-items: center;
-    }
-
-    .message-role {
-        font-weight: 600;
-    }
-
-    .message-body {
-    }
-
-    .token-usage {
-        display: flex;
-        gap: 0.5rem;
-        font-size: 0.75rem;
-        color: #888;
-    }
-
-    .token-count {
-        background-color: rgba(0, 0, 0, 0.05);
-        padding: 0.125rem 0.375rem;
-        border-radius: 0.25rem;
-    }
-`;
-
-document.head.appendChild(style);

package/ui/tool.ts

@@ -1,55 +0,0 @@
-import { z } from "zod";
-import { createTool, createFETool } from "../src/tool/createTool";
-
-export function createTools() {
-    // 文件操作工具
-    const fileTool = createTool({
-        name: "file_operation",
-        description: "执行文件操作，包括读取和写入",
-        parameters: {
-            operation: z.enum(["read", "write"]).describe("操作类型：read-读取文件，write-写入文件"),
-            filePath: z.string().describe("文件的完整路径"),
-            content: z.string().optional().describe("写入文件时的内容，仅在 operation 为 write 时需要"),
-        },
-        async execute(args) {
-            return [{ type: "text", text: "执行文件操作" }];
-        },
-    });
-
-    // 用户交互工具
-    const userInteractionTool = createFETool({
-        name: "user_interaction",
-        description: "与用户进行交互，包括确认和输入",
-        parameters: [
-            {
-                name: "type",
-                type: "string",
-                description: "交互类型：confirm-确认，input-输入",
-            },
-            {
-                name: "message",
-                type: "string",
-                description: "向用户展示的信息",
-            },
-            {
-                name: "options",
-                type: "string[]",
-                description: "选项列表，仅在 type 为 confirm 时使用",
-                optional: true,
-            },
-        ],
-        handler: async (args) => {
-            return {
-                success: true,
-                data: {
-                    type: args.type,
-                    message: args.message,
-                    options: args.options || ["确认", "取消"],
-                },
-                message: "等待用户响应",
-            };
-        },
-    });
-
-    return [fileTool, userInteractionTool];
-}