Anthropic Agent 工程实战笔记（六）安全与生产

本模块主要参考（官方）

$1$ Beyond permission prompts: Claude Code sandboxing（Anthropic Engineering）
$2$ Claude Code: Best practices for agentic coding（Anthropic Engineering）
$3$ A postmortem of three recent issues（Anthropic Engineering，Sep 2025）
$4$ Code execution with MCP（Anthropic Engineering）

概览与清单 ：<index.md> · 延伸阅读（全网最新） ：<further-reading.md>

本模块在整体中的位置

前面模块把「形态、工具、上下文、长任务、评测」都搭好了；安全与生产 是上线前的收口与上线后的持续改进。执行能力（写文件、跑代码、调 API）带来风险，仅靠「权限类」提示不足，需要沙箱（执行隔离环境，限制代码/命令的影响范围）等隔离（§1）；Coding Agent 的工程实践与其它模块结合使用（§2）。故障复盘（§3）则用真实案例说明：evals 可能未覆盖用户可见的退化、常规基础设施变更也可能放大影响、用户反馈是发现与定位问题的重要信号------因此要把生产 evals、监控与反馈通道纳入设计，而不是「先上线再补」。

逻辑线索（本模块阅读顺序）

安全：沙箱与 MCP（Model Context Protocol，模型上下文协议，统一接入工具的协议）执行环境，而非仅靠 prompt 约束。
实践：Coding Agent 最佳实践与 02/04/05 的衔接。
复盘：三起故障的根因与教训 → evals 覆盖、变更与监控、用户反馈。

本模块总流程图：安全与上线闭环 $1$ $3$

开发
沙箱 / MCP 执行
质量 Evals
上线 / 变更
监控
用户反馈：/bug、thumbs down

1. 沙箱与权限 $1$

仅靠「权限类」提示不足以保证安全；需要沙箱等执行隔离，在给 Agent 执行能力的同时限制影响范围。
Code execution with MCP $4$ 与沙箱文配合：通过 MCP 统一管理代码执行环境，便于隔离与复用。详见 <04-long-running-multiagent.md>。

2. Claude Code 与 Coding Agent 实践 $2$

Claude Code best practices $2$ 提供 Coding Agent 的工程经验与推荐用法，与 harness（见 <04-long-running-multiagent.md>）、工具（见 <02-tools.md>）、评测（见 <05-evals.md>）结合使用。

2.1 可运行代码示例：执行环境自检 $1$ $4$

在把「执行权」交给 Agent 前，建议确认运行环境隔离（沙箱或 MCP 管理的环境）。下面为最小可运行的自检脚本：检查当前进程是否在常见沙箱/容器内、以及工作目录是否在预期根下，便于在 harness 启动时做一次校验。实际生产应结合 MCP 与 $1$ $4$ 的完整沙箱方案。

python 复制代码

# 执行环境自检（沙箱/隔离检查示意）
# 运行：python check_exec_env.py

import os
import sys

def in_docker() -> bool:
    try:
        with open("/proc/1/cgroup", "r") as f:
            return "docker" in f.read() or "containerd" in f.read()
    except FileNotFoundError:
        return False

def in_sandbox_root(allowed_root: str) -> bool:
    cwd = os.path.realpath(os.getcwd())
    return cwd == os.path.realpath(allowed_root) or cwd.startswith(os.path.realpath(allowed_root) + os.sep)

def check_exec_env(allowed_root: str = "/workspace") -> dict:
    return {
        "cwd": os.getcwd(),
        "in_docker": in_docker(),
        "in_allowed_root": in_sandbox_root(allowed_root),
    }

if __name__ == "__main__":
    root = sys.argv[1] if len(sys.argv) > 1 else "/tmp"
    r = check_exec_env(root)
    print(r)
    if not r["in_allowed_root"]:
        print("WARN: CWD not under allowed root; consider restricting execution.")

配合 $1$ 沙箱与 $4$ MCP 代码执行，在 Agent 执行前做此类检查可降低误操作范围。说明：上述脚本适用于 Linux/容器环境（依赖 /proc/1/cgroup）；Windows 无此路径，路径白名单请按实际环境（如 C:\\workspace）调整。

示例：路径白名单 $1$

限制 Agent 可访问的目录，避免误写系统或其它项目；执行前校验路径在允许根下：

python 复制代码

import os

def resolve_in_allowed_root(path: str, allowed_roots: list[str]) -> str | None:
    """将 path 解析为绝对路径；仅当位于某 allowed_root 下时返回，否则返回 None。"""
    abs_path = os.path.realpath(os.path.abspath(path))
    for root in allowed_roots:
        abs_root = os.path.realpath(root)
        if abs_path == abs_root or abs_path.startswith(abs_root + os.sep):
            return abs_path
    return None

# 使用：只允许在 /workspace 与 /tmp/agent 下操作（Unix；Windows 请用如 C:\\workspace）
allowed = ["/workspace", "/tmp/agent"]
p = resolve_in_allowed_root("src/main.py", allowed)
if p is None:
    raise PermissionError("Path not under allowed roots")

LangGraph 1.0 下执行环境自检与路径白名单逻辑与上一致，可直接在 harness 或图外调用；代码集中见 <further-reading.md> 的「五、LangGraph 1.0 对照代码」§5.6。

3. 故障复盘 $3$

3.1 三起问题概览

问题	表现	根因概要
上下文窗口路由错误	部分请求被误路由到 1M context 服务器，质量下降	路由逻辑 + 负载均衡变更使更多流量走错池
输出损坏	偶发错误 token（如英文答成泰文、代码语法错）	TPU 上某运行时优化导致采样异常
近似 top-k XLA:TPU 误编译	Haiku 3.5 等受影响	混合精度与近似 top-k 在 TPU 上的 latent 问题

三起重叠发生、表现不一，排查困难；均与「为需求或负载降质」无关，纯属基础设施缺陷。

3.1.1 技术细节摘录 $3$ （便于理解「为何难查」）

采样与精度 ：生成时对下一个 token 做概率分布并采样。TPU 上用 bf16，但部分运算被 XLA 优化成 fp32（xla_allow_excess_precision），导致不同地方对「最高概率 token」不一致，有时最高概率 token 被排除。
近似 top-k ：为性能用了近似 top-k；在特定 batch/配置下会返回错误结果，且难以稳定复现（与前后操作、是否开调试有关）。最终改为 exact top-k 并统一精度，接受一定性能损失换质量稳定。
教训：基础设施与编译选项会直接影响模型输出；evals 若只在「理想环境」跑，可能覆盖不到这类问题。

3.2 教训

Evals 未覆盖 ：既有 evals 未捕捉到用户报告的退化；需在真实生产上持续跑质量 evals，并发展更能区分正常/异常行为的 evals。
常规变更也带来风险：负载均衡等「常规」变更可能显著改变受影响流量，需与质量监控挂钩。
隐私与复现：内部隐私与权限限制影响对用户问题的复现与定位；需要更好利用用户反馈的调试手段（在不牺牲隐私的前提下）。

3.3 改进方向 $3$ （原文承诺）

更快、更易用的调试与反馈工具。
在更多环节运行质量 evals（包括真实生产）。
更敏感、更能区分「正常/异常」的 evals。
继续依赖用户反馈：/bug （Claude Code 内提交问题的命令）、thumbs down（点踩反馈）、具体退化描述与用例，对定位问题非常有价值。

4. 实战自检清单

代码执行是否在沙箱或 MCP 管理的隔离环境中？是否避免仅靠 prompt 约束权限？
是否在生产或准生产环境持续跑质量 evals？变更（含负载均衡、路由）是否与 evals/监控联动？
是否提供低摩擦的用户反馈通道（如 /bug、thumbs down），并用于排查与复现？

5. 本模块要点回顾（便于自检与分享）

安全：执行能力需沙箱等隔离，不能只靠「权限类」提示；MCP 代码执行与沙箱配合。
实践：Coding Agent 最佳实践与 harness、工具、评测结合使用。
故障教训：evals 可能未覆盖用户可见退化；负载均衡等常规变更也可能放大问题；需生产 evals、监控与用户反馈（/bug、thumbs down）形成闭环。
改进方向：更敏感的 evals、在生产跑 evals、更好利用反馈的调试手段。

参考文献（本模块）

编号	来源	链接
$1$	Anthropic, Beyond permission prompts: Claude Code sandboxing	https://www.anthropic.com/engineering/claude-code-sandboxing
$2$	Anthropic, Claude Code: Best practices for agentic coding	https://www.anthropic.com/engineering/claude-code-best-practices
$3$	Anthropic, A postmortem of three recent issues	https://www.anthropic.com/engineering/a-postmortem-of-three-recent-issues
$4$	Anthropic, Code execution with MCP	https://www.anthropic.com/engineering/code-execution-with-mcp

6. 延伸

用户反馈：Claude Code 内 /bug （提交问题）；Claude 应用内「thumbs down」（点踩）；研究者/开发者若有 evals 愿分享可联系 feedback@anthropic.com。
全文 $3$ ：A postmortem of three recent issues。
GitHub ： claude-quickstarts/computer-use-demo 与 claude-agent-sdk-python 涉及执行环境与工具；索引 <index.md> 有「GitHub 与官方源码」汇总。
上一模块：<05-evals.md> · 返回 <index.md>。

Anthropic Agent 工程实战笔记（六）安全与生产

本模块在整体中的位置

逻辑线索（本模块阅读顺序）

本模块总流程图：安全与上线闭环 13

1. 沙箱与权限 1

2. Claude Code 与 Coding Agent 实践 2

2.1 可运行代码示例：执行环境自检 14

3. 故障复盘 3