dsh-plugin-store

Readme

# dsh-plugin-store · Plugin Radar

**English** | [简体中文](README.zh-CN.md)

An **App-Store-style plugin radar** for DeepSeek Harness (dsh). It installs as a normal dsh bundle and adds a **「Plugin Radar」** entry to the web Settings page.

- Probes plugins using the **same methods the radar/marketplace implementations actually use**, not README scraping:
  - `https://dsh.do/api/packages` — official dsh.do catalog API, paginated full catalog (4419+ packages).
  - `https://awesome-dsh-plugin.com/plugins.json` — curated registry (1247+ entries with categories, bilingual descriptions, install commands).
  - GitHub Search `topic:dsh-plugin` — both `sort=stars` and `sort=updated` slices.
- Browse plugins by **stars / practicality score / category / search / recency**.
- **Manual or automatic refresh** every 15 / 30 / 60 / 120 minutes.
- Source-aware one-click **install / uninstall**: npm install commands from the catalog are preferred over GitHub source URLs (e.g. **modlens** installs from npm), with GitHub as the fallback; copy commands include the current profile.
- Proper DSH **bundle plugin** (`dsh.bundle.patch`), so it also shows up in the native Plugins page after installation.
- Avatar preloading + caching to avoid icon flicker.

## Why this over similar plugin radars / marketplaces?

| Area | Typical radar / marketplace | This plugin |
| --- | --- | --- |
| Data source | Scrapes README links, or only one GitHub search page, or only pushes a card stream | Uses dsh.do official catalog API + curated registry JSON + stars/updated GitHub search slices, the same data paths the original implementations use |
| Coverage | Often truncated at 1000 repos or a single topic page | dsh.do full catalog pagination (4419+) merged with curated registry and GitHub slices |
| Ranking | Usually star-only or update-only | Transparent **practicality score** (stars, description quality, topic, curated status, recency, homepage/language) + star/update/name sorting |
| UX | Floating card streams, chat-skill flows, or bare tables | Native Settings page with hero, category chips, search, sort, pagination, and install/uninstall buttons |
| Install type | Some are skills, some require manual `cordis.patch.yml` edits | A real `dsh.bundle` package: `dsh plugin add` mounts it into the profile plugin tree |
| Refresh | Fixed interval or manual only | User-selectable manual / 15 / 30 / 60 / 120 min, persisted across restarts |
| Icons | Raw `<img>` lists can flicker | Avatar preload + cache + graceful fallback |
| Local testing | Often publish-first | `scripts/test-local.sh` runs a throwaway dsh web instance without publishing |

## Install

> Note: the npm package name `dsh-plugin-store` may already be taken. Rename `name` in `package.json` and the id in `lib/client.js` before publishing.

```bash
# from npm
dsh plugin --profile web add dsh-plugin-store

# or from git
dsh plugin --profile web add https://github.com/<your-name>/dsh-plugin-store.git
```

Then restart / refresh the dsh web UI. Open Settings and you should see **Plugin Radar**.

## How install targets are chosen

The radar no longer installs every plugin from its GitHub URL. For each probed plugin the host resolves a preferred install spec in this order:

| Priority | Source | Example | Notes |
| --- | --- | --- | --- |
| 1 | `installCommandNpm` from dsh.do | `@liustack/modlens` | Preferred: published npm packages include their `dist` files and work out of the box. |
| 2 | `installCommandGit` from dsh.do | `https://github.com/owner/repo.git` | Used when no npm command is available. |
| 3 | curated `install` from awesome-dsh-plugin | npm or git spec | Community-curated command. |
| 4 | GitHub URL fallback | `https://github.com/owner/repo.git` | Used only when the data provides no install command. |

Each card shows an install-source badge (`npm install` / `git install` / `GitHub install`), and both the install button and the copy button use the same resolved spec. For example, **modlens** is installed as `dsh plugin --profile web add @liustack/modlens`, not from its GitHub source repository.

## Local test without publishing

```bash
./scripts/test-local.sh 34129
```

This copies the plugin into a throwaway `DSH_HOME` and starts a separate `dsh web` on the given port.

## Data sources

| Source | Description | GitHub token |
| --- | --- | --- |
| `github-topic:stars` | GitHub Search `topic:dsh-plugin`, sorted by stars | optional |
| `github-topic:updated` | GitHub Search `topic:dsh-plugin`, sorted by recently updated | optional |
| `dsh.do` | Official catalog API `https://dsh.do/api/packages`, paginated | none |
| `curated:awesome-dsh-plugin` | Curated registry `https://awesome-dsh-plugin.com/plugins.json` | none |

Set `DSH_GITHUB_TOKEN` / `GITHUB_TOKEN` to raise GitHub API limits. `DSH_GITHUB_API` overrides the API base.

## Submit this plugin to the dsh ecosystem

1. **Add the `dsh-plugin` topic to the GitHub repository** — this is the key step and the officially recommended way. The official and third-party plugin markets will then discover the repo automatically.
2. **Optional: submit to the community curated list**
   - Fork the `awesome-deepseek-harness` repository.
   - Add this plugin to both `README.md` and `README.zh-CN.md` in the format required by that repo.
   - Open a Pull Request.
   - Note: the official main repository currently does not accept external PRs (`CONTRIBUTING.md` states this). The correct way to build the DSH plugin ecosystem today is **topic tagging + community curation**.
3. Best practice: ship the plugin first, tag it with `dsh-plugin`, then submit it to the community list for extra visibility.

## Development

```bash
node --check lib/index.js
node --check lib/probe.js
node --check lib/client.js
node --test test/*.test.mjs
```

The host-side probe engine can be tested standalone: `probe()` returns `{ plugins, sources, generatedAt }`.