@leeandrew/dsh-ambient-skin

v1.0.0

Published

2 months ago

Native ambient wallpaper, material and semantic-color themes for DeepSeek Harness Web UI.

0High
0Medium
0Low

deepseek deepseek-harness dsh theme skin wallpaper webui

dsh-ambient-skin 保留 Harness 原有布局和交互，只改变工作空间的光线、颜色与材质。npm 包名为 @leeandrew/dsh-ambient-skin。插件使用 Harness 官方主题令牌和稳定的 data-slot 插槽，不依赖构建后生成的随机类名，也不复制或覆盖宿主页面。

亮点

原生主题集成。通过 Harness 主题服务覆盖语义令牌，浅色与深色模式分别保持可读性。
三种内置氛围。晨雾极光、深海微光和落日工作室开箱即用。
本地图片主题。导入 JPG、PNG 或 WebP 后，插件会纠正方向、移除元数据、压缩为 WebP，并生成浅色与深色两套配色。
按场景控制背景。首页、会话、详情和专注模式使用不同的壁纸强度，避免内容区受到干扰。
可调整玻璃材质。壁纸强度、面板透明度、背景模糊、亮度和饱和度都可以独立设置。
设置页与快速切换。在 Harness 设置中管理主题，也可以通过侧栏按钮快速轮换。
可移植主题包。支持导入和导出带 SHA-256 完整性清单的 .dshskin 主题包。
安全 CSS 扩展。只允许经过白名单验证的部件、状态和样式属性，禁止网络 URL、脚本表达式和全局选择器。
数据留在本机。主题、壁纸和设置保存在 ~/.dsh/ambient-skin，不会上传到远程服务。

设计方式

插件分为 Host 与 Client 两部分。

主题层只使用 Harness 的公开接口。宿主更新时，插件不需要追逐压缩类名；若公开接口发生变化，类型检查和浏览器验收会直接暴露问题。

安装

从 npm 安装

包发布后，可以通过 DSH 插件命令安装指定版本。

npx -y @deepseek-ai/dsh plugin --profile web add @leeandrew/[email protected]

插件集合发生变化后需要重启 dsh web。更新版本时重新执行安装命令即可。

从源码安装

克隆仓库后，在项目目录执行：

cd dsh-ambient-skin
pnpm install
pnpm check
pnpm pack
npx -y @deepseek-ai/dsh plugin --profile web add ./leeandrew-dsh-ambient-skin-1.0.0.tgz

完成后重启 Harness Web UI。

卸载

npx -y @deepseek-ai/dsh plugin --profile web remove @leeandrew/dsh-ambient-skin

卸载插件不会自动删除 ~/.dsh/ambient-skin 中的个人主题和设置。

使用

打开 Harness 设置。
进入“氛围皮肤”。
选择一套内置主题，或导入本地图片。
根据屏幕和环境调整壁纸、面板、模糊、亮度与饱和度。
返回工作区后，可以使用侧栏底部的圆形按钮轮换主题。

内置主题

三套主题都提供独立的浅色与深色背景，不会把深色壁纸直接套在浅色文字方案上。

场景适配

| 场景 | 默认行为 | | :--- | :--- | | 首页 | 完整显示主题氛围 | | 会话 | 降低壁纸存在感，优先保证消息可读性 | | 详情 | 进一步降低背景强度，突出工具输出和文件内容 | | 专注模式 | 将壁纸降到最低强度，保留配色和材质 |

图片导入

支持 JPG、PNG 和 WebP。
单张图片最大 15 MB，最大解码像素为 5000 万。
原始图片不会保存。插件会移除元数据并重新编码为 WebP。
色板和焦点位置在本机分析，不依赖外部服务。
导入结果保存在 ~/.dsh/ambient-skin/themes/<theme-id>。

主题包

.dshskin 是一个 ZIP 主题包，通常包含以下文件。

| 文件 | 是否必需 | 用途 | | :--- | :---: | :--- | | theme.json | 是 | 主题名称、色板、材质和场景参数 | | background.webp | 图片主题必需 | 本地背景图 | | theme.css | 否 | 通过安全编译器处理的有限样式扩展 | | manifest.json | 推荐 | 文件大小与 SHA-256 完整性清单 | | manifest.sig | 否 | 为后续签名信任机制预留 |

完整格式、字段范围和安全 CSS 能力见主题包规范。

安全与隐私

管理 API 只接受回环地址或 Harness 明确信任的 Host。
图片在本机解码、去除元数据并重新编码。
压缩包限制总体大小、文件数量和文件路径，禁止目录穿越。
存在 manifest.json 时，文件集合、大小和 SHA-256 必须完全匹配。
theme.css 不允许 url()、@import、var()、expression() 或任意全局选择器。
删除自定义主题时先移动到 ~/.dsh/ambient-skin/deleted，方便人工恢复。

详细边界见 SECURITY.md。不要把包含私密内容的壁纸打包后公开分享。

数据目录

~/.dsh/ambient-skin/
├── settings.json       # 插件设置
├── themes/             # 本地主题
└── deleted/            # 可恢复删除的主题

兼容性

| 项目 | 当前要求 | | :--- | :--- | | DeepSeek Harness | 0.1.0-rc.6 | | Node.js | >= 20 | | 平台 | Harness Web UI |

Harness 仍处于预览阶段。升级 Harness 后，建议运行 pnpm check，并检查首页、会话页、详情区和设置页。

开发

pnpm install       # 安装依赖
pnpm typecheck     # TypeScript 类型检查
pnpm test          # 运行单元测试
pnpm build         # 生成 Host 与 Client 产物
pnpm check         # 依次执行类型检查、测试和构建
pnpm pack          # 生成可安装的 tgz 包

发布到 npm

本项目发布到个人 scope @leeandrew。首次发布前需要登录 npm，并确认当前账户正确。

npm login
npm whoami

npm whoami 应返回 leeandrew。随后检查最终发布内容并发布公开包：

pnpm check
pnpm pack --dry-run
pnpm publish --access public

发布成功后，npm 页面地址为 https://www.npmjs.com/package/@leeandrew/dsh-ambient-skin。同一版本号不能重复发布，后续更新需要先调整 package.json 中的版本号。

项目结构

dsh-ambient-skin/
├── src/
│   ├── client/          # 设置页、快捷入口、场景识别与主题应用
│   ├── index.ts         # Host 插件入口和本地 API
│   ├── repository.ts    # 主题与设置仓库
│   ├── image-analysis.ts
│   ├── safe-css.ts
│   └── builtins.ts
├── tests/               # Schema、安全 CSS 与仓库测试
├── references/          # 主题包格式文档
├── cordis.patch.yml     # DSH bundle 插入声明
├── package.json
└── SECURITY.md

GitHub 应保留的文件

src/、tests/、references/
package.json、pnpm-lock.yaml、pnpm-workspace.yaml
tsconfig.json、tsconfig.build.json、tsdown.config.ts、vitest.config.ts
cordis.patch.yml
README.md、SECURITY.md、LICENSE、.gitignore

node_modules/、.pnpm-store/、lib/、测试覆盖率、日志和 *.tgz 都是可以重新生成的内容，不需要提交。npm 发布或制作 Release 前运行 pnpm check && pnpm pack 即可。

License

MIT