Autoresearch :probe 需求审讯引擎实战指南:8 人格对抗式约束挖掘与饱和停止机制
Autoresearch :probe 需求审讯引擎实战指南:8 人格对抗式约束挖掘与饱和停止机制
/autoresearch:probe 是 Autoresearch 技能集中面向"需求不明确"场景的入口命令:它以 8 个对抗式人格同时拷问用户与代码库,逐轮抽取原子约束,直到"净新增约束"连续多轮跌破阈值才机械性停止,最终输出可直接喂给下游命令的 Goal/Scope/Metric/Verify 配置。阅读本文后,你将掌握 probe 的全部参数、十阶段单轮循环、饱和判定算法、--evals 检查点与 handoff.json 链式交接,并能在 Claude Code、OpenCode 与 Codex 环境中把模糊目标转化为可执行的 Autoresearch 配置。
本文以 .agents/skills/autoresearch/probe.md(Codex 分发版命令文件,与 claude-plugin/commands/autoresearch/probe.md、plugins/autoresearch/skills/autoresearch/probe.md 内容一致)为核心骨架,并结合 guide/autoresearch-probe.md 长文指南、README.md 命令总览与 guide/chains-and-combinations.md 链式组合文档展开。
一、为什么需要 probe:单次提问收集不到真实需求
Autoresearch 的核心循环是"修改 → 验证 → 保留/丢弃 → 重复",但它的前提是有一个机械化的目标。而传统的一次性需求收集("你的目标是什么?")只能拿到用户当下能说出来的部分,拿不到工作真正需要的约束。含糊的意图会不断叠加——每一轮迭代都建立在一个未言明的假设之上,之后任何一次返工的成本都会成倍放大。
:probe 的解决思路是:同时拷问用户与代码库,通过 8 个对抗式人格一轮接一轮地收割原子约束,直到追加提问不再产出新约束为止(默认 15 轮)。输出物是 5 个 Autoresearch 原语(Goal、Scope、Metric、Direction、Verify),可直接喂给其他任何子命令。正如 guide/autoresearch-probe.md 所述,这正是 probe 与 plan 的分工边界:如果你已经能用一句话说清 Goal/Scope/Metric,用 plan;如果三句"但是那又怎样"之后还有追问空间,用 probe。
在 README.md 的命令速查表中,probe 的角色被概括为"8 personas interrogate requirements",默认迭代 15 轮,推荐使用场景包括"Surface hidden constraints before starting"(开工前暴露隐藏约束)、"Pre-flight a fuzzy goal then loop"(模糊目标起飞前预检,--chain plan,autoresearch)以及"Probe requirements then research improvements"(--probe --improve)。
二、参数解析:命令入口与完整参数表
probe 的 frontmatter 给出的调用骨架为:
[Topic: <text>] [Scope: <glob>] [--depth shallow|standard|deep] [--personas N] [--mode interactive|autonomous] [Iterations: N] [--evals]
命令文件开头标注 EXECUTE IMMEDIATELY,即收到调用即执行,不等待额外确认。解析逻辑按以下键提取 $ARGUMENTS:
| 参数 | 别名/形式 | 含义与取值 |
|---|---|---|
Topic: |
无 | 去除关键字后剩余文本即主题;若没有该关键字则使用完整 $ARGUMENTS |
Scope: |
--scope |
代码库接地(grounding)所用的文件 glob |
Depth: |
--depth |
轮数上限:shallow=5 轮,standard=15 轮,deep=30 轮 |
--personas N |
Personas: |
活跃人格数量,3–8,默认 6 |
--saturation-threshold N |
无 | 净新增约束阈值,低于该值的轮次计入饱和窗口,默认 2 |
--mode |
Mode: |
interactive(默认,交互式提问)或 autonomous(自主模式,从代码库自答) |
--adversarial |
无 | 将敌意人格轮换到最前 |
Iterations: |
--iterations |
轮数硬上限,默认 15;unlimited 表示无界 |
--evals / --evals-interval N |
无 | 中途评估检查点及间隔 |
--chain |
--<subcommand> |
饱和后顺序交接给下游命令 |
注意:根据 claude-plugin/commands/autoresearch/probe.md(Claude Code 分发版),交互式提问使用的工具是
AskUserQuestion;而 .agents/skills/autoresearch/probe.md(Codex 分发版)与 plugins/autoresearch/skills/autoresearch/probe.md 写的是request_user_input。这是不同宿主平台的提问工具差异,语义相同。
在 guide/autoresearch-probe.md 中还有一张更完整的旗标表,其中补充了:Iterations: N 会覆盖 --depth;--scope 缺省时默认取仓库顶层 3 个目录;--chain <targets> 缺省为 none(不链式)。
三、交互式 Setup:缺失 Topic 时的四个问题
如果调用时没有提供 Topic:,probe 会以单批次方式发起一轮提问(一次性收集,避免反复打断),包含四个问题:
- Q1 (Topic):"What to probe?"——开放式文本,描述功能、需求或设计;
- Q2 (Scope):"Which files for context?"——建议 glob,外加整个代码库;
- Q3 (Depth):"How deep?"——shallow(5 轮)、standard(15 轮)、deep(30 轮)、unlimited;
- Q4 (Mode):"How to answer persona questions?"——interactive(你来回答)或 autonomous(agent 从代码推断)。
如果四个输入都已提供,则跳过 Setup 直接进入循环。
四、8 人格体系与对抗式轮换
probe 的核心机制是 8 个固定角色,每个角色从一个独立视角拷问需求。.agents 命令文件中的定义如下:
| # | Persona | Focus(关注点) |
|---|---|---|
| 1 | Domain Expert | 业务规则、领域约束、术语 |
| 2 | End User | 可用性、期望、错误恢复 |
| 3 | Skeptic | 可能错误的假设 |
| 4 | Edge-Case Hunter | 边界条件、罕见场景 |
| 5 | Ops Engineer | 部署、监控、扩展、故障模式 |
| 6 | Security Reviewer | 攻击向量、数据保护、鉴权 |
| 7 | Contradiction Finder | 需求之间的冲突 |
| 8 | Scope Guardian | 功能蔓延、不必要的复杂度 |
当传入 --adversarial 时,将 Skeptic + Contradiction Finder + Edge-Case Hunter 三个敌意人格轮换到最前,优先发起攻击性提问。
需要说明的是,guide/autoresearch-probe.md 与 README.md 中给出了另一套人格命名(Skeptic、Edge-Case Hunter、Scope Sentinel、Ambiguity Detective、Contradiction Finder、Prior-Art Investigator、Success-Criteria Auditor、Constraint Excavator),两者是同一机制在不同文档版本中的表述变体;命令文件中的表格是权威执行定义。两版共享的对抗轮换规则一致:--adversarial 会把 Skeptic、Contradiction Finder、Edge-Case Hunter 提到最前。
五、单轮循环的完整流程:从 Seed 到 Log
probe 的循环围绕约束注册表(constraint registry)展开。命令文件将流程组织为 Phase 1(种子)+ 每轮 8 个阶段(Phase 2–8)+ 结束阶段(Phase 9),guide/autoresearch-probe.md 将其细化为"每轮 10 阶段"的流水线:
Phase 1: Seed Capture Parse topic; tokenize into seed atoms
Phase 2: Persona Activation Pick N personas (default 6 of 8)
Phase 3: Codebase Grounding Scan --scope, build prior-art ledger
Phase 4: Round Generation Each persona drafts 1–2 candidate questions
Phase 5: Question Synthesis Dedupe, drop answered, cap at ≤5/round
Phase 6: Answer Capture Single batched AskUserQuestion call
Phase 7: Constraint Extract Classify atoms (7 types)
Phase 8: Cross-Check Validate against codebase + prior rounds
Phase 9: Saturation Check Net-new < threshold for K rounds → STOP
Phase 10: Synthesize & Handoff probe-spec.md + autoresearch-config.yml + handoff.json
命令文件中的各阶段要点如下:
- Phase 1(Seed):把主题解析为初始约束集;若提供了
--scope则读取代码库上下文;初始化一个空的约束注册表。 - Phase 2(Persona Activation):每轮挑选 2–3 个人格(在全部 8 个中轮转),每个人格从自身视角生成 3–5 个拷问问题。
- Phase 3(Codebase Grounding):把问题与既有代码对照取证,为每个问题标注:相关
file:line、既有行为、差距(gaps)。 - Phase 4(Answer Capture):交互模式下通过提问工具收集回答;自主模式下从代码库上下文推断答案,并标注置信度 high/medium/low。
- Phase 5(Constraint Extraction):把回答解析为原子约束,每条约束包含:id、来源人格、描述、置信度、证据;与既有注册表去重。
- Phase 6(Cross-Check):将新约束与既有约束交叉检查冲突;交互模式把矛盾抛给用户裁决,自主模式仅记录不确定性。
- Phase 7(Saturation Check):统计本轮净新增约束;若连续 3 轮净新增 < 阈值则判定 SATURATED 并退出循环;持续追踪总约束数、本轮新增数、饱和窗口。
- Phase 8(Log):追加输出本轮记录:轮次、活跃人格、提问数、抽取约束数、净新增数。
- Eval Checkpoint:若启用
--evals,当current_round % interval == 0时运行检查点。 - Bounded Check:若设置了轮数上限且
current_round >= max_iterations,退出循环。
一个值得强调的设计细节(见 guide 的 Phase 5):每轮最终合成的问题会被去重、丢弃已解答项,并控制在每轮 ≤5 个——这保证了交互模式下一次批量提问即可完成一轮,而不是被问题淹没。
六、饱和机制:数学说了算的机械停止
probe 与其他命令最大的差异是停止条件由数据驱动:当追加提问不再产出新约束时,继续追问就是浪费。默认配置为:
saturation_threshold = 2 (默认——每轮净新增原子数)
window_K = 3 (默认——连续低于阈值的轮数)
guide 文档给出一个直观示例:
Round 1: 14 atoms
Round 2: 9 atoms
Round 5: 2 atoms — entered window
Round 6: 1 atom
Round 7: 1 atom — window=[2,1,1] — all < threshold → SATURATED
第 5 轮净新增 2 个(等于阈值,进入窗口),第 6、7 轮分别只有 1 个,连续 3 轮全部低于阈值 2,于是判定 SATURATED 并停止。
循环的退出状态有四种(加上链式交接状态):
| 状态 | 含义 |
|---|---|
SATURATED |
净新增连续 K 轮低于阈值 |
BOUNDED |
Iterations: N 用尽 |
USER_INTERRUPT |
Ctrl+C 或中途回答 "stop" |
SCOPE_LOCKED |
连续 2 轮所有原子都被判定为 out-of-scope |
(SCOPE_LOCKED 出现在 guide 文档的状态表中;命令文件的 handoff 状态枚举为 COMPLETE / SATURATED / USER_INTERRUPT / BOUNDED / ERROR。)默认 15 轮的 Iterations: 是硬上限,会覆盖 --depth 设定的轮数;Iterations: unlimited 则让循环完全交给饱和判定来结束。
七、Phase 9:合成输出与可运行配置
循环结束后,probe 进入合成阶段。命令文件规定输出目录为:
autoresearch/probe-{YYMMDD}-{HHMM}/
(guide 文档的目录命名为 probe/{YYMMDD}-{HHMM}-{slug}/,二者是同一输出在不同文档版本中的命名变体。)写入三部分内容:
constraints.md—— 完整的约束注册表,按类别组织;conflicts.md—— 未解决的矛盾(来自 Contradiction Finder);- 生成可直接运行的 autoresearch 配置 —— 从约束推导 Goal、Scope、Metric、Verify,并以代码块形式写入
summary.md。
最后打印:总轮数、找到的约束数、饱和状态、未解决冲突数。Summary 阶段还会输出净新增趋势与 top 5 最具影响力的约束。
guide 文档给出了 autoresearch-config.yml 的完整示例——这是 probe 最重要的产物,可以直接管道给下一个命令:
goal: "Add OAuth2 password-grant flow to /api/v1/auth"
scope: "src/api/auth/**, src/middleware/auth.ts, tests/auth/**"
metric: "auth_score = passing_tests * 10 + zero_secrets_in_logs * 50"
direction: "minimize"
verify: "npm test -- auth/ && npm run lint"
guard: "no new dependencies; no breaking changes to /api/v1/users"
iterations: 25
注意 guard 字段——它对应 Autoresearch 的 Guard 安全网机制("Verify = 目标是否改善,Guard = 是否破坏其他东西"),probe 从约束中把它也一并推导出来。guide 文档还展示了更完整的输出结构,包含逐轮明细:
probe/{YYMMDD}-{HHMM}-{slug}/
├── probe-spec.md Narrative requirements doc
├── constraints.tsv (round, persona, atom, type, flag, source)
├── questions-asked.tsv (round, persona, question, answer, atoms_extracted)
├── contradictions.md Inter-answer conflicts from Contradiction Finder
├── hidden-assumptions.md Atoms that quietly negate prior-art constraints
├── autoresearch-config.yml Ready-to-use Goal/Scope/Metric/Direction/Verify
├── summary.md Composite metric, termination reason, persona contribution
└── handoff.json Chain-ready (same shape as predict's handoff.json)
README.md 对 probe 输出的概括与之对应:probe/{date}-{slug}/ 下包含 probe-spec.md、constraints.tsv、autoresearch-config.yml、handoff.json。
八、Eval 检查点(--evals 旗标)
若调用时带 --evals,probe 会在循环中插入自适应检查点:
- 间隔计算:
floor(max_iterations / 3),最小为 1;无界运行(unbounded)时固定为 10。 - 每个检查点打印固定格式报告:
--- Eval Checkpoint (rounds {X}-{Y}) ---
Constraints: {total} (+{new}) | Saturation: {window_count}/3
{recommendation}
---
- 若连续 3 个检查点都判定饱和,则建议提前停止。
- 循环结束时输出完整的 evals 总结到
evals-summary.md。
这与 claude-plugin/skills/autoresearch/SKILL.md 中"所有循环命令的通用旗标"一致:--evals 对所有循环型命令生效,提供中途检查点与最终总结,--evals-interval N 可覆盖检查点频率。在 Autoresearch 的命令体系中,evals 还能独立作为 /autoresearch:evals 命令读取任何 *-results.tsv 做趋势与高原分析。
九、Chain Handoff:与下游命令的交接协议
probe 是 Autoresearch 链条的前置引擎——它不直接改代码,而是产出配置后把接力棒交给下游。命令文件规定,饱和/结束时写入 handoff.json:
version: "2.1.0"source: "probe"timestamp: 时间戳status: COMPLETE | SATURATED | USER_INTERRUPT | BOUNDED | ERRORfindings: 抽取的约束config: 推导出的 autoresearch 配置
随后按 --chain 指定的顺序调用下一个目标,并把 --evals 旗标透传给下游。guide/chains-and-combinations.md 说明了交接协议的价值:"每个命令的输出通过 handoff.json 喂给下一个——零复制粘贴、零上下文丢失",下游命令读取该文件完成初始化,绝不从零重建上下文。
常用链式组合(来自 guide 与 guide/chains-and-combinations.md):
| 链 | 使用时机 |
|---|---|
probe → plan → loop |
需求模糊时启动指标优化 |
probe → scenario,debug,fix |
未知需求 + 未知边界 + 未知 bug |
probe → improve(或 --improve 快捷旗标) |
需求模糊且需要产品方向(improve 是终端发射器,PRD 交给外部工具) |
probe → predict |
约束采集后进入多专家预测 |
probe → plan,autoresearch |
模糊目标预检后直接进入迭代循环 |
其中 --<subcommand> 是 --chain <subcommand> 的快捷写法,因此 --improve 等价于 --chain improve。
十、实战用法示例
以下用法全部取自 guide/autoresearch-probe.md 与 README.md,可直接照抄运行:
# 无界——一直探测到饱和
/autoresearch:probe
# 有界——恰好 10 轮
/autoresearch:probe
Iterations: 10
# 内联主题 + 旗标
/autoresearch:probe --depth deep --personas 8 --adversarial
Topic: Migrate session storage from Redis to Postgres
# 代码库接地(推荐用于继承代码)
/autoresearch:probe --scope src/auth/**
Topic: Tighten OAuth2 token validation
# 自主模式(无用户提示)
/autoresearch:probe --mode autonomous --scope src/checkout/**
Topic: Identify race conditions in checkout flow
# 链式——probe 合成配置后直接跑 autoresearch 循环
/autoresearch:probe --chain plan
Topic: Add rate limiting to /api/v1/*
经典的 probe → plan → loop 完整链路(来自 chains 指南):
/autoresearch:probe
Topic: Reduce p95 latency on /search to under 50ms
# 约 12 轮后饱和,产出 autoresearch-config.yml
/autoresearch:plan
Goal: (from probe output)
/autoresearch
Iterations: 25
Goal: Reduce p95 search latency below 50ms
Scope: src/search/**/*.ts
Metric: p95 latency in ms (lower is better)
Verify: npm run bench:search | grep "p95"
Guard: npm test
README.md 还给出了两个面向具体场景的推荐:/autoresearch:probe --chain plan,autoresearch(模糊目标预检后循环)与 /autoresearch:probe --improve(约束采集后接产品改进研究)。注意在 OpenCode 中命令使用下划线命名(/autoresearch_probe),在 Codex 中通过 $autoresearch probe mention 语法调用——三种宿主平台的安装方式见 README.md 的 Quick Start 与 guide/getting-started.md。
十一、两种运行模式:交互式与自主式
Interactive(默认):每轮 probe 把最多 5 个问题合并为单次批量调用,你每轮只回答一次。这是"人在环上"的需求澄清最佳形态——人类回答语义,agent 负责追问结构。
Autonomous(--mode autonomous):从代码库 + 人格推理自我作答,每条原子标记 confidence: low|med|high。guide 文档列出三种典型用途:
- 继承代码库:在问人之前先从代码推导意图;
- CI/CD 门禁:用旧规格探测当前代码,发现矛盾即失败;
- 引导启动(Bootstrapping):自动生成一份待审阅的起始配置。
十二、probe vs plan:何时用哪个
两者都产出 5 个 Autoresearch 原语,但机制完全不同(对照表来自 guide/autoresearch-probe.md):
| 维度 | /autoresearch:plan |
/autoresearch:probe |
|---|---|---|
| 轮数 | 1 | 直到饱和(典型 8–12 轮) |
| 人格数 | 1 | 6–8 个对抗式人格 |
| 代码库接地 | 可选 | 强制(Phase 3) |
| 输出 | 5 个原语 | 5 个原语 + constraints.tsv + contradictions + hidden-assumptions |
| 最佳场景 | 意图清晰 | 意图模糊或对抗式预检(pre-mortem) |
判断法则:如果 Goal/Scope/Metric 一句话各能说清,用 plan;如果大概率会出现三轮"是,但是那又怎样"的追问,用 probe。
十三、反模式:什么会让 probe 失效
guide 文档专门列出四类反模式及其失败原因:
| 反模式 | 为何失败 |
|---|---|
| 含糊的问题("这完整吗?") | 产不出任何原子——每个问题都必须要求一个原子约束 |
| 人格漂移 | Skeptic 必须保持怀疑,不能变成 planner |
| 接受"听起来没问题" | 含糊的回答重新排队,绝不被抽取为约束 |
| 跳过代码库接地 | 没有 Phase 3,问题会重复代码中已做出的决策 |
一句话总结:probe 的价值密度取决于问题的原子性与代码库取证,而非提问数量本身。
十四、在 Autoresearch 命令体系中的定位
probe 是 Autoresearch 14 个命令中唯一以"需求挖掘"为单一职责的命令。在 claude-plugin/skills/autoresearch/SKILL.md 的子命令表中,它被定位为"8 personas interrogate requirements until saturation",默认 15 轮;在 README.md 的命令架构图中,它与 plan 同属"开工前"阶段,衔接 scenario(边界枚举)、predict(专家预测)等分析类命令,最终把约束转化为可迭代的机械指标。它不修改代码、不部署、不发布——所有写操作都发生在 autoresearch/probe-{YYMMDD}-{HHMM}/ 输出目录内,遵守整个技能的安全不变量(有界默认、结果落盘、handoff.json 交接)。
如果你面对的是一个"说不清但必须做对"的需求,probe 就是 Autoresearch 链条上最值得先跑的那一个环节:让 8 个人格替你穷尽追问,让饱和机制替你决定何时该停,然后把一份有证据、有冲突记录、有可运行指标的配置交到下游手里。