Perfirstvito/dsh-prospector

dsh-prospector

面向 DeepSeek Harness 的 GitHub "探矿"研究助手：给 agent 提供 搜索仓库、读 README/源码、列文件树、clone 候选仓库 这几只"眼睛"，让它为你的 idea 去开源世界找现成方案，最后综合出一份实现计划。

使用场景

- 动手造轮子之前 —— 先探矿：有哪些现成方案、各自贡献什么、还缺什么要自己写。
- 技术选型 —— 对比候选仓库的活跃度、结构、可采性。
- 深度尽调 —— clone 并读核心源码，评估集成、license、维护风险。

工具

| 工具 | 作用 |
|---|---|
| github_search_repos(query, limit?) | 搜索仓库，支持 topic:/language:/stars:>N 限定符。 |
| github_get_readme(owner, repo) | 拉 README，受字节上限约束。 |
| github_read_file(owner, repo, path) | 拉单个文件。 |
| github_list_tree(owner, repo) | 列文件树（仅文件）。 |
| github_clone_repo(owner, repo, into?) | 浅 clone 到工作区，返回本地路径。 |

agent 负责组合与判断（搜 → 读 README/源码 → clone → 深读），插件只提供"眼睛"。

命令

/research [low|medium|high]

从头到尾研究一个 idea 并给出计划。可选档位（默认 medium）决定搜索广度和研读深度。每个主题在工作区下独立成文件夹。

/gh-login

报告 GitHub 认证状态；未认证时给出登录步骤。

深度档位

| 档位 | 搜索 | 研读 | Clone |
|---|---|---|---|
| low | top 5 | 仅 README | 否 |
| medium | top 10 | README + 关键文件 + top 1-2 文件树 | 1-2 个最可能的 |
| high | top 20 + 限定符/翻页 | 核心源码多文件 + 全量树 | 多个 |

安装

挂载到 composition 即可；作为 bundle 安装时 cordis.patch.yml 会自动插入：

- name: 'dsh-prospector'
config:
client: 'rest'               # 'rest'（默认）或 'gh'
ghPath: 'gh'                 # gh 不在 PATH 时给绝对路径
workspaceRoot: '~/dsh-prospector'  # 可选；默认 ~/dsh-prospector

与 subprocess provider、文件系统工具一起挂载。

认证

插件不存储 token。读操作从 GH_TOKEN/GITHUB_TOKEN 环境变量取 token，否则走 gh auth token。跑一次 gh auth login（设备流 → github.com/login/device）或设置 GH_TOKEN 即可。

工作区

clone 落在专用工作区根目录（默认 ~/dsh-prospector）下，每个研究主题一个子文件夹：

~/dsh-prospector/
/          # 每个 /research 主题一个文件夹
__/     # 浅 clone

工作区根目录和每个主题文件夹首次使用时自动创建。

配置

| 字段 | 默认 | 含义 |
|---|---|---|
| client | rest | 读后端：rest 或 gh；clone 恒用 git。 |
| ghPath | gh | gh 可执行文件路径。 |
| workspaceRoot | ~/dsh-prospector | 主题文件夹与 clone 的根目录。 |
| maxReadmeBytes | 200000 | README 字节预算。 |
| maxFileBytes | 100000 | 单文件字节预算。 |
| maxTreePaths | 2000 | 文件树条数上限。 |
| searchLimit | 10 | 默认搜索条数。 |
| maxAttempts | 3 | REST 重试上限。 |
| fallbackToGh | true | REST 基础设施故障时回退 gh。 |

注意事项

- 需要 gh 和 git —— gh 用于认证/token，git 用于 clone。
- GitHub 限流 —— 搜索 API 认证后约 30 次/分钟，广搜/深挖受此约束。
- 除 clone 外只读 —— 插件不改模型请求或会话面，只有 clone 会写工作区。
- 同一主题重复 clone 会失败 —— 复用主题文件夹前先删旧 clone。
- 暂无设置面板 / 档位选择器 UI —— 配置走 cordis.yml；交互式档位选择器和设置卡片依赖 DSH 对外部插件的 client bundle 工具链。

许可证

MIT