前言¶
用编码智能体改代码，常见的毛病是它先动手：不查文档里当前的 API 签名，不翻仓库里已有的实现，也不看社区有没有踩过同样的坑，写完再一轮轮试错。一种补救是在工具调用前硬性拦截、强制先调查，但调查本身可能无法进行——离线环境、网络受限、文档根本拉不下来——任务就卡在那里。
dsh-research-first 走的是另一条路：默认不阻断，而是在 agent 未调查就要写、改、执行时，往会话里注入一条模型可见的提醒，并记录到会话日志；调查工具失败时提醒用户，由人决定是否继续。下面介绍这个插件的功能、安装和配置。
这是什么¶
dsh-research-first 是 DeepSeek Harness（DSH）的插件，由 outnever 维护，MIT 许可证。一句话定位：在 agent 动手之前温和地推它先去调查文档、代码和社区，检测调查被阻断的情况，并把每条提醒都记录到会话日志。
DSH 的理念是「一切皆插件」。这个插件没有引入私有机制，全部功能只基于 DSH 官方扩展点实现。
核心功能¶
软提醒（默认 remind 模式）¶
agent 未调查就调用写、改、执行类工具时，插件不硬阻断，注入一条提醒后流程继续。提醒对模型可见，同时记录到会话日志。
阻断研究检测¶
web_search 等调查工具失败时，插件会提醒研究被阻断，并询问用户是否继续。
研究规范注入¶
向 systemPrompt 注入一份 golden research habits：搜索时带上版本、优先官方工具、被阻断时说明原因。注意这只是通过提示词做的软引导。
失败提醒¶
连续失败达到阈值后，提醒先查社区反馈（GitHub issues）。
全量留痕¶
每条提醒均为插件来源消息，可回放、可审计。
三档强度¶
intensity 三档可配：remind（提醒）/ warn（需批准）/ block（拒绝）。默认 remind，需要硬性执行时切到 block。
安装与启用¶
官方安装（推荐，需要 pnpm）¶
dsh plugin --profile web add github:outnever/dsh-research-first
装完重启：
dsh web
手动安装（无 pnpm）¶
如果环境里没有 pnpm，可以先克隆插件仓库到本地，记下绝对路径，然后按下面三步操作。
1、建立 symlink：
ln -sfn /absolute/path/to/dsh-research-first ~/.dsh/profiles/web/node_modules/dsh-research-first
2、在 ~/.dsh/profiles/web/cordis.patch.yml 中插入：
insert:
- id: research-first
name: 'dsh-research-first'
config: { intensity: remind }
3、重启 dsh web。
这条路能走通的前提，是插件保持零 dsh 包导入——一旦导入 dsh 包，symlink 加载时依赖就解析不了。
验证¶
经过上面的步骤，用下面的命令确认插件已被加载：
dsh --profile web --dump-config | grep -A2 research-first
预期输出：
id: research-first
name: dsh-research-first
intensity: remind
依赖通过 peerDependencies 声明：@deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-tools 0.1.0-rc.6。
配置项¶
| 配置项 | 默认值 | 含义 |
|---|---|---|
intensity |
remind |
remind 提醒 / warn 需批准 / block 拒绝 |
failureThreshold |
2 |
触发社区反馈提醒前的连续失败次数 |
injectNorm |
true |
是否向 systemPrompt 注入研究规范 |
detectBlocked |
true |
是否检测调查工具失败并提醒 |
investigationTools |
read, grep, glob, web_search, read_image, ask_user_question, skill |
计入「调查」的工具名 |
mutationTools |
write, edit, bash, pwsh, str_replace_editor |
计入「写改执行」的工具名 |
工作原理¶
插件仅基于 DSH 官方扩展点实现：
tools/pre-execute/tools/post-execute：分别在工具执行前后介入，完成调查判定、提醒注入、阻断研究检测与失败统计；agent/pre-step：回合开始时的状态重置；systemPrompt.section：向 systemPrompt 注入研究规范。
提醒以插件来源消息的形式进入会话，所以能回放、能审计。实现上代码只依赖 Node 内置的 node:crypto，零 dsh 包导入。
测试¶
node test.mjs
仓库自带 19 个 mock 单元测试，覆盖软提醒、阻断研究、失败提醒、block/warn 模式、规范注入、回合重置。
适用场景与注意¶
适合的情况：
- 希望 agent 动手前先查文档、代码、社区，但不接受任务被硬性卡住；
- 离线或网络受限环境，调查不可行时希望把决定权交回用户；
- 需要提醒留痕、事后回放审计。
几点注意：
1、remind 是会话中的软提示，不强制，模型可能忽略；需要强制时把 intensity 设为 block（或 warn，需批准）。
2、「带版本搜索、优先官方工具」仅通过 systemPrompt 软引导，规则层面无法硬保证。
3、插件以当前 dsh 进程的权限运行，安装前应检查源码与许可证（MIT）。
4、如果想参与贡献，仓库要求：保持零 dsh 包导入；更新 test.mjs 并保持 node test.mjs 通过；更新 README 中的行为描述。
结尾¶
dsh-research-first 做的事情不重：不替你写代码，也不粗暴拦截，只是在 agent 跳过调查时递上一条可回放的提醒，调查走不通时把决定交还给人。对想让智能体「先看资料再动手」的 DSH 用户，它是一个成本低、可审计的选择。
- GitHub：https://github.com/outnever/dsh-research-first
- 社区目录（独立站点）：https://www.skillhub.cn/plugins/outnever/dsh-research-first
