protocol

package
v0.1.27 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 19, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package protocol 是跨 HTTP/WebSocket/前端/运行时边界共享的协议真相源。

L2 | 父级: internal（L1 见 AGENTS.md）

只放跨边界共享的协议模型、枚举、事件构造和代码生成输入；服务内部输入、仓储 DTO、 持久化 codec 留在对应 internal/service/* 或 internal/storage/*。

成员清单（按域，本包整体即协议模型，故文件不再加 model_ 前缀）：

  • session*.go：Session / Message / SessionKey 统一会话模型。
  • room*.go：房间、成员、directed message。
  • conversation_turn.go / event.go / goal.go / input_queue.go： 对话投影、统一事件类型与权威 runtime slot 快照、Goal 生命周期/objective revision、输入队列快照与持久接受 ACK。
  • chat_attachment.go / workspace_file_artifact.go / delivery_policy.go： 聊天附件、工作区文件产物、投递策略。
  • identity.go / value.go：ID 生成与跨边界值解码。
  • generate.go / typescript_event.go：前端 TS 类型代码生成入口（go:generate）。

[PROTOCOL]: 变更时更新此头部，然后检查父级入口 AGENTS.md（L1）

[INPUT]: 依赖会话/运行时跨边界状态与时间戳。 [OUTPUT]: 对外提供统一事件类型、请求 ACK 与权威 pending slot 快照事件。 [POS]: protocol 包的 WebSocket 事件真相源。

INPUT: 跨 HTTP/WS/runtime 的 Goal 状态、请求与 continuation 数据。 OUTPUT: Goal 领域协议、Room creator/lead 权限身份及归一化常量。 POS: Goal 前后端与运行时共享的协议真相源。

INPUT: 输入队列项、变更结果与客户端请求关联 ID。 OUTPUT: 对外提供输入队列协议模型、快照事件与持久接受 ACK。 POS: protocol 包的输入队列跨边界真相源。

INPUT: protocol 包的事件、ACK 与会话投影契约。 OUTPUT: 生成前端共享 TypeScript 类型的单一文本定义。 POS: Go 协议模型到 web 类型面的代码生成输入。

Index

Constants

View Source 
const (
	ChatAttachmentKindText  ChatAttachmentKind = "text"
	ChatAttachmentKindImage ChatAttachmentKind = "image"
	ChatAttachmentKindFile  ChatAttachmentKind = "file"

	ChatAttachmentScopeAgentWorkspace   ChatAttachmentScope = "agent_workspace"
	ChatAttachmentScopeRoomConversation ChatAttachmentScope = "room_conversation"
)
View Source 
const (
	GoalMetadataRoomGoalScope                         = "room_goal_scope"
	GoalMetadataRoomGoalCreatorAgentID                = "room_goal_creator_agent_id"
	GoalMetadataRoomGoalLeadAgentID                   = "room_goal_lead_agent_id"
	GoalMetadataRoomGoalLeadAgentName                 = "room_goal_lead_agent_name"
	GoalMetadataRoomGoalLoopSlug                      = "room_goal_loop_slug"
	GoalMetadataRoomGoalLoopTitle                     = "room_goal_loop_title"
	GoalMetadataRoomGoalCollaborationRequired         = "room_goal_collaboration_required"
	GoalMetadataRoomGoalCollaborationObserved         = "room_goal_collaboration_observed"
	GoalMetadataRoomGoalCollaborationAgentID          = "room_goal_collaboration_agent_id"
	GoalMetadataRoomGoalCollaborationRoundID          = "room_goal_collaboration_round_id"
	GoalMetadataRoomGoalCollaborationObservedAt       = "room_goal_collaboration_observed_at"
	GoalMetadataRoomGoalCollaborationRequirementRound = "room_goal_collaboration_requirement_round_id"
	GoalMetadataObjectiveRevision                     = "objective_revision"
)
View Source 
const (
	// RoomTypeDM 表示单成员直聊房间。
	RoomTypeDM = "dm"
	// RoomTypeGroup 表示多人协作房间。
	RoomTypeGroup = "room"
	// ConversationTypeDM 表示 DM 主对话。
	ConversationTypeDM = "dm"
	// ConversationTypeMain 表示 Room 主对话。
	ConversationTypeMain = "room_main"
	// ConversationTypeTopic 表示 Room 话题对话。
	ConversationTypeTopic = "topic"
	// MemberTypeUser 表示用户成员。
	MemberTypeUser = "user"
	// MemberTypeAgent 表示 Agent 成员。
	MemberTypeAgent = "agent"
)
View Source 
const (
	// SessionChannelWebSocketSegment 表示 session_key 中的 WebSocket 通道段。
	SessionChannelWebSocketSegment = "ws"
	// SessionChannelDiscordSegment 表示 session_key 中的 Discord 通道段。
	SessionChannelDiscordSegment = "dg"
	// SessionChannelTelegramSegment 表示 session_key 中的 Telegram 通道段。
	SessionChannelTelegramSegment = "tg"
	// SessionChannelDingTalkSegment 表示 session_key 中的钉钉通道段。
	SessionChannelDingTalkSegment = "dt"
	// SessionChannelWeChatSegment 表示 session_key 中的微信通道段。
	SessionChannelWeChatSegment = "wx"
	// SessionChannelWeixinPersonalSegment 表示个人微信 iLink 通道段。
	SessionChannelWeixinPersonalSegment = "weixin-personal"
	// SessionChannelFeishuSegment 表示 session_key 中的飞书通道段。
	SessionChannelFeishuSegment = "fs"
	// SessionChannelInternalSegment 表示 session_key 中的内部通道段。
	SessionChannelInternalSegment = "internal"

	// SessionChannelWebSocket 表示持久化后的 WebSocket 通道类型。
	SessionChannelWebSocket = "websocket"
	// SessionChannelDiscord 表示持久化后的 Discord 通道类型。
	SessionChannelDiscord = "discord"
	// SessionChannelTelegram 表示持久化后的 Telegram 通道类型。
	SessionChannelTelegram = "telegram"
	// SessionChannelDingTalk 表示持久化后的钉钉通道类型。
	SessionChannelDingTalk = "dingtalk"
	// SessionChannelWeChat 表示持久化后的微信通道类型。
	SessionChannelWeChat = "wechat"
	// SessionChannelWeixinPersonal 表示持久化后的个人微信 iLink 通道类型。
	SessionChannelWeixinPersonal = "weixin-personal"
	// SessionChannelFeishu 表示持久化后的飞书通道类型。
	SessionChannelFeishu = "feishu"

	// AutomationInboxSessionRef 表示定时任务投递到 Agent 时使用的固定内部会话。
	AutomationInboxSessionRef = "automation-inbox"
)
View Source 
const (
	// OptionRuntimeKind 表示创建/续用 SDK session 时使用的 runtime 类型。
	OptionRuntimeKind = "runtime_kind"
	// OptionRuntimeProvider 表示创建/续用 SDK session 时使用的 provider key。
	OptionRuntimeProvider = "runtime_provider"
	// OptionRuntimeModel 表示创建/续用 SDK session 时使用的模型。
	OptionRuntimeModel = "runtime_model"
)
View Source 
const (
	WorkspaceFileArtifactOperationWrite  = "write"
	WorkspaceFileArtifactOperationUpdate = "update"
)
View Source 
const (
	WorkspaceFileArtifactKindFile     = "file"
	WorkspaceFileArtifactKindImage    = "image"
	WorkspaceFileArtifactKindMarkdown = "markdown"
	WorkspaceFileArtifactKindHTML     = "html"
	WorkspaceFileArtifactKindMermaid  = "mermaid"
	WorkspaceFileArtifactKindSVG      = "svg"
	WorkspaceFileArtifactKindPDF      = "pdf"
)
View Source 
const ChatAckTimeoutMS = RequestAckTimeoutMS

ChatAckTimeoutMS 保留 chat_ack 的兼容名称；所有请求 ACK 共用同一超时契约。

View Source 
const (
	// ContentBlockTypeWorkspaceFileArtifact 表示 Agent 在工作区生成或更新的文件产物。
	ContentBlockTypeWorkspaceFileArtifact = "workspace_file_artifact"
)
View Source 
const RequestAckTimeoutMS = 10000

RequestAckTimeoutMS 是客户端等待请求 ACK 的上限（毫秒）。 服务端不强制该窗口，但承诺在此之前回 ack； 前端据此设置本地超时，两侧同源避免漂移。

View Source 
const (
	WorkspaceFileArtifactScopeAgentWorkspace = "agent_workspace"
)

Variables

View Source 
var ErrInvalidSessionKey = errors.New("invalid structured session_key")

ErrInvalidSessionKey 表示 session_key 不符合结构化协议。

Functions

func BuildAgentAccountSessionKey added in v0.1.21 

func BuildAgentAccountSessionKey(agentID string, channel string, chatType string, accountID string, ref string, threadID string) string

BuildAgentAccountSessionKey 构建带外部通道账号作用域的 agent key。

func BuildAgentSessionKey 

func BuildAgentSessionKey(agentID string, channel string, chatType string, ref string, threadID string) string

BuildAgentSessionKey 构建 agent 作用域 key。

func BuildRoomAgentSessionKey 

func BuildRoomAgentSessionKey(conversationID string, agentID string, roomType string) string

BuildRoomAgentSessionKey 构建 Room 成员侧的 agent session_key。

func BuildRoomSharedSessionKey 

func BuildRoomSharedSessionKey(conversationID string) string

BuildRoomSharedSessionKey 构建共享 room key。

func ClientErrorMessage added in v0.1.27 

func ClientErrorMessage(err error) (string, bool)

ClientErrorMessage 只读取业务错误显式声明的安全文案，未知内部错误不得穿透到客户端。

func GetSessionKeyValidationError 

func GetSessionKeyValidationError(raw string) string

GetSessionKeyValidationError 返回结构化 session_key 校验错误。

func GoalMetadataBool added in v0.1.16 

func GoalMetadataBool(metadata map[string]any, key string) bool

GoalMetadataBool 从 Goal metadata 中读取布尔值。

func GoalMetadataInt64 added in v0.1.27 

func GoalMetadataInt64(metadata map[string]any, key string) int64

GoalMetadataInt64 从 Goal metadata 中读取 JSON 兼容的整数值。

func GoalMetadataString added in v0.1.16 

func GoalMetadataString(metadata map[string]any, key string) string

GoalMetadataString 从 Goal metadata 中读取字符串值。

func HasChatInput added in v0.1.6 

func HasChatInput(content string, attachments []ChatAttachment) bool

HasChatInput 判断一次用户输入是否包含正文或附件。

func Int64FromAny added in v0.1.27 

func Int64FromAny(value any) int64

Int64FromAny 统一解码 JSON payload 与进程内协议对象中的整数值。 非数字、溢出和非有限浮点数返回 0，调用方无需复制不完整的类型分支。

func IsCurrentGoalStatus added in v0.1.15 

func IsCurrentGoalStatus(status GoalStatus) bool

IsCurrentGoalStatus 判断状态是否属于当前 Goal。

func IsRoomSharedSessionKey 

func IsRoomSharedSessionKey(raw string) bool

IsRoomSharedSessionKey 判断是否为 Room 共享消息流 key。

func IsRuntimeAccountingGoalStatus added in v0.1.15 

func IsRuntimeAccountingGoalStatus(status GoalStatus) bool

IsRuntimeAccountingGoalStatus 判断状态是否应作为运行中 round 的 Goal usage 目标。

func IsRuntimeGoalStatus added in v0.1.15 

func IsRuntimeGoalStatus(status GoalStatus) bool

IsRuntimeGoalStatus 判断状态是否应注入运行时上下文。

func IsTerminalRoundStatus added in v0.1.26 

func IsTerminalRoundStatus(status string) bool

IsTerminalRoundStatus 判断 round / slot 状态是否终态。

func IsTranscriptNativeMessage 

func IsTranscriptNativeMessage(message Message) bool

IsTranscriptNativeMessage 表示该 durable message 是否属于 cc transcript 原生真相。 当前只有 assistant 正文快照属于 transcript 原生消息； result / system / task_progress 等都需要由 Nexus overlay 补齐。

func MessageRole 

func MessageRole(message Message) string

MessageRole 返回消息角色。

func MessageRoundID 

func MessageRoundID(message Message) string

MessageRoundID 返回消息所属 round_id。

func NewAgentRoundID added in v0.1.26 

func NewAgentRoundID() string

NewAgentRoundID 生成 agent slot 执行轮次 id，与 round_id 相互独立。

func NewRoundID added in v0.1.26 

func NewRoundID() string

NewRoundID 生成根业务轮次 id，只允许 Nexus 后端调用。

func NewUserMessageID added in v0.1.26 

func NewUserMessageID() string

NewUserMessageID 生成 durable 用户消息 id。

func NormalizeSessionChatType 

func NormalizeSessionChatType(chatType string) string

NormalizeSessionChatType 统一 chat_type 的默认值和枚举。

func NormalizeSessionKeyChannelSegment 

func NormalizeSessionKeyChannelSegment(channel string) string

NormalizeSessionKeyChannelSegment 把外部输入统一成 session_key 使用的 channel 段。

func NormalizeStoredChannelType 

func NormalizeStoredChannelType(channel string) string

NormalizeStoredChannelType 把 channel 归一成持久化和运行时使用的名称。

func ParseRoomConversationID 

func ParseRoomConversationID(raw string) string

ParseRoomConversationID 读取 Room 共享流里的 conversation_id。

func RequireStructuredSessionKey 

func RequireStructuredSessionKey(raw string) (string, error)

RequireStructuredSessionKey 要求必须是结构化 session_key。

func ShouldGuideRunningRound added in v0.1.2 

func ShouldGuideRunningRound(policy ChatDeliveryPolicy) bool

ShouldGuideRunningRound 判断运行中会话是否接收 hook 引导输入。

func ShouldQueueRunningRound added in v0.1.2 

func ShouldQueueRunningRound(policy ChatDeliveryPolicy) bool

ShouldQueueRunningRound 判断运行中会话默认是否接收排队输入。

func TypeScriptDefinitions 

func TypeScriptDefinitions() string

TypeScriptDefinitions 返回生成前端类型定义所需内容。

Types

type AddRoomMemberRequest 

type AddRoomMemberRequest struct {
	AgentID string `json:"agent_id"`
}

AddRoomMemberRequest 表示追加成员请求。

type Agent 

type Agent struct {
	AgentID         string    `json:"agent_id"`
	Name            string    `json:"name"`
	WorkspacePath   string    `json:"workspace_path"`
	IsMain          bool      `json:"is_main,omitempty"`
	DisplayName     string    `json:"display_name,omitempty"`
	Headline        string    `json:"headline,omitempty"`
	ProfileMarkdown string    `json:"profile_markdown,omitempty"`
	Options         Options   `json:"options"`
	CreatedAt       time.Time `json:"created_at"`
	Status          string    `json:"status"`
	Avatar          string    `json:"avatar,omitempty"`
	Description     string    `json:"description,omitempty"`
	VibeTags        []string  `json:"vibe_tags,omitempty"`
	SkillsCount     int       `json:"skills_count"`
	OwnerUserID     string    `json:"-"`
}

Agent 表示对外 Agent 模型。

type AgentMention added in v0.1.27 

type AgentMention struct {
	AgentID           string `json:"agent_id"`
	Label             string `json:"label"`
	ContentBlockIndex int    `json:"content_block_index"`
	StartRune         int    `json:"start_rune"`
	EndRune           int    `json:"end_rune"`
	HandoffID         string `json:"handoff_id,omitempty"`
}

AgentMention 是消息正文中经过服务端目录解析的 Agent mention span。

type AgentPrivateEvent added in v0.1.9 

type AgentPrivateEvent struct {
	MessageID         string                    `json:"message_id"`
	ThreadID          string                    `json:"thread_id"`
	Direction         string                    `json:"direction"`
	SourceAgentID     string                    `json:"source_agent_id"`
	Recipients        []string                  `json:"recipients"`
	WakeTargets       []string                  `json:"wake_targets,omitempty"`
	Content           string                    `json:"content,omitempty"`
	ReplyRoute        RoomReplyRoute            `json:"reply_route"`
	WakePolicy        RoomWakePolicy            `json:"wake_policy,omitempty"`
	DelaySeconds      int                       `json:"delay_seconds,omitempty"`
	CorrelationID     string                    `json:"correlation_id,omitempty"`
	RootRoundID       string                    `json:"root_round_id,omitempty"`
	CausedByRoundID   string                    `json:"caused_by_round_id,omitempty"`
	HopIndex          int                       `json:"hop_index,omitempty"`
	RoomID            string                    `json:"room_id,omitempty"`
	RoomName          string                    `json:"room_name,omitempty"`
	RoomType          string                    `json:"room_type,omitempty"`
	ConversationID    string                    `json:"conversation_id,omitempty"`
	ConversationTitle string                    `json:"conversation_title,omitempty"`
	Participants      []AgentPrivateParticipant `json:"participants"`
	Timestamp         int64                     `json:"timestamp"`
}

AgentPrivateEvent 表示私域线程内的一条可见 directed message。

type AgentPrivateEventPage added in v0.1.9 

type AgentPrivateEventPage struct {
	Thread AgentPrivateThread  `json:"thread"`
	Items  []AgentPrivateEvent `json:"items"`
}

AgentPrivateEventPage 表示私域线程事件列表响应。

type AgentPrivateParticipant added in v0.1.9 

type AgentPrivateParticipant struct {
	AgentID string `json:"agent_id"`
	Name    string `json:"name,omitempty"`
	Avatar  string `json:"avatar,omitempty"`
}

AgentPrivateParticipant 表示私域投影里的 Agent 参与者摘要。

type AgentPrivateThread added in v0.1.9 

type AgentPrivateThread struct {
	ThreadID            string                    `json:"thread_id"`
	AgentID             string                    `json:"agent_id"`
	Scope               string                    `json:"scope"`
	ParticipantAgentIDs []string                  `json:"participant_agent_ids"`
	PeerAgentIDs        []string                  `json:"peer_agent_ids"`
	Participants        []AgentPrivateParticipant `json:"participants"`
	RoomID              string                    `json:"room_id,omitempty"`
	RoomName            string                    `json:"room_name,omitempty"`
	RoomType            string                    `json:"room_type,omitempty"`
	ConversationID      string                    `json:"conversation_id,omitempty"`
	ConversationTitle   string                    `json:"conversation_title,omitempty"`
	LastMessageID       string                    `json:"last_message_id,omitempty"`
	LastContentPreview  string                    `json:"last_content_preview,omitempty"`
	LastTimestamp       int64                     `json:"last_timestamp,omitempty"`
	MessageCount        int                       `json:"message_count"`
}

AgentPrivateThread 表示从某个 Agent 视角聚合出来的一条私域会话线索。

type AgentPrivateThreadPage added in v0.1.9 

type AgentPrivateThreadPage struct {
	Items []AgentPrivateThread `json:"items"`
}

AgentPrivateThreadPage 表示私域线程列表响应。

type AgentTurnSlot added in v0.1.26 

type AgentTurnSlot struct {
	AgentID            string                  `json:"agent_id"`
	AgentRoundID       string                  `json:"agent_round_id"`
	MsgID              string                  `json:"msg_id,omitempty"`
	Status             string                  `json:"status"`
	AssistantMessages  []ConversationMessage   `json:"assistant_messages"`
	PendingPermissions []TurnPendingPermission `json:"pending_permissions"`
	ResultSummary      map[string]any          `json:"result_summary,omitempty"`
	StartedAt          *int64                  `json:"started_at,omitempty"`
	FinishedAt         *int64                  `json:"finished_at,omitempty"`
}

AgentTurnSlot 表示一个 agent 在某个 turn 中的执行槽位。

type BlockGoalRequest added in v0.1.15 

type BlockGoalRequest struct {
	Reason                    string `json:"reason"`
	NeededInput               string `json:"needed_input,omitempty"`
	RoundID                   string `json:"round_id,omitempty"`
	AgentID                   string `json:"-"`
	ExpectedObjectiveRevision int64  `json:"-"`
}

BlockGoalRequest 表示阻塞 Goal 的请求。

type ChatAckPendingSlot added in v0.1.26 

type ChatAckPendingSlot struct {
	AgentID      string `json:"agent_id"`
	AgentRoundID string `json:"agent_round_id"`
	MsgID        string `json:"msg_id"`
	Status       string `json:"status"`
	Timestamp    int64  `json:"timestamp"`
	Index        int    `json:"index"`
}

ChatAckPendingSlot 表示 chat_ack 中一个 agent slot 的占位信息。

type ChatAttachment added in v0.1.6 

type ChatAttachment struct {
	FileName         string              `json:"file_name"`
	WorkspacePath    string              `json:"workspace_path"`
	WorkspaceAgentID string              `json:"workspace_agent_id,omitempty"`
	RoomID           string              `json:"room_id,omitempty"`
	ConversationID   string              `json:"conversation_id,omitempty"`
	Scope            ChatAttachmentScope `json:"scope,omitempty"`
	Kind             ChatAttachmentKind  `json:"kind"`
	MIMEType         string              `json:"mime_type,omitempty"`
	Size             int64               `json:"size,omitempty"`
}

ChatAttachment 表示一次用户输入绑定的应用层附件。

func ChatAttachmentFromMap added in v0.1.6 

func ChatAttachmentFromMap(value map[string]any) ChatAttachment

ChatAttachmentFromMap 从 map payload 中解析单个附件。

func ChatAttachmentsFromAny added in v0.1.6 

func ChatAttachmentsFromAny(value any) []ChatAttachment

ChatAttachmentsFromAny 从弱类型 payload 中解析附件列表。

func NormalizeChatAttachment added in v0.1.6 

func NormalizeChatAttachment(value ChatAttachment, defaultAgentID string) ChatAttachment

NormalizeChatAttachment 归一化单个聊天附件。

func NormalizeChatAttachments added in v0.1.6 

func NormalizeChatAttachments(values []ChatAttachment, defaultAgentID string) []ChatAttachment

NormalizeChatAttachments 归一化并过滤无效附件。

type ChatAttachmentKind added in v0.1.6 

type ChatAttachmentKind string

ChatAttachmentKind 表示聊天附件的粗粒度类型。

func NormalizeChatAttachmentKind added in v0.1.6 

func NormalizeChatAttachmentKind(value string) ChatAttachmentKind

NormalizeChatAttachmentKind 归一化附件类型。

type ChatAttachmentScope added in v0.1.6 

type ChatAttachmentScope string

func NormalizeChatAttachmentScope added in v0.1.6 

func NormalizeChatAttachmentScope(value string, conversationID string) ChatAttachmentScope

NormalizeChatAttachmentScope 归一化附件存储作用域。

type ChatDeliveryPolicy added in v0.1.2 

type ChatDeliveryPolicy string

ChatDeliveryPolicy 表示新输入遇到运行中会话时的投递策略。 

const (
	// ChatDeliveryPolicyQueue 表示把新输入排入当前流式会话，不中断正在执行的 round。
	ChatDeliveryPolicyQueue ChatDeliveryPolicy = "queue"
	// ChatDeliveryPolicyGuide 表示把新输入暂存在运行时，等待 PostToolUse hook 注入当前 round。
	ChatDeliveryPolicyGuide ChatDeliveryPolicy = "guide"
	// ChatDeliveryPolicyInterrupt 表示先中断当前运行，再启动新的 round。
	ChatDeliveryPolicyInterrupt ChatDeliveryPolicy = "interrupt"
	// ChatDeliveryPolicyAuto 预留给后续智能选择；当前等价于 queue。
	ChatDeliveryPolicyAuto ChatDeliveryPolicy = "auto"
)

func NormalizeChatDeliveryPolicy added in v0.1.2 

func NormalizeChatDeliveryPolicy(value string) ChatDeliveryPolicy

NormalizeChatDeliveryPolicy 归一化前端传入的投递策略。

type CompleteGoalRequest added in v0.1.15 

type CompleteGoalRequest struct {
	Summary                   string `json:"summary,omitempty"`
	RoundID                   string `json:"round_id,omitempty"`
	AgentID                   string `json:"-"`
	ExpectedObjectiveRevision int64  `json:"-"`
}

CompleteGoalRequest 表示完成 Goal 的请求。

type ConversationContextAggregate 

type ConversationContextAggregate struct {
	Room         RoomRecord         `json:"room"`
	Members      []MemberRecord     `json:"members"`
	MemberAgents []Agent            `json:"member_agents,omitempty"`
	Conversation ConversationRecord `json:"conversation"`
	Sessions     []SessionRecord    `json:"sessions"`
}

ConversationContextAggregate 表示房间对话上下文聚合。

type ConversationMessage added in v0.1.26 

type ConversationMessage struct {
	MessageID     string         `json:"message_id"`
	SessionKey    string         `json:"session_key,omitempty"`
	Role          string         `json:"role"`
	RoundID       string         `json:"round_id"`
	AgentRoundID  string         `json:"agent_round_id,omitempty"`
	AgentID       string         `json:"agent_id,omitempty"`
	ParentID      string         `json:"parent_id,omitempty"`
	Content       any            `json:"content"`
	Timestamp     int64          `json:"timestamp"`
	DisplayOrder  int64          `json:"display_order,omitempty"`
	StreamStatus  string         `json:"stream_status,omitempty"`
	ResultSummary map[string]any `json:"result_summary,omitempty"`
	AgentMentions []AgentMention `json:"agent_mentions,omitempty"`
}

ConversationMessage 是投影后的对话消息，round_id 永远是 root round。

type ConversationRecord 

type ConversationRecord struct {
	ID               string    `json:"id"`
	RoomID           string    `json:"room_id"`
	ConversationType string    `json:"conversation_type"`
	Title            string    `json:"title,omitempty"`
	MessageCount     int       `json:"message_count"`
	LastActivityAt   time.Time `json:"last_activity_at,omitempty"`
	CreatedAt        time.Time `json:"created_at,omitempty"`
	UpdatedAt        time.Time `json:"updated_at,omitempty"`
}

ConversationRecord 表示房间对话记录。

type ConversationTurn added in v0.1.26 

type ConversationTurn struct {
	RoundID      string                `json:"round_id"`
	Status       string                `json:"status"`
	CreatedAt    int64                 `json:"created_at"`
	UpdatedAt    int64                 `json:"updated_at"`
	UserMessage  *ConversationMessage  `json:"user_message"`
	AgentSlots   []AgentTurnSlot       `json:"agent_slots"`
	SystemEvents []ConversationMessage `json:"system_events"`
	IsLoaded     bool                  `json:"is_loaded"`
}

ConversationTurn 是前端时间线主对象，也是历史分页单位。

type ConversationTurnIndexItem added in v0.1.26 

type ConversationTurnIndexItem struct {
	RoundID     string   `json:"round_id"`
	CreatedAt   int64    `json:"created_at"`
	UpdatedAt   int64    `json:"updated_at"`
	Status      string   `json:"status"`
	UserPreview string   `json:"user_preview"`
	AgentIDs    []string `json:"agent_ids"`
	Loaded      bool     `json:"loaded"`
}

ConversationTurnIndexItem 是 navigator / 虚拟列表占位用的 turn 索引项。

type CreateConversationRequest 

type CreateConversationRequest struct {
	Title string `json:"title,omitempty"`
}

CreateConversationRequest 表示创建话题请求。

type CreateGoalRequest added in v0.1.15 

type CreateGoalRequest struct {
	SessionKey      string         `json:"session_key"`
	Objective       string         `json:"objective"`
	TokenBudget     *int64         `json:"token_budget,omitempty"`
	ReplaceExisting bool           `json:"replace_existing,omitempty"`
	CreatedBy       string         `json:"created_by,omitempty"`
	RoundID         string         `json:"round_id,omitempty"`
	OwnerUserID     string         `json:"owner_user_id,omitempty"`
	AgentID         string         `json:"-"`
	Metadata        map[string]any `json:"metadata,omitempty"`
}

CreateGoalRequest 表示创建 Goal 的请求。

type CreateRequest 

type CreateRequest struct {
	Name        string   `json:"name"`
	Options     *Options `json:"options,omitempty"`
	Avatar      string   `json:"avatar,omitempty"`
	Description string   `json:"description,omitempty"`
	VibeTags    []string `json:"vibe_tags,omitempty"`
}

CreateRequest 表示创建 Agent 请求。

type CreateRoomDirectedMessageRequest added in v0.1.12 

type CreateRoomDirectedMessageRequest struct {
	// SourceAgentID 只能由受控运行时注入，不能从 JSON body 写入。
	SourceAgentID string `json:"-"`
	// RootRoundID 由受控运行时注入，用于让工具触发的后续轮次继承因果链。
	RootRoundID   string         `json:"-"`
	Recipients    []string       `json:"recipients"`
	WakeTargets   []string       `json:"wake_targets,omitempty"`
	Content       string         `json:"content"`
	WakePolicy    RoomWakePolicy `json:"wake_policy,omitempty"`
	ReplyRoute    RoomReplyRoute `json:"reply_route"`
	DelaySeconds  int            `json:"delay_seconds,omitempty"`
	CorrelationID string         `json:"correlation_id,omitempty"`
}

CreateRoomDirectedMessageRequest 表示创建 Room directed message 的请求。

type CreateRoomPublicMessageRequest added in v0.1.12 

type CreateRoomPublicMessageRequest struct {
	// SourceAgentID 只能由受控运行时注入，不能从 JSON body 写入。
	SourceAgentID string `json:"-"`
	// RootRoundID 由受控运行时注入，用于保证主动广播属于当前 slot 轮次。
	RootRoundID   string `json:"-"`
	Content       string `json:"content"`
	CorrelationID string `json:"correlation_id,omitempty"`
}

CreateRoomPublicMessageRequest 表示受控运行时主动发布公区消息的请求。

type CreateRoomRequest 

type CreateRoomRequest struct {
	AgentIDs               []string `json:"agent_ids"`
	Name                   string   `json:"name,omitempty"`
	Description            string   `json:"description,omitempty"`
	Title                  string   `json:"title,omitempty"`
	Avatar                 string   `json:"avatar,omitempty"`
	SkillNames             []string `json:"skill_names,omitempty"`
	HostAgentID            string   `json:"host_agent_id,omitempty"`
	HostAutoReplyEnabled   bool     `json:"host_auto_reply_enabled,omitempty"`
	PrivateMessagesEnabled bool     `json:"private_messages_enabled,omitempty"`
}

CreateRoomRequest 表示创建房间请求。

type EventMessage 

type EventMessage struct {
	EnvelopeID      string         `json:"envelope_id,omitempty"`
	ProtocolVersion int            `json:"protocol_version"`
	DeliveryMode    string         `json:"delivery_mode,omitempty"`
	EventType       EventType      `json:"event_type"`
	SessionKey      string         `json:"session_key,omitempty"`
	SessionSeq      *int64         `json:"session_seq,omitempty"`
	RoomID          string         `json:"room_id,omitempty"`
	RoomSeq         *int64         `json:"room_seq,omitempty"`
	ConversationID  string         `json:"conversation_id,omitempty"`
	AgentID         string         `json:"agent_id,omitempty"`
	MessageID       string         `json:"message_id,omitempty"`
	SessionID       string         `json:"session_id,omitempty"`
	RoundID         string         `json:"round_id,omitempty"`
	AgentRoundID    string         `json:"agent_round_id,omitempty"`
	Data            map[string]any `json:"data"`
	Timestamp       int64          `json:"timestamp"`
}

EventMessage 对齐前后端统一 envelope。

func GoalEventEnvelope added in v0.1.15 

func GoalEventEnvelope(sessionKey string, eventType EventType, goal Goal, payload map[string]any) EventMessage

GoalEventEnvelope 构造 WebSocket Goal 事件。

func NewAgentRoundStatusEvent added in v0.1.26 

func NewAgentRoundStatusEvent(sessionKey string, roundID string, agentRoundID string, agentID string, status string) EventMessage

NewAgentRoundStatusEvent 构造 agent_round_status 事件（Room slot 生命周期）。

func NewChatAckEvent 

func NewChatAckEvent(
	sessionKey string,
	clientRequestID string,
	clientMessageID string,
	roundID string,
	userMessageID string,
	userMessageCommitted bool,
	pending []ChatAckPendingSlot,
) EventMessage

NewChatAckEvent 构造 chat_ack 事件。round_id / user_message_id 由后端 mint， client_request_id / client_message_id 原样回传供前端关联。

func NewChatPendingSnapshotEvent added in v0.1.27 

func NewChatPendingSnapshotEvent(sessionKey string, roundID string, pending []ChatAckPendingSlot) EventMessage

NewChatPendingSnapshotEvent 构造订阅恢复时的权威 Room slot 快照。 前端必须用 pending 整体替换本地恢复值；空数组同样有意义，用于清除陈旧占位。

func NewErrorEvent 

func NewErrorEvent(sessionKey string, message string) EventMessage

NewErrorEvent 构造错误事件。

func NewEvent 

func NewEvent(eventType EventType, data map[string]any) EventMessage

NewEvent 构造通用事件。

func NewInputQueueAckEvent added in v0.1.27 

func NewInputQueueAckEvent(
	sessionKey string,
	clientRequestID string,
	clientMessageID string,
	result InputQueueMutationResult,
) EventMessage

NewInputQueueAckEvent 构造 input_queue_ack 事件。 client_request_id / client_message_id 原样回传；duplicate 表示同一幂等请求此前已持久接受。

func NewInputQueueEvent added in v0.1.2 

func NewInputQueueEvent(sessionKey string, items []InputQueueItem) EventMessage

NewInputQueueEvent 构造 input_queue 快照事件。

func NewPermissionRequestResolvedEvent 

func NewPermissionRequestResolvedEvent(sessionKey string, requestID string, status string) EventMessage

NewPermissionRequestResolvedEvent 构造权限请求结束事件。

func NewPongEvent 

func NewPongEvent(sessionKey string) EventMessage

NewPongEvent 构造 pong 事件。

func NewRoundStatusEvent 

func NewRoundStatusEvent(sessionKey string, roundID string, status string, resultSubtype string) EventMessage

NewRoundStatusEvent 构造 round_status 事件。

type EventType 

type EventType string

EventType 表示统一事件类型。 

const (
	EventTypeMessage                     EventType = "message"
	EventTypeStream                      EventType = "stream"
	EventTypeChatAck                     EventType = "chat_ack"
	EventTypeInputQueue                  EventType = "input_queue"
	EventTypeInputQueueAck               EventType = "input_queue_ack"
	EventTypeRoundStatus                 EventType = "round_status"
	EventTypeAgentRoundStatus            EventType = "agent_round_status"
	EventTypeSessionStatus               EventType = "session_status"
	EventTypeRuntimeStatus               EventType = "runtime_status"
	EventTypeGoalCreated                 EventType = "goal_created"
	EventTypeGoalUpdated                 EventType = "goal_updated"
	EventTypeGoalStatusChanged           EventType = "goal_status_changed"
	EventTypeGoalProgress                EventType = "goal_progress"
	EventTypeGoalContinuation            EventType = "goal_continuation"
	EventTypeGoalCleared                 EventType = "goal_cleared"
	EventTypePermissionRequest           EventType = "permission_request"
	EventTypePermissionRequestResolved   EventType = "permission_request_resolved"
	EventTypeAgentRuntimeEvent           EventType = "agent_runtime_event"
	EventTypeWorkspaceEvent              EventType = "workspace_event"
	EventTypeDirectoryChanged            EventType = "directory_changed"
	EventTypeScheduledTaskChanged        EventType = "scheduled_task_changed"
	EventTypeRoomMemberAdded             EventType = "room_member_added"
	EventTypeRoomMemberRemoved           EventType = "room_member_removed"
	EventTypeRoomDeleted                 EventType = "room_deleted"
	EventTypeRoomDirectedMessage         EventType = "room_directed_message"
	EventTypeRoomDirectedMessageConsumed EventType = "room_directed_message_consumed"
	EventTypeRoomResyncRequired          EventType = "room_resync_required"
	EventTypeSessionResyncRequired       EventType = "session_resync_required"
	EventTypeStreamStart                 EventType = "stream_start"
	EventTypeStreamEnd                   EventType = "stream_end"
	EventTypeStreamCancelled             EventType = "stream_cancelled"
	EventTypeError                       EventType = "error"
	EventTypePong                        EventType = "pong"
)

type Goal added in v0.1.15 

type Goal struct {
	ID                 string         `json:"id"`
	SessionKey         string         `json:"session_key"`
	Objective          string         `json:"objective"`
	Status             GoalStatus     `json:"status"`
	TokenBudget        *int64         `json:"token_budget,omitempty"`
	Usage              GoalUsage      `json:"usage"`
	TimeUsedSeconds    int64          `json:"time_used_seconds,omitempty"`
	ContinuationCount  int            `json:"continuation_count"`
	EmptyProgressCount int            `json:"empty_progress_count"`
	Version            int64          `json:"version"`
	CreatedBy          string         `json:"created_by,omitempty"`
	CreatedAt          time.Time      `json:"created_at"`
	UpdatedAt          time.Time      `json:"updated_at"`
	CompletedAt        *time.Time     `json:"completed_at,omitempty"`
	BlockedAt          *time.Time     `json:"blocked_at,omitempty"`
	LastError          string         `json:"last_error,omitempty"`
	Metadata           map[string]any `json:"metadata,omitempty"`
}

Goal 表示一个 session 的当前长程目标。

func (Goal) ObjectiveRevision added in v0.1.27 

func (g Goal) ObjectiveRevision() int64

ObjectiveRevision 返回只随 objective 变化的 revision；旧数据从 1 起算。

func (Goal) RemainingTokens added in v0.1.15 

func (g Goal) RemainingTokens() *int64

RemainingTokens 返回剩余 token 预算；没有预算时返回 nil。

type GoalContinuation added in v0.1.15 

type GoalContinuation struct {
	Goal           Goal              `json:"goal"`
	RoundID        string            `json:"round_id"`
	Prompt         string            `json:"prompt"`
	HiddenFromUser bool              `json:"hidden_from_user"`
	Synthetic      bool              `json:"synthetic"`
	Purpose        string            `json:"purpose"`
	Metadata       map[string]string `json:"metadata,omitempty"`
}

GoalContinuation 表示一次由系统触发的隐藏 Goal 续跑输入。

type GoalEvent added in v0.1.15 

type GoalEvent struct {
	ID         string           `json:"id"`
	GoalID     string           `json:"goal_id"`
	SessionKey string           `json:"session_key"`
	EventType  string           `json:"event_type"`
	Source     GoalUpdateSource `json:"source"`
	RoundID    string           `json:"round_id,omitempty"`
	Payload    map[string]any   `json:"payload,omitempty"`
	CreatedAt  time.Time        `json:"created_at"`
}

GoalEvent 表示 Goal 审计事件。

type GoalStatus added in v0.1.15 

type GoalStatus string

GoalStatus 表示会话 Goal 的生命周期状态。 

const (
	GoalStatusActive        GoalStatus = "active"
	GoalStatusPaused        GoalStatus = "paused"
	GoalStatusComplete      GoalStatus = "complete"
	GoalStatusBlocked       GoalStatus = "blocked"
	GoalStatusBudgetLimited GoalStatus = "budget_limited"
	GoalStatusUsageLimited  GoalStatus = "usage_limited"
)

func NormalizeGoalStatus added in v0.1.15 

func NormalizeGoalStatus(status GoalStatus) GoalStatus

NormalizeGoalStatus 规范化 Goal 状态。

type GoalUpdateSource added in v0.1.15 

type GoalUpdateSource string

GoalUpdateSource 表示 Goal 状态变化来源。 

const (
	GoalUpdateSourceUser     GoalUpdateSource = "user"
	GoalUpdateSourceModel    GoalUpdateSource = "model"
	GoalUpdateSourceSystem   GoalUpdateSource = "system"
	GoalUpdateSourceExternal GoalUpdateSource = "external"
)

type GoalUsage added in v0.1.15 

type GoalUsage struct {
	InputTokens              int64 `json:"input_tokens,omitempty"`
	OutputTokens             int64 `json:"output_tokens,omitempty"`
	CacheCreationInputTokens int64 `json:"cache_creation_input_tokens,omitempty"`
	CacheReadInputTokens     int64 `json:"cache_read_input_tokens,omitempty"`
	ReasoningTokens          int64 `json:"reasoning_tokens,omitempty"`
	TotalTokens              int64 `json:"total_tokens,omitempty"`
	RuntimeSeconds           int64 `json:"runtime_seconds,omitempty"`
}

GoalUsage 记录 Goal 长程执行累计用量。

func (GoalUsage) Add added in v0.1.15 

func (u GoalUsage) Add(other GoalUsage) GoalUsage

Add 合并 token usage。

func (GoalUsage) BudgetTokens added in v0.1.15 

func (u GoalUsage) BudgetTokens() int64

BudgetTokens 按 Codex Goal 口径统计预算 token：非缓存输入 token + 输出 token。

func (GoalUsage) Total added in v0.1.15 

func (u GoalUsage) Total() int64

Total 返回可用于预算判断的 token 总量。

type InboundWebSocketMessage 

type InboundWebSocketMessage struct {
	Type       string `json:"type"`
	SessionKey string `json:"session_key,omitempty"`
}

InboundWebSocketMessage 表示前端发送给服务端的基础消息。

type InputQueueItem added in v0.1.2 

type InputQueueItem struct {
	ID              string             `json:"id"`
	Scope           InputQueueScope    `json:"scope"`
	SessionKey      string             `json:"session_key"`
	RoomID          string             `json:"room_id,omitempty"`
	ConversationID  string             `json:"conversation_id,omitempty"`
	AgentID         string             `json:"agent_id,omitempty"`
	SourceAgentID   string             `json:"source_agent_id,omitempty"`
	SourceMessageID string             `json:"source_message_id,omitempty"`
	HandoffID       string             `json:"handoff_id,omitempty"`
	TargetAgentIDs  []string           `json:"target_agent_ids,omitempty"`
	Source          InputQueueSource   `json:"source"`
	Content         string             `json:"content"`
	Attachments     []ChatAttachment   `json:"attachments,omitempty"`
	DeliveryPolicy  ChatDeliveryPolicy `json:"delivery_policy"`
	ReplyRoute      RoomReplyRoute     `json:"reply_route,omitempty"`
	OwnerUserID     string             `json:"owner_user_id,omitempty"`
	RootRoundID     string             `json:"root_round_id,omitempty"`
	HopIndex        int                `json:"hop_index,omitempty"`
	QueueOrder      int64              `json:"queue_order,omitempty"`
	ExpiresAt       int64              `json:"expires_at,omitempty"`
	CreatedAt       int64              `json:"created_at"`
	UpdatedAt       int64              `json:"updated_at"`
}

InputQueueItem 表示后端同步的待发送队列项。

type InputQueueMutationResult added in v0.1.27 

type InputQueueMutationResult struct {
	Action    string `json:"action"`
	ItemID    string `json:"item_id,omitempty"`
	Duplicate bool   `json:"duplicate"`
}

InputQueueMutationResult 表示一次已被服务端持久接受的输入队列变更。

type InputQueueScope added in v0.1.2 

type InputQueueScope string

InputQueueScope 表示待发送队列所在的会话面。 

const (
	InputQueueScopeDM   InputQueueScope = "dm"
	InputQueueScopeRoom InputQueueScope = "room"
)

func NormalizeInputQueueScope added in v0.1.2 

func NormalizeInputQueueScope(value string) InputQueueScope

NormalizeInputQueueScope 归一化队列作用域。

type InputQueueSource added in v0.1.2 

type InputQueueSource string

InputQueueSource 表示队列项来源。 

const (
	InputQueueSourceUser               InputQueueSource = "user"
	InputQueueSourceAgentPublicMention InputQueueSource = "agent_public_mention"
	InputQueueSourceAgentRoomMessage   InputQueueSource = "agent_room_directed_message"
)

func NormalizeInputQueueSource added in v0.1.2 

func NormalizeInputQueueSource(value string) InputQueueSource

NormalizeInputQueueSource 归一化队列来源。

type MemberRecord 

type MemberRecord struct {
	ID            string    `json:"id"`
	RoomID        string    `json:"room_id"`
	MemberType    string    `json:"member_type"`
	MemberUserID  string    `json:"member_user_id,omitempty"`
	MemberAgentID string    `json:"member_agent_id,omitempty"`
	JoinedAt      time.Time `json:"joined_at,omitempty"`
}

MemberRecord 表示房间成员记录。

type Message 

type Message map[string]any

Message 表示历史消息行。

func Clone 

func Clone(message Message) Message

Clone 复制消息，避免不同层直接共享 map 引用。

type MessagePage 

type MessagePage struct {
	Items                    []Message `json:"items"`
	HasMore                  bool      `json:"has_more"`
	NextBeforeRoundID        *string   `json:"next_before_round_id,omitempty"`
	NextBeforeRoundTimestamp *int64    `json:"next_before_round_timestamp,omitempty"`
}

MessagePage 表示按 round 分页的消息历史结果。

type OptionalInt64 added in v0.1.15 

type OptionalInt64 struct {
	Present bool
	Value   *int64
}

OptionalInt64 表示 JSON 字段的三态：缺省、null、整数值。

func (*OptionalInt64) UnmarshalJSON added in v0.1.15 

func (v *OptionalInt64) UnmarshalJSON(data []byte) error

UnmarshalJSON 记录字段是否出现，并保留 null 与整数值的差异。

type Options 

type Options struct {
	Provider          string         `json:"provider,omitempty"`
	Model             string         `json:"model,omitempty"`
	PermissionMode    string         `json:"permission_mode,omitempty"`
	AllowedTools      []string       `json:"allowed_tools,omitempty"`
	DisallowedTools   []string       `json:"disallowed_tools,omitempty"`
	MaxTurns          *int           `json:"max_turns,omitempty"`
	MaxThinkingTokens *int           `json:"max_thinking_tokens,omitempty"`
	MCPServers        map[string]any `json:"mcp_servers,omitempty"`
	SettingSources    []string       `json:"setting_sources,omitempty"`
}

Options 表示 Agent 运行时配置。

type RetargetGoalRequest added in v0.1.27 

type RetargetGoalRequest struct {
	Objective                 string `json:"objective"`
	RoundID                   string `json:"round_id,omitempty"`
	AgentID                   string `json:"-"`
	ExpectedObjectiveRevision int64  `json:"-"`
}

RetargetGoalRequest 表示模型基于用户明确纠正重定向当前 active Goal。

type RoomAggregate 

type RoomAggregate struct {
	Room    RoomRecord     `json:"room"`
	Members []MemberRecord `json:"members"`
}

RoomAggregate 表示房间聚合。

type RoomDirectedMessageRecord added in v0.1.12 

type RoomDirectedMessageRecord struct {
	MessageID       string         `json:"message_id"`
	RoomID          string         `json:"room_id"`
	ConversationID  string         `json:"conversation_id"`
	SourceAgentID   string         `json:"source_agent_id"`
	Recipients      []string       `json:"recipients"`
	WakeTargets     []string       `json:"wake_targets,omitempty"`
	Content         string         `json:"content,omitempty"`
	WakePolicy      RoomWakePolicy `json:"wake_policy,omitempty"`
	ReplyRoute      RoomReplyRoute `json:"reply_route"`
	DelaySeconds    int            `json:"delay_seconds,omitempty"`
	CorrelationID   string         `json:"correlation_id,omitempty"`
	RootRoundID     string         `json:"root_round_id,omitempty"`
	CausedByRoundID string         `json:"caused_by_round_id,omitempty"`
	HopIndex        int            `json:"hop_index,omitempty"`
	Timestamp       int64          `json:"timestamp"`
}

RoomDirectedMessageRecord 表示 Room directed message 的 append-only 持久化记录。

type RoomRecord 

type RoomRecord struct {
	ID                     string    `json:"id"`
	OwnerUserID            string    `json:"-"`
	RoomType               string    `json:"room_type"`
	Name                   string    `json:"name,omitempty"`
	Description            string    `json:"description"`
	Avatar                 string    `json:"avatar,omitempty"`
	SkillNames             []string  `json:"skill_names"`
	HostAgentID            string    `json:"host_agent_id,omitempty"`
	HostAutoReplyEnabled   bool      `json:"host_auto_reply_enabled"`
	PrivateMessagesEnabled bool      `json:"private_messages_enabled"`
	CreatedAt              time.Time `json:"created_at,omitempty"`
	UpdatedAt              time.Time `json:"updated_at,omitempty"`
}

RoomRecord 表示房间记录。

type RoomReplyRoute added in v0.1.12 

type RoomReplyRoute struct {
	Mode           RoomReplyRouteMode `json:"mode"`
	Recipients     []string           `json:"recipients,omitempty"`
	WakePolicy     RoomWakePolicy     `json:"wake_policy,omitempty"`
	NextReplyRoute *RoomReplyRoute    `json:"next_reply_route,omitempty"`
}

RoomReplyRoute 表示 directed message 触发后的 final reply 投影规则。

type RoomReplyRouteMode added in v0.1.12 

type RoomReplyRouteMode string

RoomReplyRouteMode 表示 directed message 唤醒后的回复投影位置。 

const (
	RoomReplyRoutePublic  RoomReplyRouteMode = "public"
	RoomReplyRoutePrivate RoomReplyRouteMode = "private"
	RoomReplyRouteNone    RoomReplyRouteMode = "none"
)

type RoomWakePolicy added in v0.1.3 

type RoomWakePolicy string

RoomWakePolicy 表示 directed message 是否触发目标成员运行。 

const (
	RoomWakePolicyNone      RoomWakePolicy = "none"
	RoomWakePolicyImmediate RoomWakePolicy = "immediate"
	RoomWakePolicyDelayed   RoomWakePolicy = "delayed"
)

type RoundStatusData 

type RoundStatusData struct {
	RoundID       string `json:"round_id"`
	Status        string `json:"status"`
	IsTerminal    bool   `json:"is_terminal"`
	ResultSubtype string `json:"result_subtype,omitempty"`
}

RoundStatusData 表示 round 生命周期事件。

type RuntimeStatus added in v0.1.27 

type RuntimeStatus string

RuntimeStatus 表示当前会话内由 Agent runtime 主动上报的瞬时阶段。 

const (
	RuntimeStatusCompacting RuntimeStatus = "compacting"
)

type RuntimeStatusData added in v0.1.27 

type RuntimeStatusData struct {
	Status *RuntimeStatus `json:"status"`
}

RuntimeStatusData 使用 nil 明确结束上一状态，避免客户端依赖轮次事件猜测。

type Session 

type Session struct {
	SessionKey     string         `json:"session_key"`
	AgentID        string         `json:"agent_id"`
	SessionID      *string        `json:"session_id"`
	RoomSessionID  *string        `json:"room_session_id"`
	RoomID         *string        `json:"room_id"`
	ConversationID *string        `json:"conversation_id"`
	ChannelType    string         `json:"channel_type"`
	ChatType       string         `json:"chat_type"`
	Status         string         `json:"status"`
	CreatedAt      time.Time      `json:"created_at"`
	LastActivity   time.Time      `json:"last_activity"`
	Title          string         `json:"title"`
	MessageCount   int            `json:"message_count"`
	Options        map[string]any `json:"options"`
	IsActive       bool           `json:"is_active"`
}

Session 表示对外暴露的统一会话模型。

type SessionKey 

type SessionKey struct {
	Raw            string         `json:"raw"`
	Kind           SessionKeyKind `json:"kind"`
	IsStructured   bool           `json:"is_structured"`
	IsShared       bool           `json:"is_shared"`
	AgentID        string         `json:"agent_id,omitempty"`
	Channel        string         `json:"channel,omitempty"`
	ChatType       string         `json:"chat_type,omitempty"`
	AccountID      string         `json:"account_id,omitempty"`
	Ref            string         `json:"ref,omitempty"`
	ThreadID       string         `json:"thread_id,omitempty"`
	ConversationID string         `json:"conversation_id,omitempty"`
	RoomRef        string         `json:"room_ref,omitempty"`
}

SessionKey 表示结构化会话键。

func ParseSessionKey 

func ParseSessionKey(raw string) SessionKey

ParseSessionKey 解析 session_key。

type SessionKeyKind 

type SessionKeyKind string

SessionKeyKind 表示协议族。 

const (
	// SessionKeyKindAgent 表示 agent 私有运行时。
	SessionKeyKindAgent SessionKeyKind = "agent"
	// SessionKeyKindRoom 表示共享 room 流。
	SessionKeyKindRoom SessionKeyKind = "room"
	// SessionKeyKindUnknown 表示无法识别。
	SessionKeyKindUnknown SessionKeyKind = "unknown"
)

type SessionRecord 

type SessionRecord struct {
	ID             string    `json:"id"`
	ConversationID string    `json:"conversation_id"`
	AgentID        string    `json:"agent_id"`
	RuntimeID      string    `json:"runtime_id"`
	VersionNo      int       `json:"version_no"`
	BranchKey      string    `json:"branch_key"`
	IsPrimary      bool      `json:"is_primary"`
	SDKSessionID   string    `json:"sdk_session_id,omitempty"`
	Status         string    `json:"status"`
	LastActivityAt time.Time `json:"last_activity_at,omitempty"`
	CreatedAt      time.Time `json:"created_at,omitempty"`
	UpdatedAt      time.Time `json:"updated_at,omitempty"`
}

SessionRecord 表示房间内的运行时会话索引。

type SessionRoundIndex added in v0.1.23 

type SessionRoundIndex struct {
	Items []SessionRoundIndexItem `json:"items"`
}

SessionRoundIndex 表示 session 级 round 导航索引。

type SessionRoundIndexItem added in v0.1.23 

type SessionRoundIndexItem struct {
	RoundID        string   `json:"round_id"`
	Title          string   `json:"title,omitempty"`
	Timestamp      int64    `json:"timestamp,omitempty"`
	Status         string   `json:"status,omitempty"`
	DurationMS     *int64   `json:"duration_ms,omitempty"`
	IsLive         bool     `json:"is_live,omitempty"`
	HasUserMessage bool     `json:"has_user_message,omitempty"`
	AgentIDs       []string `json:"agent_ids,omitempty"`
}

SessionRoundIndexItem 表示一个 round 的轻量导航元数据。

type SessionStatusData 

type SessionStatusData struct {
	IsGenerating    bool     `json:"is_generating"`
	RunningRoundIDs []string `json:"running_round_ids,omitempty"`
}

SessionStatusData 表示 session 生命周期事件。

type StructuredSessionKeyError 

type StructuredSessionKeyError struct {
	Message string
}

StructuredSessionKeyError 对齐前端 HTTP 入口的 422 校验错误。

func (StructuredSessionKeyError) Error 

func (e StructuredSessionKeyError) Error() string

type TurnPage added in v0.1.26 

type TurnPage struct {
	Turns                 []ConversationTurn `json:"turns"`
	NextBeforeRoundID     string             `json:"next_before_round_id,omitempty"`
	BackwardsAfterRoundID string             `json:"backwards_after_round_id,omitempty"`
}

TurnPage 是 /turns 历史 API 的分页响应。

type TurnPendingPermission added in v0.1.26 

type TurnPendingPermission struct {
	RequestID string `json:"request_id"`
	MessageID string `json:"message_id,omitempty"`
	ToolUseID string `json:"tool_use_id,omitempty"`
	ToolName  string `json:"tool_name,omitempty"`
}

TurnPendingPermission 是投影输出中挂在 slot 上的待确认权限。

type UpdateConversationRequest 

type UpdateConversationRequest struct {
	Title string `json:"title,omitempty"`
}

UpdateConversationRequest 表示更新话题请求。

type UpdateGoalRequest added in v0.1.15 

type UpdateGoalRequest struct {
	Objective   *string        `json:"objective,omitempty"`
	TokenBudget OptionalInt64  `json:"token_budget,omitempty"`
	OwnerUserID string         `json:"owner_user_id,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

UpdateGoalRequest 表示更新 Goal 的请求。

type UpdateRequest 

type UpdateRequest struct {
	Name        *string  `json:"name,omitempty"`
	Options     *Options `json:"options,omitempty"`
	Avatar      *string  `json:"avatar,omitempty"`
	Description *string  `json:"description,omitempty"`
	VibeTags    []string `json:"vibe_tags,omitempty"`
}

UpdateRequest 表示更新 Agent 请求。

type UpdateRoomRequest 

type UpdateRoomRequest struct {
	Name                   string    `json:"name,omitempty"`
	Description            string    `json:"description,omitempty"`
	Title                  string    `json:"title,omitempty"`
	Avatar                 *string   `json:"avatar,omitempty"`
	SkillNames             *[]string `json:"skill_names,omitempty"`
	HostAgentID            *string   `json:"host_agent_id,omitempty"`
	HostAutoReplyEnabled   *bool     `json:"host_auto_reply_enabled,omitempty"`
	PrivateMessagesEnabled *bool     `json:"private_messages_enabled,omitempty"`
}

UpdateRoomRequest 表示更新房间请求。

type ValidateNameResponse 

type ValidateNameResponse struct {
	Name           string `json:"name"`
	NormalizedName string `json:"normalized_name"`
	IsValid        bool   `json:"is_valid"`
	IsAvailable    bool   `json:"is_available"`
	WorkspacePath  string `json:"workspace_path,omitempty"`
	Reason         string `json:"reason,omitempty"`
}

ValidateNameResponse 对齐当前校验协议。

type WorkspaceFileArtifactBlock added in v0.1.6 

type WorkspaceFileArtifactBlock struct {
	ID               string `json:"id,omitempty"`
	Type             string `json:"type"`
	Path             string `json:"path"`
	DisplayPath      string `json:"display_path,omitempty"`
	Label            string `json:"label,omitempty"`
	Title            string `json:"title,omitempty"`
	ArtifactKind     string `json:"artifact_kind,omitempty"`
	MIMEType         string `json:"mime_type,omitempty"`
	Operation        string `json:"operation,omitempty"`
	Scope            string `json:"scope,omitempty"`
	WorkspaceAgentID string `json:"workspace_agent_id,omitempty"`
	SourceToolUseID  string `json:"source_tool_use_id,omitempty"`
	SourceToolName   string `json:"source_tool_name,omitempty"`
}

WorkspaceFileArtifactBlock 描述对话中可直接打开的工作区文件产物。

func (WorkspaceFileArtifactBlock) Map added in v0.1.6 

func (b WorkspaceFileArtifactBlock) Map() map[string]any

Map 转成动态消息块，供现有 transcript map 写入链路复用。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.