# @deep-eye/core 中文文档

规范地址：https://npmcn.com/package/%40deep-eye/core/

版本：1\.3\.80
npm 元数据更新时间：2026-11-05T12:23:20.081Z
中文译文更新时间：2026-11-11T19:42:04.045Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deep-eye/core
原文对照：https://npmcn.com/package/%40deep-eye/core/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：29.6 MB，838 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：vue ^3\.5\.0
- 首次发布：2026-05-07T02:04:26.506Z
- 最新版本发布：2026-11-05T12:23:19.888Z
- 近 30 天下载量：4383（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：169（近 12 个月 169 个）

## 中文简介

Vue 3 企业Vue 3 组件库 深通前端团队

## 安装

```sh
npm install @deep-eye/core
```

也可以使用：`pnpm add @deep-eye/core`、`yarn add @deep-eye/core`、`bun add @deep-eye/core`

## README

# @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(...)` 整体注册；请通过包管理器安装后使用具名导入。

## 安装

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

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

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

## 快速开始：ChatBot

```vue
<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` 作为终态权威结果做一次性校准。

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

## 标准消息模型

```ts
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` | 交互式思维导图：缩放、拖拽、展开折叠、多套内置主题 |

```vue
<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>
```

```vue
<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>
```

```vue
<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）。≥ 1.3.79 起，引用悬浮 tip 和文本目录里的公式与正文一样渲染，PDF 页图文字层仍是纯文本；「产出文件」列表固定宽 480px，单文件预览仍默认 55%，文件名溢出时悬停才显示全文；侧栏任务历史把带前导零的 Java 日期按本地时间计算。≥ 1.3.80 起，满 5 轮的对话在左侧显示会话索引；模型列表与详情卡宽 300px，消耗速度读 `ratio`；独立成段且已闭合、能通过图表校验的 ` ```json ` / ` ```echarts ` 直接画成图。询问用户优先走 `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` 开启后：编辑、删除、排序、终态自动出队）。≥ 1.3.77 配置 `cloud.chat` 后可把排队消息插入正在生成的这一轮；请求失败退回队列。≥ 1.3.78 起，行上只留「立即发送」和「删除」，「编辑消息」和「引导」在「更多」菜单里。`ChatBotExpose.steerQueueItem(id)` 可由宿主触发同一操作，接口默认 `/agent/generic/responses/instruction`，可用 `cloud.chat.instructionUrl` 覆盖。引导原文在过程组内显示为「用户引导」，历史会话同样可以查看。
-   **`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 自定义属性：

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

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

```html
<!-- 显式指定 -->
<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

内部使用，保留所有权利。详见仓库根目录 [LICENSE](https://npmcn.com/package/LICENSE)。

## 常见问题

### @deep-eye/core 是什么？

Vue 3 企业Vue 3 组件库 深通前端团队

### 如何安装 @deep-eye/core？

在项目目录运行 npm install @deep-eye/core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.5\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @deep-eye/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @deep-eye/core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @deep-eye/core 可以商用吗？

@deep-eye/core 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @deep-eye/core 的下载量有多少？

根据 npm 官方下载统计，@deep-eye/core 在 2026/10/12 – 2026/11/10 这 30 天内被下载 4,383 次，日均约 146 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deep-eye/core 还在维护吗？

最新版本 1\.3\.80 发布于 2026/11/05（6 天前）；至今共发布 169 个版本，其中过去 12 个月发布了 169 个；首次发布于 2026/05/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。