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