Menu
当用户需要从目标描述到代码合并的端到端自动化、或说"自动驾驶"时使用。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional 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。