evolveguard

evolveguard

功能介绍 • 快速开始 • CLI 参考 • Agent 原生用法 • MCP 服务 • 比较 • 常见问题

在 Claude Agent Skill 或 Claude Code MEMORY.md 文件自行编辑后、变更发布前，检测其行为漂移。

# PyPI -- Python CLI + library (genuine port, not a Node wrapper)
pip install evolveguard-cli

# npm -- JavaScript/TypeScript CLI + library
npm install -g evolveguard-cli

说明

两个软件包均已发布，且名称一致：PyPI 上的 evolveguard-cli 和 npm 上的 evolveguard-cli（于 2026-07-19 从原来的 plain evolveguard 更名；旧名称现已在两个软件包仓库中弃用）。npm install -g evolveguard-cli 和 pip install evolveguard-cli 目前都可以正常使用；下方的演示 GIF 均录制自已发布的软件包， 而非本地构建版本。

功能介绍

evolveguard record ./SKILL.md --fixtures ./fixtures.json
# ... skill gets edited, by a human or an agent ...
evolveguard check ./SKILL.md

EvolveGuard v0.2.0 -- Regression Check
skill: monorepo-scanner  baseline: 2026-07-15  fixtures: 1

[DRIFT] fixture: "scan a monorepo"  new tool call: fs.write (baseline had none)
         -> new tool call: fs.write (baseline had none) -- this edit introduces a
            capability the baseline never used

0 PASS, 1 DRIFT, 0 FAIL
exit code 1 (DRIFT blocks merge by default; override with --allow-drift)

这是本仓库自身 fixtures/labeled-non-breaking-edits/case-03-add-write-capability/ 测试用例的实际输出，该用例将技能 frontmatter 中的 filesystem: read-only 改为 read-write。 你也可以亲自复现：对该文件夹中的 before/SKILL.md 运行 evolveguard record，并使用其 fixtures.json；然后对 after/SKILL.md 运行 evolveguard check。

功能

静态分析，不运行实时 Agent。 record 会解析技能文件的 YAML frontmatter（声明的 tools、network、filesystem、scope 以及任何捆绑的 hooks），扫描技能正文和钩子脚本，查找网络调用或文件系统写入的证据，并将两者合并为能力面。check 会用相同逻辑重新解析编辑后的文件并比较差异。TypeScript 和 Python 发行版中的这两个命令都不会运行 eval、启动子进程或执行技能的钩子脚本。

两级差异比较可捕获单个 fixture 可能遗漏的变化。 每个 fixture 的 expectedToolCalls 会筛选记录的能力面，只保留该 fixture 关心的内容，但 check 也会单独比较技能的_完整_能力面。即使某项新能力恰好未被任何 fixture 的 expectedToolCalls 覆盖，也会显示为 surfaceChanges 条目，而不会悄然通过。已在本仓库自己的 case-04-scope-widened fixture 中确认：fs.write 的范围从 ./workspace/** 扩大到了 ./**。

在已标注语料上可复现地实现 0% 误报。 npx vitest run src/evolveguard/benchmark.test.ts 会针对 fixtures/labeled-non-breaking-edits/ 运行 record/check/diff 流程：2 个人工标注为非破坏性的案例（措辞调整、修复拼写错误）和 3 个标注为破坏性的案例（新增写入能力、扩大范围、钩子脚本新增网络调用）。截至此提交，两个非破坏性案例均未触发告警：2 个案例中有 0 个被标记为存在漂移。语料规模较小，并会随着更多真实技能编辑案例的报告而增长。

针对钩子脚本的路径遍历防护。 读取技能声明的钩子路径之前，会先解析并验证这些路径是否位于该技能自己的目录中；即使通过了词法包含性检查，还会再次检查是否通过符号链接逃逸（src/evolveguard/paths.ts 和 python/src/evolveguard/paths.py）。

每个子命令都支持 --json。 record、check 和 report 都接受 --json 标志，并返回带稳定 schemaVersion 标记的结构，因此编码 Agent 可以将其中任一命令作为子进程调用，并直接解析其结果。

两个独立维护、格式兼容的发行版。 npm 包（TypeScript，仓库根目录）和 PyPI 包（Python，python/）会解析相同的 frontmatter 架构，并生成字节兼容的基线和报告 JSON。可以用一个 CLI 记录基线，再用另一个 CLI 检查；文件格式详情请参阅docs/concepts.md。

evolveguard 会检测技能_声明或展示_的能力变化。它不会运行实时大模型 Agent，也不会重放真实对话记录，因此无法判断 Agent 在给定提示词下是否会有不同表现。这是有意设定的范围限制，也正因如此，它不依赖任何托管服务，并能在预提交钩子或 CI 任务中完全离线运行。

快速入门

# 1. Record a baseline against a skill and its labeled fixtures
evolveguard record ./skills/my-skill/SKILL.md --fixtures ./fixtures/my-skill.json
# writes ./skills/my-skill/.evolveguard-baseline.json

# 2. Edit the skill (by hand, or let an agent edit it)

# 3. Check for drift
evolveguard check ./skills/my-skill/SKILL.md
# writes ./evolveguard-report.json, exits 1 if drift was found

fixtures 文件是一个 JSON 数组，包含带标签的提示词以及每条提示词预期会触及的工具调用形态：

[
  {
    "id": "scan-a-monorepo",
    "prompt": "scan a monorepo",
    "expectedToolCalls": [{ "tool": "fs.read" }, { "tool": "fs.write" }]
  }
]

expectedToolCalls 是可选项；省略后，fixture 会被视为覆盖技能的整个能力面。scopeMatches（一个 glob）可将工具范围限定到特定文件系统范围，例如 { "tool": "fs.write", "scopeMatches": "./workspace/**" }。

CLI 命令参考

根据已安装 CLI 的实际 --help 输出生成（已对照 npm 和 PyPI 版本验证；各发行版的标志和默认值相同）。

Usage: evolveguard [options] [command]

Regression-testing CLI for self-edited Claude Agent Skills (SKILL.md,
MEMORY.md) -- golden-transcript record/replay against a skill's own declared
and inferred capability surface, zero hosted infrastructure.

Options:
  -V, --version                  output the version number
  -h, --help                     display help for command

Commands:
  record [options] <skillPath>   Record a golden-transcript baseline for a
                                 skill against a set of labeled fixtures
  check [options] <skillPath>    Replay the fixtures from a baseline against
                                 the current (possibly edited) skill and report
                                 drift
  report [options] [reportPath]  Print a previously generated
                                 evolveguard-report.json
  mcp                            [coming soon] Expose record/check/report as
                                 MCP tools for a coding agent to call
                                 mid-session
  help [command]                 display help for command

Usage: evolveguard record [options] <skillPath>

Record a golden-transcript baseline for a skill against a set of labeled
fixtures

Arguments:
  skillPath          path to the SKILL.md or MEMORY.md file to baseline

Options:
  --fixtures <path>  path to a fixtures JSON file (array of {id, prompt,
                     expectedToolCalls?})
  --baseline <path>  path to write the baseline file (default:
                     <skill-dir>/.evolveguard-baseline.json)
  --json             output structured JSON instead of human-readable text
                     (default: false)
  -h, --help         display help for command

Usage: evolveguard check [options] <skillPath>

Replay the fixtures from a baseline against the current (possibly edited) skill
and report drift

Arguments:
  skillPath          path to the SKILL.md or MEMORY.md file to check

Options:
  --baseline <path>  path to the baseline file (default:
                     <skill-dir>/.evolveguard-baseline.json)
  --report <path>    path to write the report file (default:
                     "./evolveguard-report.json")
  --allow-drift      exit 0 even if drift is detected (drift is still reported)
                     (default: false)
  --json             output structured JSON instead of human-readable text
                     (default: false)
  -h, --help         display help for command

Usage: evolveguard report [options] [reportPath]

Print a previously generated evolveguard-report.json

Arguments:
  reportPath  path to the report file (default: "./evolveguard-report.json")

Options:
  --json      output structured JSON instead of human-readable text (default:
              false)
  -h, --help  display help for command

退出代码： 0 所有 fixture 均通过（PASS），且没有表层漂移；1 发现至少一项漂移（DRIFT）（传入 --allow-drift 后，即使报告漂移也仍以代码 0 退出）；2 用法错误或文件解析失败。

警告

npm 版本的 evolveguard --version 目前会输出 0.1.0，但已发布的软件包版本比 package.json 中的版本更新；PyPI 版本从已安装的软件包元数据中读取版本，因此报告的版本正确。如果需要获取 npm 软件包当前已发布的准确版本号，请查看上方徽章，而不要使用 --version。

面向 Agent 的原生用法

每个子命令都支持 --json，可输出 Agent 能直接解析的结构化数据：

evolveguard check ./SKILL.md --json

{
  "schemaVersion": 1,
  "skillName": "monorepo-scanner",
  "results": [
    {
      "id": "scan-a-monorepo",
      "verdict": "DRIFT",
      "changes": [/* ... */]
    }
  ],
  "surfaceChanges": [],
  "summary": { "pass": 0, "drift": 1, "total": 1 },
  "exitCode": 1
}

说明

Python 发行版附带一个真正的 MCP 服务（参见下方的 MCP 服务）。 npm/TypeScript 发行版的 evolveguard mcp 子命令仍是“即将推出”的占位实现；在该功能推出之前，可以从编码 Agent 中直接将 record/check/report --json 作为子进程调用，也可以使用 Python MCP 服务，即使工具链的其他部分使用的是 npm 软件包。

MCP 服务

Python 发行版（PyPI 上的软件包名为 evolveguard-cli）附带一个模型上下文协议服务，因此，兼容 MCP 的 Agent（如 Claude Desktop、Claude Code 等）可以直接调用 evolveguard，而无需通过 shell 调用并解析文本。npm/TypeScript 发行版目前尚未附带 MCP 服务——其 evolveguard mcp 子命令仍是占位实现。

pip install "evolveguard-cli[mcp]"

将其添加到 MCP 客户端的配置中，例如 Claude Desktop 的 claude_desktop_config.json：

{
  "mcpServers": {
    "evolveguard": {
      "command": "evolveguard-mcp"
    }
  }
}

该服务仅公开一个工具 run(args: list[str])，它会使用你在终端中输入的确切 argv 调用已安装的 evolveguard CLI，并返回 {returncode, stdout, stderr, json?}（如果命令失败、超时或以非零代码退出，则返回 {error: ...}）——因此，一个工具即可涵盖 record、check 和 report，无需为每个子命令单独定制 MCP 工具。Agent 调用示例：

{ "tool": "run", "arguments": { "args": ["check", "./SKILL.md", "--json"] } }

返回的结构化报告与 evolveguard check ./SKILL.md --json 的输出相同，另外还包含原始的 returncode/stdout/stderr。

库 API

evolveguard 还针对相同的流程提供了编程 API，供希望将其集成到自有工具中、而非通过 shell 调用 CLI 的团队使用。两个发行版公开相同的函数，并使用兼容 JSON 的相同文件格式；可以使用一个 CLI 记录基线，再用另一个进行检查（参见 docs/concepts.md）。

TypeScript：

import {
  recordBaseline,
  replaySkill,
  diffAll,
  writeBaseline,
  readBaseline,
} from 'evolveguard';

const baseline = recordBaseline('./SKILL.md', './fixtures.json');
writeBaseline('./.evolveguard-baseline.json', baseline);

// ... skill gets edited ...

const saved = readBaseline('./.evolveguard-baseline.json');
const replay = replaySkill('./SKILL.md', saved);
const report = diffAll(saved, replay);

完整的导出内容请参见 src/evolveguard/index.ts：parseSkillFile、 deriveCapabilitySurface、loadSkill、buildFixtureSnapshots、loadFixtures、 recordBaseline、replaySkill、diffFixture、diffAll、diffSurface、writeBaseline、 readBaseline、writeReport、readReport，以及共享的 types.ts 接口。

Python（pip install evolveguard-cli）：

from evolveguard import record_baseline, replay_skill, diff_all, write_baseline, read_baseline

baseline = record_baseline("./SKILL.md", "./fixtures.json")
write_baseline("./.evolveguard-baseline.json", baseline)

# ... skill gets edited ...

saved = read_baseline("./.evolveguard-baseline.json")
replay = replay_skill("./SKILL.md", saved)
report = diff_all(saved, replay)

Python 专属的使用指南以及 evolveguard/__init__.py 中导出的相同内容，请参见 python/README.md。

对比

Braintrust 是一个通用的大模型评估与可观测性平台。如果你已经在记录线上 Agent 的追踪信息，并希望对多次运行进行统计评估打分，它是个不错的选择；但它需要集成 SDK，并为每个应用定义评估。

evolveguard 两者都不需要：只需指定一个 SKILL.md 文件和一个 fixtures JSON，即可使用。

agent-eval（同一作者的另一个仓库）要解决的是另一个问题：判断你定义的两个版本之间，Agent 的行为是否发生变化。它适用于任何 Agent，且与框架无关；你需要自行运行两个版本，并计算差异的 p 值。evolveguard 则由 SKILL.md/MEMORY.md 文件差异直接触发，用来判断_这次具体编辑_是否改变了基线记录的能力范围。它会解析技能文件本身，不需要你定义或运行任何线上内容。

evolveguard 是什么，为什么会有它

evolveguard 是一个命令行工具和 TypeScript 库，用于检测由人或 Agent 编辑后的 Claude Agent Skill 文件（SKILL.md）和 Claude Code 自动记忆文件（MEMORY.md）中的能力漂移。它会解析技能文件声明的 frontmatter 作用范围，以及正文和随附钩子脚本中静态体现的网络或文件系统写入行为，并将其快照保存为基线；编辑后再重新生成相同快照，与基线进行差异比较。之所以开发它，是因为 Claude Code 的 Agent Skills 生态系统允许技能文件和记忆文件改变 Agent 的行为，却不一定有人工逐一审核每次编辑是否造成回归；而现有工具中没有任何工具能检查这种特定的文件形态，同时又无需集成 SDK 或运行线上 Agent。

状态

这是一个 v0.1 版本：对现有 Claude Agent Skills 生态系统的一项小型、专注的补充。它完全采用 MIT 许可证发布，没有专有版本，提供两个独立且同等重要的包：

• PyPI（evolveguard-cli，Python），已在 pypi.org/project/evolveguard-cli 发布。这是一个真正独立的移植版本，并非 Node 二进制文件的封装（参见 python/README.md）。直接运行 pip install evolveguard-cli 即可安装。该包最初以 evolveguard 之名发布；旧的 PyPI 项目现已停用，不再接收更新，请改为安装 evolveguard-cli。
• npm（evolveguard-cli，TypeScript），已在 npmjs.com/package/evolveguard-cli 发布。直接运行 npm install -g evolveguard-cli 即可安装。该包于 2026-07-19 从原来的 evolveguard 更名而来；旧名称现已弃用。此次更名是为了与 PyPI 包的命名规则保持一致。

常见问题

evolveguard 到底是什么？ 它是一款命令行工具和库，用于检测 Claude Agent Skill 文件（SKILL.md）和 Claude Code 自动记忆文件（MEMORY.md）在编辑后是否发生了能力漂移。它不是自我进化的 Agent 框架，也不会自行构建、运行或托管 Agent。它是一个回归测试 CI 门禁，在技能产物文件已经被人或 Agent 修改后，根据文件差异作出响应。完整定义请参阅上文“evolveguard 是什么，以及它为何存在”。

evolveguard 会调用大模型吗？ 不会。record 和 check 都完全静态且确定；每条命令具体解析和扫描的内容请参阅上文“功能”。

与通用测试或评估工具相比，它的核心差异是什么？ 它不需要任何托管服务，也不需要集成：指定一个 SKILL.md 文件和一个 fixtures JSON 后，record/check 就能立即运行，无需集成 SDK，也不需要运行实时 Agent。这正是上文“对比情况”表格所记录的取舍：范围比通用评估平台窄，但无需任何设置。

evolveguard 与 Braintrust 相比如何？ Braintrust 是一个通用大模型评估与可观测性平台，需要集成 SDK 并定义评估，而且会对实时 Agent 运行产生的真实轨迹评分。evolveguard 两者都不需要；它直接解析技能文件，且从不调用大模型。如果你已经在记录轨迹，并希望跨多次运行进行统计评估评分，请使用 Braintrust。如果你想在提交前或 CI 中检查 SKILL.md/MEMORY.md 编辑是否在未明示的情况下扩大了技能的能力，请使用 evolveguard。完整对比请参阅上文“对比情况”中的表格，其中也包括它与同一作者的 agent-eval 的比较。

它支持没有 frontmatter 的 MEMORY.md 文件吗？ 支持。没有 frontmatter 的文件会以空的声明范围进行解析，因此其能力范围完全来自正文中找到的静态证据。

它支持哪些平台，如何安装？ npm 包要求 Node.js >=20.12（支持 Node 的任意操作系统），使用 npm install -g evolveguard-cli 安装。PyPI 包要求 Python >=3.9，使用 pip install evolveguard-cli 安装。两个发行包都是纯库/命令行包，不包含原生绑定，因此两者都无需执行特定操作系统的构建步骤。

依赖它之前，有什么实际限制需要了解？ 它只能识别_声明或展示的_能力，无法识别运行时行为。某项技能即使通过 check，也仍可能针对特定提示词表现不同，只要这种差异不涉及其能力范围。误报基准测试（见上文“功能”）目前也只是一个包含 5 组前后对比的人工标注小型语料库，并非大型数据集，因此应将 0% 视为初步测量结果，而非统计保证。Python 发行包附带一个真正的 MCP 服务（见上文“MCP 服务”）；npm/TypeScript 的 mcp 子命令仍是“即将推出”的占位实现，而且 npm 构建中的 evolveguard --version 输出目前未跟上软件包实际发布的版本（见上文“CLI 命令参考”）。

这是一个通用的 Agent 进化框架吗？ 不是。请参阅上文“对比情况”。evolveguard 有意不构建或托管自我进化的 Agent 框架；它只测试已经发生的技能/记忆编辑。

evolveguard 可以免费使用吗？包括商业用途？ 可以。它采用 MIT 许可证，不设专有版本或付费版本；请参阅 LICENSE。你可以根据标准 MIT 条款使用、修改和再分发它，包括用于商业项目。

参与贡献

请参阅 CONTRIBUTING.md。每项更改都会在两个发行包中配套测试；对 frontmatter 架构、能力范围推导或差异判定逻辑的更改，必须同时在 src/evolveguard/（TypeScript）和 python/src/evolveguard/（Python）中完成，并在两个测试套件中添加相应的覆盖。

安全

请参阅 SECURITY.md。evolveguard 会读取你指定的本地文件，但绝不会执行这些文件；它不会发起网络调用，也不会运行实时 Agent。

许可证

MIT。请参阅 LICENSE。