Introduction

A common issue when coding agents modify code is that they act first: they don’t check the current API signatures in the documentation, don’t look at existing implementations in the repository, and don’t check if the community has encountered the same pitfalls, resorting to trial and error after writing. One remedy is to forcibly intercept before tool calls, forcing an investigation first. However, the investigation itself might be impossible—offline environments, restricted networks, or documentation that simply cannot be fetched—and the task gets stuck.

dsh-research-first takes a different path: it doesn’t block by default. Instead, when an agent is about to write, modify, or execute without investigating, it injects a model-visible reminder into the session and logs it to the session log; when investigation tools fail, it prompts the user to decide whether to continue. Below is an introduction to the plugin’s features, installation, and configuration.

What is it

dsh-research-first is a plugin for DeepSeek Harness (DSH), maintained by outnever, under the MIT license. In a nutshell: it gently nudge the agent to investigate documentation, code, and the community before acting, detect when investigation is blocked, and log every reminder to the session log.

DSH’s philosophy is “everything is a plugin.” This plugin does not introduce private mechanisms; all functionality is implemented solely based on official DSH extension points.

Core Features

Soft Reminders (Default remind Mode)

When an agent calls write, modify, or execute tools without investigating, the plugin does not forcibly block; it injects a reminder and the process continues. The reminder is visible to the model and recorded in the session log.

Blocked Research Detection

When investigation tools like web_search fail, the plugin alerts that research is blocked and asks the user if they want to continue.

Research Norms Injection

Injects a set of “golden research habits” into the systemPrompt: including version numbers during search, preferring official tools, and explaining reasons when blocked. Note that this is only soft guidance via prompts.

Failure Reminders

After consecutive failures reach a threshold, it reminds the agent to check community feedback (GitHub issues) first.

Full Audit Trail

Every reminder is a message from the plugin, making it replayable and auditable.

Three Intensity Levels

The intensity level is configurable in three tiers: remind (alert) / warn (requires approval) / block (reject). Default is remind; switch to block when hard enforcement is needed.

Installation and Enablement

dsh plugin --profile web add github:outnever/dsh-research-first

Restart after installation:

dsh web

Manual Installation (No pnpm)

If pnpm is not available in the environment, you can clone the plugin repository locally, note the absolute path, and then follow these three steps.

  1. Create a symlink:
ln -sfn /absolute/path/to/dsh-research-first ~/.dsh/profiles/web/node_modules/dsh-research-first
  1. Insert into ~/.dsh/profiles/web/cordis.patch.yml:
insert:
  - id: research-first
    name: 'dsh-research-first'
    config: { intensity: remind }
  1. Restart dsh web.

The prerequisite for this method to work is that the plugin maintains zero imports of dsh packages—once a dsh package is imported, dependencies cannot be resolved when loading via symlink.

Verification

After the steps above, use the following command to confirm the plugin is loaded:

dsh --profile web --dump-config | grep -A2 research-first

Expected output:

id: research-first
name: dsh-research-first
intensity: remind

Dependencies are declared via peerDependencies: @deepseek-ai/cordis ^4.0.1, @deepseek-ai/dsh-tools 0.1.0-rc.6.

Configuration

Config Default Meaning
intensity remind remind alert / warn requires approval / block reject
failureThreshold 2 Number of consecutive failures before triggering the community feedback reminder
injectNorm true Whether to inject research norms into systemPrompt
detectBlocked true Whether to detect investigation tool failures and alert
investigationTools read, grep, glob, web_search, read_image, ask_user_question, skill Tool names counted as “investigation”
mutationTools write, edit, bash, pwsh, str_replace_editor Tool names counted as “write/modify/execute”

How it Works

The plugin is implemented solely using official DSH extension points:

  • tools/pre-execute / tools/post-execute: Intervene before and after tool execution to handle investigation judgment, reminder injection, blocked research detection, and failure statistics;
  • agent/pre-step: State reset at the start of a turn;
  • systemPrompt.section: Inject research norms into systemPrompt.

Reminders enter the session as messages from the plugin, making them replayable and auditable. Implementation-wise, the code relies only on Node’s built-in node:crypto and has zero imports of dsh packages.

Testing

node test.mjs

The repository includes 19 mock unit tests covering soft reminders, blocked research, failure reminders, block/warn modes, norm injection, and turn reset.

Use Cases and Notes

Suitable scenarios:

  • Want the agent to investigate documentation, code, and community before acting, but don’t accept tasks being forcibly stuck;
  • Offline or restricted network environments where investigation is infeasible, and you want to hand decision-making back to the user;
  • Need reminders to be logged for audit trails and replay.

A few notes:

  1. remind is a soft prompt in the session and not mandatory; the model might ignore it. If enforcement is needed, set intensity to block (or warn, which requires approval).
  2. “Searching with versions, preferring official tools” is only soft guidance via systemPrompt; it cannot be strictly guaranteed at the rule level.
  3. The plugin runs with the permissions of the current DSH process; check the source code and license (MIT) before installing.
  4. If you want to contribute, the repository requires: maintaining zero dsh package imports; updating test.mjs and ensuring node test.mjs passes; updating behavior descriptions in the README.

Conclusion

dsh-research-first doesn’t do anything heavy: it doesn’t write code for you, nor does it intercept crudely. It simply offers a replayable reminder when the agent skips investigation, and returns decision-making to humans when investigation fails. For DSH users who want their agents to “look up materials before acting,” it is a low-cost, auditable choice.

  • GitHub: https://github.com/outnever/dsh-research-first
  • Community Directory (Independent Site): https://www.skillhub.cn/plugins/outnever/dsh-research-first