add vitepress docs

2026-09-21 16:05:14 +08:00
parent b435bf992e
commit 37cf38fe27
73 changed files with 7003 additions and 802 deletions
@@ -0,0 +1,70 @@
+# AiChatPanel 对话面板
+
+把消息列表与输入框组装成完整对话界面，由业务侧驱动数据。
+
+## 基础用法
+
+:::preview 基础用法 || 回答由本地假流逐块吐出，可随时点「停止」
+
+demo-preview=../demos/ai-chat-panel/basic.vue
+
+:::
+
+## 何时使用
+
+需要一个开箱即用的对话界面时使用。面板本身是**纯展示组件**——它不发起请求、不维护会话，全部状态由外部传入。
+
+## 与 useAiChat 接线
+
+库提供了 `useAiChat` 组合式函数管理会话与流式消息，把它的返回值直接摊给面板即可：
+
+```vue
+<script lang="ts" setup>
+import { AiChatPanel, useAiChat } from "timi-tdesign-mobile";
+
+const {
+	messages, isGenerating, activeToolStatus, lastError, canRetry,
+	sendMessage, stopGeneration, retryLastMessage
+} = useAiChat({
+	request: ({ message, signal }) => fetchReply(message, signal)
+});
+</script>
+
+<template>
+	<ai-chat-panel
+		:messages="messages"
+		:is-generating="isGenerating"
+		:active-tool-status="activeToolStatus"
+		:last-error="lastError"
+		:can-retry="canRetry"
+		@send="sendMessage"
+		@stop="stopGeneration"
+		@retry="retryLastMessage"
+	/>
+</template>
+```
+
+`request` 需要返回一个 SSE 流式的 `Response`，其余能力（历史会话、错误文案、上下文切换）都通过 `useAiChat` 的可选配置注入，组件侧不用改。
+
+## SSE 事件协议
+
+`useAiChat` 内置了一套事件协议，`event:` 后跟事件名、`data:` 后跟 JSON 或纯文本：
+
+| 事件名（含别名） | 作用 | 载荷取值字段 |
+| --- | --- | --- |
+| `thinking` / `think` / `agent_thought` | 思考过程分段 | `thought`、`thinking`、`reasoning`、`observation`、`text`、`content` |
+| `answer` / `message` / `text` | 回答正文增量 | `answer`、`text`、`content` |
+| `tool-status` / `tool_status` | 工具调用状态 | `text`、`message`、`statusText`、`status` |
+| `citation` / `source` | 引用信息 | `source`、`dataDomain`、`timeRange`、`caliber`、`generatedAt` |
+| `done` / `finish` / `completed` | 生成结束 | `conversationId`、`duration` |
+| `error` | 流内错误 | `message`、`code` |
+
+载荷是纯文本时会直接当作内容使用。协议不匹配时可以用 `parseEvent` 自行转换。
+
+## 自定义
+
+`welcome`、`composer`、`tool-status`、`message` 等插槽可以替换对应区域。`composer` 插槽会拿到 `draft`、`on-send`、`on-stop`、`on-retry` 等，便于接入自定义输入框。
+
+## API
+
+<api-table name="AiChatPanel" />