Harness 的可见性危机:当 AI Agent 跑了 35 分钟,你只看到一个 ✅

这是「TEngine 工程哲学」系列的第二篇。第一篇:TEngine 的工程哲学:为什么 SDD + Harness Engineering 是 AI 编程的最优解 讨论了为什么 AI 工程需要自己的方法论,而不是照搬传统软件工程。这篇我们聚焦一个被严重低估的问题:Harness 的可视化–当你把一个 AI Agent 放进 Harness 里跑了 35 分钟,它到底做了什么?

引言:Harness 的可见性危机

设想一个场景。

你给 AI Agent 下了一个任务:”把角色背包系统从同步重构为异步加载,使用 Addressables 替代 Resources,确保不卡主线程。”Agent 接到任务,开始工作。终端上出现了一行行日志–读取 Prefab、修改脚本、迁移引用、运行 Play Mode 测试……然后,35 分钟后,你看到了:

✅ Task completed successfully

你的第一反应是什么?

如果你和我一样,你的第一反应不是”太好了”,而是”等等,你到底做了什么?”

这就是 Harness 的可见性危机。Harness–作为约束、监控和验证 AI Agent 行为的执行框架–在”是否完成”这个问题上给了你答案,但在”如何完成”、”是否遵循约束”、”中间做了哪些决策”这些问题上,给你的信息近乎为零。

这不仅仅是 UI 的问题。这是一个信任架构的问题。一个你看不见过程的系统,你敢把它放到生产环境吗?

让我们从头说起。

---

第一章:为什么 Harness 必须可视化

先定义一下术语。在本文语境中,Harness 指的是围绕 AI Agent 构建的执行环境–它包括约束定义(Spec)、执行运行时(Runtime)、行为监控(Monitor)和质量门控(Gate)。你可以把它类比成传统软件中的测试 harness,但要复杂得多:因为被测试的对象不是一个确定性函数,而是一个可能做出出乎意料决策的自主 Agent。

可视化为什么不是锦上添花,而是刚需?四个字:信、调、约、协。

1.1 信任(Trust)

信任是协作的基石。你和一个人共事,你需要知道他的工作方式–他倾向于先做调研还是直接动手?他的代码风格偏保守还是激进?他遇到问题会停下来沟通还是自己硬扛?

对 AI Agent 也是一样。但你无法通过”一起吃午饭”来了解一个 Agent。你唯一能了解它的方式,就是观察它在 Harness 中的行为轨迹。

具体来说,信任需要回答这些问题:

• Agent 在这个任务中总共做了多少次文件修改?修改了哪些文件?
• 它有没有”偷偷”做了你没要求的事情?(比如重构时顺便改了无关模块的命名)
• 它遇到错误时的恢复策略是什么?是回滚、重试、还是绕过?
• 它的 token 消耗和执行时间是否在预期范围内?

没有可视化,这些问题全靠猜。猜不是信任。

类比:想象你雇佣了一个远程自由职业者。他每周给你发一封邮件:”本周工作已完成。”你会满意吗?不会。你需要看到 commit history、PR 描述、设计文档。Harness 可视化就是 AI Agent 的”工作周报”–但它应该比周报更实时、更细粒度。

1.2 调试(Debugging)

AI Agent 的行为是概率性的。同一个任务,跑两次可能得到不同结果。这意味着传统的”复现 bug → 修复”模式部分失效–你甚至不确定 bug 是否能复现。

调试 AI Agent 需要一种全新的工作流:

1. 事后回溯(Post-hoc Tracing):Agent 做完了一件事,你需要回溯它的完整决策链。”为什么它删掉了 ItemDatabase.cs 里的那个缓存逻辑?”–你需要在时间线上找到那个决策点,看当时的上下文是什么、Agent 的推理是什么。

2. 约束违反分析:Harness Spec 说”不得修改 Assets/Scenes/ 目录下的 Scene 文件”,但 Agent 改了。为什么?是 Agent 理解错了 Spec?是 Spec 的表述有歧义?还是 Agent 在某个子任务中把约束”忘”了?

3. 性能归因:任务耗时 35 分钟,但同类任务上次只用了 12 分钟。时间花在哪里了?是在依赖安装上卡住了?是 Agent 做了不必要的”探索”?还是 LLM 的推理时间异常?

没有可视化,调试就像在黑暗中摸索。你知道出了问题,但你不知道问题出在哪里。

1.3 约束验证(Constraint Verification)

Harness 的核心功能之一是约束执行–确保 Agent 的行为在预定义的边界内。但约束验证不是二元判断(违反/未违反),而是一个频谱:

• 硬约束(Hard Constraints):绝对不能违反。”不能删除 Assets/Scenes/ 下的任何 Scene 文件。” 这种约束的可视化是红绿灯–绿色就是 OK,红色就是立刻中止。
• 软约束(Soft Constraints):应该遵守但允许例外。”MonoBehaviour 方法不超过 50 行。” 这种约束的可视化需要展示遵守率–是 90% 遵守还是 50% 遵守?哪些例外是合理的?
• 渐变约束(Gradient Constraints):在连续空间上的约束。”资源加载耗时不超过 2 帧。” 这种约束的可视化需要展示趋势–加载时间是上升了还是下降了?幅度多大?

一个成熟的 Harness 可视化系统,应该能让你一眼看到每条约束的状态:哪些绿灯、哪些黄灯、哪些红灯,以及每个非绿灯状态的详细信息。

1.4 团队协作(Team Collaboration)

AI Agent 不是一个人的工具。在一个工程团队中:

• Tech Lead 需要看到 Agent 的执行是否符合架构意图
• Code Reviewer 需要看到 Agent 的修改范围和理由
• DevOps 需要看到 Agent 的资源消耗和对基础设施的影响
• QA 需要看到 Agent 是否覆盖了所有测试场景

不同角色需要不同粒度和不同视角的可视化。这不是”做一个 dashboard”就能解决的–它需要多层可视化架构,我们会在第五章详细讨论。

---

第二章:Harness 的四层循环与可视化需求

在 TEngine 的工程哲学中,我们将 Harness 的执行模型抽象为一个四层循环(Four-Layer Loop)。每一层都有自己的可视化需求,而且需求截然不同。

2.1 Context 层:世界是什么样的?

Context 层负责回答”当前状态是什么”–代码库的状态、任务的要求、可用的工具、历史的上下文。这是 Agent 做出决策的基础。

可视化需求:

• 上下文地图(Context Map):Agent 在做决策时能看到多大的”世界”?它读取了哪些文件?忽略了哪些?有没有关键的上下文因为窗口限制被截断了?
• 任务分解树(Task Decomposition Tree):一个复杂任务被分解成了哪些子任务?子任务之间的依赖关系是什么?哪些是串行的,哪些是并行的?
• 工具可用性面板(Tool Availability Panel):Agent 当前可以调用哪些工具?哪些工具被 Harness 约束禁用了?

为什么重要:Context 层的可视化能帮你判断 Agent 是否拥有”足够的信息”来做出正确的决策。很多 Agent 的错误不是推理错误,而是上下文不足导致的–它根本没看到关键信息。如果你看不到 Agent 看到了什么,你就无法诊断这类问题。

具体例子:Agent 需要修改背包系统的物品加载逻辑,但因为上下文窗口有限,它没有看到另一个 Scene 中也引用了同一个加载接口。结果修改后导致那个 Scene 的背包打开时闪退。如果在 Context 层有可视化,你能看到 Agent 的”视野范围”只覆盖了文件的 60%,你就能预判这个风险。

2.2 Run 层:Agent 在做什么?

Run 层是最接近传统”执行日志”的层。它记录 Agent 的每一个动作:读文件、写文件、调用工具、LLM 推理。

可视化需求:

• 执行时间线(Execution Timeline):把 Agent 的行为展开在时间轴上。什么时候开始、什么时候结束、中间有哪些阶段?每个阶段耗时多少?
• 动作流(Action Flow):Agent 的一连串动作构成了一个有向图。”读文件 A → 调用 LLM → 写文件 B → 运行测试 → 读测试输出 → 再次调用 LLM → 写文件 C”。这个图能让你看到 Agent 的工作”形状”–是线性推进,还是反复迭代,还是来回跳转?
• 实时状态(Live Status):如果 Agent 还在运行,你现在能看到什么?当前在做什么?进度大概多少?有没有卡住?

为什么重要:Run 层的可视化是最基础的需求,但也是最容易被做错的。最常见的错误是把 Run 层的可视化等同于”把日志展示出来”–日志是给人读的文本,可视化是让模式浮现的图形。35 分钟的执行可能产生几千行日志,但可视化后可能只是一个”读-写-测试-修复”的四步循环图,让你一秒就理解了 Agent 的行为模式。

2.3 Observe 层:Agent 的行为是否合规?

Observe 层是 Harness 的核心–它监控 Agent 的行为,检查是否违反约束,记录 Evidence(证据)。

可视化需求:

• 约束状态面板(Constraint Status Panel):所有约束的当前状态–通过、违反、警告、不可评估。
• 违规详情(Violation Details):如果某个约束被违反了,具体是什么时候、在什么上下文中、违反的程度如何?
• Evidence 浏览器(Evidence Browser):Agent 在执行过程中留下了哪些”证据”?比如代码变更的 diff、测试的输出、性能指标的变化。这些 Evidence 是 Review 的基础。
• 熵变化曲线(Entropy Curve):这是一个更高级的可视化–追踪 Agent 行为的”可预测性”。如果 Agent 突然开始做意料之外的事情(熵增加),这条曲线会上升,给你一个早期预警。

为什么重要:Observe 层将 Harness 从一个”黑盒执行器”变成一个”可审计的监督者”。没有这层可视化,你只能看到”Agent 完成了任务”–但你不知道它是否按规矩来的。这就像你雇了一个承包商翻修房子,他告诉你”搞定了”,但你不检查他有没有偷工减料、有没有用合同规定以外的材料。

2.4 Govern 层:系统是否健康?

Govern 层是最顶层–它关注的是 Harness 系统本身的健康度、Agent 的长期表现趋势、以及跨任务的治理策略。

可视化需求:

• 治理仪表盘(Governance Dashboard):跨多个任务的聚合视图。过去一周,Agent 完成了多少任务?成功率多少?平均耗时多少?约束违反率多少?
• Agent 行为模式(Agent Behavioral Patterns):Agent 是否表现出某些稳定的”性格特征”?比如它是否总是倾向于过度工程化?是否总是在某个类型的任务上失败?
• Spec 演化追踪(Spec Evolution Tracking):Harness Spec 本身也在演化。上个月你加了一条新约束,这条约束的实际效果如何?它是否减少了某种类型的错误?

为什么重要:Govern 层把 Harness 从一个”单次执行工具”提升到一个”持续改进系统”。没有这层可视化,你只能对每次执行做反应(出了问题就修),而无法做到预防(看到趋势就提前调整)。

2.5 四层之间的关系

这四层不是孤立的,它们构成了一个嵌套循环:

Govern ──────────────────────────────────────┐
  │                                            │
  └─► Observe ──────────────────────────────┐ │
       │                                     │ │
       └─► Run ───────────────────────────┐ │ │
            │                              │ │ │
            └─► Context ──► (Agent Acts) ──┘ │ │
                                            │ │
            ◄──────── Evidence ──────────────┘ │
                                            │ │
            ◄──────── Metrics ────────────────┘ │

• Context 为 Run 提供输入
• Run 产生 Evidence 给 Observe
• Observe 聚合成 Metrics 给 Govern
• Govern 反过来调整 Context 和 Spec

可视化也需要反映这种嵌套关系–你需要能在 Govern 层”下钻”到某次具体执行的 Observe 层,再下钻到某个动作的 Run 层,再看当时的 Context 层。这不是四个独立的 dashboard,而是一个可钻取的统一视图。

---

第三章:从 Spec 到 Harness 可视化:工具链的演化

在讨论具体的可视化方案之前,让我们先拉远视角,看看我们是怎么走到这一步的。AI 工程中”约束 Agent 行为”这个需求,并不是 Harness 诞生后才有的–它有一条清晰的工具链演化路径。理解这条路径,能帮我们看清 Harness 可视化为什么是必然的下一步,而不是一时的时髦。

阶段一:Prompt Engineering 时代(2023 年 - 2024 年)

特征:约束以自然语言写在 Prompt 里,没有”Spec”的概念,没有结构化,没有验证。

在 AI Agent 的”蛮荒时代”,我们是这样给 Agent 加约束的:把所有规则写成一大段自然语言,塞进 system prompt。比如:

你是一个高级 Unity 工程师。请遵循以下规则:
1. 所有 MonoBehaviour 方法不得超过 50 行
2. 变量名使用 camelCase,常量使用 PascalCase
3. 不要使用 Resources.Load,统一使用 Addressables
4. 所有 UI 操作必须切主线程
5. 不要修改 Assets/Scenes/ 目录下的 Scene 文件
...(还有 20 条)

注意:这个阶段没有”Spec”的概念。人们只是把约束随手写进 Prompt,和任务指令混在一起。约束只是 Prompt Engineering 的一部分,而不是一个独立的概念。

问题:Agent 对这些约束的遵守率完全取决于 LLM 的”心情”。研究发现,当约束超过 7-10 条时,LLM 对后面约束的遵守率会急剧下降–这不是模型能力的问题,而是注意力稀释的必然结果。你的第 15 条约束,Agent 大概率直接忽略。

验证方式:人工 review 代码。是的,纯手工。你让 Agent 写完代码,然后像 review 人类同事的 PR 一样逐行检查。这耗费大量时间,而且–讽刺的是–很多团队发现 review AI 代码比 review 人类代码更累,因为你对 AI 的”习惯”一无所知,你不知道哪些地方可能藏着坑。

类比:这就像给一个新员工发了一本 50 页的员工手册,然后让他在没有任何监督的情况下工作。你只能在他做完之后检查结果。如果员工忽略了手册的第 37 页(“所有资源加载必须走 Addressables 管线”),你可能在 code review 中发现,也可能在玩家反馈”进背包卡死了”时才发现。

阶段二:Prompt + Linter(2023 年末 - 2024 年)

特征:自然语言 Prompt + 自动化静态检查工具。

工程师们很快意识到:不能把所有约束都交给 LLM 的”自觉性”。解决方案是引入 Linter–自动化的静态检查工具,在 Agent 写完代码后立刻验证。

典型的工作流变成:

Agent 写代码 → Linter 检查 → 发现问题 → Agent 修复 → 再次 Linter → 通过 → 人工 review

工具链:

• IDE Linter(C#/Unity):检查代码风格、命名规范、未使用引用
• Roslyn Analyzer:检查 C# 编码规范和常见反模式
• Semgrep:检查安全模式(如硬编码密钥、不安全的序列化)
• 自定义规则:团队用 YAML 定义的约束,如”不允许 FindObjectOfType“、”必须使用 [SerializeField] 而非 public 字段”

进步:Linter 把一部分约束从”靠自觉”变成了”靠机器”。Agent 可以忽略 system prompt 的第 15 条,但如果第 15 条被编码成了 Linter 规则,那它过不了 Linter 就交不了差。

局限:Linter 只能检查静态模式–代码的文本特征。它无法检查运行时行为:

• “函数执行时间不超过 2 帧” → Linter 无法验证
• “Prefab 引用链完整性” → Linter 无法验证
• “没有引入不必要的 Package” → Linter 只能做粗略检查

更重要的是,Linter 的输出是一堆文本报告。20 条规则、15 个文件,Linter 输出可能有上百行。你仍然缺乏全局视图–哪些规则经常被违反?哪些文件是重灾区?Agent 的行为是否在改善?

阶段三:Spec 驱动开发(2025 年)

特征:”Spec”作为正式概念被提出,约束从 Prompt 中独立出来,形成结构化的规范文件。

2025 年,随着 AI Agent 能力的飞跃和工程化需求的爆发,Spec-Driven Development(SDD) 作为一个独立概念正式出现。人们意识到:约束不应该被埋在 Prompt 的某个角落里,而应该被提取出来,成为一份独立的、结构化的、可版本化的规范文件。

“Spec”和”Prompt”的本质区别:

	Prompt	Spec
目的	驱动 LLM 生成回答	定义 Agent 的行为边界
结构	自然语言段落	结构化字段(约束、上下文、验证规则)
版本管理	很少	可 git 追踪、可 diff
验证	无	可被 Linter/CI/Monitor 自动验证
复用	任务级(每次任务重写)	项目级(一份 Spec 适用于多个任务)

Spec 的出现让约束验证进入了新阶段:

• Spec + Linter:约束不再只是 Prompt 里的自然语言,而是被编码为 Linter 规则。Spec 是”法律条文”,Linter 是”执法工具”。
• Spec + CI:约束验证被搬到 CI 流水线里。Agent 提交代码后,CI 根据 Spec 中定义的约束自动运行单元测试、集成测试、类型检查、安全扫描。

CI 工作流:

Agent 提交代码 → CI Pipeline 触发 →
  Stage 1: Lint(基于 Spec 规则)→
  Stage 2: Type Check →
  Stage 3: Unit Test →
  Stage 4: Integration Test →
  Stage 5: Security Scan →
  全部通过 → ✓

进步:CI 把约束验证自动化和流程化了。Agent 不能再”偷偷”提交不合规的代码–CI 会拦住它。而且 CI 的结果是结构化的–每个 stage 通过/失败,可以聚合、追踪。

局限:CI 解决了”代码是否正确”的问题,但没有解决”过程是否正确”的问题:

• Agent 在完成任务的 35 分钟里,经历了多少次 CI 失败和重试?
• Agent 是否做了大量无关的修改,只是碰巧通过了 CI?
• CI 只能检查最终产出,无法监控中间过程

可视化的萌芽:CI 平台(GitHub Actions、GitLab CI)开始提供 pipeline 可视化–你可以看到每个 stage 的状态、耗时、日志。但这个可视化是以 pipeline 为中心的,不是以 Agent 为中心的。你看到的是”Stage 3 失败了”,而不是”Agent 在第 12 分钟做了一个导致 Stage 3 失败的决策”。

阶段四:Harness Engineering(2025 年末 - 2026 年初)

特征:”Harness”概念正式提出,从单纯的 Spec 验证跃升为全链路的行为监控框架。

2025 年末,人们开始意识到一个关键区别:AI Agent 不是普通代码的提交者,它是一个自主决策的执行者。对普通开发者,Spec + CI 足够了,因为你可以假设开发者”理解自己在做什么”。对 AI Agent,你不能做这个假设–你需要监控它的决策过程。

于是,Harness Engineering 作为一个独立概念被正式提出。Harness 不只是 Spec + CI 的简单叠加,而是一个完整的执行框架,包含:

• Spec:约束定义层
• Runtime:Agent 执行环境
• Monitor:运行时行为追踪–记录 Agent 的每一个动作(读什么文件、调用什么工具、传了什么参数、LLM 返回了什么)
• Gate:质量门控–基于 Spec 中的约束对最终产出做 PASS/FAIL/CONDITIONAL 判断

Harness 在 CI 的基础上增加了运行时监控:

• 行为追踪(Behavioral Tracing):Agent 的每一步操作被完整记录
• 约束运行时检查(Runtime Constraint Checking):不只是检查最终代码,而是在 Agent 执行过程中实时检查约束。”Agent 正在尝试删除 Assets/Scenes/MainMenu.unity–这条操作违反了 Spec 第 5 条”。
• Evidence 收集(Evidence Collection):Agent 的每一个决策都被记录为 Evidence,供后续 Review 使用。

工具链变成:

Structured Spec(YAML/JSON) → Agent 启动 →
  Harness Monitor 开始记录 →
  Agent 执行(每个动作被追踪)→
  运行时约束检查(实时拦截违规)→
  Agent 完成 → Gate 质量门控 →
  Evidence 汇总 → Review

进步:Harness 把”约束”从事后检查提升到了全链路管控–从 Spec 定义到执行监控再到质量门控,形成闭环。这就像是给承包商装了摄像头–你可以实时看到他在做什么,而不仅仅是验收时检查结果。

局限:Harness Monitor 产生了海量数据。一次 35 分钟的执行可能产生数千条 trace 记录、数十个 constraint check、几百个 evidence。这些数据以 JSON/text 的形式存在,人几乎不可能从中提取有意义的信息。

你有了数据,但你没有洞察。

这就是可视化成为刚需的时刻。

阶段五:Harness 可视化(2026 年)

特征:将 Harness 产生的数据转化为人类可理解的可视化–Harness 可视化作为独立课题被正式提出。

2026 年,Harness 可视化不再是某个工具的附属功能,而是被作为一个独立的工程课题来对待。它的核心任务是把 Harness 产生的非结构化/半结构化数据,转化为工程师可以快速理解和行动的视觉形式。

这不仅仅是”画图表”。Harness 可视化需要解决几个独特挑战:

1. 时间维度:AI Agent 的执行是时间序列数据,需要时间线可视化
2. 因果维度:Agent 的动作之间存在因果关系(因为读了文件 A,所以修改了文件 B),需要因果图可视化
3. 约束维度:需要在同一个视图中展示约束的状态和 Agent 的行为
4. 层级维度:不同角色(开发者、Review、管理者)需要不同粒度的视图

工具链演化时间线总结

阶段	时间段	约束形式	验证方式	验证时机	可视化程度	核心局限
一:Prompt Engineering	2023-2024	自然语言 Prompt	人工 Review	事后	无	LLM 遵守率低,人工成本高
二:Prompt + Linter	2023末-2024	NL + 静态规则	Linter 自动检查	写完即检	文本报告	只能检查静态模式
三:Spec 驱动开发	2025	结构化 Spec	Spec + Linter + CI	提交后	Pipeline 状态图	只能检查最终产出
四:Harness Engineering	2025末-2026初	Harness 框架(Spec+Runtime+Monitor+Gate)	运行时追踪 + Gate	执行中+事后	原始数据(JSON)	数据过载,缺乏洞察
五:Harness 可视化	2026	Harness + 可视化层	全链路可视化	实时 + 事后	多层可视化架构	仍在演化中

一条清晰的线索:约束的定义从模糊到精确(Prompt → Linter → 结构化 Spec → Harness 框架),验证的时机从事后到实时(Review → CI → Runtime Monitor),但可视化一直滞后–直到 2026 年阶段五才追上来。Spec 在 2025 年正式提出,让约束从”随手的 Prompt”变成了”可管理的规范”;Harness 在 2025 年末被提出,让约束验证从”检查结果”变成了”监控全链路”;而 Harness 可视化在 2026 年的出现,标志着 AI 工程工具链走向成熟:我们终于有了和约束粒度匹配的观察工具。

---

第四章:现有方案的可视化缺口

在讨论理想方案之前,让我们先看看现有的工具有哪些可视化能力,以及它们在哪里卡壳。

4.1 IDE 可视化

现状:Cursor、Windsurf、Copilot 等 AI 编码工具在 IDE 中提供了一定程度的可视化–diff 预览、inline suggestion、chat history。

缺口:

• 微观视角陷阱:IDE 可视化天然聚焦于”当前文件”和”当前编辑”。但 AI Agent 的工作范围往往横跨多个文件、多个目录。你在 IDE 中看到的只是冰山一角。
• 缺乏时间维度:IDE 展示的是”当前状态”,不是”变化过程”。你看到文件被修改了,但看不到修改之前 Agent 经历了什么–它试了几个方案?为什么选了当前这个?
• 无约束视图:IDE 不知道 Harness Spec 的存在。Agent 可能正在违反一条约束,但 IDE 不会给你任何提示。

4.2 CI/CD 可视化

现状:GitHub Actions、GitLab CI、Jenkins 等 CI 平台提供了 pipeline 可视化–stage 状态、耗时、日志。

缺口:

• Pipeline-centric,不是 Agent-centric:CI 可视化以 pipeline 为中心组织信息。”Stage 2 失败了”是 CI 的语言,不是 Agent 的语言。你需要的不是”Stage 2 失败了”,而是”Agent 在第 8 分钟做了一个导致测试失败的修改”。
• 缺乏因果链:CI 的每个 stage 是独立运行的。Stage 3 的失败可能和 Stage 1 的某个 warning 相关,但 CI 不会帮你建立这种关联。
• 最终产出偏见:CI 天然关注”最终结果是否正确”。但 Harness 需要关注”过程是否正确”–即使最终结果碰巧正确,如果过程有问题(比如 Agent 尝试了危险操作后才回滚),你也需要知道。

4.3 Code Review 可视化

现状:GitHub PR、GitLab MR 提供了 diff 可视化、comment 线程、review 状态。

缺口:

• 静态快照:PR diff 是代码变更的静态快照。它告诉你”什么变了”,但不告诉你”为什么变”和”怎么变的”。AI Agent 的修改理由往往深埋在它的推理过程中,但 PR 界面无法呈现这些推理。
• 缺乏行为上下文:Review 看到的是代码变更,不是 Agent 的行为。Agent 可能尝试了 5 种方案,最终选择了第 5 种。前 4 种尝试的信息(对理解第 5 种方案为什么是这样)在 PR 中完全丢失。
• Review 负担:AI Agent 可能一次修改 30 个文件、产生 2000 行 diff。对 Reviewer 来说,这已经超出了人类有效 review 的范围(通常认为 200-400 行 diff 是 review 的有效上限)。没有可视化辅助,Review 变成了形式主义。

4.4 Chat UI 可视化

现状:ChatGPT、Claude 的对话界面是一种”线性可视化”–把 Agent 的行为展现在一个线性的对话流中。

缺口:

• 线性叙事的局限:对话 UI 是线性的–消息 1、消息 2、消息 3……但 Agent 的行为不是线性的。它可能并行做了几件事,或者在某个决策点回退了。线性 UI 无法表达这种非线性结构。
• 信息密度低:对话 UI 的信息密度很低。35 分钟的执行可能产生几百条消息,其中大部分是中间过程。你需要的不是逐条阅读这些消息,而是看到高层摘要 + 下钻能力。
• 缺乏聚合:对话 UI 没有聚合视图。你无法看到”过去 10 次执行中,约束 X 的违反率是多少”。

4.5 缺口总结

工具类型	视角	时间维度	因果维度	约束可见性	聚合能力
IDE	文件级	无	无	无	无
CI/CD	Pipeline 级	Stage 级	无	间接	Pipeline 级
Code Review	Diff 级	快照	无	无	PR 级
Chat UI	消息级	线性	无	无	无
需要的	Agent 级	连续	有	一等公民	跨任务

每个现有工具都在自己的领域做对了什么,但没有一个覆盖了 Harness 可视化的全部需求。我们需要一个新的可视化层–一个以 Agent 行为为中心的、跨越时间和因果维度的、把约束作为一等公民的可视化系统。

---

第五章:理想模型:三层可视化架构

基于以上分析,我提出一个 Harness 可视化的理想模型:三层架构。每一层解决不同的问题,服务不同的角色,同时层与层之间可以自由钻取。

5.1 第一层:执行时间线(Execution Timeline)

服务对象:开发者、调试者

核心问题:”Agent 做了什么?什么时候做的?花了多长时间?”

视觉形式:横向时间线,类似 Git 提交历史的时间线视图,但更丰富:

0min        5min        10min       15min       20min       25min       30min       35min
├───────────┼───────────┼───────────┼───────────┼───────────┼───────────┼───────────┤
│ 读取文件   │ 修改代码   │ 运行测试   │ 修复错误   │ 再次测试   │ 修改文档   │ 最终检查   │
│ (12 files) │ (5 files)  │ ❌ 3失败   │ (2 files)  │ ✅ 全通过  │ (1 file)   │ ✅         │
│ 🔵 低风险   │ 🟡 中风险   │ 🔴 高风险  │ 🟡 中风险   │ 🟢 低风险   │ 🟢 低风险   │ 🟢 低风险   │

关键元素:

• 阶段划分:Agent 的行为被自动分组为语义化的阶段–”调研”、”实现”、”测试”、”修复”、”收尾”。不是按时间等分,而是按语义划分。
• 风险色标:每个阶段根据约束检查的结果标记风险等级。绿色 = 无约束违反,黄色 = 软约束警告,红色 = 硬约束违反或接近违反。
• 耗时热力:每个阶段的耗时用色温表示。如果某个阶段异常耗时(比如”修复错误”花了 20 分钟),它会以更深的颜色高亮。
• 动作计数:每个阶段内的动作数量(读/写/调用工具的次数)。这能帮你看清 Agent 的工作量分布。

交互方式:点击任意阶段,下钻到该阶段内的详细动作列表。再点击某个动作,看到该动作的完整上下文–当时的 Agent prompt、LLM response、文件状态。

5.2 第二层:影响图谱(Impact Graph)

服务对象:Reviewer、架构师

核心问题:”Agent 的修改影响了哪些东西?这些影响之间有什么关系?”

视觉形式:有向无环图(DAG)或力导向图。节点是代码实体(文件、函数、类、模块),边是依赖/影响关系。

               ┌───────────────────┐
               │ InventoryUI.cs    │ ← 修改(核心变更)
               └──┬───────┬────────┘
                  │       │
         ┌────────┘       └────────┐
         ▼                         ▼
┌──────────────────┐    ┌──────────────────────┐
│ ItemSlot.cs      │    │ InventoryController  │ ← 修改(级联影响)
└──────┬───────────┘    └──────┬───────────────┘
       │                       │
       ▼                       ▼
┌──────────────────┐    ┌──────────────────────┐
│ ItemIcon.prefab  │    │ AddressableLoader.cs │ ← 新增(加载层)
└──────────────────┘    └──────────────────────┘

关键元素:

• 节点着色:按修改类型着色–绿色(新增)、黄色(修改)、红色(删除)、灰色(未修改但被影响)。
• 边标注:依赖类型–”调用”、”导入”、”测试”、”配置”。
• 爆炸半径(Blast Radius):自动计算并高亮”爆炸半径”–Agent 的核心修改影响了多少个下游实体。爆炸半径越大,Reviewer 需要越仔细。
• 约束覆盖:图谱上叠加约束检查结果。如果某个修改违反了约束,对应的节点会显示警告标记。

交互方式:点击节点查看 diff。点击边查看依赖详情。可以切换”代码视图”和”模块视图”–模块视图以目录/模块为单位聚合节点,适合宏观审查。

5.3 第三层:治理仪表盘(Governance Dashboard)

服务对象:Tech Lead、工程管理者

核心问题:”Harness 系统健康吗?Agent 的长期表现如何?”

视觉形式:多面板仪表盘,包含多个图表和指标。

关键面板:

• 任务成功率趋势图:折线图,展示过去 N 天的任务成功率
• 约束违反热力图:以约束为行、以任务为列的矩阵,颜色表示违反程度。一眼看出哪些约束最常被违反。
• 执行时间分布图:直方图,展示任务执行时间的分布。是否有异常值?
• Agent”性格”雷达图:多维度评分–”保守 vs 激进”、”简洁 vs 冗余”、”遵循规范 vs 自作主张”、”快速 vs 谨慎”。
• Spec 效果追踪:每条 Spec 规则的”ROI”–它减少了多少错误,又引入了多少误报。

5.4 三层之间的钻取路径

三层架构的核心价值不仅在于每层的可视化,更在于层间的钻取路径(Drill-down Path):

治理仪表盘:约束违反热力图显示"规则 #7 本周被违反 5 次"
  ↓ 点击"规则 #7"
影响图谱:展示本周 5 次违反涉及的文件和依赖关系
  ↓ 点击某次违反
执行时间线:展示该次执行的完整过程,高亮违反发生的时刻
  ↓ 点击该时刻
原始数据:Agent 当时看到的上下文、做出的推理、执行的动作

这种从宏观到微观的无缝钻取,是 Harness 可视化和传统日志/仪表盘的根本区别。传统方案中,宏观(仪表盘)和微观(日志)是断裂的–你看到仪表盘上有个异常,然后需要手动去翻日志找原因。Harness 可视化要做的,是消除这个断裂。

---

第六章:关键可视化模式

三层架构描述了”骨架”,现在我们来填充”血肉”–具体到每个可视化组件,有哪些经过验证的设计模式可以借鉴。

6.1 约束热力图(Constraint Heatmap)

场景:你定义了 20 条约束,Agent 完成了一次任务。你想一眼看出哪些约束被触发、触发的频率和严重程度。

设计:

• 矩阵热力图。横轴是时间(或执行阶段),纵轴是约束。
• 每个单元格的颜色表示约束在该时间点的状态:绿色(通过)、黄色(警告)、红色(违反)、灰色(未评估)。
• 鼠标悬停显示详情–为什么这条约束在此时被触发。

约束 / 时间    0-5min  5-10min  10-15min  15-20min  20-25min  25-30min  30-35min
────────────────────────────────────────────────────────────────────────────────
禁止删 Prefab    🟢       🟢       🟢        🟢        🟢        🟢        🟢
方法≤50行       🟢       🟡       🟡        🟡        🟢        🟢        🟢
不卡主线程      ─       ─        🟡        🔴        🟡        🟢        🟢
不修改 Resources/ 🟢       🟢       🟢        🟢        🟢        🟢        🟢
不引入新 Package  🟢       🟢       🟢        🟢        🟢        🟡        🟡
Addressable 标签同步 ─       ─        ─         ─         ─         🟡        🟢

洞察:从这个热力图你能一眼看出:主线程阻塞在 15-20 分钟区间出现了红色违反(加载逻辑还是同步调用),但在后续修复后变绿。不引入新 Package 在最后阶段出现警告–Agent 引入了新的 Addressables 相关包。这些都是需要 Review 关注的信号。

6.2 决策树回放(Decision Tree Replay)

场景:Agent 在任务执行过程中做出了多个关键决策。你想理解每个决策的推理过程,以及如果做了不同选择会怎样。

设计:

类似 Git 的分支可视化,但用于 Agent 的决策过程:

开始任务:背包系统 Resources → Addressables 迁移
│
├─ 决策1:先读现有代码 or 先读 Addressables 文档?
│  └─ 选择:先读现有代码 ✅(理由:需要理解当前引用链)
│     │
│     ├─ 决策2:整体迁移 or 分批迁移?
│     │  ├─ 方案A:整体迁移(风险高,一次到位)
│     │  └─ 方案B:按物品类型分批迁移(风险低,逐步验证) ✅ 已选
│     │     │
│     │     ├─ 决策3:先迁哪类资源?
│     │     │  ├─ 武器/装备图标(高频引用)
│     │     │  └─ 消耗品/材料图标(低频引用) ✅ 已选
│     │     │     │
│     │     │     └─ 决策4:加载策略
│     │     │        ├─ 预加载全部到内存
│     │     │        └─ 按需异步加载 ✅ 已选 ⚠️(可能出现 UI 闪烁)

洞察:决策树回放让你看到 Agent 在每个岔路口的选择和理由。特别是标记了 ⚠️ 的决策–”先迁移再补测试”–这是一个有争议的选择。如果你不赞同,你可以在 Spec 中加入约束:”所有迁移任务必须先编写或更新测试”。

这种可视化的价值不仅在于事后审计,更在于Spec 演化–你通过观察 Agent 的决策模式,不断改进你的约束定义。

6.3 熵变化曲线(Entropy Curve)

场景:你想知道 Agent 的行为是否”可预测”–它是在按照预期的路径推进,还是开始”乱来”?

设计:折线图,Y 轴是”行为熵”(Behavioral Entropy),X 轴是时间。

• 低熵:Agent 按照可预测的模式工作–读文件、修改文件、运行测试。行为高度结构化。
• 高熵:Agent 开始做意料之外的事情–频繁切换目标、反复修改同一个文件、调用了不常用的工具。

熵值
▲
│     ╱╲
│    ╱  ╲        ╱╲╱╲
│   ╱    ╲      ╱    ╲
│──╱──────╲────╱──────╲────
│          ╲  ╱        ╲
│           ╲╱          ╲
└─────────────────────────────► 时间
  调研    实现    测试    修复    完成
  (低熵)  (中熵)  (低熵)  (高熵!)  (低熵)

洞察:”修复”阶段出现了高熵–Agent 的行为变得不可预测,反复尝试不同的修复方案。这是一个信号:

1. 积极信号:Agent 遇到了复杂 bug,需要探索多种修复方案。这是正常的。
2. 消极信号:Agent 陷入了”反复试错”的循环,缺乏系统性的调试策略。这时候可能需要人工介入,或者改进 Spec 中的调试指引。

关键不在于熵高或低,而在于熵是否在你的预期之内。如果”修复”阶段通常是低熵的,但这次突然高熵了,那说明这次的问题可能比以往更复杂。

6.4 上下文地图(Context Map)

场景:你想知道 Agent 在做决策时”看到了”多大的世界–它的上下文窗口中包含了哪些信息,又忽略了哪些。

设计:类似地理地图的”探索迷雾”可视化–Agent 读过的文件/区域是明亮的,没读过的是灰暗的(“迷雾”)。

代码库地图(已探索区域)

┌── Assets/Scripts/ ──────────────────────┐
│  ├── Inventory/                         │
│  │   ├── InventoryUI.cs       ✅ 已读    │
│  │   ├── ItemSlot.cs          ✅ 已读    │
│  │   ├── ItemDatabase.cs      ✅ 已读    │
│  │   └── InventoryConfig.cs   ░░ 未读    │
│  ├── UI/                                │
│  │   ├── UIPanelBase.cs       ✅ 已读    │
│  │   ├── UIDragHandler.cs     ░░ 未读    │  ← 可能遇漏!
│  │   └── UIFadeAnimation.cs   ░░ 未读    │
│  ├── Addressables/                      │
│  │   └── (全部 ░░ 未读)                   │
│  └── Resources/                         │
│      └── (已标记为废弃)          🔒 禁改    │
├── Assets/Prefabs/ ──────────────────────┐
│  ├── ItemIcon.prefab           ✅ 已读    │
│  ├── InventoryPanel.prefab     ░░ 未读    │  ← Prefab 引用可能断裂!
│  └── ItemTooltip.prefab        ░░ 未读    │
└────────────────────────────────────────┘
探索率:35%(已读 5/14 文件)

洞察:Agent 只读了 UI/UIPanelBase.cs 但没有读 UI/UIDragHandler.cs。如果 InventoryUI 继承了 UIPanelBase 并依赖 UIDragHandler 处理拖拽排序,而 Agent 修改了物品槽位的初始化逻辑,那拖拽排序可能在修改后失效–但 Agent 不知道,因为它没读过这个文件。

上下文地图的另一个用途是优化 Agent 的上下文策略。如果你发现 Agent 在类似任务中总是忽略某些文件,你可以在 Spec 中明确指定需要读取的文件列表,或者改进 Agent 的文件发现策略。

6.5 Gate 决策流(Gate Decision Flow)

场景:Harness 中的 Review Gate 对 Agent 的产出做了审查。你想看到 Gate 的完整决策过程。

设计:流程图 + 状态标注。

任务完成
  │
  ▼
┌─────────────────┐
│ Gate 1: Harness  │
│ Monitor          │
│ "发生了什么?"     │
└───────┬─────────┘
        │
   ┌────┴────┐
   │ 评估结果  │
   ├─────────┤
   │ ✅ 修改5个│
   │    脚本  │
   │ ✅ Play  │
   │    Mode  │
   │    通过  │
   │ ⚠️ 1个新 │
   │    Package│
   └────┬────┘
        │ 通过 ▼
┌─────────────────┐
│ Gate 2: Entrix   │
│ Fitness          │
│ "应该是什么?"     │
└───────┬─────────┘
        │
   ┌────┴────┐
   │ 评估结果  │
   ├─────────┤
   │ ✅ 符合架构│
   │    设计  │
   │ ✅ 主线程 │
   │    无卡顿 │
   │ ⚠️ 迁移不 │
   │    完整  │
   └────┬────┘
        │ 条件通过 ▼
┌─────────────────┐
│ Gate 3: Gate     │
│ Specialist       │
│ "能否推进?"      │
└───────┬─────────┘
        │
   ┌────┴────┐
   │ 最终决策  │
   ├─────────┤
   │ ✅ 允许合并│
   │ 📝 需补充 │
   │    迁移文档│
   └─────────┘

洞察:Gate 决策流让你看到多层审查的完整过程–每一层关注什么、发现了什么、做出了什么判断。特别重要的是条件通过(Conditional Pass)的标注–Gate 2 认为迁移不完整,但不是致命问题,所以条件通过并传递给 Gate 3 做最终判断。这种分层决策的可视化,比一个简单的”通过/不通过”提供了丰富得多的信息。

6.6 六种模式的关系

这六种可视化模式不是孤立的–它们覆盖了 Harness 四层循环的不同层面:

可视化模式	主要服务层	核心问题	时间尺度
约束热力图	Observe	哪些约束被触发?	单次执行
决策树回放	Run	Agent 为什么做了这个选择?	单次执行
熵变化曲线	Run + Observe	Agent 是否按预期行事?	单次执行
上下文地图	Context	Agent 看到了什么?	单次执行
Gate 决策流	Govern	审查结论是什么?	单次执行
治理仪表盘	Govern	长期趋势如何?	跨任务

理想的可视化系统应该同时提供这些模式,并允许用户在它们之间自由切换和钻取。

---

第七章:Routa 的 Harness Monitor 实践分析

理论讲够了,让我们看一个真实的案例。Routa 是一个 workspace-first multi-agent coordination platform,它的 Harness Monitor 设计提供了很多有价值的实践经验。

7.1 Routa 的核心架构:四层 Loop + Review Gate

Routa 的核心执行模型是一个四层循环,和我们前面讨论的四层模型高度对应。在理解架构之前,先记住 Routa 的三个核心角色:

• ROUTA 负责协调(coordinates)–它是编排者,决定谁做什么、什么时候做
• CRAFTER 负责实现(implements)–它是执行者,真正动手写代码、改文件、跑测试
• GATE 负责验证(verifies)–它是守卫者,检查 CRAFTER 的产出是否符合规范

这三个角色通过 Kanban 协调总线串联起来:

Kanban(协调总线)
  │
  ├─ Backlog Refiner(需求精炼)
  │    └─ 分析需求,拆分为可执行的 TODO
  │
  ├─ Todo Orchestrator(任务编排)
  │    └─ 排列优先级,分配给 specialist
  │
  ├─ Dev Crafter(开发执行)
  │    └─ CRAFTER 主导:代码编写、修改、测试
  │
  ├─ Review Guard(审查守卫)
  │    └─ GATE 主导:Harness Monitor + 约束验证
  │
  └─ Done Reporter(完成报告)
       └─ 汇总 Evidence,生成报告

ROUTA 贯穿整个 Kanban 流程,在每个泳道之间协调任务流转;CRAFTER 在 Dev Crafter 泳道中全力输出;GATE 在 Review Guard 泳道中严格把关。三者之间的配合默契度,直接决定了 Harness 的有效性。

关键设计决策:Routa 把 Kanban 作为协调总线–每个泳道(swimlane)背后不是一个简单的任务队列,而是一个完整的 specialist prompt。这意味着:

• 每个 specialist 有自己的上下文、约束和能力
• 任务在泳道之间流转时,会经过转换(不仅仅是状态变更)
• Kanban 本身就是一个可视化协调层–你可以看到任务在哪个阶段、谁在处理、是否有阻塞

7.2 Review Gate 的三层设计

Routa 的 Review Gate 是它最精巧的设计之一。三层审查,每层关注不同的问题:

第一层:Harness Monitor(“发生了什么?”)

这是事实层。它记录和回答的是客观事实:

• 修改了哪些文件?每个文件的变更摘要
• 运行了哪些命令?每个命令的输出
• 调用了哪些外部 API?参数和响应是什么
• 执行耗时和资源消耗

第二层:Entrix Fitness(“应该是什么?”)

这是规范层。它把 Harness Monitor 收集的事实和预定义的 Spec 进行比对:

• 变更范围是否符合预期？（Spec 说改 3 个脚本，实际改了 5 个）
• 代码风格是否符合规范？（和 Lint 规则比对）
• 安全约束是否满足？（检查硬编码密钥、不安全的序列化、未授权的资源访问）
• 性能约束是否满足？（检查是否有主线程阻塞、N+1 资源加载、不必要的 Instantiate）

第三层:Gate Specialist(“能否推进?”)

这是决策层。综合前两层的信息,做出最终判断:

• 通过(PASS):质量达标,可以推进到下一阶段
• 条件通过(CONDITIONAL PASS):有小问题但非致命,记录待办事项后推进
• 回退(REWORK):需要 Crafter 修复后重新提交
• 终止(ABORT):严重问题,任务需要人工介入

为什么三层? 因为每层需要不同的”心智模型”。Harness Monitor 需要”观察者”的客观性,Entrix Fitness 需要”审计员”的严谨性,Gate Specialist 需要”决策者”的判断力。把这些职责混在一个 prompt 里,效果会大打折扣–模型(LLM)会在不同角色之间”串台”。

7.3 Routa 做对了什么

1 Trace 是一等公民

Routa 把 Trace(行为追踪)作为系统的一等数据类型。每一条 trace 都有:

• trace_id:唯一标识
• span_id:在一个 trace 内的子操作标识
• parent_span_id:父操作的标识(构成树结构)
• timestamp:时间戳
• action_type:动作类型(read/write/execute/think)
• input/output:输入输出
• constraint_checks:该动作触发的约束检查

这种结构化的 trace 数据,是所有可视化的基础。没有它,Harness 可视化就是无源之水。

2 Evidence-based Review

Routa 的 Review 不是基于代码 diff 的(传统方式),而是基于 Evidence 的。每次 Review Guard 审查一个任务,它看到的不仅仅是代码变更,而是:

• 任务上下文(需求是什么、为什么要做)
• 执行 trace(Crafter 做了什么、为什么这么做)
• 约束检查结果(哪些约束通过了、哪些违反了)
• Evidence 列表(每个关键决策的”证据”)

这就像法庭审判–不是只看结果(代码),而是看证据链(trace + constraint checks + reasoning)。

3 Kanban 作为协调总线

Kanban 不仅仅是任务管理工具,它是协调的可视化层。当 Crafter 完成一个任务并提交 Review 时:

1. 任务卡片从 “Dev Crafter” 泳道移到 “Review Guard” 泳道
2. 卡片上显示执行摘要(修改文件数、测试结果、风险等级)
3. Review Guard 处理时,卡片状态更新为 “审查中”
4. 审查完成后,卡片要么移到 “Done Reporter”,要么退回 “Dev Crafter”

整个团队可以实时看到任务的状态–不是通过看日志,而是通过看 Kanban 板。这是一种零成本的协作可视化。

7.4 可视化空间:Routa 还可以做什么

尽管 Routa 的 Harness Monitor 设计已经很成熟,但在可视化方面仍有提升空间:

缺失一:跨任务聚合

Routa 的 Kanban 可视化是单次任务维度的。你看到的是某个任务在泳道之间的流转。但你很难看到:

• 过去一周,Dev Crafter 泳道的平均停留时间是多少?
• 哪些类型的任务最容易被 Review Guard 退回?
• Gate Specialist 的”条件通过”率是多少?这些条件通过后来都修复了吗?

这需要治理仪表盘–也就是我们三层架构中的第三层。

缺失二:决策树可视化

Routa 的 trace 数据足以支持决策树可视化,但目前的 UI 只展示了线性 trace 列表。如果把 trace 中的 parent_span_id 关系可视化为树状结构,Reviewer 能更直观地理解 Agent 的决策路径。

缺失三:上下文地图

Review Guard 在审查时会读取相关文件,但它”看到了什么”这个信息没有被可视化。如果能看到 Review Guard 的上下文地图,就能判断它的审查是否充分–是否遗漏了某些关键文件。

7.5 对 Unity 工程的启示

Routa 的实践给我们几个关键启示:

1. Trace 先行:在做可视化之前,先确保你有结构化的 trace 数据。可视化是 trace 数据的消费端,如果 trace 数据不够丰富或不够结构化,可视化就是空中楼阁。

2. 分层 Review:不要把所有审查逻辑塞进一个 prompt。三层 Review Gate 的设计(事实 → 规范 → 决策)是一个值得借鉴的模式。

3. Kanban 即可视化:不需要一开始就做复杂的三层可视化架构。Kanban 本身就是一个简单但有效的可视化起点–它让任务的流转变得可见。

4. Evidence 驱动:Review 应该基于 Evidence(结构化的执行证据),而不是基于 diff(代码文本差异)。这个范式转变对可视化设计有深远影响–你需要展示的不是”代码变了什么”,而是”Agent 做了什么,为什么这么做,结果是什么”。

---

第八章:从概念到落地

谈了这么多理论,如果明天就要开始做 Harness 可视化,应该怎么做?我建议一个三阶段策略:MVP → 进阶 → 工程化。

8.1 MVP:让 Agent 的行为变得可见(1-2 周)

目标:不追求完美的可视化,先做到”能看到”。

具体行动:

1. Trace 结构化:在 Agent 执行循环中加入 trace 埋点。每个动作记录 {timestamp, action_type, input, output, duration}。这是所有后续可视化的基础。

2. 时间线 MVP:用最简单的形式–一个 Markdown 表格或静态 HTML 页面–展示 Agent 的执行时间线。不需要交互,不需要钻取,只需要按时间顺序列出 Agent 的动作。

   | 时间 | 动作 | 目标 | 结果 | 耗时 |
   |------|------|------|------|------|
   | 0:01 | read | InventoryUI.cs    | 成功       | 0.5s |
   | 0:02 | read | ItemSlot.cs       | 成功       | 0.3s |
   | 3:15 | write| InventoryUI.cs    | 已修改     | 1.2s |
   | 5:30 | execute | Unity Play Mode | 2 failures | 12s  |

3. 约束检查日志:把 Harness Spec 中的约束实现为运行时检查函数,在 Agent 动作后调用,记录检查结果。

4. 执行摘要:在任务完成后,自动生成一段自然语言摘要–”任务耗时 35 分钟,修改了 5 个文件,运行了 3 次测试(2 次失败后修复),引入了 1 个新依赖。”

交付物:一个简单的 HTML 页面,展示时间线 + 约束检查结果 + 执行摘要。

8.2 进阶:加入因果和约束维度(3-4 周)

目标:从”能看到”到”能理解”。

具体行动:

1. 动作因果图:分析 trace 数据中的因果关系–”读文件 A 导致了写文件 B”。用简单的箭头或连线展示这种因果关系。不需要完整的 DAG,只需要最直接的因果链。

2. 约束热力图:把约束检查结果以时间×约束的矩阵形式展示。用 CSS 即可实现颜色编码。

3. 风险评分:根据约束违反的频率和严重程度,给每次执行计算一个风险评分。高风险执行在列表中优先展示。

4. 文件爆炸半径:自动计算一次执行影响了多少文件、多少行代码。爆炸半径大的执行自动标记为”需要详细 Review”。

5. Gate 决策可视化:如果使用了多层 Gate(如 Routa 的三层 Gate),把每层的决策过程可视化–通过、条件通过、回退。

交付物:一个交互式 Web 页面,支持时间线 + 因果图 + 约束热力图,可以从宏观视图钻取到具体动作。

8.3 工程化:构建可持续的可视化系统(持续迭代)

目标:从”能理解”到”能治理”。

具体行动:

1. 治理仪表盘:跨任务聚合指标–成功率、约束违反率、执行时间分布、Agent 行为模式。这是长期价值最高的可视化组件。

2. Spec 演化追踪:记录每条 Spec 规则的修改历史和效果变化。回答”这条规则加入后,相关的约束违反是否减少了?”

3. Agent 性格分析:基于大量执行数据,分析 Agent 的”性格特征”–它倾向于过度工程化还是欠工程化?它是保守的还是激进的?

4. 团队协作视图:不同角色的定制视图–Tech Lead 看治理仪表盘,Reviewer 看影响图谱,DevOps 看资源消耗。

5. 告警系统:基于可视化指标设置告警–”如果某类约束的违反率突然升高,发送通知”。

技术选型建议:

• 数据层:Trace 数据存储在时序数据库(如 ClickHouse、TimescaleDB),约束数据存储在关系数据库
• 可视化层:对于交互式图表,D3.js 或 ECharts;对于仪表盘,Grafana 或自定义 React 组件
• API 层:GraphQL 很适合这种需要灵活钻取的场景–前端可以按需查询不同粒度的数据

工程化注意事项:

• 性能:一次 35 分钟的执行可能产生数千条 trace。可视化层需要支持聚合和采样–不需要每次都展示所有原始数据
• 存储:Trace 数据增长很快。制定数据保留策略–原始 trace 保留 30 天,聚合指标永久保留
• 隐私:Trace 数据可能包含敏感信息(API key、用户数据)。确保可视化系统的访问控制和数据脱敏

---

第九章:未来展望

Harness 可视化还处于早期阶段。让我大胆预测几个方向。

9.1 实时协作审查

未来的 Harness 可视化不会只是”事后查看”,而是支持实时协作审查。当 Agent 正在执行时,多个团队成员可以同时观察其行为,添加评论,甚至在关键时刻介入(暂停 Agent、修改约束、提供指导)。

这就像直播 code review–但不是 review 人写的代码,而是实时观察 AI 的行为并给出反馈。这种模式能极大提高团队对 AI Agent 的信任度,因为”看到了过程”比”看到了结果”更能建立信任。

9.2 Agent-to-Agent 可视化

当多个 Agent 协作时(Multi-Agent 场景),可视化需要覆盖的不只是单个 Agent 的行为,而是 Agent 之间的交互模式:

• Agent A 产出了什么,传递给了 Agent B?
• Agent B 基于 Agent A 的产出做了什么决策?
• 两个 Agent 之间是否存在”乒乓”模式(A 改了 B 又改回去)?
• 协作的整体效率如何?有多少时间花在了 Agent 间的”通信”上?

这对可视化提出了新的挑战–你需要一个多 Agent 拓扑图,展示 Agent 之间的数据流和控制流。

9.3 自适应可视化

不同的人、不同的场景需要不同的可视化。未来系统可能会根据上下文自动调整可视化模式:

• 调试场景:自动切换到决策树回放 + 熵变化曲线
• Review 场景:自动切换到影响图谱 + 约束热力图
• 管理场景:自动切换到治理仪表盘
• 新人 onboarding:自动切换到上下文地图 + 简化的时间线

9.4 可视化驱动的 Spec 优化

最终,可视化不只是”看 Agent 做了什么”,而是驱动 Harness 本身的进化。通过观察可视化,你发现某些约束总是被违反–这说明约束可能定义得不合理,需要调整。你发现 Agent 总是在某个阶段卡住–这说明 Spec 中缺少对该场景的指引。

这是一个正向反馈循环:

Spec 定义 → Agent 执行 → Harness Monitor 记录 → 可视化展示 → 人类洞察 → Spec 优化
     ▲                                                                       │
     └───────────────────────────────────────────────────────────────────────┘

可视化是这个循环的催化剂。没有它,从”执行”到”洞察”这一步只能靠人工翻日志–慢、不可靠、不可扩展。

9.5 从工程走向产品

目前 Harness 可视化主要是工程团队的内部工具。但随着 AI Agent 进入更多非技术场景(设计、营销、法律),Harness 可视化需要变成用户友好的产品–不是只有工程师能看懂的技术仪表盘,而是任何人都能理解的”AI 工作报告”。

想象一下:你是一个产品经理,你让 AI Agent 做了一个竞品分析。Agent 完成后,你看到的不是一堆 JSON trace,而是一个精美的交互式报告–”Agent 分析了 15 个竞品,重点调研了 5 个,发现 3 个关键趋势。以下是详细的分析过程和证据。”这才是 Harness 可视化的终极形态。

---

总结

让我们回到开头的问题:当 AI Agent 跑了 35 分钟,你只看到一个 ✅,你能信任它吗?

答案是:不应该信任,除非你能看到过程。

Harness 可视化要做的,就是把那个 ✅ 背后的 35 分钟展开给你看:

• 执行时间线让你看到 Agent 做了什么、花了多长时间
• 影响图谱让你看到 Agent 的修改影响了什么、范围有多大
• 治理仪表盘让你看到 Harness 系统是否健康、趋势如何
• 约束热力图让你看到哪些规则被触发、Agent 是否在边界内工作
• 决策树回放让你看到 Agent 在每个岔路口的选择和理由
• Gate 决策流让你看到多层审查的完整过程

从工具链演化的角度看,Harness 可视化不是可有可无的 UI 美化,而是 AI 工具链演化的必然终点–我们终于有了和约束粒度匹配的观察工具。

从实践的角度看,Routa 的 Harness Monitor 提供了一个优秀的参考:Trace 作为一等公民、Evidence-based Review、Kanban 作为协调总线–这些设计决策值得每一个构建 Harness 系统的团队学习。

从未来的角度看,Harness 可视化还处于”CLI 时代”(类比软件工程早期的命令行界面)。它需要走向”GUI 时代”–更直观、更交互、更面向非技术用户。而在这个过程中,那些率先投资 Harness 可视化的团队,将在 AI 工程的”可视化鸿沟”中获得先发优势。

记住:你看不见的东西,你无法信任。你无法信任的东西,你无法依赖。你不能依赖的 AI Agent,不如不要。

---

系列阅读:

• TEngine 的工程哲学:为什么 SDD + Harness Engineering 是 AI 编程的最优解(上一篇)
• 本文:Harness 的可见性危机