dsh-skin

dsh-skin 是 DeepSeek Harness Web 的原生 Cordis 皮肤插件。主题选择和 ZIP 导入直接集成在 Harness 自带的“设置 > 通用设置”中，不修改 DSH 安装包，也不需要 浏览器扩展或 CDP 注入器。

已在 @deepseek-ai/dsh@0.1.0-rc.6 的 Web profile 中验证。

快速安装

前置条件：已安装 DeepSeek Harness，终端中可以运行 dsh，Node.js 版本不低于 18。

dsh plugin --profile web add github:huyansheng3/dsh-skin
dsh web

当前 main 安装包内置 20 套精选 Gallery 主题和 2 套项目主题；它们会自动出现在 皮肤下拉框中，但首次安装仍保持“官方外观”，不会自动激活社区主题。

打开 DSH Web 页面后，进入 设置 > 通用设置 > 皮肤：

1. 在下拉框中选择内置主题；
2. 或点击“导入 ZIP”安装自己的 DreamSkin 主题；
3. 选择“官方外观”即可停用皮肤。

导入主题不会自动激活。若 dsh web 已经在运行，安装或升级插件后请重启服务。

升级与卸载

升级到当前 main 分支：

dsh plugin --profile web add github:huyansheng3/dsh-skin

卸载：

dsh plugin --profile web remove dsh-skin

从本地源码安装

适合开发或离线环境：

git clone https://github.com/huyansheng3/dsh-skin.git
cd dsh-skin
npm run build
dsh plugin --profile web add "$PWD"
dsh web

源码仓库已经包含随包的 20 套精选主题。需要把本地开发库扩展到审计保留的 76 套时， 再执行 npm run vendor:gallery：

npm run vendor:gallery
DSH_SKIN_GALLERY_DIR="$PWD/gallery/themes" dsh web

vendor:gallery 从 DreamSkin Gallery 热门前 100 的冻结审计中排除 24 个源可读性 不合格主题，再按 精选目录 下载并校验剩余 76 个具体版本， 在项目的 gallery/themes/ 中生成本地内置主题库。运行时不会联网，也不会自动切换 当前主题。已有 ZIP 缓存可用于完全离线物化：

npm run vendor:gallery -- --cache-dir /path/to/cache --offline

Gallery 包由社区作者发布，并不统一使用 MIT 许可。发布包只收录其中 20 个经审计、 许可允许再分发的主题，其余主题只在本地物化。目录记录每个版本的作者、原始许可、 体积和 SHA-256；随包背景以不裁切、不调色的高质量 WebP 分发，将 GitHub 安装包控制 在约 6.5 MB。主题归属、许可和重编码说明见 第三方声明。

功能

• 原生设置集成：不创建额外路由、浮动按钮或 iframe；
• 即时切换：设置成功后刷新主题 stylesheet，不替换 Harness DOM；
• 内置主题：发布包自带 2 套原创带图主题和 20 套精选 Gallery 主题；源码可物化 76 套；
• ZIP 导入：兼容 DreamSkin 与 legacy DSH 主题格式；
• Safe CSS：拒绝脚本、@import、危险 URL 和未经授权的布局覆盖；
• 作者保真：保留主题原始配色、玻璃透明度和自定义 CSS，不在运行时强制修色；
• 定点可读性：仅让原生代码块、行内代码和不透明控件使用作者的实色面板 token， 不覆盖正文颜色、不加全局遮罩；
• Headless 安全：没有 webServer 时插件保持 no-op。

常见问题

设置中没有“皮肤”选项

确认插件安装在 web profile，而不是默认或其他 profile：

dsh plugin --profile web list --depth 0

列表中应包含 dsh-skin。随后停止并重新运行 dsh web。

页面仍显示旧主题

先刷新浏览器。仍未更新时，重启 dsh web；插件会用 theme@version:revision 缓存键刷新样式资源。

ZIP 导入失败

DreamSkin ZIP 必须包含 manifest.json、theme.json、非空 theme.css 和清单中 声明的一张背景图。插件还会检查文件哈希、路径穿越、条目数量、压缩大小和解压大小。 完整格式见 主题规范。

固定主题后不能在页面切换

部署配置中的 activeTheme 会锁定页面选择器。删除该配置，或改用 defaultTheme 只设置首次默认主题。

工作方式

DSH Web Loader
  +-- dsh-skin Host
  |   +-- tapIndex() 注入 /_skin/active.css
  |   +-- /_skin/bg/* 提供当前背景图
  |   +-- /_skin/api/* 提供主题查询、切换和 ZIP 导入
  +-- dsh-skin Client
      +-- settings.general.item 提供原生设置行

Host 始终注入一个带缓存版本的 stylesheet link。带图主题由 body::before 绘制 pointer-events: none 的背景层，原生 UI、弹窗和 portal 仍由 DSH 管理。插件不会 修改 API Key、Base URL 或官方安装包，也不会在运行时下载网络资源或启动外部常驻 进程。只有开发者显式执行 vendor:gallery 时才会访问 Gallery 官方 API。

架构和生命周期详见 架构说明。

配置

仓库自带的 cordis.patch.yml 只注册插件，不默认激活主题。 部署方需要固定主题时，可以在额外 patch 中配置：

- id: dsh-skin
  name: dsh-skin
  config:
    activeTheme: gothic-void-crusade

DSH 的 id-targeted patch 会替换整行而不是深合并，因此覆盖时要同时保留 name: dsh-skin。

CLI

CLI 与 Web 设置读取同一个本地主题库：

dsh-skin install ./my-theme
dsh-skin import ./my-theme.zip
dsh-skin list
dsh-skin activate my-theme
dsh-skin deactivate
dsh-skin info my-theme
dsh-skin remove my-theme
dsh-skin pack ./my-theme

CLI 修改选择后需要刷新页面；页面设置内的切换会立即刷新 stylesheet。内置主题不 复制到用户主题库，因此 CLI 的 list、info 和 activate 只管理已安装主题。

主题格式

推荐使用 DreamSkin 格式：

{
  "packageVersion": 1,
  "themeId": "my-theme",
  "name": "My Theme",
  "version": "1.0.0",
  "files": [
    { "path": "theme.json", "mediaType": "application/json" },
    { "path": "theme.css", "mediaType": "text/css" },
    { "path": "background.jpg", "mediaType": "image/jpeg" }
  ]
}

{
  "appearance": "dark",
  "colors": {
    "background": "#1e1e2e",
    "panel": "#313244",
    "panelAlt": "#45475a",
    "accent": "#cba6f7",
    "accentAlt": "#b4befe",
    "text": "#cdd6f4",
    "muted": "#a6adc8",
    "line": "#45475a",
    "highlight": "#585b70"
  },
  "art": { "focusX": 0.5, "focusY": 0.4, "taskMode": "fill" },
  "backgroundOpacity": 1,
  "backgroundBlur": 0
}

目录安装允许不带背景图或自定义 CSS。从 ZIP 导入 DreamSkin 时，必须同时包含清单 声明的背景图和非空 theme.css。Legacy DSH schema: 1 格式继续用于已有本地主题。 完整字段与安全约束见 主题规范。

主题库位置

测试可设置 DSH_SKIN_DATA_DIR 使用隔离的数据目录。 随安装包提供的 20 套 Gallery 主题位于 gallery/themes/，DSH 进程会自动发现。 DSH_SKIN_GALLERY_DIR=/absolute/path/to/gallery/themes 仅用于覆盖安装包内的默认目录， 例如加载开发机物化的 76 套主题。用户主题始终优先于同 ID 的 Gallery 主题，物化和 扫描过程都不会改写 state.json。

开发

npm test
node --check src/index.js src/client/index.js src/lib/theme-manager.mjs
npm pack --dry-run

发布维护者需要重新生成随包背景时，安装 cwebp 后运行 npm run optimize:gallery；该命令不会在用户安装插件时执行。

Gallery 兼容性结果见 审计报告。热门前 100 中有 93 个原包 通过严格 ZIP 导入，另 7 个缺少 theme.css，本地物化时使用有界兼容 CSS。24 个可 导入主题因原始文字或强调色对比度不足，已由 排除清单 从默认目录和本地主题库删除。剩余 76 个已在真实长会话中逐个完成背景安全、原生控件 和溢出 E2E 检查；不透明文字表面低于 3:1 会直接失败，普通壁纸区域仍只报告作者 效果告警。3 条不同的现有会话均逐个复验 76 套主题，结果都是 76/76 结构通过。

License

MIT。发布包自带第三方主题的作者与许可证记录在各自 manifest.json 和 第三方声明 中；项目许可证不会替代主题各自的许可证。