@blueking/chat-x 0.0.49-beta.9 → 0.0.51-beta.1

package/dist/mcp/generated/docs/use-artifact-preview.md

@@ -75,32 +75,30 @@ const { addCustomTab, ensureCustomTab, removeCustomTab } = useCustomTabProvider(
 // 会话级文件产物聚合已内聚在 useMessageGroup，直接消费
 const { sessionArtifacts } = useMessageGroup({ keyword, messages, selectedUserMessages });
 
+const FILE_ARTIFACT_TAB = {
+  closable: false,
+  label: t('文件产物'),
+  name: FILE_ARTIFACT_TAB_NAME,
+  order: -1,
+};
+
+// 常驻挂载：不随产物有无增删，无产物时由面板展示空态
+ensureCustomTab(FILE_ARTIFACT_TAB);
+
 const { activeArtifactId, setActiveArtifactId } = useArtifactPreviewProvider({
   getOnArtifactClick: () => props.onArtifactClick,
   // 点击文件卡片：展开侧栏并选中「文件产物」Tab
   onOpen: () => {
-    addCustomTab({
-      closable: false,
-      label: t('文件产物'),
-      name: FILE_ARTIFACT_TAB_NAME,
-      order: -1,
-    });
+    addCustomTab(FILE_ARTIFACT_TAB);
   },
 });
 
-// 有产物时静默挂上 Tab（不抢焦点）；无产物时清理
+// 仅维护命中态：无产物清空，命中项失效时回落到第一个
 watch(sessionArtifacts, list => {
   if (!list.length) {
-    removeCustomTab(FILE_ARTIFACT_TAB_NAME);
     setActiveArtifactId('');
     return;
   }
-  ensureCustomTab({
-    closable: false,
-    label: t('文件产物'),
-    name: FILE_ARTIFACT_TAB_NAME,
-    order: -1,
-  });
   if (!list.some(item => item.outputId === activeArtifactId.value)) {
     setActiveArtifactId(list[0].outputId);
   }
@@ -211,8 +209,12 @@ ArtifactFileCard（点击）
                  └─ FileArtifactPanel（列表 + 下载头，@select → setActiveArtifactId）
                       └─ ArtifactPreviewHost（loader + 分类型 renderer）
 
-sessionArtifacts 变化（有产物）
-  └─ ensureCustomTab(FILE_ARTIFACT_TAB_NAME) 静默挂上，不抢当前选中（如执行情况）
+容器初始化
+  └─ ensureCustomTab(FILE_ARTIFACT_TAB_NAME) 常驻挂上（不展开侧栏）；因 order:-1 排在首位，
+     未主动切换过 Tab 时会成为默认选中面板；无产物时由面板展示整块空态
+
+sessionArtifacts 变化
+  └─ 仅维护命中态（无产物清空，命中项失效回落第一个）；不增删 Tab
 ```
 
 分类型预览策略见 [FileArtifactPanel 预览机制](../components/message/file-artifact-panel#预览机制)。
@@ -222,7 +224,7 @@ sessionArtifacts 变化（有产物）
 - **职责单一**：composable 不直接调用 `useCustomTab`，侧栏 Tab 打开逻辑由 `onOpen` 注入；也不做正文 fetch / iframe 渲染
 - **ShallowRef 优先**：`activeArtifactId` 使用 `shallowRef`，避免不必要的深层响应式开销
 - **Consumer 兜底**：`useArtifactPreviewConsumer` 无 Provider 时返回 `undefined`，文件卡片在无容器上下文时自动不可点击
-- **与 useCustomTab 协作**：点击卡片走 `addCustomTab`（展开 + 选中）；会话已有产物时走 `ensureCustomTab`（只挂载，不抢焦点）；无文件产物时由容器 `removeCustomTab` 清理
+- **与 useCustomTab 协作**：点击卡片走 `addCustomTab`（展开 + 选中）；容器初始化时走 `ensureCustomTab` 常驻挂载（不展开；因 `order: -1` 在未主动切换前会成为默认选中），无产物也不移除，由面板展示空态
 
 ## 关联组件
 

package/dist/mcp/generated/docs/use-custom-tab.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-useCustomTabProvider 返回 tabs、selectedTab、isCollapse 及 add/ensure/remove/selectCustomTab，并通过 provide 共享；可选 onTabChange 在切换时拉取数据。 ensureCustomTab 只挂载/合并元信息，不展开侧栏、不切换选中；addCustomTab 会展开并选中。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。
+useCustomTabProvider 返回 tabs、selectedTab、isCollapse 及 add/ensure/remove/selectCustomTab，并通过 provide 共享；可选 onTabChange 在切换时拉取数据、可选 collapsed 注入受控折叠态 ref。 ensureCustomTab 只挂载/合并元信息，不展开侧栏、不主动切换选中；addCustomTab 会展开并选中。 未被主动切换过时，选中态默认跟随 Tab 栏首位（order 最小），如常驻的「文件产物」。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。
 
 ### 关联组件
 - **chat-container** — Provider 与侧栏 Tab 主场景
@@ -21,6 +21,8 @@ Provider/Consumer 模式的自定义 Tab 管理，用于 `ChatContainer` 侧边
 
 ```typescript
 function useCustomTabProvider<T extends Record<string, unknown>>(options: {
+  // 侧栏折叠态；由容器传入受控 ref（如 ChatContainer 的 v-model:asideCollapsed），缺省内部自持
+  collapsed?: Ref<boolean>;
   // 执行情况 Tab 是否展示，缺省 true；传 getter 以保持响应式
   executionTabVisible?: () => boolean | undefined;
   onTabChange?: (tab: CustomTab<T>) => void;
@@ -28,7 +30,7 @@ function useCustomTabProvider<T extends Record<string, unknown>>(options: {
   tabs: ShallowRef<CustomTab<T>[]>;
   displayTabs: ComputedRef<CustomTab<T>[]>;
   selectedTab: Ref<CustomTab<T>>;
-  isCollapse: ShallowRef<boolean>;
+  isCollapse: Ref<boolean>;
   addCustomTab: (tab: CustomTab<T>) => void;
   ensureCustomTab: (tab: CustomTab<T>) => void;
   removeCustomTab: (tabName: string) => void;
@@ -88,7 +90,7 @@ tabManager?.addCustomTab({
   },
 });
 
-// 仅确保 Tab 存在（不展开、不切换选中）—— 如侧栏已因执行情况打开时同步挂上文件产物
+// 仅确保 Tab 存在（不展开、不切换选中）—— 如常驻挂上文件产物 Tab
 tabManager?.ensureCustomTab({
   name: 'file-artifact',
   label: '文件产物',
@@ -114,10 +116,10 @@ tabManager?.removeCustomTab('node-detail-123');
 | --------------- | --------------------------- | ------------------------------------------------- |
 | tabs            | `ShallowRef<CustomTab[]>`   | 所有 Tab 列表（含默认的执行情况 Tab，保留隐藏项） |
 | displayTabs     | `ComputedRef<CustomTab[]>`  | Tab 栏实际展示列表：过滤 `visible === false`，按 `order` 升序稳定排序 |
-| selectedTab     | `Ref<CustomTab>`            | 当前选中的 Tab；选中项被隐藏时自动回退到首个可见 Tab |
-| isCollapse      | `ShallowRef<boolean>`       | 侧边栏折叠状态；`addCustomTab` 时自动设为 `false` |
+| selectedTab     | `Ref<CustomTab>`            | 当前选中的 Tab；未被主动切换过时跟随 Tab 栏首位，选中项被隐藏时自动回退到首个可见 Tab |
+| isCollapse      | `Ref<boolean>`              | 侧边栏折叠状态；传入 `collapsed` 时即该受控 ref（读写都作用于外部），否则为内部状态；`addCustomTab` 时自动设为 `false` |
 | addCustomTab    | `(tab: CustomTab) => void`  | 添加/合并 Tab，**展开侧栏并选中**目标 Tab |
-| ensureCustomTab | `(tab: CustomTab) => void`  | 添加/合并 Tab，**不展开、不切换选中**；用于静默挂载（如文件产物） |
+| ensureCustomTab | `(tab: CustomTab) => void`  | 添加/合并 Tab，**不展开、不主动切换选中**；用于常驻挂载（如文件产物） |
 | removeCustomTab | `(tabName: string) => void` | 移除指定 Tab                                      |
 | selectCustomTab | `(tab: CustomTab) => void`  | 切换到指定 Tab，触发 `onTabChange` 回调           |
 | resetCustomTab  | `() => void`                  | 重置为仅保留「执行情况」Tab、折叠侧栏并选中默认 Tab；`ChatContainer` 在卸载时调用，避免残留自定义 Tab |
@@ -147,9 +149,11 @@ interface CustomTab<T = Record<string, unknown>> {
 - 排序为稳定排序，`order` 相同的 Tab 保持插入先后顺序
 - 选中的 Tab 被配置隐藏时，内容不再渲染，自动切换到首个可见 Tab
 - `addCustomTab` 同时展开侧边栏（`isCollapse = false`）并在 `nextTick` 后自动选中目标 Tab；同名 Tab 合并更新
-- `ensureCustomTab` 与 `addCustomTab` 共用合并逻辑，但不改 `isCollapse`、不切换 `selectedTab`；适合「侧栏已打开时同步挂上文件产物」等场景
+- `ensureCustomTab` 与 `addCustomTab` 共用合并逻辑，但不改 `isCollapse`、自身不切换 `selectedTab`；适合「常驻挂载文件产物 Tab」等场景
+- 默认选中跟随 Tab 栏首位：只要没调用过 `selectCustomTab` / `addCustomTab`，挂上更靠前（`order` 更小）的 Tab 就会成为选中项，因此常驻的「文件产物」（`order: -1`）是侧栏默认面板；一旦主动切换过便不再跟随。`resetCustomTab` 会重置该标记
+- 折叠态支持受控：传入 `collapsed` 后 Provider 不再自持状态，内部展开动作直接写回该 ref，容器即可通过 `v-model` 把状态交给外部判断
 
 ## 关联组件
 
 - [ChatContainer](../components/setup/chat-container) — 侧栏 Tab 与自定义面板
-- [useArtifactPreview](./use-artifact-preview) — 文件产物 Tab：有产物时 `ensureCustomTab`，点击卡片时 `addCustomTab`
+- [useArtifactPreview](./use-artifact-preview) — 文件产物 Tab：初始化 `ensureCustomTab` 常驻挂载，点击卡片时 `addCustomTab`

package/dist/mcp/generated/docs/user-message.md

@@ -315,6 +315,8 @@ binaryFiles 有值 → 进入编辑模式（editContent 可为空）
 | `edit`   | 编辑 | 切换 `isEdit=true`，进入编辑模式             |
 | `delete` | 删除 | 无内置行为，需通过 `onAction` 外部处理       |
 
+可通过 `messageTools` 按 id 覆盖/追加，`{ id: 'edit', hidden: true }` 可隐藏内置项。
+
 ```vue
 <!-- 经 MessageRender 控制工具栏状态 -->
 <MessageRender
@@ -362,6 +364,7 @@ binaryFiles 有值 → 进入编辑模式（editContent 可为空）
 | content            | `string \| InputContent[]`                                                                 | 消息内容，字符串或含 text/binary 的数组                                   |
 | createdAt          | `number \| string`                                                                         | 消息创建时间，经 `MessageTools` 的 `#prepend` 插槽交给 `MessageTime` 渲染在工具图标左侧；无值时不展示 |
 | property           | `{ extra?: MessageExtra; artifacts?: AIFileInfo[] }`                                       | 附加属性；本组件消费 `extra.cite` / `shortcut` / `context`                |
+| messageTools       | `IToolBtn[]`                                                                               | 自定义用户消息工具组；按 id 与 `CONST_USER_MESSAGE_TOOLS` 合并，`{ id, hidden: true }` 可隐藏 |
 | messageToolsStatus | `MessageToolsStatus`                                                                       | 工具按钮状态，`disabled` 禁用、`hidden` 从 DOM 移除                       |
 | onAction           | `MessageToolsProps['onAction']`                                                            | 工具回调；`copy`/`edit` 有内置行为，`cite`/`delete` 需外部处理            |
 | onInputConfirm     | `(content: UserMessage['content'], docSchema: TagSchema) => Promise<void>`                 | 普通消息编辑确认回调                                                      |

package/dist/mcp/generated/docs/user-question-card.md

@@ -188,6 +188,8 @@ const payload = buildSkipResumePayload(interrupt);
 
 `ChatContainer` 提供同名 `#interruptQuestion` slot，参数与 `#question` 一致，透传自输入区上方的 `UserQuestionCard`。
 
+> **跳过按钮禁用态**：`disabled` 时文字与图标同步变灰（`currentColor` / `#c4c6cc`）。
+
 ## API
 
 ### UserQuestionCard Props

package/dist/mcp/generated/index.json

@@ -1,6 +1,6 @@
 {
   "version": "2.0.0",
-  "generatedAt": "2026-08-17T11:24:59.221Z",
+  "generatedAt": "2026-09-01T04:15:26.001Z",
   "domains": {
     "setup": {
       "label": "对话搭建",
@@ -1433,6 +1433,10 @@
           "slug": "toolcall-render",
           "relation": "工具调用详情中渲染描述与参数"
         },
+        {
+          "slug": "tool-message",
+          "relation": "工具返回内容同样由 DescPanel 承载"
+        },
         {
           "slug": "highlight-keyword",
           "relation": "键值与文本匹配关键词高亮"
@@ -1556,7 +1560,7 @@
       "slug": "chat-container",
       "kind": "component",
       "description": "完整对话容器，组合消息列表、输入区、模型选择、快捷指令、执行摘要、分享选择和自定义 Tab。",
-      "aiSummary": "完整对话容器，组合消息列表、输入区、模型选择、快捷指令、执行摘要、分享选择和自定义 Tab。 透传 models / selectedModel；支持 welcomeTitle 与 #welcome。 源码位置：src/components/chat-container/chat-container.vue。",
+      "aiSummary": "完整对话容器，组合消息列表、输入区、模型选择、快捷指令、执行摘要、分享选择和自定义 Tab。 透传 models / selectedModel；支持 welcomeTitle 与 #welcome。 侧栏展开/折叠由外部 v-model:asideCollapsed 严格受控（传入后以外部值为准，内部展开动作仅发 update 事件），不再依赖执行数据或文件产物有无；无数据时侧栏照常展开并展示空态。 侧栏固定从右侧展开（无 placement prop），且不再内置折叠按钮。 「文件产物」Tab 常驻挂载。 源码位置：src/components/chat-container/chat-container.vue。",
       "relatedComponents": [
         {
           "slug": "message-container",
@@ -1718,7 +1722,7 @@
       "slug": "use-custom-tab",
       "kind": "composable",
       "description": "Provider/Consumer 模式的自定义 Tab 管理，用于 `ChatContainer` 侧边栏的 Tab 动态管理。Provider 在 `ChatContainer` 中创建，Consumer 在任意后代组件中注入使用。",
-      "aiSummary": "useCustomTabProvider 返回 tabs、selectedTab、isCollapse 及 add/ensure/remove/selectCustomTab，并通过 provide 共享；可选 onTabChange 在切换时拉取数据。 ensureCustomTab 只挂载/合并元信息，不展开侧栏、不切换选中；addCustomTab 会展开并选中。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。",
+      "aiSummary": "useCustomTabProvider 返回 tabs、selectedTab、isCollapse 及 add/ensure/remove/selectCustomTab，并通过 provide 共享；可选 onTabChange 在切换时拉取数据、可选 collapsed 注入受控折叠态 ref。 ensureCustomTab 只挂载/合并元信息，不展开侧栏、不主动切换选中；addCustomTab 会展开并选中。 未被主动切换过时，选中态默认跟随 Tab 栏首位（order 最小），如常驻的「文件产物」。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。",
       "relatedComponents": [
         {
           "slug": "chat-container",

package/dist/types/input.d.ts

@@ -26,3 +26,9 @@ export type UploadFile = BinaryInputContent & {
     file?: File;
     status?: UploadStatus;
 };
+/**
+ * 附件展示形态。图片均为定高 48px、宽度按原图比例（48~120px），差异只在圆角与描边：
+ * - input：输入框内待发送态（圆角 8px、浅灰描边）
+ * - message：消息内已发送态（圆角 4px、线条中描边，整体右对齐）
+ */
+export type UploadFileVariant = 'input' | 'message';

package/dist/utils/file.d.ts

@@ -16,10 +16,16 @@ export declare const getFilePreviewUrl: (file?: File) => string;
  * @returns 文件扩展名
  */
 export declare const getFileExtension: (file?: File) => string;
+/**
+ * 格式化字节数及单位展示
+ * @param size 字节数
+ * @returns 1024B -> 1KB 1024KB -> 1M 1024M -> 1GB；大小未知时返回空串
+ */
+export declare const formatBytes: (size?: number) => string;
 /**
  * 格式化文件大小 及 单位展示
  * @param file 文件
- * @returns 1024B -> 1KB 1024KB -> 1MB 1024MB -> 1GB
+ * @returns 1024B -> 1KB 1024KB -> 1M 1024M -> 1GB
  */
 export declare const formatFileSize: (file?: File) => string;
 /**

package/dist/utils/index.d.ts

@@ -1,5 +1,7 @@
 export * from './file';
 export * from './file-type';
 export * from './markdown-completer';
+export * from './merge-tools-by-id';
 export { completeMarkdownSyntax } from './stream-markdown-completer';
+export * from './upload-file';
 export * from './utils';

package/dist/utils/merge-tools-by-id.d.ts

@@ -0,0 +1,6 @@
+import type { IToolBtn } from '../types';
+/**
+ * 按 id 合并工具列表：以内置列表为基底，同 id 覆盖（字段级合并）、新 id 追加，其余保留；
+ * 最后过滤掉标记 hidden 的项，实现「隐藏内置按钮」（如 { id: 'share', hidden: true }）。
+ */
+export declare const mergeToolsById: (base: IToolBtn[], extra?: IToolBtn[]) => IToolBtn[];

package/dist/utils/upload-file.d.ts

@@ -0,0 +1,35 @@
+/** 附件的结构化最小契约，`Partial<UploadFile>` 可直接传入 */
+export type UploadFileLike = {
+    file?: File;
+    filename?: string;
+    mimeType?: string;
+    size?: number;
+    url?: string;
+};
+/** `File` 的身份标识：同名文件靠体积与修改时间区分，用于去重与列表 key */
+export declare const getFileIdentity: (file: File) => string;
+/**
+ * 附件的稳定 key：待发送态用 `File` 身份（上传成功回填 url 后不变），
+ * 已发送态退回 url / 文件名。
+ */
+export declare const getUploadFileKey: (item: UploadFileLike) => string;
+/**
+ * 是否按图片渲染缩略图。
+ * 仅依据 MIME，不再因「有 url」就当图片——解除类型限制后，
+ * 任意文件上传成功都会拿到 url，靠 url 判断必然把 doc / pdf 渲染成破图。
+ */
+export declare const isUploadImageFile: (item: UploadFileLike) => boolean;
+/** 文件名：已发送态的 filename 优先，回退原始 `File` */
+export declare const getUploadFileName: (item: UploadFileLike) => string;
+/** 字节数：待发送态取 `File.size`，已发送态取消息内下发的 size */
+export declare const getUploadFileSize: (item: UploadFileLike) => number | undefined;
+/** 附件大小文案，无法得知大小时返回空串（消息态老数据无 size） */
+export declare const formatUploadFileSize: (item: UploadFileLike) => string;
+/**
+ * 单次遍历分出图片组与其他文件组。
+ * 设计稿要求图片始终排在文件前方，分组本身即承担了排序职责。
+ */
+export declare const splitUploadFiles: <T extends UploadFileLike>(items: T[]) => {
+    imageFiles: T[];
+    otherFiles: T[];
+};

package/package.json

@@ -1,8 +1,26 @@
 {
   "name": "@blueking/chat-x",
-  "version": "0.0.49-beta.9",
+  "version": "0.0.51-beta.1",
   "description": "蓝鲸智云 AI Chat 组件库 —— 遵循 AG-UI，为 AI Agent 和人类开发者共同设计的对话 UI 组件库。",
   "main": "index.js",
+  "scripts": {
+    "prepublishOnly": "vite --config vite.config.ts build && pnpm dts && pnpm mcp:build",
+    "dev": "vite --config vite.config.ts",
+    "dts": "vue-tsc --project tsconfig.dts.json",
+    "build": "vitest && vite --config vite.config.ts build && pnpm dts",
+    "preview": "vite --config vite.config.ts build --mode preview && pnpm dts",
+    "lint:script": "eslint . --ext .vue,.ts --fix",
+    "lint:style": "stylelint \"**/*.{scss,css,vue}\" --fix",
+    "lint:all": "pnpm lint:script && pnpm lint:style",
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "wiki:dev": "vitepress dev wikis",
+    "wiki:build": "vitepress build wikis",
+    "mcp:build:index": "tsx mcp/scripts/build-index.ts",
+    "mcp:build": "tsc -p mcp/tsconfig.json && pnpm mcp:build:index",
+    "mcp:start": "node dist/mcp/index.js",
+    "mcp:dev": "tsx mcp/src/index.ts"
+  },
   "bin": {
     "chat-x-mcp": "dist/mcp/index.js"
   },
@@ -50,6 +68,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@blueking/chat-helper": "workspace:*",
     "@types/katex": "^0.16.7",
     "@types/lodash": "^4.17.23",
     "@types/markdown-it": "^14.1.2",
@@ -78,24 +97,6 @@
     "vite-bundle-analyzer": "^1.3.2",
     "vitepress": "2.0.0-alpha.16",
     "vitest": "^4.0.18",
-    "vue-tsc": "^3.1.4",
-    "@blueking/chat-helper": "0.0.12-beta.20"
-  },
-  "scripts": {
-    "dev": "vite --config vite.config.ts",
-    "dts": "vue-tsc --project tsconfig.dts.json",
-    "build": "vitest && vite --config vite.config.ts build && pnpm dts",
-    "preview": "vite --config vite.config.ts build --mode preview && pnpm dts",
-    "lint:script": "eslint . --ext .vue,.ts --fix",
-    "lint:style": "stylelint \"**/*.{scss,css,vue}\" --fix",
-    "lint:all": "pnpm lint:script && pnpm lint:style",
-    "test": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "wiki:dev": "vitepress dev wikis",
-    "wiki:build": "vitepress build wikis",
-    "mcp:build:index": "tsx mcp/scripts/build-index.ts",
-    "mcp:build": "tsc -p mcp/tsconfig.json && pnpm mcp:build:index",
-    "mcp:start": "node dist/mcp/index.js",
-    "mcp:dev": "tsx mcp/src/index.ts"
+    "vue-tsc": "^3.1.4"
   }
 }