@legendzd/ai-agent-vue 1.0.6 → 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 直接访问对话数据、控制会话
@@ -380,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 两种写法
 
@@ -563,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` | 表头背景 |
@@ -582,16 +608,33 @@ const chatRef = ref()
 流式对话接口返回的 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，供高级场景使用：
@@ -627,6 +670,7 @@ import {
   type AgentFullLayoutProps,
   type AgentMobileLayoutProps,
   type ChatMessage,
+  type MessageStructuredData,
   type SessionInfo,
   type SourceInfo,
   type StreamCallbacks,
@@ -647,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('流结束'),
@@ -682,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)
 ```
 
 ## 开发