跳到主要内容
AI教程

使用 harness-map 绘制并审计你的 Claude Code Harness

本教程将介绍如何扫描一个或多个 Claude Code 工作区、运行可选的智能体探测、生成交互式 Harness Map，并在保护敏感配置数据的同时解读其成熟度评估结果。

AI我搜编辑部阅读约 12 分钟
使用 harness-map 绘制并审计 Claude Code Harness

harness-map 的作用

harness-map 会读取 Claude Code 周围的配置，并将其转换为一张统一的可视化组装图。这些周边配置称为 harness，包括 CLAUDE.md 等指令文件、自动记忆、MCP 服务器、技能、权限、钩子、规则及相关设置。

有效 harness 会根据 Claude Code 启动时所在的文件夹以及启动新代理的方式而变化。主会话、分叉会话、子代理、Explore 或 Plan 代理、队友代理，或 claude -p 调用，可能会接收到不同的信息。harness-map 会针对每个选定的启动文件夹和启动方式显示这些差异。

本项目使用 Python 3，且不需要额外的 Python 软件包。其脚本会在不修改配置的情况下读取配置，生成结构化的 harness.json 文件，并构建可在浏览器中查看的 harness-map.html 报告。

主要功能

  • 按文件夹分析： 重复使用 --cwd，即可比较任意数量的启动目录。
  • 代理交接可视化： 查看每个组件是从父会话继承、再次从文件读取，还是不会传递给新代理。
  • 规则交互分析： 检查五种处理模式：替换、合并且拒绝优先、运行所有规则、无优先级串联，以及仅选择一条规则。
  • 风险与关注项： 识别自动记忆按文件夹划分，或团队功能导致权限模式传递给新代理等情况。
  • 成熟度评估： 在六项 harness 规范中查看 1 至 5 级成熟度，并通过六边形图表呈现。
  • 注重隐私的输出： 记录结构化元数据，同时省略指令正文、环境变量值、令牌、命令参数及其他敏感细节。
  • 便携式渲染： 将他人的 harness.json 粘贴到报告界面，即可重新绘制其映射图。

开始之前

你需要 Python 3、Git，以及访问普通用户账户所属 Claude Code 配置的权限。不需要使用 pip 安装软件包。

请使用运行 Claude Code 的同一用户运行 harness-map。不要使用 sudo。以管理员身份执行可能会改变有效主目录并暴露其他用户的配置，因此脚本会拒绝以这种方式运行。

请选择你通常启动 Claude Code 时实际使用的目录。扫描父目录不会显示在子项目中启动时适用的全部配置，因为配置会从每个启动文件夹向上解析。

安装

克隆仓库并进入其目录：

git clone https://github.com/Dominic-DK/harness-map.git
cd harness-map

你可以在 github.com/Dominic-DK/harness-map 查看项目。本项目采用 MIT 许可证发布。

第 1 步：扫描 Claude Code harness

为每个要比较的工作区使用一个 --cwd 参数运行 harness-map.py。以下命令会扫描两个示例文件夹，并将结果写入 harness.json：

python3 harness-map.py --cwd ~/work/a --cwd ~/work/b -o harness.json

你可以根据需要重复使用 --cwd。如果省略该参数，harness-map 只会扫描当前目录：

python3 harness-map.py -o harness.json

初始扫描会读取配置文件，并根据这些文件以及会话历史记录的汇总计数执行能够完成的检查。

更改会话历史记录周期

默认汇总周期为 30 天。需要使用其他观察窗口时，请使用 --days。例如，以下命令使用 90 天：

python3 harness-map.py --cwd ~/work/a --days 90 -o harness.json

会话分析只会统计事件，不会将会话文本、命令内容或文件内容复制到结果中。

第 2 步：输出代理探测计划

部分检查需要代理执行受控测试，而不仅仅是检查静态配置。使用以下命令输出项目提供的操作步骤和安全规则：

python3 harness-map.py --probe-plan

在要求代理执行检查前，请先阅读此输出。请遵循生成的说明，不要自行设计探测命令。检查内容可能包括读取配置、统计相关历史事件，以及在临时目录中测试行为。

第 3 步：执行或跳过探测

让代理执行输出的探测计划，并将其观察结果保存到 probes.json。每项探测都会记录执行了什么以及观察到什么，作为支持性证据。

此步骤为可选步骤。如果不执行某项探测，对应项目会显示为未检查，并从级别计算中排除。请避免手动声称未实际观察到的成功行为，尤其是第 5 级检查。

第 4 步：合并探测结果

使用相同的启动文件夹重新运行扫描，并添加 --probes probes.json：

python3 harness-map.py --cwd ~/work/a --cwd ~/work/b --probes probes.json -o harness.json

使用相同的 --cwd 集合，可以使最终计算与首次扫描覆盖的工作区保持一致。

第 5 步：构建并打开报告

根据完成的 JSON 文件生成 HTML 报告：

python3 build.py harness.json

在 macOS 上，使用以下命令打开：

open harness-map.html

在 Linux 上，使用：

xdg-open harness-map.html

在 Windows 上，使用：

start harness-map.html

阅读 harness-map

在报告中，切换起始文件夹和启动方式，以查看每种情况下的有效 harness。对于每个组件，报告会区分三种传递状态：

  • 新代理直接从父会话接收该组件。
  • 新代理再次从文件中读取该组件。
  • 该组件未传递给新代理。

这种对比有助于解释为什么使用同一仓库的两个代理可能表现不同。例如，子代理可能无法接收主会话可用的全部内容，而与特定起始文件夹关联的设置也可能不会在其他位置生效。

了解重叠规则

报告还会显示重叠规则的解析方式。根据配置类型，后出现的值可能替换另一个值；规则可能合并且拒绝优先；每个匹配的操作都可能执行；文本可能在没有优先级顺序的情况下拼接；或者只能选择一个选项。

当某条指令、权限或钩子看起来没有生效时，请检查这些交互。问题可能在于规则组合行为，而不是缺少文件。

了解成熟度评估

harness-map 将六个领域按 1 级到 5 级评分：

  1. 指令设计
  2. 记忆与位置
  3. 工具范围
  4. 预防性阻止
  5. 操作后验证与可观测性
  6. 委派设计

当可用数据支持时，脚本可以自动计算最高至 4 级的结果。结果会记录哪些条件已通过，以及评估在哪一步停止。评分定义存储在 harness-map.py 中的 SCORECARD 内。

5 级需要来自实际观测检查的证据。例如，只有在存在记录证明某项禁令确实阻止了一条命令时，预防性阻止才能达到 5 级。仅在配置中存在禁令并不足够。

当配置存在但看起来未被使用时，评估也可能降低分数，例如某个工具在所选历史期间内未被使用，或会话运行时采用了与配置不同的权限模式。

扫描多个起始文件夹时，显示的等级是各文件夹等级的中位数。文件夹数量为偶数时，使用中间两个值中较低的一个。报告还会显示最小值到最大值的范围。

等级越高并不一定越好。harness-map 会根据使用模式估算每个领域所需的等级，包括你是否独自工作、启动下级代理的频率，以及运行难以撤销的命令的频率。它会突出显示低于估计需求的领域，而不是对所有低于 5 级的分数发出警告。

隐私与输出审查

扫描器会读取文件，但不会更改配置。它会有意限制复制到输出中的内容：

  • 对于 CLAUDE.md 和规则文件，它会记录路径、行数以及读取时间，但不会记录文件文本。
  • 对于设置，它会记录权限模式、规则数量和环境变量名称，但不会记录环境变量值或规则内容。
  • 对于钩子，它会记录事件、来源和可执行文件名，但会省略命令参数和路径。
  • 对于 MCP 服务器，它会记录名称和来源，但会省略命令、参数、标头和令牌。
  • 对于路径，它会将真实的主目录前缀替换为 ~。

无法读取的文件会被放入 unreadable 列表。根据项目说明，Claude Code 在相同的用户权限下也无法读取这些文件。

输出仍会包含文件夹名称和已安装插件列表。在分享之前，请打开并检查 harness.json 和 harness-map.html。

仓库的 .gitignore 已配置为将 harness.json 和 harness-map.html 排除在版本控制之外，但提交前仍应检查暂存文件。

将工作流委派给编码代理

你可以要求 Claude Code 或其他编码代理遵循仓库说明。将示例文件夹替换为你自己常用的起始目录。合适的请求如下：

Read the README at https://github.com/Dominic-DK/harness-map and follow the direct execution steps.
My usual starting folders are ~/work/a and ~/work/b.
Perform the step 3 agent checks according to the documented safety rules and record the results.
When finished, open harness-map.html in a browser and summarize the result in about five clear sentences.

请在探测阶段保持人工监督。代理应遵循 --probe-plan 生成的确切安全计划。

高级提示

扫描每个有意义的入口点

不要假设扫描仓库根目录就能覆盖嵌套项目。将你实际启动 Claude Code 的每个目录分别作为一个 --cwd 添加。这样可以更有用地比较继承的指令、记忆边界和工具可用性。

选择符合工作方式的观测窗口

默认的 30 天窗口适合近期活动，但不常使用的工具可能需要更长的时间范围。请有意识地使用 --days，因为未使用的证据可能会影响成熟度评分。

将配置与已验证的行为分开

将基于文件的发现结果视为预期配置的证据，而不是控制项在运行时有效的证明。当你需要确认钩子、限制或其他行为确实生效时，请使用可选探针。

比较报告时不要暴露原始配置

如果有人向你发送经过审查的 harness.json，请使用报告中的粘贴区域重新绘制它。尽管敏感值会被省略，双方仍应先检查 JSON，因为项目名称、文件夹名称和插件名称仍会保留。

Python 不可用时使用备用方法

如果无法使用 Python 3，请将 PROMPT.md 的内容复制到代理中。代理可以直接读取配置，以相同格式创建 JSON，并构建界面。README 警告称，与脚本相比，这种方法更容易遗漏项目或错误计算项目数量。

已知限制

  • 交接规则固定写在 harness-map.py 的 SPAWN_RULES 中；它们不是通过观察你的实时会话推导出来的。
  • README 表示，这些规则遵循于 2026 年 10 月 2 日核查的 Claude Code 2.1.287 文档。后续版本中的行为可能有所不同。
  • 引用的来源是官方的 子代理、代理团队 和 记忆 文档。
  • 项目记录了一个差异：文档称子代理不会读取自动记忆，而作者的环境据称向子代理传递了记忆列表。报告将其标记为文档与观察结果之间的差异。
  • 诸如 --agents 和 --permission-mode 之类的仅限命令行设置不会存储在文件中，因此扫描器无法发现它们。
  • 对于已安装的插件，扫描器会读取插件安装目录中找到的最新版本。

结论

harness-map 提供了一种实用方式，用于了解 Claude Code 在不同项目和代理启动模式下实际接收的配置。首先扫描所有有意义的工作目录，可选择运行文档中说明的探针，利用这些证据重建数据，然后生成 HTML 报告。使用可视化和成熟度评估来发现配置缺口，但在分享前请检查生成的文件，并将文档中说明的交接规则视为与版本相关的规则。