dsh-fuse

dsh-fuse

页面级 UI 渲染插件：自然语言描述 → 结构化规格围栏 → 真实页面 UI，并带像素级走查闭环。

简体中文 · English

v1.2.1 · MIT License · DSH ≥ 0.1.1-rc.2（已适配 0.1.2-rc.1）· Node ^22.19.0 || >=24.0.0

dsh-fuse 是 DeepSeek Harness（DSH）插件，也是 ui-aesthetics 技能的插件化升级版：把审美规范数值化为设计令牌（theme.json）、把代码规约沉淀为 code-style.json，让生成的页面级 UI 从构造上就正确，并通过闭环走查器把细节微调到像素级。

是什么

模型获得「UI 设计 + 代码规范」一体化能力，三步走：

1. 生成 —— 模型用自然语言描述页面，在回答正文中输出 dsh-fuse 围栏（结构化 JSON 规格）；输出前经 validate_fuse_spec 预检，坏规格先被拦截。
2. 渲染 —— 浏览器端把规格渲染成真实页面 UI，内联呈现在对话流中；宽度与输入框对齐（居中、748px 上限），全屏也不撑满。
3. 微调 —— 点击预览内任意元素，采集 getComputedStyle + 渲染状态，按 expected → observed → diff → fix 闭环修正后重新输出完整围栏；环形缓冲保留最近 10 次快照可供撤销。

设计哲学：规则是骨架，语义是血肉，情绪是呼吸。每份规格通过 theme（default / apple / dark）显式决定情绪基调，拒绝占位壳，间距一律落在 4/8px 栅格上。

功能特性

特性	说明
一键生成	自然语言描述 → Agent 输出 dsh-fuse 围栏 → 渲染出真实页面 UI
内联预览	渲染于 DSH 对话流内；748px 居中，与输入框（composer）同宽，全屏不撑满
像素级走查	点击预览元素 → 采集 getComputedStyle + 渲染状态 → [fuse-inspect] 回传模型
渲染状态回传	viewport / overflow / clipped / primaryButtonCount —— Spec valid ≠ Render correct
修正闭环	expected（规格意图）→ observed（实际渲染）→ diff（定位差异）→ fix（重输出完整围栏）
撤销 / 历史	环形缓冲保留最近 10 次快照；预览卡右上角 ↩️ 回退
设计令牌	theme.json：default / apple / dark 三套主题，CSS 变量映射，新风格即插即用
设计原则	骨架 → 血肉 → 呼吸；适配四问（产品/受众/任务/媒介）结论写入根节点 context
代码规范	生成配套代码必守 code-style.json（命名 / 格式化 / 语法 / CSS）
双通道渲染	宿主提供 registerFenceRenderer 扩展点时直挂；原版 DSH 回退 DOM 通道
深色模式	插件壳跟随 DSH 主题：双通道探测（body[data-ds-dark-theme] / prefers-color-scheme + MutationObserver）

安装

从 GitHub 安装（推荐）

# 需要已安装 git；--profile web 换成你的 profile 名
dsh plugin --profile web add github:KLRSL/dsh-fuse

本地 bundle（开发 / link）

# 在项目目录下执行
dsh plugin --profile web add link:./dsh-fuse

dsh plugin 会自动把安装的包登记到 profile 的 dsh.profile.bundles 并挂载补丁；安装完成后重启 DSH（HTML 客户端注入在启动时生效）。

安装后验证

1. 宿主半区 —— 启动日志出现 [dsh-fuse] 启动完成：系统指令 + validate_fuse_spec + /api/fuse/config；系统提示词包含 Fuse 段（name: fuse，order: 106）；tools 服务可用时 validate_fuse_spec 工具注册成功。
2. 浏览器半区 —— 控制台报告所用通道：
   • [dsh-fuse] fence-registry 通道已挂载（注册表通道，契约宿主）
   • [dsh-fuse] fence-registry 扩展点不存在（原版 DSH）——启用 DOM 渲染通道（DOM 通道）
3. 配置 API —— GET http://localhost:<端口>/api/fuse/config 返回 { themes, codeStyle, pageKinds, componentTypes }。

然后让模型「做一个登录页」——对话流中应直接出现渲染好的 dsh-fuse 预览卡。

安全说明： 围栏走「白名单校验 → 渲染」管道。未知组件 type 整体拒绝渲染；节点预算：宿主侧 60 节点 / 8 层深，渲染器侧 200 节点 / 8 层深。

快速开始

模型在回答正文中输出 dsh-fuse 围栏：

```dsh-fuse
{
  "type": "login_form",
  "title": "欢迎回来",
  "subtitle": "登录你的账户继续",
  "theme": "default",
  "context": { "product": "网页", "audience": "个人用户", "task": "快速登录进入工作台" },
  "components": [
    { "type": "input", "label": "用户名", "placeholder": "请输入用户名" },
    { "type": "input", "label": "密码", "placeholder": "请输入密码", "inputType": "password" },
    { "type": "row", "items": [
      { "type": "checkbox", "label": "记住我" },
      { "type": "link", "label": "忘记密码？" }
    ]},
    { "type": "button", "text": "登 录", "style": "primary", "full": true, "action": "login" }
  ]
}
```

接下来会发生什么：

• 预检 —— validate_fuse_spec 按白名单校验（页面类型 / 组件词汇 / 容器规则 / 预算），坏规格在渲染前被拒绝。
• 渲染 —— 浏览器端从 /api/fuse/config 拉取设计令牌，把所选 theme 映射为 CSS 变量，渲染实时预览卡；卡片 748px 居中，与输入框同宽。
• 交互 —— 点击带 "action": "login" 的「登 录」按钮，回传 [fuse-action] login，对话继续推进流程（模拟登录 / 展示错误 / 跳转等）。
• 禁用态 —— 不带 action 的按钮渲染为禁用态。

页面级 vs 卡片级： dsh-fuse 管页面级 UI（登录页/仪表盘/设置页/表格页/落地页/个人卡片/弹窗/表单），对话内小卡片仍用 dsh-ui。完整语法以 SKILL.md 为准。

围栏规范

根结构

{
  "type": "<页面类型>",
  "title": "<页面标题>",
  "theme": "default",
  "context": { ... },
  "actions": [ ... ],
  "components": [ ... ]
}

页面类型（根 type，必须取其一）

类型	适用场景
login_form	登录页
signup_form	注册页
dashboard	控制台 / 数据总览
settings_page	设置页
table_page	数据表格页
landing_page	营销落地页
profile_card	个人资料卡
pricing_page	定价 / 套餐对比
modal	弹窗 / 浮层
form	通用表单页

组件词汇（白名单）

未知 type 整体拒绝渲染。

类别	类型
容器	page card grid row col section tabs hero nav header footer form
展示	text badge stat list table divider avatar chart steps
表单	input select textarea checkbox radio button link

字段细节（以 SKILL.md 为准）：grid 带 cols；tabs 带 items（label + content）；hero 带 title/subtitle/actions；nav 带 items；header 带 title/subtitle；footer 带 text；text 带 size（h1/h2/h3/body/caption/muted）、content、center；badge 带 label + tone（success/warn/danger/accent）；stat 带 label+value；list 的 items 为字符串或 {title,desc}；table 带 columns+rows；avatar 带 name/color；chart 带 kind（bars/donut/line）+ data [{label,value,color}]；steps 带 current + steps [{title,desc}]；input 带 label/placeholder/inputType/action；select 带 label/options/selected/action；textarea 带 label/placeholder/action；checkbox/radio 带 label/checked/action；button 带 text/style（primary/secondary/ghost/danger）/full/small/action；link 带 label/href。容器组件（page/card/grid/row/col/section/form）用 items 或 components 放子节点。

根节点字段

字段	必填	含义
type	是	页面类型，从上表取其一
components	是	非空白名单组件数组（≤ 60 节点，深度 ≤ 8）
theme	是	theme.json 中的主题名——不许输出白板规格
title	否	页面 / 卡片标题
context	否（推荐）	适配四问的结论：{ product, audience, task }——渲染器不消费，但 Agent 自省与走查 diff 会用到
actions	否	页面主操作：[{ "action": "name", "label": "…", "tone": "primary|ghost" }]

交互动作回传

• 交互组件（button / input / select / checkbox / radio）带 "action": "name" 时，点击回传 [fuse-action] name。
• 不带 action 的组件渲染为禁用态。
• 表单类页面：input / select / textarea 用 label 字段标注；主操作为 style="primary"——每页只有一个主操作按钮。

设计语言

骨架 → 血肉 → 呼吸（顺序铁律）

1. 骨架（规则） —— 信息架构与布局先行：页面类型、模块分区、层级关系清晰可循、逻辑自洽。
2. 血肉（语义） —— 内容与交互详实：每块都有真实的文字、真实的数据、真实的按钮，绝不做占位壳。
3. 呼吸（情绪） —— 克制：留白间距、微动画、低饱和柔色调。情绪靠克制而非堆砌。

顺序不许倒：先骨架、再血肉、后呼吸；不许先选一堆颜色再想结构。

适配四问（写规格前先回答）

1. 产品是什么 —— 网页 / APP / 车载 HMI / 智能穿戴 / 数据大屏 / 3D 空间界面……
2. 给谁用 —— 目标受众、使用场景与阅读环境。
3. 核心任务 —— 用户进来要完成什么，每屏只服务一个焦点。
4. 媒介约束 —— 响应式断点 / 触控目标尺寸 / 视觉距离 / 亮度与对比度。

按答案选择 theme、调整密度与层级，再写围栏规格；结论写入 context 字段。

设计令牌（config/theme.json）

主题	特征	适用
default（默认）	白底、主色 #2563EB、圆角 8/12/16	通用工具类页面
apple	#F5F5F7 浅灰底、大圆角 10/14/18、SF 字体感	消费类页面
dark	#0F1115 底、青/紫强调、发光感	数据大屏、开发者工具

• 配色只从令牌取：主色 colors.primary、强调色 colors.accent、中性色 neutralBg/Surface/Text/Muted、边框 border；反馈色 success #2E7D32 / warning #ED6C02 / error #C62828（克制饱和度）。
• 间距栅格 4/8/16/24/32；圆角 8/12/16（default 与 dark）；字号阶梯 12/14/16/20/28/36/48；行高正文 1.7 / 标题 1.25。
• brand 段为插件品牌色单一事实来源（fuse = 蓝紫）。

风格扩展（主题是风格基调，不是新体系）

新风格（可爱风 / 杂志风…）= 在 theme.json 里新增主题：复用 4/8px 栅格与字号阶梯，配色仍守「≤ 3 色 + 中性色」，只改主色 / 圆角 / 阴影——不推翻骨架与呼吸规则，渲染器动态生效，无需改代码。

壳与产物解耦： 插件自身 UI（预览卡、工具栏、设置页）跟随 DSH 主题（--fs-shell-* 令牌，经 --dsw-alias-* / data-ds-dark-theme 探测）；渲染产物跟随围栏的 theme（--fs-* 令牌，作用域在卡片根）。

走查微调

Spec valid ≠ Render correct。 validate_fuse_spec 通过只代表规格合法；渲染结果仍可能溢出、裁切、主按钮重复或层级不符预期。

走查交互流程

1. 用户点击预览内元素——选中即高亮（黄 = 选中 → 蓝 = 采集中 → 紫 = 修正中 → 红 = 失败）。
2. 模型收到 [fuse-inspect]，附：
   • 该元素的 getComputedStyle 样式数据；
   • 渲染状态：viewport（预览容器尺寸）/ overflow（是否溢出）/ clipped（元素是否被裁切）/ primaryButtonCount（主操作按钮数）。

修正闭环（expected → observed → diff → fix）

1. expected —— 回看自己规格的意图：该元素应有的尺寸 / 间距 / 层级 / 字数；
2. observed —— 读样式数据与渲染状态；
3. diff —— 定位差异：间距 / 圆角 / 配色 / 字号 / 溢出 / 主按钮重复；
4. fix —— 输出修正后的完整 dsh-fuse 围栏重新渲染，不要解释过程。

预览卡右上角提供 ↩️ 撤销（最近 10 次快照）与 🔄 手动刷新。

技术架构

dsh-fuse/
├── index.mjs               # 宿主半区：系统指令注册 + validate_fuse_spec 工具 + /api/fuse/config
├── client.js               # 浏览器半区：围栏渲染器 + 走查器 + 撤销历史 + 设置页
├── config/
│   ├── theme.json          # 设计令牌：配色 ≤ 3 色 / 4-8px 栅格 / 字号阶梯 / 圆角；品牌色
│   └── code-style.json     # 代码规范：命名 / 格式化 / 语法 / 结构 / React / CSS
├── cordis.patch.yml        # DSH cordis 宿主 bundle 补丁
├── SKILL.md                # Fuse 技能：完整围栏语法 + 审美规范 + 自审清单
├── tests/                  # node --test 单元测试、apply 冒烟、jsdom 客户端闭环、设置页渲染
├── README.md               # 本文件（简体中文）
└── README.en.md            # English

宿主半区（index.mjs） —— 注册系统指令段（name: fuse，order: 106，位于 bash=104 与 genui=105 之间），向每次请求注入围栏语言规范、紧凑主题摘要与代码规范摘要；暴露 validate_fuse_spec 预检工具；提供 GET /api/fuse/config（themes / codeStyle / pageKinds / componentTypes）供浏览器端拉取完整令牌。

浏览器半区（client.js） —— 零依赖纯 DOM 渲染器（经 __ModuleLoader__ 加载），内置 installShellThemeSync() 做 DSH 主题跟随，以及走查器与撤销机制。

双通道渲染 —— 两侧各自探测宿主：

• 注册表通道： 宿主提供 registerFenceRenderer('dsh-fuse', …)（DSH 0.1.2-rc.1 契约）时直挂；
• DOM 通道： 原版 DSH 无扩展点 → MutationObserver 扫描对话流中标 dsh-fuse 的代码块（pre、.md-code-block、[data-lang]）接管渲染（带双重渲染守卫，容器与内嵌 <pre> 只接管一次）。

宽度契约 —— 渲染卡片 max-width: 748px（取自 --dsh-chat-content-width）居中，与输入框对齐，全屏也不撑满。

开发

# 宿主单元测试（校验器 / 系统指令段 / 配置加载）
node --test tests/fuse.test.mjs

# apply() 注册冒烟
node tests/apply-smoke.mjs

# jsdom 客户端闭环（fence ⇒ DOM ⇒ 走查）
node tests/test-client.mjs

# 设置页渲染
node tests/test-settings.mjs

需要 Node ^22.19.0 || >=24.0.0（见 engines）。开发依赖：jsdom、react、react-dom。

如何贡献

1. 白名单保持同步 —— index.mjs（FUSE_COMPONENT_TYPES、FUSE_PAGE_KINDS）与 client.js（CONTAINER_TYPES、DISPLAY_TYPES、FORM_TYPES、PAGE_KINDS）必须一致。
2. 新主题只加进 config/theme.json，不改渲染器代码。
3. 行为变更必须保持 --fs-shell-*（跟随 DSH 主题）与 --fs-*（跟随围栏主题）两套令牌分离。
4. 提交前跑完整测试矩阵；类名尽量保持稳定。

版本历史

版本	日期	要点
v1.2.1	2026-09-05	适配 DSH 0.1.2-rc.1 前端：registerFenceRenderer 契约探测（宿主提供扩展点时直挂，缺失时回退 DOM 通道）+ 插件 UI 深色适配（DSH 主题跟随，双通道探测 + MutationObserver）；品牌色（蓝紫 · 设计渲染）写入 theme.json 的 brand 段作单一事实来源
v1.2.0	2026-09-05	插件自身管理 UI 按「骨架/血肉/呼吸」重构：预览卡壳、工具栏、设置页全部令牌驱动（--fs-* 变量取自 theme.json），清除 dsw-alias 硬依赖；修复 React key 警告；类名零变更，测试全绿
v1.1.0	2026-09-05	融合「规则是骨架，语义是血肉，情绪是呼吸」+ 通用 UI/UX Prompt Framework：适配四问、根节点 context 字段（validator 校验形态）、风格扩展指南（theme.json 新增主题零改代码）；走查闭环强化——渲染器回传渲染状态，系统指令引导 expected→observed→diff→fix
v1.0.2	2026-09-03	修复 DOM 通道双重渲染回归（代码块容器与内嵌 <pre> 都被接管 → 同一内容渲染两遍）；元数据与 README 全量对齐；peerDeps 放宽至 >=0.1.1-rc.2
v1.0.1	2026-08-28	渲染器适配 DSH 0.1.1-rc.2 前端；渲染容器宽度与输入框对齐（748px 居中，全屏不撑满）
v1.0.0	—	初版：ui-aesthetics 技能升级版（设计令牌 + 代码规范 + 围栏渲染 + 走查器 + 撤销历史）

鸣谢

本项目在设计与实现过程中，研究并借鉴了以下开源项目的数据结构、交互逻辑与设计数值（不涉及核心源码的复制）：

• OpenPencil — 设计令牌体系（theme.json 的 colors / spacing / typography / radius 结构）
• dsh-annotate / dsh-web-review — 样式走查与反馈回路
• Airbnb / Google / Alibaba 编码规范 — 代码规范（code-style.json）

License

MIT