@legendzd/ai-agent-vue 1.0.4 → 1.1.0

package/README.md

@@ -8,8 +8,11 @@
 - **多实例隔离** — 通过 `instanceId` 创建独立对话实例，不同用户/场景互不干扰
 - **零配置即插即用** — 内置 Pinia + 持久化，宿主应用无需额外安装状态管理
 - **会话管理** — 自动创建会话、历史记录、一键切换/新建对话
-- **SSE 流式对话** — 支持 status/sql/data/chart_config/sources/analysis_chunk 等富事件类型
-- **富内容渲染** — Markdown 代码高亮、SQL 可展开复制、结构化数据表格、ECharts 图表、来源标签
+- **SSE 流式对话** — 支持 session/status/sql/data/chart_config/sources/run_plan/analysis_chunk 等富事件类型
+- **分类存储与可配置渲染** — SQL/数据表格默认隐藏，执行计划可折叠，均可通过配置控制显隐
+- **富内容渲染** — Markdown 代码高亮、SQL 可展开复制、结构化数据表格、ECharts 图表（支持暗色主题联动）、编号引用来源、执行计划折叠面板
+- **增强错误样式** — 带左侧色条 + 警告图标的错误提示，深浅色主题适配
+- **结构化数据访问** — 通过实例 ID 或消息 ID 获取 sql/data/chartConfig/sources/runPlan 等结构化数据
 - **深色/浅色主题** — 通过 CSS 变量一键切换或自定义覆盖，所有布局均支持
 - **语音输入** — 基于浏览器 Web Speech API，可配置语言
 - **组件实例 API** — 通过 ref 直接访问对话数据、控制会话
@@ -42,15 +45,18 @@ app.use(AgentPlugin, {
 app.mount('#app')
 ```
 
-在模板中直接使用（插件注册后组件全局可用）：
+在模板中直接使用（插件注册后组件全局可用，自动继承全局配置）：
 
 ```vue
 <template>
-  <!-- 按钮弹窗布局（默认） -->
+  <!-- 按钮弹窗布局（默认），自动继承全局注册的 apiUrl/userId -->
   <AgentChat />
 
   <!-- 等价于 -->
   <AgentChatPopup />
+
+  <!-- 如需覆盖某项配置，只需传递对应字段即可 -->
+  <AgentChat :config="{ headerTitle: 'AI 助手' }" />
 </template>
 ```
 
@@ -80,6 +86,15 @@ import '@legendzd/ai-agent-vue/dist/style.css'
 右下角浮动按钮 + 弹出式聊天窗口，适合嵌入任意页面。
 
 ```vue
+<!-- 已全局注册过配置时，直接使用即可 -->
+<AgentChatPopup />
+
+<!-- 或覆盖特定配置 -->
+<AgentChatPopup :config="{
+  userId: 'user456',
+}" />
+
+<!-- 未全局注册时，需通过 config 传入必要配置 -->
 <AgentChatPopup :config="{
   apiUrl: 'http://your-server/api/v2',
   userId: 'user123',
@@ -96,6 +111,14 @@ import '@legendzd/ai-agent-vue/dist/style.css'
 左侧历史侧栏 + 右侧聊天窗口，适合作为独立聊天页面使用。
 
 ```vue
+<!-- 已全局注册过配置时 -->
+<AgentChatFull
+  :show-sidebar="true"
+  sidebar-width="280px"
+  sidebar-position="left"
+/>
+
+<!-- 未全局注册时 -->
 <AgentChatFull
   :config="{ apiUrl: 'http://your-server/api/v2', userId: 'user123' }"
   :show-sidebar="true"
@@ -122,6 +145,13 @@ import '@legendzd/ai-agent-vue/dist/style.css'
 全屏聊天 + 底部抽屉式历史面板，适配移动端安全区域。
 
 ```vue
+<!-- 已全局注册过配置时 -->
+<AgentChatMobile
+  safe-area-top="env(safe-area-inset-top, 0px)"
+  safe-area-bottom="env(safe-area-inset-bottom, 0px)"
+/>
+
+<!-- 未全局注册时 -->
 <AgentChatMobile
   :config="{ apiUrl: 'http://your-server/api/v2', userId: 'user123' }"
   safe-area-top="env(safe-area-inset-top, 0px)"
@@ -353,6 +383,10 @@ destroyChatInstance('user-a')
 | `enableVoice` | `boolean` | `true` | 是否启用语音输入（浏览器不支持时自动隐藏） |
 | `voiceLang` | `string` | `'zh-CN'` | 语音识别语言 |
 | `instanceId` | `string` | `'default'` | 实例 ID，用于多实例隔离 |
+| `showSql` | `boolean` | `false` | 是否在消息中显示 SQL 区域 |
+| `showData` | `boolean` | `false` | 是否在消息中显示数据表格区域 |
+| `showRunPlan` | `boolean` | `true` | 是否显示执行计划/思考过程面板 |
+| `defaultRunPlanExpanded` | `boolean` | `false` | 执行计划面板默认是否展开 |
 
 ### userId 两种写法
 
@@ -368,7 +402,7 @@ API 层优先使用 `getUserId()`，若未提供则 fallback 到 `userId` 静态
 
 ### config prop 合并规则
 
-组件同时支持顶层 props 和 `config` prop，`config` 优先：
+配置按优先级从高到低合并：**组件 config prop > 组件顶层 props > 全局插件注册 > 默认值**
 
 ```vue
 <!-- 两种写法等价 -->
@@ -380,6 +414,11 @@ API 层优先使用 `getUserId()`，若未提供则 fallback 到 `userId` 静态
   user-id="fallback"
   :config="{ userId: 'priority' }"
 />
+
+<!-- 全局注册的配置自动继承，组件只需覆盖差异项 -->
+<!-- 假设 app.use(AgentPlugin, { apiUrl: 'http://...', userId: 'user123' }) -->
+<AgentChat :config="{ headerTitle: 'AI 助手' }" />
+<!-- 等价于 { apiUrl: 'http://...', userId: 'user123', headerTitle: 'AI 助手' } -->
 ```
 
 ## 组件实例 API
@@ -531,6 +570,25 @@ const chatRef = ref()
 | `--agent-empty-color` | `#5a6b8a` | 空状态文字颜色 |
 | `--agent-error-color` | `#f87171` | 错误文字颜色 |
 | `--agent-error-bg` | `rgba(248,113,113,0.1)` | 错误背景色 |
+| `--agent-error-border` | `0.0625rem solid rgba(248,113,113,0.3)` | 错误边框 |
+| `--agent-error-border-radius` | `0.5rem` | 错误提示圆角 |
+| `--agent-error-padding` | `0.5rem 0.75rem` | 错误提示内边距 |
+| `--agent-error-icon-color` | `#f87171` | 错误图标颜色 |
+| `--agent-error-text-color` | `#fca5a5` | 错误文本颜色 |
+
+#### 执行计划
+
+| 变量 | 默认值（深色） | 说明 |
+|---|---|---|
+| `--agent-run-plan-bg` | `rgba(99,102,241,0.06)` | 执行计划背景色 |
+| `--agent-run-plan-border` | `0.0625rem solid rgba(99,102,241,0.15)` | 执行计划边框 |
+| `--agent-run-plan-border-radius` | `0.5rem` | 执行计划圆角 |
+| `--agent-run-plan-text-color` | `#a5b4fc` | 执行计划文本色 |
+| `--agent-run-plan-toggle-color` | `rgba(99,102,241,0.5)` | 展开/折叠图标色 |
+| `--agent-run-plan-icon-color` | `#818cf8` | 执行计划图标色 |
+| `--agent-run-plan-font-size` | `0.8125rem` | 执行计划字号 |
+| `--agent-run-plan-line-height` | `1.5` | 执行计划行高 |
+| `--agent-run-plan-padding` | `0.5rem 0.75rem` | 执行计划内边距 |
 | `--agent-code-block-bg` | `#0d1117` | 代码块背景 |
 | `--agent-table-border` | `#253354` | 表格边框色 |
 | `--agent-table-header-bg` | `#1a2340` | 表头背景 |
@@ -541,25 +599,42 @@ const chatRef = ref()
 
 | 功能 | 方法 | 完整路径 |
 |---|---|---|
-| 创建会话 | POST | `${apiUrl}/agent/chat/session` |
-| 流式对话 | POST | `${apiUrl}/agent/chat/chat/stream` |
-| 获取历史 | GET | `${apiUrl}/agent/chat/sessions?userId=xxx` |
+| 创建会话 | POST | `${apiUrl}/external/chat/session` |
+| 流式对话 | POST | `${apiUrl}/external/query-data/stream` |
+| 获取历史 | GET | `${apiUrl}/external/chat/sessions?userId=xxx` |
 
 ### SSE 事件类型
 
 流式对话接口返回的 SSE 事件格式：
 
 ```json
+{ "type": "session", "session_id": 123 }
 { "type": "status", "content": "正在查询数据..." }
 { "type": "sql", "content": "SELECT * FROM ..." }
 { "type": "data", "content": [{"col1": "val1", "col2": 100}] }
 { "type": "chart_config", "content": { /* ECharts 配置对象 */ }
 { "type": "sources", "content": [{ "id": "db", "title": "数据库" }] }
+{ "type": "run_plan", "content": "1. 解析用户意图\n2. 查询相关数据..." }
 { "type": "analysis_chunk", "content": "正在分析..." }
 { "type": "done", "report_id": 123, "title": "分析报告" }
 { "type": "error", "message": "分析失败" }
 ```
 
+### SSE 事件分类说明
+
+| 事件类型 | 是否渲染 | 说明 |
+|---|---|---|
+| `session` | 否 | 会话信息，自动保存 session_id |
+| `status` | 是 | 状态提示（如"正在分析意图"），渲染为等待文字+脉冲动画 |
+| `sql` | 可配置 | 生成的 SQL 语句，默认不渲染，通过 `showSql: true` 开启 |
+| `data` | 可配置 | SQL 查询结果数据，默认不渲染为表格，通过 `showData: true` 开启 |
+| `chart_config` | 是 | ECharts 图表配置，使用 useEcharts 渲染（支持暗色主题联动） |
+| `sources` | 是 | 引用来源，渲染为文末编号引用列表，正文中 `[1]` 自动转为上标链接 |
+| `run_plan` | 可配置 | 执行计划/思考过程，默认渲染为可折叠面板，通过 `showRunPlan` 控制 |
+| `analysis_chunk` | 是 | 正文文本流式片段 |
+| `done` | 否 | 流结束标记，携带 report_id 和 title |
+| `error` | 是 | 错误事件，渲染为带左侧色条+警告图标的错误提示 |
+
 ## 编程式 API
 
 除组件方式外，插件也导出了底层 API 和 Store，供高级场景使用：
@@ -595,6 +670,7 @@ import {
   type AgentFullLayoutProps,
   type AgentMobileLayoutProps,
   type ChatMessage,
+  type MessageStructuredData,
   type SessionInfo,
   type SourceInfo,
   type StreamCallbacks,
@@ -615,9 +691,14 @@ setAgentOptions({ apiUrl: 'http://your-server/api/v2' })
 const controller = streamChat(
   { sessionId: 'xxx', query: '你好', userId: 'user123' },
   {
+    onSession: (sid) => console.log('会话ID:', sid),
     onStatus: (text) => console.log('状态:', text),
-    onAnalysisChunk: (chunk) => process.stdout.write(chunk),
+    onSql: (sql) => console.log('SQL:', sql),
+    onData: (data) => console.log('数据:', data),
     onChartConfig: (config) => renderChart(config),
+    onSources: (sources) => console.log('来源:', sources),
+    onRunPlan: (text) => console.log('执行计划:', text),
+    onAnalysisChunk: (chunk) => process.stdout.write(chunk),
     onDone: (reportId, title) => console.log('完成:', title),
     onError: (msg) => console.error('错误:', msg),
     onComplete: () => console.log('流结束'),
@@ -650,6 +731,10 @@ await chatStore.loadSessions()
 await chatStore.newChat()
 chatStore.switchSession('some-session-id')
 chatStore.clearMessages()
+
+// 按消息 ID 获取结构化数据（sql/data/chartConfig/sources/runPlan）
+const msgData = chatStore.getMessageData('message-id')
+console.log(msgData?.sql, msgData?.chartConfig)
 ```
 
 ## 开发