dsh-tool-radar

Readme

# dsh-tool-radar

English | [中文](README_CN.md)

A `repo_radar` tool plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`). Before the agent burns a session on an unfamiliar GitHub repo, score its contribution-friendliness from live evidence, not vibes.

## What it does

One model-facing tool, `repo_radar`, returning a 0-100 score with the evidence attached:

- **Merge history** — recently merged PR count and median days from open to merge.
- **Queue health** — open PR count, stale (>90d) ratio, and queue-vs-merge-volume imbalance.
- **Maintainer responsiveness** — median days to the first maintainer comment on recently merged PRs.
- **External-contributor friendliness** — how often outside contributors (NONE/CONTRIBUTOR/FIRST_TIMER) actually get merged.
- **Verdict with reasoning** — every scoring rule leaves a plain-language note, plus machine-readable risk flags (`no_recent_merges`, `stale_pr_backlog`, `slow_maintainer_response`, `mostly_internal_merges`, `queue_overload`).

Verdict bands: `Contribute` (70+), `Consider` (45-69), `Avoid` (<45). The scoring rules are ported from [GitSense](https://github.com/he-yufeng/GitSense)'s radar, which runs this exact formula daily.

API cost stays bounded: one repo call, one closed-PR sample, one open-PR sample, and maintainer-response probes on at most five merged PRs. Unauthenticated by default; `GITHUB_TOKEN` (or `GH_TOKEN`) raises the rate limit and is used only in the `Authorization` header — never logged, never in output.

## Install

```sh
dsh plugin --profile <name> add github:he-yufeng/dsh-tool-radar
```

or from npm (once published):

```sh
dsh plugin --profile <name> add dsh-tool-radar
```

## Tool reference

| Parameter | Type | Required | Meaning |
|---|---|---|---|
| `repo` | string | yes | Repository as `owner/name` or a full GitHub URL. |
| `skills` | array | no | Skill keywords matched against the repo's languages (e.g. `["python", "llm"]`). |

Result shape (one canonical JSON value):

```json
{
  "repo": "HKUDS/Vibe-Trading",
  "stars": 33428,
  "primaryLanguage": "Python",
  "score": 100,
  "recommendation": "Contribute",
  "breakdown": {
    "mergedPrs": 22,
    "openPrs": 5,
    "staleRatio": 0,
    "medianMergeDays": 0.8,
    "medianMaintainerResponseDays": 0.6,
    "externalMergedRatio": 0.95,
    "skillMatches": [],
    "stars": 33428
  },
  "notes": [
    "some recent merges",
    "fast median merge time",
    "stale PR ratio looks manageable",
    "maintainers respond quickly",
    "outside contributors are getting merged"
  ],
  "riskFlags": []
}
```

Errors are honest: a missing or private repo, a rate-limit hit, or a malformed `owner/repo` input raises a typed `GitHubError` instead of returning a misleading score.

## Development

```sh
npm install
npm run build     # tsc -> lib/
npm test          # vitest (network fully stubbed)
```

Layout:

```
src/
  index.ts    # plugin entry: name / inject / apply
  tool.ts     # repo_radar tool definition
  collect.ts  # bounded GitHub sampling -> radar inputs
  score.ts    # the scoring rules (ported from GitSense radar.py)
  github.ts   # minimal API client; token hygiene lives here
test/
  radar.test.ts
```

## License

MIT