dsh-prospector

Readme

# dsh-prospector

English | [中文](README.zh.md)

GitHub research ("prospecting") assistant for DeepSeek Harness — gives the agent model-facing tools to **search repositories, read READMEs and source files, list file trees, and clone candidates**, then synthesize an implementation plan from the best open-source solutions it finds.

## Scenarios

- **Before building something new** — prospect open source first: what exists, what each candidate contributes, and what still needs building.
- **Technology selection** — compare candidates on activity, structure, and adoptability.
- **Deep due diligence** — clone and read core source for integration, license, and maintenance risk.

## Tools

| Tool | Does |
|---|---|
| `github_search_repos(query, limit?)` | Search repositories; supports `topic:`/`language:`/`stars:>N` qualifiers. |
| `github_get_readme(owner, repo)` | Fetch a README, bounded by `maxReadmeBytes`. |
| `github_read_file(owner, repo, path)` | Fetch one file, bounded by `maxFileBytes`. |
| `github_list_tree(owner, repo)` | List file paths (blobs only), bounded by `maxTreePaths`. |
| `github_clone_repo(owner, repo, into?)` | Shallow-clone into the workspace (`into` = topic subfolder) and return the local path. |

The agent combines these (search → read README/source → clone → read deeply); the plugin only supplies the eyes.

## Commands

### `/research [low|medium|high] <idea>`

Research an idea end to end and propose a plan. The optional leading tier (default `medium`) sets search breadth and read depth. Each idea gets its own subfolder under the workspace.

### `/gh-login`

Report the GitHub authentication state and show login steps when unauthenticated.

## Depth tiers

| Tier | Search | Read depth | Clone |
|---|---|---|---|
| `low` | top 5 | README only | no |
| `medium` | top 10 | README + key files + tree of top 1-2 | 1-2 most promising |
| `high` | top 20, qualifiers + pagination | core source across several files + full trees | several |

## Installation

Mount it in the composition; the shipped `cordis.patch.yml` inserts it automatically when installed as a bundle:

```yaml
- name: 'dsh-prospector'
  config:
    client: 'rest'               # 'rest' (default) or 'gh'
    ghPath: 'gh'                 # absolute path if gh is not on PATH
    workspaceRoot: '~/dsh-prospector'  # optional; default is ~/dsh-prospector
```

Mount it beside a subprocess provider and the filesystem tools.

## Authentication

The plugin never stores a token. Read operations resolve a token from `GH_TOKEN`/`GITHUB_TOKEN`, else `gh auth token`. Run `gh auth login` once (device flow → github.com/login/device), or set `GH_TOKEN`.

## Workspace

Clones live under a dedicated workspace root (`~/dsh-prospector` by default), one subfolder per research topic:

```
~/dsh-prospector/
  <topic-slug>/          # one folder per /research idea
    <owner>__<repo>/     # shallow clones
```

The workspace root and each topic folder are created automatically on first use.

## Configuration

| Field | Default | Meaning |
|---|---|---|
| `client` | `rest` | Read backend: `rest` (in-process HTTP) or `gh` (GitHub CLI). Clone always uses `git`. |
| `ghPath` | `gh` | Path to the gh executable. |
| `workspaceRoot` | `~/dsh-prospector` | Root where per-topic folders and clones live. |
| `maxReadmeBytes` | `200000` | Byte budget per README. |
| `maxFileBytes` | `100000` | Byte budget per file. |
| `maxTreePaths` | `2000` | Max file paths per tree listing. |
| `searchLimit` | `10` | Default search result count. |
| `maxAttempts` | `3` | Max REST attempts (retries on rate-limit/server/network errors). |
| `fallbackToGh` | `true` | Fall back to `gh` when REST hits an infrastructure error. |

## Notes & cautions

- **`gh` and `git` are required** — `gh` for auth/token, `git` for cloning.
- **GitHub rate limits** — the Search API allows ~30 requests/minute authenticated; broad/deep research is bounded by it.
- **Read-only apart from clones** — the plugin never mutates the model request or session surface; only clones write to the workspace.
- **Re-cloning into the same folder fails** — reuse a topic folder only after removing the previous clone.
- **No settings panel / tier-picker UI yet** — configuration is via `cordis.yml`; the interactive tier selector and settings card depend on DSH's client-bundle tooling for external plugins.

## License

MIT