沙箱隔离
Sandbox Isolation
Agent 执行代码时如何隔离环境，防止宿主机污染。安全性和便利性的平衡。
子问题
1.代码执行隔离：用户代码在沙箱中运行，不影响宿主机
2.文件系统隔离：Agent 只能访问指定目录
3.网络隔离：限制 Agent 的网络访问范围
4.资源限制：CPU、内存、执行时间的限制
5.环境一致性：沙箱环境与目标环境的一致性
6.变量声明作用域泄露：vm.Context 中 const/let 不挂全局，需 AST 转 globalThis
7.跨 turn 状态传递：沙箱每次执行需要访问上一次的返回值和持久化数据
8.工具热更新与不可变冲突：内置工具不可覆盖但 Action 列表需要动态更新
9.LLM 代码围栏剥离：LLM 输出常带 markdown 代码块标记需要预处理
10.Symlink 逃逸防护：共享依赖的 symlink 可能 resolve 到 workspace 外部
11.Session 恢复隔离：崩溃 session 的 workspace 和 runtime 需要独立恢复而非重建
12.Hash 命名空间碰撞：多 orchestrator 实例共享同一台机器时的 tmux/目录名冲突
13.长命令传输截断：tmux send-keys 对超过 200 字符的命令会截断，需要 load-buffer 绕过
14.双运行时切换：如何在 subprocess 和容器沙箱间无缝切换，保持工具接口一致
15.VNC GUI 沙箱：容器内运行浏览器自动化和 GUI 应用的远程桌面方案
16.异步并发限流：高并发下如何限制同时运行的 subprocess 数量，避免进程爆炸
17.产物回收：沙箱中生成的文件需要下载到宿主机才能提交评估
18.迭代超限兜底：Agent 达到步数上限时自动扫描并提交已有产物
19.参考文件双写：任务附件需同时存在于宿主机和沙箱中
20.二进制文件安全：下载 PNG/DOCX 等二进制文件需用 bytes 模式防止损坏
21.自定义模板预热：高频依赖包预装到镜像避免运行时安装延迟
22.大文件传输：base64 编码后超过 ARG_MAX 限制需要 heredoc stdin 绕过
23.timeout 向后兼容：旧版 Backend 不支持 timeout 参数需要 inspect.signature 运行时检测
24.模板自动创建：沙箱模板不存在时需要自动创建而非报错
25.setup script 宿主机变量展开：${VAR} 需在宿主机侧解析避免在沙箱内暴露环境变量获取能力
26.跨平台命令过滤：同一黑名单需覆盖 POSIX（rm -rf）和 Windows（del /f）命令变体
27.双系统独立防御：MCP Server 和 Agent 框架各自实现安全检查，如何保持一致性
28.导入控制：限制代码可 import 的模块，防止调用危险 API
29.意图转代码隔离：LLM 将用户意图转为代码再执行，避免直接注入
30.跨进程沙箱发现：多 worker 进程需要找到同一 thread 的已有沙箱，避免重复创建
31.多运行时适配：同一代码需要在 macOS Apple Container、Docker、K8s 三种运行时下工作
32.空闲沙箱回收：守护线程定期扫描超时沙箱的轮询间隔与误杀风险
33.信号链式传递：自定义 SIGTERM handler 清理后需恢复原始 handler 避免吞信号
34.环境变量引用解析：配置中 $VAR 引用需在容器启动前从宿主机 env 解析
35.健康检查轮询：容器启动后 wait_for_ready 的超时与轮询间隔平衡
36.路径前缀重叠：repo_root 尾部与输入路径头部相同时的歧义解析
37.子代理递归生成：子代理若能 spawn 新子代理会导致无限递归资源耗尽
38.Kernel 死亡恢复：Jupyter Kernel 崩溃后如何快速重建并恢复执行上下文
39.编辑语法防护：LLM 生成的代码编辑可能引入语法错误，需要 lint 前后对比和自动回滚
40.输出截断策略：成功输出取头部、错误输出取尾部，不同截断方向影响 LLM 理解
41.GPU VRAM 自适应：不同显存容量需要不同的 batch size 和 memory utilization 参数
42.区域感知镜像：模型下载源在不同地区不可达，需要双镜像策略
43.多加速器适配：同一代码需支持 CUDA/MPS/NPU/GCU/MUSA/MLU/SDAA 七种加速器
44.推理并发控制：GPU 推理请求并发过高导致 VRAM OOM，需要请求级限流
45.容器 daemon 腐败恢复：Apple Container daemon 异常时自动降级到 Docker
46.确定性镜像重建：用户删除本地镜像后根据配置哈希自动重建
47.host fallback 包安装：无容器运行时时在 Debian host 上直接 apt-get 安装
48.秘密值编码泄露：LLM 可能通过 base64/hex 编码绕过 raw 值脱敏
49.容器代际命名冲突：stale 容器占用名称时通过代际后缀避免阻塞
50.配置漂移检测：运行中容器的配置与期望配置不一致时如何感知和修复
51.浏览器隔离：Agent 控制的浏览器需要独立网络和认证机制
52.工具访问控制：沙箱内 Agent 可使用的工具需要细粒度 allow/deny 策略
53.沙箱池化冷启动：idle queue 为空时创建新沙箱的延迟优化
54.执行队列过载：高并发下队列满时的请求拒绝与反压策略
55.大代码传输：超过 shell 参数长度限制的代码需要文件中转
56.S3 凭证生命周期：沙箱内临时凭证的写入时机与自动清理
57.暂停态恢复：paused 沙箱 reconnect 后的状态一致性验证
58.字符串匹配绕过：excludeTools 基于简单字符串匹配，命令变体（如双空格、别名）可绕过黑名单
59.多入口配置一致性：CLI flag、环境变量、settings.json 三入口需要统一的优先级解析，避免配置冲突
60.macOS 原生沙箱与 Docker 沙箱的能力差异：两种运行时的隔离粒度和文件系统行为不同
61.先保存后禁用：猴子补丁禁用 API 后临时目录清理函数也失效，需提前保存引用
62.平台 rlimit 差异：macOS 不支持 RLIMIT_AS 导致内存保护层在开发机上失效
63.eval 表达式沙箱：推理时计算器需要比 exec 更轻量的隔离（空 builtins + 白名单）
64.幂运算拒绝服务：9**9**9 等指数爆炸表达式需要在 eval 前显式拦截
各项目的解法18 solutions
横向对比
| 维度 | DeerFlow | MiroThinker | AIRI | Agent-Orchestrator | AgentScope | ClawWork | DeepAgents | DeepCode | DeepResearch | DeepTutor | FastCode | MetaGPT | MinerU | Moltis | OpenClaw | Refly | iflow-cli | nanochat |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 隔离级别 | Provider+Sandbox 双层抽象（Local subprocess / Aio Docker） | E2B 云沙箱（完全隔离） | Node.js vm.Context 进程内隔离，无 require/process 访问 | 进程级：git worktree 文件隔离 + tmux/child_process 进程隔离，无容器 | subprocess 进程隔离 + 可选容器隔离（agentscope-runtime） | E2B 云 VM 级隔离，代码在独立虚拟机执行 | 远程容器/VM 级隔离，四种云提供商（Daytona/LangSmith/Modal/Runloop） | 进程级软隔离：subprocess + Path.resolve() 边界检查，无容器 | — | 进程级：subprocess.run + tempfile 临时目录，生产环境叠加 Docker 容器 | 应用层路径检查 + 命令正则黑名单，无 OS 级隔离 | 三层递进：subprocess 进程级 → Jupyter Kernel 级 → Docker 容器级 | Docker 容器级隔离，无进程级沙箱 | 四后端：Docker 容器、Apple Container VM、Linux cgroup v2、NoSandbox 直通 | Docker 容器级：read-only root + cap-drop ALL + no-new-privileges + 独立浏览器容器 | Scalebox 云沙箱进程级隔离 + S3 FUSE 文件系统隔离 | Docker 容器级隔离，shell 命令和文件修改在容器内执行 | multiprocessing.Process 进程级隔离，无容器/VM |
| 虚拟路径 | /mnt/user-data/* 双层翻译 + 输出反向翻译 | 无（直接操作沙箱内路径） | — | 无虚拟路径，Agent 直接操作真实 worktree 路径 | — | 无虚拟路径翻译，Agent 直接使用沙箱内真实路径 | — | 无虚拟路径，直接使用真实路径 + startswith 前缀检查 | — | 无虚拟路径翻译，直接使用 allowed_roots 白名单校验真实路径 | 无虚拟路径，直接用 repo_root 前缀检查 startswith | WorkspaceConfig 统一 workspace 路径，SWE_CMD_WORK_DIR 限制操作范围 | — | 沙箱内固定 /home/sandbox，host 绝对路径被拒绝或重写 | 双向翻译：host↔container 路径通过挂载点匹配，支持 workspace/agent/bind 三种挂载源 | — | — | tempfile.TemporaryDirectory 临时目录，执行后自动删除 |
| 生命周期管理 | SandboxMiddleware 懒初始化 + 空闲超时回收 600s | 每任务独立实例 + DEFAULT_TIMEOUT=600s | — | Session Manager 正序创建逆序销毁 + 每步回滚 + restore 恢复 | 临时文件自动清理（TemporaryDirectory），进程执行后立即销毁 | SessionSandbox 单例 + 任务级 cleanup + 会话级 reset 双层清理 | SandboxProvider.get_or_create + delete，context manager 自动清理，条件清理（只删自己创建的） | 无显式生命周期，workspace 随进程存在，tempfile 用后即删 | — | 懒初始化 + TemporaryDirectory 上下文管理器自动清理 | 工具实例随 AgentLoop 创建，子代理工具随任务创建销毁 | ExecuteNbCode 三态管理 build/terminate/reset，DataInterpreter 结束时显式 terminate | Compose profiles 按需启动，restart: always 自动恢复 | SandboxRouter per-session 路由 + FailoverSandbox 自动降级 | 配置 hash 驱动重建 + JSON registry 持久化 + 空闲24h/存活7天自动修剪 | Redis idle queue 池化 + BullMQ auto-pause/kill 调度 | 默认禁用，显式启用；预构建镜像 + 按需自定义构建 | 一次性进程：每次 execute_code 创建新进程，执行完即销毁 |
| 防御性设计 | 结构化异常体系（SandboxError 层级） | INVALID_SANDBOX_IDS 黑名单 + 结果/错误截断 | deepFreeze+toStructuredClone 双重冻结，数据完全只读 | SAFE_PATH_SEGMENT 白名单 + symlink 双重路径校验 + hash 碰撞检测 | UTF-8 强制编码，无缓冲输出（-u），terminate 优雅终止 | 健康检查探活 files.list('/') + 死沙箱自动重建 | — | 双层防御：MCP 字符串黑名单 + Nanobot 正则黑名单 + 路径遍历检测 | — | 三层纵深：ImportGuard(AST) + 路径白名单 + subprocess 超时 | PathUtils 异常默认拒绝 + deny_patterns 8 类危险命令 | forbidden_commands 命令黑名单 + flake8 lint guard 编辑回滚 + 输出截断防 token 溢出 | 路径遍历过滤 + UUID 目录隔离 + 后台自动清理 | SSRF DNS 解析后 IP 检查 + CIDR 白名单 + 三重编码 secret 脱敏 | 5 层纵深防御：bind 黑名单 + symlink 逃逸防护 + env 清洗 + 网络/seccomp/apparmor 校验 | 三层分布式锁 + 队列过载保护 + 资源限制四维度 | 三层纵深：Docker 隔离 + 工具过滤 + Hook 拦截，文档警告黑名单可绕过 | 三层纵深：API 猴子补丁(30+函数) + rlimit 内存 + 双重超时 |
| 代码修复 | 无 | validate_and_fix() LLM 自动修复（最多 2 次） | TypeScript AST 规范化 const→globalThis，表达式自动 return | 无自动代码修复，依赖 Agent 自身能力 | — | 无自动代码修复，执行失败返回错误由 Agent 自行重试 | — | 无自动修复，execute_python 失败后由 LLM 迭代修改代码 | — | ToolAgent 检测 exit_code 失败后添加错误前缀提示路径修正 | 无自动代码修复，EditFileTool 仅做唯一性检查 | edit_linting.sh 编辑前后 flake8 对比，新增语法错误自动回滚到备份 | — | — | 热容器保护：5 分钟窗口内不自动重建，提示 CLI 命令手动操作 | ModuleNotFoundError 自动安装缺失包后重试 | — | 无自动修复，仅返回 ExecutionResult 供调用方判断 |
| 资源限制 | — | — | 750ms 超时 + 5 次/turn 动作数上限 | — | 超时保护（默认 300s），无内存/CPU 限制（需自行添加 rlimit） | — | 默认 30 分钟执行超时（_default_timeout=1800s），execute_accepts_timeout 兼容旧版后端 | — | — | — | — | — | — | — | — | — | — | RLIMIT_AS/DATA/STACK 三重 256MB + 5s 超时，macOS 跳过 rlimit |
| 工具访问控制 | 工具层统一入口：5 个 @tool 函数均经过 ensure_sandbox_initialized 门控 | — | 两层注入：内置不可变 + Action 可热更新，Zod schema 校验 | 无沙箱内工具限制，Agent 拥有 workspace 内完整权限 | — | — | — | 配置驱动：restrict_to_workspace 开关统一控制文件和 shell 工具 | — | — | 子代理裁剪 message/spawn/cron，prompt+工具双重限制 | SWE-Agent 命令集白名单（open/edit/search/submit），Terminal forbidden_commands 黑名单 | — | ApprovalManager 对非沙箱命令做人工审批，沙箱内跳过 | glob 模式 allow/deny 列表，agent > global > default 三级优先级 | BuiltinExecuteCode 工具级 allow/deny + 预装包白名单 | coreTools 白名单 + excludeTools 黑名单 + ShellTool(cmd) 命令级粒度 | — |
| 导入控制 | — | — | vm.Context 天然隔离，无 require/import 可用 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | sys.modules 置 None 禁用 5 个模块(ipdb/joblib/resource/psutil/tkinter) |
| Scope 粒度 | 线程级隔离：每个 thread_id 独立 workspace/uploads/outputs 三目录 | — | 单 vm.Context 实例复用，mem 对象跨 turn 持久化 | per-session：每个 Issue/任务一个独立 worktree + runtime | — | 会话级单例，同一任务多次调用共享文件系统 | — | workspace 级别，所有工具共享同一 workspace 边界 | — | — | workspace 级别，restrict_to_workspace 布尔开关控制 | 按角色分层：Engineer 用 subprocess，DataInterpreter 用 Kernel，SWE-Agent 用 Terminal | — | Session/Agent/Shared 三级 scope + per-session override | 三种模式：session（每会话）/ agent（每 Agent）/ shared（全局共享） | 用户+画布级锁隔离，同一画布串行执行 | Sub Agent 级权限继承控制（isInheritTools/isInheritMcps） | — |
| 输入过滤 | — | — | extractJavaScriptCandidate 剥离 markdown 代码围栏 | — | 无输入过滤，直接执行用户代码（依赖 LLM 生成安全代码） | — | base64 编码防止 shell 注入，shlex.quote 转义 grep 参数，路径验证（partner 包检查 startswith /） | — | — | — | — | — | — | — | — | — | — | engine.py 计算器用字符白名单+危险模式黑名单+方法白名单三重过滤 |
| 上下文持久化 | FileSandboxStateStore JSON + fcntl，预留 Redis 扩展点 | — | mem 对象 + prevRun.returnRaw 跨 turn 传递状态 | — | 无状态，每次执行独立进程，不保留全局变量 | 沙箱内文件跨调用持久，uploaded_reference_files 字典跟踪 | — | — | — | — | — | — | — | HomePersistence 三模式：Off/Session/Shared，host 目录 bind mount | — | CodeContext ID 跨调用变量持久 + 优雅降级到无状态 | — | — |
| 双层沙箱 | — | — | 无双层，单层 vm.Context + 应用层防御 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | execution.py 进程沙箱(评估) + engine.py eval 沙箱(推理计算器) |
| 跨进程发现 | 确定性 ID（sha256(thread_id)[:8]）+ FileSandboxStateStore + fcntl 文件锁 | — | — | Hash 命名空间 + metadata flat-file 实现跨进程 session 发现 | — | — | — | 不涉及：MCP Server 和 Nanobot 是独立进程，各自管理 workspace | — | — | 不涉及，单进程内 asyncio 任务管理 | — | — | SandboxRouter 集中管理所有 session 的沙箱状态，无需跨进程发现 | — | — | — | — |
| 多运行时支持 | 自动检测 Apple Container / Docker，K8s 通过 RemoteSandboxBackend + Provisioner | — | — | 插件化：tmux 和 process 两种 runtime，通过 YAML 配置切换 | subprocess（开发）+ Docker/K8s（生产）双运行时 | — | 四种远程沙箱提供商统一为 SandboxBackendProtocol，BaseSandbox 模板方法使子类只需实现 execute() | 支持 Docker Compose 部署，但沙箱逻辑不区分运行时 | — | — | 不涉及，纯 Python 应用层实现 | subprocess 本地执行 + Docker 容器部署，无 K8s/Apple Container 原生支持 | 7 种加速器自动检测：CUDA/MPS/NPU/GCU/MUSA/MLU/SDAA | auto_detect_backend 自动探测 Apple Container → Docker → NoSandbox | — | 单一 Scalebox 云运行时，双模板 executor/interpreter | Docker + macOS 原生沙箱（.sb profile），双运行时适配 | — |
| 跨平台命令过滤 | — | — | — | 无命令过滤，postCreate 钩子以 trusted config 身份执行 | 无命令黑名单，依赖操作系统权限控制 | — | — | deny_patterns 同时覆盖 POSIX 和 Windows 命令模式 | — | — | deny_patterns 同时覆盖 POSIX rm/dd 和 Windows del/rmdir | Terminal 区分 win(cmd.exe)/unix(bash)，forbidden_commands 统一拦截 | — | — | — | — | — | — |
| 异步并发 | — | — | — | — | 全异步设计（asyncio），支持高并发执行 | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 结构化输出 | — | — | — | — | XML 标签格式（<returncode><stdout><stderr>），LLM 友好 | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 文件追踪 | — | — | — | — | — | ARTIFACT_PATH: stdout 标记协议 + 扩展名白名单扫描 | — | — | — | — | — | — | — | — | — | 双轨：executor diff 实际追踪 + 正则预测式元数据提取 | — | — |
| 资源池化 | 空闲超时回收（默认 600s），守护线程 60s 轮询 | — | — | — | — | 无池化，按需创建单个沙箱，3600s 超时自动回收 | — | — | — | — | — | — | Semaphore 并发控制，无预创建沙箱池 | 确定性 SHA256 镜像标签避免重复构建，删除后按需自动重建 | — | Redis idle queue + auto-pause 2min + 最大10沙箱池 | — | — |
| 产物回收机制 | — | — | — | — | — | WrapUp LangGraph 工作流：扫描→LLM选择→下载→提交 | upload_files/download_files 批量操作，支持 partial success，FileOperationError 标准化错误码 | — | — | — | — | — | — | — | — | — | — | — |
| 自定义模板 | Pydantic SandboxConfig 12 字段，image/mounts/environment 全可配 | — | — | — | — | gdpval-workspace 预装 20+ 包，基于 220 任务分析定制 | LangSmithProvider 自动检测并创建模板（DEFAULT_TEMPLATE_NAME + python:3 镜像） | — | — | — | — | — | 双区域 Dockerfile 模板，构建时模型预热 | — | — | — | .iflow/sandbox.Dockerfile + BUILD_SANDBOX=1 自动构建 | — |
| 配置驱动选择 | resolve_class 动态加载 Provider，切换模式只改 config.yaml | — | — | — | — | — | provider 字符串参数选择后端，_get_provider 工厂延迟导入，_PROVIDER_TO_WORKING_DIR 映射工作目录 | — | — | — | — | — | 环境变量驱动设备/VRAM/并发参数，支持运行时覆盖 | — | — | — | CLI flag / 环境变量 / settings.json 三入口，6 级优先级链 | — |
| 健康检查 | — | — | — | — | — | — | echo ready 轮询，2s 间隔，timeout//2 次重试，失败则删除沙箱并 raise RuntimeError | — | — | — | — | — | Docker healthcheck curl /health，30s 间隔 3 次重试 | — | — | — | 遥测系统追踪 sandbox_enabled 状态，OpenTelemetry + Jaeger 可视化 | — |
| 大文件传输 | — | — | — | — | — | — | heredoc + base64 双重编码绕过 ARG_MAX 限制，支持 >100KB 文件的 write/edit/read | — | — | — | — | — | — | — | — | — | — | — |
| 双系统独立防御 | — | — | — | — | — | — | — | — | — | — | FastCode PathUtils 和 Nanobot allowed_dir 各自独立实现路径检查 | — | — | — | — | — | — | — |
| 路径重叠解析 | — | — | — | — | — | — | — | — | — | — | resolve_path 智能去重，处理 repo_root 与输入路径前缀重叠 | — | — | — | — | — | — | — |
| GPU自适应资源 | — | — | — | — | — | — | — | — | — | — | — | — | VRAM 检测 → 动态 batch size + memory utilization | — | — | — | — | — |
| 区域感知部署 | — | — | — | — | — | — | — | — | — | — | — | — | global/china 双 Dockerfile + 双模型源 | — | — | — | — | — |
| 容器代际命名 | — | — | — | — | — | — | — | — | — | — | — | — | — | Apple Container 冲突时 bump_container_generation 追加 -g{N} 后缀 | — | — | — | — |
最佳实践
1.双层抽象是最佳实践：Provider 管生命周期、Sandbox 管操作，DeerFlow 的模式值得借鉴
2.虚拟路径必须双向翻译：输入翻译 + 输出反向翻译，否则 Agent 看到真实路径会混乱
3.懒初始化节省资源：不是所有 Agent 都需要沙箱，首次工具调用才创建
4.设置执行超时：MiroThinker 600s、博客场景 30s，防止死循环耗尽资源
5.防御 LLM 幻觉：INVALID_SANDBOX_IDS 黑名单是简单有效的防御手段
6.结果截断保护：输出超过阈值自动截断，避免 token 爆炸
7.toStructuredClone + deepFreeze 双重防护：先切断引用再冻结，比单独使用任一方更安全
8.Zod 校验失败返回结构化错误而非抛异常：让 LLM 代码可以 if(!ok) 做降级处理
9.用 TypeScript AST 做代码规范化比正则替换更可靠：能正确处理解构赋值等复杂语法
10.路径段白名单优于黑名单：SAFE_PATH_SEGMENT 正则只允许安全字符，比过滤危险字符更可靠
11.进程组隔离（detached + kill -pgid）确保 shell 子命令也被终止，不留孤儿进程
12.创建-销毁对称性：正序创建逆序销毁 + 每步失败回滚，防止资源泄漏
13.Symlink 需要双重校验：原始路径不含 .. 且 resolve 后仍在 workspace 内
14.临时文件用 shortuuid 命名：避免并发执行时的文件名冲突
15.强制 UTF-8 编码：PYTHONUTF8=1 + PYTHONIOENCODING=utf-8 解决跨平台字符问题
16.XML 标签输出：比 JSON 更适合 LLM 解析，无需转义特殊字符
17.异步优先设计：全部用 async/await，支持高并发场景
18.ARTIFACT_PATH stdout 协议让 Agent 自主声明产物，比固定目录扫描更灵活
19.健康检查用 files.list('/') 探活比捕获执行异常更快发现死沙箱
20.二进制文件下载必须用 format='bytes'，text 模式会损坏 PNG/DOCX
21.迭代超限时用 LLM 分析对话历史选择产物，比全量提交更精准
22.单方法抽象最小化适配成本：BaseSandbox 将 8 个文件操作转为 shell 命令，新提供商只需实现 execute() 约 30 行代码
23.条件清理防止误删共享沙箱：should_cleanup = sandbox_id is None，只清理自己创建的沙箱
24.heredoc 传输绕过 ARG_MAX：用 stdin 而非命令参数传递大文件内容，避免 >100KB 文件操作失败
25.正则黑名单优于字符串匹配：\brm\s+-[rf]{1,2}\b 能匹配 rm -rf 的各种变体，避免简单 in 检查被绕过
26.配置驱动隔离开关：restrict_to_workspace 允许开发时关闭、生产时开启，兼顾便利和安全
27.AST 静态分析 import 白名单是零开销的预执行安全检查，适合补充进程隔离
28.配置加载优先级链（环境变量 > 模块配置 > 全局配置 > 默认值）让同一套代码适配多种部署环境
29.LLM 意图→代码转换比直接执行用户输入更安全，ToolAgent 的 _generate_code_from_intent 模式值得借鉴
30.确定性 ID 是跨进程发现的关键：sha256(thread_id) 让所有进程推导出相同的沙箱标识
31.三层一致性获取（进程缓存→状态存储→后端发现）兼顾性能和正确性
32.技能目录只读挂载（read_only=True）防止沙箱内代码篡改共享资源
33.确定性 ID 是跨进程发现的关键：SHA256(thread_id) 让所有进程推导出相同 sandbox_id
34.三层 fallback 保证一致性：进程缓存 → 文件锁+持久化 → 后端发现，逐层降速但覆盖更广
35.信号处理必须链式调用：保存原始 handler，自身清理后恢复，避免吞掉其他组件的信号
36.配置驱动 Provider 选择：resolve_class 动态加载，开发用 Local、生产用 Aio，零代码切换
37.路径安全检查应集中到一个工具类，避免每个工具重复实现
38.子代理工具裁剪 + prompt 声明形成双重限制，比单一手段更可靠
39.命令黑名单应同时覆盖 POSIX 和 Windows 变体，一份列表跨平台
40.按角色分层选择隔离级别：轻量脚本用 subprocess，交互式分析用 Jupyter Kernel，生产部署用 Docker
41.编辑操作加 lint guard：flake8 前后对比，新增语法错误自动回滚，防止 LLM 破坏代码
42.输出截断要区分方向：成功取头部（有用信息在前）、失败取尾部（错误信息在后）
43.构建时预下载模型到镜像层，运行时设置 MODEL_SOURCE=local 实现零网络依赖启动
44.ENTRYPOINT 使用 exec "$@" 透传模式，让 Compose 的 entrypoint+command 灵活覆盖
45.VRAM 检测支持环境变量覆盖，方便在 CI/CD 或虚拟化环境中模拟不同显卡
46.Compose profiles 将多服务声明在同一文件中按需启动，比多个 compose 文件更易维护
47.FailoverSandbox 装饰器模式：primary 失败自动切 fallback，一旦降级不再回退
48.SHA256(Dockerfile) 作为镜像 tag：相同配置不重复构建，删除后可自动重建
49.SSRF 检查必须在 DNS 解析后做：直接检查域名无法防御 DNS rebinding
50.secret 脱敏需覆盖 raw + base64 + hex 三种编码：防止 LLM 通过编码变换泄露
51.SandboxRouter 即使 mode=Off 也创建真实后端：per-session override 可能动态启用沙箱
52.配置 hash 检测漂移：SHA256(normalize(config)) 对比容器 label，冷容器自动重建
53.热容器保护窗口：最近使用的容器不自动重建，避免中断正在执行的任务
54.环境变量三层过滤：正则黑名单 + 值校验（null byte/超长/base64）+ 可选严格白名单
55.原子注册表写入：临时文件 + rename 防止并发写入损坏，写锁防止竞态
56.Symlink 逃逸防护：realpathSync 解析符号链接后再次校验黑名单
57.guard().orElse() 链式降级：idle queue 取不到就 create，比 if-else 更优雅
58.三层 defer 嵌套锁保障并发：用户锁→沙箱获取→沙箱锁，自动释放不泄漏
59.双模式代码传输：小代码 Base64 内联，大代码（>64KB）写文件路径引用
60.fire-and-forget 异步清理：失败沙箱通过 BullMQ 异步 kill，不阻塞主流程
61.CodeContext 优雅降级：上下文执行失败自动回退到无状态 sandbox.runCode
62.白名单优于黑名单：coreTools 显式声明可用工具比 excludeTools 排除危险工具更安全，iflow-cli 文档明确警告黑名单可被绕过
63.Sub Agent 权限最小化：安全审计类 Agent 应设 isInheritTools: false 切断继承，仅授予 Read/Grep 等只读工具
64.三层纵深防御：容器隔离 + 工具过滤 + Hook 拦截，任一层被突破仍有其他层兜底
65.双重超时是必须的：进程内信号超时可能被代码捕获，进程外 join+kill 是最终兜底
66.API 猴子补丁按类别组织：进程控制/文件破坏/权限修改/目录逃逸/模块禁用五类分治
67.结构化返回优于布尔值：ExecutionResult 的 timeout/memory_exceeded 字段让调用方能区分失败原因
68.OMP_NUM_THREADS=1 限制线程：防止生成代码通过 OpenMP 并行消耗所有 CPU 核心