dsh-tool-github

English | 中文

A Cordis tool plugin that gives DeepSeek Harness (dsh) GitHub capabilities. Agents can look up repositories, search code, list issues, and create draft pull requests in natural language.

Built on the official "everything is a plugin" architecture via ctx.tools.register(defineTool(...)), following the official adding-a-tool contract.

Install

Install directly from GitHub (no npm publish needed):

npm install github:LJH-snow/dsh-tool-github
# or a specific branch/tag
npm install github:LJH-snow/dsh-tool-github#main

Or from a local checkout:

git clone https://github.com/LJH-snow/dsh-tool-github
cd dsh-tool-github
npm install && npm run build   # builds to lib/
npm install /path/to/dsh-tool-github

Once published to npm, it will also be installable as npm install @libai168/dsh-tool-github.

Requires @deepseek-ai/cordis (^4.0.1) and @deepseek-ai/dsh-tools (^0.1.0-rc.6) as peer dependencies, provided by the host dsh runtime.

Configuration

Load the plugin in a dsh composition config (cordis.yml):

- name: 'dsh-tool-github'
  config:
    token: 'ghp_xxx'        # GitHub PAT (optional; required for code search and PR creation)
    baseUrl: 'https://api.github.com'   # optional, override for GitHub Enterprise
    timeoutMs: 15000        # optional, request timeout in ms (default 15000)

Full example: examples/cordis.yml.

Security: read-only tools need no token. github_search_code and github_create_pr_draft require a token. Prefer a minimal-scope fine-grained token and never commit it.

The endpoint is checked before every request. Link-local addresses (169.254.0.0/16, fe80::/10, including their IPv4-mapped and NAT64 forms) are always rejected: they are never a valid API endpoint and include the cloud metadata address. Self-hosted endpoints on private networks keep working by default. Set enforcePublicEndpoint: true to additionally require a publicly reachable host; that mode also resolves ordinary hostnames and rejects loopback, private, CGNAT, multicast, reserved, and every IANA special-purpose range.

Tools

Behavior contract (per the official execute contract)

• Business failures are canonical values: missing repo → { found: false }; PR creation failure (branch missing / PR exists) → { created: false, reason }.
• Only infrastructure errors throw: invalid token (401), rate limit (403), etc.
• Cancellable: every request forwards exec.signal, with a default 15s timeout.

Development

npm install
npm run typecheck   # type check
npm test            # unit tests (vitest)
npm run build       # build to lib/

See DEVELOPMENT.md for plans and decisions.

Publishing

1. The package is published under your npm scope: @libai168/dsh-tool-github (npm publishing requires a granular access token with 2FA bypass enabled, or trusted publishing).
2. npm run build, then npm publish --access public.
3. Add the dsh-plugin topic to your GitHub repo for ecosystem discovery.

License

MIT