✨ Veneer：给 DeepSeek Harness 换一套你喜欢的界面

Veneer 是 DeepSeek Harness（DSH）的可视化换肤插件。无需修改 CSS 或配置文件：在侧栏打开「编辑」，就能调整背景、图片、字体、颜色和细节样式；保存后，下次打开仍会保留。

🎨 用法一眼看懂

1. 在 DSH 左下角点击 「编辑」。
2. 选择背景、字体、AI 主题或样式，边改边预览。
3. 点击 「保存主题」，设置会自动保留。

🚀 安装

dsh plugin --profile web add github:swordordead/dsh-Veneer

安装完成后重启一次 dsh web，刷新网页，即可在侧栏底部找到 「编辑」。

也可以使用 npm 包安装（发布后）：

dsh plugin --profile web add dsh-veneer

💡 这是一个 DSH 社区插件。 欢迎在 GitHub Issues 提交问题与建议。

🪄 能做什么

🧩 架构

• host 半区(lib/index.js):图片上传 API + 图片静态服务(嗅探真实图片格式,不信任扩展名) + AI 生成代理(POST /api/dsh-veneer/ai/generate,优先走 Harness 的 ctx.llm 统一运行时复用对话模型目录与凭据;仅当请求方显式携带 apiKey 时才直连 DeepSeek,且只允许 api.deepseek.com 上游) + 模型目录接口(GET /api/dsh-veneer/ai/models)
• client 半区(lib/client.js):侧栏按钮 + 浮动面板 + 背景/字体/样式编辑逻辑
• 主题存储(lib/theme-storage.js):Host Settings 命名空间 dsh-veneer（唯一字段 theme）+ localStorage 兼容快照的双写协调、读取优先级与迁移决策（Host 合法 → Host 优先并刷新快照；Host 空 → boot 时迁移旧本地主题一次；Host 不可用/非法 → 本地兜底且不覆盖 Host）
• 设置契约:host 端用设置命名空间 dsh-veneer 注册 Schema（直接传字符串——@deepseek-ai/dsh-settings 自 0.1.5 起移除了 settingsNamespace() 导出；旧版里该函数也只是校验格式后原样返回的恒等函数，故裸字符串在两个版本上行为一致）；settings 服务未挂载时 client 退回 localStorage，但 Harness 仍须提供静态模块 @deepseek-ai/dsh-settings / @deepseek-ai/schemastery（zip 安装器会预检）；client 端经动态可选 settingsScope 读写订阅，重置使用 unset 清空字段而非写 null
• 入口:package.json 的 dsh.client 声明 + ctx.slots.inject("sidebar.footer.action", …) 把按钮挂进侧栏底栏

📁 项目结构

dsh-veneer/
├── lib/
│   ├── index.js      # host 半区:图片上传/静态服务 + AI 生成代理
│   ├── client.js     # client 半区:侧栏按钮 + 换肤面板 + 默认皮肤预设
│   ├── theme-storage.js # 主题解析/规范化/读写协调/Host 迁移决策(纯逻辑,可单测)
│   ├── llm-errors.js # AI 错误码 → 友好中文文案映射
│   └── assets/       # 内置默认皮肤底图(随 npm 包分发,host 启动时复制到用户存储)
├── cordis.patch.yml  # bundle 注册层(随包发布,`dsh plugin add` 自动应用)
├── package.json      # 插件声明(dsh.client / dsh.bundle)+ npm 发布清单
├── install.bat       # zip 离线安装入口(双击运行)
├── install.ps1       # zip 离线安装脚本(幂等 + SHA256 校验 + 与 dsh plugin 互斥)
├── sync.ps1          # 开发期同步到本地 DSH profile
├── tools/
│   ├── pack-release.ps1        # 打 zip 离线发布包
│   └── validate_templates.cjs  # 模板 / AI 契约校验
├── test/             # Playwright(Python)回归脚本
└── docs/             # 架构 / 变更记录 / 计划

🌟 默认皮肤预设（装上即用）

首次安装打开 DSH 即为作者常用皮肤：白底 + 三张底图（侧栏 / 主背景 / 输入框）+ 深蓝文字， 无需任何配置。实现方式：

• 底图随 npm 包分发（lib/assets/），host 启动时把缺失的图复制到用户 DSH 存储目录 （~/.dsh/storages/dsh-veneer/images/），幂等且绝不覆盖用户自己上传的同名图片；
• client 端在浏览器 localStorage 无已保存主题时自动套用预设；用户一旦保存自己的主题， 即以用户数据为准，预设不再干扰；「重置全部设置」后回到预设。
• 底图来源为作者自用皮肤图片，随包分发仅供个人换肤使用（MIT）。

🤖 AI 生成主题（模型与凭据说明）

• 在面板「AI 主题」标签页选择模型（提供方 + 模型两级下拉），与对话共用 Harness 模型目录与凭据，零 API Key 配置，也不会把 Key 存到 localStorage。
• 生成请求走 Harness 的 ctx.llm 统一运行时（不带 sessionId 的一次性 completion），不进对话历史、不阻塞主对话。
• 模型服务不可用、凭据缺失/无效、限流(429)、无额度(402)或网络失败时，面板内显示友好中文错误，不影响已保存的主题。
• 生成结果先进入「预览」态,确认「应用」才会持久化;「放弃」恢复生成前状态。

🚀 安装部署

方式一：官方插件命令（推荐）

DSH 的插件机制支持「bundle」：只要包的 package.json 声明了 "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }，dsh plugin add 就会自动装包并注册，接收者零手动配置：

# 从 npm 安装
dsh plugin --profile web add dsh-veneer

# 或直接从 GitHub 仓库安装（会自动跑构建脚本，首次可能提示允许 build）
dsh plugin --profile web add github:swordordead/dsh-Veneer

# 或从本地目录/zip 解压目录安装
dsh plugin --profile web add /path/to/dsh-veneer

首次安装或含 Host 端改动的升级完成后重启一次 dsh web，再刷新浏览器；无需手动 改配置文件。仅前端 client 更新时强制刷新即可。卸载同样一条命令： dsh plugin --profile web remove dsh-veneer。

前置条件：dsh CLI 与 pnpm 都在 PATH 中（dsh plugin 底层转发给 pnpm）。

方式二：zip + 双击安装（离线 / 无 node / pnpm 环境）

针对无法使用命令行或没有 Node 环境的接收者，提供了 zip 包 + 一键安装脚本：

1. 打包（发布前先按版本号策略递增 package.json 的 version）：

   powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\pack-release.ps1

   生成 release\dsh-veneer-vX.Y.Z.zip（只含运行期必需文件：package.json、 cordis.patch.yml、lib/、install.bat、install.ps1、使用说明.txt）， 可上传 GitHub Releases 或直接发文件。

2. 接收者：解压 → 双击 install.bat。脚本自动完成复制 + 注册，幂等（重复执行不会 重复注册）、带 SHA256 校验，无需 node/pnpm。首次安装或版本包含 Host 端改动时， 需重启一次 dsh web；仅 lib/client.js 变化时强制刷新浏览器即可。 与方式一互斥：若接收者已用 dsh plugin --profile web add dsh-veneer 安装过， install.ps1 会在复制前检测到并安全退出，不会覆盖 pnpm 管理的目录；此时应使用 dsh plugin --profile web update dsh-veneer 更新。

3. 接收者升级：重新下载新包再次双击并按上条规则重启/刷新即可。主题存于 Harness Settings（settings.yaml），不随插件目录覆盖，已有设置会保留。

自定义 DSH 数据目录（设置了 DSH_HOME）的接收者：先 set DSH_HOME=... 再运行，或 powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -DshHome "目录"。

手动方式（了解原理）

$dst = "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-veneer"
New-Item -ItemType Directory -Path "$dst" -Force | Out-Null
Copy-Item -Recurse -Force .\* "$dst"

再在 profiles/web/cordis.patch.yml 注册 dsh-veneer，重启 dsh web。 （zip 里的 install.bat 就是把这两步自动化的脚本。）

日常同步（改完代码后）

powershell -ExecutionPolicy Bypass -File .\sync.ps1 -AllowManagedOverwrite

sync.ps1 默认拒绝覆盖由 dsh plugin 管理的目录；上述开关只用于维护者明确进行本地开发部署。 脚本会先对 lib/client.js、lib/index.js、lib/theme-storage.js、lib/llm-errors.js 做 node --check，仅复制运行期白名单（package.json、cordis.patch.yml、lib/）到 $env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-veneer，最后比对 SHA256。 仅前端 client 改动时刷新浏览器即可；lib/index.js、依赖或插件注册变化后需重启 dsh web。

发布到 npm（维护者）

npm login      # 首次需登录 npm 账号
npm publish    # 发布 dsh-veneer,接收者即可 `dsh plugin --profile web add dsh-veneer`

package.json 的 files 白名单只发布 lib/ + cordis.patch.yml(npm 会自动附带 package.json / README / LICENSE),docs、test、install 脚本不会进 npm 包。

✅ 测试

Node 单元测试（无需 DSH / 浏览器，随时可跑）：

npm test
# 等价于: node --experimental-test-module-mocks --test
#（Node 24 起 module mocking 需要该 flag；host-settings.test.mjs 依赖 mock.module）

# - test/ai-colors.test.mjs       AI 颜色容错单测（22 用例，mock canvas）
# - test/ai-colors.browser.test.mjs 真实浏览器引擎验证 CSS Color 4（oklch/hwb/lab/color()），
#                                    依赖 playwright（devDependency，缺失时自动跳过）
# - test/llm-errors.test.mjs      LLM 错误码映射单测
# - test/theme-storage.test.mjs   主题解析/规范化/Host 迁移决策单测
# - test/client-storage-integration.test.mjs  client 工厂有/无 settingsScope 双写集成单测
# - test/host-settings.test.mjs    Host 设置命名空间 + Schema 注册（可选依赖）单测
# - test/install-script-check.ps1  zip 安装器 BOM/依赖/官方管理互斥/离线复制校验

Playwright 回归脚本（需 DSH 跑在 127.0.0.1:3080）：

python test\veneer-skin-check.py                 # 面板结构 / 导出导入 / 字体选择器 / 无 pageerror
python test\system-fonts-check.py             # 系统字体扫描 + 字体/文字颜色精调 + 重置语义
python test\background-image-position-check.py # 背景图位置滑块 / 预览拖拽裁切 / 变淡蒙层 / 移除图
python test\import-security-check.py           # 导入安全:CSS 注入 / 非法 token / 恶意 URL / 合法 rgb 色
python test\ai-theme-check.py                 # AI 生成(mock)/ 预览应用放弃 / 样式维度 / 模板库 / 无 pageerror

模板与 AI 契约校验工具（开发期使用）:

node tools\validate_templates.cjs

📄 License

MIT