opencode-qa

opencode QA

对 opencode 编码 Agent 本身进行 QA。本技能将每种 QA 需求对应到经过测试的辅助脚本和深入参考资料。每个脚本都提供 --self-test，可针对当前运行的机器验证其场景，因此这些脚本既是 QA 工具，也是自身的回归检查。

已针对 opencode v1.17.7（bun 1.3.12，macOS）验证。使用 opencode --version 确认已安装的版本；相关功能稳定，但仍应使用 opencode <cmd> --help 对标志进行基本检查。

黄金规则（运行任何操作前请阅读）

• 读取实时数据库是安全且符合预期的。调查会话（案例 D）只会读取 ~/.local/share/opencode/opencode.db。
• 任何会启动 opencode 的操作（serve、run、TUI）都必须使用隔离的 XDG 沙盒，这样 QA 才不会把无用会话写入真实数据库。随附脚本已做好隔离；如果手动运行 opencode 进行 QA，请先将 XDG_DATA_HOME / XDG_CONFIG_HOME / XDG_STATE_HOME / XDG_CACHE_HOME 设置为临时目录。
• 对 part 表进行全局文本搜索会扫描数 GB 的数据。务必限定范围（使用 --session、--recent 或 --since）。文本脚本会有意拒绝无范围限制的扫描。
• opencode 源代码仓库（packages/opencode）使用 bun test 进行测试，且不能从仓库根目录运行测试。请参阅 references/testing-harness.md。

设置

脚本位于此文件旁边的 scripts/ 目录中。请从此技能目录中调用（或使用其绝对路径）：

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

Docker 是默认的 QA 环境。 在一次性容器中运行 QA，容器中包含最新版 opencode 和一份你的配置副本，主机不受影响： script/agent/qa-docker.sh（参阅 references/docker-qa.md）。 如果 Docker 不可用或在 Windows 上，可使用下方的本地脚本。

common.sh 提供共享测试框架（数据库路径、SQL 转义、隔离的 XDG 沙盒、空闲端口、服务启动/停止，以及 EXIT 陷阱清理）。PATH 中必须包含 opencode、sqlite3、curl、jq 和 tmux。

路由：选择你的案例

你想要……	案例	脚本	参考资料
非交互式运行 opencode / 检查 CLI 命令	A	opencode run --format json（内联）	references/cli-commands.md
按 ID 查找会话	D	scripts/db-session-by-id.sh <ses_id>	references/db-investigation.md
按标题/名称查找会话	D	scripts/db-session-by-name.sh "<text>"	references/db-investigation.md
按消息文本查找会话	D	scripts/db-session-by-text.sh --recent N "<text>"	references/db-investigation.md
将整个会话导出为 JSON	D	scripts/export-roundtrip.sh <ses_id>	references/db-investigation.md
检查 HTTP 服务 / 端点	B	scripts/server-smoke.sh	references/server-api.md
验证钩子 / 操作 / 事件已触发	B	scripts/sse-hook-probe.sh	references/events-hooks.md
验证 serve 拓扑的唤醒运行器拆分（已复现/已修复）	B	scripts/serve-wake-split-probe.sh --expect reproduced|fixed --evidence-dir DIR（自测：--self-test；模拟 LLM：scripts/lib/fake-openai-server.mjs）	references/events-hooks.md
对 TUI 进行冒烟测试	C	scripts/tui-smoke.sh	references/tui-tmux.md
在 opencode 源代码中编写/运行测试	-	（bun test）	references/testing-harness.md
通过 Bun/TS 脚本驱动 opencode	-	（SDK）	references/sdk.md

案例 A：CLI / 终端正常工作

规范的可脚本化非交互式入口是 opencode run。JSON 模式每行输出一个事件，便于据此进行断言。

# stream structured events (types: text, tool_use, step_start, step_finish, reasoning, error)
opencode run "list files in src" --format json
# run a slash command
opencode run --command commit
# resume the last session
opencode run -c "continue"
# target an already-running server instead of booting one
opencode run "explain auth" --attach http://127.0.0.1:4096 -p "$OPENCODE_SERVER_PASSWORD"

其他适用于 QA 的命令：opencode db path、opencode debug paths、opencode session list --format json、opencode models --verbose。完整标志说明请参阅 references/cli-commands.md。

案例 B：特定钩子、操作或事件

opencode 通过 Server-Sent Events 在 GET /event 上发布生命周期事件。 插件通过 event 钩子观察相同的事件，因此在数据流中看到某个事件，就能证明钩子会触发。

# prove the SSE plumbing works (isolated server, asserts server.connected)
bash scripts/sse-hook-probe.sh --self-test

# watch a REAL server for a specific event while you trigger an action
bash scripts/sse-hook-probe.sh --attach http://127.0.0.1:4096 \
  --password "$OPENCODE_SERVER_PASSWORD" --directory "$PWD" \
  --event message.part.updated --timeout 30

通过 HTTP 触发操作（即发即弃，以免阻塞数据流）：

curl -X POST -u opencode:$OPENCODE_SERVER_PASSWORD -H 'Content-Type: application/json' \
  -d '{"parts":[{"type":"text","text":"say hi"}]}' \
  "http://127.0.0.1:4096/session/<ses_id>/prompt_async?directory=$PWD"

实际提示词需要配置好的提供方，因此请在真实服务上运行监视并触发的模式，而不是在隔离沙盒中运行。事件类型目录、21 个插件钩子点，以及如何加载本地插件：references/events-hooks.md。 服务启动、身份验证和路由：references/server-api.md。

案例 C：TUI

bash scripts/tui-smoke.sh --self-test

这会在隔离沙盒中的 tmux 下启动 TUI，确认其能渲染（capture-pane），确认 send-keys 能将内容发送到编辑框，随后关闭 tmux 会话，并验证真实 DB 的会话数量未发生变化。

当 PR 需要 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 "OpenCode TUI QA" \
  --command "opencode" --input "{Enter}" \
  --evidence-dir .omo/evidence/<slug>/opencode-web-terminal

这会运行真实的 pty，在 Chrome 下通过 xterm.js 渲染，并写入 terminal.txt、terminal-ansi.txt、terminal.png（真实色彩产物）以及带有清理回执的 metadata.json（--from-file <capture.ansi> 可重放已保存的原始数据流）。隔离的 scripts/tui-smoke.sh 仍是规范的 OpenCode TUI 启动冒烟测试（tmux），与此视觉证据流程分开。

如实结论：tmux 适合冒烟测试（是否启动、渲染、接受按键），但用于断言对话输出时并不可靠（TUI 是一个 60fps 的全屏应用）。如需断言真实行为，请使用案例 A（opencode run）、案例 B（服务 API + SSE），或 TUI 控制 HTTP API（POST /tui/append-prompt、 POST /tui/submit-prompt、POST /tui/execute-command）。详情和手动 tmux 操作步骤：references/tui-tmux.md。

案例 D：调查 DB 中的会话

对运行中的 SQLite DB 执行只读操作。session 表很小（标题和 ID 查询会即时完成）；消息文本位于数 GB 的 part 表中，因此文本搜索必须限定范围。

# by id
bash scripts/db-session-by-id.sh ses_3a4ee6335ffedFB8f76BPU1Eb3
# by title / name (newest first; second arg = limit)
bash scripts/db-session-by-name.sh "auth refactor" 20
# by message text - scope with --session, --recent N, or --since "<window>"
bash scripts/db-session-by-text.sh --session ses_3a4e... "ULTRAWORK"
bash scripts/db-session-by-text.sh --recent 50 "permission denied"
bash scripts/db-session-by-text.sh --since "7 days" --limit 50 "TODO"
# export an entire session as clean JSON
bash scripts/export-roundtrip.sh ses_3a4e... > session.json

临时查询：opencode db "<SQL>" --format json。架构、带计时的已测试查询模式、旧版 message/part 与 V2 session_message 之间的区别，以及 25 GB 注意事项：references/db-investigation.md。

脚本索引

运行任意脚本时使用 --self-test，即可针对运行中的机器进行验证；使用 -h 可查看用法。DB 读取脚本均为只读；serve/sse/tui 脚本会使用隔离沙盒，并在退出时清理。

脚本	案例	自测断言
scripts/lib/common.sh --self-check	-	依赖存在、DB 路径可解析、SQL 转义正常、端口空闲、沙盒自动移除
scripts/db-session-by-id.sh	D	真实会话的 ID 往返一致
scripts/db-session-by-name.sh	D	根据派生标题生成的搜索词可返回 >=1 行
scripts/db-session-by-text.sh	D	限定范围的搜索有结果；拒绝无限制扫描；有界搜索 <30s
scripts/export-roundtrip.sh	D	导出的标准输出是有效 JSON，且 .info.id 往返一致
scripts/server-smoke.sh	B	/global/health 健康，/doc >=100 个路径，无身份验证时返回 401
scripts/sse-hook-probe.sh	B	/event 可打开并传送 server.connected
scripts/tui-smoke.sh	C	TUI 在 tmux 下渲染，随后关闭，真实 DB 未受影响

风险与注意事项

• 25 GB 的 part 表：切勿执行无范围限制的文本扫描。请使用 --session、--recent 或 --since。简单的 JOIN ... WHERE session.time_created >= X 会从最早的记录开始扫描，耗时约 50 秒；这些脚本使用针对最新会话的 IN 子查询（约 20 毫秒）。
• opencode export 会将启动横幅写入 STDERR；在交给 jq 之前，请先通过 2>/dev/null 过滤，否则会导致解析错误。
• 仅当设置了 OPENCODE_SERVER_PASSWORD 时，服务才会强制要求身份验证；否则服务将以不安全模式运行。已通过身份验证的调用使用 -u opencode:$PASS。对受保护服务发起未经身份验证的调用会返回 HTTP 401。
• 已安装的二进制文件与开发源代码：引用内部实现时使用开发源代码路径，但请根据已安装的 opencode <cmd> --help 验证标志。
• 隔离：任何会启动 opencode 的 QA 都必须使用隔离的 XDG 沙箱，以免污染真实数据库。通过比较前后两次 sqlite3 "$(opencode db path)" "SELECT count(*) FROM session" 的结果来证明隔离有效。
• TUI 输出断言很脆弱；请使用 API 进行实际断言。

参考资料

• references/cli-commands.md - 与 QA 相关的所有 opencode 子命令和标志
• references/db-investigation.md - 数据库架构、经过测试的查询、25 GB 注意事项
• references/server-api.md - 服务启动、身份验证、路由目录、/doc
• references/events-hooks.md - SSE 端点、事件类型、插件钩子
• references/tui-tmux.md - tmux 方案、隔离、TUI 控制 API
• references/testing-harness.md - opencode 如何测试自身（bun test）
• references/sdk.md - @opencode-ai/sdk 客户端（仅供参考）
• references/docker-qa.md - 在一次性 Docker 容器中运行 QA（默认方式；本地运行是备用方案）