dsh-find-plugin

一句话定位

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

核心能力

在 agent 对话中触发插件搜索：调用 find_dsh_plugin 工具，输入关键词即可返回相关插件列表
实时搜索 GitHub 上打了 dsh-plugin topic 的公开仓库，按 star 数降序排列
命中 awesome-dsh-plugin 精选列表的仓库时，优先展示列表中人工撰写的双语描述（不改变排名）
每条结果附带现成的 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 等任何原生绑定

安装方式

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 秒超时，包含精选列表拉取，弱网下可能整体失败