aiops/docs/agent/03-Harness工程化与反馈回路.md

03 - Harness 工程化与反馈回路

本文由 opsxcli 同名设计文档适配改写，结合 aiops Agent CLI 的 Web 实现（backend/pkg/agentcli/）。 Harness Engineering 是与具体语言/形态无关的理论框架，原文的思想性内容（控制论、Steering Loop、四类调节 Harness）几乎完全保留；落地实例部分从「opsxcli CLI + golangci-lint」改写为「aiops 后端库 + WebSocket 反馈回路 + Evolver 自进化」。

---

1. 核心定义：Agent = Model + Harness

1.1 什么是 Harness

Agent = Model + Harness — LangChain

Harness 是 Agent 中除 Model 本身之外的一切。在大模型运维 Agent 的有界上下文中，Harness 分为两个层次：

• 内置 Harness（built-in harness）：引擎作者构建的部分 —— System Prompt、工具注册机制、ReAct 编排循环
• 外部 Harness（outer harness）：业务方为自身场景构建的部分 —— 安全模式、确认机制、记忆注入、审计落库

Model 是「大脑」，Harness 是「身体 + 环境 + 工具 + 规则」。大脑决定智能，但身体和环境决定智能能否被正确、可靠、持续地发挥。

1.2 两个目标

一个构建良好的 Harness 服务于两个目标：

1. 提高智能体首次就做对的概率（feedforward）
2. 提供反馈回路，在问题到达人类前尽可能自我纠正（feedback） — Martin Fowler / Birgitta Böckeler

这两个目标分别对应前馈指导和反馈传感器，是 Harness 的双引擎。

1.3 核心理念

Humans steer. Agents execute. — OpenAI

人类的工作重心从「敲每一条命令」，转向设计环境、明确意图和构建反馈回路。在 aiops Agent CLI 中，运维人员的角色从「亲自 SSH 排障」变为「在 Web 上描述任务、审阅高危确认、监督 Agent 执行」。

---

2. 控制论基础：前馈与反馈

2.1 前馈指导 vs 反馈传感器

维度	前馈指导（Feedforward Guides）	反馈传感器（Feedback Sensors）
时机	智能体行动之前	智能体行动之后
目的	预期行为并加以引导	观察产出并帮助自我纠正
效果	提高首次做对的概率	在问题到达人类前自我纠正
aiops 实例	五层 System Prompt、工具描述、安全规则文本	安全 Check 拦截、循环检测、连续失败追踪、自适应检查点

仅有前馈，规则永远无法验证是否奏效；仅有反馈，智能体会重复同样的错误。两者缺一不可。

2.2 计算型 vs 推理型

类型	特点	例子
计算型（Computational）	确定性、快速、CPU 执行	黑名单匹配、命令风险分级、循环检测、token 估算
推理型（Inferential）	语义分析、AI 审查、LLM 调用	Evolver 用 LLM 提炼经验、LLM 决定下一步工具

计算型传感器成本低、速度快，适合每次工具调用都运行（如 safety.Controller.Check、AssessBashRisk）。推理型传感器更强大但更贵、不确定，适合关键节点（如任务完成后的经验提炼）。

推理型传感器的特别威力：当反馈信号被优化为 LLM 可消费的格式时（如把「连续失败」翻译为「请换一种思路」的中文提示注入对话），形成一种积极的 prompt injection —— 这正是 aiops 自适应检查点的设计依据。

2.3 Steering Loop 掌舵循环

Steering Loop 是 Harness Engineering 的元过程 —— 通过迭代改进 Harness 来引导智能体。

┌──────────┐   Agent 工作   ┌──────────┐   系统改进    ┌──────────┐
│  Harness  │ ──────────► │ 观察问题  │ ──────────► │ 更新Harness│
│ (当前版本) │              │(多次发生) │             │ (新版本)   │
└──────────┘              └──────────┘             └──────────┘
      ▲                                                    │
      └────────────────────────────────────────────────────┘
                         循环往复

在 aiops Agent CLI 中，Steering Loop 有两种实现：

1. 人工 Steering：管理员在「大模型设置」调整 SystemPrompt、温度等 → 影响 Agent 下次行为
2. 自动 Steering：Evolver 引擎观察任务执行 → 自动学习经验 → 注入下次 Prompt（详见第 08 篇）

后者是 opsxcli 设计思想的核心延伸 —— 用代码自动化 Steering Loop。

2.4 Keep Quality Left — 把质量左移

在 aiops Agent CLI 的执行链路中，反馈传感器按成本分布：

阶段	应运行的传感器	特点
工具执行前	黑名单硬拒、AssessBashRisk 分级、安全模式阈值	毫秒级，每次必跑
工具执行中	context 超时（ToolTimeout 120s 兜底）	防卡死
轮次间	自适应检查点（Round 4/8/12）、循环检测（>3 次拒绝）、连续失败追踪	防 LLM 跑偏
任务完成后	Evolver 异步学习（30s 超时）	较贵，异步

---

3. 三类调节 Harness

Agent Harness 如同一个控制论调节器（governor），通过前馈和反馈将系统调节到期望状态。

3.1 可维护性 Harness（Maintainability）

• 计算型：文件大小红线（Go handler ≤400 行、组件 ≤700 行）、go vet、tsc --noEmit
• 推理型：代码审查（review）
• 在 Agent CLI 代码中体现为「引擎库零业务依赖」「单文件 ≤300 行」等约束

3.2 架构适应度 Harness（Architecture Fitness）

• 前馈：分层依赖约定（controller → model + pkg/agentcli，引擎库不反向 import）
• 反馈：编译失败即拦截（Go 强类型天然传感器）

3.3 行为 Harness（Behaviour）— 本项目的重点

如何引导和感知 Agent 是否按预期功能运行：

• 前馈：五层 System Prompt（角色 + 安全规则 + 工作方式 ReAct 范式）
• 反馈：
  • 安全层硬拦截 + 高危确认（防破坏性操作）
  • ReAct 循环中的自适应检查点（防 LLM 死循环或编造输出）
  • WebSocket 事件流的可观测性（人类可随时观察思考与命令）
  • Evolver 经验学习（成功的工具序列被强化，失败的被记录为「换法」提示）

---

4. Harnessability 与设计启示

4.1 可 Harness 性

aiops 后端是 Go 强类型 + 清晰的包边界，天然适合被 Harness：

• 强类型使 LLM 工具的 JSON Schema 可以严格约束参数
• 清晰的 controller / model / pkg 分层使「引擎库零业务依赖」可行
• 复用 aiops 既有的凭证系统、SSH 包、DB，大幅缩减 Harness 代码量

4.2 Ashby 必要多样性定律

调节器必须拥有至少与被调节系统相同的多样性。

aiops Agent CLI 通过两层多样性缩减：

1. 工具集精简（6 → 2）：只保留 ssh_execute + analyze_output，把「在远程主机做任何事」收敛为「执行 shell + 分析输出」，让 LLM 的决策空间可控
2. Prompt 工作方式约束：明确告诉 LLM「一次只做关键的、可验证的一步」「优先只读命令」「失败要换法重试」

这是把潜在的「无限可能的 Agent」收敛为「可控的运维 Agent」的关键策略。

4.3 Harness 模板

aiops Agent CLI 本身就是一个「Web 版运维 Agent Harness 模板」—— 它的前馈（五层 Prompt）、反馈（安全 + 检查点 + Evolver）、工具协议（Tool 接口）可以被视为同类产品的参考实现。

---

5. 反馈回路设计

5.1 多轮自我评审循环

aiops ReAct 循环本质就是一种多轮自我评审：

Round 1：LLM 思考 + 决定工具
    │
Round 2：执行工具 → 观察输出（exit_code 是关键信号）
    │
Round 3：根据输出判断 → 继续排障或修复
    │
═══ 检查点 Round 4 ═══
    ├─ 若重复调用率 >50% 或连续失败 ≥3 → 注入「换思路」提示
    │
Round N：… 直到 LLM 不再返回 tool_calls
    │
═══ 检查点 Round 8 ═══ 强制中间总结
═══ 检查点 Round 12 ═══ 敦促收尾
    │
最终答案 + Evolver 学习（后台）

5.2 黄金原则

从 OpenAI Codex 实践提炼的四条原则在 aiops Agent CLI 中的体现：

1. 优先使用共享抽象：pkg/remoteexec（SSH）、pkg/agentcli/tools（Tool 接口）、pkg/agentcli/llm（Client 接口），将不变式集中管理
2. 不使用「YOLO 式」探测：所有命令先经 AssessBashRisk 评估，黑名单硬拒、高危确认，绝不盲目执行
3. 统一错误处理：工具返回 Result{Success, Output, Error}，错误信息以中文回到对话供 LLM 理解；Evolver 失败优雅降级不阻断主循环
4. 避免全局状态：Engine 每次任务一个实例，Registry 通过 sync.RWMutex 保护；会话状态走 DB 不走全局变量

---

6. aiops Agent CLI 代码对照

6.1 前馈指导实例

理论概念	aiops 实现	代码位置
角色与能力引导	五层 System Prompt	pkg/agentcli/prompt/prompt.go
工具能力披露	Registry 动态生成工具描述	core/agent.go: buildToolDescriptions
工作范式引导	ReAct 范式文本（思考-行动-观察-循环-收尾）	prompt.go Layer 4
安全规则文本	黑名单 + 优先只读 + 高危确认	prompt.go Layer 2

6.2 反馈传感器实例

理论概念	aiops 实现	代码位置
计算型反馈（执行前）	黑名单硬拒 + 风险分级	tools/risk.go + safety/safety.go: Check
计算型反馈（轮次间）	循环检测（同参 >3 拒绝）	core/agent.go: processToolCalls
计算型反馈（轮次间）	连续失败追踪	core/agent.go: updateConsecutiveFailures
结构化反馈	自适应检查点（Round 4/8/12 注入提示）	core/agent.go: checkAdaptiveCheckpoint
上下文保护	消息裁剪 + tool 消息完整性修复	core/agent.go: trimMessages + ensureToolMessageIntegrity
安全反馈	三级模式阈值 + 高危确认	safety/safety.go

6.3 Steering Loop 实例

aiops 的 Evolver 自进化引擎是自动 Steering Loop 的代码级实现：

EvolverEngine (pkg/agentcli/evolver/)
    │
    ├── engine.go     精简进化循环（OBSERVE→CLASSIFY→LEARN→STORE→MEMORIZE→PREDICT）
    └── memory.go     四层记忆（experience/factual/procedural/environment）

每次任务执行后，Evolver 异步学习并存储经验；下次任务开始时，GetContextForPrompt() 把相关历史经验注入 System Prompt 的 Layer 5 —— 这就是「观察问题 → 改进 Harness」的自动化实现。

6.4 品味不变式实例

类别	不变式	理由
语言	注释和错误信息使用中文，署名 // Logan.Li	项目规范
命名	导出函数 PascalCase，包名全小写	Go 标准
错误	Result.Error 携带中文错误，Evolver 失败降级不 panic	保留错误链，不阻断主流程
依赖	controller → model + pkg/agentcli（单向）	引擎库零业务依赖
日志	引擎 emit Event，由 controller 决定落库还是推 WS	引擎不直接依赖 DB/WS
安全	黑名单硬拒不可被确认放行	安全红线

---

7. Web 可观测性

opsxcli 是 CLI 工具，可观测性 = slog + 审计日志 + --debug。 aiops Agent CLI 是 Web 服务，可观测性 = WebSocket 事件流 + DB 持久化 + 会话历史回放。

7.1 事件流（实时）

引擎通过 EventCallback 推送结构化事件，controller 序列化为 wsEvent 后推 WebSocket：

Event.Type	含义	前端渲染
progress	轮次 + token	顶部进度条
thought	AI 思考文本	思考气泡
tool_call	即将执行的工具 + 风险	工具调用卡片（含风险标签）
tool_result	工具输出 + 成败 + 耗时	工具结果卡片
confirm	高危确认请求	useConfirm 弹框
done	最终答案	完成气泡
error	错误（含达到最大轮次）	错误气泡

7.2 持久化（事后审计）

每条事件（除 progress）落库 agent_cli_messages，前端「会话历史」页面可按 session_id 回放完整 ReAct 推理过程：

// controller/agent_cli.go: persistMsg
// 每条消息记录：round / type / role / content / tool_name / tool_args /
//               tool_output / risk / success / duration / tokens

与 opsxcli 的差异：opsxcli 把审计日志写到 ~/.opsxcli/audit/audit.log（文件），aiops 直接走 DB（多用户、可查询、可关联用户与主机）。

---

8. 参考资源

资源	说明
Martin Fowler — Harness Engineering	理论框架，控制论视角
OpenAI — Harness Engineering	实践报告，Codex 实战经验
LangChain — Agent = Model + Harness	术语定义
Anthropic — Effective Harnesses for Long-Running Agents	长时间运行 Agent 的 Harness 设计

作者：Logan.Li