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-29-desktop-ui-gray-blue-revamp-plan.md

+# OpenClaw 客户端灰白蓝科技感 UI 改造方案
+
+## 1. 目标
+
+在不改业务逻辑的前提下，重构桌面客户端的视觉系统和交互层级。
+
+最终方向是 **灰白主工作台 + 蓝色科技感 + 克制生产力工具风**：
+
+- 保留现有左侧导航栏、右侧工作区结构。
+- 保留当前偏灰白的整体基调。
+- 蓝色只作为科技感强调色，用在激活态、状态、聚焦、关键操作。
+- 降低当前浅蓝玻璃拟态和紫色渐变的存在感。
+- 让客户端更像专业 AI 桌面工作台，而不是普通网页后台或聊天 demo。
+
+## 2. 设计参考
+
+本方案结合三类参考，不直接照搬某一种：
+
+- Cursor：右侧 AI 工作区、底部输入、对话执行状态的专注感。
+- Linear：克制信息密度、清晰层级、低噪音边框和阴影。
+- Raycast：快速操作感、蓝色光感、明确状态反馈。
+
+当前客户端已有的灰白浅色基调继续保留，但需要收敛视觉语言。
+
+## 3. 现有问题
+
+- `apps/ui/src/styles.css` 中核心布局类存在多轮定义和覆盖，维护风险高。
+- 当前视觉同时存在紫色、浅蓝、灰白、玻璃、渐变，主线不够统一。
+- 左侧栏承载主导航、数字员工、专家树、会话列表，信息密度偏高。
+- 右侧工作区的聊天、专家、插件、设置页不像同一套产品系统。
+- hover 位移、强阴影、大圆角容易让界面偏轻浮，不够工具化。
+- focus、错误提示、键盘导航、滚动区边界需要进一步统一。
+- 部分中文注释或文案已有乱码迹象，后续修改必须避免编码扩大污染。
+
+## 4. 修改范围
+
+### 4.1 必改文件
+
+- `apps/ui/src/styles.css`
+  - 统一设计 token：颜色、边框、阴影、圆角、间距。
+  - 收敛重复定义的核心布局类。
+  - 重写 `.conversation-shell ...` 下聊天工作区的视觉样式。
+  - 统一插件、专家、设置页的卡片、标题区、状态 chip、滚动区。
+  - 补齐 hover、focus-visible、disabled、scrollbar 等交互状态。
+
+- `apps/ui/src/App.tsx`
+  - 仅做必要的结构类名整理和无业务语义增强。
+  - 保留现有事件处理、状态流、IPC 调用、专家选择、会话逻辑。
+  - 不移除现有 DOM 节点、按钮、自动化 selector。
+  - 可补充 `aria-label`、`role="alert"`、`aria-live` 等可访问性属性。
+  - 如实现消息 hover 时间，只在消息渲染结构中增加时间节点和格式化 helper，不改 `ChatMessage` 契约。
+
+### 4.2 不修改范围
+
+- 不改 Electron main process。
+- 不改 preload bridge。
+- 不改 `packages/shared-types` IPC 契约。
+- 不改 workspace、runtime、gateway、项目执行逻辑。
+- 不改专家、插件、会话、附件上传业务流程。
+- 不改构建、打包、安装脚本。
+
+## 5. 布局方案
+
+### 5.1 整体结构
+
+继续使用两列桌面结构：
+
+- 左侧：固定导航栏，建议宽度 `260px-280px`。
+- 右侧：主工作区，占满剩余宽度。
+
+不得把右侧工作区改成侧栏式单列页面，也不得引入第二套主壳布局。
+
+### 5.2 左侧导航栏
+
+左侧栏分为三段：
+
+- 顶部：品牌区、主导航、新建会话。
+- 中部：数字员工和专家分组。
+- 底部：会话列表和必要状态入口。
+
+交互要求：
+
+- 当前主导航使用浅蓝底、蓝色左侧激活线或细边框。
+- 专家 active 状态使用蓝色边框或蓝色浅底，不使用重阴影。
+- 专家树和会话列表分别拥有稳定滚动区。
+- 鼠标 hover 只改变背景、边框、文字色，不做明显位移。
+
+### 5.3 右侧工作区
+
+右侧统一为一个灰白工作台：
+
+- 外层背景：浅灰白。
+- 主工作面板：白色或近白色。
+- 顶部：页面标题、当前专家/模式、运行状态 chip。
+- 中部：消息列表、插件卡片、设置表单等内容。
+- 底部：Composer 或页面操作区。
+
+聊天页要求：
+
+- 消息列表独立滚动。
+- Composer 固定在右侧工作区底部。
+- 输入框 resize 不破坏工作区高度。
+- 状态提示不遮挡消息内容。
+
+插件、专家、设置页要求：
+
+- 共用同一套灰白卡片系统。
+- 标题、说明、状态、操作按钮的层级一致。
+- 页面滚动边界清晰，不出现窗口级混乱滚动。
+
+## 6. 视觉方案
+
+### 6.1 色彩
+
+建议色彩方向：
+
+- 页面背景：`#F5F7FA`、`#F8FAFC`
+- 面板背景：`#FFFFFF`、`#FDFEFF`
+- 主文本：`#0F172A`
+- 次文本：`#475569`
+- 弱文本：`#64748B`
+- 主蓝：`#2563EB`
+- 亮蓝：`#38BDF8`
+- 浅蓝底：`#EFF6FF`
+- 边框：`rgba(148, 163, 184, 0.22)`
+
+原则：
+
+- 灰白为主，蓝色为辅。
+- 不使用大面积紫色渐变。
+- 不使用大面积高透明玻璃。
+- CTA 橙色如保留，只能用于极少数关键动作，不进入常规导航。
+
+### 6.2 圆角和阴影
+
+- 小控件：`10px-12px`
+- 卡片：`14px-18px`
+- 主工作面板：`20px-24px`
+- 阴影以轻量为主，优先用细边框表达层级。
+- 避免当前过强的彩色阴影和大面积发光。
+
+### 6.3 消息样式
+
+- 用户消息：浅蓝气泡，右对齐。
+- AI 消息：白色内容卡，左对齐。
+- 代码、trace、执行状态：使用低饱和蓝灰卡片。
+- 系统提示：浅蓝状态条，明确但不抢正文注意力。
+- 用户消息气泡必须使用浅蓝色，不使用白色或深蓝实心色，确保和 AI 回复卡片区分明显。
+- 鼠标移到用户消息气泡或助手回复文本区域时，在该消息左下角显示发送/生成时间。
+- 时间格式固定为 `yyyy-mm-dd HH:mm:ss`，例如 `2026-04-29 15:30:08`。
+- 时间文字使用小字号、低对比度灰蓝色，只在 hover/focus-within 时显示，不常驻占用阅读注意力。
+- 时间显示不能改变消息主体布局高度，优先使用绝对定位或预留轻量位置处理。
+
+### 6.4 Composer
+
+- 使用白色输入面板。
+- focus 时显示蓝色描边和轻微蓝色光晕。
+- 附件、技能、发送按钮统一使用蓝色体系。
+- 禁用状态必须可读，不允许只降低到很低透明度。
+
+## 7. 交互方案
+
+- 所有可点击元素必须有 `cursor: pointer`。
+- hover 不造成布局位移，避免明显 `translateY`。
+- focus-visible 使用统一蓝色 ring。
+- disabled 状态降低强调，但保留文字可读性。
+- 错误提示使用 `role="alert"` 或 `aria-live="polite"`。
+- Tab 顺序应与视觉顺序一致。
+- 长列表使用内部滚动，不让整个应用窗口滚动。
+- 可折叠专家分组必须保留 `aria-expanded` 和 `aria-controls`。
+
+## 8. 实施步骤
+
+1. 先建立 `styles.css` 覆盖清单，标出所有核心布局类的早期定义、响应式定义、末尾主题覆盖。
+2. 明确删除/保留策略：保留基础布局定义和必要响应式规则，删除重复主题覆盖，避免继续靠文件末尾叠加修补。
+3. 建立统一 token：颜色、圆角、边框、阴影、间距，并把旧紫色/玻璃/强阴影 token 降级或替换为灰白蓝体系。
+4. 收敛主壳样式，只保留一套稳定的 `shell/sidebar/main-shell/content-area` 定义。
+5. 重写 `.conversation-shell ...` 范围内的聊天工作区样式，确保聊天页样式不泄漏到插件和设置页。
+6. 统一左侧栏主导航、专家树、会话列表的视觉和滚动区。
+7. 统一聊天、专家、插件、设置页的卡片和状态样式。
+8. 在 `App.tsx` 中只补充必要语义属性、结构类名、消息时间显示节点和格式化 helper，不改业务逻辑。
+9. 清理旧样式覆盖，避免新旧主题并存。
+10. 跑类型检查和构建。
+11. 做聊天、专家、插件、设置四个页面的人工回归和截图验收。
+
+## 9. 风险点
+
+- `styles.css` 现有重复定义较多，删除或调整顺序可能引发布局回归。
+- 当前文件末尾已有 `.shell.openclaw-theme` 和 `.conversation-shell` 主题覆盖，如果不先收敛覆盖层，会继续形成新旧主题叠加。
+- `App.tsx` 文件很大，哪怕小结构调整也可能影响隐藏的自动化依赖。
+- 消息时间显示依赖 `ChatMessage.createdAt`，字段已存在，但仍需要修改消息 DOM；应避免新增状态或改 IPC 契约。
+- 左侧栏内容较多，小屏高度下仍可能拥挤，需要重点验证滚动。
+- Composer 高度依赖 `conversationWorkspaceRef` 和当前 resize 逻辑，CSS 改动可能影响高度计算。
+- 插件、专家、设置页共用样式后，局部页面可能需要少量例外样式。
+- 中文文案和注释已有乱码，编辑时必须避免扩大编码问题。
+- 如果旧样式清理不彻底，会出现新旧主题互相覆盖。
+
+## 10. 测试计划
+
+### 10.1 自动验证
+
+```powershell
+corepack pnpm typecheck
+corepack pnpm build
+```
+
+如条件允许，补充一次截图验证：
+
+- 启动 `corepack pnpm dev`。
+- 分别截取聊天、专家、插件、设置页。
+- 覆盖 `375px`、`768px`、`1024px`、`1440px` 四个宽度。
+- 检查右侧工作区不是空白、不是侧栏化、没有明显遮挡或滚动断层。
+
+### 10.2 人工回归
+
+聊天首页：
+
+- 消息列表正常滚动。
+- Composer 固定底部。
+- 输入框 resize 正常。
+- 发送、附件、技能按钮状态正常。
+- 系统提示和错误提示可见。
+
+专家页：
+
+- 专家分组展开/收起正常。
+- 专家 active 状态清晰。
+- 专家切换不破坏当前会话逻辑。
+- 专家执行状态可读。
+
+插件页：
+
+- 插件卡片布局正常。
+- 状态 chip 可读。
+- 页面滚动区不溢出。
+
+设置页：
+
+- 表单、按钮、密钥输入、目录选择样式正常。
+- 保存、恢复、错误、成功提示可见。
+- 长内容不挤压主工作区。
+
+响应式：
+
+- `375px`
+- `768px`
+- `1024px`
+- `1440px`
+
+可访问性：
+
+- Tab 顺序合理。
+- focus-visible 明显。
+- 错误提示不是只靠颜色。
+- 普通文本对比度不低于 4.5:1。
+
+## 11. 验收标准
+
+- 视觉上明确是灰白主基调，蓝色科技感只做强调。
+- 左侧导航和右侧工作区仍保持稳定两列结构。
+- 聊天、专家、插件、设置页像同一套产品系统。
+- 没有业务行为变化。
+- 没有新增 TypeScript 或构建错误。
+- 没有明显滚动、遮挡、输入框高度回归。
+- 截图验收中聊天、专家、插件、设置页在目标宽度下都保持正确高度和滚动边界。
+- 没有新增中文乱码或编码污染。

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