Aperture MCP

AI Agent 现在会改写管理你工作的文档——规范、计划、ADR、章程、 AGENTS.md 文件。在编辑过程中，你先前设定的某项约束可能会悄然消失。

Aperture 是一个承诺触发器。 你指定关心的承诺；当某项承诺在两个版本的决策文档之间消失时，它会逐字逐句地标记出来。

捕捉“某项承诺悄无声息地消失”是触发器的工作：发生事件时，它应确定性地触发，而无需征求许可。因此，Aperture 首先将检查部署在最适合的场景中——git pre-commit 钩子 / CI 检查，运行时无需大模型，也无需联网；同时也提供命令行工具和 MCP 服务，供 Agent 在任务过程中调用。MCP 只是一个适配器，并非整个产品。

这是一个信号，而非裁判。 它会触发；由你来调查。 选择启用 · 本地运行 · 绝不使用你的数据训练。

---

它是什么（又不是什么）

Aperture 会比较同一决策的两种文本状态——较早的版本和较新的版本，并指出一种范围明确、具体的决策漂移：被追踪承诺的原文消失。一个引擎，多个使用场景：

• git pre-commit 钩子 / CI 检查——确定性检查。在 commit / PR 事件发生时触发，无模型参与，并自动阻止操作（或发出警告）。
• aperture check 命令行工具——在任意两个 git 状态之间手动运行同一项检查。
• MCP 服务——让 Agent 在编辑时调用检查（作为触发器时效果较弱，因为只有 Agent 选择调用它才会运行，但在任务过程中很有用）。

引擎能做什么、不能做什么：

• ✅ 它能做： 当你逐字列出的承诺存在于版本 A、但在版本 B 中消失时，标记出来——无论跨越不同的 commit、会话还是作者。它会返回结构化且可比较的结果，并在标签上注明自身的盲区。
• ❌ 它不能做： 理解含义。它会进行不区分大小写的子字符串匹配，因此会漏掉被改写 / 弱化 / 转述的承诺（虽然承诺被弱化了，但看起来却像是完整保留）；对于仅被翻译的承诺，它会拒绝判断 / 弃权（它无法跨文字系统逐字比较，因此会返回 degraded，而不是错误标记）；对于仅被重新排版的承诺，它仍可能错误标记（文字位置变了，含义却没变）。它不会对选项排序、评估质量，也不会告诉你某项更改是错误的。这项判断由你来做。 改用确定性的 git 钩子可以让检查可靠触发，但不会扩大它的识别范围。信号依然有限，只做逐字匹配。

一句话概括：Aperture 就是用来查找已消失承诺的 grep，并让它在 commit 时触发——它也足够坦诚，会承认自己看不到什么。

---

快速入门（约 2 分钟）

pip install aperture-mcp   # installs the `aperture` CLI + the MCP server (wire the CLI as a git hook — see below)

PyPI 软件包名为 aperture-mcp，因为纯名称 aperture 已被 PyPI 上的其他项目占用。后缀 -mcp 是历史遗留的软件包命名产物——产品名是 Aperture，MCP 只是它的一个使用场景。一次 pip install 即可获得下方列出的全部三种使用方式。

1. 确定性触发线——git pre-commit hook / CI（无大模型，离线）

创建一个 .aperture.toml，按文件列出必须保留、不得悄然消失的承诺：

fail_on_drop = true

[[watch]]
path = "CHARTER.md"
commitments = ["never train on your data", "data stays on the device"]

aperture check 会比较两个 git 状态，并标记任何消失的监控承诺，要求逐字一致：

aperture check                                    # HEAD vs working tree (default)
aperture check --staged                           # HEAD vs the staged index — for a pre-commit hook
aperture check --ref-a origin/main --ref-b HEAD   # any two refs — for CI on a PR

当监控承诺被删减时，退出码 1 会阻止提交（默认行为）； --warn-only 只会打印发现的问题，不会阻止提交。它仅依赖标准库，不会发起网络请求，也不会运行模型。

将其配置为 pre-commit hook——可以通过 pre-commit 框架（使用此仓库的 .pre-commit-hooks.yaml）：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/jaysinailabs/aperture-mcp
    rev: v0.2.0
    hooks:
      - id: aperture-commitment-drift

……也可以配置为独立的 .git/hooks/pre-commit：

#!/bin/sh
exec aperture check --staged

……或者在 CI 中将它作为 GitHub Action，在每个 PR 上运行（需要设置 fetch-depth: 0，以确保两个版本都可用——参见 examples/github-action/aperture-check.yml）：

- uses: actions/checkout@v4
  with: { fetch-depth: 0 }
- run: pip install aperture-mcp
- run: aperture check --ref-a ${{ github.event.pull_request.base.sha }} --ref-b ${{ github.sha }}

先用附带的测试样例体验一下（克隆仓库即可）：它会针对已检入的前后文档检测被删减的承诺，无需设置，完全离线—— python3 examples/git_decision_drift/git_decision_drift.py。

2. 在任务进行中，从 Agent 调用——MCP 服务

Agent 编辑内容时，也可以调用同一项检查。（只有 Agent 选择调用时，MCP 工具才会触发——作为触发线，它不如 git hook 可靠，但在任务进行中很实用。）

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

想要零安装？将客户端指向 uvx 即可： { "command": "uvx", "args": ["aperture-mcp"] }。

3. 或者从你自己的 Python 代码中调用

from aperture import compare, Anchor, AnchorKind

result = compare(
    state_a="We commit to: ci-gates-green before release; data-never-leaves-device.",
    state_b="We commit to: data-never-leaves-device.",
    anchors=[Anchor(kind=AnchorKind.COMMITMENT, id="ci-gates-green")],
)
print(result.status)            # DROPPED_SILENTLY
print(result.anchor_violations) # the commitment that vanished

---

你一定熟悉的场景

在一项耗时很长的任务中，Agent 会在多个会话和编辑过程中不断改写它所依据的文档——计划、规范之类的文档。时不时，一句重要的话就这样……消失了。

“删除任何内容前务必先询问。” 消失了。 “用户数据绝不离开设备。” 消失了。 “免费套餐始终免费。” 消失了。

没人想删掉这些内容；也没人会读完差异中的 400 行。

Aperture 会监控你指定的原文行。把它放到提交流程中——在删除内容落地前触发的 hook——它不会试图理解文档，也不会评判内容；它只会告诉你哪条承诺曾经逐字存在，如今却不见了。它是触发线，不是裁判——而且会坦诚说明其局限：如果你弱化或改写某句话，或者改了一个数字，而不是直接删除，它就检测不到。最好现在就了解这一点。

哪些变化会被捕捉，哪些会漏过

Aperture 是一种启发式方法。我们在自己的黄金语料库上对它进行了测量，并公布具体数字，而不是只报一个好看的分数，因为了解它看不到什么，就是这个产品的价值——在一个由独立大模型评审小组标注的 100 个案例语料库上，召回率为 0.400，精确率为 0.667（它能捕捉到 65 个真实漂移中的 26 个；大约每 3 个标记中就有 1 个是噪声），完整分析见 docs/measured-limits.md：

变化类型	Aperture 会标记吗？
监控中的承诺被逐字删除	✅ 能可靠捕捉——这是它擅长的唯一一件事（语料库中 24 个案例全部捕捉到）
承诺被改写 / 弱化（“必须”→“应该”）	❌ 漏过——文本仍然“匹配”
承诺被意译 / 重组	❌ 漏过
数字 / 范围 / 否定被悄悄改动	❌ 漏过
承诺被翻译成另一种语言	⚠️ 对于自然语言锚点，会放弃判断（弃权）——它无法跨文字系统逐字比较，因此会返回 degraded，而不是错误标记（承诺被删除并且被翻译时，会漏过）

确定性检测范围不会扩大。 git 钩子会可靠触发——但它仍然只捕捉逐字删除。上面每个 ❌ / ⚠️ 行，通过钩子检测时和通过 MCP 检测时一样盲。你得到的是它何时检查（提交时自动检查，无需任何人记得提出要求），而不是它能看到什么。

最后一行的结果取决于锚点风格：弃权适用于自然语言锚点。代码标识符锚点（快速入门中介绍的 ci-gates-green 风格）被视为跨语言稳定——Aperture 会继续跨语言检查它，因此如果该精确标记消失，它仍会标记 DROPPED_SILENTLY（对于稳定标识符，这通常正是你想要的）。

结论：把每个标记都当作“看看这里”，而不是“这里有错”——也不要以为没有提示就代表没有发生漂移。Aperture 能很好地捕捉逐字消失的情况，并坦诚说明自己很少能捕捉到其他情况。这个范围狭窄但可靠的信号之所以有用，恰恰是因为它不会夸大自己的能力。

**你自己的文档也遇到过这些漏检吗？**这是你能提供给我们的最有用的信息——约 30 秒即可报告（措辞可自行选择）。真实的漏检案例能帮助我们决定接下来修复什么。

为什么不直接用 git diff / grep？你可以手动复现核心检查。Aperture 的额外价值在于，它会在提交 / PR 事件发生时自动触发（作为钩子或 CI 检查），也可由 Agent 在任务过程中调用（通过 MCP）；它会返回结构化且有方向性的结果（ok / degraded / DROPPED_SILENTLY / …）；并且会在结果中报告自身的盲点，方便人工审查遗漏之处。它围绕简单、清晰的检查提供了易用性和坦诚度——而不是一个更聪明的检测器。

---

为什么要做这个

长时间运行和多 Agent 工作流会发生漂移。第 3 轮 / 第 1 个会话 / 由 Agent A 确定的约束，在四十轮之后、另一个会话中，被 Agent B 悄悄删改——直到发布后才有人发现。Aperture 是一种可用于 Agent 维护文档的预检工具：明确列出绝不能悄悄消失的承诺，并在其中一项消失时触发警报——最好是在提交时、变更合并之前。

它刻意设计得小巧且清晰。它不是替你做决定的 AI，而是一种帮助你保持前后一致的信号。

---

适用对象

适用于这样的团队和构建者：(a) 允许 AI Agent 修改存放在代码仓库中的决策文档——规格说明、计划、ADR、章程和 AGENTS.md 文件；(b) 使用版本控制管理这些文档。如果你的 Agent 会接触承载承诺的文本，Aperture 就能以低成本、坦诚的方式，为那些绝不能悄悄丢失的内容提供警报——在提交时、CI 中或任务过程中。

---

隐私

• 自愿启用，本地运行。 Aperture 在你的机器上运行——无论是 git-hook、CLI 还是 MCP 服务。它不会进行网络调用。
• 绝不使用你的数据训练。 你的决策文本属于你；它绝不会离开你的进程。
• 使用情况日志默认关闭，启用后也只记录元数据（时间戳、工具、状态、计数）——绝不记录你的决策文本或承诺措辞。

---

关于演示的说明

此仓库附带一个小型的手工编写的 ADR 示例（examples/git_decision_drift/fixtures/ 下的一组前后对照文件）。Aperture 能正确标记我们有意废弃的一项承诺，并对我们保留的一项承诺保持静默。这忠实展示了该机制的工作方式——但它是一个由我们编写并自行评判的单一样本。它展示的是触发器如何工作，而不是信号有多强。后者请参阅上文及 docs/measured-limits.md 中按类别测得的数据。 目前还没有外部采用者——如果你在自己的决策文档上运行 Aperture，我们很乐意了解它发现了什么、漏掉了什么。

---

项目状态

项目尚处早期，版本尚未达到 1.0，目前还不能作为生产环境的门禁。比较约定（v0.2）已冻结，并由一致性测试套件覆盖；包 API 仍可能变动。有关兼容性政策，请参阅 VERSIONING.md；有关变更，请参阅 CHANGELOG.md。

发现漏报？帮助改进

Aperture 确实会漏掉一些情况——这是有意为之（在所有使用场景中，它都无法识别经过改写、弱化或翻译的承诺）。当它漏掉你在意的漂移，或错误地标记了改写时，告诉我们是最有价值的贡献：

• 约 30 秒，无需账户或使用数据，可不提供原文措辞 → 提交漂移案例报告。
• 真实的漏报能告诉我们下一步该修复哪个盲点；而且只有在你选择分享原文措辞时，这些案例才会纳入黄金语料库，帮助确保 docs/measured-limits.md 中的数据真实可靠。

我们绝不会自动收集任何信息（请参阅隐私）；只有在你选择分享时才会发生。
有疑问，或想问“这款工具适合我的情况吗？”→ GitHub 讨论区。

更多参与方式：CONTRIBUTING.md。

许可证

Apache-2.0。