[Bug] 在什么情况下会触发“工作区越界”

[czhcc]

出了什么问题？（必填，附截图）

这是在生产环境上产生的，我想在开发环境重现，但让mcp工具返回长文本内容，也不会触发，如下图：

怎么复现？（必填，编号步骤）

这个问题修改工作区目录可以解决，只是想知道是什么情况下会越界。

影响模块（选填，多选）

No response

环境（必填，一行）

v1.6.0-SNAPSHOT

[mateaix]

@czhcc 已定位根因，并提交了修复。

根因

从你贴的生产截图能看到关键链路：

1. Mcp ... 这个 MCP 工具返回了一段很长的结果；
2. 紧接着 读取文件 /tmp/mate-tool-result-spill/tool-results/.../call_2... 报 [CRITICAL] 工作区越界；
3. 然后 Execute Code 用 cat /tmp/mate-tool-result-spill/... 同一个路径却成功了。

触发的是工具结果溢写（spill）机制和工作区沙箱边界的冲突：

• 单条工具结果超过 mate.agent.tool-result.per-result-threshold-chars（默认 8000 字符）时，完整内容会被写到磁盘，上下文里只留一段预览 + 一行 请用 read_file <path> 读取完整内容 的指针（见 ToolResultStorage）。
• 当这个 spill 目录落在工作区沙箱边界之外时——你的生产环境把 storage-base-dir 配成了 /tmp/mate-tool-result-spill/tool-results（若不配置、且会话没绑定 workspace base_path，则回退到 ${java.io.tmpdir}/mateclaw/tool-results，同样在边界外）——模型照着提示去 read_file 这个路径，WorkspaceBoundaryGuardian 就把它判成 WORKSPACE_BOUNDARY_ESCAPE（即"工作区越界"，CRITICAL/BLOCK），读取在执行前被拦下。

一句话：系统把工具结果写到了工作区外，又叫模型去读它，然后自己的边界守卫把这次读取拦了。

至于为什么 cat 能成功而 read_file 被拦——WorkspaceBoundaryGuardian 的 shell 工具白名单只有 execute_shell_command / shell_execute / run_command，截图里的 Execute Code 是 execute_code，不在名单内，所以绕过了边界检查（这其实是一处沙箱逃逸缺口，见文末）。

为什么开发环境复现不了

1. 默认 storage-base-dir 为空，且会话绑定了 workspace base_path 时，spill 会落到 <workspace>/.mateclaw/tool-results/——本来就在边界内，read_file 放行，自然不越界；
2. 结果必须超过 8000 字符才会 spill；只是"长文本"但没到阈值，根本不会产生 spill 路径，也就触发不了。

所以要在开发环境复现，需要三个条件同时满足：把 mate.agent.tool-result.storage-base-dir 指到工作区外（或让会话不绑定 workspace、走 tmpdir 回退）+ 开启工作区沙箱 + 让 MCP 工具返回 >8000 字符。这也解释了你说的"改工作区目录能解决"——本质是让 spill 路径回到了边界内。

修复

把 spill 的基目录登记为 WorkspacePathGuard 的受信根（与现有 skill root 同一套机制）：

• read_file / validatePath / shell 扫描三处边界检查统一放行受信根下的路径，保证模型能读到自己的 spill 文件，且 read_file 与 cat 行为一致；
• 只登记落在工作区外的两类 spill 根（显式 storage-base-dir 与 tmpdir 回退）；<workspace>/.mateclaw/tool-results 本就在边界内，不额外放开，避免跨工作区读取；
• 启动时（@PostConstruct）预先登记确定性的 spill 根，保证重启后恢复旧会话仍能读历史 spill 文件，而不必等到本次 JVM 再发生一次 spill 才生效。

已补回归测试覆盖：spill 路径放行、非 spill 的工作区外路径（如 /etc/passwd）仍然拦截、spill 根内删除不误判为"删除工作区根"。

附带发现（本次未改，建议后续单独跟进）

execute_code 不在 WorkspaceBoundaryGuardian 的工具名单里，意味着它能读写/删除工作区外的任意路径，属于一处沙箱逃逸缺口（截图里 cat /tmp/... 成功正是这个原因）。把它纳入边界守卫需要针对 execute_code 的 code 参数定制扫描（不能直接复用 command 提取逻辑），改动面更大、需单独测试，所以单独跟进更稳妥。