核心用法
sandbox-selfheal-guard 是一套面向 Agentic 沙箱环境的防挂死与自愈守护系统，专为解决容器化 AI 运行时的典型故障而设计。其核心工作流程分为预检修复（Self-Heal）与运行时保护（Guard）两个阶段：
预检修复阶段：通过 scripts/selfheal_runner.sh 库自动执行七项关键检查——系统依赖（cmake/g++/curl）补装、npx shim 防挂修复、llama.cpp 原生编译（含 AVX512/VNNI 指令优化）、四款 Qwen/DeepSeek GGUF 模型的字节级精确校验（非仅存在性检查）、以及认证令牌状态确认。任何缺失或损坏的组件均自动触发修复或重下载。
运行时保护阶段：每次模型调用均封装在 run_with_timeout 函数中，根据模型角色（SCOUT/SPARK/SAGE/FORGE）配置 60-150s 差异化超时，并建立 llama-completion → llama-simple → 退出码 2 的三级回退链。同时集成 SHA256 提示缓存层，重复查询可降至 0.06 秒响应。
轻量蜂群模式：对 8 词以内的 casual 对话自动降级为 SCOUT 单模型 2.2 秒快速响应，避免完整蜂群在简单任务上的资源浪费。
显著优点
1. 根治 Arena 类沙箱快照驱逐：精准识别 128MB/10k 文件快照上限导致的 2.4GB GGUF 模型与 build 目录丢失问题，从脚本层而非基础设施层解决问题。
2. 字节级完整性校验：超越简单的文件存在性检查，通过精确字节清单（如 484,220,320 字节）识别 HuggingFace 下载中断产生的 15 字节 HTML 错误页伪装成的损坏模型。
3. 性能优化闭环：原生编译（-DLLAMA_NATIVE=ON）带来 7-10% 的 prompt processing 提升；Flash Attention 启用（-fa on）在小型模型上实现 11-19% 的 token 生成加速；双核绑定（-t 2）避免超线程过度订阅导致的 42% 性能损失。
4. 生产级可观测性：全链路日志落盘 /tmp/selfheal.log，包含时间戳化的重建、重下载、超时回退事件，便于事后故障分析。
5. 丰富的集成测试：test_selfheal.sh 模拟六种典型故障场景（缺失二进制、缺失模型、截断模型、npx 挂死、模型超时、缓存命中），确保自愈逻辑的可靠性。
潜在缺点与局限性
1. 平台绑定较强：当前实现深度依赖 Ubuntu/Debian 系（apt-get）与 bash 环境，Alpine 或 Windows 容器需额外适配。
2. 模型清单固化：四款模型的字节校验清单硬编码于脚本中，用户自定义新增模型需修改源码，缺乏外部配置文件机制。
3. CPU 推理上限：虽通过指令集优化挖掘 CPU 极限，但 1.5B 模型仅 13 t/s、0.5B 模型 30-34 t/s 的吞吐量仍显著低于 GPU 方案，不适合高并发生产环境。
4. sudo 权限依赖：系统依赖补装需要 sudo 权限，在无特权容器或只读根文件系统环境中可能失效。
5. 缓存粒度较粗：SHA256 缓存基于完整提示文本匹配，对语义相同但表述微变的提示无法命中，存在优化空间。
适合的目标群体
- AI Arena / OpenClaw 等平台的高频用户：频繁遭遇"Agent 无限思考"或快照驱逐导致任务中断的开发者。
- 边缘 CPU 推理场景从业者：需在无 GPU 环境（树莓派、边缘服务器、低成本 VPS）稳定运行小参数 LLM 的工程师。
- Agent 工作流构建者：构建多步骤、长时间运行的自动化工作流，需要高可靠性底座而非单次交互玩具。
- llama.cpp 生态深度用户：希望获得经过调优的启动参数与防坑指南，而非从零摸索最佳实践。
使用风险
1. 网络重下载耗时：首次运行或模型校验失败时，从 HuggingFace 拉取 400MB-1.1GB 模型可能因网络波动耗时数分钟，超时窗口内需预留充足预算。
2. 原生编译资源消耗：llama.cpp 重建过程在双核容器上可能占用 100% CPU 持续 5-15 分钟，期间 Agent 响应能力受限。
3. 超时配置敏感度过高：过短的超时（如 SAGE 模型 60s）可能导致 legitimate 的深度推理被误判为挂死而中断，需根据实际任务复杂度微调。
4. 缓存未命中时的冷启动延迟：首次提示无缓存时，完整蜂群（4 模型并行）启动可能累积 8-10 秒延迟，对 latency-sensitive 场景需评估接受度。
5. 日志磁盘占用：高频自愈场景下 /tmp/selfheal.log 持续增长，长期运行需考虑日志轮转或清理策略。