dsh-deep-research

一句话定位

为 DeepSeek Harness 注册一个名为 deep_research 的工具，让模型在面对"调研/对比/文献搜集"类请求时，按控制论+信息论设计的多轮自适应流程自动拆题、并行研究、收尾成稿并可选对抗审查，整套跑在宿主官方 workflow 引擎上、复用内置 web 工具。

核心能力

• 注册 deep_research 工具，由模型按工具描述自动触发，调用即启动一次完整研究流程（src/index.ts:401-413）
• 自动定义答案空间与信息维度：先由规划代理声明这份研究要支撑什么判断，再按维度拆解子问题并声明覆盖盲区（src/index.ts:207-240）
• 多轮自适应研究闭环：第一轮并行研究所有子问题，每轮把高优先级信息缺口自动派发下一轮补充研究，规划盲区会被定向侦察验证而非静默接受（src/index.ts:275-312）
• 综合子代理按"率失真"原则压缩为带置信度与来源的最终报告，明确保留不确定性与已验证盲区（src/index.ts:335-351）
• 可选对抗性审查：引用纠错（URL 是否可达/支撑结论）、覆盖度审计、矛盾与过度自信标注（src/index.ts:353-373）
• 复用官方 workflow 引擎与内置 web_search/web_fetch：零自研编排、零自研网络逻辑，子代理继承宿主工具集（src/index.ts:483-516）

技术实现

• 语言: TypeScript（ESM，原生 TS 源码，erasable-only 语法约束，无构建步骤即可被 Node 22+ 原生类型剥离加载；编译产物在 lib/types/，package.json#main 也指向那里）
• 关键依赖: @deepseek-ai/dsh-tools（工具注册）、@deepseek-ai/dsh-workflow（WorkflowMeta 类型与官方引擎）、cordis ^4.0.0-rc.7（插件宿主框架）
• 架构模式: cordis 插件，export const inject = ['tools', 'workflows']；在 apply 中通过 ctx.tools.register 注册 deep_research 工具，工具执行时通过 ctx.workflows.start 把一段静态工作流脚本（String.raw 字面量，含规划/研究/综合/审查四阶段）提交给官方引擎跑在 worker 线程上；并通过 cordis.patch.yml 把插件行插入 profile 的 bundles
• 入口文件: src/index.ts（name/inject/apply 导出位于 67-70 / 386-539；运行时被宿主加载）

适用场景

需要就复杂主题写一份带引用、能经得起追问的研究报告的人——比如"调研一下 MCP 生态现状并对比几家主流实现"、"按这份问题清单做选型研究"、"给我一份带文献支撑的 XX 行业分析"。在对话里直接说需求即可，模型会自己判断要不要走 deep_research，并按"用途越明确，答案空间越准"的原则生成更聚焦的报告。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:omdsh-dev/dsh-deep-research

若 pnpm 把 https URL 重写成 git+ssh（本机全局 git insteadof 配置所致），显式用 git+https://... 形式；如 dsh plugin 提示需要 allowBuilds，按提示在 $DSH_HOME/profiles/<name>/pnpm-workspace.yaml 加一行即可。profile 必须在 dsh.profile.bundles 列出本包才会被注入。

配置项

模型分级是按 OpenAI 指南设计的：规划/综合/审查吃模型能力，研究代理是"高频低价值"环节可换便宜模型；这是按角色配置而非单模型，覆盖原 profile 路由。

常见问题

Q: 这个插件和官方 .claude/skills/deep-research 是同一回事吗？

A: 不是。前者是 cordis 插件，挂在官方 workflow 引擎上跑，注册模型可见的 deep_research 工具；后者是 skill 体系，由模型按 skill 描述触发。README 与源码都明确两者独立、互不替代，按需选用。

Q: 安装后需要额外配置吗？

A: 不需要。Config 全部可选，按默认值也能跑。最常见的优化是按角色分层模型——规划/综合/审查用强模型、研究代理换便宜模型，能显著降本。

Q: depth 参数到底是几轮？

A: depth 等于研究阶段的最大轮次减一：1=初步（最多 2 轮），2=深入（默认，最多 3 轮），3=穷尽（最多 4 轮）。达到上限就停；更常见的停机条件是某一轮没有新增 high-priority 缺口（边际信息增益≈0）。

Q: 有些 Web Profile 装上后没生效怎么办？

A: 本插件运行时依赖官方 workflow provider（ctx.workflows）。如果 profile 没声明该 provider，loader 会保持 pending；此时要么在 DSH Hub 登记 workflows provider 关系，要么改用已经提供该服务的 profile 组合。

Q: 我已经列好问题了，怎么跳过自动拆解？

A: 把问题清单作为字符串传给 questions（每行一条，或 1./2./3. 编号均可），插件会跳过规划阶段直接进入并行研究；如果第一轮就拿到全部证据，一轮收敛。

Q: 怎么升级和卸载？

A: 升级 dsh plugin --profile <profile> update；卸载 dsh plugin --profile <profile> remove @dsh-external/dsh-deep-research，或者从 profile 的 package.json 移除依赖后再次 update。

上手难度

入门 — 安装一行命令即可使用，所有配置都有默认值；只有想把模型按角色分层降本、或把研究深度拉满到穷尽模式时才需要看 depth/模型配置。

已知问题与限制

• 必须由 DSH 官方 workflow provider 与内置 web_search/web_fetch 提供运行时能力；若目标 profile 未声明 workflows provider（如部分 Web Profile 组合），loader 会保持 pending（README.md:117-122）
• 工具入参 topic 不能为空、depth 仅接受 1/2/3，否则在进入 ctx.workflows.start 之前直接抛错（src/index.ts:464-472 / test/regression.test.mjs:516-569）
• 工具内部判断 result.stopReason !== 'completed' 会抛错，maxTotalAgents 传 0 会被引擎直接判为 INVALID_ARGUMENT——所以 null/undefined 表示沿用引擎默认，绝不写入 0（src/index.ts:394-396 / 521-531）
• 源码必须保持 erasable-only TS 语法（无 enum/namespace/参数属性），否则 Node 22 的原生类型剥离会响亮抛错（src/index.ts:53-58）

把 deep-research 流程做成 DSH 扩展插件（plugin，与 skill 体系分开）， 基于 DSH 官方 workflow 引擎（ctx.workflows / @deepseek-ai/dsh-workflow-workerthread） 实现，按 控制论 + 信息论 设计——不是固定提示词流水线，而是活的、自适应的研究闭环。

理论 → 机制

结构

dsh-deep-research/
├── package.json    # @dsh-external/dsh-deep-research（声明 dsh.bundle.patch）
├── cordis.patch.yml  # bundle 补丁：按包名插入插件行
├── src/index.ts    # cordis 插件：注册 deep_research 工具，提交官方 workflow 脚本（原生 TS，零构建）
├── tsconfig.json   # typecheck 配置（project references 解析到 sibling deepseek-harness 源码）
└── README.md

开发与检查

pnpm install        # 仅 typescript/@types/node（typecheck 用）
pnpm run typecheck  # tsc -b，类型从 sibling deepseek-harness checkout 解析

源码即运行时：包入口直接指向 src/index.ts，无构建步骤。profile 安装的副本位于 node_modules 下，由 dsh 源码启动器的 tsx hook 加载（Node 原生类型剥离拒绝 node_modules 内的文件）；源码 checkout 在 node_modules 外直跑时也可用 Node ≥22.18 原生剥离。要求 erasable-only TS 语法（无 enum/命名空间等）， node --test/pnpm typecheck 会挡住不可移植写法。

安装与使用方式

包声明了 dsh.bundle.patch（cordis.patch.yml），通过 dsh plugin 装进任意 profile （把 <profile> 换成 tui / headless / web 或自建 profile）：

dsh plugin --profile <profile> add git+https://github.com/dsh-external/dsh-deep-research.git
dsh --profile <profile>        # 重启生效：工具 deep_research 随 profile 注入

若 pnpm 把 https URL 重写成 git+ssh（本机全局 git insteadof 配置所致），用上面的 git+https:// 形式；dsh plugin 会提示需要 allowBuilds 时按提示在 $DSH_HOME/profiles/<name>/pnpm-workspace.yaml 加一行即可。

工具由模型按工具描述自动触发（深度研究/调研/多源信息综合分析/研究报告/文献搜集）， 对话中直接说人话即可：

• 「深度调研一下 MCP 生态现状，重点对比几家主流实现，出一份带引用的报告」
• 「按这份问题清单做研究：1. ... 2. ...」（已有清单 → 跳过自动拆解，直接并行研究）
• 「调研一下 A/B 方案，purpose 是决定我们选哪个」（用途越明确，答案空间越准）
• 复杂主题会自动扩展轮次（自适应闭环），简单主题一轮收敛；想要更严谨传 depth: 3， 要引用纠错和覆盖度审计传 review: true。

成本建议：模型分层——规划/综合用强模型、研究用便宜模型（配置 plannerModel/researcherModel/synthesizerModel/reviewerModel），可显著降本。

依赖要求：profile 的组合必须包含官方 workflow 引擎与内置 web 工具——dsh 官方 base 组合自带，无需额外安装；peer 依赖（@deepseek-ai/dsh-tools 等）由组合提供， profile 的 autoInstallPeers: false 可避免向 registry 查找未发布的 @deepseek-ai/*。

更新 / 卸载：

dsh plugin --profile <profile> update
dsh plugin --profile <profile> remove @dsh-external/dsh-deep-research
# 或：从 profile 的 package.json 移除依赖后 dsh plugin --profile <profile> update

工具参数

配置（可选）

设计说明

• plugin ≠ skill：不注册进 ctx.skills；触发靠工具描述（深度研究/调研/多源信息综合分析等）。
• 复用官方能力：编排走官方 workflow 引擎（worker 隔离、并发/总数 caps、取消、进度事件、wf-runs 记录）；搜索/抓取走内置 web_search/web_fetch——插件零网络逻辑、零自研编排。
• 不碰 TUI：无 tuiPrompt / overlay / system-prompt 注入，规避 prompt 槽位 disposed 类崩溃。
• 取消传播：exec.signal 传入 workflow run，取消时子代理随之中止。
• 失败隔离：单个子问题研究失败只在该节标注；规划失败则工具报错，主代理可调参重试。
• 技能模板（.claude/skills/deep-research）保留不动，两者独立。

Profile 兼容性

本插件运行时依赖 DSH 官方 workflow 引擎（ctx.workflows，peer：@deepseek-ai/dsh-workflow）。 请把它安装进提供 workflows provider 的 Profile（如 tui/headless 组合）；若 Profile 未声明 该 provider（如部分 Web Profile 组合），Loader 会保持 pending——此时请先在 DSH Hub 登记 workflows provider 关系或改用提供该服务的组合。编译产物（lib/types/index.js）为官方 0810 生产入口，Node 原生可加载。