---
name: streaming_protocol
when: '长时间推演, 重型操作, 心跳, 超时, 连接断开'
scope: ['*']
products:
  - '*'
id: ka-pattern-streaming_protocol
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 长时间推演
  - 重型操作
  - 心跳
  - 超时
  - 连接断开
priority: P2
specificity: 3
version: 1.1.0
last_reviewed: '2026-06-01'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
stages: ["*"]
owner_mechanism_id: mc-engine-runtime
---

## 决策规则

- 重型 AI 操作（tier=heavy）执行期间必须启动流式心跳
- 心跳间隔 Heartbeat_Interval = 5000 毫秒
- 心跳通过 stdio 输出，格式: [SoloForge Heartbeat] {操作描述} 执行中... 已耗时 {N}s，当前任务已用 {M}/{T} Token
- 心跳包含字段: elapsed_ms, tokens_used, operation, message
- 轻量/中型操作（light/medium）不触发心跳
- 操作完成后调用 completeOperation() 停止心跳
- 重型操作定义: estimated_tokens > 3000（code_generation/solution_brainstorm/verification_reasoning/review_deep_analysis）

## 验收项

- [AC-01] 重型操作启动后 5 秒内首次心跳输出
- [AC-02] 心跳消息包含操作名称、耗时、Token 用量
- [AC-03] completeOperation() 调用后心跳立即停止
- [AC-04] 中型操作（test_generation/debug_analysis）不产生心跳
- [AC-05] 心跳回调通过 setHeartbeatCallback() 注册

## 格式规范

```
[SoloForge Heartbeat] 代码生成 执行中... 已耗时 10s，当前任务已用 5000/30000 Token
```

## 何时使用

advisory: 预算耗尽是 warning 不是 hard fail，不应阻断任务

## 是否 hard block

否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。

## 证据要求

- H1/H4 handler 测试通过
- heartbeat 测试通过
-

## 人工确认/降级边界

- 此能力可被开发者决策覆盖
- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
- 降级/禁用需经 sf_capability_update + 人工确认
