@baishuyun/chat-backend 0.0.8 → 0.0.10

package/.env.example

@@ -15,3 +15,6 @@ BUILD_BOT_ID=xxxxx
 
 # fill bot id
 FILL_BOT_ID=xxxxx
+
+# query bot id
+QUERY_BOT_ID=xxxxx

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @baishuyun/chat-backend
 
+## 0.0.10
+
+### Patch Changes
+
+- Updated dependencies
+  - @baishuyun/coze-provider@0.0.10
+  - @baishuyun/types@1.0.10
+
+## 0.0.9
+
+### Patch Changes
+
+- Updated dependencies
+  - @baishuyun/coze-provider@0.0.9
+  - @baishuyun/types@1.0.9
+
 ## 0.0.8
 
 ### Patch Changes

package/config/default.ts

@@ -1,34 +1,43 @@
-import { asyncConfig } from "config/async.js";
+import { asyncConfig } from 'config/async.js';
 // load async configurations
 const fetchRemoteConfig = async () => {
   return {
     // mock remote config
-    foo: "bar",
+    foo: 'bar',
   };
 };
 
 export default {
   app: {
     port: process.env.PORT || 3001,
-    host: process.env.HOST || "localhost",
+    host: process.env.HOST || 'localhost',
   },
+
   agent: {
-    host: process.env.AGENT_HOST || "47.99.202.157",
+    host: process.env.AGENT_HOST || '47.99.202.157',
 
     apiAuthKey: process.env.COZE_API_KEY,
 
     form: {
       build: {
-        botId: process.env.BUILD_BOT_ID || "7579927677256073216",
+        botId: process.env.BUILD_BOT_ID || '7579927677256073216',
         baseUrl: `http://${process.env.AGENT_HOST}/v3/`,
         apiKey: process.env.BOT_API_KEY, // load from env
       },
 
       fill: {
-        botId: process.env.FILL_BOT_ID || "7586483957357608960",
+        botId: process.env.FILL_BOT_ID || '7586483957357608960',
+        baseUrl: `http://${process.env.AGENT_HOST}/v3/`,
+        apiKey: process.env.BOT_API_KEY, // load from env
+        ocrApiKey: process.env.OCR_API_KEY || '', // load from env
+      },
+    },
+
+    report: {
+      query: {
+        botId: process.env.QUERY_BOT_ID || '7595888372090929152',
         baseUrl: `http://${process.env.AGENT_HOST}/v3/`,
         apiKey: process.env.BOT_API_KEY, // load from env
-        ocrApiKey: process.env.OCR_API_KEY || "", // load from env
       },
     },
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baishuyun/chat-backend",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -22,8 +22,8 @@
     "parse-sse": "^0.1.0",
     "pino": "^10.1.0",
     "zod": "^4.1.13",
-    "@baishuyun/coze-provider": "0.0.8",
-    "@baishuyun/types": "1.0.8"
+    "@baishuyun/coze-provider": "0.0.10",
+    "@baishuyun/types": "1.0.10"
   },
   "devDependencies": {
     "@types/config": "^3.3.5",
@@ -34,7 +34,7 @@
     "pm2": "^6.0.14",
     "tsx": "^4.7.1",
     "typescript": "^5.8.3",
-    "@baishuyun/typescript-config": "0.0.8"
+    "@baishuyun/typescript-config": "0.0.10"
   },
   "scripts": {
     "dev": "cross-env NODE_ENV=development tsx watch src/index.ts",

package/src/app/main.ts

@@ -7,9 +7,11 @@ import app from '../config/hono.config.js';
 
 // 子路由
 import { createFormRouter } from '../routes/form/form.route.js';
+import { createReportRouter } from '../routes/report/report.route.js';
 
 // 挂载子路由
 app.route('web/api/form', createFormRouter());
+app.route('web/api/report', createReportRouter());
 
 // add test route
 app.get('web/api/test', (c) => {

package/src/controllers/report/query/createQueryTransformStream.ts

@@ -0,0 +1,125 @@
+import { type LanguageModelV2StreamPart } from '@ai-sdk/provider';
+import { JSONParser } from '@streamparser/json';
+import { type IQueryResult } from '@baishuyun/types';
+import {
+  createJsonStreamTransformer,
+  type IParserCtx,
+} from '../../../utils/createJsonStreamTransformer.js';
+import { isTargetElement } from './utils.js';
+import { logger } from '../../../logger/index.js';
+import { fieldHandlers } from './handler-registry.js';
+
+export const createQueryResultTransformer = (): TransformStream<LanguageModelV2StreamPart, any> => {
+  return createJsonStreamTransformer<IQueryResult>({
+    createJSONParser: createJSONParser,
+    onParseValue: handleParsedValue,
+    onParseError(error) {
+      logger.error('JSON parsing error in query transformer: ', error);
+      return '数据解析异常，请重试';
+    },
+    onErrorChunk(chunk) {
+      logger.error('Received error chunk in query transformer');
+      return '';
+    },
+  });
+};
+
+function createJSONParser(): JSONParser {
+  return new JSONParser({
+    stringBufferSize: undefined,
+    numberBufferSize: undefined,
+    separator: '',
+    paths: [
+      '$', // 保留完整结果推送
+      '$.title',
+      '$.name',
+      '$.type',
+      '$.userID',
+      '$.forms',
+      '$.fields.*',
+      '$.xFields.*',
+      '$.yFields.*',
+      '$.metrics.*',
+      '$.formulas.*',
+      '$.filter.rel',
+      '$.filter.cond.*',
+      '$.limit',
+    ],
+    keepStack: true,
+  });
+}
+
+function handleParsedValue(ctx: IParserCtx<IQueryResult>): void {
+  const { parsedInfo, getResult, currentChunkId, deltaChunkEnqueuer: enqueueTextDelta, ctrl } = ctx;
+  const { value } = parsedInfo;
+
+  logger.debug('Parsed JSON value: ' + JSON.stringify(value));
+
+  // TODO: 使用约定的字段判断类型
+  // Phase 1: aggregate 类型 —— name 字段触发，独立处理后直接返回
+  if (isTargetElement('$.name', parsedInfo)) {
+    handleAggregateName(ctx);
+    return;
+  }
+
+  // Phase 2: 报表标题 —— 初始化结果并发送 text-start
+  if (isTargetElement('$.title', parsedInfo)) {
+    handleTitle(ctx);
+  }
+
+  // Phase 3: aggregate 结果无需后续字段处理
+  if (getResult().isAggregate) return;
+
+  // Phase 4: 按注册的 handler 分发字段处理
+  for (const { path, handler } of fieldHandlers) {
+    if (isTargetElement(path, parsedInfo)) {
+      handler(ctx, value);
+      break;
+    }
+  }
+
+  // Phase 5: 向下游推送增量结果
+  enqueueTextDelta(
+    `${JSON.stringify(value)},`,
+    { type: 'query-stream-parsed-info', result: JSON.stringify(getResult()) },
+    currentChunkId + 2,
+    true
+  );
+}
+
+// ===================== Phase Handlers =====================
+
+function handleAggregateName(ctx: IParserCtx<IQueryResult>): void {
+  const { parsedInfo, getResult, currentChunkId, deltaChunkEnqueuer: enqueueTextDelta } = ctx;
+  const value = parsedInfo.value;
+
+  ctx.setPartialResult({
+    title: value as string,
+    isAggregate: true,
+    type: 'data_table',
+  });
+
+  logger.debug('Parsed aggregate table title: ' + value);
+
+  enqueueTextDelta(
+    `${JSON.stringify(value)},`,
+    { type: 'query-stream-parsed-info', result: JSON.stringify(getResult()) },
+    currentChunkId + 1,
+    false
+  );
+}
+
+function handleTitle(ctx: IParserCtx<IQueryResult>): void {
+  const { parsedInfo, currentChunkId, ctrl } = ctx;
+
+  ctx.clearResult();
+
+  ctrl.enqueue({
+    type: 'text-start',
+    id: currentChunkId + 2,
+  });
+
+  ctx.setPartialResult({
+    title: parsedInfo.value as string,
+  });
+}

package/src/controllers/report/query/handler-helpers.ts

@@ -0,0 +1,35 @@
+import { type IQueryResult } from '@baishuyun/types';
+import { type IParserCtx } from '../../../utils/createJsonStreamTransformer.js';
+import type { ValueHandler } from './types.js';
+
+// ===================== Handler Helpers =====================
+/** 创建一个将值推入指定数组字段的 handler */
+export function pushToArray(field: keyof IQueryResult): ValueHandler {
+  return (ctx, value) => {
+    const result = ctx.getResult();
+    if (!result[field]) {
+      ctx.setPartialResult({ [field]: [] } as Partial<IQueryResult>);
+    }
+    (ctx.getResult()[field] as any[]).push(value);
+  };
+}
+
+/** 创建一个将值推入数组字段、并附加 tag/form 元信息的 handler */
+export function pushToArrayWithMeta(field: keyof IQueryResult): ValueHandler {
+  return (ctx, value) => {
+    const result = ctx.getResult();
+    if (!result[field]) {
+      ctx.setPartialResult({ [field]: [] } as Partial<IQueryResult>);
+    }
+    value.tag = `f_${Date.now()}`;
+    value.form = result.formIds ? result.formIds[0] : '';
+    (ctx.getResult()[field] as any[]).push(value);
+  };
+}
+
+/** 确保 filter 对象已初始化 */
+export function ensureFilter(ctx: IParserCtx<IQueryResult>): void {
+  if (!ctx.getResult().filter) {
+    ctx.setPartialResult({ filter: { rel: 'and', conds: [] } });
+  }
+}

package/src/controllers/report/query/handler-registry.ts

@@ -0,0 +1,46 @@
+import { type IDashWidgetType, type IQueryFilter } from '@baishuyun/types';
+import type { PathHandler } from './types.js';
+import { ensureFilter, pushToArray, pushToArrayWithMeta } from './handler-helpers.js';
+
+export const fieldHandlers: PathHandler[] = [
+  {
+    path: '$.userID',
+    handler: (ctx, value) => ctx.setPartialResult({ userID: value as number }),
+  },
+  {
+    path: '$.limit',
+    handler: (ctx, value) => ctx.setPartialResult({ limit: value as number }),
+  },
+  {
+    path: '$.forms',
+    handler: (ctx, value) => ctx.setPartialResult({ formIds: [value as string] }),
+  },
+  {
+    path: '$.type',
+    handler: (ctx, value) => ctx.setPartialResult({ type: value as IDashWidgetType }),
+  },
+  {
+    path: '$.filter.rel',
+    handler: (ctx, value) => {
+      ensureFilter(ctx);
+      ctx.setPartialResult({
+        filter: { ...ctx.getResult().filter, rel: value } as IQueryFilter,
+      });
+    },
+  },
+  {
+    path: '$.filter.cond.*',
+    handler: (ctx, value) => {
+      ensureFilter(ctx);
+      const filter = ctx.getResult().filter!;
+      ctx.setPartialResult({
+        filter: { ...filter, conds: [...(filter.conds || []), value] } as IQueryFilter,
+      });
+    },
+  },
+  { path: '$.fields.*', handler: pushToArray('fields') },
+  { path: '$.formulas.*', handler: pushToArray('formulas') },
+  { path: '$.metrics.*', handler: pushToArrayWithMeta('metrics') },
+  { path: '$.xFields.*', handler: pushToArrayWithMeta('xFields') },
+  { path: '$.yFields.*', handler: pushToArrayWithMeta('yFields') },
+];

package/src/controllers/report/query/model.ts

@@ -0,0 +1,17 @@
+import { createCoze } from '@baishuyun/coze-provider';
+
+import config from 'config';
+import { createQueryResultTransformer } from './createQueryTransformStream.js';
+
+export const createReportQueryModel = () => {
+  const reportQuery = createCoze({
+    apiKey: config.get<string>('agent.report.query.apiKey'),
+    baseURL: config.get<string>('agent.report.query.baseUrl'),
+    botId: config.get<string>('agent.report.query.botId'),
+    extraStreamTransformers: [createQueryResultTransformer],
+  });
+
+  const reportQueryModel = reportQuery.chat('chat');
+
+  return reportQueryModel;
+};

package/src/controllers/report/query/query.controller.ts

@@ -0,0 +1,50 @@
+import { type Context } from 'hono';
+import { convertToModelMessages, streamText, type UIMessage, generateId } from 'ai';
+import { createReportQueryModel } from './model.js';
+import { buildExtraMsgParts } from './utils.js';
+
+export const queryReport = async (c: Context) => {
+  let requestBody;
+
+  try {
+    const json = await c.req.json();
+    requestBody = json;
+  } catch (_) {
+    return c.json({ error: 'Invalid JSON' }, 400);
+  }
+
+  const uid = c.req.header('X-User-Id') || '';
+  const messages: UIMessage[] = requestBody.messages;
+
+  const extraText = buildExtraMsgParts({
+    appId: requestBody.appId,
+    userId: uid,
+    textOnly: true,
+  }) as string;
+
+  const lastUserTextPartOfMessage = messages
+    .slice()
+    .reverse()
+    .find((msg) => msg.role === 'user')
+    ?.parts.findLast((part) => part.type === 'text') as { type: 'text'; text: string } | undefined;
+
+  if (lastUserTextPartOfMessage) {
+    lastUserTextPartOfMessage.text = `${extraText}${lastUserTextPartOfMessage.text}`;
+  }
+
+  const modelMessages = convertToModelMessages(messages);
+  console.log('Final messages for report query:', JSON.stringify(modelMessages, null, 2));
+
+  const stream = streamText({
+    model: createReportQueryModel(),
+    messages: modelMessages,
+    includeRawChunks: true,
+    headers: {
+      'x-user-id': uid,
+    },
+  });
+
+  return stream.toUIMessageStreamResponse({
+    originalMessages: messages, // 建议添加，便于消息 ID 管理
+  });
+};

package/src/controllers/report/query/types.ts

@@ -0,0 +1,9 @@
+import { type IQueryResult } from '@baishuyun/types';
+import { type IParserCtx } from '../../../utils/createJsonStreamTransformer.js';
+
+export type ValueHandler = (ctx: IParserCtx<IQueryResult>, value: any) => void;
+
+export interface PathHandler {
+  path: string;
+  handler: ValueHandler;
+}

package/src/controllers/report/query/utils.ts

@@ -0,0 +1,84 @@
+import type { LanguageModelV2StreamPart } from '@ai-sdk/provider';
+import type { ParsedElementInfo } from '@streamparser/json/utils/types/parsedElementInfo.js';
+import type { TextUIPart, UIMessagePart } from 'ai';
+
+export const buildExtraMsgParts = ({
+  appId,
+  userId,
+  textOnly,
+}: {
+  appId: string;
+  userId: string;
+  textOnly?: boolean;
+}): Array<TextUIPart> | string => {
+  if (textOnly) {
+    return `appID为${appId}；用户ID为${userId}；`;
+  }
+
+  return [
+    {
+      type: 'text',
+      text: `appID为${appId}；`,
+    },
+    {
+      type: 'text',
+      text: `用户ID为${userId}；`,
+    },
+  ];
+};
+
+export const queryChunkGuard = (chunk: LanguageModelV2StreamPart) => {
+  if (chunk.type !== 'text-delta' || !('delta' in chunk)) {
+    return false;
+  }
+
+  return true;
+};
+
+/**
+ * 通用路径匹配器：判断当前解析到的元素是否命中指定的 JSONParser 路径。
+ *
+ * 支持两种路径形式：
+ * - 精确路径：`$.title`、`$.filter.rel` — 匹配特定 key
+ * - 通配路径：`$.fields.*`、`$.filter.cond.*` — 匹配数组元素
+ *
+ * path 格式与 `JSONParser` 的 `paths` 配置完全一致，无需额外转换。
+ *
+ * @example
+ * isTargetElement('$.title', parsedInfo)
+ * isTargetElement('$.filter.rel', parsedInfo)
+ * isTargetElement('$.fields.*', parsedInfo)
+ * isTargetElement('$.filter.cond.*', parsedInfo)
+ */
+export const isTargetElement = (path: string, parsedInfo: ParsedElementInfo): boolean => {
+  const { key, stack, parent } = parsedInfo;
+
+  // 去掉 '$.' 前缀，按 '.' 分割
+  const segments = path.replace(/^\$\./, '').split('.');
+  const endsWithWildcard = segments[segments.length - 1] === '*';
+
+  if (endsWithWildcard) {
+    // ---- 通配路径：匹配数组中的元素 ----
+    const parentKeys = segments.slice(0, -1);
+
+    // 当前 key 必须为数组索引，parent 必须为数组
+    if (typeof key !== 'number' || !Array.isArray(parent)) return false;
+
+    // stack 深度 = root(1) + parentKeys
+    if (stack.length !== parentKeys.length + 1) return false;
+
+    // 从 stack[1] 开始逐段匹配（跳过 root）
+    return parentKeys.every((seg, i) => stack[i + 1]?.key === seg);
+  }
+
+  // ---- 精确路径：匹配特定 key ----
+  const leafKey = segments[segments.length - 1];
+  if (key !== leafKey) return false;
+
+  const parentKeys = segments.slice(0, -1);
+
+  // stack 深度 = root(1) + parentKeys（叶子节点自身不在 stack 中）
+  if (stack.length !== parentKeys.length + 1) return false;
+
+  return parentKeys.every((seg, i) => stack[i + 1]?.key === seg);
+};

package/src/routes/report/report.route.ts

@@ -0,0 +1,11 @@
+import { Hono } from 'hono';
+import { queryReport } from '../../controllers/report/query/query.controller.js';
+
+export const createReportRouter = () => {
+  const reportRouter = new Hono();
+
+  // 智能问数
+  reportRouter.post('/query', queryReport);
+
+  return reportRouter;
+};

package/src/utils/createJsonStreamTransformer.ts

@@ -0,0 +1,249 @@
+import { type LanguageModelV2StreamPart } from '@ai-sdk/provider';
+import { createTextInfoEnqueuer } from '@baishuyun/coze-provider';
+import { JSONParser } from '@streamparser/json';
+import type { ParsedElementInfo } from '@streamparser/json/utils/types/parsedElementInfo.js';
+import { logger } from '../logger/index.js';
+
+/** onParseValue 回调接收的上下文 */
+export interface IParserCtx<T> {
+  /** 累积的解析结果，可直接修改 */
+  getResult: () => T;
+  setPartialResult: (partial: Partial<T>) => void;
+  clearResult: () => void;
+  /** 当前触发 onValue 的解析信息 */
+  parsedInfo: ParsedElementInfo;
+  /** 向下游推送 text-delta chunk 的工具函数 */
+  deltaChunkEnqueuer: ReturnType<typeof createTextInfoEnqueuer>;
+  /** 当前正在处理的 chunk id */
+  currentChunkId: string;
+  ctrl: Controller;
+}
+
+/** 创建 JSON 流转换器的选项 */
+export interface JsonStreamTransformerOptions<T> {
+  /** 创建 JSONParser 实例（由使用者决定路径、分隔符等解析细节） */
+  createJSONParser: () => JSONParser;
+  /** 每次解析出值时的回调 */
+  onParseValue: (ctx: IParserCtx<T>) => void;
+  /** chunk 过滤，返回 true 表示需要解析，默认检查 text-delta 类型 */
+  chunkGuard?: (chunk: LanguageModelV2StreamPart) => boolean;
+  /** 收到 error 类型 chunk 时的回调（可选） */
+  onErrorChunk?: (chunk: LanguageModelV2StreamPart) => void;
+  /** JSON 解析出错时的回调，返回要展示的错误消息（可选） */
+  onParseError?: (error: any) => string;
+}
+
+/**
+ * 创建一个 TransformStream，将 AI 流式响应中的 JSON 片段解析为结构化数据。
+ *
+ * 使用者只需关心：
+ * 1. `createJSONParser` — 决定 JSON 解析的路径 / 选项
+ * 2. `onParseValue`     — 处理每个解析出的值
+ * 3. 错误处理（均可选）
+ */
+export const createJsonStreamTransformer = <T>(
+  options: JsonStreamTransformerOptions<T>
+): TransformStream<LanguageModelV2StreamPart, any> => {
+  const processor = new JsonStreamProcessor<T>(options);
+  return new TransformStream<LanguageModelV2StreamPart, any>({
+    start: (ctrl) => processor.start(ctrl),
+    transform: (chunk, ctrl) => processor.transform(chunk, ctrl),
+    flush: (ctrl) => processor.flush(ctrl),
+  });
+};
+
+const BACKTICK_RE = /`?`?`?/g;
+const JSON_PREFIX = 'json';
+
+const ERROR_MESSAGES = {
+  PARSE_ERROR: '解析异常，请刷新重试',
+  TIMEOUT: '操作超时，请刷新重试',
+  GENERAL_ERROR: '发生错误，请刷新重试',
+} as const;
+
+type Controller = TransformStreamDefaultController<any>;
+type ChunkWithIdDelta = Extract<LanguageModelV2StreamPart, { id: string; delta: string }>;
+
+class JsonStreamProcessor<T> {
+  // -- 配置 --
+  private readonly options: JsonStreamTransformerOptions<T>;
+
+  // -- 运行时状态 --
+  private parser: JSONParser | null = null;
+  private result: T = {} as T;
+  private currentChunkId = '';
+  private parseCompleted: Promise<void> | null = null;
+  private resolveParseCompleted: (() => void) | null = null;
+  private terminated = false;
+
+  constructor(options: JsonStreamTransformerOptions<T>) {
+    this.options = options;
+  }
+
+  // ===================== 生命周期 =====================
+
+  /** TransformStream start：创建 parser、绑定回调 */
+  start(controller: Controller): void {
+    this.parser = this.options.createJSONParser();
+    this.parseCompleted = this.createCompletionPromise();
+    this.bindParserCallbacks(controller);
+  }
+
+  /** TransformStream transform：逐 chunk 处理 */
+  transform(chunk: LanguageModelV2StreamPart, controller: Controller): void {
+    if (this.terminated || !this.parser) {
+      logger.warn('JSON parser not initialized or stream already terminated');
+      return;
+    }
+
+    try {
+      // 1) error chunk → 通知下游后终止
+      if (chunk.type === 'error') {
+        this.options.onErrorChunk?.(chunk);
+        this.enqueueError(controller, ERROR_MESSAGES.GENERAL_ERROR);
+        return;
+      }
+
+      // 2) 不需要解析的 chunk → 透传
+      const guard = this.options.chunkGuard ?? defaultChunkGuard;
+      if (!guard(chunk)) {
+        controller.enqueue(chunk);
+        return;
+      }
+
+      // 3) 提取 delta 写入 parser
+      if (isChunkWithDelta(chunk)) {
+        this.currentChunkId = chunk.id;
+        this.parser.write(stripCodeFence(chunk.delta));
+      }
+    } catch (error) {
+      this.enqueueError(controller, error);
+    }
+  }
+
+  /** TransformStream flush：结束 parser 并等待所有回调完成 */
+  async flush(controller: Controller): Promise<void> {
+    try {
+      if (this.parser) {
+        this.parser.end();
+        if (this.parseCompleted) await this.parseCompleted;
+        logger.debug('Parser stopped gracefully');
+      }
+      if (!this.terminated) controller.terminate();
+    } catch (error) {
+      controller.error(`Cleanup error: ${error}`);
+    }
+  }
+
+  // ===================== Parser 回调 =====================
+
+  private bindParserCallbacks(controller: Controller): void {
+    if (!this.parser) return;
+
+    const enqueue = createTextInfoEnqueuer(controller);
+
+    this.parser.onValue = (parsedInfo: ParsedElementInfo) => {
+      // 超时错误特殊处理
+      if (isTimeoutError(parsedInfo.value)) {
+        if (!this.terminated) {
+          enqueue(JSON.stringify(parsedInfo.value), {
+            type: 'agent-error',
+            error: ERROR_MESSAGES.TIMEOUT,
+          });
+          this.terminateStream(controller);
+        }
+        return;
+      }
+
+      this.options.onParseValue({
+        parsedInfo,
+        deltaChunkEnqueuer: enqueue,
+        currentChunkId: this.currentChunkId,
+        ctrl: controller,
+        getResult: () => this.result,
+        clearResult: this.clearResult.bind(this),
+        setPartialResult: (partial) => {
+          this.result = { ...this.result, ...partial };
+        },
+      });
+    };
+
+    this.parser.onError = (err: any) => {
+      if (!this.terminated) {
+        const msg = this.options.onParseError
+          ? this.options.onParseError(err)
+          : ERROR_MESSAGES.GENERAL_ERROR;
+        logger.debug(msg);
+        enqueue('error', { type: 'agent-error', error: msg });
+        this.terminateStream(controller);
+      }
+    };
+
+    this.parser.onEnd = () => {
+      logger.debug('Parsing completed');
+      enqueue(' ', JSON.stringify({ appendConfirm: 'save-fields' }));
+      this.completeParsing();
+    };
+  }
+
+  /** 创建可外部 resolve 的 Promise，用于 flush 等待 parser 回调结束 */
+  private createCompletionPromise(): Promise<void> {
+    return new Promise<void>((resolve) => {
+      this.resolveParseCompleted = () => {
+        resolve();
+        logger.debug('Parsing completion promise resolved');
+      };
+    });
+  }
+
+  private clearResult(): void {
+    this.result = {} as T;
+  }
+
+  /** 标记解析完成，重置状态 */
+  private completeParsing(): void {
+    this.resolveParseCompleted?.();
+    this.parser = null;
+    this.result = {} as T;
+    this.currentChunkId = '';
+    this.parseCompleted = null;
+    this.resolveParseCompleted = null;
+  }
+
+  /** 安全地终止流并清理状态 */
+  private terminateStream(controller: Controller): void {
+    this.completeParsing();
+    this.terminated = true;
+    controller.terminate();
+  }
+
+  /** 向下游推送 agent-error 并终止流 */
+  private enqueueError(controller: Controller, error: unknown): void {
+    if (this.terminated) return;
+    const enqueue = createTextInfoEnqueuer(controller);
+    const msg = typeof error === 'string' ? error : ERROR_MESSAGES.PARSE_ERROR;
+    logger.error('JsonStreamProcessor error: ' + error);
+    // 先 enqueue 错误信息让下游能收到，再 terminate
+    // 注意：不能调 controller.error()，否则流进入 errored 状态，enqueue 不再生效
+    enqueue('error', { type: 'agent-error', error: msg });
+    this.terminateStream(controller);
+  }
+}
+
+/** 默认 chunkGuard：只处理带 delta 的 text-delta chunk */
+function defaultChunkGuard(chunk: LanguageModelV2StreamPart): boolean {
+  return chunk.type === 'text-delta' && 'delta' in chunk;
+}
+
+function isChunkWithDelta(chunk: LanguageModelV2StreamPart): chunk is ChunkWithIdDelta {
+  return 'id' in chunk && 'delta' in chunk;
+}
+
+/** 去掉 AI 返回的代码围栏标记 (```) 和 json 前缀 */
+function stripCodeFence(delta: string): string {
+  return delta.replace(BACKTICK_RE, '').replace(JSON_PREFIX, '');
+}
+
+function isTimeoutError(value: any): boolean {
+  return value?.error === true && value?.errorMessage === 'timeout';
+}