autoresearch 是一个闭环式机器学习实验工作流技能，用于在真实训练仓库上运行 Karpathy 风格的自主 ML 搜索。它的核心不是提供一份庞大的教程，而是充当“路由优先的前门”：先判断用户当前需要的模式，再强制不可变评估框架规则，最后把用户交给最小可用的脚本或参考文档。
用途
该技能围绕一个明确的实验闭环：人类编写 program.md；智能体编辑 train.py；prepare.py 保持固定；每次运行获得相同的 300 秒预算；更低的 val_bpb 获胜；出现退化则回滚。它适用于以下场景：在真实 GPU 机器上搭建 karpathy/autoresearch；在会话前编写或完善 program.md；运行有界的过夜 train.py 搜索循环；在会话后解读 results.tsv；在不破坏可比性的前提下适配更紧的显存约束；解释 autoresearch 与相邻评估工具之间的 ML 专属边界。
不适用场景
当用户想优化 SKILL.md、提示词或仓库本地工作流（提示词/评估冻结）时，应改用 skill-autoresearch；当用户需要应用级追踪、基于数据集的 LLM 评估、反馈审查或可观测性时，应改用 LangSmith、Braintrust、Weave、Promptfoo 等工具；当任务不涉及真实训练仓库、program.md、train.py、固定运行预算和 val_bpb 保留/回滚棘轮机制时，也不适用；当用户实际想要的是论文综述、通用基准扫描或文献回顾、无意运行训练循环时，同样不适用。
核心边界
该技能负责的可变目标是真实训练仓库中的 train.py，固定评估器是 prepare.py、验证分片、TIME_BUDGET=300 以及会话选定的 MAX_SEQ_LEN / EVAL_TOKENS，接受规则是只保留更低的 val_bpb、回滚持平或退化，主要产物是 program.md、results.tsv、保留/丢弃的提交。提示词、应用配置、SKILL.md、产品行为、提示词/评估数据集、应用记分卡、可观测性仪表盘、人工审查队列、应用级发布门禁、提示词套件、追踪、反馈数据集等则属于其他工具的范畴。如果边界不匹配，不应强行套用本技能。
必需的信息收集
行动前需要确认：模式（setup、program.md、运行循环、结果解读或受限硬件）；仓库状态（是否已克隆、依赖是否已安装）；硬件状态（GPU / VRAM / CUDA / MLX / Windows 路径）；会话状态（首次基线、活动循环或已完成运行）；约束状态（目标显存上限、prepare.py 是否已为本会话冻结）。
使用方式
第一步：只选择一种操作模式，选择能回答请求的最小模式。Setup readiness 用于仓库尚不可运行时，包括安装 uv、克隆仓库、同步依赖、用 scripts/check-hardware.sh 验证 GPU/CUDA/uv、运行首次基线实验。program.md 编写用于循环已存在但方向薄弱时，包括编写或完善人类研究纲领、记录当前基线 val_bpb、按优先级排列假设、列出已尝试内容、在循环开始前冻结约束。有界运行循环用于 setup 和 program.md 就绪后，包括确认评估器已固定、以 train.py 作为唯一可变搜索面、以保留/回滚纪律运行循环、将每次实验记录到 results.tsv。结果解读用于完成运行或检查点之后，包括总结最佳保留运行、识别重复失败或崩溃模式、提取应写入下一版 program.md 的内容、区分真实增益与一次性异常。受限硬件适配用于显存、平台或运行时约束占主导时，包括在会话前设定 MAX_SEQ_LEN 和 EVAL_TOKENS、会话开始后保持不变、调整模型/搜索策略而非中途作弊评估器、在 CUDA 假设不成立时转向社区分支。除非用户明确要求完整的端到端演练，否则不要同时回答全部五种模式。
第二步：重申不可变评估框架。每种模式都必须保留以下规则：program.md 由人类编写，会话期间只读；train.py 是主要可变搜索面；prepare.py 在会话开始后只读；TIME_BUDGET=300 保持固定；val_bpb 是主要保留/回滚指标；results.tsv 仅追加；pyproject.toml 中的依赖集保持锁定。如果用户想更改评估器，应开启新的比较轨道，而不是改动当前会话。
第三步：执行所选模式。
模式 A — Setup readiness：适用于仓库尚不可运行时。命令包括：curl -LsSf https://astral.sh/uv/install.sh | sh；git clone https://github.com/karpathy/autoresearch；cd autoresearch；uv sync；bash scripts/check-hardware.sh；uv run prepare.py；uv run train.py > run.log 2>&1；grep "^val_bpb:|^peak_vram_mb:" run.log。成功条件是完成一次基线运行并打印 val_bpb 和 peak_vram_mb。
模式 B — program.md 编写：适用于循环存在但方向薄弱时。最少章节包括：与降低 val_bpb 相关的目标；当前基线 val_bpb；按优先级排列的探索方向；已尝试内容；约束（TIME_BUDGET=300、不得修改 prepare.py、不得新增包、显存上限、每次实验只做一个有意义的改动）。更完整的模板和更新模式见 references/program-md-guide.md。
模式 C — 有界运行循环：仅在 setup 和 program.md 就绪后使用。循环契约：读取 program.md 和当前 train.py；形成一个假设；编辑 train.py；提交；运行一次 300 秒实验；提取 val_bpb；若改善则保留，否则 git reset HEAD~1；将结果追加到 results.tsv。典型命令：bash scripts/run-experiment.sh；bash scripts/run-loop.sh --max 20 --desc "session-1"。不要鼓励多改动的英雄式重写，干净的消融实验比花哨的编辑更重要。
模式 D — 结果解读：在完成运行或检查点之后使用。有用命令：bash scripts/show-results.sh --top 10；awk -F'\t' '$4=="keep"' results.tsv | sort -t$'\t' -k2 -n；awk -F'\t' '{print $4}' results.tsv | sort | uniq -c。只总结四件事：最佳增益、重复失败、应移入“已尝试内容”的部分、下一个窄实验族。
模式 E — 受限硬件适配：当显存、平台或运行时约束占主导时使用。规则：在会话前选择 MAX_SEQ_LEN 和 EVAL_TOKENS；绝不在会话中途更改；在改动评估器之前先降低模型/搜索野心；对于 Apple Silicon / 非 CUDA 路径，优先转向社区分支。具体数值和故障排除见 references/hardware-config.md。
第四步：当请求相邻时积极路由出去。当用户想优化指令、提示词或仓库本地技能时，转向 skill-autoresearch；当用户想要应用级追踪、反馈审查、可观测性或在线/离线评估仪表盘时，转向 LangSmith / Braintrust / Weave / Promptfoo；当用户想要通用文献综合而非可运行的 ML 循环时，转向研究或综述工具。
第五步：将大量细节保留在支持文件中，而不是内联重复解释。支持文件包括：references/operating-modes-and-route-outs.md（快速路由表、最小响应形态和交接逻辑）；references/architecture.md（不可变性契约、文件映射、指标依据）；references/program-md-guide.md（模板和更新规则）；references/hardware-config.md（按 GPU 的显存表、内存优化、平台故障排除）；scripts/*.sh（可运行的 setup / loop / reporting 辅助脚本）。
可用脚本（需在 autoresearch 仓库目录内运行）：setup.sh 用于一次性环境搭建，用法 bash scripts/setup.sh [--seq-len 512]；run-experiment.sh 用于单次 5 分钟实验并提取指标，用法 bash scripts/run-experiment.sh；run-loop.sh 用于自主循环：运行 → 保留/回滚 → 重复，用法 bash scripts/run-loop.sh [--max 20]；show-results.sh 用于人类可读的 results.tsv 报告，用法 bash scripts/show-results.sh [--top 10]；check-hardware.sh 用于 GPU/CUDA/uv 就绪检查（JSON 输出），用法 bash scripts/check-hardware.sh。
适用场景与限制
该技能适用于真实训练仓库上的 ML 搜索实验，强调基线优先、评估器冻结、一次一个有意义实验、results.tsv 仅追加。限制在于：它不处理提示词/应用评估或 SKILL.md 优化；不提供应用级追踪、数据集评估或可观测性；不适用于无训练循环的文献综述；具体硬件数值、平台支持和故障排除细节需查阅 references/hardware-config.md，资料中未提供完整数值表。