Run 生命周期

Run 是 wesgine 中一次完整的 Agent 执行过程——从用户消息到最终回复，经历认知循环、工具调用和认知结算。

发起 Run

curl -N http://localhost:9091/cells/my-cell/run \
  -H "Content-Type: application/json" \
  -d '{
    "actor": "alice",
    "session_id": "s1",
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好"}]
  }'

必填字段

字段	说明
`actor`	请求主体标识（空 → `ErrActorRequired`）
`session_id`	会话 ID
`model`	模型名称（空 → `ErrModelRequired`）
`messages`	消息列表

Run 事件流

Run 通过 SSE 返回事件流：

事件	说明
`stream_delta`	模型输出片段
`tool_start`	工具调用开始
`tool_result`	工具调用结果
`plan_created`	计划创建
`plan_updated`	计划步骤更新
`done`	Run 正常完成
`error`	错误
`interrupted`	被用户中断

SSE 与 Run 解耦

Run 生命周期与 SSE 连接完全解耦：

SSE 断开不会取消 Run
断开后可通过 GET /runs/{runID}/events?from_seq=N 续播事件
取消 Run 的唯一途径：POST /sessions/{sid}/interrupt

认知循环

每个 Run 内部执行认知循环：

接收用户消息
  ↓
组装上下文（System Prompt + 记忆 + 历史）
  ↓
调用 LLM
  ↓ ← 返回工具调用 → 执行工具 → 循环
  ↓ ← 返回文本 → 结束循环
  ↓
认知结算（CognitiveSettlement）
  ↓
Run 完成

终止哲学

wesgine 的终止哲学：引擎不因 counter 阈值主动终止正常运行的任务。

Run 的终止来源：

来源	说明
用户中断	`POST /sessions/{sid}/interrupt`
CycleDetector	检测到完全相同的操作+结果的死循环
ErrorStreak	连续工具错误超过阈值
BudgetCheckFn	外部预算耗尽回调
Cell Stop	Cell 生命周期关闭

CycleDetector — 循环检测

唯一的引擎内终止源。检测"可证明的死循环"（完全相同操作+完全相同结果），不是"你跑太久了"。

两阶段终止协议：

自愈 — 首次检测到循环，注入纠正消息 + 重置计数
HITL — 第二次检测到循环，暂停等待用户决定（超时 60s 自动终止）

认知结算

Run 结束时执行 CognitiveSettlement（认知结算）：

由主对话模型执行（不使用辅助模型）
产出 SessionState（下一轮对话的唯一历史来源）
对用户不可见（不通过 SSE 推送）
失败时退化为机械压缩 + 降级标记

结算是 Run 生命周期的强制阶段，唯一例外是 panic_stop。

Plan 系统

Agent 可以通过 plan 工具创建和管理执行计划：

{
  "tool": "plan",
  "action": "create",
  "steps": [
    {"description": "分析需求"},
    {"description": "编写代码"},
    {"description": "运行测试"}
  ]
}

Plan 是 LLM 驱动的线性清单——执行顺序由数组顺序决定，模型通过 plan(update) 逐步标记完成。

中断 Run

# 中断当前 Run
curl -X POST http://localhost:9091/cells/my-cell/sessions/s1/interrupt

# 中断 Cell 内所有 Run
curl -X POST http://localhost:9091/cells/my-cell/sessions/interrupt-all

查看 Run 历史

# Run 列表
GET /cells/{id}/observe/runs?limit=20

# Run 详情
GET /cells/{id}/observe/runs/{runID}

# Run 工具调用追踪
GET /cells/{id}/observe/runs/{runID}/tools