@deep-eye/core

深瞳前端团队的企业级 Vue 3 组件库，提供 AI 对话（ChatBot / ChatMessage / ChatSender）与可视化思维导图（D3MindMap）两类核心能力。

环境要求

| 依赖 | 最低版本 | | ------- | ------------------------------------------- | | Node.js | 22.0.0（LTS） | | Vue | 3.5.0（peerDependency，需宿主项目自行安装） |

组件库只发布 ES Module 与 CommonJS 两种产物，不提供浏览器 <script> 标签可用的 UMD/IIFE 版本，也不支持 app.use(...) 整体注册；请通过包管理器安装后使用具名导入。

安装

pnpm add @deep-eye/core
# 或 npm install @deep-eye/core / yarn add @deep-eye/core

在应用入口手动引入一次样式（不会被自动注入）：

import '@deep-eye/core/style.css'

快速开始：ChatBot

<script setup lang="ts">
import { ref } from 'vue'
import { ChatBot } from '@deep-eye/core'
import type { ChatBotExpose, ChatSendPayload, ConversationMessage } from '@deep-eye/core'

const chatBotRef = ref<ChatBotExpose>()
const messages = ref<ConversationMessage[]>([
  { role: 'assistant', content: '你好，有什么可以帮助你？' },
])

async function handleSend(payload: ChatSendPayload) {
  // payload.message 已写入 v-model:messages，适合业务持久化。
  // payload.modelInput：纯文本为 string；附件默认在 resource_files
  const response = await fetch('/api/responses', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ input: [payload.modelInput], stream: true }),
  })
  await chatBotRef.value?.consume(response)
}
</script>

<template>
  <ChatBot ref="chatBotRef" v-model:messages="messages" @send="handleSend" style="height: 600px" />
</template>

ChatBot 直接消费企业 Agent Responses API 返回的原始 HTTP SSE Response 对象，不接受 completion chunk、[DONE]、session/resume 或其他自定义流格式。consume() 在 response.output_text.delta、reasoning 与 function call 参数到达时立即更新最后一条 assistant 消息；response.completed.response / response.incomplete.response 作为终态权威结果做一次性校准。

await chatBotRef.value?.consume(response, {
  signal: controller.signal,
  onEvent(event, frame) {
    console.log(event.type, event.sequence_number, frame.raw)
  },
})

response.failed、error、未知事件类型、非法序号和异常 EOF 会使 consume() 抛出异常，同时保留已收到的部分 assistant 内容；response.incomplete 会保留部分内容并正常结束；调用 abort() 后流状态变为 aborted。

标准消息模型

import type { ConversationMessage } from '@deep-eye/core'

const messages: ConversationMessage[] = [
  { role: 'system', content: '回答要简洁。' },
  { role: 'user', resource_files: [], content: '描述这张图' },
  {
    role: 'assistant',
    reasoning_content: '先识别主体，再概括场景。',
    content: '图片中是一片山谷。',
    tool_calls: [
      {
        id: 'call_1',
        type: 'function',
        function: { name: 'search', arguments: '{"query":"山谷"}' },
      },
    ],
  },
  { role: 'tool', tool_call_id: 'call_1', content: '{"count":3}' },
]

user.content 保存原文，附件通过 resource_files 携带；引用过的技能 / 知识库写在可选的 user.mentions 上，气泡会高亮 /名称 和 @名称。ChatSendPayload.modelInput 对齐火山方舟 message InputItem（纯文本 content 为 string，不传 type；有媒体 ContentItem 时文本才是 input_text），附件默认走 modelInput.resource_files（项目扩展；attachmentInput 可改为官方 media parts），不会写入 messages。发送时可选带上 mentions（含 kind: knowledge | skill）和当前场景的原始 sceneId：mentions 同时写入 message.mentions 供气泡高亮，宿主还可在 cloud.chat.getParams 里组装业务字段。assistant 支持 content、reasoning_content、encrypted_content 与 tool_calls；tool 消息通过 tool_call_id 关联对应的工具调用。

主要组件

| 组件 | 用途 | | ------------- | ------------------------------------------------------------------------------------- | | ChatBot | 完整聊天界面：消息列表、输入框、附件、工具调用、可选工件侧栏，内置 Responses SSE 消费 | | ChatMessage | 单条标准消息的渲染：富文本、多模态、思考区、工具调用，可脱离 ChatBot 独立使用 | | ChatSender | 独立输入框：草稿、附件上传、截图、语音、快捷功能 | | D3MindMap | 交互式思维导图：缩放、拖拽、展开折叠、多套内置主题 |

<script setup lang="ts">
import { ChatMessage } from '@deep-eye/core'

const message = {
  role: 'assistant' as const,
  reasoning_content: '正在整理要点。',
  content: '答案支持 **Markdown**、公式和富媒体。',
}
</script>

<template>
  <ChatMessage :message="message" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ChatSender } from '@deep-eye/core'

const draft = ref('')
</script>

<template>
  <ChatSender v-model:draft="draft" show-attachment @send="(payload) => console.log(payload)" />
</template>

<script setup lang="ts">
import { D3MindMap } from '@deep-eye/core'

const data = {
  nodeData: {
    id: 'root',
    topic: '组件库',
    root: true,
    children: [{ id: 'chat', topic: 'ChatBot' }],
  },
}
</script>

<template>
  <D3MindMap :data="data" height="600px" show-toolbar />
</template>

assistant content 原生支持 GFM、代码高亮、KaTeX 公式、图片/视频/音频，以及组件库定义的 mdoc 标签（工件卡片、Chart、Action Bar）。询问用户优先走 ask_user tool（arguments: { desc, questions }）；正文仍可写 {% ask-form %} 作兼容。将 ARTIFACT_BLOCK_SYSTEM_PROMPT、ASK_USER_FORM_SYSTEM_PROMPT、CHART_BLOCK_SYSTEM_PROMPT 或 ACTION_BAR_SYSTEM_PROMPT 加入 system prompt 可引导模型；ChatBot 会自动 dock Ask Form。带 toolCallId 的提交显示在「向用户提问」工具回复里（题干 + 加粗选项），不再另起用户气泡。宿主只需用 buildAskUserFunctionCallOutput(toolCallId, answers) 续接 function_call_output——不要用 answers[].selected 拼文案。没有 toolCallId 的正文 {% ask-form %} 仍写入用户气泡（action.label）。点击工件卡片按类型分流（可预览进侧栏 / 图片灯箱 / 新标签 / 直接下载），消息内渲染 {% chart %} 与 {% action-bar %}。

进阶能力

除以上四个主要组件外，@deep-eye/core 还导出一组可组合使用的 API，用于更细粒度的定制：

• ChatProvider：统一配置上传方式、附件限制、主题、颜色模式与实例级 renderer，作用于内部所有 ChatBot 实例。
• ConversationList、ChatQueue：多会话列表与可选的流式消息队列（enableQueue 开启后：编辑、删除、排序、终态自动出队）。
• registerToolRenderer / registerChatPreviewRenderer：注册自定义工具调用渲染器与附件预览渲染器。
• useConversation：messages 数组的本地状态管理（appendMessage、setMessages、reset），不处理网络或 SSE。
• ChatBot.hydrateHistory / normalizeAgentHistoryMessages：把 GA agent_history.messages 直接灌入对话（库内消化 steps → flat 字段；ask_user 的 function_call_output 显示在工具回复里，不再补用户气泡），宿主无需 mapper。
• useMindMapTheme / useMindMapLayout：D3MindMap 主题与布局的组合式函数。
• 附件相关工具函数、classifyChatError 错误分类等。

这些 API 的完整签名与用法示例见仓库 packages/docs 文档站点的「进阶用法」章节。

主题定制

组件的 Design Token 默认值已内联在各自根元素的 scoped 样式中，引入 style.css 后即可获得正确外观，不存在可单独引入的 tokens.css 文件。自定义主题时，直接在宿主容器上覆盖同名 CSS 自定义属性：

.my-app {
  --accent: #7c3aed; /* 主色：链接、发送按钮、选中态 */
  --accent-hover: #6d28d9;
  --accent-subtle: #f5f3ff; /* 用户消息气泡背景 */
  --bg-canvas: #fafafa; /* 页面/容器底色 */
  --radius-md: 10px; /* 气泡、附件圆角 */
}

ChatBot 支持三种深色模式触发方式：

<!-- 显式指定 -->
<ChatBot data-chat-color-mode="dark" ... />

<!-- 适配宿主已有的全局主题系统 -->
<div data-theme="dark"><ChatBot ... /></div>

<!-- 跟随操作系统 -->
<ChatBot data-chat-color-mode="auto" ... />

完整 Token 清单与深色模式覆盖示例见文档站点的「主题与深色模式」章节。

完整文档

本 README 仅覆盖最小可用示例。完整的 Props / Events / Slots / Methods 参考、核心概念（消息模型与 Responses SSE 协议详解）、进阶用法与常见问题（FAQ），请查看仓库 packages/docs 目录下的 VitePress 文档站点源码。

License

MIT