# dsh-tool-radar

[English](README.md) | 中文

给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）写的 `repo_radar` 工具插件：在 agent 为一个陌生 GitHub 仓库烧掉一整个会话之前，先用活证据给它的"值不值得贡献"打个分，不靠感觉。

## 它做什么

只提供一个模型工具 `repo_radar`，返回 0-100 分和背后的全部证据：

- **合并史**：近期 merged PR 数、从提出到合并的中位天数。
- **队列健康**：open PR 数、陈旧（>90 天）比例、队列与合并量的失衡度。
- **维护者响应**：近期 merged PR 上维护者第一条回复的中位天数。
- **外部贡献者友好度**：外部作者（NONE/CONTRIBUTOR/FIRST_TIMER）的 PR 真正被合并的比例。
- **带理由的结论**：每条计分规则都留一句人话备注，外加机器可读的风险标记（`no_recent_merges`、`stale_pr_backlog`、`slow_maintainer_response`、`mostly_internal_merges`、`queue_overload`）。

结论分档：`Contribute`（70+）/ `Consider`（45-69）/ `Avoid`（<45）。计分规则移植自 [GitSense](https://github.com/he-yufeng/GitSense) 的 radar，那套公式每天都在真实跑。

API 调用是有界的：一次仓库信息、一次已关闭 PR 抽样、一次 open PR 抽样、最多五个 merged PR 的维护者响应探测。默认无认证；设了 `GITHUB_TOKEN`（或 `GH_TOKEN`）只用于提高限额，且只出现在 Authorization 头里——不写日志、不进输出。

## 安装

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

或（发布到 npm 后）：

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

## 工具参数

| 参数 | 类型 | 必填 | 含义 |
|---|---|---|---|
| `repo` | string | 是 | `owner/name` 或完整 GitHub URL |
| `skills` | array | 否 | 与仓库语言匹配的技能关键词（如 `["python", "llm"]`） |

返回一个规范 JSON：

```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": []
}
```

错误是诚实的：仓库不存在或私有、触发限额、`owner/repo` 写法不对，都会抛出明确的 `GitHubError`，而不是返回一个误导性的分数。

## 本地开发

```sh
npm install
npm run build     # tsc 编译到 lib/
npm test          # vitest（网络请求全部打桩，离线可跑）
```

目录结构：

```
src/
  index.ts    # 插件入口：name / inject / apply
  tool.ts     # repo_radar 工具定义
  collect.ts  # 有界 GitHub 抽样 -> 雷达输入
  score.ts    # 计分规则（移植自 GitSense radar.py）
  github.ts   # 极简 API 客户端；token 卫生只在这层
test/
  radar.test.ts
```

## 许可证

MIT