deepagents 系统提示快照解析：远程沙箱默认后端下的 “Shell paths vs. virtual paths“ 路由段

deepagents 系统提示快照解析：远程沙箱默认后端下的 "Shell paths vs. virtual paths" 路由段

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents

本文以 deepagents 的快照文件libs/deepagents/tests/unit_tests/smoke_tests/snapshots/system_prompt_with_sandbox_default.md为核心，解析其中 "Shell paths vs. virtual paths" 系统提示段（system prompt section）的设计意图与生成机制：当CompositeBackend的默认后端是远程/沙箱 shell 时，本地虚拟挂载（virtual mount）为何不能映射为宿主路径，以及该提示段如何由 FilesystemMiddleware 动态渲染、并被快照测试锁定。读完本文，你能准确判断不同后端组合下execute工具的可访问性，并能读懂、复现该快照测试。

快照原文：一段面向模型的路由守则

该快照文件是CompositeBackend默认后端为"沙箱型"后端（shell 运行在与本地文件系统隔离的独立环境中）时，渲染到系统提示词中的文件系统路由段。全文内容如下：

## Shell paths vs. virtual paths The `execute` tool runs commands in the host shell and can only access files that exist on the host filesystem. Some paths returned by the file tools are virtual mounts: - If a virtual mount has a host path mapping, replace its virtual prefix with the host prefix when running shell commands. - If a virtual mount does not have a host path mapping, it is not accessible from the shell. Use the file tools listed above to interact with those files. Do not assume that a path returned by a file tool can be used directly in a shell command. Virtual mounts without a host path mapping (not accessible from the shell): - `/common/`

注意这份快照与同目录的 system_prompt_with_routed_backend.md 的关键差异：没有 "Host path mappings" 小节。因为默认后端是远程沙箱时，本地FilesystemBackend路由（快照中为/common/）在 shell 侧不可达，只能整体归入 "Virtual mounts without a host path mapping (not accessible from the shell)" 列表。

快照的配套说明见 snapshots/README.md，其中对本条目的定位是：

Full prompt when the default backend is a remote/sandbox shell. Local filesystem routes should not be described as local shell-accessible host paths.

即：默认后端是远程/沙箱 shell 时的完整提示快照，且本地文件系统路由不得被描述为本地 shell 可访问的宿主路径。

生成机制：_route_host_path_prompt的路由分类逻辑

这段提示并非静态文本，而是由 middleware/filesystem.py 中的_route_host_path_prompt(backend)函数（约 L1397–L1485）按后端组合动态拼装。其核心决策链可以概括为三步：

第一步：默认后端是否使用本地 shell

default_uses_local_shell = isinstance(backend.default, LocalShellBackend)

只有当CompositeBackend的默认后端是 LocalShellBackend 时，路由的文件才可能与 shell 运行在同一文件系统上；若默认后端是远程/沙箱型SandboxBackendProtocol实现，则所有本地文件系统路由对 shell 均不可达，直接归入no_host_routes。

第二步：逐路由判定宿主路径映射

对backend.sorted_routes中的每个路由：

• 若"默认后端非本地 shell"或"路由后端不是FilesystemBackend"（如StateBackend内存路由、StoreBackend路由），路由前缀追加到no_host_routes；
• 否则若路由处于virtual mode（route_backend.virtual_mode为真），前缀映射到该后端的宿主根目录route.cwd（例如/common/->/work/app/）；
• 否则（非虚拟模式），前缀直接剥掉、剩余绝对路径原样使用，即前缀映射到文件系统根/（例如/legacy/x->/x）。

第三步：渲染成提示文本

渲染逻辑（约 L1461–L1485）先输出标题 "## Shell paths vs. virtual paths" 与两条通用守则（即快照中的两条 bullet），随后按需追加两个小节：

• if host_mappings:输出 "Host path mappings:" 及逐条映射行，每行形如- `/common/` -> `/work/app/` (e.g. `/common/dir/x.py` -> `/work/app/dir/x.py`)，其中_norm()会统一补全尾随/保证子路径替换可组合；
• if no_host_routes:输出 "Virtual mounts without a host path mapping (not accessible from the shell):" 及逐条前缀。

在沙箱默认后端的场景下，host_mappings为空、no_host_routes为["/common/"]，因此快照中只出现"无宿主映射"清单——这正是快照文件名中sandbox_default的语义所在。

注入时机：仅在execute工具激活时追加

该提示段在每次模型请求的中间件钩子中注入。_filter_unsupported_tools_and_apply_prompt（约 L3075–L3121）的注释与实现说明了注入规则：

# The host-path routing section is # essential per-backend config (virtual->host path mapping for the `execute` # shell), not prose, so it is appended when the execute tool is active # regardless of the prose. prompt_parts = [self._custom_system_prompt] if self._custom_system_prompt else [] if execution_active: route_prompt = _route_host_path_prompt(cast("BackendProtocol", backend)) if route_prompt: prompt_parts.append(route_prompt)

由此可得出三条行为边界：

1. 仅当execution_active为真（后端支持执行命令，见supports_execution，约 L1488）才计算并追加路由段；
2. 路由段被视为"关键的每后端配置"（essential per-backend config），不受提示词裁剪（trimming）影响——即使其余工具使用说明文字被精简，该段仍会出现；
3. 对非CompositeBackend，_route_host_path_prompt直接返回空串，即无路由概念时该段整体缺省。

快照测试：这条提示如何被验证

快照由 smoke_tests/test_system_prompt.py 中的test_system_prompt_snapshot_with_sandbox_default（约 L200–L230）生成并校验。测试构造方式：

class _SnapshotSandbox(SandboxBackendProtocol, StoreBackend): """A sandbox-capable default that is NOT a LocalShellBackend (e.g. remote). Its shell runs in a separate filesystem, so local filesystem routes are not reachable from it. The fake model never calls tools, so `execute` is unused. """ def execute(self, command: str, *, timeout: int | None = None) -> ExecuteResponse: return ExecuteResponse(output="", exit_code=0, truncated=False) route = FilesystemBackend(root_dir="/work/app", virtual_mode=True) backend = CompositeBackend( default=_SnapshotSandbox(store=InMemoryStore(), namespace=lambda _rt: ("default",)), routes={"/common/": route}, ) agent = create_deep_agent(model=model, backend=backend)

要点：

• _SnapshotSandbox刻意实现为"不是LocalShellBackend的沙箱型默认后端"，模拟远程沙箱：它具备execute能力，但 shell 运行在独立文件系统里，因此本地路由/common/不可达；
• 断言方式为全量快照对比：取出首次模型调用中的SystemMessage文本，与快照文件逐字符比较（快照缺失时自动创建并提示重跑，见_assert_snapshot，约 L55–L64）；
• 与之对照，test_system_prompt_snapshot_with_routed_backend（约 L145–L197）验证了本地 shell 默认后端下同一/common/路由应出现在 "Host path mappings" 中（映射到/work/app/），并演示了 Windows 路径回写归一（text.replace(str(route.cwd), "/work/app")）以保证快照可移植。

此外，单元层还有两条直接断言覆盖该段的裁剪行为，见 test_end_to_end.py（约 L3012–L3022）：

assert "Shell paths vs. virtual paths" in content, "routing section must survive trimming" ... assert "Shell paths vs. virtual paths" not in content

前者确认有路由配置时该段必须存活于裁剪后提示，后者确认无路由场景（或非复合后端）时该段不应出现。

三类路由的完整分类（与姊妹快照互参）

_route_host_path_prompt的设计目标是用一个提示段覆盖全部路由分类。对照 system_prompt_with_routed_backend.md 的测试注释（test_system_prompt.py 约 L145–L161），三种典型路由及其预期呈现如下：

这张表把快照中的两条 bullet 规则落到了具体后端组合上："有宿主映射"的判定条件 = 默认后端是LocalShellBackend且路由是FilesystemBackend，其余一律保守地声明为 shell 不可访问，要求模型改用文件工具（read_file/write_file等）操作。

对使用者的工程含义

结合以上实现，可以归纳出在实际配置 deepagents 后端时的三条判断依据（均为从源码结构得出的结论）：

1. 想让模型通过execute直接操作某路由的文件：默认后端必须使用本地 shell 后端（LocalShellBackend），路由才可能获得宿主路径映射；否则提示词会明确告知模型"shell 不可达，请用文件工具"。
2. 远程/沙箱默认后端是安全默认：即使误配置了本地FilesystemBackend路由，模型也不会尝试把虚拟前缀直接塞进 shell 命令——路由段提示词会在系统提示层面封堵这一错误路径。
3. 快照是提示词回归的护栏：修改路由判定或提示文案后，相关快照测试（system_prompt_with_sandbox_default、system_prompt_with_routed_backend等）会立即暴露差异；按 snapshots/README.md 的约定，每个快照自包含某一后端组合的完整渲染结果，新增后端组合时应补充对应的组合快照而非依赖共享基线。

小结

system_prompt_with_sandbox_default.md这份快照的价值在于：它以最小化的场景（沙箱默认后端 + 一条本地虚拟路由/common/）固化了 deepagents "shell 路径 vs 虚拟路径" 提示段在无宿主映射分支下的精确措辞——execute只触达宿主文件系统、无映射的虚拟挂载必须经文件工具访问、且不得假设文件工具返回的路径可直接入 shell。其背后是 middleware/filesystem.py 中_route_host_path_prompt按"默认后端是否本地 shell × 路由是否FilesystemBackend× 路由是否虚拟模式"三类条件的分支渲染，并由 smoke 测试 逐字符锁定，构成了 deepagents 复合后端（CompositeBackend）提示词工程的可靠基线。

【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents