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按后端组合动态拼装。其核心决策链可以概括为三步第一步默认后端是否使用本地 shelldefault_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 moderoute_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)由此可得出三条行为边界仅当execution_active为真后端支持执行命令见supports_execution约 L1488才计算并追加路由段路由段被视为关键的每后端配置essential per-backend config不受提示词裁剪trimming影响——即使其余工具使用说明文字被精简该段仍会出现对非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_code0, truncatedFalse) route FilesystemBackend(root_dir/work/app, virtual_modeTrue) backend CompositeBackend( default_SnapshotSandbox(storeInMemoryStore(), namespacelambda _rt: (default,)), routes{/common/: route}, ) agent create_deep_agent(modelmodel, backendbackend)要点_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–L3022assert 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三种典型路由及其预期呈现如下路由后端类型默认后端为本地 shell 时默认后端为远程沙箱时/common/虚拟模式FilesystemBackendroot_dir/work/app进入 Host path mappings/common/-/work/app/并给出嵌套路径示例进入无宿主映射清单本快照所示shell 不可达/legacy/非虚拟模式FilesystemBackend进入 Host path mappings/legacy/-/root_dir被忽略剩余绝对路径原样使用进入无宿主映射清单/notes/StateBackend内存态无宿主路径进入无宿主映射清单进入无宿主映射清单这张表把快照中的两条 bullet 规则落到了具体后端组合上有宿主映射的判定条件 默认后端是LocalShellBackend且路由是FilesystemBackend其余一律保守地声明为 shell 不可访问要求模型改用文件工具read_file/write_file等操作。对使用者的工程含义结合以上实现可以归纳出在实际配置 deepagents 后端时的三条判断依据均为从源码结构得出的结论想让模型通过execute直接操作某路由的文件默认后端必须使用本地 shell 后端LocalShellBackend路由才可能获得宿主路径映射否则提示词会明确告知模型shell 不可达请用文件工具。远程/沙箱默认后端是安全默认即使误配置了本地FilesystemBackend路由模型也不会尝试把虚拟前缀直接塞进 shell 命令——路由段提示词会在系统提示层面封堵这一错误路径。快照是提示词回归的护栏修改路由判定或提示文案后相关快照测试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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考