🔬 DSH Open Deep Research

English

DSH Open Deep Research 是一个基于 DeepSeek Harness 的 Deep Research Agent 与 TypeScript 框架。它接收研究问题，生成带引用链接的 Markdown 报告，并通过 CLI、DSH Tool 和程序化 API 提供同一项研究服务。

> 项目状态： 0.1.0-alpha.5 Alpha Public Preview，已使用正式发布的 DSH 0.1.0-rc.8 完成测试。当前通过 GitHub Releases 分发，尚未发布到 npm。

核心能力

• 规划一到三个研究单元，通过 DSH 子 Agent 执行，并综合各单元的结果。
• 两个专用 Profile 都支持网页搜索，research-jina 还可读取选定网页或 PDF。
• 输出带引用链接的 Markdown 报告、去重后的链接、终止状态与运行元数据。
• 通过可替换的 ResearchEngine 提供 CLI、DSH Tool 和 TypeScript 三种入口。

🏗️ 架构

flowchart TD
  USER["用户或应用"] --> ENTRY{"调用入口"}

  ENTRY --> CLI["专用 Research CLI"]
  ENTRY --> TOOL["open_deep_research Tool"]
  ENTRY --> API["createResearchClient()"]

  CLI --> ENGINE["ResearchEngine"]
  TOOL --> ENGINE
  API --> ENGINE

  ENGINE --> PLAN["Planning Agent<br/>生成 brief 和一到三个单元"]
  PLAN --> RESEARCH["Research Agents<br/>受限并发研究"]
  RESEARCH --> SYNTHESIS["Synthesis Agent<br/>生成带引用报告"]
  SYNTHESIS --> RESULT["Markdown 报告<br/>ResearchResult"]

  RESEARCH --> SEARCH["DSH web_search"]
  RESEARCH -. "仅 research-jina" .-> JINA["Jina MCP read_url"]

  DSH["DeepSeek Harness<br/>模型、工具、Preset、Session、子 Agent、取消"]
  DSH -. "运行和管理" .-> PLAN
  DSH -. "运行和管理" .-> RESEARCH
  DSH -. "运行和管理" .-> SYNTHESIS

三个入口调用同一个 ResearchEngine，当前 Profile 决定研究子 Agent 可以调用哪些来源工具。生命周期、Profile 组合、配置与结果语义见[架构说明](./docs/architecture.md)。

🚀 快速开始

请从 GitHub 下载预发布安装包。需要从源码构建的贡献者可参阅[贡献指南](./CONTRIBUTING.md)。

环境要求：Node.js ^22.19.0 或 >=24.0.0、PATH 中可用的 pnpm 10.x、DeepSeek Harness 0.1.0-rc.8。

DSH 管理 Profile 插件时还会调用 pnpm。安装前请确认 npx 和 pnpm 均可用：

node --version
pnpm --version

如果第二条命令不可用，请参考 pnpm 安装说明。

1. 下载安装包

curl -fL -O \
  https://github.com/songyang0603/dsh-open-deep-research/releases/download/v0.1.0-alpha.5/dsh-open-deep-research-0.1.0-alpha.5.tgz

完成后，当前目录中会出现 dsh-open-deep-research-0.1.0-alpha.5.tgz。Release 同时提供 SHA256SUMS，可用于校验文件。

plugin add 可能显示 host peer warning。命令退出码为 0 时，可以继续初始化。

2. 完整研究：搜索并读取正文（推荐）

research-jina 提供网页搜索和正文阅读。它会把选定的公开 URL 发送给 Jina，不会发送浏览器 Cookie。请使用公开且不含敏感信息的 URL，避免签名 URL、依赖登录态的 URL、私有网络 URL 和内网 URL。

设置两把 Key，并检查部署网络能否连接 Jina：

export DEEPSEEK_API_KEY='<your-deepseek-key>'
export JINA_API_KEY='<your-jina-key>'

curl --connect-timeout 10 --max-time 20 -I \
  'https://mcp.jina.ai/v1?include_tools=read_url&max_tokens=8000'

收到任意 HTTP 响应，说明 DNS、TCP 与 TLS 已到达 endpoint。此检查不会验证 Key，也不会完成 MCP 启动。endpoint 无响应时，请使用下方的仅搜索 Profile。

npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile research-jina add \
  ./dsh-open-deep-research-0.1.0-alpha.5.tgz

npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile research-jina exec \
  dsh-open-deep-research-init --reader jina

npx @deepseek-ai/dsh@0.1.0-rc.8 --profile research-jina \
  --breadth balanced \
  --language zh-CN \
  "调研 DeepSeek Harness rc.8 的主要变化，搜索相关材料，阅读重要来源正文，并生成带引用链接的报告。"

研究子 Agent 会根据任务选择来源工具，Profile 不会规定固定调用次数。Reader 每次最多返回 8,000 tokens，长文档可能被截断。Jina 初始化长时间未完成时，请先检查当前网络能否访问 mcp.jina.ai，或使用下方的仅搜索 Profile。

3. 仅搜索：只需 DeepSeek Key

没有 Jina Key 或 Jina 网络不可达时，可以使用独立的 research Profile。它仍会执行规划、网页搜索、多个研究单元、综合和报告生成，但无法稳定读取网页或 PDF 的完整正文。

export DEEPSEEK_API_KEY='<your-deepseek-key>'

npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile research add \
  ./dsh-open-deep-research-0.1.0-alpha.5.tgz

npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile research exec \
  dsh-open-deep-research-init

npx @deepseek-ai/dsh@0.1.0-rc.8 --profile research \
  --language zh-CN \
  "调研 DeepSeek Harness rc.8 的主要变化并生成报告。"

4. 保存输出

Markdown 模式会把报告写入 stdout，可以直接重定向到文件：

npx @deepseek-ai/dsh@0.1.0-rc.8 --profile research-jina \
  "比较两种研究方法" > report.md

干净环境首次执行 npx @deepseek-ai/dsh 时，下载和构建依赖可能需要数分钟，期间输出较少。请等待命令退出后再重试。两个 Profile 相互独立，不会覆盖对方，也不会自动降级。

⚙️ 配置

breadth 决定研究单元上限，分别为一个、两个或三个，Planning 可以选择更少的单元。模型路由、Preset、工作目录、来源工具允许列表和最大研究并发等 Provider 配置见[架构说明](./docs/architecture.md#provider-configuration)。

completed 和 partial 的退出码为 0，partial 还会向 stderr 写入简短提示。执行失败使用 1，参数错误使用 2，用户中断使用 130。失败或取消时 stdout 为空。

在 DSH 与 TypeScript 中使用

将同一个 tarball 安装到 stock DSH Profile，可以把 open_deep_research 作为 Tool 使用：

npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile headless add \
  ./dsh-open-deep-research-0.1.0-alpha.5.tgz

npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile web add \
  ./dsh-open-deep-research-0.1.0-alpha.5.tgz

stock headless 和 web 只会获得 Provider 与 Tool，其来源能力由配置的 allowedTools 决定。

普通 Agent 调用中，Tool 会使用当前轮对话的直接用户文本作为研究问题。Tool 不接收模型补写的 purpose 或 context。需要显式传入这些字段时，请使用专用 CLI 或 TypeScript API。当前消息存在未说明的历史指代时，应先请用户补充上下文。

运行结果为 completed 或 partial 时，Tool 会要求父 Agent 原样返回渲染后的 Markdown 报告。父 Agent 仍会生成普通 Assistant 回复，因此可能增加简短说明或调整少量格式。这可以降低引用被改写的概率，但不能保证字节级一致。需要精确取得规范报告时，请直接读取 Tool value 或 TypeScript 返回值。

TypeScript API 可以直接调用当前 ResearchEngine：

import { createResearchClient } from 'dsh-open-deep-research'

const result = await createResearchClient(ctx).run({
  question: 'DeepSeek Harness 如何组合 Agent Preset？',
  purpose: '为插件作者准备架构说明。',
  breadth: 'balanced',
  output: { format: 'report', language: '简体中文' },
})

console.log(result.status)
console.log(result.report)

需要取消任务时，可用 createResearchClient(ctx).start() 获取 ResearchRun。完整 API 行为见[领域契约](./docs/architecture.md#domain-contract)。

在本地 Web UI 中测试

将安装包加入 DSH web Profile：

export DEEPSEEK_API_KEY='<your-deepseek-key>'

npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile web add \
  ./dsh-open-deep-research-0.1.0-alpha.5.tgz

npx @deepseek-ai/dsh@0.1.0-rc.8 web

DSH 会在 http://127.0.0.1:3080 启动 Web UI。新建对话后可以输入：

> 请调用 open_deep_research 工具，调研 DeepSeek Harness rc.8 的主要变化，并生成带引用链接的中文报告。

这条 stock Web 安装路径默认提供仅搜索能力。推荐的搜索加正文阅读组合目前通过专用 research-jina CLI Profile 提供。

兼容性与当前限制

项目文档：[架构说明](./docs/architecture.md) · [Changelog](./CHANGELOG.md) · [贡献指南](./CONTRIBUTING.md) · [安全策略](./SECURITY.md)

License

[MIT](./LICENSE)