下一轮上下文与多模态输入

选择用户输入还是宿主上下文

用户说的话作为普通消息发送；宿主从业务系统取得、只对下一轮有效的信息，可以用 SetNextTurnContext 注入。两者应在你的数据模型中保留来源，不能把外部文档内容直接当作用户授权。

下一轮上下文不是秘密存储。即使不写入用户 transcript，它仍可能进入模型请求，因此不能放入不应交给模型的凭据或个人数据。

注入上下文

err := session.Control().SetNextTurnContext(ctx, []client.InternalContextBlock{
    {Name: "task_scope", Content: "本次只整理用户已选择的三份文件。", Priority: 100},
    {Name: "output_language", Content: "交付文件使用简体中文。", Priority: 10},
})
if err != nil { return err }
stream, err := session.Send(ctx, "请开始整理。")
if err != nil { return err }
result, err := stream.Result(ctx)
if err != nil { return err }
if result.IsError { return fmt.Errorf("任务失败：%s", result.Subtype) }
fmt.Println(result.Result)

Bridge 按优先级降序，再按名称、内容和 metadata 确定性排序。nxs 将提醒保留在实时模型历史中，但不写 transcript；Claude Code 通过 UserPromptSubmit 的 additionalContext 生成对应 attachment。

设置与发送应由同一会话调度流程执行。两者之间若插入另一个用户消息，上下文可能绑定到不符合预期的那一轮。设置后取消、或转为发送独立 slash command 时，可调用 ClearNextTurnContext 清理尚未绑定的内容。

发送文本与图片

message := protocol.NewUserBlocksMessage(
    protocol.NewTextContent("描述这张图中的界面布局。"),
    protocol.NewImageContent(imageBase64, "image/png"),
)
stream, err := session.SendMessage(ctx, message)
if err != nil { return err }
result, err := stream.Result(ctx)
if err != nil { return err }
if result.IsError { return fmt.Errorf("任务失败：%s", result.Subtype) }
fmt.Println(result.Result)

imageBase64 是图片字节的 Base64 编码，不是文件路径。宿主应先校验文件大小、真实格式和用户访问权限，再生成内容块。模型是否支持图像、输入限制多大，由运行时和模型决定。

文档可使用 NewDocumentContent。它接受 source、MIME 类型和标题；source 的具体表示必须遵守所选运行时的协议，不能把任意本地路径或 URL 填进去就假定会下载或解析。纯文本材料可先由宿主读取成文本块。

单条消息的限制

SendWithOptions 可以携带 MessageUUID、ToolAccess、MaxOutputTokens、SkipAutoMemory 等选项。其中执行策略需要 CapabilityMessageExecutionPolicy 协商。未支持时必须拒绝受限发送，不能悄悄退回普通消息。

ToolAccess: "none" 表示此轮不使用工具，适合基于已有上下文生成解释；它不表示“整个 Agent 永久禁用工具”。SkipAutoMemory 也不应被当作整个会话不持久化的替代配置。

消息身份与删除

MessageUUID 允许宿主提前指定消息身份，便于关联准入与持久化。RemoveMessages 可以删除指定消息并同步运行时 transcript，但不会撤销工具已经造成的外部副作用。删除聊天记录、回滚文件与取消任务应使用不同的业务操作。

需要从已有结果另开方案时，使用会话分叉，不要通过删除历史来模拟分支。