JOJO/agent-Specialization
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dd32db7677
agent-Specialization/doc/frontend/componentization_plan.md

7.3 KiB
Raw Blame History

前端专业化重构作业计划（持续进行中）

目标：在保持 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 分析、监控指标，确保未来扩展更易诊断。