deepagents 路由后端实战系统提示词中“Shell paths vs. virtual paths”段的生成机制【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents本文围绕 deepagents 仓库中一个黄金快照文件 system_prompt_with_routed_backend.md 展开它冻结了CompositeBackend路由后端配置下系统提示词中 “Shell paths vs. virtual paths” 小节的完整渲染结果。读完后你将掌握该提示词段的三段式路由分类规则可映射宿主机路径、映射到根路径、无宿主机映射、其生成函数 _route_host_path_prompt 的源码逻辑以及如何用 smoke 测试与单元测试复现并验证这一行为。一、这个快照文件是什么deepagents 的 SDK 为不同后端组合生成不同的系统提示词system prompt。为了防止提示词措辞被无意改动仓库在 snapshots 目录 下维护了一组“黄金快照”golden snapshot每个system_prompt_with_*.md文件是某个后端配置下完整渲染后的系统提示词_tools.json是同一配置下工具列表的 OpenAI schema 快照。按 snapshots/README.md 的说明_with_*命名表示该场景包含对应特性每个快照都是自包含的完整文件而非与某个基线的 diff。本文件对应的描述为“Full prompt for aCompositeBackendwith host-mapped, non-virtual, and unmapped virtual routes”即覆盖了三类路由全部情况。快照由 test_system_prompt.py 生成与比对测试通过_assert_snapshot把实际渲染文本与文件内容做逐字符比较若快照不存在或传入update_snapshots标志则重新写入。相关测试是 test_system_prompt_snapshot_with_routed_backend其文档字符串标注该场景对应 issue #3050。二、快照原文路由后端下的路径使用守则快照全文如下即CompositeBackend路由场景下追加到系统提示词的路由小节逐字保留## 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. Host path mappings: - /common/ - /work/app/ (e.g. /common/dir/x.py - /work/app/dir/x.py) - /legacy/ - / (e.g. /legacy/dir/x.py - /dir/x.py) Virtual mounts without a host path mapping (not accessible from the shell): - /notes/这段提示词要解决的核心矛盾是文件工具read_file、write_file、ls等工作在虚拟命名空间里而execute工具在宿主 shell 中运行、只能看到宿主机文件系统。模型如果把文件工具返回的虚拟路径原样丢进 shell 命令就会得到No such file or directory。deepagents 的解法不是改写 shell 命令而是在系统提示词中给出前缀替换映射让模型自己生成正确的命令。快照中的三个挂载点各自演示一种分类虚拟挂载路由后端分类提示词中的表现/common/FilesystemBackend(root_dir/work/app, virtual_modeTrue)可映射宿主机路径“Host path mappings”映射到后端的宿主机根目录/work/app//legacy/FilesystemBackend(root_dir/work/legacy, virtual_modeFalse)映射到文件系统根“Host path mappings”前缀直接剥掉映射到//notes/StateBackend()内存态无磁盘文件无宿主机映射“Virtual mounts without a host path mapping”标注 shell 不可达三、产生该快照的测试配置smoke 测试 的构造方式如下代码摘自测试源码model _smoke_model() route FilesystemBackend(root_dir/work/app, virtual_modeTrue) legacy FilesystemBackend(root_dir/work/legacy, virtual_modeFalse) backend CompositeBackend( defaultLocalShellBackend(root_dirPath.cwd(), virtual_modeTrue), routes{/common/: route, /legacy/: legacy, /notes/: StateBackend()}, ) agent create_deep_agent(modelmodel, backendbackend) _invoke_for_snapshot(agent, {messages: [HumanMessage(contenthi)]})各构件的角色CompositeBackendcomposite.py按路径前缀路由的后端。default是未命中任何路由时的兜底后端routes是“前缀 - 后端”字典。本例中/common/、/legacy/、/notes/三个前缀分别路由到不同后端其余路径走default。LocalShellBackend作为default它支持execute且 shell 运行在本地宿主机上——这是虚拟路由能获得宿主机映射的前提条件。FilesystemBackendfilesystem.py基于本地磁盘的只读/读写后端其virtual_mode参数决定路径语义——True时把传入路径视为虚拟绝对路径、root_dir成为虚拟根False时保留传统行为允许使用绝对路径。这一点直接决定了路由在提示词中的映射形态下一节详述。StateBackend文件存于 agent state 内存中磁盘上无实体因此天然没有宿主机路径。测试中还有一处可移植性处理值得注意FilesystemBackend.cwd会把root_dir解析为操作系统原生的绝对路径Windows 上会变成C:\work\app所以快照前用text.replace(str(route.cwd), /work/app)把它还原为规范 POSIX 形式测试第 189-194 行保证黄金文件跨平台稳定。四、源码深潜_route_host_path_prompt的三条分类规则这段提示词由 middleware/filesystem.py 中的私有函数_route_host_path_prompt(backend)生成其分类逻辑与 docstring 完全对应前置判断backend不是CompositeBackend时直接返回空字符串——单一后端不存在虚拟挂载问题整个小节都不渲染。shell 可达性判断只有当default是LocalShellBackendshell 跑在本地宿主机、与路由共享同一文件系统时本地FilesystemBackend路由才可能映射出宿主机路径default是远程/沙箱后端时shell 在另一台文件系统上本地路由一律归入“不可从 shell 访问”。逐路由分类遍历backend.sorted_routes不满足上两条 - 加入no_host_routes列表渲染为“Virtual mounts without a host path mapping”条目满足条件且route_backend.virtual_mode为True- 前缀映射到该后端的宿主机根route.cwd如/common/-/work/app/满足条件且virtual_mode为False- 前缀被剥除剩余绝对路径原样使用即前缀映射到/如/legacy/x就是宿主机上的/xroot_dir被忽略。空段过滤host_mappings与no_host_routes均为空时返回空字符串。渲染细节_norm辅助函数保证前缀以/结尾即使用户配置的路由前缀没写斜杠如/data也会渲染为/data/避免/data与dir拼接成/datadir每条映射附带一个嵌套路径示例/common/dir/x.py - /work/app/dir/x.py使替换规则对子路径也无歧义。固定文案部分与快照逐字一致包括标题## Shell paths vs. virtual paths、execute只访问宿主机文件系统的说明、两条虚拟挂载处理规则以及那句关键警告“Do not assume that a path returned by a file tool can be used directly in a shell command.”与中间件主流程的衔接_route_host_path_prompt的调用点在_filter_unsupported_tools_and_apply_promptFilesystemMiddleware在每次模型调用前处理请求的共享路径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) system_prompt \n\n.join(prompt_parts).strip()两个要点只在execute工具激活时追加。路由映射是专为 shell 命令服务的配置信息若后端不支持执行如纯FilesystemBackend该小节不会出现在提示词中。属于“per-backend 必需配置”而非可裁剪的 prose。源码注释明确写道该段是 essential per-backend config即使默认提示词走了 trimming 流程也会保留——smoke 测试与 test_end_to_end.py 中的断言Shell paths vs. virtual paths in content也把它固化为了回归约束。五、验证矩阵单元测试如何覆盖分类规则除了 smoke 快照test_execute_route_prompt.py 对该函数做了分类矩阵级的白盒测试覆盖快照所演示的每一类及更多边界test_returns_empty_for_non_composite_backend/test_returns_empty_when_no_routes非复合后端或无路由时返回空串test_maps_virtual_route_to_host_path虚拟模式路由渲染为- \/common/ - {route.cwd}/ 且带嵌套示例test_non_virtual_filesystem_route_maps_to_root非虚拟路由渲染为- \/common/ - /test_routes_without_host_path_marked_inaccessibleStoreBackend路由只出现在 no-mapping 小节且整个提示词中不出现-test_non_trailing_route_prefix_renders_with_slash无前缀斜杠的/data不会误拼出/datadirtest_remote_sandbox_default_suppresses_host_mappings与test_non_virtual_route_not_mapped_under_remote_sandbox同一本地路由在远程沙箱default下被降级为 shell-inaccessible——这对应另一个快照 system_prompt_with_sandbox_default.md其全文恰好就是该小节但没有任何 Host path mappings只有 no-mapping 条目。在本地复现验证只读运行不修改仓库cd libs/deepagents # 单个函数的分类矩阵测试 uv run pytest tests/unit_tests/middleware/test_execute_route_prompt.py -v # 路由后端完整快照比对 uv run pytest tests/unit_tests/smoke_tests/test_system_prompt.py -k routed_backend -v六、小结system_prompt_with_routed_backend.md看似只是一段十几行的提示词实则冻结了 deepagents 处理“虚拟文件命名空间与宿主 shell 分裂”这一结构性问题的完整契约CompositeBackend的每条路由按default是否为本地 shell、路由是否为本地磁盘后端、是否virtual_mode三个条件被分成“映射到宿主根”“映射到/”“shell 不可达”三类并由 _route_host_path_prompt 在execute激活时渲染进系统提示词。对使用者的实际含义是当你的 agent 同时挂载了本地文件路由与内存/远程路由时模型能否正确翻译 shell 命令路径完全取决于这段提示词是否如实反映了你的后端拓扑——而 smoke 快照与矩阵测试正是这一正确性的双重保险。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考