codex-qa

Codex QA

对 omo Codex Light 版本（packages/omo-codex/，以 lazycodex 发布）进行 QA。我们在真实的 Codex 中测试自己的插件，同时不触碰用户的任何设置：使用隔离的 CODEX_HOME 和本地模拟模型，因此不会调用真实 API，也绝不会读取或写入真实的 ~/.codex。每个辅助脚本都提供 --self-test，用于针对当前机器运行场景断言，因此这些脚本既是 QA 工具，也是它们自己的回归检查。

已在 codex-cli 0.140.0（macOS 上的 node、jq、tmux、bun）中验证。运行 codex --version 确认版本；运行 codex <cmd> --help 检查标志。

黄金规则（运行任何内容前请阅读）

• 只对我们的插件进行 QA。 所有会启动 codex 的操作都使用隔离的 CODEX_HOME（由 cqa_mk_isolated_home 创建）和本地模拟模型提供方（cqa_start_mock）。绝不针对真实的 ~/.codex 进行 QA，也绝不调用真实模型 API。随附脚本会强制执行这些规则；如果手动运行 codex，请先运行 export CODEX_HOME="$(mktemp -d)/codex"; mkdir -p "$CODEX_HOME"（已设置的 CODEX_HOME 必须已存在，否则 codex 会直接报错）。
• 证明真实主目录保持干净。 每个脚本都会在运行前后计算 ~/.codex/config.toml 的校验和，并断言文件未发生变化。手动编写脚本时，也要执行相同检查。
• 交互式 codex 是一个 shell 函数，会注入 --profile quotio。Bash 脚本会绕过它并调用真实二进制；不要依赖交互式别名。参见 references/isolation.md。
• 证明钩子触发的官方方式是 app-server 通知流（hook/started / hook/completed），而不是从日志中提取信息。参见 references/app-server.md。
• 捕获的 JSON / 窗格内容就是证据——将其写入 .omo/evidence/<YYYYMMDD>-<slug>/（没有证据文件就表示没有进行 QA）。该目录已加入 gitignore：文件仅保留在本地，PR 正文会附上摘要和关键摘录，且其中的内容绝不会被提交。

设置

cd <this-skill-dir>                        # .agents/skills/codex-qa
bash scripts/lib/common.sh --self-check    # confirm deps + isolation harness

Docker 是默认的 QA 环境。 在一次性容器中运行此 QA，该容器应包含最新的 codex 和一份你的配置副本，且不触碰主机上的 ~/.codex：script/agent/qa-docker.sh（参见 references/docker-qa.md）。以下本地脚本适用于 Docker 不可用或使用 Windows 的情况。

路由：选择你的场景

你需要……	运行	深入了解
证明插件钩子在真实 Codex 轮次中触发（官方方式）	scripts/app-server-drive.sh --plugin	app-server.md
证明 app-server 驱动本身正常工作（不含插件，速度快）	scripts/app-server-drive.sh --self-test	app-server.md
将本地构建安装到隔离的主目录中，并断言安装成功	scripts/install-verify.sh --self-test	install-verify.md
确定性地验证单个组件的钩子逻辑（不运行 codex）	scripts/hook-unit-probe.sh --self-test	components-hooks.md
在 tmux 下对真实 TUI 进行冒烟测试（启动、渲染、持续运行）	scripts/tui-smoke.sh --self-test	logging-debug.md
QA 时查看运行时日志	（参见参考文档；RUST_LOG / logs DB / /debug-config）	logging-debug.md

脚本索引（每个脚本都是独立的回归测试）

脚本	--self-test 断言
scripts/lib/common.sh --self-check	依赖项已就绪；在沙箱内创建隔离的 CODEX_HOME，并在退出时自动移除；模拟模型提供 Responses SSE；真实的 ~/.codex 未更改
scripts/app-server-drive.sh	--self-test：一轮普通对话顺利完成，并返回模拟助手文本。--plugin：安装本地 omo，驱动一轮对话，并断言 sessionStart,userPromptSubmit 的 hook/completed
scripts/install-verify.sh	本地 omo 安装到隔离主目录；config.toml 启用 omo@sisyphuslabs；组件二进制文件和 Agent TOML 文件链接到沙箱中；真实的 ~/.codex 未更改
scripts/hook-unit-probe.sh	ultrawork 组件在 ulw UserPromptSubmit 中注入 <ultrawork-mode>（也支持手动指定 --component/--event 的模式）
scripts/tui-smoke.sh	真实的 codex TUI 在隔离主目录中启动并渲染，且持续运行（不会提前退出）；捕获窗格

要在真实的 ~/.codex（而不是隔离的 QA 主目录）中区分开发 dogfood 构建与已发布版本，仓库提供了 bun run install:codex-dev，会将插件版本标记为 dev——每轮对话都会显示 (OmO dev) 钩子状态前缀，且 omo get-local-version 中会显示 [DEV] 徽标。手动 dogfooding 时，可用它确认加载的是哪个构建；它会写入真实主目录，因此绝不会用于上述隔离 QA 流程。

需要 TUI 视觉 QA 证据时，请遵循 docs/reference/web-terminal-visual-qa.md：通过真实的 xterm.js Web 终端渲染 TUI——绝不要使用 tmux capture-pane 帧，因为它会降低 颜色质量和中日韩文字的宽度精度：

node script/qa/web-terminal-visual-qa.mjs --title "Codex TUI QA" \
  --command "codex" --input "{Enter}" \
  --evidence-dir .omo/evidence/<slug>/codex-web-terminal

该辅助工具会运行真实的 pty，在 Chrome 中通过 xterm.js 渲染，并写入 terminal.txt、terminal-ansi.txt、terminal.png（真彩色）和 metadata.json（--from-file <capture.ansi> 可重放已保存的原始流）。TUI 视觉 QA 请使用这组产物；要验证断言级别的钩子行为，请使用 app-server-drive.sh --plugin。

根据更改范围匹配 QA

• 组件 / 钩子逻辑（packages/omo-codex/plugin/components/*）： 使用 hook-unit-probe.sh 检查精确的 stdout，然后使用 app-server-drive.sh --plugin 验证实时连接。参见 components-hooks.md。
• 安装程序 / config.toml（packages/omo-codex/src/install/*）： 使用 install-verify.sh。
• 任何会影响实时会话的内容（钩子、Agent、MCP 连接）： 使用 app-server-drive.sh --plugin；如果涉及 TUI 路径，还要使用 tui-smoke.sh --plugin。

捕获证据

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" 2>&1
bash scripts/install-verify.sh --self-test > "$ev/install-verify.txt" 2>&1

关于 /debugging

Codex 中没有 /debugging 命令。要观察运行情况，可查看应用服务器 通知流（见上文）、应用服务器 stderr 中的 RUST_LOG=debug、$CODEX_HOME 下的 logs SQLite、TUI 的 /debug-config，以及 codex debug … 子命令。参见 logging-debug.md。