uditgoenka/autoresearch

``` PLAN LOOP DEBUG FIX SECURE SHIP ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Goal │ │ Modify │ │ Find │ │ Fix │ │ STRIDE │ │ Stage │ │ Metric │────▶│ Verify │────▶│ Bugs │────▶│ Errors │────▶│ OWASP │────▶│ Deploy │ │ Scope │ │Keep/Drop │ │ Trace │ │ Repair │ │ Red Team │ │ Release │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ /autoresearch: /autoresearch /autoresearch: /autoresearch: /autoresearch: /autoresearch: plan debug fix security ship ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Probe │ │ Scenario │ │ Predict │ │ Reason │ │ Require- │ │ Edge │ │ 5-Expert │ │ Debate │ │ ments │ │ Cases │ │ Swarm │ │ Converge │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ /autoresearch: /autoresearch: /autoresearch: /autoresearch: probe scenario predict reason ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Learn │ │ Improve │ │ Eval │ │ Baseline │ │ Docs │ │ Research │ │ Analyze │ │ Diff │ │ Gen │ │ PRDs │ │ Results │ │ Verdict │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ /autoresearch: /autoresearch: /autoresearch: /autoresearch: learn improve evals regression ``` ## 为什么会有这个项目 [Karpathy 的 autoresearch](https://github.com/karpathy/autoresearch) 证明了，一个 630 行的 Python 脚本可以通过遵循简单的原则自主地在夜间改进 ML 模型 —— **每晚进行 100 次实验** —— 这些原则是：单一指标、受限的范围、快速验证、自动回滚，以及将 git 作为记忆。 **Claude Autoresearch 将这些原则推广到了任何领域。** 不仅仅是 ML —— 还包括代码、内容、营销、销售、人力资源、DevOps，或任何有可量化数字的事物。 **v2.1.0 是一次重大的架构重构。** 原本庞大的单体 `SKILL.md`（813 行，每次调用消耗约 100K 个 token）被替换为一个精简的 41 行路由文件和 12 个独立的命令文件（每个文件 94–120 行，每次调用消耗约 5–8K 个 token）。这在保持相同功能表面的同时，**减少了 95% 的 token 消耗**。 ## 工作原理 ``` LOOP (N iterations or until done): 1. Review current state + git history + results log 2. Pick the next change (based on what worked, what failed, what's untried) 3. Make ONE focused change 4. Git commit (before verification) 5. Run mechanical verification (tests, benchmarks, scores) 6. If improved → keep. If worse → git revert. If crashed → fix or skip. 7. Log the result 8. Repeat until N iterations complete or goal is met. ``` 每一次改进都会被叠加。每一次失败都会自动回滚。进度以 TSV 格式记录。 ### 准备阶段 在开始循环之前，Claude 会执行一次性的设置： 1. **读取上下文** — 读取所有在范围内的文件 2. **定义目标** — 提取或要求提供一个机械化指标 3. **定义范围** — 确定哪些文件可以修改，哪些是只读的 4. **建立基准** — 对当前状态运行验证（第 0 次迭代） 5. **确认并开始** — 展示设置，然后开始循环 ### 8 条核心规则 | # | 规则 | |---|------| | 1 | **默认受限** — 每个命令都有默认的迭代次数；通过 `Iterations: unlimited` 选择无限制模式 | | 2 | **先读后写** — 在修改前充分理解上下文 | | 3 | **每次迭代只做一个更改** — 原子化更改；如果出错，你会知道为什么 | | 4 | **仅进行机械化验证** — 没有主观的“看起来不错”；必须使用指标 | | 5 | **自动回滚** — 失败的更改会立即还原 | | 6 | **简单至上** — 结果相同 + 代码更少 = 保留 | | 7 | **Git 即记忆** — 实验以 `experiment:` 为前缀提交；Agent 在每次迭代前读取 `git log` + `git diff` | | 8 | **遇到瓶颈时，更深入地思考** — 重新阅读，组合差一点就成功的尝试，尝试颠覆性的改变 | ## Hooks 与安全性 v2.1.1 发布了包含 9 个 hook 的安全系统，可自动保护你的会话。这些 hook 会在每个会话中触发——不仅限于 autoresearch 命令执行期间。 ### 受保护的内容 | Hook | 作用 | 触发事件 | |------|-------------|-------| | **scout-block** | 阻止 node_modules/、.git/、__pycache__/ 等填满你的上下文 | PreToolUse | | **privacy-block** | 阻止在会话中读取 .env、SSH 密钥和凭据 | PreToolUse | | **dangerous-cmd-block** | 阻止 force-push、`rm -rf`、`git reset --hard` | PreToolUse | | **iteration-context** | 在上下文压缩后注入最近的 TSV 迭代数据 | UserPromptSubmit | | **subagent-context** | 让子 Agent 感知活跃的循环状态 | SubagentStart | | **dev-rules-reminder** | 在压缩后重新注入计划路径和代码规范 | UserPromptSubmit | | **simplify-gate** | 发布前在 400 行代码 (LOC) 时发出警告，800 行时进行阻止 | UserPromptSubmit | | **session-init** | 在会话开始时设置项目上下文 | SessionStart | | **stop-notify** | 会话结束时发送终端通知 + 可选的 webhook | SessionEnd | ### 配置 所有 hook **默认开启**。可单独禁用： ``` # 禁用特定 hook export AR_DISABLE_SCOUT_BLOCK=1 export AR_DISABLE_PRIVACY_BLOCK=1 export AR_DISABLE_DANGEROUS_CMD_BLOCK=1 # ... 等等，针对每个 hook 名称 ``` 用于会话完成通知的可选 webhook： ``` export AR_NOTIFY_WEBHOOK=https://hooks.slack.com/services/... ``` 使用项目根目录下的 `.ckignore` 文件（遵循 gitignore 语法）自定义要屏蔽的目录。 完整参考请查阅 [guide/hooks.md](guide/hooks.md)。 ## 命令 | 命令 | 功能 | 默认迭代次数 | |---------|--------------|--------------------| | `/autoresearch` | **经典模式：** 核心迭代循环：修改 → 验证 → 保留/丢弃 · **编排器模式：** 自由格式目标 → 自动选择流水线 → 循环直到满足判定条件 | 25 / 基于目标受限 | | `/autoresearch:plan` | 将目标转换为已验证的配置 | 一次性 | | `/autoresearch:debug` | 通过假设迭代追踪 bug | 15 | | `/autoresearch:fix` | 将错误逐一清零 | 20 | | `/autoresearch:security` | 结合红队的 STRIDE + OWASP 审计 | 15 | | `/autoresearch:ship` | 经历 8 个阶段进行交付 | 线性 | | `/autoresearch:scenario` | 跨 12 个维度生成边缘场景 | 20 | | `/autoresearch:predict` | 5 个专家角色进行辩论 | 一次性 | | `/autoresearch:learn` | 探索 → 生成文档 → 验证 → 修复 | 10 | | `/autoresearch:reason` | 由盲审评委进行对抗性辩论 | 8 | | `/autoresearch:probe` | 8 个角色对需求进行质询 | 15 | | `/autoresearch:improve` | 研究 ICP，发现改进点，生成 PRD | 15 | | `/autoresearch:evals` | 分析迭代结果：趋势、停滞期 | 一次性 | | `/autoresearch:regression` | 稳定性关卡：基准版本 vs 候选版本，给出 STABLE/UNSTABLE 结论 | 一次性 | **通用标志:** `Iterations: N`, `Iterations: unlimited`, `--evals`, `--evals-interval N`, `--chain `, `--` 简写。 **所有命令在不带参数调用时均使用交互式设置。** 只需输入命令——Agent 会根据你的代码库以智能默认值询问所需信息。 ### 快速决策指南 | 我想要... | 使用 | |--------------|-----| | 给出一个自然语言目标，让它自主编排 | `/autoresearch ` （不带 Metric/Verify） | | 提高测试覆盖率 / 减小打包体积 / 改善任何指标 | `/autoresearch` | | 运行有界限的迭代 | 在任何命令中添加 `Iterations: N` | | 不知道该用什么指标 | `/autoresearch:plan` | | 运行安全审计 | `/autoresearch:security` | | 交付 PR / 部署 / 发布 | `/autoresearch:ship` | | 在不破坏现有测试的前提下进行优化 | 添加 `Guard: npm test` | | 寻找代码库中的所有 bug | `/autoresearch:debug` | | 修复所有错误（测试、类型、lint） | `/autoresearch:fix` | | 先调试然后自动修复 | `/autoresearch:debug --fix` | | 检查某项内容是否已准备好交付 | `/autoresearch:ship --checklist-only` | | 探索某个功能的边缘场景 | `/autoresearch:scenario` | | 生成测试场景 | `/autoresearch:scenario --format test-scenarios` | | 在开始前获取专家意见 | `/autoresearch:predict` | | 从多个角度分析后再调试 | `/autoresearch:predict --chain debug` | | 为新代码库生成文档 | `/autoresearch:learn --mode init` | | 修改后更新现有文档 | `/autoresearch:learn --mode update` | | 对架构决策进行辩论 | `/autoresearch:reason --domain software` | | 在开始前挖掘隐藏的约束条件 | `/autoresearch:probe` | | 对模糊目标进行预检后进入循环 | `/autoresearch:probe --chain plan,autoresearch` | | 为你的 ICP 发现接下来要构建什么 | `/autoresearch:improve` | | 研究竞争对手并生成 PRD | `/autoresearch:improve --depth deep` | | 质询需求并研究改进点 | `/autoresearch:probe --improve` | | 分析过往运行的趋势和停滞期 | `/autoresearch:evals` | | 检查某次运行是否已停滞 | `/autoresearch:evals --file *-results.tsv` | | 在推送前验证更改不会发生回归 | `/autoresearch:regression` | | 为 PR 设置关卡：预测、修复、重新把关，然后交付 | `/autoresearch:regression --predict --fix --ship` | ## 快速开始 ### Claude Code **选项 A — 通过 npx 安装（推荐）：** ``` npx skills add uditgoenka/autoresearch ``` 重启 Claude Code 后，所有 14 个命令即可使用。 **选项 B — 插件安装：** ``` /plugin marketplace add uditgoenka/autoresearch /plugin install autoresearch@autoresearch ``` **更新（无需重新安装）：** ``` /plugin update autoresearch ``` 运行 `/reload-plugins` 以激活。无需卸载或重新克隆。 **选项 C — 手动复制：** ``` git clone https://github.com/uditgoenka/autoresearch.git # 复制 skill + subcommands 到你的项目 cp -r autoresearch/.claude/skills/autoresearch .claude/skills/autoresearch cp -r autoresearch/.claude/commands/autoresearch .claude/commands/autoresearch cp autoresearch/.claude/commands/autoresearch.md .claude/commands/autoresearch.md ``` 或全局安装： ``` cp -r autoresearch/.claude/skills/autoresearch ~/.claude/skills/autoresearch cp -r autoresearch/.claude/commands/autoresearch ~/.claude/commands/autoresearch cp autoresearch/.claude/commands/autoresearch.md ~/.claude/commands/autoresearch.md ``` **选项 D — 引导式安装程序：** ``` git clone https://github.com/uditgoenka/autoresearch.git cd autoresearch ./scripts/install.sh --claude --global ``` ### OpenCode 快速开始 **选项 A — 引导式安装程序（推荐）：** ``` git clone https://github.com/uditgoenka/autoresearch.git cd autoresearch ./scripts/install.sh --opencode --global ``` **选项 B — 手动复制：** ``` git clone https://github.com/uditgoenka/autoresearch.git cp -r autoresearch/.opencode/skills/autoresearch .opencode/skills/autoresearch cp autoresearch/.opencode/commands/autoresearch*.md .opencode/commands/ ``` 或全局安装： ``` cp -r autoresearch/.opencode/skills/autoresearch ~/.config/opencode/skills/autoresearch cp autoresearch/.opencode/commands/autoresearch*.md ~/.config/opencode/commands/ ``` ### Codex 快速开始 **选项 A — 引导式安装程序（推荐）：** ``` git clone https://github.com/uditgoenka/autoresearch.git cd autoresearch ./scripts/install.sh --codex --global ``` **选项 B — 手动复制：** ``` git clone https://github.com/uditgoenka/autoresearch.git cp -r autoresearch/.agents/skills/autoresearch ~/.codex/skills/autoresearch ``` ### 运行 ``` /autoresearch Goal: Increase test coverage from 72% to 90% Scope: src/**/*.test.ts, src/**/*.ts Metric: coverage % (higher is better) Verify: npm test -- --coverage | grep "All files" Iterations: 25 ``` Claude 会读取所有文件，建立基准，并开始迭代 —— 每次只做一个更改。保留改进，自动回滚失败，记录所有过程。在 N 次迭代后或你中断时停止。 ## /autoresearch:plan — 从目标到配置 最困难的部分不是循环 —— 而是正确定义 Scope、Metric 和 Verify。`/autoresearch:plan` 会将你的自然语言目标转换为经过验证且可随时执行的配置。 ``` /autoresearch:plan Goal: Make the API respond faster ``` 经历 5 个步骤：捕获目标 → 定义范围 → 定义指标 → 定义方向 → 验证 verify 命令（空运行）。每一个关卡都是机械化的——范围必须解析到具体文件，指标必须输出数字，verify 必须通过空运行。最后会输出一个 `handoff.json` 以便进行链式调用。 ## /autoresearch:debug — 自主 Bug 猎手 将科学方法与 autoresearch 循环相结合。它不会止步于一个 bug —— 而是利用可证伪的假设、基于证据的调查以及 7 种调查技术，迭代地追踪所有 bug。 ``` /autoresearch:debug Scope: src/api/**/*.ts Symptom: API returns 500 on POST /users Iterations: 15 ``` **工作原理：** 收集症状 → 侦察 提出假设（具体且可测试）→ 测试（每次迭代进行一次实验）→ 分类（已确认/已证伪/不确定）→ 记录 → 重复。 每一项发现都需要代码证据（文件:行号 + 复现步骤）。每一个被证伪的假设都会被记录下来——这同样有价值。 | 标志 | 用途 | |------|---------| | `--fix` | 狩猎完成后，自动切换至 `/autoresearch:fix` | | `--scope ` | 限制调查范围 | | `--symptom ""` | 预先填入症状 | | `--severity ` | 报告的最低严重级别 | ## /autoresearch:fix — 自主错误粉碎机 接收损坏的状态并迭代修复，直到一切通过测试。每次迭代只修复一个错误。原子化、提交、验证，失败则自动回滚。 ``` /autoresearch:fix Iterations: 20 ``` 自动检测损坏的部分（测试、类型、lint、构建）→ 排定优先级（阻塞性问题优先）→ 修复一个问题 → 提交 → 验证错误数量是否减少 → Guard 检查 → 保留/回滚 → 重复。**当错误数量降至零时自动停止。** | 标志 | 用途 | |------|---------| | `--target ` | 显式指定 verify 命令 | | `--guard ` | 必须始终通过的安全命令 | | `--category ` | 仅修复特定类型（test、type、lint、build） | | `--from-debug` | 从最近的 debug 会话中读取发现结果 | **链式调用：** `/autoresearch:debug` → `/autoresearch:fix --from-debug` ## /autoresearch:security — 自主安全审计 使用 STRIDE 威胁建模、OWASP Top 10 扫描以及包含 4 个敌对角色的红队对抗性分析进行只读安全审计。 ``` /autoresearch:security Iterations: 15 ``` 代码库侦察 → 资产盘点 → 信任边界 → STRIDE 威胁模型 → 攻击面映射 → 自主测试循环 → 结构化报告。每一项发现都需要代码证据（文件:行号 + 攻击场景）。 | 标志 | 用途 | |------|---------| | `--diff` | 仅审计自上次审计以来更改过的文件 | | `--fix` | 自动修复已确认的 Critical/High 发现 | | `--fail-on ` | 为 CI/CD 卡制返回非零退出码 | **输出：** 创建 `security/{date}-{slug}/` 目录，包含 7 个结构化报告文件。 ## /autoresearch:ship — 通用交付工作流 通过 8 个阶段交付任何内容：**识别 → 盘点 → 清单 → 准备 → 空运行 → 交付 → 验证 → 记录。** ``` /autoresearch:ship --auto ``` 自动检测你要交付的内容（代码 PR、部署、博客文章、电子邮件营销活动、销售演示文稿、研究论文、设计资产）并生成特定领域的清单 —— 每一项都可机械化验证。 | 标志 | 用途 | |------|---------| | `--dry-run` | 验证一切但不进行交付 | | `--auto` | 如果清单通过则自动批准 | | `--force` | 跳过非关键项（仍然强制执行阻塞性项） | | `--rollback` | 撤销上一次交付操作 | | `--monitor N` | 交付后监控 N 分钟 | | `--checklist-only` | 仅检查就绪状态 | **支持的 9 种类型：** code-pr、code-release、deployment、content、marketing-email、marketing-campaign、sales、research、design。 ## /autoresearch:scenario — 场景探索器 自主场景探索引擎。接收一个种子场景，并迭代地在 12 个维度上生成情境 —— 包括正常路径、错误、边缘场景、滥用、规模、并发、时间、数据变异、权限、集成、恢复和状态转换。 ``` /autoresearch:scenario Scenario: User attempts to checkout with multiple payment methods Iterations: 20 ``` 种子分析 → 分解为 12 个维度 → 每次迭代生成一个情境 → 分类（新情境/变体/重复）→ 扩展边缘场景 → 记录 → 重复。 | 标志 | 用途 | |------|---------| | `--domain ` | software、product、business、security、marketing | | `--depth ` | shallow (10)、standard (20)、deep (50+) | | `--format ` | use-cases、user-stories、test-scenarios、threat-scenarios | | `--focus ` | edge-cases、failures、security、scale | ## /autoresearch:predict — 多角色预测 在你调试、修复或交付之前 —— 在 2 分钟内获取 5 个专家视角。 模拟一个团队（架构师、安全分析师、性能工程师、可靠性工程师、魔鬼代言人），他们独立分析你的代码，对发现进行辩论，并达成共识。 ``` /autoresearch:predict --chain debug ``` - `--chain debug` — 在调试前提供预先排序的假设 - `--chain security` — 多角色红队分析 - `--chain scenario,debug,fix` — 全流程质量管道 ## /autoresearch:learn — 自主文档引擎 探索代码库 → 生成文档 → 验证 → 修复 → 重复。4 种模式：init（从零开始创建）、update（刷新已有文档）、check（只读健康报告）、summarize（快速概览）。 ``` /autoresearch:learn --mode init --depth deep Iterations: 10 ``` 动态文档发现、项目类型检测、验证-修复循环、用于更新的 git-diff 范围限定，以及通过 `--file` 选择性更新单个文档。自动生成 Mermaid 架构图、API 参考、测试指南、配置指南和交叉引用链接。 ## /autoresearch:reason — 对抗性精炼 将 autoresearch 扩展到**没有客观指标的主观领域**。盲审评审团就是适应度函数。 ``` /autoresearch:reason Task: Should we use event sourcing for our order management system? Domain: software Iterations: 8 ``` **工作原理：** 生成-A → 评审发起攻击 → 作者-B 进行回应 → 合成器进行融合 → 盲审评审团（随机化标签）选出胜者 → 胜者成为新的 A → 重复直到收敛。每个 Agent 都是冷启动的全新调用——没有历史记录的干扰。 | 标志 | 用途 | |------|---------| | `--judges N` | 评委数量（3-7，首选奇数） | | `--convergence N` | 连续获胜以达到收敛的次数（默认为 3） | | `--mode ` | convergent（默认）、creative、debate | | `--domain ` | software、product、business、security、research、content | | `--chain ` | 将收敛后的输出链接到任何 autoresearch 命令 | **输出：** 创建 `reason/{date}-{slug}/` 目录，包含 lineage.md、candidates.md、judge-transcripts.md、reason-results.tsv、handoff.json。 ## /autoresearch:probe — 对抗性需求质询 八个对抗性角色共同质询用户和代码库，直到全新的约束条件达到饱和。输出为 5 个 autoresearch 基本要素（目标/范围/指标/方向/验证）以及一个准备好提供给任何下游命令的 `handoff.json`。 ``` /autoresearch:probe --chain plan,autoresearch Topic: Add multi-tenant isolation to the database layer ``` **8 个角色：** 怀疑论者、边缘案例猎手、范围守卫者、歧义侦探、矛盾寻找者、现有技术调查员、成功标准审计员、约束挖掘机。 | 标志 | 用途 | |------|---------| | `--depth ` | shallow（5 轮）、standard（15 轮）、deep（30 轮） | | `--adversarial` | 将怀疑论者 + 矛盾寻找者 + 边缘案例猎手轮换到前台 | | `--mode ` | interactive（默认）或 autonomous | | `--chain ` | plan、predict、debug、scenario、reason、fix、ship、learn | **输出：** 创建 `probe/{date}-{slug}/` 目录，包含 probe-spec.md、constraints.tsv、autoresearch-config.yml、handoff.json。 ## /autoresearch:improve — 产品改进引擎 研究接下来要构建什么。通过深度的多源研究发现 ICP 挑战，对改进点进行评分和排名，并生成带有证据链的各功能 PRD。 ``` /autoresearch:improve Goal: Improve onboarding conversion ICP: B2B SaaS product managers at 50-500 person companies ``` **工作原理：** 解析产品上下文 → 跨 5 个类别（ICP 挑战、竞争对手差距、市场趋势、UX 与体验、收入与增长）进行研究 → 饱和度测试 → ICP 二元把关 → 分层排名（必备 / 锦上添花 / 颠覆性创新） → 用户选择功能 → 生成 PRD。 | 标志 | 用途 | |------|---------| | `--icp ""` | 理想客户画像 | | `--discover` | 即使已有现有上下文也强制扫描代码库 | | `--no-discover` | 跳过自动发现 | | `--depth ` | shallow（5）、standard（15）、deep（30+） | | `--seeds ` | 覆盖默认研究类别 | **输出：** 创建 `improve/{date}-{slug}/` 目录，包含 research-findings.md、improvement-plan.md、各功能的 PRD、summary.md、improve-results.tsv、handoff.json。 **终端发射器** — improve 是任何 autoresearch 链的最后一环。PRD 供外部工具（`/ck:plan`、`/ck:cook`）使用，而不是由其他 autoresearch 命令使用。 **链式调用至 improve：** `/autoresearch:probe --improve`、`/autoresearch:predict --improve`、`/autoresearch:debug --improve`。 ## /autoresearch:evals — 结果分析器 分析来自任何 autoresearch 运行的 `*-results.tsv` 文件。展现趋势、停滞期检测、收敛信号和迭代效率。向后兼容 v2.0.x TSV 格式。 ``` /autoresearch:evals /autoresearch:evals --file coverage-results.tsv ``` **自适应检查点：** floor(max_iterations/3)，最少 1 个检查点。报告每个检查点的增量、停滞检测、最佳迭代以及建议（继续 / 停止 / 更改策略）。 **在运行期间进行内联评估：** ``` /autoresearch Goal: Reduce bundle size below 200kb Iterations: 30 --evals-interval 10 ``` 每 10 次迭代打印一次检查点报告，且不会中断循环。 ## /autoresearch:regression — 稳定性关卡 在推送之前，证明更改没有破坏之前能正常工作的功能。从基础引用的 `git worktree` 中捕获基准行为，跨 **8 个维度**对候选版本进行差异对比，并给出单一的 **STABLE / UNSTABLE** 结论。 ``` /autoresearch:regression --predict --evals --fix --ship ``` **核心不变式：** 回归**仅指从绿变红的转换**。预先存在的失败（红变红）、新测试（不存在变红）和不稳定测试（flaky 变红）会被分类并排除——永远不会被计为回归。 **分级判定：** - **HARD 关卡**（任何从绿变红 = UNSTABLE）：`functional`、`api-contract`、`data-migration`、`integration-e2e` - **SCORE**（0–100，容忍噪音，加权；低于阈值 95 则为 UNSTABLE）：`flakiness` .30、`performance` .30、`resource` .20、`visual-ui` .20 | 标志 | 用途 | |------|---------| | `--select auto` | 使用检测到的受影响测试映射器（jest `--findRelatedTests`、nx affected），否则运行 FULL 套件——绝不静默运行子集 | | `--samples N` / `--noise-band %` | 调整性能统计关卡（默认每侧 7 个样本，Mann–Whitney U） | | `--fix` / `--fix-cycles N` | 修复后重新把关；每个周期必须严格缩小阻塞集（最多 3 个） | | `--predict` | 在关卡运行之前预先防范可能的回归 | | `--reason` | 当回归原因不明确时进行对抗性的根因分析 | | `--debug` | 强制使用二分查找猎手（HARD 维度 3/3 复现通过） | | `--max-runs N` | dims×axes×samples×cells 的上限（超过 200 时警告并确认） | **输出：** 创建 `regression/{date}-{slug}/` 目录，包含 regression-results.tsv、stability-report.md、dimensions/.md、baseline/、evals-summary.md、handoff.json。 ## Guard — 防止回归 在优化指标时，循环可能会破坏现有行为。**Guard** 是一个可选的安全网。 ``` /autoresearch Goal: Reduce API response time to under 100ms Verify: npm run bench:api | grep "p95" Guard: npm test ``` - **Verify** = “指标改善了吗？”（目标） - **Guard** = “有没有破坏其他东西？”（安全网） 如果指标改善但 Guard 失败，Claude 会重新调整优化方案（最多尝试 2 次）。Guard/测试文件永远不会被修改。 ## 结果跟踪 每次迭代都以 TSV 格式记录 ``` iteration commit metric delta status description 0 a1b2c3d 85.2 0.0 baseline initial state 1 b2c3d4e 87.1 +1.9 keep add tests for auth edge cases 2 - 86.5 -0.6 discard refactor test helpers (broke 2 tests) 3 c3d4e5f 88.3 +1.2 keep add error handling tests ``` 随时运行 `/autoresearch:evals` 来分析任何 TSV 文件中的趋势。自适应检查点会在 floor(max_iterations/3) 间隔时触发。 ## 崩溃恢复 | 故障 | 响应 | |---------|----------| | 语法错误 | 立即修复，不计入迭代次数 | | 运行时错误 | 尝试修复（最多 3 次），然后继续 | | 资源耗尽 | 回滚，尝试较小的变体 | | 无限循环 / 卡死 | 超时后终止，回滚 | | 外部依赖问题 | 跳过，记录，尝试不同的方法 | ## 仓库结构 ``` autoresearch/ ├── README.md ├── COMPARISON.md ← Karpathy's vs Claude Autoresearch ├── guide/ ← Guides — one per command + advanced patterns ├── scripts/ │ ├── install.sh ← Guided installer (Claude Code + OpenCode + Codex) │ ├── transform.sh ← Single transform: .claude/ → .opencode/ + .agents/ │ ├── release.sh ← Release automation │ └── release.md ← Release checklist ├── .claude/ │ ├── skills/autoresearch/ │ │ ├── SKILL.md ← Thin routing table (41 lines) │ │ └── references/ ← 3 focused reference files │ │ ├── security-checklist.md ← STRIDE + OWASP │ │ ├── predict-personas.md ← 5 personas + adversarial set │ │ └── reason-judge-protocol.md ← Adversarial refinement loop │ └── commands/ │ ├── autoresearch.md ← Core loop (self-contained, ~100 lines) │ └── autoresearch/ ← 13 subcommand files (self-contained) │ ├── plan.md │ ├── debug.md │ ├── fix.md │ ├── security.md │ ├── ship.md │ ├── scenario.md │ ├── predict.md │ ├── learn.md │ ├── reason.md │ ├── improve.md │ ├── probe.md │ ├── evals.md │ └── regression.md ├── .opencode/ ← OpenCode port (via transform.sh) │ ├── skills/autoresearch/ │ └── commands/ ← 14 command files (autoresearch_*.md) ├── .agents/ ← Codex port (via transform.sh) │ └── skills/autoresearch/ ├── plugins/ ← Codex plugin metadata │ └── openai.yaml └── LICENSE ``` ## 常见问题 **问：我不知道该用什么指标。** 答：运行 `/autoresearch:plan` —— 它会分析你的代码库，推荐指标，并在你启动之前对 verify 命令进行空运行。 **问：v2.2.0 有什么变化？** 答：根命令 `/autoresearch` 现在支持自主编排器模式。输入自然语言目标（例如，`/autoresearch help me fix the login bug`），而不是 `Metric:`/`Verify:`，编排器会对你的目标进行分类，推导出可验证的成功谓词，确认一次，然后跨子命令循环直到完成。当提供 `Metric:` 或 `Verify:` 时，经典的指标循环行为保持不变。 **问：v2.1.0 有什么变化？** 答：架构重构。庞大的单体 `SKILL.md`（813 行，约 100K token）被替换为精简的路由文件 + 12 个独立的命令文件（每个约 5–8K token）。减少了 95% 的 token。新的 `/autoresearch:evals` 命令可分析迭代结果。现在每个循环命令都有一个有界限的默认值，而不是无限制地运行。 **问：有界限的默认值是如何工作的？** 答：每个循环命令都带有一个合理的默认值（例如，`/autoresearch` 默认为 25 次迭代）。进行内联覆盖：使用 `Iterations: 50` 来增加次数，使用 `Iterations: unlimited` 来恢复以前的无限制行为。 **问：/autoresearch:evals 是如何工作的？** 答：将其指向之前运行生成的任何 `*-results.tsv` 文件。它会报告趋势、停滞期检测和建议。在实时运行期间使用 `--evals-interval N` 获取检查点报告，而不会中断循环。 **问：这适用于任何项目吗？** 答：是的。任何语言、框架或领域。可通过插件（Claude Code）、安装脚本或手动复制进行安装。 **问：这适用于 OpenCode 吗？** 答：是的。运行 `./scripts/install.sh --opencode --global` 或手动复制 `.opencode/` 文件。命令使用下划线命名（`/autoresearch_debug`、`/autoresearch_evals` 等）。所有 14 个命令均可用。 **问：这适用于 OpenAI Codex 吗？** 答：是的。运行 `./scripts/install.sh --codex --global` 或将 `.agents/skills/autoresearch/` 复制到 `~/.codex/skills/autoresearch`。通过 `$autoresearch` 提及语法调用。 **问：如何停止循环？** 答：按 `Ctrl+C` 或在内联配置中添加 `Iterations: N`。Claude 会在验证之前提交，因此你最后成功的状态始终保存在 git 中。 **问：我可以将其用于非代码任务吗？** 答：绝对可以。销售邮件、营销文案、人力资源政策、运行手册 —— 任何具有可量化指标的事物。参见[按领域划分的示例](guide/examples-by-domain.md)。 **问：/autoresearch:security 会修改我的代码吗？** 答：不会。默认为只读。使用 `--fix` 可选择对确认的 Critical/High 发现进行自动修复。 **问：/autoresearch:predict 和 /autoresearch:reason 有什么区别？** 答：predict 是一次性分析 —— 5 位专家对你现有的代码进行辩论。reason 是一个迭代精炼循环 —— 生成相互竞争的候选方案，经过多轮的批评、综合和盲审，直到收敛。在采取行动之前使用 predict 进行分析；在没有客观指标进行决策时使用 reason。 **问：handoff.json 是什么？** 答：这是一个由 plan、probe、reason 和其他命令输出的结构化文件，为下游命令携带 Goal/Scope/Metric/Verify 配置。当你使用 `--chain plan,autoresearch` 时，链会自动读取 handoff.json。 ## 贡献 欢迎贡献。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 感兴趣的领域：新的领域示例、验证脚本模板、CI/CD 集成、真实世界的基准测试。所有指南均位于 [guide/](guide/) 目录中。 ## Star 历史 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。 ## 鸣谢 - **[Andrej Karpathy](https://github.com/karpathy)** — 感谢 [autoresearch](https://github.com/karpathy/autoresearch) - **[Anthropic](https://anthropic.com)** — 感谢 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 及其技能系统 - **[OpenCode](https://opencode.ai)** — 感谢 OpenCode 终端 Agent - **[OpenAI](https://openai.com)** — 感谢 [Codex](https://developers.openai.com/codex) 及 Agent 技能标准

## 关于作者 **[Udit Goenka](https://udit.co)** — AI 产品专家、创始人兼天使投资人 自学成才的构建者，从印度缓慢的互联网连接起步，创立了多家公司，并帮助 700 多家初创企业创造了超过约 2500 万美元的收入。 **构建：** [TinyCheque](https://tinycheque.com)（印度首家 Agentic AI 风险工作室） · [Firstsales.io](https://firstsales.io)（销售自动化） **投资：** 支持 38 家初创企业，6 次退出。专注于早期 AI 和 SaaS。 **社交连接：** [udit.co](https://udit.co) · [@iuditg](https://x.com/iuditg) · [@uditgoenka](https://github.com/uditgoenka) · [新闻简报](https://udit.co/blog)

标签：AI编程助手, Claude, CVE检测, SOC Prime, 人工智能, 开发工具, 用户模式Hook绕过, 网络安全研究, 自动化迭代