dsh-find-plugin

One-Sentence Description

A "plugin for finding plugins" — enables agents to directly search the entire DSH plugin ecosystem within a conversation, returning candidate lists sorted by star count along with ready-to-use installation commands, eliminating the need to manually browse GitHub and documentation sites.

Core Capabilities

• Trigger plugin search in agent conversations: Call the find_dsh_plugin tool with keywords to get a list of relevant plugins
• Real-time GitHub search: Search public repositories tagged with dsh-plugin topic, sorted by star count in descending order
• Awesome list priority: When a repository matches the awesome-dsh-plugin curated list, display the human-written bilingual descriptions first (without changing the ranking)
• Ready-to-use installation commands: Each result includes a ready-made dsh plugin add command that the agent can execute directly
• Built-in memory caching: GitHub search results cached for 5 minutes per keyword, curated list cached for 1 hour; falls back to bundled offline snapshots on offline/failure
• Tool timeout: 10 seconds overall timeout, 4 seconds per GitHub request to avoid slowing down the agent

Technical Implementation

• Language: TypeScript (target: ES2022, ESM)
• Key dependencies: @deepseek-ai/cordis ^4.0.1, @deepseek-ai/dsh-tools ^0.1.0-rc.6, node:fetch (built-in)
• Architecture pattern: Inserts itself into the profile's layer stack via cordis.patch.yml; declares inject = ['tools'] in apply(ctx) and registers the find_dsh_plugin tool to ctx.tools
• Entry files: src/index.ts (coordinates tool registration), src/github.ts (GitHub search + caching), src/registry.ts (curated list fetching + snapshot fallback)

Use Cases

When users encounter questions like "I want a plugin that can do X but DSH doesn't have it" or "What TUI tools are available in DSH now?", the agent can proactively call this tool to provide candidates. A common pain point is users manually searching on GitHub, comparing repositories, and constructing installation commands — this plugin compresses this entire workflow into a single conversation and brings back trusted descriptions from the curated list to reduce the chance of hitting pitfalls.

Prerequisites & Compatibility

Installation

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

Configuration

This plugin requires no additional configuration — no Schema, no environment variables, no config files. All tunable parameters are passed when calling the find_dsh_plugin tool:

FAQ

Q: What specific functionality does this plugin add after installation?

A: It adds a single agent tool called find_dsh_plugin. Regular users won't notice any difference, but when they tell the agent "I want to find a plugin that can do X," it will automatically invoke this tool.

Q: Will search results prioritize official recommended plugins?

A: Sorting is based solely on star count, with no distinction between official/community. However, plugins in the curated list will have their GitHub default descriptions replaced with human-written ones to help quickly assess capabilities.

Q: Do I need a GitHub token or API key?

A: No. The plugin uses the anonymous GitHub Search API (10 req/min rate limit) and relies on 5-minute local caching to keep actual request volume very low.

Q: Can it still be used when offline or GitHub rate-limited?

A: GitHub search failures will throw an error directly (letting the agent know to try different keywords); curated list fetch failures will fall back to the built-in data/registry-snapshot.json offline snapshot, ensuring curated descriptions remain available.

Q: Will the returned commands be executed automatically?

A: No. The tool only returns the command string; execution is left to the agent's decision. The installed code is third-party — please review the source code yourself and lock to a specific commit.

Q: How long is the search cache? Will the same keyword hit GitHub repeatedly?

A: Results are reused within 5 minutes for the same keyword (using lowercased, trimmed query as key); curated list has 1-hour caching.

Q: Do I need to restart after installation?

A: Yes, restart dsh web. Tools are registered to the tools service via cordis at startup; runtime hot-plugging won't take effect automatically.

Q: How do I uninstall it?

A: Use dsh's standard plugin removal command (dsh plugin remove); this plugin writes no user files and has no background processes — uninstallation is complete cleanup.

Difficulty

Beginner — just install and restart to use; zero configuration. The only thing to remember is the trigger keyword (describe the capability), and the agent will automatically decide whether to call the tool.

Known Issues & Limitations

• Empty search results only suggest trying different keywords or browsing the curated site — no fallback recommendations
• Anonymous GitHub Search API has a 10 req/min rate limit; high-frequency same-query requests may still be throttled
• Sorting relies entirely on star count, not considering factors like activity, maintenance status, or security audits
• Single GitHub request has a 4-second timeout; occasional slow responses from GitHub will cause that request to fail
• Overall tool invocation has a 10-second timeout, including curated list fetching; may fail entirely under weak network conditions

English | 中文

A plugin that finds plugins — think /find-skills from skills.sh, for DSH.

Tell your agent what you want ("notify me on WeChat when a task finishes"), and it searches the DSH plugin ecosystem on GitHub for you — top results by stars, each with a one-line description and an install command.

Install

# from npm (prebuilt, recommended)
dsh plugin --profile web add dsh-find-plugin

# or from GitHub
dsh plugin --profile web add github:awesome-dsh-plugin/dsh-find-plugin

Usage

Restart dsh web after installing, then just talk to the agent — it calls find_dsh_plugin on its own whenever plugin discovery helps:

• "What terminal TUI plugins are there?"
• "I want to get a WeChat notification when a task finishes — any plugin for that?"
• "Find me something for reviewing git diffs inside DSH."

Each result comes back with stars, a description, the repo link, and a ready-to-run dsh plugin add command — ask the agent to install one and it can run the command for you.

How it works

• Live GitHub repository search scoped to the official dsh-plugin topic, re-ranked by stars (5-minute per-query cache, anonymous API).
• When a result is also listed on awesome-dsh-plugin, its hand-written bilingual description from plugins.json replaces the GitHub one (the lang parameter picks the language) — ranking is untouched.
• Every result comes with a ready-to-run dsh plugin add command. Plugins are third-party code — review the source and pin a commit.

License

MIT © awesome-dsh-plugin