dsh-prospector
English | 中文
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:
- 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
