0 Fork 0

Files

T

Logan.Li 1c98c25c74 feat(agentcli): 运行结果 incomplete 语义与契约文档

RunResult 增加 Outcome/Reason；触顶标记 incomplete:max_steps；
WebSocket finish 区分 incomplete 与 fatal error。补充 ai-agent docs 13 与挂点索引。

2026-10-19 03:53:09 +08:00

6.2 KiB

Raw Blame History

13 - 运行结果状态与可续跑契约（三产品统一）

// Logan.Li 权威语义契约：opsxcli / aiops（backend/pkg/agentcli）/ opsxshell 共用。本文档先诚实于现状，并标明目标态；代码实现以契约为准后续对齐。权威副本与 opsxcli docs/13-运行结果状态与可续跑契约.md 同步维护；本目录其它文档链到本文。配套：09-三产品定位与执行边界.md、opsxcli 12-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 后代码

6.2 KiB Raw Blame History Unescape Escape