kelai141 / dsh-github-watchdog

dsh-github-watchdog

A DeepSeek Harness (DSH) Agent Preset plugin that watches GitHub repositories and produces security-aware preliminary analysis of pull requests, CI runs, commits, and issues — read-only, with optional issue-comment publication only.

Watchdog behavior is scoped to conversations that select the GitHub Watchdog preset. Unlike a host-global daemon, it starts one background job per selected conversation, polls on a fixed interval while that conversation is open, and is cancelled when the conversation is disposed. Ordinary conversations never mount the plugin and never see its tools.

The scheduler is a real Harness background job (ctx.jobs) driven by the disposable timer service. When a poll observes a repository change, a bounded plugin notice wakes the conversation via the Agent followup API; unchanged polls never create model turns.

---

Safety model

• Reads only explicit owner/repository entries in its configuration.
• The only allowed write route is POST /repos/{owner}/{repo}/issues/{number}/comments (disabled by default).
• Never pushes, merges, approves, labels, closes, dispatches workflows, or reads secrets.
• The token is read per request from an environment variable; it is never stored, logged, or sent to an LLM.
• PR bodies, diffs, issue text, and CI logs are treated as untrusted data, never as instructions.
• Repositories are added to the whitelist only after the user explicitly confirms them; discovery is read-only and github_watchdog_inspect only serves whitelisted repositories.

---

Quick start

1. Install the plugin package

Build and pack the plugin:

npm install && npm run build && npm pack

Install the resulting dsh-github-watchdog-0.0.1.tgz into the DSH profile that your web host uses (e.g. ~/.dsh/profiles/web). Two equivalent paths:

cd ~/.dsh/profiles/web
npm install /absolute/path/to/dsh-github-watchdog-0.0.1.tgz

or declare a link dependency in the profile package.json and run npm install

{
  "dependencies": {
    "@dsh-external/dsh-github-watchdog": "link:/absolute/path/to/this/repo"
  }
}

The package must be resolvable from the DSH profile so the preset row can load it. Keep it out of the profile bundles list to avoid a host-global daemon; the plugin is designed to be mounted only by the preset.

2. Install the Agent Preset

Copy the preset/ directory into your local preset root and give it an id:

cp -r preset ~/.dsh/.agent-presets/github-watchdog

The directory contains agent.cordis.yml and preset.yml. Edit agent.cordis.yml if the plugin package name or your config path differs.

3. Create the configuration

mkdir -p ~/.dsh/github-watchdog

Create ~/.dsh/github-watchdog/config.json:

{
  "repositories": [
    { "repository": "owner/repository", "workspace": "D:/path/to/local/checkout" }
  ],
  "tokenEnv": "GH_TOKEN",
  "intervalMs": 120000,
  "comments": { "enabled": false, "maxPerHour": 4 }
}

repositories may be an empty array at first — the model will discover candidates from the conversation workspace and ask you which to track.

4. Provide the GitHub token

The token is read from the environment variable named by tokenEnv (default GH_TOKEN). Set it in the environment before the DSH host process starts, then restart the host so it inherits it:

export GH_TOKEN=github_pat_xxx        # or GITHUB_TOKEN

5. Start a Watchdog conversation

• Restart the DSH host.
• New conversation → choose the GitHub Watchdog preset.
• Send any message, e.g. "检查仓库状态".
• The model calls github_watchdog_status; if no repository is configured it calls github_watchdog_discover_workspace, lists the candidates it found under your workspace, and asks which to track. After you confirm, it calls github_watchdog_configure and the first scan runs immediately.

---

Configuration reference

Key	Type	Default	Meaning
repositories	array	[]	Explicit { repository, workspace? } whitelist
tokenEnv	string	DSH_GITHUB_WATCHDOG_TOKEN	Env var holding the GitHub token
intervalMs	number	120000	Poll interval (60 000–3 600 000 ms)
comments.enabled	boolean	false	Publish automated analysis comments to PRs
comments.maxPerHour	number	4	Per-repository hourly comment budget (1–20)
stateFile	string	~/.dsh/github-watchdog/state.json	Deduplication/snapshot state
diagnostics.enabled	boolean	true	Write the rotating diagnostic log
diagnostics.logFile	string	next to config, watchdog.log	Diagnostic log path

The configuration is read on every poll, so edits apply without restarting.

---

Model-visible tools

Tool	Kind	Purpose
github_watchdog_status	read	Current progress/report: job id, poll count, per-repo results, PR/issue titles + authors, next poll
github_watchdog_discover_workspace	read-only	List Git repositories under the conversation workspace with a GitHub origin; never writes
github_watchdog_configure	write (local)	Add only user-confirmed, workspace-discovered repositories to the whitelist; triggers an immediate scan
github_watchdog_inspect	read-only	Fetch full body, comments, or changed files of one PR/issue; whitelisted repos only

---

Behavior notes

• One official Harness background job per selected conversation; agent/disposed cancels it.
• Initialization is observable: starting → scanning (per-repository progress) → observed, with jobId, pollCount, timestamps, and nextPollAt on every status.
• A local rotating diagnostic log (watchdog.log, 256 KiB, one backup) records one line per poll, per-repository outcome, notice keys, and errors — disable with diagnostics.enabled: false.
• Cross-conversation deduplication: a shared state file and in-process repository locks prevent duplicate scans and repeated comments for the same snapshot.

---

Development

npm run build   # dependency-free copy build into lib/
npm test        # node --test (route policy, redaction, dedup, lifecycle, discovery, inspect)

Layout:

src/core.js     route policy, findings, fingerprinting, redaction
src/github.js   bounded GitHub client (reads + optional issue comments)
src/state.js    durable snapshot/comment ledger
src/index.js    preset plugin: job loop, status, discovery, configure, inspect tools
test/           unit tests
preset/         agent preset to copy into ~/.dsh/.agent-presets/<id>/

License

MIT