调查优先助手outnever/dsh-research-first

dsh-research-first

开发前「调查优先」助手插件（DeepSeek Harness，简称 DSH）。

让 agent 在动手改代码前，先做一次低成本的确定性调查——但不硬拦，避免"查不到就卡死"（因噎废食）。

English

未调查就想 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