OmX Cancel Skill 深度解析：多模式运行的安全终止与状态清理规范

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是 OmX（Oh 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 --force

SKILL.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/root）：

omx 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），必须先处理高层、再处理其链接的下层，才能避免"孤儿活动状态"残留。

各步骤要点：

1. 解析并校验参数，选取唯一精确的 session/root 作用域；
2. 按依赖顺序检查活动模式（见上）；
3. 取消 Autopilot 时保留其可恢复状态（resumable state），只清理它所拥有的链接子模式（linked child modes）——注意 SKILL.md 用的是"clean only linked child modes it owns"，即只清理 Autopilot 拥有（owns）的链接子模式，而不是盲目全清；
4. Ralph 特殊处理：将目标状态终态化（active:false、current_phase:"cancelled"、completed_at），并终态化同一作用域内经证实的链接 Ultrawork/Ecomode 状态；完成后须核对 docs/contracts/ralph-cancel-contract.md 中的后置条件；
5. 独立模式（standalone modes）仅在证明其未链接到其他活动模式后才能清理——这是防止误伤仍在运行的工作流的护栏；
6. Team 特殊处理：先用omx team status <team> --json检查运行时，在正常完成门禁（completion gate）之后使用omx team shutdown <team>，或走明确的 abort 路径；
7. 仅通过状态 API 清理所选模式/会话状态，示例：

omx state clear --input '{"mode":"<mode>","session_id":"<session>"}' --json

8. 使用--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 启动的场景：

1. 目标 Ralph 状态必须终态且非活动：
   • active=false
   • current_phase='cancelled'
   • completed_at已设置（ISO8601 时间戳）
2. 链接模式行为：
   • 若 Ralph 在同一作用域链接了 Ultrawork/Ecomode，则该链接模式也必须终态/非活动；
   • 同一作用域内无关且未链接的模式应保持不变（SHOULD remain unchanged）。
3. 跨会话安全：
   • 取消不得变更无关会话（unrelated sessions）中的模式状态。

契约文档还指出了实现对齐点：src/cli/index.ts中的cancelModes强制执行"受限取消 + 链接清理顺序"（scoped cancellation and linked cleanup ordering），而skills/cancel/SKILL.md记录了作用域感知的取消行为与兼容性回退策略。

在源码实现中，这一逻辑体现得非常直接（src/cli/index.ts）：

const 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对终态判断采用"幂等"设计——若状态已是active=false、current_phase='cancelled'且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 state）；owner_codex_session_id与active_skills条目的所有权元数据也逐一校验；
• 脱机（detached）运行权威校验：对于脱机会话（如 ralplan advisory 场景），通过 checkpoint 机制反复校验目录/文件身份（dev/ino/内容）在取消过程中未被并发改动，任何身份漂移都会触发Refusing cancellation because detached ... changed/... no longer canonical；
• Advisory 共识取消：当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.md（Ralph 取消的规范性后置条件）
• 技能镜像：plugins/oh-my-codex/skills/cancel/SKILL.md
• 实现入口：src/cli/index.ts（cancelModes及测试导出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 status+omx 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