用途：对 opencode 编码代理自身做质量验证。每个 QA 需求都被映射到已测试的辅助脚本与参考文档，脚本自带 --self-test，可与本机实况对照。已验证版本为 opencode v1.17.7（bun 1.3.12、macOS）；用 opencode --version 确认安装版本，并用 opencode <cmd> --help 核对参数。
隔离与安全规则：读取实时数据库是安全且被允许的，仅读 ~/.local/share/opencode/opencode.db。任何会 spawn opencode（serve、run、TUI）的操作都必须使用隔离的 XDG 沙箱，避免污染真实数据库；手工运行前须设置 XDG_DATA_HOME / XDG_CONFIG_HOME / XDG_STATE_HOME / XDG_CACHE_HOME 为临时目录。对 part 表的全局文本搜索是数 GB 扫描，必须用 --session、--recent 或 --since 限定范围，脚本会主动拒绝无界扫描。opencode 源码仓库测试只能用 bun test，且不能在仓库根目录运行。
使用方式：脚本位于 scripts/，从技能目录调用，先运行 bash scripts/lib/common.sh --self-check 确认依赖（opencode、sqlite3、curl、jq、tmux）。Docker 是默认 QA 环境，可用 script/agent/qa-docker.sh；本地脚本是 Docker 不可用或 Windows 时的回退。
主要用例：A 用 opencode run --format json 做非交互 CLI 验证，另有 --command、-c、--attach 等；B 通过 GET /event 的 SSE 事件证明钩子/动作/事件已触发，脚本 sse-hook-probe.sh 可对真实服务器边监听边触发；C 用 tui-smoke.sh 在 tmux 隔离沙箱中冒烟测试 TUI，视觉证据需走 docs/reference/web-terminal-visual-qa.md 用真实 xterm.js 渲染截图；D 只读排查数据库，按 id、标题或受范围的文本查找会话并用 export-roundtrip.sh 导出 JSON。
限制与注意：opencode export 的横幅写到 STDERR，需 2>/dev/null 后再接 jq。服务器仅在设置 OPENCODE_SERVER_PASSWORD 时鉴权，否则无鉴权，已鉴权调用用 -u opencode:$PASS，未鉴权访问受保护服务器返回 401。TUI 输出断言脆弱，真实行为断言应改用 run、server API + SSE 或 TUI 控制 HTTP API。隔离是否有效可用修改前后 session 计数比对来验证。参考资料覆盖 CLI、数据库排查、服务器 API、事件钩子、TUI/tmux、测试工具链、SDK 与 Docker。