# dsh-prospector

[English](README.md) | 中文

面向 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>`

从头到尾研究一个 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` 会自动插入：

```yaml
- 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/
  <topic-slug>/          # 每个 /research 主题一个文件夹
    <owner>__<repo>/     # 浅 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