autoresearch

用途

autoresearch 用于在任意 git 仓库中搭建并运行自主代码改进循环（Karpathy 风格）。其核心模式是：通过 claude -p 生成假设，实现该假设，运行程序化评估门禁，若综合评分提升则保留，否则丢弃。该模式已在两个代码库上经过 50 多次迭代验证（shadow-engine：0.69 提升至 1.0；perplexity-clone：搜索质量优化）。

五项不变量（不可违反）

单一可变面：每次迭代一个假设，每个实验一次改动。
固定评估预算：评估在有限时间内运行，门禁中无网络调用。
单一标量指标：由综合评分驱动保留/丢弃，而非主观判断。
二元保留/丢弃：有改进则保留，否则执行 git reset --hard HEAD~1 回滚。
以 git 作为记忆：每个实验都是一次提交，丢弃即回滚，历史即日志。

安全规则

在实现假设期间，绝不修改 .lab/ 内容。
绝不跳过评估：每次提交在保留/丢弃前都必须经过评估。
崩溃时始终回滚：atexit 处理器恢复 git 状态。
运行器使用订阅认证（claude -p，并剥离 ANTHROPIC_API_KEY）。

主要能力

该技能提供以下命令：

/autoresearch init：在仓库中搭建 .lab/ 脚手架。
/autoresearch run：启动循环（默认 50 次迭代）。
/autoresearch status：检查进度。
/autoresearch resume：恢复中断的运行。
/autoresearch eval-gen：从仓库分析重新生成评估门禁。

初始化工作流

验证当前目录存在 .git/。
运行栈检测：python3 ~/.claude/skills/autoresearch/scripts/detect_stack.py
查看检测到的栈信息（语言、build_cmd、test_cmd、lint_cmd）。
运行脚手架脚本：python3 ~/.claude/skills/autoresearch/scripts/scaffold.py --repo-root . --yes
查看 .lab/config.json，按需调整 keep_threshold、max_iterations、gate_weights。
编辑 .lab/program.md（最重要的文件），添加：具体改进领域、具体假设列表（排序）、智能体必须遵守的约束。
运行基线评估验证门禁：python3 .lab/eval.py
向用户报告初始综合评分。

若 .lab/ 已存在，询问用户：恢复现有 lab，还是归档到 .lab.bak.<timestamp>/ 后重新开始。

评估门禁生成工作流

无需重新搭建全部内容即可重新生成评估门禁：

python3 ~/.claude/skills/autoresearch/scripts/eval_gen.py --repo-root . --output .lab/eval.py

门禁采用 4 层架构：

T1 构建+测试（权重 0.20）：编译、测试通过、lint 干净；运行真实命令，汇总通过数。
T2 行为（权重 0.40）：集成测试、CLI 输出、API 响应；验证内容而非文件存在性。
T3 流水线（权重 0.25）：构建产物、安装、真实 I/O；文件大小 >1KB，头部验证。
T4 文档（权重 0.15）：测试数量下限、文档覆盖率；统计代码，绝不信任注释。

运行工作流

python3 .lab/runner.py --max-iterations 50

或试运行（打印假设，不创建文件）：

python3 .lab/runner.py --dry-run --max-iterations 1

在单独终端监控进度：tail -f .lab/results.tsv

运行器流程：加载配置、读取 program.md、创建 autoresearch/{date} 分支、循环（假设 -> 实现 -> git 提交 -> 评估 -> 保留/丢弃）、记录每次实验到 .lab/results.tsv、每次实验后检查 9 个收敛信号、每 10 次真实实验重新验证基线、自动生成 .lab/eval-report.md。

实验状态包括：KEEP（综合评分提升 >= keep_threshold）、KEEP*（主指标提升但次指标回退）、DISCARD（无改进，已回滚）、INTERESTING（揭示结构的负面结果，记录到 dead-ends）、CRASH（评估基础设施失败，已回滚）、TIMEOUT（实验超时，记录为崩溃）。

状态工作流

python3 ~/.claude/skills/autoresearch/scripts/report.py --repo-root .

显示：实时综合评分、实验时间线、保留/丢弃/崩溃数、活跃收敛信号、分支谱系、死胡同。

恢复工作流

检查 .lab/ 是否存在；若存在，读取 config.json、results.tsv、log.md 尾部；呈现摘要（目标、指标、实验数、当前最佳 vs 基线、最后状态）；询问恢复还是重新开始；若恢复，检查陈旧锁文件并清理后运行。

.lab/ 目录布局

.lab/ 为 gitignored 的实验知识存储，包含：config.json（所有参数）、runner.py（定制运行器）、eval.py（生成+用户扩展的评估门禁）、eval_base.py（基础框架）、program.md（人工维护的约束与优先级）、results.tsv（实验日志）、log.md（每次实验的叙述条目）、branches.md（分支注册表）、dead-ends.md（被证伪的方法及原因）、parking-lot.md（延后想法）、eval-report.md（自动生成的累积报告）、runner-*.log（运行器日志）、.runner.lock（PID 锁文件，防止并发运行）。

选择 .lab/ 而非 autoresearch/ 的原因：代码状态（git）与实验知识（.lab/）完全解耦。git reset --hard HEAD~1（核心丢弃机制）绝不触及 .lab/，结果在分支操作后依然保留。

三层输出协议

评估门禁向 stderr 发出结构化诊断：

GATE build=PASS：二元，FAIL 时阻止迭代。
METRIC test_count=475：连续，记录在 results.tsv。
TRACE gate_duration_ms=3200：执行数据，仅用于调试。

脚本参考

scripts/detect_stack.py：检测语言、构建系统、测试运行器。
scripts/scaffold.py：创建 .lab/ 及所有文件。
scripts/eval_gen.py：生成对抗性评估门禁。
scripts/report.py：渲染状态报告。
scripts/runner_template.py：模板，复制到 .lab/runner.py。
assets/eval_base.py：基础评估框架，复制到 .lab/。
assets/config.json.tmpl：带文档字段的配置模板。
assets/program.md.tmpl：program.md 模板。

所有脚本使用 python3 运行（无特殊依赖），也可使用 uv run。

注意事项

环境中的 ANTHROPIC_API_KEY：运行器会剥离它，使 claude -p 使用订阅认证（而非按量付费 API）。若想使用 API 认证，在 config.json 中设置 use_api_key: true。
门禁随机性：若门禁对同一代码产生不同评分，运行器会在保留/丢弃间反复摇摆。所有门禁必须确定性。
恢复时的大 dt：若机器在运行期间挂起，运行器通过 atexit + 锁文件清理优雅处理。
评估崩溃 vs 门禁崩溃：评估崩溃（eval.py 本身失败）中止迭代；门禁崩溃（某个门禁抛出异常）记录在 crashed_gates 中并从综合评分中排除。

运行后检查清单

每次 autoresearch 运行后：查看 .lab/results.tsv 的保留/丢弃；阅读 .lab/eval-report.md 了解累积进度和上限检测；若满意，将 autoresearch 分支合并到 main；用被证伪的方法更新 .lab/program.md 的死胡同；运行 python3 .lab/eval.py 确认最终综合评分。

禁止事项

运行期间绝不修改 .lab/eval_base.py 或 .lab/runner.py。
绝不并发运行两个运行器（锁文件可防止，但不要绕过）。
绝不将 .lab/ 提交到 git（它被 gitignore 是有原因的）。
绝不信任包含崩溃门禁的综合评分。

适用场景与限制

适用场景：在 git 仓库中进行自主代码改进、搜索质量优化等可量化评估的任务。限制：需要确定性评估门禁；依赖 claude -p 与订阅认证；评估预算固定且门禁中无网络调用；.lab/ 不可提交到 git。