@templmf/temp-solf-lmf 0.0.53 → 0.0.55

package/guanwang/docs/test-cases.md

@@ -0,0 +1,395 @@
+# 测试用例文档
+
+> 手动测试用例，覆盖核心功能路径。标注 `[自动化]` 的建议后续接入 Vitest / Playwright。
+
+---
+
+## 一、配置与初始化
+
+### T-001 单模型初始化
+**步骤**：配置单个模型，打开对话页  
+**预期**：输入栏不显示模型选择器，直接可发送消息
+
+### T-002 多模型初始化
+**步骤**：配置 2+ 个模型，打开对话页  
+**预期**：输入栏底部显示模型 pill，默认选中 `defaultModel`
+
+### T-003 features 全关
+**步骤**：`features: { artifact: false, upload: false, markdown: false, codepreview: false }`  
+**预期**：AI 回复纯文本，无代码高亮，无上传按钮，无 artifact 面板
+
+### T-004 userControls 不声明
+**步骤**：`features: { artifact: true }`，`userControls` 不写  
+**预期**：artifact 功能开启，设置面板中不显示 artifact 开关
+
+### T-005 设置持久化
+**步骤**：切换模型 → 刷新页面  
+**预期**：模型选择保持上次的值
+
+---
+
+## 二、对话核心
+
+### T-010 发送纯文本消息
+**步骤**：输入框输入文字 → Enter 发送  
+**预期**：用户气泡显示，AI 气泡流式输出，loading 状态正确
+
+### T-011 中止流式输出
+**步骤**：发送消息 → AI 输出中途点击"停止"  
+**预期**：输出停止，AI 气泡标记完成，loading 消失，可继续发送
+
+### T-012 发送后自动滚到底部
+**步骤**：消息列表超出可视区 → 发送新消息  
+**预期**：自动滚动到最新消息
+
+### T-013 用户上翻时不强制滚动
+**步骤**：AI 流式输出中 → 用户手动上翻  
+**预期**：不强制滚到底部，顶部显示"新消息"提示按钮
+
+### T-014 点击"新消息"跳到底部
+**步骤**：T-013 状态 → 点击"新消息"  
+**预期**：滚到底部，提示按钮消失
+
+### T-015 API 请求失败
+**步骤**：配置错误的 `baseURL` → 发送消息  
+**预期**：AI 气泡显示错误信息，不崩溃，可继续发送
+
+### T-016 多会话切换
+**步骤**：创建两个会话各发一条消息 → 来回切换  
+**预期**：消息列表正确隔离，artifact 各自独立
+
+### T-017 清空会话
+**步骤**：有消息的会话 → 点击"清空"  
+**预期**：消息清空，标题重置为"新对话"，artifact 面板关闭
+
+---
+
+## 三、多模型
+
+### T-020 运行时切换模型
+**步骤**：发送一条消息（模型A）→ 切换到模型B → 发送第二条消息  
+**预期**：两条消息使用不同模型，API 请求的 `baseURL` 各自正确
+
+### T-021 autoVision 自动切模型
+**步骤**：配置一个 `vision: true` 的模型，上传图片 → 发送  
+**预期**：自动使用 vision 模型，不显示切换提示
+
+### T-022 autoVision 纯文本不切换
+**步骤**：发送纯文本消息  
+**预期**：使用当前选中模型，不切换到 vision 模型
+
+---
+
+## 四、多模式
+
+### T-030 Code 模式默认
+**步骤**：打开对话，默认 Code 模式  
+**预期**：AI 自我介绍为 Code 角色，回答代码类问题
+
+### T-031 切换到 Ask 模式
+**步骤**：顶部模式切换 → Ask  
+**预期**：下一条消息 system prompt 变为 Ask 角色，AI 不主动输出代码文件
+
+### T-032 切换到 Architect 模式
+**步骤**：切换到 Architect → 提问"帮我设计一个用户系统"  
+**预期**：AI 先追问信息，不直接写代码，输出技术方案文档
+
+### T-033 需求模式四步流程
+**步骤**：切换到需求模式 → 输入"我想做一个商品管理功能"  
+**预期**：AI 先复述目标 → 列假设清单 → 识别系统边界 → 输出需求文档
+
+### T-034 模式 prompt 不跨会话污染
+**步骤**：在 Code 模式对话后 → 创建新会话 → 切换到 Ask 模式  
+**预期**：新会话使用 Ask 的 system prompt，不携带 Code 模式的历史
+
+---
+
+## 五、Tool-use
+
+### T-040 ask_followup_question 渲染
+**步骤**：触发 AI 输出 `<ask_followup_question>` 工具调用  
+**预期**：气泡底部显示选项按钮，点选后文字作为新消息发送
+
+### T-041 attempt_completion 标记完成
+**步骤**：AI 输出 `<attempt_completion>`  
+**预期**：当前 AI 消息标记为完成状态（视觉区分），不再 loading
+
+### T-042 switch_mode 切换提示
+**步骤**：AI 输出 `<switch_mode mode_slug="code" reason="...">`  
+**预期**：显示切换提示，模式切换，后续 system prompt 更新
+
+### T-043 render_artifact 触发面板
+**步骤**：AI 输出 `<render_artifact>` 工具  
+**预期**：右侧 artifact 面板展开，文件出现在 Tab 栏
+
+### T-044 request_context 引导提示
+**步骤**：AI 输出 `<request_context hint="请提供...">`  
+**预期**：消息列表追加系统提示，引导用户粘贴代码
+
+### T-045 onToolCall 覆盖默认行为
+**步骤**：消费方注册 `onToolCall('switch_mode', handler)` → AI 触发该工具  
+**预期**：执行消费方的 handler，不执行默认行为
+
+---
+
+## 六、Artifact 面板
+
+### T-050 生成文件并展示
+**步骤**：Code 模式请求生成 Vue 组件  
+**预期**：右侧面板展开，Tab 显示文件名，代码视图有行号和高亮
+
+### T-051 多文件切换
+**步骤**：AI 在一次回复中生成多个 artifact  
+**预期**：Tab 栏显示所有文件，点击可切换
+
+### T-052 复制代码
+**步骤**：点击复制按钮  
+**预期**：代码写入剪贴板，按钮短暂显示对勾
+
+### T-053 下载文件
+**步骤**：点击下载按钮  
+**预期**：浏览器下载文件，文件名与 artifact 一致
+
+### T-054 代码预览 HTML
+**步骤**：生成 HTML 代码 → 点击"预览" Tab  
+**预期**：iframe 正常渲染 HTML，无跨域报错
+
+### T-055 Vue SFC 预览
+**步骤**：生成 Vue 组件 → 切换到"预览" Tab  
+**预期**：`@vue/repl` 加载，组件正常编译渲染
+
+### T-056 流式高亮不闪烁
+**步骤**：观察 AI 流式输出代码时的面板  
+**预期**：代码逐行增加，无整体重绘闪烁，行号实时更新
+
+---
+
+## 七、Markdown 渲染
+
+### T-060 代码高亮
+**步骤**：AI 输出包含代码块的回复  
+**预期**：Shiki 高亮，深色/浅色主题跟随系统
+
+### T-061 主题切换重新渲染
+**步骤**：切换深色/浅色主题  
+**预期**：已渲染的消息高亮主题同步更新
+
+### T-062 KaTeX 数学公式
+**步骤**：AI 输出 `$E=mc^2$`  
+**预期**：公式正常渲染，不显示原始 LaTeX 文本
+
+### T-063 Mermaid 流程图
+**步骤**：AI 输出 mermaid 代码块  
+**预期**：图表正常渲染
+
+### T-064 原始文本调试面板 [仅开发]
+**步骤**：`.env` 设置 `VITE_SHOW_RAW_TEXT=true` → AI 回复  
+**预期**：气泡底部显示可折叠的原始文本和字符数，生产环境不显示
+
+---
+
+## 八、文件上传
+
+### T-070 上传图片
+**步骤**：点击附件按钮 → 选择图片 → 发送  
+**预期**：气泡内显示缩略图，API 请求包含 base64 图片数据
+
+### T-071 粘贴截图
+**步骤**：截图后在输入框 Ctrl+V  
+**预期**：图片作为附件添加，等同手动上传
+
+### T-072 上传代码文件
+**步骤**：上传 `.vue` 文件  
+**预期**：文件内容作为文本附入消息，气泡显示文件名图标
+
+### T-073 超过 5 个附件限制
+**步骤**：尝试添加第 6 个附件  
+**预期**：显示 warning 提示，不添加第 6 个
+
+### T-074 拖拽上传
+**步骤**：将文件拖入输入区域  
+**预期**：显示拖拽遮罩，松开后文件被添加
+
+---
+
+## 九、Headless 模式 `[自动化]`
+
+### T-080 useChat 返回正确状态
+**步骤**：调用 `useChat(config)`  
+**预期**：`messages` 初始为空数组，`isLoading` 为 false，`availableModels` 与 config 一致
+
+### T-081 send() 触发请求
+**步骤**：`send({ text: 'test' })`  
+**预期**：`isLoading` 变为 true，`messages` 追加 user 和 assistant 消息
+
+### T-082 messages 格式正确
+**步骤**：发送消息并等待响应  
+**预期**：user 消息含 `parts`，assistant 消息 `streaming` 从 true 变 false
+
+### T-083 switchMode 更新 currentMode
+**步骤**：`switchMode('ask')`  
+**预期**：`currentMode.value === 'ask'`，下一条消息使用 Ask 模式 prompt
+
+### T-084 selectModel 更新 selectedModel
+**步骤**：`selectModel('qwen3-7b')`  
+**预期**：`selectedModel.value.id === 'qwen3-7b'`
+
+---
+
+## 十、CodePreview 弹框
+
+### T-090 点击代码块打开
+**步骤**：AI 回复含代码块 → 点击右上角"预览"按钮  
+**预期**：弹框打开，默认"分屏"Tab，左代码右预览
+
+### T-091 代码区滚动独立
+**步骤**：代码行数超出可视区 → 滚动代码区  
+**预期**：代码区独立滚动，状态栏不随内容滚动消失
+
+### T-092 行列号更新
+**步骤**：点击代码区某行  
+**预期**：底部状态栏行号更新为点击行
+
+### T-093 Vue SFC 分屏不混乱
+**步骤**：打开 Vue SFC 代码的预览弹框  
+**预期**：只显示 `@vue/repl` 界面，不出现我们自己的 shiki 代码面板叠加
+
+---
+
+## 十一、埋点
+
+### T-100 埋点总开关关闭
+**步骤**：`.env` 设置 `VITE_TRACK_ENABLED=false` → 发消息、复制代码  
+**预期**：Network 面板无任何 Ackee 请求，控制台无报错
+
+### T-101 未配置 ACKEE_URL 时静默
+**步骤**：不设置 `VITE_ACKEE_URL` → 正常使用对话功能  
+**预期**：功能正常，无 Ackee 请求，无报错
+
+### T-102 页面访问上报
+**步骤**：切换路由（如从首页到 /chat）  
+**预期**：Ackee「页面访问」Event 收到对应路径的 action
+
+### T-103 消息发送三维度上报
+**步骤**：Code 模式 + qwen3-32b 模型 + 用户"张三"发送一条消息  
+**预期**：Ackee 中「消息发送-模式」key=code、「消息发送-模型」key=qwen3-32b、「消息发送-用户」key=张三 各增加 1
+
+### T-104 提问意图识别-代码生成
+**步骤**：Code 模式发送"帮我生成一个登录组件"  
+**预期**：「提问-意图」key=code_gen 增加 1
+
+### T-105 提问意图识别-调试
+**步骤**：Ask 模式发送"这段代码报错了怎么解决"  
+**预期**：「提问-意图」key=debug 增加 1
+
+### T-106 需求方向不上报意图
+**步骤**：需求模式发送任意消息  
+**预期**：「提问-方向」key=requirement 增加 1，「提问-意图」不上报（无新 action）
+
+### T-107 提问复杂度分级
+**步骤**：分别发送 <50字、50-200字、>200字 的消息  
+**预期**：「提问-复杂度」分别上报 short / medium / long
+
+### T-108 代码块复制埋点
+**步骤**：点击 AI 回复里代码块的复制按钮  
+**预期**：「内容复制-来源」key=code_block、「内容复制-用户」key=当前用户名 各增加 1
+
+### T-109 Artifact 面板复制埋点
+**步骤**：在 ArtifactPanel 点击复制按钮  
+**预期**：「内容复制-来源」key=artifact_panel 增加 1，同时「内容复制-语言」上报对应语言
+
+### T-110 文件下载埋点
+**步骤**：在 ArtifactPanel 点击下载按钮  
+**预期**：「文件下载-用户」和「文件下载-语言」各增加 1
+
+### T-111 回复耗时上报
+**步骤**：发送消息 → 等待 AI 完整回复  
+**预期**：「回复耗时」Event 的对应模型 key 新增一条数值记录，Chart 平均值有变化
+
+### T-112 中止上报
+**步骤**：AI 回复中途点击停止  
+**预期**：「回复中止」Event key=当前用户名 增加 1，「回复耗时」不上报
+
+### T-113 报错上报
+**步骤**：配置错误 apiKey → 发送消息触发 API 报错  
+**预期**：「回复报错」Event key=api 增加 1
+
+### T-114 模式切换上报
+**步骤**：手动从 Code 切换到 Ask 模式  
+**预期**：「模式切换」key=code→ask:manual 增加 1
+
+### T-115 未登录用户不上报用户维度
+**步骤**：未登录状态下发送消息  
+**预期**：「消息发送-用户」无新 action，「消息发送-模式」和「消息发送-模型」正常上报
+
+---
+
+## 十一、埋点
+
+### T-100 埋点总开关关闭
+**步骤**：`.env` 设置 `VITE_TRACK_ENABLED=false` → 发消息、复制、切换模式  
+**预期**：不发出任何网络请求到 Ackee，控制台无埋点相关日志
+
+### T-101 未配置 ACKEE_URL 时静默
+**步骤**：`.env` 不填 `VITE_ACKEE_URL` → 正常使用对话框  
+**预期**：所有功能正常，不报错，埋点静默丢弃
+
+### T-102 发消息触发模式/模型/用户三个 Event
+**步骤**：登录后在 Code 模式用 qwen3-32b 发一条消息  
+**预期**：Ackee 后台「消息发送-模式」出现 `code`，「消息发送-模型」出现 `qwen3-32b`，「消息发送-用户」出现对应用户名
+
+### T-103 提问方向分类
+**步骤**：在 Code 模式发消息 → 在需求模式发消息  
+**预期**：「提问-方向」出现 `code` 和 `requirement` 两个 key
+
+### T-104 意图识别-code_gen
+**步骤**：发送"帮我生成一个登录组件"  
+**预期**：「提问-意图」出现 `code_gen`
+
+### T-105 意图识别-debug
+**步骤**：发送"这段代码报错了怎么解决"  
+**预期**：「提问-意图」出现 `debug`
+
+### T-106 意图识别-其他（other）
+**步骤**：发送一条不包含任何意图关键词的消息  
+**预期**：「提问-意图」出现 `other`
+
+### T-107 需求模式不上报意图
+**步骤**：切换到需求模式发消息  
+**预期**：「提问-意图」无新增记录（需求方向不做意图细分）
+
+### T-108 复杂度分类
+**步骤**：分别发送 <50字、50-200字、>200字 的消息  
+**预期**：「提问-复杂度」出现 `short` / `medium` / `long`
+
+### T-109 代码块复制埋点
+**步骤**：点击 AI 回复里代码块的 Copy 按钮  
+**预期**：「内容复制-来源」出现 `code_block`，「内容复制-用户」出现当前用户名，「内容复制-语言」出现对应语言
+
+### T-110 Artifact 复制埋点
+**步骤**：在 ArtifactPanel 点击复制按钮  
+**预期**：「内容复制-来源」出现 `artifact_panel`
+
+### T-111 文件下载埋点
+**步骤**：在 ArtifactPanel 点击下载按钮  
+**预期**：「文件下载-语言」和「文件下载-用户」各新增一条记录
+
+### T-112 回复耗时上报
+**步骤**：发一条消息等待 AI 完整回复  
+**预期**：「回复耗时」Chart 有新增数据点，value 为合理的毫秒数（>0）
+
+### T-113 中止回复埋点
+**步骤**：发消息后点击"停止"按钮  
+**预期**：「回复中止」出现当前用户名
+
+### T-114 模式切换埋点
+**步骤**：从 Code 切换到 Ask 模式  
+**预期**：「模式切换」出现 `code→ask:manual`
+
+### T-115 工具调用埋点
+**步骤**：触发 AI 使用 `render_artifact` 工具  
+**预期**：「工具调用」出现 `render_artifact`
+
+### T-116 未登录用户不上报用户字段
+**步骤**：未登录状态下发消息并复制内容  
+**预期**：「消息发送-用户」和「内容复制-用户」无新增记录（不上报 anonymous）

package/guanwang/docs/usage.md

@@ -0,0 +1,291 @@
+# chat-sdk 使用文档
+
+## 两种接入方式
+
+### 方式一：完整视图模式
+
+挂载整套对话界面，无需自己写 UI。
+
+```js
+import { createAIChat } from '@/chat-sdk'
+
+createAIChat({
+  el: '#chat-container',
+
+  models: [
+    { id: 'qwen3-32b', name: 'Qwen3 32B', baseURL: 'http://192.168.1.100:8080', apiKey: 'sk-xxx', vision: false },
+    { id: 'qwen-vl',   name: 'Qwen VL',   baseURL: 'http://192.168.1.101:8080', apiKey: 'sk-yyy', vision: true  },
+  ],
+  defaultModel: 'qwen3-32b',
+  autoVision: true,
+
+  features: {
+    artifact:    true,
+    markdown:    true,
+    upload:      true,
+    codepreview: true,
+  },
+
+  userControls: {
+    modelSelector: true,
+    artifact:      true,
+    upload:        true,
+  },
+
+  modes: ['code', 'ask', 'architect', 'requirements'],
+  defaultMode: 'code',
+  customInstructions: '你是公司内部 AI 助手，回答请简洁专业。',
+})
+```
+
+---
+
+### 方式二：Headless 模式
+
+只接入能力，自己控制视图。
+
+```vue
+<script setup>
+import { useChat } from '@/chat-sdk/headless'
+
+const {
+  messages,
+  isLoading,
+  currentMode,
+  selectedModel,
+  availableModels,
+  activeArtifacts,
+  send,
+  abort,
+  switchMode,
+  selectModel,
+  clearSession,
+  newSession,
+  onToolCall,
+} = useChat({
+  models: [
+    { id: 'qwen3-32b', name: 'Qwen3 32B', baseURL: 'http://192.168.1.100:8080', apiKey: 'sk-xxx', vision: false },
+  ],
+  defaultModel: 'qwen3-32b',
+  modes: ['code', 'ask'],
+  defaultMode: 'code',
+  features: { artifact: true, markdown: true },
+})
+
+// 可选：覆盖工具默认行为
+onToolCall('ask_followup_question', ({ params, resolve }) => {
+  // 自己渲染选项 UI，用户选择后调用 resolve(answer)
+  showMyOptions(params.suggests, resolve)
+})
+</script>
+
+<template>
+  <div v-for="msg in messages" :key="msg.id">
+    <span>{{ msg.role }}</span>
+    <span>{{ msg.content }}</span>
+    <!-- activeArtifacts 自己决定如何渲染 -->
+  </div>
+  <button @click="send({ text: '你好' })">发送</button>
+</template>
+```
+
+---
+
+## config 完整字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `el` | `string \| HTMLElement` | 完整视图必填 | 挂载节点，如 `'#app'` |
+| `models` | `ModelConfig[]` | 是 | 模型列表，见下方 |
+| `defaultModel` | `string` | 是 | 默认模型 id |
+| `autoVision` | `boolean` | 否 | 消息含图片时自动切 `vision:true` 的模型 |
+| `features` | `FeaturesConfig` | 否 | 控制哪些 chunk 加载，见下方 |
+| `userControls` | `UserControlsConfig` | 否 | 控制哪些开关对用户可见 |
+| `modes` | `string[]` | 否 | 启用的模式，默认 `['code']` |
+| `defaultMode` | `string` | 否 | 默认模式 id |
+| `customInstructions` | `string` | 否 | 追加到所有模式 prompt 末尾的自定义指令 |
+| `title` | `string` | 否 | 对话框标题，默认 `'AI 助手'` |
+| `placeholder` | `string` | 否 | 输入框占位文字 |
+
+### ModelConfig
+
+```ts
+{
+  id:      string   // 模型唯一标识（也是发给 API 的 model 字段）
+  name:    string   // 显示名称
+  baseURL: string   // 接口地址，如 'http://192.168.1.100:8080'
+  apiKey:  string   // API Key，内网可传空字符串
+  vision:  boolean  // 是否支持图片输入
+}
+```
+
+### FeaturesConfig
+
+控制对应 chunk 是否下载，`false` 时代码完全不加载。
+
+| key | 说明 |
+|---|---|
+| `artifact` | 代码文件生成面板 |
+| `markdown` | Markdown / 代码高亮 / KaTeX 渲染 |
+| `upload` | 文件和图片上传 |
+| `codepreview` | 代码预览弹框（含 Vue SFC / HTML 预览）|
+
+### UserControlsConfig
+
+声明哪些开关在设置面板里对用户可见。
+
+| 值 | 含义 |
+|---|---|
+| `true` | 显示开关，默认开启，用户可关闭 |
+| `false` | 显示开关，默认关闭，用户可开启 |
+| 不填 | 不显示开关，强制开启 |
+
+---
+
+## useChat() 返回值
+
+### 状态（只读 ref）
+
+| 名称 | 类型 | 说明 |
+|---|---|---|
+| `messages` | `Ref<Message[]>` | 当前会话消息列表 |
+| `isLoading` | `Ref<boolean>` | 是否请求中 |
+| `currentMode` | `Ref<string>` | 当前模式 id |
+| `selectedModel` | `ComputedRef<ModelConfig>` | 当前选中模型 |
+| `availableModels` | `ModelConfig[]` | 全部可用模型（非响应式） |
+| `activeArtifacts` | `Ref<Artifact[]>` | 当前会话的 artifact 列表 |
+
+### 方法
+
+| 名称 | 签名 | 说明 |
+|---|---|---|
+| `send` | `(input: SendInput) => void` | 发送消息 |
+| `abort` | `() => void` | 中止当前流式请求 |
+| `switchMode` | `(modeId: string) => void` | 切换模式 |
+| `selectModel` | `(modelId: string) => void` | 切换模型 |
+| `clearSession` | `() => void` | 清空当前会话 |
+| `newSession` | `() => number` | 新建会话，返回会话 id |
+| `onToolCall` | `(name, handler) \| (handler)` | 注册工具回调 |
+
+### SendInput
+
+```ts
+// 纯文本
+send({ text: '帮我写一个登录组件' })
+
+// 带附件
+send({
+  text: '分析这张截图',
+  attachments: [{ type: 'image', file: File }],
+})
+```
+
+### Message 格式
+
+```ts
+{
+  id:        number
+  role:      'user' | 'assistant' | 'system-tip' | 'followup'
+  content:   string          // AI / 用户文字内容
+  parts:     Part[]          // 结构化内容（text / image / file）
+  streaming: boolean         // 是否流式输出中
+  error:     boolean         // 是否出错
+  artifacts: string[]        // 关联的 artifact id 列表
+}
+```
+
+---
+
+## 模式说明
+
+| 模式 id | 名称 | 职责 |
+|---|---|---|
+| `code` | Code | 编写、修改、重构代码，输出完整代码文件 |
+| `ask` | Ask | 解释概念、回答技术问题，不生成代码文件 |
+| `architect` | Architect | 系统设计、技术方案、架构拆解，输出技术文档 |
+| `requirements` | 需求 | 梳理需求，输出用户故事和功能拆解列表 |
+
+模式切换方式：
+```js
+// 代码切换
+switchMode('architect')
+
+// AI 自动触发（通过 switch_mode 工具）
+// 消费方监听
+onToolCall('switch_mode', ({ params, resolve }) => {
+  if (confirm(`切换到 ${params.mode_slug} 模式？`)) {
+    switchMode(params.mode_slug)
+    resolve()
+  }
+})
+```
+
+---
+
+## 埋点接入
+
+### 官网页面埋点
+
+在 `App.vue` 路由钩子和登录成功回调里接入：
+
+```js
+import { useTracker } from '@/tracker'
+const tracker = useTracker()
+
+// 路由 afterEach
+router.afterEach((to) => tracker.pageView(to.path))
+
+// 按钮点击
+tracker.btnClick('hero_cta', '立即体验')
+
+// 登录成功
+tracker.loginSuccess(user.name)
+```
+
+### 对话框埋点
+
+对话行为埋点（发消息、回复、中止、模式切换）已内置在 `useChatStore` 中，只需在 `createAIChat` config 里注入 `getUser`：
+
+```js
+createAIChat({
+  // ...其他配置
+  getUser: () => ({ name: currentUser.name, id: currentUser.id }),
+})
+```
+
+采纳行为埋点（复制、下载）在 `ArtifactPanel` 和 `MessageBubble` 里通过 `chatStore.tracker` 调用，已自动处理，无需额外接入。
+
+### 环境变量
+
+```env
+VITE_ACKEE_URL=http://your-ackee-server:3000    # Ackee 服务地址
+VITE_ACKEE_DOMAIN=your-domain-uuid              # Ackee Domain ID
+VITE_TRACK_ENABLED=true                          # false 时全部静默，默认 true
+```
+
+### 自定义关键词字典
+
+在 `src/tracker/config.js` 的 `INTENT_KEYWORDS` 里维护意图匹配关键词，修改后无需改动其他文件。
+
+---
+
+## 环境变量（guanwang 项目专用）
+
+项目根目录创建 `.env.local`：
+
+```env
+VITE_API_BASE_URL=http://192.168.1.100:8080
+VITE_API_KEY=sk-xxx
+VITE_MODEL=qwen3-32b
+
+# 多模型（逗号分隔）
+VITE_MODELS=qwen3-32b,qwen3-7b,qwen-vl
+
+# 调试：AI 气泡底部显示原始文本
+VITE_SHOW_RAW_TEXT=false
+
+# 埋点
+VITE_ACKEE_URL=http://192.168.1.200:3000
+VITE_ACKEE_DOMAIN=your-domain-uuid
+VITE_TRACK_ENABLED=true
+```