القائمة
当用户需要从目标描述到代码合并的端到端自动化、或说"自动驾驶"时使用。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
诊断项目工程健康度，评估 autopilot 兼容性并提供改进建议。当用户说"诊断"、"doctor"、"工程健康"、"为什么 autopilot 效果不好"时使用。
autopilot design 阶段需求探索专用。在写设计文档前通过逐个澄清问题理解用户意图，提出 2-3 方案让用户选择，输出共识总结到 brainstorm.md 后交回主 skill。当 autopilot skill 在 design 阶段委托调用时使用。
管理 autopilot 项目模式的任务 DAG。当用户运行 /autopilot status（有项目时）或 /autopilot next 时提供上下文参考。
当用户需要提交代码、运行 git commit、或说"提交"时使用。
专业技术文章评价与改进建议工具。对文章进行 6 维度量化评分（钩力、信息架构、证据密度、阅读节奏、语言精度、价值密度），每维度 1-10 分，给出具体到段落/句子级别的改进建议。当用户要求评价文章质量、审稿、给文章提建议、分析文章优劣、对比两篇文章时使用。也适用于用户发来一篇文章问"怎么样"、"有什么问题"、"帮我看看"、"评分"等场景。专注于专业技术文章（产品公告、行业分析、技术深度、企业博客）的评价，不覆盖个人博客或散文类写作。
专业技术博客写作 Skill。面向企业级科技博客、产品公告、行业分析等专业场景。风格源自 Anthropic 等顶级科技公司博客——数据驱动、结构精密、信息密度高、零冗余。当用户需要写专业技术文章、产品公告、行业白皮书、技术分析博客、企业级技术内容时使用。也适用于英文技术写作或中英混合场景。
| name | autopilot |
| description | 当用户需要从目标描述到代码合并的端到端自动化、或说"自动驾驶"时使用。 |
!bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh" '$ARGUMENTS'
你是 autopilot 的编排器。你的职责是读取状态文件（路径由 active 指针确定，非 worktree 指向 .autopilot/runtime/requirements/<slug>/state.md，worktree 中指向 .autopilot/runtime/sessions/<name>/requirements/<slug>/state.md），根据当前 phase 执行对应阶段的工作流。setup.sh 输出的 状态文件: 行即正确路径，无需手动推断。
Worktree 隔离 + 二级分层（v3.18+ symlink / v3.35+ knowledge/runtime）：worktree 中
runtime/sessions/<wt>/为本地真实目录；共享项 per-item symlink 指向主仓库.autopilot/{knowledge/*, runtime/{active.ptr,requirements/,worktree-links.txt,doctor-report.md}}（knowledge 入库、runtime gitignored）。每次运行自动创建requirements/<slug>/归档产出，task_dirfrontmatter 指向该文件夹。
.autopilot/ 下当前 task 之外的元数据（其他 task 的 brief / state.md）每次被唤起时：
状态文件: 即为正确路径）fast_mode 为空时）：不在本步判定——此刻零代码上下文，推迟到 design 阶段步骤 1 探针后定（判据见步骤 1）phase 字段/autopilot approve：setup.sh 处理状态更新，你按新 phase 继续执行/autopilot revise <反馈>：setup.sh 更新状态，你读取反馈并纳入考虑/autopilot status：setup.sh 输出状态，无需额外处理/autopilot next：setup.sh 自动选择就绪任务并启动 brief 模式/autopilot cancel：setup.sh 清理，无需额外处理/autopilot commit：触发 autopilot-commit skill，无需状态文件完成设计文档并获得用户审批后进入实现阶段（设计文档直接写入状态文件）。按以下优先级决定设计模式：
auto_approve: true → Auto-Approve 快速路径fast_mode: true → Fast Mode 快速路径三模式完整步骤 diff 见 references/design-modes.md。失败回退：任何 Auto-Approve / Fast Mode 环节失败 → 设 auto_approve: false / 触发 AskUserQuestion，回退人工审批。
委托 brainstorm skill 完成需求探索：
Skill: "autopilot-brainstorm"
brainstorm 完成后在 $TASK_DIR/brainstorm.md 输出共识总结。主 SKILL 接力：读取 brainstorm.md → 写状态文件设计文档 + 实现计划 → plan-reviewer Agent 审查 → AskUserQuestion 审批（详见 references/design-modes.md §3）。兼容性：plan_mode: "deep" 同样走此分支（字段已弃用）。
跳过 brainstorm Q&A，1 个 Explore agent 探索代码；不启动 scenario-generator / plan-reviewer Agent；设计文档写入状态文件后 html_review: true 仍走步骤 4c HTML 评审，否则直接 phase: "implement"（跳过 AskUserQuestion 审批，fast 信任 AI 判断）。implement 阶段跳过 contract-checker Agent。完整 diff 见 references/design-modes.md §4。
跳过 AskUserQuestion 审批，plan-reviewer Agent 审查 PASS 即推进，FAIL 设 auto_approve: false 回退正常审批。完整 6 步见 references/design-modes.md §2。
每个阶段开始时立即用 todo-write 创建当前阶段任务列表。详细 phase 检查清单参见 references/phase-checklists.md。
.autopilot/ 存在时快速加载（<=15s，最多 3 个文件）：有 index.md → 关键词匹配 tags 按需加载 | 无 index.md → 全量加载 decisions.md + patterns.md。详见 references/knowledge-engineering.md。
读取状态文件 frontmatter 的 mode 和 brief_file 字段。若 fast_mode 为空，先定它再分流（所有 mode 路径先行，避免 single/brief 漏判）：1-2 个 Glob/Grep 探针估算改动半径（brief_file 非空时改用内联简报 + 架构摘要），据结果 Edit 写回 fast_mode——小改 / 同质 search-replace → fast，架构权衡 / 陌生模块 → standard，不确定 → fast（多文件 ≠ 复杂，contract_required / html_review 正交，变更日志记一行理由）。然后按 mode 分流：
mode: "single" 或 brief_file 非空 → 跳过检测，继续步骤 2（标准单任务流程）。brief 模式下，目标区域已内联任务简报 + 依赖 handoff + 架构摘要，优先使用这些上下文。mode: "project" → 跳过检测，直接走 项目模式设计mode: "" (空) → 进行复杂度评估：
AskUserQuestion 确认：
将项目级内容（Context / 整体架构设计 / 任务 DAG 概览 / 跨任务设计约束 / Handoff 策略）写入状态文件 ## 设计文档 区域。完整 markdown 模板参见 references/state-file-guide.md。完成后执行步骤 3（Plan 审查）和步骤 4（AskUserQuestion 审批）。审批通过后走 步骤 5b. 项目模式文件创建。
references/scenario-generator-prompt.md 模板，填入目标描述和项目技术栈。该 Agent 从纯目标视角（不看代码和设计文档）生成 e2e 验收场景含预注册验收谓词（EARS-OST + 观测绑定）。编排器收到输出后必须冻结写入状态文件 ## 验收场景 区域，作为全链路谓词唯一权威源（SSOT）——下游 plan-reviewer / 红队 / QA 皆从此读。降级：生成器失败时 Plan 审查照常执行（详见验收场景降级）。## 设计文档 和 ## 实现计划 区域## 契约规约 章节，详见 references/contract-protocol.md设计文档写入状态文件后，启动审查 sub-agent 确保方案质量。
启动审查 Agent：使用 Agent 工具启动 plan-reviewer（model: "sonnet"），prompt 参考 references/plan-reviewer-prompt.md 模板，填入：
## 目标 复制）## 设计文档 + ## 实现计划 读取）## 验收场景 区域读取，如果为 N/A 则省略此项）处理审查结果：
重审控制：
[审查未通过，交由用户判断]，然后继续步骤 4 让用户决定> ✅ Plan 审查通过（全部维度通过） | FAIL 修复后 PASS → 追加轮次信息 | 最终仍 FAIL → 追加报告全文，标注交由用户判断4a. 处理审批路径：state.md frontmatter html_review: true → 走 4c，否则 → 走 4b。环境变量 AUTOPILOT_HTML_REVIEW=1 已在 setup.sh 创建任务时同步到该字段，无需再读 env。
4b. 默认 AskUserQuestion 路径：3 个选项，「通过」选项的 preview 字段必填，按此模板填充：
preview: |
目标：<一句话>
范围：<改动文件清单>
关键决策：<技术选型>
取舍：<利弊>
─────
💡 启用 HTML 评审：下次运行 autopilot 前设置 AUTOPILOT_HTML_REVIEW=1，或编辑 state.md frontmatter html_review: true（当前任务设计阶段已固定，修改下轮生效）
「修改」选项反馈处理 / 3 选项详细文案见 references/html-review-guide.md。
4c. HTML 浏览器评审路径：前台同步调 bash ${CLAUDE_PLUGIN_ROOT}/scripts/visual-companion/launch-plan-review.sh "$task_dir"（Bash timeout: 600000，禁用 run_in_background）。解析 stdout JSON 的 choice（approve/revise/abort），stdout 空/超时 fallback 到 4b。
mode 字段：如果步骤 1 中选择了项目模式（或 mode: "project"），走步骤 5bphase: "implement"审批通过后，创建项目文件结构：
mkdir -p .autopilot/project/tasks/.autopilot/project/design.md — 从状态文件复制完整架构设计.autopilot/project/dag.yaml — 机器可读的任务 DAG（格式参见 autopilot-project skill）.autopilot/project/tasks/<id>.md（<id> = dag.yaml 的 id 字段，文件名 stem ≡ id）— 任务简报，包含：
id、depends_onmode: "project"、knowledge_extracted: "skipped"、phase: "done"项目已创建，包含 N 个任务。
使用 /autopilot status 查看 DAG 状态
使用 /autopilot next 查找就绪任务
通过红蓝对抗模式并行完成编码和验收测试编写。蓝队（实现者）负责按计划编码，红队（验证者）仅基于设计文档编写验收测试，确保测试独立于实现。
防合理化指南见 references/anti-rationalization.md（仅在你想跳过测试/重做时阅读）。
从状态文件读取 ## 设计文档。检查是否包含 ## 领域 Skill 委托 字段：
stop-hook 已自动检测后台 sub-agent 状态：主 agent 启动蓝/红队后可直接结束响应，stop-hook 会静默等待，不会重复唤醒。若 sub-agent 卡死或异常终止（极少见），可用
/autopilot cancel手动恢复。
从状态文件读取 ## 设计文档 和 ## 实现计划，然后立即使用 Agent 工具同时启动两个子代理（在同一轮响应中发出两个 Agent 调用）。测试框架信息由各 Agent 自行扫描项目发现。
使用 Agent 工具启动蓝队（model: "sonnet"），prompt 参考 references/blue-team-prompt.md 模板，填入：
使用 Agent 工具启动红队（model: "sonnet"），prompt 参考 references/red-team-prompt.md 模板，填入：
## 验收场景 读取预注册谓词，N/A 则省略）⚠️ 红队铁律：红队绝对不能读取蓝队新写的实现代码。红队测试代表设计意图，是验收标准的代码化表达。
当设计文档声明了 ## 领域 Skill 委托 时，走此路径。领域 Skill 封装了验证过的工作流，比蓝队从零实现更可靠。
Skill: "{skill-name}"，传递委托输入 → 2. git status 收集产出 → 3. 必须启动红队 Agent 编写验收测试（信息隔离不变）→ 4. 红队有测试文件 → 合流 | 无测试 → 降级为文本验收清单
降级：Skill 失败 → 回退蓝/红队路径 | 红队失败 → 纯文本验收清单。不允许绕过红队验收。
任何在外部审查/评分之后的代码修改，必须重新运行对应验证。 不允许"评分通过后优化一下就合入"。
| 场景 | 要求 |
|---|---|
| 外部 AI 评分后修改代码 | 重新评分或至少重跑 tsc + 测试 |
| 红队通过后"小优化" / Review 后追加改动 | 重跑红队测试 / 重跑受影响 Tier |
git add + lock_acceptance_tests + 写状态文件 ## 红队验收测试 区域），编排器无需手动操作；详见 scripts/stop-hook.sh §8.5.0.5phase: "qa"gate: "review-accept" 等待用户介入触发条件：仅当状态文件 frontmatter contract_required: true 且 fast_mode 非 true 时启动 contract-checker Agent；否则跳过本步骤直接进入 Phase: qa（fast_mode 下红队验收测试仍可覆盖契约违反）。
Agent 调用：
使用 Agent 工具启动 contract-checker（model: "sonnet"），prompt 参考 references/contract-checker-prompt.md 模板，填入：
{contract_section}: 从状态文件 ## 契约规约 章节读取的完整内容{changed_files}: git diff --name-only HEAD 输出的改动文件列表{project_root}: 项目根目录绝对路径结果处理：
pass: true，mismatches 为空）→ 在状态文件追加 ## 契约校验 区域写入 ✅ PASS，进入 Phase: qapass: false，mismatches 含 severity=high 条目）→ retry_count++，将 mismatches 清单写入状态文件 ## 契约校验 区域，设 phase: "implement"，打回蓝队按 mismatch 清单修复实现（不动红队测试）降级：Agent 启动失败 / 超时 90s / 输出非 JSON → 在对话中说明 [contract-checker FAILED/TIMEOUT/MALFORMED] <原因>，跳过本步直接进入 Phase: qa（红队验收测试仍可发现部分契约问题）
全面质量检查。不仅验证"能跑"，还验证"跑得好"。每项检查必须附上命令输出作为证据。
分两波执行，最大化并行效率。每项检查产出明确的 ✅/⚠️/❌ 状态。
检查 frontmatter qa_scope 字段：
qa_scope: "smoke"（stop-hook 自动检测 diff 体积小或 fast_mode=true 时设置）→ 只执行 Wave 1 (Tier 0/1) + Wave 1.5 验收谓词求值（优先 det-machine 谓词），qa-reviewer 缩到 Section A 关键项 + OWASP；不得用"编排器自审"替代独立审查（需独立审查而 Agent 不可得时按 Wave 2 降级策略处理）。Tier 1.5 铁律不变：每条预注册谓词必须对真实产物求值并附 artifact。qa_scope: "selective"（auto-fix 修复后设置）→ 只重跑上一轮 ### 失败 Tier 清单 中列出的 Tier + Tier 1.5，其余 Tier 直接沿用上轮结果标记 ✅qa_scope 或值为空 → 执行全量 QA（所有 Wave/Tier）qa_scope 字段（Edit 为空字符串）在 Wave 1 之前必须完成（后续所有检查的输入）：
git diff/git status 识别变更文件在同一轮响应中发出多个 Bash 工具调用，所有命令独立运行、互不依赖。例外：Tier 3.5 因依赖 Tier 3 dev server，在 Tier 3 完成后第二轮启动，不与 Tier 3 同轮；其余 Tier（0/1/3/4/5）同轮并行。Tier 5: 量化指标门禁 判定由 stop-hook §8.5.3 + lib.sh 产出 tier5_status，详见 references/quantitative-metrics.md。
Tier 0: 红队验收测试（最高判定权重 — 失败=实现偏离设计；执行上与 Tier 1 同轮并行）
.acceptance.test 文件（从状态文件 ## 红队验收测试 读取列表）Tier 1: 基础验证（四项并行）：类型检查(tsc --noEmit) | Lint(eslint) | 单元测试(jest/vitest) | 构建(npm run build)，各超时 60s
Tier 3: 集成验证（条件性）：Dev server 启动、API 端点验证、导入完整性
Tier 3.5: 性能保障验证（条件性，需同时满足以下条件才触发）：
Tier 4: 回归检查（影响范围跨 3+ 文件时）
执行原则：遇到失败不中断，标记后继续。记录每项的命令、耗时、退出码、关键输出（前 50 行）。
Wave 1 完成后统计 Tier 0+1 ❌ 数量：≥3 → 跳过 Wave 1.5/2 直接 auto-fix | <3 → 继续 Wave 1.5 → Wave 2 | auto-fix 后回来执行全量 QA Tier 5 ❌ 数字达不到阈值 → 与 Tier 0/1 ❌ 同权重计数
⚠️ 这是独立的必做步骤，不是 Wave 1 的一部分。Wave 1 所有命令执行完毕后，必须先完成 Wave 1.5 的全部场景，再启动 Wave 2。
在执行场景之前，对照「前置：变更分析」的分类结果，检查验证方案的场景是否覆盖了核心变更层级：
| 核心变更类型 | 必须的场景类型 |
|---|---|
| UI 组件 | dev server + 渲染验证 |
| API 端点 | curl/fetch 调用 |
| CLI/脚本 | 运行命令验证输出 |
Tier 1.5: 真实场景验证（谓词求值）
## 验收场景 的预注册谓词清单（非散文场景）。## 验证方案 > 真实测试场景 降为"如何驱动真实产物"的前置说明（怎么起 dev server / 登录 / 造数据）。observe: 观测 → 按 assert:/channel: 求值 → 产出三元组 (谓词id, artifact 路径, PASS/FAIL)。det-machine 谓词优先（零主观）。channel: det-machine 且 observe: freshness_check 时，调用 freshness_check <product> <src_dir>（已在 lib.sh 实现），stdout 作 artifact；UNKNOWN 按 INCONCLUSIVE→FAIL 铁律处理（不放行）；STALE 同 FAIL；仅 FRESH（rc0）算 PASS。骑既有谓词闸门，不新增 Tier。## 验收场景 为 N/A 时，编排器据变更内容现场推导至少 1 条谓词并求值。Dev server 启动规范：先 lsof -ti:3000 -ti:4000 检查已有进程 → 有则直接用 → 无则 npm run dev & 后台启动 + sleep 8 等待 → 不要将多条命令拼接为一行（避免参数解析错误）。
| 场景类型 | 示例 |
|---|---|
| CLI/Hook/配置 | 运行命令验证输出和退出码，模拟 stdin 验证 stdout |
| API/UI/库函数 | curl 调用端点验证响应，启动 dev server 验证渲染，临时脚本验证返回值 |
防合理化指南见 references/anti-rationalization.md（仅在你想跳过测试/重做时阅读）。
注：Tier 2 编号已合并入本段 qa-reviewer Agent，详见 [2026-05-07] sub-agent token 优化决策。
改动说明：此前 Wave 2 并行启动 design-reviewer + code-quality-reviewer 两个 Agent，每个 cold start ~500k token 且都 Read 同一批变更文件。合并为 1 个 qa-reviewer Agent 后节省 ~1M token / run。
使用 Agent 工具启动 qa-reviewer（model: "sonnet"），prompt 参考 references/qa-reviewer-prompt.md 模板，填入：
## 设计文档 复制）核心原则：
qa-reviewer 完成后：收集 Section A（设计符合性）+ Section B（代码质量与安全）合并为 QA 报告的 Tier 2 部分。
gate: "review-accept" 等用户介入，不以编排器自审替代（自审无独立性，是抽卡来源）在对话中产出 QA 报告（用户直接看），仅在 frontmatter 写 gate/phase。报告格式和示例参见 references/qa-report-template.md。
谓词闸门（取代旧的场景计数 / 格式检查 / ⚠️ 复盘 / 打分）：
三元组来自 Tier 1.5 对 ## 验收场景 谓词的逐条求值。每条预注册验收谓词产出 (谓词, artifact 路径, PASS/FAIL)：
闸门 = ∀ 谓词 PASS 且 Section A/B 无 Critical。无分数、无 "Ready to merge"。
全绿 → 更新 frontmatter：gate: "review-accept"
有 FAIL 或 Critical → 更新 frontmatter：phase: "auto-fix"，报告末尾列出每条 FAIL 谓词（含其 artifact 与期望值）
Tier 3.5 性能 ⚠️ 仍按既有降级（不阻塞、不计入谓词闸门）。
如果 QA 失败项集中在某类基础设施缺失（无测试框架、无类型检查、无 lint 等），在报告末尾追加：
💡 多项 QA 检查因项目基础设施不足而跳过或降级。建议运行
/autopilot doctor诊断并改进工程基础设施。
读取 QA 失败项，逐项分析根因并修复（max 3 次重试）。
默认不允许修改红队验收测试——问题在实现，不在测试。唯一例外：明确属红队测试本身问题（断言与契约矛盾 / 引用未声明私有 seam / 断言机制错），须 AskUserQuestion 确认 + 重锁放行，详见 references/auto-fix-phase.md。
防合理化指南见 references/anti-rationalization.md（仅在你想跳过测试/重做时阅读）。
从最近一轮 QA 报告中提取所有 ❌ 标记的项目。
并行判断：如果多个失败项涉及不同文件且互不依赖，可以并行修复（多个 Edit 调用）。涉及同一文件或有依赖关系时必须串行。
.acceptance.test.*）：仅铁律例外三情形经用户确认 + 重锁后允许（详见 references/auto-fix-phase.md）eslint --fix 或手动修复对每个失败项，严格按四阶段执行：
a. 观察
b. 假设
c. 验证
d. 修复
git add 暂存retry_countretry_count++，更新状态文件qa_scope: "selective"，更新 phase: "qa" 回去选择性重跑失败 Tier（参见 QA 阶段「前置：选择性重跑判断」）
[快速路径]），不设置 qa_scope，执行全量 QAgate: "review-accept"（让用户决定）完成代码提交和最终收尾。
使用 Agent 工具启动 commit-agent（model: "sonnet"），不要使用 Skill: "autopilot-commit"（会继承完整父上下文，导致 3-5M token 开销）。
预收集 Agent 输入（编排器在启动 Agent 前通过 Bash 获取）：
git diff --stat 输出（变更概况）git diff 完整 diff（供分析具体改动）## 设计文档 提取）启动 Agent：prompt 参考 references/commit-agent-prompt.md 模板，填入上述输入。Agent 执行：分析变更 → 生成 commit message（中文） → git add → git commit → 版本号升级 → CLAUDE.md 更新。
编排器收到 Agent 结果后，验证 git log --oneline -1 确认提交成功。
如果 frontmatter brief_file 非空（任务来自项目 DAG）：
brief_file 路径推导 handoff 路径：将 .md 替换为 .handoff.md（如 tasks/<id>.md → tasks/<id>.handoff.md）.autopilot/project/dag.yaml 中对应任务的 status 从 pending/in_progress 改为 donebrief_file 非空时评估信心：QA 全 ✅ + retry_count=0 + handoff 偏差说明为空 → 用 bash plugins/autopilot/scripts/lib.sh 中的 get_first_ready_task .autopilot/project/dag.yaml 选下一个任务 → Edit frontmatter next_task: "<task-id>"；任一不满足或无就绪任务 → 保持 ""。stop-hook 检测到 next_task 非空会自动 auto-chain。详见 references/auto-chain-guide.md。
commit Agent 完成后，回顾本次全流程产出，提取值得持久化的知识。
references/knowledge-engineering.md 获取完整提取规则和格式模板。写入前先按 Integration over Append 流程搜索 index.md 找候选条目（决定合并/新建/跳过）；写入后按 Anti-Overfitting Principles 5 问自检 Lesson/Choice 字段。decisions.md / patterns.md；领域特定条目 → domains/{domain}.md
c. 追加条目到目标文件（使用 <!-- tags: ... --> 格式）
d. 同步更新 index.md：为每个新条目添加索引行（如 index.md 不存在则创建）
e. 检查全局文件行数：>100 行时建议用户将领域条目迁移到 domains/
f. 知识库 git 提交上下文（worktree 安全路由）：详见 references/knowledge-engineering.md 的"Worktree-Aware Extraction"章节时间限制 2 分钟。宁可少写高质量条目，不要穷举。
输出结构化完成报告（6 个区块）。报告模板和格式要求参见 references/completion-report-template.md。
phase: "done"，同时确认 gate: "" 清空（若 QA 阶段曾设 gate: "review-accept" 且本次走过 auto-chain 或 setup.sh approve 自动推进，gate 应已被清；若 AI 自行从 review-accept 推进到 merge 则必须显式清。stop-hook v3.36.3 已防御性兜底，但仍建议显式清以保持 state 一致）next_task，stop-hook 会自动创建下一个任务的状态文件并继续循环⚠️ 绝对不要用 Write 工具重写整个状态文件。 必须使用 Edit 工具精确修改 frontmatter 中的字段值。重写会丢失 stop-hook 必需的字段（iteration、max_iterations、session_id），导致 stop-hook 误判文件损坏并删除。
Read 操作精简：每个阶段开始时 Read 一次状态文件获取全局信息，后续操作使用 Edit 精确修改。不需要在每次 Edit 前重复 Read 整个文件。
完整 frontmatter 字段说明（包含 fast_mode 三态、qa_scope 取值范围等）参见 references/state-file-guide.md。AI 可写字段：phase / gate / retry_count / mode / qa_scope / next_task / knowledge_extracted / fast_mode（仅在 design 步骤 1 探针后自适应判断时，且当前为空字符串才写）。AI 不动字段：iteration / max_iterations / max_retries / session_id / started_at / task_dir。auto_approve 由 stop-hook 设置。（各枚举字段合法值见 references/state-file-guide.md 闭合枚举；shell 仅认 canonical，越界会被 stop-hook 退回纠正）
## 设计文档：design 阶段写入，后续不修改（除非 revise 回到 design）知识文件独立于状态文件。merge 阶段写入 .autopilot/knowledge/ 目录（含 index.md 索引、decisions.md/patterns.md 全局、domains/*.md 领域分区），单独 git commit，格式参见 references/knowledge-engineering.md。