前言¶

在 DeepSeek Harness（DSH）裏做編碼智能體時，一個常見情況是：agent 反覆讀代碼、改文件、跑命令，然後遇到同樣的失敗。此時查一下官方文檔、GitHub 或網頁，可能比繼續本地試錯更快。

dsh-research-nudge 是爲這類情況提供的 advisory research-debt guard。它不直接執行搜索，也不攔截工具，只是在下一個模型步驟里加入一條短提醒，提醒 agent 先判斷是否需要外部證據。

這是什麼¶

dsh-research-nudge 是 Leitarkkk 維護的 DSH 插件，採用 MIT 許可證。它觀察 agent 的工具執行情況，當一段時間內出現讀取、編輯、執行和重複失敗，但沒有使用被識別的外部研究工具時，會加入一個短提醒。

它主要做這幾件事：

• 把本地循環的累積成本變成一個確定性分數，稱爲 Research Debt。
• 當狀態滿足條件時，在下一個模型步驟中加入提醒。
• 提供一個模型可見的 research_nudge_snooze 工具，供 agent 按 agent 粒度臨時靜音。
• 在 DSH 配置中註冊一個 research-nudge 行，便於覆蓋設置。

它不做這些：

• 不調用 LLM。
• 不執行搜索。
• 不阻塞工具調用。
• 不強制 agent 瀏覽網頁。

核心功能¶

觀察本地試錯¶

插件關注的是 agent 在本地循環中的信號：讀取代碼、編輯文件、執行命令、失敗、再次失敗。它會把這些成本累積成 Research Debt。

加入提醒¶

當 Research Debt 或相關狀態達到插件設定的條件時，插件會把一條短提醒加入下一個模型步驟。提醒會建議 agent 暫停並判斷：當前任務是否可以靠本地證據完成；如果不確定 API、報錯或平臺行爲，是否需要查官方文檔、GitHub 或網頁。

提醒後，默認會進入 10 分鐘冷卻，期間不再重複提醒。

識別外部研究¶

當 agent 使用被識別的研究工具時，該 agent 的累積狀態會被重置。這裏的“研究工具”由插件配置中的 researchTools 規則匹配。

臨時靜音¶

如果 agent 確實想基於本地證據繼續推進，可以調用 research_nudge_snooze 工具臨時抑制提醒。默認持續 30 分鐘，並受 maxAgentSnoozeMinutes 上限約束。

需要注意：

• 靜音是按 agent 的，其他 agent 不受影響。
• 靜音期間 Research Debt 繼續累積，它不算研究，也不會清除失敗計數。
• 如果 research_nudge_snooze 調用失敗，它會被記錄爲普通失敗調用，不會重置債務。

安裝與啓用¶

先確認環境滿足前置條件：

DeepSeek Harness 0.1.0-rc.7
Node.js ^22.19.0 或 >=24.0.0

從 GitHub 安裝：

dsh plugin --profile web add github:Leitarkkk/dsh-research-nudge

如果希望固定版本，可以固定 tag 或 commit：

dsh plugin --profile web add github:Leitarkkk/dsh-research-nudge#<tag-or-commit>

如果該包已發佈到 npm，也可以使用預構建安裝：

dsh plugin --profile web add dsh-research-nudge

Git 安裝會運行包中的 prepare 構建。pnpm 可能會拒絕該構建，直到你顯式信任它。建議先檢查源碼和 MIT 許可證，再按 DSH/pnpm 提示處理構建信任問題。

安裝後，檢查組合後的配置層，然後重啓 profile：

dsh --profile web --dump-config
dsh web

典型用法¶

覆蓋插件配置¶

插件會在 DSH 配置中註冊一個 research-nudge 行。你可以在 profile 的 cordis.patch.yml 中覆蓋這一行：

- id: research-nudge
  config:
    enabled: true
    debtThreshold: <number>
    researchTools:
      - <research-tool-pattern>
    reminder: <custom-string>
    debug: false

DSH 的 patch 層會替換這一行的整個 config 值，而不是深合併，因此覆蓋時建議把該行需要保留的字段寫完整。

本地開發安裝¶

如果你要修改或調試插件，可以本地克隆並安裝：

git clone https://github.com/Leitarkkk/dsh-research-nudge.git
cd dsh-research-nudge
npm install
npm run check
dsh plugin --profile web add .

使用臨時靜音¶

在 agent 工具調用上下文中，可以使用模型可見工具：

research_nudge_snooze

它用於抑制一段時間的提醒，默認 30 分鐘，並受 maxAgentSnoozeMinutes 限制。

適用場景與注意¶

適合使用它的場景：

• 在 DSH 的 web profile 或其他 profile 中運行編碼 agent。
• agent 經常進行本地讀取、編輯、執行和失敗重試。
• 你希望用輕提醒方式，減少無外部證據的重複試錯。
• 你接受插件以 advisory 方式工作，不直接搜索、不攔截工具。

使用前注意：

• 插件作爲 DSH 插件運行，使用當前 dsh 進程可用的權限；安裝前應檢查源碼與許可證。
• 該插件是提醒型，不是強制搜索；提醒會允許不需要外部研究的任務繼續。
• 配置覆蓋是整行替換，不是深合併。
• 臨時靜音隻影響調用它的 agent，不重置 Research Debt。
• npm 安裝命令以該包已發佈爲前提；未發佈時優先使用 GitHub 安裝或本地路徑安裝。

鏈接¶

插件目錄頁：

https://www.skillhub.cn/plugins/Leitarkkk/dsh-research-nudge

GitHub 倉庫：

https://github.com/Leitarkkk/dsh-research-nudge