# 灵隙协议实现规范:人工介入(HiL)三级升级机制 > 版本:1.0.0 | 层级:实现层 --- ## 目录 1. [升级级别定义](#1-升级级别定义) 2. [HiL 状态流转](#2-hil-状态流转) 3. [HiL 请求结构](#3-hil-请求结构) 4. [升级判定规则](#4-升级判定规则) 5. [人工响应结构](#5-人工响应结构) 6. [超时与降级策略](#6-超时与降级策略) 7. [通知渠道规范](#7-通知渠道规范) 8. [审计与日志](#8-审计与日志) --- ## 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 状态定义 ```go 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 ```go // 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 ```go 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 ```go 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 ```go 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 ```go 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 请求结构示例 ```json { "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 需要人工介入的代码映射表 ```go // 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 升级级别映射表 ```go // 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 动态判定函数 ```go // 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 ```go 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 ```go 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 响应处理函数 ```go // 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 响应示例 ```json { "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 超时监控 ```go // 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 通知渠道配置 ```go 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 审计记录结构 ```go 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](../v0/06-implementation-details.md#5-人工介入hil三级升级机制) 第5章扩展编写,是灵隙协议实现规范的一部分。 > > 相关文档:[raw-protocol.md](01_raw-protocol.md) | [a2a-protocol.md](02_a2a-protocol.md) | [a2n-protocol.md](03_a2n-protocol.md)