Better Harness 是我们开源的一套工具，用来检查 Coding Agent 的工作方式，并把有效经验沉淀成可复用的 SKILL。上线以来，我们一直在做一件事：从 Agent 的会话中识别重复出现的工作路径，判断哪些值得进一步沉淀。做起来以后发现，这件事远比“分析会话”复杂。
对于一次软件开发任务来说，Agent 的行为并不是孤立发生的。它从一个需求或者用户故事开始，经过对需求的理解、上下文探索、代码修改和验证，最终才形成一次可以被评审的代码贡献。只看中间的 Session，我们能看到 Agent 做了什么，却很难判断这些行为为什么发生，又有哪些行为最终进入了交付。
因此，我们开始把一次 Agent 的交付理解成一条连续的链路。现在，只需要在项目目录执行：
npx @qoder-ai/better-harness inspector
就可以生成一个本地、只读的 Harness Inspector 页面，把当前项目中的 Agent Session、文件活动和 Commit 放到同一个交互界面里。
GitHub：https://github.com/QoderAI/better-harness
从 Session 到一次完整的交付过程
Harness Inspector 最初只是一个会话调试工具：帮助我们查看 Agent 说了什么、调用了哪些工具，以及修改了哪些文件。但随着 Session、文件活动和 Git 历史逐渐被连接起来，我们发现，值得观察的是一个更完整的问题：
一次软件变更如何从一个意图出发，经过 Agent 的执行，最终形成可以进入工程系统的产出。
Session 只是这条链路的中间部分。
从意图到产出的交付链
我们将一次 Coding Agent 的交付拆成三个连续、但边界不同的部分：
- 意图（Intent）是一次变化的语义化起点，例如用户的需求、Issue、Spec 或者是架构约束等，它们都是 Intent 的具体形态。
- 过程（Process）体现的是这次变化发生的过程，对于 Agent 来说，主要体现为 Session 记录以及其中的搜索、读取、修改和验证
- 产出（Output）则是 Agent 交付到工程系统的最终结果，现阶段最清晰的锚点就是代码 Commit。
所以，Spec、Session 和 Commit 并不是三个并列的抽象概念，它们分别是 Intent、Process 和 Output 在当前软件开发工具链中的可观察对象。Harness Inspector 要做的，是重新建立这条从需求到提交的可追溯的交付链路。
从叙述上看，它是一条连续的交付链；但在真实项目中，它更接近一张证据图。一个 Story 可能经历多个 Session，一段 Session 也可能涉及多个 Commit。
一个简单的示例：从 Spec 到 Commit
我们在 Better Harness 文档页创建了一个只读的公开样本（英文示例数据，不读取本地内容）：https://qoderai.github.io/better-harness/inspector，其中最完整的一条是：
只看 Session，我们只能看到它是一串搜索、读取、修改和测试活动。很难确定它是否一直围绕最初的需求展开，也不知道其中哪些修改最终进入了代码库。单独看 Commit，我们虽然可以看到最终修改了哪些文件，却无法知道 Agent 在提交之前如何理解问题、建立上下文和完成验证。
当 Story、Session 和 Commit 被放到同一个界面后，这次变化才成为一段相对完整的交付过程：Story 说明为什么要修改，Session 展示修改是怎样发生的，Commit 则记录最后留下了什么。
把需求、Agent 行为和代码提交连接起来，让我们第一次能够从整体上检查一次交付。但打开一些包含数百次 Tool Call 的实际 Session 后，另一个问题很快出现了：能够把一次交付连接起来，并不意味着我们已经能够读懂它。
Harness Inspector 如何读懂一次 Agent 交付？
围绕 Better Harness 的 Harness 模型，我们将 Harness Inspector 定义为：
Harness Inspector 是一个面向 Agent 交付过程的本地、只读工作台。它将需求、Agent Session、文件活动和 Commit 放在同一个交互界面中，用来检查一次软件变化为什么发生、怎样发生，以及最终留下了什么。
Harness Inspector 以一次完整交付为中心，围绕从需求到提交的链路，提供了三种观察方式：
- Workbench：查看需求、Session 与 Commit 之间的关系；
- Trace：查看 Session 内部的工作结构；
- Replay：按照事件顺序重新观察任务如何展开。
简单来说，Workbench 看关系，Trace 看结构，Replay 看顺序。三者共同帮助我们还原一个需求如何经过 Agent 的理解、探索、修改和验证，最终形成一次可以被评审的代码提交。
Workbench：连接需求、过程与产出
Workbench 是一次交付的整体视图。在左侧，我们可以看到触发这段 Session 的用户需求，以及执行过程中对目标的补充和调整；中间展示 Agent 在 Session 中发生的搜索、读取、工具调用和 Git 操作；右侧则是当前范围内观察到的 Commit，以及它最终修改的文件。
它的重点在于展示需求、过程和产出之间已经观察到的关系。关系证据不足时，Inspector 会保留为候选或未映射，不会自动拼出一条看起来完整的交付路径。
Trace：把 Session 读成一条工作轨迹
Workbench 帮助我们找到一次交付，Trace 则进一步展开其中的 Session。
进入 Session 后，Trace 会按照 Turn 组织用户输入、中间回复、Tool Call 和文件活动，并通过顶部的时间轴连接事件在时间上的位置。点击某个区段可以跳转到对应调用，连续重复的活动也会被折叠，避免大量相似操作淹没关键变化。
Trace 只处理已经记录下来的行为，将它们重新组织成一条可以阅读的工作轨迹，帮助我们检查 Agent 如何搜索上下文、修改代码和执行验证。
Replay：沿事件顺序回看一次交付
Replay 则沿着已经保留的事件逐步回看任务如何展开。Reviewer 可以依次查看用户输入、Agent 回复、Tool Call、文件和 Commit，观察 Agent 在什么上下文中形成方向，又在什么时候进行了修改和验证。
它只是一次只读的证据回放，不会重新运行工具、恢复工作区或者继续原来的 Session；没有精确时间的内容，也只保留顺序，不会补充没有被记录的过程。Workbench 建立交付上下文，Trace 展开 Session 的工作轨迹，Replay 补充事件发生的顺序。三者共同把一次从需求到提交的 Agent 交付，变成可以逐层进入和检查的过程。
从交付过程中提炼可复用经验
看清一次交付，只是第一步。我们更关心的是：一段 Session 里，哪些做法值得进一步沉淀成 SKILL？
判断标准不在于某个 Tool Call 出现了多少次。Agent 反复读取同一个文件，可能只是没有获得足够的上下文；不断重试一条命令，也可能只是因为执行失败。这些高频动作未必是值得复用的经验，很多时候反而意味着 Agent 走了弯路。
更值得关注的，是那些在相似任务中反复出现，并且最终带来有效产出的工作路径。例如，Agent 如何从需求中划定修改范围，如何找到必要的上下文，又如何完成修改、执行验证并检查最终结果。把这些行为与对应的 Story、Session 和 Commit 对照起来，我们才能分辨哪些只是某次任务中的临时选择，哪些已经形成了相对稳定、可以迁移到其他任务中的做法。
因此，SKILL 自动沉淀的核心工作，是从多次交付中提炼共性，补充适用条件、执行步骤和验证方式。Inspector 首先要做的，就是把每次交付的来龙去脉保留下来，为后续的比较、提炼和验证提供依据。
结语：从看清交付开始
我们最初关注的是 Session，希望从中找到可以复用的工作路径。但 Session 只记录了交付过程的一部分：它能告诉我们 Agent 做了什么，却很难单独说明为什么这样做，以及这些行为最终留下了什么。
Harness Inspector 将需求、Session、文件活动和 Commit 串联起来，让一次 Agent 交付有迹可循。看清任务的来由、执行过程和最终结果，我们才可能从中分辨偶然行为与稳定经验，并把经过验证的做法沉淀成 SKILL。
对 Better Harness 来说，这只是 SKILL 自动演进的起点。
试一下：npx @qoder-ai/better-harness inspector
