Logan.Li
1c98c25c74
RunResult 增加 Outcome/Reason；触顶标记 incomplete:max_steps； WebSocket finish 区分 incomplete 与 fatal error。补充 ai-agent docs 13 与挂点索引。
6.2 KiB
6.2 KiB
13 - 运行结果状态与可续跑契约（三产品统一）
// Logan.Li 权威语义契约：opsxcli / aiops（backend/pkg/agentcli）/ opsxshell 共用。 本文档先诚实于现状，并标明目标态；代码实现以契约为准后续对齐。 权威副本与 opsxcli
docs/13-运行结果状态与可续跑契约.md同步维护；本目录其它文档链到本文。 配套：09-三产品定位与执行边界.md、opsxcli12-Agent运行边界与安全基线.md。
1. 统一运行结果状态（RunOutcome）
所有面向用户/上游的 Agent 运行结束，必须能归入下列之一（禁止用「看起来像完成了」掩盖预算耗尽）：
| 状态 | 含义 | 用户感知 |
|---|---|---|
completed |
在预算内达成任务目标，给出可用最终答案 | 正常完成 |
incomplete |
未完成：因预算/超时/连接等原因主动或被迫停住，但已有部分轨迹可续 | 「步骤没跑完」——应可续跑或加预算 |
failed |
不可恢复错误（协议坏、鉴权失败、不可重试的工具致命错等） | 失败，需改输入/环境 |
cancelled |
用户/上游主动取消 | 已取消 |
awaiting_confirm |
安全策略要求人工确认后才能继续 | 等待确认 |
1.1 incomplete 必须可区分原因（IncompleteReason）
| reason | 典型触发 |
|---|---|
max_steps |
触达 MaxIterations / MAX_AGENT_STEPS |
context_budget |
上下文裁剪/窗口不足导致无法安全继续本轮 |
tool_timeout |
工具执行超时 |
llm_timeout |
LLM/流式读超时 |
connection_lost |
SSH/网络会话中断 |
safety_abort |
安全控制器中止（非「等待确认」） |
规则：触顶步数预算 → 必须是 incomplete + max_steps，不得伪装成 completed，也不宜仅抛「任务未能完成」而无结构化状态（目标态）。
2. 「可续跑」（Resumable）定义
2.1 什么才算真·续跑
必须同时满足：
- 持久化 tool 轨迹：assistant
tool_calls与对应 tool observation（含tool_call_id）已落盘； - 引擎注入：下次
Run/RunStream/continueTask把历史 messages（或等价 prior）注入 Agent 上下文，从中断点继续推理与工具调用。
仅恢复 TUI/UI 聊天泡泡、仅 Load 会话元数据、或不注入引擎的「回放」，不算 resume。
2.2 借鉴要点（oh-my-pi / pi，勿照搬实现）
| 思想 | 对我们的含义 |
|---|---|
| resume 切换会话后重建 agent context（含中断 turn 的 abort 合成） | Load 后必须重建可喂给 LLM 的 messages |
| fork = 新会话身份 + 复制轨迹 | 续跑可同会话续，或 fork 新会话隔离实验 |
| compaction / handoff | 上下文不够时摘要保真，而非静默丢 tool observation |
| retry 与 compaction 分轨 | 超时/限流可重试；窗口溢出走压缩/incomplete，不混为一谈 |
| session lifecycle status（interrupted 等） | 与 incomplete 对齐，列表/UI 可区分 |
3. 步数预算语义
| 原则 | 说明 |
|---|---|
| 默认值是预算不是质量承诺 | opsxcli/aiops 默认 16、opsxshell MAX_AGENT_STEPS=12 只表示「这一趟最多走几步」 |
触顶 = incomplete |
不是「覆盖 90% 场景所以算完成」 |
| 目标态 | 支持：加大预算续跑、同会话 resume、显式 continue；可选任务级 checkpoint |
4. 文档 vs 实现对照表（现状 / 目标）
4.1 opsxcli
| 能力 | 现状（2026-09） | 目标 |
|---|---|---|
| MaxIterations 默认 16 | 触顶硬失败「任务未能完成」 | incomplete/max_steps + partial + 可续 |
| resume / TUI load | 主要恢复 UI；Run/RunStream 重置 messages；真·Agent 续跑未接通 |
Load → 注入 messages；每轮持久化 |
| SaveToolResult | 有接口，生产路径基本无调用 | 每轮 tool 结果必写 |
| ensureToolMessageIntegrity | 一轮多 tool 时可能丢 observation（前一条须为 assistant） | 按 tool_call_id 整组保留（对齐 aiops） |
| EstimateMessages | 忽略 ToolCalls；MaxContextTokens 默认 6000 | 计入 ToolCalls/结果；按模型窗口配置 |
| RunStream 自适应检查点 | 未接入（仅 Run 有） | Run/RunStream 行为一致 |
| ToolTimeout | 默认 60s | 分层超时；长工具可心跳/提高上限 |
4.2 aiops（backend/pkg/agentcli）
| 能力 | 现状 | 目标 |
|---|---|---|
| MaxIterations=16 | 同样硬停 | 同契约：incomplete + 可续 |
| tool integrity | 已按 tool_call_id 整组保留（优于 opsxcli） |
保持；成为三产品参考实现 |
| 续聊 | resumeSession→convHistory→continueTask(prior) 已有 |
补齐结构化 incomplete 原因与 UI/API 暴露 |
| ToolTimeout / MaxContext | 120s / 8000 | 与契约字段对齐；预算可配置 |
4.3 opsxshell
| 能力 | 现状 | 目标 |
|---|---|---|
AiTerminalPanel MAX_AGENT_STEPS=12 |
触顶抛错 | incomplete/max_steps；可续或提示加预算 |
| 执行边界 | 绑当前 SSH connectionId |
保持；不引入跨入口通用远程执行器 |
4.4 三产品边界（不变）
不得共享「可跨入口自由切换」的通用远程执行器。统一的是结果状态与续跑语义，不是执行平面。详见 aiops 09-三产品定位与执行边界.md。
5. 建议对外字段（目标态 API/事件，非现状承诺）
run_outcome: completed | incomplete | failed | cancelled | awaiting_confirm
incomplete_reason?: max_steps | context_budget | tool_timeout | llm_timeout | connection_lost | safety_abort
resumable: bool # 是否满足 §2.1
steps_used / steps_budget
session_id / run_id
partial_summary?: string # 触顶时的已有进展摘要（可选）
可观测事件：在现有 done/error 之外，目标态增加明确的 incomplete phase/type，避免全部打成 error。
6. 文档索引
| 产品 | 落点 |
|---|---|
| opsxcli | 本文；06/10/03/12；README.md |
| aiops | docs/ai-agent/ 链到本文副本或相对链接；00/03/06/09 |
| opsxshell | docs/01-AI-Agent步数预算与incomplete.md |
文档版本: v1.0 | 2026-09-18 CST | 先 docs 后代码