HarnessScope

HarnessScope

为 Agent 框架提供轮次级治理可观测性。 HarnessScope 读取 Agent 框架已生成的对话记录，根据工作区自身的运行规则（先规划后编码、完成前验证、上下文预算、路径边界等）评估每一轮，并提供本地查看器，展示每个会话如何经过这些治理环节——包括通过的环节，而不只是违规项。

以上每一帧都是 hscope demo：在本地生成的合成数据集。真实对话记录包含完整的提示词文本，绝不会用于演示。

---

发现

一个会话并不是一个模型在自言自语——它会生成子 Agent，它们使用父 Agent 未使用过的模型运行，而流式响应会多次写入同一个请求。若天真地读取这种结构，数字就会出错。以下是针对这些问题所做的修正，均基于本项目自己的对话记录测得：

天真读取的结果	实际情况	原因
重读浪费	其中 42% 是误报	子 Agent 读取父 Agent 读过的文件，并不算重读——它从未拥有过那些 token。浪费按上下文窗口（agent_id）计费，而不是按会话计费。
90,957,147 个输出 token	32,348,242（高估 2.8 倍）	流式响应会为每个 requestId 写入多条用量记录。只统计最后一条——前面的记录是部分数据（2，而完成后的响应显示为 31,979）。
3,121 轮	2,438（高估 28%）	一轮就是一条用户提示词（promptId）。中断通知、<command-name> 回显和 <bash-input> 块也都是用户记录。
格式稳定	一个月内有 29 个 harness 版本	对话记录格式没有文档说明，而且会不断变化。因此，hscope doctor 会明确报错并指出导致问题的版本，而不是悄悄输出错误数字。
剩下的重读浪费	其中 81% 也是假象	使用 (context, path) 作为键时，分页读取大文件（offset=501）与读取两次无法区分——而每个新分块都会被计为上下文已经持有的 token。854,334 token 中有 692,292 个属于这种情况。现在，键中包含了范围。

最后一行最重要，也最晚发现：它是在 v0.1.3 发布后，将工具指向它自己的工作区并查看结果时发现的。这和第一行属于同一类错误，只是深入了一层，而且出现在已经通过自身测试的代码中。一个声称能发现治理失效的工具，最好经得起用自身来检验——因此现在这就是它的常规用途，而它接下来的发现更糟。

这让三条规则失去了默认启用状态。R1（优先索引）、R2（优先内联）和 R6（审批门槛）询问的是语义问题——这是一个领域问题吗？这种扇出有必要吗？这段代码属于那个计划吗？——却用语法测试来回答：提示词中的关键词、提示词的字符数、项目文件夹。根据真实会话测量，R2 的违规项中有 84% 是调用了一个唯一职责就是扇出的命令的轮次。这不是需要调整的阈值；无法追踪概念的代理指标，调不出真正的概念。现在，这些规则默认都处于禁用状态，并各自标明测得的误报率（precision 是规则上的一等字段，会显示在模型中、rule_health 中，以及可悬停查看的徽章上）。重点不在于禁用，而在于禁用，并说明原因和数字。默默默认启用的规则，会让治理界面变成无人信任的噪声——而这正是本项目旨在指出的问题。

R8 出于同样的原因，不再报告合规率。它的机会数按定义就是违规数——重读计数器从未观察过合规的重读——所以“0% 合规率”只是恒等式，并非发现：这个数字看起来像是在定罪，却什么也没说明。现在它只报告数量，不再报告比率。

这些是对单一语料库的观察，而不是基准测试——你的数字会有所不同。关键在于，这些数字至少可以读懂：指标知道数量，账单知道金额，但它们都不知道“子 Agent”这个词。完整推理过程：docs/MULTI-AGENT.md。

HarnessScope 的对比

HarnessScope 观察的层面与大多数“LLM 可观测性”工具不同：它关注的不是你插桩的应用，而是Agent harness 本身，并从其自身的转录记录中读取数据。

工具	观察内容	数据获取方式	运行位置
HarnessScope (hscope)	Claude Code 会话的治理合规情况与令牌流转，逐轮观察	读取转录 JSONL——事后读取，或在 harness 追加内容时实时读取（--watch）。无需插桩，也不需要在会话中安装钩子	本地运行，不包含大模型
ccusage 和类似的 CLI	同一批转录记录中的令牌／成本总计	读取转录 JSONL	本地运行
LangSmith / Langfuse	你的应用发出的 LLM 调用跟踪记录	由你编写 SDK 插桩代码	SaaS（Langfuse 也可自托管）
Arize Phoenix (OpenInference)	你插桩的 LLM 应用的 OTel 跟踪记录	OTel SDK 插桩	本地运行／可自托管
Claude Code /cost、OTel 指标	当前会话的开销；汇总计数器	在 harness 内	在 harness 内

其他工具都不涉及的一点是：会话是否遵循工作区的操作规则——先规划再编码、先验证再完成、路径边界、上下文预算。成本工具会告诉你会话花费了多少；跟踪工具会告诉你应用发出的 LLM 调用做了什么；HarnessScope 则会告诉你 Agent 是否按照工作区要求的方式工作。

试用——30 秒，不涉及你的任何数据

pipx install hscope        # or: pip install hscope · npx -y hscope  (Python 3.11+ either way)
hscope demo --serve        # synthetic corpus → ingest → judge → viewer

三个虚构会话：一个合规会话，一个浪费资源的会话（重复读取、无用上下文、读取边界外的内容，以及在没有任何验证的情况下宣告完成），还有一个扇出会话（两个子 Agent——一个引用了自己读取的内容，另一个没有；一个在后台启动——并加上一轮跨主机 MCP 往返）。

这批数据采用与真实数据相同的标准：必须通过 hscope doctor，因此，如果生成器写出的格式不符合解析器预期，就会被不变量检查发现。它已经两次证明了这一点——一次是 requestId 在多个会话中重复使用（hscope 正确地将其识别为一次被 fork 重放的 API 调用），另一次是带填充空格的 agentId: 被解析器的正则表达式整个吞掉。

然后将它指向你自己的会话

hscope                     # scan ~/.claude/projects → ingest → judge → check → open the viewer

无需标志，无需配置文件。它不会弄错两件事：

• 端口是查找出来的，不是默认假定的。 8000 是一个合理的默认值，但在某些 Windows 计算机上，它属于保留范围（WinError 10013）。第一印象不该是一段堆栈跟踪。
• 它会说明转录记录会过期。 harness 会在大约 30 天后删除这些记录，而摄取会让它们永久保存。摄取间隔超过这个期限，就会悄无声息地丢失会话——从未摄取的会话，与从未发生过的会话无法区分。首次运行时会显示最早的转录记录有多旧，并建议摄取频率。

它还会声明即将用于评判的规则——中立预设，或它在磁盘上找到的工作区模型。口头声称使用“预设”，却悄悄应用了一个模型，与静默回退一样是在撒谎。

一切都以本地为先：转录数据不会离开你的计算机（唯一的例外是选择启用的 Tier B 大模型评判器——默认关闭，只有对单个会话明确点击后才会运行）。该工具绝不会写入你的项目、.mcp.json 或 harness 设置：观察治理的工具，不得改变自己所观察的对象。

实时观察——只观察

hscope --watch             # the circuit stays live: sessions are re-ingested and re-judged as they run

会话仍在进行时，harness 应用会持续向转录记录追加内容，因此实时视图所需的数据一直都在——缺少的只是循环。--watch 每 2 秒扫描一次修改时间，只对发生变化的文件计算哈希（修改时间是触发条件；哈希才是判断依据），仅重新评估这些会话，并由查看器自行刷新。若某次扫描没有文件变化，就不会解析、计算哈希或打印任何内容。

它只观察，不会干预。 不会在你的会话中安装钩子，不会阻止任何操作，屏幕上的违规也需要由人来处理。要实施阻止，就得使用 PreToolUse 钩子——这会让上文“不会向会话注入钩子”这一项变成谎言，把工具绑定到某一种 harness，还可能让错误的判定中断你的工作（事后看来，错误判定只是一个错误徽章；实时判定却会直接拦下操作）。与其等到 40k 个 token 才发现问题，不如在 5k 个 token 时就看到重复读取循环或扇出，这很有价值；但这并不意味着工具需要踩下刹车。

仍在运行的轮次会显示出来，但不会被评判。 评判它会违反 hscope 自己的规则：验证门规则会在即将运行检查的轮次上触发——三秒后判定就会被推翻；而流式响应的 token 用量要等最后一条记录到达后才会确定。因此，实时轮次会显示“进行中 · 尚未评判”徽章，并在轮次结束后显示判定。延后判定不应变成跳过判定：如果你中断该轮次，文件就会停止更新；hscope 会在其活跃窗口期过后评判，而不会让它永远处于待评判状态。

你会得到什么

Harness Circuit

将单个轮次呈现为拓扑固定的示意图：上下文来源 → Agent → 操作界面 → 治理输出。子 Agent 会显示为带有生成边和返回边的节点——返回边会标注返回了什么，而不是子 Agent 消耗了什么（一个真实轮次中，三个 Agent 分别消耗了 16.5k / 6.3k / 5.3k 个输出 token，并向父级交回 1.5k / 2.2k / 2.0k 个 token）。外部主机上的 MCP 跳转和具备写入能力的服务都会在线路上标出。

Session Replay

轮次时间线：哪些内容加载到了上下文中、运行了哪些工具，以及每个轮次的规则判定——包括通过的情况。只列出违规项的治理视图无法区分“符合规范”和“从未检查”。

Rule Health

按规则展示合规率 × 覆盖率。一条规则在 3 个可评估轮次中合规率为 100%，与在 300 个轮次中合规率为 100% 并不相同；如果没有任何内容可以评估某条规则，系统会如实报告，而不会给它打分。

Token / Loop

按轮次统计 token 消耗，并用损耗定位标记指出问题所在——重复读取、无效上下文（已加载但从未引用）、错误反复和缓存窗口浪费——同时归因于实际产生这些开销的轮次和上下文窗口。

Setup

你注册的每个钩子、MCP 服务、技能和子 Agent，以及转录记录显示它们实际上是否被调用：active / unused / unregistered-call。注册是一种声明；转录记录才是证据。（这里特意不放截图——这个屏幕会读取你自己的机器配置，因此任何截图都会展示某个人真实的工作区。）

无需你手写的规则

没人应该为了尝试工具而手写规则。首次运行时，如果找不到工作区模型，hscope 会根据你的代码仓库结构生成一个模型，并为你已有的大模型留下一页说明：

hscope                   # ...with no rules of your own, writes ~/.hscope/<id>/HSCOPE-SETUP.md
hscope mcp --install     # prints an MCP snippet; paste it into .mcp.json
hscope setup             # regenerate the page whenever your canon moves

HSCOPE-SETUP.md 有两类读者。对你而言，其中包含 hscope 找到的规范、钩子、MCP 服务、技能和子 Agent，以及尚无规则引用的规范条款。对你的大模型而言，其中包含调用 get_setup_guide → suggest_rules → set_rule 并编写这些规则的说明。你来审批；它负责起草。

整个流程只有 三个手动操作——运行 hscope、粘贴代码片段、交出该页面。代码片段包含 HSCOPE_MCP_WRITE=1，因此粘贴它 就是 对写入的授权；不需要第二步。而且 hscope 绝不会自行修改 .mcp.json。

入门流程真的有效吗？

hscope onboard      # read-only, idempotent; exit 1 while incomplete

六个可观测阶段和一个结论。hscope 会在每次运行结束时打印这些内容，因此即使你不知道这个命令的存在，也能看到它。

1  transcripts ingested             PASS   297 session(s), oldest 35d
       -> oldest is 35d and the harness deletes transcripts at ~30d -- ingest more often
2  hscope MCP registered            FAIL   not in your harness config
       -> run `hscope mcp --install` and paste the snippet it prints
3  workspace model exists           PASS   ~/.hscope/warp/workspace-model.json
4  the model governs your sessions  PASS   289 of 297 session(s)
5  the model is not empty           PASS   14 rule(s), 25 role(s)
6  your rules actually fire         PASS   10 of 10 enabled rule(s) had an opportunity

disabled, so not judged at all: R1, R2, R6, B1

INCOMPLETE -- next: step 2, hscope MCP registered

其中四项是检查清单。其中两项会静默失败，这正是这个命令存在的原因：

• 步骤 4——模型管理你的会话。 模型可能保存在磁盘上，但其 workspace.roots 声称不包含你实际工作的任何路径。此时 hscope 会依据中性预设进行判断，而在这个关卡之前，它对此只字不提——于是你会在屏幕上看到自己的规则名称，却不知道这些规则从未生效。现在，它会打印出你的会话实际运行所在的 cwd。
• 步骤 6——你的规则确实触发。 大模型为你编写的十二条规则，如果在你的语料中从未有机会触发，那就不算入门流程；它们不过是在空无一物之上打了个绿色勾。零次触发机会的规则会被点名。仅仅已禁用的规则会标记为关闭，而不是失效——这是两种不同的事实，把它们混为一谈，正是这个工具要揭穿的谎言。

失效规则是一个发现项，而不是失败：覆盖率为零，确实可能意味着“目前还没有机会”，如果因此让关卡失败，反而会鼓励少写规则。但如果你写的规则一个都没有触发，关卡就会显示 INCOMPLETE——这属于空洞通过，而 hscope doctor 已经拒绝对你的转录报告这种结果。这里采用同样的拒绝逻辑，只不过针对的是你的设置。

工作区模型（可选，但建议使用）

没有模型时，HarnessScope 会基于中性预设运行：使用领域值为空的通用规则，路径标签回退为文件名，会话则呈现为扁平列表。它能在任意代码仓库中稳定运行，不会崩溃——这就是去领域化约定。

使用模型（~/.hscope/<workspace>/workspace-model.json）时，你可以在一个 JSON 文档中声明你的工作区如何管理：

• rules[] — 使用你的参数（关键词、阈值、标记）的原型实例
• roles[] — 每个路径 / MCP 服务 / 子 Agent 的含义（标签、电路节点、主机边界）
• gates[] — 你的管理流程（例如 context-load → plan-approval → implement → verify → ledger）
• unmeasurable[] — 无法通过检测器检查的规范条款（如实呈现，而不是伪造）
• work_items — 可选的会话上级分组（此工作区使用带有状态 frontmatter 的 plans/**；其他代码仓库可以将 issue/PR 映射到同一位置）。缺省时 ⇒ 显示扁平会话列表。

架构和一个中性示例位于 hscope/schema/。验证你的模型：

python -m hscope.schema.validate_model ~/.hscope/<workspace>/workspace-model.json

MCP 接口

任何 MCP 客户端都可以读取 HarnessScope 观察到的内容，闭环由此形成：Agent 通过读取上一个会话的评分来开启新会话，而不必重新验证已发现的问题。

// .mcp.json
{ "mcpServers": { "harness-scope": {
    "command": "python", "args": ["-m", "hscope.cli", "mcp", "--db", "/path/to/harness_scope.db"] } } }

工具
list_sessions · session_report · token_hotspots · rule_health	查看器中的数据
get_workspace_model	本仓库的治理方式，汇总为一份文档
get_setup_guide · suggest_roles · suggest_rules	编写规则的依据
set_role · set_rule	将其写回

此服务内部不会运行模型。 客户端就是模型：get_setup_guide 会向客户端提供封闭的原型库以及每个原型的参数模式，suggest_rules 会提供尚无规则引用的规范条款，而判断结果则通过 set_rule 返回——在写入任何内容之前，参数会根据相应原型的模式进行验证。因此，MCP 路径无需提供商、凭据，也无需征得允许将数据发送到主机外部的同意。hscope compile 会通过一次批量大模型调用完成同样的工作；这是它的对话式、渐进式版本。

写入功能默认关闭（HSCOPE_MCP_WRITE=1），且始终只能修改 ~/.hscope/<workspace>/workspace-model.json。没有任何工具会写入项目文件或操控其他 Agent——HarnessScope 负责观察和判断，不负责驱动。

文档

MULTI-AGENT.md	为什么一个会话不是一个模型自言自语——以及 发现的内容 中每个数字的含义
DOCTOR.md	hscope doctor：九项不变量，以及它拒绝做的两件事
FAILURE-MODES.md	优雅降级——当转录文本、数据库或模型出错时会发生什么
VERIFICATION.md	验证套件（完成定义）；CI 会在 3 种操作系统上运行这些套件
CONFIG.md	环境变量 · 可选启用的 Tier B 判定器
RUN-FROM-SOURCE.md	贡献者：所需条件、逐阶段介绍流水线、仓库布局

常见问题

HarnessScope 是什么？ 一款本地优先的 Claude Code 可观测性工具：它会将你的对话记录 JSONL 文件解析到 SQLite，根据工作区自身的操作规则评估每一轮，并提供一个 Web 查看器，展示每个会话如何经过这套治理结构。使用 pip install hscope（或 npx -y hscope）安装。

我的对话记录数据会离开我的设备吗？ 不会。解析、规则评估和查看器都在本地运行；服务绑定到 127.0.0.1。唯一例外是可选择启用的 Tier B 大模型评估器，它默认关闭，只有在你点击对应会话的评估按钮时，才会发送该会话的一份摘要。

运行它需要 API 密钥或大模型吗？ 不需要。HarnessScope 内部不包含模型——规则引擎是确定性的。只有在你自行引入时才会用到大模型：用于可选的 Tier B 评估器，或通过 MCP 接口让你的编码 Agent 编写规则。

它与 ccusage、LangSmith 或 Phoenix 有什么不同？ 它们位于不同层级（见上方的对比表）。成本命令行工具统计会话花费；追踪平台会检测你的应用程序发起的大模型调用。HarnessScope 读取底层框架本身的对话记录并评估治理情况：会话是否在编写代码前制定计划、在宣称完成前进行验证、遵守路径边界，以及令牌实际消耗在何处。

我的 Agent 可以读取结果吗？ 可以——这正是 MCP 接口的用途。任何 MCP 客户端都能获取 session_report、token_hotspots、rule_health 和工作区模型，让下一次会话一开始就能查看上一次的评分，而不必重新发现相同问题。

Claude Code 更改对话记录格式时会发生什么？ hscope doctor 会明确报错，指出破坏不变量的底层框架版本，而不是悄悄输出错误数据。仅这个语料库就在一个月内记录了 29 个底层框架版本；格式漂移会被检测到，而不会通过调参掩盖。

它支持哪些平台？ Windows、macOS 和 Linux——CI 矩阵会在这三种平台上运行验证框架。Python 3.10+（建议使用 3.11+）。

数据与隐私

• SQLite 数据库包含对话记录中的完整提示词文本。该文件已加入 gitignore（*.db），必须保留在本地——切勿提交或上传。
• 服务默认绑定到 127.0.0.1，并且以只读方式访问数据库。
• 只有在你点击对应会话的评估按钮时，Tier B（大模型评估器）才会将该会话的摘要发送到本机以外；规则（B1）默认禁用。

许可证与开放核心边界

HarnessScope 是 Apache-2.0 开放核心软件。个人用户接触到的一切功能永久免费，不设功能限制——付费层级（如果将来推出）只会增加组织所需的功能，绝不会移除个人用户可用的功能：

层级	免费（Apache-2.0 核心）	企业版（ee/，未来推出）
数据采集	对话记录导入 + hooks	MCP 网关（跨底层框架采集）
分析	规则引擎 · 电路 · 令牌损耗 · 覆盖率——全部功能	多用户聚合、组织仪表板
安全	本地安全流规则（自我审计）	组织合规报告、审计日志
账户	本地单用户	SSO / RBAC

请参阅 LICENSE（Apache-2.0）、ee/README.md（边界）和 CONTRIBUTING.md（DCO）。