# 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）。