openclaw-crabbox

Crabbox

• PR CI = 默认的全面验证。 首先：运行有针对性的本地测试，以及定向的 lint、类型检查和格式检查。检查通过且更改可构建：打开一个可合并的 PR；CI 会运行全面测试套件。绝不要为了运行 PR 前的测试套件而延迟提交 PR。
• 仅当 CI／本地覆盖存在缺口时才使用 Box：其他 OS／设备、实时提供商／频道、耗时较长的 E2E、重量级基准测试。只有在命令已准备就绪且能立即获批时才获取。
• 排队时：停止由任务发起的请求；改为在本地运行。绝不要等待队列，也不要依次尝试 Testbox → AWS → 其他提供商。
• 修复真实故障；绝不要只为获得绿色状态而重新运行或重新推送。将故障归因于更改前，先阅读可用的 CI 故障分类信息。

仓库约定

• Skill 负责可移植的路由、租约、同步、命令和清理。
• 从可信的使用方说明、包脚本或 hydration 工作流中解析 <check-command>、运行时／容器镜像、PR 和引导流程。
• 绝不要臆造缺失的命令，也不要照搬其他使用方的设置。
• 始终报告提供商、ID、运行 URL、命令和结果。绝不要称 Testbox 为 “AWS Crabbox”，也不要把本地 Docker 说成远程验证。

授权与隔离

• 常规的已配置用法：创建／复用／停止任务自有的租约、临时状态目录，以及用于验证或必需 Crabbox 修复的干净检出／工作树；无需另行审批。

• 保留用户的检出、分支和无关编辑；检出有改动、缺失或被占用时，使用任务自有的检出。

• 遵守来源信任、凭证、生产环境访问和预算边界，以及发布边界。

• 绝不要在本地或凭证 hydration 后的 Testbox 上执行不可信仓库中的封装脚本／配置。使用无密钥的 fork CI 或经过净化的直接 AWS：每个完整的 head SHA 使用一个全新租约；不使用实例角色、Tailscale 或 hydration；只转发 CI。

• 在 AWS 上执行不可信内容前：阅读并遵循完整的不可信配方，包括无角色和 SHA 证明。无法提供证明时：使用无密钥的 fork CI。

• 实时凭证：精确的密钥，仅用于一条命令，并且只能通过安全方式注入。绝不要打印密钥、将其写入仓库文件／shell 历史记录，或将虚假密钥称为实时验证。没有安全的注入途径：实时认证受阻。检查捕获的产物，确认其中不含密钥。

• 将验证隔离在使用方的临时状态／配置目录中；绝不要修改操作员的常规安装。使用后停止自有租约，包括发生故障时。

优先选择路由

• 来源信任会限制可用提供商，但不会替你选择提供商。检查并保留已解析的提供商。
• 通常省略 --provider；只有在明确要求或验证需要后端语义时才覆盖。绝不要为了调整大小、时长、hydration 故障或容量而覆盖。
• 不要试探性预热，也不要升级到其他提供商。

提供商	用途
blacksmith-testbox	已准备好 CI 的可信维护者来源；tbx_...
aws	直接经由 broker 执行、新 PR、自定义同步／环境／捕获；cbx_...
local-container	已配置／按要求使用本地 Docker；不属于远程验证
ssh	操作员现有的 macOS／Windows／WSL2 主机

预检

从仓库根目录选择一个可信的已安装二进制文件：

export CRABBOX="$(command -v crabbox)"
test -n "$CRABBOX"
"$CRABBOX" --version
"$CRABBOX" config show --json | jq '{provider, profile, target}'
"$CRABBOX" run --help

• 读取 .crabbox.yaml 和已解析的配置，包括用户／环境设置。
• Testbox：还要检查 command -v blacksmith 和 blacksmith --version。
• 使用方可以指定可信封装脚本；若缺失／损坏：遵循可信的安装／更新途径；在干净的任务检出中构建前，验证规范上游来源。
• 绝不要假设同级检出可信，也不要用任务构建的二进制文件替换操作员的二进制文件。
• 在同一已解析提供商上，使用已安装的 CLI 隔离封装脚本故障。

可信 Testbox

仅适用于已解析/请求的 Testbox。提供方中立的命令会保留配置； 仅在明确覆盖时添加 --provider blacksmith-testbox。

"$CRABBOX" run --timing-json -- CI=1 <check-command>

多个命令：保存 ID、复用、停止：

"$CRABBOX" warmup --keep --timing-json
"$CRABBOX" run --id <tbx_id> --timing-json -- <check-command>
"$CRABBOX" stop <tbx_id>

• 一个租约对应一个活动命令；运行期间不要同步/回收。--reclaim 仅用于有意转移结账路径的所有权。
• 即使复用了 ID，Testbox 原生运行也会同步。基线测试时切勿依赖 --no-sync，即使是未更改的重跑也不行；该选项可能会被静默忽略。
• 基础版本/目标版本已更改：停止并重新预热；切勿覆盖过期租约。warmup --ref：仅接受分支/标签，绝不接受原始 SHA。切勿在已同步的根目录中检出引用。
• Testbox 原生状态/停止命令：使用 --id；状态命令没有 --json。使用 blacksmith testbox list --all 或 blacksmith testbox status --id <tbx_id>。
• 委派的 Testbox 不接受 --fresh-pr、--full-resync、--script*、--env-helper 和捕获/下载标志。Crabbox stop 不接受 --timing-json。

验证已同步的输入

• 缺少模块/测试夹具：将所需输入与冻结的源代码进行比较；检查同步排除项，包括 Git 忽略规则中的否定项。同步成功也可能遗漏已跟踪文件。
• 记录每个缺失路径及其冻结的 Git blob。仅将经过审查的必需输入恢复到任务专属的远程检出目录；验证字节内容。另行处理已更改/未跟踪的输入。每次原生同步后都要重新检查。
• 切勿重新生成基线、复制无关状态、禁用排除项，或假设所有缺失文件都安全。
• 同步超时 ≠ 测试结果。确认是否已派发负载；若不确定，先检查租约/调用记录再重试。按源代码身份保留已完成的证明；仅运行缺失的验证。

专项证明与诊断

仅阅读相关指南；路由和即时可用性规则仍然适用：

• 直接 AWS、容器、桌面和跨操作系统：精确的提供方命令、代理身份验证、付费 macOS 配额/支出前检查、桌面交接。不得静默替换；切勿将证明资产提交到产品仓库。
• 诊断与真实端到端测试：捕获/环境标志、故障层级、用户路径证明。“在 Crabbox 中测试”=真实的安装/更新/引导/CLI/服务/API 路径，而不只是远程单元测试。全屏 CLI：使用真实 PTY。在同一次已同步调用中，使用分离的临时工作树比较 Testbox 修订版本；后续运行会重新同步本地源代码。