LLM技能自动化测试：使用skillprobe实现端到端验证与CI集成

1. 项目概述：技能探针，为LLM技能提供确定性测试

如果你正在使用 Claude Code 或 Cursor 这类AI编程工具，并且为它们编写了自定义的“技能”（Skills），那么你很可能正面临一个所有早期采用者都会遇到的困境：你如何知道你的技能真的在按预期工作？更关键的是，当模型更新、工具版本迭代，或者你与其他人的技能组合使用时，你如何确保这些变化没有让你的技能“静默失效”？靠人工抽查、凭感觉判断，在个人项目里或许可行，一旦进入团队协作或产品化阶段，这种不确定性就会成为巨大的风险。

skillprobe正是为了解决这个问题而生的。它不是一个简单的提示词测试框架，而是一个端到端的、面向真实工作流的自动化测试工具。它的核心思想非常直接：既然技能最终是在 Claude Code 或 Cursor 这样的真实工具里运行的，那么测试就应该在完全相同的环境中进行。skillprobe会启动这些工具作为子进程，在一个隔离的临时工作区中，模拟真实用户的对话和操作，然后根据预设的断言来验证技能的行为和输出结果。

想象一下，你写了一个“代码审查”技能，希望AI在提交代码前自动检查代码风格。没有skillprobe时，你只能手动打开工具，输入几次“请审查这段代码”，然后肉眼观察AI的回复是否符合预期。这个过程无法量化、无法自动化、也无法回归。而有了skillprobe，你可以将这个场景编写成一个YAML测试文件，定义好初始工作区状态（比如一个待提交的Git仓库）、触发技能的提示词（如“commit my changes”），以及成功标准（如AI的回复中必须包含“conventional commit”字样，或者必须调用了“Bash”工具）。之后，无论是模型升级、技能修改，还是CI流水线，一键运行就能得到清晰的“通过/失败”报告和量化数据。

1.1 核心价值：从“感觉还行”到“数据驱动”

为什么我们需要这样一个工具？这背后是LLM技能开发与传统的确定性软件开发的根本差异。

技能是概率性的，而非确定性的。你写的技能文本，本质上是一段被注入到LLM上下文中的指令。无论你措辞多么严谨，LLM都有一定概率会忽略、误解或偏离你的指令。这与编写一个Python函数或一个Shell脚本完全不同，后者的行为是100%可预测的。因此，对技能的评估不能是二元的“能运行/不能运行”，而必须是统计意义上的“在N次尝试中，以多高的概率达到预期效果”。

“钩子”（Hooks）与“技能”（Skills）的职责分离。很多AI工具提供了“钩子”机制，比如在文件保存时触发代码检查，或在执行命令前进行拦截。钩子是确定性的，每次都会执行。但它们的能力是有限的，通常只能做“事后检查”或“事前拦截”。钩子无法引导AI在思考过程中做出更好的架构决策，无法传授团队特有的领域知识，也无法设定代码审查反馈的基调。这些“引导性”和“知识性”的任务，正是技能的用武之地。skillprobe测试的正是技能的这部分“软性”能力是否可靠。

技能组合的复杂性爆炸。单个技能可能工作良好，但当多个技能同时加载时，它们可能会相互冲突、竞争或产生意想不到的副作用。一个要求“代码简洁”的技能，可能会与另一个要求“详细注释”的技能产生矛盾。skillprobe提供了专门的“矩阵测试”和“基线模式”，能够系统地测试技能组合，并识别出真正的组合回归问题，而不是将自然波动误判为故障。

因此，skillprobe的目标用户非常明确：

1. 个人开发者：希望对自己的技能进行系统化测试，避免模型更新导致技能失效而不自知。
2. 团队技术负责人：需要为团队共享的技能库建立质量标准，确保所有成员使用的技能都符合预期。
3. 技能市场发布者：在将技能发布到Claude Code或Cursor市场前，需要进行严格的、可复现的测试，以建立用户信任。
4. 任何受困于“无限调试循环”的人：当你反复修改技能文本却无法确定新版本是否真的更好时，skillprobe能提供客观的A/B测试数据，告诉你哪个版本的通过率更高。

2. 核心概念与架构设计解析

要高效使用skillprobe，必须理解其核心组件是如何协同工作的。它的设计哲学是“模拟真实，保持轻量”，整个架构围绕着“测试套件”、“场景”、“工作区”和“断言”这几个关键概念展开。

2.1 核心组件：测试套件、场景与断言

一个skillprobe测试的核心是一个YAML文件，我们称之为测试套件。这个文件定义了测试的全局配置和一系列具体的场景。

# 这是一个测试套件文件 (test-my-skill.yaml) harness: claude-code # 测试哪个工具？可选 claude-code 或 cursor model: claude-3-5-sonnet-20241022 # 使用哪个模型？ timeout: 120 # 每个场景的超时时间（秒） skill: ./skills/my-clean-code-skill.md # 要测试的技能文件路径 scenarios: # 场景列表开始 - name: "技能在相关提示下被激活" steps: - prompt: "写一个Python函数，计算两个数的和" assert: - type: contains value: "def add" - type: skill_activated value: "my-clean-code-skill"

测试套件的顶层配置设定了测试的“舞台”：用什么工具、什么模型、测试哪个技能。harness指定了被测试的AI编程工具，skillprobe会通过命令行接口与它交互。model的指定非常重要，因为不同模型对同一技能的响应可能差异巨大。

场景是测试的基本单元，代表一个独立的、完整的用户交互流程。一个场景通常包含：

• name: 场景的描述性名称，用于在报告中识别。
• workspace: （可选）一个目录路径，该目录的内容会在每次测试运行时被复制到一个全新的临时工作区中。这用于模拟一个特定的项目初始状态，比如一个包含特定错误代码的文件。
• setup: （可选）一系列在AI对话开始前执行的Shell命令，用于进一步准备工作区，例如安装依赖、创建文件。
• steps: 一个对话步骤的列表。每个步骤包含一个发送给AI的prompt，以及一系列用于验证AI响应的assert。
• after: （可选）在AI对话全部结束后执行的断言，用于检查工作区的最终状态，例如某个文件是否被创建、文件内容是否符合预期。

断言是验证机制的核心。skillprobe支持多种断言类型，覆盖了从文本匹配到工具调用的各个方面：

• contains/not_contains: 检查AI的回复文本中是否包含（或不包含）特定字符串。这是最常用的断言。
• regex: 使用正则表达式进行更灵活的文本模式匹配。
• tool_called: 检查AI在响应过程中是否调用了某个特定的工具（如“Bash”、“Python”、“File Editor”）。这对于验证技能引导AI执行了正确操作至关重要。
• skill_activated: 检查特定的技能是否被AI工具加载并识别。这直接测试了技能的“可发现性”。
• file_exists/file_contains: 在对话结束后，检查工作区中某个文件是否存在或其内容是否包含特定文本。这用于验证AI对文件系统的实际操作结果。

2.2 工作区隔离：保证测试的独立性与可重复性

skillprobe一个关键的设计是为每个场景的运行创建独立的临时工作区。这是实现可靠、可重复测试的基石。

它是如何工作的？

1. 当运行一个场景时，skillprobe会在系统的临时目录（如/tmp）下创建一个唯一的文件夹。
2. 如果场景中定义了workspace，则该目录下的所有文件和子目录会被递归复制到这个临时工作区。
3. 如果定义了setup命令，这些命令会在临时工作区内依次执行。
4. 随后，skillprobe启动harness（如Claude Code），并将当前工作目录设置为这个临时工作区。AI工具看到和操作的就是这个隔离的环境。
5. 测试结束后，无论成功与否，这个临时工作区都会被自动清理。

这样做的好处：

• 无状态性：每次测试都从一个干净、已知的状态开始，完全不受之前测试运行的影响。
• 并行安全：因为每个场景都有自己的独立工作区，所以可以安全地使用--parallel参数并行运行多个场景，极大提升测试速度。
• 副作用隔离：AI工具在测试中可能会创建、修改或删除文件。将这些操作限制在临时目录中，可以完全避免污染你的实际项目文件或系统其他部分。
• 精准复现：当测试失败时，你可以精确地知道失败是在哪个初始状态下发生的，因为工作区的初始内容是确定的。

实操心得：工作区目录结构我建议将测试所需的“夹具”（fixtures）放在项目根目录下的一个fixtures/文件夹中。例如，fixtures/dirty-repo/可以是一个初始化了但包含未提交更改的小型Git仓库。在YAML中引用为workspace: fixtures/dirty-repo。这样既保持了项目结构的清晰，也便于版本控制。

2.3 与 promptfoo 的核心理念差异

你可能会问，市面上已有promptfoo这样的优秀提示词测试和评估框架，为什么还需要skillprobe？两者的定位有本质区别，解决的是不同层面的问题。

promptfoo：提示词与模型的“单元测试”promptfoo的核心是直接通过LLM的API（如OpenAI API, Anthropic API）发送提示词，并评估返回的文本内容。它擅长于：

• 对比不同模型（GPT-4 vs Claude-3.5）对同一提示词的表现。
• 对提示词进行A/B测试，量化不同措辞带来的输出质量差异。
• 评估模型输出的客观指标，如符合格式、包含关键词、通过代码执行等。

然而，promptfoo测试的是“裸”的提示词和模型交互。它不涉及技能在具体工具（如Claude Code）中的加载、解析和执行逻辑，也不模拟工具特有的交互模式（如多轮对话、工具调用、文件编辑）。

skillprobe：技能在真实环境中的“集成测试”/“端到端测试”skillprobe测试的是完整的用户工作流。它启动的是你日常使用的那个带图形界面（以无头模式运行）的Claude Code或Cursor应用。这意味着：

• 测试真实技能加载：技能文件是如何被工具发现和解析的？技能之间的优先级和冲突如何处理？这些只有在真实工具中才能测试。
• 测试完整的交互链：用户输入提示词 -> AI思考并可能调用技能 -> AI可能使用工具（Bash, File Editor） -> 工具执行并返回结果 -> AI生成最终回复。skillprobe能捕获这个链条中的每一个环节。
• 测试订阅模式：许多用户使用的是工具的订阅版，而非直接调用API。skillprobe兼容这种模式，因为它启动的就是本地的订阅版客户端。
• 测试文件系统操作：AI通过文件编辑器工具创建、修改文件后，工作区的实际状态变化可以被file_exists等断言精确验证。

简而言之，promptfoo告诉你“这个提示词让模型说了什么”，而skillprobe告诉你“这个技能在真实工具中引导用户完成了什么”。后者对于确保技能在实际开发流程中可靠工作，是不可或缺的。

3. 从零开始：编写你的第一个技能测试

理论说得再多，不如动手实践。让我们从一个最简单的例子开始，为你自己编写的技能创建第一个测试。

3.1 环境准备与安装

首先，确保你的系统已经安装了目标AI工具（Claude Code 或 Cursor）的命令行版本，并且已经完成认证登录。这是skillprobe能够启动它们的前提。

然后，安装skillprobe本身。推荐使用uv（一个快速的Python包管理器和安装器），因为它能更好地处理依赖隔离。

# 安装 uv (如果尚未安装) curl -LsSf https://astral.sh/uv/install.sh | sh # 使用 uv 全局安装 skillprobe uv tool install skillprobe # 验证安装 skillprobe --version

当然，你也可以使用传统的pip：

pip install skillprobe

或者从源码安装以获取最新特性：

git clone https://github.com/Anyesh/skillprobe.git cd skillprobe uv sync # 或 pip install -e .

3.2 剖析一个简单的技能：Python代码清洁技能

假设我们有一个非常简单的技能，名为clean-python.md，其内容如下：

# Clean Python Code When writing Python code, always follow these rules: 1. Use type hints for function arguments and return values. 2. Keep functions small and focused on a single task. 3. Avoid obvious comments that just repeat the code (e.g., `# increment i`). 4. Place imports at the top of the file.

这个技能的目标是引导AI在编写Python代码时遵循一些基本的清洁规范。

3.3 编写对应的测试场景

现在，我们为这个技能编写测试。创建一个名为test-clean-python-basic.yaml的文件。

# test-clean-python-basic.yaml harness: claude-code model: claude-3-5-haiku-20241022 # 使用一个成本较低的模型进行测试 timeout: 60 skill: ./skills/clean-python.md # 假设技能文件在此路径 scenarios: - name: "技能应引导AI为函数添加类型提示" steps: - prompt: "写一个Python函数，接收两个字符串，返回它们的连接结果。" assert: - type: regex value: 'def \w+\(.*: str.*: str.*\) -> str' # 这个正则匹配类似 `def concat(a: str, b: str) -> str` 的模式 - type: contains value: "-> str" # 双重验证，确保返回类型被声明 - name: "技能应阻止明显的无用注释" steps: - prompt: | 写一个循环，遍历列表 `items` 并打印每个元素。 在循环内部添加一个计数器 `i`。 assert: - type: not_contains value: "# increment i" - type: not_contains value: "# loop over items" # 我们断言AI的回复中不应包含这些低价值的注释 - name: "技能不应干扰与Python无关的请求" steps: - prompt: "用JavaScript写一个简单的Hello World函数。" assert: - type: not_contains value: "type hint" - type: not_contains value: "import" # 当请求是非Python代码时，技能相关的关键词不应出现

这个测试套件包含了三个场景：

1. 正向激活测试：验证技能在相关提示下能正确工作（添加类型提示）。
2. 负向约束测试：验证技能能阻止不希望出现的行为（添加无用注释）。
3. 无关请求测试：验证技能在无关的上下文中保持静默，不会“多管闲事”。

3.4 运行测试并解读结果

在终端中，导航到你的项目目录，运行测试：

skillprobe run test-clean-python-basic.yaml

你会看到类似如下的输出：

Running: test-clean-python-basic.yaml Harness: claude-code Model: claude-3-5-haiku-20241022 Scenarios: 3 Parallel: 1 [PASS] 技能应引导AI为函数添加类型提示 (8.5s $0.015) [FAIL] 技能应阻止明显的无用注释 (7.2s $0.013) step 1: "写一个循环，遍历列表 `items` 并打印每个元素。..." Pattern '# increment i' matched in response. [PASS] 技能不应干扰与Python无关的请求 (6.1s $0.011) 2/3 passed (21.8s) Total cost: $0.039

结果解读：

• 第一个场景通过了，说明技能在引导添加类型提示方面是有效的。
• 第二个场景失败了！AI在代码中添加了# increment i这样的注释。这说明我们的技能在阻止低价值注释方面是无效的，或者措辞不够有力。这就是测试的价值——它暴露了我们凭感觉可能发现不了的问题。
• 第三个场景通过了，说明技能没有在不该激活的时候乱入，这是好的。
• 报告还显示了每个场景的运行时间和估算成本（对于Claude Code，基于Token使用量），这对于管理测试预算很有帮助。

注意事项：理解“失败”测试失败不一定是坏事，尤其是早期。它提供了明确的反馈，告诉你技能的哪些部分需要加强。在上面的例子中，我们需要回去修改clean-python.md技能，更加强调“避免无用注释”这一点，或者提供更具体的反面例子。修改后，重新运行测试，观察通过率是否提升。

4. 进阶测试策略：应对概率性、组合与回归

基础的通过/失败测试对于确定性功能是足够的，但对于LLM技能，我们需要更高级的策略来应对其固有的不确定性。

4.1 量化可靠性：多次运行与最小通过率

由于LLM输出的概率性，单次测试通过可能只是运气好，单次失败也可能只是模型“开小差”。因此，skillprobe允许你对一个步骤进行多次运行，并设定一个可接受的最小通过率。

scenarios: - name: "类型提示技能的可靠性测试" steps: - prompt: "写一个函数，计算列表的平均值。" runs: 10 # 将此提示词运行10次 min_pass_rate: 0.8 # 要求至少8次通过（80%的通过率） assert: - type: regex value: 'def \w+\(.*: list.*\) -> float' - type: contains value: "float"

运行后，报告会显示聚合结果：

[PASS] 类型提示技能的可靠性测试 (42.1s $0.075) step 1: [ok] 9/10 passed (90%)

这比单次测试提供了更强的信心。但问题来了：min_pass_rate: 0.8这个阈值是拍脑袋决定的吗？我们如何知道一个场景的“自然”通过率是多少？这就是skillprobe measure命令的用武之地。

4.2 测量自然方差：为阈值寻找科学依据

在设定min_pass_rate之前，你应该先测量该场景在当前模型和技能版本下的基准表现。

skillprobe measure test-clean-python-basic.yaml --runs 30

这个命令会忽略缓存，将每个场景运行30次，并输出详细的统计报告：

Measuring: test-clean-python-basic.yaml Harness: claude-code Model: claude-3-5-haiku-20241022 Runs per scenario: 30 Scenario: 技能应引导AI为函数添加类型提示 Assertion `regex 'def \w+\(.*: str.*: str.*\) -> str'`: Pass rate: 93.3% (28/30) 95% Wilson CI: [78.7%, 98.1%] Variance: probabilistic Assertion `contains '-> str'`: Pass rate: 100.0% (30/30) 95% Wilson CI: [88.6%, 100.0%] Variance: deterministic Scenario: 技能应阻止明显的无用注释 Assertion `not_contains '# increment i'`: Pass rate: 40.0% (12/30) 95% Wilson CI: [24.6%, 57.7%] Variance: noisy

报告解读：

• 通过率：第一个断言（类型提示）有93.3%的通过率，相当可靠。第二个断言（无用注释）只有40%的通过率，说明技能在这个要求上基本是失效的。
• 95%置信区间：这是一个统计学概念，表示我们有95%的把握认为，该断言的真实通过率落在这个区间内。例如[24.6%, 57.7%]这个很宽的区间，表明我们还需要更多数据才能对通过率有一个精确的估计。区间越窄，估计越准。
• 方差分类：
  • deterministic(确定性): 通过率接近100%，表现稳定。
  • probabilistic(概率性): 通过率较高（如>80%）但非100%，是LLM技能的典型表现。
  • noisy(嘈杂): 通过率在中等范围（如30%-70%），表现不稳定。
  • unreliable(不可靠): 通过率很低（<30%）。

基于这个测量结果，我们可以做出更明智的决策：

• 对于“类型提示”断言，我们可以有信心地设置min_pass_rate: 0.85或0.9。
• 对于“无用注释”断言，当前技能版本根本无法达到可接受的可靠性（比如0.8）。我们需要重新设计或加强这个技能指令，而不是盲目提高测试容忍度。也许需要提供更具体的反面例子，或者改变指令的表述方式。

4.3 测试技能组合：发现冲突与协同

真实的开发环境中，我们往往会同时加载多个技能。一个“代码清洁”技能和一个“快速原型”技能可能会产生冲突。skillprobe允许你在一个测试套件中加载多个技能进行组合测试。

# test-skill-combo.yaml harness: claude-code model: claude-3-5-sonnet-20241022 skills: # 使用 skills 列表加载多个技能 - ./skills/clean-python.md - ./skills/explain-thoroughly.md # 假设这个技能要求AI为代码添加详细解释 scenarios: - name: "组合技能：清洁代码与详细解释的平衡" steps: - prompt: "实现一个函数，判断一个数是否为素数。" runs: 5 min_pass_rate: 0.6 # 组合下要求可能降低 assert: - type: regex value: 'def is_prime\(n: int\) -> bool' # 清洁技能要求类型提示 - type: contains value: "素数" # 解释技能要求中文解释 - type: contains value: "质数" # 另一种说法 - type: not_contains value: "显而易见" # 清洁技能可能反对的模糊注释

运行这个测试，你可能会发现一些有趣的现象：

• 通过率下降：组合技能的通过率可能低于单个技能。
• 输出矛盾：AI的回复可能同时包含类型提示和详细解释，但解释部分可能过于冗长，违反了“清洁”的原则。
• 技能竞争：在某些情况下，可能只有一个技能被显著激活。

测试组合技能能帮你发现技能设计中的隐含冲突，从而有机会去调整技能的优先级、修改措辞以避免矛盾，或者创建新的“协调”技能来处理特定组合。

4.4 矩阵测试与基线分析：系统性排查组合回归

当你有一个核心技能（例如团队内部代码规范），需要确保它与一系列其他常用技能（如第三方库的专用技能、代码审查技能等）兼容时，手动为每一对组合编写测试套件是繁琐的。skillprobe的矩阵测试功能可以自动化这个过程。

# test-matrix.yaml harness: claude-code model: claude-3-5-haiku-20241022 matrix: base: ./skills/our-code-style.md # 我们的核心规范技能 pair_with: # 需要与之测试兼容性的技能列表 - ./skills/third-party-lib-a.md - ./skills/third-party-lib-b.md - ./skills/rapid-prototyping.md - ./skills/security-audit.md scenarios: # 这个场景会针对每一对(base, pair_with)组合运行 - name: "核心规范在组合中仍被遵守" steps: - prompt: "使用库A（或B）写一个数据处理的示例。" runs: 3 min_pass_rate: 0.66 assert: - type: contains value: "# OUR_TEAM_STANDARD_HEADER" - type: regex value: '^def .+\(.*\) -> .+:' # 我们的规范要求类型提示

运行skillprobe run test-matrix.yaml，你会得到一个报告，清晰地显示our-code-style与列表中每一个技能配对时的测试结果。这能快速识别出哪个第三方技能与我们的核心规范冲突最大。

但矩阵测试只告诉你“组合失败了”。它无法区分失败是因为组合产生了新的问题，还是因为某个技能本身就有问题。这就是基线模式的价值。

skillprobe run test-matrix.yaml --baseline --baseline-runs 15

加上--baseline参数后，skillprobe会为矩阵中的每一个配对进行三轮测试：

1. 只运行base技能。
2. 只运行pair_with技能。
3. 同时运行base和pair_with技能。

然后，它会比较三轮测试的结果，将每个断言分类：

• 回归：单独运行base和pair_with都通过，但组合运行时的通过率显著下降（下降幅度超过--regression-margin，默认0.15）。这是你需要重点关注和修复的真正组合问题。
• 共享失败：单独运行和组合运行都失败了。这说明问题出在测试场景本身，或者某个技能本身就有缺陷，不是组合导致的。
• 不稳定：组合运行的通过率有所下降，但下降幅度在误差范围内。这可能只是正常的概率波动，需要关注但优先级较低。
• 正常：组合运行的表现与单独运行相当或更好。

基线分析是确保技能生态健康性的强大工具，尤其适合在发布新技能版本或引入新第三方技能前进行集成验证。

5. 集成到CI/CD流程：让技能测试自动化

技能的可靠性不是一次性的工作，而需要持续守护。将skillprobe集成到你的CI/CD（持续集成/持续部署）流水线中，可以在每次技能文件变更或模型更新时自动运行测试，及时捕获回归。

5.1 GitHub Actions 配置示例

以下是一个完整的GitHub Actions工作流配置示例，它会在技能文件或测试文件变更时触发测试，并每周定时运行一次以应对潜在的模型更新。

# .github/workflows/skill-tests.yml name: Skill Tests on: push: paths: - 'skills/**' # 技能文件变更时触发 - 'tests/**' # 测试文件变更时触发 - '.github/workflows/skill-tests.yml' # 工作流自身变更时触发 pull_request: paths: - 'skills/**' - 'tests/**' schedule: - cron: '0 2 * * 1' # 每周一凌晨2点运行（UTC时间），监测模型更新 jobs: test-skills: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup Python with uv uses: astral-sh/setup-uv@v4 with: version: "latest" - name: Install Claude Code CLI run: npm install -g @anthropic-ai/claude-code # 注意：CI环境中需要提供认证方式，见下文。 - name: Install skillprobe run: uv tool install skillprobe - name: Run skillprobe tests run: | skillprobe run tests/critical-skills.yaml \ --harness claude-code \ --model claude-3-5-haiku-20241022 \ --parallel 2 \ --timeout 180 env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} # 对于Claude Code，通常需要API Key。 # 对于Cursor，可能需要设置其他环境变量或使用已登录的配置。

5.2 CI环境下的关键挑战与解决方案

在无头（headless）的CI服务器上运行GUI工具的测试，会面临一些特殊挑战：

1. 认证与授权

• Claude Code：通常需要通过ANTHROPIC_API_KEY环境变量提供API密钥。你可以将密钥存储在GitHub仓库的Secrets中。
• Cursor：认证机制可能更复杂，可能依赖于本地配置文件或OAuth。在CI中，你可能需要预先通过某种方式（如在构建步骤中运行一次交互式登录并缓存token）来设置认证状态。这通常需要更复杂的脚本。

2. 资源与超时

• CI runner的资源（CPU、内存）可能有限，而LLM推理和工具调用是计算密集型任务。
• 对策：使用更轻量的模型进行CI测试（如claude-haiku），并适当增加--timeout。使用--parallel可以加速，但需注意不要超过runner的资源限制。

3. 成本控制

• 在CI中自动运行测试会产生API调用费用。
• 对策：
  • 使用--max-cost参数为每个子进程设置花费上限（Claude Code支持）。
  • 精心设计测试场景，避免冗长、昂贵的提示词。
  • 利用skillprobe的缓存功能（默认开启）。只要技能文件、提示词、模型和skillprobe版本未变，测试结果就会从缓存中读取，不会产生新的费用。在CI中，你可以考虑配置一个更长的缓存TTL，或者跨工作流共享缓存目录（如使用actions/cache）。

4. 测试稳定性

• CI环境可能不如本地环境稳定，网络波动可能导致超时。
• 对策：为关键测试设置合理的重试机制。虽然skillprobe本身没有内置重试，但你可以在GitHub Actions的步骤级别使用continue-on-error和重试逻辑，或者只将最核心、最稳定的测试场景放入CI。

5.3 测试策略建议：分层测试金字塔

借鉴软件测试的金字塔模型，为你的技能测试也建立一个分层策略：

• 底层（单元测试）：使用skillprobe measure对单个技能的核心断言进行大量重复运行（如50-100次），建立其基准通过率和置信区间。这些测试运行成本较高，可以安排在夜间或每周执行。
• 中层（集成测试）：使用skillprobe run运行主要的组合测试套件和矩阵测试。这些测试覆盖了技能间的交互，是CI流水线中的核心环节，应在每次Pull Request时运行。
• 高层（端到端测试）：模拟真实的用户工作流，例如“从需求到提交代码”的完整场景。这类测试数量少但价值高，可以作为发布前的验收测试。

通过分层，你可以在保证质量的同时，优化测试速度和成本。

6. 高级技巧与避坑指南

在长期使用skillprobe的过程中，我积累了一些能显著提升效率和可靠性的经验。

6.1 编写健壮断言的技巧

断言是测试的灵魂。一个脆弱的断言会导致测试“flake”（时而通过时而失败），掩盖真正的问题。

避免过度精确的字符串匹配

# 脆弱 assert: - type: contains value: "Here is a Python function that adds two numbers:" # 更健壮 assert: - type: contains value: "def add" - type: regex value: '\(.*:.*int.*,.*:.*int.*\)' # 匹配包含两个int类型参数的函数签名

AI生成的开场白可能每次都不一样。断言应该聚焦于输出的实质内容（生成的代码、调用的工具），而不是无关的叙述文本。

善用regex的灵活性正则表达式是处理LLM输出变化的利器。

• .*匹配任意字符（包括换行）。
• \s*匹配任意空白字符（包括空格、制表符、换行），用于处理格式差异。
• 使用(?s)标志使.匹配换行符，进行多行匹配。

assert: - type: regex value: '(?s)def calculate_average.*:.*list.*:.*float' # 跨行匹配函数定义

组合使用多种断言类型不要只依赖一种断言。结合contains,not_contains,tool_called,file_exists来多角度验证行为。

steps: - prompt: "请创建一个名为config.yaml的配置文件，并设置debug: false" assert: - type: tool_called value: "File Editor" # 验证AI使用了文件编辑器工具 - type: file_exists value: "config.yaml" # 验证文件被创建 - type: file_contains value: "debug: false" # 验证文件内容正确

6.2 性能优化与成本控制

测试LLM技能既耗时间也耗金钱（API调用）。以下策略可以帮助你优化：

1. 充分利用缓存skillprobe的缓存是其核心优化。理解其缓存键的组成：

• 技能文件的内容哈希
• 测试场景的YAML内容哈希（包括提示词、断言）
• 使用的模型和工具 (harness)
• skillprobe的版本号

这意味着：

• 只要你的技能或测试文件没有改动，重新运行测试几乎是瞬间完成的（[cache hit]）。
• 在CI中，你可以使用actions/cache动作来持久化~/.cache/skillprobe目录，从而在不同工作流运行之间共享缓存，大幅节省成本和时间。
• 如果你在调试测试，可以临时使用--no-cache或--force-refresh来绕过缓存。

2. 并行执行使用--parallel N参数可以同时运行N个场景。这对于有多个独立场景的测试套件提速明显。但要注意：

• 并行度受限于你的机器CPU/内存和AI工具的并发能力。
• 每个并行进程都会启动一个独立的AI工具实例，可能会消耗更多内存。
• 在CI中，根据runner的配置选择合适的并行数（通常2-4）。

3. 选择性价比高的模型

• 在开发和CI中使用成本较低的模型，如claude-3-5-haiku。
• 在发布前或对质量要求极高的测试中，再使用claude-3-5-sonnet或更强大的模型进行最终验证。
• 你可以在测试套件YAML中指定model，也可以通过--model命令行参数覆盖。

4. 设置超时和成本上限

• --timeout：防止某个场景因AI“卡住”而无限期运行。
• --max-cost(Claude Code)：为每个测试运行设置一个硬性的成本上限，避免意外产生高额费用。

6.3 调试失败的测试

当测试失败时，skillprobe的报告会指出哪个断言失败了。但有时你需要更详细的信息来理解AI到底做了什么。

1. 查看详细输出运行测试时，可以添加-v或--verbose标志来获取更详细的日志，包括AI工具的标准输出和错误输出。这对于诊断启动问题或超时问题特别有用。

2. 检查临时工作区（高级）测试运行时，临时工作区默认在测试结束后被删除。你可以在运行测试时设置环境变量SKILLPROBE_KEEP_WORKSPACES=1来保留这些目录。然后去系统的临时目录（如/tmp）下查找以skillprobe-开头的文件夹，里面就是测试运行时的完整现场。你可以查看AI创建或修改了哪些文件，这往往是理解失败原因的关键。

3. 手动复现场景有时，最直接的调试方式就是手动模拟测试场景。按照测试YAML中的设置，创建一个相同的工作区，手动在Claude Code或Cursor中输入相同的提示词，观察AI的完整交互过程。你可能会发现一些测试中未捕获的细微差别，比如AI多问了一个澄清性问题，或者工具调用的顺序不同。

6.4 安全须知

skillprobe为了进行真实的测试，赋予了AI工具相当大的权限：

• setup命令以你的用户权限执行。
• AI工具运行时带有--dangerously-skip-permissions(Claude Code) 或--force(Cursor) 标志，意味着它可以访问和修改你系统上的任何文件（尽管skillprobe会尝试将它的工作目录限制在临时空间）。

因此，务必牢记：

• 将测试YAML文件视为可执行代码。不要运行来自不信任来源的YAML文件。
• 在隔离环境中运行不熟悉的测试。可以考虑在虚拟机、容器或专用的CI runner中运行。
• 仔细审查setup命令。确保其中没有恶意命令。

skillprobe在文件路径断言（file_exists,file_contains）中加入了边界检查，以防止AI工具试图访问工作区之外的文件，但这并非万无一失。保持警惕是安全的最佳实践。

7. 总结与展望：构建可靠的技能工作流

经过以上深入的探讨，我们可以看到，skillprobe不仅仅是一个测试工具，它更是一种方法论，一种将概率性的LLM技能开发推向工程化、可靠化的实践。

它的价值在于将“我觉得这个技能好用”的主观感受，转化为“这个技能在20次测试中通过了18次，在与此技能组合时通过率下降了15%”的客观数据。这种转变对于个人开发者、团队协作乃至产品化都至关重要。

在实际操作中，我建议将skillprobe融入你的技能开发工作流：

1. 编写技能->立即编写基础测试：养成习惯，为每个新技能或重大修改同时编写对应的测试场景。这有助于在早期定义“成功”的标准。
2. 使用measure建立基线：在设定min_pass_rate之前，先运行skillprobe measure来了解技能在当前模型下的自然表现，用数据代替猜测。
3. 在CI中运行核心测试：将最关键的功能测试和组合测试集成到CI中，确保每次变更都不会破坏核心用例。
4. 定期进行矩阵与基线测试：每周或每月运行一次全面的矩阵和基线分析，主动发现技能生态中潜在的冲突和回归，而不是等到用户报告问题。
5. 迭代与优化：将测试失败视为宝贵的反馈，用于持续优化技能指令的措辞、结构和优先级。

随着AI编程工具的不断进化，技能的复杂性和重要性只会与日俱增。skillprobe提供了一套切实可行的框架，帮助我们在享受AI辅助编程强大能力的同时，建立起必要的质量护栏和信心。它让技能的开发从一门“艺术”，逐渐向一门可测量、可验证、可重复的“工程”学科靠拢。