dsh-plugin-library-search

Readme

# dsh-plugin-library-search

DSH（DeepSeek Harness）插件：在 **设置 → 插件** 页搜索 GitHub 官方插件库，瀑布流浏览并一键安装。

- 安装后在 **设置 → 插件** 页出现「**插件库搜索**」标签页，位于「插件列表」右侧。
- 对接 GitHub 官方插件库：<https://github.com/topics/dsh-plugin>（经 GitHub Search API，按 Star 排序，可搜索）。
- 瀑布流卡片，从上到下：**插件图片 → 插件名称 → 插件描述**。
- 每张卡片提供 **安装** 按钮与 **跳转 GitHub 插件页** 链接。

## 界面预览

设置 → 插件 → 「插件库搜索」标签页：

![插件库搜索界面](docs/screenshot-plugin-library.jpg)

## 安装

```sh
# 从 npm 发布（推荐）
dsh plugin --profile web add dsh-plugin-library-search

# 或直接从本 GitHub 仓库安装（无需 npm 发布）
dsh plugin --profile web add "github:AiLi1337/dsh-plugin-library-search"
```

安装完成后**重启 dsh web**（本插件是 bundle 插件，进 `dsh.profile.bundles` 层栈），
刷新浏览器后进入 设置 → 插件 → 插件库搜索。

## 使用

1. 打开 **设置 → 插件**，点击右侧的「**插件库搜索**」标签。
2. 默认展示官方插件库按 Star 排序的仓库列表；可在搜索框输入关键词（名称/描述/作者）过滤。
   滚动到列表底部会自动加载下一页（无限滚动，每页约 100 个，最多加载 500 个），
   状态栏显示「正在加载更多…」与总数进度。
3. 点击卡片上的 **安装** 按钮：
   - 插件会自动解析仓库 `package.json` 里的 npm 包名，优先 `pnpm add <npm包名>`；
     若未发布到 npm，回退为 `pnpm add github:<owner>/<repo>`。
   - **bundle 插件**（声明 `dsh.bundle`）安装后写入 `dsh.profile.bundles` 层栈，**重启 dsh web 后生效**；
   - **纯 cordis 插件**安装后写入 profile 的 `cordis.patch.yml` insert 行，**配置 HMR 实时挂载**，刷新页面即可看到。
4. 点击「GitHub ↗」在新标签页打开插件仓库。

> 提示：topic:dsh-plugin 下包含大量非可安装内容（文档、皮肤、桌面壳等），
> 安装按钮会给出失败原因；此时可到仓库页查看其实际安装方式。

## AI 调用（模型可直接搜索/安装插件）

插件通过官方 `tools` 服务注册了三个工具，模型（agent）可以直接调用：

| 工具 | 作用 |
|---|---|
| `plugin_library_search` | 搜索官方插件库（topic:dsh-plugin，按 Star 排序，分页 `page` 参数，可带 `query` 过滤） |
| `plugin_library_install` | 按 `owner/name` 安装插件（自动解析 npm 源，git 源回退；与页面安装按钮同一机制） |
| `plugin_library_installed` | 列出当前 profile 已安装的插件 |

在对话里直接说「帮我搜索一下插件库里的 xxx 插件」或「安装 vlln/plugin-registry」，
模型就会调用这些工具。重启后新会话即可看到工具。

## 加载失败（HTTP 403）怎么办

GitHub 搜索 API 未认证限流只有 **10 次/分钟**（超限返回 HTTP 403）。本插件已内置两层缓解：

1. **自动回退**：API 被限流/失败时自动改抓取 `github.com/topics/dsh-plugin` 页面
   （网页通道无认证配额限制），无需任何配置即可继续浏览。
2. **推荐配置令牌**：在启动 dsh 的环境里设置 `GITHUB_TOKEN`（或 `GH_TOKEN`），
   搜索配额提升到 30 次/分钟；宿主端另有 5 分钟缓存进一步减少请求。

## 工作原理

- **宿主端**（`lib/index.js`）：注册 `webServer` 路由
  - `GET /dsh-plugin-library-search/api/search?q=` — 代理 GitHub 搜索 API（topic:dsh-plugin，
    带缓存；限流时自动回退抓取 topic 页面 HTML，查询词在结果上过滤）
  - `GET /dsh-plugin-library-search/api/installed` — 当前 profile 已安装插件名
  - `POST /dsh-plugin-library-search/api/install` — 解析安装源 → `pnpm add` → 按官方机制挂载
  - `GET /dsh-plugin-library-search/client.js` — 自托管浏览器端 bundle，并通过 `webServer.tapIndex`
    注入 `window.__DSH_BOOT__` 引导图行
- **浏览器端**（`lib/client.js`）：以 DSH module-loader 格式注册
  `settings.plugins.tab` 槽位（`order: 20`，位于内置「插件列表」`order: 10` 右侧），
  渲染瀑布流 UI。

## 已知限制

- GitHub 搜索 API 未认证限流 10 次/分钟；插件在 API 失败时自动回退到 topic 页面抓取，
  结果一致但排序为 topic 默认顺序（非按 Star）；设置 `GITHUB_TOKEN` 可提升配额。
- 一键安装依赖 `pnpm` 在 web 服务进程的 PATH 中（与官方 `dsh plugin` 相同的要求）。
- 从 git 源安装的仓库若带 prepare 脚本，pnpm 可能需要先在 `pnpm-workspace.yaml` 的
  `allowBuilds` 中放行（与官方提示一致）。
- 安装后插件列表的「已安装」标记基于包名匹配；未发布到 npm 的仓库以安装成功响应为准。

## License

MIT