OmX Cancel Skill 深度解析多模式运行的安全终止与状态清理规范【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex导读cancel是 OmXOh My codeX内置的技能Skill用于安全终止任意活动中的 OMX 模式autopilot、ralph、ultrawork、ecomode、ultraqa、swarm、ultrapilot、pipeline、team 等并执行文档规定的清理流程。本指南将基于 skills/cancel/SKILL.md 完整解析/cancel及cancelomc/stopomc的输入校验、依赖顺序、跨模式链接清理、Team 关闭路径与终态证据规范并结合 ralph-cancel-contract.md 与src/cli/index.ts中cancelModes的源码实现说明其底层的身份校验、回滚机制与拒绝策略。读完本文你将掌握在 OmX 中安全终止活动模式、正确使用--force、以及验证清理后置条件post-conditions的完整实操能力。一、Cancel Skill 的定位与使用时机OmX 的定位是你的 Codex 并不孤单——它在 Codex 之上叠加了 hooks、Agent 团队、HUD 等大量扩展并内置了多套可叠加运行的执行模式。当 autopilot、ralph、ultrawork、ecomode、ultraqa、swarm、ultrapilot、pipeline、team 等任一模式处于活动状态时用户需要一种精确、可回滚、可验证的方式来终止它们这正是cancel技能的存在意义。SKILL.md 明确要求使用/cancel或cancelomc/stopomc停止活动中的 OMX 模式并执行其文档规定的清理。在动手之前必须先阅读 AGENTS.md 中durable-runtime-invariants-canonical-ssot一节——它是关于作用域scope、所有权ownership、hooks 与 Team 清理的不变式权威invariant authority。也就是说cancel 并不是简单地把状态文件标记为非活动而是要服从一组跨会话、跨模式的一致性约束。注意OmX 的 cancel 技能同时以镜像形式存在于 plugins/oh-my-codex/skills/cancel/SKILL.md插件分发目录两者内容保持一致src/verification/__tests__/ralph-persistence-gate.test.ts还对该契约文档的存在性与持久化门禁进行了校验。二、输入形式与前置条件严格拒绝模糊操作Cancel 技能对命令行参数采取白名单校验策略任何超出允许范围的参数都会在发生状态变更mutation之前被拒绝。接受的合法形式仅有两种/cancel/cancel --forceSKILL.md 明确要求拒绝以下非法输入--all、未知 flags、重复 flags、混合 flags。这一要求在源码中得到了精确落实。在 src/cli/index.ts 的cancelModes实现中if (args.length 1 || args.some((arg) arg ! --force)) { const unsupported args.find((arg) arg ! --force) ?? args[1] ?? ; throw new Error(unsupported --all ? omx cancel --all is not supported; broad workspace cancellation requires a separate command. : Unknown cancel argument: ${unsupported}); }即omx cancel --all会被明确拒绝提示broad workspace cancellation requires a separate command任何未知参数都会以Unknown cancel argument: ...报错。force标志仅当参数恰好为[--force]时为真const force args.length 1;。在执行清理之前必须先通过状态读取接口state read surfaces发现当前会话/根session/rootomx state list-active --json omx state get-status --mode mode --json从 CLI 结构看omx state子命令支持read | write | clear | list-active | get-status五类操作见 src/cli/tests/state.test.ts 与嵌套帮助路由测试 src/cli/tests/nested-help-routing.test.ts。其中list-active --json用于枚举当前活动模式get-status --mode mode --json用于查看指定模式的详细状态。关键前置条件必须确认当前会话/根session/root与精确的目标target当缺少必需证据时应当停止stop而不是强行继续。这与源码中大量Refusing cancellation ...拒绝逻辑一脉相承——证据不足即拒绝而不是盲目写入。三、操作步骤按依赖顺序逐层清理SKILL.md 给出了 8 步操作流程核心是依赖顺序dependency order。活动模式的检查顺序固定为autopilot → ralph → ultrawork → ecomode → ultraqa → swarm → ultrapilot → pipeline → team → plan-consensus这个顺序并非随意排列而是体现了模式之间的父子/链接关系高层模式如 autopilot、ralph可能拥有或链接低层模式如 ultrawork、ecomode必须先处理高层、再处理其链接的下层才能避免孤儿活动状态残留。各步骤要点解析并校验参数选取唯一精确的 session/root 作用域按依赖顺序检查活动模式见上取消 Autopilot 时保留其可恢复状态resumable state只清理它所拥有的链接子模式linked child modes——注意 SKILL.md 用的是clean only linked child modes it owns即只清理 Autopilot 拥有owns的链接子模式而不是盲目全清Ralph 特殊处理将目标状态终态化active:false、current_phase:cancelled、completed_at并终态化同一作用域内经证实的链接 Ultrawork/Ecomode 状态完成后须核对 docs/contracts/ralph-cancel-contract.md 中的后置条件独立模式standalone modes仅在证明其未链接到其他活动模式后才能清理——这是防止误伤仍在运行的工作流的护栏Team 特殊处理先用omx team status team --json检查运行时在正常完成门禁completion gate之后使用omx team shutdown team或走明确的 abort 路径仅通过状态 API 清理所选模式/会话状态示例omx state clear --input {mode:mode,session_id:session} --json使用--force时执行其文档规定的 native-stop 清理并且如实报告回滚rollback或清理失败而不是声称成功。从 CLI 命令路由看omx cancel在 src/cli/index.ts 中被映射到cancelModes(args.slice(1))并且list命令在没有活动工作流模式时会与omx cancel保持同等表现parity见同文件 L5114 注释。四、Ralph 取消契约终态化的规范性后置条件cancel 对 Ralph 的处理是整个技能中最严谨的部分它由一份独立的规范性契约文档 docs/contracts/ralph-cancel-contract.md 约束。该契约定义了 Ralph 取消的必需后置条件required post-conditions适用于 Ralph 被直接启动、或作为其他工作流之后的独立 follow-up 启动的场景目标 Ralph 状态必须终态且非活动activefalsecurrent_phasecancelledcompleted_at已设置ISO8601 时间戳链接模式行为若 Ralph 在同一作用域链接了 Ultrawork/Ecomode则该链接模式也必须终态/非活动同一作用域内无关且未链接的模式应保持不变SHOULD remain unchanged。跨会话安全取消不得变更无关会话unrelated sessions中的模式状态。契约文档还指出了实现对齐点src/cli/index.ts中的cancelModes强制执行受限取消 链接清理顺序scoped cancellation and linked cleanup ordering而skills/cancel/SKILL.md记录了作用域感知的取消行为与兼容性回退策略。在源码实现中这一逻辑体现得非常直接src/cli/index.tsconst cancelMode (mode, phase cancelled, reportIfWasActive true) { // 若 active!false 或 current_phase!phase 或 completed_at 缺失/为空 才需要变更 entry.state.active false; entry.state.current_phase phase; entry.state.completed_at nowIso; // nowIso new Date().toISOString() entry.state.last_turn_at nowIso; }; const linkedRalphMode (state) { if (state.linked_ultrawork true || state.linked_mode ultrawork) return ultrawork; if (state.linked_ecomode true || state.linked_mode ecomode) return ecomode; }; const cancelRalphSkillEntries (linkedMode) { // 只处理 active_skills 中 skill ∈ {ralph, 链接模式} 的条目置为 active:false, phase:cancelled };其中linkedRalphMode通过linked_ultrawork/linked_ecomode/linked_mode字段判断 Ralph 的链接方向cancelRalphSkillEntries则负责把skill-active-state.json中对应的ralph及其链接模式的 skill 条目一并终态化。这也解释了契约第 2 条链接模式也必须终态的落地方式。值得注意的细节是cancelMode对终态判断采用幂等设计——若状态已是activefalse、current_phasecancelled且completed_at非空则无需再次变更if (!needsChange) return;避免重复写入。五、Team 关闭状态读取与显式 abort 路径Team 模式不能像普通模式一样直接改状态文件因为 Team 是一个运行时runtime概念涉及进程树与多方协作。SKILL.md 给出的流程是omx team status team --json # 先检查运行时 omx team shutdown team # 在正常完成门禁之后关闭即先通过omx team status team --json检查团队运行时状态在正常完成门禁normal completion gate之后执行omx team shutdown team或者走显式的 abort 路径。从 src/cli/tests/team.test.ts 可以看到omx team status还会被 leader 监控提示引用如leader_check: omx team status my-team与轮询建议sleep 30 omx team status my-team说明 status 命令同时承担着团队活性检测的职责。当 Team 被选中取消时退出报告中必须包含 Team 状态与 shutdown 证据。六、源码级原理校验、身份确认与回滚cancelModes的实现远比写几个字段复杂它在写入前执行了多层安全校验这也回应了 SKILL.md当必需证据缺失时停止的要求。核心机制包括可写作用域解析resolveWritableStateScope确定本次取消作用于 root 还是某个 session并解析精确的会话取消权威resolveExactSessionCancellationAuthority路径与符号链接防护对每个状态文件执行lstat/realpath拒绝非常规文件non-regular、符号链接状态目标Refusing cancellation through non-regular state target/Refusing cancellation through symlinked state authority root并校验目标必须位于授权的状态根之内Refusing cancellation outside authorized state root内容一致性校验状态文件必须是合法 JSON 对象否则Refusing partial cancellation because ... is malformed文件内mode字段与目标 ref 不符时拒绝Refusing contradictory mode stateowner_codex_session_id与active_skills条目的所有权元数据也逐一校验脱机detached运行权威校验对于脱机会话如 ralplan advisory 场景通过 checkpoint 机制反复校验目录/文件身份dev/ino/内容在取消过程中未被并发改动任何身份漂移都会触发Refusing cancellation because detached ... changed/... no longer canonicalAdvisory 共识取消当ralplan状态处于 advisory 变体时会委托cancelRalplanConsensus来自 src/ralplan/runtime.ts并在未真正终态化所选 generation 时报错Refusing false Advisory cancellation success注入式故障测试cancelModes接受testFaults选项CancellationTestFaults可在写入失败或回滚失败时注入故障Injected cancellation write failure for .../Injected cancellation rollback failure for ...用于验证回滚路径最终若写入失败且回滚失败会报告(cancellation_rollback_failed:...)无操作输出当没有任何活动模式时控制台输出No active modes to cancel.SKILL.md 中对应的干净无操作报告为No active OMX modes detected.。这些机制共同保证了取消操作是原子的、可回滚的、有证据的——即使写入中途失败也会尝试回滚已写入的条目而不是留下一半已取消、一半仍活动的状态。七、退出与证据规范SKILL.md 要求每个被选中的模式报告一个结果包含mode模式scope/session作用域/会话terminal phase终态阶段preserved state保留的状态如 Autopilot 的可恢复状态linked cleanup链接清理情况refusal reason拒绝理由若有干净无操作时报告No active OMX modes detected.当 Team 被选中时报告还需包含 Team 状态与 shutdown 证据。这与上文源码中reported集合仅当模式曾为活动时才计入报告以及如实报告失败的要求相互印证。这套每模式一报告 显式无操作信息 拒绝理由的输出规范使 cancel 的结果既可用于人工确认也可被自动化流程hooks、状态检查消费与 OmX 一贯的命令 JSON 证据风格保持一致。八、验证与延伸阅读契约文档docs/contracts/ralph-cancel-contract.mdRalph 取消的规范性后置条件技能镜像plugins/oh-my-codex/skills/cancel/SKILL.md实现入口src/cli/index.tscancelModes及测试导出cancelModesForTest状态子命令测试src/cli/tests/state.test.ts、src/cli/tests/session-scoped-runtime.test.ts覆盖worktree 状态 list-active 为空时取消 hook-visible run-dir 会话状态等边界场景Team 相关src/cli/team.ts、src/cli/tests/team.test.ts持久化门禁校验src/verification/tests/ralph-persistence-gate.test.ts参考矩阵docs/reference/ralph-parity-matrix.md交叉引用 ralph-state-contract、ralph-cancel-contract 与持久化门禁、docs/qa/ralph-persistence-gate.md实操要点回顾始终先omx state list-active --json与omx state get-status --mode mode --json取证严格按照autopilot → ralph → ... → plan-consensus的依赖顺序处理Ralph 必须连同其链接的 Ultrawork/Ecomode 一起终态化并核对契约后置条件Team 走omx team statusomx team shutdown或显式 abort 路径--force仅用于执行 native-stop 清理且失败必须如实上报。掌握这些规则就能在 OmX 多模式并发运行环境中做到安全、可回滚、可审计的终止操作。【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考