dsh-plugin-audit — 插件生态体检（Plugin Health Audit for DSH）

Turn the GitHub dsh-plugin topic into a local, scored plugin catalog for DeepSeek Harness. Every plugin gets a 0–100 health score across four signals, a leaderboard in the web UI, and agent tools that answer "which plugins are worth installing?".

| Signal | Weight | What it measures | | --- | --- | --- | | Maintenance | 30 | last push recency + star tier + star trend (archived → 0 + 🚨 flag) | | Docs | 25 | README presence + description depth + license | | npm | 30 | npm package exists + publish recency + weekly downloads (v0.3) | | Ecosystem | 15 | presence in the curated awesome list + listing recency |

Grades: A 🛡️ (80+) · B ✅ (60+) · C ⚠️ (40+) · D 🚨 (<40 or any high flag). Scores are pure functions over plain records — fully explainable (every deduction carries a note).

v0.3: npm signal now includes a weekly-downloads tier (exists 10 + publish recency 14 + weekly downloads 6).

v0.4 (真插件校验 / topic-tag farming filter): deep scan now verifies a repo is actually a DSH plugin — presence of cordis.patch.yml, dsh.bundle in package.json, or a plugin entry file. Repos with none of these are flagged not-plugin (medium) and capped at grade C, no matter how healthy they look. The npm probe also detects whether the published package declares dsh.bundle (installable via dsh plugin add). This filters the ~half of the topic that is old projects or tag farming.

Security (v0.2) is a veto, not a weight: audit_scan static-scans a plugin's package.json install scripts, shell scripts, and entry sources for remote-code-execution, encoded commands, rc persistence, obfuscation, and exfiltration to non-allowlisted hosts. High/critical findings land in the flags contract → grade D, no matter how healthy the other signals look. Each finding carries evidence; the scanner is deliberately conservative.

Compatibility

Tool schemas are validated against the @deepseek-ai/dsh-tools value-schema DSL at plugin load (checked against dsh-tools 0.1.0-rc.6 and 0.1.1-rc.2). Earlier releases used JSON-Schema required at the root of output.schema and closed nested objects without declared properties, which made the host abort the whole profile boot with unsupported JSON schema: schema.required is not supported by the value schema DSL and could reject the tool's own results. Current releases fix both; if an affected version left your DSH unable to start, remove the plugin from the profile (or upgrade) — no data is lost.

Features

| Feature | Status | | --- | --- | | audit_sync — sweep the topic, probe npm, re-score (incremental, rate-limit aware) | ✅ stable | | audit_top — leaderboard by score / stars / newest / name, category filter | ✅ stable | | audit_plugin — full report card with evidence notes | ✅ stable | | audit_scan — per-plugin static security scan (files → findings → veto) | ✅ stable (v0.2) | | audit_history — score timeline per repo + biggest gainers/losers | ✅ stable (v0.5) | | Star trend in maintenance signal (from rolling history snapshots) | ✅ stable (v0.2) | | auditSummary session projection + composer-dock leaderboard | 🧪 experimental (loader-format client bundle) | | Optional periodic sync (schedule service) | 🧪 guarded | | Seed catalog from the awesome-dsh-plugin list (1018 plugins) | ✅ stable |

How it works

• One Cordis plugin: host face (lib/index.js) registers tools + projection + optional schedule; browser face (lib/client.js) renders the dock; cordis.patch.yml mounts the row.
• Sync pulls GET /search/repositories?q=topic:dsh-plugin (100/page), probes registry.npmjs.org/<name> with bounded concurrency, then upserts into a JSON catalog. Rate-limit-aware: stops early when the search budget runs low and resumes next time; failed probes keep the previous values.
• Storage: dataDir (default $DSH_HOME/dsh-plugin-audit or ~/.dsh/dsh-plugin-audit): catalog.json + meta.json + history.json (rolling star snapshots for future trend tiers).
• All writes are atomic (temp + rename); corrupt files fall back to empty instead of crashing.

Install

The package declares "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }, so it goes through DSH's official plugin management:

# from a local checkout
dsh plugin --profile <profile> add /path/to/dsh-audit

# or after publishing to npm
dsh plugin --profile <profile> add dsh-audit

Restart DSH. The audit_* tools are registered host-wide; the leaderboard dock appears in the web UI on a web profile.

First sync

Give the agent a GitHub token (search API: 30 req/min vs 10 anonymous) and ask it to audit_sync, or configure it:

• dataDir — catalog location (empty = default)
• githubToken — or env DSH_GITHUB_TOKEN / GITHUB_TOKEN
• syncIntervalHours — periodic sync (0 disables; requires schedule service)
• npmProbe — probe npm registry (default true)

Standalone (outside DSH, for testing / CI)

node scripts/seed.mjs                       # build data/catalog.json from the awesome list checkout
node scripts/sync.mjs --token <gh-token>    # real sync, no DSH needed
node --test test/                           # run tests

Development notes

• Tests are fully offline (fake fetch injected) — node --test test/ needs no network.
• Data model: one catalog record per repo (repo, stars, pushedAt, license, archived, npm, curated, addedAt, score, flags, …). See lib/audit.js repoToRecord and lib/scoring.js.
• The flags array is the extension contract for the security tier (v0.2).

Roadmap

• v0.3 — open data export (JSON) so other marketplaces can cite the scores
• v0.4 — appeal/comments channel per plugin
• v0.5 — batch scan scheduling (scan the top-N by stars on each sync) + transitive-dependency signals

License

MIT