用 Mojito 做研究：上手指南

这页写给第一次用 Mojito 做研究的人：怎么把研究工作区搭起来，怎么让 agent 自动找想法，怎么让它跑实验、把论文写完。

先弄清谁做什么

四个研究技能是：Research Ideas（找问题、发展想法）、Research Experiments（设计并跑对照实验）、Research Review（独立核查）、Paper Writing（围绕一个中心主张写论文）。仓库里带了通用示例，你可以照自己的习惯改。

第一步：搭起来（第一次大约半天）

1. 拿代码，做成你的私有仓库。不要点 Fork，Fork 出来的仓库是公开的。

   git clone https://github.com/TimeLovercc/mojito.git my-mojito
   cd my-mojito
   git remote rename origin upstream
   git remote add origin <你新建的空私有仓库地址>
   git push -u origin main

2. 按 docs/SETUP.md 部署。hub 和 agent 放在一台常开的机器上（1 GB 内存的小服务器就够），worker 放在你自己的电脑上，再把网页版装到手机主屏。只想做研究的话，日历、Gmail、安卓 app、Mac app 都可以先不配。
3. 装四个研究技能。先原样用仓库里的示例，以后按你的习惯改。

   cp -R examples/skills/research-idea-funnel examples/skills/research-experiments \
         examples/skills/research-review examples/skills/paper-writing ~/.claude/skills/

   用 Codex 的话，复制到 Codex 读技能的目录。
4. 在 worker/.env 里填三个路径（都写绝对路径，不要用波浪号）。

   MOJITO_SKILLS_DIR=/Users/you/.claude/skills        # 四个技能所在的目录
   MOJITO_RESEARCH_RULES=/Users/you/my-mojito/examples/research-rules.md   # 每轮研究都读的规则，也可以换成你自己的 CLAUDE.md
   MOJITO_RESEARCH_MAP=/Users/you/research/map.json   # 研究地图文件

5. 建研究地图 map.json。最小的一份：

   {"updated_at": "2026-01-01T00:00:00+00:00", "principles": [],
    "areas": [{"id": "llm", "name": "LLM", "children": []},
              {"id": "life", "name": "Life", "children": []}],
    "projects": [], "hidden": [], "inbox": []}

   principles 写你做研究的几条总原则，areas 是你的研究方向，格式见 docs/api.md 的「研究地图」一节。worker 一分钟内会读到改动。
6. 给终端里的研究会话发同步令牌。hub/deploy/gen-tokens.sh 会生成一个只能读写 Idea Lab 的 source:ideas 令牌，再用下面这句写到本机：

   hub/deploy/mac-env.sh source:ideas MOJITO_IDEA_LAB_TOKEN "$MOJITO_SECRETS_DIR/idea-lab.env"

7. 检查。打开 app 的项目页，顶部能看到「灵感收件箱」「Idea Lab」「研究技能」三个入口，研究技能里列着四个技能。

第二步：让 agent 自动找想法

1. 放材料。把读到的论文、关注的作者、博客、自己冒出来的念头写进 map.json 的 inbox：

   {"at": "2026-01-05T09:00:00+00:00", "kind": "paper",
    "text": "LoRA: 冻结原权重、只训练低秩增量", "source": "https://arxiv.org/abs/2106.09685",
    "area": "llm", "note": "想知道低秩够不够学新知识"}

   kind 可以是 idea、paper、author、blog。同一批加好几条时，每条的 at 错开一秒。
2. 在 app 里发起一轮：项目页 → Idea Lab → 开始研究。要填：
   • 运行名称（英文）、重要方向与研究偏好、本轮目标；
   • 模式选「探索问题」；
   • 在「选择种子」里勾这轮要用的材料；
   • 时间预算（1–120 分钟）和最大调用轮数（1–100）。
   找想法只需要读网页，「允许 CPU 数据分析」「允许写研究产物」可以先不勾。agent 会读你的研究技能、规则文件、地图上的总原则和收件箱材料，结果写成 Idea Lab 卡片：问题、为什么重要、竞争假设、带出处的证据、下一步。没有新发现时，它会直说没有。
3. 让它自己持续找：勾「启用有界持续探索」，填间隔（5 分钟到 30 天）和「授权总轮数」（最多 100），再二选一：
   • 按间隔运行：每到间隔跑一轮；
   • 新材料触发：到了间隔、收件箱里又有新条目时才跑，新条目自动加进这一轮的材料。
   每轮的模式和预算都和第一轮一样，并接着前几轮产出的想法往下做。上一轮还在排队或运行时不会开下一轮，所以电脑睡着时不会攒下一串任务。跑满总轮数就停，也可以随时停用。
4. 在终端里一起想：开一个 Claude Code 会话，直接说「用 Research Ideas 技能，围绕 X 方向做一轮 Explore，材料用收件箱里的 Y」。它每轮结束会用 research-idea-funnel/scripts/idea_lab.py 把结果同步进 Idea Lab。
5. 挑想法：在 Idea Lab 里看每张卡的证据和判断变化。值得继续的，用「发展想法」模式（或终端里的 Develop）往深里做：读最接近的已有工作，写清主张和对立解释，找下一个能把它们分开的观察。卡片状态会从「正在发展」走到「待验证」「实验中」，有证据才会标「有证据支持」。

第三步：让 agent 跑实验

1. 先立项目。想法要真做时，给它建一个项目仓库，在 hub 里建项目（在 app 的对话里说一句「新建研究项目 X，仓库在 /绝对路径」就行；要给仓库路径，worker 才找得到它的 overview.json），再在 map.json 的 projects 里给它一个位置。项目会话在仓库里维护一份 overview.json，app 里这个项目的卡片就显示它：核心想法、主实验、贡献、状态、待你决定的事、状态历史。格式见 docs/api.md「研究地图」，每次改完跑一次 mojito-overview-check <overview.json 路径>。
2. 小实验交给 Idea Lab：只用 CPU、只用公开数据的分析，可以在 Idea Lab 选「实验验证」模式，勾「允许 CPU 数据分析」和「允许写研究产物」，在「实验范围与限制」里写清边界。它不碰 GPU，产物留在 worker 的暂存区。
3. 正式实验交给终端会话：在有 GPU 的机器上、项目仓库里开一个 Claude Code 会话，交代清楚问题、对应的 Idea Lab 想法、能用的资源和花费上限。它按 Research Experiments 技能做：
   • 跑之前先写下：假设和对立解释、唯一改变的变量、可比的基线、多大的效果才算数、结果怎么判读；
   • 先用一条数据走一遍真实流程，确认新机制真的生效，再正式跑；
   • 结果只归四类：支持、否定、没有结论、无效（测量或执行坏了）。无效的不算证据，也不为了凑出正面结果反复重跑；
   • 跑完把结论作为实验证据同步回 Idea Lab，更新 overview.json，释放 GPU。
   可以这样交代：

   用 Research Experiments 技能做 Idea Lab 里「<想法标题>」的下一步实验。
   资源：2 张 GPU，最多 12 小时，不调用付费 API。
   先写实验计划和判读规则，跑一条冒烟确认流程通了，再正式跑。
   跑完把结论同步到 Idea Lab，更新 overview.json；需要我拍板的写进 decisions。

4. 长时间无人值守：实验放在 tmux 里跑，会话定时回来查看进度（Claude Code 可以用 /loop）。要你决定的事（加预算、换方向、停项目）它写进卡片的「待你决定」，你在 app 里看到了再回它。

第四步：让 agent 写完论文

1. 先复核：一个结论要写进论文之前，在终端里另开一个没参与这项研究的会话，用 Research Review 技能做独立检查：想法评审、主张和证据逐条对账，或者整篇审稿。Idea Lab 的「独立核查」模式按同样的方法检查，但它就是一轮普通的研究运行，不算独立审稿人。
2. 再写：论点够具体时，在项目会话里加载 Paper Writing 技能。它围绕一个中心主张，按提纲 → 初稿 → 图表 → 独立复核 → 修改的顺序写，正文放在项目仓库里（比如 LaTeX）。还没跑出来的结果留成显眼的占位，不编数字。Idea Lab 的「论文写作」模式可以先出一份提纲。

   用 Paper Writing 技能，把 Idea Lab 里「<想法标题>」写成一篇短论文。
   中心主张：<一句话>。证据只用已经同步到 Idea Lab 的实验和文献。
   先给我提纲和证据清单，我确认后再写初稿；写完用 Research Review 做一次全文评审。

3. 投不投、投哪里由你定。agent 不会替你投稿，也不会往外发任何东西。

一键跑完整一轮

Idea Lab 的「完整研究循环」模式把上面几步串成一轮：先探索或发展想法；勾了「允许 CPU 数据分析」时再做一次最小的诊断；维护论文提纲；最后另起一个只读的复核，检查来源、实验记录和归因。复核占这轮调用轮数的三分之一（最多 10 轮），和研究共用时间预算。复核认为证据不足或有问题时，这轮停在「需要补充条件」，新结论不会被标成「有证据支持」；最大调用轮数少于 3 时复核做不了，结果也一样。负面结果也算完成了一轮。

做不到的和要花的

• app 里发起的研究一次只跑一轮。它不跑 GPU、不调付费接口、不往外发消息、不写 Notion，文字在 Idea Lab 里一直标「待同步」，等你搬进自己的文档。
• 每轮用的是你自己的 Claude 订阅额度。
• 研究树不会自动生长：地图上的方向和项目位置由你或项目会话来改。多轮之间也没有长期的 autoresearch 流水线，能自动重复的只有上面说的「有界持续探索」。

附录：研究正文模板

在 Notion 或任何文档工具里建一个研究文档库，字段建议：Name（标题）、Type（Idea / Experiment / Review / Paper / Note）、Status（和 Idea Lab 的状态对应）、Idea Lab ID（卡片的 id，终端会话用 idea_lab.py 同步后会返回；卡片的 notion_url 反过来指向这一页）、Project、Sources（arXiv 或 DOI）、Date。