dsh-skin-market

一句话定位

dsh-skin-market 是 DSH Web 设置页里内嵌的「皮肤市场」，让你像逛应用商店一样浏览、安装、激活、停用、常驻、更新和卸载社区皮肤插件。安装来源固定到具体 commit，遇到失败会自动回滚 profile 文件，最大限度降低外观变更带来的风险。

核心能力

• 浏览社区皮肤目录并按名称、标签、明暗模式搜索或排序
• 在 DSH 设置页内一键安装、激活、停用、常驻（pin）、更新、卸载皮肤
• 每 5 分钟静默从 GitHub Pages 拉取最新目录，离线时回退到缓存或内置目录
• 皮肤安装、更新过程显示下载进度、速度和实时阶段，可中途取消
• 提供皮肤市场自身的页面内更新（无需重启 DSH 即可检测新版本）
• 安装/激活失败时自动恢复 profile 的 package.json、cordis.patch.yml、workspace 与 lockfile 快照

技术实现

• 语言: TypeScript（含客户端 React 18）
• 关键依赖: @deepseek-ai/cordis（peerDependencies，DSH 宿主框架）、@deepseek-ai/dsh-client-ui-primitives（客户端 UI 原语）、yaml（读写 cordis.patch.yml）、ajv（目录 schema 校验）
• 架构模式: 通过 Cordis 注入 webServer/loader/agents 服务，注册一组 HTTP 路由（/dsh-skin-market/...）；客户端通过 slots 注入设置页的 settings.section 槽位；通过 child_process 调用 dsh plugin 子命令完成实际 pnpm 安装/卸载
• 入口文件: src/index.ts（Host 端）、src/client/index.ts（Client 端，注入 settings 槽位）

适用场景

想把 DSH Web 换个外观，但不想手动复制仓库、改 cordis.patch.yml、跑 pnpm 命令的用户。或者装了多个第三方皮肤想做统一管理、想试装一批皮肤再决定保留哪个的人。如果你只装一款皮肤且以后不再调整，可以直接装单个皮肤插件，不必用本市场。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:kingOfSoySauce/dsh-skin-market

配置项

说明：皮肤目录中每个皮肤可能声明自己的 compatibility.dsh 和 install.allowBuild，但这些是目录条目级属性，不是插件运行时配置。

常见问题

Q: 安装 dsh-skin-market 之前需要做哪些准备？

A: 建议先关闭其他皮肤类插件以避免冲突，DSH 使用 pnpm 管理 profile 依赖，需确认 pnpm 在 PATH 中。本地开发需要 Node.js 22 或更高版本。

Q: 皮肤市场安装、更新、卸载一个皮肤会失败吗？

A: 不会修改你的真实 profile。每一步操作前会先快照 package.json、cordis.patch.yml、pnpm-workspace.yaml 和 pnpm-lock.yaml，出错时会原子恢复并清理半安装状态；遇到 pnpm allowBuilds 审批时只把必要的 key 写入对应字段。

Q: 列表里的皮肤是怎么获取的，需要每次手动更新插件吗？

A: 不需要。市场从 GitHub Pages 拉取远程目录 JSON，每 5 分钟或窗口重新获得焦点时静默校验一次。校验通过后会写入 profile 的 IndexedDB 缓存；离线或超时会回退到缓存，再回退到插件内置目录。

Q: 安装来源为什么不固定到某个分支，而要绑定完整 commit？

A: 目录中每个皮肤的目标形如 github:/#<40位 commit>，必要时带 &path: 子目录。固定 commit 可避免 main 分支后续提交对已收录版本造成意外覆盖，皮肤详情页也能精确显示来源。

Q: 皮肤市场支持哪些操作？使用流程是怎样的？

A: 支持 install / activate / deactivate / pin（常驻开启）/ unpin / update / uninstall 七种生命周期操作。每个皮肤可安装、可使用、可常驻；卸载前若仍在使用会自动停用并恢复默认外观，再删除 package。

Q: 皮肤市场会主动创建 GitHub PR 或读取隐私文件吗？

A: 不会。浏览器只能提交目录里的 skinId，无法提交任意命令或安装地址；收录流程只在维护者本地的 fork 中通过 PR 提交，并明确不读取 .env、凭据、聊天记录或工作区外的私密文件。

Q: 安装或激活后界面没变化怎么办？

A: 多数皮肤需要在 DSH Web 重启后生效。设置 → 皮肤市场 → 选中皮肤 → 点击「使用」→「重启 DSH」。重启时若仍有 Agent 正在运行，会被等待至空闲后再安全重启。

Q: 页面因皮肤冲突无法操作时怎么恢复？

A: 先停止 DSH 进程，执行 ~/.dsh/profiles/web/node_modules/.bin/dsh-skin-market-reset --profile web，会关闭市场管理的所有皮肤并保留包文件；之后重启 DSH 即可。命令使用原子写入，失败会回滚。

上手难度

入门 — 用户只需在设置页点点按钮，不需要手动编辑 profile；遇到冲突时也提供一键恢复命令，不要求理解 Cordis 或 pnpm 内部机制。

已知问题与限制

• 单个 pnpm 子命令的硬超时为 10 分钟；GitHub 大包下载慢时会触发「插件下载超时」提示（src/commands.ts:30、src/commands.ts:132-139）
• 目录要求远程 generatedAt 严格不小于本地已接受版本；远程目录若被回滚到旧时间戳，会被视为非法并保留旧目录（src/catalog.ts:140-143）
• 皮肤市场通过 .npmrc 中的 fetch-timeout=600000 临时延长 pnpm 下载超时；这是为了规避 pnpm 11 把 --config.fetchTimeout 当字符串处理导致报错的边界问题（src/lifecycle.ts:117-118）
• 仅面向 DSH Web 0.1.0-rc.6 完成实机验证；README 明确该组合已通过 132 条目录校验、70 项自动化测试和 5 分钟静默更新测试，但不代表目录内所有第三方皮肤均经过同等级别审核（README.md:182-190）
• 安装、激活、停用等生命周期操作一次只能运行一个；并发请求会被拒绝（src/lifecycle.ts:241）

一个嵌入 DSH 设置页的皮肤市场，可以浏览、安装、使用、停用、更新和卸载社区皮肤。

在线预览

点击查看在线皮肤市场

近期收录

• 2026-08-19：CAPTAIN1275/dsh-ui-web（0.2.7）——7 款皮肤一次收录：极光 Aurora、蓝色幻想、龙之继承者、初音未来、Minecraft、鲸吟、Windows XP
• 更多请查看收录日志

安装

方式一，命令安装：

安装前请确保已关闭其他皮肤插件，避免冲突

dsh plugin --profile web add 'dsh-skin-market@latest'

方式二，提示词安装：

请把 dsh-skin-market 插件安装到 DSH 的 web profile。不能先安装再检查，必须严格按以下顺序执行：

1. 安装前只读检查 web profile 的 package.json（dependencies 与 dsh.profile.bundles）、profile 的 cordis.patch.yml 和 $DSH_HOME/cordis.patch.yml（如有）。
2. 从当前启用的 bundles 中识别皮肤、主题或外观插件：排除 @deepseek-ai/dsh-base、@deepseek-ai/dsh-web-app 和 dsh-skin-market；读取候选 package.json 的名称、描述、dsh.client/dsh.bundle 声明，必要时再读 README。无法确定的候选先列出包名和描述。
3. 如果发现已启用的皮肤插件，列出它们并停在安装前，提醒我先停用以避免冲突；未经我确认不得修改任何 profile 文件，也不得执行安装。
4. 如果没有冲突，明确说“未检测到已启用的皮肤插件”，然后直接执行：

dsh plugin --profile web add 'dsh-skin-market@latest'

5. 安装后读取 web profile 的 package.json，确认 dependencies 和 dsh.profile.bundles 中都有 dsh-skin-market；缺失则报告安装或注册失败。
6. 告诉我如何重启 DSH Web，并确认重启后可从“设置 → 皮肤市场”打开。不要替我安装任何皮肤。

如果安装命令报错（例如 pnpm 不在 PATH、allowBuilds 构建审批、manifest 缺失），再读 https://github.com/kingOfSoySauce/dsh-skin-market 的 README「安装失败时，可以让 DSH 自己排查」一节处理，或把完整报错贴给我。

安装失败时，可以让 DSH 自己排查

皮肤市场的安装、更新和卸载会调用 DSH 的 profile 插件管理器；当前 DSH 使用 pnpm 管理 profile 依赖。如果出现 pnpm is not recognized、package manifest missing 或 allowBuilds 相关报错，不必手动猜测 profile 状态。

请帮我排查 DSH Web 皮肤市场的安装失败。下面是完整原始报错：

<把完整报错粘贴到这里>

请严格按以下 3 步处理，并报告每一步的结果：

1. 确认当前使用的 profile 名称和实际目录，并检查 DSH 进程自身是否能找到 pnpm（Windows 同时检查 pnpm.cmd）。如果 pnpm 不在 PATH，先说明如何安装或修复 pnpm，并停止把问题误判为 allowBuilds 配置问题。
2. 只有确认 pnpm 可用后，才检查 profile 的 pnpm-workspace.yaml。若 pnpm 输出了构建审批 key，只把报错中完整、精确的 key 合并到 allowBuilds，对应值设为 true；不要启用 dangerouslyAllowAllBuilds，也不要放宽其他包。不要读取 .env、凭据或聊天记录。
3. 重新执行原来的皮肤安装命令。完成后验证 profile package.json 依赖、node_modules 中目标包的 package.json、dsh.client/dsh.bundle 声明和 loader 注册项；如果仍失败，请指出具体失败阶段和完整错误，不要把 package manifest missing 当作根因。

更新本插件

方式一，页面更新（推荐）：

在「设置 → 皮肤市场」标题右侧点击“更新”，完成后会提醒重启 DSH Web。

方式二，命令更新：

dsh plugin --profile web add 'dsh-skin-market@latest'

完成后需手动重启 DSH

方式三，提示词更新：

请把已安装在 DSH Web profile 的 dsh-skin-market 更新到 npm 最新版本。

请严格按以下顺序执行：
1. 确认当前使用的是 web profile，并读取其 package.json，确认已安装 dsh-skin-market；不要先卸载，也不要修改其他皮肤。
2. 执行：

dsh plugin --profile web add 'dsh-skin-market@latest'

3. 更新后重新读取 web profile 的 package.json，确认 dsh-skin-market 依赖和 bundle 注册仍然存在。
4. 告诉我更新前后版本，并提醒我确认没有 Agent 正在运行后重启 DSH Web。不要替我更新或卸载任何社区皮肤。

收录你的皮肤

如果你开发了 DSH 皮肤，先准备一个公开的 GitHub 仓库，再复制下面整段提示词给你的 Agent。把 <你的皮肤仓库地址> 换成真实地址即可。

这不是终端命令，而是交给 Agent 的任务说明：

请把我的 DSH 皮肤提交到 DSH 皮肤市场。

皮肤仓库：<你的皮肤仓库地址>
目标目录仓库：https://github.com/kingOfSoySauce/dsh-skin-market
目录路径：registry/skins

请自主完成以下工作：
1. 只用只读方式检查皮肤仓库；识别单包或 monorepo 子包，读取 package.json、DSH bundle/client 声明、cordis.patch.yml、README、许可证、真实预览图和 release/tag。
2. 确认它确实是可安装的 DSH Web 皮肤，不要仅凭仓库名、README 文案或 dsh-plugin topic 判定。
3. 解析准备收录版本对应的完整 40 位 commit SHA。安装目标必须固定到该 SHA，禁止使用 main、master、HEAD 或其他可变分支。
4. 不要猜测皮肤名、包名、rowId、许可证、兼容版本或素材授权。缺少关键信息时先列出缺项，不要创建虚假条目。
5. 预览图只选择仓库内真实截图，使用固定 commit 的 GitHub raw HTTPS 地址；不要使用 SVG、data URI、第三方图床或带追踪参数的 URL。
6. fork 或 clone 目标目录仓库并新建分支；按照 registry/skin.schema.json，在 registry/skins 下只新增一个独立 YAML。不要修改或提交生成的 data/catalog.json，也不要覆盖已有条目。
7. 在目标目录仓库根目录运行 npm run registry:check 和相关测试。这个检查只验证 registry，不会改写生成文件。不得安装到我的真实 DSH profile，不得读取 .env、凭据、聊天记录或工作区外的私密文件。
8. 检查 git diff --name-only，确认变更只包含 registry/skins/<条目文件>.yml；提交变更并向目标目录仓库创建 PR。PR 标题使用“feat(registry): add <皮肤名>”，正文列出仓库、子包、版本、commit、许可证、预览来源、兼容性、自动检查结果和仍需人工确认的风险。
9. 创建 PR 后返回 PR 链接；如果没有 GitHub 权限或需要登录，只准备好分支、commit 和可复制的 PR 内容，并明确告诉我下一步。

收录不等于安全认证。不要声称该皮肤已被 DSH 官方、安全团队或市场背书。

皮肤市场里的「提交皮肤」也可以根据仓库地址生成这段提示词。

registry/skins/ 是社区提交的唯一事实来源，每个皮肤一个 YAML 文件。data/catalog.json 是生成文件，不需要在社区 PR 中维护；PR 合并到 main 后会由仓库自动重生成。这样新增皮肤之间不会因为共同编辑一个目录文件而反复冲突。

收录要求

皮肤市场同时支持带 dsh.bundle 的完整插件和只有 dsh.client 的纯前端皮肤。对于后者，市场会在安装后自动、幂等地写入该皮肤已审核的 rowId 和 package 注册项；卸载时一并移除。维护者不必为了进入市场而额外复制一份 cordis.patch.yml，但仍须在 package 或 README 中提供明确的 row ID 和 DSH 兼容范围。

• 必须是公开、可安装的 DSH Web 皮肤仓库或 monorepo 子包
• 安装来源必须固定到完整 40 位 commit SHA
• 必须提供明确的 package、row ID、许可证和兼容范围
• 预览图必须是仓库中的真实界面截图
• Topic、仓库名称和 Stars 只用于发现与排序，不代表安全审核或官方背书

仓库健康建议

市场在同步已收录仓库时会检查三项便于用户理解和安装的基础规范，并在皮肤详情页展示结果：

• README 是否展示仓库内、可固定到版本的真实界面截图
• README 或 package 元数据是否明确声明支持的 DSH Web 版本范围
• package 名称、dsh.client Web 声明、row ID 和已构建客户端入口是否满足市场的一键安装要求

检查结果用于给维护者提供改进建议，不代表安全认证。暂未满足某项规范时，页面会说明如何完善，而不会把仓库描述为“不可用”。

“兼容性待验证”和“市场能否安装”是两个独立维度：

• 兼容性表示维护者是否明确声明并验证了支持的 DSH Web 版本；缺少声明时会提示风险，但不会单独阻止市场安装。
• 市场安装表示目录是否具备固定安装目标、package、dsh.client Web 声明、row ID 和可解析的已构建客户端入口。符合这些条件时，市场会调用 DSH 的 plugin add 命令完成安装；不要求插件仓库自行实现名为 add 的命令。

兼容性验证

当前面向 DSH Web 0.1.0-rc.6。目录中的安装目标固定到收录时的完整 commit。

截至 2026-08-17，npm 的 DSH latest 与 next 均为 0.1.0-rc.6。本项目使用重新安装的该版本完成了以下验证：

• 皮肤市场 0.1.15：132 条目录校验、70 项自动化测试、类型检查、Host/Client 构建、站点构建和 package preflight 全部通过
• DSH Web 实机启动：市场 Host 路由、客户端设置入口、在线目录和 5 分钟静默更新正常加载
• Liang Intensity 0.1.4 联合冒烟：8 项测试和客户端 bundle 构建通过，并可在同一 DSH Web profile 中保持 active

这组结果证明上述版本组合可以启动和运行，不代表市场内所有第三方皮肤都已完成同等级别的人工兼容或安全审核。

在线目录更新

已安装的皮肤市场不需要升级插件才能看到新收录或更新后的皮肤：

• 打开市场时由 DSH Host 从 GitHub Pages 拉取最新 catalog.json
• 页面保持打开时每 5 分钟静默检查一次；窗口重新获得焦点时也会立即静默检查
• npm 上出现更高的市场插件版本时，标题右侧会显示下载按钮；悬停后显示“更新”，安装完成后提示重启生效
• 浏览器会用 IndexedDB 保留最近一次有效目录；再次打开时先展示缓存，再在后台校验在线目录
• 列表首批只渲染 20 个皮肤，接近底部时每次无感追加 20 个；搜索和排序仍覆盖完整目录
• 首次无缓存时显示结构化骨架屏，预览图延迟加载并保留固定尺寸，避免页面跳动
• 远程目录通过 schema、唯一 ID/package/rowId、GitHub 仓库地址和固定 commit 安装目标校验后，才会进入可安装生命周期
• 验证成功的目录会缓存到当前 profile；离线、超时或远程数据不合法时自动回退到缓存，再回退到插件内置目录
• 每日抓取任务在完整测试通过后直接部署在线目录，同时继续创建 registry PR 留下可审查记录

本地开发

需要 Node.js 22 或更高版本。

git clone https://github.com/kingOfSoySauce/dsh-skin-market.git
cd dsh-skin-market
npm install
npm run dev

npm run dev 只启动使用 Mock Host 数据的预览页面，不会修改任何 DSH profile。

本地目录调试

本地开发 DSH 皮肤时，市场默认仍会从 GitHub Pages 请求远程 catalog.json，因此刚写入本地 registry/skins 的条目可能被远程目录覆盖。启动 DSH Web 前设置下面的开发环境变量，市场会固定使用当前构建包内的 data/catalog.json，不发起远程目录请求：

DSH_SKIN_MARKET_LOCAL_CATALOG=1 dsh web

该开关只影响当前进程的目录读取；安装、激活、停用、更新和卸载仍然经过本地市场的完整生命周期。未设置时保持线上行为：优先读取远程目录，并在失败时回退到缓存和内置目录。

本地条目验证完成后，再删除该环境变量运行 DSH，确认远程目录行为没有被改变。

本地验证生成的 WebP

WebP 是独立的市场静态资源，catalog 中的 media 字段会让插件和在线页默认直接请求 GitHub Pages 上的 preview/full；没有对应 WebP 或请求失败时，继续使用原始 PNG/JPG。需要重新生成资源时，先安装 cwebp（macOS 可用 brew install webp），然后运行：

npm run registry
npm run media:build

本地调试默认也请求线上 WebP。只有需要关闭 WebP 对比原图时，才在地址后追加：

?dsh-media=0

对应仓库图片更新后，媒体脚本会重新下载并更新同一内容键；图片资源先发布到 ops 和 public market，插件代码可以单独发布。

常用检查命令：

npm run registry
npm test
npm run typecheck
npm run build
npm run release -- 0.1.31 --dry-run

正式发布时去掉 --dry-run；脚本会校验工作区、同步 npm 版本、提交并推送 Git tag，再发布 npm。需要同时创建 GitHub Release 时追加 --github-release。

完整的本地安装和回滚验证步骤见 TESTING.md。

目录维护

公共仓库保留 registry Schema、目录生成和社区提交校验。候选发现、全量收录、实机截图补录和运营报告属于维护者内部流程，不随市场运行时发布；正式目录条目仍位于 registry/skins/，data/catalog.json 是生成文件。

市场截图会作为 marketScreenshots 与上游截图合并展示；公共构建只负责校验和合并，不包含截图采集或提升工具。

安全说明

• 浏览器只能提交 registry 中的 skinId，不能提交任意命令或安装地址
• 安装、更新和激活失败时会恢复 profile manifest 快照并清理半安装状态
• GitHub Stars 由定时收录任务写入带更新时间的目录快照，页面和 Host 都不在浏览时请求 GitHub API
• 市场不会代替开发者登录 GitHub，也不会静默创建 PR

页面异常时重置皮肤

如果皮肤冲突导致 DSH 页面无法操作，先停止当前 DSH 进程，再执行：

~/.dsh/profiles/web/node_modules/.bin/dsh-skin-market-reset --profile web

该命令会关闭皮肤市场管理的所有皮肤并恢复默认外观，但保留已经安装的皮肤包和皮肤市场。随后重新启动 DSH 即可。命令使用原子写入；任何一步失败都会恢复执行前的 profile 文件。

License

MIT