reins框架：把Agent驾驭的”缰绳“握在自己手里

// AgentDescriptor 描述 Agent 能力，供意图路由和编排层使用
type AgentDescriptor struct {
    Name        string   // [通用] 唯一标识
    Description string   // [通用] 能力描述（用于 LLM 路由）
    InputTypes  []string // [通用] 接受的 artifact 类型
    OutputTypes []string // [通用] 产出的 artifact 类型
    // [通用] 可选元数据，业务层通过 tags 携带自定义属性（如 risk_level、domain 等）
    // 不在接口层内置业务字段，避免通用协议被业务假设污染
    Tags        map[string]string
}

// BaseAgent 是所有 Agent 的统一接口
type BaseAgent interface {
    Run(ctx context.Context, input ContextEnvelope) (AgentOutput, error)
    Describe() AgentDescriptor
}

// [通用]
type RouteDecision struct {
    TargetAgent    string   // 主路由目标 Agent 名称
    SecondaryHints []string // 接力意图声明（Orchestrator 消费，不透传 Agent）
    RouteReason    string   // 路由原因，用于审计
    Confidence     string   // "high" | "medium" | "low"
    RuleID         string   // 命中的规则 ID，空字符串表示 LLM 兜底
    ModelVersion   string   // LLM 路由时使用的模型版本
    IsFallback     bool     // 是否为兜底路由
}

type WorkflowStatus string

// [通用] 核心状态
const (
    StatusPending          WorkflowStatus = "pending"
    StatusRouted           WorkflowStatus = "routed"
    StatusRunning          WorkflowStatus = "running"
    StatusWaitingHandoff   WorkflowStatus = "waiting_handoff_approval"
    StatusWaitingUserInput WorkflowStatus = "waiting_user_input"
    StatusPartialFailed    WorkflowStatus = "partial_failed"
    StatusCompleted        WorkflowStatus = "completed"
    StatusFailed           WorkflowStatus = "failed"
    StatusCanceled         WorkflowStatus = "canceled"
)

// [通用] WorkflowState 核心字段
type WorkflowState struct {
    WorkflowID       string         // 全局唯一
    SessionID        string         // "tenant:user:session"
    TenantID         string         // 租户隔离键
    Status           WorkflowStatus
    CurrentAgent     string         // 当前执行中的 Agent
    VisitedAgents    []string       // 已访问 Agent 列表（防环检测）
    StepIndex        int            // 当前步骤序号
    DeadlineMs       int64          // 工作流总截止时间戳（Unix ms）
    RetryBudget      int            // 剩余重试次数
    TokenBudget      int            // 剩余 token 预算
    ConfigSnapshotID string         // 绑定的配置快照（会话内不变）
    ArtifactRefs     []string       // 已产出产物引用
    TraceID          string         // 贯穿全链路的 Trace ID

    // [扩展点] 业务层可通过此字段携带自定义状态，框架不感知
    Extensions       map[string]interface{}
}

// [通用]
type ContextEnvelope struct {
    TaskInstruction     string       // 针对当前 Agent 的具体任务指令
    ConversationExcerpt []ConvTurn   // 最近 N 轮原文（N 由 ContextBuilder 策略决定）
    ConversationSummary string       // 更早轮次的摘要（摘要策略见 5.2 节）
    Artifacts           []ArtifactRef // 上游结构化产物引用
    SessionMeta         SessionMetadata
    Budgets             ExecutionBudget
    ExecutionHints      *ExecutionHints // 可选，Orchestrator 按需填充
}

// [通用]
type ExecutionBudget struct {
    DeadlineMs  int64
    TokenBudget int
}

// [通用] 执行提示，帮助 Agent 感知自身在 pipeline 中的位置
// 注意：这里使用开放字符串而非枚举，避免框架预设 pipeline 形态
type ExecutionHints struct {
    // [通用] Agent 在当前调用链中的角色描述，影响输出详细程度
    // 示例值："first_in_chain" | "last_in_chain" | "standalone" | 业务自定义值
    // 非线性 pipeline 的项目可使用不同的语义，框架不做强制约束
    PipelineRole      string

    // [通用] 下游期望的产物类型，引导 Agent 在非终止节点时输出结构化数据
    DownstreamExpects string

    // [通用] 仅用于调试和可观测性，Agent 不应基于此做决策
    ChainIntent       string
}

// [通用]
type AgentOutput struct {
    ProtocolVersion string    // 协议版本
    Status          string    // "success" | "partial" | "error"
    Answer          string    // 面向用户的文字答案
    Artifacts       []Artifact

    Handoff    *HandoffSuggestion // 可选，仅为建议
    Confidence ConfidenceSignal
    Usage      UsageStats        // [通用] 必填，缺失视为协议不完整
    Error      *AgentError
    NextAction *NextAction       // 面向用户的下一步提示
}

// [通用]
type Artifact struct {
    ID       string
    Type     string          // 业务层定义类型标签
    Content  json.RawMessage // 见下方说明
    Metadata ArtifactMeta
}

// [通用] 必填
type UsageStats struct {
    InputTokens  int
    OutputTokens int
    ToolCalls    int
    LatencyMs    int64
}

// 消费方按 Type 分发，得到强类型结构
switch artifact.Type {
case "feature_list":
    var fl FeatureList
    json.Unmarshal(artifact.Content, &fl)
case "code_snippet":
    var cs CodeSnippet
    json.Unmarshal(artifact.Content, &cs)
}

type ArtifactMeta struct {
    Version       string // Artifact 内容结构版本（如 "v1", "v2"）
    Source        string
    CreatedAt     time.Time
}

// [通用] Orchestrator 配置
type OrchestratorConfig struct {
    // 最大 handoff 深度，0 表示不限制
    // A业务 V1 推荐设为 1，其他场景可调整
    MaxHandoffDepth int
    // 其他配置...
}

// [通用扩展点] 业务层注册，在 Agent 输出满足特定条件时触发人工审核流程
type ReviewHook interface {
    // ShouldReview 判断当前输出是否需要人工确认
    ShouldReview(output AgentOutput, state WorkflowState) bool
    // OnReviewRequired 触发时的处理逻辑（如更新 Extensions、发送通知）
    OnReviewRequired(ctx context.Context, output AgentOutput, state *WorkflowState) error
}

// [通用扩展点] 业务层可自定义摘要策略
type SummaryStrategy interface {
    Summarize(ctx context.Context, turns []ConvTurn, budget TokenBudget) (string, error)
}

// [通用] 默认实现：规则截断（保留最近 K 轮，其余丢弃）
type TruncateSummary struct{ KeepLastK int }

// [可选] LLM 摘要实现，需业务层自行注入 LLMClient
type LLMSummary struct{ Client LLMClient; MaxSummaryTokens int }

// [通用]
type Tool interface {
    Name() string
    Description() string
    InputSchema() Schema
    Execute(ctx context.Context, input map[string]interface{}) (interface{}, error)
}

// [通用]
type ToolRegistry interface {
    Register(tool Tool) error
    Get(name string) (Tool, error)
    ListFor(agentName string) []Tool // 按 Agent 权限返回可用工具列表
}

// [通用] 屏蔽厂商差异
type LLMClient interface {
    Chat(ctx context.Context, req ChatRequest) (ChatResponse, error)
    ChatStream(ctx context.Context, req ChatRequest) (<-chan ChatDelta, error)
    Embed(ctx context.Context, texts []string) ([][]float32, error)
}

// [通用]
type ChatRequest struct {
    Messages    []Message
    Tools       []ToolSchema
    MaxTokens   int
    Temperature float32
    ModelHints  ModelHints
}

// [通用] 用意图表达偏好，网关决定实际路由
type ModelHints struct {
    Tier    string // "economy" | "standard" | "premium"
    UseCase string // "generation" | "embedding" | "rerank" | 业务自定义值
    // [说明] "classification" 是 Router 特有场景，其他场景不一定需要
    // UseCase 为开放字符串，不强制枚举，各业务按实际模型分层定义
}

// [通用] 必须贯穿全链路
type TraceContext struct {
    TraceID          string // 全链路追踪
    SessionID        string
    WorkflowID       string
    TenantID         string
    AgentName        string // 当前执行节点
    ModelName        string // 实际调用的模型
    ConfigSnapshotID string // 绑定的配置快照版本
}

// [通用]
type StreamEvent struct {
    EventID    string          `json:"event_id"`
    WorkflowID string          `json:"workflow_id"`
    Seq        int             `json:"seq"`       // 严格递增，用于乱序检测
    EventType  string          `json:"event_type"`
    Timestamp  time.Time       `json:"timestamp"`
    Payload    json.RawMessage `json:"payload"`   // 与 Artifact.Content 保持一致，用 RawMessage
    Final      bool            `json:"final"`
}

// [通用] 内置事件类型
const (
    EventWorkflowAccepted     = "workflow.accepted"
    EventRouteResolved        = "route.resolved"
    EventAgentStarted         = "agent.started"
    EventTextDelta            = "text.delta"
    EventArtifactReady        = "artifact.ready"
    EventUserInputRequired    = "user_input.required"
    EventWorkflowCompleted    = "workflow.completed"
    EventWorkflowFailed       = "workflow.failed"
    // [扩展] 业务层可自定义事件类型，前缀用业务域名隔离，如 "A业务.expr.validation.completed"
)

// [通用] 编排层扩展点接口集合
type OrchestratorExtensions struct {
    // 上下文摘要策略
    SummaryStrategy SummaryStrategy

    // 人工审核钩子（替代内置 needs_manual_review 状态）
    ReviewHook ReviewHook

    // Handoff 审批策略（允许业务层自定义审批逻辑）
    HandoffApprover HandoffApprover

    // 结果聚合策略（多 Agent 输出如何合并为最终答案）
    ResultAggregator ResultAggregator
}

// [通用] Handoff 审批策略接口
type HandoffApprover interface {
    Approve(suggestion HandoffSuggestion, state WorkflowState) (bool, string)
}