Agent-System/internal/stream/types.go

package stream

import (
	"time"
)

// EventType 定义流式事件类型
type EventType string

const (
	EventTurnAck     EventType = "turn_ack"    // 回合确认：用户消息已落库，携带 user_message_id
	EventPhase       EventType = "phase"       // 阶段性状态跃迁（组建小队、法规筛选、初稿撰写、门禁审核）
	EventStatus      EventType = "status"      // 意图识别结果、成熟度状态机更新
	EventSummary     EventType = "summary"     // 提炼的核心进展摘要（低认知负荷）
	EventBriefing    EventType = "briefing"    // 贴身业务参谋决策锦囊（B轨赋能）
	EventDelta       EventType = "delta"       // 对话自然语言逐字/逐句流式吐出
	EventDetail      EventType = "detail"      // 详细推演草稿或思考链（按需显示，默认折叠）
	EventDeliverable EventType = "deliverable" // A轨正式合规文档生成通知
	EventGovernance  EventType = "governance"  // 受控文档治理与认领/变更提案拦截通知
	EventError       EventType = "error"       // 运行异常警报
	EventDone        EventType = "done"        // 会话流完成
)

// GovernancePayload 文档治理生命周期与认领变更载荷
type GovernancePayload struct {
	DocID             string `json:"doc_id"`
	Action            string `json:"action"`        // claimed, proposal_required, proposal_decided, submitted_review, rejected, approved
	CurrentState      string `json:"current_state"` // drafting, reviewing, approving, approved
	IsLocked          bool   `json:"is_locked"`
	AuthorClaimed     bool   `json:"author_claimed"`
	ProposalID        string `json:"proposal_id,omitempty"`
	ProposedChanges   string `json:"proposed_changes,omitempty"`
	ImpactSummary     string `json:"impact_summary,omitempty"`
	RiskSummary       string `json:"risk_summary,omitempty"`
	AuthorDecision    string `json:"author_decision,omitempty"`
	NotificationTitle string `json:"notification_title"` // 用户前台高亮简报标题
	NotificationMsg   string `json:"notification_msg"`   // 用户前台高亮简报内容
}

// PhasePayload 阶段性任务状态更新载荷
type PhasePayload struct {
	PhaseID    string `json:"phase_id"`              // 如 squad_assembly, knowledge_retrieval, step_executing, quality_gate
	Message    string `json:"message"`               // 用户友好的自然语言进度说明
	Role       string `json:"role,omitempty"`        // 角色 (如 regulatory, writer, leader)
	StepIndex  int    `json:"step_index,omitempty"`  // 当前步骤索引 (如 1)
	TotalSteps int    `json:"total_steps,omitempty"` // 总步骤数 (如 3)
	Progress   int    `json:"progress,omitempty"`    // 百分比估算 (0-100)
}

// StatusPayload 意图与状态机更新载荷
type StatusPayload struct {
	Intent       string            `json:"intent,omitempty"`
	Branch       string            `json:"branch,omitempty"`
	CurrentStage string            `json:"current_stage,omitempty"`
	Patches      map[string]string `json:"patches,omitempty"`
	Message      string            `json:"message,omitempty"`
}

// SummaryPayload 核心进展摘要载荷 (低认知负荷)
type SummaryPayload struct {
	Title         string `json:"title"`
	Content       string `json:"content"`
	MaturityScore int    `json:"maturity_score,omitempty"`
	MaturityLevel string `json:"maturity_level,omitempty"`
}

// DetailPayload 详细执行与推演过程载荷 (按需显示，默认折叠)
type DetailPayload struct {
	Category    string `json:"category"`          // agent_thought, step_output, tool_call, log
	StepID      string `json:"step_id,omitempty"` // 步骤标识 (如 tasks/01_regulatory)
	Role        string `json:"role,omitempty"`    // 对应角色
	Title       string `json:"title"`
	Content     string `json:"content"`     // 完整推演正文或技术草稿
	Collapsible bool   `json:"collapsible"` // 客户端是否应当默认折叠显示
	// ---- 过程流扩展（2026-09-28 subagent 过程展示设计 B.2）----
	ItemID string `json:"item_id,omitempty"` // 聚合项 ID：一个思考块/一次工具调用
	// 增量模式：Delta 追加到 ItemID 项；Content 为快照对账帧；Done 定稿。
	Delta string `json:"delta,omitempty"`
	Done  bool   `json:"done,omitempty"`
	// ToolCallInfo 工具调用状态帧（Category == "tool_call" 时）。
	Tool *ToolCallInfo `json:"tool,omitempty"`
}

// ToolCallInfo 一次工具调用的状态投影（thinking 流式展示用）。
type ToolCallInfo struct {
	Name       string `json:"name"`             // write_file / read_file / ...
	Status     string `json:"status"`           // calling | succeeded | failed
	Input      string `json:"input,omitempty"`  // 入参摘要（截断）
	Output     string `json:"output,omitempty"` // 结果摘要（截断）
	DurationMs int64  `json:"duration_ms,omitempty"`
}

// DeliverablePayload A轨正式合规文档交付载荷
type DeliverablePayload struct {
	TaskKey      string  `json:"task_key"`
	Title        string  `json:"title"`
	FilePath     string  `json:"file_path"`
	WordCount    int     `json:"word_count,omitempty"`
	QualityScore float64 `json:"quality_score,omitempty"`
}

// TurnAckPayload 回合确认载荷（用户消息落库后立即回传）
type TurnAckPayload struct {
	ClientTurnID  string `json:"client_turn_id,omitempty"`
	UserMessageID int64  `json:"user_message_id,omitempty"`
	Status        string `json:"status,omitempty"` // processing | completed | duplicate
	Duplicate     bool   `json:"duplicate,omitempty"`
}

// DonePayload 流结束载荷
type DonePayload struct {
	SessionID        string `json:"session_id,omitempty"`
	ClientTurnID     string `json:"client_turn_id,omitempty"`
	DurationMs       int64  `json:"duration_ms"`
	TotalEvents      int    `json:"total_events"`
	WorkspaceID      string `json:"workspace_id,omitempty"` // P2: 任务工作区目录（供前端「继续任务」续跑）
	UserMessageID    int64  `json:"user_message_id,omitempty"`
	MessageID        int64  `json:"message_id,omitempty"`
	Status           string `json:"status,omitempty"`
	ContentRevision  int    `json:"content_revision,omitempty"`
	ContentSha256    string `json:"content_sha256,omitempty"`
	ExportCapability any    `json:"export_capability,omitempty"`
}

type ErrorClass string

const (
	ErrorClassTransient ErrorClass = "transient"
	ErrorClassResumable ErrorClass = "resumable"
	ErrorClassFatal     ErrorClass = "fatal"
	ErrorClassCancelled ErrorClass = "cancelled"
)

type ErrorInfo struct {
	UserMessage string     `json:"user_message"`
	Message     string     `json:"message,omitempty"`
	Code        string     `json:"code"`
	Class       ErrorClass `json:"class"`
	Guide       string     `json:"guide,omitempty"`
	PhaseID     string     `json:"phase_id,omitempty"`
	Upstream    string     `json:"upstream,omitempty"`
	RequestID   string     `json:"request_id,omitempty"`
	SessionID   string     `json:"session_id,omitempty"`
	WorkspaceID string     `json:"workspace_id,omitempty"`
	Actions     []string   `json:"actions"`
}

// StreamEvent 统一多层级流式事件
type StreamEvent struct {
	ID        string    `json:"id"`
	Type      EventType `json:"type"`
	Timestamp time.Time `json:"timestamp"`

	Phase       *PhasePayload       `json:"phase,omitempty"`
	Status      *StatusPayload      `json:"status,omitempty"`
	Summary     *SummaryPayload     `json:"summary,omitempty"`
	Briefing    any                 `json:"briefing,omitempty"`
	Detail      *DetailPayload      `json:"detail,omitempty"`
	Delta       string              `json:"delta,omitempty"`
	Deliverable *DeliverablePayload `json:"deliverable,omitempty"`
	Governance  *GovernancePayload  `json:"governance,omitempty"`
	Error       string              `json:"error,omitempty"`
	ErrorInfo   *ErrorInfo          `json:"error_info,omitempty"`
	Turn        *TurnAckPayload     `json:"turn,omitempty"`
	Done        *DonePayload        `json:"done,omitempty"`
}