wtfai 1.5.7 → 1.6.0

package/README.md

@@ -34,7 +34,7 @@ const client = new Wtfai({
 const session = client.createSession('workflow-id')
 
 // 3. 发送消息
-await session.send({ content: '你好' })
+await session.send({ parts: [{ type: 'text', text: '你好' }] })
 ```
 
 ## API 文档
@@ -161,8 +161,64 @@ session.on('error', ({ message }) => {
   // 发生错误
 })
 
+session.on('contentAction', ({ type, payload }) => {
+  // 内容区域（如 Markdown）触发的自定义动作
+  if (type === 'workflow') {
+    const { workflowId, params } = payload
+    console.log('跳转工作流:', workflowId, '参数:', params)
+  }
+})
 ```
 
+**Markdown 交互 (自定义协议)**
+
+SDK 的 Markdown 组件支持通过特殊协议触发 `contentAction` 事件，方便在内容中嵌入交互按钮或链接：
+
+- **跳转工作流**：使用 `workflow:` 协议。
+  格式：`[文字](workflow:工作流ID?参数1=值1&参数2=值2)`
+  示例：`[查看详情](workflow:cm0p1234?from=chat)`
+
+当用户点击此类链接时，SDK 不会执行页面跳转，而是触发 `contentAction` 事件，由宿主应用决定如何处理（如切换侧边栏、打开弹窗等）。
+
+---
+
+### 结构化内容处理 (WorkflowRegistry)
+
+为了在聊天内容中更美观地展示工作流引用，SDK 提供了 `<workflow>` 自定义标签和全局注册机制。
+
+#### 1. 全局注册工作流信息
+
+在应用顶层（或页面容器层）使用 `WorkflowRegistry` 注入工作流的展示名称和图标：
+
+```tsx
+import { WorkflowRegistry } from 'wtfai';
+import { RobotOutlined } from '@ant-design/icons';
+
+const MY_WORKFLOWS = {
+  'wf_week_report': { 
+    name: '自动化周报', 
+    icon: <RobotOutlined /> 
+  },
+};
+
+// 在容器层包裹一次即可
+<WorkflowRegistry mapping={MY_WORKFLOWS}>
+   <App />
+</WorkflowRegistry>
+```
+
+#### 2. 在 Markdown 中使用
+
+通过自定义标签 `<workflow id="xxx" />` 引用工作流：
+
+- **基本用法**：`<workflow id="wf_week_report" />`
+- **自定义文字**：`<workflow id="wf_week_report">立即查看</workflow>`
+
+**渲染效果**：
+SDK 会自动将其渲染为一个美观的“药丸状”卡片按钮，包含图标和名称。如果 `WorkflowRegistry` 中没有匹配到 ID，则会降级显示标签内容或 ID。
+
+点击该卡片会触发 `contentAction` 事件，`type` 为 `'workflow'`。
+
 **最佳实践（推荐组合）**
 
 1. **打字机效果**：使用 `token` 拼接流式内容。
@@ -442,6 +498,128 @@ const url = await IframeBridge.uploadFile(file, {
 
 ---
 
+### Session Data CRUD API
+
+用于会话级数据的持久化存储，与 `saveData/loadData` 不同，这是一套完整的 CRUD 接口，支持集合（Collection）概念，适合存储结构化数据。
+
+> **与 saveData/loadData 的区别**：
+> - `saveData/loadData` 存储在工作流 state 中（适合简单 key-value）
+> - Session Data API 存储在独立数据表中（适合结构化数据、列表数据）
+
+#### `IframeBridge.createRecord(collection, data)`
+
+在指定集合中创建一条记录。
+
+```javascript
+const id = await IframeBridge.createRecord('notes', {
+  title: 'My Note',
+  content: 'Hello World',
+  createdAt: Date.now()
+});
+console.log('创建成功, ID:', id);
+```
+
+#### `IframeBridge.getRecord(collection, id)`
+
+获取单条记录。
+
+```javascript
+const data = await IframeBridge.getRecord('notes', id);
+if (data) {
+  console.log('记录内容:', data.title, data.content);
+} else {
+  console.log('记录不存在');
+}
+```
+
+#### `IframeBridge.updateRecord(collection, id, data)`
+
+更新记录（完整替换）。
+
+```javascript
+await IframeBridge.updateRecord('notes', id, {
+  title: 'Updated Title',
+  content: 'New content',
+  updatedAt: Date.now()
+});
+```
+
+#### `IframeBridge.deleteRecord(collection, id)`
+
+删除单条记录。
+
+```javascript
+await IframeBridge.deleteRecord('notes', id);
+```
+
+#### `IframeBridge.listRecords(collection, options?)`
+
+分页查询集合中的记录。
+
+```javascript
+const result = await IframeBridge.listRecords('notes', {
+  page: 1,
+  pageSize: 10
+});
+console.log(`共 ${result.total} 条记录`);
+result.records.forEach(r => {
+  console.log(r.id, r.data.title);
+});
+```
+
+#### `IframeBridge.clearCollection(collection)`
+
+清空集合中的所有记录。
+
+```javascript
+const count = await IframeBridge.clearCollection('notes');
+console.log(`已删除 ${count} 条记录`);
+```
+
+**使用场景**：
+- 待办事项列表
+- 用户收藏/历史记录
+- 表单草稿
+- 游戏存档
+
+---
+
+## HTTP API
+
+以下 API 可直接通过 HTTP 调用，无需使用 SDK。
+
+### 中断工作流执行
+
+中断正在运行的工作流。工作流会返回 `error` 事件携带中断原因后关闭连接。
+
+**请求**
+
+```http
+POST /workflows/:workflowId/interrupt
+Content-Type: application/json
+
+{
+  "threadId": "会话ID",
+  "reason": "中断原因"
+}
+```
+
+**响应**
+
+```json
+{
+  "success": true,
+  "local": true  // true=本地实例中断, false=通过集群广播
+}
+```
+
+**说明**：
+- 支持集群模式，会通过 Redis Pub/Sub 广播中断信号到所有实例
+- 工作流被中断后会触发 `error` 事件，`message` 为传入的 `reason`
+- 如果找不到对应的执行会话，返回 404
+
+---
+
 ### UploadService
 
 文件上传服务（通过 `client.upload` 访问）。

package/dist/iframe-bridge.js

@@ -97,6 +97,7 @@ class IframeBridgeHost {
             'executeWorkflow',
             'uploadFile',
             'updateSessionTitle',
+            'getSessionId',
             'createRecord',
             'getRecord',
             'updateRecord',

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { Wtfai } from './client';
 export default Wtfai;
 export { WorkflowSession } from './session';
 export { UploadService } from './upload';
-export type { ClientConfig, SessionOptions, SessionState, SessionEventListeners, SendInput, UploadParams, UploadImageParams, CompressOptions, WorkflowInfo, ContentPart, } from './types';
+export type { ClientConfig, SessionOptions, SessionState, SessionEventListeners, SendInput, UploadParams, UploadImageParams, CompressOptions, WorkflowInfo, ContentPart, ContentAction, } from './types';
 export type { SimpleMessage, Workflow, WorkflowConfig, } from '@our-llm/shared/types';
-export { Markdown, type MarkdownProps } from './ui/markdown';
+export { Markdown, type MarkdownProps, WorkflowRegistry } from './ui/markdown';
+export type { WorkflowInfoMapping } from './ui/context';

package/dist/index.js

@@ -1,6 +1,6 @@
 import { Wtfai } from "./client.js";
 import { WorkflowSession } from "./session.js";
 import { UploadService } from "./upload.js";
-import { Markdown } from "./ui/markdown.js";
+import { Markdown, WorkflowRegistry } from "./ui/markdown.js";
 const src = Wtfai;
-export { Markdown, UploadService, WorkflowSession, src as default };
+export { Markdown, UploadService, WorkflowRegistry, WorkflowSession, src as default };

package/dist/session.d.ts

@@ -44,8 +44,13 @@ export declare class WorkflowSession {
      * 移除事件监听
      */
     off<K extends keyof SessionEventListeners>(event: K, listener: SessionEventListeners[K]): this;
+    /**
+     * 触发内容区域（如 Markdown）产生的交互动作
+     */
+    emitContentAction(action: import('./types').ContentAction): void;
     /**
      * 触发事件
+     * @internal
      */
     private emit;
     /**

package/dist/session.js

@@ -64,6 +64,9 @@ class WorkflowSession {
         null == (_this_listeners_get = this.listeners.get(event)) || _this_listeners_get.delete(listener);
         return this;
     }
+    emitContentAction(action) {
+        this.emit('contentAction', action);
+    }
     emit(event, ...args) {
         if (this.disposed) return;
         const listeners = this.listeners.get(event);

package/dist/types.d.ts

@@ -155,7 +155,21 @@ export interface SessionEventListeners {
     error: (error: {
         message: string;
     }) => void;
+    contentAction: (action: ContentAction) => void;
 }
+/**
+ * 内容交互动作联合类型
+ */
+export type ContentAction = {
+    /** 跳转工作流 */
+    type: 'workflow';
+    payload: {
+        workflowId: string;
+        /** 暂时没用上 */
+        params?: Record<string, string>;
+        extra?: Record<string, any>;
+    };
+};
 /**
  * 会话状态
  */

package/dist/ui/context.d.ts

@@ -1,3 +1,11 @@
 import type { WorkflowSession } from '../session';
+export interface WorkflowInfoMapping {
+    name: string;
+    icon?: React.ReactNode;
+    /** 额外的信息，会在点击的时候透传给调用方，方便使用 */
+    extra?: Record<string, any>;
+}
 export declare const SessionContext: import("react").Context<WorkflowSession | null>;
+export declare const WorkflowRegistryContext: import("react").Context<Record<string, WorkflowInfoMapping>>;
 export declare const useWorkflowSession: () => WorkflowSession | null;
+export declare const useWorkflowRegistry: () => Record<string, WorkflowInfoMapping>;

package/dist/ui/context.js

@@ -1,4 +1,6 @@
 import { createContext, useContext } from "react";
 const SessionContext = createContext(null);
+const WorkflowRegistryContext = createContext({});
 const useWorkflowSession = ()=>useContext(SessionContext);
-export { SessionContext, useWorkflowSession };
+const useWorkflowRegistry = ()=>useContext(WorkflowRegistryContext);
+export { SessionContext, WorkflowRegistryContext, useWorkflowRegistry, useWorkflowSession };

package/dist/ui/markdown.css

@@ -0,0 +1,14 @@
+.workflow-link {
+  cursor: pointer;
+  align-items: center;
+  display: inline-flex;
+}
+
+.workflow-link-icon {
+  margin-right: 4px;
+}
+
+.workflow-link-icon img {
+  margin: 0;
+}
+

package/dist/ui/markdown.d.ts

@@ -1,8 +1,16 @@
 import { XMarkdownProps } from '@ant-design/x-markdown';
 import '@ant-design/x-markdown/themes/light.css';
+import './markdown.css';
+import { WorkflowInfoMapping } from './context';
 import type { WorkflowSession } from '../session';
 export interface MarkdownProps extends XMarkdownProps {
     session?: WorkflowSession;
 }
-declare const Markdown: ({ className, streaming, config, components, session, ...props }: MarkdownProps) => import("react/jsx-runtime").JSX.Element;
-export { Markdown };
+/**
+ * 工作流信息注册表提供者
+ */
+export declare const WorkflowRegistry: ({ children, mapping, }: {
+    children: React.ReactNode;
+    mapping: Record<string, WorkflowInfoMapping>;
+}) => import("react/jsx-runtime").JSX.Element;
+export declare const Markdown: ({ className, streaming, config, components, session, ...props }: MarkdownProps) => import("react/jsx-runtime").JSX.Element;

package/dist/ui/markdown.js

@@ -1,4 +1,5 @@
-import { jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Children } from "react";
 import { XMarkdown } from "@ant-design/x-markdown";
 import "@ant-design/x-markdown/themes/light.css";
 import Latex from "@ant-design/x-markdown/plugins/Latex";
@@ -6,8 +7,25 @@ import zh_CN from "@ant-design/x/locale/zh_CN";
 import clsx from "clsx";
 import { Code } from "./code.js";
 import { XProvider } from "@ant-design/x";
-import { SessionContext } from "./context.js";
-const Markdown = ({ className, streaming, config, components, session, ...props })=>/*#__PURE__*/ jsx(XProvider, {
+import "./markdown.css";
+import { SessionContext, WorkflowRegistryContext, useWorkflowRegistry } from "./context.js";
+const WorkflowRegistry = ({ children, mapping })=>{
+    const parentRegistry = useWorkflowRegistry();
+    const mergedRegistry = {
+        ...parentRegistry,
+        ...mapping
+    };
+    return /*#__PURE__*/ jsx(SessionContext.Provider, {
+        value: null,
+        children: /*#__PURE__*/ jsx(WorkflowRegistryContext.Provider, {
+            value: mergedRegistry,
+            children: children
+        })
+    });
+};
+const Markdown = ({ className, streaming, config, components, session, ...props })=>{
+    const globalRegistry = useWorkflowRegistry();
+    return /*#__PURE__*/ jsx(XProvider, {
         locale: zh_CN,
         children: /*#__PURE__*/ jsx(SessionContext.Provider, {
             value: session || null,
@@ -23,10 +41,37 @@ const Markdown = ({ className, streaming, config, components, session, ...props
                 },
                 components: {
                     ...components,
-                    code: Code
+                    code: Code,
+                    workflow: (props)=>{
+                        const { id, children } = props;
+                        const info = id ? globalRegistry[id] : void 0;
+                        const displayContent = (null == info ? void 0 : info.name) || (Children.count(children) > 0 ? children : id);
+                        return /*#__PURE__*/ jsxs("a", {
+                            onClick: (e)=>{
+                                e.preventDefault();
+                                e.stopPropagation();
+                                null == session || session.emitContentAction({
+                                    type: 'workflow',
+                                    payload: {
+                                        workflowId: id,
+                                        extra: null == info ? void 0 : info.extra
+                                    }
+                                });
+                            },
+                            className: "workflow-link",
+                            children: [
+                                (null == info ? void 0 : info.icon) && /*#__PURE__*/ jsx("span", {
+                                    className: "workflow-link-icon",
+                                    children: info.icon
+                                }),
+                                displayContent
+                            ]
+                        });
+                    }
                 },
                 ...props
             })
         })
     });
-export { Markdown };
+};
+export { Markdown, WorkflowRegistry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wtfai",
-  "version": "1.5.7",
+  "version": "1.6.0",
   "type": "module",
   "exports": {
     ".": {
@@ -13,26 +13,26 @@
     "dist"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
+    "@eslint/js": "^9.39.3",
     "@rsbuild/plugin-react": "^1.4.5",
-    "@rslib/core": "^0.19.5",
-    "@types/react": "^19.2.13",
-    "eslint": "^9.39.2",
+    "@rslib/core": "^0.19.6",
+    "@types/react": "^19.2.14",
+    "eslint": "^9.39.3",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
-    "globals": "^17.3.0",
+    "globals": "^17.4.0",
     "prettier": "^3.8.1",
     "react": "^19.2.4",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.54.0"
+    "typescript-eslint": "^8.56.1"
   },
   "peerDependencies": {
     "react": ">=16.9.0",
     "react-dom": ">=16.9.0"
   },
   "dependencies": {
-    "@ant-design/x": "^2.2.2",
-    "@ant-design/x-markdown": "^2.2.2",
+    "@ant-design/x": "^2.3.0",
+    "@ant-design/x-markdown": "^2.3.0",
     "@microsoft/fetch-event-source": "^2.0.1",
     "clsx": "^2.1.1",
     "compressorjs": "^1.2.1",