OmX Ralph 取消契约ralph-cancel-contract深入解析状态终结、联动模式与跨会话安全的规范化实现【免费下载链接】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导读docs/contracts/ralph-cancel-contract.md是 OmXOh My codeX项目中一份规范性Normative契约它规定了当 Ralph 被直接启动、或作为其他工作流之后的独立后续standalone follow-up启动时取消cancellation操作必须满足的一组后置条件post-conditions。本文以该契约为骨架结合 src/cli/index.ts 中cancelModes的完整实现、src/ralph/contract.ts 的状态机校验逻辑以及 skills/cancel/SKILL.md 的操作指南讲清 Ralph 取消的三大核心目标状态如何进入终态、与 Ultrawork/Ecomode 的联动清理顺序、以及跨会话状态隔离的边界机制。读完你将能回答取消 Ralph 后ralph-state.json里应该是什么、为什么联动模式必须一并终结、以及实现如何阻止越界清掉别的会话。一、契约定位为什么需要一份取消契约在 OmX 中Ralph 是一个拥有持久状态active、current_phase、completed_at等字段的模式mode。它既可能被用户直接启动也可能在 Autopilot、Ultrawork 或其他工作流结束后作为后续任务独立运行。这两种启动路径都会走到同一个取消入口因此需要一个与实现解耦、可被测试验证的规范文本避免以下三类问题取消后状态残留——active仍为true导致再次查询时误判为还在运行联动模式遗漏——Ralph 与 Ultrawork/Ecomode 在同一个 scope 内互相链接只取消 Ralph 会让链接方处于悬挂激活状态跨会话越界——取消逻辑误改其他 session 的模式状态破坏会话隔离。这份契约的约束对象不仅是 CLI 实现还包括omx state clear等状态操作路径参见 docs/contracts/multi-state-transition-contract.md 对模式状态文件与状态操作的约定因此它以必须MUST/应当SHOULD的 RFC 2119 语气陈述后置条件供实现者与测试者共同引用。二、核心后置条件终态三要素与联动/隔离规则契约正文将必需的后置条件分为三类本节逐条拆解并给出源码印证。1. 目标 Ralph 状态必须为终态且非激活取消完成后被定位的 Ralph 状态必须满足字段要求含义activefalse模式不再处于激活运行态current_phasecancelled进入终止相位集合completed_at已设置ISO8601记录结束时间戳在 src/cli/index.ts 的cancelMode帮助函数中这三条被逐一强制写入entry.state.active false; entry.state.current_phase phase; // 默认 cancelled entry.state.completed_at nowIso; // new Date().toISOString() entry.state.last_turn_at nowIso;nowIso在cancelModes入口处统一取new Date().toISOString()src/cli/index.ts保证同一批取消操作的时间戳一致。而终态必须非激活、终态必须带completed_at并非 CLI 的临时决定而是由 src/ralph/contract.ts 的状态机校验强制约束的if (typeof next.current_phase string RALPH_TERMINAL_PHASE_SET.has(next.current_phase as RalphPhase)) { if (next.active true) { return { ok: false, error: terminal Ralph phases require activefalse }; } if (next.completed_at null) { next.completed_at nowIso; } }其中终止相位集合RALPH_TERMINAL_PHASE_SET {blocked_on_user, complete, failed, cancelled}src/ralph/contract.tscancelled是 Ralph 八个合法相位之一starting / executing / verifying / fixing / blocked_on_user / complete / failed / cancelled。这意味着即使有人绕过cancelModes直接写状态文件只要走validateAndNormalizeRalphState校验activetrue与current_phasecancelled的组合也会被拒绝——契约在状态机层有第二道防线。2. 联动模式行为链接方必须终态无关模式保持原样契约规定若 Ralph 在同一 scope 内与Ultrawork/Ecomode链接则该链接模式也必须是终态/非激活MUST同一 scope 内未链接的无关模式应当保持不变SHOULD。实现侧的链接判定来自 src/cli/index.ts 的linkedRalphModeconst linkedRalphMode (state: Recordstring, unknown): ultrawork | ecomode | undefined { if (state.linked_ultrawork true || state.linked_mode ultrawork) return ultrawork; if (state.linked_ecomode true || state.linked_mode ecomode) return ecomode; return undefined; };也就是说Ralph 状态文件中的linked_ultrawork: true、linked_ecomode: true或统一字段linked_mode: ultrawork | ecomode都会被识别为联动。取消时src/cli/index.ts的清理顺序是先联动、后 Ralph 本身if (ralph ralph.state.active true) { const linkedMode linkedRalphMode(ralph.state); if (linkedMode) cancelMode(linkedMode, cancelled, true); cancelMode(ralph, cancelled, true); cancelRalphSkillEntries(linkedMode); }注意此处隐含了链接清理排序linked cleanup ordering联动模式先于 Ralph 落盘。测试用例也覆盖了这一场景例如 src/cli/tests/session-scoped-runtime.test.ts 构造了linked_ultrawork: true的 Ralph 状态第 2088 行则构造了linked_ecomode: true且current_phase: executing的会话级状态验证取消后两者都被终态化。同时由于取消只遍历linkedRalphMode指向的那个模式同一 scope 下其他未被链接的模式如独立的plan-consensus、team等不会被动到——这正是契约第 2 条 SHOULD 约束的实现体现。3. 跨会话安全取消不得改写无关会话的模式状态契约第 3 条是硬性边界取消操作绝对不允许变更无关会话中的模式状态MUST NOT。源码中用两层机制保证这一点scope 解析cancelModes首先通过resolveWritableStateScope(cwd)确定可写 scoperoot 或具体 session随后只在目标 scope 内收集模式状态文件src/cli/index.ts。会话级取消时只装载该会话的mode-state.json其他会话的状态文件根本不在候选列表里。路径权威校验装载每个状态文件前loadStates会通过realpathSync解析规范路径并用isCanonicalPathWithin(canonicalAuthorityRoot, ...)断言其必须位于授权的状态根目录之内任何指向授权根之外的符号链接或非常规文件都会被拒绝Refusing cancellation outside authorized state rootsrc/cli/index.ts。三、实操入口从 CLI 命令到状态文件的完整取消链路命令与参数约束omx cancel在 src/cli/index.ts 中被分发到cancelModes。参数解析非常严格src/cli/index.ts只接受/cancel与/cancel --force两种形式--all、未知参数、重复参数、混合参数一律在变更任何状态之前抛错拒绝特别地omx cancel --all会得到明确提示omx cancel --all is not supported; broad workspace cancellation requires a separate command.这与 skills/cancel/SKILL.md 中Accepted forms are/canceland/cancel --force; Reject--all, unknown flags, repeated flags, and mixed flags before mutation的输入前置条件完全一致。取消前的证据收集SKILL 要求取消前先通过状态读取面确认当前 session/root 与精确目标omx state list-active --json omx state get-status --mode mode --json确认失败或缺证据时应当停止而不是盲目取消。这与实现中装载状态前先解析 authority、收集 owner id、逐文件做身份dev/ino与内容一致性校验的防御姿态一脉相承。清理顺序与--force语义取消按依赖顺序检查活动模式autopilot → ralph → ultrawork → ecomode → ultraqa → swarm → ultrapilot → pipeline → team → plan-consensus。其中Autopilot先取消但保留其可恢复状态只清理它拥有的链接子模式Ralph按前述契约终态化并连带终态化已证明链接的 Ultrawork/Ecomode独立模式只有在证明未被其他活动模式链接后才清除Team需先用omx team status team --json检查运行时正常完成门之后用omx team shutdown team或走显式中止路径状态清除统一走状态 API例如omx state clear --input {mode:mode,session_id:session} --json带--force时执行文档化的 native-stop 清理cancelModes会从native-stop状态条目的sessions中删除当前 sessionId 记录src/cli/index.ts。写盘事务身份校验、顺序写、失败回滚契约虽未展开但实现提供了远超改三个字段的事务保障src/cli/index.ts先验证后写对所有待变更条目用O_RDWR | O_NOFOLLOW打开逐一核对文件仍为常规文件、dev/ino身份未变、内容与装载时快照一致任何偏差都会在写盘前拒绝顺序提交变更按排序后的顺序落盘——注意排序中ralph被特意排到最后if (left ralph) return 1;确保联动模式先于 Ralph 提交写失败回滚任一条目写入失败时已提交的条目按逆序恢复为原始内容并sync()若回滚也失败则抛出带cancellation_rollback_failed:count的错误信息绝不虚报成功。这一事务路径可通过cancelModesForTestsrc/cli/index.ts注入写失败/回滚失败故障进行确定性测试。结果报告与退出语义每个被取消的活动模式输出一行Cancelled: mode无活动模式时输出No active modes to cancel.对应 SKILL 中的 clean no-op 报告任何异常走logCliOperationFailure并设置process.exitCode 1src/cli/index.ts。SKILL 的退出与证据要求与此对应每个被选模式报告 mode、scope/session、终止相位、保留的状态、联动清理结果以及任何拒绝理由。四、验证与测试契约可被证伪契约的价值在于可验证。仓库中已有两条主要验证路径单元级src/ralph/contract.ts 的validateAndNormalizeRalphState是状态机的规范化/校验实现终止相位必须activefalse且自动补齐completed_at可直接针对契约第 1 条做断言集成级src/cli/tests/session-scoped-runtime.test.ts 构造带linked_ultrawork/linked_ecomode标记的 Ralph 会话状态调用cancelModesForTest后断言联动模式与 Ralph 均进入终态契约第 2 条且取消不触碰其他会话契约第 3 条src/cli/tests/ralplan-advisory.test.ts 等测试则覆盖了 Ralph 之外的取消路径与空取消场景。五、与其他契约的关系ralph-cancel-contract.md不是孤立文档它与仓库契约体系相互引用docs/contracts/multi-state-transition-contract.md 定义了模式状态文件.omx/state/{scope}/mode-state.json的通用转换与omx state clear语义本契约是其面向 Ralph 取消场景的特化后置条件skills/cancel/SKILL.md 将本契约的 MUST/SHOULD 翻译为操作步骤步骤 4 明确要求确认 docs/contracts/ralph-cancel-contract.md 中的后置条件docs/STATE_MODEL.md 与 docs/contracts/runtime-authority-backlog-replay-readiness.md 提供了 scope、authority、会话归属等底层概念供深入理解第 3 条跨会话安全的边界来源。小结ralph-cancel-contract.md用最小篇幅锁定了一个易错行为的全部后置条件activefalsecurrent_phasecancelled ISO8601completed_at的终态三要素、同 scope 联动模式Ultrawork/Ecomode的连带终态化、以及不得触碰无关会话的隔离红线。而 src/cli/index.ts 中的cancelModes用 scope 解析、canonical path 校验、dev/ino 身份核对、排序提交与失败回滚把这三条契约落成了可注入故障、可被测试证伪的工业级实现。对于需要在 OmX 之上扩展模式生命周期管理的开发者这份契约连同 src/ralph/contract.ts 的状态机校验是理解取消语义最权威的两份依据。【免费下载链接】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），仅供参考