用途
Smoke Test Skillpack 用于在机器或容器重启后、或系统疑似故障时，快速验证 gbrain 安装及配套服务的健康状况。文档建议在任何机器/容器重启后或出现问题时运行。
契约（保证能力）
- 8 项核心测试在重启后验证 gbrain 健康（当存在 OpenClaw 服务时一并检测，否则跳过）。
- 有界的本地失败会在报告前自动修复；worker 修复是显式操作，因为进程拓扑与 shell 作业策略属于运维方选择。
- 支持通过 ~/.gbrain/smoke-tests.d/*.sh 放置脚本进行用户扩展。
- 结果记录到 /tmp/gbrain-smoke-test.log。
- 退出码 = 未修复失败的数量（0 表示全部通过）。
内置测试
| # | 测试 | 自动修复 |
|---|---|---|
| 1 | Bun 运行时 | 从 bun.sh 安装 |
| 2 | GBrain CLI 加载 | 重装依赖 |
| 3 | GBrain 数据库（通过 gbrain engine status --json 确认引擎身份，再用 doctor --json 的连接检查） | gbrain db-repair --yes，然后重新测试 |
| 4 | GBrain worker 进程 | —（原生 supervisor 状态 + 重复检测） |
| 5 | OpenClaw Codex 插件（Zod CJS）；OpenClaw 不存在时跳过 | npm install zod@4 --force |
| 6 | OpenClaw 网关；OpenClaw 不存在时跳过 | —（可能尚未启动） |
| 7 | Embedding API 密钥 | —（检查 .env） |
| 8 | Brain 仓库存在 | — |
使用方式
CLI：
gbrain smoke-test
适用于所有安装；它会从已安装包中解析测试脚本。
从任意启动脚本或登录钩子运行：
gbrain smoke-test >> /tmp/bootstrap.log 2>&1
从 OpenClaw bootstrap（仅 OpenClaw 部署）：
加入你的 ensure-services.sh 或等价文件：
bash /path/to/gbrain/scripts/smoke-test.sh >> /tmp/bootstrap.log 2>&1
从 agent 调用：
exec: gbrain smoke-test
贡献者说明：在 gbrain 仓库检出目录内，也可以直接用 bash scripts/smoke-test.sh 运行脚本。
添加自定义测试
在 ~/.gbrain/smoke-tests.d/ 中创建可执行脚本，例如：
~/.gbrain/smoke-tests.d/check-redis.sh
#!/bin/bash redis-cli ping | grep -q PONG
规则：
- 退出码 0 = 通过，非零 = 失败。
- 文件名即测试名（例如 check-redis.sh 对应 check-redis）。
- 保持测试快速（每个 < 10 秒）。
- 测试按字母顺序运行。
添加内置测试（gbrain 贡献者）
本节面向在 gbrain 源码仓库中工作的贡献者。插件安装分发的是只读脚本，升级会覆盖它；若只想增加检查，请使用上面的 ~/.gbrain/smoke-tests.d/ 放置脚本。
编辑 scripts/smoke-test.sh，遵循以下模式：
── N. [Service Name] ──────────────────────────────────────
if [test condition]; then pass "[Service Name]" else
Auto-fix attempt
[fix command] if [re-test condition]; then fixed "[What was fixed]" pass "[Service Name] (after fix)" else fail "[Service Name] — [error detail]" fi fi
设计规则：
- 先测试 —— 未确认损坏前绝不修复。
- 修复后重新测试 —— 验证修复生效。
- 一切都要加超时 —— 对任何可能挂起的命令使用 timeout N。
- 使用辅助函数 —— pass()、fail()、fixed()、skip()。
- 修复幂等 —— 可安全重复运行。
- 优雅跳过 —— 缺少前置条件时用 skip()，而非 fail。
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
| GBRAIN_SMOKE_LOG | /tmp/gbrain-smoke-test.log | 日志文件路径 |
| GBRAIN_DIR_OVERRIDE | （自动检测） | 强制 gbrain 安装路径 |
| GBRAIN_BUN_PATH | （自动检测） | 强制 Bun 二进制路径 |
| GBRAIN_DATABASE_URL | （来自 .env） | 数据库连接 URL |
| GBRAIN_SMOKE_WORKER_PID_FILE | /tmp/gbrain-worker.pid | 传统 bare-worker PID 路径 |
| OPENCLAW_GATEWAY_PORT | 18789 | 要测试的网关端口 |
| GBRAIN_BRAIN_PATH | （部署相关） | Brain 仓库路径。容器部署默认 /data/brain；其他情况设为你的 brain 仓库路径。未设置时测试 8 跳过（而非失败）。 |
已知问题及其自动修复
Codex Zod core.cjs 缺失（2026-04-23 发现）： （仅适用于 OpenClaw 网关部署：这涉及 OpenClaw 的 Codex ACP 插件，而非 OpenAI Codex CLI。）
- 症状：Cannot find module './core.cjs' → 所有 Codex ACP 会话失败。
- 原因：Zod v4 npm 包在某些安装中未附带 core.cjs。
- 自动修复：在 codex 扩展的 zod 目录中执行 npm install zod@4 --force。
- 持久性：不会在容器重启后保留（网关会重装依赖）。
- 这正是每次重启都必须运行冒烟测试的原因。
GBrain Worker 鉴权失败：
- 症状：Worker 无法连接数据库。
- 原因：GBRAIN_DATABASE_URL 未传递给 worker 子进程。
- 自动修复：脚本显式同时传递 DATABASE_URL 和 GBRAIN_DATABASE_URL。
失败时的处理
遵循 agent 运维协议处理任何 gbrain 错误码、退出码、[AGENT] 块或通知块。本技能特定规则：
- 退出码 = 未修复失败的数量：按名称逐项报告并说明尝试过的修复；当有测试被跳过时，绝不要报告全绿。
- 数据库测试以 GBRAIN_DB_ACCESS 标记失败：运行 gbrain db-repair 并重新测试；rewrite 层级需要用户同意。
- Embedding API 密钥检查失败：没有自动修复。告知用户缺少哪个密钥，并说明在设置之前搜索仅使用关键词模式。
反模式
- ❌ 每一轮对话都运行冒烟测试。每次容器重启（或用户请求）运行一次足够。脚本虽便宜但并非免费。
- ❌ 编写用户放置脚本时，对任何可能挂起的命令不加 timeout N。单个挂起的放置脚本会拖住后续所有运行。
- ❌ 未先确认检查确实损坏就自动修复。pass → 检测失败 → 修复 → 重新测试 是契约；跳过重新测试的修复可能在实际仍损坏时报告成功。
- ❌ 把跳过当作失败。缺少前置条件（未安装 OpenClaw、未配置 brain 仓库）属于跳过，而非失败。退出码 = 真实失败数，不含跳过的检查。
- ❌ 在用户放置脚本中硬编码路径。读取环境变量（GBRAIN_DATABASE_URL、HOME 等），让脚本能跨容器重建迁移。
输出格式
脚本将每项检查的单行状态写入 stdout（✅/❌/🔧/⏭️），并输出最终汇总行：Results: N/M passed, F auto-fixed, S skipped。带时间戳的结构化日志追加到 $GBRAIN_SMOKE_LOG（默认 /tmp/gbrain-smoke-test.log）以供运行后取证。退出码等于未修复失败的数量（0 = 全部通过，正整数 = 剩余失败数）。