@templmf/temp-solf-lmf 0.0.54 → 0.0.55

package/guanwang/README.md

@@ -0,0 +1,95 @@
+# Citic Frontend（Vue 3 版）
+
+基于 **Vue 3 + Vite + Vue Router v4** 构建的Citic Frontend AI体验平台。
+
+## 快速启动
+
+```bash
+# 1. 安装依赖（需要 Node 18+）
+npm install
+
+# 2. 配置环境变量
+cp .env.local.example .env.local
+# 编辑 .env.local，填入模型 API 地址和 Key
+
+# 3. 启动开发服务器
+npm run dev
+
+# 4. 打包生产版本
+npm run build
+```
+
+## 环境变量
+
+| 变量名 | 说明 | 示例 |
+|---|---|---|
+| `VITE_API_BASE_URL` | 模型 API 地址（OpenAI 兼容） | `https://api.openai.com` |
+| `VITE_API_KEY` | API Key | `sk-xxxx` |
+| `VITE_MODEL` | 模型名称 | `gpt-4o` |
+
+## 项目结构
+
+```
+src/
+├── config/
+│   └── api.js                 # API 配置（读取 .env.local）
+├── services/
+│   ├── chatApi.js             # OpenAI 兼容流式请求封装
+│   └── authApi.js             # 登录/登出（mock，可替换为真实接口）
+├── composables/               # 对应 React Hooks
+│   ├── useAuth.js             # 全局用户状态（provide/inject）
+│   ├── useChatStore.js        # 聊天会话状态管理
+│   ├── useTheme.js            # 主题（深色/浅色）
+│   └── useCountUp.js          # 数字滚动动画
+├── components/
+│   ├── Navbar.vue             # 导航栏（含登录入口、用户头像下拉）
+│   ├── LoginModal.vue         # 登录弹框
+│   ├── ChatInputBar.vue       # 聊天输入框
+│   ├── ChatSidebar.vue        # 聊天侧边栏
+│   ├── MessageBubble.vue      # 消息气泡
+│   ├── ThemeToggle.vue        # 主题切换按钮
+│   ├── Footer.vue
+│   └── CustomCursor.vue       # 自定义鼠标（桌面端）
+├── views/
+│   ├── HomeView.vue           # 首页
+│   ├── ChatView.vue           # AI 对话页
+│   ├── MarketView.vue         # 组件市场
+│   ├── SkillsView.vue         # Skills 市场
+│   └── PracticesView.vue      # 最佳实践
+├── router/
+│   └── index.js               # Vue Router v4 路由配置
+├── styles/
+│   └── global.css             # CSS 变量 + 全局工具类
+├── App.vue                    # 根组件
+└── main.js                    # 入口文件
+```
+
+## 路由
+
+| 路径 | 页面 |
+|---|---|
+| `/` | 首页 |
+| `/chat` | AI 对话（需登录） |
+| `/market` | 组件市场 |
+| `/skills` | Skills 市场 |
+| `/practices` | 最佳实践 |
+
+## 登录账号（mock）
+
+| 账号 | 密码 | 角色 |
+|---|---|---|
+| `admin` | `admin123` | 管理员 |
+| `dev` | `dev123` | 开发者 |
+
+## React → Vue 3 迁移说明
+
+| React 原始方案 | Vue 3 方案 |
+|---|---|
+| `createContext` + `useContext` | `provide` / `inject` |
+| `useState` / `useRef` | `ref` |
+| `useMemo` | `computed` |
+| `useEffect` + `IntersectionObserver` | `onMounted` + `onUnmounted` |
+| `useCallback` | 普通函数（Vue 响应性系统不需要） |
+| JSX 内联子组件 | 拆分为独立 `.vue` 文件 |
+| `lucide-react` | `lucide-vue-next` |
+| `react-router-dom` | `vue-router` |

package/guanwang/docs/changelog.md

@@ -0,0 +1,145 @@
+# Changelog
+
+## [1.1.0] — 2025-03-20
+
+### 新增：埋点系统
+
+- `src/tracker/config.js`：埋点总配置，Ackee URL/Domain 从环境变量读取，21 个 Event UUID 集中管理，意图关键词字典和复杂度阈值可配置，`VITE_TRACK_ENABLED=false` 时全部静默
+- `src/tracker/analyze.js`：本地分析函数，提问方向/意图/复杂度/附件类型全部本地判断，不上报原文
+- `src/tracker/service.js`：Ackee 实例懒加载 + 上报队列，避免初始化期间丢事件
+- `src/tracker/useTracker.js`：官网页面埋点（`pageView` / `btnClick` / `loginSuccess`）
+- `src/tracker/useChatTracker.js`：对话框埋点，覆盖发消息、回复完成/报错/中止、模式切换、复制、下载，提问内容分析无用户关联
+- `src/tracker/index.js`：统一导出入口
+
+**埋点覆盖范围（21 个 Ackee Event）**
+- 页面行为 3 个：页面访问、按钮点击、登录成功
+- 对话行为 8 个：消息发送-模式/模型/用户、回复耗时、首字节延迟、中止、报错、模式切换
+- 采纳行为 5 个：内容复制-来源/用户/语言、文件下载-用户/语言
+- 提问内容分析 4 个：方向、意图、复杂度、附件（无用户关联）
+- 工具调用 1 个
+
+**采纳率三口径**：消息级、会话级、用户级，共用同一批事件，聚合 key 不同
+
+### 变更：useChatStore
+
+- 新增 `config.getUser` 注入接口，消费方传入获取当前用户信息的函数
+- `return` 新增 `tracker` 字段，供 `ArtifactPanel` / `MessageBubble` 调用采纳行为埋点
+- `abortStream()` 和 `switchMode()` 内置埋点调用
+
+### 文档
+- `docs/product.md` 新增「埋点与数据分析」章节
+- `docs/usage.md` 新增「埋点接入」章节，补充三个埋点环境变量
+- `docs/test-cases.md` 新增「十一、埋点」章节，16 个测试用例（T-100 ~ T-115）
+- `docs/doc-maintenance.md` 新增埋点维护规范
+
+---
+
+## [1.1.0] — 2025-03-20
+
+### 新增：埋点系统
+
+- `src/tracker/config.js`：埋点总配置，Ackee URL/Domain/开关从 `.env` 读取，21 个 Event UUID 集中管理，意图关键词字典、模式方向映射、复杂度阈值全部可配置
+- `src/tracker/analyze.js`：提问内容本地分析，输出方向/意图/复杂度/附件类型，不上报原文
+- `src/tracker/service.js`：Ackee 实例懒加载 + 上报队列，`TRACK_ENABLED=false` 时全部静默
+- `src/tracker/useTracker.js`：官网页面埋点 composable（`pageView` / `btnClick` / `loginSuccess`）
+- `src/tracker/useChatTracker.js`：对话框全量埋点 composable（发消息、回复完成/报错/中止、模式切换、复制、下载）
+- `src/tracker/index.js`：统一入口
+
+### 埋点
+
+共 21 个 Ackee Event，分五类：
+
+- 页面行为（3个）：页面访问、按钮点击、登录成功
+- 对话行为（8个）：消息发送模式/模型/用户分布、回复耗时、首字节延迟、中止、报错、模式切换
+- 采纳行为（5个）：复制来源/用户/语言分布、下载用户/语言分布
+- 提问内容分析（4个，无用户关联）：提问方向、意图、复杂度、附件类型
+- 工具调用（1个）：工具名分布
+
+### 变更
+
+- `useChatStore.js`：注入 `useChatTracker`，新增 `config.getUser` 注入口，`return` 暴露 `tracker` 供上层组件调用采纳埋点
+- `useChatStore.switchMode()`：注入模式切换埋点（⚠️ 函数内部逻辑有变，但对外接口不变）
+
+### 文档
+
+- `docs/doc-maintenance.md`：新增埋点维护步骤、Ackee 展示类型速查、自查清单补充埋点项
+
+---
+
+## [1.0.0] — 2025-03-20
+
+### 架构重构
+
+- 引入 `chat-sdk/` 目录，将对话能力从 guanwang 页面层剥离为独立 SDK
+- 新增双接入入口：`createAIChat()`（完整视图）和 `useChat()`（Headless 纯逻辑）
+- 分层结构：`headless/` → `core/` → `features/`，依赖方向单向
+- `features/` 每个目录内部区分 `core.js`（逻辑）和 `*.vue`（UI），headless 模式只引用逻辑层
+
+### 新增：多模型支持
+
+- `config.models` 支持配置多个独立 `baseURL/apiKey/model` 的模型
+- 输入栏底部新增模型 pill 选择器，仅在模型数 > 1 且 `userControls.modelSelector` 时显示
+- `autoVision`：含图片消息自动路由到 `vision: true` 的模型
+- 移除旧的 `VITE_VL_*` 视觉模型环境变量，统一到 `config.models`
+
+### 新增：多模式 Prompt 系统
+
+- `modes/code.js`：Code 模式，代码生成/修改，强制 `render_artifact` 输出
+- `modes/ask.js`：Ask 模式，只回答不生成文件
+- `modes/architect.js`：Architect 模式，系统设计，输出技术文档
+- `modes/requirements.js`：需求创造者模式，假设+确认流程，输出用户故事和功能拆解
+- `headless/buildSystemPrompt.js`：动态组装 system prompt，七区块结构，针对 Qwen3/弱模型优化
+- 模式切换时 system prompt 自动重建
+
+### 新增：Tool-use 解析循环
+
+- `tools/parser.js`：XML 工具调用解析，支持流式快速检测和批量提取
+- `tools/defaults.js`：五个工具内置默认处理逻辑（`ask_followup_question` / `attempt_completion` / `switch_mode` / `render_artifact` / `request_context`）
+- `useChatStore.onToolCall()`：支持按工具名或全局覆盖默认行为
+
+### 新增：设置面板
+
+- `settings/useSettings.js`：两层配置规则实现，`localStorage` 持久化
+- `settings/SettingsPanel.vue`：模型列表 + 功能开关 UI
+
+### 重构：chatApi.js
+
+- 移除全局 `selectConfig` 依赖，改为接收 `modelConfig` 对象
+- `headless/api/adapters/openai.js`：UI 消息格式 → OpenAI 兼容格式转换层，与业务逻辑解耦
+
+### 重构：useChatStore.js
+
+- 接收 `config` 参数，移除硬编码 `SYSTEM_PROMPT`
+- 集成 `loadModes()`、`buildSystemPrompt()`、`toAPIMessages()`
+- 集成 tool-use 循环：流式结束后自动解析并执行工具调用
+- 新增 `switchMode()`、`selectModel()`、`newSession()`、`switchSession()` 方法
+
+### 重构：ChatView.vue
+
+- 从 248 行页面组件精简为 46 行挂载壳，所有对话逻辑迁入 `ChatBox.vue`
+- `sdkConfig` 由环境变量组装，为后续迁移到 `createAIChat()` 调用预留接口
+
+### 重构：InputBar.vue
+
+- 移除全局 `config/api.js` 依赖
+- 改为接收 `availableModels`、`selectedModelId`、`showModelSelector` props
+- 通过 `emit('select-model')` 通知上层，不再内部维护模型状态
+
+### Bug 修复
+
+- `CodePreview.vue`：修复 Vue SFC 预览报错 `props.store.init is not a function`，`<Repl>` 组件内部会自调 `init()`，移除重复调用
+- `CodePreview.vue`：修复 `editor` prop 必填报错，补充 `CodeMirror` 异步加载并传入
+- `CodePreview.vue`：修复代码区滚动异常，改为 `flex` 列布局 + `shiki-scroll` 层独立滚动，`min-height: 0` 消除 flex 子元素默认约束
+- `ArtifactPanel.vue`：修复流式期间高亮竞态，引入 token 机制，后发的异步结果自动丢弃
+- `MessageBubble.vue`：原始文本调试面板（`VITE_SHOW_RAW_TEXT=true` 时显示）
+
+### 字体
+
+- 全局字体统一替换为 `Inter, 'Helvetica Neue', Helvetica, 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', '微软雅黑', Arial, sans-serif`
+- 涉及文件：`global.css` 及所有组件，数字/代码字体 monospace 保持不变
+
+---
+
+## [0.x] — 历史版本
+
+> 历史版本为 guanwang 项目初始开发阶段，未形成 SDK 结构，不单独记录。

package/guanwang/docs/doc-maintenance.md

@@ -0,0 +1,229 @@
+# 文档维护规范
+
+每次新增功能或修复 Bug 后，按以下步骤同步更新文档。
+
+---
+
+## 需要维护的文档
+
+| 文档 | 路径 | 维护频率 |
+|---|---|---|
+| 产品说明书 | `docs/product.md` | 新增/删除功能时 |
+| 组件使用文档 | `docs/usage.md` | 接口变更时 |
+| 测试用例 | `docs/test-cases.md` | 新增功能时 |
+| 埋点配置 | `src/tracker/config.js` | 新增埋点事件时 |
+
+> `docs/changelog.md` 每次都要更新，不在上表之列，但每步都涉及。
+
+---
+
+## 每次更新的步骤
+
+### 第一步：在 changelog.md 新增版本条目
+
+在文件顶部（最新版本之前）插入新条目：
+
+```markdown
+## [x.x.x] — YYYY-MM-DD
+
+### 新增
+- 简短描述，说明加了什么、为什么加
+
+### 修复
+- 简短描述，说明修了什么 Bug
+
+### 变更
+- 简短描述，说明改了什么接口或行为（破坏性变更需标注 ⚠️）
+
+### 埋点
+- 新增了哪些 Event，用途是什么
+
+### 文档
+- 同步更新了哪些文档
+```
+
+只写本次实际改动，没有的分类直接省略。
+
+---
+
+### 第二步：按改动类型更新对应文档
+
+#### 新增功能 → 更新 product.md
+
+找到对应功能模块的章节，补充新能力描述。若是全新模块，在合适位置新增一节。
+
+```markdown
+### [新功能名]
+- 一句话说明这个功能是什么
+- 关键限制或注意事项（如有）
+```
+
+#### 接口变更 → 更新 usage.md
+
+- 新增 config 字段：在「config 完整字段说明」表格补行
+- 新增 `useChat()` 返回值：在对应表格补行
+- 接口删除或重命名：更新对应行，备注「已废弃，改用 xxx」
+
+#### 新增功能 → 更新 test-cases.md
+
+在对应模块章节末尾追加测试用例，编号连续递增（当前最大编号 T-093）：
+
+```markdown
+### T-xxx 用例名称
+**步骤**：操作步骤描述
+**预期**：期望的结果
+```
+
+功能较多时可新增模块章节（`## 十一、xxx`）。
+
+#### 新增埋点 → 更新 tracker/config.js
+
+这是埋点维护的核心步骤，分三小步：
+
+**① 在 Ackee 后台创建 Event**
+
+进入 Ackee 管理后台 → Settings → Events → 新建 Event，填写：
+- Name：和 `config.js` 里的注释保持一致，方便后台辨识
+- Type：参考下方「展示类型速查」选择
+
+**② 把 UUID 填入 config.js**
+
+找到 `src/tracker/config.js` 的 `EVENTS` 对象，将 Ackee 生成的真实 UUID 替换对应的占位 UUID：
+
+```js
+export const EVENTS = {
+  // 把这里的占位 UUID 替换成 Ackee 后台生成的真实 UUID
+  NEW_EVENT: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+}
+```
+
+**③ 在对应的 tracker 函数里调用**
+
+- 页面行为 → `src/tracker/useTracker.js`
+- 对话行为 / 采纳行为 / 工具调用 → `src/tracker/useChatTracker.js`
+- 提问内容分析 → `src/tracker/analyze.js`（关键词字典）+ `useChatTracker.js`
+
+新增意图关键词时，只需修改 `config.js` 里的 `INTENT_KEYWORDS`，无需改其他文件。
+
+---
+
+### 第三步：自查清单
+
+提交前过一遍：
+
+- [ ] `changelog.md` 已新增版本条目，日期正确
+- [ ] 新增功能已在 `product.md` 对应章节有描述
+- [ ] 接口变更已在 `usage.md` 对应表格更新
+- [ ] 新功能有对应测试用例，编号连续
+- [ ] 新增埋点已在 Ackee 后台创建 Event，UUID 已更新到 `config.js`
+- [ ] 新增埋点已在对应 tracker 函数里调用，并在 `changelog.md` 的「埋点」分类里记录
+- [ ] 已知限制有变化的，`product.md` 底部「已知限制」已更新
+- [ ] **涉及文件迁移或路径变更的，已执行引用扫描（见下方）**
+
+---
+
+### 架构变更专项：引用扫描
+
+**每次发生以下情况，必须执行引用扫描，不得跳过：**
+
+- 文件移动或重命名
+- 文件删除或被新文件取代
+- 模块路径变更（如从 `composables/` 迁移到 `chat-sdk/headless/`）
+- 接口名称变更
+
+**扫描指令（在项目根目录执行）：**
+
+```bash
+# 扫描某个旧路径是否还有文件在引用
+grep -rn "旧文件名或旧路径" src/ --include="*.vue" --include="*.js"
+
+# 示例：确认旧的 useChatStore 没有残留引用
+grep -rn "composables/useChatStore" src/ --include="*.vue" --include="*.js"
+
+# 示例：确认旧的 config/api.js 没有残留引用  
+grep -rn "config/api" src/ --include="*.vue" --include="*.js"
+```
+
+**结果为空才算完成**，有输出说明还有文件没更新，必须逐一处理后再提交。
+
+**扫描时机：每改完一个文件，立即扫一次对应的旧路径**，不要等所有文件改完再统一扫，否则容易遗漏。
+
+---
+
+## 版本号规则
+
+遵循语义化版本 `major.minor.patch`：
+
+| 变更类型 | 升级哪位 | 示例 |
+|---|---|---|
+| 破坏性接口变更 | major | 1.0.0 → 2.0.0 |
+| 新增功能（向后兼容） | minor | 1.0.0 → 1.1.0 |
+| Bug 修复 / 文档 / 样式 / 埋点 | patch | 1.0.0 → 1.0.1 |
+
+---
+
+## 展示类型速查（Ackee Event Type）
+
+| 类型 | 适用场景 | 示例 |
+|---|---|---|
+| List 总计 | 统计各 key 的出现次数 | 模式分布、用户用量、复制来源 |
+| List 平均值 | 统计各 key 的平均数值 | 不常用 |
+| Chart 总计 | 按时间看总量趋势 | 不常用 |
+| Chart 平均值 | 按时间看均值趋势 | 回复耗时、首字节延迟 |
+
+---
+
+## 快速参考：各文档的章节结构
+
+### product.md 章节
+```
+## 核心能力
+  ### [功能模块]    ← 新增/修改功能在这里
+## 技术架构
+## 配置两层边界
+## 已知限制         ← Bug 修复后可能需要更新
+```
+
+### usage.md 章节
+```
+## 两种接入方式
+## config 完整字段说明   ← 新字段加这里
+  ### ModelConfig
+  ### FeaturesConfig
+  ### UserControlsConfig
+## useChat() 返回值      ← 新返回值加这里
+  ### 状态
+  ### 方法
+## 模式说明
+## 环境变量             ← 新环境变量加这里
+```
+
+### test-cases.md 章节
+```
+## 一、配置与初始化   (T-001 ~ T-005)
+## 二、对话核心       (T-010 ~ T-017)
+## 三、多模型         (T-020 ~ T-022)
+## 四、多模式         (T-030 ~ T-034)
+## 五、Tool-use       (T-040 ~ T-045)
+## 六、Artifact 面板  (T-050 ~ T-056)
+## 七、Markdown 渲染  (T-060 ~ T-064)
+## 八、文件上传       (T-070 ~ T-074)
+## 九、Headless 模式  (T-080 ~ T-084)
+## 十、CodePreview    (T-090 ~ T-093)
+## 十一、埋点         (T-100 ~)       ← 新增埋点测试用例加这里
+```
+
+### tracker/config.js 结构
+```
+ACKEE_URL / ACKEE_DOMAIN / TRACK_ENABLED  ← 读取环境变量，不要硬编码
+EVENTS = {
+  // 页面行为（3个）
+  // 对话行为（8个）
+  // 采纳行为（5个）
+  // 提问内容分析（4个）
+  // 工具调用（1个）
+}
+INTENT_KEYWORDS   ← 意图关键词字典，新增意图类型在这里加
+MODE_TO_DIRECTION ← 模式→方向映射
+COMPLEXITY_THRESHOLD
+```

package/guanwang/docs/product.md

@@ -0,0 +1,181 @@
+# chat-sdk 产品说明书
+
+版本：1.0.0 · 面向 Vue3 项目的可嵌入 AI 对话组件库
+
+---
+
+## 核心能力
+
+### 对话
+
+- 流式输出，token 逐字渲染，rAF 节流避免掉帧
+- 多会话管理，侧边栏切换，标题自动截取
+- 中止请求（停止按钮）
+- 首条消息自动触发 AI 自我介绍
+
+### 多模型
+
+- 每个模型独立 `baseURL` / `apiKey` / `model id`，适配内网多服务部署
+- 支持运行时切换，输入栏底部 pill 选择器
+- `autoVision`：消息含图片时自动路由到 `vision: true` 的模型
+- 用户选择持久化至 `localStorage`
+
+### 多模式（Prompt 系统）
+
+| 模式 | 核心职责 | 不做什么 |
+|---|---|---|
+| Code | 生成/修改代码，输出 Artifact 文件 | 不做需求分析，不做系统设计 |
+| Ask | 解释概念、回答技术问题 | 不生成完整代码文件 |
+| Architect | 系统设计、技术方案、架构拆解 | 不写实现代码 |
+| 需求 | 梳理需求，输出用户故事和功能拆解 | 不主动切换到 Code/Architect |
+
+Prompt 特性：
+- 针对 Qwen3 / 弱模型优化：大量工具示例，强约束语气（MUST/NEVER/ALWAYS）
+- 重要规则前置（弱模型容易忽略 prompt 后半段）
+- 中文 prompt，与 Qwen3 中文语料对齐
+- 模式切换时 system prompt 自动重建
+
+### Tool-use 循环
+
+AI 输出中包含工具调用时自动触发，流式结束后解析执行。
+
+| 工具 | 默认行为 | 可覆盖 |
+|---|---|---|
+| `ask_followup_question` | 渲染选项气泡，等用户点选 | ✓ |
+| `attempt_completion` | 标记任务完成 | ✓ |
+| `switch_mode` | 切换模式，追加系统提示 | ✓ |
+| `render_artifact` | 注册到 ArtifactPanel 展示 | ✓ |
+| `request_context` | 追加引导提示，请求用户粘贴代码 | ✓ |
+
+### Artifact 文件面板
+
+- AI 生成完整代码时自动弹出右侧面板
+- 顶部 Tab 栏，支持多文件切换
+- 代码视图：Shiki 语法高亮、行号、行列号状态栏
+- 预览视图：HTML/JS/CSS iframe 运行预览，Vue SFC 通过 `@vue/repl` 实时编译预览
+- 支持复制代码、下载文件
+
+### Markdown 渲染
+
+- `marked` 解析，`DOMPurify` 净化
+- `Shiki` 代码高亮（双主题：`one-dark-pro` / `github-light`）
+- `KaTeX` 数学公式
+- `Mermaid` 流程图
+- 流式渲染：双区差分（已完成区 + 流入区），避免整体重绘闪烁
+
+### 文件上传
+
+支持类型：图片（JPG/PNG/GIF/WebP）、PDF、代码文件（.vue/.ts/.js/.py 等）、Word（.docx）、Excel（.xlsx）
+
+- 图片：base64 编码，附入 API 消息，气泡内显示缩略图
+- PDF / Word / Excel：提取文本内容附入消息，显示文件名图标
+- 粘贴截图（Ctrl+V）
+- 拖拽上传
+- 最多同时 5 个附件
+
+### CodePreview 弹框
+
+- 点击代码块右上角按钮打开
+- 分屏 / 代码 / 预览 三种 Tab
+- Vue SFC：`@vue/repl` 实时编译，CodeMirror 编辑器
+- HTML/JS/JSX：iframe 沙箱运行
+- SVG：inline 渲染
+- 代码区行号，底部状态栏显示总行数和点击位置行列号
+
+---
+
+## 技术架构
+
+### 分层设计
+
+```
+headless/     纯逻辑层，零 UI 依赖，可独立使用
+core/         UI 组件层，依赖 headless
+features/     按需加载，feature 内部分 core.js（逻辑）和 *.vue（UI）
+modes/        Prompt 配置，纯 JS，按需导入
+tools/        Tool-use 解析器和默认处理器
+settings/     运行时开关持久化
+```
+
+### 两种接入方式
+
+**完整视图**：`createAIChat(config)` 挂载整套界面
+
+**Headless**：`useChat(config)` 返回状态和方法，消费方自己写视图
+
+### 按需加载机制
+
+两层配置控制加载行为：
+
+- `features.xxx = false`：对应 chunk 不下载，代码体积最小化
+- `userControls.xxx`：控制运行时 UI 开关是否对用户可见
+
+### 数据流
+
+```
+消费方 send({ text, attachments })
+  → headless/useChatStore
+  → api/adapters/openai.js  UI消息 → API格式
+  → headless/api/chatApi.js 流式请求
+  → token 回来 → RAF 节流渲染
+  → 流结束 → tools/parser.js 解析工具调用
+  → tools/defaults.js 执行默认行为 / 消费方覆盖
+  → messages 状态更新 → 视图重渲染
+```
+
+### API 格式适配层
+
+`headless/api/adapters/openai.js` 负责 UI 消息格式 → OpenAI 兼容格式转换，更换模型服务时只需新增 adapter，不影响上层。
+
+---
+
+## 配置两层边界
+
+| 层级 | 配置位置 | 控制内容 | 谁决定 |
+|---|---|---|---|
+| 初始化层 | `features` | chunk 是否下载 | 开发者 |
+| 运行时层 | `userControls` | UI 开关是否可见和默认状态 | 用户 |
+
+`features: false` 时，即使 `userControls` 声明了对应开关，开关也不会显示（代码未加载）。
+
+---
+
+## 埋点与数据分析
+
+基于 Ackee 的隐私友好型埋点，共 21 个 Event，分四个模块。
+
+### 页面行为
+页面访问、按钮点击、登录成功。通过路由 `afterEach` 自动上报页面访问，按钮需手动调用 `btnClick(btnId)`。
+
+### 对话行为
+消息发送（模式/模型/用户三维度）、回复耗时与首字节延迟（Chart 平均值）、中止、报错、模式切换。内置在 `useChatStore` 中，无需额外接入。
+
+### 采纳行为（三口径采纳率）
+内容复制（来源/用户/语言）、文件下载（用户/语言）。支持三个统计口径：
+- 消息级：有采纳行为的消息数 / AI 消息总数
+- 会话级：有采纳的会话数 / 总会话数
+- 用户级：有采纳的用户数 / 活跃用户数
+
+### 提问内容分析（无用户关联）
+- **方向**：从当前模式直接读取（code/ask/architect → `code`，requirements → `requirement`）
+- **意图**：关键词字典本地匹配（code_gen / debug / explain / refactor / review / other），仅代码方向触发
+- **复杂度**：按字符数划分（short < 50 / medium < 200 / long ≥ 200）
+- **附件类型**：image / code_file / pdf / mixed / none
+
+全部本地分析，不上报提问原文，不关联用户身份。
+
+### 配置
+```env
+VITE_ACKEE_URL=http://your-ackee-server:3000
+VITE_ACKEE_DOMAIN=your-domain-uuid
+VITE_TRACK_ENABLED=true   # false 时全部静默
+```
+Event UUID 在 `src/tracker/config.js` 的 `EVENTS` 对象中集中管理，替换为 Ackee 后台生成的真实 UUID 即可。
+
+## 已知限制
+
+- 仅支持 Vue3 项目
+- 不支持 SSR（依赖 `localStorage` 和浏览器 API）
+- 对话历史仅存在内存，刷新页面丢失（持久化能力预留 `useChatDB.js`，未完整实现）
+- `@vue/repl` Vue SFC 预览依赖网络加载 Vue 运行时（离线环境不可用）
+- 单次请求无超时控制，长请求依赖用户手动中止