代码执行与沙箱

一句话定义

给 Agent 一个代码执行器（REPL/解释器 + 隔离环境），等于给它一个"万能工具"：任何能用代码表达的操作——算数、数据处理、调用任意库、组合其他工具的输出——都不必再预置专用工具；沙箱则是让这种能力不变成灾难的安全容器。

为什么重要

预置工具永远追不上任务的长尾：你可以给 calculator、sort_list、csv_to_json……但用户总会提出你没想到的组合。代码是行动空间的通用界面——这就是为什么 2024-2026 年顶级 Agent（Claude Code、OpenAI Code Interpreter、Deep Research）不约而同把"写代码并执行"作为核心行动方式。附赠三个红利：精确（LLM 算不对的数，Python 算得对）、可审计（代码即操作日志）、可复用（用户能拿走脚本）。代价只有一个但很重：任意代码执行 = 任意副作用，沙箱与权限因此成为生死线（kp-026）。

前置知识

kp-009（函数调用）、kp-010（工具设计）。

核心概念

代码执行作为工具的形态

name: execute_code
description: 在 Python 沙箱中执行代码并返回 stdout/stderr。
  适合：计算、数据处理、批量文件操作。
  沙箱无网络、10s 超时、/workspace 目录持久。
input_schema: { code: string, timeout?: int }
返回：stdout（截断至 4KB） + stderr + 是否超时

配套设计三件套：

持久工作区：多次执行共享 /workspace（文件写了下次还能读）——这构成了 Agent 的"草稿环境"
返回值设计（kp-010 精髓）：成功时返回 stdout 摘要；异常时返回含 traceback 的可行动错误——Python 的报错信息天然"告诉模型该怎么改"，这是代码 Agent 自我纠正效率极高的原因（kp-014）
交互式 REPL vs 单次执行：REPL（如 Claude 的 code-execution 工具）保持进程状态，省去重复 import；Jupyter kernel 是常见实现底座

沙箱的隔离层级（从严到松）

层级	技术	适用
无隔离（危险）	直接 exec	仅本地玩具实验
进程级	子进程 + 超时 + 资源限制	内网可信任务
容器级	Docker/gVisor，文件系统与网络隔离	生产标配
微 VM	Firecracker/WASM	多租户平台（强隔离 + 快启动）

必须限制的四类资源：CPU/内存/时长（防死循环烧钱）、文件系统（只挂载工作区）、网络（默认禁用，白名单放行）、系统调用（seccomp 类）。

原理与机制

为什么"代码作为行动"优于"枚举工具"？一个信息论式的论证：预置 k 个工具覆盖的是你能预见的行为空间，而任务分布的尾部无限长；代码执行覆盖的是该语言可计算的全部行为，一次接入长尾全消。观察到的实践模式也一致：模型在"工具拼装"场景（先 A 再 B 再 C，中间转格式）里易错，改为"写一段脚本串起来"后正确率显著上升——因为把编排逻辑从概率采样（每次选择都可能错）变成了确定性执行（写对一次就对）。

安全机制上现代沙箱的关键点：执行前后做文件系统快照/diff（审计改变了什么）；网络出口走代理 + 域名白名单（数据外传检测，kp-026）；敏感操作（rm -rf /workspace 外、环境变量读取）直接拒绝并返回说明。

直观类比

预置工具 = 给员工一套定制厨具（切菜机、和面机……遇到没有的工具就干不了）；代码执行 = 给他一个带齐全刀具的厨房——什么菜都能做。沙箱 = 厨房的门禁与监控：能用火（CPU）、能拿刀（文件），但出不了这间房（网络隔离），而且全程录像（审计日志）。

实例与案例

数据整理任务的两种实现对比：

任务：把 200 行 CSV 里的日期统一成 ISO 格式，剔除金额为负的行

预置工具路线：read_csv → parse_date(×200) → filter → write_csv
  （模型要串 6+ 次工具调用，每次参数都可能错）

代码路线：
  execute_code("""
    import pandas as pd
    df = pd.read_csv('orders.csv')
    df['date'] = pd.to_datetime(df['date'], errors='coerce')
    df = df.dropna(subset=['date'])
    df = df[df['amount'] >= 0]
    df.to_csv('orders_clean.csv', index=False)
    print(len(df), '行已写出')
  """)
  → 一次调用，确定性执行，输出"187 行已写出"即验收标准

常见误区

误区一："沙箱会拖慢 Agent"。容器冷启动 1-3s，相对模型推理延迟可忽略；真正要优化的是会话复用（同任务复用一个容器）。
误区二：给沙箱完整网络"方便查资料"。等于给 Agent 无限制外传通道——提示注入一旦发生（kp-026），数据就从这个口子走了。查资料应该走专用搜索工具（可审计），而非沙箱 curl。
误区三：忽视输出截断策略。print 一个 10 万行 DataFrame 会瞬间撑爆上下文——沙箱侧截断 + 提示模型"大结果写文件"是标配组合（kp-003）。
误区四：只在出错时才看代码。代码就是行动日志，人工审查抽样轨迹应含代码（kp-025）。

自测题

为什么代码执行被称为"行动空间的通用界面"？
沙箱必须限制哪四类资源？
为什么"写脚本串任务"比"多次工具调用"更可靠？

（参考答案：1. 覆盖语言可计算的全部行为，消除预置工具的长尾缺口；2. CPU/内存/时长、文件系统、网络、系统调用；3. 编排从概率采样变成确定性执行，一次写对次次对。）

与其他知识点的关系

安全纵深 → kp-026；编程 Agent 的全面应用 → kp-028
GUI 操控（另一种通用行动）→ kp-029；错误驱动的自我纠正 → kp-014