@skillpet/chat-vue

文档

• 在线 API 文档 — 前端组件完整接口参考（AI 可读版）
• 后端对接手册 — HTTP 接口、SSE 协议、消息存储（AI 可读版）
• llms.txt — AI 文档索引

功能特性

• SSE 流式对话，实时显示 AI 思考过程与工具调用
• 子智能体（consult agent）多轮对话与工具步骤展示
• 结构化提问（ask_user）表单交互
• ask_user 选项支持 description 描述（v0.11，卡片式选项布局）
• 流式排队发送 — AI 回复中可继续输入，消息自动排队按序发送（v0.6）
• 队列管理 — 编辑、删除、拖拽排序排队中的消息（v0.6）
• 附件增强 — 拖放文件上传、粘贴图片上传、图片缩略图预览（v0.6）
• 图片生成展示与选择（display / 单选 / 多选，v0.7）
• readOnly 只读模式：隐藏输入区，仅展示消息流（v0.9+）
• ChatPanelHandle：forwardRef 暴露命令式 API，与 readOnly 组合使用（v0.10+）
• 斜杠指令面板
• 内置 7 种语言（zh-CN、zh-TW、en、ja、ko、es、fr）
• 蓝色品牌色默认主题，支持深色/浅色模式
• CSS 变量完全自定义配色
• Markdown 渲染
• Vue 3.3+ 兼容

安装

npm install @skillpet/chat-vue

自动安装 @skillpet/chat-core（类型/SSE/i18n）及 lucide-vue-next、markdown-it 等依赖。

快速开始

<script setup>
import { ChatPanel } from "@skillpet/chat-vue";
import "@skillpet/chat-core/styles.css";

const config = {
  api: {
    baseUrl: "/api/chat",
    deleteConversationUrl: "/api/chat/conversation",
  },
  getAccessToken: () => localStorage.getItem("token"),
};
</script>

<template>
  <ChatPanel project-id="my-project" :config="config" />
</template>

三层 API

Layer 1: 开箱即用

| 导出 | 说明 | |------|------| | ChatPanel | 主组件 SFC，包含完整聊天 UI | | provideChatConfig | 通过 provide/inject 注入配置 | | useChatConfig | 读取注入的配置 | | setChatLanguage | 切换 i18n 语言 |

Layer 2: 自定义组合

| 导出 | 说明 | |------|------| | useChatPanel | Composable，返回响应式状态和操作 | | MessageBubble | 消息气泡 SFC | | AskUserBlock | 结构化表单 SFC | | ThinkingBlock | AI 思考过程 SFC | | SlashCommandPalette | 斜杠指令面板 SFC |

Layer 3: 底层原语

| 导出 | 说明 | |------|------| | processSSEStream | SSE 流处理（从 core 重导出） | | parseHistoryMessages | 历史消息解析（从 core 重导出） |

ChatPanel Props

| Prop | 类型 | 必选 | 说明 | |------|------|------|------| | projectId | string | 是 | 项目/会话 ID | | config | ChatPanelConfig | | API 地址、鉴权等配置 | | quickStarters | string[] | | 空状态快捷开场文案 | | emptyState | ChatPanelEmptyState | | 自定义空状态 | | extraSlashCommands | SlashCommand[] | | 追加斜杠指令 | | onUploadAttachment | (file: File) => Promise<ChatAttachment> | | 自定义附件上传 | | onDeleteAttachment | (id: string) => Promise<void> | | 自定义附件删除 | | capVisibleOverride | string[] | | 覆盖能力可见列表（如 ["thinking", "queuedSend"]） | | avatars | { botAvatarUrl?, userAvatarUrl? } | | 覆盖头像 | | readOnly | boolean | | 只读模式，隐藏输入区与 quickStarter 按钮（v0.9+） | | className | string | | 追加 CSS 类名 |

readOnly (v0.9.0+)

boolean | undefined，默认 false。

启用后 <ChatPanel> 进入"只读模式"，仅展示消息流，不渲染底部输入区与空状态的 quickStarter 按钮。 适用于工作流运行态、历史回放、只读访客视图等场景。

<template>
  <ChatPanel project-id="..." :read-only="true" :empty-state="{ title: '等待中…' }" />
</template>

宿主仍可通过 useChatPanel composable 的 handleSend(payload, undefined, { suppressUserBubble: true }) 程序化派发首条消息。

chatRef — ChatPanelHandle (v0.10.0+)

通过 defineExpose 暴露命令式 API，适用于 readOnly 模式下程序化控制消息流。

<script setup>
import { ref, onMounted } from "vue";
import { ChatPanel } from "@skillpet/chat-vue";
import type { ChatPanelHandle } from "@skillpet/chat-vue";

const chatRef = ref<ChatPanelHandle | null>(null);

onMounted(() => {
  chatRef.value?.handleSend(
    JSON.stringify({ action: "start" }),
    undefined,
    { suppressUserBubble: true }
  );
});
</script>

<template>
  <ChatPanel ref="chatRef" :read-only="true" :config="config" />
</template>

ChatPanelHandle API

| 方法 | 说明 | |---|---| | handleSend(msg?, attachments?, opts?) | 发送消息；opts.suppressUserBubble: true 隐藏用户气泡 | | setMessages(updater) | 直接更新消息列表（外部进度同步等） | | stopGeneration() | 中断当前 SSE 流 | | scrollToBottom(animated?) | 滚动到底部 | | getMessages() | 获取当前消息列表快照 |

多配置共享

<script setup>
import { ChatPanel, provideChatConfig } from "@skillpet/chat-vue";

provideChatConfig({
  api: { baseUrl: "/api/chat", deleteConversationUrl: "/api/chat/conversation" },
  getAccessToken: () => localStorage.getItem("token"),
});
</script>

<template>
  <ChatPanel project-id="project-a" />
  <ChatPanel project-id="project-b" />
</template>

排队发送（v0.6）

当后端 /init 接口返回 capabilities.queuedSend.enabled: true 时自动启用。API 与 React 版完全对等。

useChatPanel 新增返回值：queuedSendCap、queuedSendEnabled、messageQueue、enqueueMessage、removeQueuedMessage、popQueuedMessage、reorderQueue、clearQueue。

图片生成 (v0.7)

支持后端推送 AI 生成的图片，三种展示模式：

• display：纯展示，点击放大
• single_select：单选一张后提交
• multi_select：多选（min~max 张）后提交

通过 SSE 事件 image_generating（加载态）和 image_generation（完成态）推送，useChatPanel 返回 handleImageSelect 处理选择结果。

详见 API 文档 中的「图片生成」章节。

自定义 UI

<script setup>
import { useChatPanel, MessageBubble } from "@skillpet/chat-vue";
import "@skillpet/chat-core/styles.css";

const chat = useChatPanel({
  projectId: "xxx",
  config: { /* ... */ },
});
</script>

<template>
  <div class="skillpet-chat">
    <MessageBubble v-for="msg in chat.messages.value" :key="msg.id" :msg="msg" />
  </div>
</template>

主题定制

与 React 版共享同一套 CSS 变量系统。深色模式通过 .dark 类或 [data-theme="dark"] 自动切换。

.skillpet-chat {
  --skillpet-chat-primary: oklch(0.6 0.22 145);
}

i18n

import { setChatLanguage } from "@skillpet/chat-vue";
setChatLanguage("en"); // zh-CN | zh-TW | en | ja | ko | es | fr

CDN 使用

<script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>
<script src="https://unpkg.com/@skillpet/chat-core/dist/index.umd.js"></script>
<script src="https://unpkg.com/@skillpet/chat-vue/dist/index.umd.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@skillpet/chat-core/dist/skillpet-chat.css" />

<div id="app" class="skillpet-chat"></div>
<script>
  const { ChatPanel } = SkillpetChatVue;
  const app = Vue.createApp({
    components: { ChatPanel },
    template: `<ChatPanel project-id="demo" :config="config" />`,
    setup() {
      return { config: { /* ... */ } };
    },
  });
  app.mount("#app");
</script>

License

MIT