DeepThonk

DeepThonk

多思考，不多花钱。

DeepThonk 将 OpenDeepThink 算法（Zhou 等人，2026 年，arXiv:2605.15177）实现为经济实惠、与提供商无关的“深度思考 / 专业模式”封装，并对 DeepSeek 提供一流支持。请参阅致谢。

DeepThonk 会让一组候选答案依次经过两两评判、Bradley-Terry 排名、由批评指导的变异、精英保留，以及最终的密集排名。CLI 和 MCP 服务都调用同一个 TypeScript 核心引擎。

专为 Agent 设计。 算法的每个维度——种群形态（n、k、t、m）、正则化（lambda）、各阶段的温度、提示词风格，以及各阶段的提示词模板——都可以通过 MCP 参数和 CLI 标志直接设置。CLI 可以通过 --prompts 加载提示词文件，或通过 --prompts-json 加载内联 JSON；MCP 则接受内联结构化提示词参数。每个中间产物（配置、候选项、种群、比较结果、分数、每次调用的用量、状态）都作为 MCP 资源公开，便于 Agent 检查任意步骤。有关完整的 Agent 可组合接口，请参阅自定义。

适用于困难、可验证的推理、编码、规划和综合任务；在这类任务中，广度加上判断力可能胜过一次昂贵的单次调用。避免用于高度主观、评判噪声占主导的任务。

快速开始

需要 Node ≥ 22.13。

无需安装即可运行：

npx -y deepthonk plan --profile paper
npx -y deepthonk run --provider fake --profile quick \
  --task "Find the smallest positive integer divisible by 3, 4, and 5." \
  --out runs/test-quick
npx -y deepthonk inspect runs/test-quick

或全局安装：

npm install -g deepthonk
deepthonk plan --profile paper

论文配置会规划 285 次模型调用和 8 轮顺序执行。将其用于付费模型前，请确认预算和提供商定价。短别名 dt 会与 deepthonk 一同安装。从源代码开始开发：请参阅开发。

DeepThonk 是独立的 TypeScript 重实现和实用集成层；已发布的算法是核心依据。成本保证依赖配置中提供的提供商定价。Trace-v2 恢复功能可以在崩溃后重用已验证的逐项回执，而较早版本的 trace 会整体重放未完成的阶段。MCP HTTP 传输仍仅限环回地址。随附的验收烟雾测试使用确定性假提供商和玩具任务，并非 CF-73 / HLE 复现；规范论文和 Python 参考实现请参阅 docs/ 和致谢。

设置

创建可重复使用的本地配置：

deepthonk setup \
  --provider deepseek \
  --api-key-env DEEPSEEK_API_KEY \
  --fast-model deepseek-v4-flash \
  --judge-model deepseek-v4-pro

默认情况下，这会写入 ~/.config/deepthonk/config.yaml。未提供 --config 时，deepthonk run 会自动加载该文件。如果传入 --api-key，设置过程会将其存储在 ~/.config/deepthonk/env；否则会使用 shell 中指定名称的环境变量。

DeepSeek

export DEEPSEEK_API_KEY=...
deepthonk run \
  --task task.md \
  --profile paper \
  --provider deepseek \
  --generator-model deepseek-v4-flash \
  --mutator-model deepseek-v4-flash \
  --judge-model deepseek-v4-pro \
  --out runs/task-paper

DeepSeek 以兼容 OpenAI 的配置文件实现，使用 https://api.deepseek.com/v1。DeepThonk 根据 DeepSeek 官方定价页面，为 deepseek-v4-flash 和 deepseek-v4-pro 提供默认美元定价，包括缓存命中 / 未命中的输入价格。模型名称和价格仍可在配置中编辑，因为二者都可能变化。

付费运行前，请检查成本情况和解析后的配置：

deepthonk plan --config ~/.config/deepthonk/config.yaml
deepthonk run --task task.md --config ~/.config/deepthonk/config.yaml --profile quick --dry-run

建议从 --profile quick 开始，并在使用更大的付费配置前考虑设置 --max-concurrency、--max-calls、--max-input-tokens、--max-output-tokens、--max-usd 和 --request-timeout-ms。max_calls 会在分发前预留，并统计逻辑模型调用次数，包括失败调用和无效 JSON 重试；提供商内部的 HTTP 重试会单独报告。只有在收到响应后才能确定 Token / 美元总量，超出幅度最多为当前并发窗口的上限。计划中的 calls 不包含最终处理和重试预留量，这些预留量单独计入 worst_case_calls。

OpenAI 兼容的提供商

export DEEPTHONK_API_KEY=...
deepthonk run \
  --task task.md \
  --profile balanced \
  --provider openai-compatible \
  --base-url https://provider.example.com/v1 \
  --api-key-env DEEPTHONK_API_KEY \
  --generator-model cheap-model \
  --judge-model strong-model

驱动程序会调用 POST {base_url}/chat/completions，并在支持时为比较请求 JSON 模式。如果提供商返回 400 或 422，且响应正文提及 response_format 或 json，驱动程序会在不使用 JSON 模式的情况下重试，在并发调用之间协调该功能探测，并在进程运行期间记住结果。在 YAML 中设置 supports_json_mode: false，可预先禁用 JSON 模式。

提供商名称可以灵活设置。对于自定义的 OpenAI 兼容端点，可使用任意提供商标签，并指定 --base-url、--api-key-env 和按角色区分的模型参数。对于 OpenRouter：

export OPENROUTER_API_KEY=...
deepthonk run \
  --task task.md \
  --profile balanced \
  --provider openrouter \
  --generator-model openrouter/auto \
  --mutator-model openrouter/auto \
  --judge-model openrouter/auto

对于混合提供商运行，请使用 YAML 配置，并在 providers 下覆盖各个角色，尤其是 judge。

可选的 finalizer_model / --finalizer-model 可对排名第一的答案进行后处理。如果希望最终结果保留原始排名答案，请将其留空。

MCP

MCP 服务会公开与 CLI 相同的引擎。连接到 MCP 主机后，主机可以规划预算、启动后台运行、轮询状态、获取获胜结果，并流式传输结构化跟踪产物——全部通过 MCP 工具、资源和提示词完成。

DeepThonk 自 v0.2.1 起已在 MCP Registry 中列出，名称为 io.github.linxule/deepthonk。通过注册表名称安装的主机会自动将其解析为 npx deepthonk serve-mcp。对于不支持此功能的主机，以下显式配置可手动实现相同效果。

提供商 API 密钥来自主机进程的环境变量，而不只是 DeepThonk 的配置。各主机传递环境变量的方式略有不同，具体模式见下文。启动服务不需要密钥：对于支持 Sampling 的主机，可以运行 provider: "sampling"；fake 提供商则完全不需要网络。

当连接的主机声明支持 MCP Sampling 功能时，可使用 provider: "sampling"。阻塞式 run、rank 和 mutate 可通过 stdio 和有状态的 Streamable HTTP 运行。HTTP 后台 start 不支持 Sampling，因为嵌套 Sampling 必须保持在发起请求的上下文中；stdio 后台运行和直接使用提供商的 HTTP 后台运行仍可用。独立 CLI 运行不支持 Sampling。

Claude Code

claude mcp add deepthonk \
  -e DEEPSEEK_API_KEY=$DEEPSEEK_API_KEY \
  -- npx -y deepthonk serve-mcp --transport stdio

跨项目使用时，请使用 -s user；要将注册信息写入 .claude/，请使用 -s project。使用 claude mcp list 验证。权威的标志列表请参阅 claude mcp --help。

Claude Desktop

配置文件路径：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）、%APPDATA%\Claude\claude_desktop_config.json（Windows）、~/.config/Claude/claude_desktop_config.json（Linux）。添加：

{
  "mcpServers": {
    "deepthonk": {
      "command": "npx",
      "args": ["-y", "deepthonk", "serve-mcp", "--transport", "stdio"],
      "env": {
        "DEEPSEEK_API_KEY": "sk-..."
      }
    }
  }
}

编辑后请重启 Claude Desktop。

Cursor

项目级配置：工作区中的 .cursor/mcp.json。用户全局配置：~/.cursor/mcp.json。JSON 结构与 Claude Desktop 相同：

{
  "mcpServers": {
    "deepthonk": {
      "command": "npx",
      "args": ["-y", "deepthonk", "serve-mcp", "--transport", "stdio"],
      "env": { "DEEPSEEK_API_KEY": "sk-..." }
    }
  }
}

其他 MCP 主机（stdio）

任何支持 MCP stdio 的主机都可以启动：

npx -y deepthonk serve-mcp --transport stdio

并在进程中设置相关提供商环境变量。如果想要全局安装，可运行 npm install -g deepthonk，然后直接使用 command: "deepthonk"。配置结构请参阅主机的 MCP 注册文档。

Streamable HTTP

适用于本地 Web 主机，或无法使用 stdio 的情况：

deepthonk serve-mcp --transport http --port 3333 \
  --max-active-jobs 2 --max-queued-jobs 32

服务仅绑定到 127.0.0.1:3333，并在 http://127.0.0.1:3333/mcp 提供有状态的 POST、GET 和 DELETE。会话使用加密安全的 ID；无请求处于活动状态时，空闲 30 分钟后过期；会话数量上限为 64。已启用 DNS 重绑定防护（CVE-2025-66414）：Host 标头不属于 127.0.0.1:3333 / localhost:3333 的请求将被拒绝。在读取请求正文之前，包装器还会拒绝非 JSON 的 POST、非环回的 Origin 标头，以及 Sec-Fetch-Site: cross-site 请求。此服务没有 Bearer 身份验证。未经重新评估该信任边界，请勿通过反向代理公开此端口。

工具

工具	用途
deepthonk.plan	估算某个配置文件所需的调用次数和顺序轮数（不调用模型）。在付费运行前使用。
deepthonk.start	在后台启动一次运行；返回 run_dir、job_id 和作业范围内的工件资源。
deepthonk.status	根据 run_dir 轮询作业状态。
deepthonk.result	作业完成后返回最终摘要和获胜项。
deepthonk.cancel	通过在运行目录中写入 cancel.json 请求取消。
deepthonk.lock_inspect / deepthonk.lock_reclaim	检查锁的所有权，并且只针对完全匹配的指纹显式回收锁。
deepthonk.repair_budget	将旧版 [redacted] 数值预算字段替换为明确的原始值。
deepthonk.run	阻塞式便捷工具：在一次调用中启动运行并等待完成。对于长时间运行的作业，优先使用 start + 轮询。
deepthonk.rank	使用成对评判 + Bradley-Terry 对用户提供的候选集进行排名（跳过生成）。
deepthonk.mutate	通过评判改进一个提供的候选项（单次执行）。
deepthonk.resume	检测运行是否可以恢复；使用 continue: true 时，从最后一个经过验证的阶段边界开始重放。
deepthonk.export	以 JSON 或 Markdown 格式导出运行摘要或完整追踪记录。
deepthonk.profile_list	列出已保存的命名配置文件包。
deepthonk.profile_show	显示一个已保存的配置文件；加载时会拒绝经过手动编辑、看起来像密钥的值。
deepthonk.profile_save	保存可重复使用的命名配置文件包。
deepthonk.profile_delete	删除已保存的命名配置文件包。

所有工具都接受内联的提供方／模型字段，或指向 DeepThonk YAML 配置文件的 config_path。

资源

• deepthonk://runs — runs/ 中所有运行的 JSON 索引。
• deepthonk://runs/{run_id}/summary — 运行摘要（JSON）。
• deepthonk://runs/{run_id}/config — 已脱敏的运行配置（JSON）。
• deepthonk://runs/{run_id}/{candidates|comparisons|scores|usage|trace} — 各阶段及各次调用的 NDJSON。
• deepthonk://runs/{run_id}/population/{generation} — 某一代的人群快照（JSON）。
• deepthonk://runs/{run_id}/{winner|final} — 文本工件。
• deepthonk://runs/{run_id}/status — 运行状态（JSON）。
• deepthonk://runs/{run_id}/prompts/{sha256} — 经过验证、按内容寻址的渲染后提示词（JSON）。
• deepthonk://runs/{run_id}/trace-v2 — 有界阶段索引；按照其中的清单、提交记录、检查点索引和检查点 URI 检查每份回执。
• deepthonk://jobs/{job_id}/{status|result|config|candidates|comparisons|scores|usage|trace|final|winner}?run_dir=... — 作业范围内的查询；必须提供 run_dir 查询参数。
• deepthonk://jobs/{job_id}/population/{generation}?run_dir=... — 完成前后均可查询的作业范围内人群快照。
• 作业结果还包含作业范围内对应项的 prompt_template 和 trace_v2_template。
• deepthonk://runs/{run_id}/{resource}/page/{cursor} 及对应的作业 URI — 不透明的有界分页读取。整体读取上限为 1 MiB；每页最多包含 1,000 条记录和 1 MiB 数据。

提示词

四个模板对应核心循环：deepthonk/generate、deepthonk/compare、deepthonk/mutate、deepthonk/finalize。宿主可以直接渲染这些模板，手动驱动算法，而无需调用工具接口。

限制

deepthonk.resume 默认报告追踪状态。使用 continue: true 时，它会验证阶段顺序、工件、运行／提供方／模型身份、评分、用量、确定性成对计划、trace-v2 回执和阶段提交记录。有效的不完整阶段回执会被复用，不会再次调用提供方。MCP Sampling 模型提示仅作为偏好，令牌用量可能不可用。共享的自适应限流器初始值为 4；直接提供方的初始值为 8。

自定义

每个算法维度都可通过 MCP 参数和 CLI 标志设置：

• 种群形状：n、k、t、m — 可在调用时覆盖配置档默认值。
• 算法常量：lambda、sample_temperature、mutate_temperature、judge_temperature。
• 提示词风格：general 或 paper-programming。
• 各阶段提示词模板：使用自定义系统/用户模板和变量替换（{task}、{rubric}、{candidate}、{candidateA}、{candidateB}、{critique}）覆盖 generate、compare、mutate 或 finalize。CLI 支持 --prompts <yaml> 和 --prompts-json <json>；MCP 支持内联 prompts。未知变量会在运行开始时触发快速失败错误。
• 并发：为 generate、judge、mutate 设置各阶段的上限。
• 提供方背压：provider_max_concurrency 设置共享自适应提供方路由限制器的恢复上限。
• 单次调用输出上限：分别设置生成、变异、评审和最终整理的令牌上限。
• 最终排名计划：采用带种子的 all-pairs 或 k-regular，并设置明确的逻辑调用上限。
• 评述上限：在变异前进行确定性去重，并设置可配置的总字符上限。

Agent 调用示例（MCP），无需 YAML 文件：

{
  "task": "Draft a concise non-solicitation clause for a senior sales employee.",
  "profile": "balanced",
  "n": 6, "t": 1,
  "provider": "deepseek",
  "judge_model": "deepseek-v4-pro",
  "prompts": {
    "generate": { "system": "You are an experienced employment-law attorney." },
    "compare":  { "system": "Prefer enforceable clauses under California law. Return strict JSON only." }
  }
}

CLI 支持相同的配置项。使用 --prompts <yaml> 指定可复用的提示词文件，或使用 --prompts-json <json> 设置一次性内联覆盖项。MCP 和 CLI 都会在任何 --config/config_path YAML 默认值基础上进行合并。

将可复用配置包保存为 ~/.config/deepthonk/profiles/<name>.yaml 下的命名配置档，并通过 --profile-name <name>（CLI）或 profile_name: "<name>"（MCP）加载。命名配置档是独立配置包，会在该次运行中替代主配置文件；CLI 标志和 MCP 内联参数仍可覆盖其中的字段。请参阅 examples/profiles/legal-drafting.yaml 了解其格式。自定义指南介绍了如何在 CLI 和 MCP 中列出、查看、保存和删除命名配置档。

请参阅自定义指南，了解完整的变量约定、compare 阶段的 JSON 安全规则、命名配置档架构以及三个完整示例。按角色路由提供方（providers.judge.provider = openrouter）和按模型定价仅支持 YAML 配置——它们属于嵌套结构化配置，并非适合内联设置的选项。

跟踪文件

成功运行后会写入：

runs/{run_id}/
  config.json
  events.jsonl
  candidates.jsonl
  comparisons.jsonl
  scores.jsonl
  usage.jsonl
  population-0.json
  population-{generation}.json
  manifests/*.json
  checkpoints/*/*.json
  commits/*.json
  summary.json
  artifacts/winner.txt
  artifacts/final.txt
  artifacts/prompts/<sha256>.json  # only when prompt capture is enabled

通过 MCP deepthonk.start 启动运行时会写入 status.json（供异步客户端轮询）。仅在请求取消时才会写入 cancel.json。运行期间会持有 run.lock 文件。

跟踪记录会通过单个写入器批量追加，并在生命周期边界前刷新。每项输出和用量凭证都会在阶段提交前以原子方式写入。如果运行在锦标赛中途被终止，trace-v2 恢复会验证并复用已完成的凭证，重新生成对应的 JSONL 行，并且仅针对缺失或无效的工作调用提供方。

usage.jsonl 每次提供方调用（生成器、评审器、变异器、最终整理器）写入一行，包含阶段/角色/提供方/模型/令牌/USD/延迟/重试信息。其中不包含提示词内容。使用 jq 处理 usage.jsonl 是按角色拆分运行成本的最简单方式。

默认不保存提示词和模型原始输出。启用提示词捕获后，候选项/比较记录会带有 promptRef，相同的渲染后提示词会共享 artifacts/prompts/ 下的一个内容寻址数据块；不会在每条 JSONL 行或凭证中重复完整提示词。API 密钥绝不会写入文件。候选答案、评述、分数和最终产物属于跟踪数据，会按设计存储/导出；因此，除非可以接受，否则不要将共享运行目录用于敏感任务。

开发

pnpm install
pnpm run build
pnpm test
pnpm run lint

此仓库仅包含源代码。生成的运行跟踪记录、论文笔记、构建输出、覆盖率报告、日志和 node_modules 均有意忽略。

发布通过 npm Trusted Publishing 在推送标签时触发。提升版本或推送 v* 标签前，请参阅 docs/release.md。

此版本的已知限制：

• Trace-v1 恢复时会整体重放中断的阶段；逐项复用需要使用 DeepThonk v0.2 创建 Trace-v2 运行记录。
• HTTP Sampling 仅支持阻塞模式。对于后台 deepthonk.start 工作，请使用 stdio 或直接使用提供方。
• maxUsd 需要已知的模型定价；对于自定义提供方和模型 ID，请在 YAML 中添加明确的价格。可选字段 longContextThresholdTokens、inputUsdPerMillionLong 和 outputUsdPerMillionLong 可为存在长上下文附加费用的模型启用分层定价（例如，Gemini 在输入令牌达到 200K 时）。缓存命中率和未命中率仍按统一费率计算。

致谢

DeepThonk 是对 OpenDeepThink 算法的独立 TypeScript 重实现。它不是分支项目；未引入参考实现中的任何源代码。该算法、基准测试方法和实证结果均归论文作者所有。

• 论文：Shang Zhou、Wenhao Chai、Kaiyuan Liu、Huanzhi Mao、Qiuyang Mang、Jingbo Shang。OpenDeepThink：通过 Bradley–Terry 聚合实现并行推理。arXiv:2605.15177，2026 年。https://arxiv.org/abs/2605.15177
• 参考 Python 实现：https://github.com/ZhouShang0817/open-deep-think（MIT）。这是作者发布的代码，也是复现论文结果（CF-73、HLE）的规范实现。

DeepThonk 的贡献是一个集成层：与提供方无关的 TypeScript 核心、MCP 服务、命令行、结构化跟踪制品和预算强制机制。算法本身属于他们。