前言¶
用編碼智能體改代碼，常見的毛病是它先動手：不查文檔裏當前的 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
