NanoResearch：端到端AI科研自动化引擎，从想法到论文的九阶段流水线实践

1. 项目概述：从零到一的AI科研自动化革命

如果你是一名AI领域的研究者或工程师，一定经历过这样的痛苦循环：有了一个绝妙的研究想法，兴奋地打开编辑器，然后就被无尽的代码调试、实验排队、数据整理和论文撰写所淹没。从灵感到一篇结构完整、数据翔实的论文，中间隔着无数个不眠之夜和反复试错。NanoResearch的出现，正是为了终结这个循环。它不是一个简单的“AI写作助手”，而是一个端到端的自主AI科研引擎，能够将你的研究想法，通过一个九阶段的深度流水线，自动转化为一篇包含真实实验数据和完整LaTeX源码的学术论文。

简单来说，你只需要提供一个研究课题，比如“Adaptive Sparse Attention Mechanisms”，NanoResearch就能自动完成从文献调研、实验设计、代码生成、GPU训练、结果分析、图表绘制到论文撰写的全部流程。最核心的差异在于，它真的会运行代码。论文里的每一张图表、每一个数据点，都来自于在本地GPU或SLURM集群上实际执行的训练任务，而不是大语言模型（LLM）的“合理想象”或编造。这从根本上解决了当前AI辅助科研工具“纸上谈兵”的痛点，将自动化从文本生成推进到了实验验证的层面。

这个项目适合所有希望提升科研效率的人：无论是想快速验证想法的资深研究员，需要批量生成基准测试（Benchmark）结果的工程师，还是正在为论文初稿发愁的研究生。它为你构建了一个完整、可追溯、可复现的自动化工作空间，让你能将宝贵的精力聚焦在最具创造性的部分——提出问题和定义方向上。

2. 核心架构与九阶段流水线深度解析

NanoResearch的强大，源于其精心设计的模块化流水线架构。它不是一个单一的黑箱模型，而是一个由多个智能体（Agent）协同工作的系统，每个智能体负责科研流程中的一个特定环节，并通过统一的状态机进行编排。理解这个流水线，是高效使用它的关键。

2.1 九阶段流水线详解

整个流程被分解为九个顺序执行但支持断点续跑的阶段，形成一个完整的闭环：

第一阶段：IDEATION（构思与文献检索）这是整个研究的起点。系统会基于你提供的课题，调用OpenAlex和Semantic Scholar的API，自动检索相关的学术文献。它的目标不是简单地罗列论文，而是进行“研究空白发现”——分析现有工作的局限性，并提出一个具体、可验证的科学假说。同时，它会收集一批高质量的必引文献，为后续的论文写作打下基础。这个阶段决定了整个研究的方向和质量。

第二阶段：PLANNING（实验方案设计）有了假说，接下来就需要设计实验来验证它。Planning Agent会将抽象的研究想法，转化为一份极其详细的“实验蓝图”。这份蓝图会明确指定：

• 数据集：使用哪个公开数据集，或如何构建合成数据。
• 基线模型（Baselines）：需要与哪些经典或SOTA方法进行对比。
• 评估指标：使用准确率、F1分数、BLEU还是其他特定指标。
• 消融实验（Ablation Studies）：计划对模型的哪些组件（如注意力头数、层数、特定模块）进行消融，以验证其有效性。 这个蓝图是后续所有编码和执行阶段的“宪法”，确保了实验的系统性和可比性。

第三阶段：SETUP（环境准备）在这个阶段，系统会为即将开始的实验创建一个独立、干净的工作空间。它会根据实验蓝图，自动处理环境依赖，例如生成requirements.txt或environment.yml文件，确保代码的可复现性。如果实验需要下载特定的预训练模型或数据集，它也会尝试自动完成这些准备工作。

第四阶段：CODING（代码生成）这是将蓝图变为现实的第一步。Code Generation Agent会根据实验方案，生成完整、可运行的Python代码。这不仅仅是一个训练脚本，而是一个小型的项目工程，通常包括：

• 数据加载与预处理模块。
• 模型定义（基于PyTorch或TensorFlow）。
• 训练循环（Trainer），包含优化器、损失函数、学习率调度器。
• 验证和测试逻辑。
• 日志记录（通常使用TensorBoard或WandB）。 生成的代码力求简洁、模块化，并包含必要的注释，便于后续人工审查和调试。

第五阶段：EXECUTION（实验执行）——核心差异化环节这是NanoResearch的“灵魂”。它不仅仅是生成代码，而是真正地执行它。系统会自动检测可用的计算资源：

• 本地GPU模式：如果检测到本地有可用的NVIDIA GPU，它会直接启动训练进程，并实时监控日志和资源消耗。
• SLURM集群模式：对于需要大量计算资源的任务，它会自动生成符合规范的sbatch提交脚本，将任务提交到高性能计算集群，并持续监控作业状态（Pending, Running, Failed, Completed）。 更强大的是它的“自动调试与重试”机制。如果训练因代码错误（如张量维度不匹配）或资源问题（如OOM）而失败，系统会分析错误日志，尝试自动修复问题（例如调整批量大小），然后重新提交任务。这个能力极大地提升了自动化流程的鲁棒性。

第六阶段：ANALYSIS（结果分析）训练完成后，系统会解析训练过程中产生的日志文件（如TensorBoard event files或文本日志），提取关键指标（训练损失、验证准确率等），并将其结构化为清晰的实验证据。它会对比不同实验设置（如不同模型、超参数）的结果，并初步判断假说是否得到数据支持。

第七阶段：FIGURE_GEN（图表生成）“一图胜千言”。此阶段负责生成论文所需的所有配图，包括：

1. 方法架构图：根据生成的代码，自动或调用图像生成模型（如Gemini）绘制模型结构示意图。
2. 结果对比图：将Analysis阶段的结构化数据，通过Matplotlib或Seaborn生成折线图、柱状图，直观展示主实验结果和消融实验。
3. 可视化图：例如对于CV任务，生成模型注意力热力图；对于NLP任务，生成词嵌入投影图等。 所有图表都基于真实的实验数据渲染，并保存为高分辨率的矢量图（如PDF、SVG）或位图（如PNG），方便嵌入LaTeX。

第八阶段：WRITING（论文撰写）基于前面所有阶段的产出——研究假说、实验方案、代码、实验结果和图表——Writing Agent开始撰写完整的学术论文。它使用Jinja2模板引擎，将内容填充到预定义的LaTeX模板（如NeurIPS、ICML、arXiv格式）中。论文会包含标准的IMRaD结构：引言、相关工作、方法、实验、结果与讨论、结论。所有引用都会自动生成BibTeX条目，并插入正确的位置。

第九阶段：REVIEW（审稿与修订）最后，系统会扮演“审稿人”和“作者”的双重角色，对生成的论文草稿进行多轮审查。它会检查逻辑一致性、实验描述的清晰度、图表与正文的对应关系、语法错误等，并提出修订意见。然后，系统会根据这些意见自动修订论文，形成更完善的版本。

2.2 状态管理与断点续跑

整个流水线的状态由一个核心的manifest.json文件管理。这个文件记录了每个阶段的执行状态（Pending, Running, Success, Failed）、输入输出、以及产生的所有中间文件（如检索到的论文PDF、实验日志、图表文件）的路径。这种设计带来了一个至关重要的特性：断点续跑。 如果流程在任何阶段因网络超时、API限制或代码错误而中断，你无需从头开始。只需执行nanoresearch resume命令，系统就会读取manifest.json，自动定位到最后一个未完成的阶段，并从那里继续执行。这对于需要数小时甚至数天运行的完整实验流程来说，是保证可用性的基石。

3. 三种驱动模式实战指南

NanoResearch提供了三种互补的使用方式，适应不同的用户习惯和技术环境。你可以根据场景灵活选择或组合使用。

3.1 模式一：Python CLI（命令行接口）—— 全功能控制

这是功能最全面、最灵活的模式，适合习惯在终端工作、需要对流程进行深度定制的用户。

安装与配置首先，克隆仓库并安装依赖。建议使用开发模式安装，以便于后续贡献代码或自定义Agent。

git clone https://github.com/OpenRaiser/NanoResearch.git cd NanoResearch pip install -e ".[dev]"

接下来是核心的配置步骤。你需要创建一个配置文件~/.nanobot/config.json。最关键的是配置一个兼容OpenAI API的端点。如果你使用OpenAI官方API，可以直接填写其地址和密钥。但更经济实惠的方案是使用诸如DeepSeek、Groq等提供的兼容端点，或者本地部署的Ollama、vLLM等开源模型服务。

{ "research": { "base_url": "https://api.deepseek.com/v1/", // 例如DeepSeek的端点 "api_key": "your-deepseek-api-key-here", "template_format": "neurips2025", "execution_profile": "local_quick", // ... 其他配置 "ideation": { "model": "deepseek-chat" }, "planning": { "model": "deepseek-chat" }, "code_gen": { "model": "deepseek-coder" }, // 代码生成建议使用代码专用模型 "writing": { "model": "deepseek-chat" } } }

实操心得：对于code_gen阶段，强烈建议使用代码能力强的专用模型，如deepseek-coder、claude-3-5-sonnet或gpt-4o。这能显著减少生成的代码中的语法错误和逻辑漏洞，提高EXECUTION阶段的一次成功率。

运行你的第一个研究配置完成后，一个最简单的启动命令如下：

nanoresearch run --topic "Graph Neural Networks for Molecular Property Prediction" --verbose

--verbose参数会让你看到每个阶段的详细日志输出。首次运行会经历完整的九阶段流程，耗时取决于实验复杂度和模型速度，可能从几十分钟到数小时不等。

高级用法与技巧

• 跳过实验阶段：如果你只想快速生成一篇论文的“架子”或进行文献综述，可以跳过耗时的实验环节。在配置文件中设置"skip_stages": ["SETUP", "CODING", "EXECUTION", "ANALYSIS"]，系统将直接基于假设和现有知识生成论文。
• 模型路由：你可以在配置中为不同阶段指定不同的模型，实现性价比和效果的最优组合。例如，让便宜的模型处理文献检索和实验设计，让强大的模型负责代码生成和论文润色。
• 工作空间管理：使用nanoresearch list查看所有历史会话，使用nanoresearch inspect --workspace <path>深入查看某个工作空间的所有中间产物，这对于调试和复现至关重要。

3.2 模式二：Claude Code模式 —— 零配置交互

如果你拥有Claude Code的访问权限，这是最便捷的入门方式。你无需配置任何API密钥或环境变量，直接在Claude Code的聊天界面中就能驱动整个研究流水线。

工作原理在Claude Code模式下，Claude Code本身成为了执行引擎。它利用自身的WebSearch工具进行文献检索，用Bash工具来执行生成的Python代码、提交SLURM作业、编译LaTeX，并通过文件读写工具来管理整个工作空间。所有逻辑都复用项目已有的Python代码库，Claude Code只是作为一个“智能执行器”来调用它们。

快速开始在Claude Code中，打开已克隆的NanoResearch项目目录，然后只需输入一条命令：

/project:research "Few-shot learning for medical image segmentation"

Claude Code会自动理解这是一个研究项目请求，并启动完整的流水线。它会逐步向你汇报每个阶段的进展，并在遇到需要选择时（例如选择哪个GPU）与你交互。

可用命令集Claude Code模式支持一系列以/project:开头的快捷命令，对应流水线的不同阶段：

• /project:ideation <topic>：仅执行文献检索和假说生成。
• /project:planning：基于已有的构思产出实验方案。
• /project:experiment：执行环境准备、代码生成和实验运行（阶段3-5）。
• /project:writing：基于实验结果生成图表和撰写论文。
• /project:status：查看当前流水线的状态。
• /project:resume：从断点恢复执行。

注意事项：在Claude Code模式下生成论文架构图（FIGURE_GEN阶段）可能受限，因为Claude自身不直接生成图像。一种变通方案是，在此阶段让Claude Code调用一个外部的图像生成API（如DALL-E 3或Midjourney的API）来创建图片。项目文档中提到了可通过Bash调用“Nano Banana”系列图像API来实现。

3.3 模式三：飞书机器人 —— 移动端与协同办公

对于希望随时随地触发研究、或在团队内共享进度的用户，飞书机器人提供了绝佳的解决方案。你可以像与同事聊天一样，在飞书群里向机器人发送指令。

配置与启动配置机器人需要你在飞书开放平台创建一个自定义应用，获取App ID和App Secret。然后将它们设置到环境变量或配置文件中。

export FEISHU_APP_ID="cli_xxxxxx" export FEISHU_APP_SECRET="xxxxxx" # 启动机器人服务 nanoresearch feishu -v

启动后，机器人会建立一个WebSocket长连接，这意味着你不需要拥有公网IP的服务器来接收回调，简化了部署。

交互式研究在飞书对话中，你可以直接发送：

• /run 基于对比学习的视频异常检测方法研究
• /status（查看当前任务进度）
• /list（列出所有历史研究）
• /export（将最近完成的研究论文打包发给我）

机器人支持对话记忆，你可以进行多轮交互，例如询问“实验为什么失败了？”，它会去查询日志并给出分析。当流水线全部完成后，它会自动将生成的paper.pdf作为文件发送到对话中。

踩坑记录：飞书机器人的权限配置是关键。确保在开放平台后台为应用开启了“获取与发送单聊、群组消息”以及“上传文件”的权限。否则机器人将无法正常接收指令或发送结果。

4. 模型选型、成本控制与高级配置

如何以合理的成本获得最佳的输出质量，是使用任何AI工具的核心问题。NanoResearch的模块化设计，让你可以精细地控制每个阶段的模型花费。

4.1 分阶段模型路由策略

不同阶段对模型能力的需求差异很大。以下是一个经过实践验证的性价比策略：

在config.json中，你可以为每个阶段单独指定模型：

{ "research": { "ideation": { "model": "deepseek-chat" }, "planning": { "model": "claude-3-5-sonnet-20241022" }, "code_gen": { "model": "gpt-4o" }, "writing": { "model": "claude-3-5-sonnet-20241022" }, "figure_gen": { "model": "dall-e-3", "image_backend": "openai" // 指定图像后端 } } }

4.2 成本估算与优化实战

费用主要产生于调用大模型API和GPU计算资源。以下是一个粗略估算：

• 纯文本生成（跳过实验）：如果只运行到WRITING阶段，消耗的主要是API Token。使用DeepSeek等低成本模型，完成一篇论文的生成大约需要50万-100万Token，费用在0.5-2美元之间。如果混合使用Claude/GPT，费用可能升至5-15美元。
• 完整流水线（含实验）：费用大头转向GPU。例如，在AWS上一台g5.xlarge（单A10G）实例每小时约1美元。一个中等复杂度的模型训练2-4小时，加上API费用，总成本可能在3-10美元。如果在本地或已有集群运行，则GPU成本为零，仅需支付API费用。

成本控制实战技巧：

1. 本地优先：充分利用本地GPU进行实验，这是成本最低的方式。
2. 模型降级：在IDEATION、PLANNING等对精度要求相对较低的阶段，果断使用DeepSeek、Qwen等国产优秀模型，成本仅为Claude/GPT的十分之一甚至百分之一。
3. 设置Token上限与超时：在配置中为每个阶段设置合理的max_tokens和timeout，避免因模型“跑飞”而产生意外高费用。
4. 善用“跳过实验”模式：在头脑风暴和方案设计阶段，先用此模式快速生成论文草稿和实验方案，人工审查确认方向可行后，再开启完整流水线进行实验验证，避免盲目实验浪费资源。

4.3 执行配置与集群集成

execution_profile配置决定了系统如何利用计算资源：

• fast_draft：所有阶段都快速执行，可能使用更小的模型或简化实验，用于快速产出草案。
• local_quick：默认配置。优先尝试在本地GPU执行，如果资源不足或任务太重，会提示用户或尝试降级。
• cluster_full：为重量级实验设计。系统会倾向于生成SLURM作业脚本，提交到高性能计算集群。

SLURM集群集成详解： 要让NanoResearch在你的集群上工作，需要在配置或环境变量中提供SLURM的相关信息，例如分区（partition）、账户（account）、QOS等。系统生成的sbatch脚本会包含这些参数。你需要确保运行NanoResearch的节点能够通过sbatch命令提交作业，并且有权限访问共享存储（如NFS），以便流水线能访问到任务输出的日志和模型文件。

5. 输出产物、自定义与社区生态

5.1 剖析最终输出：一个完整的可复现研究包

运行结束后，使用nanoresearch export命令导出的，远不止一个PDF文件。它是一个完整的、可归档、可复现的研究工作空间。

my_adaptive_attention_paper/ ├── paper.pdf # 编译好的论文PDF ├── paper.tex # LaTeX源代码 ├── references.bib # BibTeX参考文献库 ├── figures/ # 所有矢量图和位图 │ ├── model_architecture.pdf │ ├── main_results.png │ └── ablation_study.svg ├── code/ # 完整的实验代码 │ ├── train.py │ ├── model.py │ ├── dataset.py │ └── requirements.txt ├── data/ # 处理后的数据或数据索引 │ └── processed/ ├── experiments/ # 训练日志、模型检查点 │ └── run_20250321_142356/ └── manifest.json # 整个研究过程的元数据记录

这个结构遵循了现代可复现研究的最佳实践。任何人拿到这个包，都可以根据manifest.json和代码，清晰地复现整个研究流程，从数据准备到最终图表生成。

5.2 自定义与扩展：打造你的专属科研引擎

NanoResearch是高度可扩展的。

• 自定义Agent：如果你对某个阶段（比如实验分析）有特殊要求，可以继承基类，重写execute方法，实现你自己的逻辑，并在配置中指定使用你的自定义Agent。
• 添加论文模板：在nanoresearch/templates/目录下，你可以添加新的Jinja2 LaTeX模板。模板需要定义好占位符，系统会自动将内容填充进去。这让你可以轻松适配CVPR、ACL等任何会议或期刊的格式。
• 集成新的工具：例如，你可以将数据可视化从Matplotlib切换到Plotly，或者在代码生成阶段集成你团队内部的代码库工具。

5.3 社区、贡献与未来

NanoResearch是一个活跃的开源项目。其核心价值在于社区的共同建设和分享。

• 问题反馈：如果你在使用中遇到Bug，或有功能建议，在GitHub Issues中提出是最直接的帮助方式。清晰的复现步骤和日志信息能极大加快解决速度。
• 贡献代码：项目结构清晰，欢迎提交Pull Request (PR)。常见的贡献包括：修复文档错别字、增加新的示例、实现一个新的论文模板、优化某个Agent的提示词（Prompts）等。
• 分享用例：在项目的Discussions板块分享你用NanoResearch完成的有趣研究，无论是成功的还是失败的，都能给其他用户带来宝贵参考。

最后一点个人体会：使用NanoResearch最大的心态转变，是从“执行者”变为“规划者”和“评审者”。你的核心工作不再是埋头写代码和调参，而是提出清晰、有价值的研究问题，并审阅AI生成的方案、代码和论文初稿，给出高阶的反馈和指导。它并没有取代研究者，而是将研究者从重复性劳动中解放出来，去从事更具创造性和战略性的思考。刚开始使用时，不要期望它第一次就能生成可直接投稿的完美论文。把它看作一个不知疲倦、执行力极强的科研助理，它能帮你完成90%的“脏活累活”，而剩下的10%——最具洞察力的分析、最精妙的论证、最画龙点睛的表述——依然需要你的智慧来最终完成。