Logan.Li
1c98c25c74
RunResult 增加 Outcome/Reason；触顶标记 incomplete:max_steps； WebSocket finish 区分 incomplete 与 fatal error。补充 ai-agent docs 13 与挂点索引。
159 lines
5.2 KiB
Markdown
159 lines
5.2 KiB
Markdown
# 03 - 执行循环与 Harness
|
||
|
||
> Harness 是把 LLM 包装成可靠工程系统的外部机制。AIOps 的 Harness 包含 Prompt、工具、风险控制、事件流、会话和记忆。// Logan.Li
|
||
|
||
---
|
||
|
||
## 核心执行循环
|
||
|
||
`backend/pkg/agentcli/core/agent.go` 实现 ReAct 循环：
|
||
|
||
```text
|
||
用户任务
|
||
→ 构建 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 构建
|
||
|
||
入口：
|
||
|
||
```go
|
||
BuildSystemPrompt(mode, targetInfo, toolDescs, evolveContext)
|
||
```
|
||
|
||
Prompt 分为六层：
|
||
|
||
1. 角色：主机 Agent 或 Kubernetes Agent。
|
||
2. 目标：主机、集群、Namespace、Pod、Container。
|
||
3. 安全：禁止破坏性命令，高危操作需确认。
|
||
4. 工具：只注入当前模式可用工具。
|
||
5. 工作方式：思考、行动、观察、循环、收尾。
|
||
6. 记忆：Evolver 提供的相关经验。
|
||
|
||
Prompt 是软约束，不能代替执行前的代码安全检查。
|
||
|
||
---
|
||
|
||
## 事件模型
|
||
|
||
核心引擎产生结构化事件：
|
||
|
||
| 事件 | 含义 |
|
||
|------|------|
|
||
| `progress` | 轮次或 token 更新 |
|
||
| `thought` | 模型阶段性判断 |
|
||
| `tool_call` | 工具名、参数、风险 |
|
||
| `tool_result` | 工具输出、成功状态、耗时 |
|
||
| `done` | 最终答案 |
|
||
| `error` | LLM、工具或最大轮次错误 |
|
||
|
||
Controller 将事件推送给前端，同时写入 `agent_cli_messages`。这相当于 AIOps 自己的 Agent trace。
|
||
|
||
---
|
||
|
||
## 工具调用处理
|
||
|
||
```text
|
||
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()` 的策略：
|
||
|
||
1. 永远保留 system prompt。
|
||
2. 从最近消息向前保留。
|
||
3. 控制在 `MaxContextTokens * 90%`。
|
||
4. 至少保留最近 4 条。
|
||
5. 裁剪后校验 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-契约](13-运行结果状态与可续跑契约.md)：`incomplete` 一等公民 |
|
||
| 反馈回路 | 失败可纠正、未完成可续 | 续聊可用；缺统一 incomplete 语义 | API/事件暴露 reason + resumable |
|
||
|
||
共同缺口：长时间任务的任务级 checkpoint、触顶后的诚实 `incomplete`（而非仅 error）。
|
||
|
||
借鉴：Anthropic long-running harness；oh-my-pi（retry 与 compaction 分轨、resume 重建 context）。
|