docs: add UI and installer follow-up plans

docs/# 安装包瘦身回滚计划.md

+# 安装包瘦身回滚计划
+
+## 当前结论
+
+上一轮回滚不合格：它删除了 runtime cleanup，导致新安装包变成完整 payload，体积超过最近可用备份包。
+
+- 最近可用基线：`dist/installer/backup/千匠问天-20260430-164341.exe`
+- 基线大小：`538,315,023 bytes`
+- 回滚后的异常包：`dist/installer/千匠问天-Setup-0.1.0.exe`
+- 异常包大小：`596,924,319 bytes`
+- 增量：`58,609,296 bytes`，约 `55.9 MiB`
+
+## 回滚原则
+
+瘦身失败时，必须回到最近可用小包基线，不能回到更大的完整 runtime payload。
+
+允许保留：
+
+- `ffmpeg/bin/ffmpeg.exe`
+- `ffmpeg/bin/ffprobe.exe`
+- `playwright-browsers/`
+- 当前 runtime 必需 Python 依赖
+
+必须恢复：
+
+- runtime payload cleanup
+- cleanup 统计写入 manifest
+- OpenClaw docs 裁剪但保留 workspace templates
+- Python tests、cache、pyc/pyo、source map 等无运行价值文件清理
+
+## 修正方式
+
+1. 恢复 `build/scripts/materialize-runtime-payload.ps1` 中 cleanup 相关逻辑。
+2. 确认 `materializationInputs.schemaVersion` 回到 cleanup 对应版本。
+3. 不修改 `apps/desktop/electron-builder.yml`，当前 `compression: store` 是既有状态。
+4. 删除并重新生成 runtime payload。
+5. 重新打包。
+6. 对比新包大小，必须不大于 `538,315,023 bytes`。
+
+## 验证命令
+
+```powershell
+corepack pnpm materialize:runtime
+corepack pnpm package
+corepack pnpm typecheck
+corepack pnpm smoke:ffmpeg-runtime
+```
+
+必要时再运行：
+
+```powershell
+corepack pnpm smoke:installer
+```
+
+## 接受标准
+
+- `vendor/openclaw-runtime/runtime-manifest.json` 包含 `cleanupSummary` 和 `payloadStats`。
+- 新安装包大小 `<= 538,315,023 bytes`。
+- `ffmpeg.exe` 和 `ffprobe.exe` 仍在 runtime payload 中。
+- 抖音视频/ffprobe 相关 smoke 不因瘦身缺少二进制而失败。
+
+## 失败处理
+
+如果新包仍然大于基线，不继续扩大回滚范围；先分析 manifest 的 `topLevelBreakdown` 和 `payloadStats`，定位新增体积来源后再补充 cleanup 规则。

docs/2026-04-30-frontend-ui-phased-refactor-plan.md

+# 前端 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 验证。

docs/客户端自动更新方案.md

+# OpenClaw 客户端自动更新方案
+
+  ## Summary
+
+  为当前 Electron 客户端增加“版本更新自动推送”能力：客户端启动后自动检查版本，云端可按版本、渠道、员工/组织做灰度或强
+  制更新；用户收到提示后点击下载并安装，体验接近 WorkBuddy。
+
+  默认采用“自有云接口 + electron-updater + NSIS 安装包”的方案，优先适配当前 Windows-first 打包链路。
+
+  ## Key Changes
+
+  ### 更新发布链路
+
+  - 在 apps/desktop 引入 electron-updater。
+  - 在 apps/desktop/electron-builder.yml 增加 publish/update feed 配置。
+  - 打包后产物需要包含：
+      - 千匠问天-Setup-x.y.z.exe
+      - latest.yml
+      - 安装包 sha512 校验信息
+  - 发布流程调整为：
+      1. 更新根 package.json 和 apps/desktop/package.json 版本号。
+      2. 执行 corepack pnpm package。
+      3. 上传 installer 与 latest.yml 到云端文件存储/CDN。
+      4. 后端登记该版本的元数据。
+
+  ### 云端版本接口
+
+  新增一个产品更新接口，建议路径：
+
+  POST /v1/desktop/update/check
+
+  请求包含：
+
+  {
+    "appId": "com.qianjiangclaw.desktop",
+    "currentVersion": "0.1.0",
+    "platform": "win32",
+    "arch": "x64",
+    "employeeId": "xxx",
+    "channel": "stable"
+  }
+
+  响应包含：
+
+  {
+    "available": true,
+    "version": "0.2.0",
+    "channel": "stable",
+    "mandatory": false,
+    "releaseNotes": "修复启动问题，优化专家加载。",
+    "feedUrl": "https://cdn.example.com/qjclaw/stable/latest.yml",
+    "downloadUrl": "https://cdn.example.com/qjclaw/stable/千匠问天-Setup-0.2.0.exe",
+    "sha512": "..."
+  }
+
+  云端需要支持：
+
+  - stable/beta/dev 渠道。
+  - 按员工、组织、版本范围灰度。
+  - 强制更新标记。
+  - 最低可用版本，用于阻止过旧客户端继续使用。
+  - 回滚到上一版本。
+
+  ### 桌面主进程
+
+  新增 AppUpdateService，放在 apps/desktop/src/main/services/app-update.ts。
+
+  职责：
+
+  - 读取当前 app.getVersion()。
+  - 调用云端更新检查接口。
+  - 配置 autoUpdater.setFeedURL(...)。
+  - 管理状态机：
+      - idle
+      - checking
+      - available
+      - not-available
+      - downloading
+      - downloaded
+      - installing
+      - error
+  - 处理 electron-updater 事件：
+      - checking-for-update
+      - update-available
+      - update-not-available
+      - download-progress
+      - update-downloaded
+      - error
+  - 提供“立即安装”能力：调用 autoUpdater.quitAndInstall()。
+  - 开发环境不自动安装，只返回 mock/disabled 状态。
+
+  ### IPC 与共享类型
+
+  在 packages/shared-types/src/index.ts 增加：
+
+  - UpdateStatus
+  - UpdateCheckResult
+  - UpdateProgress
+  - UpdateState
+  - IPC channels：
+      - app-update:get-status
+      - app-update:check
+      - app-update:download
+      - app-update:install
+      - app-update:event
+
+  在 apps/desktop/src/preload/index.ts 暴露：
+
+  qjcDesktop.appUpdate.getStatus()
+  qjcDesktop.appUpdate.check()
+  qjcDesktop.appUpdate.download()
+  qjcDesktop.appUpdate.install()
+  qjcDesktop.appUpdate.onEvent(listener)
+
+  ### Renderer UI
+
+  在 apps/ui/src/App.tsx 增加更新提示入口，保持现有主布局稳定。
+
+  建议 UI 行为：
+
+  - 普通更新：
+      - 顶部 toast/notice 显示“发现新版本 x.y.z”。
+      - 按钮：“立即更新”“稍后”。
+      - 下载中显示进度。
+      - 下载完成显示“重启并安装”。
+  - 强制更新：
+      - 显示不可关闭的更新弹窗。
+      - 允许查看更新说明。
+  - smoke/mock API 中补 mock update 状态，避免开发模式 UI 崩溃。
+
+  - Windows 发布前建议接入代码签名证书。
+  - 下载包必须校验 sha512。
+  - 更新失败不得破坏现有安装。
+  - 下载中断后允许重新下载。
+  - 强制更新只阻止业务入口，不直接杀进程。
+  - dev 模式默认禁用真实安装，避免误触发本地更新。
+
+  ## Test Plan
+
+  - corepack pnpm typecheck
+  - corepack pnpm build
+  - corepack pnpm package
+  - 新增 smoke：
+      - mock 云端返回无更新。
+      - mock 云端返回普通更新。
+      - mock 云端返回强制更新。
+      - mock 下载失败时 UI 显示错误。
+      - 已下载后触发安装 IPC。
+  - 手工验证：
+      - 旧版本安装后能检测到新版本。
+      - 点击更新能下载安装包。
+      - 点击“重启并安装”后版本变为新版本。
+      - 强制更新弹窗不可被普通关闭绕过。
+      - 设置页显示当前版本正确。
+
+  ## Assumptions
+
+  - 首期只支持 Windows NSIS 更新。
+  - 更新源使用自有云接口控制版本策略，安装包文件放 CDN/对象存储。
+  - 首期采用轮询检查，不做真正 WebSocket 实时推送：
+      - 启动后检查一次。
+      - 登录/绑定成功后检查一次。
+      - 每 6 小时后台检查一次。
+  - 真实“服务端主动推送”可作为二期，在现有状态机上增加 WebSocket/SSE 触发检查即可。
+  - 未签名也能开发测试，但生产发布建议签名后再开放自动更新。
\ No newline at end of file

docs/左侧栏数字员工树形目录与 13/14 寸适配计划.md

+# 左侧栏数字员工树形目录与 13/14 寸适配计划
+
+  ## Summary
+  在不改业务逻辑的前提下，重构客户端左侧栏的信息密度和响应式表现。目标是：删除顶部 logo 品牌块，让导航和新建对话整体上移；把新建对话下方的专家区改成固定高度的“数字员工”树形目录；同时保持当前蓝紫玻璃质感、浅色渐变、圆角卡片、细描边的原 有
+  风格，不引入突兀的新视觉语言。
+
+  ## Design Direction
+  - 延续现有风格：
+    - 保留浅色玻璃背景、蓝紫边框、柔和渐变、圆角卡片、轻阴影。
+    - 不改成纯扁平黑白，也不引入强烈新配色。
+    - 树形目录使用当前已有的紫蓝高亮、浅底卡片、细滚动条。
+  - 降低突兀感：
+    - 分类行高度、字体、圆角接近现有 `nav-item` 和 `sidebar-session-card`。
+    - 展开专家项使用现有专家 SVG 图标体系，不用 emoji。
+    - 动效只保留 150–200ms 的颜色/箭头旋转，不做明显弹层或位移动画。
+  - 信息层级：
+    - 顶部：主导航 + 新建对话。
+    - 中部固定块：标题 `数字员工` + 树形分类。
+    - 底部弹性块：会话列表。
+
+  ## Key Changes
+  - `App.tsx` 结构调整：
+    - 删除 `<div className="sidebar-logo-block">...千匠问天...</div>`。
+    - 保留 `nav-list`、`sidebarNewSessionAction` 原 class，避免影响自动化。
+    - 在 `sidebar-experts-entry` 内新增标题栏：
+      - 左侧文字：`数字员工`
+      - 可选右侧轻量计数：专家总数，例如 `8`
+    - 当前 `CATEGORY_CONFIG` 保留分类 id/name，但移除 emoji icon 依赖。
+    - 分类头从 `<div onClick>` 改为 `<button type="button">`。
+    - 专家项从 `<div onClick>` 改为 `<button type="button">`。
+    - 展开内容改为行内树结构，不再使用绝对定位弹出层。
+  - 树形目录行为：
+    - 点击“内容营销”展开其专家列表，再点收起。
+    - 点击专家后继续调用现有 `handleExpertSelect(entry)`。
+    - 点击专家后仍关闭所有展开分类，沿用当前 `setExpandedCategories({})` 行为。
+    - 空分类不展示展开内容；分类行仍显示但可禁用或显示 `0`，推荐显示但禁用展开。
+  - 样式调整：
+    - `.sidebar` 改为响应式宽度：`clamp(232px, 19vw, 280px)`。
+    - 删除 logo 后缩小 `.sidebar-top` 的 gap 和顶部 padding，让“对话”区域自然上移。
+    - `.sidebar-experts-entry` 固定高度：
+      - 普通桌面：约 `280px`
+      - 13/14 寸紧凑屏：约 `220–240px`
+    - `.sidebar-expert-scroll` 只在数字员工块内部滚动：
+      - `overflow-y: auto`
+      - `overflow-x: hidden`
+      - 透明/细滚动条
+    - `.sidebar-session-section` 保持 `minmax(0, 1fr)`，吃掉剩余高度。
+  - 13/14 寸适配：
+    - 增加紧凑断点，推荐条件：
+      - `@media (max-width: 1440px), (max-height: 820px)`
+    - 紧凑模式压缩：
+      - sidebar padding：从约 `24px/16px` 降到 `14–16px/12px`
+      - nav-item 高度：从 `44px` 降到 `38–40px`
+      - 新建对话高度：从 `46px` 降到 `40px`
+      - 数字员工块 padding/gap 下降 2–4px
+      - 会话卡片高度和间距轻微下降
+    - 保证主工作区仍使用 `minmax(0, 1fr)`，不产生横向滚动。
+
+    - `switchExpert`
+    - `activateHomeShortcut`
+    - `openHomeChat`
+    - `nav-item`
+    - `conversation-new-session`
+    - `sidebar-new-session`
+    - `sidebar-digital-workers-title`
+    - `expert-tree-list`
+    - `expert-tree-category`
+    - `expert-tree-category-trigger`
+    - `expert-tree-expert`
+
+  ## Risk Points
+  - `styles.css` 里侧栏样式重复较多，后面的 `.conversation-shell ...` 规则优先级更高，实际改动应放在后段生效区，避免被覆盖。
+  - 删除 logo 后，侧栏顶部高度会明显变化，需要检查窗口拖拽区域是否仍可用。
+  - 固定数字员工高度可能挤压会话列表，必须在 `1366×768` 检查。
+  - 分类匹配目前依赖正则识别专家 id/name，新增专家可能落到“其他专家”。
+  - 不要删除核心 DOM class，否则 smoke helper 或自动化选择器可能失效。
+  - 当前有残留 Electron 进程 PID `32180` 曾拒绝结束，后续跑 smoke 前需确认不会干扰测试。
+
+  ## Test Plan
+  - 静态验证：
+    - `corepack pnpm typecheck`
+    - `corepack pnpm build`
+  - 手动视觉检查：
+    - `1366×768`：13 寸常见低高屏，重点看是否挤压、是否横向滚动。
+    - `1440×900`：14 寸常见比例。
+    - `1536×864`：Windows 缩放常见工作区。
+    - `1920×1080`：标准桌面。
+  - 功能检查：
+    - “对话 / 数字员工 / 知识库 / 插件 / 设置”可切换。
+    - “新对话”可点击。
+    - “数字员工”标题存在。
+    - 点击“内容营销”展开专家。
+    - 点击专家后仍进入对应专家或填入快捷 prompt。
+    - 会话列表可滚动、切换、关闭。
+    - 数字员工块内部滚动，不影响整页布局。
+  - UI 验收：
+    - 无 logo 和“千匠问天”品牌块。
+    - 导航和新建对话明显上移。
+    - 树形目录不浮层遮挡。
+    - 样式与现有蓝紫玻璃风一致。
+    - 无横向滚动。
\ No newline at end of file