企业官网建设流程全解析

OmX 0.17.1 发布解读：Team/Ultragoal 职责切分、可审计 Question 事件与发布就绪硬化

【免费下载链接】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

0.17.1 是 OmX（Oh My codeX）在 0.17.0 之后的一次「发布就绪 + 运行时协调」补丁版本，核心目的是在不破坏新引入的 0.17.x 工作流接口的前提下，收紧 Team/Ultragoal 交接、问题（Question）协调、Setup MCP 迁移行为、HUD/tmux 所有权、原生会话叠加层与发布安全门禁。本文以 docs/release-notes-0.17.1.md 为主线，结合仓库源码（问题事件流、Hermes 桥、Ralph 完成审计、Lore 提交守卫、HUD 测试等）逐项解析改动动机、实现细节与升级注意事项，帮助你在升级到 0.17.1 后正确理解新的工作流契约、事件格式与验证门禁。

版本定位：一次面向工作流契约的协调性补丁

从版本节奏看，0.17.1 不是功能大版本，而是对 0.17.x 工作流面的加固。它的四类核心目标非常明确：

• Team 与 Ultragoal 的协调显式化：规划（planning）、ralplan、Team、Ultragoal 四套指引现在明确记载了职责切分——Ultragoal 继续持有 Leader 所有的持久化目标/台账（goal/ledger）状态，而 Team 负责并行执行泳道（execution lanes）并返回可检查点的证据（checkpoint-ready evidence）。
• Question 桥接事件可审计：问题协调器桥（question coordinator bridge）开始输出结构化事件，并支持围绕 pending/answered 问题状态的、有界的 Hermes/MCP 协调。
• Setup MCP 默认行为更安全：setup不再静默移除受管理的 MCP 默认项，移除需要显式确认；doctor输出也能正确区分插件模式（plugin-mode）下的none状态。
• 发布列车审计干净：package 与 Cargo 元数据统一对齐到0.17.1，lockfile 中fast-uri、hono、ip-address、express-rate-limit等传递性 npm 安全公告（advisories）均已解决。

Team + Ultragoal：Leader 台账与并行泳道的明确边界

这是 0.17.1 最重要的工作流契约变更。在此之前，Ultragoal 与 Team 的职责边界容易模糊：目标状态被多处写入，执行证据又缺乏统一出口。0.17.1 将边界固定为：

• Ultragoal = Leader 所有的持久化目标/台账状态：目标、里程碑、验收标准这类「长期事实」只由 Leader 角色经 Ultragoal 指引维护；
• Team = 并行执行泳道：Team 只负责把目标拆解为可并行执行的任务，产出可检查点（checkpoint-ready）的证据后交回，而不是自己去改写目标台账。

配套的直接开发提交中包括「将 Ultragoal 目标与 Team 执行链接起来」（link Ultragoal goals with Team execution），即两个工作流之间不再是两个孤立系统，而是「目标驱动 → 泳道执行 → 证据回填」的闭环。仓库中 Team 侧的协调协议可参考 src/team/coordination-protocol.ts，其状态模型见 src/team/state/types.ts，相关行为由 src/team/tests/coordination-protocol.test.ts 覆盖。

升级提示：如果你此前依赖 Team 自行维护 Ultragoal 台账，请迁移到「Ultragoal 定目标、Team 回证据」的模型，否则后续的交接校验会拒绝不完整状态。

可审计的 Question 协调事件流

0.17.1 的亮点之一是把「提问/作答」从内部状态变成可审计的事件流。这样外部观察者（Hermes/MCP 客户端、自动化脚本）可以只读地跟踪问题的创建、回答与错误，而无需触碰内部记录文件。

事件模型：omx.question-event/v1

仓库中事件记录的类型定义位于 src/question/events.ts，每条记录带kind: 'omx.question-event/v1'，事件类型为三选一：

• question-created：问题创建并落盘时触发；
• question-answered：问题被合法回答时触发；
• question-error：问题进入错误/中止等异常终态时触发。

事件记录的关键字段包括：

落盘与并发安全：JSONL + 目录锁

事件以 JSONL（每行一个 JSON 对象）追加写入状态目录下的question-events.jsonl（见getQuestionEventsPath）。为避免多进程并发追加导致行撕裂，实现采用「目录锁 + owner token」方案：

• 锁超时 10 秒，锁陈旧判定 30 秒（QUESTION_EVENT_LOCK_TIMEOUT_MS/QUESTION_EVENT_LOCK_STALE_MS）；
• 拿到锁后写入 owner token，释放前校验 token 属于自己，避免误删他人锁；
• appendQuestionAnsweredEventOnce会在锁内先扫描是否已存在同question_id的question-answered事件，保证「已回答」事件只会落盘一次——这对重试提交场景非常重要。

读取侧提供readQuestionEvents，可按类型过滤并取最近 N 条（limit下限 1、上限 1000，默认 100）。

从创建到回答的完整链路

问题生命周期在 src/question/state.ts 中实现，事件在以下节点被发出：

1. createQuestionRecord(..., { emitEvent: true })→ 写question-created；
2. 记录进入pending→ 渲染后markQuestionPrompting置为prompting；
3. submitQuestionAnswerById在提交锁内校验答案 schema 后置为answered，并调用appendQuestionAnsweredEventOnce写question-answered；
4. 异常终态由markQuestionTerminalError处理（aborted/error）。

值得注意的还有答案严格校验：normalizeSubmittedAnswers要求answer.kind必须是option/other/multi之一，且必须携带selected_labels[]与selected_values[]；validateAnswerAgainstQuestion会核对选项值是否在 schema 内、单选只能选一个、other仅允许在allow_other时使用等。这也解释了为什么事件里的option_schema要打快照——后续审计时可以把「用户实际选择」与「当时给出的选项」对照。

Hermes/MCP 协调的有界暴露

「有界 Hermes/MCP 协调」在 src/mcp/hermes-bridge.ts 中落地，桥接层对外暴露了三组与问题相关的能力：

• hermes_list_question_events：读事件流，limit默认 100、上限 1000；
• hermes_list_questions：按状态过滤（open/pending/prompting/answered/aborted/error），返回精简投影HermesQuestionSummary；
• hermes_submit_question_answer：提交答案，需要allow_mutation: true，错误被映射为question_unknown/question_not_open/question_invalid_answer等可机读错误码。

这意味着外部 Agent 可以只读地「看到」提问状态、有界地「回答」问题，但不能越权修改内部记录——这正是 release notes 所说的「bounded coordination」。CLI 侧的阻塞式提问封装见 src/question/client.ts 的runOmxQuestion，它以omx question --json --input ...子进程方式调用，并对无输出、非法 JSON、非零退出码给出独立错误码（question_no_stdout、question_invalid_stdout、question_cli_not_found、question_nonzero_exit）。

Setup MCP 默认行为收紧：不再静默移除默认项

0.17.1 修复了 Setup 的迁移行为：旧版本可能在切换 MCP 模式时静默移除受管理的 MCP 默认项。新行为是：

• 移除必须经过显式确认；
• doctor输出能正确区分插件模式下的none状态（即「未配置 MCP 模式」与「插件模式为 none」不再混为一谈）。

从 src/cli/setup.ts 源码可见相关痕迹：DEFAULT_SETUP_MCP_MODE = "none"，且对「已弃用的第一方 OMX MCP 注册」会输出明确提示并询问「Remove first-party OMX MCP registrations now? [y/N]」（默认 N，即不主动删除）。mcpMode的取值优先来自 CLI 参数，其次来自持久化偏好（persistedPreferences.mcpMode），与直接开发提交中「修复插件 MCP none 的 doctor 状态」相对应。

修复与兼容性说明逐项解读

Team 工作线程启动：避免冗余 MCP 启动，隔离空闲 Ultragoal 计划

Team worker 启动路径不再重复启动 MCP（redundant MCP startup），并且空闲（idle）的 Ultragoal 计划不会再干扰 Team 的启动行为。如果你的环境里 MCP 服务较重，这一改动能明显降低 Team 启动时的资源抖动。

Team 就绪：超时即失败，而非带着歧义继续

此前 draft-only（只有草稿状态）的 Team 启动在就绪超时后会带着不明确的执行状态继续跑；0.17.1 改为「超时就失败启动」。也就是说，团队启动的确定性被提高了：无法确认就绪就不进入执行，避免后续交接出现「半启动」歧义。相关 PR 为 #2312。

Approved execution handoff：以审批后的仓库上下文为准

0.17.1 移除了旧的 context-pack 交接路径，改为「已审批的仓库上下文（approved repository context）」。这是一次工作流契约迁移：

发布操作者应把已审批的 PRD / test-spec 产物与 Team 证据视为交接的唯一事实来源（source of truth）。

换言之，旧的「把上下文打包传递」机制被废弃，交接信任建立在「审批后的文档产物 + Team 执行证据」之上。这意味着你的发布流程应保证 PRD/test-spec 与 Team 证据在交接点前完成审批与固化（相关目录约定可参考 docs/contracts/repo-aware-team-dag-decomposition.md 与 docs/contracts/team-delivery-state-contract.md）。

Ralph 完成示例：必须有可审计的完成证据

Ralph（长任务执行者）的完成示例（completion examples）现在要求先记录可审计的完成证据，才能标记工作完成。实现位于 src/ralph/completion-audit.ts：

• 证据候选来源：状态内的completion_audit/completionAudit等键，或指向工作区内 JSON 文件的completion_audit_path等路径（路径必须落在工作目录内、必须是.json）；
• 校验规则：必须存在审计对象、passed === true、存在非空的 checklist（prompt_to_artifact_checklist/requirements_checklist等）、存在非空的验证证据（verification_evidence/commands/tests等）；
• 失败时给出机读原因：missing_completion_audit、completion_audit_not_passing、missing_completion_checklist、missing_verification_evidence。

对使用 Ralph 的团队来说，这意味着「声称完成」必须有可回放的证据文件，否则会被判定为未完成（相关状态契约见 docs/contracts/ralph-state-contract.md）。

HUD/tmux：窗口尺寸变化与所有权冲突

HUD 在终端 resize 事件下更稳定，且避免了窗口之间的 hook 所有权冲突。从 src/hud/tests/index.test.ts 与 src/hud/tests/reconcile.test.ts 可以看到对应回归测试：当自适应预算（adaptive budget）变化时，只对 OMX 自己拥有的 HUD pane 执行resize-pane（例如高度 3 行），且不会把 resize 或 hook 施加到非 OMX 所有（%2等）的 pane 上。两个 PR（#2305 强制 resize 时 pane 高度、#2306 防止 resize hook 所有权冲突）共同保证多窗口场景下 HUD 不互相踩踏。

原生会话叠加层：保留用户 AGENTS 指引，隔离生成样板

原生（native）会话叠加层现在会保留用户手写的 AGENTS 指引，同时把生成的工程样板（generated project boilerplate）排除在会话指令之外。对应 PR #2296「preserve user-generated AGENTS guidance」。这一改动的意义在于：用户自定义规则不会被升级或生成流程覆盖，同时自动生成的模板文本也不会污染模型上下文（相关机制可参考 src/hooks/session.ts 与 src/hooks/prompt-session-provenance.ts）。

Lore 提交守卫：接受紧凑合规消息，仍强制 OmX 合著者署名

Lore commit guard 现在接受紧凑的合规提交消息，但依然要求 OmX co-author trailer（Co-authored-by: OmX ...之类）。实现位于 src/config/commit-lore-guard.ts：守卫默认关闭，可通过环境变量OMX_LORE_COMMIT_GUARD开启，支持1/true/yes/on取值；同时会读取$CODEX_HOME/config.toml（默认~/.codex/config.toml）中的shell_environment_policy.set或env配置来获取开关值。注意：读取配置失败或未配置时按默认关闭处理。

发布列车审计与依赖治理

0.17.1 把 npm 与 Cargo 元数据统一对齐到0.17.1，并在 lockfile 中解决了四个传递性 npm 安全公告：fast-uri、hono、ip-address、express-rate-limit。这些都属于「传递依赖」层面（通常由上游包间接引入），升级到 0.17.1 后npm audit的高级别（high-level）结果应更干净。仓库根目录的 package.json 与 Cargo.toml（及 crates 下各 workspace crate）即为版本对齐的载体。

合并 PR 清单（0.17.1）

0.17.1 的合并 PR 与直接开发提交如下（完整清单见 docs/release-notes-0.17.1.md）：

• #2287— 发出 question bridge 事件
• #2290— Ralph 示例要求记录可审计完成证据
• #2292— 移除 context-pack 审批执行交接
• #2296— 保留用户生成的 AGENTS 指引
• #2301— 用诊断信息约束普通工作循环（bounded ordinary working loops）
• #2303 / #2304— 升级@types/node与@biomejs/biome
• #2305— 终端 resize 时强制 HUD pane 高度
• #2306— 防止 HUD resize hook 所有权冲突
• #2312— 就绪超时后让仅草稿的 Team 启动失败
• #2319— 弃用默认的 MCP setup 移除行为
• 直接开发提交— 将 Ultragoal 目标与 Team 执行链接、让 Team worker 不参与冗余 MCP 启动、修复插件 MCPnone的 doctor 状态、在原生会话替换时保留 OMX owner、准备审计干净的 0.17.1 发布元数据

验证与发布就绪证据

发布就绪证据记录在 docs/qa/release-readiness-0.17.1.md。本地的 tag 前置门禁全部通过，包括：

• 版本同步检查（version sync）
• lint（@biomejs/biome，见 biome.json）
• no-unused 类型检查（tsconfig.no-unused.json）
• Cargo workspace 检查（Cargo.toml）
• npm 高级别审计
• 空白/whitespace 检查

需要说明的局限是：本次发布没有在附带的 OMX/tmux 运行时中重跑完整 Node 测试套件，原因是此前尝试显示存在环境运行时污染与泄漏的 question 测试子进程（ambient runtime contamination / leaked question test children）；因此权威的干净 CI/发布门禁仍是 release tag 工作流。也就是说，0.17.1 的「审计干净」以静态门禁 + 定向回归（如 HUD resize、question 事件、Ralph 审计等单测）为准，全量套件留给 tag 工作流把关。

升级与落地建议

综合以上改动，升级到 0.17.1 时建议按以下清单核对：

1. 工作流契约：确认 Team 与 Ultragoal 按「Ultragoal 持台账、Team 回证据」协作；交接点只认审批后的 PRD/test-spec 产物与 Team 证据，不再依赖 context-pack。
2. 问题协调：如需对接 Hermes/MCP，直接消费question-events.jsonl或hermes_list_question_events；回答类调用务必传allow_mutation: true，并按question_*错误码处理失败。
3. Setup 迁移：MCP 默认项移除需要显式确认；用omx doctor核对插件模式下mcpMode=none的输出是否符合预期。
4. Ralph 完成判定：为完成示例补齐带passed: true、checklist 与验证证据的 JSON 审计文件（或状态内嵌审计对象），否则会判定为未完成。
5. 提交规范：若开启 Lore commit guard（OMX_LORE_COMMIT_GUARD=1），紧凑消息可接受，但 OmX co-author trailer 仍为必填。
6. 依赖安全：升级后复查npm audit，确认fast-uri、hono、ip-address、express-rate-limit相关公告已消失。

0.17.1 的总体取向是「少改功能、多立规则」：它把此前模糊的职责边界（目标 vs 执行）、脆弱的内部状态（提问 vs 审计）、有风险的操作（MCP 静默移除）全部显式化、可审计化，为 0.17.x 工作流面打下一个更稳固的发布基线。

【免费下载链接】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