dsh-advisor

English | 中文

Independent-model advisory review for DeepSeek Harness.

After each tool step, a separate reviewer model audits the agent's most recent
operations. When it finds a real concern (destructive or irreversible
operations, contract/schema violations, deviations from the user's explicit
request, correctness bugs), it injects a short [advisor] guidance message
into the next model call so the agent can self-correct. When the work is
sound, nothing is injected and the review costs only the (cheap) reviewer
call.

dsh has no built-in advisor; this plugin implements one on the standard
agent/pre-step waterfall (the same injection channel used by
dsh-agent-instructions and dsh-compaction-basic).

Install

dsh plugin add @slhssb/dsh-advisor

or add to the profile's package.json:

"dependencies": { "@slhssb/dsh-advisor": "^0.1.0" },
"dsh": { "profile": { "bundles": ["@slhssb/dsh-advisor"] } }

Then npm install (or pnpm install) in the profile directory and restart dsh.

Configuration

Defaults target the DeepSeek official API (deepseek-official provider) with
the cheap deepseek-v4-flash model. The API key is not handled by this
plugin: the deepseek-official adapter resolves it per request from the
DEEPSEEK_API_KEY environment variable or the credentials store.

The defaults need no override — they already target the DeepSeek official
API (deepseek-official/deepseek-v4-flash). To point the reviewer
elsewhere, override in the profile's cordis.patch.yml (last write per row
wins). This example routes the reviewer through a third-party relay: the API
key is resolved by that provider's adapter (here the TOKENRHYTHM_API_KEY
environment variable, per its apiKeyEnv in settings.yaml) — this file
never holds keys:

- id: advisor
  config:
    provider: tokenrhythm
    model: deepseek-v4-pro
    maxTokens: 512
    maxHistoryMessages: 40
    interval: 1
    timeoutMs: 30000

Disable entirely with disabled: true on the row, or set an empty
provider/model to fall back to the current request route (agent/session
request header, then agent options).

Rules (deterministic checks)

Beyond the LLM review, rules give you zero-cost, deterministic checks that
match the latest tool call (tool name + raw arguments JSON) against regular
expressions. They never fail and never cost a token; a warn rule injects a
[advisor] Rule check: message into the next step, a block rule rejects
the step outright (opt-in — default is warn).

- id: advisor
  config:
    provider: deepseek-official
    rules:
      - id: no-recursive-delete
        pattern: 'Remove-Item|rm\s+(-rf|-r\s*-f)|del\s+/[sq]'
        message: '检测到破坏性删除命令，请确认目标路径与用户授权。'
        action: warn            # or block
        tools: ['pwsh', 'bash'] # optional: only run for these tool names
        enabled: true           # optional, default true

Invalid rules (missing fields, bad regex) are skipped with a warning; the
agent flow is never blocked by a misconfigured rule. Multiple warn hits are
merged into one message. block fires before the LLM review — the review is
not run for a blocked step.

How it works

1. agent/pre-step (waterfall) fires before every model call.
2. The plugin scans the session log for the newest tool/result event. If
   none exists, or its seq was already reviewed, the step passes through.
3. Otherwise the reviewer model receives the recent derived history plus the
   review instruction and streams a response.
4. A non-empty response is wrapped as a user message
   (source: { kind: 'plugin', plugin: 'dsh-advisor' }, text prefixed
   [advisor]) and spliced into the step's messages after the claimed
   messages, before system context — the same insertion point
   dsh-agent-instructions uses, so the next model call is guaranteed to see
   it.
5. Review failure (LLM error, timeout, empty output) logs a warning, injects
   nothing, and advances the reviewed-seq marker so the same batch is not
   retried on the next step. The agent's main flow is never blocked.

Injected [advisor] messages are ordinary user/message log entries; they
never produce tool/result events, so review can never recurse on itself.

Development

npm install
npx tsc -p tsconfig.json
node test/smoke.mjs   # hand-built fakes; no network

lib/ is committed so git-installed consumers work without a build step;
node_modules/, test/smoke.mjs, and package-lock.json are gitignored.
npm pack ships lib via the files whitelist.

Publish

Published on npm as @slhssb/dsh-advisor; the repository carries the GitHub
dsh-plugin topic for discovery. Bump version in package.json, publish,
then tag the release:

npm publish --access public
git tag v0.1.0 && git push --tags