oh-my-claudecode 命名 Autopilot 阶段工作流Named Autopilot Stage Profiles v1设计详解与源码验证【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode本篇技术指南围绕 oh-my-claudecode 仓库中的架构决策记录 ADR 03487 展开系统讲解命名 Autopilot 阶段 ProfileNamed Autopilot Stage Profiles v1这一能力的契约、配置、校验、完整性保障与恰好一次exactly-once的阶段推进机制。读完本文你将掌握如何通过/autopilot --workflow name task选择预置阶段编排、如何在用户或项目 JSONC 中声明可复用的阶段调度、这些配置为何必须满足严格约束以及该设计与既有 Autopilot 生命周期cancel/resume/HUD/Stop之间如何协作。1. 决策背景为什么要引入命名阶段 Profile在 v1 之前Autopilot 已有固定的ralplan → execution → ralph → qa管线能力其内部类型定义可见于 pipeline-types.ts它以PipelineStageId ralplan | execution | ralph | qa表达四类阶段并以STAGE_ORDER声明规范顺序。然而不同任务对规划、实现、验证、QA四个环节的组合需求并不相同有的场景只想要规划 实现有的则需要规划 实现 独立 QA还有的要规划 实现 ralph 验证 QA。ADR 03487 的核心动机有五个均指向一个设计边界——让 Autopilot 提供可复用、有名字的阶段调度但绝不膨胀成通用工作流引擎提供可复用的命名阶段调度同时避免把 Autopilot 改造成通用工作流引擎保留 Autopilot 既有职责状态state、取消cancel、恢复resume、清理cleanup、HUD、Stop 延续等能力仍归 Autopilot 单一主体所有只放行输入与完成语义自洽且可验证的序列保证所选运行不可变immutable、可做完整性校验并且对插件路径与独立安装standaloneHook 路径同样安全避免不安全的路由权威——因为当前无法认证工作流生成的 spawn 是否可信所以 v1 不做模型/Provider 级路由。换句话说这是一个被刻意收紧的 v1 契约收益是确定性与安全边界代价是功能范围被严格裁剪。2. v1 决策契约一个 opt-in 的封闭 Profile 合约2.1 唯一入口/autopilot --workflow name taskv1 Profile 是opt-in的封闭合约只能通过如下显式命令行形式激活/autopilot --workflow name task从源码实现看keyword-detector.mjs 在进入通用/autopilot处理之前会先调用parseWorkflowInvocation定义于 workflow-profile-runtime.mjs只有以/autopilot可带oh-my-claudecode:或omc:前缀开头、且紧跟--workflow的调用才会进入命名 Profile 路径--workflowname的等号写法、缺少名字、缺少 task 都会被判定为invalid-explicit-workflow-invocation并在创建任何 Autopilot 状态之前报错退出。2.2 Profile 存放位置与形状Profile 存放在用户或项目级 JSONC 配置的autopilot.workflows.slug下。v1 Profile 只允许两个键version必须等于数字1与stages{ autopilot: { workflows: { plan-build-qa: { version: 1, stages: [ralplan, execution, qa] } } } }配置解析实现在validateDefinitionsworkflow-profile-runtime.mjs它会剥离 JSONC 注释与尾逗号后解析配置逐条检查名称、保留字、键集合、version值与stages数组任何不合规项都会以带来源user/project的错误消息拒绝。用户配置路径位于~/.config/claude-omc/config.jsoncWindows 下为%APPDATA%/claude-omc/config.jsonc项目配置则从工作目录向上在.claude/omc.jsonc中解析可结合 git 根与.omc-workspace边界判定。2.3 v1 唯一放行的四种序列[ralplan, execution] [ralplan, execution, ralph] [ralplan, execution, qa] [ralplan, execution, ralph, qa]这与 pipeline-types.ts 中的WorkflowProfileStages联合类型逐字对应运行时isApprovedSequenceworkflow-profile-runtime.mjs按完全等值比对实现任何调序、重复、缺前置阶段、非内置阶段的组合一律被拒。2.4 语义边界Profile 是元数据 阶段调度仅此而已ADR 反复强调Profile 既不是动态命令、也不是关键词别名、模式mode、插件、文件名、状态标识或可独立取消的工作流。旧的/autopilot task行为保持为无 Profile 的兼容路径no-profile path两者在后续的取消、恢复、清理与 Stop 语义上完全一致。3. 阶段输入/输出契约Admission I/O与校验规则3.1 各阶段的产物依赖链v1 只承认四种序列根本原因在于这四个阶段之间存在严格的产物依赖ralplan消费调用时的任务文本产出规范canonical的 Autopilot 计划工件spec 与实现计划见阶段提示词中.omc/autopilot/spec.md与.omc/plans/autopilot-impl.mdexecution要求存在可读的计划产出实现变更ralph要求计划与execution的实现都存在用于验证它不会凭空制造缺失的实现qa要求来自execution的实现直接或经ralph之后。因此ralplan与恰好一个execution是必选ralph与qa只能按声明顺序作为可选追加。这四条序列恰好是 v1 中唯一能自行建立完整计划 实现工件的编排。3.2 名称与 Profile 键约束名称必须匹配^[a-z][a-z0-9-]{0,62}$空名、大写、含空白都拒绝不得与内置阶段 ID、Autopilot/canonical 模式名、废弃别名冲突。源码中的RESERVED_WORKFLOW_NAMES集合workflow-profile-runtime.mjs明确禁止诸如autopilot、ralplan、execution、ralph、qa、ultrapilot、swarm、plan、team、cancel、deep-interview、tdd、default等名字v1 Profile 对象拒绝未知键、version必须是数字1、不接受任何 model 字段这是与已否决的stageModels方案的直接区隔。3.3 多来源组合与原子替换用户配置源与项目配置源在合并前各自独立校验错误信息带来源限定。不同名字的 Profile 可以共存若项目 Profile 与用户 Profile 同名则项目 Profile 整体原子替换用户 Profile——Profile 对象永远不做深度合并never deep-merged。环境environment配置既不能定义也不能替换 Profile。3.4 平台前提Linux flockv1 的运行时支持明确要求Linux 且装有flock工具经过认证的 transcript 边界依赖 Linux 的不跟随符号链接的文件描述符遍历可恢复的陈旧锁清理依赖内核咨询锁advisory locking。实现中isWorkflowRuntimeSupportedworkflow-profile-runtime.mjs会检测process.platform linux且/usr/bin/flock或/bin/flock存在在不支持的环境下显式命名 Profile 会在任何 Autopilot 状态变更前被拒绝错误信息即named autopilot workflow profiles require Linux with flock而遗留 Autopilot 依旧跨平台可用。4. Descriptor 与完整性一次写入、不可变、全程可校验4.1 状态记录与不可变 Descriptor选定 Profile 成功后Autopilot 会原子地写入一条完整的、作用于当前会话的 Autopilot 状态记录其中包含不可变 Descriptor 与仅含选中阶段的PipelineTracking。ADR 明确规定不允许先写一个通用占位记录、之后再去打补丁。对应接口定义在 pipeline-types.tsinterface WorkflowDescriptor { readonly descriptorVersion: 1; readonly workflowName: string; readonly profileVersion: 1; readonly stages: WorkflowProfileStages; readonly profileHash: string; }ADR 原文中该结构名为WorkflowRunDescriptorV1仓库当前源码中即为上述WorkflowDescriptor二者语义一致。4.2profileHash的确定性计算profileHash是小写 SHA-256计算对象是如下结构的 UTF-8 规范化紧凑 JSON{descriptorVersion: 1, workflowName, profileVersion: 1, stages}。规范化规则为对象键递归按字典序排序stages使用已校验的阶段顺序。源码canonicalJson与selectWorkflowProfile精确实现了该约定选中 Profile 后立即构造 descriptor 并生成哈希workflow-profile-runtime.mjs。Descriptor刻意排除任务文本、完整配置、模型设置与可变状态整个运行期间唯一允许变化的是用于展示进度的PipelineTracking含trackingRevision单调递增修订号、currentStageIndex、激活边界与完成观测类型定义见 pipeline-types.ts 的PipelineTracking。4.3 读取/恢复/Stop 前重算哈希任何一次读取、恢复resume与 Stop 在推导下一阶段前都会重算哈希并与持久化值比对。Descriptor 畸形或不匹配时统一返回workflow_descriptor_integrity_failed不产出阶段提示词、不重载配置、也不悄悄修复状态。已取消但有效的运行会依据持久化的 Descriptor 与 tracking 恢复因此之后发生的配置变更无法影响这次运行。这一校验在 keyword-detector 的恢复路径中也有镜像hasWorkflowMarker与hasValidWorkflowDescriptor不一致即上报workflow_descriptor_integrity_failedkeyword-detector.mjs。5. 恰好一次Exactly-once的 Transcript 边界与阶段推进5.1 激活边界与权威 Stop Hook在发出某个适配器提示词之前当前激活阶段会记录其激活序号、时间戳与 transcript 边界。权威的插件 Stop Hook 链路为hooks/hooks.json→scripts/persistent-mode.mjshooks.json 的Stop匹配器中确实按序注册了context-guard-stop、workflow-drift-guard、persistent-mode等处理器独立安装时由安装器提供配套的templates/hooks/persistent-mode.mjs两者必须使用相同契约。5.2 什么证据可以推进阶段一个阶段转移只接受当前适配器在边界之后、出现在被授权的 assistant JSONL 记录中的精确完成信号。证据必须绑定到拥有者会话、有界的bounded常规非符号链接 transcript且文件名与会话匹配。以下情形一律不能推进阶段用户记录、工具记录、local-command-stdout畸形 JSONL激活边界之前的证据陈旧状态、错误阶段、错误会话任意或符号链接伪造的 transcript。每个候选记录都携带不可变的证据元数据阶段与会话 ID、精确信号、记录位置与内容哈希、transcript 身份/大小快照、激活边界引用、观测时间。这些字段与 pipeline-types.ts 中PipelineCompletionObservation、PipelineActivationBoundary、PipelineTranscriptFileIdentity设备号、inode、size、mtime/ctime 纳秒、内容 SHA-256一一对应。完成信号字符串在运行时定义为PIPELINE_RALPLAN_COMPLETE/PIPELINE_EXECUTION_COMPLETE/PIPELINE_RALPH_COMPLETE/PIPELINE_QA_COMPLETE。5.3 Compare-before-write并发下的唯一推进者在发生任何状态变更前Stop 处理器会重新读取权威状态、核验 Descriptor 哈希与所有权并以compare-before-write守卫 tracking 的修订号/转移令牌。一次调用只完成当前阶段收尾、记录观测、精确激活下一个选中阶段、发出该适配器的精确提示词。若出现重复或并发调用竞争失败方只读取一次并报告已是当前状态而不会重放旧候选——因此阶段完成是恰好一次的。6. Canonical 入口点一览ADR 给出的五个规范入口点仓库均已落地SurfaceCanonical entrypoint职责插件提示词选择hooks/hooks.json→scripts/keyword-detector.mjs解析选择、校验与组合配置源、构造 Descriptor/Tracking、在写状态前原子初始化或拒绝插件 Stophooks/hooks.json→scripts/persistent-mode.mjs授权 transcript 证据并恰好一次地推进所选 Tracking插件 PreToolUsehooks/hooks.json→scripts/pre-tool-enforcer.mjsv1 模型行为保持不变其 transcript 加固经验被 Stop 授权复用独立安装的 Hooksrc/installer/hooks.ts安装templates/hooks/{keyword-detector,pre-tool-use,persistent-mode}.mjs与插件版 Descriptor、生命周期与转移行为保持一致库消费者src/hooks/autopilot/*、HUD、状态工具保持等价的状态语义与安全的公开呈现不是主要安装启动路径值得留意的是keyword-detector 在发现已存在同名运行时会做恢复resumeWorkflowProfile且只有完整且已终止的运行才允许走 resume 分支keyword-detector.mjs与 ADR 中无迁移、cancel 保留私有 descriptor/tracking的描述吻合。7. 否决过的备选方案Alternativesv1 明确拒绝了四类方案理解这些边界有助于避免误用本功能Profiles stageModels现有提示词已显式选择模型且没有可信标记能证明某个 Task/Agent 调用由活跃工作流产生而非用户或嵌套任意工作默认模型要么失效、要么误伤无关调用。活跃阶段的全局模型默认值会对阶段活跃期间所有匹配调用生效把手工、嵌套、无关工作也一并纳入且无法溯源。动态工作流命令或模式动态命令/别名/模式/文件名/状态标识会大幅扩张冲突面、生命周期、发布与取消语义超出阶段 Profile的能力范围。通用工作流/插件引擎任意阶段、提示词、插件、分支、循环、DAG、回调、Provider 需要独立的架构与安全模型。8. 为什么这样选择Why chosen与影响Consequences为什么选中封闭的 Profile 组合既提供实用的可复用调度又保留固定适配器集合与 Autopilot 既有生命周期。四种序列是 v1 中唯一能自行建立计划 实现工件的编排不可变 Descriptor、经过认证的 transcript 边界与 compare-before-write 转移让恢复和已安装 Stop Hook 的安全性不依赖新运行时身份。影响与代价首个交付提供命名且经校验的阶段调度但不包含按工作流成本调优、模型路由、直达任务 Profile、行内 token 节省。插件与独立安装模板都属于产品表面必须持续做一致性parity测试Profile 初始化与阶段转移的完整性与证据要求比旧的 no-profile 行为更严格。9. 迁移、兼容与公开状态Public-state处理迁移现有 Autopilot 调用无需迁移。不带--workflow时遗留 no-profile 路径行为不变autopilot-state.json仍是唯一的状态身份。Cancel 将同一状态标记为 inactive 但保留私有 Descriptor/Tracking 供恢复clear 维持既有删除语义。不会新增任何工作流专属的取消、状态文件或 HUD 身份。公开状态磁盘上的 Descriptor 与转移观测是私有的。公开状态与状态预览只暴露安全工作流元数据工作流名、Profile 版本、12 位十六进制哈希前缀加省略号、阶段列表、当前阶段与状态/进度。HUD 渲染有界的合法名称与stage:id i/nDescriptor 完整性失败时渲染有界的workflow:invalid。Stop 强化消息不泄露任务文本、Descriptor 内部字段、plan/spec 路径、transcript 路径、偏移、记录哈希或未来模型值。遗留 Autopilot 输出保持兼容。10. 从源码读到的纵深实现证据将 ADR 与仓库源码交叉验证后可归纳出如下实现事实阶段提示词是规范化产物workflow-stage-prompts.mjs 由scripts/build-workflow-stage-prompts.mjs从 TypeScript 阶段适配器生成内部以令牌__OMC_NAMED_WORKFLOW_TASK_DISPLAY__等占位运行时才注入任务与 analyst/architect 提示词文件头明确注明请勿直接编辑。校验是逐条硬性比对无论 Profile 的version、stages、名称正则、保留字、未知键任何一项不满足都直接抛错绝不静默降级哈希校验要求 profileHash 为 64 位小写十六进制并精确重算比对。状态写入是一次性快照createWorkflowState在初始化时同时写入 workflow 描述与PipelineTracking首阶段active、其余pending、trackingRevision从 0 起步与 ADR不得写占位再打补丁的规定对应。并发安全依赖读-验-比-写四步转移候选返回期望修订号与期望证据哈希交由调用方Stop Hook做 compare-before-write 提交workflow-profile-runtime.mjs。测试覆盖仓库包含专门的完整性测试 workflow-integrity.test.ts、阶段转移测试transitions.test.ts/transition.test.ts以及端到端的 Stop 转移集成测试 workflow-profile-stop-transition.test.ts可视为 ADR 关键行为的可执行规格。用户文档已同步正式参考文档 REFERENCE.md 中Named autopilot stage profiles (v1)一节给出了与 ADR 完全一致的 JSONC 示例、四种合法序列、哈希与公开状态说明并链接回本 ADR 作为决策记录。11. Follow-ups 与显式推迟项以下内容明确不在 v1 范围stageModels、一切模型/Provider/角色路由及优先级变更、可信的工作流 spawn 溯源、无模型 Profile 渲染、行内/无 spawn 执行、直达主会话执行、动态命令/模式/状态文件、任意阶段/提示词/插件、自定义重试、回调、分支、循环、DAG 与环境 Profile 定义。此外行内数组形式的自定义 skill frontmatter 解析器不一致属于独立问题不与本功能捆绑。未来的工作可能提议可信 spawn 溯源与限定范围的模型路由、真正的行内执行语义、或仅限工作流的直达任务输入——每项都需要独立设计与验证方案。12. 实践要点总结要在当前仓库中使用 v1 命名阶段 Profile请记住这条最小可用链路在 Linux带flock环境中于用户配置~/.config/claude-omc/config.jsonc或项目.claude/omc.jsonc中声明autopilot.workflows.nameversion恒为1stages只能是四种合法序列之一用/autopilot --workflow name task显式激活缺 task、名字非法、Profile 不存在或重复声明都会在状态变更前失败运行期由 Autopilot 统一管理状态、取消、恢复与 HUD每个阶段的完成信号由权威 Stop Hook 依据 transcript 边界恰好一次地认证并推进若想中途恢复或取消走既有的 Autopilot cancel/resume 语义即可无需任何迁移也不会产生额外状态文件。该机制的精髓在于用一份小到不能再小的封闭契约换取可复用的编排与可证明的安全推进——它是理解 oh-my-claudecode 如何在管线自动化与可控性之间取得平衡的重要入口后续继续阅读 ADR 03487 与 REFERENCE.md 中的工作流章节即可把这一设计横向迁移到对你最有价值的自定义调度上。【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考