@chatbi-v/mocks 1.0.1

package/README.md

@@ -0,0 +1,119 @@
+# @chatbi/mocks
+
+ChatBI Mock 数据模块，提供灵活的 JSON 和 SSE (Server-Sent Events) 数据模拟功能。
+
+## 特性
+
+- **多种响应策略**：支持 `json` (普通接口)、`sse` (流式接口)、`sse-page` (带分页的流式接口)。
+- **Mock.js 深度集成**：完全支持 Mock.js 的模板语法（如 `'data|8-12'` 生成数组）。
+- **动态模板插值**：支持在 Mock 模板中使用 `{{$query.param}}` 引用请求参数。
+- **自动扁平化**：SSE 事件流自动扁平化处理，支持批量生成事件。
+
+## 快速开始
+
+### 1. 定义 Mock Schema
+
+在 `api/modules/chat.mock.ts` 或其他 mock 文件中定义接口模拟规则：
+
+```typescript
+import { SUCCESS_CODE } from '@chatbi/core';
+
+export default {
+  // 普通 JSON 接口
+  getConversationList: {
+    type: 'json',
+    delay: 200,
+    responseSchema: {
+      code: SUCCESS_CODE,
+      msg: 'success',
+      'data|10': [{ id: '@increment', title: '@ctitle' }]
+    }
+  },
+
+  // SSE 流式接口
+  chat: {
+    type: 'sse',
+    responseSchema: {
+      'data|3-5': [{
+        event: 'data',
+        data: { content: '@cparagraph', role: 'assistant' },
+        delay: '@increment(100)'
+      }]
+    }
+  },
+
+  // SSE 分页接口 (适用于历史记录等场景)
+  getHistory: {
+    type: 'sse-page',
+    responseSchema: {
+      'data|8-12': [{ // 随机生成 8-12 条数据
+        event: 'data',
+        data: { 
+          id: '@guid', 
+          content: '@csentence',
+          role: '@pick(["user", "assistant"])'
+        },
+        delay: 50
+      }]
+    },
+    // 分页元数据事件（自动计算并在最后推送）
+    pageEvent: {
+      event: 'page',
+      data: {
+        pageNo: '{{$query.pageNo}}', // 引用请求参数
+        pageSize: 20,
+        total: 100,
+        hasNext: true
+      }
+    }
+  }
+}
+```
+
+## 核心概念
+
+### 策略类型 (type)
+
+| 类型 | 描述 |
+|Data|说明|
+|---|---|
+| `json` | 默认类型。返回标准的 JSON 对象。 |
+| `sse` | 返回 `Content-Type: text/event-stream`。将 `responseSchema` 生成的数组扁平化后，按 `delay` 排序依次推送。 |
+| `sse-page` | 基于 `sse`，但在流的末尾会自动追加一个 `page` 事件，用于传递分页元数据。需要配合 `pageEvent` 字段使用。 |
+
+### 模板增强功能
+
+#### 1. 数组范围生成
+支持 Mock.js 的 Key 规则生成指定数量的事件。在 SSE 场景下，生成的数组会被自动展开（flatten），确保每个数组元素作为一个独立的 SSE 事件发送。
+
+```javascript
+{
+  'data|8-12': [ // 随机生成 8 到 12 个事件
+    { event: 'data', ... }
+  ]
+}
+```
+
+#### 2. 请求参数引用与计算
+在字符串值中可以使用 `{{$query.xxx}}` 语法引用 URL 查询参数。支持简单的 JavaScript 表达式计算。
+
+```javascript
+{
+  // 假设请求 URL 为 ?pageNo=2
+  pageNo: '{{$query.pageNo}}', // 结果: 2 (自动转换类型)
+  offset: '{{$query.pageNo * 10}}', // 结果: 20
+  desc: '当前是第 {{$query.pageNo}} 页' // 结果: "当前是第 2 页"
+}
+```
+
+### SSE 数据结构约定
+
+为了配合前端的 `StreamStrategy`，SSE 事件通常遵循以下结构：
+
+```typescript
+interface MockEvent {
+  event: string; // 事件类型：data, log, error, page, todos
+  data: any;     // 事件载荷
+  delay?: number; // 延迟毫秒数（相对于流开始时间）
+}
+```

package/dist/adapter.d.ts

@@ -0,0 +1,48 @@
+import { ApiAdapter, ApiEndpointConfig, ApiRequestConfig, StreamCallbacks } from '@chatbi-v/core';
+import { MockGeneratorStrategy } from './types';
+/**
+ * 基于 Mock.js 的请求适配器
+ * @description 根据 API 配置中的 responseSchema 自动生成 Mock 数据，支持普通 JSON 和流式 SSE 响应
+ */
+export declare class MockAdapter implements ApiAdapter {
+    private delay;
+    private static strategies;
+    /**
+     * 构造函数
+     * @param delay 全局模拟延迟时间（毫秒），默认 300ms
+     */
+    constructor(delay?: number);
+    /**
+     * 注册自定义 Mock 生成策略
+     * @param key 策略唯一标识符 (e.g., 'chat_stream', 'history_stream')
+     * @param strategy 实现了 MockGeneratorStrategy 接口的策略实例
+     */
+    static registerStrategy(key: string, strategy: MockGeneratorStrategy): void;
+    /**
+     * 处理普通 HTTP 请求（非流式）
+     * @param config 请求配置对象
+     * @param endpointConfig API 端点配置，包含 responseSchema
+     * @returns Promise 返回模拟的响应数据
+     */
+    request<T = any>(config: ApiRequestConfig, endpointConfig?: ApiEndpointConfig): Promise<T>;
+    /**
+     * 处理流式请求 (SSE)
+     * @param config 请求配置对象
+     * @param callbacks 流式回调函数集合 (onMessage, onFinish, onError)
+     * @param endpointConfig API 端点配置，包含 responseSchema
+     */
+    stream(config: ApiRequestConfig, callbacks: StreamCallbacks, endpointConfig?: ApiEndpointConfig): Promise<void>;
+    /**
+     * 判断是否为遗留的 schema 格式
+     */
+    private isLegacySchema;
+    /**
+     * 判断是否为新版配置格式
+     * @description 检查配置对象中是否包含有效的 type 字段
+     */
+    private isNewConfig;
+    /**
+     * 生成遗留的高级 schema 数据块
+     */
+    private generateAdvancedChunks;
+}

package/dist/adapter.js

@@ -0,0 +1,260 @@
+import { createLogger, dateUtils, } from '@chatbi-v/core';
+import Mock from 'mockjs';
+import { ChatStreamStrategy, HistoryStreamStrategy, StrategyFactory } from './strategies';
+import { sleep } from './utils';
+const logger = createLogger('MockAdapter');
+/**
+ * 基于 Mock.js 的请求适配器
+ * @description 根据 API 配置中的 responseSchema 自动生成 Mock 数据，支持普通 JSON 和流式 SSE 响应
+ */
+export class MockAdapter {
+    delay;
+    // 遗留策略（为了兼容旧版代码）
+    static strategies = {
+        chat_stream: new ChatStreamStrategy(),
+        history_stream: new HistoryStreamStrategy(),
+    };
+    /**
+     * 构造函数
+     * @param delay 全局模拟延迟时间（毫秒），默认 300ms
+     */
+    constructor(delay = 300) {
+        this.delay = delay;
+    }
+    /**
+     * 注册自定义 Mock 生成策略
+     * @param key 策略唯一标识符 (e.g., 'chat_stream', 'history_stream')
+     * @param strategy 实现了 MockGeneratorStrategy 接口的策略实例
+     */
+    static registerStrategy(key, strategy) {
+        this.strategies[key] = strategy;
+    }
+    /**
+     * 处理普通 HTTP 请求（非流式）
+     * @param config 请求配置对象
+     * @param endpointConfig API 端点配置，包含 responseSchema
+     * @returns Promise 返回模拟的响应数据
+     */
+    async request(config, endpointConfig) {
+        return new Promise((resolve) => {
+            setTimeout(() => {
+                if (!endpointConfig || !endpointConfig.responseSchema) {
+                    logger.warn(`未找到响应架构配置: ${config.url}`);
+                    resolve({});
+                    return;
+                }
+                let schema = endpointConfig.responseSchema;
+                let mockData;
+                // 支持函数式 schema，允许根据请求参数动态生成 schema
+                if (typeof schema === 'function') {
+                    schema = schema(config);
+                }
+                // 构造有效配置对象，合并 endpointConfig 顶层属性
+                const effectiveConfig = {
+                    type: endpointConfig.type,
+                    pageEvent: endpointConfig.pageEvent,
+                    responseSchema: schema,
+                    ...(typeof schema === 'object' ? schema : {}),
+                };
+                // 1. 字符串 Schema：直接作为结果返回（极少情况）
+                if (typeof schema === 'string') {
+                    mockData = schema;
+                }
+                // 2. 遗留的高级 Schema (通过 _type 字段识别)
+                else if (this.isLegacySchema(schema)) {
+                    const strategy = MockAdapter.strategies[schema._type];
+                    if (strategy) {
+                        const chunks = strategy.generate(schema);
+                        // 将流式块合并为单个字符串，并清理 SSE 格式标记
+                        mockData = chunks
+                            .join('')
+                            .replace(/event: data\ndata: /g, '')
+                            .replace(/\n\n/g, '');
+                        try {
+                            mockData = JSON.parse(mockData);
+                        }
+                        catch (e) {
+                            // 忽略解析错误，保持原始数据格式
+                        }
+                    }
+                    else {
+                        logger.warn(`未找到对应的策略类型: ${schema._type}`);
+                        mockData = {};
+                    }
+                }
+                // 3. 新版 Schema (通过 type: 'json' | 'sse' | 'sse-page' 识别)
+                else if (this.isNewConfig(effectiveConfig)) {
+                    const type = effectiveConfig.type || 'json';
+                    const strategy = StrategyFactory.getStrategy(type);
+                    // 对于 request() 调用，我们只处理 'json' 类型
+                    if (type === 'json') {
+                        mockData = strategy.process(effectiveConfig, config.params || config.data);
+                    }
+                    else {
+                        logger.warn(`在同步请求中调用了流式接口: ${config.url}`);
+                        mockData = {};
+                    }
+                }
+                // 4. 默认 MockJS 回退：直接使用 Mock.mock 生成
+                else {
+                    mockData = Mock.mock(schema);
+                }
+                logger.info(`Request: ${config.method} ${config.url}`, config.data || config.params);
+                logger.info(`Response:`, mockData);
+                resolve(mockData);
+            }, this.delay);
+        });
+    }
+    /**
+     * 处理流式请求 (SSE)
+     * @param config 请求配置对象
+     * @param callbacks 流式回调函数集合 (onMessage, onFinish, onError)
+     * @param endpointConfig API 端点配置，包含 responseSchema
+     */
+    async stream(config, callbacks, endpointConfig) {
+        const { onMessage, onFinish, onError } = callbacks;
+        const signal = config.signal;
+        return new Promise((resolve) => {
+            // 如果请求已被取消，直接结束
+            if (signal && signal.aborted) {
+                if (onFinish)
+                    onFinish();
+                resolve();
+                return;
+            }
+            setTimeout(async () => {
+                try {
+                    if (!endpointConfig || !endpointConfig.responseSchema) {
+                        logger.warn(`未找到流式响应架构: ${config.url}`);
+                        if (onFinish)
+                            onFinish();
+                        resolve();
+                        return;
+                    }
+                    const requestStart = dateUtils.now();
+                    logger.info(`[SSE Start] Request: ${config.method} ${config.url}`, {
+                        params: config.data || config.params,
+                        time: dateUtils.dayjs().toISOString(),
+                    });
+                    let schema = endpointConfig.responseSchema;
+                    // 支持函数式 schema
+                    if (typeof schema === 'function') {
+                        schema = schema(config);
+                    }
+                    // 构造有效配置对象，合并 endpointConfig 顶层属性
+                    const effectiveConfig = {
+                        type: endpointConfig.type,
+                        pageEvent: endpointConfig.pageEvent,
+                        responseSchema: schema,
+                        ...(typeof schema === 'object' ? schema : {}),
+                    };
+                    // 1. 新版 Schema 策略 (sse, sse-page)
+                    if (this.isNewConfig(effectiveConfig)) {
+                        const type = effectiveConfig.type || 'sse';
+                        const strategy = StrategyFactory.getStrategy(type);
+                        // 策略处理返回 MockEvent 数组
+                        const events = strategy.process(effectiveConfig, config.params || config.data);
+                        if (Array.isArray(events)) {
+                            const startTime = dateUtils.now();
+                            let eventCount = 0;
+                            logger.info(`[SSE Processing] Generated ${events.length} events for ${type} strategy`);
+                            for (const event of events) {
+                                if (signal && signal.aborted) {
+                                    logger.info(`[SSE Abort] Stream aborted by user after ${dateUtils.now() - requestStart}ms`);
+                                    break;
+                                }
+                                // 计算延迟
+                                const delay = typeof event.delay === 'number'
+                                    ? event.delay
+                                    : parseInt(String(event.delay || 0));
+                                const elapsed = dateUtils.now() - startTime;
+                                const remaining = Math.max(0, delay - elapsed);
+                                if (remaining > 0) {
+                                    await sleep(remaining);
+                                }
+                                if (signal && signal.aborted)
+                                    break;
+                                // 构造 SSE 格式数据块
+                                const chunk = `event: ${event.event}\ndata: ${JSON.stringify(event.data)}\n\n`;
+                                // 记录关键事件日志
+                                if (['error', 'todos', 'page'].includes(event.event)) {
+                                    logger.info(`[SSE Event] Emitting special event: ${event.event}`, event.data);
+                                }
+                                else if (eventCount === 0 || eventCount === events.length - 1) {
+                                    logger.info(`[SSE Event] Emitting ${eventCount === 0 ? 'first' : 'last'} data event`, { preview: JSON.stringify(event.data).slice(0, 50) + '...' });
+                                }
+                                if (onMessage)
+                                    onMessage(chunk);
+                                eventCount++;
+                            }
+                        }
+                    }
+                    // 2. 遗留策略处理
+                    else {
+                        let chunks = [];
+                        if (typeof schema === 'string') {
+                            chunks = schema.split('\n\n').map((chunk) => chunk + '\n\n');
+                        }
+                        else if (this.isLegacySchema(schema)) {
+                            chunks = this.generateAdvancedChunks(schema);
+                        }
+                        else {
+                            const mockData = Mock.mock(schema);
+                            chunks = [`data: ${JSON.stringify(mockData)}\n\n`];
+                        }
+                        for (const chunk of chunks) {
+                            if (signal && signal.aborted) {
+                                logger.info('[SSE Abort] Stream aborted by user');
+                                break;
+                            }
+                            if (chunk.trim()) {
+                                if (onMessage)
+                                    onMessage(chunk);
+                                await new Promise((r) => setTimeout(r, 200));
+                            }
+                        }
+                    }
+                    if (!signal || !signal.aborted) {
+                        logger.info(`[SSE Complete] Stream finished successfully in ${dateUtils.now() - requestStart}ms`);
+                        if (onFinish)
+                            onFinish();
+                    }
+                    resolve();
+                }
+                catch (error) {
+                    logger.error(`[SSE Error] Stream processing failed`, error);
+                    if (onError)
+                        onError(error);
+                    resolve();
+                }
+            }, this.delay);
+        });
+    }
+    /**
+     * 判断是否为遗留的 schema 格式
+     */
+    isLegacySchema(schema) {
+        return schema && typeof schema === 'object' && '_type' in schema;
+    }
+    /**
+     * 判断是否为新版配置格式
+     * @description 检查配置对象中是否包含有效的 type 字段
+     */
+    isNewConfig(config) {
+        return (config &&
+            typeof config === 'object' &&
+            (['json', 'sse', 'sse-page'].includes(config.type) || 'responseSchema' in config) // 备用检查，如果 schema 内部定义了结构
+        );
+    }
+    /**
+     * 生成遗留的高级 schema 数据块
+     */
+    generateAdvancedChunks(schema) {
+        const strategy = MockAdapter.strategies[schema._type];
+        if (strategy) {
+            return strategy.generate(schema);
+        }
+        logger.warn(`未找到对应的策略类型: ${schema._type}`);
+        return [];
+    }
+}

package/dist/generator.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Mock 响应生成器
+ * @description 用于动态生成流式响应数据，支持阶段流转、日志插入和内容分块
+ */
+export declare class MockResponseGenerator {
+    private events;
+    private sessionId;
+    private agentName;
+    private currentTodos;
+    constructor(agentName?: string, sessionId?: string);
+    /**
+     * 生成历史消息流
+     */
+    emitHistory(history: {
+        role: string;
+        content: string;
+        createTime: string;
+        todos?: any[];
+    }[]): this;
+    /**
+     * 初始化执行计划
+     * @param steps 计划步骤列表
+     */
+    initPlan(steps: string[]): this;
+    /**
+     * 更新执行计划状态
+     * @param activeIndex 当前正在进行的步骤索引
+     */
+    updatePlanStatus(activeIndex: number): this;
+    /**
+     * 标记所有计划为完成
+     */
+    completePlan(): this;
+    /**
+     * 添加日志
+     * @param content 日志内容
+     * @param type 日志类型
+     * @param agentName 可选的 Agent 名称
+     */
+    addLog(content: string, type?: 'info' | 'warning' | 'error', agentName?: string): this;
+    /**
+     * 添加系统错误事件
+     * @param errorCode 错误码
+     * @param errorMessage 错误信息
+     */
+    addError(errorCode: string, errorMessage: string): this;
+    /**
+     * 添加流式内容块
+     * @param content 完整内容
+     * @param chunkSize 分块大小
+     */
+    streamContent(content: string, chunkSize?: number): this;
+    /**
+     * 结束流
+     */
+    finish(): this;
+    /**
+     * 生成 A2UI 响应
+     * @param component A2UI 组件配置对象
+     */
+    emitA2UI(component: Record<string, any>): this;
+    /**
+     * 生成最终的响应字符串
+     */
+    toString(): string;
+    private pushTodos;
+    private pushEvent;
+}

package/dist/generator.js

@@ -0,0 +1,149 @@
+import { dateUtils } from '@chatbi-v/core';
+/**
+ * Mock 响应生成器
+ * @description 用于动态生成流式响应数据，支持阶段流转、日志插入和内容分块
+ */
+export class MockResponseGenerator {
+    events = [];
+    sessionId;
+    agentName;
+    currentTodos = [];
+    constructor(agentName = 'Assistant', sessionId) {
+        this.sessionId = sessionId || ('conv_' + dateUtils.now());
+        this.agentName = agentName;
+    }
+    /**
+     * 生成历史消息流
+     */
+    emitHistory(history) {
+        history.forEach(msg => {
+            const data = {
+                content: msg.content,
+                sessionId: this.sessionId,
+                role: msg.role,
+                completed: true,
+                agentName: this.agentName,
+                createTime: msg.createTime
+            };
+            this.pushEvent('data', data);
+            if (msg.todos) {
+                this.pushEvent('todos', { items: msg.todos });
+            }
+        });
+        return this;
+    }
+    /**
+     * 初始化执行计划
+     * @param steps 计划步骤列表
+     */
+    initPlan(steps) {
+        this.currentTodos = steps.map(step => ({
+            content: step,
+            status: 'PENDING'
+        }));
+        this.pushTodos();
+        return this;
+    }
+    /**
+     * 更新执行计划状态
+     * @param activeIndex 当前正在进行的步骤索引
+     */
+    updatePlanStatus(activeIndex) {
+        this.currentTodos = this.currentTodos.map((todo, index) => {
+            if (index < activeIndex) {
+                return { ...todo, status: 'COMPLETED' };
+            }
+            else if (index === activeIndex) {
+                return { ...todo, status: 'IN_PROGRESS' };
+            }
+            else {
+                return { ...todo, status: 'PENDING' };
+            }
+        });
+        this.pushTodos();
+        return this;
+    }
+    /**
+     * 标记所有计划为完成
+     */
+    completePlan() {
+        this.currentTodos = this.currentTodos.map(todo => ({ ...todo, status: 'COMPLETED' }));
+        this.pushTodos();
+        return this;
+    }
+    /**
+     * 添加日志
+     * @param content 日志内容
+     * @param type 日志类型
+     * @param agentName 可选的 Agent 名称
+     */
+    addLog(content, type = 'info', agentName) {
+        this.pushEvent('log', {
+            type,
+            content,
+            agentName: agentName || this.agentName
+        });
+        return this;
+    }
+    /**
+     * 添加系统错误事件
+     * @param errorCode 错误码
+     * @param errorMessage 错误信息
+     */
+    addError(errorCode, errorMessage) {
+        this.pushEvent('error', {
+            errorCode,
+            errorMessage
+        });
+        return this;
+    }
+    /**
+     * 添加流式内容块
+     * @param content 完整内容
+     * @param chunkSize 分块大小
+     */
+    streamContent(content, chunkSize = 20) {
+        for (let i = 0; i < content.length; i += chunkSize) {
+            const chunk = content.slice(i, i + chunkSize);
+            this.pushEvent('data', {
+                content: chunk,
+                sessionId: this.sessionId,
+                completed: false,
+                agentName: this.agentName
+            });
+        }
+        return this;
+    }
+    /**
+     * 结束流
+     */
+    finish() {
+        this.pushEvent('data', {
+            content: '',
+            sessionId: this.sessionId,
+            completed: true,
+            agentName: this.agentName
+        });
+        return this;
+    }
+    /**
+     * 生成 A2UI 响应
+     * @param component A2UI 组件配置对象
+     */
+    emitA2UI(component) {
+        const content = JSON.stringify(component, null, 2);
+        return this.streamContent(content);
+    }
+    /**
+     * 生成最终的响应字符串
+     */
+    toString() {
+        return this.events.join('\n');
+    }
+    pushTodos() {
+        this.pushEvent('todos', { items: this.currentTodos });
+    }
+    pushEvent(type, data) {
+        this.events.push(`event: ${type}\ndata: ${JSON.stringify(data)}\n`);
+    }
+}