跳到主要内容

Harness Inspector

Harness Inspector 是一个本地、只读的交付溯源工作台。它把已声明的产品意图、 Coding Agent 会话、归一化工具活动、Git 提交与仓库路径放在同一视图中，同时不把 相关性包装成作者身份或改进效果的证明。

它用来回答三个有边界的问题：

  1. 当前能看到哪些产品意图、会话、操作、文件与提交？
  2. Inspector 为什么关联两个对象，这份证据有多强？
  3. 哪些信息仍然缺失、只是推断，或不足以支持更强的结论？

Harness Inspector 架构：有界的本地证据经过归一化和带限制的关联，最终渲染为自包含只读报告

工作原理​

  1. 选择有边界的本地窗口。 CLI 会限制 Provider、日期、会话数与提交数； 可选 Feature Tree 用于提供经过评审的 Feature 与 Story 意图。
  2. 独立采集证据。 Session Adapter 读取受支持的本地 Coding Agent 证据；Git 与 Entire Reader 采集提交、文件和 checkpoint 事实。缺失的 Provider 会保持为 显式证据缺口。
  3. 归一化但不扩大隐私边界。 Inspector 只保留通过隐私过滤的提示词、跨 Provider 的动作标签、有界工具细节、已观察时间与仓库相对路径。原始工具 payload、隐藏推理、凭证与用户目录绝对路径不会进入报告。
  4. 建立有证据边界的关联。 经过评审的引用、显式 commit/session metadata、 已观察的 commit call、精确路径重合、时间与保留文本拥有不同的结论权限。 每条关系都携带事实、来源和限制。
  5. 渲染一个自包含报告。 输出是读取投影证据的交互式 HTML 文件；它不会写入 Git metadata、重新运行工具、恢复代码或恢复原生 Coding Agent 会话。

阅读工作台​

  • Capability 按经过评审的 Feature 与 Story 意图限定报告范围。
  • Date 在产品映射缺失或不完整时，仍然保留可见的会话与提交。
  • User prompts / Agent activity / Commits and files 是并列的三条信息轨； 一条信息轨不会静默证明另一条信息轨中的作者身份。
  • Evidence Drawer 解释当前选中关系以及它的限制。
  • Session Trace 展示保留的轮次、归一化动作、已观察时间、空闲区间、文件与筛选。
  • Replay 只沿保留证据前进；没有观察到精确时间的事件会保留 sequence-only 标签。

证据词汇​

标签它能支持什么它不能证明什么
Explicit / direct保留的评审引用或显式 metadata 直接连接两个对象。每个操作或每行改动都参与了最终交付。
Observed same-path会话与提交证据中出现完全相同的仓库相对路径。该会话创作了最终提交内容。
Candidate结构、保留文本或时间提示了一个值得检查的关联。经过评审的任务身份或因果关系。
Contextual邻近日期或路径历史有助于解释当前交付窗口。直接的会话、Story 或提交关联。

Feature Tree 的选择范围与证据置信度彼此独立。一个 Story 可以是有用的导航范围， 但它与会话的关系仍可能只是 candidate。

生成私有 Inspector​

在需要检查的仓库中运行最短命令。npx 会下载或复用当前包，渲染当前工作区， 并打开已经写入的报告：

npx @qoder-ai/better-harness inspector

默认会打开当前工作区，并包含最近 30 个 UTC 日内的活动，最多采集 200 个 commit 和 100 个完整 session。Date 只列出存在已观察证据的日期，不会虚构“零活动”日期。 完成 Better Harness 安装后，或者需要显式限定范围时，仍然可以使用完整形式：

better-harness harness-inspector render --workspace . --open

默认输出位置：

.qoder/better-harness-runs/harness-inspector/inspector.html

可以使用 --platform、--since、--until、--commits 与 --max-sessions 限定范围。--platform all 会从 Qoder、Codex、Claude Code、 Cursor、Qwen Code、GitHub Copilot、Pi、Kimi Code、WorkBuddy 和 Grok 中发现 证据，同时保留各 Provider 的证据缺口。

可选的 .better-harness/feature-tree.md 用于声明经过评审的意图：

- [ ] Checkout reliability
  - [ ] Explain payment failure telemetry {#payment-failure-telemetry}

两个空格的缩进表示父子关系；内部节点成为 Feature，叶子节点成为 Story。当其他 产物需要引用节点时，建议提供稳定的 {#id} anchor。

边界​

  • Inspector 是观察界面，不是恢复或变更权限的所有者。
  • 标记为 Run tests 的 Tool Call 只能证明该调用被观察到，不能单独证明测试通过。
  • 相同路径与邻近时间支持相关性判断，但不证明作者身份。
  • 缺失的 Token、Cost、Outcome、Base Commit、Budget 或 Harness Revision 证据 必须保持为 unobserved，不能被转换为零值或干净结果。

未来演进​

预期演进链路是 Inspect → Compare → Eval → Decision。

  • Compare 应当是顶层工作区模式，而不是 Capability 或 Date 之外的第三种 Scope。它的第一项能力是判断两条会话是否可比。
  • 第一阶段应是以 Story 为主要发现入口的观察性轨迹比较：对齐跨 Provider 的归一化 动作，中性展示 Delta 与混杂因素，并把 insufficient evidence 作为正常结果。 同一 Story 只是发现入口，不是任务等价证明。
  • improvement 或 regression 等更强结论应等待后续 Eval 证据：绑定的 Harness Revision、受控 treatment、客观 Outcome、兼容 Budget、重复 Trial，或 held-out/later-comparable cohort。
  • Decision 层才可以支持 retain、narrow、revise 或 revert；Inspector Compare 本身不能制造这种结论权限。