refactor: 基于 Nuxt 4 约定优于配置原则重构前端架构并优化 UI 体验

CI/linter/license/.licenserc.yaml

@@ -84,4 +84,5 @@ header:
     - 'CI/linter/codespell/.codespell.skip'
     - 'mvnw'
     - 'mvnw.cmd'
+    - '**/*.mdc'
   comment: never

data-agent-frontend-nuxt/.cursor/rules/frontend-standards-nuxt4-spa.mdc

@@ -0,0 +1,92 @@
+---
+alwaysApply: true
+---
+# DataAgent（Nuxt 4 SPA + TypeScript + Vuetify 3）开发法则
+
+## 0. 关键上下文（最高优先级）
+- 框架：Nuxt 4（Nitro），项目以 **纯 SPA 模式** 运行（`ssr: false`）。
+- 包管理器：只能使用 `pnpm`。
+- 语言：TypeScript（建议严格模式思维），**禁止**引入或使用 `.js` 新文件。
+- UI：Vuetify 3（MDI 图标使用 `mdi-*` 字符串形式，优先 `<v-icon icon="mdi-xxx" />`）。
+- 请求：服务层统一放在 `app/services/`，并以该仓库现有习惯为准（本项目当前广泛使用 `axios`；如有冲突以现有服务实现风格为准）。
+- HTML 安全：任何 `v-html` 展示都需先经过 `DOMPurify`（或明确来自已处理的安全渲染函数）。
+
+## 1. 知识检索协议（在“写代码/改代码”之前必须做）
+1. **框架层优先级**：涉及 Nuxt 核心（route、plugin、composable、Nitro 等）优先参考 Nuxt 官方文档与仓库内现有实现模式。
+2. **本地上下文**：修改或新增组件/模块前，先检查目标目录下是否存在自动生成的 `README.md`（技能卡/上下文卡片）。
+3. **查重机制（Exist before Create）**：如果仓库已有类似实现（组件、工具函数、composable、utils），优先复用与小幅改造，而不是复制新代码。
+4. **类型优先**：优先引用现有 `types/` 或同级 `.ts` 定义；避免凭空猜测数据结构。
+
+## 2. 编码规范（Coding Standards）
+### 2.1 TypeScript 约束
+- 所有变量/参数/返回值尽量显式类型（至少保证关键边界类型安全）。
+- 禁止使用 `any`；需要时使用合理联合类型/泛型/类型守卫（type guards）。
+- 避免“看起来已经判断过”的可空值类型仍被 TS 推断为 `T | undefined`：用局部变量收窄（例如 `const x = arr[0]; if (!x) return; ...`）或非空断言（仅在确认绝对安全时使用）。
+
+### 2.2 Vue / Nuxt 写法
+- 使用 `<script setup lang="ts">`（保持组合式 API 风格）。
+- 组件内部函数命名统一采用 `onXxx` / `handleXxx` / `getXxx` / `renderXxx` 等语义风格（与当前代码风格一致）。
+- 需要在模板中判断复杂逻辑时，优先提取成 `computed` / `function`，不要在模板里写超长表达式。
+- 涉及页面显隐、大块内容切换时，添加适当过渡（例如 `<v-fade-transition>` / `<v-expand-transition>` 或 `<transition>`）。
+- Nuxt 自动导入规则：Nuxt 及本项目配置会自动导入 Nuxt 组件、Vue 的常用响应式 API（如 `ref` / `computed` / `watch`）以及常用 composable；**无需手动 import 这些值**。仅当你要导入 **TypeScript 类型**（`type`）时，才需要 `import type`。
+
+### 2.3 模板规范（Vue 模板）
+- 属性顺序：`class` -> 其他属性 -> `v-if` -> 事件绑定（如 `@click`）。
+- 插槽：统一使用 `#slotName` 简写（禁止 `v-slot:`）。
+
+### 2.4 样式规范
+- `style` 默认使用 `scoped`。
+- 深层样式使用 `:deep(...)`，并控制在必要范围内，避免全局污染。
+
+## 3. 复用与重构策略（Reuse & Refactor）
+- DRY 原则：禁止无意义重复工具函数/极其相似的 UI 组件。
+- 多态扩展：优先通过可选参数、回调策略、泛型来扩展既有逻辑。
+- 兼容性：重构必须保证向后兼容；如果需要改变函数签名，改为可选参数而非修改必填参数。
+- 性能：在流式（SSE/逐字/逐块）场景，优先使用 `requestAnimationFrame` / 防抖节流 / 合并渲染更新，避免每个 SSE 消息都触发重渲染风暴。
+
+## 4. 组件 / 模块目录结构规范（必须遵守）
+> 目标：让“查找”和“复用”成本最低，同时保证服务层/组件层边界清晰。
+
+### 4.1 建议的目录结构（通用标准）
+```
+app/
+  components/
+    common/
+      <CommonComponent>/
+        index.vue
+        types.ts              (可选)
+        styles.scss           (可选)
+        README.md             (自动生成/不手改)
+    <feature>/
+      <ComponentName>.vue
+      <ComponentName>/
+        index.vue             (当组件较复杂时建议用文件夹承载)
+        types.ts              (可选)
+        utils.ts              (可选)
+  composables/
+    <feature>/
+      useXxx.ts
+  services/
+    <domain>/
+      index.ts
+      (其它模块按需拆分，但服务入口尽量保留 index.ts)
+  utils/
+    <domain>/
+      xxx.ts
+```
+
+### 4.2 组件组织规则（必须满足）
+- 如果组件复杂度较低：直接在 `app/components/<feature>/` 下放置单文件 `ComponentName.vue`。
+- 如果组件复杂度较高（包含多个逻辑分支/多块状态/对接多个子渲染器）：优先使用文件夹承载（`ComponentName/`），在其中提供 `index.vue`，并按需拆 `types.ts` / `utils.ts`。
+- 公共组件优先放在 `app/components/common/`。
+- 不要为每次需求重复造“只差一点点”的新组件；先复用或抽取差异点。
+
+### 4.3 模块边界规则（必须满足）
+- UI：只做渲染与交互，业务请求与数据获取放到 `app/services/`。
+- 服务层：只负责调用与数据转换，不直接耦合 UI。
+- utils/composables：用于纯逻辑/可复用状态与渲染辅助（例如 Markdown/ECharts 渲染器、SSE 解析等）。
+
+## 5. 协作协议（提交质量）
+- 禁止手动修改仓库中由自动脚本生成的 `README.md`（如不确定是否可改，先询问或保持不改）。
+- 提交前必须确认：TypeScript 无错误；同时页面不会引入明显运行时异常（尤其是 SSE 流式、v-html 渲染、iframe src/Blob URL 等路径）。
+

data-agent-frontend-nuxt/.cursor/skills/code-review-refactor/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: code-review-refactor
+description: 对现有 Nuxt 4 + Vue3 + Vuetify3 代码进行 Code Review，并给出“可落地”的重构/复用方案（逻辑抽取、CSS 去重、页面 JSON 驱动复用）。
+---
+
+# Code Review & Refactor 规范 Skill
+
+当用户提出“代码很乱 / 需要 Code Review / 重构不够规范 / 提取可复用逻辑 / CSS 太多 / 页面重复应该 JSON 驱动”等诉求时，使用本 Skill。
+
+## 0. 使用范围（When to Use）
+- 用户明确说要 Code Review
+- 或用户反馈：组件/页面冗长、CSS 重复、相似页面太多、缺少抽取到 `utils/composables/services`、缺少可复用结构
+- 或发现你在修改时重复造轮子（应优先提取/复用）
+
+## 1. 重构总原则（必须遵守）
+1. **行为优先（Behavior First）**：重构仅做结构优化，不改变既有功能、接口与用户交互语义。
+2. **小步可验证**：每次改动都应能局部验证；先提取再替换，避免“一次大改导致难排查”。
+3. **优先抽取可复用逻辑**：
+   - 纯函数与可复用算法：`app/utils/`
+   - 与组件生命周期/状态联动的逻辑：`app/composables/`
+   - API 请求/数据转换：`app/services/`
+4. **优先组件化重复 UI**：
+   - 动作按钮组、筛选条、分页条、表格工具栏等重复结构 -> 公共组件
+   - 相似页面 -> 用“配置/JSON + 事件绑定”做驱动，而不是拷贝复制页面
+5. **CSS 去重**：
+   - 多处重复的 CSS -> 提取为组件内共用 class，或提取公共样式（同风格、同作用域规则）
+   - 只为“一个小变量”复制 CSS 的 -> 合并成同一个 class + 参数化/状态类
+
+## 2. Code Review 检查清单（Checklists）
+
+### 2.1 逻辑抽取（Logic Extraction）
+在 review 时，逐段检查是否存在以下情况：
+1. 一个组件里出现多次相同的处理逻辑（如 parse/safeParse/格式化/渲染拼装）。
+2. 多个页面存在相同的业务流程（如同一类 SSE 流式组装、同一类 markdown/eCharts 渲染触发）。
+3. 与页面无关的纯逻辑没有被移到 `utils` 或 `composables`。
+
+输出要求：
+- 指出“重复点”与“提取位置建议”（utils/composables/services 哪个更合适）
+- 给出新的接口/函数签名建议（至少用参数名与返回类型描述）
+
+### 2.2 组件拆分（Componentization）
+- 组件文件是否超过合理规模（建议阈值：500 行内易维护，复杂组件建议拆子组件）
+- 是否存在“混杂多职责”（例如：渲染 + 请求 + 状态 + 事件处理全部写在一个组件）
+
+输出要求：
+- 提出“拆分方案”：哪些子组件/哪些 composables
+- 标明拆分后组件仍保持同样的 Props/事件语义
+
+### 2.3 CSS 去重（CSS De-duplication）
+检查：
+1. 不同组件/页面有大量相同 CSS（尤其是 `markdown-body`、code block、card spacing、按钮样式等）。
+2. 相同选择器重复定义或只差少量颜色/间距。
+
+输出要求：
+- 优先给出“提取成一个 class”方案
+- 或建议做“公共样式组件/公共 wrapper 组件”（如果是 UI 结构层面的重复）
+
+### 2.4 JSON 驱动的页面复用（Config-Driven Pages）
+当你发现多个管理页面“按钮数量不同、内容通过 JSON 稍有差异”，建议使用 JSON 驱动：
+- 页面结构拆为通用骨架：
+  - 顶部标题区
+  - 操作按钮组（来自配置）
+  - 表格/列表区（列定义来自配置）
+  - 弹窗/抽屉（表单字段来自配置）
+- 事件由页面注入（例如：`onAction(actionKey, payload)` 或通过映射表）
+
+输出要求：
+- 提出一个“最小通用配置 schema”（字段列表 + 示例）
+- 指出每个页面需要补充的差异化配置项
+
+### 2.5 TypeScript 与安全护栏
+检查是否存在：
+- `arr[i]` 取值后未做 TS 收窄导致 `T | undefined` 警告
+- SSE/流式数据拼接在 TS 层面不安全
+
+输出要求：
+- 给出 TS 收窄的推荐写法（局部变量 + if 守卫 / type guard）
+
+## 3. 推荐的输出格式（必须用）
+当用户说开始 Code Review 时，你的回答应使用以下结构（按序）：
+
+1. `## 最关键问题（按严重度从高到低）`
+   - 每条用一句话概括 + 标明影响范围（渲染/性能/可维护性/正确性）
+2. `## 重构/复用建议（可落地）`
+   - 对每条建议写：提取目标（utils/composables/services/组件/CSS）、原因、预计收益
+3. `## JSON 驱动复用方案（如果存在重复页面）`
+   - 给出配置 schema（字段列表）+ 示例（可以是伪 JSON）
+4. `## 验证与回归（Test Plan）`
+   - 给出最少的手动验证清单（UI 是否一致、功能是否不变、关键交互是否回归）
+
+## 4. 允许与禁止
+允许：
+- 提取公共逻辑、拆子组件、创建新 util/composable/services
+- CSS 合并、抽取公共 class、增加必要 wrapper 组件
+禁止：
+- 仅为“看起来更漂亮”而改变现有交互语义或数据结构
+- 大而全的重写（除非用户明确要求并且能接受高风险）
+

data-agent-frontend-nuxt/.cursor/skills/git-commit-message-generator/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: git-commit-message-generator
+description: 生成符合约定式提交（Conventional Commits）的 Git 提交信息（如 `feat:xxx`）。
+---
+
+# Git 提交信息生成器（Conventional Commits）
+
+当用户提出诸如“帮我写一下 git 的提交信息 / commit message / 提交信息怎么写”时，使用本 Skill 生成完整提交信息。
+
+## 1. 提交信息类型约定
+提交信息类型必须从以下集合中选择其一（无则让用户确认，或根据上下文推断）：
+- `feat`: 新功能
+- `fix`: 修复 bug
+- `docs`: 文档更新
+- `style`: 代码格式调整（不改行为）
+- `refactor`: 重构（不改变对外行为）
+- `test`: 测试相关
+- `chore`: 构建工具或辅助工具变动
+
+## 2. 生成规则
+1. 若用户未明确给出类型：根据用户描述推断（新功能/修复/重构/文档/测试/构建工具）。
+2. 生成的主题（subject）要求：
+   - 使用中文（与项目一致）
+   - 简洁、动作明确、避免“做了/修改了/更新了”这类空话
+   - 主题长度建议 12~30 个中文字符
+3. 默认只输出一行（不添加 body），格式为：
+   - `type:主题`
+
+## 3. 可选追问（仅在关键信息缺失时）
+如果无法推断类型或主题过于模糊，最多追问 1 次：
+- “你希望类型是 `feat` 还是 `fix`？主题你想写成什么（一句话即可）？”
+
+## 4. 输出示例
+- `feat:完成了对话页面`
+- `fix:修复SSE滚动不自动到底部`
+- `refactor:重构时间线渲染以支持流式报告`
+- `docs:更新ECharts渲染说明文档`
+- `chore:调整lint/format脚本配置`
+

data-agent-frontend-nuxt/.cursor/skills/ui-feedback-utils/tip/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: ui-tip-usage
+description: 规范全局 $tip Toast 的调用方式（成功默认、错误需手动指定 icon）。
+---
+
+# $tip Toast 统一调用 Skill
+
+本 Skill 用于当用户提出“提示/Toast 怎么写”、“$tip 怎么用”、“复制成功要不要提示”等需求时。  
+同时：在你编写代码时，只要你想到需要向用户展示一个提示（成功/失败/警告/信息），也要优先按本 Skill 的规范调用 `$tip`。
+
+## 统一调用规则
+1. 使用前必须先写：
+   - `const { $tip } = useNuxtApp();`
+2. 调用签名：
+   - `$tip(message, { color: string, icon: string, timeout: number })`
+3. 成功默认规则：
+   - 只要写：`$tip(message)`
+   - 默认 `color: 'success'`
+   - 默认 `icon: 'mdi-check'`（对勾）
+   - 默认 `timeout: 3000`
+4. `timeout: -1` 代表永久不自动关闭：
+   - 需要用户自己手动关闭（Snackbar 右上角关闭按钮）
+   - 示例：`$tip('长期提示', { timeout: -1 })`
+5. 错误规则（必须手动）：
+   - 当你要表达错误时，必须手动传：
+   - `$tip(message, { color: 'error', icon: 'mdi-error' })`
+
+## 示例
+- 成功提示：
+  - `const { $tip } = useNuxtApp();`
+  - `$tip('操作成功');`
+
+- 错误提示（必须指定 icon）：
+  - `const { $tip } = useNuxtApp();`
+  - `$tip('保存失败', { color: 'error', icon: 'mdi-error' });`
+
+- 自定义颜色/超时（非 error 时可不传 icon）：
+  - `$tip('正在生成报告...', { color: 'info', timeout: 5000 });`
+

data-agent-frontend-nuxt/.cursor/skills/ui-feedback-utils/use-confirm/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: ui-useconfirm-usage
+description: 规范全局确认弹窗 useConfirm 的调用方式。
+---
+
+# useConfirm 确认弹窗 Skill
+
+本 Skill 用于当用户提出“删除确认/是否继续/确认弹窗怎么写”等需求时。
+
+## 使用方式（必做）
+1. 使用前必须写：
+   - `const { showConfirm } = useConfirm();`
+2. 参数使用 `showConfirm(options)`，并通过 `onConfirm` 提供确认后回调。
+3. 取消/关闭弹窗时：不会触发 `onConfirm`。
+
+## showConfirm(options) 参数规范
+`showConfirm({
+  title: string,
+  message: string,
+  icon?: string,         // 默认 'mdi-help-circle'
+  confirmText?: string,  // 默认 '确认'
+  onConfirm: () => void | Promise<void>
+})`
+
+## 示例：删除会话
+```typescript
+const { showConfirm } = useConfirm();
+const { $tip } = useNuxtApp();
+
+showConfirm({
+  title: '删除会话',
+  message: '确定要删除这个会话吗？此操作不可恢复。',
+  icon: 'mdi-delete',
+  confirmText: '确定删除',
+  onConfirm: async () => {
+    await store.removeSession(sessionToDelete);
+    $tip('删除成功');
+  }
+});
+```
+