dsh-deep-research

One-Line Positioning

Register a tool named deep_research with DeepSeek Harness. When the model receives requests for "research/comparison/literature collection," it automatically decomposes the topic, conducts parallel research, drafts the final report, and optionally performs adversarial review—all following a cybernetic and information-theoretic multi-round adaptive flow, running on the host's official workflow engine and reusing built-in web tools.

Core Capabilities

• Register the deep_research tool, automatically triggered by the model based on the tool description. Calling it starts a complete research flow (src/index.ts:401-413)
• Automatically define answer space and information dimensions: first, the planning agent declares what judgments the research should support, then decompose sub-questions by dimension and declare coverage blind spots (src/index.ts:207-240)
• Multi-round adaptive research loop: first round researches all sub-questions in parallel, each round automatically dispatches high-priority information gaps to the next round for supplementary research, planned blind spots are proactively scouted and verified rather than silently accepted (src/index.ts:275-312)
• The synthesis sub-agent compresses into a final report with confidence levels and sources following the "rate-distortion" principle, clearly preserving uncertainties and verified blind spots (src/index.ts:335-351)
• Optional adversarial review: citation error-checking (whether URLs are reachable/support conclusions), coverage audit, contradiction and overconfidence labeling (src/index.ts:353-373)
• Reuse official workflow engine and built-in web_search/web_fetch: zero self-developed orchestration, zero self-developed network logic, sub-agents inherit host's toolset (src/index.ts:483-516)

Technical Implementation

• Language: TypeScript (ESM, native TS source, erasable-only syntax constraints, can be loaded by Node 22+ with native type stripping without build steps; compiled output in lib/types/, package.json#main also points there)
• Key Dependencies: @deepseek-ai/dsh-tools (tool registration), @deepseek-ai/dsh-workflow (WorkflowMeta types and official engine), cordis ^4.0.0-rc.7 (plugin host framework)
• Architecture Pattern: cordis plugin, export const inject = ['tools', 'workflows']; in apply, register the deep_research tool via ctx.tools.register. When the tool executes, submit a static workflow script (String.raw literal, containing planning/research/synthesis/review four stages) to the official engine running on worker threads via ctx.workflows.start; also inject the plugin line into profile's bundles via cordis.patch.yml
• Entry File: src/index.ts (name/inject/apply exports at 67-70 / 386-539; loaded by host at runtime)

Use Cases

People who need to write a well-cited, cross-examination-resistant research report on complex topics—examples: "Research the current MCP ecosystem and compare several mainstream implementations," "Do a selection study based on this list of questions," "Give me an XX industry analysis with literature support." Just state your needs directly in the conversation; the model will decide whether to use deep_research, and generate more focused reports following the principle that "the clearer the purpose, the more accurate the answer space."

Prerequisites & Compatibility

Installation

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

If pnpm rewrites https URLs to git+ssh (due to local global git insteadof configuration), explicitly use the git+https://... form; if dsh plugin indicates allowBuilds is needed, add a line in $DSH_HOME/profiles/<name>/pnpm-workspace.yaml as prompted. The profile must list this package in dsh.profile.bundles to be injected.

Configuration Options

Model tiering is designed per OpenAI guidelines: planning/synthesis/review require capable models, research agent is "high-frequency low-value" and can use cheaper models; this is role-based configuration rather than single-model, overriding original profile routing.

FAQ

Q: Is this plugin the same as the official .claude/skills/deep-research?

A: No. The former is a cordis plugin, runs on the official workflow engine, registers the model-visible deep_research tool; the latter is a skill system, triggered by the model based on skill description. Both README and source code clearly state they are independent and non-interchangeable; choose based on your needs.

Q: Do I need extra configuration after installation?

A: No. All configs are optional; it works with default values. The most common optimization is tiered models by role—strong models for planning/synthesis/review, cheaper models for research agents, which can significantly reduce costs.

Q: What exactly is the depth parameter in rounds?

A: depth equals the maximum research rounds minus one: 1=basic (up to 2 rounds), 2=in-depth (default, up to 3 rounds), 3=exhaustive (up to 4 rounds). Stops when limit is reached; the more common stopping condition is when a round has no new high-priority gaps (marginal information gain ≈ 0).

Q: What if some Web Profile doesn't work after installation?

A: This plugin depends on the official workflow provider (ctx.workflows) at runtime. If the profile doesn't declare that provider, the loader stays pending; either register the workflows provider relationship in DSH Hub, or use a profile composition that already provides that service.

Q: I've already listed my questions—how do I skip automatic decomposition?

A: Pass the question list as a string to questions (one per line, or 1./2./3. numbered), and the plugin will skip the planning phase and go directly to parallel research; if all evidence is obtained in the first round, it converges in one round.

Q: How to upgrade and uninstall?

A: Upgrade: dsh plugin --profile <profile> update; uninstall: dsh plugin --profile <profile> remove @dsh-external/dsh-deep-research, or remove the dependency from the profile's package.json then run update again.

Learning Curve

Beginner — one installation command and it's ready to use, all configs have default values; only need to look at depth/model configuration when you want to tier models by role for cost savings, or push research depth to exhaustive mode.

Known Issues & Limitations

• Must rely on DSH official workflow provider and built-in web_search/web_fetch for runtime capabilities; if the target profile doesn't declare workflows provider (like some Web Profile combinations), the loader stays pending (README.md:117-122)
• Tool input topic cannot be empty, depth only accepts 1/2/3, otherwise throws error before entering ctx.workflows.start (src/index.ts:464-472 / test/regression.test.mjs:516-569)
• Tool internally checks result.stopReason !== 'completed' and throws error, passing maxTotalAgents as 0 is directly judged as INVALID_ARGUMENT by the engine—therefore null/undefined means use engine default, never write 0 (src/index.ts:394-396 / 521-531)
• Source code must maintain erasable-only TS syntax (no enum/namespace/parameter properties), otherwise Node 22's native type stripping will throw a loud error (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 原生可加载。