fix(harness): 保留跳过摘要时的轻量上下文裁剪结果

[yyyzl]

关联问题

Fixes #2970

AgentScope-Java Version

2.0.3-SNAPSHOT，基于 main 的 ea511ec2f68ca929a6bbc4e92cd0c0952a38c592。

背景与必要性

ConversationCompactor.compactIfNeeded() 在判断是否需要 LLM 摘要前，先执行工具参数截断和工具结果裁剪。但下面两个提前返回分支会丢弃已经生成的裁剪结果：

1. 裁剪后的 token 数低于摘要触发阈值；
2. 触发了摘要，但安全切分点为 0，没有可摘要的前缀。

这两个分支都返回 Optional.empty()。CompactionMiddleware 因此继续传递原始 ReasoningInput，也不更新工作 AgentState。结果是：轻量裁剪确实执行了，下一次模型请求却仍携带原始大段内容，可能继续触发上下文超限。

这与 #2267 / #2319 修复的 ToolResultEvictionMiddleware 状态和输入不同步问题不同；本次问题位于 ConversationCompactor 的提前返回路径。

变更内容

1. 保存轻量裁剪产生的替换列表，在上述两个分支中返回；只有消息未变化时才返回 Optional.empty()。
2. 复用现有调用方处理非空结果的逻辑，使模型输入和工作状态都得到裁剪后的消息，无需修改 Middleware 或新增返回类型。
3. 更新公开方法的 Javadoc：非空结果既可能是轻量裁剪后的消息，也可能是摘要加保留尾部。
4. 增加真实 Middleware 调用边界的回归测试，不 mock compactor。

两个轻量处理方法在无改动时都会返回原列表，因此这里只比较列表引用，不对大段消息做深度比较。

复现与验证

最小输入为一条用户消息、一条工具调用及其匹配结果。工具结果含 "x".repeat(10_000)；配置 triggerTokens(1_000)、keepTokens(0)、keepMessages(20)，以及 protectTokens(0)、minimumTokens(1)、maxOutputChars(100) 的裁剪策略。裁剪后低于阈值，但原实现仍把原始请求传给 next。

设置 triggerMessages(3) 可覆盖安全切分点为 0 的分支；将大段内容放到 write_file 参数并启用参数截断，可复现参数截断对应的两个分支。

新增 6 个参数化场景：

• 工具结果裁剪 / 工具参数截断 × 低于摘要阈值 / 安全切分点为 0，共 4 个场景；
• 两个提前返回分支下消息确实未变化的 2 个对照场景。

修复前：4 个裁剪场景全部失败，2 个无变化场景通过。修复后：ConversationCompactorTest 和 CompactionMiddlewareTest 共 23 项全部通过。

此外，mvn -pl agentscope-harness -am test 构建成功：Core 共 2,318 项（跳过 9 项），Harness 共 925 项（跳过 5 项），均为 0 failures / 0 errors。验证环境为 Java 17 / Maven 3.8.7，运行时状态目录隔离到临时测试目录。

断言同时检查下游输入、工作状态、原输入不被修改、系统消息和工具调用配对保留、tools/options 透传，并确认轻量裁剪不触发模型调用。测试使用 mock model，不需要模型凭证或网络调用。

mvn -pl agentscope-harness spotless:apply
mvn -pl agentscope-harness -am \
  -Dtest=ConversationCompactorTest,CompactionMiddlewareTest \
  -Dsurefire.failIfNoSpecifiedTests=false test
mvn -pl agentscope-harness -am test

当前范围与兼容性

• 保留现有方法签名，不新增依赖、配置或 LLM 调用。
• 不改摘要逻辑、异常降级和中断传播。
• 不改变默认参数截断开关、裁剪阈值、排除工具和最近消息保护窗口。
• 本 PR 只保证“已经做出的裁剪能被使用”，不保证所有超大上下文都能降到模型窗口内；处于保护窗口的内容、未启用参数截断的工具输入，仍需按原有策略处理。

想请维护者确认的取舍

这里保留 Optional<List<Msg>>，将非空结果解释为“存在应应用的替换消息”，不再隐含“一定生成了摘要”。目前仓内两个生产调用点都按替换列表使用结果。希望确认这一返回语义是否符合项目预期；若外部调用方需要区分轻量裁剪和摘要，可另行讨论显式结果类型，本 PR 暂不扩大 API 改动范围。

Checklist

• 已执行 Harness 模块的 mvn spotless:apply。
• 已运行并通过本次改动对应的聚焦测试。
• Core/Harness 全量测试构建成功；跳过项数量见验证结果。
• 已更新 Javadoc，说明轻量裁剪结果的返回语义。
• 无需修改公开配置文档或使用示例。
• 代码可供审查。

验证范围为 Core/Harness，未宣称其他所有模块的全仓 mvn test 已通过。

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!