上一篇，我们探讨了如何将“确定性逻辑”从 Prompt 中分离出来，核心在于明确“什么该由代码负责”。今天，我们接着聚焦于工具的边界问题。当主流程已经清晰，有哪些能力应当以可组合工具的形式存在，而不是永久地绑定在一条从头到尾的管道中。

本文的重点，并非“我们是如何拆分工具的”，而是回答一个更通用的核心问题：在什么时机下，我们应该将一条固定的流程，拆解为一套可自由组合的工具箱。

SkillSentry 最初的设计是一个单体管道，只有一种固定的执行模式：从头运行到尾。这种设计确保了流程的完整性，但也带来了一个现实痛点——在日常开发中，最频繁的需求并非“每次都需要全面重新测试”，而是“我只修改了一条规则，是否可以仅验证受影响的几个用例？”

在实现工具化改造后，最大的收获并非仅仅是速度提升，而是自然涌现出一个在旧架构下根本无法存在的工作流：regression。这种回归测试流程跳过了用例设计阶段，直接复用已有的 Golden Set 和历史失败用例，完美契合了日常修复后的验证需求。

实现的核心方法十分简洁：将整个管道拆解为五个原子能力（sentry-static / cases / executor / grader-report / sentry-report），并通过 JSON 文件而非函数调用来传递状态；编排器仅负责调度顺序，绝不承载业务逻辑。

最终，我们得出两条核心结论：

1. 工具箱化带来的最大收益不是速度，而是让 regression 这种按需工作流得以实现。
2. 在 LLM 编排架构中，工具之间通过文件而非函数调用传递状态，反而更有利于状态恢复、工具替换和过程检查。

• 一、先说清楚问题：不是「慢」，是「绑死了」
• 二、拆分的前提：先定清楚每个工具的边界
• 三、原子工具：为什么这样拆
• 四、架构涌现：一个我没设计过的工作流
• 五、JSON 文件是合约：LLM 工具链的接口设计
• 六、编排器越薄越好
• 七、改造前后对比
• 八、诚实面对：工具箱化解决不了什么
• 九、工具箱化之后的新问题：可分发性

本文中最重要的发现，并非“测评速度变快了”，而是：将单体管道拆分后，一个你从未刻意设计过的工作流，它自己悄然出现了——它在单体管道时代根本不可能存在，却在工具组合之后自然涌现。这个发现，比所有性能数据都更值得记录。

一、先说清楚问题：不是「慢」，是「绑死了」

SkillSentry 最初的设计，是一条完整的测评管道：

规则提炼 → 触发率评估 → 用例设计 → [L1 执行] → [L2 Grader] → [L3 Comparator] → 报告

很长一段时间，大家认为主要问题是“太慢了”，于是进行了一轮性能优化：通过 MD5 哈希缓存（跳过规则重提炼）、mega-batch 并行、Grader 批量调用、上下文压缩等手段。优化完成后，quick 模式从 30 分钟降到了 8-10 分钟（mcp_based）/ 15-20 分钟（其他）。

但经过一段时间的使用后，我们逐渐意识到，更本质的问题并非速度，而是整个系统只有一种单一的使用方式。

三个高频场景，都被这个单一流程卡住了：

场景一（最常见）：当你修改了报销单提交逻辑中的一个字段映射，只想快速确认“主流程没有崩溃”。系统的回应是：重新提炼规则 → 重新设计 10 个用例 → 每个用例跑 2 次 × 双侧 → Grader → 报告。整个过程需要 20 分钟。我们真正需要的是：仅运行上次已验证通过的 5 个核心用例，5 分钟就能得出结果。

场景二：你刚写完一个新 Skill 的 description，想先确认触发率是否足够，再决定是否要编写功能规则。但系统不具备这种能力，只能触发全量流程，等待 20 分钟，最终得到一份根本不需要的完整报告。

场景三：在 Skill 上线前，想进行一次静态检查，确认 HiL 节点没有遗漏、规则没有冗余。同样，这种需求也无法被满足。

这三个场景的共同症结并非“流程太慢”，而是：“工具”与“流程”被强行捆绑在了一起——是否拥有 MCP 连接、是否运行完整 Grader、是否生成 HTML 报告，这些决策在用例设计阶段就已经被固定，用户没有任何选择的余地。

工具箱化要解决的，正是这个问题，而不仅仅是速度。

二、拆分的前提：先定清楚每个工具的边界

“工具箱化”并非简单地将一个大文件切分成若干小文件。在动手之前，必须首先回答一个问题：

每个工具的输入是什么、输出是什么、它对外部状态有哪些依赖？

这一步花费的时间比编写代码更多，因为如果边界不清晰，拆分出的工具就会在暗中依赖彼此的内部状态，表面上看似独立，实质上仍是一条串联的管道。

经过梳理，我们得到了下面这张表：

这张表中有一个关键信息列：能否独立运行。每个工具的依赖必须是文件（如 evals.json、grading.json），而不能是内存中的某个对象或另一个工具的运行时状态。这个约束条件，直接决定了后续工具间数据接口的设计方向。

三、原子工具：为什么这样拆

拆分之后，每个工具都是一个独立的本地 Skill，并拥有自己的 description（用于触发检测）。

早期版本曾讨论过“五个原子工具”，在稳定实现后，已将其中一部分合并为更清晰的入口。保留的设计原则是：工具边界必须依据输入/输出文件来划分，而非根据“看起来像一个步骤”的口头描述。

少拆分（例如将 cases + executor 合并）的问题在于：合并后，“只设计用例、不执行”的场景就会消失——用例设计完毕后，先进行 review，再决定是否执行，这个中间状态就不复存在了。

多拆分（例如将评分和报告长期拆分为两个常规步骤）的问题在于：报告强依赖于评分结果，拆分会增加一次 subagent 调度和一套接口维护的开销。因此，当前版本的主流程收敛为 grader-report；独立的 sentry-report 仅保留给“已有 grading，需要重新生成报告”的特殊场景。

当前的工具，按“是否需要真实执行”分为两类：

不需要执行任何工具的（纯分析/生成）：

• sentry-static：静态读取 SKILL.md，覆盖 description、HiL、复杂度、冗余规则、规则可测试性和触发检查，耗时约 30 秒到 2 分钟
• cases：读取规则 + inputs/，通过双源合流方式设计用例，标注断言强度分级，输出 evals.json，耗时约 5-10 分钟

需要执行的（启动 subagent）：

• executor：读取 evals.json，并行启动 with_skill / without_skill（根据当前 baseline 规则决定是否需要 without_skill），输出 transcript + timing，耗时约 10-20 分钟
• grader-report：读取执行结果，完成断言评审、汇总指标、生成报告和发布建议
• sentry-report：读取已有的 grading/session，重新生成报告，不作为主 pipeline 的常规评分步骤

值得一提的是 sentry-static：这个工具的最大价值在于，它不需要任何 MCP 连接。当 Skill 刚写完、尚未配置任何工具调用时，30 秒内就能发现 HiL 漏洞。最典型的漏洞场景是：编写了“提交前询问用户确认”，但遗漏了“用户拒绝时如何处理”——这正属于 HiL 检查项，通过静态分析即可发现，比运行测试用例要快得多。

四、架构涌现：一个我没设计过的工作流

这是全文最重要的一节，也是在动手拆分之前，任何人无法预料的事情。

拆分完成后，在梳理“各种工具可以组成哪些工作流”时，发现了一个之前根本不存在的组合：

跳过 cases 设计环节，直接使用 inputs/ 中已有的用例，运行 executor → grader-report。

这就是 regression（回归测试）工作流。

为什么说它是“涌现”而非“设计”的？

在单体架构中，这个工作流在物理上不可能存在。SkillSentry 的主流程是：规则提炼 → 用例设计 → 执行 → 评审 → 报告，这五步构成了一条强制串联的流水线。没有任何地方可以插入“我已经拥有用例，请跳过设计步骤”的选项。即便有这个需求，也无法实现。

拆分为工具箱后，工具之间独立，流程由编排器决定，“跳过某个工具”就变成了一个正常选项。regression 工作流是架构本身提供的，而非事先设计的结果。

它的价值在哪里？

让我们看看这张频率分布表：

regression 工作流恰好命中了最高频的使用场景，而这个场景在单体架构中，一直是由 quick 工作流（过度设计）来勉强支撑的。

这个发现让一个道理变得非常清晰：工具箱化的真正收益，并非为现有工作流提速，而是让那些被压抑的工作流重新浮现。单体架构将“测评”定义为一个不可分割的动作，而工具箱化则将其还原为一组可以独立使用的能力。

五、JSON 文件是合约：LLM 工具链的接口设计

在设计工具之间的数据传递方式时，我们自然而然地选择了文件——工具 A 将结果写入 evals.json，工具 B 再读取该文件。

完成之后才意识到，这个选择与传统软件工程的直觉是相悖的。

传统软件工程通常建议：优先采用函数调用（参数类型安全，无文件 I/O 开销），而文件耦合被视为反模式（两个模块通过临时文件传递状态，耦合关系隐含、难以测试）。

但对于 LLM 工具链，这种直觉在三个关键点上失效了：

① LLM subagent 之间没有共享内存

传统函数调用之所以好用，是因为调用方和被调用方处于同一个进程中，可以传递内存引用。但 LLM subagent 并非如此——每个 subagent 都是独立的 API 调用，没有共享堆内存，“将对象引用传递给另一个 subagent”这种操作根本不存在。唯一能传递的只有可序列化的数据。在 LLM 编排中，选择“函数调用”还是“文件”，本质上是选择“直接 inline 所有数据”还是“用文件路径作为引用”。文件路径引用，反而是更轻量的方式。

② 文件使失败可恢复

假设一次 executor 批次中途崩溃（因网络超时、MCP server 不稳定），已完成评估的 transcript.md 仍然保留在磁盘上。重新触发时，只需检查文件是否存在，若存在则跳过，仅运行未完成的部分。

如果采用函数调用加内存传递，这个能力根本无法实现——上一次的运行结果在 subagent 退出时就消失了。

③ 文件使工具可替换

如果想换一个更快的 Grader 实现，只需保证其输出的 grading.json 格式不变，其他工具完全无需修改。

若想添加一个新工具（例如专门用于“regression 对比”的工具），只需它能读取 grading.json，并向 workspace 目录写入一个新 JSON 文件，即可接入工作流。

这就是“接口稳定性”在 LLM 编排中的具体形态：工具间的接口是文件格式，而非函数签名。改变函数签名需要同时修改调用方；而更改文件格式时，只要旧格式的读取方和新格式的写入方同步更新，过渡就是可控的。

④ 文件使状态可检查

当测评进行到一半时，如果想知道哪些评估已经完成、哪些断言失败，只需执行 cat sessions/xxx/eval-3/grading.json 即可获取信息，无需借助 LLM 来回答。

这是 LLM 工具链中一个常被忽视的可观测性问题：LLM 的上下文并非永久存储，对话一旦结束，状态便消失。使用文件持久化中间状态，是实现 LLM 工具链“调试友好”的必要条件。

工具间的文件接口如下，每个文件的格式即工具间的合约——写入方不能随意修改字段，读取方也明确知道可以依赖哪些字段：

rules.cache.json ← SkillSentry 写入，cases 步骤读取
cases.cache.json ← cases 步骤写入，复用时 executor 间接受益
evals.json ← cases 步骤写入，executor 读取
timing_with.json ← executor 写入，grader-report 读取
timing_without.json ← executor 写入，grader-report 读取
grading.json ← grader-report 写入，sentry-report 可在重新生成报告时读取
trigger_eval.json ← sentry-static 写入，grader-report 读取（full 模式）
comparison.json ← Comparator/Analyzer 写入，grader-report 汇总时读取（standard/full 模式）
eval_environment.json ← executor 写入（并行率审计）

这张图中有一个值得注意的地方：没有任何一个工具既是某个文件的读取方，又是另一个文件的写入方（除了 SkillSentry 编排器本身）。每个工具的依赖链都是单向的，没有形成循环。这并非偶然，而是在定义工具边界时强制保证的。

六、编排器越薄越好

改造后，SkillSentry 主 SKILL.md 从 222 行精简至 154 行，execution-phases.md 从 600 行精简至 140 行。

被删除的内容，全部迁移到了各工具自己的 SKILL.md 中——包括 subagent steps 上限、transcript 双分离格式、Grader 调用规则、without_skill 早退指令等。这些执行细节，与编排器没有任何关系。

编排器现在只负责以下工作：

1. 识别用户意图 → 映射到工作流
2. 初始化工作目录 + 规则缓存检查
3. 按顺序触发工具，传入 workspace_dir
4. 工具通过文件传递状态（编排器不关心文件内容）

这里有一个反直觉的地方：编排器越薄，工具箱反而越好用。

道理很简单：如果编排器中包含了工具的执行细节（例如“Grader 每次必须处理 ≥2 个用例”），那么每次 Grader 的规则变化，都需要改编排器。但 Grader 的用法只与 Grader 自身有关，应封装在 agents/grader.md 中，不应泄漏到编排器里。

当编排器只知道“调用 Grader”而不知道“Grader 具体如何工作时”，工具的内部实现就可以独立演进，不会每次修改工具时都同时改编排器。

这与微服务设计中“API Gateway 不应包含业务逻辑”是同一个原则，只是在 LLM 编排的语境下进行了重新表述。

七、改造前后对比

时间变化（典型场景）

full 测评的时间没有变化——工具箱化优化的是“不必要的全量流程”，而非全量流程本身的运行速度。

文件体积变化

execution-phases.md 的变化最为显著。最初，它承担了“Phase 1 触发率规范 + Phase 3 用例设计规范 + Phase 4 执行规范 + Phase 5 报告规范”四项职责，600 行代码中任何一处的修改都需要理解整个文件的上下文。现在，它只做一件事：定义工具间的数据接口，仅 140 行，修改任何一个 JSON 字段，其影响范围都一目了然。

八、诚实面对：工具箱化解决不了什么

工具间的接口变更是新的风险

使用文件作为接口，其优势已在前面阐述。代价是：接口变更不会在编译期报错。如果 executor 步骤修改了 timing_with.json 的字段名，grader-report 在读取时会静默地得到 null 值，不会有任何错误提示，直到生成报告时才发现数据缺失。

在传统软件中，这个问题由类型系统和编译器解决；而在 LLM 工具链中，缺乏对应的机制，只能依赖文档（execution-phases.md 中的接口定义）和人工纪律来保证。

单独调用工具时，用户需自行了解前置条件

executor 步骤需要事先存在 evals.json，grader-report 需要先有执行结果，sentry-report 需要先有已有的 grading/session。如果用户不清楚这些前置条件，就会得到令人困惑的“文件不存在”错误，而非“请先运行 cases 步骤”这样的友好提示。目前，我们通过 description 字段进行说明，但尚未实现自动的前置条件检查。

regression 工作流的正确性依赖于 Golden Set 的质量

regression 工作流跳过了用例设计，它假设 inputs/ 中的 Golden Set 已经足够优秀。如果 Golden Set 本身存在盲区（例如缺少某类边界用例），即使 regression 测试通过，也并不意味着 Skill 质量没有问题，只能说明 Golden Set 中的用例均已通过。因此，Golden Set 的维护成为了一个新的质量保证环节，这个责任从工具本身转移到了使用者身上。

LLM 的串行本能并未得到根本解决

工具箱化改变了架构，但并未改变 LLM 的执行倾向。在 executor 步骤中，我们要求“with_skill 和 without_skill 必须在同一消息中并行发出”，这条规则依赖于 LLM 的自觉遵守。并行度审计（每批完成后计算 start_gap）虽然能让违规行为可见，但无法主动阻止串行。真正可靠的并行执行，仍然需要平台层提供原生的并发支持。

工具箱化为 SkillSentry 带来的最大价值，并非速度提升，而是将测评系统从一个单一动作转变为一组灵活的能力。这个变化，使得之前被压抑的 regression 工作流获得了存在的空间——而它恰恰是日常开发中最需要的那一个。

九、工具箱化之后的新问题：可分发性

完成工具箱化之后，我们才意识到，架构问题只解决了一半——工具是否能够被他人使用，是第二个关键问题。

工具箱化完成后，我们系统地梳理了一次“一个普通人拿到这个工具，首次使用的完整开销”。这个梳理过程本身就揭示了几个问题——它们与架构无关，但对实际可用性的影响很大。

问题一：安装需要克隆 6 个仓库

工具箱化之后，每个独立 Skill 都位于独立目录。用户若要安装 SkillSentry，需要分别克隆 6 个目录到正确位置。这对于开发者自己使用不是问题，但如果要分享给他人，就构成了门槛。

解决方案是将 sentry-* 的 SKILL.md 全部放入 SkillSentry 主仓库的 tools/ 子目录，并编写一个安装脚本（install.sh + install.ps1），负责将各工具部署到正确位置。用户现在的安装步骤简化为：

获取 SkillSentry 发布包后进入目录
cd SkillSentry && bash install.sh

该脚本会自动检测系统中安装了本地编码助手还是 OpenCode（或两者皆有），并部署到对应路径，最后输出验证结果。一次克隆，即可覆盖两个平台。

这个改动的工程量很小，但对“能否传播出去”的影响是质变的。工具再好，如果需要 6 步才能安装，大多数人在第 2 步就会放弃。

问题二：mcp_based Skill 测评可能产生假阴性，但用户不知情

executor 步骤在运行用例时会直接调用被测 Skill 所依赖的 MCP 工具。如果 MCP server 未启动，工具调用会报错，transcript 中将出现大量 error，Grader 会判定为 FAIL。

这个 FAIL 并非 Skill 本身的问题，而是环境的问题。然而对用户来说，收到的报告中写着“通过率 30%，建议修复”——用户会因此去修改 Skill，而不会去检查环境配置。这是测评系统最危险的一种失效模式：结论看似可信，但其来源已被污染。

修复方法是，在执行工作流之前增加一步 MCP 可用性预检：列出被测 Skill 引用的工具名称，与当前可用工具进行比对，不匹配时明确发出警告，并让用户选择继续还是中止。这一步将“静默失败”转化为“可见失败”，代价是多一次工具调用，收益是结论的可信度得到了保障。

问题三：使用开销不够透明

当用户提出“测评 xxx”时，他们无法预估这次操作会消耗多少 token。quick 模式包含 10 个用例 × 2 次运行 × 双侧 = 20 个 subagent，单次消耗大约 5-10 万 token。如果使用的是按量计费的运行环境，这确实是真实的资源消耗，应在开始前告知用户。

修复方法很直接：在推断工作流的确认提示中增加一行 Token 预估。这些信息原本就存在（工作流决定了用例数和运行次数），只是之前没有输出给用户查看。

这三个问题有一个共同的特征：它们只有在真实分发、真实使用的场景下才会浮现。自己使用时，我们知道如何配置 MCP，知道 6 个目录如何摆放，知道这次大概需要运行多久——这些背景知识隐含在脑海中，不会感觉到任何门槛。

工具设计从“我能用”到“别人也能用”，需要的并非更多功能，而是将这些隐含的前提条件一条一条地显式化。

后续演进：工具箱化之后还要收敛契约

工具箱化解决了“能否按需组合”的问题，但这并非终点。后续架构还需继续向两个方向收敛：

核心思路没有变化：工具箱化、按需组合、文件作为步骤间契约。变化的是执行保障机制——从“依赖编排器记忆”升级为“状态机强制执行”，以解决长对话中 AI 跳步的结构性问题。