Glitch Toolkit

glitch

已经不再拒绝请求的检查，仍然会通过。 这就是本工具要查找的故障。

2026 年 9 月 8 日，在提取出此软件包的代码仓库中，有一项测试用于保护一本付费书籍中免费赠送的唯一章节——它断言样章会在截断处停止，不会泄露其余内容。测试通过了。它搜索的是一个根本没有书的页面，自然也找不到任何段落，却仍然通过了。没有任何东西出问题；脱敏工作正常。警报器已断开，却仍亮着绿灯。

每一道护栏最终都会这样退化，而且这种退化悄无声息，因为不再拒绝任何内容的护栏，看起来和没有内容可拒绝的护栏一模一样。

glitch 会在你的代码仓库中安装六道护栏，然后在你每次要求时，针对一个理应拒绝的案例运行每一道护栏。任何一道不再拒绝任何内容的护栏，都会在这里大声报错，而不是悄悄通过。

pip install glitch-toolkit

glitch install     # put the artifacts in this repository
glitch status      # what is installed, what is not
glitch check --all # verify every step

没有依赖项、没有网络调用、没有遥测。它不会在你指定目录之外写入任何内容。

它实际检查的内容

文件存在，并不意味着一个步骤就已完成。每项检查都会执行以下三项操作，并报告其中哪些操作失败：

1. 查找产物
2. 运行产物，并期望它能正常工作
3. 针对一个刻意构造的错误案例运行产物，并期望它会拒绝

如果没有第三项，只要你复制了一个文件，检查就会通过，无论这个文件是否还起作用；而且它会永远对每位读者显示绿灯。tests/test_cli.py 的存在就是为了证明检查器会在这种情况下失败；它的 SABOTAGE 测试会安装能够运行、以 0 退出，却什么都不拒绝的产物。

install 不会做什么

它不会写入你的 CLAUDE.md、FLEET.md、FLOOR.md 或 PLAN.md。六个步骤中有四个会根据你自己的文件进行检查，因为对这四个步骤来说，文件本身就是工作成果：一份有效的规则文件、一张只有一名提交者的值班表、一份经过两次测量的楼层图、一份经他人批准的计划。要是命令替你写好这些文件，这条路径就会变成“你运行了一个安装程序”。FLOOR.md 和 PLAN.md 模板也特意设计成无法通过检查，原因相同。

它不会覆盖文件。代码仓库中已有的产物会保留原样，并报告为已保留；使用 --force 可以明确要求覆盖。

它不会在你指定目录之外写入任何内容，不会进行网络调用，也不依赖标准库以外的任何内容。

不安装也能运行

cli.py 是单个文件，并且始终保持为单个文件。将它复制到一个代码仓库中，无需设置路径，也无需安装，就能使用 status 和 check——这是有意为之，而且有测试验证它使用的搜索路径。只有 install 需要软件包的其余部分；它会明确说明这一点，而不会莫名其妙地失败。

MCP 服务（只读）

uvx --from 'glitch-toolkit[mcp]' glitch-mcp --repo .

请在隔离环境中安装额外依赖，不要安装到系统 Python 中。 检查器没有依赖，这是我们的承诺。[mcp] 额外依赖则恰恰相反：mcp>=2.0 会拉取 pydantic、starlette、cryptography、opentelemetry 以及另外十几个依赖，而 pip 会毫不犹豫地升级已有的软件包来满足这些依赖。2026 年 9 月 8 日，在全局解释器中安装时，它把 pydantic 1.10 替换为 2.13，把 starlette 0.46 替换为 1.6，导致同一台机器上一个无关的 FastAPI 应用无法运行。uvx 会构建一个临时环境，不会触碰其他内容，所以注册表条目会以这种方式启动它。

虚拟环境也完全可以：

python -m venv .venv && .venv/bin/pip install 'glitch-toolkit[mcp]'

它向 Agent 提供三个检查工具——glitch_status、glitch_check、glitch_ledger_tail——并将每个问题和答案追加到 .claude/toolkit/ledger/ledger.jsonl。

它不会进行任何门控。 它无法暂停、阻止、拒绝或拦截任何操作。它没有数据库连接、没有凭据，也不会发起网络调用。第一版就是这样设计的：一个位于 Agent 和生产数据库之间的服务，是严肃的软件；正确的做法是先以只读方式运行、读取日志，弄清它本来会拒绝什么，然后再赋予它拒绝的能力。在记录形成之前就构建门控，只是带着权限进行猜测。

这些检查不会向你的代码库写入任何内容。服务只有一处例外——它会向日志追加内容；--no-ledger 可以连这也关闭，但代价是失去唯一值得保留的东西。

在 Claude Code 中，.mcp.json：

{
  "mcpServers": {
    "glitch": { "command": "glitch-mcp", "args": ["--repo", "."] }
  }
}

日志

只追加的 JSONL。任何一行都不会被重写，除非它是刚刚写入的；被新记录取代的记录会标记为已取代，两条记录都会保留；没有测量过的字段值为 null，而不是 0；末尾未完整写入的一行会被跳过并计数，绝不会修复，因为修复意味着重写文件。

测试

python tests/run_all.py      # all three suites, 40 tests

没有安装 [mcp] 额外依赖时，服务测试套件会正常跳过，运行器会将其报告为 SKIPPED，而不是通过；因为绿色的通过标记如果代表“我们没有检查”，正是门控检查实践要防止的问题。

检查的由来

这里的每项检查都源于曾经发生的问题，CORPUS.md 列出了相关内容——发生了什么、造成了什么代价，以及现在由哪项检查捕获。

其中还列出了目前尚无检查能够捕获的问题，包括让这个软件包两次各自增加一个版本号的那两起问题。只记录已解决问题的语料库，会重蹈这个软件包要解决的问题。

许可证

Apache License 2.0——详见 LICENSE 和 NOTICE。选择它而非 MIT，是因为它授予了专利许可。

本代码库中的所有内容都适用该许可证。你可以将其用于商业用途、修改并重新分发。

上面的链接有意使用绝对路径：此 README 也是该软件包在 PyPI 上的说明，而相对链接会以 pypi.org 为基准解析，返回 404。

本项目的由来

本代码库是一个已发布的镜像。该软件包在一个私有单体仓库中开发，与书籍 Building Your Store Or Your SaaS With Claude 并列；本软件包实现并检查书中的实践，并作为子树推送到这里。这本书、销售它的商店以及该仓库的其他内容都不是开源的，也不在这里。本软件包所属的内容没有任何被排除在这个代码库之外。

问题和拉取请求应提交到这里，而不是那里，因为这里是任何人都可以阅读的部分。

状态

版本为 0.1.1。它可以安装，并且会检查本书倡导的六项实践。0.1.0 是首个版本；0.1.1 修改了此说明并添加了持续集成，但没有改变代码的行为。

目前尚未实现的功能：它不会阻止任何操作。glitch-mcp 只会报告并记录，无法阻止 Agent 执行任何操作。这是有意为之，原因已在 mcp_server.py 中说明——一个处于 Agent 与生产数据库之间的服务，应先用证据证明自身，再获得拒绝操作的权力。