fix(harness): bound filesystem search tool output

[wzq-xzwj]

背景与必要性

目前 grep_files 和 glob_files 会将文件系统后端返回的全部匹配项拼接成一条工具结果。当工作区文件较多、搜索条件较宽（例如 **/*）时，单次工具调用可能向上下文写入 MB 级内容，进而导致上下文压缩或下一次模型调用失败。

为什么现有压缩机制不能稳定兜底

这里的问题并不是单纯“历史消息太多”，而是超大搜索结果通常产生在当前推理轮次的最新位置，正好落在现有压缩机制的保护区域中：

1. TokenCounterUtil 会统计 ToolResultBlock 的输出，因此 grep_files / glob_files 的大结果会被计入总 token，并可能触发 compaction；
2. 但 ConversationCompactor.pruneToolResults 会从后向前扫描，并默认保护最近约 40,000 token 的工具输出。刚刚产生的超大搜索结果通常位于这段保护窗口内，不会被 prune；
3. 后续 compaction 又会按 keepMessages / keepTokens 保留最近一段消息原文。默认消息模式会保留最近 20 条消息，因此这条最新的超大工具结果通常仍位于 preserved tail，不会进入摘要；
4. 与此同时，ToolResultEvictionConfig.DEFAULT_EXCLUDED_TOOLS 当前默认排除了 grep_files 和 glob_files，因为配置假设它们的输出已经是自限制的，但现有实现实际上没有结果数量限制。

因此可能出现这样的链路：

无上限搜索结果
  -> 默认 eviction 跳过
  -> token 统计触发 compaction
  -> 结果因处于最近保护窗口 / preserved tail 而原样保留
  -> 压缩后上下文仍然过大，下一次模型调用失败

也就是说，仅依赖事后 compaction 不能稳定解决这个问题，更合适的第一道防线是在工具输出进入上下文之前就实施确定性的数量限制。

相关问题：#2831

当前实现草案

这个 PR 先提供了一版偏保守的保护方案：

• 为 grep_files 和 glob_files 增加可选的 limit 参数；
• 即使模型没有传入 limit，也由 FilesystemTool 强制应用默认值：
  • grep_files：100 条；
  • glob_files：200 条；
• 调用方可以调整 limit，但服务端硬上限为 1000；
• 存在更多匹配项时，在结果末尾明确提示已截断；
• 将 grep_files / glob_files 从 tool-result eviction 的默认排除列表中移除，作为单条匹配内容异常大时的第二道保护；
• 保留原有 Java 方法重载，避免影响直接调用 FilesystemTool 的现有代码；
• 同步更新中英文文档及测试。

这里的关键点是：安全上限由 Harness 兜底，不依赖模型是否记得传可选参数。

当前范围与已知限制

本 PR 当前限制的是 FilesystemTool 最终返回给模型的结果条数，即首先解决 #2831 中的上下文膨胀问题。AbstractFilesystem.grep/glob 的接口目前没有 limit 参数，各 filesystem backend 仍会完成全量搜索并将匹配项物化后，再由工具层截断输出。

因此，这一版能够限制工具消息大小，但尚未限制病态搜索场景下的后端扫描时间和内存占用。把 limit 下推到 AbstractFilesystem 和各后端、支持扫描阶段提前终止，是更完整但影响范围更大的后续优化；还需要同时确定 Composite/Overlay 合并排序、去重以及 hasMore / truncated 的语义。

想请维护者确认的取舍

这版数值和落点并非一定要固定，希望听取维护者意见：

1. 默认值采用 grep=100、glob=200，硬上限为 1000，是否符合项目的常见工作区规模？是否更倾向两个工具使用同一默认值？
2. 当前限制放在 FilesystemTool 输出边界，能以较小改动解决上下文膨胀，并兼容所有 filesystem backend；后续是否希望继续把 limit 下推到 AbstractFilesystem 及各后端，以便在扫描阶段提前停止、进一步降低 I/O 和内存开销？
3. grep_files / glob_files 是否应该恢复参与默认 eviction？当前实现认为“条数限制 + 字符数 eviction”是两层互补保护；如果维护者希望维持原有排除策略，我也可以只保留条数限制。
4. 截断提示目前使用纯文本，是否需要在后续演进为带 truncated / next_offset 等字段的结构化结果或分页接口？
5. 从压缩策略角度，是否也希望单独调整 recent tool-result protection，使单条超大结果即使位于保护窗口内也能被裁剪？这可以作为与工具侧限流互补的后续改进。

如果项目对默认值、API 形态或分层位置有既定方向，我可以按维护者建议调整本 PR。

兼容性

• 原有 Java 调用签名继续保留，并委托到带 limit 的新方法；
• 小于默认上限的搜索结果格式保持不变；
• limit 在工具 schema 中是可选参数。

验证

• mvn -pl agentscope-harness -am '-Dtest=FilesystemToolTest,ToolResultEvictionMiddlewareTest' '-Dsurefire.failIfNoSpecifiedTests=false' test
• mvn -pl agentscope-harness -am -DskipTests package

Fixes #2831

[codecov]

Codecov Report

❌ Patch coverage is 89.65517% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../agentscope/harness/agent/tool/FilesystemTool.java	89.65%	1 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[guslegend0510]

看过了，这版核心功能是实际生效的：grep_files / glob_files 已实现默认条数限制、1000 条硬上限和截断提示，相关测试也通过。
作为解决 #2831 常规上下文膨胀问题的第一阶段方案，我认为可以。需要明确的是，目前只限制最终返回条数，底层仍会全量扫描和物化结果，单条超长内容也没有字符级硬限制；这些可以作为后续优化，不阻塞本次 PR。

[guslegend0510]

LGTM