autoresearch

Autoresearch — 自主目标导向迭代

安全不变量（适用于所有子命令）

• 未经用户明确批准，绝不推送、发布或部署。
• 默认设有上限。使用 Iterations: unlimited 可覆盖上限。
• 所有结果均记录在 autoresearch/{subcommand}-{YYMMDD}-{HHMM}/ 目录中。
• 通过 handoff.json 传递任务；Evals 会读取 *-results.tsv。

分发（裸 $autoresearch）

按以下顺序解析调用：

条件	模式
存在 Metric: 或 Verify:	经典模式 — 使用现有指标循环，不做改动
自由格式的自然语言目标，且没有指标或验证项	编排器 — 参见“编排器”章节
没有内容	设置向导 — 交互式配置生成器
--classic 标志	无论目标文本为何，强制使用经典模式
--auto 标志	无论目标文本为何，强制使用编排器

每次调用都打印横幅：[autoresearch] mode: classic | orchestrator | wizard。

子命令

命令	功能	默认迭代次数
$autoresearch	针对指标迭代：修改 → 验证 → 保留或丢弃	25
$autoresearch plan	将目标转换为经过验证的 Scope、Metric、Verify 配置	不适用
$autoresearch debug	排查错误：提出假设 → 测试 → 证伪 → 重复	15
$autoresearch fix	逐个解决错误，直到全部清零	20
$autoresearch security	使用红队角色开展 STRIDE + OWASP 审计	15
$autoresearch ship	通过 8 个阶段完成交付：检查清单 → 演练 → 部署 → 验证	不适用
$autoresearch scenario	从 12 个维度生成边缘案例	20
$autoresearch predict	实施前由 5 个专家角色进行辩论	不适用
$autoresearch learn	探查代码库 → 生成文档或 wiki → 验证 → 修复循环	10
$autoresearch reason	与对抗性辩论者展开讨论，由盲审者评判，直到达成共识	8
$autoresearch probe	由 8 个角色盘问需求，直到信息饱和	15
$autoresearch improve	研究 ICP 挑战、发现改进方向并生成 PRD	15
$autoresearch evals	分析迭代结果：趋势、平台期、回归	不适用
$autoresearch regression	回归稳定性关卡：基线与候选版本对比，判定 STABLE/UNSTABLE	不适用

通用标志

标志	适用范围	用途
Iterations: N	所有循环	设置迭代次数
Iterations: unlimited	所有循环	选择不设上限
--evals	所有循环	在循环中设置检查点并生成最终摘要
--evals-interval N	所有循环	覆盖检查点频率
--chain <targets>	全部	完成后按顺序交接任务
--<subcommand>	全部	--chain <subcommand> 的简写
--dry-run	编排器	打印推导出的配置和计划的流水线；不执行
--max-cycles N	编排器	编排周期的硬性上限（默认 50）
--classic	裸 $autoresearch	强制使用经典指标循环模式
--auto	裸 $autoresearch	强制使用编排器模式

编排器

当给出纯语言目标且没有 Metric:/Verify: 时启用。它会将目标归类为某种目标类型 — 参见 references/orchestrator-routing.md 中的类型表和路由决策表。

以下所有 scripts/... 路径都必须相对于此已安装的技能目录解析，不能相对于调用方的工作目录解析。

根据目标类型分为两种模式：

• 编排循环 — 含有谓词的目标类型（ship-ready、optimize-metric、fix-broken、harden、build-feature、explore）。目标具有机械可判定的成功谓词；循环会持续运行，直到满足该谓词。
• 单次分发 — 主观或终结型目标类型（document、what-to-build、decide-design）。只路由一次到合适的子命令（learn / improve / reason），让其自行终止，然后报告结果。没有循环、平台期或交付关卡。

编排循环步骤

由 scripts/orchestrate.sh 提供支持（确定性接口——所有路由逻辑都位于其中）。开放的子命令：classify、next-hop、units、plateau、screen-cmd、verdict、validate-state、screen-state-predicate。

1. 分类 — scripts/orchestrate.sh classify "<goal>" → 原型标签 + 模式。
2. 推导谓词 — 重用 plan 逻辑，生成具体的成功谓词：精确的 shell 命令 + 预期输出。对于 optimize-metric，在内部运行完整的计划／向导推导流程。
3. 确认 — 显示一个 request_user_input，其中包含：原型、模式、具体谓词（命令 + 预期输出）、终止选择（验证后停止或继续交付）。分类错误会在此处发现，而不是在运行过程中。
4. 第 0 轮试运行 — 证明谓词命令能够运行并返回值；通过 screen-cmd 对每条推导出的命令进行安全筛查；打印预计的循环预算。如果是 --dry-run，则在此处停止。
5. 循环直到满足谓词： a. 根据低成本信号（最近的 handoff.json、回归判定、错误数）以及受影响测试的验证来评估状态。 b. scripts/orchestrate.sh next-hop orchestrator-state.json → 下一个子命令。 c. 运行子命令（其自身有界的内部循环）。 d. 记录每个步骤的结果 ∈ {有进展、无操作、失败、受阻}。 e. 将该步骤的 handoff.json 合并到 orchestrator-state.json。 f. scripts/orchestrate.sh units → 重新计算剩余单位数。
6. 停止条件（每个步骤完成后检查）：
   • 满足谓词 → 进入交付关卡（仅当交付在流程中时），否则报告 CONVERGED。
   • scripts/orchestrate.sh plateau orchestrator-state.json → 返回 true → 停止并报告 PLATEAU。
   • 循环次数 > 上限（默认为 50，可通过 --max-cycles N 覆盖）→ 停止并报告 CEILING。
   • 步骤结果为 blocked／failed，且没有其他路线 → 设置检查点并停止，报告 BLOCKED。

编排器状态

orchestrator-state.json — 由编排器拥有，采用增量记录。跟踪：目标、原型、谓词、终止选择、units_remaining 历史、循环次数、包含各步骤结果的流程日志、当前最优项。每个步骤的 handoff.json 保持不变（单步骤桥接）；编排器读取后将其合并。两个归属清晰的状态对象，互不重叠。

编排器安全不变量

• 绝不自动批准交付／部署／推送。 编排器绝不会向 ship 传递 --auto；部署始终需要用户明确批准。
• 数据迁移受锚定的 DB-URL 允许列表保护。 重用回归流程的允许列表——主机必须是 localhost／127.0.0.1／容器主机名，或数据库名称带有 _test／_ci 后缀。仅匹配子字符串不符合条件。其他情况一律拒绝。
• 对每条推导出的命令运行 screen-cmd — 在循环开始前运行，并在恢复时对从持久化状态文件读取的每条命令运行。绝不信任持久化命令；恢复时通过 screen-state-predicate 重新筛查固定的谓词，若结果为 refuse 则拒绝执行。
• 循环过程中不得执行未经筛查的命令。 自主循环无法引入绕过 screen-cmd 的新 shell 命令。
• 固定谓词，不重新推导。 第 0 轮会将推导出的成功谓词原样写入 orchestrator-state.json；每个循环和每次恢复都会重用该精确字符串，确保不同运行中“完成”的判定可复现。
• 路由前验证账本。 validate-state 会检查 orchestrator-state.json（必需字段 + 粗略类型）；格式错误的账本不得用于路由。
• 收敛前进行独立验证。 根据工作信号集接受的高影响变更会设置 pending_verify；next-hop 会在 DONE 或交付前路由到 verify 步骤（留出集／对抗性检查）。验证步骤绝不会自动批准交付。
• 单位数未知的循环不计入平台期计数器。 如果 units 返回 unknown（例如运行器崩溃），该循环不会被计为零进展；持续返回 unknown 时会路由到 BLOCKED。