@blueking/chat-x 0.0.50 → 0.0.51-beta.1

package/dist/mcp/generated/index.json

@@ -1,6 +1,6 @@
 {
   "version": "2.0.0",
-  "generatedAt": "2026-08-13T08:24:18.572Z",
+  "generatedAt": "2026-09-01T04:15:26.001Z",
   "domains": {
     "setup": {
       "label": "对话搭建",
@@ -83,6 +83,7 @@
       "label": "工具与反馈",
       "components": [
         "delete-tool",
+        "message-time",
         "message-tools",
         "scroll-btn",
         "tool-btn",
@@ -434,12 +435,35 @@
       "docFile": "docs/delete-tool.md",
       "domain": "feedback"
     },
+    {
+      "name": "MessageTime 消息时间",
+      "slug": "message-time",
+      "kind": "component",
+      "description": "按「今天 / 昨天 / 今年内 / 跨年」四档格式展示消息创建时间。",
+      "aiSummary": "按 createdAt 展示消息时间，四档格式：今天 `12:00`、昨天 `昨天 12:00`、今年内更早 `3-12 12:00`、非今年 `2025-3-12 12:00`； 时区取 props.timezone，未传时回退 injectGlobalConfig().timezone（由 ChatContainer 的 timezone prop 注入），都没有则用浏览器时区； 无值或非法时间不渲染任何 DOM。通常通过 MessageTools 的 prepend / append 插槽使用。 源码位置：src/components/message-tools/message-time/message-time.vue。",
+      "relatedComponents": [
+        {
+          "slug": "message-tools",
+          "relation": "通过 prepend / append 插槽嵌入工具栏"
+        },
+        {
+          "slug": "user-message",
+          "relation": "用户消息在工具栏左侧展示时间"
+        },
+        {
+          "slug": "message-container",
+          "relation": "AI 消息组在工具栏右侧展示本轮回答时间"
+        }
+      ],
+      "docFile": "docs/message-time.md",
+      "domain": "feedback"
+    },
     {
       "name": "MessageTools 消息工具栏",
       "slug": "message-tools",
       "kind": "component",
       "description": "消息悬浮工具栏，组合复制、删除、反馈等工具按钮。",
-      "aiSummary": "消息悬浮工具栏，组合复制、删除、反馈等工具按钮。 源码位置：src/components/message-tools/message-tools.vue。",
+      "aiSummary": "消息悬浮工具栏，组合复制、删除、反馈等工具按钮；提供 prepend / append 两端插槽承载消息时间等附加内容。 源码位置：src/components/message-tools/message-tools.vue。",
       "relatedComponents": [
         {
           "slug": "tool-btn",
@@ -452,6 +476,10 @@
         {
           "slug": "delete-tool",
           "relation": "id 为 delete 时替换为带确认的删除按钮"
+        },
+        {
+          "slug": "message-time",
+          "relation": "通过 prepend / append 插槽嵌入消息时间"
         }
       ],
       "docFile": "docs/message-tools.md",
@@ -1287,6 +1315,10 @@
           "slug": "message-tools",
           "relation": "消息工具栏交互与状态由 MessageTools 体系承载"
         },
+        {
+          "slug": "message-time",
+          "relation": "createdAt 经工具栏 prepend 插槽展示"
+        },
         {
           "slug": "message-container",
           "relation": "嵌入列表时由 MessageContainer 管理分组与多选"
@@ -1401,6 +1433,10 @@
           "slug": "toolcall-render",
           "relation": "工具调用详情中渲染描述与参数"
         },
+        {
+          "slug": "tool-message",
+          "relation": "工具返回内容同样由 DescPanel 承载"
+        },
         {
           "slug": "highlight-keyword",
           "relation": "键值与文本匹配关键词高亮"
@@ -1524,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",
@@ -1686,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",
@@ -1731,12 +1767,16 @@
       "name": "useGlobalConfig",
       "slug": "use-global-config",
       "kind": "composable",
-      "description": "在聊天根容器与子组件之间通过 provide/inject 共享全局展示配置（字号主题档位、是否支持上传等）。",
-      "aiSummary": "useGlobalConfig 接收 GlobalConfig（含 size?: ComputedRef<AiSizeMode>、supportUpload: ComputedRef<boolean>），以 GLOBAL_CONFIG_TOKEN provide 给后代； injectGlobalConfig 在子组件中取出配置，无 Provider 时返回 undefined。ChatContainer 在 setup 中调用 useGlobalConfig 注入 size 与 supportUpload； 后代组件可通过 injectGlobalConfig 读取配置；字号主题主要通过根节点 data-ai-size 与 CSS 变量生效。",
+      "description": "在聊天根容器与子组件之间通过 provide/inject 共享全局展示配置（字号主题档位、是否支持上传、消息时间时区等）。",
+      "aiSummary": "useGlobalConfig 接收 GlobalConfig（含 size?: ComputedRef<AiSizeMode>、supportUpload: ComputedRef<boolean>、timezone?: ComputedRef<string | undefined>），以 GLOBAL_CONFIG_TOKEN provide 给后代； injectGlobalConfig 在子组件中取出配置，无 Provider 时返回 undefined。ChatContainer 在 setup 中调用 useGlobalConfig 注入 size、supportUpload 与 timezone； 后代组件可通过 injectGlobalConfig 读取配置；字号主题主要通过根节点 data-ai-size 与 CSS 变量生效。",
       "relatedComponents": [
         {
           "slug": "chat-container",
           "relation": "根容器调用 useGlobalConfig 注入 supportUpload"
+        },
+        {
+          "slug": "message-time",
+          "relation": "消息时间组件读取 timezone"
         }
       ],
       "docFile": "docs/use-global-config.md"

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,6 +1,6 @@
 {
   "name": "@blueking/chat-x",
-  "version": "0.0.50",
+  "version": "0.0.51-beta.1",
   "description": "蓝鲸智云 AI Chat 组件库 —— 遵循 AG-UI，为 AI Agent 和人类开发者共同设计的对话 UI 组件库。",
   "main": "index.js",
   "scripts": {