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

5.2 KiB

Raw Blame History

03 - 执行循环与 Harness

Harness 是把 LLM 包装成可靠工程系统的外部机制。AIOps 的 Harness 包含 Prompt、工具、风险控制、事件流、会话和记忆。// Logan.Li

核心执行循环

backend/pkg/agentcli/core/agent.go 实现 ReAct 循环：

用户任务
  → 构建 System Prompt
  → LLM 生成思考或工具调用
  → 工具执行前安全检查
  → 工具输出回写给 LLM
  → LLM 基于观察继续判断
  → 输出最终答案
  → Evolver 异步学习

ReAct 的价值在于让模型交替进行推理和行动，工具输出会校正模型判断，减少纯文本推理里的幻觉和错误传播。

Harness 组件

组件	代码位置	作用
Prompt Harness	`pkg/agentcli/prompt/prompt.go`	角色、目标、安全规则、工具说明、输出要求
Tool Harness	`pkg/agentcli/tools/`	把真实操作封装成函数调用
Safety Harness	`pkg/agentcli/safety/`	工具执行前风险判断和确认
Event Harness	`core.EventCallback`	将内部状态转换为前端事件和 DB 消息
Session Harness	`controller/agent_cli*.go`	创建会话、恢复历史、继续追问
Memory Harness	`pkg/agentcli/evolver/`	任务结束后沉淀经验

Core Config

字段	默认值	说明
`MaxIterations`	`16`	最大 ReAct 轮数
`Temperature`	`0.3`	运维任务偏稳定，温度不宜太高
`ToolTimeout`	`120s`	单次工具超时
`OutputMaxLength`	`10000`	工具输出进入上下文前截断
`MaxContextTokens`	`8000`	历史上下文预算
`MemoryDir`	`data/agentcli`	Evolver 记忆目录
`RoundOffset`	`0`	继续追问时接续轮次

Prompt 构建

入口：

BuildSystemPrompt(mode, targetInfo, toolDescs, evolveContext)

Prompt 分为六层：

角色：主机 Agent 或 Kubernetes Agent。
目标：主机、集群、Namespace、Pod、Container。
安全：禁止破坏性命令，高危操作需确认。
工具：只注入当前模式可用工具。
工作方式：思考、行动、观察、循环、收尾。
记忆：Evolver 提供的相关经验。

Prompt 是软约束，不能代替执行前的代码安全检查。

事件模型

核心引擎产生结构化事件：

事件	含义
`progress`	轮次或 token 更新
`thought`	模型阶段性判断
`tool_call`	工具名、参数、风险
`tool_result`	工具输出、成功状态、耗时
`done`	最终答案
`error`	LLM、工具或最大轮次错误

Controller 将事件推送给前端，同时写入 agent_cli_messages。这相当于 AIOps 自己的 Agent trace。

工具调用处理

tool_call
  → Registry.Get()
  → JSON 参数解析
  → 动态风险评估
  → safety.Check()
  → Execute()
  → 超长输出自动 analyze_output
  → 输出截断
  → tool_result
  → observation 返回给 LLM

OpenAI Agents 的 guardrail 思路也强调：输入、输出和工具调用都要在各自阶段检查。AIOps 当前最核心的是工具 guardrail，后续需要补齐输入和输出 guardrail。

循环检测与检查点

机制	当前实现
同参循环检测	同一工具同一参数超过 3 次则拒绝
第 4 轮检查点	重复调用或连续失败时提示换思路
第 8 轮检查点	要求总结进展，信息够就收尾
第 12 轮检查点	提醒剩余步数有限，尽快输出结论

这些机制用于降低 Agent 原地打转的概率。

上下文管理

trimMessages() 的策略：

永远保留 system prompt。
从最近消息向前保留。
控制在 MaxContextTokens * 90%。
至少保留最近 4 条。
裁剪后校验 tool_call 和 tool_result 配对。

这对应生产 Agent 的“own your context window”原则：上下文窗口是工程资源，需要明确管理。

待增强

能力	原因
输入 Guardrail	防 Prompt Injection、越权任务、无目标任务
输出 Guardrail	防敏感信息泄露、错误修复建议、不可执行总结
Trace ID	把一次运行串起 LLM、工具、确认、审计
Eval 数据集	固化典型主机/K8s 排障任务，回归测试 Agent 质量

理论 vs 运行时（2026-09-18 增补）// Logan.Li

层次	含义	aiops 现状（摘要）	目标
工程 Harness	文档、评审、测试、发布门禁	随仓库既有实践	持续 Steering Loop
运行时 Harness	主循环预算、完整性、续跑、可观测状态	MaxIterations=16 硬停；续聊链路已有；integrity 较好	统一 13-契约：`incomplete` 一等公民
反馈回路	失败可纠正、未完成可续	续聊可用；缺统一 incomplete 语义	API/事件暴露 reason + resumable

共同缺口：长时间任务的任务级 checkpoint、触顶后的诚实 incomplete（而非仅 error）。

借鉴：Anthropic long-running harness；oh-my-pi（retry 与 compaction 分轨、resume 重建 context）。

5.2 KiB Raw Blame History Unescape Escape