@veltra/ai 2.1.6 → 2.1.8

package/dist/components/ai-orb/style2.css

@@ -14,7 +14,7 @@
 * --u-height-default: 32px;
 * --u-height-small: 24px;
 */
-/** 暗色：data-theme 与系统偏好，与 UITheme.injectBuiltInThemes 选择器策略一致 */
+/** 暗色：`UITheme.render()` 按主题系列写入 html[data-theme] */
 .u-ai-orb {
   display: block;
   flex-shrink: 0;

package/dist/index.d.ts

@@ -1,13 +1,15 @@
 import _sfc_main$1 from "./components/ai-orb/ai-orb.js";
 import _sfc_main from "./components/ai-chat/ai-chat.js";
-import { ChatAttachment, ChatMessage, ChatQueuedMessage, ChatTokenUsage, ChatTool, ChatToolCall, ChatToolContext, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, ToolCallStatus } from "./chat/types.js";
+import { ChatAttachment, ChatJob, ChatJobStatus, ChatMessage, ChatQueuedMessage, ChatTokenUsage, ChatTool, ChatToolCall, ChatToolContext, ChatToolMeta, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, ToolCallStatus } from "./chat/types.js";
+import { AskQuestionAnswer, AskQuestionArgs, AskQuestionItem, AskQuestionResult } from "./tools/ask-question/ask-question.js";
+import "./tools/index.js";
+import { ChatSessionAdapter, ChatSessionEvent, ChatSessionTransport, createServerTransport, isServerTransport } from "./chat/session.js";
 import { ChatModel, ChatModelOption, ChatProvider, ChatReasoningLevel } from "./providers/types.js";
 import { AiChatEmits, AiChatExposed, AiChatProps, _AiChatExposed } from "./types/ai-chat.js";
 import { AiOrbEmits, AiOrbExposed, AiOrbProps, AiOrbReaction, AiOrbStatus } from "./types/ai-orb.js";
 import "./types/index.js";
+import { ChatFoldState, ChatPendingApproval, createFoldState, foldSessionEvent } from "./chat/fold.js";
 import { UseChatOptions, useChat } from "./chat/use-chat.js";
 import { OpenAITransport, OpenAITransportOptions, createOpenAITransport } from "./chat/transports/openai.js";
 import "./chat/index.js";
-import { AskQuestionAnswer, AskQuestionArgs, AskQuestionItem, AskQuestionResult } from "./tools/ask-question/ask-question.js";
-import "./tools/index.js";
-export { type AiChatEmits, type AiChatExposed, type AiChatProps, type AiOrbEmits, type AiOrbExposed, type AiOrbProps, type AiOrbReaction, type AiOrbStatus, type AskQuestionAnswer, type AskQuestionArgs, type AskQuestionItem, type AskQuestionResult, ChatAttachment, ChatMessage, type ChatModel, type ChatModelOption, type ChatProvider, ChatQueuedMessage, type ChatReasoningLevel, ChatTokenUsage, ChatTool, ChatToolCall, ChatToolContext, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, OpenAITransport, OpenAITransportOptions, ToolCallStatus, _sfc_main as UAiChat, _sfc_main$1 as UAiOrb, UseChatOptions, type _AiChatExposed, createOpenAITransport, useChat };
+export { type AiChatEmits, type AiChatExposed, type AiChatProps, type AiOrbEmits, type AiOrbExposed, type AiOrbProps, type AiOrbReaction, type AiOrbStatus, type AskQuestionAnswer, type AskQuestionArgs, type AskQuestionItem, type AskQuestionResult, ChatAttachment, ChatFoldState, ChatJob, ChatJobStatus, ChatMessage, type ChatModel, type ChatModelOption, ChatPendingApproval, type ChatProvider, ChatQueuedMessage, type ChatReasoningLevel, ChatSessionAdapter, ChatSessionEvent, ChatSessionTransport, ChatTokenUsage, ChatTool, ChatToolCall, ChatToolContext, ChatToolMeta, ChatToolRenderProps, ChatTransport, ChatTransportHandlers, ChatTransportRequest, OpenAITransport, OpenAITransportOptions, ToolCallStatus, _sfc_main as UAiChat, _sfc_main$1 as UAiOrb, UseChatOptions, type _AiChatExposed, createFoldState, createOpenAITransport, createServerTransport, foldSessionEvent, isServerTransport, useChat };

package/dist/index.js

@@ -1,5 +1,7 @@
+import { createServerTransport, isServerTransport } from "./chat/session.js";
+import { createFoldState, foldSessionEvent } from "./chat/fold.js";
 import { useChat } from "./chat/use-chat.js";
 import { createOpenAITransport } from "./chat/transports/openai.js";
 import _sfc_main$1 from "./components/ai-orb/ai-orb.js";
 import _sfc_main from "./components/ai-chat/ai-chat.js";
-export { _sfc_main as UAiChat, _sfc_main$1 as UAiOrb, createOpenAITransport, useChat };
+export { _sfc_main as UAiChat, _sfc_main$1 as UAiOrb, createFoldState, createOpenAITransport, createServerTransport, foldSessionEvent, isServerTransport, useChat };

package/dist/tools/ask-question/ask-question.js

@@ -1,5 +1,6 @@
-import { deferAskQuestion, takeAskQuestionDeferred } from "./deferred.js";
 import _sfc_main from "../../components/ai-chat/ask-question.js";
+import { deferAskQuestion, resolveAskQuestion, takeAskQuestionDeferred } from "./deferred.js";
+import { computed, defineComponent, h } from "vue";
 import { QuestionFilled } from "@veltra/icons/normal";
 //#region src/tools/ask-question/ask-question.ts
 const DEFAULT_DESCRIPTION = "当需求不明确或存在歧义时，向用户提问以澄清。一次可提 1-4 个关键问题；每个问题可提供若干预设选项，用户可选择选项或自定义输入。用户作答后再继续生成。";
@@ -33,6 +34,51 @@ const QUESTIONS_SCHEMA = {
 	} },
 	required: ["questions"]
 };
+function parseQuestions(toolCall) {
+	try {
+		const args = JSON.parse(toolCall.arguments || "{}");
+		return Array.isArray(args.questions) ? args.questions : [];
+	} catch {
+		return [];
+	}
+}
+function parseAnswers(toolCall) {
+	if (toolCall.status !== "success" || !toolCall.result) return void 0;
+	try {
+		const result = JSON.parse(toolCall.result);
+		return Array.isArray(result.answers) ? result.answers : void 0;
+	} catch {
+		return;
+	}
+}
+function statusError(toolCall) {
+	if (toolCall.status !== "error") return void 0;
+	const err = toolCall.error ?? "";
+	if (err.includes("Abort") || err.includes("取消")) return "已取消";
+	return err || "提问失败";
+}
+/** 把 toolCall 转成提问表单的 questions / onSubmit；提交仍走 resolveAskQuestion */
+const AskQuestionRender = defineComponent({
+	name: "AskQuestionRender",
+	props: { toolCall: {
+		type: Object,
+		required: true
+	} },
+	setup(props) {
+		const questions = computed(() => parseQuestions(props.toolCall));
+		const answers = computed(() => parseAnswers(props.toolCall));
+		const error = computed(() => statusError(props.toolCall));
+		const onSubmit = (value) => {
+			resolveAskQuestion(props.toolCall.id, { answers: Array.isArray(value) ? value : value.answers });
+		};
+		return () => h(_sfc_main, {
+			questions: questions.value,
+			answers: answers.value,
+			error: error.value,
+			onSubmit
+		});
+	}
+});
 /**
 * 创建内置提问工具：execute 挂起等待用户在 UI 中作答，提交后结果回灌模型。
 * 工具卡片由内联提问表单渲染（多题分页导航，提交后展示问答摘要，不自动折叠）。
@@ -45,7 +91,7 @@ function createAskQuestionTool(options = {}) {
 		parameters: QUESTIONS_SCHEMA,
 		icon,
 		label,
-		render: _sfc_main,
+		render: AskQuestionRender,
 		execute: (_args, { toolCall, signal }) => new Promise((resolve, reject) => {
 			deferAskQuestion(toolCall.id, {
 				resolve,

package/dist/tools/ask-question/ask-question.js.map

@@ -1 +1 @@
-{"version":3,"file":"ask-question.js","names":["AskQuestion"],"sources":["../../../src/tools/ask-question/ask-question.ts"],"sourcesContent":["import { QuestionFilled } from '@veltra/icons/normal'\nimport type { Component } from 'vue'\n\nimport type { ChatTool } from '../../chat/types'\nimport AskQuestion from '../../components/ai-chat/ask-question.vue'\nimport { deferAskQuestion, takeAskQuestionDeferred } from './deferred'\n\n/** 单个提问项 */\nexport interface AskQuestionItem {\n  /** 问题文案 */\n  question: string\n  /** 预设选项（单选）；缺省为纯文本题 */\n  options?: string[]\n  /** 自定义输入占位文案 */\n  placeholder?: string\n}\n\n/** 一条问答结果 */\nexport interface AskQuestionAnswer {\n  /** 问题文案 */\n  question: string\n  /** 用户回答（选中的选项或自定义输入） */\n  answer: string\n}\n\n/** 提问工具参数（模型输出） */\nexport interface AskQuestionArgs {\n  questions: AskQuestionItem[]\n}\n\n/** 提问工具结果（序列化后回灌模型，渲染层据此展示问答摘要） */\nexport interface AskQuestionResult {\n  answers: AskQuestionAnswer[]\n}\n\nexport interface CreateAskQuestionToolOptions {\n  /** 工具名（传给模型），默认 askQuestion */\n  name?: string\n  /** 工具描述（传给模型） */\n  description?: string\n  /** 工具显示名，默认「提问」 */\n  label?: string\n  /** 工具图标，默认 QuestionFilled */\n  icon?: Component\n}\n\nconst DEFAULT_DESCRIPTION =\n  '当需求不明确或存在歧义时，向用户提问以澄清。一次可提 1-4 个关键问题；' +\n  '每个问题可提供若干预设选项，用户可选择选项或自定义输入。用户作答后再继续生成。'\n\n/** 提问参数 JSON Schema（原样传给模型） */\nconst QUESTIONS_SCHEMA: Record<string, unknown> = {\n  type: 'object',\n  properties: {\n    questions: {\n      type: 'array',\n      description: '问题列表',\n      minItems: 1,\n      maxItems: 4,\n      items: {\n        type: 'object',\n        properties: {\n          question: { type: 'string', description: '问题文案' },\n          options: {\n            type: 'array',\n            description: '预设选项（单选）；缺省为纯文本题',\n            items: { type: 'string' }\n          },\n          placeholder: { type: 'string', description: '自定义输入占位文案' }\n        },\n        required: ['question']\n      }\n    }\n  },\n  required: ['questions']\n}\n\n/**\n * 创建内置提问工具：execute 挂起等待用户在 UI 中作答，提交后结果回灌模型。\n * 工具卡片由内联提问表单渲染（多题分页导航，提交后展示问答摘要，不自动折叠）。\n */\nexport function createAskQuestionTool(\n  options: CreateAskQuestionToolOptions = {}\n): ChatTool<AskQuestionArgs> {\n  const {\n    name = 'askQuestion',\n    description = DEFAULT_DESCRIPTION,\n    label = '提问',\n    icon = QuestionFilled\n  } = options\n\n  return {\n    name,\n    description,\n    parameters: QUESTIONS_SCHEMA,\n    icon,\n    label,\n    render: AskQuestion,\n    execute: (_args, { toolCall, signal }) =>\n      new Promise<AskQuestionResult>((resolve, reject) => {\n        deferAskQuestion(toolCall.id, { resolve, reject })\n        signal.addEventListener(\n          'abort',\n          () => {\n            // 不依赖 signal.reason（各环境 DOMException 行为不一），统一拒绝为 AbortError\n            const error = new Error('Aborted')\n            error.name = 'AbortError'\n            takeAskQuestionDeferred(toolCall.id)?.reject(error)\n          },\n          { once: true }\n        )\n      })\n  }\n}\n"],"mappings":";;;;AA8CA,MAAM,sBACJ;;AAIF,MAAM,mBAA4C;CAChD,MAAM;CACN,YAAY,EACV,WAAW;EACT,MAAM;EACN,aAAa;EACb,UAAU;EACV,UAAU;EACV,OAAO;GACL,MAAM;GACN,YAAY;IACV,UAAU;KAAE,MAAM;KAAU,aAAa;IAAO;IAChD,SAAS;KACP,MAAM;KACN,aAAa;KACb,OAAO,EAAE,MAAM,SAAS;IAC1B;IACA,aAAa;KAAE,MAAM;KAAU,aAAa;IAAY;GAC1D;GACA,UAAU,CAAC,UAAU;EACvB;CACF,EACF;CACA,UAAU,CAAC,WAAW;AACxB;;;;;AAMA,SAAgB,sBACd,UAAwC,CAAC,GACd;CAC3B,MAAM,EACJ,OAAO,eACP,cAAc,qBACd,QAAQ,MACR,OAAO,mBACL;CAEJ,OAAO;EACL;EACA;EACA,YAAY;EACZ;EACA;EACA,QAAQA;EACR,UAAU,OAAO,EAAE,UAAU,aAC3B,IAAI,SAA4B,SAAS,WAAW;GAClD,iBAAiB,SAAS,IAAI;IAAE;IAAS;GAAO,CAAC;GACjD,OAAO,iBACL,eACM;IAEJ,MAAM,wBAAQ,IAAI,MAAM,SAAS;IACjC,MAAM,OAAO;IACb,wBAAwB,SAAS,EAAE,CAAC,EAAE,OAAO,KAAK;GACpD,GACA,EAAE,MAAM,KAAK,CACf;EACF,CAAC;CACL;AACF"}
+{"version":3,"file":"ask-question.js","names":["AskQuestion"],"sources":["../../../src/tools/ask-question/ask-question.ts"],"sourcesContent":["import { QuestionFilled } from '@veltra/icons/normal'\nimport { computed, defineComponent, h, type Component, type PropType } from 'vue'\n\nimport type { ChatTool, ChatToolCall } from '../../chat/types'\nimport AskQuestion from '../../components/ai-chat/ask-question.vue'\nimport { deferAskQuestion, resolveAskQuestion, takeAskQuestionDeferred } from './deferred'\n\n/** 单个提问项 */\nexport interface AskQuestionItem {\n  /** 问题文案 */\n  question: string\n  /** 预设选项（单选）；缺省为纯文本题 */\n  options?: string[]\n  /** 自定义输入占位文案 */\n  placeholder?: string\n}\n\n/** 一条问答结果 */\nexport interface AskQuestionAnswer {\n  /** 问题文案 */\n  question: string\n  /** 用户回答（选中的选项或自定义输入） */\n  answer: string\n}\n\n/** 提问工具参数（模型输出） */\nexport interface AskQuestionArgs {\n  questions: AskQuestionItem[]\n}\n\n/** 提问工具结果（序列化后回灌模型，渲染层据此展示问答摘要） */\nexport interface AskQuestionResult {\n  answers: AskQuestionAnswer[]\n}\n\nexport interface CreateAskQuestionToolOptions {\n  /** 工具名（传给模型），默认 askQuestion */\n  name?: string\n  /** 工具描述（传给模型） */\n  description?: string\n  /** 工具显示名，默认「提问」 */\n  label?: string\n  /** 工具图标，默认 QuestionFilled */\n  icon?: Component\n}\n\nconst DEFAULT_DESCRIPTION =\n  '当需求不明确或存在歧义时，向用户提问以澄清。一次可提 1-4 个关键问题；' +\n  '每个问题可提供若干预设选项，用户可选择选项或自定义输入。用户作答后再继续生成。'\n\n/** 提问参数 JSON Schema（原样传给模型） */\nconst QUESTIONS_SCHEMA: Record<string, unknown> = {\n  type: 'object',\n  properties: {\n    questions: {\n      type: 'array',\n      description: '问题列表',\n      minItems: 1,\n      maxItems: 4,\n      items: {\n        type: 'object',\n        properties: {\n          question: { type: 'string', description: '问题文案' },\n          options: {\n            type: 'array',\n            description: '预设选项（单选）；缺省为纯文本题',\n            items: { type: 'string' }\n          },\n          placeholder: { type: 'string', description: '自定义输入占位文案' }\n        },\n        required: ['question']\n      }\n    }\n  },\n  required: ['questions']\n}\n\nfunction parseQuestions(toolCall: ChatToolCall): AskQuestionItem[] {\n  try {\n    const args = JSON.parse(toolCall.arguments || '{}') as Partial<AskQuestionArgs>\n    return Array.isArray(args.questions) ? args.questions : []\n  } catch {\n    return []\n  }\n}\n\nfunction parseAnswers(toolCall: ChatToolCall): AskQuestionAnswer[] | undefined {\n  if (toolCall.status !== 'success' || !toolCall.result) return undefined\n  try {\n    const result = JSON.parse(toolCall.result) as Partial<AskQuestionResult>\n    return Array.isArray(result.answers) ? result.answers : undefined\n  } catch {\n    return undefined\n  }\n}\n\nfunction statusError(toolCall: ChatToolCall): string | undefined {\n  if (toolCall.status !== 'error') return undefined\n  const err = toolCall.error ?? ''\n  if (err.includes('Abort') || err.includes('取消')) return '已取消'\n  return err || '提问失败'\n}\n\n/** 把 toolCall 转成提问表单的 questions / onSubmit；提交仍走 resolveAskQuestion */\nconst AskQuestionRender = defineComponent({\n  name: 'AskQuestionRender',\n  props: { toolCall: { type: Object as PropType<ChatToolCall>, required: true } },\n  setup(props) {\n    const questions = computed(() => parseQuestions(props.toolCall))\n    const answers = computed(() => parseAnswers(props.toolCall))\n    const error = computed(() => statusError(props.toolCall))\n    const onSubmit = (value: AskQuestionAnswer[] | AskQuestionResult) => {\n      resolveAskQuestion(props.toolCall.id, {\n        answers: Array.isArray(value) ? value : value.answers\n      })\n    }\n    return () =>\n      h(AskQuestion, {\n        questions: questions.value,\n        answers: answers.value,\n        error: error.value,\n        onSubmit\n      })\n  }\n})\n\n/**\n * 创建内置提问工具：execute 挂起等待用户在 UI 中作答，提交后结果回灌模型。\n * 工具卡片由内联提问表单渲染（多题分页导航，提交后展示问答摘要，不自动折叠）。\n */\nexport function createAskQuestionTool(\n  options: CreateAskQuestionToolOptions = {}\n): ChatTool<AskQuestionArgs> {\n  const {\n    name = 'askQuestion',\n    description = DEFAULT_DESCRIPTION,\n    label = '提问',\n    icon = QuestionFilled\n  } = options\n\n  return {\n    name,\n    description,\n    parameters: QUESTIONS_SCHEMA,\n    icon,\n    label,\n    render: AskQuestionRender,\n    execute: (_args, { toolCall, signal }) =>\n      new Promise<AskQuestionResult>((resolve, reject) => {\n        deferAskQuestion(toolCall.id, { resolve, reject })\n        signal.addEventListener(\n          'abort',\n          () => {\n            // 不依赖 signal.reason（各环境 DOMException 行为不一），统一拒绝为 AbortError\n            const error = new Error('Aborted')\n            error.name = 'AbortError'\n            takeAskQuestionDeferred(toolCall.id)?.reject(error)\n          },\n          { once: true }\n        )\n      })\n  }\n}\n"],"mappings":";;;;;AA8CA,MAAM,sBACJ;;AAIF,MAAM,mBAA4C;CAChD,MAAM;CACN,YAAY,EACV,WAAW;EACT,MAAM;EACN,aAAa;EACb,UAAU;EACV,UAAU;EACV,OAAO;GACL,MAAM;GACN,YAAY;IACV,UAAU;KAAE,MAAM;KAAU,aAAa;IAAO;IAChD,SAAS;KACP,MAAM;KACN,aAAa;KACb,OAAO,EAAE,MAAM,SAAS;IAC1B;IACA,aAAa;KAAE,MAAM;KAAU,aAAa;IAAY;GAC1D;GACA,UAAU,CAAC,UAAU;EACvB;CACF,EACF;CACA,UAAU,CAAC,WAAW;AACxB;AAEA,SAAS,eAAe,UAA2C;CACjE,IAAI;EACF,MAAM,OAAO,KAAK,MAAM,SAAS,aAAa,IAAI;EAClD,OAAO,MAAM,QAAQ,KAAK,SAAS,IAAI,KAAK,YAAY,CAAC;CAC3D,QAAQ;EACN,OAAO,CAAC;CACV;AACF;AAEA,SAAS,aAAa,UAAyD;CAC7E,IAAI,SAAS,WAAW,aAAa,CAAC,SAAS,QAAQ,OAAO,KAAA;CAC9D,IAAI;EACF,MAAM,SAAS,KAAK,MAAM,SAAS,MAAM;EACzC,OAAO,MAAM,QAAQ,OAAO,OAAO,IAAI,OAAO,UAAU,KAAA;CAC1D,QAAQ;EACN;CACF;AACF;AAEA,SAAS,YAAY,UAA4C;CAC/D,IAAI,SAAS,WAAW,SAAS,OAAO,KAAA;CACxC,MAAM,MAAM,SAAS,SAAS;CAC9B,IAAI,IAAI,SAAS,OAAO,KAAK,IAAI,SAAS,IAAI,GAAG,OAAO;CACxD,OAAO,OAAO;AAChB;;AAGA,MAAM,oBAAoB,gBAAgB;CACxC,MAAM;CACN,OAAO,EAAE,UAAU;EAAE,MAAM;EAAkC,UAAU;CAAK,EAAE;CAC9E,MAAM,OAAO;EACX,MAAM,YAAY,eAAe,eAAe,MAAM,QAAQ,CAAC;EAC/D,MAAM,UAAU,eAAe,aAAa,MAAM,QAAQ,CAAC;EAC3D,MAAM,QAAQ,eAAe,YAAY,MAAM,QAAQ,CAAC;EACxD,MAAM,YAAY,UAAmD;GACnE,mBAAmB,MAAM,SAAS,IAAI,EACpC,SAAS,MAAM,QAAQ,KAAK,IAAI,QAAQ,MAAM,QAChD,CAAC;EACH;EACA,aACE,EAAEA,WAAa;GACb,WAAW,UAAU;GACrB,SAAS,QAAQ;GACjB,OAAO,MAAM;GACb;EACF,CAAC;CACL;AACF,CAAC;;;;;AAMD,SAAgB,sBACd,UAAwC,CAAC,GACd;CAC3B,MAAM,EACJ,OAAO,eACP,cAAc,qBACd,QAAQ,MACR,OAAO,mBACL;CAEJ,OAAO;EACL;EACA;EACA,YAAY;EACZ;EACA;EACA,QAAQ;EACR,UAAU,OAAO,EAAE,UAAU,aAC3B,IAAI,SAA4B,SAAS,WAAW;GAClD,iBAAiB,SAAS,IAAI;IAAE;IAAS;GAAO,CAAC;GACjD,OAAO,iBACL,eACM;IAEJ,MAAM,wBAAQ,IAAI,MAAM,SAAS;IACjC,MAAM,OAAO;IACb,wBAAwB,SAAS,EAAE,CAAC,EAAE,OAAO,KAAK;GACpD,GACA,EAAE,MAAM,KAAK,CACf;EACF,CAAC;CACL;AACF"}

package/dist/types/ai-chat.d.ts

@@ -1,13 +1,17 @@
-import { ChatAttachment, ChatMessage, ChatQueuedMessage, ChatTokenUsage, ChatTool, ChatToolCall, ChatTransport } from "../chat/types.js";
+import { ChatAttachment, ChatMessage, ChatQueuedMessage, ChatTokenUsage, ChatTool, ChatToolCall, ChatToolMeta, ChatTransport } from "../chat/types.js";
+import { ChatSessionTransport } from "../chat/session.js";
 import { ChatModelOption } from "../providers/types.js";
-import { Ref } from "vue";
+import { Component, Ref } from "vue";
 import { DeconstructValue } from "@veltra/utils";
 //#region src/types/ai-chat.d.ts
 interface AiChatProps {
-  /** 传输层（必填），可使用导出的 createOpenAITransport() 创建 */
-  transport: ChatTransport;
-  /** 工具定义列表，不同场景传入不同工具赋予助手不同能力 */
-  tools?: ChatTool[];
+  /** 传输层（必填）；函数型 ChatTransport 或 session 对象，可使用 createOpenAITransport / createServerTransport */
+  transport: ChatTransport | ChatSessionTransport;
+  /**
+   * 工具列表。函数 transport 传入 ChatTool[]（必有 execute）；
+   * session 下可为 ChatToolMeta[]（仅渲染元信息）。ChatTool[] 仍可赋值。
+   */
+  tools?: (ChatTool | ChatToolMeta)[];
   /** 系统提示词 */
   systemPrompt?: string;
   /**
@@ -41,6 +45,13 @@ interface AiChatProps {
    * 默认 false：仅在拿到 usage 时显示会话累计「总 token」。接口未返回 usage 时不展示。
    */
   tokenUsageDetail?: boolean;
+  /**
+   * 覆盖包内 toolName → icon 映射（精确名优先于内置名称规则）。
+   * 缺省不传则走内置表；未命中的名称仍用兜底图标，不得 throw。
+   */
+  toolIcons?: Record<string, Component>;
+  /** 只读：不展示输入区、欢迎语不可发送、队列无插队/编辑/移除。默认 false */
+  readonly?: boolean;
 }
 interface AiChatEmits {
   /** 消息列表变化 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veltra/ai",
-  "version": "2.1.6",
+  "version": "2.1.8",
   "homepage": "https://github.com/cabinet-fe/ultra-ui#readme",
   "bugs": {
     "url": "https://github.com/cabinet-fe/ultra-ui/issues"
@@ -36,14 +36,14 @@
     }
   },
   "dependencies": {
-    "markstream-vue": "^2.0.0"
+    "markstream-vue": "^2.0.8"
   },
   "peerDependencies": {
-    "@veltra/compositions": "^1.6.4",
-    "@veltra/desktop": "^1.6.4",
+    "@veltra/compositions": "^1.7.9",
+    "@veltra/desktop": "^1.7.9",
     "@veltra/icons": "^1.5.0",
-    "@veltra/styles": "^1.6.4",
-    "@veltra/utils": "^1.6.4",
-    "vue": ">=3.5.41"
+    "@veltra/styles": "^1.7.9",
+    "@veltra/utils": "^1.7.9",
+    "vue": ">=3.5.42"
   }
 }

package/src/chat/__test__/fold.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest'
+
+import { createFoldState, foldSessionEvent } from '../fold'
+import type { ChatSessionEvent } from '../session'
+
+const foldAll = (events: ChatSessionEvent[]) => events.reduce(foldSessionEvent, createFoldState())
+
+describe('foldSessionEvent', () => {
+  it('user/message 按服务端回显追加，不制造本地占位', () => {
+    const state = foldAll([{ type: 'user/message', messageId: 'u1', seq: 1, content: '你好' }])
+    expect(state.messages).toEqual([{ id: 'u1', role: 'user', content: '你好' }])
+  })
+
+  it('assistant/chunk 按 messageId 累积 content 与 reasoning', () => {
+    const state = foldAll([
+      { type: 'assistant/chunk', messageId: 'a1', seq: 1, delta: '你', reasoningDelta: '想' },
+      { type: 'assistant/chunk', messageId: 'a1', seq: 2, delta: '好', reasoningDelta: '一下' }
+    ])
+    expect(state.messages).toHaveLength(1)
+    expect(state.messages[0]).toMatchObject({
+      id: 'a1',
+      role: 'assistant',
+      content: '你好',
+      reasoning: '想一下',
+      status: 'streaming'
+    })
+  })
+
+  it('assistant/message 定稿内容与状态', () => {
+    const state = foldAll([
+      { type: 'assistant/chunk', messageId: 'a1', seq: 1, delta: '草' },
+      {
+        type: 'assistant/message',
+        messageId: 'a1',
+        seq: 2,
+        content: '你好世界',
+        reasoning: '想完了'
+      }
+    ])
+    expect(state.messages[0]).toMatchObject({
+      id: 'a1',
+      content: '你好世界',
+      reasoning: '想完了',
+      status: 'done'
+    })
+  })
+
+  it('tool/call 追加 pending 的 ChatToolCall 并保留 view', () => {
+    const view = { preview: 'ls' }
+    const state = foldAll([
+      { type: 'assistant/chunk', messageId: 'a1', seq: 1, delta: '' },
+      { type: 'tool/call', callId: 'c1', name: 'bash', arguments: '{"cmd":"ls"}', seq: 2, view }
+    ])
+    expect(state.messages[0]?.toolCalls).toEqual([
+      { id: 'c1', name: 'bash', arguments: '{"cmd":"ls"}', status: 'pending', view }
+    ])
+  })
+
+  it('tool/result 按 callId 更新 status / result / error / view', () => {
+    const state = foldAll([
+      { type: 'tool/call', callId: 'c1', name: 'bash', arguments: '{}', seq: 1, view: { step: 1 } },
+      {
+        type: 'tool/result',
+        callId: 'c1',
+        status: 'error',
+        result: 'out',
+        error: 'boom',
+        seq: 2,
+        view: { step: 2 }
+      }
+    ])
+    expect(state.messages[0]?.toolCalls?.[0]).toMatchObject({
+      id: 'c1',
+      status: 'error',
+      result: 'out',
+      error: 'boom',
+      view: { step: 2 }
+    })
+  })
+
+  it('queue/snapshot 与 jobs/snapshot 整体替换', () => {
+    const state = foldAll([
+      { type: 'queue/snapshot', items: [{ id: 'q1', content: '旧' }] },
+      {
+        type: 'jobs/snapshot',
+        jobs: [{ id: 'j1', kind: 'bash', label: '旧作业', status: 'running' }]
+      },
+      { type: 'queue/snapshot', items: [{ id: 'q2', content: '新' }] },
+      { type: 'jobs/snapshot', jobs: [{ id: 'j2', kind: 'web', label: '新作业', status: 'done' }] }
+    ])
+    expect(state.queue).toEqual([{ id: 'q2', content: '新' }])
+    expect(state.jobs).toEqual([{ id: 'j2', kind: 'web', label: '新作业', status: 'done' }])
+  })
+
+  it('projection：tokenUsage 合并、title 取出、其余进 projections', () => {
+    const state = foldAll([
+      {
+        type: 'projection',
+        key: 'tokenUsage',
+        seq: 1,
+        value: { promptTokens: 1, completionTokens: 2, totalTokens: 3 }
+      },
+      {
+        type: 'projection',
+        key: 'tokenUsage',
+        seq: 2,
+        value: { promptTokens: 4, completionTokens: 5, totalTokens: 9 }
+      },
+      { type: 'projection', key: 'title', seq: 3, value: '会话标题' },
+      { type: 'projection', key: 'extra', seq: 4, value: { n: 1 } }
+    ])
+    expect(state.tokenUsage).toEqual({ promptTokens: 5, completionTokens: 7, totalTokens: 12 })
+    expect(state.title).toBe('会话标题')
+    expect(state.projections).toEqual({ extra: { n: 1 } })
+    expect(state.projections).not.toHaveProperty('title')
+    expect(state.projections).not.toHaveProperty('tokenUsage')
+  })
+
+  it('乱序 seq 不覆盖已应用事件', () => {
+    const applied = foldSessionEvent(createFoldState(), {
+      type: 'user/message',
+      messageId: 'u2',
+      seq: 2,
+      content: '后到的先到'
+    })
+    const skipped = foldSessionEvent(applied, {
+      type: 'user/message',
+      messageId: 'u1',
+      seq: 1,
+      content: '乱序应丢弃'
+    })
+    expect(skipped).toBe(applied)
+    expect(skipped.messages).toEqual([{ id: 'u2', role: 'user', content: '后到的先到' }])
+    expect(skipped.lastSeq).toBe(2)
+  })
+})

package/src/chat/__test__/session.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { createFoldState, foldSessionEvent } from '../fold'
+import * as chat from '../index'
+import {
+  createServerTransport,
+  isServerTransport,
+  type ChatSessionAdapter,
+  type ChatSessionEvent
+} from '../session'
+
+function createFakeAdapter(options?: {
+  catchUp?: ChatSessionEvent[]
+}): ChatSessionAdapter & {
+  emit: (event: ChatSessionEvent) => void
+  disconnect: () => void
+  unsubscribed: () => boolean
+} {
+  let listener: { onEvent(event: ChatSessionEvent): void; onDisconnect?(): void } | undefined
+  let unsubscribed = false
+
+  const adapter: ChatSessionAdapter = {
+    subscribe(handlers) {
+      listener = handlers
+      return () => {
+        unsubscribed = true
+        listener = undefined
+      }
+    },
+    send: vi.fn(async () => {}),
+    cancel: vi.fn(async () => {}),
+    respond: vi.fn(async () => {}),
+    fetchHistory: vi.fn(async () => ({ events: options?.catchUp ?? [], hasMore: false })),
+    selectModel: vi.fn(async () => {})
+  }
+
+  return Object.assign(adapter, {
+    emit(event: ChatSessionEvent) {
+      listener?.onEvent(event)
+    },
+    disconnect() {
+      listener?.onDisconnect?.()
+    },
+    unsubscribed: () => unsubscribed
+  })
+}
+
+describe('isServerTransport', () => {
+  it('仅对 kind: session 的对象为 true', () => {
+    const transport = createServerTransport(createFakeAdapter())
+    expect(transport.kind).toBe('session')
+    expect(isServerTransport(transport)).toBe(true)
+    expect(isServerTransport({ kind: 'session' })).toBe(true)
+    expect(isServerTransport(() => {})).toBe(false)
+    expect(isServerTransport(null)).toBe(false)
+    expect(isServerTransport(undefined)).toBe(false)
+    expect(isServerTransport({})).toBe(false)
+    expect(isServerTransport({ kind: 'client' })).toBe(false)
+  })
+})
+
+describe('createServerTransport', () => {
+  it('主入口导出 A1 符号且不导出 createBedrockTransport', () => {
+    expect(chat.createServerTransport).toBeTypeOf('function')
+    expect(chat.isServerTransport).toBeTypeOf('function')
+    expect(chat.foldSessionEvent).toBeTypeOf('function')
+    expect(chat.createFoldState).toBeTypeOf('function')
+    expect('createBedrockTransport' in chat).toBe(false)
+  })
+
+  it('后到的更小 seq 丢弃且 console.warn，不打乱已折叠状态', () => {
+    const adapter = createFakeAdapter()
+    const transport = createServerTransport(adapter)
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    let state = createFoldState()
+    transport.open({
+      onEvent(event) {
+        state = foldSessionEvent(state, event)
+      }
+    })
+
+    adapter.emit({ type: 'user/message', messageId: 'u2', seq: 2, content: '先到' })
+    adapter.emit({ type: 'user/message', messageId: 'u1', seq: 1, content: '乱序' })
+
+    expect(warn).toHaveBeenCalledTimes(1)
+    expect(warn.mock.calls[0]?.[0]).toMatch(/丢弃乱序事件/)
+    expect(state.messages).toHaveLength(1)
+    expect(state.messages[0]).toMatchObject({ id: 'u2', content: '先到' })
+    warn.mockRestore()
+  })
+
+  it('open 的 disposer 释放订阅', () => {
+    const adapter = createFakeAdapter()
+    const transport = createServerTransport(adapter)
+    const onEvent = vi.fn()
+    const dispose = transport.open({ onEvent })
+
+    adapter.emit({ type: 'finish' })
+    expect(onEvent).toHaveBeenCalledTimes(1)
+
+    dispose()
+    expect(adapter.unsubscribed()).toBe(true)
+    adapter.emit({ type: 'finish' })
+    adapter.disconnect()
+    expect(onEvent).toHaveBeenCalledTimes(1)
+    expect(adapter.fetchHistory).not.toHaveBeenCalled()
+  })
+
+  it('断开后 fetchHistory(lastSeq) 补拉再 fold', async () => {
+    const catchUp: ChatSessionEvent[] = [
+      { type: 'user/message', messageId: 'u2', seq: 2, content: '补拉' }
+    ]
+    const adapter = createFakeAdapter({ catchUp })
+    const transport = createServerTransport(adapter)
+    let state = createFoldState()
+    const onDisconnect = vi.fn()
+    transport.open({
+      onEvent(event) {
+        state = foldSessionEvent(state, event)
+      },
+      onDisconnect
+    })
+
+    adapter.emit({ type: 'user/message', messageId: 'u1', seq: 1, content: '已有' })
+    adapter.disconnect()
+
+    await vi.waitFor(() => {
+      expect(adapter.fetchHistory).toHaveBeenCalledWith(1)
+      expect(state.messages.map((m) => m.id)).toEqual(['u1', 'u2'])
+      expect(onDisconnect).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  it('send / cancel / respond / selectModel 同一动作未完成时忽略重复调用', async () => {
+    const adapter = createFakeAdapter()
+    let releaseSend!: () => void
+    let releaseCancel!: () => void
+    let releaseRespond!: () => void
+    let releaseSelect!: () => void
+    adapter.send = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          releaseSend = resolve
+        })
+    )
+    adapter.cancel = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          releaseCancel = resolve
+        })
+    )
+    adapter.respond = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          releaseRespond = resolve
+        })
+    )
+    adapter.selectModel = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          releaseSelect = resolve
+        })
+    )
+
+    const transport = createServerTransport(adapter)
+
+    const send1 = transport.send('a')
+    const send2 = transport.send('b')
+    expect(adapter.send).toHaveBeenCalledTimes(1)
+    releaseSend()
+    await Promise.all([send1, send2])
+
+    const cancel1 = transport.cancel()
+    const cancel2 = transport.cancel()
+    expect(adapter.cancel).toHaveBeenCalledTimes(1)
+    releaseCancel()
+    await Promise.all([cancel1, cancel2])
+
+    const respond1 = transport.respond('rpc-1', true)
+    const respond2 = transport.respond('rpc-2', false)
+    expect(adapter.respond).toHaveBeenCalledTimes(1)
+    releaseRespond()
+    await Promise.all([respond1, respond2])
+
+    const select1 = transport.selectModel('p', 'm1')
+    const select2 = transport.selectModel('p', 'm2')
+    expect(adapter.selectModel).toHaveBeenCalledTimes(1)
+    releaseSelect()
+    await Promise.all([select1, select2])
+  })
+})