核心用法
sandbox-selfheal-guard 是一套面向容器化AI运行环境的可靠性基础设施，专为解决Arena.ai、OpenClaw等平台常见的"快照驱逐导致的Agent假死"问题而生。其核心工作流围绕预检自愈（pre-flight self-heal）机制展开：在每次模型调用前，系统自动执行五项校验——依赖包完整性（apt）、npx防挂 shim、llama.cpp原生编译优化、GGUF模型字节级校验，以及认证状态检查。任何异常均触发自动修复并记录日志，确保调用链路零中断。
执行层采用分层超时策略：SCOUT/SPARK/FORGE等轻量模型限定60秒，深度推理SAGE放宽至150秒，绝对硬顶300秒。超时后自动降级执行链：高性能llama-completion → 兼容模式llama-simple → 返回错误码2。配合v2.1.0新增的提示缓存层（prompt-cache），通过SHA256哈希命中可将重复推理耗时从2.1秒降至0.06秒，效率提升33倍。
轻量蜂群模式（light-swarm auto） 智能识别8词以内 casual 对话，仅激活2.2秒极速响应的SCOUT模型，避免完整蜂群在 trivial chat 场景下的资源浪费与挂起风险。
---
显著优点
1. 根治快照驱逐顽疾：精准识别128MB/10k文件上限触发的二进制驱逐场景，通过字节级manifest校验（非仅存在性检查）捕获15字节HTML错误页伪装成2.4GB模型的典型故障。
2. 原生性能释放：-DLLAMA_NATIVE=ON 编译标志自动启用AVX512/VNNI指令集，在兼容CPU上实现7-10%的prompt processing加速；线程数锁死物理核心数，避免超线程导致的42%吞吐量衰减。
3. 全链路可观测：/tmp/selfheal.log 记录每一次重建、重下载、缓存命中事件，配合测试套件test_selfheal.sh可模拟六种故障场景，实现故障复现与修复验证的标准化。
4. 零配置防御：220行的selfheal_runner.sh作为可source库嵌入任意调用脚本，无需改造现有Agent逻辑即可获得超时、回退、缓存、自愈能力。
---
潜在缺点与局限性
- 平台锁定倾向：shim机制与apt依赖管理深度绑定Debian/Ubuntu系容器，Alpine或其他发行版需手动适配包管理器。
- 网络单点依赖：模型重下载固定指向HuggingFace仓库，未内置镜像回退或P2P分发机制，大陆网络环境可能遭遇间歇性拉取失败。
- 缓存策略偏保守：SHA256全匹配要求，对语义相同但格式微变的提示无法去重，适合结构化输入场景，自由文本复用率受限。
- 日志未分级：所有事件写入同一文件，高并发场景下可能产生竞写，需外部logrotate配合。
---
适合目标群体
- 容器化AI平台开发者：运营Arena类沙箱环境，需保证多租户场景下的推理服务稳定性。
- 边缘CPU推理用户：在AVX512-capable裸金属或vCPU上追求llama.cpp极致吞吐的效能敏感型团队。
- 自动化Agent构建者：构建长周期自主运行Agent，需防御"思考 forever"类僵尸状态导致的人工干预成本。
- 模型即服务（MaaS）运维：管理多版本GGUF模型分发，需字节级完整性校验保障推理一致性。
---
常规使用风险
性能风险：cmake --build原生重编译在2核容器上可能耗时5-8分钟，首次启动或镜像更新后触发用户可见延迟；建议配合预 baked 镜像或延长健康检查阈值。
依赖风险：sudo apt-get要求容器以privileged模式或特定capabilities运行，与部分平台的安全策略冲突，可能触发权限拒绝导致自愈链断裂。
模型漂移风险：硬编码的四模型manifest随上游版本迭代可能失效，需定期更新skill版本以同步字节校验基准。
缓存污染风险：/tmp挂载若为tmpfs，容器重启导致缓存失效，与"长期驻留"预期存在张力；建议结合openclaw-cache-kit实现持久化存储层。