核心概念
消息元数据
使用消息元数据控制消息的可见性和分类
消息元数据
消息元数据系统允许精细控制消息在不同受众（用户界面、LLM 上下文）中的可见性。
📋 概述
每条消息可以附带 MessageMetadata，控制其可见性和分类：
type MessageMetadata struct {
UserVisible bool // 是否对用户 UI 可见
AgentVisible bool // 是否包含在 LLM 上下文中
Source string // 消息来源标识
Tags []string // 自定义标签
}
🎯 使用场景
| 场景 | UserVisible | AgentVisible | 说明 |
|---|---|---|---|
| 普通消息 | ✅ | ✅ | 默认行为 |
| 系统摘要 | ❌ | ✅ | 用户无需看到内部摘要 |
| 用户反馈 | ✅ | ❌ | 纯展示，不影响 LLM |
| 已归档消息 | ❌ | ❌ | 压缩后的旧消息 |
🛠️ 创建消息元数据
工厂方法
import "github.com/astercloud/aster/pkg/types"
// 创建默认元数据（双方可见）
meta := types.NewMessageMetadata()
// 仅 Agent 可见（用于摘要）
meta := types.NewMessageMetadata().AgentOnly()
// 仅用户可见（用于反馈）
meta := types.NewMessageMetadata().UserOnly()
// 双方不可见（已归档）
meta := types.NewMessageMetadata().Invisible()
链式设置
meta := types.NewMessageMetadata().
AgentOnly().
WithSource("summary").
WithTags("context", "compressed")
📝 附加到消息
msg := types.Message{
Role: types.RoleSystem,
Content: "## 对话历史摘要\n之前讨论了项目架构...",
Metadata: types.NewMessageMetadata().
AgentOnly().
WithSource("summary"),
}
🔍 过滤消息
根据可见性过滤消息列表：
import "github.com/astercloud/aster/pkg/types"
messages := []types.Message{...}
// 过滤出 Agent 可见的消息（发送给 LLM）
agentMessages := types.FilterMessagesForAgent(messages)
// 过滤出用户可见的消息（显示在 UI）
userMessages := types.FilterMessagesForUser(messages)
// 自定义过滤
filtered := types.FilterMessages(messages, func(m *types.Message) bool {
return m.Metadata == nil || m.Metadata.UserVisible
})
// 按来源过滤
summaries := types.FilterMessagesBySource(messages, "summary")
// 按标签过滤
important := types.FilterMessagesByTag(messages, "important")
🔄 与上下文压缩集成
消息元数据与 Summarization 中间件配合使用：
// 压缩旧消息时，不删除而是标记为不可见
for i := range oldMessages {
if oldMessages[i].Metadata == nil {
oldMessages[i].Metadata = types.NewMessageMetadata()
}
oldMessages[i].Metadata.Invisible()
}
// 创建摘要消息，仅 Agent 可见
summaryMsg := types.Message{
Role: types.RoleSystem,
Content: summary,
Metadata: types.NewMessageMetadata().
AgentOnly().
WithSource("summary"),
}
📊 来源标识
推荐的 Source 值：
| 来源 | 说明 |
|---|---|
user | 用户输入 |
system | 系统消息 |
summary | 自动生成的摘要 |
tool | 工具执行结果 |
memory | 从长期记忆加载 |
feedback | 用户反馈/评价 |
💡 最佳实践
- 默认可见：不设置 Metadata 的消息默认对双方可见
- 向后兼容：Metadata 使用
omitempty，旧数据自动兼容 - 摘要标记 AgentOnly：压缩生成的摘要不需要显示给用户
- 保留原始消息：使用 Invisible 而非删除，便于审计和恢复
- 合理使用标签：Tags 用于业务分类，便于后续检索