测试发现工具的路径和资源范围如何限制

一个只读工具也可能把任务做得过头。用户让 Agent 找某个模块的测试,工具从仓库根目录一路扫描,进入依赖目录、构建产物与符号链接指向的位置。最后虽然只返回十个文件名,后台却已经访问了大量与问题无关的文件。
测试发现需要两道边界:允许访问哪里,以及本次最多做多少工作。前者保护资源范围,后者控制延迟与消耗。把两个约束放在服务端执行,比在提示词里写“请谨慎扫描”更可靠。
先固定仓库,再接受相对范围
模型输入应使用服务端认可的仓库标识,例如 repository_id。服务端再将它映射为授权目录。不要让模型传机器上的任意根路径,也不要从用户问题中抽取一个看起来像目录的字符串后直接访问。
scope 可以是仓库内相对目录,默认值也要明确。若默认扫描 tests,就返回实际使用的范围;若该目录不存在,应报告不存在,而不是悄悄扩大到整个工作区。输入校验失败与“合法范围内没有匹配文件”是不同结果。
路径排除规则可以包含版本控制内部目录、依赖目录和构建输出。项目允许自定义排除规则时,也应限制配置来源。不能因为扫描遇到一个目录里的说明文件,就把它当成允许访问仓库外文件的新授权。
字符串检查只解决表面问题
拒绝 ../ 有帮助,却不是完整的路径范围校验。绝对路径、规范化结果和符号链接目标都影响实际访问位置。一般应先解析路径,再判断目标是否仍在授权根目录之内;比较时使用路径组件关系,而不是字符串前缀。
例如,/work/repo-extra 以 /work/repo 开头,但它不是后者的子目录。链接也可能看起来位于仓库内,目标却在仓库外。Python 的 pathlib 官方文档 说明了 resolve() 解析符号链接与消除 .. 的行为;相对路径关系检查与实际文件系统解析应配合使用。
这仍不是面对并发修改的完整隔离保证。路径检查后、打开文件前,链接或目录可能发生变化。对于不可信工作区,应使用适合目标平台的目录句柄访问约束、受限运行环境或只读快照等机制,避免把一次路径解析描述成万无一失的沙箱。轻量产品也可以先选择不跟随链接,并清楚报告跳过项。
返回数量与访问数量分开算
接口参数中的 limit 通常限制返回多少候选。它不能限制扫描过程中经过多少文件。一个没有测试文件的巨大目录,可能让工具扫完很久才返回空列表。
因此,工具至少要维护几个独立预算:访问条目数、遍历深度或范围、扫描耗时、结果条数和输出字节数。是否需要全部暴露给模型,可以按产品选择;无论输入提供什么,服务端都应有自己的硬上限。
若只是按文件名发现测试,就不要顺带读取全部文件内容。需要内容判断时,先返回候选,再由受限读取工具读取必要片段。这样预算更容易解释:发现阶段花在定位,读取阶段花在确认相关性。

图里的返回体积应按实际编码后的字节或明确约定的单位计量。文件名很长或包含多字节字符时,条数相同不代表响应大小相同。
到达预算时明确停止在哪里
扫描完成与达到预算提前停止,需要不同的状态。否则 Agent 看到空列表,可能误报“这个模块没有测试”,实际上工具只访问了前面一小部分目录。
一个响应可以同时表达 status、truncated、已扫描范围与停止原因。若支持继续扫描,再提供受服务端校验的游标。游标应绑定仓库、快照、过滤规则和扫描顺序,不能让用户随意改一个目录偏移量去读取其他资源。
结果顺序也应稳定。若每次返回顺序不同,重试可能反复得到同一批文件,或漏过部分候选。对于工作区文件不断变化的场景,可以提示结果对应扫描时状态;对于固定提交的文件树,采用稳定排序会更容易复现。
让 Agent 按原因调整下一步
范围太宽时,可以缩小到目标模块或测试目录;返回截断时,可以分页;权限不足时,则应报告不可访问的部分。不要把所有错误都变成“重新调用一次”,更不能在授权范围失败后去用户主目录里寻找替代材料。
遇到操作系统访问错误,保留错误类别与受影响的相对路径即可。日志没有必要泄露完整本机目录、环境变量或文件内容。面向用户的报告应说明哪些候选已确认,哪些部分还未扫描。
核验工具时可以用几个明确场景:仓库外路径、指向外部的链接、大量无匹配文件、超过返回上限的候选,以及扫描中途发生的权限错误。分别检查访问是否停止、截断是否可见、Agent 有没有把部分扫描说成全量结果。这是检查设计,不是本文声称已执行的测试报告。
我会先让测试发现保持只读、受限和可解释。它只要能回答“在获准范围内,按哪些规则扫描到这里,返回了这些候选”,就足以支持下一步查代码;不必用一次发现调用承担整个测试工作流。
更多推荐


所有评论(0)