MODULE // PHOENIX HARNESS

Phoenix Agent Harness 的探索实现

从「支付回调 500」的真实场景出发，用第一性原理讲清 Phoenix Agent Harness 是什么、为什么需要、架构如何分工、三个不变量如何撑住实现原理，以及 Phoenix 在这条路线上的设计取舍。

一、从一个事故场景说起：为什么「会调 API 的 while 循环」不够？

周五晚，值班同学对一个 Coding Agent 说：「生产环境支付回调 500，帮我查日志、定位原因并提交修复。」Agent 开始干活——拉取应用日志，猜测是回调验签配置过期；直接改了一行生产配置；又跑 shell 做连通性测试；测试失败后继续改代码、再跑一遍。看起来「很智能」，直到周一复盘：没人说得清它依据哪条日志得出「验签过期」；改配置前没有任何人确认；进程重启后上下文全丢，同事无法复现同样输入下的决策链。

这不是模型「不够聪明」，而是缺少运行时壳：脚本式 Agent 能跑通 demo，却在五处必然撞墙——无法追责、无法回放、工具无门控、人不能介入、状态随进程消失。这五处失败，恰好对应 Harness 必须接管的五类职责：状态、循环、工具、治理、可观测。

FIG.01//场景爆点如何映射到 Harness 五职责看懂：每个生产事故点，对应 Harness 必须接管的一层职责

支付回调 500 · 裸 Loop

读生产日志

⚠ 依据难追溯

猜原因改配置

⚠ 无法回放决策链

跑 shell 测修复

⚠ 危险命令无门控

测试失败继续改

⚠ 人不能介入

进程重启

⚠ 上下文全丢

Harness 应接管

可观测

回应：依据难追溯

状态 / 日志

回应：无法回放决策链

工具治理

回应：危险命令无门控

人机协作

回应：人不能介入

会话持久

回应：上下文全丢

状态循环工具治理可观测

Harness 的定义由此清晰：它包住模型，负责「能跑、可控、可运维」；模型只负责「想一步」。Phoenix 的核心主张是——模型只是插件之一。换供应商、换上下文窗口，不必改动工具注册、会话持久与审批逻辑。Harness 才是产品，模型是可替换的推理引擎。

FIG.02//裸 Agent Loop vs Harness看懂：Harness 不是更复杂的 prompt，而是可运维的运行时壳

while + LLM + tools

· 状态在内存里，重启即失忆
· 工具调用不可拦截
· UI 与模型各记各的
· 换模型要改主流程
· 无法复现同样决策链

Phoenix Agent Harness

· 事件日志持久，可回放 / Fork
· 执行前三段门 + 审批
· 单一真相源投影 UI 与上下文
· 模型只是能力插件之一
· Turn / Step 可追溯

设计取舍

得到

长期可运维：可回放、可审计、可分级管控，团队敢把 Agent 放进生产链路。

付出

前期架构成本更高——要设计日志协议、扩展缝与组装层，上手慢于 fifty 行 while 循环。

本章收束

Harness 不是「更复杂的 prompt」，而是把 Agent 从实验脚本升级为可运维系统。下文将说明：这种系统长什么样、靠什么不变量撑住、Phoenix 如何在一次 Go 探索实现里验证这条路线。