Slipmark

Slipmark

一个 Reply Intelligence Group 项目。

让 AI Agent 证明自己检查过什么。

将它添加到工作流中：

- uses: actions/checkout@v4
- uses: founder-ship-it/[email protected]
  with:
    require: |
      specs/your-spec.md

如果文件在 Agent 签署通过后发生变化，构建就会拒绝：

Slipmark verify: 1 verified · 1 refused

  ✓ verified             review-agent verified examples/attestation/brief.md
  ✗ hash_mismatch        security-audit-agent gave "cleared" for a different version of
                         examples/attestation/spec.md. The file changed after the verdict.

只需一条命令即可完成设置：npx slipmark init。随后，你的编码 Agent 会使用 slipmark attest 写入签署结果（参见与编码 Agent 配合使用）。无需调用模型，无需账户，只需一个 GitHub Action。

滑移标记是工程师在螺栓拧紧并检查完毕后画上的一道漆线。如果螺栓后来发生移动，漆线就会断开，所有人都能看到。Slipmark 对 AI Agent 的判定做了同样的事：Agent 一旦签署通过某个文件，之后的任何更改都会使标记失效。

如今，Agent 会审查代码、审核规范，还会签署自己的工作结果。薄弱之处在于判定。Agent 可能会报告某个文件“通过”，但该文件后来已经更改，或者 Agent 根本没有检查过它，而下游环节对此无从知晓。

Slipmark 做两件事：

1. 判定证明。 每项 Agent 判定都会绑定到 Agent 读取的确切文件的 SHA-256 哈希值。发布前，门禁会重新计算这些文件的哈希值。哈希不匹配、文件缺失、判定未通过，或根本没有证明：一律拒绝。结果确定，无需调用模型，只需一个 GitHub Action。
2. 漂移诊断。 为 AI 功能设置行为“锁定项”。更改导致某项锁定失效时，Slipmark 会说明可能导致问题的原因、对此有多大把握（并且不会伪装出自己没有的信心），还会向编码 Agent 提供修复提示词。

状态：v0.7.0，早期版本。Apache-2.0。可选托管层：Slipmark Cloud。

为什么需要门禁

我们运行着一个每晚执行的流水线，其中有 20 多个 Agent，负责研究、架构、安全审核、构建和 QA。每天早上，它们都会报告哪些环节通过了。

后来我们发现，最终验证任务几个月来一直在检查错误的分支。它不可能失败，所以它从未失败过。连续数月一片绿勾，却证明不了任何事。

于是我们构建了门禁：将每项判定绑定到所读取内容的哈希值，并在发布前重新检查。将它用于 23 个未合并的 Agent 拉取请求时，它拒绝了全部 23 个。

Slipmark 能证明什么，不能证明什么

Slipmark 不会判断你的 Agent 是否正确。它确保你所信任的判定针对的是你要发布的代码。

它能证明：

• 判定针对的就是这些确切字节。只要其中一个文件发生变化，该判定就不再有效。
• 你要求的每个文件都有当前且通过的判定。缺少判定就会被拒绝，而不是悄无声息地放行。
• 每次得到的答案都相同。无需调用模型，无需评分，也无需判断。

它不能证明：

• Agent 很聪明。如果 Agent 在第一天漏掉了一个错误，只要文件保持不变，Slipmark 就会一直放行该文件。这是 Agent 给出的判定，Slipmark 会如实保留。
• 谁写下了未经签名的证明。任何有权限推送的人都可以写入 "by": "security-reviewer"。要求使用签名判定，并且只将由你信任的工作流签署的判定计入结果。

因此，请将它与现有的可信检查配合使用。Slipmark 锁定的是判定，而不是判定本身。如果你想要更可靠的判定，就要求提供更多判定：覆盖每个已更改文件、由 Slipmark 自行运行检查，或在模型更改时重新审查。这些功能目前已在 main 中 （docs/attestation.md）。针对敏感路径进行两次独立审查，以及其余的证明 v2，都在后续计划中。

快速开始

在你想要保护的代码仓库中（Node 22.6 或更高版本）：

npx slipmark init

  + create .slipmark/attestations/.gitkeep      attestation directory, committed with the repo
  + create .github/workflows/slipmark.yml       report-only gate on pull requests
  + create AGENTS.md                            agent instructions for attesting verdicts
  ~ update CLAUDE.md                            agent instructions for attesting verdicts

设置就这些：

• 一个工作流，在每个拉取请求上运行门禁。它会以仅报告模式启动，因为尚无判定结果的代码仓库本来就会失败。 等你的 Agent 开始进行证明后，将 fail-on-refusal: "true" 设为启用。
• Agent 指令写入 AGENTS.md，以及代码仓库已有的 CLAUDE.md、Cursor 规则或 Copilot 指令。重新运行 init 会原地更新代码块，不会改动这些文件中的其他内容。

随时运行 npx slipmark verify 检查。提交 .slipmark/attestations/。

适用于你的编码 Agent

init 写入的指令足以让 Agent 自行进行证明。我们在一个全新的代码仓库中给 Claude Code 一个普通的审查任务，没有提到 Slipmark：

根据 specs/invoice-export.md 审查 src/export.ts。它是否符合规范？

它读取了两个文件，发现导出格式不是 CSV，并记录了：

{
  "by": "reviewer",
  "verdict": "fail",
  "subjects": [
    { "path": "src/export.ts", "sha256": "0ea6029f…" },
    { "path": "specs/invoice-export.md", "sha256": "81994e0f…" }
  ],
  "note": "Tenant filter and 10k limit OK; no CSV output, returns raw query result"
}

它依据的是这两个文件，而不只是正在审查的文件。代码修复后，旧判定结果将不再有效，直到 Agent 再次读取该文件。

Claude Code、Cursor、Copilot 和 Codex 的设置说明见 docs/agents.md。

Claude Code 插件

Claude Code 还有一个插件。它会添加一项技能，让 Claude 无需任何代码仓库指令即可记录判定结果；还会添加 /slipmark:verify 和 /slipmark:setup 命令，以及一项停止检查：如果 Claude 签字确认的文件此后发生了更改，就会要求 Claude 重新读取并再次进行证明。

/plugin marketplace add founder-ship-it/Slipmark
/plugin install slipmark@slipmark

详细信息（包括它具体运行的内容）见 claude-plugin/。

MCP 服务：Codex、Cursor、Copilot、Gemini

slipmark mcp 会将 slipmark_attest 和 slipmark_verify 提供为 MCP 工具，因此任何支持 MCP 的 Agent 都能记录和检查判定结果。对于 OpenAI Codex，在 ~/.codex/config.toml 中：

[mcp_servers.slipmark]
command = "npx"
args = ["-y", "[email protected]", "mcp"]

Claude Code、Cursor、VS Code 中的 Copilot 和 Gemini CLI 的设置说明见 docs/mcp.md。Agent 无法通过它记录人工批准。

判定证明

1. Agent 对其读取的内容进行证明。 在任何给出判定结果的 Agent 步骤结束时调用：

slipmark attest --by security-audit-agent --verdict cleared \
  --subject specs/invoice-export.md --subject src/export.ts

这会写入 .slipmark/attestations/<agent>--<file>.json：

{
  "schema": "slipmark/attestation@1",
  "by": "security-audit-agent",
  "verdict": "cleared",
  "at": "2026-10-17T09:00:00.000Z",
  "subjects": [
    { "path": "specs/invoice-export.md", "sha256": "cf89da70…" }
  ]
}

2. 门禁会在任何内容发布前进行检查。

slipmark verify --require specs/invoice-export.md

结果	含义
verified	判定通过，且文件与 Agent 读取时逐字节相同
hash_mismatch	判定结果生成后文件发生了更改。该判定针对的是另一个文件。
subject_missing	经证明的文件已不存在
verdict_not_passing	Agent 判定为失败或阻止
unattested	使用 --require 要求的文件没有当前有效的通过判定，或者完全没有证明记录
invalid	证明格式错误，或路径位于代码仓库之外

通过判定包括 pass 和 cleared。空门禁会拒绝，而不会静默通过。--json 会输出完整报告，供其他工具使用。

更严格的判定（在 main 上，尚未发布）。记录判定结果所依据的检查内容，并让 Slipmark 自行运行这些检查：

slipmark attest --by reviewer --verdict pass --subject src/export.ts \
  --against specs/invoice-export.md --run "npm test"

如果 --run 检查失败，就会拒绝通过判定。然后，要求为每个已更改的文件提供判定，而不只是你列出的文件：

slipmark verify --coverage diff --base origin/main

详细信息见 docs/attestation.md。

Agent 上下文

审阅者通过了代码。但谁编写了审阅者的指令？ 2026 年的编码 Agent 攻击篡改了 AGENTS.md、技能和 MCP 配置，却没有动审阅过的代码。在 .slipmark/policy.json 中添加 "context": {}，Slipmark 就会将每项判定也绑定到 Agent 的指令：

• 如果判定所依据的指令后来发生变化，该判定就不再有效
• 修改 AGENTS.md、CLAUDE.md、技能或 MCP 配置，需要审批者给出判定（可配合 CODEOWNERS 使用，或要求签署审批）
• 修改后的指令必须是 GitHub 能完整显示的纯 Markdown：白名单会拒绝其他所有内容（HTML、注释、图片、图表，以及 GitHub 今后添加的任何内容）；在 GitHub Actions 中，还会根据 GitHub 自己的渲染器检查每个文件
• 如果上下文文件链接到监控范围之外的内容，则会被拒绝

策略从基础分支读取，因此拉取请求无法关闭此功能。尚未涵盖的内容列在文档中。详情请参阅 docs/attestation.md。

在 slipmark-context-demo 中，查看它如何通过开放拉取请求拒绝五种真实攻击模式（Ghostcommit、Deadbugz、隐藏注释、不可见 Unicode 字符，以及关闭检查的拉取请求）。

签署判定

证明是谁给出了判定，而不只是判定针对什么（适用于 main，尚未发布）。在 GitHub Actions 作业中运行审阅 Agent，并在其出具证明时进行签名：

slipmark attest --by security-reviewer --verdict pass --subject src/auth/session.ts --sign

判定通过 Sigstore 使用作业自身的 GitHub 身份签名：无需管理密钥，且每个签名都会记录在公开透明日志中。然后，只统计来自可信工作流的判定：

- uses: founder-ship-it/Slipmark@main
  with:
    require-signed: "true"
    trusted-signers: |
      https://github.com/acme/api/.github/workflows/agent-review.yml@refs/heads/main

手动输入、由其他工作流生成或签名后经过编辑的判定都会被拒绝。详情（包括应信任哪个 ref）请参阅 docs/attestation.md。

作为 GitHub Action 使用：

- uses: actions/checkout@v4
- uses: founder-ship-it/[email protected]
  with:
    require: |
      specs/invoice-export.md

想要逐步推出？将 fail-on-refusal: "false" 设置为 false，即可将拒绝报告为警告，而不会导致构建失败。无论哪种情况，此步骤的 result 输出都是 passed 或 refused。

**格式化工具。**格式化工具运行后会改变字节内容，因此和其他任何改动一样，会使判定失效。让格式化工具在 Agent 出具证明前运行（优先放在 pre-commit 钩子中），就能避免大多数这类问题。支持格式化的哈希模式以及仅针对差异重新审阅的功能计划在 v0.5 推出。

在即将合并的分支上运行。由于它检查的是内容而非分支名称，在一个分支上生成的判定无法为另一棵代码树放行。

更多信息请参阅 docs/attestation.md。

Slipmark Cloud

上方的门禁免费、开源且无需账号。Slipmark Cloud 是可选的托管层，适合需要留存记录、而不只是构建结果的团队：

• 仅追加、哈希链式账本，记录每次运行，并为每次运行提供证明页面。其中内容无法编辑或删除，链头每天都会发布到 Sigstore 的公共 Rekor 日志，因此任何人都可以检查历史记录是否被篡改。
• 它不会盲信 CI。 Cloud 会从 GitHub 自己保存的提交副本中重新读取证明和经证明的文件，并重新计算每项结果。
• 将规则设为必需检查。 例如，“src/auth/** 下的变更必须获得 security-reviewer 的通过判定”，并以 Slipmark policy 的名义发布到拉取请求。管理员可以批准未通过的检查，但必须提供书面理由，并将其记录在案。
• 明确告知该怎么做的警报。 支持 Slack、Microsoft Teams、Discord、Google Chat、PagerDuty、电子邮件，或向其他任何目标发送签名 Webhook（Standard Webhooks）。每次失败都会指出相关规则、文件、需要签字确认的 Agent，以及修复命令。可按仓库和规则路由，并通知合适的人员。拉取请求通过后，PagerDuty 事件会自动关闭。
• Slipmark Slack 应用。 每个拉取请求对应一个讨论串，管理员可以在 Slack 中批准未通过的检查，并提供书面理由，将其记录在案。
• 每周摘要，汇总运行情况、被阻止的拉取请求、发现的过期判定以及每次例外批准。
• 面向 SOC 2 CC8.1 和 ISO 27001 变更管理控制的洞察与审计证据包： 提供 PDF，供审计员查看，JSON 文件附在其中。

安装 Slipmark GitHub App，并在工作流中添加两行即可启用：

jobs:
  verify:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write   # GitHub signs a token saying which repo and run this is. No API key.
    steps:
      - uses: actions/checkout@v4
      - uses: founder-ship-it/[email protected]
        with:
          cloud: "true"

cloud 永远不会改变门禁结果。所有仓库（无论公开还是私有）都可以免费使用门禁。 Cloud 对公开仓库免费。Team 方案中的私有仓库每个席位每月 £15（至少 3 个席位），并提供 14 天免费试用。请参阅 快速入门和 定价。

漂移诊断：有何不同

大多数 AI 评估 / 可观测性工具侧重于检测（为输出评分、标记回归、绘制仪表板）。Slipmark 的独特之处在于诊断 + 修复，并且会如实说明结论的确定程度。

置信度来自证据，而非猜测——三档诚实上限：

可用证据	置信度上限	含义
仅签名 / 模式	0.40（低 / 中）	启发式判断，并非证据——investigate_first
+ 执行跟踪	0.69（中）	我们知道机制，但不知道具体提交
+ git diff 或二分定位的提交	无上限（最高可达高）	因果证据将问题关联到具体变更

• 拒绝伪造精确度。 置信度较低时，完全不提供排序后的文件列表，并切换到明确的调查模式（“不要盲目应用修复”）。
• 修复提示词受模式限制——suggest_patch（高）、minimal_fix（中）、investigate_first（低）——确保 Agent 获得恰到好处的操作空间。
• 防止钻空子： 所有提示词都禁止编辑锁定文件 / 测试夹具来强行通过检查。

获得的因果证据

有证据时，Slipmark 会呈现确凿证据，而不是猜测：

• 执行跟踪 — 锁会自行检测（执行过的模块／符号，以及 intentSourceUsed="first" 之类的观测结果），因此诊断基于代码实际执行的操作。
• 二分查找 — bisectFirstFailing() 是真正的“针对 AI 行为的 git-bisect”：给定提交历史和探测命令，它会通过二分查找，在约 log₂(n) 步内找到问题提交。宿主提供探测方式（检出并重新运行）；引擎负责算法。
• 发生变化的受监控符号 — 锁会声明其不变量所依赖的符号；当差异改变其中一个符号时，就有了确凿证据，表明行为背后的具体代码发生了变化。

漂移演示

该演示（packs/demo-shop）是一个电商客服助手——刻意设计成与原产品不同——用于证明引擎具有通用性。它内置了一个人为植入的回归问题，让你观察 Slipmark 如何发现并诊断问题。

Slipmark — pack `demo-shop`
  1 passed · 1 drifted · 0 errored (of 2)
  ✗ shop.latest_intent_wins — drift
      cause: Likely: stale intent carryover …  Probable hot-spot: `…/shopAssist.ts` (85% relevance).
      confidence: high (86%) · severity: high · mode: suggest_patch

在 packs/demo-shop/shopAssist.ts 中将 PLANTED_BUG 设为 false，锁就会变绿。

工作原理

locks (your behavioral invariants)
   │  run() → pass / drift + failed assertions
   ▼
engine
   ├─ signatures      match the failure to a known drift pattern   (pack-supplied)
   ├─ scorer          rank changed files + modules by relevance
   ├─ confidence      structured score + honesty caps + tier-gating
   └─ repairPlan      mode-gated, coding-agent-ready repair prompt
   ▼
DriftAnalysisReport  (cause, ranked files/modules, confidence, repair prompt)

编写锁 — 两种方式

1. 仅使用配置（JSON，无需代码）— 最快的入门方式

使用纯 JSON 定义一个包，并为每个锁指定一个输出 AI 结果的目标命令。Slipmark 会将测试样例通过 stdin 传给该命令，并断言 stdout 中的内容——它不关心你的系统使用哪种语言：

{
  "id": "my-product",
  "locks": [{
    "key": "support.latest_intent_wins",
    "scope": "ai",
    "invariants": ["When the user pivots topic, the reply addresses the latest intent."],
    "failureSignatures": ["stale_intent_carryover"],
    "watchedSymbols": ["composeReply"],
    "target": { "command": "node assistant.mjs", "inputFormat": "stdin-json" },
    "fixture": { "turns": [/* ... */] },
    "assertions": [
      { "name": "focuses_on_latest_intent", "type": "matches", "value": "track|delivery" },
      { "name": "no_prior_intent_carryover", "type": "not_matches", "value": "return|refund" }
    ]
  }]
}

slipmark ./drift.pack.json --emit .slipmark

断言类型：contains、not_contains、matches、not_matches、equals、not_equals。省略 target.command 可使用“黄金模式”（测试样例本身就是输出）。完整的可运行示例请参见 packs/demo-shop-declarative/。

2. TypeScript（功能完整）

对于任意验证逻辑、自检测执行跟踪或进程内目标，可使用 TypeScript 定义 Pack。

Pack — 完整的扩展机制

引擎不会导入任何特定领域的内容。Pack 包含所有这些内容：

import { definePack } from "slipmark";

export const myPack = definePack({
  id: "my-product",
  signatures: [ /* how to recognise your drift patterns */ ],
  signatureToModules: { /* signature → modules it implicates */ },
  baseConstraints: [ /* do-not-break rules injected into every repair prompt */ ],
  scopeConstraints: { /* per-scope extra constraints */ },
  scopeImpact: { /* per-scope business impact copy */ },
  signatureGoals: { /* per-signature repair goal */ },
  signatureImpact: { /* per-signature impact */ },
  diffKeywords: [ /* domain words that align a diff to behaviour */ ],
  systemMap: { modules: [ /* your module responsibilities */ ] },
  locks: [ /* your behavioral invariants */ ],
});

替换包并将其指向另一款产品——无需修改引擎。这正是将其单独提取出来的意义所在。

CLI

slipmark init [--dry-run] [--no-workflow] [--no-agents] [--force]
slipmark <pack.js> [--git <git-context.json>] [--prompts] [--emit <dir>]
slipmark attest --by <agent> --verdict <pass|cleared|fail> --subject <file>... [--note "..."] [--out <file>]
slipmark verify [--dir .slipmark/attestations] [--require <file>...] [--json]
slipmark bisect --range <git-range> --command "<probe>"
slipmark dashboard <pack> --history <h.json> --out <file.html>

只要任一锁发生漂移或出错，就会以非零状态码退出，因此可用于拦截 CI。传入 Git 上下文（自上次通过运行以来变更的文件），即可将置信度从“特征启发式”提升到“有证据支持”，并显示按排名排列的文件。

二分查找 — 找出问题提交

引擎内置了真正的“针对 AI 行为的 git-bisect”。指定提交范围和探测命令（退出码为 0 表示锁通过）；它会通过二分查找找到引入回归问题的提交，并在之后恢复你的工作树：

slipmark bisect --range "main~30..main" \
  --command "npm run build --silent && node dist/src/cli.js dist/packs/demo-shop/pack.js"

  ✗ first failing commit: deadbeef…
    last good commit:    00aa11bb…
    probes evaluated:    5          # not 30 — ~log2(n)

二分查找定位到的问题提交，是 Slipmark 能提供的最有力因果证据：它会提高置信度上限，并将精确的提交范围传递给修复提示词。

本地仪表板

Slipmark 会根据本地运行历史 JSON 文件，生成一个独立的 HTML 仪表板，展示多次运行的漂移趋势、锁状态、置信度条和可深入查看的修复提示词。如需查看跨仓库共享的托管视图，请参见 Slipmark Cloud。

# Run a pack and append the result to a rolling history, then render the dashboard:
slipmark dashboard ./drift.pack.json --history .slipmark/history.json --out dashboard.html

# Or render an existing history file:
slipmark dashboard --from dashboard/sample-history.json --out dashboard/sample.html

--history 文件会随着时间累积运行记录。渲染后的示例请参见 dashboard/sample.html。

编码 Agent 集成

--emit <dir> 会为每个失败的锁写入：

• <lockKey>.repair.md — 可直接运行的修复提示词
• index.md — 链接到每个修复项的摘要
• AGENT_RULES.md — 放入 .cursor/rules/ 或 CLAUDE.md，让任何编码 Agent 都能安全地处理 Slipmark 提示词（遵循调查模式，绝不通过修改锁来强行通过，变更后重新运行锁）

以无头模式将提示词交给 Claude Code：

claude -p "$(cat .slipmark/shop.latest_intent_wins.repair.md)"

这就是切入点：大多数工具只会告诉你某项指标下降了。Slipmark 会告诉你的 Agent 可能是什么导致了问题以及如何安全修复——如果证据不足，它会拒绝过度自信地给出结论。

通往“精英级”的路线图

1. 更深入的因果分析 — 已完成。 执行跟踪、真实二分查找 （bisectFirstFailing）以及变更监控符号分析，现在共同支撑一个有据可依的三层置信度模型。✅
2. 编码 Agent 集成 — 已完成。 --emit 会生成修复提示词和 AGENT_RULES。✅
3. 二分查找主机适配器 — 已完成。 slipmark bisect / runGitBisect 会检出真实提交、运行探针，并还原工作树。✅
4. 自助创作 — 已完成。 使用纯 JSON 定义套件，包括目标命令和声明式断言——无需 TypeScript。✅
5. 仪表板视图 — 已完成（静态）。 独立的 HTML 仪表板，包含漂移趋势、锁状态和可深入查看的修复提示词，并由运行历史 JSON 提供支持。✅
6. 判定证明，已完成。 slipmark attest / verify 会将 Agent 判定绑定到 SHA-256 哈希，并在不匹配时拒绝通过。✅
7. 托管云服务（开放核心），已完成判定证明功能。 Slipmark Cloud： 台账、服务端重新验证、规则、提醒、证据包。✅
8. 判定证明 v2 (下一步)：记录给出判定的模型，由 Slipmark 自行运行检查，覆盖每个变更文件，在敏感路径上实行法定人数要求，以及支持容忍格式差异的哈希模式。

开发 Slipmark

npm install
npm test              # 40 tests
npm run demo:verify   # the attestation gate refusing a stale verdict
npm run demo          # drift diagnosis on the demo pack

文档

• 判定证明：架构、状态，以及如何接入 Agent。
• 编码 Agent：Claude Code、Cursor、Copilot 和 Codex 的配置。
• MCP 服务：适用于任何支持 MCP 的 Agent 的 slipmark mcp。
• 判定证明 v2（草案）：更丰富的证明、覆盖率、法定人数、增量重新证明、人工覆盖。
• 哈希模式（草案）：容忍格式差异的哈希，根据策略按路径选择。
• 概念 — 心智模型（锁、套件、签名、诚实度模型、修复提示词）。
• 创作指南 — JSON 和 TypeScript 套件、断言类型、二分查找接线。
• 贡献指南 — 设置、项目结构、不可妥协事项。
• 更新日志。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。关于此选择的理由，请见 LICENSE-OPTIONS.md。

---

Slipmark 由英国沃特福德的 Reply Intelligence Group 开发。© 2026 Reply Intelligence Group Ltd.