PerryLink/dsh-score

🏆 dsh-score

• 1024 store channel: npm i -g dsh1024 once, then dsh1024 plugin --profile web add dsh-score (counts toward the deepseek1024.com install ranking).

Multi-dimensional quality scoring for DeepSeek Harness plugins.

*Five dimensions, real gh/npm evidence, one weighted risk card and leaderboard.*

English · 简体中文 · Español · Português · हिन्दी

dsh plugin --profile <name> add dsh-score

📖 Ecosystem knowledge base — measured data, not marketing: plugin development guide · plugin-selection data · maintenance criteria.

Install & uninstall

dsh plugin --profile web add dsh-score     # install (npm) — or the git form above
dsh plugin --profile web remove dsh-score  # uninstall

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（95 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

*English:* part of a 95 plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

What is dsh-score?

Multi-dimensional quality scoring for DeepSeek Harness plugins.

Five dimensions, real gh/npm evidence, one weighted risk card and leaderboard.

*Workflow overview: question → sealed sources → report. The examples below use the real command surface.*

Comparison

Compatibility

Component · Version DeepSeek Harness · `dsh-v0.2.1-rc.2` (GitHub tag). The engines.dsh gate is >=0.2.1-0 =24.0.0 Package manager · pnpm@11.7.0 Platform · Windows / macOS / Linux (host-only plugin) External tools · gh CLI on PATH (authenticated for API reads), npm CLI on PATH

What you get

• score tool — one target through the five-dimension pipeline; returns the structured risk card, or { kind: 'background', jobId } with background: true.
• /score command — batch scoring of a whitespace/comma-separated target list as a score-batch background job over ctx.jobs, producing a leaderboard snapshot (JSON + Markdown).
• score_report tool — fetch any stored score card (sc_...), leaderboard (lb_...), or the latest leaderboard.
• score_badge tool — an embeddable README badge (shields.io flat SVG + endpoint URL) and the five-dimension JSON for one scored target.
• Five dimensions (weights configurable, defaults sum to 100): install success 25, maintenance 20, documentation 20, security 20, compliance 15.
• Evidence discipline — every dimension records its audit links (source, sanitized detail, observedAt); a dimension without evidence reports no-evidence (score 0, excluded from the weighted total), never a fabricated number.
• Structured results — every record carries schema: "dsh-score/v1" with first-class fields; this is the machine-readable contract downstream tooling consumes.

Quick start

Git channel

dsh plugin --profile web add github:PerryLink/dsh-score#<commit-sha>

The first add fails because pnpm blocks the package's prepare build; copy the exact key pnpm printed into the profile's pnpm-workspace.yaml and re-run:

allowBuilds:
  'dsh-score': true

npm channel

dsh plugin --profile web add dsh-score

Prebuilt packages need no build allowance. Restart the profile, then use score / /score from a session.

Examples

These are the plugin's real entry points; install once, then call one.

Detailed example

Command

~~~sh score({ target: "owner/repo" }) ~~~

Output

~~~text

Score sc_65e817eec8cd71ed

• Target: owner/repo (repo)
• Grade: B — total 88/100
• Verdict: healthy (weighted total 88/100)

Dimension · Status · Score · Weight · Summary Install success · ⬜ no-evidence · 0 · 25 · no dsh-test-drive result recorded for this target (install success unmeasured) Maintenance · ✅ pass · 100 · 20 · active (2026-08-15T00:00:00.000Z; 0 open issues) Documentation · 🟠 warn · 70 · 20 · 1/4 language READMEs + CHANGELOG + SECURITY Security · ✅ pass · 100 · 20 · license MIT Protocol compliance · ✅ pass · 81 · 15 · dsh.bundle.patch declared ~~~

*Observed from README.md:141-149,169-191; tests/tools.spec.ts:64-65; tests/score.spec.ts:50-55; src/report.ts:40-53*

Failure branch

Input

~~~text {"id":"sc_nope"} ~~~

Output

~~~text isError=true; error.message=dsh-score: no score recorded with id sc_nope ~~~

*Observed from plugins/dsh-score/src/tools.ts:351-354 (throw); plugins/dsh-score/tests/tools.spec.ts:95-99 (unknown id); plugins/dsh-score/README.md:179-181 (score_report); exercised through plugins/dsh-score/tests/harness.ts*

Brief examples

Configuration

All keys are optional (defaults shown); invalid values fail loudly at load.

Key · Default · Description probeTimeoutMs · 60000 · Deadline for one gh/npm probe command. outputTailBytes · 8000 · Cap on the sanitized output tail recorded per probe. cacheMaxAgeMs · 86400000 · How long a cached score card is reused before re-scoring (0 disables the cache). staleCommitWarnDays · 90 · Commit/publish age at which maintenance drops to warn. staleCommitFailDays · 365 · Commit/publish age at which maintenance drops to fail. staleIssueWarnDays · 30 · Oldest-open-issue age (response proxy) at which maintenance drops to warn. staleIssueFailDays · 180 · Oldest-open-issue age at which maintenance drops to fail. maxBatchTargets · 20 · /score batch cap. batchConcurrency · 1 · Batch concurrency (serial avoids API-rate contention). weights · {install:25, maintenance:20, documentation:20, security:20, compliance:15} · Per-dimension weights (each 0–100; at least one must be > 0).

Tools & surfaces

score

score(target: string, refresh?: boolean, background?: boolean)

• target — a GitHub repo (github:owner/repo, owner/repo, a git/https URL) or an npm package name.
• refresh: true bypasses the score cache and re-gathers evidence.
• background: true starts a score-batch job and returns its id.

/score

Starts one background batch job; progress streams through the job output, and the final line names the leaderboard id for score_report.

score_report(id?)

Returns a score card (sc_...), a leaderboard (lb_...), or — with no id — the latest leaderboard.

score_badge(target? | id?, refresh?)

Generates an embeddable README badge and the five-dimension JSON for one target:

• target — score a GitHub repo or npm package (through the cache) and badge it; mutually exclusive with id.
• id — badge a stored score card (sc_...) without re-scoring.
• refresh: true — bypass the score cache (only applies to target).

Returns the badge (SVG + endpoint + Markdown embed) and the compact five-dimension JSON — see Badge & JSON API.

Structured result sample

{
  "schema": "dsh-score/v1",
  "scoreId": "sc_8f1c2e4a9b3d7f01",
  "target": { "kind": "repo", "spec": "github:owner/dsh-click#abc123" },
  "scoredAt": "2026-08-16T00:00:00.000Z",
  "durationMs": 3210,
  "pluginVersion": "0.2.22",
  "dimensions": {
    "install": { "dimension": "install", "status": "no-evidence", "score": 0, "weight": 25,
                 "summary": "no dsh-test-drive result recorded for this target (install success unmeasured)",
                 "evidence": [{ "source": "test-drive", "detail": "no test-drive record found in the test_drive domain", "observedAt": "2026-08-16T00:00:00.000Z" }] },
    "maintenance": { "dimension": "maintenance", "status": "pass", "score": 100, "weight": 20,
                     "summary": "active (2026-08-10T00:00:00Z; 0 open issues)",
                     "evidence": [{ "source": "gh-api", "detail": "last activity 2026-08-10T00:00:00Z", "observedAt": "2026-08-16T00:00:00.000Z" }] }
  },
  "total": 88,
  "grade": "B",
  "verdict": "healthy (weighted total 88/100)"
}

Scoring: the total is a weighted average over dimensions that gathered evidence (no-evidence dimensions are excluded and renormalized); A ≥ 90, B ≥ 75, C ≥ 60, D ≥ 40, else F, and N/A when nothing had evidence.

Badge & JSON API

score_badge generates an embeddable README badge and the five-dimension JSON for one scored target.

Badge

Three forms, all derived from the same settled score card:

• Endpoint — a documented shields.io static URL, paste-ready for a README image (zero self-hosting).
• SVG — a self-contained shields.io flat-style SVG (badge.svg field / renderScoreBadge) for offline or self-hosted READMEs.
• Markdown — the embed snippet combining both.

Embed the total badge in any README:

![dsh-score: B · 84/100](https://img.shields.io/badge/dsh--score-B_%C2%B7_84%2F100-green)

Five-dimension JSON

The same call returns the compact JSON API envelope (schema: "dsh-score/badge/v1"):

{
  "schema": "dsh-score/badge/v1",
  "target": { "kind": "repo", "spec": "github:owner/dsh-click#abc123" },
  "scoredAt": "2026-08-16T00:00:00.000Z",
  "total": 84,
  "grade": "B",
  "dimensions": {
    "install":      { "label": "install", "status": "no-evidence", "score": 0,  "weight": 25, "summary": "no dsh-test-drive result recorded" },
    "maintenance":  { "label": "maintenance", "status": "pass", "score": 90, "weight": 20, "summary": "active (0 open issues)" },
    "documentation": { "label": "docs", "status": "pass", "score": 85, "weight": 20, "summary": "README + CHANGELOG + SECURITY" },
    "security":     { "label": "security", "status": "warn", "score": 60, "weight": 20, "summary": "permissive license" },
    "compliance":   { "label": "compliance", "status": "pass", "score": 100, "weight": 15, "summary": "dsh.bundle.patch + dsh-plugin topic" }
  }
}

A no-evidence dimension keeps its honest status and score 0 — the badge and JSON never fabricate a number.

Permissions & data

• Only public services are consumed: ctx.subprocess, ctx.jobs, ctx.storageDomain, ctx.tools, ctx.commands.
• Score cards and leaderboards are stored in the score storage-domain (tables scores, leaderboards; latest-leaderboard pointer). When the composition has no storageDomain (profiles that predate the base bundle's storage rows, such as the 0.1.1-rc.2-era headless profile), tools still work and score persistence is disabled with a logged reason. The published dsh-base bundle mounts storage-domain from 0.1.2-rc.1 on (verified against the 0.1.2-rc.1 and 0.1.5-alpha.1 tarballs), so persistence is active on the published line.
• Child processes inherit the provider's credential-scrubbed environment; gh reads its own credential store. No environment value is ever logged.
• All report/log strings pass through pure sanitizers: token literals, URL credentials, and bearer headers are redacted, and tails are byte-capped.

Security boundaries

• No code execution. The pipeline runs gh api and npm view only; it never installs, builds, or runs a target.
• Argv-only subprocesses. Every CLI invocation is an argv array, never shell-interpreted; repo owner/repo segments are validated against a restricted character set before use in an endpoint.
• Evidence discipline. No score is fabricated: a probe that fails or returns unparsable output yields no-evidence, never a number.
• Detection vs redaction. Secret-leak and malicious-install-script detection share the same pure regexes as redaction; both are unit-tested against extreme inputs.