dsh-design

把设计 brief 或已有代码变成经过验证的 Web/UI 文件。

dsh-design 是面向开发者的 DeepSeek Harness 设计 Agent Bundle。它把设计方向、真实文件实现、渲染评审、修改和 hash 绑定交付放进同一个有界循环。它组合 DSH 的 Skill、Tool、Artifact、preset 和独立的 dsh-vision-toolkit。所有工作都发生在 DSH workspace 内。

English | 中文

为什么需要 dsh-design

Coding Agent 可以写 HTML 和 CSS。无约束的“做得更好看”循环没有稳定完成标准：它可能偏离 brief，也可能在没有记录源码、render、viewport 和对比证据时声称视觉质量达标。

dsh-design 让这个循环变得明确。Agent 解析一个权威设计系统包，把 usage、token、组件索引和 Craft 参考组合成有大小上限的上下文，修改 workspace 中的真实文件，并执行确定性结构检查。只有证据能够改变下一次修改时才会请求视觉证据；测量结果最好的候选版本被保留，交付 manifest 可供其他人或 Agent 复核。

它补充了什么

• 交付真实 artifact。brief 变成 workspace 内的 HTML/CSS/JavaScript 文件。
• 用测量证据完成 Recreate。在声明的 viewport 对比参考图与实现 render，并保留测量结果最好的源码。
• Refine 时保留声明的约束。内容、行为、框架、路由、组件 API 和品牌约束保持不变，同时修复实质问题。
• 组合可移植上下文。rich 设计系统包和有序 Craft 参考在实现前生成一个有大小上限的 digest。
• 评审不冒充验证。最多三轮 design_review 可以保留确定性 finding 和声明的观察，但评分不能授予 verified。
• 限制视觉迭代预算。首次 render 后，每个 viewport 最多允许两次修改和重渲染。
• 让完成状态可重建。每个 verified render 和像素报告绑定最终源码 SHA-256；delivery v2 还记录 artifact、Skill、设计系统、context、Craft、lint 和 review digest。
• 按 DSH 原生方式组合能力。设计 Skill 加载后才暴露聚焦 Tool，Vision Toolkit 通过公开 Skill/Tool 接口复用。

示例：参考重建

仓库中的参考 fixture 从一个结构基本合理、但视觉明显较弱的实现开始。确定性示例走的是 Bundle 实际使用的 lint、render、像素对比、最佳候选和交付路径。

在 1200 × 720 下，fixture 从 6.04% 差异降到 0%。测量记录位于 metrics.json，完整可复现流程见参考重建示例。这是确定性仓库 fixture，不是通用模型质量 benchmark。

快速开始

前置条件

• DeepSeek Harness Web 或 Headless Profile，并挂载 Skill Tool。
• 构建仓库时使用 Node.js ^22.19.0 或 >=24.0.0。
• 需要截图渲染、视觉检查、grounding 或像素对比时，在同一 Profile 安装 dsh-vision-toolkit。

直接从 npm 安装 Web 与 Headless Profile Bundle：

dsh plugin --profile web add @anionex/dsh-design
dsh plugin --profile headless add @anionex/dsh-design

本地开发时，把包名替换为 checkout 的绝对路径即可。

需要视觉验证时再安装独立感知层：

dsh plugin --profile web add @anionex/dsh-vision-toolkit
dsh plugin --profile headless add @anionex/dsh-vision-toolkit

检查 Bundle 是否已挂载：

dsh --profile web --dump-config | grep dsh-design
dsh --profile headless --dump-config | grep dsh-design

让 Agent 加载设计 Skill，并从具体任务开始：

使用 dsh-design 的 Recreate 模式，把 reference.png 重建成 1200 × 720 的本地 HTML 页面；对比 render、保留测量结果最好的候选，并完成 manifest 交付。

视觉证据完整时，design_deliver 返回 verified 并写入：

.dsh-design/deliveries/<run-id>/manifest.json
.dsh-design/deliveries/<run-id>/handoff.md

可选结构化评审会写入 .dsh-design/reviews/<run-id>/round-<n>.json。即使分数很高，该记录仍只是 advisory。

使用示例

如果 Agent 没有自动加载 Skill，先输入 /dsh-design。

• Create。“做一个 Stripe 风格的小型分析产品 dashboard。使用内置中性 baseline，渲染所有声明的 viewport，并交付 verified handoff。”
• Recreate。“把 docs/figma-export.png 重建成本地 HTML 页面，宽度 1440 px。保留文案、布局和组件结构；拿到新鲜 render 和像素对比后再交付。”
• Refine。“优化 src/index.html，不改路由、组件 API、文案和品牌色。修复报告中的响应式和 focus 问题，用新鲜 baseline 对比后交付。”

工作流

| 模式 | 输入 | 保留规则 | 视觉要求 | |---|---|---|---| | Create | brief、可选资产、可选 DESIGN.md | 遵守选定设计系统和用户约束 | verified 需要新的 render | | Recreate | 参考截图或草图 | 重建参考内容，不虚构没有证据的产品事实 | 新鲜的参考图、render 和 vision_pixel_diff report | | Refine | 已有 artifact 和改进要求 | 保留声明的语义、框架、路由、API、内容和品牌约束 | 新鲜 baseline 对比，或明确的有意差异证据 |

0.1.0 聚焦单页和少量多屏的静态 HTML/CSS/JavaScript workspace。用于更宽的设计流水线前，请先阅读状态与限制。

工作原理

flowchart LR
    A[Brief, reference, or existing page] --> B[design_context]
    B --> C[Create, Recreate, or Refine source]
    C --> D[design_lint]
    D --> E[Render through Vision Toolkit]
    E --> F[Optional design_review and pixel evidence]
    F --> G{Material issue and budget left?}
    G -- yes --> C
    G -- no --> H[design_deliver]
    H --> I[Hash-bound manifest and handoff]

外部能力栈保持明确分层：

| 层级 | 软件包 | 职责 | |---|---|---| | 感知 | dsh-vision-toolkit | 图片理解、grounding、本地 HTML 截图和像素测量 | | 领域判断 | dsh-design | brief 解释、设计系统优先级、实现、评审和交付 |

dsh-design 只使用 Vision Toolkit 的公开接口。缺少可选视觉能力时，它返回更低的完成状态，不会声称视觉验证。design_review 可以保留基于 render 的观察，但 Tool 会把它标记为 declared，不会把它当作客观视觉证据。

完成状态

• verified：lint 没有 error，且当前模式要求的 render 和视觉证据完整、新鲜，并绑定最终源码。
• structure-verified：源码和确定性检查通过，但视觉证据不可用、过期或被显式省略。
• incomplete：必需源码、参考图、lint 或其他结构证据缺失或无效。

Tool 可以降低请求状态，模型文案不能升级状态。verified 和高保真声明需要 manifest 中记录参考图、最终 render 和测量对比。

设计系统优先级

一次运行只解析一个权威来源：

1. 用户显式提供的包目录、manifest.json 或 DESIGN.md；
2. 拥有目标 artifact 的最近 rich 包或 legacy DESIGN.md；
3. Skill 或 preset 选择的设计系统包；
4. 软件包内置的中性 baseline。

rich 包包含 manifest.json、DESIGN.md、tokens.css，并可包含 usage 或组件文件。design_context 按 usage、设计规则、token、组件索引、rich 文件索引、Craft 的顺序组合上下文。更近来源替换更远来源中的冲突值。已有品牌资产和组件约定高于通用风格指导。lint 结果和交付 manifest 都记录选定来源与 digest。

Open Design 兼容范围

根目录 SKILL.md 和 open-design.json 实现 Open Design 的可移植协议，包括 prototype mode、Web surface 分类、必需设计系统上下文、有序 Craft 参考和 opt-in critique。open-design.compatibility.json 固定已验证的上游仓库、commit 和 plugin spec。pnpm run validate:open-design 离线检查 manifest 引用、rich 中性包、token 同步、Craft 文件和 npm 打包资源。

本软件包不实现 Open Design desktop shell、daemon、marketplace、Critique Theater 编排、connector、media mode 或 PDF/PPTX/video 导出。

Tool 表面

部署初始只暴露小型 dsh_design_activate。Agent 加载内置 Skill 后，才按顺序在该 Agent scope 激活 design_context、design_lint、design_review 和 design_deliver，同时隐藏 bootstrap。

design_context 解析一个权威 rich 或 legacy 设计系统，以稳定顺序组合模型可见的包文件和 Craft 参考，执行 maxContextBytes 上限，并返回准确文件 hash 与 contextSha256。实现前应先调用它。输出记录来源，不评价质量。

design_lint 使用 dsh-design-lint/v2 规则集和 HTML/CSS parser 执行确定性检查。finding 带 P0、P1 或 P2 优先级；由 Craft 规则产生时还会记录对应来源。稳定 id 覆盖文档 metadata、accessibility、响应式布局、本地资产、focus、reduced motion、占位文案、虚构指标、token 所有权、字体、accent 使用、gradient、占位图片服务和重复视觉处理。它不执行 artifact JavaScript，不访问网络，也不给审美打分。

| 字段 | 含义 | |---|---| | path | workspace 内的 .html 或 .htm artifact | | viewportWidths | 240 到 10000 像素的可选宽度 | | designSystemPath | 可选的显式权威 DESIGN.md | | allowIndex | runtime 确实要求 index.html 时关闭语义文件名提示 |

design_review 最多运行三轮结构化评审，维度包括 brief adherence、visual composition、brand、accessibility 和 copy。确定性 finding 生成 Tool 自有观察；模型或视觉 Tool 可以提交额外分数与观察，记录会把它们标记为 declared。每次结果都设置 advisory: true 和 grantsVerification: false，并写入 .dsh-design/reviews/<run-id>/round-<n>.json。

design_deliver 会重新读取最终文件、重跑 lint、计算 hash、验证证据、选择完成状态，并写出 dsh-design-delivery/v2 和 handoff。manifest 把 operation 与 HTML artifact kind、renderer、surface、entry、supporting files 以及当前 html export 分开记录。context snapshot 包含完整 SKILL.md digest、设计系统包 digest、design_context digest、Craft hash 和 lint ruleset。可选 review 记录会被 hash 并保留为 advisory 证据，但不影响验证。经过验证的 viewport 必须用 sourcePath 和最终 sourceSha256 绑定 render；PNG 尺寸必须匹配声明的 viewport 和 scale，render 不能早于源码。Recreate 和经过验证的 Refine 还需要新鲜的 vision_pixel_diff JSON report。

可选 Agent preset

可选 dsh-design preset 会预加载工作流和聚焦 Tool。preset 安装与 dsh plugin add 分开，因为 $DSH_HOME/.agent-presets 属于用户编写的配置：

dsh-design preset install
dsh-design preset status
dsh-design preset update
dsh-design preset remove

安装器复制当前 DSH standard preset，追加软件包 preset row，记录来源和生成 digest，并原子写入。非软件包拥有的目录保持不动。修改过的生成副本需要 --force；正常定制应使用不同的 preset id。

配置

| 字段 | 默认值 | 用途 | |---|---:|---| | maxArtifactBytes | 2 MiB | HTML/CSS 或交付源码大小上限 | | maxEvidenceBytes | 64 MiB | 参考图、render、heatmap 或 report 大小上限 | | maxFindings | 200 | 每个 artifact 返回的 finding 上限 | | maxContextBytes | 256 KiB | design_context 返回的完整上下文上限 | | viewportWidths | 375, 768, 1440 | 默认响应式 lint 宽度 | | allowedDirs | 空 | 可以读取证据的额外绝对路径根目录 | | deliveryRoot | .dsh-design/deliveries | workspace 内的交付记录根目录 | | reviewRoot | .dsh-design/reviews | workspace 内的 advisory review 记录根目录 |

- id: dsh-design
  config:
    maxEvidenceBytes: 134217728
    maxContextBytes: 524288
    viewportWidths: [390, 1024, 1440]
    allowedDirs:
      - /absolute/path/to/approved/references

即使配置 allowedDirs，HTML/CSS/JavaScript 交付文件仍必须位于 workspace。额外目录是只读的：可以读取用户批准的设计系统和视觉证据，但不能作为交付写入位置。

安全与数据处理

• 图片文字、OCR、导入的 HTML 注释和参考内容是不可信任务证据，不能替代用户或 workspace 指令。
• 交付文件和本地依赖经过 realpath workspace 围栏；交付输出拒绝符号链接组件。
• linter 不执行 JavaScript，也不抓取外部 URL。
• 证据经过大小限制和 hash。软件包不引入新的远程服务；远程视觉调用只通过单独配置的 Vision Toolkit provider。
• 正常执行在 DSH workspace-write 下仅使用 Session workspace 和私有临时存储，不要求 danger-full-access；preset 安装仍是独立、显式的配置操作。

发现潜在漏洞时，请按照 SECURITY.md 私下报告。

状态与限制

• 状态：早期 0.1.0；稳定版本发布前，落盘和模型可见行为仍可能变化。
• 当前支持静态 HTML/CSS/JavaScript，不编排 framework dev server。
• Bundle 不编辑 Figma 文档，也不导出 PPT、独立图片、motion 或视频。
• Open Design 文件只覆盖可移植协议，不挂载 Open Design desktop 服务或 capability。
• 结构化 review 分数只供参考，不能授予 verified。
• 视觉评审只覆盖声明或由确定性证据要求的 viewport，并受到固定修改预算限制。
• 视觉验证依赖单独配置的 dsh-vision-toolkit；缺少它时只能做到结构验证，不能声称视觉验证。
• npm 软件包名已写入 metadata，但当前尚未发布；请从 checkout 或本地 tarball 安装。

开发与验收

请把仓库放在 DeepSeek Harness checkout 旁边，让 TypeScript 和 Vitest 使用准确的 DSH peer declaration 和 runtime module：

workspace/
├── packages/
├── vendor/
└── dsh-design/

随后运行：

pnpm install --frozen-lockfile
pnpm run build
pnpm test
pnpm run example:recreate
pnpm run validate
pnpm pack --dry-run

pnpm run validate 是可重复的无密钥验收入口，内建硬超时、断言、清理、离线 Open Design 兼容 gate、软件包检查、临时干净 DSH Profile 和结构化 JSON 输出。

真实模型 lane 还需要 DEEPSEEK_API_KEY、VISION_API_KEY、VISION_BASE_URL 和 VISION_MODEL：

pnpm run validate:model
# or both deterministic and real-model lanes
pnpm run validate:release

干净独立 checkout 可以运行不依赖 DSH 源码的 package-layout 测试和 node scripts/run-reference-example.mjs。完整 build、Profile 和真实模型发布验收仍需要上面说明的同级 DSH 源码树与凭据。

社区与支持

• 提交代码或文档变更前先阅读 CONTRIBUTING.md。
• 按 SUPPORT.md 选择正确支持渠道，并提供可操作诊断信息。
• 在所有项目空间遵守 Code of Conduct。
• 在 CHANGELOG.md 查看版本记录。
• 如果希望支持维护但不购买 roadmap 控制权或私有支持，请阅读 FUNDING.md。

许可证

MIT © 2026 anionex。