# dsh-find-plugin

> 在 agent 内搜索 DSH 插件生态：实时 GitHub topic 搜索+精选列表双语描述，按 star 排序返回可执行安装命令。

## Metadata

- Author: [@awesome-dsh-plugin](https://github.com/awesome-dsh-plugin)
- Repo: <https://github.com/awesome-dsh-plugin/dsh-find-plugin.git>
- GitHub: [awesome-dsh-plugin/dsh-find-plugin](https://github.com/awesome-dsh-plugin/dsh-find-plugin)
- Stars: 69
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `deepseek-harness`, `dsh`, `dsh-plugin`
- Forks: 2
- Open Issues: 1
- Last push: 2026-08-19T05:24:43.000Z
- Added: 2026-08-14T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:awesome-dsh-plugin/dsh-find-plugin
```

## Wiki

## 一句话定位
一个"找插件的插件"——让 agent 在对话里直接搜索整个 DSH 插件生态，按 star 数返回候选清单和现成的安装命令，免去手动翻 GitHub 和文档站。

## 核心能力
- 在 agent 对话中触发插件搜索：调用 `find_dsh_plugin` 工具，输入关键词即可返回相关插件列表
- 实时搜索 GitHub 上打了 `dsh-plugin` topic 的公开仓库，按 star 数降序排列
- 命中 [awesome-dsh-plugin](https://awesome-dsh-plugin.com) 精选列表的仓库时，优先展示列表中人工撰写的双语描述（不改变排名）
- 每条结果附带现成的 `dsh plugin add` 安装命令，agent 可直接代为执行
- 内置内存缓存：GitHub 搜索每关键词 5 分钟缓存、精选列表 1 小时缓存，离线/失败时回落到打包的离线快照
- 工具超时 10 秒、单查询 GitHub 请求 4 秒超时，避免拖慢 agent

## 技术实现
- **语言**: TypeScript（`target: ES2022`，ESM）
- **关键依赖**: `@deepseek-ai/cordis` ^4.0.1、`@deepseek-ai/dsh-tools` ^0.1.0-rc.6、`node:fetch`（内置）
- **架构模式**: 通过 `cordis.patch.yml` 把自己插入到 profile 的 layer 栈里；在 `apply(ctx)` 中声明 `inject = ['tools']`，并向 `ctx.tools` 注册 `find_dsh_plugin` 工具
- **入口文件**: `src/index.ts`（协调工具注册），`src/github.ts`（GitHub 搜索 + 缓存），`src/registry.ts`（精选列表拉取 + 快照兜底）

## 适用场景
当用户遇到"我想要一个能 X 的插件但 DSH 没有"或"DSH 里现在有哪些 TUI 工具？"这类问题时，agent 可主动调用该工具给出候选。常见痛点是用户在 GitHub 手动搜、对比仓库、拼安装命令——本插件把这套流程压缩成一句话对话，并把精选列表里的可信描述带回来降低踩坑概率。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness (cordis) | ^4.0.1 | peerDependency，插件通过 cordis 服务挂载 |
| @deepseek-ai/dsh-tools | ^0.1.0-rc.6 | peerDependency，提供 defineTool |
| Node | 未声明 | 源码使用 `AbortSignal.timeout` 等 Node 内置 API，无 engines 字段 |
| 平台 | 跨平台 | 无 os/cpu 限制；纯网络调用，不涉及原生模块 |
| 原生模块 | 无 | 不依赖 node-pty、node:sqlite 等任何原生绑定 |

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

## 配置项
本插件无需额外配置——无 Schema、无环境变量、无配置文件。所有可调参数都在 `find_dsh_plugin` 工具调用时传入：

| 参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `query` | 字符串（必填） | 描述想找的能力的关键词，例如 `wechat notifications`、`TUI`、`跨会话记忆` | — |
| `limit` | 数字 | 返回结果数量上限（内部夹紧到 1–20） | 8 |
| `lang` | 字符串 | 精选条目优先使用的描述语言（`en` / `zh` 等） | `en` |

## 常见问题
**Q: 这个插件装上后具体多了什么功能？**

A: 多了一个名为 `find_dsh_plugin` 的 agent 工具。普通用户感受不到差异，但跟 agent 说"我想找个能做 XX 的插件"时，它会自动调起来。

**Q: 搜索结果会优先显示官方推荐的插件吗？**

A: 排序只看 star 数，不区分官方/社区。但精选列表里的插件会用人工写的描述替换 GitHub 默认描述，方便快速判断能力。

**Q: 需要 GitHub token 或 API key 吗？**

A: 不需要。插件用匿名 GitHub Search API（10 req/min 上限），并靠 5 分钟本地缓存把实际请求量压得很低。

**Q: 离线或 GitHub 限流时还能用吗？**

A: GitHub 搜索失败会直接抛错（让 agent 知道需要换关键词）；精选列表拉取失败会回落到内置的 `data/registry-snapshot.json` 离线快照，保证精选描述这部分仍可用。

**Q: 返回的命令会直接执行吗？**

A: 不会。工具只返回命令字符串，是否执行交给 agent 决策；安装的是第三方代码，请自行审阅源码并锁定 commit。

**Q: 搜索缓存多久？同一关键词会重复打 GitHub 吗？**

A: 同一关键词 5 分钟内复用结果（按小写 trim 后的 query 作 key）；精选列表 1 小时缓存。

**Q: 装好后需要重启吗？**

A: 需要重启 `dsh web`。工具是在启动时通过 cordis 注册到 `tools` 服务的，运行时插拔不会自动生效。

**Q: 想卸载怎么操作？**

A: 走 dsh 标准的插件移除命令即可（`dsh plugin remove`）；本插件不写入用户文件、无后台进程，卸载即清理。

## 上手难度
入门 — 装完重启即可使用，零配置；唯一需要记住的是触发关键词（描述能力即可），agent 会自动判断要不要调用工具。

## 已知问题与限制
- 搜索结果为空时只提示换关键词或去精选站浏览，不返回兜底推荐
- 匿名 GitHub Search API 有 10 req/min 速率限制，高频同 query 之外仍可能受限
- 排序完全依赖 star 数，不考虑活跃度、维护状态、安全审计等维度
- 单次 GitHub 请求 4 秒超时，GitHub 端偶发慢响应时该次会失败
- 工具调用整体 10 秒超时，包含精选列表拉取，弱网下可能整体失败

---

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