# 前端 UI 与交互分阶段改造计划

## 背景

当前 renderer 曾长期集中在 `apps/ui/src/App.tsx` 和 `apps/ui/src/styles.css`：

- `App.tsx` 同时承担 IPC mock、workspace 状态、聊天流、专家入口、设置页、插件页、smoke hooks 和主要 JSX。
- `styles.css` 存在多轮核心布局类定义，后续 UI 调整容易互相覆盖。
- 参考项目 `D:\cloud-desk-hero-main` 的 `features/*`、`stores/*`、`components/ui/*`、`lib/ipc/*` 分层方式适合当前项目，但不建议整套直接搬迁。

改造目标是渐进式拆分架构、稳定交互、统一视觉，而不是一次性重写。

## 总体原则

- 保留现有 Electron IPC、preload bridge、shared-types 合约。
- 保留现有 smoke hooks 和自动化依赖的 DOM/selector。
- 保留桌面两栏骨架：左侧 sidebar，右侧 workspace。
- 继续使用核心结构类：`conversation-shell`、`conversation-main-layout`、`conversation-content-area`、`conversation-panel`。
- 不直接全量引入参考项目的 shadcn/Radix/Tailwind 3 配置；当前项目是 React 19 + Tailwind 4。
- 每阶段都必须能独立构建、验证、回滚。

## Phase 1：架构拆分准备，不改视觉

目标：先把纯逻辑和 mock 层从巨型 `App.tsx` 拆出，保持 UI 外观和行为不变。

修改范围：

- 新增 `apps/ui/src/lib/desktop-api.ts`，迁移 `desktopApi`、`mockDesktopApi`、mock stream 相关逻辑。
- 新增 `apps/ui/src/lib/chat-utils.ts`，迁移消息合并、markdown 渲染、附件判断、时间格式化等纯函数。
- 新增 `apps/ui/src/lib/constants.ts`，迁移默认 skill、附件扩展名、composer 尺寸常量。
- `App.tsx` 暂时仍负责顶层状态和 JSX，只减少内联工具逻辑。

当前状态：已完成。

代码事实：

- `apps/ui/src/lib/desktop-api.ts` 已存在。
- `apps/ui/src/lib/chat-utils.ts` 已存在。
- `apps/ui/src/lib/constants.ts` 已存在。

## Phase 2：Shell 与页面分区

目标：建立类似参考项目的 `features/*` 结构，但继续复用现有 CSS class 和交互行为。

修改范围：

- 新增 `features/shell/Sidebar.tsx`
- 新增 `features/shell/TopBar.tsx`
- 新增 `features/chat/ChatWorkspace.tsx`
- 新增 `features/experts/ExpertsView.tsx`
- 新增 `features/plugins/PluginsView.tsx`
- 新增 `features/settings/SettingsView.tsx`
- 新增 `features/knowledge/KnowledgeView.tsx`
- `App.tsx` 改为视图编排层。

当前状态：基本完成。

代码事实：

- `apps/ui/src/features/shell/AppSidebar.tsx` 已存在并被 `App.tsx` 引用。
- `apps/ui/src/features/shell/Sidebar.tsx` 已存在。
- `apps/ui/src/features/shell/TopBar.tsx` 已存在。
- `apps/ui/src/features/chat/ConversationWorkspaceView.tsx` 已存在并被 `App.tsx` 引用。
- `apps/ui/src/features/chat/ChatWorkspace.tsx` 已存在。
- `apps/ui/src/features/experts/ExpertsView.tsx` 已存在。
- `apps/ui/src/features/plugins/PluginsView.tsx` 已存在。
- `apps/ui/src/features/settings/SettingsView.tsx` 已存在。
- `apps/ui/src/features/settings/SettingsPanels.tsx` 已存在并被 `App.tsx` 引用。
- `apps/ui/src/features/knowledge/KnowledgeView.tsx` 已存在。

剩余边界：

- `App.tsx` 仍保留顶层编排、smoke actions、部分业务状态和回调。

## Phase 3：状态管理分层

目标：参考 store 思路，把 UI 状态、聊天状态、workspace 状态拆开。

修改范围：

- 新增 `useWorkspaceState`
- 新增 `useChatState`
- 新增 `useExpertsState`
- 新增 `useSettingsState`
- 新增 `useUiState`
- 先用 React hooks/context 实现；如状态复杂度仍高，再评估引入 `zustand`。
- 下沉 `sendPrompt`、stream event、session 切换、专家入口选择等逻辑。

当前状态：部分完成。

代码事实：

- `apps/ui/src/features/chat/useProjectSessions.ts` 已存在。
- `apps/ui/src/features/chat/useSessionMessages.ts` 已存在。
- `apps/ui/src/features/chat/useMessageTraces.ts` 已存在。
- `apps/ui/src/features/chat/useChatStreamingController.ts` 已存在并被 `App.tsx` 引用。
- `apps/ui/src/features/chat/useChatSessionsController.ts` 已存在并被 `App.tsx` 引用。
- `apps/ui/src/features/chat/usePromptSubmission.ts` 已存在并被 `App.tsx` 引用。
- `apps/ui/src/features/chat/useHomeIntentSuggestion.ts` 已存在。
- `apps/ui/src/features/settings/useSettingsState.ts` 已存在。
- `apps/ui/src/features/shell/useHomeNavigation.ts` 已存在并承载 `openHomeChat`、`activateHomeShortcut`、`handleNavSelection`。

剩余边界：

- `App.tsx` 当前仍有 2054 行。
- `App.tsx` 仍保留 smoke actions、部分顶层状态、页面级编排和部分业务回调；conversation/settings 的页面 props 组装已提到 return 前的 typed props 常量。
- `zustand` 未引入。

## Phase 4：设计系统与交互升级

目标：吸收参考项目视觉体系和组件化优点，但适配当前桌面工具产品。

修改范围：

- 整理 `styles.css`，确保核心布局类只保留最终生效的一套定义。
- 建立轻量 `apps/ui/src/components/ui/*`：
  - `Button`
  - `IconButton`
  - `Panel`
  - `Tabs`
  - `StatusChip`
  - `ScrollArea`
- 统一颜色、间距、圆角、focus、hover、disabled、loading、error 状态。
- 优化聊天、专家、插件、设置页的桌面工具型布局。

当前状态：未完成，继续收口中。

代码事实：

- `apps/ui/src/components/ui/Button.tsx` 已存在。
- `apps/ui/src/components/ui/IconButton.tsx` 已存在。
- `apps/ui/src/components/ui/Panel.tsx` 已存在。
- `apps/ui/src/components/ui/ScrollArea.tsx` 已存在。
- `apps/ui/src/components/ui/StatusChip.tsx` 已存在。
- `Tabs` 未实现。
- `lucide-react` 未引入。
- `apps/ui/src/styles.css` 已收口为 8 行入口 import，实际样式拆到 `apps/ui/src/styles/*.css`。
- `apps/ui/src/styles/base.css`、`chat.css`、`components.css`、`knowledge.css`、`plugins.css`、`settings.css`、`shell.css`、`theme-openclaw.css` 已存在并承载主样式。
- `conversation-shell`、`conversation-main-layout`、`conversation-content-area`、`conversation-panel` 等核心骨架类仍保留。
- 本轮已清理部分旧注释、空弹层注释块，并删除被末端 revamp 层覆盖的 `conversation-workspace` 早期视觉声明；布局、滚动和核心骨架类保留。
- 本轮已修复 `ConversationWorkspaceView` 中一处可见 mojibake 文案，恢复为“当前对话”。

剩余边界：

- 继续收口 `styles.css` 中确认安全的历史重复规则。
- 暂不迁移 composer submit、新建会话、home intent actions、smoke actions、stream 主链路这些高风险节点。
- 暂不引入 `lucide-react`、Radix、shadcn、zustand。

## 当前验收状态

截至 2026-05-08，最近一轮验证已通过：

- `corepack pnpm --filter @qjclaw/ui typecheck`
- `corepack pnpm build`
- `corepack pnpm smoke:default-chat`
- `corepack pnpm smoke:desktop-session-switch-stream`
- `corepack pnpm smoke:desktop-expert-bootstrap-ui`
- `corepack pnpm smoke:settings`

本轮验证：

- `corepack pnpm --filter @qjclaw/ui typecheck`
- `corepack pnpm build`
- `corepack pnpm smoke:default-chat`
- `corepack pnpm smoke:desktop-session-switch-stream`
- `corepack pnpm smoke:desktop-expert-bootstrap-ui`
- `corepack pnpm smoke:settings`
- 编码检查：`App.tsx`、`styles.css`、`ConversationWorkspaceView.tsx`、本文档均无 UTF-8 BOM；UI/文档错码标记扫描通过。
- 人工检查：Vite renderer chat 页面可打开，左侧栏/右侧 workspace 高度稳定，message list 与 composer 未出现横向溢出；Playwright 后续 nav 点击探针超时，未完成五页人工验收。

本轮未完成：

- 未新增 `Tabs`。
- 未引入 `lucide-react`、Radix、shadcn、zustand。
- 未迁移 stream 主链路、composer submit、新建会话、home intent actions、smoke actions。

## 当前结论

四个阶段没有全部完成。

- Phase 1：已完成。
- Phase 2：基本完成。
- Phase 3：部分完成。
- Phase 4：未完成，仍处于 CSS 收口和低风险组件接入阶段。

下一步优先级：

- 继续压薄 `App.tsx` 中的顶层编排，但不动 stream 主链路和 smoke action 协议。
- 继续收口 `styles.css`，只删除确认被最终规则覆盖且不影响布局/滚动的历史规则。
- 如要推进设计系统，先补 `Tabs` 或扩大现有 UI 组件接入，但必须逐页 smoke 验证。
