插件设计资源库 Physicolor/dsh-design-resources

description: "DeepSeek Harness 插件生态的设计规范、座位目录、官方 token、图标集与可复用源码知识库。"

DeepSeek Design Resources

让社区的插件看起来像同一个产品。
规范 · 座位目录 · 设计令牌 · 官方图标集 · 可复用源码 · 实况组件画廊

这个仓库解决什么问题

DeepSeek Harness 公开了 Cordis 插件接口、slot 机制、语义令牌、UI primitives 和客户端开发指引。相关规则分布在 GitHub 文档、Agent 指引与源码中，目前没有一份按社区插件作者的界面任务组织的完整设计手册。

结果是社区插件各写各的，同一个界面里按钮高矮不一、间距忽大忽小、层级顺序不可预测。这不是某个插件的错，是缺少规范与检查的必然结果。

本仓库把这些依据整理成插件作者可查阅、可复现的参考。三条原则：

1. 不发明数值。 每一条尺寸、间距、时长都标注来源（官方客户端包 / Apple HIG / OpenHarmony / 本仓库建议）。没有权威依据的地方会明确写出来，而不是编一个看起来专业的数字。
2. 不用主观偏好代替评估。 视觉质量按信息层级、阅读宽度、密度、对齐、主题对比和交互反馈等可检查标准评估。
3. 可判定的才是规范。 「间距要舒适」不是规范；「相邻独立控件垂直间距 < 16px 判过挤」才是。每篇文档都会写明该判据能否自动检测。

仓库结构

| 目录 | 内容 |
| spec/ | 10 篇规范文档：主页面骨架、座位选择、控件、令牌、动效、图标、可访问性、自检清单、冲突裁决 |
| rules/ | rules.json / rules.csv——自检清单的机器可读形式，供 CI 与审计器消费 |
| guides/ | 面向插件任务的指南：指南概览、官方依据、设计原则、界面模式、座位与集成、验证与来源 |
| data/ | 从运行中的 Harness 采集的数据：75 个图标、90 个座位、令牌（色板 77 / 浅色别名 115 / 深色别名 119 / 尺度与排版 207）、元素清单。口径与采集时间见 docs/FACTS-2026-10-02.md |
| icons/ | 75 个官方图标 + 品牌标识，SVG 原样导出（来源见 icons/README.md） |
| components/ | 可复用源码知识库：分类归档、零依赖、只用官方令牌的 React 实现 |
| website/ | 插件设计指南与实况组件画廊：导航、正文和页内目录分栏呈现，支持检索 |
| scripts/ | 采集与生成脚本——所有数据都可重新生成，不依赖手工记录 |

打开网站

网站是零构建、file:// 可直接打开的静态站，也已经发布在 GitHub Pages 上：

https://physicolor.github.io/dsh-design-resources/
website/index.html # 同一份文件，本地打开

或起一个本地服务器（无缓存，编辑后刷新即见）：

node scripts/serve.mjs # → http://127.0.0.1:4173/

网站里每个组件都用原生 HTML 实况渲染（不是设计稿截图），因为它本来就是 WebUI 技术栈做出来的。左侧是 pages 索引，中间是组件实况，右侧是「为什么这么设计 / 什么时候用 / 几何来源」。

站点本身也按这份规范做，因此它不只是一份说明书，还是规范的第一个实现：

- 规范里嵌的是能跑的演示，不是截图：三列分区（hover 高亮每一栏）、输入区纵向结构、右栏开合对比、官方图标几何标注（画板 / 安全区 / 外接轮廓 / 描边）、应用图标量板（容器 50 × 50、本体 36 × 36、墨迹外接圆现测）、控件量板（9 格读数 + 五态 + 三个反例）、令牌量板（六档圆角 / 四层高程 / 八个字号 / 浅深两次解色）、可访问性量板（对比度按 WCAG 公式现算、命中区现量）、自检清单（可点、必选缺一条即判不得提交）、冲突裁决板（真实占用登记 + 换个注册时序看顺序变）、规则与来源对照板——全是原生 HTML，可 hover、可点、可复制。每篇规范都必须带一个能跑的演示，这条由 build 判定（every spec carries an operable demo + 逐页探针），插了空壳也算不合格；
- 规范里嵌的是产品界面的复刻，不是示意图：三列分区、输入区纵向结构、右栏开合，用的是同一套 website/shell/ 实例——几何逐条取自 docs/reference/（脚本从运行中的产品采出来的真实盒子与计算样式：框架 geometry.json、输入区 composer-geometry.json、会话区 conversation-geometry.json、顶栏 top-strip.json、卡下 dock status-line.json），可以在窗口里面直接拖、直接点；
- 演示是活的，所以在真实浏览器里逐个点一遍：npm run audit 打开每一条路由，点开每个演示里的每个控件（会钻进产品复刻那层 shadow root），检查四件事——有没有元素盖住整个窗口、有没有元素逃出演示框、演示框有没有被撑高、点一下有没有把某一栏滚走。这一条是从两次真实事故里长出来的：对话框演示的 position: fixed 遮罩盖住了整站，输入区选择器点一下把中栏滚走约 950px（看着就是「整个窗口变白」）。根因是 shadow root 本身不是包含块，现在由演示容器的 position: relative + contain: layout 兜住，verify 里也钉了一条不变量；
- 复现的规矩是先截图、再量几何、才动手：docs/reference/ 存着产品的真实截图，任何界面都必须能对着它解释"为什么长这样"，找不到出处的宁可不画；
- 组件分「官方」与「本仓库补充」两类并显著标注：26 个组件里 3 个官方并没有对应物（键值列表、迷你进度条、面板座位），它们是本仓库给插件作者的实现建议，页面会明说产品里没有这个界面；其余 23 个都能追到产品自有 CSS 模块或官方 primitives 里的实现。分错了的会被 build 判出来——components/origins.json 里每个 id 必须归到一类，proposed 必须写明它服务的真实场景；
- 左栏是可折叠的树：分组是小标题而不是开关（点了会藏内容的标题，省的是高度、丢的是「这里面有什么」这个答案），只有组件分类可折叠——整行就是那个开关，收起时和周围的叶子行一样（只有字和箭头，没有框），展开时才亮起同一枚胶囊（分类页从「全部组件」的「查看全部 N」进）；当前所在的那一行再加粗，两件事分开表达；
- 预览没有外框：实况内容直接铺在页面上，不再套「框里的框」；
- 三栏各自滚动，页面本身不滚动；顶栏是液态玻璃，内容从下方穿过；
- 左右栏可拖动调宽（键盘方向键也行），宽度与开关状态会被记住；
- 左右栏都可以整栏收起，带展开/收起动画；
- 中英双语，两边都是完整的：规范正文、指南、组件说明与示意页都有英文版；英文页面上出现的每一条中文都是被引用的产品实景串，后面紧跟英文释义。约定与门禁见 docs/I18N.md；
- 浅色与深色两套都是作者手写的——在浅色下看着还行、在深色下崩掉的设计，在这里算缺陷；
- 可操作的动效试验台：动效规范页里能直接比较 100/150/200/300/350ms 五档与两条曲线，这是纸面文档做不到、HTML 电子说明书能做到的事；
- 预览用 Shadow DOM 渲染，不用 iframe：file:// 下每个文档都是独立安全源，父页读不到 iframe 的高度也无法测量内容，预览会静默退化；shadow root 既隔离 demo 的样式，又因为参与正常布局而不需要测量；
- tooltip 是自绘的：不用浏览器原生气泡，用 DSH 官方的 tooltip 几何（padding 3/7、radius 8、13px/20）；
- 面包屑 + 本页目录：任何下钻页面都能一键返回上一级，右栏给出可点击跳转的文档目录；只有真有辅助内容的页面才展开右栏，只有元数据的页面会自动收起。

重新生成数据

所有数据都来自本机运行中的 Harness，可随时重采：

node scripts/collect-icons.mjs # 官方图标集 → icons/ + data/icons.json
node scripts/collect-tokens.mjs # 官方主题令牌 → data/tokens.json + website/css/dsh-tokens.css
node scripts/collect-slots.mjs # 座位目录（需 data/raw/ 下的快照）→ data/slots.json
node scripts/gen-rules.mjs # 自检清单 → rules/rules.json
node scripts/check-i18n.mjs # 缺译或译文过期即失败（--update 重新钉住）
node scripts/check-demos-i18n.mjs # 示意页还有未译文案即失败
node website/gen-site.mjs # 汇总 → website/js/data.js
node scripts/gen-index.mjs # 清单 → index.json（包的入口文件）
node scripts/check-refs.mjs # 文档提到不存在的座位即失败
node website/verify.mjs # 自检：结构 + 数据 + 真实浏览器渲染 + 截图
npm run build # 上面全部，按这个顺序

采集脚本读取本机的 DSH 安装（DSH_ASAR / DSH_PRIMITIVES 可覆盖路径）。collect-tokens.mjs 需要桌面版 app.asar；collect-slots.mjs 需要一份座位树快照（由 Harness 的座位检查接口产出，快照文件放在 data/raw/）。

这一套：规范 + 运行时

两个仓库是一条线上的两半，装在一起才算完整：一个说「应该长什么样」，一个在真实运行的产品里把它落实、并把做不到的地方报出来。

| 仓库 | 角色 | 回答的问题 |
| dsh-design-resources（本仓库） | 规范、资源、可复用源码、站点 | 界面应该怎么做：控件多大、间距多少、动效多长、图标怎么画 |
| dsh-ui-harmonizer | 装进产品的运行时插件 | 实际做得怎么样：只读兼容性审计，问题在设置页里列出来 |

- 站点：physicolor.github.io/dsh-design-resources
- 运行时：github.com/Physicolor/dsh-ui-harmonizer

规范不强制任何人改代码；它让冲突可见、可解释、可一键出 issue。

来源与许可边界

本仓库的代码与文档（spec/、components/、website/、scripts/、rules/）为原创，MIT 许可。

icons/ 与 data/tokens.json 的内容提取自 DeepSeek 官方客户端包（@deepseek-ai/dsh-client-ui-primitives、桌面版主题定义），版权归 DeepSeek。它们在这里以参考与互操作的目的收录，逐条标注了来源，未做任何改写。使用前请自行确认官方许可条款；本仓库的 MIT 许可不覆盖这部分内容。详见 icons/README.md。

spec/ 中移植自外部规范的部分（Apple Human Interface Guidelines、OpenHarmony 设计文档）均在条文内标注了出处。

效力层级

规范条目分三档，每条都带稳定 ID（如 FL-MF-01、CT-RC-14）：

- MF 强制——必须遵守，偏离即不合规；
- RC 推荐——偏离需在 README 写明理由；
- AD 建议——取舍由作者判断。

自检清单（spec/70-checklist.md）把其中 64 条整理成二元判定项，并标注每一条能否自动检测：36 条可自动检测、19 条半自动、9 条需人审。