ai/synapse

Fork 0

Files

lychang 65710a4536 灵隙(synapse) v1.0.0 版本

2026-06-29 02:12:44 +08:00

39 KiB

Raw Permalink Blame History

灵隙协议实现规范：人工介入（HiL）三级升级机制

版本：1.0.0 | 层级：实现层

1. 升级级别定义

HiL（Human-in-the-Loop）三级升级机制根据决策的重要性、紧急程度和风险等级，将人工介入分为三个级别。

1.1 级别总览

级别	名称	默认超时	紧急超时	决策者	适用场景
Level 1	Agent 建议 + 人确认	24 小时	—	任务发起人 / 值班人	信息缺失、创意方向、用户主动请求
Level 2	必须人工决策	12 小时	2 小时	领域负责人 / 审核专员	品牌风格、合规审查、能力不足、高风险操作
Level 3	专家 / 管理层决策	72 小时	24 小时	专家委员会 / 管理层	战略决策、重大争议、跨系统冲突

1.2 Level 1：Agent 建议 + 人确认

定位：低风险、低成本的快速确认。Agent 提供建议方案，人类只需确认或微调。

触发条件：

触发代码	场景描述	示例
`INFO_MISSING`	Agent 缺少关键信息，需要人类补充	客户未提供明确的需求规格
`CREATIVE_DIRECTION`	创意方向需人类确认	Logo 设计方案初选
`USER_REQUESTED`	用户主动要求人工介入	用户明确要求"请人工审核"
`CONTENT_REVIEW`	内容发布前快速确认	推文、公告文案确认
`PREFERENCE_CONFIRM`	偏好确认	颜色、字体等视觉偏好选择

行为规范：

Agent 必须提供明确的建议值（SuggestedValue）
人类可执行的操作：批准、修改后批准、拒绝并说明原因
超时默认策略：自动以 Agent 建议值继续执行
升级频率限制：同一任务单日不超过 5 次 Level 1 升级

1.3 Level 2：必须人工决策

定位：中高风险，必须由具备相应领域知识的人类做出决策，Agent 不可自行决定。

触发条件：

触发代码	场景描述	示例
`BRAND_STYLE`	品牌风格相关决策	品牌色调、VI 元素使用
`COMPLIANCE`	合规要求判定	数据隐私法规、行业合规
`CAPABILITY_LACKING`	Agent 能力不足以完成任务	需要特定领域专家的判断
`HIGH_COST_RISK`	高成本或高风险操作	预算超过阈值、涉及敏感操作
`RESOURCE_DEADLOCK`	资源死锁或竞争	多个 Agent 争夺同一资源
`SENSITIVE_CONTENT`	敏感内容判定	涉及政治、色情、暴力等内容
`THIRD_PARTY_ESCALATION`	第三方系统接入审批	外部 API 调用、数据交换审批

行为规范：

Agent 必须提供完整的决策上下文（Context），包括推理过程和依据
Agent 应提供至少 2 个可选方案（Options），并分析各自的优缺点
人类可执行的操作：批准某一方案、驳回并要求补充信息、修改方案后执行
超时默认策略：升级至 Level 3（不可自动通过或拒绝）
紧急模式下（HIGH_COST_RISK、SENSITIVE_CONTENT），超时缩短为 2 小时

1.4 Level 3：专家 / 管理层决策

定位：最高级别的决策层级，涉及战略方向、重大争议和跨系统冲突，必须由专家委员会或管理层做出最终裁决。

触发条件：

触发代码	场景描述	示例
`STRATEGIC_DECISION`	战略级决策	产品方向、市场策略、合作伙伴选择
`MAJOR_DISPUTE`	重大争议	Agent 之间无法达成共识，且影响重大
`CROSS_SYSTEM_CONFLICT`	跨系统冲突	两个独立系统间的数据或资源冲突
`LEVEL2_TIMEOUT_ESCALATED`	Level 2 超时升级	Level 2 超时后自动升级
`POLICY_EXCEPTION`	策略例外申请	需要突破既定策略的特殊情况
`CRISIS_RESPONSE`	危机响应	安全事件、数据泄露、服务中断

行为规范：

Agent 必须提供完整的背景报告，包括事件时间线、影响范围、可选方案及风险评估
需要至少 2 位 具备相应权限的决策者参与
决策方式：投票制（简单多数或加权投票，根据场景配置）
超时默认策略：任务挂起（不自动执行任何操作），等待人工跟进
所有 Level 3 决策必须记录完整的审计日志

1.5 级别间关系

Level 1 ──超时──→ 自动以建议值执行
   │
   ├──复杂情况──→ Level 2
   │
Level 2 ──超时──→ Level 3
   │
   ├──驳回并要求补充──→ Level 1 / Level 2（重新提交）
   │
Level 3 ──超时──→ 任务挂起（等待人工）
   │
   └──决策完成──→ 任务继续执行或终止

2. HiL 状态流转

2.1 状态定义

type HILStatus string

const (
    // 初始状态：请求已创建，尚未进入人工队列
    HILStatusPending HILStatus = "pending"

    // 等待状态：请求已进入人工队列，等待分配决策者
    HILStatusWaiting HILStatus = "waiting"

    // 决策中：决策者正在审阅中，尚未给出结论
    HILStatusDeciding HILStatus = "deciding"

    // 已批准：决策者批准了 Agent 的建议或某一方案
    HILStatusApproved HILStatus = "approved"

    // 已拒绝：决策者拒绝了所有方案
    HILStatusRejected HILStatus = "rejected"

    // 超时：在截止时间前未收到人工响应
    HILStatusTimeout HILStatus = "timeout"

    // 已升级：当前级别无法处理，升级至更高级别
    HILStatusEscalated HILStatus = "escalated"
)

2.2 状态流转图

                    ┌─────────────────────────────────────┐
                    │             创建请求                  │
                    │         HILStatusPending              │
                    └────────────────┬────────────────────┘
                                     │
                                     ▼
                    ┌─────────────────────────────────────┐
                    │          进入人工队列                 │
                    │         HILStatusWaiting              │
                    └────────────────┬────────────────────┘
                                     │
                         ┌───────────┴───────────┐
                         │      分配决策者        │
                         ▼                       ▼
            ┌────────────────────────┐  ┌────────────────────┐
            │    决策者开始审阅       │  │   超时未分配       │
            │   HILStatusDeciding    │  │  HILStatusTimeout  │
            └──────────┬─────────────┘  └─────────┬──────────┘
                       │                          │
          ┌────────────┼────────────┬─────────────┘
          ▼            ▼            ▼
    ┌──────────┐ ┌──────────┐ ┌──────────────┐
    │  批准    │ │  拒绝    │ │  升级        │
    │ Approved │ │ Rejected │ │ Escalated    │
    └──────────┘ └──────────┘ └──────┬───────┘
                                     │
                                     ▼
                          ┌────────────────────┐
                          │  进入更高级别流程   │
                          │ Pending/Waiting    │
                          └────────────────────┘

2.3 状态转移矩阵

当前状态 \ 目标状态	pending	waiting	deciding	approved	rejected	timeout	escalated
pending	—	✔️ 入队	❌	❌	❌	❌	❌
waiting	❌	—	✔️ 分配决策者	❌	❌	✔️ 超时未分配	✔️ 手动升级
deciding	❌	❌	—	✔️ 批准方案	✔️ 拒绝方案	✔️ 决策超时	✔️ 无法决策
approved	❌	❌	❌	—	❌	❌	❌
rejected	❌	❌	❌	❌	—	❌	❌
timeout	❌	❌	❌	❌	❌	—	✔️ 超时升级
escalated	❌	❌	❌	❌	❌	❌	—

2.4 状态流转 Hook

// HILStatusHook - 状态变更回调接口
type HILStatusHook interface {
    // OnStatusChanged - 状态变更时触发
    OnStatusChanged(ctx context.Context, req *HILRequest, oldStatus, newStatus HILStatus) error

    // OnEscalated - 升级时触发
    OnEscalated(ctx context.Context, req *HILRequest, fromLevel, toLevel int) error

    // OnTimeout - 超时时触发
    OnTimeout(ctx context.Context, req *HILRequest) error

    // OnDecisionMade - 决策完成时触发
    OnDecisionMade(ctx context.Context, req *HILRequest, resp *HILResponse) error
}

3. HiL 请求结构

3.1 HILRequest

type HILRequest struct {
    // 基础标识
    ID              string       `json:"id"`                // 请求唯一 ID（UUID）
    TaskID          string       `json:"task_id"`           // 关联任务 ID
    ParentRequestID string       `json:"parent_request_id,omitempty"` // 父请求 ID（升级时关联）

    // 升级信息
    EscalationType  EscalationType `json:"escalation_type"`  // 升级类型
    EscalationLevel int           `json:"escalation_level"`  // 升级级别（1/2/3）
    SourceSystemID  string        `json:"source_system_id"`  // 发起方系统 ID
    SourceAgentID   string        `json:"source_agent_id"`   // 发起方 Agent ID

    // 决策内容
    Reason          HILReason     `json:"reason"`            // 介入原因
    Context         HILContext    `json:"context"`           // 决策上下文
    Options         []HILOption   `json:"options"`           // 可选方案（至少 1 个）
    SuggestedValue  any           `json:"suggested_value"`   // Agent 建议值

    // 时间与状态
    CreatedAt       time.Time     `json:"created_at"`        // 创建时间
    Deadline        time.Time     `json:"deadline"`          // 截止时间
    RespondedAt     *time.Time    `json:"responded_at,omitempty"` // 响应时间
    Status          HILStatus     `json:"status"`            // 当前状态
    StatusHistory   []StatusEntry `json:"status_history"`    // 状态变更历史

    // 响应
    Response        *HILResponse  `json:"response,omitempty"` // 人工响应
    AssignedTo      []string      `json:"assigned_to,omitempty"` // 指定决策者 ID 列表
    AssignedRoles   []string      `json:"assigned_roles,omitempty"` // 指定决策角色

    // 元数据
    Priority        int           `json:"priority"`          // 优先级（1-5，5 最高）
    Tags            map[string]string `json:"tags,omitempty"` // 自定义标签
    Notified        bool          `json:"notified"`          // 是否已发送通知
}

// EscalationType - 升级类型
type EscalationType string

const (
    EscalationP2P        EscalationType = "P2P"         // 点对点升级
    EscalationGROUP      EscalationType = "GROUP"       // 群组内升级
    EscalationInterGROUP EscalationType = "INTER_GROUP" // 跨群组升级
    EscalationSYSTEM     EscalationType = "SYSTEM"      // 系统级升级
)

// StatusEntry - 状态变更记录
type StatusEntry struct {
    FromStatus HILStatus `json:"from_status"` // 原状态
    ToStatus   HILStatus `json:"to_status"`   // 新状态
    ChangedBy  string    `json:"changed_by"`  // 变更者
    Reason     string    `json:"reason"`      // 变更原因
    Timestamp  time.Time `json:"timestamp"`   // 变更时间
}

3.2 HILReason

type HILReason struct {
    Code        HILReasonCode  `json:"code"`        // 原因代码
    Message     string         `json:"message"`     // 人类可读的描述
    Detail      string         `json:"detail"`      // 详细说明
    Confidence  int            `json:"confidence"`  // Agent 置信度（0-100）
    TriggerEvent string        `json:"trigger_event,omitempty"` // 触发事件标识
}

// HILReasonCode - 原因代码枚举
type HILReasonCode string

const (
    // Level 1 原因
    ReasonInfoMissing       HILReasonCode = "INFO_MISSING"        // 信息缺失
    ReasonCreativeDirection HILReasonCode = "CREATIVE_DIRECTION"  // 创意方向
    ReasonUserRequested     HILReasonCode = "USER_REQUESTED"      // 用户请求
    ReasonContentReview     HILReasonCode = "CONTENT_REVIEW"      // 内容审核
    ReasonPreferenceConfirm HILReasonCode = "PREFERENCE_CONFIRM"  // 偏好确认

    // Level 2 原因
    ReasonBrandStyle       HILReasonCode = "BRAND_STYLE"          // 品牌风格
    ReasonCompliance       HILReasonCode = "COMPLIANCE"           // 合规要求
    ReasonCapabilityLacking HILReasonCode = "CAPABILITY_LACKING"  // 能力不足
    ReasonHighCostRisk     HILReasonCode = "HIGH_COST_RISK"       // 高成本风险
    ReasonResourceDeadlock HILReasonCode = "RESOURCE_DEADLOCK"    // 资源死锁
    ReasonSensitiveContent HILReasonCode = "SENSITIVE_CONTENT"    // 敏感内容
    ReasonThirdPartyEsc    HILReasonCode = "THIRD_PARTY_ESCALATION" // 第三方介入

    // Level 3 原因
    ReasonStrategicDecision  HILReasonCode = "STRATEGIC_DECISION"    // 战略决策
    ReasonMajorDispute       HILReasonCode = "MAJOR_DISPUTE"         // 重大争议
    ReasonCrossSystemConflict HILReasonCode = "CROSS_SYSTEM_CONFLICT" // 跨系统冲突
    ReasonLevel2TimeoutEsc   HILReasonCode = "LEVEL2_TIMEOUT_ESCALATED" // Level 2 超时升级
    ReasonPolicyException    HILReasonCode = "POLICY_EXCEPTION"      // 策略例外
    ReasonCrisisResponse     HILReasonCode = "CRISIS_RESPONSE"       // 危机响应
)

3.3 HILContext

type HILContext struct {
    // 任务上下文
    TaskType        string                 `json:"task_type"`          // 任务类型
    TaskDescription string                 `json:"task_description"`   // 任务描述
    TaskPayload     any                    `json:"task_payload"`       // 任务载荷摘要

    // 决策上下文
    CurrentState    any                    `json:"current_state"`      // 当前状态
    AffectedFields  []string               `json:"affected_fields"`    // 受影响字段列表
    Constraints     map[string]interface{}  `json:"constraints"`       // 约束条件

    // Agent 推理
    ReasoningChain  string                 `json:"reasoning_chain"`    // Agent 推理链摘要
    ConfidenceScore float64                `json:"confidence_score"`   // 整体置信度（0.0-1.0）
    Alternatives    []string               `json:"alternatives"`       // 已排除的替代方案

    // 风险信息
    RiskLevel       string                 `json:"risk_level"`         // 风险等级（low/mid/high/critical）
    RiskAssessment  string                 `json:"risk_assessment"`    // 风险评估
    ImpactScope     string                 `json:"impact_scope"`       // 影响范围

    // 附件
    Attachments     []ContextAttachment    `json:"attachments,omitempty"` // 附件列表
}

// ContextAttachment - 上下文附件
type ContextAttachment struct {
    Name        string `json:"name"`         // 附件名
    Type        string `json:"type"`         // 附件类型（image/document/data）
    URL         string `json:"url"`          // 附件 URL
    Description string `json:"description"`  // 附件描述
    Size        int64  `json:"size"`         // 附件大小（字节）
}

3.4 HILOption

type HILOption struct {
    // 选项标识
    ID          string `json:"id"`           // 选项 ID
    Field       string `json:"field"`        // 对应字段名

    // 选项内容
    Value       any    `json:"value"`        // 候选值
    Label       string `json:"label"`        // 人类可读的显示标签
    Description string `json:"description"`  // 详细描述

    // 分析信息
    ProsCons    string `json:"pros_cons"`    // 优缺点分析
    Confidence  int    `json:"confidence"`   // Agent 置信度（0-100）
    EstimatedCost string `json:"estimated_cost,omitempty"` // 预估成本
    RiskNote    string `json:"risk_note,omitempty"`    // 风险提示

    // 元数据
    IsDefault   bool   `json:"is_default"`   // 是否为默认推荐
    Source      string `json:"source"`       // 来源（agent/human/auto）
}

// HILOptionSet - 选项集合（工具方法）
type HILOptionSet struct {
    Options []HILOption `json:"options"`
}

func (s *HILOptionSet) GetDefault() *HILOption {
    for _, opt := range s.Options {
        if opt.IsDefault {
            return &opt
        }
    }
    if len(s.Options) > 0 {
        return &s.Options[0]
    }
    return nil
}

func (s *HILOptionSet) GetByID(id string) *HILOption {
    for _, opt := range s.Options {
        if opt.ID == id {
            return &opt
        }
    }
    return nil
}

3.5 请求结构示例

{
  "id": "hil-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "task_id": "task-20260628-001",
  "parent_request_id": "",
  "escalation_type": "P2P",
  "escalation_level": 2,
  "source_system_id": "sys-creative-001",
  "source_agent_id": "agent-designer-v3",

  "reason": {
    "code": "BRAND_STYLE",
    "message": "品牌风格决策：需要确认视觉元素是否符合品牌规范",
    "detail": "Agent 在生成 banner 设计稿时，对主色调使用存在不确定性。当前候选色 #3366FF 与品牌指南中规定的 Primary-500 存在偏差（偏差值 #2244DD）。",
    "confidence": 72,
    "trigger_event": "brand_style_check_failed"
  },

  "context": {
    "task_type": "banner_design",
    "task_description": "为夏季促销活动生成一张 1200x628 的社交媒体 banner",
    "task_payload": { "campaign": "summer_sale_2026", "format": "social_media" },
    "affected_fields": ["color_primary", "color_secondary", "typography"],
    "constraints": { "budget_level": "standard" },
    "reasoning_chain": "1. 分析品牌指南 V3.2 → 2. 检测到主色偏差 → 3. 计算偏差值 → 4. 需要人工确认",
    "confidence_score": 0.72,
    "risk_level": "mid",
    "risk_assessment": "颜色偏差不会导致功能问题，但可能影响品牌一致性"
  },

  "options": [
    {
      "id": "opt-1",
      "field": "color_primary",
      "value": "#3366FF",
      "label": "推荐方案：使用 #3366FF",
      "description": "基于夏季活力主题的微调版本，与品牌色系相近",
      "pros_cons": "优点：更符合夏季活动调性；缺点：与品牌指南有微小偏差",
      "confidence": 72,
      "is_default": true
    },
    {
      "id": "opt-2",
      "field": "color_primary",
      "value": "#2244DD",
      "label": "保守方案：严格遵循品牌色 #2244DD",
      "description": "100% 符合品牌指南 V3.2 规定的 Primary-500",
      "pros_cons": "优点：完全合规；缺点：与夏季活力主题契合度较低",
      "confidence": 95,
      "is_default": false
    }
  ],

  "suggested_value": { "color_primary": "#3366FF" },

  "status": "pending",
  "priority": 3,
  "assigned_roles": ["brand_manager", "creative_director"]
}

4. 升级判定规则

4.1 需要人工介入的代码映射表

// hilRequiredCodes - 需要人工介入的原因代码映射表
// true  = 必须人工介入，Agent 不可自行决策
// false = 可由 Agent 自行决策（默认值）
var hilRequiredCodes = map[HILReasonCode]bool{
    // Level 1
    ReasonInfoMissing:       true,
    ReasonCreativeDirection: true,
    ReasonUserRequested:     true,
    ReasonContentReview:     true,
    ReasonPreferenceConfirm: true,

    // Level 2
    ReasonBrandStyle:        true,
    ReasonCompliance:        true,
    ReasonCapabilityLacking: true,
    ReasonHighCostRisk:      true,
    ReasonResourceDeadlock:  true,
    ReasonSensitiveContent:  true,
    ReasonThirdPartyEsc:     true,

    // Level 3
    ReasonStrategicDecision:   true,
    ReasonMajorDispute:        true,
    ReasonCrossSystemConflict: true,
    ReasonLevel2TimeoutEsc:    true,
    ReasonPolicyException:     true,
    ReasonCrisisResponse:      true,
}

4.2 升级级别映射表

// levelMap - 原因代码到升级级别的映射
// 决定升级到 Level 1 / 2 / 3
var levelMap = map[HILReasonCode]int{
    // ── Level 1 ──
    ReasonInfoMissing:       1,
    ReasonCreativeDirection: 1,
    ReasonUserRequested:     1,
    ReasonContentReview:     1,
    ReasonPreferenceConfirm: 1,

    // ── Level 2 ──
    ReasonBrandStyle:        2,
    ReasonCompliance:        2,
    ReasonCapabilityLacking: 2,
    ReasonHighCostRisk:      2,
    ReasonResourceDeadlock:  2,
    ReasonSensitiveContent:  2,
    ReasonThirdPartyEsc:     2,

    // ── Level 3 ──
    ReasonStrategicDecision:   3,
    ReasonMajorDispute:        3,
    ReasonCrossSystemConflict: 3,
    ReasonLevel2TimeoutEsc:    3,
    ReasonPolicyException:     3,
    ReasonCrisisResponse:      3,
}

4.3 完整判定规则表

原因代码	中文说明	是否必须 HiL	升级级别	默认超时	超时策略
`INFO_MISSING`	信息缺失	✔️	1	24h	以建议值继续
`CREATIVE_DIRECTION`	创意方向	✔️	1	24h	以建议值继续
`USER_REQUESTED`	用户请求	✔️	1	24h	以建议值继续
`CONTENT_REVIEW`	内容审核	✔️	1	24h	以建议值继续
`PREFERENCE_CONFIRM`	偏好确认	✔️	1	24h	以建议值继续
`BRAND_STYLE`	品牌风格	✔️	2	12h	升级至 Level 3
`COMPLIANCE`	合规要求	✔️	2	12h	升级至 Level 3
`CAPABILITY_LACKING`	能力不足	✔️	2	12h	升级至 Level 3
`HIGH_COST_RISK`	高成本风险	✔️	2	2h（紧急）	升级至 Level 3
`RESOURCE_DEADLOCK`	资源死锁	✔️	2	12h	升级至 Level 3
`SENSITIVE_CONTENT`	敏感内容	✔️	2	2h（紧急）	升级至 Level 3
`THIRD_PARTY_ESCALATION`	第三方介入	✔️	2	12h	升级至 Level 3
`STRATEGIC_DECISION`	战略决策	✔️	3	72h	任务挂起
`MAJOR_DISPUTE`	重大争议	✔️	3	72h	任务挂起
`CROSS_SYSTEM_CONFLICT`	跨系统冲突	✔️	3	72h	任务挂起
`LEVEL2_TIMEOUT_ESCALATED`	Level 2 超时	✔️	3	72h	任务挂起
`POLICY_EXCEPTION`	策略例外	✔️	3	72h	任务挂起
`CRISIS_RESPONSE`	危机响应	✔️	3	24h（紧急）	任务挂起

4.4 动态判定函数

// DetermineHiLLevel - 根据原因代码和上下文判定升级级别
// 返回：是否需要 HiL、升级级别、建议超时时间
func DetermineHiLLevel(reasonCode HILReasonCode, ctx context.Context) (required bool, level int, timeout time.Duration) {
    // 是否必须 HiL
    required = hilRequiredCodes[reasonCode]

    if !required {
        return false, 0, 0
    }

    // 判定升级级别
    level = levelMap[reasonCode]
    if level == 0 {
        level = 1 // 默认 Level 1
    }

    // 根据上下文调整超时
    timeout = getDefaultTimeout(level)

    // 紧急模式判定：高风险场景缩短超时
    if isEmergencyMode(ctx, reasonCode) {
        timeout = getEmergencyTimeout(level)
    }

    return required, level, timeout
}

func getDefaultTimeout(level int) time.Duration {
    switch level {
    case 1:
        return 24 * time.Hour
    case 2:
        return 12 * time.Hour
    case 3:
        return 72 * time.Hour
    default:
        return 24 * time.Hour
    }
}

func getEmergencyTimeout(level int) time.Duration {
    switch level {
    case 2:
        return 2 * time.Hour
    case 3:
        return 24 * time.Hour
    default:
        return getDefaultTimeout(level)
    }
}

// isEmergencyMode - 判断是否为紧急模式
func isEmergencyMode(ctx context.Context, reasonCode HILReasonCode) bool {
    emergencyCodes := map[HILReasonCode]bool{
        ReasonHighCostRisk:    true,
        ReasonSensitiveContent: true,
        ReasonCrisisResponse:  true,
    }
    return emergencyCodes[reasonCode]
}

4.5 阈值配置表

配置项	默认值	说明
`hil.max_level1_per_task`	5	单任务最大 Level 1 升级次数
`hil.max_level2_per_task`	3	单任务最大 Level 2 升级次数
`hil.max_level3_per_task`	1	单任务最大 Level 3 升级次数
`hil.cost_threshold_high`	1000	高成本阈值（SYN 代币）
`hil.confidence_threshold`	60	Agent 置信度阈值（低于此值建议升级）
`hil.max_pending_requests`	50	最大待处理请求数（超出后拒绝新请求）
`hil.emergency_mode_enabled`	true	是否启用紧急模式
`hil.auto_approve_on_timeout_level1`	true	Level 1 超时是否自动以建议值通过

5. 人工响应结构

5.1 HILResponse

type HILResponse struct {
    // 决策标识
    DecisionID string    `json:"decision_id"`         // 决策唯一 ID
    RequestID  string    `json:"request_id"`          // 关联请求 ID

    // 决策者信息
    UserID     string    `json:"user_id"`             // 决策用户 ID
    UserName   string    `json:"user_name"`           // 用户名
    UserRole   string    `json:"user_role"`           // 用户角色
    UserAvatar string    `json:"user_avatar,omitempty"` // 用户头像 URL

    // 决策内容
    Action     DecisionAction `json:"action"`         // 决策动作
    Decision   HILDecision    `json:"decision"`       // 决策内容
    Notes      string         `json:"notes"`          // 备注说明

    // 元数据
    Timestamp  time.Time      `json:"timestamp"`      // 决策时间
    Duration   time.Duration  `json:"duration"`       // 决策耗时
    Source     string         `json:"source"`         // 响应渠道（web/mobile/api/email）
}

// DecisionAction - 决策动作枚举
type DecisionAction string

const (
    ActionApprove DecisionAction = "approve" // 批准建议值或默认方案
    ActionReject  DecisionAction = "reject"  // 拒绝所有方案
    ActionModify  DecisionAction = "modify"  // 修改后批准
    ActionSelect  DecisionAction = "select"  // 选择某一方案
    ActionDefer   DecisionAction = "defer"   // 暂缓决策，需要更多信息
    ActionEscalate DecisionAction = "escalate" // 手动升级
)

5.2 HILDecision

type HILDecision struct {
    // 批准的字段（Action = approve 时使用）
    // key = 字段名, value = 批准的值
    ApprovedFields  map[string]interface{} `json:"approved_fields,omitempty"`

    // 修改的字段（Action = modify 时使用）
    // 与 ApprovedFields 的区别：ModifiedFields 包含人类手动调整的值
    ModifiedFields  map[string]interface{} `json:"modified_fields,omitempty"`

    // 选中的选项 ID（Action = select 时使用）
    SelectedOption  string                 `json:"selected_option,omitempty"`

    // 拒绝原因（Action = reject 时使用）
    RejectionReason string                 `json:"rejection_reason,omitempty"`

    // 附加指令（Action = modify/defer 时使用）
    Instructions    string                 `json:"instructions,omitempty"`

    // 决策影响评估
    Impact          *DecisionImpact        `json:"impact,omitempty"`
}

// DecisionImpact - 决策影响评估
type DecisionImpact struct {
    EstimatedCost    float64 `json:"estimated_cost"`     // 预估成本
    EstimatedTime    string  `json:"estimated_time"`     // 预估耗时
    AffectedSystems  []string `json:"affected_systems"`  // 受影响系统
    RollbackPossible bool    `json:"rollback_possible"`  // 是否可回滚
    RollbackPlan     string  `json:"rollback_plan,omitempty"` // 回滚方案
}

5.3 决策动作对照表

动作	适用级别	含义	后续流程
`approve`	1 / 2 / 3	批准 Agent 的建议值或默认方案	任务继续执行
`reject`	1 / 2 / 3	拒绝所有方案	任务终止或返回修改
`modify`	1 / 2	修改建议值后批准	按修改后的值执行
`select`	2 / 3	从多个方案中选择一个	按选中方案执行
`defer`	2 / 3	暂缓决策，要求补充信息	返回等待状态，Agent 补充信息
`escalate`	1 / 2	手动升级至更高级别	进入更高级别的流程

5.4 响应处理函数

// ProcessHILResponse - 处理人工响应
// 返回：是否需要触发后续操作、错误信息
func ProcessHILResponse(ctx context.Context, resp *HILResponse) (bool, error) {
    switch resp.Action {
    case ActionApprove:
        return handleApprove(ctx, resp)
    case ActionReject:
        return handleReject(ctx, resp)
    case ActionModify:
        return handleModify(ctx, resp)
    case ActionSelect:
        return handleSelect(ctx, resp)
    case ActionDefer:
        return handleDefer(ctx, resp)
    case ActionEscalate:
        return handleEscalate(ctx, resp)
    default:
        return false, fmt.Errorf("unknown decision action: %s", resp.Action)
    }
}

func handleApprove(ctx context.Context, resp *HILResponse) (bool, error) {
    // 1. 更新请求状态为 approved
    // 2. 应用 approved_fields 到任务
    // 3. 触发任务继续执行
    // 4. 记录审计日志
    return true, nil
}

func handleModify(ctx context.Context, resp *HILResponse) (bool, error) {
    // 1. 更新请求状态为 approved
    // 2. 将 modified_fields 合并到任务参数
    // 3. 记录原始值与修改值到审计日志
    // 4. 触发任务继续执行
    return true, nil
}

func handleSelect(ctx context.Context, resp *HILResponse) (bool, error) {
    // 1. 验证 selected_option 存在
    // 2. 更新请求状态为 approved
    // 3. 提取选中选项的值并应用到任务
    // 4. 触发任务继续执行
    return true, nil
}

func handleReject(ctx context.Context, resp *HILResponse) (bool, error) {
    // 1. 更新请求状态为 rejected
    // 2. 记录拒绝原因
    // 3. 通知任务发起方
    // 4. 根据策略决定任务终止或重新提交
    return true, nil
}

func handleDefer(ctx context.Context, resp *HILResponse) (bool, error) {
    // 1. 更新请求状态为 pending（重新进入队列）
    // 2. 记录 instructions 为补充信息要求
    // 3. 通知 Agent 补充信息
    // 4. 更新 deadline
    return true, nil
}

func handleEscalate(ctx context.Context, resp *HILResponse) (bool, error) {
    // 1. 更新当前请求状态为 escalated
    // 2. 创建新的升级请求（level + 1）
    // 3. 关联 parent_request_id
    // 4. 通知更高级别的决策者
    return true, nil
}

5.5 响应示例

{
  "decision_id": "dec-9876-5432-1098",
  "request_id": "hil-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user_id": "user-zhangsan-001",
  "user_name": "张三",
  "user_role": "brand_manager",
  "action": "modify",
  "decision": {
    "modified_fields": {
      "color_primary": "#3377FF",
      "color_secondary": "#FF7722"
    },
    "instructions": "主色调调整为 #3377FF（介于推荐和保守方案之间），辅助色使用 #FF7722 突出促销氛围。请按此配色重新生成设计稿。",
    "impact": {
      "estimated_cost": 0,
      "estimated_time": "15min",
      "affected_systems": ["creative-engine", "brand-assets"],
      "rollback_possible": true,
      "rollback_plan": "恢复至修改前的配色方案即可"
    }
  },
  "notes": "颜色调整合理，注意保持整体的视觉平衡。",
  "timestamp": "2026-06-28T14:30:00+08:00",
  "duration": 1800000000000,
  "source": "web"
}

6. 超时与降级策略

6.1 超时处理矩阵

级别	超时时间	超时动作	说明
Level 1	24h	自动批准（以 Agent 建议值执行）	低风险场景，Agent 建议值视为默认
Level 1（紧急）	4h	自动批准	任务优先级高时缩短超时
Level 2	12h	升级至 Level 3	不可自动决策，必须由更高级别介入
Level 2（紧急）	2h	升级至 Level 3	高风险场景快速升级
Level 3	72h	任务挂起	不做任何自动操作，等待人工
Level 3（紧急）	24h	任务挂起 + 通知管理层	危机场景需尽快响应

6.2 超时监控

// HILTimeoutWatcher - 超时监控器
type HILTimeoutWatcher struct {
    mu          sync.RWMutex
    timers      map[string]*time.Timer
    onTimeout   func(ctx context.Context, req *HILRequest)
}

func NewHILTimeoutWatcher(onTimeout func(ctx context.Context, req *HILRequest)) *HILTimeoutWatcher {
    return &HILTimeoutWatcher{
        timers:    make(map[string]*time.Timer),
        onTimeout: onTimeout,
    }
}

func (w *HILTimeoutWatcher) Register(req *HILRequest) {
    w.mu.Lock()
    defer w.mu.Unlock()

    timeout := time.Until(req.Deadline)
    timer := time.AfterFunc(timeout, func() {
        ctx := context.Background()
        w.onTimeout(ctx, req)
    })
    w.timers[req.ID] = timer
}

func (w *HILTimeoutWatcher) Cancel(reqID string) {
    w.mu.Lock()
    defer w.mu.Unlock()

    if timer, ok := w.timers[reqID]; ok {
        timer.Stop()
        delete(w.timers, reqID)
    }
}

6.3 超时通知策略

级别	超时前提醒	提醒方式	超时后通知
Level 1	超时前 4h	站内通知	通知请求发起人
Level 2	超时前 2h、30min	站内通知 + 邮件	通知请求发起人 + 升级接收人
Level 3	超时前 24h、4h、30min	站内通知 + 邮件 + 短信	通知管理层 + 升级委员会

7. 通知渠道规范

7.1 通知渠道配置

type HILNotificationConfig struct {
    // 渠道启用状态
    InAppEnabled  bool `json:"in_app_enabled"`  // 站内通知
    EmailEnabled  bool `json:"email_enabled"`   // 邮件通知
    SMSEnabled    bool `json:"sms_enabled"`     // 短信通知
    WebhookEnabled bool `json:"webhook_enabled"` // Webhook 通知

    // 各渠道的级别阈值
    InAppLevel    int    `json:"in_app_level"`    // 站内通知最低级别（1）
    EmailLevel    int    `json:"email_level"`     // 邮件通知最低级别（2）
    SMSLevel      int    `json:"sms_level"`       // 短信通知最低级别（3）
    WebhookURL    string `json:"webhook_url,omitempty"` // Webhook URL

    // 通知模板
    TitleTemplate string `json:"title_template"` // 标题模板
    BodyTemplate  string `json:"body_template"`  // 内容模板
}

// HILNotification - 通知消息结构
type HILNotification struct {
    ID        string          `json:"id"`
    RequestID string          `json:"request_id"`
    Channels  []string        `json:"channels"`    // 通知渠道列表
    Title     string          `json:"title"`
    Body      string          `json:"body"`
    Level     int             `json:"level"`
    Recipients []string       `json:"recipients"`
    Status    string          `json:"status"`      // sent/delivered/failed
    CreatedAt time.Time       `json:"created_at"`
}

7.2 渠道-级别对照表

级别	站内通知	邮件	短信	Webhook
Level 1	✔️	❌	❌	可选
Level 2	✔️	✔️	❌	可选
Level 3	✔️	✔️	✔️（紧急）	✔️
紧急模式	✔️	✔️	✔️	✔️

8. 审计与日志

8.1 审计记录结构

type HILAuditLog struct {
    LogID       string            `json:"log_id"`        // 审计日志 ID
    RequestID   string            `json:"request_id"`    // 关联请求 ID
    TaskID      string            `json:"task_id"`       // 关联任务 ID

    // 事件信息
    EventType   string            `json:"event_type"`    // 事件类型
    EventData   map[string]interface{} `json:"event_data"` // 事件数据
    Timestamp   time.Time         `json:"timestamp"`     // 事件时间

    // 操作者
    ActorID     string            `json:"actor_id"`      // 操作者 ID
    ActorType   string            `json:"actor_type"`    // 操作者类型（agent/human/system）
    ActorRole   string            `json:"actor_role"`    // 操作者角色

    // 变更记录
    Changes     []FieldChange     `json:"changes"`       // 字段变更记录

    // 完整性
    Checksum    string            `json:"checksum"`      // 日志校验和
    Signature   string            `json:"signature"`     // 数字签名
}

type FieldChange struct {
    Field     string      `json:"field"`     // 字段名
    OldValue  interface{} `json:"old_value"` // 旧值
    NewValue  interface{} `json:"new_value"` // 新值
    Reason    string      `json:"reason"`    // 变更原因
}

8.2 审计事件类型

事件类型	说明	记录内容
`hil.request.created`	请求创建	请求完整内容、发起方信息
`hil.request.assigned`	分配决策者	决策者 ID、角色
`hil.request.status_changed`	状态变更	原状态、新状态、变更原因
`hil.request.notified`	发送通知	通知渠道、接收人列表
`hil.request.timeout`	超时触发	超时级别、触发策略
`hil.request.escalated`	升级触发	原级别、新级别、升级原因
`hil.decision.submitted`	决策提交	决策完整内容、决策者信息
`hil.decision.applied`	决策应用	应用字段、变更值
`hil.request.completed`	请求完成	最终状态、耗时

8.3 审计日志保留策略

级别	保留期限	存储方式
Level 1	90 天	热存储
Level 2	180 天	热存储
Level 3	365 天	热存储 + 冷备份
紧急模式	730 天	热存储 + 冷备份 + 加密归档

本文档基于 06-implementation-details.md 第5章扩展编写，是灵隙协议实现规范的一部分。

相关文档：raw-protocol.md | a2a-protocol.md | a2n-protocol.md

39 KiB Raw Permalink Blame History Unescape Escape

灵隙协议实现规范：人工介入（HiL）三级升级机制

目录

1. 升级级别定义

1.1 级别总览

1.2 Level 1：Agent 建议 + 人确认

1.3 Level 2：必须人工决策

1.4 Level 3：专家 / 管理层决策

1.5 级别间关系

2. HiL 状态流转

2.1 状态定义

2.2 状态流转图

2.3 状态转移矩阵

2.4 状态流转 Hook

3. HiL 请求结构

3.1 HILRequest

3.2 HILReason

3.3 HILContext

3.4 HILOption

3.5 请求结构示例

4. 升级判定规则

4.1 需要人工介入的代码映射表

4.2 升级级别映射表

4.3 完整判定规则表

4.4 动态判定函数

4.5 阈值配置表

5. 人工响应结构

5.1 HILResponse

5.2 HILDecision

5.3 决策动作对照表

5.4 响应处理函数

5.5 响应示例

6. 超时与降级策略

6.1 超时处理矩阵

6.2 超时监控

6.3 超时通知策略

7. 通知渠道规范

7.1 通知渠道配置

7.2 渠道-级别对照表

8. 审计与日志

8.1 审计记录结构

8.2 审计事件类型

8.3 审计日志保留策略

39 KiB

Raw Permalink Blame History