前言¶

在使用 DeepSeek Harness（DSH）开发智能体时，面对一个陌生的 GitHub 仓库，直接投入会话往往成本过高，且容易因为环境不熟悉导致任务失败。dsh-tool-radar 提供了一个基于实时数据而非主观判断的评估方案。它作为一个 repo_radar 工具插件，在智能体投入工作前，从 GitHub 的实时证据中提取数据，对仓库的“贡献友好度”进行打分和诊断。

核心功能¶

该插件通过 repo_radar 工具向模型提供量化指标，帮助智能体决策是否应该贡献代码。

• 量化评分：返回 0-100 的分数，并附带具体的证据说明。
• 四大维度分析：
  1. 合并历史：分析最近合并的 PR 数量以及从打开到合并的中位天数。
  2. 队列健康：分析开放 PR 数量、陈旧（>90天）PR 的比例，以及队列与合并量的失衡情况。
  3. 维护者响应度：分析最近合并 PR 中，维护者首次评论的中位等待天数。
  4. 外部贡献者友好度：分析外部贡献者被合并的频率。
• 判定区间：提供三个判定带。
  • Contribute：分数 70 分及以上。
  • Consider：分数 45-69 分。
  • Avoid：分数低于 45 分。
• 风险标志：提供机器可读的风险标志，包括 no_recent_merges、stale_pr_backlog、slow_maintainer_response、mostly_internal_merges 和 queue_overload。

安装与启用¶

在终端中执行以下命令，将插件添加到指定的 DSH 配置文件中：

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

插件安装后，可通过 repo_radar 工具进行调用。

典型用法¶

工具调用需要传入参数，返回结构化的 JSON 数据。

参数说明：
* repo（字符串，必填）：仓库名称，格式为 owner/name 或完整的 GitHub URL。
* skills（数组，可选）：技能关键词，用于匹配仓库的主要语言。

返回数据结构示例：

{
  "repo": "owner/repo",
  "stars": null,
  "primaryLanguage": "Language",
  "score": 85,
  "recommendation": "Contribute",
  "breakdown": {
    "mergedPrs": 10,
    "openPrs": 3,
    "staleRatio": 0.1,
    "medianMergeDays": 2.5,
    "medianMaintainerResponseDays": 1.2,
    "externalMergedRatio": 0.6,
    "skillMatches": [],
    "stars": null
  },
  "notes": [
    "some recent merges",
    "maintainers respond within a day"
  ],
  "riskFlags": []
}

技术细节与限制¶

• API 成本控制：插件对 API 调用进行了严格限制，每次调用仅消耗：
  1. 1 个仓库信息调用。
  2. 1 个关闭 PR 样本。
  3. 1 个开放 PR 样本。
  4. 最多 5 个合并 PR 的维护者响应探针。
• 认证机制：默认为未认证状态。如果需要提升 GitHub API 限流，可设置环境变量 GITHUB_TOKEN 或 GH_TOKEN。该 Token 仅用于 Authorization 头部，绝不会记录在日志中，也不会出现在输出结果中。
• 错误处理：如果输入的仓库不存在、是私有仓库、触发限流或格式错误，插件会抛出类型化的 GitHubError，而不是返回误导性的分数。

生态与注意事项¶

DSH 的核心理念是“一切皆插件”。dsh-tool-radar 作为一个独立维护的插件，其源码和许可证可在 GitHub 仓库查看。在使用前，请务必检查源码与许可证，确保符合项目规范。插件以当前 DSH 进程的权限运行，安装前请确认来源的安全性。