dsh-perfscope

Readme

<div align="center">

# ⚡ dsh-perfscope

**PerfScope for DeepSeek Harness — one-click health check & score for your installed plugins.**

Scan → Score → Fix → Share, all local. Is your Harness healthy? Find out in one click.

[![version](https://img.shields.io/badge/version-0.1.0-blue)](https://www.npmjs.com/package/dsh-perfscope) [![license](https://img.shields.io/github/license/Evhye38496/dsh-perfscope)](LICENSE) [![stars](https://img.shields.io/github/stars/Evhye38496/dsh-perfscope)](https://github.com/Evhye38496/dsh-perfscope) [![dsh-plugin](https://img.shields.io/badge/dsh-plugin-topic-orange)](https://github.com/topics/dsh-plugin)

`dsh plugin --profile web add dsh-perfscope`

*(listing in the dsh-market registry pending — see Project plan)*

</div>

---

## Why

DeepSeek Harness is young, and its plugin ecosystem is exploding — thousands of plugins, skins, tools, and presets appear weekly. After you install a few dozen, questions show up fast:

- **Which plugin is actually broken or silently failing?**
- **Which ones slow down every session or eat tokens?**
- **Am I running duplicates, conflicts, or stale plugins I forgot about?**
- **Is my setup trustworthy — or a pile of random tags?**

The ecosystem has no "health check" yet. **dsh-perfscope** fills that gap: one click gives you a **0–100 health score**, a plain-language issue list, and safe one-click fixes you can undo anytime.

> This is the same methodology that powers our VS Code tool, **PerfScope** — adapted to the agent-harness world, where every run is traceable and runtime data is richer than any IDE.

## What it checks

Health score = three dimensions, weighted configurable (default `0.6 / 0.25 / 0.15`):

| Dimension | Question | Examples of signals |
| --- | --- | --- |
| **Hard health** | Can it actually be used? | mount failures, unmet dependencies, core version conflicts, invalid config, incompatibility with your dsh RC |
| **Runtime health** | Is it fast and stable? | tool error/timeout rates, average latency vs. baseline, token / context share |
| **Governance health** | Is it tidy and trustworthy? | overlapping capabilities, stale plugins, sources outside curated registries |

Severity grading `critical / warning / suggestion` — every finding is one sentence a human can act on.

## Safety first

- Reads your plugin tree and session/telemetry stats **locally**. Nothing ever leaves your machine by default.
- Fixes only write patch rows to `cordis.patch.yml` (`- id: …` + `disabled: true`, the official patch layer) — **never** uninstalls, deletes, or edits source.
- Every write is **previewed first**, recorded in the **Doctor Change Log**, and **reversible with one click**.
- Host-critical plugins and hand-edited patch rows are protected from one-click toggles.

## Install

```bash
dsh plugin --profile web add dsh-perfscope
```

Restart `dsh web`, then open **Settings → dsh-perfscope**.

Prerequisites: Node `^22.19.0` or `24+`. Targets dsh `0.1.0-rc.8` (pinned post-SPIKE; preview moves fast — see roadmap).

## Usage

**Web UI** — Settings → dsh-perfscope: run a full check, read your score card, apply safe fixes with preview, undo any fix, export a report. (v1.0)

**Headless / CI** — scan the real host, fix, undo:

```bash
# scan the live dsh profile (read-only; no model key needed)
npx dsh-perfscope scan --profile web --format markdown --out report.md
# shareable score card
npx dsh-perfscope scan --profile web --format html --out scorecard.html
# one-click safe fix (writes cordis.patch.yml, HMR applies in ~1s) and undo
npx dsh-perfscope fix --profile web --disable broken-plugin
npx dsh-perfscope fix --profile web --undo
# offline JSON snapshot mode (no dsh host needed, for CI/fixtures)
dsh-perfscope --input test/fixtures/scan-input.json --format markdown --out report.md
```

Options: `--registry` (optional online check of npm publish time / curated status), `--sessions-dir`, `--dsh-cli`, `--dsh-home`.

## Development

```bash
pnpm install
pnpm test          # pure engine + change-log tests
pnpm run typecheck
pnpm run build     # bundle via tsup
```

Repository layout and the SPIKE notes that gate host integration live in [PROJECT.md](./PROJECT.md) (§5). The dsh-facing glue (`scanner/`, `ui/`, standalone bootstrap) is stubbed until SPIKE confirms the data contract against the pinned RC.

## Roadmap

- **S1 SPIKE** — done (2026-08-20): dump-config reconstruction and patch+HMR loop confirmed at source level; session-level runtime stats free, per-plugin attribution needs self-built mapping (v1.1). See [SPIKE-S1.md](./docs/SPIKE-S1.md).
- **S2 v0.1** — done (2026-08-23): real-host scanner (`scan`), headless `fix`/`undo` writing `cordis.patch.yml`, offline JSONL session analysis (zstd supported), report + score card. npm name locked to `dsh-perfscope`.
- **S3 上架** — awesome-dsh-plugin registry PR, `dsh-plugin` topic, directories.
- **v1.0** — Web UI settings panel, runtime-health dimension wired from session logs.
- **v1.1** — per-plugin runtime attribution (tool-name→plugin mapping).

## Community

- Tag your setup reports and feature ideas in [GitHub Discussions]() (link incoming).
- Plugin discoverability: covered by the `dsh-plugin` topic; listed in the awesome-dsh-plugin registry (pending).

## License

MIT © 2026 Evhye. Mirrors the PerfScope project license.

---

<sub>Unofficial, open-source project. Not affiliated with DeepSeek AI.</sub>