86 lines
7.3 KiB
Markdown
86 lines
7.3 KiB
Markdown
# 前端专业化重构作业计划（持续进行中）
|
||
|
||
> 目标：在保持 `static/old_version_backup/前端备份` 视觉与交互 100% 还原的前提下，完成基于 Vite + Vue 3 + Pinia 的组件化重写。本文为后续接手者提供当前进度与下一步任务拆解。
|
||
|
||
## 当前进展（2025‑11）
|
||
|
||
1. **模板与逻辑彻底迁移**：原 `index.html + app.js` DOM/方法已全部拆到 `static/src/App.vue` 及 Pinia store/composables，`static/src/app.ts` 仅保留少数兼容辅助。根 HTML 只负责挂载点、复制脚本与安全脚本。
|
||
2. **全量 Pinia + 组合式 API**：连接、会话、聊天、文件/聚焦、资源、工具、个性化、子智能体、UI 等状态均落在 `static/src/stores/**`，`useLegacySocket`、`useMarkdownRenderer`、`useUploadStore`、`useEasterEgg` 等组合式函数负责跨模块逻辑。
|
||
3. **全局壳层完成组件化**：`AppShell.vue` 托管 ToastStack、ConfirmDialog、QuotaToast、EasterEggOverlay、ContextMenu；聊天区、输入区、Quick Menu、TokenDrawer、RightFocusPanel、PersonalizationDrawer、ActionBlock 系列全为独立组件。
|
||
4. **样式模块化完结**：`static/src/styles/` 以 base/layout/components/utilities 分层，`npm run build` 输出 `static/dist/assets/main.css`，`static/style.css` 退化为对该文件的 `@import`，旧版真值迁至 `static/old_version_backup/前端备份`。
|
||
5. **构建/依赖稳定**：Vite 5 + Vue 3 + Pinia + Sass 作为唯一真值，`npm run build`、`npm run dev` 可直接产出最新 UI；KaTeX/Prism/Socket.IO 通过 npm/ESM 管理。
|
||
|
||
## 架构索引（按模块划分）
|
||
|
||
### 1. Store 分层（Pinia，已落地）
|
||
|
||
| Store | 数据来源（原 data 字段） | 关键方法/事件 |
|
||
| --- | --- | --- |
|
||
| `useConnectionStore` | `isConnected`, `socket`, `stopRequested` | `initSocket`, `disconnect`, Stop 按钮/事件处理 |
|
||
| `useSystemStore` | `projectPath`, `agentVersion`, `thinkingMode` | `fetchStatus`, `toggleThinkingMode` |
|
||
| `useConversationStore` | `conversations*`, `currentConversationId`, `currentConversationTitle`, `searchQuery`, `hasMoreConversations` | 对话 CRUD、搜索、加载更多、路由同步 |
|
||
| `useChatStore` | `messages`, `streamingMessage`, `expandedBlocks`, `thinkingScrollLocks`, `autoScrollEnabled`, `userScrolling` | 消息渲染、滚动锁、append/modify/system 块渲染、socket 事件映射 |
|
||
| `useFileStore` | `fileTree`, `expandedFolders`, `focusedFiles`, `contextMenu` | 文件树加载、右键菜单、聚焦/下载等 |
|
||
| `useResourceStore` | `tokenPanelCollapsed`, `currentContextTokens`, `currentConversationTokens`, `usageQuota`, `projectStorage`, `containerStatus`, `polling timer` | Token/Quota/Storage/容器轮询与渲染 |
|
||
| `useToolStore` | `preparingTools`, `activeTools`, `toolActionIndex`, `toolStacks`, `toolSettings*`, `toolMenuOpen` | Quick Menu、工具禁用面板、流式工具卡片 |
|
||
| `useUiStore` | `sidebarCollapsed`, `leftWidth`, `rightWidth`, `rightCollapsed`, `isResizing`, `panelMode`, `panelMenuOpen`, `settingsOpen`, `quickMenuOpen`, `toastQueue`, `confirmDialog`, `easterEgg` | 面板布局、Toast/Confirm、彩蛋生命周期 |
|
||
| `usePersonalizationStore` | `personalPageVisible`, `personalization*`, `tonePresets`, `newConsideration`, `draggedConsiderationIndex` | 个人空间表单/拖拽/保存 |
|
||
| `useSubAgentStore` | `subAgents`, `subAgentPollTimer` | 子智能体轮询 |
|
||
|
||
> 源码位于 `static/src/stores/`，组合式函数位于 `static/src/composables/`，如 `useLegacySocket.ts`、`useMarkdownRenderer.ts`、`useUploadStore.ts`。
|
||
|
||
### 2. 组件切分（全部完成，可按需继续细分）
|
||
|
||
1. **全局壳层**：`AppShell.vue` 负责 ToastStack、ConfirmDialog、EasterEggOverlay、ContextMenu，内部 slot 负责主布局。
|
||
2. **侧边栏**：`ConversationSidebar.vue`（对话列表 + 搜索 + 按钮）、`ConversationList.vue`、`ConversationItem.vue`。
|
||
3. **三合一面板**：`LeftPanel.vue`（Logo 卡、模式切换）、`PanelSwitcher.vue`、`FileTreePanel.vue`（内含 `FileNode`）、`TodoPanel.vue`、`SubAgentPanel.vue`。
|
||
4. **聊天区域**：`ChatArea.vue`、`MessageList.vue`、`MessageItem.vue`、`ActionBlock` 系列（thinking/text/tool/append/modify/system）。
|
||
5. **输入区**：`InputComposer.vue`、`QuickMenu.vue`、`ToolToggleMenu.vue`、`SettingsMenu.vue`、`UploadButton.vue`。
|
||
6. **右侧聚焦**：`RightFocusPanel.vue`、`FocusedFileCard.vue`、`ScrollLockButton.vue`。
|
||
7. **资源/统计**：`TokenDrawer.vue`、`ResourceStats.vue`、`UsageDashboard.vue`。
|
||
8. **个人空间**：`PersonalizationDrawer.vue`、`TonePresetList.vue` 等。
|
||
|
||
所有组件均在 `static/src/components/` 下维护。若新增模块，沿用同一拆分策略：先从壳层/侧栏等低耦合区域着手，再处理聊天与输入区，最终迁移全局遮罩和抽屉。
|
||
|
||
### 3. 逻辑剥离 & Composable（已落地）
|
||
|
||
- **Socket 管理**：`useLegacySocket()` 负责事件绑定/解绑并分发至 Pinia。
|
||
- **滚动/尺寸**：`useAutoScroll()`、`useResizeHandles()` 等组合式函数维护滚动锁、面板拖拽。
|
||
- **彩蛋系统**：`useEasterEgg()` 封装 `handleEasterEggPayload`、`startEasterEggEffect`。
|
||
- **工具/Markdown**：`useToolActions()`、`useMarkdownRenderer()` 解析工具栈、思考文本、代码块复制。
|
||
|
||
### 4. 样式模块化（已落地）
|
||
|
||
- `static/src/styles/` 以 `base/`、`layout/`、`components/`、`utilities/` 四层维护 SCSS，`main.ts` 统一导入 `./styles/index.scss`。
|
||
- `npm run build` 输出 `static/dist/assets/main.css`；`static/style.css` 仅 `@import` 该文件以兼容旧 URL。
|
||
- 旧版 CSS 仍保存在 `static/old_version_backup/前端备份/style.css` 供视觉对照。
|
||
|
||
### 5. 验证清单
|
||
|
||
1. `npm run build`
|
||
2. 手动测试：
|
||
- 对话切换、搜索、加载更多
|
||
- Token/Quota 更新、Stop 按钮、思考块折叠
|
||
- Quick Menu：上传文件、工具禁用、模式切换、设置子菜单动作
|
||
- 聚焦面板联动、锁定滚动按钮
|
||
- 个人空间开启/保存/拖动
|
||
- 子智能体轮询与卡片展示
|
||
- 彩蛋触发与结束
|
||
- Append/Modify/System 块渲染 & 复制代码按钮
|
||
|
||
## 注意事项
|
||
|
||
- 保持与旧版一致的 API/Socket contract，不要修改后端接口。
|
||
- 所有按钮的 `title/aria-label` 均需保留。
|
||
- `window.ensureCsrfToken`、`window.requestSocketToken`、`EasterEggRegistry` 等全局对象仍由后端注入，前端需防御其缺失。
|
||
- 在组件化过程中，务必维持 `state -> UI` 的单向数据流，避免在多个组件中直接 mutate 同一对象，可通过 store action 统一更改。
|
||
|
||
> 如需快速定位旧逻辑，可在 `static/src/app.ts` 搜索原方法名称；拆分完成后再逐步删除未使用的段落，直至 `app.ts` 不再作为兼容入口。
|
||
|
||
## 后续关注
|
||
|
||
1. **卫星页面重写**：登录/注册/终端/资源忙碌等页面仍在 `static/old_version_backup/`，后续若需要统一体验，可按本文架构另建轻量 Vue 入口。
|
||
2. **文件管理器现代化**：`static/file_manager/` 仍为独立 HTML/JS，可先迁移 API 调用，再视情况接入 Pinia。
|
||
3. **自动化验证**：目前主要依靠手测，建议补充组件单测或端到端脚本覆盖 Quick Menu、上传、彩蛋等关键链路。
|
||
4. **性能与可 observability**：随着样式模块化完成，可继续引入 bundle 分析、监控指标，确保未来扩展更易诊断。
|