# dsh-plugin-workshop

> DSH 插件工坊：免服务器，直接在 DSH Web 侧栏浏览/搜索/安装/卸载第三方插件，支持中文关键词、GitHub 趋势窗口与本地插件管理。

## Metadata

- Author: [@yyyyukari](https://github.com/yyyyukari)
- Repo: <https://github.com/yyyyukari/dsh-plugin-workshop.git>
- GitHub: [yyyyukari/dsh-plugin-workshop](https://github.com/yyyyukari/dsh-plugin-workshop)
- Stars: 25
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `deepseek-harness`, `dsh`, `dsh-plugin`, `workshop`
- Forks: 3
- Open Issues: 3
- Last push: 2026-08-17T14:53:20.000Z
- Added: 2026-08-16T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:yyyyukari/dsh-plugin-workshop
```

## Wiki

## 一句话定位
在 DSH Web UI 侧栏里嵌入一个类似 Steam 创意工坊的插件浏览器，免部署、纯用 GitHub 做目录，支持搜索、中文关键词、热度/飙升榜、一键安装/卸载与本地插件管理。

## 核心能力
- 侧栏常驻入口：在 DSH 侧栏「新会话」按钮正下方克隆出一个「🧩 插件工坊」按钮，样式与官方一致，刷新和重启后自动恢复。
- 默认只搜 DSH 插件：默认查询 `topic:dsh-plugin`，结果自动过滤官方核心仓库；想看全站时还会做插件特征校验（识别 `package.json` 的 `dsh` 字段或 `cordis.yml`）。
- 搜索与排序：支持中文关键词自动映射英文（内置「天气→weather」「翻译→translate」等词表）；可按最热、最新、近 7/30/90 天飙升排序。
- 智能一键安装/卸载：详情页先预检仓库结构，按 bundle（标准插件包）/nested（monorepo 内单包）/preset（无 dsh 声明）/multi（多包）四类走不同路径；不可一键安装的会降级为「按作者给出的命令手动安装」。
- 已安装管理：「📦 已安装」视图合并 profile 依赖、激活行、本地预设三类来源，展示插件类型、激活状态与安装来源，支持一键更新和卸载。
- 双语体验：描述可一键切换原文/机翻中文，详情页可整篇翻译 README（Google gtx，有缓存）。
- 额度透明：实时显示 GitHub 搜索剩余额度与恢复倒计时；可选填 GitHub Personal Access Token 把额度从 10 次/分提到 30 次/分。

## 技术实现
- **语言**: JavaScript（宿主侧用 ESM，浏览器侧由 `scripts/build.mjs` 打成 CJS 注入到平台）
- **关键依赖**: 宿主侧仅使用 Node.js 内置模块（`node:child_process`、`node:fs`、`node:crypto`、`node:http`/`node:https`）；浏览器侧通过平台种子 require `react`；数据源为 `api.github.com` + `raw.githubusercontent.com` + Google gtx 翻译
- **架构模式**: 双端架构 —— 宿主侧 (`lib/index.js`) 在 `webServer` 服务上注册同源 HTTP 路由负责安装/卸载/更新与预检；客户端 (`lib/client.js`) 以 React 浮层 + DOM 克隆官方按钮的方式常驻侧栏；通过 `package.json#dsh.bundle.patch` 自动加入 profile bundles 实现一键激活
- **入口文件**: `lib/index.js`（宿主）、`lib/client.js`（浏览器，构建自 `src/client/index.js`）

## 适用场景
DSH 用户想找一个集中的地方浏览 GitHub 上散落的第三方插件，而不想自己挨个搜仓库。工坊把搜索、特征校验、热度排序、装机预览、一键安装/更新/卸载都封装在侧栏按钮里，对不爱自己折腾命令行的人比较友好。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 未声明 | 需要 DSH 支持 `webServer` 服务注册和 `dsh.bundle.patch` 机制（README 演示使用 `dsh plugin --profile web add` 命令） |
| Node.js | 未声明 | 宿主侧使用 `node:crypto` 的 `randomUUID`、浏览器端使用 `AbortSignal.timeout`，实际需要较新的 Node 运行时（DSH 自带） |
| 平台 | 跨平台（搜索/浏览）；一键安装/卸载仅 Windows 顺畅 | 详情见下方「已知问题」 |
| 原生模块 | 无 | 仅依赖 Node 内置模块，不引入任何 native binding |
| 其他 | 可选 Git 客户端 | 一键安装/更新通过 `git clone` / `git pull` 工作，缺失时界面会明确提示 |

## 安装方式
```bash
dsh plugin --profile web add github:yyyyukari/dsh-plugin-workshop
```

## 配置项
本插件没有需要在前端填写或宿主配置面板里设置的选项；下面两项是可选的环境变量，只在你启用社区统计徽章时才需要。

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `DSH_HOME` | 环境变量 | 宿主侧用来定位 profile 目录、`.agent-presets`、cordis 补丁文件等 | `~/.dsh` |
| `DSH_WORKSHOP_STATS_URL` | 环境变量 | 可选：指向自部署的统计服务地址；不设置则工坊保持零服务器模式，只用 GitHub 搜索 | 不设置 |

> 插件侧还有一处内置浏览器 localStorage：`dsh-plugin-workshop:token`，保存 GitHub PAT；只存在本机浏览器、清浏览器数据即丢。

## 常见问题

**Q: 装上之后插件界面在哪里？**

A: 打开 DSH Web UI，侧栏「新会话」按钮正下方会出现「🧩 插件工坊」；另外「设置 → 插件」里也会多一个工坊标签页。

**Q: 和 DSH_Creative_Workshop 这种集中市场型方案有什么区别？**

A: 工坊走零基础设施路线 —— 不部署自己的目录服务、不做账号体系，搜索/热度/装机量都来自 GitHub 公开 API；缺点是搜索结果受 GitHub 搜索 API 限速（匿名 10 次/分）影响。

**Q: 装机徽章和真·飙升榜怎么开？**

A: 默认是关闭的（零服务器模式）。按 `remote/README.md` 部署 Cloudflare Worker + D1，给 `dsh web` 进程设置环境变量 `DSH_WORKSHOP_STATS_URL=https://你的子域.workers.dev` 后重启，插件会自动上报 install/update/uninstall 事件并展示社区装机徽章与真实飙升榜。

**Q: 安装失败时报错「带 prepare 构建脚本被 pnpm 拦截」怎么办？**

A: 这是被 pnpm 默认拒绝的构建脚本触发的。需要按报错提示，在 profile 目录的 `pnpm-workspace.yaml` 里把对应包的 `onlyBuiltDependencies` / `allowBuilds` 加进去，再重试一键安装。

**Q: 卸载时显示「pnpm remove 失败，未做任何改动」会留垃圾吗？**

A: 不会。工坊遵循「失败不动」原则 —— `pnpm remove` 失败时不会去删激活行或本地副本，profile 里的依赖条目保持原状，重试或手动处理后插件仍然可用。

**Q: 一键安装按钮是灰色 / 详情页显示「建议手动」是为什么？**

A: 详情页的预检（probe 接口）会按 bundle/nested/preset/multi 四类评级。当仓库是多包 monorepo、根目录没有 `dsh` 声明也没有 `cordis.yml`、带 `prepare` 构建脚本，或本机非 Windows 时，会被标记为「有风险」或「建议手动」，并把从 README 提取出来的安装命令展示给你复制执行。

## 上手难度
入门 — 安装就一条 `dsh plugin add` 命令，激活后侧栏按钮可直接点开使用；只有想启用社区装机徽章时才需要额外部署 Cloudflare Worker。

## 已知问题与限制
- 一键安装/更新/卸载通过 Windows 的 `cmd /c` 通道调度 `dsh` 命令；macOS / Linux 上预检会被降级为「有风险/建议手动」（`lib/index.js:552`），需要走详情页里提取的手工安装命令。
- 卸载成功后，只有命令行版 `dsh web`（Windows）会自动重启刷新插件表；运行在桌面 App（Electron）里的 DSH 不会自我重启，需要你手动重启 App（`lib/index.js:362-373`）。
- 预检结果有 10 分钟缓存，期间同一仓库结构变化不会立即反映（`lib/index.js:39, 526`）。
- GitHub 搜索结果里的「最热」用的是 stars 数近似热度；要得到按实际安装净增长的「真·飙升榜」需要部署 `remote/` 下的 Worker。
- 匿名搜索额度受 GitHub 限制（10 次/分），触顶后会被提示去 ⚙ 里填 Token；Token 仅存在 localStorage（`src/client/index.js:34-36`）。
- 插件宿主侧代码会在 Windows 上向 `C:/Users/Administrator/workshop-host-probe.txt` 写一条 `apply ran: <时间>` 的探针日志（`lib/index.js:439`），属于诊断痕迹，不影响功能但可能引起注意。

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-plugin-workshop](https://deepseek-plugin.org/plugins/yyyyukari/dsh-plugin-workshop)
Wiki generated by AI (model: `MiniMax-M3`)