用 Codex app-server 做一手钩子验证oh-my-openagent 的 Codex 插件 QA 通道全解析【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent本篇文章围绕 oh-my-openagent 仓库中codex-qa技能的核心参考文档 app-server.md 展开讲解如何通过 Codex 官方app-server协议直接驱动真实 Codex 会话以结构化通知流hook/started/hook/completed作为 omo 插件钩子在真实回合中被触发的权威证据。读完你将对 app-server 的传输帧格式、一轮 turn 的完整消息序列、mock 模型原理、隔离式 QA 沙箱以及端到端驱动脚本的实现与判定逻辑形成可直接上手复用的认识。为什么 app-server 是「一手」QA 通道在 Codex 生态里要验证一个插件plugin的钩子是否在真实会话中被触发常见做法是脚本化操作 TUI 或抓取运行日志。这两种方式都有明显缺陷TUI 脚本化脆弱且慢日志抓取则是间接推断无法确凿证明插件钩子确实在某个 live turn 中执行了。codex app-server提供了另一条路径宿主程序IDE、QA harness以编程方式驱动 Codex。它不依赖屏幕交互而是直接讲 app-server 自己的协议从而能读取结构化通知流——其中包括hook/started/hook/completed这两类通知。这正是 omo 插件钩子在真实回合中触发的权威证明一个事件从running走到completed意味着 Codex 确确实实把该钩子接入了运行管线而非我们根据日志猜测。在 oh-my-openagent 仓库中这条通道由codex-qa技能落地实现其参考文档明确标注已针对codex-cli 0.139.0验证技能入口 SKILL.md 层面则标注了0.140.0源码引证均以path:line形式给出。传输层与帧格式启动命令与实现位置codex app-server不带子命令即运行服务器由 Codex 上游的codex-app-servercrate 实现。在仓库中所有 QA 脚本都以该命令为入口例如 app-server-client.mjs 中构造参数的方式const args overrides.flatMap((o) [-c, o]).concat(app-server); const child spawn(CODEX_BIN, args, { stdio: [pipe, pipe, pipe], env: process.env });默认传输stdio 换行分隔 JSON默认传输是stdio帧格式是newline-delimited JSONNDJSON——一行一条消息它不是标准 JSON-RPC 2.0消息中没有jsonrpc字段。请求形如{id, method, params}通知形如{method, params}字段名一律 camelCase。客户端 app-server-client.mjs 按行解析 stdout 缓冲区逐行JSON.parse后交给状态处理函数正是对这一帧格式的直接实现。校验已安装二进制的完整方法集用generate-json-schema子命令可以把协议的方法集导出成 JSON Schema用于离线确认当前安装版本支持哪些请求/通知codex app-server generate-json-schema --out $(mktemp -d) # 产出 ClientRequest.json / ServerNotification.json注意一个交互环境陷阱部分 shell 会把codex包装成注入--profile参数的 shell 函数这会破坏generate-json-schema这类非运行时子命令。bash 脚本不继承该函数因此在脚本中拿到的才是 PATH 上真实的二进制common.sh 中的cqa_codex_bin专门做显式解析可被CODEX_BIN覆盖。详见 isolation.md 的「Thecodexshell-function trap」一节。驱动一轮 turn 的完整消息序列驱动端driver使用的握手序列固定为四步{id:1,method:initialize,params:{clientInfo:{name:codex-qa,version:0.1.0},capabilities:{experimentalApi:true,requestAttestation:false}}} {method:initialized} // notificationREQUIRED不带 id {id:2,method:thread/start,params:{cwd:/abs/workdir}} // - result.thread.id {id:3,method:turn/start,params:{threadId:id,input:[{type:text,text:say hello}]}} // - result.turn.id要点拆解消息作用响应initialize带 id声明客户端身份与能力握手成功协议可用initializednotification必须发送且不带 id无thread/start以cwd打开一个会话线程result.thread.idturn/start提交input文本消息列表开始一轮推理result.turn.id在 app-server-client.mjs 的实现里这三步由handle()状态机串起来收到id:1的 result 后回发initialized并立刻发thread/start收到id:2的 result 后记录threadId并发turn/start收到id:3的 result 后记录turnId。每条请求通过send()写一行 JSON 到 stdinconst send (obj) child.stdin.write(JSON.stringify(obj) \n);逐行读取 stdout 需要收集什么握手完成后驱动端逐行读取 stdout重点收集三类通知hook/started/hook/completed——插件钩子被触发的证明params.run.eventName钩子事件名camelCase如sessionStart、userPromptSubmit、stopparams.run.status从running→completed的状态迁移params.run.sourceplugin标识钩子来自插件。item/completed且item.type agentMessage——item.text即助手回复文本。turn/completed——当turn.status completed或failed且带turn.error且对应自己的turnId时停止本轮驱动。客户端脚本对这三类消息的收集逻辑与文档完全一致app-server-client.mjs钩子通知被压入hooks数组并归一化字段eventName、status、source、pluginId、hookName、runIdagentMessage的文本存入assistantTextturn/completed触发finish()收尾。为什么需要一个 mock 模型一轮 turn 必须有模型可用。如果让真实 Codex 去连 OpenAIQA 就变成了「测 OpenAI 而不是测我们的插件」——既花钱、又不可控、还有网络出口依赖。解法是把自定义model_provider指向本地 mock-model.mjs一个 OpenAI Responses 协议 SSE 服务器让回合在零真实 API 调用的情况下跑完。非 OpenAI 提供方不需要鉴权requires_openai_auth默认为 false因此本地 mock 无需任何 key。驱动端通过-c覆盖注入 provider 配置详见 isolation.md-c覆盖优先于config.toml里的任何值即使隔离 home 配置错误也会落到 mock 上。mock 模型长什么样mock-model.mjs 是一个极简 Node HTTP 服务器对POST .../responses返回text/event-stream每次请求推送恰好三条事件构成 Codex 生成一条助手消息所需的最小 Responses 流sse({ type: response.created, response: { id: resp-1 } }); sse({ type: response.output_item.done, item: { type: message, role: assistant, id: msg-1, content: [{ type: output_text, text: TEXT }] }, }); sse({ type: response.completed, response: { id: resp-1, usage: { input_tokens: 0, output_tokens: 0, total_tokens: 0 } }, });关键设计每次 POST 都拿到一条全新响应因此一个 turn 里多次模型请求如 session-start 探测 turn 本体都能被覆盖。MOCK_PORT缺省为 0由操作系统分配启动后在 stdout 打印MOCK_LISTENING port供调用方读取——common.sh 的cqa_start_mock正是轮询该输出拿到端口并导出MOCK_PORT。客户端注入的-c覆盖全集app-server-client.mjs 中固化了一整套覆盖项值得逐条理解const overrides [ modelmock-model, model_providermock_provider, model_providers.mock_provider.namecodex-qa mock, model_providers.mock_provider.base_urlhttp://127.0.0.1:${MOCK_PORT}/v1, model_providers.mock_provider.wire_apiresponses, model_providers.mock_provider.request_max_retries0, model_providers.mock_provider.stream_max_retries0, approval_policynever, sandbox_moderead-only, ];model/model_provider把回合钉到mock_providermodel_providers.mock_provider.name必填provider 名为空会导致配置加载失败见 isolation.mdwire_apiresponses声明走 OpenAI Responses wire 协议request_max_retries0/stream_max_retries0关闭重试避免 QA 卡在假失败重试上approval_policynever、sandbox_moderead-only非交互、只读沙箱保证回合无人工介入、无写副作用。隔离与安全QA 只测我们的插件整条 QA 通道的安全模型在 common.sh 的注释中写得很清楚只 QA 自己的插件绝不碰用户的真实~/.codex。两个杠杆隔离的CODEX_HOMECODEX_HOME是 Codex 的主状态根config.toml、auth.json、会话、SQLite、插件、日志都挂在其下指向全新临时目录后 Codex 就不会读写其他位置。注意CODEX_HOME一旦设置必须已存在否则 Codex 直接硬错误所以cqa_mk_isolated_homecommon.sh会先mkdir -p。它还导出OMO_CODEX_PROJECT/QA_CWD沙箱项目目录、CODEX_LOCAL_BIN_DIR$CODEX_HOME/bin组件二进制落在沙箱内、OMO_DISABLE_POSTHOG1与OMO_CODEX_DISABLE_POSTHOG1切断遥测出口。证明真实 home 未被改动cqa_guard_real_homecommon.sh在开始前对~/.codex/config.toml做 shasum 快照cqa_assert_real_home_unchangedcommon.sh在结束后重算并断言一致。每个脚本都会跑这道校验。端到端驱动脚本两种模式、可判定退出码app-server-drive.sh 是文档描述的端到端断言入口支持两种模式--self-test裸隔离 home不装插件证明驱动本身可用——turn 能跑、mock 的助手消息能回来。快无需安装。--plugin把本仓库的本地 omo 构建装进隔离 home内部调用packages/omo-codex/scripts/install-local.mjs然后驱动一轮 turn通过断言hook/completed通知来证明插件钩子真的触发了。较重但这是断言级证据。模式选项选项说明--prompt text用户消息默认say hello--plugin模式下默认ulw: say hello以便触发 ultrawork 的userPromptSubmit钩子--expect ev,...必须完成的钩子事件名列表--plugin默认sessionStart,userPromptSubmit--keep保留隔离 home 以便检查默认退出即清理脚本内部依次cqa_require codex node jq→cqa_guard_real_home→cqa_mk_isolated_home→插件模式cqa_install_local_omo并 grep 断言config.toml中启用了omosisyphuslabs→cqa_start_mock→ 运行客户端。客户端rc0时打印 PASS 与钩子清单失败时打印missingHooks。整体由trap cqa_cleanup EXITcommon.sh保证 app-server、mock、tmux 会话与全部临时目录在退出时被拆除。判定逻辑与单测验证客户端 app-server-client.mjs 的summarizeRun定义了三重判定缺一不可turn 状态为completed每个EXPECT_HOOK事件都出现过hook/completed且status completed否则计入missingHooks不存在任何hook/completed但状态非completed的记录否则计入failedHooks。输出为一份 JSON 摘要含turnStatus、assistantText、threadId、turnId、expectHook、missingHooks、failedHooks、hooks、stderrTailok为 true 时进程退出码为 0否则为 1。硬性截止时间DEADLINE_MS默认 60000兜底超时同样判失败。环境变量一览app-server-client.mjs环境变量默认值说明MOCK_PORT必填mock 模型服务器端口缺省直接退出码 2PROMPTsay hello用户消息文本QA_CWDprocess.cwd()会话工作目录DEADLINE_MS60000硬性停止毫秒数EXPECT_HOOK空逗号分隔的钩子事件名空则只要求turn/completedCODEX_BINcodexcodex 二进制PATH 查找非 shell 函数该判定逻辑有配套单测 app-server-client.test.jsbun:test覆盖了三个关键语义即便某个期望事件已完成只要同事件存在一条failed的钩子运行整体仍判失败全部期望事件完成才通过EXPECT_HOOK的逗号分隔解析会忽略空白与空段。0.139.0 上的实测结果把 omo 装进隔离的CODEX_HOME后单轮ulw: say hello的实测事件流为见 app-server.mdsessionStart阶段触发hook/*rules规则注入、telemetry、bootstrap、auto-updateuserPromptSubmit阶段触发rules、ultrawork、ulw-loopstop阶段触发start-work-continuation随后是 mock 助手消息与turn/completed。scripts/app-server-drive.sh --plugin正是对这条链路做端到端断言。如需按组件确认「哪个组件、哪个事件、以什么可观测产物证明触发了」可参考 components-hooks.md 中rules、ultrawork、ulw-loop、comment-checker、lsp、start-work-continuation、git-bash、telemetry、bootstrap九个组件的钩子事件与可观测证明对照表——其中「稳定必触发」的断言建议是live 层断言sessionStart与userPromptSubmit的hook/completed多个组件都接这两个事件必然触发unit 层用ultrawork在ulw提示词下确定性注入ultrawork-mode。实战清单跑一次完整的一手 QA按技能 SKILL.md 的流程完整步骤如下# 1. 确认依赖 隔离 harness 自检 bash scripts/lib/common.sh --self-check # 2. 先证明驱动本身可用快不装插件 bash scripts/app-server-drive.sh --self-test # 3. 装本地 omo 并驱动真实回合断言钩子触发 bash scripts/app-server-drive.sh --plugin # 4. 把 JSON 摘要存为证据无证据文件 QA 没发生 ev.omo/evidence/$(date %Y%m%d)-codex-qa-slug; mkdir -p $ev bash scripts/app-server-drive.sh --plugin $ev/app-server-drive.json 21文中所有脚本的路径均位于.agents/skills/codex-qa/目录下app-server-drive.sh、scripts/lib/app-server-client.mjs、scripts/lib/mock-model.mjs、scripts/lib/common.sh。默认的 QA 面是 Docker见script/agent/qa-docker.sh本地脚本是 Docker 不可用或 Windows 环境下的回退方案。注意事项与限制版本锚定参考文档明确「Verified againstcodex-cli 0.139.0」技能入口标注0.140.0。app-server 的协议方法集会随版本演进务必用generate-json-schema核对当前安装版本必要时升级重验。无/debugging命令Codex 没有/debugging子命令。运行时观测请走app-server 通知流、RUST_LOGdebugapp-server 的 stderr、$CODEX_HOME下的 logs SQLite、TUI 的/debug-config以及codex debug …子命令见 SKILL.md 的On /debugging一节。字段命名差异hook/*通知的eventName是 camelCasesessionStart、userPromptSubmit、stop…而 hooks.json 的 matcher 用 snake_casesession_start、user_prompt_submit…组件 CLI 接收的是 kebab 形式hook user-prompt-submit跨层断言时不要混用见 components-hooks.md。证据即产物驱动脚本输出的 JSON 摘要就是证据本体务必重定向进.omo/evidence/YYYYMMDD-slug/目录保存。总结codex app-server让 omo 插件的 QA 从「猜测日志」升级为「读取权威结构化通知」。本文所述的传输帧格式、四步握手、hook 通知收集、mock 模型与-c覆盖注入、隔离沙箱与判定退出码构成一套完整的、可复现的、断言级的一手 QA 通道——它是codex-qa技能中验证「插件钩子在真实 Codex 回合中确实触发」的首选方法。【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考