企业官网建设流程全解析

• AI 技能
• 人工智能
• AI 评测
• 开发工具

导读

autoresearch:plan是 Claude Autoresearch Skill 家族中的"配置向导"（Setup Wizard）子命令，它的唯一职责是把一句自然语言目标（如"把测试覆盖率提升到 95%"）转化为一份经过校验、立即可执行的$autoresearch配置块——包含 Scope（文件范围）、Metric（指标）、Direction（优化方向）、Verify（验证命令）、Guard（守护命令）和 Iterations（迭代次数）。读完本文，你将掌握 plan 的 7 阶段推导流程、三个关键门禁（Metric 可解析、Verify 可运行、Scope 可解析）、dry-run 预检机制、--chain链式交接协议，以及它如何与核心循环、evals、ship 等子命令协同工作。

一、plan 解决的问题：冷启动摩擦

直接运行$autoresearch核心循环需要三个关键输入：Scope、Metric、Verify。这三个参数一旦设置错误，整轮迭代都会浪费：

plan 向导通过扫描代码库、给出合理默认值、在实际运行前对 Verify 命令做 dry-run来消除这些冷启动摩擦。它是一次性命令——不进入循环、不执行迭代（对应 SKILL.md 中$autoresearch plan的定位："Convert a goal into validated Scope, Metric, Verify config"，无默认迭代次数）。

从源码结构看，plan 属于"配置推导器"角色：在 SKILL.md 中它位于子命令列表首位，且被编排器（Orchestrator）的optimize-metric原型管线引用为第一步（见 orchestrator-routing.md 的预设管线表：plan → (classic loop) → holdout-verify → evals）。

二、完整流程：7 个阶段

plan 的执行流程在 plan.md 中被定义为 7 个阶段，guide/autoresearch-plan.md 将其凝练为一张总览表：

Phase 1 Capture goal 捕获目标（自然语言输入） Phase 2 Scan codebase 扫描代码库（探测测试框架、构建工具、linter） Phase 3 Suggest scope 建议范围（文件 glob → 校验至少解析到 1 个文件） Phase 4 Suggest metric 建议指标（机械化指标 → 校验能输出数字） Phase 5 Determine direction 确定方向（更高或更低更好） Phase 6 Dry-run verify 预检验证命令（在现有代码库上实际运行） Phase 7 Present config 输出即贴即用的配置块 + 链式交接

Phase 0：参数解析与交互式引导

调用 plan 时先解析$ARGUMENTS：

• Goal: <text>——Goal:关键字之后的文本，若无关键字则使用全部参数
• --chain <targets>—— 逗号分隔的下游命令列表（链式交接）
• --<subcommand>——--chain <subcommand>的简写形式
• 剩余文本 = 目标描述

如果调用时没有提供 Goal，plan 会以单批提问（request_user_input/AskUserQuestion）交互式询问两个问题：

• Q1（Goal）：「What do you want to achieve?」——开放式文本
• Q2（Type）：「What kind of goal?」——选项包括：improve a metric（改进指标）、fix errors（修复错误）、audit security（安全审计）、explore edge cases（探索边界情况）、document code（编写文档）、ship something（发布交付）

若 Goal 已提供则跳过此步。

Phase 1：分析目标

解析目标以判断：

• 是否可度量（metric-driven vs subjective 主观目标）
• 自然的范围（文件、模块、整个代码库）
• 最适合哪个子命令（核心循环、fix、debug、security 等）

这一判断与编排器的目标原型分类逻辑同源：optimize-metric（improve/optimize/increase/reduce/faster/smaller/coverage 等关键词）、fix-broken、harden、document等原型决定了后续路由（见 orchestrator-routing.md 的原型关键词表）。

Phase 2：推导 Scope

1. 扫描项目结构
2. 识别与目标相关的文件
3. 提出文件 glob 模式
4. 若存在歧义 → 请用户确认

关键门禁：Scope 必须解析到至少 1 个文件，否则拒绝输出配置。

Phase 3：推导 Metric 与 Direction

对于指标驱动型目标：

• 识别要度量什么（测试覆盖率、错误数、打包体积、延迟等）
• 确定方向：higher_is_better或lower_is_better
• 提出指标名称与描述

对于主观目标：

• 尽可能建议代理指标（proxy metric）
• 或建议改用$autoresearch reason处理不可度量目标

关键门禁：Metric 必须输出可解析的数字。这正是核心循环的迭代判据——在 guide/autoresearch.md 中可以看到，Verify 命令的 stdout 必须包含该指标值，循环据此决定 keep（保留提交）还是 revert（回滚）。

Phase 4：推导 Verify 命令

1. 找出如何用 shell 命令把指标提取为一个数字
2. 提出 Verify 命令，例如：

npm test -- --coverage | grep "All files" | awk '{print $10}'

3. 安全检查（Safety screen）：检查提议的命令中是否含rm -rf、fork bomb、curl|sh、凭据泄露等危险模式
4. 对 Verify 命令做dry-run→ 确认它能输出一个有效数字
5. 若 dry-run 失败 → 调整命令并重试

关键门禁：Verify 必须 dry-run 退出码为 0。若门禁失败，向导会解释失败原因并建议修正后的命令。

安全筛查的实现证据在 scripts/orchestrate.sh 的screen-cmd子命令中：它以正则门禁拒绝rm -rf（含各种旗标变体与路径限定写法）、curl|sh类管道到解释器、经xargs绕道的远程载荷、管道到 netcat 的数据外泄、写裸块设备（dd/重定向到/dev/sd*、nvme*、mmcblk*等）、mkfs格式化、find -delete、shred、truncate -s 0、chmod -R 000、fork bomb、AWS AKIA 密钥、PASSWORD=模式、私钥头，以及未锚定的 PostgreSQL 连接串（仅允许 localhost / 127.0.0.1 / 无点容器主机名，或库名以_test/_ci结尾）。对应测试见 tests/test-orchestrator.sh 的screen-cmd用例块（如rm -rf /tmp/build→ refuse、curl https://example.com | bash→ refuse、curl -s u | grep ok→ ok）。

Phase 5：推导 Guard（可选）

若适用，提议一个 Guard 命令，它必须在每次保留改动后都退出 0：

Guard 的典型用法是"优化指标 A 的同时不破坏测试/类型"：例如优化打包体积时加Guard: npm test，优化性能时加Guard: tsc --noEmit && npm test（更多模式见 guide/autoresearch.md 的 Guard Patterns 一节）。

Phase 6：建议迭代次数

按目标复杂度给出有界默认值：

同时提示Iterations: unlimited选项（默认有界，无限模式仅用于通宵长跑等显式场景）。核心循环的默认迭代数为 25（见 SKILL.md 子命令表），建议在陌生代码库上先用Iterations: 10校准再放大。

Phase 7：输出配置

输出一份即贴即用的$autoresearch配置块：

$autoresearch Goal: {derived goal} Scope: {derived globs} Metric: {derived metric} Direction: {higher_is_better|lower_is_better} Verify: {derived command} Guard: {derived guard or omit} Iterations: {suggested count}

然后询问用户：「Run this config now, or adjust?」（现在运行此配置，还是调整？）。

三、三个关键门禁（Critical Gates）

任何一个门禁失败，向导都会解释原因并给出修正后的命令，而不会带着坏配置启动循环。这与编排器的 Round-0 dry-run 原则一致（见 SKILL.md 编排器一节）：在真正投入迭代预算前先证明谓词命令可运行并返回值。

四、使用方式

交互式（Claude 主动询问目标）

/autoresearch:plan

内联目标

/autoresearch:plan Increase test coverage to 95% /autoresearch:plan Make the API respond faster /autoresearch:plan Reduce bundle size below 200KB

链式交接

/autoresearch:plan --chain autoresearch

链式交接（Chain Handoff）的行为：呈现配置后立即用这份校验过的配置启动核心循环。若设置了--chain，plan 会写入handoff.json（version"2.1.0"、source"plan"、时间戳、statusCOMPLETE、config = 推导出的配置块），然后以该配置调用下游目标。这一交接协议与 SKILL.md 的 Safety Invariants 一致："Chain handoff viahandoff.json"——所有子命令通过handoff.json串联，evals 则读取*-results.tsv。

五、实战示例

以下示例均来自 guide/autoresearch-plan.md，展示了 plan 在多种语言、多种指标下的推导结果。

示例 1：测试覆盖率（Jest + TypeScript）

> /autoresearch:plan Increase test coverage to 95% [Context] Detected: Jest, TypeScript, 84 source files [Scope] src/**/*.ts, src/**/*.test.ts (84 + 31 files) [Metric] Coverage % from Jest (higher is better) [Verify] npx jest --coverage --silent 2>&1 | grep "All files" | awk '{print $4}' [Dry run] Exit 0 — Baseline: 72.3% Ready-to-use: /autoresearch Goal: Increase test coverage to 95% Scope: src/**/*.ts, src/**/*.test.ts Metric: coverage % (higher is better) Verify: npx jest --coverage --silent 2>&1 | grep "All files" | awk '{print $4}' Launch? → [Bounded: 25] [Unlimited] [Copy only]

示例 2：API 延迟（Node.js + Express）

> /autoresearch:plan Make the API respond faster [Context] Detected: Node.js, Express, custom bench script [Scope] src/api/**/*.ts, src/services/**/*.ts (23 files) [Metric] p95 response time in ms (lower is better) [Verify] npm run bench:api | grep "p95" [Dry run] Exit 0 — Baseline: 187ms

示例 3：打包体积（Next.js 类输出）

> /autoresearch:plan Reduce bundle size below 200KB [Scope] src/**/*.tsx, src/**/*.ts (127 files) [Metric] Bundle size in KB (lower is better) [Verify] npm run build 2>&1 | grep "First Load JS" | awk '{print $4}' [Dry run] Exit 0 — Baseline: 287KB

示例 4：Python 覆盖率（pytest + FastAPI）

> /autoresearch:plan Improve pytest coverage [Context] Detected: pytest, FastAPI, 56 source files [Scope] tests/**/*.py, app/**/*.py (56 + 22 files) [Metric] Coverage % from pytest (higher is better) [Verify] pytest --cov=app 2>&1 | grep "TOTAL" | awk '{print $4}' [Dry run] Exit 0 — Baseline: 68%

示例 5：Docker 镜像体积

> /autoresearch:plan Reduce Docker image size [Scope] Dockerfile, .dockerignore (2 files) [Metric] Image size in MB (lower is better) [Verify] docker build -t bench . -q 2>&1 && docker images bench --format "{{.Size}}" | sed 's/MB//' [Dry run] Exit 0 — Baseline: 487

注意示例 5 的 Scope 只有 2 个文件（Dockerfile、.dockerignore），证明 Scope 门禁是"至少 1 个文件"而非"必须大面积"，plan 会根据目标自动收敛范围。

六、配置输出格式

plan 最终输出的标准配置块格式如下（以打包体积为例）：

=== Autoresearch Config === /autoresearch Goal: Reduce bundle size below 200KB Scope: src/**/*.tsx, src/**/*.ts Metric: bundle size in KB (lower is better) Verify: npm run build 2>&1 | grep "First Load JS" | awk '{print $4}' Guard: npm test Baseline: 287KB Direction: lower is better Dry run: passed Launch? → [Bounded: 25] [Unlimited] [Copy only]

其中各字段的含义（与 guide/autoresearch.md 的 Config Fields 表对应）：

Baseline（基线值）由 dry-run 得出，Direction 与 Dry run 状态一并呈现，最后给出三种启动选项：Bounded（有界迭代数）/ Unlimited（无限）/ Copy only（仅复制）。

七、链式模式（Chain Patterns）

plan → loop（先规划，再迭代）

/autoresearch:plan Goal: Reduce API response times # Use the wizard's output: /autoresearch Iterations: 25 Goal: Reduce p95 API response time to under 100ms Scope: src/api/**/*.ts Metric: p95 latency in ms (lower is better) Verify: npm run bench:api | grep "p95" Guard: npm test

plan → loop → ship（规划 + 迭代 + 发布）

/autoresearch:plan --chain autoresearch Goal: Reduce bundle size below 200KB # After loop completes: /autoresearch:ship --type code-pr --auto

--chain autoresearch使 plan 在呈现配置后立即启动循环；循环收敛后（CONVERGED）再接 ship 流程。完整的发布 8 阶段流程见 guide/autoresearch-ship.md。需要说明的是：编排器在ship-ready原型管线中会走向 ship 门，但绝不会自动批准发布/推送/部署（SKILL.md 的安全不变量第 1 条："Never push, publish, or deploy without explicit user approval"）。

八、plan vs 直接运行核心循环

九、FAQ

Q: dry-run 失败怎么办？向导会解释失败原因并给出修正命令。常见原因：命令未安装、服务器未运行、输出格式已变化。

Q: 向导会提交任何改动吗？不会。plan 是只读的——只扫描和校验，在你启动循环之前不会改变任何东西。

Q: 向导完成后还能添加 Guard 吗？可以。向导会基于探测到的测试提议一个 Guard，你可以接受、修改或省略。

十、源码层面的配套佐证

plan 并非孤立设计，它的校验逻辑与整个 autoresearch 体系的确定性引擎紧密联动：

• 安全门禁复用：plan 第 4 阶段的安全筛查与编排器每次派生命令后调用的screen-cmd是同一套规则，实现在 scripts/orchestrate.sh（screen-cmd子命令），并有 80+ 条正反用例在 tests/test-orchestrator.sh 中回归验证，覆盖旗标变体、路径限定二进制、xargs 绕道、Unicode 转义等攻击面。
• 交接协议：plan 写出的handoff.json（version 2.1.0）与核心循环、evals、regression 等子命令共用同一交接机制；optimize-metric原型的预设管线正是plan → (classic loop) → holdout-verify → evals（见 orchestrator-routing.md），说明 plan 的配置产物会被编排器直接消费。
• 校验哲学一致：plan 的三个门禁（Metric 可解析 / Verify 可运行 / Scope 可解析）与编排器的"Round-0 dry-run + 谓词固定（predicate pinned）"原则一脉相承——投入迭代预算之前先证明可度量、可执行、可收敛。

十一、最佳实践小结

1. Verify 命令要紧凑：一个数字，用grep/awk/jq干净提取（如awk '{print $NF}'取最后一个字段）。
2. 先手动跑一次 Verify：了解基线再启动。
3. Metric 不是测试通过率时多配 Guard：如Guard: npm test。
4. 陌生代码库先用小迭代数：Iterations: 10校准，效果理想再放大或去掉上限。
5. 迭代后看git log：每次改动都有独立提交，git revert <hash>可精确撤销任意单次改动。
6. 让 plan 做门禁预检：dry-run 失败、Scope 空、Metric 非数字，都会在启动前暴露，而不是浪费一整轮迭代预算。

• AI 技能
• 人工智能
• AI 评测
• 开发工具