superlab

superlab 是一个面向 Codex 和 Claude 的严格 /lab:* 研究工作流包。

它包含：

• Codex 和 Claude 的命令安装入口
• 共享的 /lab skill
• 基于 lab 自己目录约定的 change 工件
• 带有 Ralph Wiggum 风格边界控制的实验迭代
• 运行登记、评估汇总和结果校验脚本

安装方式

推荐先安装 CLI，再进入项目目录初始化：

npm install -g superlab
cd your-project
superlab init

执行完 init 或 update 后，请新开一个 Codex 或 Claude 会话；如果新的 /lab:* 命令仍未生效，再重启应用。

如果 npm 还没发布，也可以直接从 GitHub 安装：

npx github:zhouhaoUCAS/superlab init

superlab init 会默认进入一个简洁的交互式向导：

• 先选语言：默认按系统 locale 猜测，高亮 English 或 中文
• 再选平台：all、codex、claude

交互方式：

• ↑ / ↓ 移动选项
• Enter 确认
• Space 为以后多选步骤预留，当前单选菜单里也接受为确认

安装后会写入：

• .codex/prompts/lab-*.md
• .codex/skills/lab/
• .claude/commands/lab*.md
• .claude/skills/lab/
• AGENTS.md
• CLAUDE.md
• .lab/system/core.md
• .lab/config/workflow.json
• .lab/context/
• .lab/changes/
• .lab/.managed/templates/
• .lab/.managed/scripts/
• results/
• figures/

如果你更喜欢非交互方式，也可以直接传参：

superlab init --platform codex
superlab init --platform claude
superlab init --platform both

高级用法：

superlab init --target /path/to/project --platform both --lang zh --force
superlab init --all

--all 是 --platform both 的别名。如果目标目录已有同名文件，可以加 --force 覆盖。

更新

刷新当前项目：

superlab update

刷新指定项目：

superlab update --target /path/to/project

接入一个用户自己提供的 LaTeX 模板目录，但默认不改模板文件：

superlab paper attach-template --target /path/to/project --path /path/to/template

这个命令只会把模板目录记录进项目配置。模板目录会被视为用户资产，里面可能已经有上游或你自己的修改，superlab 默认不会重写它。

刷新当前用户登记过的所有项目：

superlab update --all-projects

superlab init 会在项目内写入 .lab/.managed/install.json，并在用户级 registry 里登记项目路径，所以 update --all-projects 才知道要刷新哪些项目。

较老版本的 superlab 项目可能已经有 .codex/、.claude/ 或 .superlab/ 资产，但还没有 .lab/.managed/install.json。现在 superlab update 会自动重建这份 metadata，然后原地升级该项目。

上下文工具

根据当前项目上下文重建压缩后的 handoff 层：

superlab context refresh

清理已解决或已过期的 active-context 内容：

superlab context prune

把冷历史迭代和写作轮次归档出去：

superlab context archive

输出新 AI 会话最小接手包：

superlab handoff

检查当前 .lab 受管布局是否健康：

superlab doctor

doctor 目前会校验：

• 必需的 .lab 文件是否存在
• workflow.json 结构是否合法
• results_root 和 figures_root 是否放在合理位置
• deliverables_root 是否放在合理位置
• paper_template_root 在配置时是否合法
• <deliverables_root>/paper/ 下是否仍然满足 LaTeX-first 输出约束
• .lab/context/eval-protocol.md 在评估规划已启动时是否完整
• 评估规划已启动后，指标与对比实现是否补齐了来源约束字段
• 是否把长期 run 输出错误地堆在 .lab/changes/*/runs

自动模式

先填写 .lab/context/eval-protocol.md，把论文导向的评估目标、主表计划、指标释义、指标与对比实现的来源、gate 和实验阶梯写清楚。然后再填写 .lab/context/auto-mode.md，明确本次自治执行的边界契约、各阶段命令、阶段产物约束，以及 success/stop/promotion 的检查命令；同时选择 Autonomy level，声明一个明确的终止目标（rounds、metric-threshold 或 task-completion），保持 Approval status: draft 直到你审过这份契约，再改成 approved 后启动当前项目的自动模式：

superlab auto start

查看自动模式当前状态：

superlab auto status

停止当前自动模式：

superlab auto stop

/lab:auto 是叠加在现有执行阶段之上的编排模式。它会在 .lab/context/eval-protocol.md、.lab/context/auto-mode.md 和 .lab/context/auto-status.md 的约束下，复用 run、iterate、review、report，以及可选的 write。superlab auto start 只会在契约被显式批准后启动，然后保持前台长驻、轮询长任务直到完成、按 .lab/context/eval-protocol.md 里声明的结构化 rung 转移继续推进，同时保护已声明的 frozen core、写出 .lab/context/auto-outcome.md，并校验各阶段的产物约束。指标、baseline 行为和对比方法实现必须先在评估协议里挂到来源上，才能拿来做 gate 或 promotion：

• L1 是安全运行级别，只允许 run、review、report

• L2 是默认推荐级别，允许 run、iterate、review、report

• L3 是激进 campaign 级别，才允许额外编排 write

• 如果不确定，默认推荐 L2

• run 和 iterate 必须更新 results_root 下的持久输出

• review 必须更新规范的审查上下文

• report 必须写出 <deliverables_root>/report.md、<deliverables_root>/main-tables.md 和 <deliverables_root>/artifact-status.md

• write 必须写出 <deliverables_root>/paper/ 下的 LaTeX 论文产物

• promotion 成功后必须写回 .lab/context/data-decisions.md、.lab/context/decisions.md、.lab/context/state.md 和 .lab/context/session-brief.md

• 每次运行都必须写出 .lab/context/auto-outcome.md，记录为什么停止、是否达到终止目标，以及哪一个工件是最终结果

• 如果评估协议里声明了结构化 rung，每个 rung 都应声明 Stage、Goal、Command、Watch、Gate、On pass、On fail、On stop；auto 会把当前 rung、监视目标和下一 rung 写进 .lab/context/auto-status.md

它不会替代手动的 idea、data、framing、spec 决策。

好的 /lab:auto 输入应该显式写清。把 Autonomy level L1/L2/L3 当成执行权限级别，把 paper layer、phase、table 当成实验目标，不要混用。如果 workflow language 是中文，摘要、清单条目、任务标签和进度更新也应保持中文，除非某个字面标识符必须保持原样。

/lab:auto 层级指南：

• L1：适合安全验证、一轮有边界真实运行，或简单的 report 刷新
• L2：适合冻结核心边界内的常规实验迭代，也是默认推荐级别
• L3：只在你明确想做更大范围 campaign、允许更广探索和可选写作时使用
• 如果用户输入没写级别，或者把级别和 paper layer、phase、table 混用了，就应先停下来，给出更详细的层级说明，再要求用户明确选 L1/L2/L3
• 如果不确定，默认推荐 L2

示例：

/lab:auto 自治级别 L2。目标：推进 paper layer 3 的一项有边界协议改进。终止条件：完成 bounded protocol、测试、一项最小实现和一轮小规模结果。允许修改：配置、评估脚本、数据加载逻辑。

版本查询

查看当前 CLI 版本和当前目录项目的资产版本：

superlab version

只看当前项目资产版本：

superlab version --project

查看指定项目：

superlab version --target /path/to/project

如果项目还是旧的 pre-metadata 安装，superlab version 会显示 project: legacy；执行一次 superlab update 后就会切换到正式版本号。

语言

安装器会根据系统 locale 自动猜测展示语言。检测到中文 locale 时会安装中文命令和技能文案；否则默认安装英文文案。

也可以显式覆盖：

superlab init --lang zh
superlab init --lang en

安装器还会写入 .lab/config/workflow.json。这个文件是全局约束，至少控制：

• workflow_language
• paper_language
• paper_format
• results_root
• figures_root
• deliverables_root
• paper_template_root
• paper_language_finalization_decision

后续 stage 应该按这个配置决定语言和论文格式，而不是各模板自己猜。

依赖

• Node.js 18+
• Python 3.10+
• Git

/lab:write 自带 vendored 的 paper-writing 章节参考、abstract、introduction、method 对应的 upstream example bank，以及为 related work、experiments、conclusion 补齐的 manuscript-delivery examples，不再依赖额外安装一个运行时写作 skill。

命令集合

Codex 和 Claude 的命令入口不一样：

• Codex：/lab:idea、/lab:auto、/lab:write

• Claude Code：/lab idea ... 或 /lab-idea；/lab auto ... 或 /lab-auto；/lab write ... 或 /lab-write

• /lab:idea 调研 idea、文献、数据集、指标和 baseline，并输出初始方案。

• /lab:data 把已批准的 idea 收敛成数据集与 benchmark 方案，要求记录年份、使用论文、来源审计、下载计划，并明确 classic-public、recent-strong-public、claim-specific 三类 benchmark 的纳入理由，以及 canonical baselines、strong historical baselines、recent strong public methods、closest prior work 四类对比方法的纳入理由。

• /lab:framing 在正式写作前收紧方法名、模块名、论文题目和 contribution wording。

• /lab:auto 在已批准边界内编排 run、iterate、review、report 和可选 write，并在升格策略满足时允许把 exploratory additions 自动升级为 primary package。

• /lab:run、/lab:iterate、/lab:auto、/lab:report 都应优先使用 .lab/context/eval-protocol.md 里带来源的指标定义和对比实现说明，而不是凭记忆现想。

• /lab:spec 把批准后的方案转换成一个统一的 .lab/changes/<change-id>/ 目录。

• /lab:run 执行最小可运行实验，并建立首版评估链路。

• 持久 run 输出应写到 results_root，不要写进 .lab/changes/。

• /lab:iterate 以固定 mission、固定阈值和最大轮次做有边界的实验迭代。

• /lab:review 以审稿人模式检查方法、对照、公平性、泄漏和统计问题。

• /lab:report 根据累积工件生成最终实验报告。

• /lab:write 把稳定的 report 工件转成论文 section，并按小步方式逐轮修改。 它要求先有一个经批准的 /lab:framing 工件。 它会读取随 lab 一起安装的 vendored 章节参考，这些参考来源于 Research-Paper-Writing-Skills。

使用流程

1. 在目标项目执行 superlab init。
2. 在 Codex 中调用 /lab:idea；在 Claude Code 中调用 /lab idea ... 或 /lab-idea。
3. 经确认后，在 Codex 中执行 /lab:data，或在 Claude Code 中执行 /lab data ... / /lab-data，锁定数据集、下载来源、benchmark 类别覆盖，以及各类对比方法的纳入理由。
4. 再执行 /lab:spec，或在 Claude Code 中执行 /lab spec ... / /lab-spec。
5. 用 /lab:run，或在 Claude Code 中用 /lab run ... / /lab-run 打通最小实验链路。
6. 用 /lab:iterate，或在 Claude Code 中用 /lab iterate ... / /lab-iterate 进行多轮迭代。
7. 在关键节点运行 /lab:review，或在 Claude Code 中运行 /lab review ... / /lab-review。
8. 最后用 /lab:report，或在 Claude Code 中用 /lab report ... / /lab-report 产出总报告。
9. 用 /lab:framing，或在 Claude Code 中用 /lab framing ... / /lab-framing 收紧题目、命名和 contribution wording。
10. 用 /lab:write，或在 Claude Code 中用 /lab write ... / /lab-write 把稳定结果写成论文各 section。

/lab:write 会把最终可交付物写到 deliverables_root 指定的目录，默认是 docs/research：

• docs/research/report.md
• docs/research/main-tables.md
• docs/research/artifact-status.md
• docs/research/paper/main.tex
• docs/research/paper/references.bib
• docs/research/paper/sections/*.tex
• docs/research/paper/tables/*.tex
• docs/research/paper/figures/*.tex

内部写作控制工件放在：

• .lab/writing/framing.md
• .lab/writing/plan.md
• .lab/writing/iterations/*.md

如果配置了 paper_template_root，/lab:write 应先检查该模板目录并按其结构写作。 如果没有配置模板，第一次进入论文 .tex 写作时应先追问一次：继续使用内置默认 LaTeX scaffold，还是先接入模板目录。 如果用户确认先用默认 scaffold，就把这个决定持久化到 .lab/config/workflow.json，后续普通轮次不再重复追问。 普通论文起草轮次应先跟随 workflow_language。 如果 workflow_language 和 paper_language 不一致，/lab:write 应先保留一套可阅读的 workflow-language 交付稿，再在第一次进入最终定稿或导出轮次时追问一次：保持当前草稿语言，还是把 canonical manuscript 转换成 paper_language，并把这个决定持久化。 这套 workflow-language 交付稿是正式持久化产物，不是 review 层，除非被明确刷新，否则应继续保留。 但在最终导出或最终定稿节点，如果项目仍在使用默认 scaffold 且没有接入模板，应再提醒一次，给用户最后切换模板的机会。 在最终定稿或导出轮次里，/lab:write 还应物化真正的 LaTeX 表格、带图意图的 figure placeholders、非空的 references.bib，并在停止前通过 .lab/.managed/scripts/validate_manuscript_delivery.py --paper-dir <deliverables_root>/paper。

/lab 把 .lab/ 视为工作流控制层，不是正式结果目录。持久输出应按自然根目录放置：

• results_root：日志、checkpoint、metrics
• figures_root：图表和导出图片
• deliverables_root：报告和论文源码

仓库内容

• commands/ 是源码仓库里的说明文件。
• package-assets/ 是 npm 安装时真正分发到目标项目的命令与 skill 资产。
• skills/lab/ 是仓库开发时使用的共享 workflow 定义。
• templates/ 是研究工件模板。
• scripts/ 是运行登记、评估汇总和结果校验脚本，其中也包括论文交付校验器。
• results/ 和 figures/ 是默认的自然结果目录。
• tests/ 是脚本与安装器测试。
• examples/ 是最小端到端示例。
• docs/ 存放设计文档和发布说明。
• docs/release.md 是发布到 npm 的操作说明。
• .github/workflows/ci.yml 会在 main 和 PR 上自动执行 npm run release:check。
• .github/workflows/publish.yml 支持在配置好 NPM_TOKEN 后手动从 GitHub Actions 发布到 npm。

致谢

superlab 借鉴了 OpenSpec、superpowers 和 Ralph Wiggum 的流程纪律。随包提供的写作参考改编自 Research-Paper-Writing-Skills。