前言¶
在 DeepSeek Harness（DSH）里做选型或尽职调查时，智能体常会拉 GitHub 上的贡献者数、PR 合并天数、open issue 数量。这些数 API 都能给，但直接拿「均值」「open_issues_count」下结论，很容易把维护风险读反：一个长期未合并的 PR 会把均值从 3 天拖到 10.8 天；Issues 端点会把 PR 混进来；不分页则 silently 只拿到第一页。
dsh-tool-mining（维护者 yuehancn）是面向 DSH 的自建工具插件：只读公开 GitHub REST API，不装 SDK，只用 fetch。它在社区目录 skillhub.cn 中归类为「模型推理」相关能力；核心价值是把「看清楚」和「下判断」拆开——工具返回中位数与均值、是否截断、过滤规则等，由调用方或 Harness 对话里再归纳。
这是什么¶
一句话：给 DSH 用的仓库挖掘工具集，从 GitHub 拉贡献集中度、PR 合并速度（含趋势）、bus factor 与单作者文件、issue backlog 年龄等，并显式处理 bot、分页、PR/issue 混数等坑。
- 仓库：github.com/yuehancn/dsh-tool-mining
- 版本（package.json）：
1.0.0 - 许可：MIT
- 兼容性：针对 dsh
0.2.0-rc.2（preview）构建与测试；apply(ctx)插件规范相对稳定，若你使用更新版 dsh 需自行核对。
DSH 生态理念是「一切皆插件」；skillhub.cn 为社区目录站点，与 DeepSeek / 幻方无官方从属关系。
核心功能：五个工具¶
插件在 Cordis 中注册 id 为 tool-mining 的一组工具，典型调用关系如下（参数均为 owner, repo，部分工具有可选参数）：
| 工具 | 作用 |
|---|---|
mining_status |
API 是否可达、token 是否配置、当日剩余配额与重置时间、可用操作与分页上限；多页分析前应先查配额（匿名约 60 次/小时）。 |
mining_contributors |
按提交数排名；报告第一名/前五占比、覆盖一半提交需要几人（halfOfWorkNeeds）；bot 与人类分开，份额分母为人类提交总数。 |
mining_velocity |
PR 从开到合并：中位数（主指标）、均值（与中位数分歧即信息）、p90（线性插值）、按周合并数时间线 trend。 |
mining_busfactor |
用一份 commit 列表同时算作者分布与「仅一人改过的文件」；risk 为 high/moderate/low 并附带判据话术；文件列表缺失时在 notes 说明而非空数组暗示。 |
mining_issues |
backlog：开放数、中位等待天数、零回复占比、标签分布、每周新增；过滤 PR、draft PR，并说明与页面 open_issues_count 的差异。 |
设计要点（README 强调）：
mining_velocity同时报中位数和均值，避免替调用方做单一数字判断。- 分页触顶时返回
truncated: true与说明，不给出「看起来完整」的半份结果。 owner/repo经encodeURIComponent写入 URL，避免特殊字符拼错路径。
安装与启用¶
官方一行安装（README 原文，支持 desktop 与 web profile）：
dsh plugin --profile desktop add github:yuehancn/dsh-tool-mining
Web 版将 --profile desktop 换成 --profile web。安装后重启 dsh 即可在 Harness 中调用上述工具。
配置（写入 ~/.dsh/profiles/<profile>/cordis.patch.yml，与插件 bundle 中的 patch 对应）：
# ~/.dsh/profiles/<profile>/cordis.patch.yml
- id: tool-mining
config:
token: ghp_xxxxxxxxxxxxxxxxxxxx
maxPages: 5
perPage: 100
| 字段 | 默认 | 说明 |
|---|---|---|
token |
"" |
GitHub PAT；强烈建议配置。公开仓库不配也可用，匿名配额很低。 |
apiBase |
https://api.github.com |
可指向 GitHub Enterprise 等。 |
maxPages |
5 |
每份列表最多翻页数。 |
perPage |
100 |
每页条数。 |
timeoutMs |
600000 |
单次调用超时（10 分钟）。 |
status / contributors / velocity / busfactor / issues |
true |
可按需关闭单个工具。 |
典型用法¶
在 DSH 对话中，可按 README 给出的分析顺序依次调用（逻辑上先确认 API 与配额，再查人、速度、bus factor、issue）：
mining_status(owner, repo)— 确认 token 与剩余配额。mining_contributors(owner, repo)— 看贡献是否集中在少数人；可选limit控制列表人数。mining_velocity(owner, repo)— 看中位合并天数、均值是否被离群 PR 拉高；可选weeks、includeBots。mining_busfactor(owner, repo)— 默认近 300 个 commit，可选commits、sampleFiles。mining_issues(owner, repo)— 看 backlog 年龄与零回复比例；可选weeks。
README 用同一仓库故事说明五个工具如何拼成判断，例如：中位 3 天合并、均值 10.8 天、bus factor 1、一半 issue 无人回复等——具体数值随目标仓库变化，此处不编造案例仓库名。
维护者提供的本地测试方式（需本机已安装对应 profile 的 dsh 依赖）：
mkdir -p node_modules/@deepseek-ai
cp -r "$HOME/.dsh/profiles/desktop/node_modules/@deepseek-ai/." node_modules/@deepseek-ai/
node _test/run-all.mjs
README 记载三个测试套件共 346 条断言，HTTP 走可注入的 fetchImpl，套件内禁止真实出网。
适用场景与注意¶
适合谁
- 在 DSH 里评估开源依赖、fork 候选或内部镜像仓库时，需要可复现的指标而非页面扫一眼。
- 希望 Harness 用工具调用拉数，且接受「中位数 + 均值 + notes」而非单一 KPI。
务必注意
- 插件以当前 dsh 进程的权限运行；安装前请阅读 源码与 MIT 许可证，自行确认 token 存放位置（仅进请求头，不进 URL/日志/错误回显，见 README 安全说明）。
- 仅
fetch、不落盘；大仓库多页分析会消耗 GitHub 配额，务必先mining_status。 - 私有仓库需有效 PAT；404 可能是仓库不存在或 token 无权限。
结尾¶
dsh-tool-mining 把 GitHub 上容易误读的统计（均值、混 PR 的 issue 数、未分页列表）做成五个边界清晰的 DSH 工具，并把过滤规则、截断和 bot 处理写进返回与 notes。若你在 Harness 里做仓库侧写，可从社区目录了解归类与简介，并在 GitHub 查看完整 README 与配置项。
