dsh-webui-market-plugin

一句话定位

把 awesome-dsh-plugin.com 插件目录搬进 dsh Web 设置页的可视化插件市场：打开「设置 → 插件 → 插件市场」即可浏览、搜索、一键安装/卸载/更新社区插件，并把 web 已装的插件一键同步到桌面端等其他 profile。

核心能力

• 浏览和搜索来自 awesome-dsh-plugin.com 的社区插件目录（含分类、星标数、收录日期、中英文描述），按「最热 / 最新」排序
• 一键安装、更新、卸载，按 FIFO 队列串行执行；实时显示「排队中 / 校验中 / 执行中 / 完成 / 失败 / 已终止 / 超时」状态和 pnpm 日志
• 安装前两层安全把关：来源白名单（只接受精选目录里的 github: 源）+ 试装验证（web profile 在临时环境实际启动一次）
• 跨 profile 一键同步：把 web 已装的插件按本地复制方式补装到桌面端等其他已初始化 profile，只增不删
• 停用 / 启用：保留依赖文件，只切换激活状态；停用状态在重启后仍然保留
• 一键更新全部 + 单插件更新：github 源对比 lockfile commit 与 HEAD，npm 源对比 dist-tag.latest
• 本机插件清单：列出所有由依赖管理的插件（含市场外安装的），标注目录内 / 目录外、来源类型、停用状态
• 安装成功后简单插件可热挂载到当前运行组合，无需重启 Web 服务即可使用

技术实现

• 语言: TypeScript（编译产物为 ESM JS，源码构建为 lib/host.js + lib/client.js）
• 关键依赖: @deepseek-ai/cordis（宿主框架，peerDependency）；@deepseek-ai/dsh-client-runtime 与 @deepseek-ai/dsh-client-ui-slots（浏览器侧注册设置页 tab）；react ^18.2.0（写面板 UI）
• 架构模式: Cordis 双形态插件 —— 宿主半通过 apply(ctx) 在 webServer 服务上注册 /api/dsh-market HTTP 路由，浏览器半通过 exports["./client"] + dsh.client.platform: "web" 声明被前端 ModuleLoader 加载，注册到 settings.plugins.tab 槽位；安装/更新/卸载通过 node:child_process 调起 dsh plugin 子进程执行，写操作要求同源 POST
• 入口文件: 宿主入口 lib/host.js（导出 name: 'dsh-market-plugin'、inject: ['webServer']、apply）；客户端入口 lib/client.js（导出 inject: ['slots','sessions','workspaces']、apply，注册到 settings.plugins.tab 槽位）

适用场景

日常用 dsh web 或桌面端、希望在图形界面里浏览和安装社区插件而不手敲 dsh plugin add 命令的用户；需要在 web 和桌面端等多个 profile 间同步插件的人；以及希望对每个插件的状态（停用 / 启用 / 已安装 / 有更新）有可视化掌控、并能在失败时一键询问 DSH 排查问题的运维型用户。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Sanqi-normal/dsh-webui-market-plugin

配置项

本插件不需要在 cordis patch 里写配置；所有面向用户的开关都在面板「安装设置」和「跨 Profile 同步」里。

环境变量（在宿主进程环境里设置）：

常见问题

Q: 这个插件和 awesome-dsh-plugin.com 是什么关系？

A: 列表直接来自 awesome-dsh-plugin.com 的 plugins.json 接口（lib/host.js:973, 1069-1077），自动跟随系统语言返回中英文描述；首次拉取失败时会回退到内置离线快照 data/catalog-snapshot.json。本地安装默认只接受精选目录里的 github: 源，目录外的会被白名单拒绝。

Q: 安装后一定要重启 Web 服务吗？

A: 简单插件（cordis.patch.yml 只有 - id: / name: 插入行）会尝试热挂载到当前运行组合并自动刷新页面生效（lib/host.js:1152-1176）；如果 patch 较复杂或环境不支持，市场会回退为「下次重启 Web 后生效」，不会自动重启宿主。

Q: 安装时遇到 pnpm 的 "Blocked build scripts" 怎么解决？

A: pnpm ≥11 默认拦截未在 allowBuilds 中放行的构建脚本。市场在任务失败时会自动把被拦截的包名加入 profile 的 pnpm-workspace.yaml 的 allowBuilds 并重试一次（lib/host.js:442-468, 685-695）；如果该依赖确实不需要执行构建脚本，把对应项写成 false（明确拒绝）即可，不会被自动重新放行。

Q: 试装验证会不会改动我的真实 profile？

A: 不会。试装验证在临时目录（mkdtempSync(tmpdir() + 'dsh-mkts-probe-')）里按 web profile 模板重建组合、用同一套 dsh CLI 装入候选插件、再以 --port 0 实际启动一次，只有出现 dsh web: 就绪行才判定可装（lib/host.js:823-893）；真实 profile 全程未被写入，验证结束无论成败都会清理临时目录。

Q: 为什么有些插件装不上（被拒绝）？

A: 默认情况下只有精选目录收录的 github: 源能通过白名单；registry/link 源不受此限制但仍走白名单 + 安装前快照；试装启动失败也会被拒并返回真实启动错误（lib/host.js:601-617）。如确需安装目录外或试装失败的插件，可勾选「跳过安全检查」（风险自负）。

Q: 怎么把装到 web 的插件同步到桌面端？

A: 面板顶部「跨 Profile 同步」区会列出本机所有已初始化的 profile（如 desktop）；点「同步到 xxx」会把 web 里已装但目标 profile 缺失的插件按本地复制方式补装过去（lib/host.js:1492-1506），同步只新增、不删除或降级目标 profile 里现有的任何内容，装完重启对应应用生效。同步携带 syncFrom 校验：仅当目标源确为源 profile 已装依赖时才放行，所以装在 web 但不在精选目录的插件（如 aegis）也能同步。

Q: 停用插件和卸载插件有什么区别？

A: 停用保留依赖与磁盘文件，只把插件从 dsh.profile.bundles 里移出并写入 dsh.market.disabled，重启后仍保持停用（lib/host.js:1284-1318）；卸载会把依赖连同 bundle 一起删除。注意：在命令行手工执行 dsh plugin add/remove/update 会触发 reconcile 短暂恢复停用项，下次市场操作或重启会再次停用。

Q: 安装/更新失败时怎么处理？

A: 失败行有「询问 DSH」按钮，点击后会在新对话里把操作目标、状态、环境信息（DSH_HOME / node / dsh 探测结果）和完整错误日志作为 prompt 发送给 AI，方便直接排查（lib/client.js:165, 740）。网络类错误（ETIMEDOUT / ECONNRESET 等）市场会自动重试一次（lib/host.js:700-707），持续失败时会提示检查代理或镜像。

Q: 一键更新全部会把所有插件都更新吗？

A: 不会。一键更新只会重新安装 updateAvailable=true 的插件（lib/host.js:1820-1840）：github 源对比 lockfile commit 与 GitHub HEAD，npm 源对比 dist-tags.latest 与已装版本，并考虑了 pnpm 11 的 24h minimumReleaseAge；本地 link/file 链接不参与检测。检测失败会静默降级为「无更新」，不会阻塞列表。

上手难度

入门 — 安装后无需任何配置就能直接用；如果自动探测 dsh CLI 失败才需要在面板填一下 apps/cli/lib/bin.js 路径或设置 DSH_BIN，绝大多数情况下零配置上手。

已知问题与限制

• 大多数插件安装后需要重启 Web 服务才能生效；只有 patch 是纯 - id: / name: 插入行的简单插件才会热挂载并自动刷新页面生效（lib/host.js:1152-1176, 1201-1217）
• 试装验证仅对 web profile 执行：非 web profile（如 desktop）的组合由对应桌面壳定义、市场无法在临时环境复刻，其安装由「来源白名单 + 安装前快照」把关，没有启动判定（README.md:66、lib/host.js:599-617）
• 在命令行手工执行 dsh plugin add/remove/update 会触发 reconcile 短暂恢复停用项，需要重启或下一次市场操作才会再次停用（README.md:75）
• 单个任务默认 120 秒超时，可在宿主环境里通过 DSH_MARKET_OP_TIMEOUT_MS 调大（如 300000）；pnpm 子进程固定以 CI 模式运行，避免无 TTY 时静默卡住（lib/host.js:32, 52-58, 656）
• pnpm 11 的 24h minimumReleaseAge 与 ERR_PNPM_IGNORED_BUILDS 拦截会自动修复并重试一次；如果在试装环境里临时批准了构建脚本，那次审批只作用于试装目录，不写入真实 profile（lib/host.js:676-695, 866-878）
• 跨 profile 同步是只新增、绝不删除或降级；如果目标 profile 已经装了同名依赖（哪怕是不同版本），同步会跳过它（lib/host.js:1492-1506）
• 写操作（install / uninstall / update / disable / enable / kill / clear）只接受同源 POST（Origin 头与 Host 一致），跨源请求一律返回 403（lib/host.js:221-230, 1822-1825, 1843-1845, 1878-1881, 1885-1887, 1900-1903, 1921-1924）

English | 中文

在 dsh web GUI 内部的社区插件市场：浏览 awesome-dsh-plugin.com 的插件目录，直接在 设置 → 插件 → 插件市场 里安装 / 卸载插件到 profile。界面风格与 harness 前端一致（跟随系统深浅色主题），支持中英文（按系统语言自动切换）。

推荐 awesome-dsh-plugin.com 网站的实现 dsh-market。

效果展示

安装

方式一：从 npm registry 安装（推荐，无 git 克隆 / prepare 脚本步骤）：

dsh plugin --profile web add @sanqi-normal/dsh-webui-market-plugin

方式二：从 GitHub 源码安装：

dsh plugin --profile web add github:Sanqi-normal/dsh-webui-market-plugin

安装后重启 web 服务生效：

pnpm dsh web

GitHub 源安装会执行包内 prepare 脚本，如被 pnpm 拦截，把提示的包名加入 profile 的 pnpm-workspace.yaml 的 allowBuilds 后重试。

pnpm 11 起，依赖树中"构建脚本未在 allowBuilds 中显式放行或拒绝"的包会直接导致 ERR_PNPM_IGNORED_BUILDS。若该包在当前 profile 不需要执行构建脚本，可把对应项写成 false（明确拒绝）而不是 true（放行执行）；市场插件的试装验证会继承真实 web profile 的 pnpm-workspace.yaml，因此这里的 true/false 决策也会作用于试装环境。

宿主依赖说明

本插件是 DSH web profile 内运行的插件，不是独立 npm 应用。以下 peer 依赖由 DSH 宿主环境提供，用户无需手动安装：

• @deepseek-ai/cordis
• @deepseek-ai/dsh-client-runtime
• @deepseek-ai/dsh-client-ui-slots

当前版本面向 DSH 0.0.1-rc.2+（不含已知解析问题的 0.0.1-rc.1）及 0.1.0-rc.2+ 环境。若使用纯 npm registry 工具解析本包，可能因为 DSH 上游部分 host 包未发布而提示依赖图不完整，这属于 DSH 宿主依赖的发布问题。

使用

打开 设置（Settings）→ 插件（Plugins）→ 插件市场（Plugin Market）：

• 目录按分类分组，支持搜索与"已安装"过滤；每个卡片显示 GitHub Star 数（无数据不显示），可一键按 最热（Star 降序，无 Star 的排最后）/ 最新（收录日期） 排序，或恢复官网默认顺序；大目录分批渐进渲染，避免打开瞬间一次性插入数百卡片造成卡顿
• 点 详情 查看该插件的官方安装命令（含目标 profile）
• 跨 Profile 安装 / 一键同步（desktop 等）：官网目录只发布 --profile web 命令，而桌面端（desktop shell）启动的是自己独立的 profile（如 desktop），市场装进 web 的插件桌面应用不会自动加载。面板顶部有 安装设置（含说明）与 跨 Profile 同步 区，自动列出本机已初始化的 profile：
  • 默认「有什么装什么」：安装设置 里的「自动同步到其它 profile」默认开启——安装插件时自动装到本机所有已初始化的 profile（有 web 装 web，有 desktop 也装 desktop；在确认框直接选了 desktop 的也会自动补装到 web）；关闭后仅装到安装时选择的 profile
  • 安装确认框可选目标 profile（默认 web）；跨 Profile 同步 区把 web 里已装的插件一键补装到目标 profile（只新增缺失项）
  • 同步是本地复制：源已在源 profile 安装过（syncFrom 校验），所以不再受目录白名单限制——装在 web 但不在精选目录的插件（如 aegis）也能同步；每个补装任务照常做安装前快照 + FIFO 队列，装完后重启对应应用生效
• 安装 / 更新 / 卸载 组成 FIFO 任务队列：多个插件可以连续排队提交，任务面板固定在右下角、不随页面滚动隐藏，实时显示「排队中 / 校验中 / 执行中 / 完成 / 失败 / 已终止 / 超时」，可取消排队项、终止执行项、查看每个任务的 pnpm 日志；每个任务默认超过 120 秒自动超时（可用环境变量 DSH_MARKET_OP_TIMEOUT_MS 调大，如 300000）；遇到 pnpm 的临时网络错误（GET ... error / ETIMEDOUT / ECONNRESET 等）会自动重试一次，持续失败时给出代理/镜像排查提示；一键更新全部会把所有可更新插件依次加入队列；队列头部「清空」可一键清除全部已完成/失败记录（逐条清除也支持），清除会同步到服务端，刷新或重新打开面板后不会再次出现
• 失败后询问 DSH：安装 / 更新 / 卸载失败（含超时、已终止、已拒绝）后，失败弹窗和任务队列的失败行会出现 询问 DSH 按钮；点击后前端会新建一个对话，并把操作目标、状态、环境信息和完整错误日志作为 prompt 自动发送给 AI，方便直接排查或解释状况
• pnpm ≥11 默认开启 24 小时 minimumReleaseAge 供应链策略：依赖里刚发布（24 小时内）的包会让所有安装/更新/卸载被 pnpm 拦截。遇到 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION 时市场会自动把违规的 name@version 合并进 profile 的 pnpm-workspace.yaml 的 minimumReleaseAgeExclude（同名多版本写成 name@v1||v2 联合，避免 pnpm 只认首条同名规则）并自动重试一次，无需手动改配置
• 停用 / 启用：停用保留依赖与磁盘文件，只把插件移出激活的 bundle 层（重启后仍保持停用）；启用按原顺序恢复，免删装；卡片操作区横向排列在卡片底部，避免右侧按钮拥挤
• 本机插件：列出所有由依赖管理的插件（含在市场之外安装的、以及未进 bundle 层的 client-only/普通依赖），标注目录内/目录外、已停用、来源类型，可直接停用、启用或卸载（内置 bundle 与本地 link/file 源不会提供删除）
• 每个插件卡片显示真实的已安装状态（与 profile 的 package.json 同步）：安装状态按「作者 + 仓库」（owner/repo）识别，目录里有同名插件（如两个作者的 dsh-memory）时，装了哪个作者就只显示哪个已安装，不会误标另一位作者的卡片；「本机插件」列表也会显示解析出的 owner/repo 身份
• 顶部显示插件目录来源官网链接，可直接打开

工作原理

持久化 bundle（package.json 的 dsh.bundle.patch → cordis.patch.yml），由 dsh plugin add 的 reconcile 自动加入 profile 的 dsh.profile.bundles 层：

• Host 半（lib/host.js）：注册 /api/dsh-market 路由，提供 list（读取官网 JSON API plugins.json，失败回退内置离线快照，含 stars/added；与官方 dsh-market 一致：先试官网 JSON，再用过期缓存，最后落离线快照，不解析官网 HTML）、probe（环境探测，含本机已初始化 profile 列表）、installed / installedAll（读取 profile package.json 与已装包 manifest）、syncPlan（跨 profile 只读差异：web 已装、目标 profile 缺失的插件清单）、install / update / updateAll / uninstall（FIFO 队列 + 后台 spawn dsh plugin CLI，白名单在队列头对所有 profile 执行、试装验证仅对 web 执行）、disable / enable（停用/启用并持久化到 dsh.market.disabled）、op（队列快照）、kill（终止/取消任务）
• Client 半（lib/client.js）：通过 exports["./client"] + dsh.client 声明被 web 前端加载，注册到 settings.plugins.tab 槽位

安全与限制

• 来源白名单：安装只接受精选目录（awesome-dsh-plugin.com curated registry）收录的 github: 源，目录外的一律拒绝，与 dsh-market 的白名单策略一致（目录抓取失败或 registry/link 源不做此限制）；该白名单对所有目标 profile（含 desktop 同步）生效，勾选"跳过安全检查"才可绕过
• npm 优先（官方同款镜像策略）：目录条目带 npm 映射时，优先用 npm 包名安装/更新（npm tarball 走 CDN/镜像，不依赖 GitHub 下载）；只有未发布 npm 的 GitHub-only 插件才走 GitHub 源。用户可在 npm/pnpm 配置中设置国内 registry 镜像（如 registry=https://registry.npmmirror.com），npm 源的安装/更新会自动走该镜像
• 试装验证（trial boot）：白名单通过后，若插件未声明 web client 半端（dsh.client.platform === 'web'），会先做试装验证：在临时 DSH_HOME 里按 web profile 模板重建组合，用同一套 dsh plugin add 装入候选插件，再以 --port 0（系统空闲端口）实际启动一次，只有出现 dsh web: 就绪行（Loader 树成功结算后才打印）才判定可装。验证失败会给出真实的启动错误（如重复 api-gateway / webserver 等）并拒绝安装，此时真实 profile 从未被写入、试装目录自动清理，无需任何回退操作。试装验证仅对 web profile 执行：非 web profile（如 desktop）的组合由对应桌面壳定义、市场无法在临时环境复刻，其安装由「来源白名单 + 安装前快照」把关（同样无破坏性，只是没有启动判定）。试装环境会继承真实 web profile 的 pnpm-workspace.yaml（allowBuilds / minimumReleaseAgeExclude），因此已在真实 profile 中显式拒绝（false）的构建脚本不会在试装时被重新放行或执行。
• 跨 profile 同步只增不删：syncPlan 只计算「web 已装、目标缺失」的插件，且要求目标 profile 已初始化（避免误建空 profile）；同步仅补装、绝不删除或降级目标 profile 里已有的任何内容。同步安装携带 syncFrom 来源校验：仅当目标源确为源 profile 已装依赖时才放行（本地复制，不视为新的远端信任决策），未通过校验的仍走目录白名单；装到 desktop 等 profile 后需重启对应应用生效
• 同源校验：install / uninstall / update / kill 写操作只接受同源 POST（Origin 头与 Host 一致），跨源请求一律 403
• 热挂载（免重启）：安装成功后，若新插件的 cordis.patch.yml 是纯 id/name 插入行，会尝试挂入运行中的组合并自动刷新页面生效（无需手动操作）；patch 复杂或环境不支持时回退"重启生效"。热挂载输入存于 <profile>/.dsh-market/，每次启动自动清理；热挂载、热卸载与 Loader 停用/启用只作用于运行中的 web profile，desktop 等其它 profile 的操作不会触碰 web 的运行态
• 更新检测与更新：已安装插件卡片自动显示"更新"按钮（github 源对比 lockfile 锁定 commit 与 GitHub HEAD；registry 源对比 npm latest 与已装版本；本地 link/file 源不检测），点击即重新解析最新版本并作为后台任务执行，完成后下次重启生效；检测失败静默降级为"无更新"，不会阻塞列表。github 源更新时会把检测到的 HEAD commit 写成 github:owner/repo#<sha> 再执行，避免 pnpm 走 git ls-remote（SSH）解析 HEAD 时因未配置 SSH key 报 Permission denied (publickey)
• 离线目录快照：data/catalog-snapshot.json 作为官网抓取失败时的离线兜底，可用 pnpm run snapshot 从官网 JSON API 直接抓取刷新（不走回退链，官网不可达时会失败而非复制旧数据）
• 安装前自动快照：写入任一 profile 前会把 package.json 备份为同目录 .mkts-snapshot-<时间戳>.json（跨 profile 同步与"跳过安全检查"的安装同样备份），配合 dsh plugin --profile <name> remove <包名> 可手工回退
• CI=true：pnpm 子进程以 CI 模式运行，避免无 TTY 时静默卡在交互提示
• 网络超时控制：pnpm 子进程默认使用较短的 fetch-timeout（30s）和 fetch-retries（1），避免弱网下"GET 链接 error 一直 retry"拖到任务超时；可用 DSH_MARKET_FETCH_TIMEOUT_MS、DSH_MARKET_FETCH_RETRIES、DSH_MARKET_FETCH_RETRY_MINTIMEOUT_MS、DSH_MARKET_FETCH_RETRY_MAXTIMEOUT_MS 覆盖；前端 /api/dsh-market 请求默认 30 秒超时，防止面板因外部网络卡死
• 停用持久化：停用状态写入 profile package.json 的 dsh.market.disabled（保留依赖、移出 dsh.profile.bundles）；市场在启动时和每次 pnpm 操作后会重新应用该集合。注意：在命令行手工执行 dsh plugin add/remove/update 会触发 reconcile 短暂恢复停用项，重启或下一次市场操作会再次停用
• 安装 / 卸载后需重启 web 服务生效（热挂载成功的除外，本插件不做自动重启）
• 目录数据来自官网 JSON API（plugins.json，与 dsh-market 同源，含 Star 数），抓取失败时按「过期缓存 → 内置离线快照」回退（与官方 dsh-market 策略一致，不再解析官网 HTML 静态页）；插件数量与分类以官网为准