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
1 parent f3a4fb569f
commit 1c98c25c74
@@ -21,7 +21,7 @@ AI Agent / Agent CLI 是 AIOps 的智能执行入口。用户在浏览器中选

 ## 文档目录

-当前目录包含 9 篇正文，避免把同一条链路拆得过碎：
+当前目录以设计正文为主，并增补运行结果契约与挂点索引，避免把同一条链路拆得过碎：

 | 编号 | 文档 | 说明 |
 |------|------|------|
@@ -34,6 +34,8 @@ AI Agent / Agent CLI 是 AIOps 的智能执行入口。用户在浏览器中选
 | 07 | [路线图与评测](07-路线图与评测.md) | 可用堡垒机、企业堡垒机、智能闭环、评测指标 |
 | 08 | [代码审计与平台智能化优化](08-代码审计与平台智能化优化.md) | Agent CLI 代码差距、AIOps 上下文工具、告警分析和预测分析升级路线 |
 | 09 | [三产品定位与执行边界](09-三产品定位与执行边界.md) | OpsXCLI、OpsXShell、AIOps 的独立目标、凭证、执行和审计边界 |
+| 08b | [代码审计与挂点索引](08-代码审计与挂点索引.md) | incomplete/续跑挂点速查（配套平台智能化优化长文） |
+| 13 | [运行结果状态与可续跑契约](13-运行结果状态与可续跑契约.md) | **先 docs 后代码**：completed/incomplete/可续跑统一语义 |

 ---

@@ -125,3 +127,19 @@ backend/pkg/agentcli/
 | [安全审计与堡垒机](../security-bastion/README.md) | 会话、审计、审批统一设计 |
 | [终端体系](../terminal/README.md) | WebSSH、Pod exec、kubectl 终端 |
 | [Kubernetes 管理](../kubernetes/README.md) | K8s 资源、Pod、YAML、AI 排障 |
+
+---
+
+## 运行结果语义（2026-09-18 增补）
+
+> 先 docs 后代码。实现逐步对齐契约，勿把步数触顶当成「完成」。
+
+| 项 | 诚实现状 | 目标 |
+|----|----------|------|
+| MaxIterations | 默认 16，硬停 | `incomplete`/`max_steps` + 可续 |
+| integrity | 已按 `tool_call_id` 整组保留（优于 opsxcli） | 保持为参考实现 |
+| 续聊 | `resumeSession`→`convHistory`→`continueTask(prior)` 已有 | 暴露结构化 incomplete reason |
+| 超时/上下文 | ToolTimeout 120s；MaxContext 8000 | 字段与契约对齐、可配置 |
+
+权威契约：[13-运行结果状态与可续跑契约](13-运行结果状态与可续跑契约.md)（与 opsxcli `docs/13-*.md` 同步）。
+
@@ -142,3 +142,17 @@ OpenAI Agents 的 guardrail 思路也强调：输入、输出和工具调用都
 | 输出 Guardrail | 防敏感信息泄露、错误修复建议、不可执行总结 |
 | Trace ID | 把一次运行串起 LLM、工具、确认、审计 |
 | Eval 数据集 | 固化典型主机/K8s 排障任务，回归测试 Agent 质量 |
+
+---
+
+## 理论 vs 运行时（2026-09-18 增补）// Logan.Li
+
+| 层次 | 含义 | aiops 现状（摘要） | 目标 |
+|------|------|-------------------|------|
+| 工程 Harness | 文档、评审、测试、发布门禁 | 随仓库既有实践 | 持续 Steering Loop |
+| 运行时 Harness | 主循环预算、完整性、续跑、可观测状态 | MaxIterations=16 硬停；续聊链路已有；integrity 较好 | 统一 [13-契约](13-运行结果状态与可续跑契约.md)：`incomplete` 一等公民 |
+| 反馈回路 | 失败可纠正、未完成可续 | 续聊可用；缺统一 incomplete 语义 | API/事件暴露 reason + resumable |
+
+共同缺口：长时间任务的任务级 checkpoint、触顶后的诚实 `incomplete`（而非仅 error）。
+
+借鉴：Anthropic long-running harness；oh-my-pi（retry 与 compaction 分轨、resume 重建 context）。
@@ -132,3 +132,25 @@ data/agentcli/
 | 记忆脱敏 | 敏感输出不进入记忆 |
 | 团队共享 | 高质量经验可转为团队 Runbook |
 | 来源追踪 | 每条记忆能追溯到 session/message |
+
+---
+
+## 续聊与 incomplete（2026-09-18 增补）// Logan.Li
+
+平台路径：`resumeSession → convHistory → continueTask(prior)` ——相对 opsxcli 更接近真·续跑。
+
+仍须对齐 [13-契约](13-运行结果状态与可续跑契约.md)：tool 轨迹完整；触顶/超时标记 `incomplete` + reason + `resumable`。
+
+| 项 | 现状 | 目标 |
+|----|------|------|
+| 续聊 prior 注入 | 已有 | 保持；补集成测试与文档示例 |
+| MaxIterations=16 硬停 | 有 | `incomplete`/`max_steps`，允许加预算再 continue |
+| incomplete 对外语义 | 偏 error/文案 | 结构化状态枚举 |
+| ToolTimeout / MaxContext | 120s / 8000 | 写入可观测字段；与契约一致 |
+
+| | opsxcli | aiops |
+|--|---------|-------|
+| resume | UI 为主，引擎未接通 | 续聊链路已通 |
+| tool integrity | 多 tool 有丢 observation 风险 | 按 tool_call_id 整组保留 |
+| 默认上下文 | 6000 | 8000 |
+| 默认工具超时 | 60s | 120s |
@@ -325,3 +325,9 @@ RCA 输出不要只要自然语言，建议固定结构：
 4. **可执行**：建议能转成只读检查、修复计划、审批动作或自动化任务。

 只要沿着这条线做，智能助手、告警分析、预测分析就会从“AI 页面”变成 AIOps 平台真正的智能中枢。
+
+---
+
+## 挂点速查（2026-09-18）// Logan.Li
+
+复杂多步「未跑完就挂」的对照表与修复优先级见：[08-代码审计与挂点索引](08-代码审计与挂点索引.md) 与权威契约 [13-运行结果状态与可续跑契约](13-运行结果状态与可续跑契约.md)。本文保留平台智能化长文；挂点索引为增量入口。
@@ -0,0 +1,19 @@
+# 08 - 代码审计与挂点索引（摘录）
+
+> // Logan.Li
+> 可选短文：指向「复杂多步骤未跑完」相关挂点。完整审计正文若已在本机，将本节作为附录合并即可。
+
+## 本次文档对齐的挂点
+
+| 产品 | 挂点 | 文档落点 |
+|------|------|----------|
+| 三产品 | 缺统一 `incomplete` / 可续跑定义 | [13-契约](13-运行结果状态与可续跑契约.md) |
+| opsxcli | 触顶硬失败；resume 未注入引擎；SaveToolResult 无调用；integrity；Estimate 忽略 ToolCalls；RunStream 无检查点 | opsxcli `06`/`10`/`12`/`13` |
+| aiops | 16 硬停；续聊已有；integrity 较好 | 本文档集 `06`/`09`/`13` |
+| opsxshell | `MAX_AGENT_STEPS=12` 抛错；绑 connectionId | `09` + opsxshell `01` |
+
+排查底稿（box）：`opsx-ai-docs/hang-rootcause-report.md`（若已同步到本机可一并归档）。
+
+---
+
+*更新: 2026-09-18 CST*
@@ -52,3 +52,25 @@
 - P0：脱敏、目标锁定、危险操作拒绝、超时与真实取消、记忆不自动获得执行权。
 - P1：结构化结果、只读诊断工具、执行后验证、目标与命令绑定确认。
 - P2：版本化 Runbook、受控经验库、场景评测、跨资产自动化与熔断。
+
+---
+
+## 统一结果状态衔接（2026-09-18 增补）// Logan.Li
+
+**边界优先**：统一结果状态 ≠ 统一执行平面。不削弱上文三产品隔离；不得共享可跨入口自由切换的通用远程执行器。
+
+三产品应对用户暴露同一套语义（实现可分阶段）：
+
+`completed` | `incomplete` | `failed` | `cancelled` | `awaiting_confirm`
+
+`incomplete` reason：`max_steps` / `context_budget` / `tool_timeout` / `llm_timeout` / `connection_lost` / `safety_abort`
+
+详见 [13-运行结果状态与可续跑契约](13-运行结果状态与可续跑契约.md)。
+
+| 产品 | 默认步数预算 | 触顶现状 | 目标 |
+|------|--------------|----------|------|
+| opsxcli | MaxIterations=16 | 硬失败文案 | incomplete + 可续 |
+| aiops agentcli | MaxIterations=16 | 硬停 | 同上；续聊已有 prior |
+| opsxshell | `MAX_AGENT_STEPS=12` | 抛错 | 同上；仍绑当前 connectionId |
+
+Shell 侧短文：`opsxshell/docs/01-AI-Agent步数预算与incomplete.md`。
@@ -0,0 +1,132 @@
+# 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 什么才算真·续跑
+
+**必须同时满足**：
+
+1. **持久化 tool 轨迹**：assistant `tool_calls` 与对应 tool observation（含 `tool_call_id`）已落盘；
+2. **引擎注入**：下次 `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/事件，非现状承诺）
+
+```text
+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 后代码*