dsh-research-first
开发前「调查优先」助手插件（DeepSeek Harness，简称 DSH）。
让 agent 在动手改代码前，先做一次低成本的确定性调查——但不硬拦，避免"查不到就卡死"（因噎废食）。
未调查就想 write/edit/bash
│
▼
软引导：放行 + 注入一条提醒（模型可见、写入会话日志）
│
查证受阻（web_search 失败 / GitHub 不可达）
│
▼
提醒用户受阻原因，可询问是否继续 —— 全程留痕，可追溯---
为什么需要它
LLM 编程有三个真实顽疾，且互相叠加：
| 顽疾 | 表现 |
|---|---|
| 动手前靠猜 | 需求/API 没查清就 write，凭记忆而非事实改代码 |
| 边踩雷边改 | 连续失败不回头，反复瞎试，忽略社区已知的 workaround |
| 用过时知识 | 记忆里的版本/端点已失效，按旧写法改新项目 |
核心洞察：一次便宜的查询，换掉一次昂贵的返工。
---
设计理念
> 把「查证」做成优先尝试 + 无感引导 + 受阻提醒 + 全程留痕，而不是极端的必要条件。
为什么不硬拦？ 现实中存在查证不可行的场景（如内网环境、网络受限、无官方文档）。如果"查不到就终止开发"，就是因噎废食。所以默认软引导——提醒但不阻断，把选择权留给 agent 和用户。
| 行为 | 说明 |
|---|---|
软引导（默认 remind） | 未调查就想修改 → 不拦截，注入提醒（模型可见 + 进会话日志） |
| 查证受阻检测 | 调查工具（web_search 等）失败 → 提醒"查证受阻，可询问用户是否继续" |
| 调查规范注入 | 往 systemPrompt 加"黄金调查姿势"：带版本查、先找官方途径、受阻时说明 |
| 踩雷提醒 | 连续失败后，提醒先查社区反馈（GitHub issues） |
| 全程留痕 | 所有提醒以 plugin-sourced 消息写入会话日志，可追溯、可回放 |
需要硬约束时，把 intensity 改成 warn（挂审批）或 block（拒绝）即可。
---
与同类插件的定位差异
| 插件 | 定位 | 与本插件的区别 |
|---|---|---|
dsh-doublecheck | 工程纪律门禁（盘需求、红绿测试、对抗审查） | 它默认倾向硬约束（block 编辑）；本插件默认软引导 |
dsh-pain-point-check | 踩雷后否决式逼停 | 它否决非调查工具；本插件提醒不阻断 |
| dsh-research-first（本插件） | 调查优先的轻量助手 | 无感、不阻断、受阻时把决定权交给用户 |
三者不冲突，可叠加：想要极致纪律用 doublecheck，想要轻量无感用本插件。
---
安装
方式一：官方（推荐，需 pnpm）
dsh plugin --profile web add github:outnever/dsh-research-first重启：
dsh web方式二：手动（无需 pnpm）
# 1. symlink 进 profile 的 node_modules
ln -sfn /绝对路径/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 --profile web --dump-config | grep -A2 research-first
# 期望看到 id: research-first / name: dsh-research-first / intensity: remind---
配置项
| 字段 | 默认 | 说明 |
|---|---|---|
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（waterfall）：标记调查 / 决定放行·提醒·拒绝tools/post-execute（waterfall）：注入additionalContexts提醒、检测受阻、统计失败agent/pre-step（waterfall）：step===1时重置调查标记systemPrompt.section：注入调查规范
关键实现细节：提醒消息是手写的 UserMessage 结构（{ id, role:'user', content, source:{kind:'plugin',...} }），用 Node 内置 crypto.randomUUID() 生成 id，零 dsh 包 import——因此能通过 symlink 直接加载，无需 pnpm 解析依赖。
---
测试
node test.mjs
# 19 项 mock 单元测试：软引导、受阻提醒、踩雷、block/warn 档、规范注入、turn 重置无需安装依赖——lib/index.js 只 import node:crypto。
---
已知限制
remind档的提醒是"注入会话的软提示"，不强制——模型仍可能忽略。要强制用block。- "带版本查 / 先找官方途径"靠 systemPrompt 规范软引导，无法用规则硬保证（本质是模型的认知意愿）。
---
贡献
欢迎提 Issue 和 PR。改动请：
1. 保持零 dsh 包 import（这是 symlink 免 pnpm 加载的前提）； 2. 同步更新 test.mjs 并跑通 node test.mjs； 3. 更新 README 的行为说明。
---
License
[MIT](LICENSE)