agent-Specialization/doc/frontend/next_steps_4.md

前端重构续办说明（next_steps_4）

承接 next_steps_3，本阶段工作完成了“第二阶段：业务面板与个性化”的全部目标，并准备进入“第三阶段：全局壳层与 Socket/Overlay 拆解”。下文总结当前状态、仍需处理的事项及建议顺序，供下一位开发者参考。若与 legacy_ui_spec.md 有冲突，请以规范文档为准。

阶段成果回顾

1. 文件/待办/右键菜单

   • 新增 useFileStore 托管 fileTree/expandedFolders/todoList 与右键菜单；文件树更新、右键定位、下载入口、TODO Socket 事件均通过 store 维护，LeftPanel 与 FileNode 直接消费 store 状态。
   • 上传/下载触发链路保留在 app.ts，但右键显示/隐藏、目录展开逻辑已与模板解耦。

2. 聚焦面板

   • 新增 useFocusStore 负责 /api/focused 拉取与 focused_files_update Socket 事件，FocusPanel 直接订阅 Pinia 状态；聚焦变化时的 Token 刷新仍由 resourceStore 完成。

3. 子智能体

   • 新增 useSubAgentStore 托管列表数据与轮询；LeftPanel 切换到 store action，App 仅在 mounted/unmounted 时启动/停止 Polling，并在切换到子智能体面板时触发拉取。

4. 个性化/个人空间

   • 新增 usePersonalizationStore，封装整个 Drawer 的状态、表单、拖拽、保存/启停与登出逻辑；PersonalizationDrawer 由 store 驱动，App 只负责打开入口和上传/Socket 相关联动。

5. App.vue/App.ts 解耦

   • 删除了原有的 fileTree/focusedFiles/todoList/subAgents/personalization data 字段、方法与 watchers，将布局中对应 props/事件精简为 store 驱动。

当前状态

• 第一阶段（聊天/输入域）：全部子任务已完成（状态迁移、Action 组件化、动作按钮 store 化、append/modify payload 渲染），请以 doc/frontend/next_steps_3.md 为参考。
• 第二阶段（业务面板/个性化）：三个模块均完成 Pinia 化；app.ts 中已无业务状态，仅保留连接、聊天和工具相关逻辑。
• 第三阶段（待启动）：App 仍承载 Socket 管理、Toast/Confirm/Overlay/EasterEgg 等壳层逻辑；app.ts 依旧超出推荐体量，需要继续拆解。

下一步建议（第三阶段）

1. Socket 与跨模块事件

   • 抽象 useLegacySocket() 或类似 composable，将所有 socket.on/emit 管理集中到独立模块，通过事件总线或 store action 分发。目标：app.ts 仅负责初始化 & 注入依赖。
   • 结合 useResourceStore/useChatStore/useFileStore 等 store，统一处理 token_update、todo_updated、focused_files_update 等事件，避免重复逻辑。

2. 全局壳层

   • 拆分 ToastStack、ConfirmDialog、QuotaToast、EasterEggOverlay、ContextMenu 等通用 UI，创建 AppShell.vue 或多个全局组件，使用 store/composable 提供状态（如 useUiStore 新增 toast/confirm/easterEgg slice）。
   • 移除 app.ts 中的 DOM 事件监听（click/scroll/keydown）与手动 document.body 操作，改为组件级的事件绑定或 onMounted composable。

3. 输入/上传/工具联动

   • 虽已存在 useUploadStore，但上传流程、Quick Menu 与工具禁用仍在 app.ts；推荐将上传动作（uploadSelectedFile、toast 管理、错误文案）迁至新 composable/stores，并为 Quick Menu 建立独立模块。

4. 样式与可维护性

   • 当前仍使用旧版 CSS，大量样式依赖 static/style.css。第三阶段完成后，可按组件拆分 SCSS 或 CSS Modules（长期目标），确保 legacy 风格可控。

风险与注意事项

• Socket 兼容：拆分过程中确保所有 socket.emit 与 socket.on 名称、顺序保持与后端契约一致；必要时在 composable 中集中打印日志便于调试。
• Store 循环依赖：多个 store 之间会互相引用（如子智能体依赖 UI store 的 panelMode）；拆分时注意封装结构，避免在 store 初始化阶段互相 import 产生循环。
• 右键菜单/下载：现阶段下载操作仍在 app.ts 中调用 downloadResource，但 contextMenu 状态来自 useFileStore；迁移时要保留 legacy_ui_spec 里要求的按钮标题与行为。
• 个性化：usePersonalizationStore 目前直接调用 fetch；后续若新增 API 校验或需要与其他 store 联动，可考虑抽象 API 层，保持请求可 Mock。

推荐实施顺序

1. 重构 Socket 管理（建立 composable + 事件分发）。
2. 拆出 AppShell/Toast/Confirm/EasterEgg 组件，与 useUiStore 整合。
3. 将上传/Quick Menu/工具禁用逻辑移入专用 store/composable。
4. 在 store/composable 稳定后，继续拆分 style.css，并补充端到端验证脚本或自动化测试（例如聚焦文件/子智能体/Todo socket 事件回放）。

完成第三阶段后，app.ts 应仅承担框架级入口（createApp、Pinia 注册、Shell 布局），所有业务状态通过 store + 组件组合而成。请持续参考 legacy_ui_spec.md，确保视觉与交互严格一致。