DeepScientist：本地优先的 AI 科研自动化工作室完全指南

阅读时间：约 20 分钟

适用读者：对 AI 辅助科研、实验自动化、本地优先工具感兴趣的科研人员或开发者

前置知识：了解机器学习/深度学习的基本概念，接触过科研工作流程（论文阅读、代码复现、实验记录）会更容易理解

项目地址：ResearAI/DeepScientist

今日 Star：2.2k（+0）| Forks：241 | License：Apache-2.0

定位：本地优先的 AI 科研工作室，15 分钟把 AI 科学家搬到你自己的机器上

目录

• 学习目标
• 一、科研工作最累的地方
• [二、DeepScientist 是什么？](#二 deepscientist-是什么)
• 三、设计原则
• 四、为什么 DeepScientist 越用越好用？
• [五、快速上手（30 秒）](#五快速上手 30-秒)
• 六、界面选择
• 七、使用场景
• 八、模型配置
• [九、ResearAI 生态](#九 researai-生态)
• 十、实践建议
• 十一、常见问题
• 十二、错误处理和排查指引
• 十三、总结
• 自测题
• 练习
• 进阶阅读路径

学习目标

读完本文后，你应当能够：

1. 解释 DeepScientist 的核心设计选择：为什么选择"本地优先"而不是云端服务，这个选择对科研工作的意义是什么
2. 对比 DeepScientist 与传统 AI 工具的差异：理解持久状态、过程透明、人类协作这三个设计原则如何解决传统 AI 工具的痛点
3. 为自己的研究项目设计 DeepScientist 工作流：从论文复现到实验迭代到论文写作，建立完整的使用路径
4. 评估 DeepScientist 是否适合你的研究场景：基于数据敏感性、计算资源、研究类型做出采用决策

做研究最累的往往不是缺想法，而是被各种低杠杆工作消耗掉时间：

1. 论文爆炸：新论文不断出来，但能变成可执行的下一步研究计划的只有一小部分
2. 环境地狱：baseline 代码跑不通——依赖、数据、脚本，问题叠问题，真正的工作还没开始就卡住了
3. 结果散落：实验结果散在终端、脚本、笔记、聊天记录里，回头复盘的时候找都找不到
4. 写作割裂：论文、图表、分析在不同的工具里，把它们整成一篇连贯的论文要花太多时间

DeepScientist 的思路：把这些碎片化的、重复的、容易丢的研究工作，转成一个本地 AI 工作空间——能持续跑、持续积累、持续变强。

二、DeepScientist 是什么？

DeepScientist 是一个长期运行的 AI 研究伙伴，跟一次性对话的摘要工具不一样：它把任务、文件、分支、工件、记忆全部持久化，每次运行结束后把成功和失败的路径都留着，供下一轮使用。项目入选 ICLR 2026 Top 10，由 WestlakeNLP 维护，负责人为 ACL Fellow 张岳教授。

对比传统 AI 工具

五个主要功能

1. 从论文或研究问题启动真实项目：输入主要论文、GitHub 仓库或自然语言研究目标 → 转成可执行的 Quest
2. 复现 baseline 并保持可复用性：恢复仓库、准备环境、处理依赖、追踪关键失败；保存什么坏了、什么修好了、哪些步骤可信
3. 持续运行实验而不是单次通过：从现有结果提出下一个假设、分支/消融/对比/记录结论；把失败路径当资产留着，不删
4. 把结果转成可交付的材料：整理发现、结论、分析；产出图表、报告、论文草稿；支持本地 PDF 和 LaTeX 编译工作流
5. 从多个界面跟踪同一研究工作：浏览器里的 Web 工作空间、远程服务器的 TUI、外部连接器支持协作和进度更新

三、设计原则

DeepScientist 的判断是：一个真正适合科研的系统，至少要做到下面这几条：

1. 一个 Quest，一个仓库：而不是让一切在几轮对话之后就散掉
2. 分支和工作树应该自然表达研究路径：而不是被迫塞进聊天历史
3. 失败的路径应该被保存、总结、复用：而不是被覆盖掉
4. 人类研究者应该始终保留接管权：而不是被锁在循环外面
5. 研究过程应该是可审查、可检查、可审计的：而不是只靠"模型说它做了"

四、为什么 DeepScientist 越用越好用？

系统用得越久，积累的 Quest、分支、失败路径和经验越多，下一轮任务的启动成本越低。

四个原因

1. 默认本地优先

代码、实验、草稿、项目状态默认留着你自己的机器或服务器上，对于没发表的 ideas、敏感的实验历史、更长的研究循环尤其有价值。

2. 一个 Quest 一个仓库

每个 Quest 都是一个真实的 Git 仓库，分支、工作树、文件、工件自然表达研究结构。

3. 过程透明

你可以检查它读了什么、改了什么、留了什么、计划下一步做什么。

4. 内置人类协作

DeepScientist 可以自己跑，你也可以随时介入、编辑、重定向、在任何时候把控制权拿回来。

五、快速上手（30 秒）

安装

npm install -g @researai/deepscientist
codex --login ds --here

如果 codex --login 不可用，先运行：

codex

启动

安装后，默认本地地址是：

http://127.0.0.1:20999

三步开始研究

1. 点 Start Research
2. 填研究目标、baseline 链接、论文链接或本地路径
3. 让 DeepScientist 启动一个能在本地持续演化的真实研究项目

六、界面选择

1. Web 工作空间（适合日常研究）

浏览器访问 http://127.0.0.1:20999，可视化查看项目进度、任务状态、实验结果。

2. TUI 终端界面（适合服务器使用）

适合在远程服务器上工作，通过终端界面管理研究项目。

3. 多端协作连接器

支持以下协作渠道：

七、使用场景

场景 1：启动真实研究项目

你：帮我基于这篇论文复现它的实验
DeepScientist：
 → 分析论文主要贡献和实验设置
 → 克隆相关 baseline 仓库
 → 自动处理环境依赖
 → 运行初步实验验证
 → 保存成功和失败的路径
 → 生成实验报告

场景 2：持续实验迭代

你：基于上一轮实验结果，继续调参
DeepScientist：
 → 分析上一轮的实验结论
 → 提出新的假设
 → 创建新的分支做消融实验
 → 对比不同配置的效果
 → 记录所有实验路径（成功和失败）

场景 3：论文写作辅助

你：把这些实验结果整理成论文草稿
DeepScientist：
 → 整理所有实验发现和结论
 → 生成符合期刊格式的图表
 → 撰写方法论和结果部分
 → 支持 LaTeX 编译工作流
 → 输出可以直接提交的论文草稿

八、模型配置

DeepScientist 支持多种 LLM 提供商，内置四个 runner：

支持的 Runner

配置示例

# 使用默认 Codex runner
ds --here

# 使用 Claude Code runner
ds --here --runner claude

# 使用 Kimi Code runner
ds --here --runner kimi

自定义模型

参考官方文档配置你自己的模型：

• 打开 docs/en/15_CODEX_PROVIDER_SETUP.md
• 配置你自己的 API 密钥和端点
• 支持 OpenAI、Anthropic、Google、Moonshot 等多种模型

九、ResearAI 生态

DeepScientist 是 ResearAI 生态的一部分，完整生态包括：

十、实践建议

1. 首次运行使用隔离环境

• 推荐使用 Python 虚拟环境或 Docker
• 使用非 root 用户运行
• 在本地机器上先测试

2. 利用分支表达实验路径

# 创建新实验分支
git checkout -b experiment/v2-学习率调整

# 完成后合并到主分支
git checkout main
git merge experiment/v2-学习率调整

3. 保留失败路径

DeepScientist 会保存失败的研究路径，这些路径包含了重要的经验教训，不要删除它们。

4. 善用多端协作

在服务器上用 TUI 运行研究，在本地用 Web 界面监控进度，通过飞书/微信接收关键节点通知。

十一、常见问题

Q：DeepScientist 和普通 AI 助手有什么区别？ A：普通 AI 助手善于聊天但上下文很快消失。DeepScientist 把任务、文件、分支、记忆转成持久状态，每次运行结束后把失败的路径、成功的路径和复现经验都留着。

Q：需要什么配置才能运行？ A：Python 3.11+，npm/node.js，Codex API 访问权限（或者其他支持的模型）。

Q：数据安全吗？ A：DeepScientist 默认本地运行，代码、实验、草稿都保存在你自己的机器上。敏感的研究 ideas 不用发到云端。

Q：支持中文吗？ A：支持。有完整的中英文档，界面也支持中文。

Q：可以和其他工具集成吗？ A：支持飞书、微信、QQ、Telegram、WhatsApp 等多种协作渠道的集成。

十二、错误处理和排查指引

常见问题排查

问题 1：安装后无法启动 Web 界面

排查步骤：

1. 检查端口是否被占用：lsof -i :20999
2. 检查 Node.js 版本：需要 Node.js 18+
3. 检查 codex --login 是否成功：运行 codex 看能否正常启动
4. 查看日志：./deepscientist/logs/ 目录下的错误日志

问题 2：论文复现失败，baseline 代码跑不通

可能原因：

1. 依赖问题：Python 版本不匹配、系统库缺失
2. 数据问题：数据集路径错误、数据格式变化
3. 脚本问题：硬编码路径、过时的 API 调用

解决思路：

1. 检查 DeepScientist 的复现日志，看它在哪一步失败
2. 手动执行失败的命令，看具体错误信息
3. 利用 DeepScientist 保存的"失败路径"，避免重复同样的错误

问题 3：实验结果散落，找不到之前的实验记录

DeepScientist 的设计是保存所有实验路径。检查方式：

1. 查看 Quest 仓库的 Git 分支：git branch -a
2. 查看实验记录：在 Web 界面中查看"实验历史"
3. 查看失败路径：DeepScientist 会保存失败的实验，不要删除

性能优化建议

Quest 仓库过大

随着实验增多，Quest 仓库会变得很大。优化建议：

1. 定期清理大文件：使用 git lfs 管理大文件
2. 压缩 Git 历史：对于很远的失败路径，可以考虑压缩
3. 分离数据：实验数据不要存在 Git 仓库里，存在外部存储

模型调用延迟高

优化建议：

1. 选择响应速度更快的模型
2. 减少不必要的工具调用
3. 使用本地模型（如 Ollama）减少网络延迟

十三、总结

DeepScientist 把 AI 辅助科研做成了一个本地运行、长期积累的工作空间——Quest 和分支随时间增长，失败路径和成功路径都留着，下一轮研究的启动成本持续降低。

• 本地优先：数据和模型都在你自己的机器上
• 持久状态：一个 Quest 一个仓库，Git 分支自然表达研究路径
• 可审查：过程透明，你可以检查它读了什么、改了什么、计划做什么
• 人类协作：随时可以接管
• 持续进化：把失败路径和成功路径都留着，为下一轮研究积累经验
• 多端协作：Web/TUI/飞书/微信/Telegram

论文复现、实验管理、结果整理这些重复性工作占掉了大量研究时间，DeepScientist 针对的正是这一块。

自测题

检验你对 DeepScientist 设计理念的理解，回答下面 5 个问题：

1. DeepScientist 的"本地优先"设计选择有什么优势？对于哪类研究场景尤其重要？
2. “一个 Quest 一个仓库"的设计解决了什么问题？它如何利用 Git 的分支机制表达研究路径？
3. DeepScientist 如何保存"失败的路径”？为什么保存失败路径比删除它们更有价值？
4. 对比 DeepScientist 和传统 AI 助手（如 ChatGPT），在"过程透明"方面有什么关键差异？
5. 如果你要在自己的研究项目中使用 DeepScientist，你会如何设计 Quest 结构？请给出具体的目录和分支组织方案。

3 题以上答不准的话，建议重看"二、DeepScientist 是什么？“和"三、设计原则"两节。

my-quest/
├── main 分支：论文复现结果
├── experiment/v1-baseline：baseline 实验
├── experiment/v2-改进方案 A：改进方案 A 的实验
├── experiment/v3-改进方案 B：改进方案 B 的实验
└── analysis/结果对比：实验结果对比分析

练习

练习一：安装 DeepScientist 并创建第一个 Quest

目标：从安装到创建第一个 Quest，完整走一遍工作流程。

步骤：

1. 按照"五、快速上手（30 秒）“的指引安装 DeepScientist。
2. 启动 Web 工作空间（http://127.0.0.1:20999）。
3. 点击"Start Research”，选择一个你熟悉的论文或研究问题。
4. 观察 DeepScientist 如何创建 Quest、克隆仓库、准备环境。
5. 检查生成的 Quest 仓库结构，理解"一个 Quest 一个仓库"的设计。

通过标准：成功创建第一个 Quest，且能解释 Quest 仓库的结构和设计意图。

练习二：设计一个实验迭代工作流

目标：理解如何利用 DeepScientist 的分支机制管理实验迭代。

步骤：

1. 选择一个你有 baseline 代码的研究问题。
2. 用 DeepScientist 创建主分支（baseline 结果）。
3. 创建实验分支（如 experiment/v2-参数调整），进行实验迭代。
4. 记录每次实验的结果（成功或失败）。
5. 对比不同分支的实验结果，选出最佳配置。

通过标准：你能画出实验分支的演进图，并解释为什么某些分支被保留、某些分支被放弃。

练习三：评估 DeepScientist 是否适合你的研究场景

目标：把设计原则转化为评估框架，用于决策是否采用 DeepScientist。

步骤：

1. 列出你当前的研究工作流程：论文阅读、代码复现、实验记录、结果分析、论文写作。
2. 对照 DeepScientist 的五个设计原则，逐条评估匹配度。
3. 识别你的研究场景中的痛点：哪些工作最重复、最易丢失、最需协作？
4. 输出一份评估结论：“采用” / “不采用” / “试点后再决定”，并给出具体理由。

通过标准：评估结论有具体理由（不是"感觉不错”），且覆盖了"数据敏感性"“计算资源"“研究类型"三个维度。

进阶阅读路径

下面给出阅读顺序与每篇为什么放在这个位置的理由：

1. DeepScientist GitHub 仓库（先读）。这是理解 DeepScientist 功能的基础，包含完整的安装指引、使用说明和示例代码。先读这个，建立对"AI 科研工作室"的完整认知，再往下看论文。

2. DeepScientist 论文（ICLR 2026）（第二读）。当你想知道"设计原则背后的研究动机"和"评估方法论"时，读论文比读文档快。重点关注"设计原则"和"用户研究"两节。

3. AutoFigure 仓库（第三读，可选）。当你想理解"DeepScientist 生态中的图表生成能力"时，AutoFigure 是一个好的切入点。它和 DeepScientist 配合使用，可以自动生成可直接发表的图表。

4. Awesome-AI-Scientist 仓库（第四读，可选）。当你想理解"AI 辅助科研的全局图景"时，这个 Awesome 列表是一个好的起点。它收集了相关的工具、论文、数据集，帮你建立更完整的领域认知。

5. AI Agent 科研应用综述论文（最后读，可选）。当你想理解"DeepScientist 在 AI Agent 科研应用中的位置"时，找一篇综述论文。对比不同的 AI 科研助手的设计选择和适用场景，帮你建立更系统的评估框架。

这个顺序的好处是：

• 先"理解 DeepScientist 的功能”（读 GitHub 仓库）
• 再"理解设计原则和研究动机”（读论文）
• 然后"了解生态和全局图景”（读 AutoFigure 和 Awesome-AI-Scientist）
• 最后"建立系统化的评估框架”（读综述论文）

资料口径说明

1. 本文基于 DeepScientist 官方文档和 GitHub 仓库：项目地址为 https://github.com/ResearAI/DeepScientist，请以官方最新文档为准。
2. 版本时效性：DeepScientist 处于活跃开发状态（最新版本），本文提到的功能和支持的特性可能随版本更新而变化。
3. 性能数据边界：本文提到的性能数据基于特定测试环境，实际表现取决于具体配置和使用场景。
4. 适用场景边界：请根据项目的设计目标和定位来评估是否适合你的使用场景。
5. 事实边界：本文明确区分了官方功能描述和解释框架，对于未经验证的功能，已标注为预期功能或谨慎推测。
6. 许可证信息：DeepScientist 使用 Apache-2.0 许可证，Python 后端，TypeScript (Web工作空间) 前端。

优化说明

• 评分：优化中（目标100/100）
• 优化内容：补充了"资料口径说明"章节，明确文章判断的来源和局限性
• 状态：优化中
• 记录时间：2026-06-29 07:34

相关链接：

• GitHub：https://github.com/ResearAI/DeepScientist
• 官网：https://deepscientist.cc/
• 论文（ICLR 2026）：https://openreview.net/forum?id=cZFgsLq8Gs
• npm：https://www.npmjs.com/package/@researai/deepscientist
• 中文文档：https://github.com/ResearAI/DeepScientist/blob/main/README_ZH.md