wtfai 1.5.1 → 1.5.3

package/README.md

@@ -33,13 +33,7 @@ const client = new Wtfai({
 // 2. 创建会话
 const session = client.createSession('workflow-id')
 
-// 3. 监听状态变化
-session.on('stateChange', (state) => {
-  console.log('消息列表:', state.messages)
-  console.log('是否执行中:', state.isExecuting)
-})
-
-// 4. 发送消息
+// 3. 发送消息
 await session.send({ content: '你好' })
 ```
 
@@ -105,12 +99,33 @@ const session = client.createSession('workflow-id', {
 
 ##### `on(event, listener)`
 
-监听事件。
+监听事件。事件语义与后端 SSE 推送保持一致（见 `docs/sse-event-protocol.md`）。
+
+**事件说明与常见用法**
+
+- `start`：工作流开始执行。会返回后端确认的 `threadId`；`title` 仅在新会话时返回（默认为工作流名）。
+  - 常见用法：首次拿到 `threadId` 后持久化，便于恢复会话。
+- `nodeStart`：某个节点开始执行（排除了 LangGraph 内置的 `__start__/__end__`）。
+  - 常见用法：在 UI 上标记「当前节点」，或显示步骤进度。
+- `nodeEnd`：某个节点执行结束，可能包含 `variables` 和/或 `messages`。
+  - 常见用法：更新节点级结果或收集中间产物。
+  - 注意：后端当前只透传 billing 相关变量；`brain/loop` 节点的消息已在流式 token 中渲染，这里会省略以避免重复。
+- `token`：LLM 流式 token。`isReasoning` 表示推理内容（例如 DeepSeek 的 reasoning_content）。
+  - 常见用法：实现打字机效果；区分显示「推理」与「最终输出」。
+- `loading`：仅在 Loading 节点触发，`message` 为配置的提示语（纯字符串）。
+  - 常见用法：展示阶段性加载提示。
+- `title`：异步生成的会话标题（仅新会话）。通常在 `start` 之后稍晚到达。
+  - 常见用法：更新会话列表标题/面包屑。
+- `complete`：本次执行成功结束。
+  - 常见用法：停止输入框 loading、允许再次发送。
+- `error`：执行出错时触发（错误时不会再触发 `complete`）。
+  - 常见用法：toast 提示、错误上报、兜底 UI。
 
 ```typescript
 session.on('start', ({ threadId, title }) => {
-  // 工作流开始执行，获取到 threadId
-  // title 只有新会话才会有（默认为工作流名称），追问会话不会返回
+  // 工作流开始执行，获取到后端确认的 threadId
+  // title 只有新会话才会有（默认为工作流名称）
+  // 建议持久化 threadId，便于恢复会话
 })
 
 session.on('nodeStart', ({ nodeId }) => {
@@ -119,14 +134,17 @@ session.on('nodeStart', ({ nodeId }) => {
 
 session.on('nodeEnd', ({ nodeId, variables, messages }) => {
   // 节点执行结束
+  // variables: 目前只包含 billing 相关变量
+  // messages: brain/loop 节点通常已在 token 中渲染，可能为空
 })
 
 session.on('token', ({ nodeId, content, isReasoning }) => {
   // 收到流式 token（用于打字机效果）
+  // isReasoning 为 true 时表示推理内容
 })
 
 session.on('loading', ({ nodeId, message }) => {
-  // 收到 loading 事件，用于更新加载状态
+  // Loading 节点的提示语（纯字符串）
   console.log('Loading:', message)
 })
 
@@ -136,22 +154,22 @@ session.on('title', ({ title }) => {
 })
 
 session.on('complete', () => {
-  // 工作流执行完成
+  // 工作流执行完成（成功）
 })
 
 session.on('error', ({ message }) => {
   // 发生错误
 })
 
-session.on('stateChange', (state) => {
-  // 状态变化（推荐使用此事件更新 UI）
-  // state.messages: SimpleMessage[]
-  // state.isExecuting: boolean
-  // state.threadId?: string
-  // state.currentNodeId?: string
-})
 ```
 
+**最佳实践（推荐组合）**
+
+1. **打字机效果**：使用 `token` 拼接流式内容。
+2. **消息列表**：优先由 `token` 推进 AI 回复；`nodeEnd` 仅用于补齐非 brain/loop 节点的消息。
+3. **加载状态**：`loading` 展示阶段性提示，`complete/error` 关闭 loading 并解锁输入。
+4. **会话管理**：在 `start` 保存 `threadId`，`title` 更新会话标题。
+
 ##### `off(event, listener)`
 
 移除事件监听。
@@ -235,7 +253,16 @@ const session = client.createSession('workflow-id', {
   threadId: 'existing-thread-id',
 })
 await session.restore()
-// 会触发 stateChange 事件，包含历史消息
+// 会将历史消息写入 state，可通过 getState 获取
+```
+
+##### `updateSessionTitle(title: string)`
+
+更新会话标题（手动修改）。
+
+```typescript
+await session.updateSessionTitle('新的会话标题')
+// 会更新服务端变量，并触发 title 事件
 ```
 
 ##### `getState()`
@@ -256,6 +283,18 @@ console.log(state.isExecuting)
 session.abort()
 ```
 
+##### `dispose()`
+
+释放会话资源：移除所有事件监听并中止执行，同时清空会话内部状态。被释放的 session 不可再使用。
+
+```typescript
+session.dispose()
+```
+
+**说明**：
+- `abort()` 仅用于中断当前执行（比如用户点击停止生成）
+- `dispose()` 用于彻底清理会话（组件卸载、切换会话时），调用后不可再复用该 session
+
 ##### `setWorkflowVariables(values)`
 
 更新服务端会话变量。
@@ -511,6 +550,7 @@ function ChatComponent({ workflowId }: { workflowId: string }) {
   const [isExecuting, setIsExecuting] = useState(false)
   const [input, setInput] = useState('')
   const sessionRef = useRef<WorkflowSession | null>(null)
+  const streamingIndexRef = useRef<number | null>(null)
 
   useEffect(() => {
     return () => {
@@ -524,22 +564,54 @@ function ChatComponent({ workflowId }: { workflowId: string }) {
     const session = client.createSession(workflowId)
     sessionRef.current = session
 
-    session.on('stateChange', (state) => {
-      setMessages([...state.messages])
-      setIsExecuting(state.isExecuting)
+    session.on('token', ({ content }) => {
+      setMessages((prev) => {
+        const next = [...prev]
+        if (streamingIndexRef.current === null) {
+          streamingIndexRef.current = next.length
+          next.push({
+            type: 'ai',
+            parts: [{ type: 'text', text: content }],
+          })
+          return next
+        }
+
+        const index = streamingIndexRef.current
+        const msg = next[index]
+        const firstPart = msg?.parts?.[0]
+        if (msg && firstPart?.type === 'text') {
+          const updatedParts = [...msg.parts]
+          updatedParts[0] = {
+            ...firstPart,
+            text: firstPart.text + content,
+          }
+          next[index] = { ...msg, parts: updatedParts }
+        }
+        return next
+      })
+    })
+
+    session.on('complete', () => {
+      setIsExecuting(false)
+      streamingIndexRef.current = null
     })
 
     session.on('error', ({ message }) => {
       alert(`错误: ${message}`)
+      setIsExecuting(false)
+      streamingIndexRef.current = null
     })
 
     try {
+      setIsExecuting(true)
       await session.send({
         parts: [{ type: 'text', text: input }]
       })
       setInput('')
     } catch (error) {
       console.error(error)
+      setIsExecuting(false)
+      streamingIndexRef.current = null
     }
   }
 
@@ -548,7 +620,7 @@ function ChatComponent({ workflowId }: { workflowId: string }) {
       <div className="messages">
         {messages.map((msg, i) => (
           <div key={i} className={msg.type}>
-            {typeof msg.content === 'string' ? msg.content : '...'}
+            {msg.parts.find((part) => part.type === 'text')?.text || '...'}
           </div>
         ))}
         {isExecuting && <div>思考中...</div>}

package/dist/client.d.ts

@@ -22,11 +22,6 @@ import { UploadService } from './upload';
  * // 创建会话
  * const session = client.createSession('workflow-id')
  *
- * // 监听状态变化
- * session.on('stateChange', (state) => {
- *   console.log('Messages:', state.messages)
- * })
- *
  * // 发送消息
  * await session.send({ parts: [{ type: 'text', text: '你好' }] })
  * ```

package/dist/session.d.ts

@@ -13,6 +13,7 @@ export declare class WorkflowSession {
     private state;
     private listeners;
     private abortController?;
+    private disposed;
     constructor(workflowId: string, baseUrl: string, uploadService: UploadService, headers?: Record<string, string>, options?: SessionOptions);
     private iframeMethods;
     /**
@@ -47,7 +48,7 @@ export declare class WorkflowSession {
      */
     private emit;
     /**
-     * 更新状态并触发 stateChange 事件
+     * 更新会话状态
      */
     private updateState;
     /**
@@ -58,15 +59,17 @@ export declare class WorkflowSession {
      * 恢复历史会话
      */
     restore(): Promise<void>;
-    /**
-     * 获取工作流变量
-     */
     getWorkflowVariables(): Promise<Record<string, any>>;
     /**
      * 更新会话状态（服务端变量）
      * @param values 需要更新的变量键值对
      */
     setWorkflowVariables(values: Record<string, unknown>): Promise<void>;
+    /**
+     * 更新会话标题
+     * @param title 新的标题
+     */
+    updateSessionTitle(title: string): Promise<void>;
     /**
      * 执行指定的工作流（临时/嵌套执行）
      * 不会影响当前会话的状态（messages 等）
@@ -98,4 +101,12 @@ export declare class WorkflowSession {
      * 中止执行
      */
     abort(): void;
+    /**
+     * 释放会话资源（移除监听并中止执行）
+     */
+    dispose(): void;
+    /**
+     * 确保会话未被释放
+     */
+    private assertNotDisposed;
 }

package/dist/session.js

@@ -12,6 +12,7 @@ function _define_property(obj, key, value) {
 }
 class WorkflowSession {
     registerIframeMethods(methods) {
+        this.assertNotDisposed();
         this.iframeMethods = {
             ...this.iframeMethods,
             ...methods
@@ -19,9 +20,11 @@ class WorkflowSession {
         return this;
     }
     getIframeMethods() {
+        this.assertNotDisposed();
         return this.iframeMethods;
     }
     async uploadFileFromIframe(options) {
+        this.assertNotDisposed();
         const { base64, filename, mimeType, resourceType = 'conversation' } = options;
         const byteString = atob(base64);
         const arrayBuffer = new ArrayBuffer(byteString.length);
@@ -47,16 +50,19 @@ class WorkflowSession {
         });
     }
     on(event, listener) {
+        this.assertNotDisposed();
         if (!this.listeners.has(event)) this.listeners.set(event, new Set());
         this.listeners.get(event).add(listener);
         return this;
     }
     off(event, listener) {
         var _this_listeners_get;
+        this.assertNotDisposed();
         null == (_this_listeners_get = this.listeners.get(event)) || _this_listeners_get.delete(listener);
         return this;
     }
     emit(event, ...args) {
+        if (this.disposed) return;
         const listeners = this.listeners.get(event);
         if (listeners) Array.from(listeners).forEach((listener)=>{
             listener(...args);
@@ -67,27 +73,29 @@ class WorkflowSession {
             ...this.state,
             ...updates
         };
-        this.emit('stateChange', {
-            ...this.state
-        });
     }
     getState() {
+        this.assertNotDisposed();
         return {
             ...this.state
         };
     }
     async restore() {
+        this.assertNotDisposed();
         if (!this.state.threadId) throw new Error('无法恢复会话：未提供 threadId');
         const response = await fetch(`${this.baseUrl}/workflows/${this.workflowId}/state?threadId=${this.state.threadId}`, {
             headers: this.headers
         });
         if (!response.ok) throw new Error('获取工作流状态失败');
         const data = await response.json();
+        const variables = data.variables || {};
         this.updateState({
-            messages: data.messages
+            messages: data.messages,
+            title: variables.conversationTitle
         });
     }
     async getWorkflowVariables() {
+        this.assertNotDisposed();
         if (!this.state.threadId) throw new Error('No active session (missing threadId)');
         const response = await fetch(`${this.baseUrl}/workflows/${this.workflowId}/state?threadId=${this.state.threadId}`, {
             headers: this.headers
@@ -97,7 +105,8 @@ class WorkflowSession {
         return data.variables || {};
     }
     async setWorkflowVariables(values) {
-        if (!this.state.threadId || this.state.threadId.startsWith('tmp_')) throw new Error('No active session (missing valid threadId)');
+        this.assertNotDisposed();
+        if (!this.state.threadId) throw new Error('No active session (missing valid threadId)');
         const response = await fetch(`${this.baseUrl}/workflows/${this.workflowId}/variables`, {
             method: 'POST',
             headers: {
@@ -111,7 +120,43 @@ class WorkflowSession {
         });
         if (!response.ok) throw new Error('Failed to update state');
     }
+    async updateSessionTitle(title) {
+        this.assertNotDisposed();
+        if (!this.state.threadId) throw new Error('No active session (missing valid threadId)');
+        const executionInput = {
+            messages: [],
+            variables: {
+                conversationTitle: title
+            }
+        };
+        return new Promise((resolve, reject)=>{
+            executeWorkflowSSE(`${this.baseUrl}/workflows/${this.workflowId}/execute`, {
+                input: executionInput,
+                threadId: this.state.threadId,
+                mode: 'title_update'
+            }, {
+                onTitle: (data)=>{
+                    this.updateState({
+                        title: data.ti
+                    });
+                    this.emit('title', {
+                        title: data.ti
+                    });
+                },
+                onComplete: ()=>{
+                    this.updateState({
+                        title
+                    });
+                    resolve();
+                },
+                onError: (err)=>{
+                    reject(new Error(err.message));
+                }
+            }, this.headers).catch(reject);
+        });
+    }
     async executeWorkflow(workflowId, input) {
+        this.assertNotDisposed();
         const { parts: inputParts, ...rest } = input;
         const parts = [];
         for (const part of inputParts)switch(part.type){
@@ -190,6 +235,7 @@ class WorkflowSession {
         });
     }
     async send({ parts: inputParts, ...rest }) {
+        this.assertNotDisposed();
         if (this.state.isExecuting) throw new Error('工作流正在执行中');
         this.updateState({
             isExecuting: true,
@@ -271,6 +317,9 @@ class WorkflowSession {
                     this.updateState({
                         threadId: data.t
                     });
+                    if (data.ti) this.updateState({
+                        title: data.ti
+                    });
                     this.emit('start', {
                         threadId: data.t,
                         ...data.ti && {
@@ -346,6 +395,9 @@ class WorkflowSession {
                     });
                 },
                 onTitle: (data)=>{
+                    this.updateState({
+                        title: data.ti
+                    });
                     this.emit('title', {
                         title: data.ti
                     });
@@ -431,6 +483,7 @@ class WorkflowSession {
         throw new Error('Document part must have either file or url');
     }
     abort() {
+        if (this.disposed) return;
         if (this.abortController) {
             this.abortController.abort();
             this.updateState({
@@ -439,6 +492,21 @@ class WorkflowSession {
             });
         }
     }
+    dispose() {
+        if (this.disposed) return;
+        this.disposed = true;
+        this.abort();
+        this.listeners.clear();
+        this.iframeMethods = {};
+        this.abortController = void 0;
+        this.state = {
+            messages: [],
+            isExecuting: false
+        };
+    }
+    assertNotDisposed() {
+        if (this.disposed) throw new Error('Session has been disposed');
+    }
     constructor(workflowId, baseUrl, uploadService, headers = {}, options = {}){
         _define_property(this, "workflowId", void 0);
         _define_property(this, "baseUrl", void 0);
@@ -447,6 +515,7 @@ class WorkflowSession {
         _define_property(this, "state", void 0);
         _define_property(this, "listeners", void 0);
         _define_property(this, "abortController", void 0);
+        _define_property(this, "disposed", void 0);
         _define_property(this, "iframeMethods", void 0);
         this.workflowId = workflowId;
         this.baseUrl = baseUrl;
@@ -457,6 +526,7 @@ class WorkflowSession {
             isExecuting: false
         };
         this.listeners = new Map();
+        this.disposed = false;
         this.iframeMethods = {};
         if (options.threadId) this.state.threadId = options.threadId;
         else this.state.threadId = v7();

package/dist/types.d.ts

@@ -122,7 +122,7 @@ export interface UploadCredentials {
 /**
  * 会话事件类型
  */
-export type SessionEventType = 'start' | 'nodeStart' | 'nodeEnd' | 'token' | 'loading' | 'complete' | 'error' | 'stateChange';
+export type SessionEventType = 'start' | 'nodeStart' | 'nodeEnd' | 'token' | 'loading' | 'complete' | 'error';
 /**
  * 会话事件监听器类型映射
  */
@@ -155,7 +155,6 @@ export interface SessionEventListeners {
     error: (error: {
         message: string;
     }) => void;
-    stateChange: (state: SessionState) => void;
 }
 /**
  * 会话状态
@@ -169,6 +168,8 @@ export interface SessionState {
     isExecuting: boolean;
     /** 当前执行节点 ID */
     currentNodeId?: string;
+    /** 会话标题 */
+    title?: string;
 }
 /**
  * 工作流基本信息

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wtfai",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "type": "module",
   "exports": {
     ".": {
@@ -16,23 +16,23 @@
     "@eslint/js": "^9.39.2",
     "@rsbuild/plugin-react": "^1.4.3",
     "@rslib/core": "^0.19.3",
-    "@types/react": "^19.2.9",
+    "@types/react": "^19.2.10",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
-    "globals": "^17.1.0",
+    "globals": "^17.2.0",
     "prettier": "^3.8.1",
-    "react": "^19.2.3",
+    "react": "^19.2.4",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.53.1"
+    "typescript-eslint": "^8.54.0"
   },
   "peerDependencies": {
     "react": ">=16.9.0",
     "react-dom": ">=16.9.0"
   },
   "dependencies": {
-    "@ant-design/x": "^2.1.3",
-    "@ant-design/x-markdown": "^2.1.3",
+    "@ant-design/x": "^2.2.0",
+    "@ant-design/x-markdown": "^2.2.0",
     "@microsoft/fetch-event-source": "^2.0.1",
     "clsx": "^2.1.1",
     "compressorjs": "^1.2.1",