🎯 今日核心问题
- system 和 user 在模型眼里真的是两种东西吗?为什么 system 里的规则更容易被遵守?
- assistant 消息除了 content 还要保存什么?为什么 tool 消息必须带
tool_call_id? - 多轮对话里,历史消息该全量带上,还是裁剪?裁哪些、留哪些?
📖 精读提纲
【一】四种角色的语义边界
system:定义"你是谁、遵守什么规则、何时调什么工具"。它在训练中被赋予了更高的指令优先级,是唯一适合放长期不变约束的位置。实战要点:写清"未拿到工具结果前不得猜测数据"这类硬约束;工具清单和输出格式也放这里;不要把用户输入拼进 system,那是注入攻击的入口。
user:用户真实输入。多轮场景下是标准的 user/assistant 交替。不要在这里塞系统指令("请用 JSON 输出")——一旦多轮,模型会把它当普通对话内容,遵守度骤降。
assistant:模型自己的历史输出,包含两种形态:纯文本,或带 tool_calls 的行动指令。回填时必须原样保留 tool_calls 数组和 content(可能是 null),因为下一步的 tool 消息要靠 tool_call_id 和它配对。丢掉 id 就是 400。
tool:工具执行结果,结构固定为 {role:"tool", tool_call_id, content}。content 永远建议是字符串形式的 JSON,不要塞自然语言摘要。tool 消息不能凭空出现——前面必须有一条 assistant 消息声明了对应 id,这是协议强校验。
【二】消息链的合法形态
顺序规则只有一条:system? → ( user → assistant(+tool_calls) → tool* → assistant ... )*。也就是每个 tool 消息必须紧跟在一组 tool_calls 之后,个数和 id 一一对应。一轮里模型调用 2 个工具,你就得回 2 条 tool 消息,少一条模型会拒绝。
多轮时,上一轮的 tool_calls 和 tool 结果可以保留也可以裁剪。经验:保留它们能提升连贯性,但 token 涨得快。折中做法是保留最近 2 轮的完整 tool 交换,更早的只留 user/assistant 文本,并把被裁掉的工具调用改写成一行摘要塞进 assistant 的 content,比如"(已查询杭州天气:小雨 18℃)"。
【三】实战应用:Spring Boot 场景——用 sealed interface 建模消息
Map 拼消息的最大问题是编译期无保护。用 Java 17 的 sealed interface + record 建模,配合 Jackson 的 @JsonTypeInfo 多态序列化,可以在编译期拦住 90% 的字段错误:SystemMsg(String content)、UserMsg(String content)、AssistantMsg(String content, List<ToolCall> toolCalls)、ToolMsg(String toolCallId, String content)。
发送前用一个 MessageValidator 做结构校验:每个 ToolMsg.toolCallId 都能在前面找到对应的 ToolCall.id;同一组 tool_calls 的返回数量匹配。这类校验放在序列化之前,出错时打印完整消息链(明天 D6 专门讲打印技巧),你就不用再对着 400 错误瞎猜。
【四】常见误区
- ❌ tool 消息不带 id 或 id 写错。最常见的一类 bug。建议用 record 强制传参,别用 Map。
- ❌ 把工具 id 用序号代替。必须用模型返回的原 id(如
call_a1b2),自己生成会失配。 - ❌ 所有规则塞 system 就以为万事大吉。system 太长(超 500 字)后约束会被稀释,优先级靠前的规则更有效。
- ❌ 历史里保留大段工具原始返回。一个 5KB 的订单 JSON 留在上下文里,后续每轮都重付 token。落库留全量,进上下文要裁剪。
💻 代码示例
// AgentMessage.java —— 类型安全的消息协议(Java 17 sealed + record)
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "role")
@JsonSubTypes({
@JsonSubTypes.Type(value = SystemMsg.class, name = "system"),
@JsonSubTypes.Type(value = UserMsg.class, name = "user"),
@JsonSubTypes.Type(value = AssistantMsg.class, name = "assistant"),
@JsonSubTypes.Type(value = ToolMsg.class, name = "tool")
})
public sealed interface AgentMessage
permits SystemMsg, UserMsg, AssistantMsg, ToolMsg {}
public record SystemMsg(String content) implements AgentMessage {}
public record UserMsg(String content) implements AgentMessage {}
public record AssistantMsg(String content, List<ToolCall> toolCalls) implements AgentMessage {
@JsonInclude(JsonInclude.Include.NON_NULL)
public record ToolCall(String id, String type, Function function) {
public record Function(String name, String arguments) {}
}
}
public record ToolMsg(String toolCallId, String content) implements AgentMessage {}
// MessageValidator.java —— 发请求前的结构校验,把 400 挡在本地
@Component
public class MessageValidator {
public void validate(List<AgentMessage> msgs) {
Set<String> pending = new HashSet<>();
for (AgentMessage m : msgs) {
if (m instanceof AssistantMsg a && a.toolCalls() != null) {
a.toolCalls().forEach(c -> pending.add(c.id()));
} else if (m instanceof ToolMsg t) {
if (!pending.remove(t.toolCallId())) {
throw new IllegalStateException(
"tool_call_id 无归属: " + t.toolCallId() + " | 当前消息链: " + msgs);
}
}
}
if (!pending.isEmpty()) throw new IllegalStateException("以上 tool_calls 缺少返回: " + pending);
}
}
// 使用
List<AgentMessage> msgs = new ArrayList<>();
msgs.add(new SystemMsg("你是天气助手。必须以工具返回为准,不得编造天气。"));
msgs.add(new UserMsg("杭州今天要带伞吗"));
validator.validate(msgs);
String json = om.writeValueAsString(msgs); // 自动带 role 字段
✏️ 今日动手
- 把昨天的
AgentMini从List<Map>重构为List<AgentMessage>,四种 record 全部建好,用om.writeValueAsString打印一条 AssistantMsg,确认输出里的role字段和tool_calls[].function.arguments(字符串)形态正确。 - 写
MessageValidator并加两个单元测试:漏掉一条 tool 消息应抛异常;id 对不上应抛异常。 - 把
SystemMsg的 content 写完整(角色 + 工具使用规则 + "无数据不许猜"),然后故意问一个工具查不到的城市,看模型会不会编造——这是检验 system 有效性的最快方法。
交付物:AgentMessage 四件套 + MessageValidator + 2 个通过的单元测试。
🔖 明日预告
消息协议规范了,但循环还没有刹车的逻辑。明天讲终止条件:除了"模型不再调工具"这个自然终止,还要处理步数上限、token 预算、重复调用检测、以及"模型反复调同一个工具同一组参数"这种死循环。这几种情况在你的账单上都是真金白银。