@blueking/chat-x 0.0.48-beta.1 → 0.0.49-beta.10

package/dist/mcp/generated/index.json

@@ -1,6 +1,6 @@
 {
   "version": "2.0.0",
-  "generatedAt": "2026-07-27T02:31:49.169Z",
+  "generatedAt": "2026-08-18T06:27:42.645Z",
   "domains": {
     "setup": {
       "label": "对话搭建",
@@ -14,6 +14,7 @@
       "components": [
         "activity-message",
         "assistant-message",
+        "file-artifact-panel",
         "info-message",
         "loading-message",
         "message-render",
@@ -82,6 +83,7 @@
       "label": "工具与反馈",
       "components": [
         "delete-tool",
+        "message-time",
         "message-tools",
         "scroll-btn",
         "tool-btn",
@@ -97,6 +99,7 @@
       "components": [
         "activity-layout",
         "ai-loading",
+        "file-icon",
         "highlight-keyword",
         "message-loading",
         "questions-container",
@@ -361,8 +364,8 @@
       "name": "UserQuestionCard 用户问题中断",
       "slug": "user-question-card",
       "kind": "component",
-      "description": "渲染 UserQuestion 中断的待回答面板，支持单选、多选、Others 与跳过。",
-      "aiSummary": "渲染 UserQuestion 中断的待回答面板，支持单选、多选、Others 与跳过。 源码位置：src/components/chat-message/interrupt-message/user-question/user-question-card.vue。",
+      "description": "渲染 UserQuestion 中断的待回答面板；一次一题分页切换，支持单选/多选、Others、跳过与已完成进度。",
+      "aiSummary": "渲染 UserQuestion 中断的待回答面板：一次只展示一题，标题栏提供题号切换， Footer 展示已完成进度；支持单选自动跳下一题、多选/Others、完成与跳过。 源码位置：src/components/chat-message/interrupt-message/user-question/user-question-card.vue。",
       "relatedComponents": [
         {
           "slug": "interrupt-message",
@@ -432,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",
@@ -450,6 +476,10 @@
         {
           "slug": "delete-tool",
           "relation": "id 为 delete 时替换为带确认的删除按钮"
+        },
+        {
+          "slug": "message-time",
+          "relation": "通过 prepend / append 插槽嵌入消息时间"
         }
       ],
       "docFile": "docs/message-tools.md",
@@ -554,6 +584,25 @@
       "docFile": "docs/ai-loading.md",
       "domain": "helper"
     },
+    {
+      "name": "FileIcon 文件类型图标",
+      "slug": "file-icon",
+      "kind": "component",
+      "description": "按文件扩展名渲染对应类型图标，尺寸随外层 font-size 自适应。",
+      "aiSummary": "按扩展名渲染文件类型图标：内联 svg，尺寸用 1em 跟随外层 font-size； 扩展名解析走 normalizeFileExtension（优先 fileType，缺省回退 fileName，大小写不敏感， 支持 Dockerfile / .gitignore 这类无扩展名或点号开头的文件）；未登记类型返回 unknown 兜底图标。 源码位置：src/components/file-icon/file-icon.vue，图标注册表在 src/icons/file-icons.ts。",
+      "relatedComponents": [
+        {
+          "slug": "file-artifact-panel",
+          "relation": "文件产物列表与预览头使用该组件展示类型图标"
+        },
+        {
+          "slug": "assistant-message",
+          "relation": "消息内的文件产物卡片使用该组件"
+        }
+      ],
+      "docFile": "docs/file-icon.md",
+      "domain": "helper"
+    },
     {
       "name": "HighlightKeyword 关键词高亮",
       "slug": "highlight-keyword",
@@ -1063,8 +1112,20 @@
           "relation": "由 MessageRender 在 role 为 activity 时创建"
         },
         {
-          "slug": "assistant-message",
-          "relation": "常与助手回复相邻，描述检索或执行背景"
+          "slug": "flow-agent-content",
+          "relation": "activityType 为 flow_agent 时渲染"
+        },
+        {
+          "slug": "knowledge-rag-content",
+          "relation": "activityType 为 knowledge_rag 时渲染"
+        },
+        {
+          "slug": "reference-doc-content",
+          "relation": "activityType 为 reference_document 时渲染"
+        },
+        {
+          "slug": "chat-container",
+          "relation": "uid / onInterruptResume / 侧栏 Tab 与 ChatContainer 联动"
         }
       ],
       "docFile": "docs/activity-message.md",
@@ -1074,8 +1135,8 @@
       "name": "AssistantMessage AI 助手消息",
       "slug": "assistant-message",
       "kind": "component",
-      "description": "渲染助手消息主体、工具调用与文件内容，默认插槽可覆盖正文渲染。",
-      "aiSummary": "渲染助手消息主体、工具调用与文件内容，默认插槽可覆盖正文渲染。 源码位置：src/components/chat-message/assistant-message/assistant-message.vue。",
+      "description": "渲染助手消息主体、工具调用与文件产物，默认插槽可覆盖正文渲染。",
+      "aiSummary": "渲染助手 Markdown 正文、ToolCallRender 工具调用列表，以及 property.artifacts 文件卡片； 默认插槽仅覆盖正文。源码位置：src/components/chat-message/assistant-message/assistant-message.vue。",
       "relatedComponents": [
         {
           "slug": "message-render",
@@ -1088,11 +1149,42 @@
         {
           "slug": "toolcall-render",
           "relation": "多条工具调用由 ToolcallRender 统一渲染"
+        },
+        {
+          "slug": "file-artifact-panel",
+          "relation": "property.artifacts 文件产物点击后在侧栏预览"
         }
       ],
       "docFile": "docs/assistant-message.md",
       "domain": "message"
     },
+    {
+      "name": "FileArtifactPanel 文件产物预览",
+      "slug": "file-artifact-panel",
+      "kind": "component",
+      "description": "汇总当前会话全部文件产物，支持搜索、选中与分类型预览，挂载在 ChatContainer 侧栏「文件产物」Tab。",
+      "aiSummary": "汇总当前会话所有 AssistantMessage 的 artifacts（按 outputId 去重），支持关键词搜索、列表选中与下载； 预览区委托 ArtifactPreviewHost：由 resolveFileKind 把扩展名归入 code / markdown / html / text / image / binary 六类， 前四类走 text_from_download 拉正文（code 交给 highlight.js 高亮），image / binary 走 preview_url； download_url / preview_url 经 onArtifactClick 每次异步获取（无 URL 缓存，并发去重）； 预览重载键为 outputId:type；重试再次调用 load() 重新取链。 源码位置：src/components/chat-message/assistant-message/message-artifacts/file-artifact-panel.vue。",
+      "relatedComponents": [
+        {
+          "slug": "assistant-message",
+          "relation": "文件产物来源于 AssistantMessage.property.artifacts"
+        },
+        {
+          "slug": "chat-container",
+          "relation": "面板挂载在侧栏「文件产物」Tab（固定、不可关闭），并通过 onArtifactClick 异步取链"
+        },
+        {
+          "slug": "execution-summary",
+          "relation": "同为 ChatContainer 侧栏 Tab 面板，交互形态一致"
+        },
+        {
+          "slug": "message-loading",
+          "relation": "ArtifactPreviewHost 取链 / 拉取正文过程使用 MessageLoading"
+        }
+      ],
+      "docFile": "docs/file-artifact-panel.md",
+      "domain": "message"
+    },
     {
       "name": "InfoMessage 信息消息",
       "slug": "info-message",
@@ -1189,8 +1281,8 @@
       "name": "ToolMessage 工具消息",
       "slug": "tool-message",
       "kind": "component",
-      "description": "渲染工具返回内容，JSON 场景交给 DescPanel 展示。",
-      "aiSummary": "渲染工具返回内容，JSON 场景交给 DescPanel 展示。 源码位置：src/components/chat-message/tool-message/tool-message.vue。",
+      "description": "渲染工具返回内容，JSON 场景交给 DescPanel + HighlightKeyword 展示。",
+      "aiSummary": "渲染工具返回内容；DescPanel 解析 JSON 为 key-value，嵌套值 JSON.stringify 后经 HighlightKeyword 展示。 源码位置：src/components/chat-message/tool-message/tool-message.vue。",
       "relatedComponents": [
         {
           "slug": "assistant-message",
@@ -1212,8 +1304,8 @@
       "name": "UserMessage 用户消息",
       "slug": "user-message",
       "kind": "component",
-      "description": "渲染用户消息，支持文本、键值、Markdown、引用、文件和编辑态输入。",
-      "aiSummary": "渲染用户消息，支持文本、键值、Markdown、引用、文件和编辑态输入。 源码位置：src/components/chat-message/user-message/user-message.vue。",
+      "description": "渲染用户消息，支持纯文本、键值引用、文件附件和编辑态输入。",
+      "aiSummary": "渲染用户消息：纯文本（非 Markdown）、键值引用、二进制附件与编辑态 ChatInput / ShortcutRender； 工具栏含 copy / cite / edit / delete。源码位置：src/components/chat-message/user-message/user-message.vue。",
       "relatedComponents": [
         {
           "slug": "message-render",
@@ -1223,9 +1315,17 @@
           "slug": "message-tools",
           "relation": "消息工具栏交互与状态由 MessageTools 体系承载"
         },
+        {
+          "slug": "message-time",
+          "relation": "createdAt 经工具栏 prepend 插槽展示"
+        },
         {
           "slug": "message-container",
           "relation": "嵌入列表时由 MessageContainer 管理分组与多选"
+        },
+        {
+          "slug": "chat-input",
+          "relation": "编辑态普通消息使用 ChatInput"
         }
       ],
       "docFile": "docs/user-message.md",
@@ -1456,7 +1556,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",
@@ -1533,6 +1633,28 @@
       ],
       "docFile": "docs/use-animation-text.md"
     },
+    {
+      "name": "useArtifactPreview",
+      "slug": "use-artifact-preview",
+      "kind": "composable",
+      "description": "Provider/Consumer 模式的文件产物预览状态管理，用于 ChatContainer 侧栏「文件产物」Tab 的命中与切换。 Provider 在 ChatContainer 中创建，Consumer 在深层文件卡片中注入使用。",
+      "aiSummary": "useArtifactPreviewProvider 维护 activeArtifactId（值为 outputId），openPreview 命中文件并触发 onOpen 打开侧栏 Tab； 并通过 getOnArtifactClick 封装 resolveArtifactUrls（每次重新取链，并发去重）； useArtifactPreviewConsumer 在后代注入同一套 API。SessionArtifact 即 AIFileInfo，会话内以 outputId 为唯一键。 正文加载与分类型渲染不在本 composable，由 FileArtifactPanel 内 ArtifactPreviewHost 完成（重载键 outputId:type）。 FILE_ARTIFACT_TAB_NAME 标识固定「文件产物」Tab。",
+      "relatedComponents": [
+        {
+          "slug": "chat-container",
+          "relation": "Provider 主场景，聚合 sessionArtifacts 并挂载 FileArtifactPanel"
+        },
+        {
+          "slug": "file-artifact-panel",
+          "relation": "侧栏面板消费 activeArtifactId 与 setActiveArtifactId；预览加载在面板内 Host"
+        },
+        {
+          "slug": "assistant-message",
+          "relation": "文件产物来源 property.artifacts"
+        }
+      ],
+      "docFile": "docs/use-artifact-preview.md"
+    },
     {
       "name": "useClipboard",
       "slug": "use-clipboard",
@@ -1574,7 +1696,7 @@
       "slug": "use-container-scroll",
       "kind": "composable",
       "description": "为消息容器提供滚动控制的组合式函数对，通过 **Provider/Consumer** 模式在父子组件间共享滚动状态。",
-      "aiSummary": "useContainerScrollProvider 在滚动容器与底部锚点上绑定 IntersectionObserver、scroll、wheel，提供 isScrollBottom、scrollBottomHeight、autoScrollEnabled、toScrollBottom/toScrollTop 及防抖「返回底部」按钮状态。 useContainerScrollConsumer 通过 inject 在子组件中获取同一套控制，无需 props 透传。 典型用于流式输出时仅在用户位于底部时自动滚底。MessageContainer 与 ScrollBtn 配合使用。",
+      "aiSummary": "useContainerScrollProvider 在滚动容器与底部锚点上绑定 IntersectionObserver、scroll、wheel，提供 isScrollBottom、scrollBottomHeight、autoScrollEnabled、jumpToBottom、toScrollBottom/toScrollTop 及防抖「返回底部」按钮状态。 toScrollBottom 缺省按距底部距离自动选择行为：超过 INSTANT_SCROLL_DISTANCE（600px）时瞬时贴底，否则平滑滚动，避免切换会话时出现长距离平滑滚动动画。 useContainerScrollConsumer 通过 inject 在子组件中获取同一套控制，无需 props 透传。 典型用于流式输出时仅在用户位于底部时自动滚底。MessageContainer 与 ScrollBtn 配合使用。",
       "relatedComponents": [
         {
           "slug": "message-container",
@@ -1596,7 +1718,7 @@
       "slug": "use-custom-tab",
       "kind": "composable",
       "description": "Provider/Consumer 模式的自定义 Tab 管理，用于 `ChatContainer` 侧边栏的 Tab 动态管理。Provider 在 `ChatContainer` 中创建，Consumer 在任意后代组件中注入使用。",
-      "aiSummary": "useCustomTabProvider 返回 tabs、selectedTab、isCollapse 及 add/remove/selectCustomTab，并通过 provide 共享；可选 onTabChange 在切换时拉取数据。 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",
@@ -1641,12 +1763,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"
@@ -1717,7 +1843,7 @@
       "slug": "constants",
       "kind": "type",
       "description": "`@blueking/chat-x` 导出的常量和枚举类型。",
-      "aiSummary": "汇总 MessageRole、MessageStatus（含 Fetching 请求中）、MessageContentType、MessageToolsStatus、MessageState、Z-Index 与 CONST_MESSAGE_TOOLS 等导出常量。 用于构造消息、配置 MessageContainer 工具栏与输入态，以及层级与默认快捷指令。与类型 messages 配套使用。",
+      "aiSummary": "汇总 MessageRole、MessageStatus（含 Fetching 请求中、Complete/Completed 完成态兼容）、MessageContentType、MessageToolsStatus、MessageState、Z-Index 与 CONST_MESSAGE_TOOLS 等导出常量。 用于构造消息、配置 MessageContainer 工具栏与输入态，以及层级与默认快捷指令。与类型 messages 配套使用。",
       "relatedComponents": [
         {
           "slug": "message-tools",

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

@@ -0,0 +1,14 @@
+/**
+ * 文件分类：图标兜底与预览渲染策略的共同依据。
+ * - code：可交给 highlight.js 渲染的源码 / 配置文件
+ * - text：纯文本，直接按原文展示
+ * - binary：无法在前端直接解析，统一交由后端 preview_url 预览
+ */
+export type AIFileKind = 'binary' | 'code' | 'html' | 'image' | 'markdown' | 'text';
+/**
+ * 归一化文件类型标识：优先取后台下发的 type，缺省时回退文件名。
+ * 统一转小写并截取最后一段扩展名；无扩展名的文件（Dockerfile / Makefile）直接返回文件名本身。
+ */
+export declare const normalizeFileExtension: (type?: string, name?: string) => string;
+/** 解析文件分类；未登记的扩展名按 binary 兜底 */
+export declare const resolveFileKind: (type?: string, name?: string) => AIFileKind;

package/dist/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './file';
+export * from './file-type';
 export * from './markdown-completer';
 export { completeMarkdownSyntax } from './stream-markdown-completer';
 export * from './utils';

package/package.json

@@ -1,26 +1,8 @@
 {
   "name": "@blueking/chat-x",
-  "version": "0.0.48-beta.1",
+  "version": "0.0.49-beta.10",
   "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"
   },
@@ -68,7 +50,6 @@
     "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",
@@ -97,6 +78,24 @@
     "vite-bundle-analyzer": "^1.3.2",
     "vitepress": "2.0.0-alpha.16",
     "vitest": "^4.0.18",
-    "vue-tsc": "^3.1.4"
+    "vue-tsc": "^3.1.4",
+    "@blueking/chat-helper": "0.0.12-beta.21"
+  },
+  "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"
   }
 }