# 桌面端专家工作台侧栏、设置页与窗口拖拽改造方案

## 1. 背景

当前桌面端专家工作台有三类明显体验问题：

1. 左侧栏仍存在空壳专家入口与占位标签，用户会误以为这些专家可用，降低完成度与可信度。
2. 设置页缺少面向内容生产场景的模型配置入口，无法分别配置生图、视频、文案三类模型的 `base_url` 与 `api_key`。
3. 桌面端窗口存在“拖不动”的问题，影响基础可用性。当前主窗口为无边框窗口，拖拽能力依赖前端显式标记的 drag 区域；现状中仅局部区域设置了 `-webkit-app-region: drag`，而窗口控制按钮区域又被标记为 `no-drag`，导致可拖拽热区不足且不稳定。

本轮目标聚焦为**桌面端 UI 与交互改造**，先把入口、图标、设置页结构、配置保存体验以及窗口拖拽体验整理到位；**本轮不接入抖音专家与小红书专家对这些模型配置的实际消费逻辑**。

## 2. 改造目标

改造完成后，应满足以下结果：

- 左侧栏只展示真实可用的专家入口，不再出现空壳项。
- 抖音专家不再使用红书书本语义图标，统一替换为音符风格图标。
- 设置页只保留当前需要暴露的能力：
  - 更换龙虾密钥
  - 三类专家模型配置
  - 工作目录
  - 导出诊断
- 生图模型、视频模型、文案模型均支持独立填写：
  - `base_url`
  - `api_key`
- 上述配置可保存、可回显、可区分“已配置 / 未配置”状态。
- 主窗口在顶部应存在稳定、连续、易命中的可拖拽区域；按钮、输入框、导航等交互控件不误触发拖拽。
- 保持现有底层兼容链路，不影响当前 runtime / cloud / 员工密钥能力。

## 3. 本轮范围

### 3.1 包含内容

#### A. 左侧栏专家区整理
- 删除当前硬编码的空壳专家占位入口。
- 左侧栏只保留真实项目型专家入口。
- 如果 `browser-ops` 仍在真实项目列表中，则继续按真实专家展示。

#### B. 抖音专家图标替换
- 保留小红书专家当前书本风格图标。
- 为抖音专家新增独立的音符 SVG 图标。
- 在左侧栏、专家卡片、专家详情 hero 等平台识别位置统一切换图标映射。

#### C. 设置页结构重做
设置页调整为三块：

1. **基础连接**
   - 保留“更换龙虾密钥”入口
   - 复用现有员工密钥链路，只改 UI 文案

2. **专家模型配置**
   - 生图模型配置
   - 视频模型配置
   - 文案模型配置
   - 每组字段统一为：`base_url`、`api_key`
   - 每组显示独立配置状态与用途说明

3. **诊断与工作区**
   - 工作目录
   - 导出诊断

#### D. 配置保存与回显
- 前端可编辑三组模型配置。
- 保存后重新进入设置页可以回显：
  - `base_url`
  - `apiKeyConfigured` 状态
- 不重新输入 `api_key` 时，不应误清空已有 key。

#### E. 窗口拖拽热区修复
- 保证 frameless 主窗口存在稳定的顶部拖拽区域。
- 拖拽热区不能依赖过小或被内容挤压的局部容器。
- 窗口控制按钮、输入框、tab、导航按钮等交互元素明确标记为 `no-drag`。
- 拖拽区域应覆盖主要页面共享头部，而不是只在个别页面生效。

### 3.2 明确不做

本轮**不做**以下内容：

- 不修改抖音专家、小红书专家的执行逻辑。
- 不让专家任务在本轮实际读取 `expertModelConfig`。
- 不改 `project-skill-router.ts`、`project-intent-router.ts` 等执行链路来接入这些模型配置。
- 不扩展为新的专家调度策略或模型路由策略。

## 4. UI / UX 设计要求

按 `ui-ux-pro-max` 约束落地，确保整体偏“科技感、高级感、可操作”。

### 4.1 视觉要求
- 所有新增图标使用 SVG，不使用 emoji。
- 保持深色主题一致性，采用卡片式分区。
- 使用细描边、弱发光、轻层次阴影，避免花哨渐变泛滥。
- 保证文字、边框、状态标签在暗色背景下有足够对比度。

### 4.2 交互要求
- 所有输入框必须保留明确 label，不能仅依赖 placeholder。
- 所有可点击元素提供清晰 hover / focus 状态。
- 触控目标不小于 44px。
- 保存按钮需要明确 loading / disabled 状态，避免重复提交。
- hover 不做位移或缩放导致布局抖动，只做颜色、描边、阴影、透明度变化。
- 可拖拽区域与可交互区域边界明确，避免“想点击却拖动窗口”或“想拖动却无响应”。

### 4.3 信息结构要求
- 旧通用配置项在界面中隐藏：
  - `Setup Mode`
  - `Provider`
  - 通用 `Base URL`
  - `Default Model`
- 当前“员工密钥”相关对外文案统一改为“龙虾密钥”。
- 工作目录保留，但视觉优先级低于模型配置区。

## 5. 关键改造点

### 5.1 左侧栏专家入口
**目标文件：** `apps/ui/src/App.tsx`

复用现有真实项目数据链路，去掉现在写死的 placeholder 专家标签，例如：

- `知乎专家`
- `视频号专家`
- 重复的 `抖音专家` 占位项

保留并复用现有：
- `workspace.projects`
- `visibleProjects`
- `expertCards`
- `resolveExpertKey()`

### 5.2 抖音专家图标
**目标文件：** `apps/ui/src/App.tsx`

处理方式：
- `xiaohongshu` 继续使用 `RedBookIcon`
- `douyin` 新增 `DouyinNoteIcon`
- `browser` / `general` 保持现有中性图标

需要统一覆盖以下使用场景：
- 左侧栏专家快捷入口
- 专家卡片
- 专家页 hero / 标题区
- 其他按平台渲染图标的位置

### 5.3 设置页结构与表单
**目标文件：** `apps/ui/src/App.tsx`

建议结构：
- 顶部摘要说明当前页用途
- 中间三张模型配置卡片
- 下方诊断与工作区卡片

三组模型配置建议统一结构：
- 标题
- 简短用途描述
- 已配置 / 未配置状态
- `base_url` 输入框
- `api_key` 密码输入框

### 5.4 配置类型契约
**目标文件：** `packages/shared-types/src/index.ts`

在不破坏现有类型兼容的前提下新增：

- `ModelEndpointConfig`
- `ModelEndpointInput`
- `ExpertModelConfig`

建议结构：

```ts
interface ModelEndpointConfig {
  baseUrl: string;
  apiKeyConfigured: boolean;
}

interface ModelEndpointInput {
  baseUrl: string;
  apiKey?: string;
}

interface ExpertModelConfig {
  image: ModelEndpointConfig;
  video: ModelEndpointConfig;
  copywriting: ModelEndpointConfig;
}
```

并扩展：

- `AppConfig.expertModelConfig`
- `SaveConfigInput.expertModelConfig?`

保留旧字段继续存在，避免影响当前其它链路。

### 5.5 配置持久化与密钥存储
**目标文件：**
- `apps/desktop/src/main/services/app-config.ts`
- `apps/desktop/src/main/services/secrets.ts`
- `apps/desktop/src/main/ipc.ts`
- `apps/desktop/src/preload/index.ts`

处理原则：

#### 普通配置
进入 `app-config.json`：
- 三组模型配置中的 `baseUrl`

#### 密钥配置
进入 `SecretManager`：
- `imageModelApiKey`
- `videoModelApiKey`
- `copywritingModelApiKey`

#### 返回给前端的内容
仅返回：
- `baseUrl`
- `apiKeyConfigured`

不向 renderer 返回明文 secret。

### 5.6 窗口拖拽热区修复
**目标文件：**
- `apps/ui/src/styles.css`
- `apps/ui/src/App.tsx`
- `apps/desktop/src/main/create-window.ts`

现状代码显示：
- 主窗口为 `frame: false`，并使用 `titleBarStyle: "hidden"`，属于需要前端自行提供拖拽热区的无边框窗口。
- 当前 `apps/ui/src/styles.css` 中窗口控制区为 `-webkit-app-region: no-drag`。
- 当前仅 `apps/ui/src/styles.css` 的 `.page-topbar` 被标记为 `-webkit-app-region: drag`，拖拽区域过于局部。

改造要求：
- 在共享顶栏或稳定头部容器上提供连续 drag 区域。
- 交互控件所在容器统一补 `-webkit-app-region: no-drag`。
- 避免 drag 区域被按钮组、表单、滚动容器完全挤占。
- 如现有布局难以保证稳定热区，可增加独立的顶层拖拽条，但必须保持视觉克制，不破坏科技感界面。

## 6. 关键文件

- `apps/ui/src/App.tsx`
- `apps/ui/src/styles.css`
- `apps/desktop/src/main/create-window.ts`
- `packages/shared-types/src/index.ts`
- `apps/desktop/src/main/services/app-config.ts`
- `apps/desktop/src/main/services/secrets.ts`
- `apps/desktop/src/main/ipc.ts`
- `apps/desktop/src/preload/index.ts`

## 7. 复用点

优先复用已有逻辑，避免重复造轮子：

- 专家识别：`apps/ui/src/App.tsx` 中 `resolveExpertKey()`
- 专家文案：`apps/ui/src/App.tsx` 中 `getExpertGuide()`
- 配置读写：`apps/desktop/src/main/services/app-config.ts` 中 `AppConfigService.load()` / `save()`
- 密钥存储：`apps/desktop/src/main/services/secrets.ts` 中 `SecretManager`
- 配置桥接：`apps/desktop/src/preload/index.ts` 与 `apps/desktop/src/main/ipc.ts` 中现有 `config.load/save`
- 诊断导出：现有 `diagnostics.exportSnapshot()` 链路
- 窗口创建：`apps/desktop/src/main/create-window.ts` 中现有 frameless window 配置

## 8. 验证项

### 8.1 左侧栏验证
- 左侧栏不再出现空壳专家 chip。
- 只展示真实专家入口。
- 抖音专家显示音符图标。
- 小红书专家继续显示书本图标。

### 8.2 设置页验证
- 页面只保留目标项：龙虾密钥、三类模型配置、工作目录、导出诊断。
- 三类模型都能填写 `base_url` 与 `api_key`。
- 不重新输入 `api_key` 时不会清空已保存密钥。
- 保存后重新进入页面，状态能正确回显。

### 8.3 配置持久化验证
- 重启应用后，三组 `baseUrl` 仍存在。
- 三组 `apiKeyConfigured` 状态正确。
- 原有龙虾密钥链路不受影响。
- 原运行时与云端配置链路不受影响。

### 8.4 窗口拖拽验证
- 主窗口顶部存在稳定可拖拽区域。
- 在聊天页、专家页、设置页都能正常拖动窗口。
- 点击最小化、最大化、关闭按钮不会误触发拖拽。
- 点击输入框、按钮、导航项、专家卡片时不会因为 drag 区域覆盖而失去交互。
- Windows 下拖拽体验连续，不出现“只有局部像素能拖动”的情况。

### 8.5 交互与视觉验证
- 深色主题下文本、边框、状态标签清晰可读。
- 输入框 focus 态清楚。
- 按钮 hover / disabled / loading 态明确。
- 无布局抖动、无误导性占位入口。

## 9. 建议落地顺序

1. 先改 `shared-types`，补齐三类模型配置契约。
2. 再改 `app-config` / `secrets` / `ipc` / `preload`，打通保存与回显。
3. 处理窗口拖拽热区：
   - 梳理共享头部结构
   - 明确 drag / no-drag 分区
   - 回归聊天页、专家页、设置页
4. 最后集中改 `apps/ui/src/App.tsx`：
   - 清理左侧栏空壳专家
   - 替换抖音图标
   - 重做设置页布局与交互
5. 最后做桌面端手动回归与 smoke 验证。
