@blueking/chat-x 0.0.51-beta.5 → 0.0.52-dev.1

package/dist/utils/collect-message-artifacts.d.ts

@@ -0,0 +1,14 @@
+import type { AIFileInfo } from '../ag-ui/types/file';
+import type { Message } from '../ag-ui/types/messages';
+import type { IInputMenuItem } from '../types/input-menu';
+/**
+ * 把文件产物转成输入框菜单条目。
+ *
+ * 「消息里自动收集」与「点击引用按钮插入」必须共用这套映射：id 不一致会导致
+ * `@` 菜单的去重、以及已插入标签的匹配全部失效。
+ */
+export declare const toArtifactMenuItem: (file: AIFileInfo) => IInputMenuItem;
+/** 从同一条消息提取具有 outputId 的助手产物与上传附件，供菜单、侧栏共用。 */
+export declare const getMessageArtifacts: (message: Message) => AIFileInfo[];
+/** 同一 outputId 取最后一次名称，菜单位置保持首次出现的顺序。 */
+export declare const collectMessageArtifacts: (messages?: Message[]) => IInputMenuItem[];

package/dist/utils/file.d.ts

@@ -36,10 +36,10 @@ export declare const formatUploadNotAddedMessage: (count: number, maxMb: string,
 export declare const normalizeAcceptTokens: (accept: string) => string[];
 /** 当前 accept 是否就是对话默认允许列表（忽略顺序与大小写） */
 export declare const isDefaultUploadAccept: (accept?: string) => boolean;
-/** 默认允许列表的分类说明，与 ALLOWED_UPLOAD_EXTENSIONS 同源；每一类单独一行 */
-export declare const formatDefaultUploadAcceptTip: (isEn: boolean) => string;
 /**
  * 按 input accept 规则判断文件是否允许上传。
- * accept 为空表示不限制；支持扩展名、精确 mime、以及 mime 通配（含全部类型）。
+ * accept 为空表示不限制；支持扩展名、精确 mime、类型通配（如 image/*）以及任意类型。
  */
 export declare const isFileAcceptedByAccept: (file: File, accept?: string) => boolean;
+/** 默认允许列表的分类说明，与 ALLOWED_UPLOAD_EXTENSIONS 同源；每一类单独一行 */
+export declare const formatDefaultUploadAcceptTip: (isEn: boolean) => string;

package/dist/utils/index.d.ts

@@ -1,8 +1,9 @@
+export * from './artifact-tags';
+export * from './collect-message-artifacts';
 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-accept';
 export * from './upload-file';
 export * from './utils';

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

@@ -1,16 +1,19 @@
+import type { AIFileInfo } from '../ag-ui/types/file';
 /** 附件的结构化最小契约，`Partial<UploadFile>` 可直接传入 */
 export type UploadFileLike = {
     file?: File;
     filename?: string;
     mimeType?: string;
+    outputId?: string;
     size?: number;
+    status?: string;
     url?: string;
 };
 /** `File` 的身份标识：同名文件靠体积与修改时间区分，用于去重与列表 key */
 export declare const getFileIdentity: (file: File) => string;
 /**
  * 附件的稳定 key：待发送态用 `File` 身份（上传成功回填 url 后不变），
- * 已发送态退回 url / 文件名。
+ * 已发送态优先用 outputId，旧附件退回 url / 文件名。
  */
 export declare const getUploadFileKey: (item: UploadFileLike) => string;
 /**
@@ -33,3 +36,5 @@ export declare const splitUploadFiles: <T extends UploadFileLike>(items: T[]) =>
     imageFiles: T[];
     otherFiles: T[];
 };
+/** 已上传附件按 path 映射出的 outputId 进入与助手产物相同的引用、预览流程。 */
+export declare const toUploadArtifact: (item: UploadFileLike) => AIFileInfo | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/chat-x",
-  "version": "0.0.51-beta.5",
+  "version": "0.0.52-dev.1",
   "description": "蓝鲸智云 AI Chat 组件库 —— 遵循 AG-UI，为 AI Agent 和人类开发者共同设计的对话 UI 组件库。",
   "main": "index.js",
   "bin": {
@@ -20,7 +20,8 @@
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "keywords": [],
   "author": "Tencent BlueKing",

package/skills/blueking-chat-x/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: blueking-chat-x
+description: >-
+  Use when 在消费方项目中接入 / 使用 @blueking/chat-x 对话组件库（已 npm 安装、非改库源码），
+  涉及「某组件怎么用、有哪些 props / events / slots / expose / v-model、怎么搭 AI 对话界面、
+  流式输出、停止生成、工具调用 ToolCall、快捷指令、文件上传、图片上传、@ 资源、自定义消息或侧栏 Tab、
+  分享多选、HITL 中断审批、Markdown / 代码 / 公式 / 图表渲染、字号与主题 CSS 变量、
+  消息时间 MessageTime / timezone」等问题时优先使用。
+  若是在 packages/chat-x/src 内改库源码（写组件 / composable / 样式 / 测试），改用 chat-x-dev skill。
+---
+
+# 使用 @blueking/chat-x
+
+帮助**消费方项目**（已 `npm i @blueking/chat-x`）快速理解组件库、查清每个组件的用法与 API，并写出正确的接入代码。
+
+本 skill 的组件资料在 `references/` 下，由 `scripts/generate-references.mjs` 从库的 `wikis/` 文档自动生成（剥离演示噪音、保留完整 API 与示例）。**它就是组件 API 的真相源**——不要凭记忆臆测 props/事件/插槽名。
+
+## 信息源优先级（先查再写）
+
+| 想知道什么 | 去哪里查（按优先级） |
+| --- | --- |
+| 某组件的 Props / Events / Slots / Expose / v-model / 用法 | ① `references/_index.md` 定位 slug → ② `references/components/<slug>.md`；③ 若项目装了 chat-x MCP，可用 `get_component_doc` / `search_docs` 交叉验证 |
+| 有哪些组件、按能力域怎么选 | `references/_index.md`（能力地图） |
+| composable / 类型 / 主题（字号、CSS 变量） | `references/composables/*`、`references/types/*`、`references/theme/*` |
+| 工具函数 / 指令 / Markdown 插件 / 图标 | `references/utils/*`、`references/directives/*`、`references/plugins/*`、`references/icons/*` |
+| 某个组件到底能不能 `import` | 看 reference 顶部：有「导入」行才是包入口导出；标注「未从包入口导出」的是内部组件，须经上层组件使用 |
+| 最小接入怎么写 | 本文「快速接入」一节 |
+
+> references 缺失或过期时，按本文「再生成 references」一节重新生成。
+
+## 心智模型（一句话）
+
+**消息驱动 + 角色分发**：业务维护一份 `Message[]` → `ChatContainer`（或 `useMessageGroup`）分组 → `MessageRender` 按 `message.role` 分发到具体消息组件 → `ContentRender` 按内容类型分发 → `MarkdownContent` 按 token 分发。
+
+接入心智：**你只负责维护 `messages` 数组和实现 `onSendMessage` 等回调**，组件负责渲染与交互。
+
+## 快速接入（ChatContainer 一站式，推荐入口）
+
+```vue
+<template>
+  <ChatContainer
+    v-model="input"
+    :messages="messages"
+    :message-status="messageStatus"
+    :on-send-message="handleSendMessage"
+    :on-stop-sending="handleStopSending"
+    @stop-streaming="handleStopStreaming"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { ChatContainer, MessageRole, MessageStatus, type Message, type TagSchema, type UserMessage } from '@blueking/chat-x';
+
+  const input = ref('');
+  const messages = ref<Message[]>([]);
+  const messageStatus = ref(MessageStatus.Complete);
+
+  const handleSendMessage = async (content: UserMessage['content'], docSchema: TagSchema) => {
+    messages.value.push({ id: `u_${Date.now()}`, messageId: `u_${Date.now()}`, role: MessageRole.User, content, status: MessageStatus.Complete });
+    const ai: Message = { id: `a_${Date.now()}`, messageId: `a_${Date.now()}`, role: MessageRole.Assistant, content: '', status: MessageStatus.Streaming };
+    messages.value.push(ai);
+    messageStatus.value = MessageStatus.Streaming;
+    // 接你的 SSE / WebSocket，把增量写入 ai.content
+    ai.status = MessageStatus.Complete;
+    messageStatus.value = MessageStatus.Complete;
+  };
+  const handleStopSending = async () => { messageStatus.value = MessageStatus.Stop; };
+  const handleStopStreaming = () => { messageStatus.value = MessageStatus.Stop; };
+</script>
+```
+
+前置依赖：`vue >= 3.5`、`bkui-vue 2.x`；样式随导入自动加载，无需手动引入。
+需要完全控制布局时改用「`MessageContainer` + `ChatInput` + `useMessageGroup`」组合——细节查 `references/components/message-container.md` 与 `chat-input.md`。
+
+## 怎么查一个组件（标准流程）
+
+1. 在 `references/_index.md` 里按名称/能力域找到组件，拿到它的 `path`。
+2. 读 `references/components/<slug>.md`：顶部是能力域 + 导入符号（或「未从包入口导出」标注）+ 概述 + 关联组件，正文含「核心能力 / 基础用法 / API（Props/Events/Slots/Expose/v-model）/ 类型定义」。
+3. 按 API 表格落地代码，需要的类型与常量从 `@blueking/chat-x` 具名导入。
+
+> 接入逻辑常跨多个组件（如 `ChatContainer` 透传 `ChatInput` / `MessageContainer` 的 props，自定义 `#message` 插槽需透传 `onAction` 等回调）。遇到「透传到底要带哪些参数」时，连同关联组件文档一起读。
+
+## 常见坑（消费方高频，先看再调）
+
+| 症状 | 原因 / 修法 |
+| --- | --- |
+| 自定义 `#message` 插槽后，用户消息的工具（删除/编辑/复制/引用）全失效，但 AI 消息工具正常 | 自定义 `#message` 渲染 `MessageRender` 时漏透传 `on-action` / `on-input-confirm` / `on-shortcut-confirm` / `tippy-options`；AI 消息工具在 `MessageContainer` 内部渲染不经过该插槽，故不受影响 |
+| 用户消息编辑态的 `ChatInput` 上传配置与主输入区不一致 | `supportUpload` 需全链路透传 `ChatContainer → MessageContainer → MessageRender → UserMessage`，否则回退默认 `true` |
+| 想自定义代码块头部动作（插入/应用代码）无从下手 | 用 `codeHeader` 插槽，参数为 `{ language, token }`（`AIBlueking/ChatBot` 已支持透传） |
+| `requestOptions.data` 不知道进 body 还是 query | POST/PUT/PATCH/DELETE 合并进 body；GET/HEAD/OPTIONS 合并进 query（params） |
+
+## 常见任务 → 入口
+
+| 任务 | 入口组件 / 文档 |
+| --- | --- |
+| 搭完整对话界面 | `components/chat-container.md` |
+| 自定义布局（自己拼消息列表 + 输入框） | `components/message-container.md` + `components/chat-input.md` + `composables/use-message-group.md` |
+| `/` Prompt、`@` 资源、文件 / 图片上传 | `components/chat-input.md` |
+| 流式输出 / 停止生成 | `components/chat-container.md`（`messageStatus` + `@stop-streaming`） |
+| 工具调用 / ToolCall 渲染 | `components/toolcall-render.md`、`components/tool-message.md` |
+| HITL 中断 / 工具审批 / 用户提问 | `components/interrupt-message.md`、`components/tool-approval-card.md`、`components/user-question-card.md` |
+| FlowAgent 执行 / 知识召回展示 | `components/flow-agent-content.md`、`components/knowledge-rag-content.md` |
+| 渲染 Markdown / 代码 / 公式 / 图表 | `components/content-render.md`、`components/markdown-content.md`、`components/code-content.md` |
+| 图片预览 / 文件展示 | `components/ai-image.md`、`components/image-preview-group.md`、`components/file-content.md` |
+| 快捷指令表单 | `components/shortcut-render.md`、`components/chat-input.md` |
+| 分享 / 多选 | `components/chat-container.md`、`components/selection-footer.md` |
+| 自定义消息类型 / 侧栏 Tab | `composables/use-custom-tab.md` + `components/chat-container.md` |
+| 字号 / 主题 CSS 变量 | `theme/theme.md` |
+| 消息时间 / 时区 | `ChatContainer` 的 `timezone` prop；组件 `MessageTime`（wikis `components/feedback/message-time.md`）。四档：今天 `12:00` / 昨天 / 今年内 `3-12 12:00` / 跨年；无 `createdAt` 不渲染 |
+
+## 类型与常量速查
+
+```typescript
+// 类型按需具名导入
+import type { Message, UserMessage, AssistantMessage, ToolMessage, IToolBtn, Shortcut, TagSchema } from '@blueking/chat-x';
+
+// 枚举 / 预置工具
+import {
+  MessageRole, MessageStatus, MessageContentType,
+  CONST_MESSAGE_TOOLS,       // AI 消息默认工具：复制 / 引用 / 重新生成 / 分享
+  CONST_USER_MESSAGE_TOOLS,  // 用户消息默认工具：复制 / 引用 / 编辑 / 删除
+} from '@blueking/chat-x';
+```
+
+更全的类型/常量定义查 `references/types/*`。
+
+## 再生成 references
+
+references 由脚本从 `wikis/` 生成。当库升级、wikis 更新，或 references 缺失/过期时重新生成（**运行脚本前需经用户同意**）：
+
+```bash
+# 在 packages/chat-x 下执行（依赖 glob / gray-matter 已在 devDependencies）
+node skills/blueking-chat-x/scripts/generate-references.mjs
+```
+
+脚本会全量重建 `references/`：`glob wikis` → `gray-matter` 解析 frontmatter → 清洗正文（去 VitePress demo `<script>` / `<div class="demo">` / 内联 style，保留代码围栏与 API 表格）→ 按组件能力域 + composables / types / utils / directives / plugins / icons / theme 写出 + 生成 `_index.md`。
+
+「导入」行不是从文档标题猜的：脚本会从 `src/index.ts` 递归解析 barrel，拿到包入口**值导出**与**类型导出**两个集合，只有命中值导出才生成 `import` 语句；大小写漂移（`ToolcallRender` → `ToolCallRender`）自动纠正，只存在同名类型导出的（如 `UserMessage`）会明确标注「同名导出是 TS 类型，不是组件」。个别导出名与组件名不一致时，在 wikis frontmatter 用 `exportSymbol: MessageUserFeedback` 指定，确认为内部组件则写 `exportSymbol: false`。运行后留意 `[warn]` 输出。
+
+## 通用项目规则
+
+中文回复、不擅自处理 eslint/格式、运行脚本需先经同意、git 提交禁用 `--no-verify`、不确定先问——见仓库 `AGENTS.md` 与 `.cursor/rules/project.mdc`。

package/skills/blueking-chat-x/references/_index.md

@@ -0,0 +1,153 @@
+# @blueking/chat-x 能力地图（自动生成）
+
+> 由 `scripts/generate-references.mjs` 从 `wikis/` 生成，请勿手改。
+> 查某个能力时：先在本索引定位 slug，再读对应 `path` 的 reference 文档。
+
+## 组件（按能力域）
+
+### 对话搭建
+
+- **ChatContainer 聊天容器** — 完整对话容器，组合消息列表、输入区、模型选择、快捷指令、执行摘要、分享选择和自定义 Tab。 → `components/chat-container.md`
+- **MessageContainer 消息列表容器** — 负责消息分组渲染、滚动控制、工具栏和消息插槽透传。 → `components/message-container.md`
+
+### 消息系统
+
+- **ActivityMessage 活动消息** — 按 activityType 分发 FlowAgent、知识召回、引用文档等活动内容。 → `components/activity-message.md`
+- **AssistantMessage AI 助手消息** — 渲染助手消息主体、工具调用与文件产物，默认插槽可覆盖正文渲染。 → `components/assistant-message.md`
+- **FileArtifactPanel 文件产物预览** — 汇总当前会话全部文件产物，支持搜索、选中与分类型预览，挂载在 ChatContainer 侧栏「文件产物」Tab。 → `components/file-artifact-panel.md`
+- **InfoMessage 信息消息** — 渲染居中的系统信息提示。 → `components/info-message.md`
+- **LoadingMessage 加载消息** — 消息列表中的加载占位，默认使用 AiLoading，也支持默认插槽覆盖。 → `components/loading-message.md`
+- **MessageRender 消息渲染器** — 按 message.role 分发到用户、助手、工具、推理、活动、中断等消息组件。 → `components/message-render.md`
+- **ReasoningMessage 推理消息** — 渲染推理过程，覆盖加载、错误与 Markdown 内容展示。 → `components/reasoning-message.md`
+- **ToolMessage 工具消息** — 渲染工具返回内容，JSON 场景交给 DescPanel + HighlightKeyword 展示。 → `components/tool-message.md`
+- **UserMessage 用户消息** — 渲染用户消息，支持纯文本、键值引用、文件附件和编辑态输入。 → `components/user-message.md`
+
+### 内容渲染
+
+- **AnimationText 动画文本** — 按文本增量播放流式动画。 → `components/animation-text.md`
+- **CiteContent 引用内容** — 渲染输入或消息中的引用片段。 → `components/cite-content.md`
+- **CodeContent 代码块** — 渲染 Markdown 代码块，支持高亮、复制和 header 插槽。 → `components/code-content.md`
+- **CollapsibleContent 折叠内容** — 内容超过阈值高度时折叠，并在下方展示「显示更多 / 收起」。 → `components/collapsible-content.md`
+- **CommonErrorContent 错误内容** — 展示统一错误提示内容。 → `components/common-error-content.md`
+- **ContentRender 内容渲染器** — 按 MessageContentType 分发 Markdown、文本、引用、键值、图片等内容。 → `components/content-render.md`
+- **DescPanel 描述面板** — 将文本或 JSON 内容降级为可读描述面板。 → `components/desc-panel.md`
+- **KeyValueContent 键值内容** — 以键值列表展示结构化内容。 → `components/key-value-content.md`
+- **LatexContent LaTeX 公式** — 使用 KaTeX 渲染 LaTeX 公式内容。 → `components/latex-content.md`
+- **MarkdownContent Markdown 内容渲染** — Markdown 主渲染器，集成代码块、公式、错误降级和 codeHeader 插槽。 → `components/markdown-content.md`
+- **MentionTag 资源标签** — 单个资源标签，带类型图标、描述气泡与会话产物点击预览。 → `components/mention-tag.md`
+- **MentionText 标签文本** — 把发送时保留的富文本文档还原成「文本 + 资源标签」，用于用户消息回显。 → `components/mention-text.md`
+- **MermaidContent Mermaid 图表** — 渲染 Mermaid 图表并处理渲染事件。 → `components/mermaid-content.md`
+- **ReferenceContent 引用来源** — 渲染引用文档/来源列表。 → `components/reference-content.md`
+- **TextContent 文本内容** — 渲染纯文本内容。 → `components/text-content.md`
+
+### 媒体文件
+
+- **AiImage 图片展示** — 图片展示组件，组合加载、错误、预览和 extra 插槽。 → `components/ai-image.md`
+- **FileContent 文件内容** — 渲染文件附件，支持图片预览、上传中/失败态和下载事件。 → `components/file-content.md`
+- **ImageContent 图片内容** — 渲染 Markdown 图片 token。 → `components/image-content.md`
+- **ImagePreview 图片预览** — 图片全屏预览容器，支持缩放、旋转、下载工具栏。 → `components/image-preview.md`
+- **ImagePreviewGroup 图片预览组** — 通过 provide/inject 管理同组图片预览。 → `components/image-preview-group.md`
+- **PreviewToolbar 图片预览工具栏** — 图片预览的缩放、旋转、下载等工具按钮。 → `components/preview-toolbar.md`
+
+### 输入交互
+
+- **AddMenuBtn 添加菜单按钮** — 输入框左下角的 + 号按钮，唤起聚合菜单，展开态高亮。 → `components/add-menu-btn.md`
+- **AiSelection 划词选择** — 监听选中文本并展示快捷操作浮窗。 → `components/ai-selection.md`
+- **AiSlashInput 富文本命令输入** — ChatInput 内部富文本编辑区，负责触发符识别、资源标签插入与文档同步。 → `components/ai-slash-input.md`
+- **ChatInput 聊天输入框** — 聊天输入区，组合富文本输入、统一菜单（@ / \ 与 + 号）、快捷指令、附件、引用、发送/停止等交互。 → `components/chat-input.md`
+- **FileUploadBtn 文件上传按钮** — 文件选择按钮，封装 input[type=file] 并输出选择事件。 → `components/file-upload-btn.md`
+- **InputAttachment 输入附件区** — ChatInput 底部附件区布局，承载快捷按钮、文件与发送图标。 → `components/input-attachment.md`
+- **InputInfoAlert 输入提示条** — ChatInput 上方的信息提示条。 → `components/input-info-alert.md`
+- **InputMenuPanel 输入框菜单** — 输入框上方的统一菜单面板，@ / \ 与 + 号共用一套数据源、分组与折叠逻辑。 → `components/input-menu-panel.md`
+- **ModelSelector 模型选择器** — 聊天输入区的模型下拉选择器，支持搜索过滤、能力标签与键盘导航。 → `components/model-selector.md`
+- **SelectionFooter 多选操作栏** — 消息多选/分享模式下的底部操作栏。 → `components/selection-footer.md`
+- **ShortcutBtn 快捷指令按钮** — 单个快捷指令按钮，支持默认/append 插槽和 expose focus。 → `components/shortcut-btn.md`
+- **ShortcutBtns 快捷指令按钮组** — 快捷指令列表入口，内部组合多个 ShortcutBtn。 → `components/shortcut-btns.md`
+- **ShortcutRender 快捷指令表单** — 渲染快捷指令 components 表单并回传确认数据。 → `components/shortcut-render.md`
+
+### Agent 能力
+
+- **DetailSection 详情分段** — FlowAgent 节点详情中的标题/内容分段容器。 → `components/detail-section.md`
+- **ExecutionSummary 执行摘要** — 按消息流提取执行摘要，支持关键词定位和消息渲染。 → `components/execution-summary.md`
+- **FlowAgentContent FlowAgent 执行内容** — 渲染 FlowAgent 任务/节点执行状态、耗时、详情入口和自定义 Tab 联动。 → `components/flow-agent-content.md`
+- **FlowAgentNodeDetail FlowAgent 节点详情** — 展示 FlowAgent 节点输入、输出、异常、耗时等详情。 → `components/flow-agent-node-detail.md`
+- **InterruptMessage 中断消息** — 渲染 human-in-the-loop 中断消息，分发工具审批，并按 reason 回显 resume 结果。 → `components/interrupt-message.md`
+- **KnowledgeRagContent 知识召回内容** — 渲染知识召回活动，包含加载态、Markdown 内容与引用来源。 → `components/knowledge-rag-content.md`
+- **ReferenceDocContent 引用文档活动** — 渲染引用文档类活动内容，复用 ActivityLayout 与 ReferenceContent。 → `components/reference-doc-content.md`
+- **SimpleTable 简易表格** — FlowAgent 节点详情中的轻量表格展示组件。 → `components/simple-table.md`
+- **ToolApprovalCard 工具审批卡片** — 渲染 AIDevToolApproval 中断的审批信息与取消/刷新操作，readonly prop 支持纯只读展示。 → `components/tool-approval-card.md`
+- **ToolcallRender 工具调用渲染器** — 渲染 assistant toolCalls，展示工具调用状态、参数和结果。 → `components/toolcall-render.md`
+- **UserQuestionAnsweredCard 用户问题回答回显** — 在 UserQuestion resume 成功后回显用户回答或取消状态。 → `components/user-question-answered-card.md`
+- **UserQuestionCard 用户问题中断** — 渲染 UserQuestion 中断的待回答面板；一次一题分页切换，支持单选/多选、Others、跳过与已完成进度。 → `components/user-question-card.md`
+- **UserQuestionChoice 用户问题选择题** — UserQuestionCard 默认的选择题渲染组件，封装单选/多选、Others 输入与答案组装。 → `components/user-question-choice.md`
+- **UserQuestionOption 用户问题选项** — UserQuestionChoice 内部选项行，处理单选/多选状态和 Others 输入。 → `components/user-question-option.md`
+
+### 工具与反馈
+
+- **DeleteTool 删除确认按钮** — 消息删除二次确认工具。 → `components/delete-tool.md`
+- **MessageTime 消息时间** — 按「今天 / 昨天 / 今年内 / 跨年」四档格式展示消息创建时间。 → `components/message-time.md`
+- **MessageTools 消息工具栏** — 消息悬浮工具栏，组合复制、删除、反馈等工具按钮。 → `components/message-tools.md`
+- **ScrollBtn 滚动按钮** — 停止生成或返回底部等滚动/状态按钮。 → `components/scroll-btn.md`
+- **ToolBtn 工具按钮** — 工具栏图标按钮。 → `components/tool-btn.md`
+- **UserFeedback 用户反馈** — 用户反馈弹层，提交踩/反馈原因。 → `components/user-feedback.md`
+
+### 辅助能力
+
+- **ActivityLayout 活动布局** — 活动消息的折叠布局容器，提供 title/default 插槽。 → `components/activity-layout.md`
+- **AiLoading 三点加载** — 小尺寸 AI 加载动效。 → `components/ai-loading.md`
+- **FileIcon 文件类型图标** — 按文件扩展名渲染对应类型图标，尺寸随外层 font-size 自适应。 → `components/file-icon.md`
+- **HighlightKeyword 关键词高亮** — 根据注入关键词高亮文本片段。 → `components/highlight-keyword.md`
+- **MessageLoading 品牌加载** — 带品牌图标和逐字渐变动画的加载组件。 → `components/message-loading.md`
+- **QuestionsContainer 问题容器占位** — 源码为空文件，没有 props、emits、slots 或渲染能力；不建议作为功能组件使用。 → `components/questions-container.md`
+- **ResourceIcon 资源图标** — 按 URL / Vue 组件 / 类型兜底三级策略渲染资源图标，图片失效自动回退。 → `components/resource-icon.md`
+- **SelectionQuestion 选择问题占位** — 源码为空文件，没有 props、emits、slots 或渲染能力；不建议作为功能组件使用。 → `components/selection-question.md`
+- **VNodeRenderer VNode 渲染器** — 将 Markdown token 转成 VNode 的内部渲染桥。 → `components/vnode-renderer.md`
+
+## Composables 组合式函数
+
+- **useAnimationText** — 文本淡入动画的组合式函数。将响应式文本按**增量**拆分为独立 chunk，每个新增 chunk 对应一次淡入动画，适用于 AI 流式输出的逐段渐显效果。 → `composables/use-animation-text.md`
+- **useArtifactPreview** — Provider/Consumer 模式的文件产物预览状态管理，用于 ChatContainer 侧栏「文件产物」Tab 的命中与切换。 Provider 在 ChatContainer 中创建，Consumer 在深层文件卡片中注入使用。 → `composables/use-artifact-preview.md`
+- **useClipboard** — 复制文本到剪贴板的组合式函数。内置两级降级策略，并自动通过 bkui-vue `Message` 提示复制结果，调用方无需关心成功/失败处理。 → `composables/use-clipboard.md`
+- **useCommandSelection** — 为 `edix` 富文本编辑器提供光标位置追踪能力的组合式函数。内部封装一个 `EditorCommand`，由编辑器调用后将光标的行列信息存入响应式变量，供后续编辑命令（如插入 tag、删除关键词）精确定位。 → `composables/use-command-selection.md`
+- **useContainerScroll** — 为消息容器提供滚动控制的组合式函数对，通过 **Provider/Consumer** 模式在父子组件间共享滚动状态。 → `composables/use-container-scroll.md`
+- **useCustomTab** — Provider/Consumer 模式的自定义 Tab 管理，用于 `ChatContainer` 侧边栏的 Tab 动态管理。Provider 在 `ChatContainer` 中创建，Consumer 在任意后代组件中注入使用。 → `composables/use-custom-tab.md`
+- **useFlowNodeActions** — 聚合 FlowAgent 节点行尾操作（详情 / 重试 / 跳过）为声明式视图模型列表，显隐与 resume 回调收敛于此。 → `composables/use-flow-node-actions.md`
+- **useFullScreen** — 基于浏览器原生 Fullscreen API 的全屏控制组合式函数，自动嗅探标准与 WebKit 前缀，状态与 ESC 退出保持同步。 → `composables/use-full-screen.md`
+- **useGlobalConfig** — 在聊天根容器与子组件之间通过 provide/inject 共享全局展示配置（字号主题档位、是否支持上传、消息时间时区、输入框菜单数据源）。 → `composables/use-global-config.md`
+- **useInputMention** — 通过 provide/inject 把「资源插入输入框」的能力开放给任意深度的后代组件。 → `composables/use-input-mention.md`
+- **useMenuKeydown** — 为弹出菜单提供键盘导航能力的组合式函数。在 `onMounted` 时于 **`window` 捕获阶段**注册 `keydown` 监听，在 `onScopeDispose` 时自动移除，通过 `menuRef.offsetParent` 检测菜单可见性来决定是否响应按键。 → `composables/use-menu-keydown.md`
+- **useMessageGroup** — 核心消息分组逻辑，将原始 `Message[]` 数组转换为结构化的 `MessageGroup[]`。处理 Tool 消息合并、Loading 自动注入、执行摘要过滤和消息多选/分享等逻辑。 → `composables/use-message-group.md`
+- **useObserverVisibleList** — 基于 `ResizeObserver` 的容器宽度感知组合式函数：遍历列表项的实际 `offsetWidth`，使用贪心算法计算在容器中能完整显示的项目子集，并为"更多"按钮动态预留空间。 → `composables/use-observer-visible-list.md`
+- **useParentScrolling** — 向上递归查找**最近可滚动祖先**，监听其 `scroll` / `scrollend` 事件，提供 `isScrolling` 状态。常用于滚动时自动关闭浮层、禁用交互等场景。 → `composables/use-parent-scrolling.md`
+
+## 类型定义
+
+- **常量枚举** — `@blueking/chat-x` 导出的常量和枚举类型。 → `types/constants.md`
+- **类型定义** — `@blueking/chat-x` 提供完整的 TypeScript 类型定义。 → `types/index.md`
+- **中断类型 Interrupt** — AG-UI human-in-the-loop 中断相关类型，含 Interrupt、UserQuestion、InterruptMessage 与 resume 回调。 → `types/interrupt.md`
+- **消息类型** — `@blueking/chat-x` 提供了完整的消息类型定义，用于构建 AI 对话消息。 → `types/messages.md`
+- **用户问题 Schema** — 历史 human-in-the-loop 用户问题 JSON Schema 工具；新 UserQuestion 中断协议以 Interrupt 文档为准。 → `types/schema.md`
+
+## Utils 工具函数
+
+- **工具函数** — `@blueking/chat-x` 提供了一些工具函数，用于处理 Markdown、Cookie 等常见操作。 → `utils/index.md`
+
+## Directives 指令
+
+- **指令总览** — `@blueking/chat-x` 目前提供以下 Vue 自定义指令： → `directives/index.md`
+- **OverflowTips** — 当元素文本**水平溢出**（`scrollWidth > clientWidth`）时，鼠标悬停自动弹出 Tippy tooltip 显示完整内容；未溢出时不创建实例，零性能损耗。 → `directives/overflow-tips.md`
+
+## Plugins Markdown 插件
+
+- **插件** — `@blueking/chat-x` 提供了一些 Markdown-it 插件，用于扩展 Markdown 的解析能力。 → `plugins/index.md`
+- **markdownItContainer** — Markdown-it 自定义容器插件，支持 ::: name ... ::: 语法，用于对齐块等场景。 → `plugins/markdown-container.md`
+- **markdownItLatex** — Markdown-it LaTeX 解析插件，用于解析 LaTeX 数学公式语法。 → `plugins/markdown-latex.md`
+- **markdownItMermaid** — Markdown-it Mermaid 解析插件，用于解析 Mermaid 图表代码块。 → `plugins/markdown-mermaid.md`
+
+## Icons 图标
+
+- **图标** — `@blueking/chat-x` 内置了 76 个 SVG 图标：其中 70 个通过 Vue `h()` 预创建为 VNode 对象，可直接用于模板渲染； → `icons/index.md`
+
+## 主题
+
+- **主题配置** — `@blueking/chat-x` 使用 SCSS 变量和 CSS 类来控制样式，支持通过覆盖变量或样式来自定义主题。 → `theme/theme.md`

package/skills/blueking-chat-x/references/components/activity-layout.md

@@ -0,0 +1,134 @@
+# ActivityLayout 活动布局
+
+> 能力域：辅助能力 ｜ 未从包入口导出：内部组件，请通过上层组件使用 ｜ since 1.0.0
+
+活动消息的折叠布局容器，提供 title/default 插槽。 源码位置：src/components/chat-content/activity-layout/activity-layout.vue。
+
+**关联**：activity-message（活动消息通过本组件承载标题栏与内容区）、knowledge-rag-content（知识召回活动复用本组件展示加载标题与正文）、reference-doc-content（引用文档活动复用本组件展示文档数量与引用列表）、flow-agent-content（FlowAgent 活动复用本组件，但隐藏默认折叠箭头）
+
+---
+
+# ActivityLayout 活动布局
+
+> **能力域**：辅助能力
+
+`ActivityLayout` 是活动消息的通用折叠布局容器，负责渲染标题栏、折叠箭头和内容区域。它不关心活动内容类型本身，标题和正文均通过插槽传入，因此常被 `KnowledgeRagContent`、`ReferenceDocContent`、`FlowAgentContent` 等活动组件复用。
+
+通常不需要业务侧直接使用；如果要新增一种活动消息内容，可以用它作为标题/内容外壳。
+
+## 源码事实
+
+- **源码位置**：`src/components/chat-content/activity-layout/activity-layout.vue`
+- **能力说明**：活动消息的折叠布局容器，提供 `title` / `default` 插槽。
+
+## 核心能力
+
+- **标题栏点击折叠**：点击标题栏切换 `collapsed`，内容区通过 `v-show="!collapsed"` 显示或隐藏
+- **双向绑定**：通过 `v-model:collapsed` 让父组件控制展开/收起状态，默认展开
+- **标题插槽透传状态**：`title` 插槽会收到 `{ collapsed }`，可根据折叠状态调整标题内容
+- **默认折叠箭头**：非 FlowAgent 活动自动在标题右侧显示折叠箭头
+- **FlowAgent 特例**：`activityType === MessageContentType.FlowAgent` 时隐藏默认折叠箭头，由 FlowAgent 自己渲染标题交互
+
+## 基础用法
+
+```vue
+<template>
+  <ActivityLayout v-model:collapsed="collapsed">
+    <template #title="{ collapsed }">
+      <span class="ai-activity-message-title-icon">
+        <DocumentIcon style="font-size: 12px" />
+      </span>
+      <span class="ai-activity-message-title-text">
+        {{ collapsed ? '已折叠' : '引用 2 篇资料作为参考' }}
+      </span>
+    </template>
+
+    <div style="padding: 0 14px;">
+      活动内容
+    </div>
+  </ActivityLayout>
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import ActivityLayout from '@blueking/chat-x/src/components/chat-content/activity-layout/activity-layout.vue';
+  import { DocumentIcon } from '@blueking/chat-x/src/icons/content';
+
+  const collapsed = ref(false);
+</script>
+```
+
+**渲染效果**
+
+## 折叠状态
+
+`collapsed` 默认为 `false`。设置为 `true` 时只展示标题栏，正文内容保留在 DOM 中但通过 `v-show` 隐藏。
+
+## FlowAgent 活动
+
+传入 `activityType="flow_agent"` 时，`ActivityLayout` 不渲染右侧默认折叠箭头。该场景下标题栏通常由 `FlowAgentContent` 自己展示状态统计、加载图标和展开箭头。
+
+```vue
+<ActivityLayout
+  v-model:collapsed="collapsed"
+  :activity-type="MessageContentType.FlowAgent"
+>
+  <template #title>
+    <span>执行情况: 成功 2 / 失败 1</span>
+  </template>
+  <div>FlowAgent 节点列表</div>
+</ActivityLayout>
+```
+
+## 组件结构
+
+```
+.ai-activity-message
+├── .ai-activity-message-title（点击切换 collapsed）
+│   ├── title slot（slot props: { collapsed }）
+│   └── CollapsedIcon（activityType !== flow_agent 时显示）
+└── .ai-activity-message-content（v-show="!collapsed"）
+    └── default slot
+```
+
+## API
+
+### Props
+
+| 属性名       | 类型                 | 必填 | 默认值 | 说明                                          |
+| ------------ | -------------------- | ---- | ------ | --------------------------------------------- |
+| activityType | `MessageContentType` | 否   | —      | 活动类型；为 `flow_agent` 时隐藏默认折叠箭头 |
+
+### Models
+
+| 名称      | 类型      | 默认值  | 说明             |
+| --------- | --------- | ------- | ---------------- |
+| collapsed | `boolean` | `false` | 活动内容是否折叠 |
+
+### Emits
+
+- 无显式 emits；`v-model:collapsed` 会产生 `update:collapsed`。
+
+### Slots
+
+| 插槽名  | 参数                    | 说明       |
+| ------- | ----------------------- | ---------- |
+| title   | `{ collapsed: boolean }` | 标题栏内容 |
+| default | —                       | 活动正文   |
+
+### Expose
+
+- 无。
+
+## 使用建议
+
+- 适合作为活动消息内部布局外壳，不建议替代通用卡片、面板或页面 Section。
+- 标题栏点击区域会整体触发折叠，标题插槽内如有按钮或链接，需要自行处理事件冒泡。
+- `default` 内容使用 `v-show` 控制可见性，折叠时不会卸载内部组件。
+
+## 关联组件
+
+- [ActivityMessage](../message/activity-message.md) — 活动消息分发入口。
+- [KnowledgeRagContent](../agent/knowledge-rag-content.md) — 知识召回活动。
+- [ReferenceDocContent](../agent/reference-doc-content.md) — 引用文档活动。
+- [FlowAgentContent](../agent/flow-agent-content.md) — FlowAgent 执行活动。