{"_id":"@anionex/dsh-design","name":"@anionex/dsh-design","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@anionex/dsh-design","version":"0.1.0","description":"DSH-native Web/UI design Agent bundle with Create, Recreate, Refine, deterministic linting, verified handoff, Vision Toolkit composition, and an optional Agent preset","keywords":["deepseek","deepseek-harness","design-agent","web-design","ui-recreation","visual-qa","agent-skills"],"repository":{"type":"git","url":"git+https://github.com/Anionex/dsh-design.git"},"bugs":{"url":"https://github.com/Anionex/dsh-design/issues"},"type":"module","packageManager":"pnpm@11.20.0","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./preset":{"types":"./lib/types/preset.d.ts","default":"./lib/preset.js"},"./cordis.patch.yml":"./cordis.patch.yml","./SKILL.md":"./SKILL.md","./open-design.json":"./open-design.json","./open-design.compatibility.json":"./open-design.compatibility.json","./package.json":"./package.json"},"bin":{"dsh-design":"scripts/preset.mjs"},"scripts":{"build":"tsc -p tsconfig.json","prepack":"pnpm run build","test":"pnpm run build && vitest run tests","test:model":"node scripts/model-e2e.mjs --mode all","test:watch":"vitest tests","example:recreate":"pnpm run build && node scripts/run-reference-example.mjs","validate":"node scripts/validate.mjs --lane all","validate:open-design":"node scripts/validate-open-design.mjs","validate:local":"node scripts/validate.mjs --lane local","validate:profile":"node scripts/validate.mjs --lane profile","validate:model":"node scripts/model-e2e.mjs --mode all","validate:release":"pnpm run validate && pnpm run validate:model"},"dsh":{"bundle":{"patch":"./cordis.patch.yml"}},"dependencies":{"css-tree":"3.2.1","parse5":"8.0.1","yaml":"2.8.1"},"peerDependencies":{"@deepseek-ai/dsh-agent":"^0.1.0-rc.6","@deepseek-ai/dsh-llm":"^0.1.0-rc.6","@deepseek-ai/dsh-session":"^0.1.0-rc.6","@deepseek-ai/dsh-skill":"^0.1.0-rc.6","@deepseek-ai/dsh-system-prompt":"^0.1.0-rc.6","@deepseek-ai/dsh-tools":"^0.1.0-rc.6","@deepseek-ai/cordis":"^4.0.1","@deepseek-ai/schemastery":"^3.18.1"},"devDependencies":{"@types/css-tree":"^2.3.10","@types/node":"^22.20.0","typescript":"^6.0.3","vitest":"^4.1.8"},"engines":{"node":"^22.19.0 || >=24.0.0"},"license":"MIT","_id":"@anionex/dsh-design@0.1.0","homepage":"https://github.com/Anionex/dsh-design#readme","_integrity":"sha512-PJj9vP7tJDniKz6yYwo4Y2XXmVm/aukkJjdhmYFVTa0ZjYBF3fhwKwa0YGOjFBZLBiR8Q5YCUqm+TgOd3+Xpuw==","_resolved":"/tmp/anionex-dsh-design-0.1.0.tgz","_from":"file:/tmp/anionex-dsh-design-0.1.0.tgz","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-PJj9vP7tJDniKz6yYwo4Y2XXmVm/aukkJjdhmYFVTa0ZjYBF3fhwKwa0YGOjFBZLBiR8Q5YCUqm+TgOd3+Xpuw==","shasum":"e6e53f426cdcd1b9fa6af0d160cf8704e330246a","tarball":"https://registry.npmjs.org/@anionex/dsh-design/-/dsh-design-0.1.0.tgz","fileCount":124,"unpackedSize":1131225,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCs3DJlJMlGHMqKp463gD5ry4vhCQEJAM8SaWRRmMPc8wIgJzql59QhTs89lWQOmT7sX/cp1mJY1rBaiAs/NACDzuY="}]},"_npmUser":{"name":"anionex","email":"davidyang042@gmail.com"},"directories":{},"maintainers":[{"name":"anionex","email":"davidyang042@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-design_0.1.0_1786719480426_0.13324168469783504"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-14T14:58:00.246Z","0.1.0":"2026-08-14T14:58:00.583Z","modified":"2026-08-14T14:58:00.810Z"},"maintainers":[{"name":"anionex","email":"davidyang042@gmail.com"}],"description":"DSH-native Web/UI design Agent bundle with Create, Recreate, Refine, deterministic linting, verified handoff, Vision Toolkit composition, and an optional Agent preset","homepage":"https://github.com/Anionex/dsh-design#readme","keywords":["deepseek","deepseek-harness","design-agent","web-design","ui-recreation","visual-qa","agent-skills"],"repository":{"type":"git","url":"git+https://github.com/Anionex/dsh-design.git"},"bugs":{"url":"https://github.com/Anionex/dsh-design/issues"},"license":"MIT","readme":"# dsh-design\n\n[![MIT License](https://img.shields.io/badge/license-MIT-2f855a.svg)](LICENSE)\n![Node.js](https://img.shields.io/badge/Node.js-%5E22.19%20%7C%7C%20%3E%3D24-339933.svg)\n![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-Bundle-5b50ed.svg)\n\n把设计 brief 或已有代码变成经过验证的 Web/UI 文件。\n\n`dsh-design` 是面向开发者的 DeepSeek Harness 设计 Agent Bundle。它把设计方向、真实文件实现、渲染评审、修改和 hash 绑定交付放进同一个有界循环。它组合 DSH 的 Skill、Tool、Artifact、preset 和独立的 `dsh-vision-toolkit`。所有工作都发生在 DSH workspace 内。\n\n[English](README.md) | 中文\n\n## 为什么需要 dsh-design\n\nCoding Agent 可以写 HTML 和 CSS。无约束的“做得更好看”循环没有稳定完成标准：它可能偏离 brief，也可能在没有记录源码、render、viewport 和对比证据时声称视觉质量达标。\n\n`dsh-design` 让这个循环变得明确。Agent 解析一个权威设计系统包，把 usage、token、组件索引和 Craft 参考组合成有大小上限的上下文，修改 workspace 中的真实文件，并执行确定性结构检查。只有证据能够改变下一次修改时才会请求视觉证据；测量结果最好的候选版本被保留，交付 manifest 可供其他人或 Agent 复核。\n\n## 它补充了什么\n\n- 交付真实 artifact。brief 变成 workspace 内的 HTML/CSS/JavaScript 文件。\n- 用测量证据完成 Recreate。在声明的 viewport 对比参考图与实现 render，并保留测量结果最好的源码。\n- Refine 时保留声明的约束。内容、行为、框架、路由、组件 API 和品牌约束保持不变，同时修复实质问题。\n- 组合可移植上下文。rich 设计系统包和有序 Craft 参考在实现前生成一个有大小上限的 digest。\n- 评审不冒充验证。最多三轮 `design_review` 可以保留确定性 finding 和声明的观察，但评分不能授予 verified。\n- 限制视觉迭代预算。首次 render 后，每个 viewport 最多允许两次修改和重渲染。\n- 让完成状态可重建。每个 verified render 和像素报告绑定最终源码 SHA-256；delivery v2 还记录 artifact、Skill、设计系统、context、Craft、lint 和 review digest。\n- 按 DSH 原生方式组合能力。设计 Skill 加载后才暴露聚焦 Tool，Vision Toolkit 通过公开 Skill/Tool 接口复用。\n\n## 示例：参考重建\n\n仓库中的参考 fixture 从一个结构基本合理、但视觉明显较弱的实现开始。确定性示例走的是 Bundle 实际使用的 lint、render、像素对比、最佳候选和交付路径。\n\n<p align=\"center\">\n  <img src=\"examples/reference-recreation/assets/weak.png\" width=\"49%\" alt=\"初始重建版本，导航、卡片、对比面板和表格都较简化；与参考图的像素差异为 6.04%。\" />\n  <img src=\"examples/reference-recreation/assets/improved.png\" width=\"49%\" alt=\"经过有界修改后的最终版本，在 1200×720 fixture 中与参考图的测量差异为 0%。\" />\n</p>\n\n在 `1200 × 720` 下，fixture 从 6.04% 差异降到 0%。测量记录位于 [`metrics.json`](examples/reference-recreation/assets/metrics.json)，完整可复现流程见[参考重建示例](examples/reference-recreation/README.md)。这是确定性仓库 fixture，不是通用模型质量 benchmark。\n\n## 快速开始\n\n### 前置条件\n\n- DeepSeek Harness Web 或 Headless Profile，并挂载 Skill Tool。\n- 构建仓库时使用 Node.js `^22.19.0` 或 `>=24.0.0`。\n- 需要截图渲染、视觉检查、grounding 或像素对比时，在同一 Profile 安装 `dsh-vision-toolkit`。\n\n直接从 npm 安装 Web 与 Headless Profile Bundle：\n\n```sh\ndsh plugin --profile web add @anionex/dsh-design\ndsh plugin --profile headless add @anionex/dsh-design\n```\n\n本地开发时，把包名替换为 checkout 的绝对路径即可。\n\n需要视觉验证时再安装独立感知层：\n\n```sh\ndsh plugin --profile web add @anionex/dsh-vision-toolkit\ndsh plugin --profile headless add @anionex/dsh-vision-toolkit\n```\n\n检查 Bundle 是否已挂载：\n\n```sh\ndsh --profile web --dump-config | grep dsh-design\ndsh --profile headless --dump-config | grep dsh-design\n```\n\n让 Agent 加载设计 Skill，并从具体任务开始：\n\n> 使用 dsh-design 的 Recreate 模式，把 `reference.png` 重建成 1200 × 720 的本地 HTML 页面；对比 render、保留测量结果最好的候选，并完成 manifest 交付。\n\n视觉证据完整时，`design_deliver` 返回 `verified` 并写入：\n\n```text\n.dsh-design/deliveries/<run-id>/manifest.json\n.dsh-design/deliveries/<run-id>/handoff.md\n```\n\n可选结构化评审会写入 `.dsh-design/reviews/<run-id>/round-<n>.json`。即使分数很高，该记录仍只是 advisory。\n\n## 使用示例\n\n如果 Agent 没有自动加载 Skill，先输入 `/dsh-design`。\n\n- Create。“做一个 Stripe 风格的小型分析产品 dashboard。使用内置中性 baseline，渲染所有声明的 viewport，并交付 verified handoff。”\n- Recreate。“把 `docs/figma-export.png` 重建成本地 HTML 页面，宽度 1440 px。保留文案、布局和组件结构；拿到新鲜 render 和像素对比后再交付。”\n- Refine。“优化 `src/index.html`，不改路由、组件 API、文案和品牌色。修复报告中的响应式和 focus 问题，用新鲜 baseline 对比后交付。”\n\n## 工作流\n\n| 模式 | 输入 | 保留规则 | 视觉要求 |\n|---|---|---|---|\n| Create | brief、可选资产、可选 `DESIGN.md` | 遵守选定设计系统和用户约束 | `verified` 需要新的 render |\n| Recreate | 参考截图或草图 | 重建参考内容，不虚构没有证据的产品事实 | 新鲜的参考图、render 和 `vision_pixel_diff` report |\n| Refine | 已有 artifact 和改进要求 | 保留声明的语义、框架、路由、API、内容和品牌约束 | 新鲜 baseline 对比，或明确的有意差异证据 |\n\n`0.1.0` 聚焦单页和少量多屏的静态 HTML/CSS/JavaScript workspace。用于更宽的设计流水线前，请先阅读[状态与限制](#status-and-limitations)。\n\n## 工作原理\n\n```mermaid\nflowchart LR\n    A[Brief, reference, or existing page] --> B[design_context]\n    B --> C[Create, Recreate, or Refine source]\n    C --> D[design_lint]\n    D --> E[Render through Vision Toolkit]\n    E --> F[Optional design_review and pixel evidence]\n    F --> G{Material issue and budget left?}\n    G -- yes --> C\n    G -- no --> H[design_deliver]\n    H --> I[Hash-bound manifest and handoff]\n```\n\n外部能力栈保持明确分层：\n\n| 层级 | 软件包 | 职责 |\n|---|---|---|\n| 感知 | `dsh-vision-toolkit` | 图片理解、grounding、本地 HTML 截图和像素测量 |\n| 领域判断 | `dsh-design` | brief 解释、设计系统优先级、实现、评审和交付 |\n\n`dsh-design` 只使用 Vision Toolkit 的公开接口。缺少可选视觉能力时，它返回更低的完成状态，不会声称视觉验证。`design_review` 可以保留基于 render 的观察，但 Tool 会把它标记为 `declared`，不会把它当作客观视觉证据。\n\n## 完成状态\n\n- `verified`：lint 没有 error，且当前模式要求的 render 和视觉证据完整、新鲜，并绑定最终源码。\n- `structure-verified`：源码和确定性检查通过，但视觉证据不可用、过期或被显式省略。\n- `incomplete`：必需源码、参考图、lint 或其他结构证据缺失或无效。\n\nTool 可以降低请求状态，模型文案不能升级状态。`verified` 和高保真声明需要 manifest 中记录参考图、最终 render 和测量对比。\n\n## 设计系统优先级\n\n一次运行只解析一个权威来源：\n\n1. 用户显式提供的包目录、`manifest.json` 或 `DESIGN.md`；\n2. 拥有目标 artifact 的最近 rich 包或 legacy `DESIGN.md`；\n3. Skill 或 preset 选择的设计系统包；\n4. 软件包内置的中性 baseline。\n\nrich 包包含 `manifest.json`、`DESIGN.md`、`tokens.css`，并可包含 usage 或组件文件。`design_context` 按 usage、设计规则、token、组件索引、rich 文件索引、Craft 的顺序组合上下文。更近来源替换更远来源中的冲突值。已有品牌资产和组件约定高于通用风格指导。lint 结果和交付 manifest 都记录选定来源与 digest。\n\n## Open Design 兼容范围\n\n根目录 [`SKILL.md`](SKILL.md) 和 [`open-design.json`](open-design.json) 实现 Open Design 的可移植协议，包括 prototype mode、Web surface 分类、必需设计系统上下文、有序 Craft 参考和 opt-in critique。[`open-design.compatibility.json`](open-design.compatibility.json) 固定已验证的上游仓库、commit 和 plugin spec。`pnpm run validate:open-design` 离线检查 manifest 引用、rich 中性包、token 同步、Craft 文件和 npm 打包资源。\n\n本软件包不实现 Open Design desktop shell、daemon、marketplace、Critique Theater 编排、connector、media mode 或 PDF/PPTX/video 导出。\n\n## Tool 表面\n\n部署初始只暴露小型 `dsh_design_activate`。Agent 加载内置 Skill 后，才按顺序在该 Agent scope 激活 `design_context`、`design_lint`、`design_review` 和 `design_deliver`，同时隐藏 bootstrap。\n\n<details>\n<summary><code>design_context</code></summary>\n\n`design_context` 解析一个权威 rich 或 legacy 设计系统，以稳定顺序组合模型可见的包文件和 Craft 参考，执行 `maxContextBytes` 上限，并返回准确文件 hash 与 `contextSha256`。实现前应先调用它。输出记录来源，不评价质量。\n\n</details>\n\n<details>\n<summary><code>design_lint</code></summary>\n\n`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，不访问网络，也不给审美打分。\n\n| 字段 | 含义 |\n|---|---|\n| `path` | workspace 内的 `.html` 或 `.htm` artifact |\n| `viewportWidths` | 240 到 10000 像素的可选宽度 |\n| `designSystemPath` | 可选的显式权威 `DESIGN.md` |\n| `allowIndex` | runtime 确实要求 `index.html` 时关闭语义文件名提示 |\n\n</details>\n\n<details>\n<summary><code>design_review</code></summary>\n\n`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`。\n\n</details>\n\n<details>\n<summary><code>design_deliver</code></summary>\n\n`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。\n\n</details>\n\n## 可选 Agent preset\n\n可选 `dsh-design` preset 会预加载工作流和聚焦 Tool。preset 安装与 `dsh plugin add` 分开，因为 `$DSH_HOME/.agent-presets` 属于用户编写的配置：\n\n```sh\ndsh-design preset install\ndsh-design preset status\ndsh-design preset update\ndsh-design preset remove\n```\n\n安装器复制当前 DSH `standard` preset，追加软件包 preset row，记录来源和生成 digest，并原子写入。非软件包拥有的目录保持不动。修改过的生成副本需要 `--force`；正常定制应使用不同的 preset id。\n\n## 配置\n\n<details>\n<summary>Bundle 配置字段</summary>\n\n| 字段 | 默认值 | 用途 |\n|---|---:|---|\n| `maxArtifactBytes` | 2 MiB | HTML/CSS 或交付源码大小上限 |\n| `maxEvidenceBytes` | 64 MiB | 参考图、render、heatmap 或 report 大小上限 |\n| `maxFindings` | 200 | 每个 artifact 返回的 finding 上限 |\n| `maxContextBytes` | 256 KiB | `design_context` 返回的完整上下文上限 |\n| `viewportWidths` | `375, 768, 1440` | 默认响应式 lint 宽度 |\n| `allowedDirs` | 空 | 可以读取证据的额外绝对路径根目录 |\n| `deliveryRoot` | `.dsh-design/deliveries` | workspace 内的交付记录根目录 |\n| `reviewRoot` | `.dsh-design/reviews` | workspace 内的 advisory review 记录根目录 |\n\n```yaml\n- id: dsh-design\n  config:\n    maxEvidenceBytes: 134217728\n    maxContextBytes: 524288\n    viewportWidths: [390, 1024, 1440]\n    allowedDirs:\n      - /absolute/path/to/approved/references\n```\n\n即使配置 `allowedDirs`，HTML/CSS/JavaScript 交付文件仍必须位于 workspace。额外目录是只读的：可以读取用户批准的设计系统和视觉证据，但不能作为交付写入位置。\n\n</details>\n\n## 安全与数据处理\n\n- 图片文字、OCR、导入的 HTML 注释和参考内容是不可信任务证据，不能替代用户或 workspace 指令。\n- 交付文件和本地依赖经过 realpath workspace 围栏；交付输出拒绝符号链接组件。\n- linter 不执行 JavaScript，也不抓取外部 URL。\n- 证据经过大小限制和 hash。软件包不引入新的远程服务；远程视觉调用只通过单独配置的 Vision Toolkit provider。\n- 正常执行在 DSH `workspace-write` 下仅使用 Session workspace 和私有临时存储，不要求 `danger-full-access`；preset 安装仍是独立、显式的配置操作。\n\n发现潜在漏洞时，请按照 [SECURITY.md](SECURITY.md) 私下报告。\n\n<a id=\"status-and-limitations\"></a>\n\n## 状态与限制\n\n- 状态：早期 `0.1.0`；稳定版本发布前，落盘和模型可见行为仍可能变化。\n- 当前支持静态 HTML/CSS/JavaScript，不编排 framework dev server。\n- Bundle 不编辑 Figma 文档，也不导出 PPT、独立图片、motion 或视频。\n- Open Design 文件只覆盖可移植协议，不挂载 Open Design desktop 服务或 capability。\n- 结构化 review 分数只供参考，不能授予 `verified`。\n- 视觉评审只覆盖声明或由确定性证据要求的 viewport，并受到固定修改预算限制。\n- 视觉验证依赖单独配置的 `dsh-vision-toolkit`；缺少它时只能做到结构验证，不能声称视觉验证。\n- npm 软件包名已写入 metadata，但当前尚未发布；请从 checkout 或本地 tarball 安装。\n\n## 开发与验收\n\n请把仓库放在 DeepSeek Harness checkout 旁边，让 TypeScript 和 Vitest 使用准确的 DSH peer declaration 和 runtime module：\n\n```text\nworkspace/\n├── packages/\n├── vendor/\n└── dsh-design/\n```\n\n随后运行：\n\n```sh\npnpm install --frozen-lockfile\npnpm run build\npnpm test\npnpm run example:recreate\npnpm run validate\npnpm pack --dry-run\n```\n\n`pnpm run validate` 是可重复的无密钥验收入口，内建硬超时、断言、清理、离线 Open Design 兼容 gate、软件包检查、临时干净 DSH Profile 和结构化 JSON 输出。\n\n真实模型 lane 还需要 `DEEPSEEK_API_KEY`、`VISION_API_KEY`、`VISION_BASE_URL` 和 `VISION_MODEL`：\n\n```sh\npnpm run validate:model\n# or both deterministic and real-model lanes\npnpm run validate:release\n```\n\n干净独立 checkout 可以运行不依赖 DSH 源码的 package-layout 测试和 `node scripts/run-reference-example.mjs`。完整 build、Profile 和真实模型发布验收仍需要上面说明的同级 DSH 源码树与凭据。\n\n## 社区与支持\n\n- 提交代码或文档变更前先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。\n- 按 [SUPPORT.md](SUPPORT.md) 选择正确支持渠道，并提供可操作诊断信息。\n- 在所有项目空间遵守 [Code of Conduct](CODE_OF_CONDUCT.md)。\n- 在 [CHANGELOG.md](CHANGELOG.md) 查看版本记录。\n- 如果希望支持维护但不购买 roadmap 控制权或私有支持，请阅读 [FUNDING.md](FUNDING.md)。\n\n## 许可证\n\n[MIT](LICENSE) © 2026 anionex。\n","readmeFilename":"README.zh.md","_rev":"1-eeef21eca40288d5f8c94cde298cc936"}