前言¶

在使用 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 進程的權限運行，安裝前請確認來源的安全性。