skin-developer

name	skin-developer
description	Build a new skin for the dsh-web-ui skin collection (DSH Web GUI) and publish it into the skin-center plugin — scaffold with scripts/dsh-skin-new, author skin.json plus the apply/dispose + scoped-CSS contract, build and test with the official standalone bundle standard (turtle-ui shape), regenerate the skin-center registry and gallery, and submit the PR. Use when the user asks to create, add, develop, scaffold, or publish a new skin for the dsh web GUI skin collection.
whenToUse	The user wants a new skin (新建/新增/开发一个皮肤), or wants to publish/发 skin-center, or asks how skins are built and shipped in the dsh-web-ui repo. Not for switching skins (scripts/dsh-skin) or gallery-only edits.

皮肤开发者（dsh-web-ui 皮肤集合）

本技能指导在 /Users/zcl/code/dsh-web-ui（或任何 dsh-web-ui 克隆）里从零构建一个新皮肤， 并把它发布进 skin-center 插件（GUI 设置页 Skins 分区）与 gallery。每个皮肤是符合 DSH 官方插件标准（turtle-ui 式 setup）的自包含包，可被 dsh plugin add 安装。

仓库与标准速览

• packages/skins/<name>/ — 一个皮肤 = 一个自包含插件包；packages/skins/qq98/ 是成熟样例，遇到疑问先读它。
• 官方标准四件套（对照 DSH docs/user/develop/basic/publish.md，turtle-ui 为范例）：
  1. package.json 声明 dsh.bundle.patch → cordis.patch.yml（安装时自动插入 ui-skin-* dshClient 行）；
  2. cordis.patch.yml — bundle patch 层；
  3. prepare 脚本 = tsdown（pnpm 在 git 安装后自动运行，自包含构建 lib/，无项目引用、无类型检查）；
  4. devDependencies 只用真实发布版本（tsdown / lightningcss / cordis / vitest / jsdom）—— @deepseek-ai/dsh-* 未发布到 npm，运行时由宿主 shell 的 module table 提供，构建时作 external。
• 构建预设：packages/skins/tsdown.client.ts（官方 packages/client/tsdown.client.ts 的 standalone 移植）。
• 仓库是 pnpm workspace：根目录 pnpm install 一次即可构建/测试全部皮肤。

0. 前置

cd <dsh-web-ui 克隆根>
pnpm install        # 首次；顺带跑每个皮肤的 prepare

先读 packages/skins/qq98/ 的 src/client/index.ts 与 skin.json，理解 apply 契约与元数据契约。

1. 脚手架

node scripts/dsh-skin-new <kebab-case-name>   # 如 matrix、coffee-break

生成 packages/skins/<name>/：package.json（官方标准）、cordis.patch.yml、tsdown.config.ts、 tsconfig.json、skin.json（order 自动取最大值+1）、src/index.ts（无操作 host 入口）、 src/client/index.ts（最小 apply 模板）、<name>.module.css（作用域样式）、tests/apply.spec.ts （契约测试）、README.md。随后按脚本打印的 next steps 填写。

2. 皮肤契约（硬性约束，违反会挂评审）

• 纯呈现层：不注入服务、不发 cordis 事件、不触及模型请求（与既有皮肤一致）。
• apply(ctx) 只写自己会收回的东西：body 属性、注入的 chrome DOM、favicon、document.title； 所有写面在 ctx.effect(() => () => {...}, 'ui-skin-<name>: …') 的 disposer 里全部收回 （包括 body 属性、每个注入元素、favicon；标题仅在仍是皮肤自己的标题时才还原，不覆盖会话标题）。
• 样式全部挂在自己的 body 属性下：body[data-dsh-<name>]；暗色变体 body[data-dsh-<name>][data-ds-dark-theme]。不得用裸类名/全局选择器污染其它皮肤与官方 UI。
• CSS Modules：import css from './<name>.module.css'，类名经 css[name] 取值； CSS 文本由 bundle 的 CSS-modules 自动注入（<style data-plugin-css>，loader 卸载时移除）， 皮肤不自己管理 style 标签。
• 不携带静态资源文件：内联 SVG / data URI（参考 qq98 的企鹅 favicon 写法）。
• skin.json 字段（gallery 与 dsh-skin 的契约）：id（=目录名）、name/nameEn、author、 tagline、description、tags、accent、bodyAttr、package、wiring、preview 路径、order。

3. 构建与测试

pnpm --filter @deepseek-ai/dsh-client-ui-skin-<name> build   # 或根目录 pnpm build
pnpm --filter @deepseek-ai/dsh-client-ui-skin-<name> test    # 或根目录 pnpm test

• 产物：lib/index.js（node half）+ lib/client.js（bundle，window.__ModuleLoader__.load({id, factory})， 导出 apply）。
• 测试：tests/apply.spec.ts（vitest + jsdom）至少断言 body 属性设置/收回、chrome 注入/收回、 标题固定/还原。可按 qq98 的 apply.spec 扩展。
• 冒烟：bundle 结构可用 node 脚本核对（__ModuleLoader__.load 一次、exports.apply 为函数）。

4. 试穿与截图

open gallery/preview.html?skin=<name>&theme=light   # 真实执行 bundle 的模拟器
open gallery/preview.html?skin=<name>&theme=dark

• 模拟器真实执行 lib/client.js（shim __ModuleLoader__ + 最小 ctx），chrome/样式真实渲染。
• 重拍并提交预览图（脚本需要 playwright chromium，已装则直接跑）：

node scripts/capture-previews    # 重写 packages/skins/<name>/preview/{light,dark}.png（提交入库）

5. 发布到皮肤中心与 gallery

node scripts/skin-center-bundles   # 扫描 packages/skins/*/skin.json + lib/client.js，重新生成
                                   # packages/skins/skin-center/src/client/generated/skins.ts（内嵌注册表）
pnpm --filter @linxin666/dsh-client-ui-skin-center build   # skin-center 重新构建以嵌入新注册表
node scripts/gallery-build         # 重新生成 gallery/manifest.js + gallery/bundles.js

• 若皮肤要出现在仓库 README「结构」表/「优质推荐」里，同步更新 README.md（中文）与 README.en.md（英文）。
• dsh-skin 的 SKINS 注册表在 scripts/dsh-skin 顶部——新皮肤需由维护者添加（或用 dsh-skin install <name> 直接官方安装）。
• 提交全部生成产物（lib/、preview/、generated/skins.ts、gallery 产物、README），推送到 dsh-external/dsh-web-ui（private）并开 PR。PR 描述附 gallery 试穿截图（亮/暗）。

6. 验收清单（全部满足才算完成）

• pnpm build 通过，lib/client.js 结构正确（__ModuleLoader__.load + exports.apply）
• pnpm test 通过（body 属性与 chrome 的 apply/dispose 契约）
• gallery 模拟器试穿真实渲染，亮/暗两态正常（preview.html?skin=<name>&theme=light|dark）
• preview/{light,dark}.png 已用 capture-previews 重拍并提交
• scripts/skin-center-bundles 已重跑、skin-center 已重建（新皮肤会出现在 GUI 设置页 Skins 分区）
• scripts/gallery-build 已重跑，gallery 产物已提交
• 纯呈现层约束未违反（无服务注入/事件/模型请求）
• 提交信息清晰，PR 附试穿截图

常见坑

• 别删 dsh.bundle/cordis.patch.yml/prepare：这是官方安装（dsh plugin add）的契约。
• 别把 @deepseek-ai/dsh-* 写进 devDependencies：未发布到 npm，workspace:^ 在独立环境必炸。
• 作用域外漏样式：检查 CSS 每个规则都以 body[data-dsh-<name>] 开头（含暗色变体）。
• dispose 没收干净：对照 qq98 逐项核对——body 属性、每个 append 的节点、favicon、标题。
• 预览图过期：改完外观必须重跑 capture-previews，否则 gallery/皮肤中心显示旧图。
• 皮肤中心不显示新皮肤：先确认 skin-center-bundles 已重跑 + skin-center 已重建（注册表内嵌在 bundle 里）。