---
artifact: design-system
product: dsh-skill-trace
version: "1.5"
updated: 2026-08-28
status: current-authority
---

# DSH Skill Trace Design System

## 1. 文档职责

本文是 DSH Skill Trace 的 UI 视觉与交互权威。后续新增页面、组件或状态时，应先遵守本文，再补充局部实现；稳定规则经过至少两个页面或状态验证后，才允许提升到本文。

本文定义：

- 产品的视觉方向与宿主一致性；
- 页面骨架、信息层级和通用组件合同；
- 状态、证据、表单、响应式、语言与可访问性规则；
- UI 变更的设计 Gate 与验收标准。

本文不定义：

- Skill 加载、收据、关联与验证结果的数据语义；
- Host 路由、Schema、隐私白名单和持久化策略；
- 产品版本范围和功能优先级；
- 其他插件的业务对象与状态机。

发生冲突时，权威顺序为：

1. DeepSeek Harness Desktop 的宿主合同；
2. `README.md` 的产品语义、版本范围与权限边界；
3. `docs/ARCHITECTURE.md` 的数据和实现合同；
4. 本文的视觉与交互规则；
5. 单页或组件的局部方案。

UI 不得反向改变证据语义、数据字段、正式状态或写入权限。

## 2. 设计目标

### 2.1 方向

关键词：`quiet / dense / precise / trustworthy / desktop-native`。

- 安静：界面退后，Skill、收据与用户任务前置。
- 紧凑：面向桌面工具场景，保持高信息密度和清晰分组。
- 任务导向：每个视图只突出一个主要任务，次要动作渐进披露。
- 宿主一致：继承 DSH 的字体、主题、语言和基础 Token。
- 证据可信：视觉层级不能把候选、推断或用户记录伪装成系统事实。
- 本地克制：不使用“云同步、排行榜、自动推荐”等不存在的能力暗示。

### 2.2 拒绝的模式

- 营销落地页式大标题、大留白和宣传语；
- 大面积蓝紫渐变、发光边缘、玻璃拟态与装饰动画；
- 每个容器都使用卡片、阴影和彩色标签；
- 同一页面出现多个竞争性的主按钮；
- 只依赖红、黄、绿表达状态；
- 用流程图连线暗示不存在的因果关系；
- 因单次截图好看而破坏宿主一致性或窄窗可用性。

## 3. 产品信息架构

```text
Skill 追踪
├── 我的 Skill
│   ├── Skill 列表：搜索、筛选、当前发现与历史候选
│   └── Skill 详情：声明 / 运行记录 / 学习与验证时间线
└── 当前会话
    ├── Skill 收据：按证据顺序阅读
    └── 流程地图：同一事实的关系视图
        └── 右侧 Inspector：节点解释与本地操作
```

固定原则：

- “我的 Skill”是跨会话入口，不是第三种当前会话视图。
- Skill 收据与流程地图共享同一 View Model，只改变阅读方式。
- 列表负责选择，详情负责理解，Inspector 负责当前对象的局部解释与操作。
- 页面加载、空、错误和就绪状态必须先经过状态 Gate，再挂载业务视图。

## 4. 语义 Token

宿主 Token 是第一选择；回退值只用于宿主 Token 缺失的异常环境。

```css
[data-plugin="dsh-skill-trace"] {
  --st-brand: var(--dsw-alias-state-business-primary,
    var(--dsw-static-deepseek-500, #3567d6));
  --st-bg: var(--dsw-alias-bg-base, #f7f8fa);
  --st-layer: var(--dsw-alias-bg-layer-1, #fff);
  --st-layer-2: var(--dsw-alias-bg-layer-2, #f3f5f7);
  --st-border: var(--dsw-alias-border-l2, rgba(22, 27, 36, .14));
  --st-border-soft: var(--dsw-alias-border-l3, rgba(22, 27, 36, .09));
  --st-text: var(--dsw-alias-label-primary, #17191d);
  --st-muted: var(--dsw-alias-label-secondary, #626871);
  --st-faint: var(--dsw-alias-label-tertiary, #8b9098);
  --st-success: var(--dsw-alias-state-success-primary, #16834b);
  --st-warning: var(--dsw-alias-state-warn-primary, #b36500);
  --st-error: var(--dsw-alias-state-error-primary, #c23c45);
}
```

| Token | 表达 | 不得表达 |
|---|---|---|
| `brand` | 当前选择、焦点、主动作、结构编号 | 成功或有效 |
| `success` | 已确认、操作成功、加载成功 | 候选、可能相关 |
| `warning` | 待确认、候选、变化、证据不足 | 普通未选择 |
| `error` | 失败、冲突、不可恢复错误 | 一般说明 |
| `muted / faint` | 元数据、辅助说明、证据边界 | 唯一的关键结果 |

状态必须同时包含文字；颜色只做辅助。

## 5. 字体、间距与表面

### 5.1 字体

插件继承宿主字体，不加载网络字体，不单独建立品牌字体。

| 层级 | 字号 | 字重 | 用途 |
|---|---:|---:|---|
| 页面标题 | 16px | 650 | 顶部栏当前任务 |
| 对象标题 | 22–24px | 680 | Skill 详情标题 |
| 区块标题 | 13–15px | 650 | 收据区块、详情区、Inspector |
| 正文 | 12–13px | 400 | 核心说明、表单内容 |
| 辅助文字 | 10.5–11px | 400 | 元数据、提示、边界 |
| 微型标签 | 9.5–10px | 500 | 状态、计数、字段提示 |

### 5.2 间距与圆角

- 间距阶梯：`4 / 6 / 8 / 10 / 12 / 16 / 18 / 24px`。
- 控件内部：6–12px；卡片内部：12–16px；主内容区：18–24px。
- 小控件圆角：5–7px；卡片：8–10px；胶囊标签：999px。
- 默认边框 1px；优先用边框、层级色和留白建立结构。
- 阴影只用于选中项或浮层，强度不高于 `0 1px 2px rgba(20,24,32,.08)`。

## 6. 页面骨架

### 6.1 顶部栏

- 最小高度 58px，水平内边距 16px。
- 左侧：状态点、页面标题、工作区或会话上下文。
- 右侧：页面级入口、当前会话视图切换、刷新。
- 顶部栏不放学习笔记保存、验证清除或收据删除等对象级动作。
- 同级视图使用紧凑分段控件，并通过 `aria-pressed` 表达当前项。

### 6.2 当前会话

```css
.st-layout {
  display: grid;
  grid-template-columns: minmax(0, 1fr) 290px;
}
```

- 主区承担收据或地图阅读；右侧栏承担当前 Skill / 节点的解释与本地操作。
- 收据最大宽度 980px，并在主区水平居中。
- 右侧栏建议 280–300px，不因内容无限加宽。
- 无 Trace 时只保留单一主区，不显示空 Inspector。

### 6.3 我的 Skill

```css
.st-catalog-page {
  display: grid;
  grid-template-columns: 380px minmax(0, 1fr);
}
```

- 左栏：搜索、状态筛选、Skill 列表。
- 左栏标准宽度为 380px；新增摘要或数据操作后不得继续压缩到需要省略关键状态文字。
- 右栏：详情最大宽度 860px，水平居中。
- 搜索和筛选可粘在列表顶部；列表卡只显示选择所需信息。
- 左栏顶部可以提供紧凑的回看摘要与确定性排序；汇总不得消除“已确认同源 / 候选历史”的详情分界。
- 回看摘要只保留标题与可操作计数；默认态不追加解释计数来源的注释，关联边界在 Skill 详情中按需说明。
- 搜索个人理解与人工结果时，列表只接收匹配条目 ID，不回传或展示整段个人内容。
- 备份、恢复与清空属于低频本地数据动作，收进渐进披露区；清空必须使用页面内确认并展示可用的安全备份状态。
- 本地数据主动作在侧栏内纵向排列并占满可用宽度；不得为了同排而让危险操作折成两行。
- 详情按“声明 → 运行记录 → 学习与验证时间线”组织。
- 来源完整一致与候选历史必须分区，不因视觉合并而提升关联等级。
- 未选择 Skill 时，右栏不是纯占位空白，而是显示“Skill Trace 如何帮助你”的七步学习导览；导览只解释产品机制、证据边界和下一步，不展示虚构数据，也不把界面说明写成“用户已经学会”的结论。
- 左栏目录摘要旁保留“使用指南”入口；用户看过某个 Skill 后仍可返回导览。窄屏隐藏该入口，因为窄屏未选择状态以目录选择为主，不显示右侧导览。
- 七步固定为：观察加载请求 → 形成真实收据 → 用流程地图看顺序 → 在我的 Skill 找到条目 → 写下个人理解 → 选择手工延续方式并制定验证 → 回来记录人工结果。
- 导览只保留一句价值说明、七步路径和一条合并后的开始/证据边界；不增加 eyebrow、收益摘要卡、重复小标题或盒装页脚。
- 七步标题说明动作，辅助短语只补充结果或边界；同屏已经表达过的事实不得换一种说法重复解释。
- 导览以一条连续的证据路径为唯一视觉重点，沿用现有字号、颜色、边框和圆角，不制作营销式大标题、彩色卡片墙或装饰插画。
- 宽屏导览内容最大宽度 860px 并水平居中；小于 1000px 时目录优先承担选择任务，不把完整导览强塞进 Skill 列表或造成额外横向滚动。

### 6.4 流程地图

- 外层负责铺满、网格和滚动；内部逻辑舞台固定 1000px。
- 可用宽度大于 1000px 时，逻辑舞台水平居中。
- 窄于 1000px 时，从左侧起点进入并允许横向滚动。
- 节点、连线、区块标签必须共享同一坐标舞台。
- 网格透明度低于普通边框；虚线必须配文字说明关系性质。
- 输出只与会话级人工关联相连，不连接到最后一个 Skill Step 暗示因果。

## 7. 通用组件合同

| 组件 | 必要内容 | 状态与约束 |
|---|---|---|
| PageHeader | 状态点、标题、上下文、页面级动作 | 不放对象级表单 |
| SegmentedSwitch | 2–3 个同级视图 | default / selected / focus |
| PrimaryButton | 文字，图标可选 | 每个视图最多 1–2 个主动作 |
| SecondaryButton | 文字或图标+文字 | 删除、清除不与保存竞争 |
| IconButton | 32×32px、14–16px 图标 | 必须有可访问名称 |
| StatusChip | 圆点、文字、语义色 | 不只用颜色，不写模糊“已完成” |
| FilterChip | 短标签 | 横向可滚动，不形成多行按钮墙 |
| SkillCard | 名称、摘要、最少状态信号 | 一张卡只表达一个 Skill |
| EvidenceSection | 编号、标题、解释、内容 | 结构顺序固定，内容按证据决定 |
| InspectorBlock | 标题、说明、局部表单 | 只编辑当前对象 |
| Notice | 中性底色、边框、解释 | 用于边界，不代替错误 |
| InlineConfirm | 影响说明、确认、取消 | 优先于 WebView 原生 `window.confirm` |
| ReviewSummary | 待回看、人工结果、版本变化计数 | 只做入口；详情继续区分真实与候选 |
| ContinuationCard | 原收据时间、候选步骤、用户记录、人工判断 | 确定性整理；不调用模型、不自动执行 |
| LocalDataTools | 创建备份、备份历史、打开位置、恢复、清空、结果状态 | 低频折叠；清空前必须形成可验证的安全备份 |
| LearningGuide | 一句产品价值、七步使用路径、合并后的开始与证据边界 | 仅在“我的 Skill”未选择条目时显示；不使用示例收据，不重复摘要路径 |
| EmptyState | 准确原因、可选单一动作 | 区分无数据、无匹配、不可读取 |

## 8. 交互规则

### 8.1 主次动作

每个视图必须回答：我在看什么、当前状态是什么、下一步能做什么。

- 页面主动作：刷新、切换入口或当前任务的唯一主操作。
- 对象动作：放在详情或 Inspector 内，与对象相邻。
- 危险动作：放在局部区块底部，使用页面内二次确认。
- 低频说明与历史：按需展开，不占据首屏主层级。

### 8.2 渐进披露

- 列表负责选择，详情负责完整阅读。
- 默认展示结论、状态和下一步；证据、事件和历史按需展开。
- 展开内容必须占完整可读宽度，不塞在多列中的单个窄列。
- 多条记录不得为了整洁而静默聚合或丢失。

### 8.3 保存、清除与错误

- 点击、发起请求或触发浏览器下载不等于完成；成功态必须来自 Host 已提交并可回读的结果。
- 保存后在原位显示成功结果，Toast 不能作为唯一反馈。
- Busy 时禁用重复提交并保持按钮宽度稳定。
- 清除必须说明将删除什么、保留什么，并提供确认与取消。
- 全量清空需要说明影响数量、最近安全备份、DSH 原始会话不受影响、当前运行会话的加载证据可能重建。
- 本地备份由明确动作触发；成功后展示文件名、时间、数量与打开位置，不得用“已下载”“已同步”或云图标代替可验证回执。
- 删除用户主动填写的数据前必须先完成安全备份或提供等价的可验证撤销路径；备份失败时禁止继续删除。
- 恢复必须先预览影响。若同一会话不存在，恢复整张收据；若活动会话已重建加载证据，只补回其缺失的个人理解、人工结果、输出引用和继续方式，不覆盖当前已存在的同类用户记录。
- 恢复与活动会话写入必须走同一 Session 串行队列；界面分别报告“完整恢复、补回个人记录、保留现有记录”，不得把冲突跳过伪装成恢复成功。
- 全量清空在安全备份与删除期间必须建立维护屏障：既有写入先完成，新写入等待清空结束；单张删除的读取、备份和删除属于同一 Session 串行操作。
- 表单草稿必须区分未保存、保存中、已保存和失败；切换对象或页面不得静默丢失未保存内容。
- 未保存草稿只可在当前 Desktop 运行期间做有界本地暂存，并明确提示“尚未进入收据与备份”；恢复草稿前必须确认它仍基于同一已保存版本，避免旧草稿覆盖新记录。
- 错误必须写清发生什么以及用户如何恢复。
- UI 不显示本地绝对路径、凭据、内部堆栈或完整 Skill 正文。

## 9. 证据表达规则

Skill Trace 的视觉系统必须服从证据强度：

| 事实强度 | UI 表达 |
|---|---|
| 系统观察到加载成功 | `success` + “已加载” |
| 系统观察到失败 | `error` + “加载失败” |
| 结果未知或记录待定 | `warning` + 明确原因 |
| 来源身份完整一致 | “已确认同源” |
| 内容相符但身份不足 | “内容相符候选” |
| 用户写下理解或结果 | “个人理解 / 人工结果”，不写系统结论 |
| 用户关联输出 | “人工关联”，不画成因果 |

禁止：

- 把“加载”写成“采用、遵循、有效”；
- 把人工验证结果写成 Skill 普遍质量评分；
- 把候选历史混入真实收据计数；
- 自动生成“当前正确理解”；
- 通过更醒目的颜色把推断提升为事实。

## 10. 页面状态

### Loading

- 保留页面上下文或显示单行轻量状态。
- 使用 6–7px 状态点轻量呼吸；`aria-live="polite"`。
- `prefers-reduced-motion: reduce` 时停止持续动画。

### Empty

必须区分：

- 当前会话没有可追踪 Skill；
- 当前作用域没有可发现 Skill；
- 搜索或筛选无匹配；
- Registry / 目录不可确认；
- 尚未选择 Skill。

不得统一写成“暂无数据”。

### Error

- 使用 `role="alert"`；
- 提供重试、返回或检查来源等恢复动作；
- 以边框和文字色表达，不使用大面积高饱和红底。

### Ready

- 当前选择必须同时有结构、文字或边框反馈。
- 局部数据更新不把用户踢回列表顶端。
- 不自动打开危险操作或替用户做人工判断。

## 11. 响应式与可访问性

| 宽度 | 行为 |
|---:|---|
| `>1050px` | 主区 + 290px Inspector；列表 + 详情 |
| `1000–1050px` | Inspector 可缩至约 250px；密集栅格减列 |
| `<1000px` | 当前会话改为上下布局；目录改为列表→详情 |
| `<460px` | 控件最小 44px；编辑控件 16px；表单单列 |

无障碍要求：

- 所有按钮、筛选、列表项、节点和展开控件可键盘访问。
- `:focus-visible` 使用 2px 品牌色外框和 2px 偏移。
- 选中使用 `aria-pressed` 或 `aria-current`。
- Loading 容器使用 `aria-busy`；错误使用 `role="alert"`。
- 对象名可在列表省略，但详情必须展示完整内容。
- 用户输入与路径使用 `overflow-wrap:anywhere`。
- 不得移除 outline 后不补焦点样式。

## 12. 图标、语言与主题

### 图标

- 24×24 ViewBox 的线性图标，约 1.8 描边，圆角端点。
- 常用尺寸 14 / 16 / 18px；图标按钮 32×32px。
- 关键动作必须带文字；不使用 emoji 代替正式图标。
- 刷新、删除等图标必须检查 ViewBox，避免边缘裁切。

### 语言

- 通过 DSH `ctx.locale` 注册 `zh / en` 字典并订阅 revision。
- 宿主运行中切换语言后，当前 Tab 原位刷新。
- 未知 locale 回退英文。
- 只翻译插件自有 UI；Skill 名称、声明、工作区名、输出引用和用户输入保持原文。

### 主题

- 颜色来自宿主语义 Token，不为浅色或深色复制两套硬编码颜色。
- 内容对比、边框层级和状态文字在浅色、深色、跟随系统下都必须可读。

## 13. 设计变更 Gate

新增或修改 UI 前：

1. 明确用户任务、业务状态和证据来源；
2. 判断是全局稳定规则、跨页面模式还是单页表达；
3. 优先复用现有 Token 和组件合同；
4. 检查 loading / empty / error / ready 与窄窗影响；
5. 确认不会把候选、人工记录或静态演示写成系统事实。

完成后：

1. Desktop 宽屏检查主内容居中与信息层级；
2. DSH 窄窗检查重排、滚动与返回路径；
3. 检查中文、英文和运行时切换；
4. 检查键盘焦点、禁用、Busy、错误和确认状态；
5. 对照收据事实确认两个视图没有生成第二套语义；
6. 在 README 当前状态与本轮交付说明中记录验证范围和未验证项。

只有经过两个页面或两个真实状态稳定复用的规则，才提升到本文；一次性页面值留在局部样式中。

## 14. 验收标准

| 场景 | 标准 |
|---|---|
| 宽屏 | 主内容居中；右栏不无限扩展；地图舞台不贴左 |
| DSH 窄窗 | 双栏不挤压；列表→详情有返回；表单可操作 |
| 中文 / 英文 | 无插件文案遗漏；切换后原位刷新；用户内容不翻译 |
| Loading | 有上下文、有轻量反馈、无阻塞性装饰动画 |
| Empty | 原因准确，不用历史或演示内容冒充当前数据 |
| Error | 原因与恢复动作明确，不泄露敏感内容 |
| 状态 | 文字、结构和颜色共同表达；候选与真实分离 |
| 表单 | 保存、Busy、错误、成功、清除和确认完整 |
| 本地数据 | Host 落盘并回读后才显示成功；可打开位置；备份可预览恢复；清空前安全备份；偏好与 DSH 对话不受影响 |
| 键盘 | 主流程可完成，焦点可见，图标按钮有名称 |
| 长文本 | 不撑破布局；列表可省略，详情可读完整内容 |
| 减少动效 | reduced motion 下无持续动画 |

## 15. 跨插件复用边界

其他 DSH 插件可以复用本文的宿主 Token、密度、页面壳层、列表/详情、Inspector、状态、表单和响应式原则，但不得复制 Skill Trace 的业务语言、收据结构、证据等级或固定地图关系。

创作配方台可复用：

- 安静、紧凑、任务导向的宿主内工作台外壳；
- 中性工具表面 + 内容素材承担视觉丰富度；
- 候选 / 待确认 / 正式 / 冲突的准确状态表达；
- 页面内二次确认、列表→详情与主区→Inspector 模式。

创作配方台必须自行定义配方、角色、家族资产、候选与正式写入 Gate。共享设计系统不等于共享页面布局或业务状态机。

## 16. 当前实现与证据

- 实现入口：`src/dsh/client/client.js`；
- 产品语义与版本边界：`README.md`；
- 技术合同：`docs/ARCHITECTURE.md`；
- 隐私与本地数据边界：`docs/PRIVACY.md`；
- 版本变化：`CHANGELOG.md`。

本文描述当前设计合同，不代表所有状态已完成系统级无障碍、真实小屏或全部主题验收。实际验证范围以 README 当前状态和每轮交付说明为准。