---
title: 设置工作台设计规范
doc_type: design-guideline
domain: settings-ui
keywords:
  - 设置页
  - 设置工作台
  - design guideline
  - settings workspace
  - 控制台设计
summary: 固定 `/settings/*` 的工作台式布局、视觉层级、状态表达和分批优化待办。
when_to_read:
  - 要改 `/settings/*` 的布局、视觉、文案或交互层级
  - 要新增设置子页或统一现有设置页体验
  - 要把设置页优化拆成可执行的分批任务
read_next:
  - ../overview/architecture.md
  - ./research-workbench-layout.md
---
# 设置工作台设计规范

这篇文档固定的是“设置页应该长什么样、先展示什么、哪些地方不能继续漂移”。

它不是运行时任务看板，也不负责记录活跃协作状态；它负责给后续每一批 `/settings/*` 优化提供统一设计口径和稳定的 todo 清单。读完后如果要改具体实现，再回看 [项目架构](../overview/architecture.md) 和 [研究链路页面排版约定](./research-workbench-layout.md)。

## 本文职责

| 本文只负责什么 | 本文不负责什么 |
| --- | --- |
| 固定设置页的工作台式布局、视觉语气和组件层级 | 改变业务权限模型 |
| 统一状态摘要、字段卡片、分段导航和表格容器的设计口径 | 讨论 Rust / bridge / SQLite 边界 |
| 给后续优化拆分可执行的分批 todo | 代替运行时任务看板 |

## 设计定位

设置页在本项目里不是“系统偏好设置集合”，而是本地研究工作台的控制面。

它必须服务下面 3 件事：

1. 先让用户确认当前连接、规则和运行状态是否健康。
2. 再让用户进入具体配置或排障动作。
3. 让业务入口和控制面共处同一工作区，但层级清楚，不靠隐藏形成第二套菜单。

对应的视觉语气固定为：

- 冷静、专业、低噪音
- 高密度但不压迫
- 先状态，后表单
- 先必要信息，再单字段

## 统一设计约定

### 1. 整体壳层必须是“左侧分类导航 + 右侧工作区”

- `/settings` 顶层固定为双栏结构。
- 左侧负责分类、分组和切换，不承担长说明。
- 左侧导航默认使用“窄列图标 + 短标签”，正式长标题只保留在右侧工作区页头。
- 右侧负责当前分类的标题、摘要状态和内容区。
- 当前分类必须高亮；非当前分类保持低干扰。
- 所有设置入口共用同一套壳层，不允许为控制面入口另起第二套视觉语言。

### 2. 当前分类只显示“与当前动作直接相关的状态”

- 每个设置工作区页头部先给：
  - 当前分类名
  - 一句短说明
  - 0 到 3 个必要状态
- 摘要状态的推荐结构固定为：
  - `label`
  - `value`
  - 可选 `hint`
- 摘要状态只能表达当前页最关键的判断信息，例如：
  - 已启用数据源数
  - 凭据是否齐全
  - 是否有未保存修改
  - 后台运行是否正常
- 如果状态可以用一行短 chip 表达，就不要再单独起一排摘要卡。
- 禁止展示和当前配置动作无关的“虚荣统计”，例如：
  - 模块组数量
  - 设置入口数量
  - 仅用于凑版面的概览数字
- 顶层 `SettingsView.vue` 默认不展示全局统计块；除非状态会影响当前操作，否则不要把它塞进首页壳层。

### 3. 设置页内部只允许 4 类主内容容器

| 容器类型 | 适用场景 | 设计要求 |
| --- | --- | --- |
| 工作区头部面板 | 数据源、LLM、任务、通知这类分组入口页 | 先摘要，再切换子段 |
| 配置面板 | 应用、导入、系统状态、规则维护 | 短标题 + 短说明 + 操作按钮 |
| provider 双栏壳层 | AkShare / Tushare / iFind / CNInfo / LLM provider | 左侧字段，右侧能力/运行态说明 |
| 表格壳层 | 账户、日志、历史、失败任务、通知历史 | 工具栏在上，表格在中，统计脚注在下 |

禁止继续出现：

- 同一页里混用多种不一致的大卡片语言
- 一层卡片里面再嵌一层视觉同等强度的卡片
- 把长说明文字放在表单前面堆成信息墙
- 为了“看起来完整”而加一组没有操作价值的统计卡

补充：

- 像关键词、剔除词、分类这类“离散规则项”，优先使用紧凑按钮组或 token 组维护，不再回到逐项大卡片列表。
- 这类规则项的默认交互是：常用项可一键添加，已选项可一键删除。
- 如果规则项来自大词表或正式目录，例如 CNInfo 分类目录，优先使用单行高密度下拉：
  - 左侧主标题
  - 右侧辅助信息（父分类 / 编码）
  - 独立 popper 样式
  - 行高必须和虚拟列表配置一致，禁止再次出现文字裁切或遮挡

### 4. 状态表达必须统一用短词，不得自由发挥

设置页正式状态词统一优先使用下面这组：

- `已启用`
- `未启用`
- `已配置`
- `待补齐`
- `可用`
- `已停用`
- `未保存`
- `有风险`
- `开发`

要求：

- 同一语义只用一个正式短词，不允许同义词并存。
- 结构性缺失不允许展示成空白、`-` 或“看起来没问题”的默认值。
- badge / 摘要卡 / 字段说明应保持同一套状态词，不要每页自己翻译。

### 5. 文案层级固定为“短 kicker + 短标题 + 一句说明”

- kicker 只负责告诉用户当前工作区属于哪一类控制面。
- 标题只说当前页在做什么。
- 说明文字只保留一句话，避免和后续摘要或字段说明重复。
- 工具栏按钮文案优先使用动作动词，例如：
  - `刷新`
  - `保存`
  - `测试连接`
  - `打开下载页`
- 工具栏按钮默认采用“图标 + 短词”；二级动作在不损失可理解性的前提下优先收成图标按钮。

### 6. 视觉语言固定为“浅色协作台”，但继续兼容全局主题 token

- 以浅底、弱边框、轻阴影、小圆角为主。
- 大部分层级靠留白、分组和边框区分，不靠重色块。
- 强调色只用于当前选中、可操作主按钮和状态提醒。
- 图标以小圆点或轻量标识为主，不引入夸张插画或大色块 icon。
- 不允许把设置页重新做回“深色金融终端大面板堆叠”。

### 7. 响应式规则必须优先保证“可继续操作”

- 窄窗下先把双栏回落为单列，不允许关键按钮被挤出首屏。
- 导航项允许变短，但当前页标题、摘要状态和主要操作必须保留。
- provider 双栏壳层在窄窗下必须改为单列，右侧说明区跟到主内容下方。
- 表格页允许横向滚动，但工具栏和分页脚注不能失去可见性。

## 页面类型落点

### 设置首页壳层

- 目标文件：`SettingsView.vue`
- 负责统一左侧导航、当前分类标题和右侧工作区上下文。
- 不负责具体业务字段。
- 顶层只保留当前分类标题、一句短说明和必要状态；不要在这里展示模块数、入口数等概览统计。

### 分组入口页

- 目标页面：
  - `DataSourceSettings.vue`
  - `LlmSettings.vue`
  - `TaskScheduleSettings.vue`
  - `NotificationSettings.vue`
- 这些页必须先给当前状态摘要，再给 segment 切换。
- 当前状态摘要优先使用短 chip，不再默认展示 3 到 4 张概览卡。

### provider 明细页

- 目标页面：
  - `AkshareSettings.vue`
  - `TushareSettings.vue`
  - `IFindSettings.vue`
  - `CninfoSettings.vue`
  - `LlmProviderSettings.vue`
- 统一使用双栏壳层：
  - 左侧字段和保存动作
  - 右侧能力说明、运行态、连接反馈

### 运维 / 表格页

- 目标页面：
  - `AccountSettings.vue`
  - `SystemStatusSettings.vue`
  - `DebugToolsSettings.vue`
  - `TaskScheduleOverviewSettings.vue`
  - `TaskScheduleHistorySettings.vue`
  - `TaskScheduleFailedSettings.vue`
  - `NotificationPolicySettings.vue`
  - `NotificationHistorySettings.vue`
  - `LlmLogSettings.vue`
- 统一要求：
  - 先摘要
  - 再工具栏
  - 再表格或结果区
  - 最后给统计脚注

## 共享组件使用约定

设置页共享组件不允许随页面自由混搭，默认按下面使用：

| 组件 | 什么时候用 | 不该拿来做什么 |
| --- | --- | --- |
| `SettingsPagePanel` | 单页主面板，例如应用、导入、系统状态、规则页 | provider 双栏详情页 |
| `SettingsProviderPageShell` | 单个 provider 的明细配置页 | 历史表格页或普通单面板页 |
| `SettingsTableShell` | 主体内容是表格、历史、分页列表的页面 | 代替页面头或规则编辑容器 |
| `SettingsStatePanel` | 设置页里的 `loading / error / empty / success` 状态 | 业务字段卡或普通说明文案 |
| `SettingsSummaryGrid` | 当前工作区的 2 到 4 个关键摘要判断 | 展示长说明或完整配置详情 |
| `SettingsSegmentNav` | 同一父工作区下的子页切换 | 普通操作按钮组 |

补充约定：

- 新页面优先复用现有共享组件，不再新增平级视觉容器。
- 如果某个页面需要例外布局，先判断是不是现有 4 类主内容容器之一；不是的话，优先扩展共享组件，而不是在页面里直接写一套新容器。
- 设置页状态色、边框色和浅底 tone 统一走全局 `--settings-tone-*` token，不在单页里再写一套私有颜色。

## 验收口径

- 设置页顶层必须稳定呈现“导航区 + 工作区”两层结构。
- 设置页顶层不得展示与当前操作无关的统计块或概览数字。
- 每个分组入口页必须先显示摘要状态，再显示分段切换。
- 相同语义的状态词在不同设置页中必须一致。
- provider 明细页必须共享同一种双栏结构，不得再各写各的布局。
- 表格页必须共享同一套工具栏、表格容器和脚注节奏。
- 窄窗下必须可以继续完成主要操作，不得只剩视觉完整、无法操作。

## 当前基线

截至 `2026-04-02`，当前设置页已经开始向这套规范收口，主要落点包括：

- `SettingsView.vue`：壳层已收口为紧凑设置中心，不再显示全局虚荣统计
- `SettingsSectionFrame.vue`、`SettingsSummaryGrid.vue`、`SettingsSegmentNav.vue`：已压缩容器尺寸和装饰强度，避免继续膨胀成大块卡片
- `DataSourceSettings.vue`、`LlmSettings.vue`、`TaskScheduleSettings.vue`、`NotificationSettings.vue`：已补当前工作区摘要与子段切换说明
- `AkshareSettings.vue`、`TushareSettings.vue`、`IFindSettings.vue`、`CninfoSettings.vue`、`LlmProviderSettings.vue`：已统一 provider 页的摘要状态、字段顺序和侧栏反馈节奏
- `AccountSettings.vue`、`DebugToolsSettings.vue`、`LlmLogSettings.vue`、`NotificationPolicySettings.vue`、`NotificationHistorySettings.vue`、`TaskScheduleOverviewSettings.vue`、`TaskScheduleHistorySettings.vue`、`TaskScheduleFailedSettings.vue`、`SystemStatusSettings.vue`：已统一表格页摘要提示、工具栏说明和脚注节奏
- `NoticeRuleSettings.vue`、`ImportSettings.vue`、`AppSettings.vue`：已统一规则页、长任务页和应用页的摘要提示、字段 hint 与 footer 说明
- `NoticeRuleSettings.vue` 已固定为“阈值 / 剔除词 / 放行分类 / 放行关键词”四段单焦点切换，不再把四类规则堆在同一屏里
- `NoticeRuleSettings.vue` 的关键词、剔除词和分类项已继续收口为按钮组，常用项支持快速添加，已选项支持快速删除
- `NoticeRuleSettings.vue` 的放行分类下拉已收口为单行高密度目录列表，右侧显示父分类 / 编码，并使用独立 popper 样式
- 顶层左侧导航已收口为窄列图标 + 短标签，正式长标题只保留在工作区头部
- `DataSourceSettings.vue`、`LlmSettings.vue`、`TaskScheduleSettings.vue`、`NotificationSettings.vue` 已把父级摘要从概览卡收口到短状态 chip
- 高优先级工具栏动作已开始统一为“图标 + 短词”，规则页和部分控制面二级动作已收成图标按钮
- `SettingsStatePanel.vue` 已成为设置页统一的 loading / error / empty / success 状态容器；常见表格空态、设置页同步状态和关键空白页已开始接入
- 设置页共享 tone 已统一到全局 `--settings-tone-*` token，`SettingsPagePanel / SettingsProviderPageShell / SettingsTableShell / SettingsStatePanel` 的使用边界也已固定

这说明当前重点不是再发明第三套方向，而是继续删除无效概览和过度装饰，把剩余页面收口到同一规则。

## 2026-04-02 当前结论

- 设置页已经有正式设计真值，但顶层壳层不再鼓励“工作台式统计块”。
- 当前默认方向是紧凑设置中心，而不是仪表盘化设置首页。
- 当前父级工作台页优先用短状态 chip 表达当前健康度，不再默认起摘要卡行。
- 当前工具栏默认方向是“图标 + 短词”，不是长按钮堆叠。
- 后续如果继续改 `/settings/*`，优先删无操作价值的信息和装饰，再考虑新增视觉层级。

## 分批优化 Todo

### Batch 1：稳定共享设置组件

- [x] 审查 `SettingsActionButton / SettingsFieldCard / SettingsPagePanel / SettingsTableShell` 的 token 命名，避免继续出现只在单页生效的私有视觉分支。
- [x] 给共享设置组件补一轮注释和使用约定，明确哪些页面该用哪种壳层。
- [x] 清点当前设置组件里仍然偏重、偏暗或层级重复的视觉写法，并统一到浅色协作台语言。

### Batch 2：统一 provider 明细页

- [x] 收口 `AkshareSettings.vue`、`TushareSettings.vue`、`IFindSettings.vue`、`CninfoSettings.vue` 的字段顺序、摘要语气和右侧能力说明版式。
- [x] 收口 `LlmProviderSettings.vue` 的状态摘要、测试反馈和能力列表层级，使其与数据源 provider 页语言一致。
- [x] 为所有 provider 页补“未配置 / 待补齐 / 可用 / 未保存”的统一状态呈现，不再各页自定义表达。

### Batch 3：统一表格与运维页

- [x] 收口 `AccountSettings.vue`、`DebugToolsSettings.vue`、`LlmLogSettings.vue` 的工具栏和表格节奏，减少“表格页各长各的”问题。
- [x] 收口 `TaskScheduleOverviewSettings.vue`、`TaskScheduleHistorySettings.vue`、`TaskScheduleFailedSettings.vue` 的控制面层级，让“概览 / 历史 / 失败处理”三页共享同一结构。
- [x] 收口 `NotificationPolicySettings.vue`、`NotificationHistorySettings.vue` 的规则编辑、历史审计和空状态表现。
- [x] 收口 `SystemStatusSettings.vue`，把状态卡、动作按钮和字段区改成同一控制台语言。

### Batch 4：统一规则与导入页

- [x] 收口 `NoticeRuleSettings.vue` 的规则编辑区，避免说明、操作和列表层级混杂。
- [x] 收口 `ImportSettings.vue` 的路径输入、进度卡和错误区，使其更接近“长任务控制台”而不是“普通表单页”。
- [x] 检查 `AppSettings.vue` 的偏好、更新和运行信息 3 个面板，确保和其他设置页保持同一节奏。

### Batch 5：状态与交互打磨

- [x] 为设置页统一 loading / error / empty / success 的视觉语气，避免每页单独定义。
- [x] 检查所有摘要卡、badge、按钮和字段焦点态，确保键盘可达和主题一致。
- [x] 为常见长表格和分段页补充窄窗回落规则，避免移动宽度下出现首屏不可操作。

### Batch 6：回归与设计漂移门禁

- [x] 每完成一批页面优化，都跑 `python3 ~/.codex/skills/ui-design-drift-guard/scripts/drift_check.py --phase post`。
- [x] 每完成一批实现，都跑 `npm run check:constraints` 与 `npm run typecheck`。
- [x] 如果某一批改动涉及共享契约、状态映射或跨层编排，补跑 `npm run verify:logic`。
- [x] 每批收尾后，把“已完成页面 / 仍有漂移页面 / 下一批目标”回写到本文，不再另起运行时看板文档。
