dsh-research-nudge
DeepSeek Harness 的研究债务防护工具：促使编码代理在反复进行本地试错前，先搜索文档、GitHub 和网络。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:Leitarkkk/dsh-research-nudge#9c89186e99485ea1c941af6fe76567907b69c606Research Nudge 以 dsh-research-nudge 发布，当前版本为 0.3.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 简体中文
An advisory research-debt guard for DeepSeek Harness. It notices when an agent spends a long stretch reading, editing, executing, and repeating failures without consulting external evidence, then adds a short reminder to the next model step.
It does not call an LLM, perform a search, block a tool, or force the agent to browse. The reminder explicitly allows self-contained work to continue normally.
Agents sometimes fall into a local trial-and-error loop:
read → guess an unfamiliar API → edit → run → fail → edit → run → same failure
A search of the official docs, an exact error message, or an existing GitHub issue may resolve that uncertainty faster. dsh-research-nudge turns the growing cost of the local loop into a deterministic score called Research Debt.
This is a hypothetical sequence calculated from the documented default weights, not production telemetry. It shows exactly how the score would cross the threshold:
| Step | Signal | Added debt | Total |
|---|---|---|---|
| Read local code | ordinary tool | +1 | 1 |
| Edit a file | mutation | +2 | 3 |
| Run and fail | execution + failure | +1 +4 | 8 |
| Edit again | mutation | +2 | 10 |
| Run and hit the equivalent failure again | execution + failure + repeated failure | +1 +4 +6 | 21 |
The default threshold is 20, so the last result carries an additional model-visible context:
[Research Nudge]
Pause and reflect before continuing:
1. What problem am I trying to solve right now? Restate it precisely.
2. What approach am I currently taking, and how many attempts has it taken without success?
3. Am I fully confident this approach will work? If I am guessing at an API, an error message, a library's behavior, or platform details I have not verified, I am not fully confident.
4. If I am not fully confident: external research is cheaper than more local trial-and-error. Search the official documentation, GitHub issues, existing libraries, or the exact error message before trying again.
Do not search merely to satisfy this reminder. If the task is self-contained and external research would not help, continue normally. If you are deliberately making progress from local evidence and do not want another reminder for a while, use the research_nudge_snooze tool.
Current signals: debt=21/20, tool_calls_since_research=5,
failures=2, repeated_failures=1.
Equivalent failures are fingerprinted after normalizing changing numbers and addresses, so TypeError at line 123 and TypeError at line 456 count as a repeat. A recognized research tool resets the accumulated state for that agent.
Prerequisites:
0.1.0-rc.7 (the current next release line)^22.19.0 or >=24.0.0, matching the current DSH baselineFrom GitHub:
dsh plugin --profile web add github:Leitarkkk/dsh-research-nudge
Git installs run this package's prepare build. pnpm may reject that build until you explicitly trust it. Follow the exact allowBuilds entry printed by DSH/pnpm, review the source first, and pin a tag or commit for reproducible installs:
dsh plugin --profile web add github:Leitarkkk/dsh-research-nudge#<tag-or-commit>
After the package is published to npm, the prebuilt install is:
dsh plugin --profile web add dsh-research-nudge
Verify the composed layer, then restart the profile:
dsh --profile web --dump-config
dsh web
git clone https://github.com/Leitarkkk/dsh-research-nudge.git
cd dsh-research-nudge
npm install
npm run check
dsh plugin --profile web add .
Relative paths are resolved from the directory where dsh plugin is invoked.
| Signal | Debt |
|---|---|
| Ordinary tool call | +1 |
| File mutation | +2 |
| Shell/build/test execution | +1 |
| Failed tool result | +4 |
| Repeated equivalent failure | +6 |
| Recognized external research tool | reset to 0 |
A reminder is eligible when any condition is met:
After a reminder, the per-agent state continues accumulating but further reminders are suppressed for 10 minutes. Names are normalized before classification and research matching, so WebSearch, web_search, and web-search are treated consistently.
An agent that is deliberately making progress from local evidence can call the model-visible research_nudge_snooze tool to suppress reminders for a while (defaults to 30 minutes, capped by maxAgentSnoozeMinutes):
researchTools pattern such as search (which substring-matches the snooze tool's own name) can never turn a failed snooze into a debt reset.The bundle inserts a row with the id research-nudge. Override that row in the profile's cordis.patch.yml:
- id: research-nudge
config:
enabled: true
debtThreshold: 20
maxToolCallsWithoutResearch: 15
maxMinutesWithoutResearch: 15
cooldownMinutes: 10
ordinaryToolDebt: 1
mutationDebt: 2
executionDebt: 1
failureDebt: 4
repeatedFailureDebt: 6
maxAgentSnoozeMinutes: 60
researchTools:
- web_search
- web_fetch
- github_search
- docs_search
- fetch_url
debug: false
DSH patch layers replace a row's entire config value rather than deep-merging it. Any omitted fields above fall back to this plugin's schema defaults. reminder may also be set to a custom string.
| Field | Default | Meaning |
|---|---|---|
enabled | true | Register the lifecycle listener |
debtThreshold | 20 | Debt score that makes a reminder eligible |
maxToolCallsWithoutResearch | 15 | Call-count fallback threshold |
maxMinutesWithoutResearch | 15 | Elapsed-time fallback threshold |
cooldownMinutes | 10 | Minimum time between reminders |
ordinaryToolDebt | 1 | Weight for other local tools |
mutationDebt | 2 | Weight for write/edit/delete-style tools |
executionDebt | 1 | Weight for shell/build/test-style tools |
failureDebt | 4 | Extra weight for a failed result |
repeatedFailureDebt | 6 | Extra weight for an equivalent consecutive failure |
maxAgentSnoozeMinutes | 60 | Upper bound for one agent-requested snooze of reminders |
researchTools | common web/docs/GitHub names | Substring patterns that reset state after normalization |
reminder | built-in advisory text | Model-visible reminder body |
debug | false | Log resets and queued reminders to stderr |
The plugin listens to the current tools/post-execute waterfall. It observes the typed ToolExecution and ToolExecutionResult, delegates to later listeners with next(), then prepends one official createUserMessage(...) notice through PostToolDecision.additionalContexts. Accept/block decisions and existing contexts are preserved.
The plugin declares inject: ['tools'] and registers its research_nudge_snooze tool through ctx.tools.register(...); no other service is read from ctx. State is held in a WeakMap keyed by the calling agent and disappears with the agent/runtime.
The adapter is compiled and tested against the official @deepseek-ai/dsh-tools and @deepseek-ai/dsh-llm 0.1.0-rc.7 contracts. DSH is still a Developer Preview and explicitly allows compatibility-breaking changes. If a later DSH release changes the tool waterfall or message contract, update the small adapter in src/index.ts; the deterministic policy in src/policy.ts is independent.
npm ci
npm run check
npm pack --dry-run
See CONTRIBUTING.md for contribution guidelines.