Elliot

独立核查 AI Agent 编写的代码。
Elliot 会对照代码，核查 Agent 声称完成的内容以及 README 中承诺的内容。每项发现都附有证据。

快速开始 · 核查结果 · 工作原理 · 命令 · 配置 · 常见问题

---

快速开始

在你要核查的代码仓库中：

npx -y github:EmanueleCell4/elliot-mcp init

重启 Agent，然后输入：

/elliot-audit

一到三分钟后，报告会生成在仓库根目录下的 elliot-report/<date>-<commit>/ 中：report.html、report.md 和 claims.json。无需打开任何内容，也没有仪表板或账号。

要求：Node 20 或更高版本、git，以及 Claude Code、Cursor 或 Codex。

作为 Claude Code 插件使用

在 Claude Code 中：

/plugin install elliot --marketplace EmanueleCell4/elliot-mcp

这会添加 Elliot 工具、一个 /elliot:audit 命令，以及一个技能，让 Claude 在报告自己“已完成”之前先核查相关声明。

在每个拉取请求上运行（GitHub Action）

Elliot 会读取拉取请求说明，逐项对照代码核查其中的声明（“修复了 X”“为 Y 添加了测试”“行为没有变化”），并附上证据发表评论。如果 PR 是由 Agent 编写的，这正是核查它是否“已完成”的地方。

# .github/workflows/elliot.yml
name: Elliot
on:
  pull_request:
    types: [opened, edited, synchronize]
permissions:
  contents: read
  pull-requests: write
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: EmanueleCell4/[email protected]
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

评论示例如下：

判定	声明	证据
❌ 不实	为注释构建器添加单元测试，位于 test/comment.test.js	搜索 comment.test.js：未找到
✅ 已验证	仅当审计没有发现问题时才会提供徽章	src/audit-report.js:27

它会使用你的 API 密钥运行 Claude Code。每次核查通常需要 1–2 分钟。除 Anthropic 的 API 和 GitHub 外，不会向任何地方发送数据。

README 徽章

当 Elliot 核查的每项声明都得到证实时，报告会附带一个徽章，你可以将它粘贴到 README 中：

原因

编码 Agent 会在工作尚未完成时说“完成了 ✅”。它们会删除失败的测试、跳过检查、描述并不存在的安全措施，还会编写承诺了代码实际上做不到的 README。CI 依然保持绿色，因为测试检查的是 Agent 编写的代码，而不是产品做出的承诺。

我也是吃了亏才发现这一点。我自己的法律科技应用有一个安全页面，承诺在数据库中强制执行基于角色的访问控制。数据层的设计却绕过了这项控制，而每个权限检查函数都会忽略输入。Agent 当时告诉我已经完成了。

常见的解决办法是让第二个 AI 审查第一个 AI。这只会让你得到另一个犯过同类错误的系统的意见。在我进行的第一次自动审计中，负责检查的 Agent 在 17 份提交中，有 4 份引用了并不存在的行号。

Elliot 采用了相反的方式：**Agent 提议，Elliot 验证。**每条引文都必须确实存在于文件的对应行和对应提交中：审计开始时会为代码树生成指纹（包括已跟踪的更改和未跟踪的文件），一旦发生任何更改，就不再接受证据；指向仓库外部的符号链接也不算证据。每项“此内容不存在”都会由 Elliot 自行搜索。之后，一位全新的审查者会尝试证明每项发现有误，再将其纳入报告。

发现了什么

Elliot 0.3 于 2026 年 10 月在 Claude Code 中无人值守运行，对 AI 编码 Agent 生态中 9 个热门开源工具进行了检查。随后，一位没有看过审计结果的独立审查者逐项对照代码核查了每项发现。

报告中的发现	确认正确	审查者未能确认	错误	每个仓库耗时
13	12	1	0	1 到 3 分钟

“错误”指事实性错误：代码并未体现该发现所述的情况。

它发现的问题包括：

• 某工具的 README 声称 “无遥测：不收集或追踪任何数据”，但该工具默认启用分析功能，并且同意状态预设为“是”。（公开 issue）
• 某应用在用户关闭遥测后，一登录就会重新启用遥测，随后还会通过电子邮件识别用户。（公开 issue）
• 某安全页面将脚本沙箱称为 “只读”，但代码可以赋予脚本文件写入权限和 MCP 工具。项目的分流机器人已确认此问题，并已向上游提交文档修复。（issue，PR）
• 文档称 API 密钥经过加密存储，但代码却将其以纯 JSON 格式写入。
• 某热门 Agent 工具默认会将用户的 完整 AI 提示词和回复发送给第三方错误追踪服务，而该选项的名称是“anonymousTelemetry”。已私下向维护者报告；修复后将公布详情。

它目前仍会漏掉一些问题：在同样的 9 个仓库中，它发现了我此前手动找到的 10 个严重问题中的 6 个（这组问题数量较少且经过人工挑选，因此只能将其视为粗略的覆盖率，而不是召回率估算）。最常见的漏报是缺少授权检查（例如，下载端点没有检查请求者的身份）。Elliot 目前还不会查找这类问题；请参阅路线图。

基准测试：使用 Elliot 的 Claude 与单独使用 Claude

8 个广泛使用的 SDK，通过更改文档所述默认值背后的值，植入 18 项不符的承诺；每种条件运行两次，使用相同的模型和指令。盲审员检查了所有非植入的发现。

	单独使用 Claude	使用 Claude + Elliot
发现的植入漏洞（2 次运行）	28 / 36（78%）	30 / 36（83%）
误报（判定为不属实）	占发现的 21%	占发现的 6%
发现的真实非植入问题	8	5

Elliot 的误报约少三分之二，发现的植入漏洞略多；单独使用 Claude 则会更广泛地搜索。两位盲审员（Claude 和 Codex）意见不一致时，阅读代码发现 Codex 有 9 次错误描述了代码：如果没有人重新阅读源代码，第二个模型就不能算作核查。方法、限制和所有原始输出：benchmark/planted-promises。

基准测试：任何人都能重新核查 Agent 声称已验证的内容吗？

56 个真实漏洞修复（28 项任务，使用 Opus 和 Haiku）。每项修复都正确，也没有 Agent 错误地声称“完成”。但在 56 次运行中的 19 次（34%），Agent 声称运行的检查无法由其他人重新运行：已删除的临时脚本、用文字描述的检查、Agent 自己机器上的路径。工作没问题，证据却不见了。benchmark/done-claims

工作原理

1. 风险扫描（Elliot）。 在 Agent 阅读任何内容之前，Elliot 会扫描文档中的高风险承诺（遥测、隐私、加密、访问控制、沙箱、“永不”、“默认情况下”），并扫描代码中经常与这些承诺相矛盾的信号：分析 SDK、--dangerously-skip-permissions 等权限绕过方式、特权数据库客户端、写入磁盘的机密信息。只有每项内容都得到处理，或说明理由后跳过，审计才能完成。
2. 阅读并提出建议（你的 Agent）。 你的 Agent 会逐条追踪声明在代码中的依据，并引用文档和代码，提出判定结果。
3. 验证证据（Elliot）。 每条引文都会与固定提交中的文件进行匹配，位置必须在 Agent 所述位置的两行范围内。对于每条“缺失”声明，Elliot 都会使用 git grep 搜索。无法核实的引用会被驳回，Agent 必须修正。
4. 实质性测试。 FALSE 或 PARTIAL 判定必须说明信任文档的用户会在哪方面产生误解。遗漏、命名细节和轻微延迟会作为备注，而非发现。变更日志、路线图和内部开发者文档会被拒绝作为来源，因为它们不是面向用户的承诺。
5. 独立审查。 一个从未看过审计的新子 Agent 会尝试推翻每项发现，并确认、降级或撤回该发现。在每项发现都经过审查之前，Elliot 不会撰写报告。
6. 报告。 在 elliot-report/ 中生成 HTML、Markdown 和 JSON，并在 .elliot/receipts.jsonl 中为每项检查生成防篡改回执。

如果你在同一会话中编写了代码，协议会指示 Agent 在新的子 Agent 中运行审计，确保审计员不是代码作者。

报告示例

完整报告见 examples/lex-ai-report.html。该报告由较早版本生成，当时尚未加入独立审查步骤。

命令

安装：init

npx -y github:EmanueleCell4/elliot-mcp init            # every agent it detects
npx -y github:EmanueleCell4/elliot-mcp init --claude   # only Claude Code
npx -y github:EmanueleCell4/elliot-mcp init --cursor   # only Cursor
npx -y github:EmanueleCell4/elliot-mcp init --codex    # only Codex
npx -y github:EmanueleCell4/elliot-mcp init --all      # all three

init 是幂等的：运行两次不会产生任何变化，也绝不会覆盖你编辑过的命令文件。它会写入：

Agent	注册 MCP 服务的位置	添加的命令
Claude Code	.mcp.json（项目）	.claude/commands/elliot-audit.md → /elliot-audit
Cursor	.cursor/mcp.json（项目）	.cursor/commands/elliot-audit.md → /elliot-audit
Codex	~/.codex/config.toml	~/.codex/prompts/elliot-audit.md → /prompts:elliot-audit

审计代码库：/elliot-audit

在代码库根目录下的 Agent 中运行。在 Claude Code 和 Codex 中，你在命令后输入的内容会作为额外指令传递给 Agent，例如 /elliot-audit focus on the security page。

检查“已完成”的声明

同一个服务还会在 Agent 工作时检查单项声明。它会附带指令，告诉 Agent 在声称“已完成”之前使用这些工具。

Agent 的说法	工具	Elliot 检查的内容
“我修复了 / 清理了 / 重构了代码”	elliot_snapshot，然后是 verify_changes	任务前后每个文件的内容哈希
“功能正常”	verify_outcome	在临时 OS 沙箱中运行请求的测试命令；只有退出代码为 0 才会判定为 VERIFIED
“已部署 / 已上线”	verify_url	HTTP 状态码以及 URL 实际提供的文本
“PR 已合并”“CI 通过”“已推送”	verify_github	GitHub API：合并状态、检查运行结果，以及提交是否存在
“已发布到 npm”	verify_npm	npm 注册表：版本是否存在，以及是否在指定时间之后发布
“我的 Agent 今天到底做了什么？”	elliot_report	你的凭据：检查过的声明，以及其中有多少经得起验证

这些检查会给出 VERIFIED、NOT_VERIFIED 或 INCONCLUSIVE。INCONCLUSIVE 表示 Elliot 无法确认，例如遇到 GitHub 速率限制。它绝不会猜测。

所有 MCP 工具

工具	使用者	功能
elliot_audit_start	Agent	固定提交，列出用于支撑声明的文件，运行风险扫描，并返回协议。
elliot_record_claim	Agent	记录一条带有判定结果的声明。检查来源引文、每条证据引文和每次缺失项搜索。
elliot_record_behavior	Agent	记录文档从未提及的高风险代码行为，并附上已核查的代码引文。
elliot_review_packet	Agent	为新的审查子 Agent 返回一条自包含提示词。
elliot_record_review	审查者	确认、降级或撤回一项发现。撤回时必须提供代码引文。
elliot_audit_finish	Agent	如果风险扫描项目或审查尚未完成，则拒绝结束；全部完成后写入报告。
elliot_snapshot	Agent	在任务开始前为工作树生成指纹。
verify_changes	Agent	将工作树与快照或 HEAD 进行比较。
verify_outcome	Agent	在一次性副本中运行命令及其参数；写入操作仅限于该副本，并阻止网络访问。
verify_attestation	任何人	检查 Ed25519 签名和凭据摘要，也可选择与单独信任的公钥进行验证。
verify_url	Agent	检查 URL 的状态和预期文本。
verify_github	Agent	检查 pr_merged、checks_passing 或 commit_exists。
verify_npm	Agent	检查注册表中的软件包版本。
elliot_report	你	汇总近期凭据。

审计中的判定结果

判定结果	含义
VERIFIED	代码实现了该声明。不会误导任何人的细微差距会作为备注保留。
PARTIAL	已实现，但存在差距；依赖该功能的用户会因此采取错误操作。
FALSE	代码与声明矛盾，或者该功能、命令、标志或选项并不存在。
UNVERIFIABLE	取决于代码库之外的部署、合同或服务。
UNDISCLOSED	文档从未提及的高风险代码行为。

手动安装

如果你不想运行 init，请使用此方式。

Claude Code

claude mcp add elliot -- npx -y github:EmanueleCell4/elliot-mcp

Codex（~/.codex/config.toml）

[mcp_servers.elliot]
command = "npx"
args = ["-y", "github:EmanueleCell4/elliot-mcp"]

Cursor（.cursor/mcp.json）和任何其他 MCP 客户端

{ "mcpServers": { "elliot": { "command": "npx", "args": ["-y", "github:EmanueleCell4/elliot-mcp"] } } }

然后自行添加命令，或让你的 Agent“对这个仓库运行 Elliot 声明审计”。对于支持技能的 Agent，还要添加 skills/elliot/SKILL.md。

配置

所有设置均为可选环境变量。

变量	默认值	作用
GITHUB_TOKEN	未设置	供 verify_github 用于访问私有仓库并提高速率限制。
ELLIOT_DIR	工作目录中的 .elliot/	收据和审计状态的存储位置。
ELLIOT_GITHUB_API	https://api.github.com	GitHub API 基础 URL，适用于 GitHub Enterprise 或测试。
ELLIOT_NPM_REGISTRY	https://registry.npmjs.org	verify_npm 使用的注册表。
ELLIOT_SIGNING_KEY	未设置	Ed25519 PKCS#8 私钥的路径。设置后，每份已保存的收据都会签名。请将其保存在仓库之外。
ELLIOT_SIGNER_ID	公钥指纹	已签名收据中包含的易读签名者标签。该标签本身不能证明身份。
ELLIOT_ROLE	未设置	对单独运行的仅审核者 MCP 服务进程设置为 reviewer。
ELLIOT_REVIEW_TOKEN	未设置	启用隔离审核模式；请在审计者和审核者服务进程上配置相同的非空密钥。

网络访问和数据

Elliot 不收集遥测数据，也没有自己的服务。它会访问以下内容：

• **审计（/elliot-audit、/elliot:audit）：**读取仓库中的文件，并在本地运行 git。不会发起网络请求。
• **verify_url：**向 Agent 传入的 URL 发送一个 GET 请求。除非设置 ELLIOT_ALLOW_PRIVATE_URLS=1，否则每次重定向时都会拒绝环回、私有网络和链路本地地址（包括云元数据地址）；整个请求共用 15 秒时限，响应正文最多读取 2 MiB。
• **verify_github：**调用 api.github.com（或 ELLIOT_GITHUB_API）。如果设置了 GitHub 令牌（GITHUB_TOKEN 环境变量或插件的可选 github_token 设置），该令牌只会发送到该 API。
• **verify_npm：**调用 registry.npmjs.org（或 ELLIOT_NPM_REGISTRY）。
• **GitHub Action：**在你的 CI 中运行 Claude Code，使用你的 ANTHROPIC_API_KEY，读取 PR 描述和代码，并通过 GitHub API 发布一条评论。
• **磁盘上：**收据存储在仓库内的 .elliot/（或 ELLIOT_DIR）中，报告存储在 elliot-report/ 中。

Claude Code 插件运行此仓库中打包的服务（node src/index.js）。安装插件时，Claude Code 会根据 package-lock.json 安装其两个 npm 依赖项。

输出

your-repo/
├── elliot-report/
│   └── 2026-10-22-dd84474/
│       ├── report.html     # open in a browser
│       ├── report.md       # paste into an issue or PR
│       └── claims.json     # everything, for scripts and CI
└── .elliot/
    ├── receipts.jsonl      # one tamper-evident receipt per check
    └── audits/             # audit state

将 .elliot/ 添加到 .gitignore。如果希望报告与代码一同存放，请提交 elliot-report/。

收据示例如下：

{
  "elliot": "0.3.0",
  "id": "rcpt_3f9a1c2b7d10",
  "check": "claim",
  "claim": "Role-based access is enforced at the database layer through row-level security.",
  "target": "lex-ai@dd84474",
  "verdict": "FALSE",
  "reason": "All data access uses the service-role client, which bypasses RLS.",
  "evidence": { "source": { "file": "app/security/page.tsx", "line_start": 14 }, "evidence": [ { "file": "lib/supabase/index.ts", "line_start": 10 } ] },
  "checked_at": "2026-10-21T19:42:11.000Z",
  "checker": "local",
  "digest": "sha256:…"
}

摘要可检测收据是否发生更改。如需第三方验证，请在仓库之外配置私钥：

openssl genpkey -algorithm Ed25519 -out "$HOME/.elliot-signing-key.pem"
chmod 600 "$HOME/.elliot-signing-key.pem"
export ELLIOT_SIGNING_KEY="$HOME/.elliot-signing-key.pem"
export ELLIOT_SIGNER_ID="acme-ci"

此后保存的收据会包含 Ed25519 公钥、其 SHA-256 指纹、签名者标签和签名。验证器使用 verify_attestation 检查摘要和签名；只有在提供了单独信任的公钥且该公钥匹配时，valid 才为 true。如果未提供该公钥，验证器会报告密码学验证有效，但会将签名者身份标记为不受信任。嵌入的密钥可以证明是哪个密钥生成了签名，但不能证明该密钥属于某个特定的人或组织。请通过验证者已信任的渠道发布或分发受信任的公钥。请在仓库之外妥善保管并备份私钥。为保持兼容性，未设置 ELLIOT_SIGNING_KEY 时创建的收据不会签名。

隔离审查

如需强制审查者彼此隔离，请使用相同的 ELLIOT_DIR 和私密的 ELLIOT_REVIEW_TOKEN 运行 Elliot 两次（使用 openssl rand -hex 32 生成令牌）。审计进程使用 ELLIOT_ROLE=auditor；独立审查者进程使用 ELLIOT_ROLE=reviewer。审计服务不提供 elliot_record_review；审查者服务只提供该工具。elliot_review_packet 会向审查者提供发现、经过核验的引文、影响和审计范围内的能力令牌，但不提供仓库访问权限或审计者的解释。Elliot 会在审计状态中加密该能力令牌，在提交时核对其哈希值和审查者服务凭据，并拒绝跨审计重复使用及重复决策。在两份主机配置中保留共享的 ELLIOT_REVIEW_TOKEN；只有单次审计的能力令牌会随审查数据包传递。

{
  "mcpServers": {
    "elliot-auditor": {
      "command": "node", "args": ["/path/to/elliot-mcp/src/index.js"],
      "env": { "ELLIOT_ROLE": "auditor", "ELLIOT_REVIEW_TOKEN": "<same-random-secret>", "ELLIOT_DIR": "/path/to/project/.elliot" }
    },
    "elliot-reviewer": {
      "command": "node", "args": ["/path/to/elliot-mcp/src/index.js"],
      "env": { "ELLIOT_ROLE": "reviewer", "ELLIOT_REVIEW_TOKEN": "<same-random-secret>", "ELLIOT_DIR": "/path/to/project/.elliot" }
    }
  }
}

主机必须只向审查者提供数据包和审查者 MCP 连接。默认的未配置模式会保留原有的组合工具界面，以兼容现有 MCP 客户端。进程隔离和工具权限会强制执行这一边界；如果部署环境中的审计者能够读取审查者主机配置或冒充其 MCP 连接，则无法形成独立的信任域。

功能结果检查

使用可执行文件和参数数组调用 verify_outcome，例如：command: "npm", args: ["test"]。Elliot 会将工作树复制到临时目录，然后在操作系统沙箱中运行该命令（macOS 上使用 sandbox-exec，Linux 上使用 bwrap），阻止网络访问，并将写入限制在临时副本中。退出码为 0 时结果为 VERIFIED；检查失败时结果为 NOT_VERIFIED。如果操作系统沙箱不可用，结果为 INCONCLUSIVE，且不会运行该命令。node_modules 中已有的依赖也会复制到临时树中。不会进行 Shell 展开；请将标志作为单独参数传入。

常见问题

这不就是让一个 LLM 来评判另一个 LLM 吗？
不是。Agent 会提出判定，但所有证据都会经过确定性核验：引文会与固定提交中的文件比对，文件缺失情况则由 Elliot 自己使用 git grep 检查。第二个从未看过该审计的 Agent 会审查每项发现；撤回结论也必须有代码引文佐证，并由 Elliot 核验。

它会把我的代码发送到别处吗？
Elliot 本身在审计期间不会发起网络请求。它会读取文件并在本地运行 git。你的 Agent 会像平常一样读取代码，并使用你已有的模型。只有在 Agent 使用 verify_url、verify_github 和 verify_npm 检查时，才会调用这些服务。

它会修改我的代码吗？
不会。它只会写入 .elliot/ 和 elliot-report/；init 会写入上文列出的配置文件。

费用是多少？
免费。Elliot 采用 MIT 许可，审计使用的是你已经付费使用的 Agent 和模型。在我们的测试中，审计一个中型仓库耗时 1 到 3 分钟。

它能审计私有仓库吗？
可以。它会在代码所在的位置运行。只有审计私有仓库时，verify_github 才需要 GITHUB_TOKEN。

我可以相信 PASS 吗？
请将报告无异常理解为“在已检查的声明中未发现问题”，而不是一份保证书。声明审计只是对代码进行静态阅读；它不会运行你的应用（如需运行，请使用 verify_outcome）。只有在同级处理器会检查调用者、而某个处理器没有检查的情况下，才会涵盖授权检查；目前尚未涵盖所有权检查。

我发现了误报。
请附上报告中的 claims.json 条目并提交问题。Elliot 的设计目标之一，就是让误报数量始终为零。

路线图

• 文件、URL、GitHub 和 npm 检查，并生成本地回执
• /elliot-audit：核查声明并附上已核验的引用，报告位于 elliot-report/
• 风险扫描、未披露行为、重要性测试和独立审查
• 授权缺口：处理程序跳过其同级处理程序会执行的授权检查
• 所有权检查：处理程序会检查调用者是否已登录，但不会检查调用者是否拥有该记录
• 在 OS 沙盒中运行功能结果检查
• 在 Agent 停止时自动运行 Elliot 的钩子（Claude Code、Codex）
• 用于检查每个拉取请求描述中声明的 GitHub Action
• 使用 Ed25519 签名的回执，支持离线验证

开发

git clone https://github.com/EmanueleCell4/elliot-mcp && cd elliot-mcp
npm install
npm test     # 35 tests, including end-to-end runs that drive the server over stdio with the MCP client

该服务使用纯 Node（ES 模块）编写，仅依赖两个项：MCP SDK 和 zod。主要部分如下：

文件	功能
src/index.js	MCP 服务、工具定义、init 入口点
src/audit.js	审计状态、引用检查、审查关卡、判定解析
src/risk.js	风险扫描：文档中的风险承诺和代码信号
src/audit-protocol.js	Agent 遵循的协议
src/audit-report.js	HTML 和 Markdown 报告
src/init.js	在 Claude Code、Cursor 和 Codex 中注册 Elliot
src/checks/	verify_changes、verify_outcome、verify_url、verify_github、verify_npm

欢迎提交问题、误报案例，以及 Agent 告诉你任务已经完成的经历。

许可证

MIT © 2026 Emanuele Cella