fix: prevent truncation logic from removing the only user message in long tool-calling conversations

[leonforcode]

压缩算法删除 user 消息 Bug 修复报告 关联 Issue:#6196

修复文件：core/astrbot/core/agent/context/truncator.py

---

1. 问题现象

AstrBot 在长工具调用链场景下（1 条 user 消息 + 大量 assistant/tool 循环），调用智谱 (Zhipu) 大模型 API 时报错：

Error code: 400 - {'error': {'code': '1214', 'message': 'messages 参数非法。请检查文档。'}}

主模型 glm-4.7 和备用模型 glm-5 均返回同样错误，导致本轮对话彻底失败。

---

2. 问题分析

2.1 日志关键线索

[BefCompact] RunCtx.messages -> [44] system,user,assistant,tool,...,assistant,tool
[AftCompact] RunCtx.messages -> [41] system,assistant,tool,...,assistant,tool

压缩前有 44 条消息，压缩后变成 41 条。关键变化：user 消息在压缩后消失了，消息序列从 system,user,... 变成了 system,assistant,...。

2.2 根本原因

问题出在 truncator.py 的截断逻辑中。调用链如下：

manager.py: process()
  → 检查 token 超限 → TruncateByTurnsCompressor.__call__()
    → truncator.truncate_by_dropping_oldest_turns()
      → 如果还超限 → truncator.truncate_by_halving()

三个截断方法（truncate_by_turns、truncate_by_dropping_oldest_turns、truncate_by_halving）都存在同一缺陷：

1. 将消息分为 system_messages + non_system_messages
2. 从 non_system_messages 前端或中间截断
3. 在截断后的列表中查找第一个 user 消息，如果找不到就清空或以 assistant 开头

在纯工具调用对话中（用户只发了 1 条消息，后面全是 assistant/tool 循环），唯一的 user 消息位于 non_system_messages 最前端。截断时被删除后，剩余消息全是 assistant/tool，没有任何 user 消息。

这导致发送给 API 的消息格式变成 system → assistant → tool → ...，违反了智谱 API 的格式要求（system 后必须紧跟 user），触发 1214 错误。

2.3 影响范围

• 所有使用智谱（及其他对消息格式有严格要求的）模型的场景
• 长工具调用链对话（单条 user 消息 + 多轮 tool 调用）最容易触发
• truncate_by_dropping_oldest_turns()、truncate_by_halving()、truncate_by_turns() 三个方法均存在此问题

---

3. 修复方案

3.1 修改策略

在 truncator.py 中新增两个方法，并修改三个截断方法的返回逻辑：

变更	说明
新增 _split_system_and_rest()	提取重复的 system/非system 拆分逻辑为公共方法，消除三处重复代码
新增 _ensure_first_user_message()	核心修复方法。在截断结果中检查是否仍保留 user 消息；如果被截掉，则从原始消息列表中找回第一条 user 消息并插入到 system 之后
修改 truncate_by_turns()	末尾改为调用 _ensure_first_user_message()
修改 truncate_by_dropping_oldest_turns()	末尾改为调用 _ensure_first_user_message()（报错的直接触发点）
修改 truncate_by_halving()	末尾改为调用 _ensure_first_user_message()

3.2 _ensure_first_user_message() 核心逻辑

def _ensure_first_user_message(self, system_messages, non_system_messages, original_messages):
    # 1. 快速路径：截断后第一条非system消息已是 user → 直接返回
    # 2. 否则从原始消息中找到第一条 user 消息
    # 3. 用 identity check (is) 避免重复插入
    # 4. 将 user 消息插入到 system 之后、其余消息之前
    # 5. 最后经过 fix_messages() 修复 tool_call 配对

---

4. 测试验证

#	测试场景	结果
1	1 条 user + 20 轮 tool 调用，drop oldest 1 轮	✅ system→user 保持
2	1 条 user + 21 轮 tool 调用，对半砍	✅ system→user 保持
3	1 条 user + 20 轮 tool 调用，keep=5 轮	✅ system→user 保持
4	极端：drop 19 轮（几乎全删）	✅ system→user 保持
5	正常多轮对话（多个 user 消息）	✅ 无回归影响
6	TruncateByTurnsCompressor 端到端完整流程	✅ 消息格式合法

---

5. 文件清单

文件	说明
truncator.py	修复后的完整文件副本
修复报告.md	本文档

---

6. 注意事项

• 修改后需要重启 AstrBot 实例才能生效

Summary by Sourcery

Ensure conversation truncation preserves a leading user message after system messages to satisfy LLM API requirements and avoid invalid message sequences.

Bug Fixes:

• Prevent truncation logic from removing the only user message in long tool-calling conversations, which caused invalid system→assistant/tool-only message sequences and downstream API errors.

Enhancements:

• Refactor repeated system/non-system message splitting into a shared helper used by all truncation strategies.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

此拉取请求旨在增强 AstrBot 消息截断算法的鲁棒性，特别是在处理与对消息格式有严格要求的大模型 API 交互时。通过引入新的辅助方法，确保即使在极端截断情况下，对话消息序列也能保持其逻辑完整性，尤其是 system 消息后必须紧跟 user 消息的约定，从而避免因消息格式错误导致的 API 调用失败，提升了系统的稳定性和用户体验。

Highlights

• 修复核心问题: 解决了在长工具调用链场景下，消息截断算法可能错误删除用户（user）消息，导致智谱（Zhipu）等大模型 API 报错的问题。此问题表现为 system 消息后缺少 user 消息，违反了 API 格式要求。
• 引入通用消息拆分逻辑: 新增了 _split_system_and_rest() 方法，将消息列表拆分为系统消息和非系统消息的通用逻辑进行封装，减少了 truncator.py 中多处重复代码。
• 确保首条用户消息存在: 新增了核心修复方法 _ensure_first_user_message()。该方法在消息截断后，检查并确保消息列表中始终包含第一条用户消息，并将其放置在系统消息之后，以满足大模型 API 的严格格式要求。
• 重构截断方法: 修改了 truncate_by_turns()、truncate_by_dropping_oldest_turns() 和 truncate_by_halving() 三个截断方法，使其在完成截断后调用 _ensure_first_user_message() 来校正消息顺序，确保消息格式的合法性。

Changelog

• astrbot/core/agent/context/truncator.py
  • 新增了 _split_system_and_rest 方法，用于统一系统消息和非系统消息的拆分逻辑。
  • 新增了 _ensure_first_user_message 方法，确保截断后的消息列表中包含并正确放置首条用户消息。
  • 修改了 truncate_by_turns 方法，使其使用新的消息拆分和用户消息确保逻辑。
  • 修改了 truncate_by_dropping_oldest_turns 方法，使其使用新的消息拆分和用户消息确保逻辑。
  • 修改了 truncate_by_halving 方法，使其使用新的消息拆分和用户消息确保逻辑。

Activity

• 目前没有新的活动报告。

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="astrbot/core/agent/context/truncator.py" line_range="23-29" />
<code_context>
+        Returns:
+            tuple: (system_messages, non_system_messages)
+        """
+        first_non_system = 0
+        for i, msg in enumerate(messages):
+            if msg.role != "system":
+                first_non_system = i
+                break
+
+        return messages[:first_non_system], messages[first_non_system:]
+
+    def _ensure_first_user_message(
</code_context>
<issue_to_address>
**issue:** _split_system_and_rest mishandles the case where all messages are system-role

When all messages are system-role, `first_non_system` stays 0 and the function returns `([], messages)`, treating every system message as non-system. This contradicts the contract and risks truncating or misclassifying system prompts. Consider initializing `first_non_system = len(messages)` or explicitly handling the "no non-system message" case so that all messages are treated as system messages in that scenario.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[gemini-code-assist]

Code Review

This pull request refactors message truncation logic by extracting common message splitting into a new _split_system_and_rest helper method. It also introduces a new _ensure_first_user_message helper to guarantee that truncated message lists always start with system messages followed by a user message, addressing a requirement of certain LLM APIs. These new helpers are integrated into existing truncation functions like truncate_by_turns, truncate_by_dropping_oldest_turns, and truncate_by_halving to improve code reusability and ensure API compatibility.