| 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/* |
| 最小接入怎么写 | 本文「快速接入」一节 |
references 缺失或过期时，按本文「再生成 references」一节重新生成。
心智模型（一句话）
消息驱动 + 角色分发：业务维护一份 Message[] → ChatContainer（或 useMessageGroup）分组 → MessageRender 按 message.role 分发到具体消息组件 → ContentRender 按内容类型分发 → MarkdownContent 按 token 分发。
接入心智：你只负责维护 messages 数组和实现 onSendMessage 等回调，组件负责渲染与交互。
快速接入（ChatContainer 一站式，推荐入口）
<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。
怎么查一个组件（标准流程）
- 在
references/_index.md 里按名称/能力域找到组件，拿到它的 path。
- 读
references/components/<slug>.md：顶部是能力域 + 导入符号 + 概述 + 关联组件，正文含「核心能力 / 基础用法 / API（Props/Events/Slots/Expose/v-model）/ 类型定义」。
- 按 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 / 跨年；无 不渲染 |
类型与常量速查
import type { Message, UserMessage, AssistantMessage, ToolMessage, IToolBtn, Shortcut, TagSchema } from '@blueking/chat-x';
import {
MessageRole, MessageStatus, MessageContentType,
CONST_MESSAGE_TOOLS,
CONST_USER_MESSAGE_TOOLS,
} from '@blueking/chat-x';
更全的类型/常量定义查 references/types/*。
再生成 references
references 由脚本从 wikis/ 生成。当库升级、wikis 更新，或 references 缺失/过期时重新生成（运行脚本前需经用户同意）：
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/theme 写出 + 生成 _index.md。
通用项目规则
中文回复、不擅自处理 eslint/格式、运行脚本需先经同意、git 提交禁用 --no-verify、不确定先问——见仓库 AGENTS.md 与 .cursor/rules/project.mdc。
