doc-ears-autopilot

doc-ears-autopilot

用途

自动化的 EARS 生成流水线。从上游 PRD、用户提示词或实现计划（IPLAN-*）出发，分析源内容、验证上游就绪情况，生成完整的 EARS 文档，其中包含原子化的 WHEN-THE-SHALL-WITHIN 语句，验证就绪情况，维护 EARS-00_index.md，并推动审计↔修复循环直至通过评分——支持单个 EARS 或批量处理。

层级：3。上游：PRD（及其 BRD）、提示词或 IPLAN。 下游：已验证的 EARS + 索引条目。

技能依赖

技能	作用
../doc-ears/SKILL.md	EARS 结构、四种模式、语法规则
../doc-ears-audit/SKILL.md	质量门禁（评分 + 发现项）
../doc-ears-fixer/SKILL.md	根据审计报告应用修复
../doc-naming/SKILL.md	元素 ID 标准和 @threshold: 标签

输入约定

接受：目标 EARS ID/路径；上游 PRD ID/路径；自由文本提示词；或 IPLAN 路径。可选项：评分阈值（默认 90）、最大修复迭代次数（默认 3）、批次列表。若未提供明确输入，则将请求视为提示词。

智能文档检测

对于每个目标，检查 EARS 是否已存在（嵌套文件夹 docs/03_EARS/EARS-NN_{slug}/）：

• 不存在 → 生成模式（基于上游 PRD / 提示词 / IPLAN）。
• 已存在 → 审查并修复模式（先审计，低于阈值时再修复）。

根据源内容确定 deliverable_type（code/document/ux/risk/process，继承自上游 PRD）。

模型预检查

仅供参考，尽力而为。显示此层级建议使用的模型；无法切换会话模型。调用驱动程序前：

1. 如果 .claude/aidoc-flow.config.yaml 不存在，或没有 model.* 键，则完全跳过本节（不输出任何内容）。
2. 确定建议使用的模型：若已设置则使用 model.per_layer.EARS，否则使用 model.default。
3. 根据 model.precheck（warn | silent | block）执行操作：
   • warn（默认）——打印一行，然后继续调用驱动程序： ℹ EARS recommends model '<rec>'. If you're not on it, run /model <rec> (or set model.precheck: silent to hide this).
   • silent ——不打印任何内容；继续。
   • block ——打印上面一行，并追加 precheck=block: confirm you want to draft on the current model, or run /model <rec> first., 然后等待用户确认后再继续。

工作流

Saga 驱动的生成循环（review_mode: team）

步骤 1 — 调用驱动程序。就此执行。 在调用此 SKILL 前，运行环境会设置 PREV_OUTPUT、ARTIFACT_ID、ARTIFACT_PATH 环境变量。 你的首个编排操作必须是 Bash 工具（先运行上述 Model 预检查），并严格执行：

python3 "${CLAUDE_PLUGIN_ROOT}/tools/saga_driver.py" \
  --layer 03_EARS \
  --allow-skip-permissions

--allow-skip-permissions 可让驱动程序调度的各阶段无需权限提示即可写入文件——无人值守自动执行必须使用此标记。 删除此标记，即可使用 Claude Code 的常规提示运行相同循环。

请设置宽裕的超时时间（≥1800s）。不要预先分析输入。不要阅读上游内容。不要分类类型／范围。驱动程序及其调度的子进程（草稿阶段使用 /aidoc-flow:doc-ears，审查阶段使用 /aidoc-flow:doc-ears-audit，修复阶段使用 /aidoc-flow:doc-ears-fixer）会处理所有这些工作。驱动程序会依据 ${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md，预先强制执行状态机；此 SKILL 的职责是调用它并报告结果。

步骤 2 — 驱动程序返回后，报告结果。 读取 .aidoc/review/03_EARS/${ARTIFACT_ID}/saga.json。最终状态必须为 CLOSED（通过）、ESCALATED（终止失败）或 PARTIAL_TIMEOUT（软截止；可恢复）。输出状态、verdict.json 中的最终分数（若存在）以及一行摘要。

步骤 3 — 更新索引（仅限 CLOSED）。 在 docs/03_EARS/EARS-00_index.md 中添加一行，引用新的 EARS；更新上游工件的下游条目。

这就是 team 模式的全部工作流。如果你发现自己在做其他事情——起草文字、调度 Task 子代理、调用其他斜杠命令——请停止，意识到自己正在绕过驱动程序，并改为调用上述 Bash 命令。

线性流水线（review_mode: single_pass）

未更改的旧版行为——当配置文件指定使用此模式、无法调度 Task 子代理，或在写入时（on_author）成本为首要考虑因素时使用。以下 5 步会话内模式可生成 EARS，但不会生成 saga.json；因此运行环境的 saga 日志检查会导致该层失败，此模式仅适用于手动试运行。

1. 输入分析 — 对输入分类（PRD／提示词／IPLAN），定位上游 PRD 及其 BRD，并决定是生成还是审查并修复。
2. 就绪检查 — 确认上游 PRD 存在且已达到 EARS 就绪状态（分数 ≥ 阈值）；预留下一个 EARS-NN。将 PRD 需求归类到四种 EARS 模式（事件、状态、非预期、通用）。
3. 生成 — 按照 ../doc-ears/SKILL.md 生成 EARS：先写文档控制，包含全部 5 个章节，使用原子化 WHEN-THE-SHALL-WITHIN 语句，以表格形式列出质量属性（百分位时序），元素 ID 使用 EARS.NN.SS.xxxx，使用累积的 @brd／@prd 标签、@threshold: 引用，以及通过 ../charts-flow/SKILL.md 添加的状态／序列图标签。
4. 验证 — 从头开始运行 ../doc-ears-audit/SKILL.md。
5. 审查 ↔ 修复循环 — 当分数低于阈值且迭代次数低于上限时：运行 ../doc-ears-fixer/SKILL.md，然后重新审查。通过后，更新 docs/03_EARS/EARS-00_index.md；若迭代次数耗尽，则标记为需人工审查。

执行模式

• 单项 — 一个 EARS（生成或审查并修复）。
• 批量 — 多个 EARS，按每批 3 个分块处理，以控制上下文；只有确认上游 PRD 已就绪后，才生成各 EARS。
• 试运行 — 报告计划执行的操作（模式、章节、ID），不写入文件。

质量门槛

• 只有审查通过（BDD 就绪度 ≥ 阈值，且 Tier-1 错误为 0）或达到迭代上限（此时标记为需人工审查）后，生成才算完成。
• 只有 EARS 通过后才更新 EARS 索引。
• 每个循环都要重新审查，不使用缓存分数。

错误处理

情况	操作
上游 PRD 缺失或未达到 EARS-Ready 门槛	停止；报告缺失或未就绪的依赖项
达到最大迭代次数后仍未达到门槛	编写报告，标记为需人工审核，并继续处理批次
源输入含糊不清	回退到提示词模式；在 EARS 中记录假设
含糊或复合语句无法自动解决	标记为需人工审核，并继续处理批次
写入/权限错误	记录日志，跳过该项，并继续处理批次

适配

应用默认设置前，先读取项目适配配置文件 （.aidoc/profile.yaml），并在生成阶段和内部 审计/修复阶段应用该配置。遵循 section_toggles、active_layers、audit_threshold （仅可提高，即只能采用更严格的标准）和 glossary。忽略任何未知或 超出适用范围的键；若未提供配置文件，则使用框架默认设置。 权威依据：${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md。

相关资源

• 创建：../doc-ears/SKILL.md · 审计：../doc-ears-audit/SKILL.md · 修复： ../doc-ears-fixer/SKILL.md
• 权威依据：${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-TEMPLATE.yaml、 ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/README.md、 ${CLAUDE_PLUGIN_ROOT}/framework/layers/03_EARS/EARS-00_index.TEMPLATE.md