--- url: /chat/chatbot.md --- # Chatbot 对话窗口 开箱可用的 AI 对话窗口：消息流（Markdown 渲染、代码块复制、思考过程、附件、流式光标）、输入区（Enter 发送 / Shift+Enter 换行、输入法组字安全、字数与附件上限、停止生成）、动作条（复制 / 重新生成，键盘与触屏可达）。接口层完全由你承接——`send` 事件拿到输入，回写 `modelValue` 即完成闭环。 ::: tip 这个家族住在独立包里 本页组件属于 `@wil-works/evoke-chat`（2026-09 从 `@wil-works/evoke-business-ui` 拆出，`marked` / `highlight.js` 只在用得上时才进依赖树）。装两个包并各自注册一次即可： ```js import EvokeBusinessUI from '@wil-works/evoke-business-ui' // 底座：基础组件 + 设计令牌 import '@wil-works/evoke-business-ui/styles' import EvokeChat from '@wil-works/evoke-chat' import '@wil-works/evoke-chat/styles' app.use(EvokeBusinessUI) app.use(EvokeChat) ``` ::: ## 基础对话 发送后回写消息数组，异步回复用 `loading` 显示打字态： ## 流式输出与思考过程 > 示例统一用 460~520px 的窗口高度：输入区固定约占 96px，正文区吃掉其余空间——高度给太小会只露出半条消息。 配合导出的 `useChatEngine` 组装流式会话：`appendContent` 逐段回写正文（状态自动进入 streaming，正文末尾出现流式光标，重解析按帧合并），`appendThinkContent` 写入思考内容（消息上方出现可折叠的思考块，流式期间自动展开、结束后可收起），`completeMessage` 收尾并自动记录回答用时。`regenerate` 事件里删掉旧回复后按上文重新流式输出即可： 不想等流式也能看清思考块的三种形态——**思考中**（自动展开、内容实时追加）、**已深度思考**（结束后收起、可点开）、**带用时**（结束时间点折成 `thinkDuration`，标题右侧给「（用时 X）」）： 消息项上的思考字段：`thinking: true` 表示正在思考（流式期间强制展开），`thinkContent` 是思考正文，`thinkDuration`（毫秒）是思考耗时——由引擎的 `appendThinkContent` / `stopThinking` / `completeMessage` / `cancelMessage` 自动结算，宿主手写静态数据时也可直接给；`thinkInterrupted: true` 表示思考阶段就被停止，思考块标题据此改说「思考已中断」。 ## 停止生成与中断态 `stoppable` 让发送钮在 `loading` 期间变成停止钮，点击抛 `stop`（AbortController 由你自持）。中断时用 `cancelMessage` 把该条消息置为 `cancelled` 而不是 `error`：已流出的正文原地保留，下面挂一行「已停止生成」灰标，而不是整段被红色错误块替换；若停的时候还在思考，思考块标题改说「思考已中断」并补上思考用时，不会谎报「已深度思考」。生成中输入框保持可打字，便于准备下一句；Enter 既不并发投递也不会误触中断。 ## 头像、名称与纯文本 `user-name` / `assistant-name` 决定双方昵称与头像首字，`avatar-user` / `avatar-assistant` 传图片地址可替换为图片头像；`render-mode` 切换为 `text` 后消息不再解析 Markdown，适合展示日志、代码原文等纯文本。 `show-avatar` / `show-name` 把头像与昵称整块隐去（适合头像已由外层提供、或消息密集的窄栏），传 `{ user: false }` / `{ assistant: false }` 可分侧关闭；**时间戳默认就在消息下方**，与动作条同排、悬浮消息（或键盘聚焦）时一起出现，`show-time` 可整块关掉： 也想分侧控制时传对象——只隐去自己那侧（对方仍带头像昵称）： ## 自定义动作与事件埋点 `actions` 在助手消息的动作条上追加自定义动作（`{ key, label, icon? }`，icon 使用组件库图标名）；`copy` / `regenerate` / `action` 事件把消息对象透传给页面，在此上报埋点或执行业务逻辑。动作条悬停消息时显示： ## 追问建议、评价与编辑重发 `editable` 给你的消息加「编辑」，点开后原地变输入框，保存抛 `edit`（原文与新文两参）；`feedback` 在助手回答下加点赞点踩，点踩会展开结构化原因与备注面板，提交抛 `feedback`（消息 + `{ value, reasons, note }`）；回答尾部的追问 chips 来自消息的 `suggestions` 字段，点击抛 `suggestion-click`。三者都由 `modelValue` 承载状态，宿主负责回写。**版面约定：追问 chips、评价、动作条落在消息下方同一行**（chips 吃掉剩余宽度、可换行；评价与动作条靠右，动作条仍随悬浮出现）；点踩展开原因面板时，评价块整行铺开——面板太窄读不了： ## 来源引用与行内上标 消息带 `citations` 数组即渲染来源卡列表（序号 / favicon / 标题 / 域名 / 摘要，可折叠；条目可带 `status` 说明定位状态——如「未定位」——与域名同行展示，不必把它拼进标题）。正文里的行内引用用 **`source:` 协议**书写——`[1](source:c1)` 渲染成可点击上标，点击会展开来源列表并高亮对应卡片，同时抛 `citation-click`： 链接文字是纯数字就直接用作序号；不是数字则按本次渲染递增分配。刻意不做裸 `[1]` 自动识别——那会和有序列表、脚注、代码里的方括号打架；宿主若拿到的是 Perplexity 风格的裸数字，在自己的 transport 里改写成 `[n](source:id)` 即可。 ## 工具调用卡 消息带 `toolCalls` 数组即在正文之前渲染执行轨迹（先执行再作答）：每步一行，带状态标记、状态文案与耗时，有参数或结果时可展开。多个步骤自动归到组标题下——跑着说「正在执行 N 个步骤」（带流光），跑完结算成「执行了 N 个步骤（用时 X）」。失败态给重试钮并在折叠行露出错误首行，点击抛 `tool-retry`（工具调用 + 消息两参）。 配合 `useChatEngine` 的状态机驱动：`startToolCall(msgId, { name, args })` 新建并转执行中（传已存在的 `id` 则复用），`addSubToolCall(msgId, parentCallId, { name, args })` 给某个调用挂子调用（返回子调用 id，与 `startToolCall` 一致；父不存在或超过 16 层返回 null），这三个写操作都按 id **递归**作用到子调用上；`appendToolCallResult(msgId, callId, chunk)` 逐片回写工具输出（状态自动转执行中并打上 `streaming`，卡片露出光标、自动展开并贴底），`completeToolCall(msgId, callId, result)` 收尾并自动记耗时（**省略 `result` 时保留已流出的输出**），`failToolCall(msgId, callId, error)` 转失败。整轮被 `cancelMessage` 中断时，还在跑/等待的调用会落 `cancelled`（「已停止」），且不再接收迟到的增量或收尾。参数与结果默认走带环检测的 JSON `
`，宿主可用 `#args` / `#result` 插槽换成 `EbJsonViewer` 等。

## 系统提示消息

`role` 为 `system` 或 `notice` 的消息按系统提示呈现：居中一行、弱化底色，不带头像 / 昵称 / 动作条，也不参与复制、评价与编辑。适合「以上为历史对话」「已切换到某模型」这类分隔性说明。正文仍走 Markdown，`render-mode="text"` 时原样显示。

`message` 插槽接管整条消息的渲染，作用域参数给 `message` / `index` / `isLast` / `itemProps`（`itemProps` 就是 `ChatList` 本来要传给内部 `ChatMessage` 的全量 props）。只想让某几类消息长得不一样、其余照旧，用 `itemProps` 显式回落即可，不必自己重接头像与动作条：

只换正文、保留消息外壳（头像 / 思考块 / 工具卡 / 来源卡 / 动作条）用 `message-content`，作用域参数给 `message` / `content` / `renderMode` / `streaming`。两者同时给以 `message` 为准。`EbChatMessage` 单独使用时对应插槽名为 `content`。

一点要注意：插槽**产出为空时 Vue 会回落默认渲染**（空模板、仅注释、`v-if` 为假都算空）。所以不能靠「把不想显示的行留空」来隐藏消息——那样得到的是默认渲染，不是空白。

## 附件与输入控制

`max-length` 限制输入长度，`show-word-count` 显示字数；`max-attachments` 限制附件数量。附件投递支持点 `+` 选文件、**拖拽进输入区**、**直接粘贴剪贴板里的图片**三种方式（`allow-drop` 可关）。

类型与体积由 `accept` / `max-file-size` 约束——浏览器对 `input[accept]` 只是建议，拖拽和粘贴路径组件会自己按同一套规则校验；不合格的文件经 `attachment-reject(file, reason)` 交回，`reason` 取 `type` / `size` / `limit` / `empty`，提示文案由你决定。

上传状态由你回写附件对象驱动（组件不自己发请求）：`status: 'uploading'` + `progress` 显示进度条，`'error'` + `error` 显示失败原因，`'done'` 显示已上传；不写 `status` 的历史附件不出现任何状态位。

## 自定义区域与实例方法

`header` 定制面板标题栏，`empty` 定制空会话占位，`tip` 替换底部提示，`sender-toolbar` 在输入框工具栏追加按钮（示例配合 `v-model:input-value` 受控输入）；实例方法 `focus()` / `scrollToBottom(smooth)` / `reset()` 支持外部操控，注意 `reset()` 不会回写 `v-model`，受控使用时需同步清空绑定数组：

## 正文渲染配置

对话正文的 Markdown 管线从包入口导出四个函数，宿主可在挂载前统一调配置：

```js
import {
  configureChatMarkdown,
  getChatMarkdownConfig,
  renderChatMarkdown,
  registerHighlightLanguage,
} from '@wil-works/evoke-chat'

// 自定义协议链接的主题色（默认 entity→primary、doc→info、action→danger …）
configureChatMarkdown({ protocolThemes: { ticket: 'warning' } })

// 放行宿主自己的协议；data: 默认不在链接白名单内（聊天内容不可信）
configureChatMarkdown({ standardProtocols: { add: ['https'] } })

// 默认高亮只带 highlight.js/lib/common 的 36 种语言，冷门语言自行注册
import cobol from 'highlight.js/lib/languages/cobol'
registerHighlightLanguage('cobol', cobol)
```

数学公式与图表同理——**渲染器由你注入**，包内不引这两个依赖：

```js
import katex from 'katex'
import 'katex/dist/katex.min.css'   // 样式与字体要自己引

configureChatMarkdown({
  // (tex, displayMode) => html；返回的内容按原样插入，转义由你的渲染器负责
  math: (tex, display) => katex.renderToString(tex, { displayMode: display, throwOnError: false }),
})

// mermaid 是异步的，塞不进同步渲染管线：围栏保留为代码块，旁边多一个
// 「渲染图表」按钮，点击后调这个函数并把代码块换成返回的 SVG
configureChatMarkdown({
  mermaid: async (source) => {
    const { svg } = await mermaid.render(`m${Date.now()}`, source)
    return svg
  },
})
```

不注入就不出现：`$x$` 与 `$$…$$` 原样保留，mermaid 围栏就是普通代码块。数学的行内识别带两条保守规则——`$` 内侧不留空白，且纯数字内容（`$100 与 $200` 这类金额写法）直接放行不当公式。宿主渲染器抛错时退回转义原文，不影响整篇。

安全边界（都是刻意选择，不是漏做）：正文里的 raw HTML 一律转义为纯文本展示，`