# Blueking Chat X

> 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。

- Skill: `tencentblueking/blueking-chat-x` (Agent Skill, multi-file: 93 files)
- Install (CLI): `npx skillmds@latest add tencentblueking/blueking-chat-x`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tencentblueking/blueking-chat-x/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tencentblueking (https://skillmd.com/u/tencentblueking)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tencentblueking/blueking-chat-x

---


# 使用 @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 一站式，推荐入口）

```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/theme 写出 + 生成 `_index.md`。

## 通用项目规则

中文回复、不擅自处理 eslint/格式、运行脚本需先经同意、git 提交禁用 `--no-verify`、不确定先问——见仓库 `AGENTS.md` 与 `.cursor/rules/project.mdc`。