GitPin

重要

已于 2026-10-15 归档。 已由 Assay 取代，这是一个用于确定性 Agent 控制的参考架构。 原因：同一个 Agent 既编写变更，也编写其证据清单，因此门禁证明的是覆盖情况和哈希固定，而非声明为真。Assay 改为通过确定性代码作出决策。 最后一个版本 0.6.4 仍保留在 npm 上。此 README 的其余内容未作更改。

---

为什么要有它

编码 Agent 现在会提交描述很笃定的拉取请求：“添加了重试日志记录”“更新了协议文档”“没有改动其他文件”。想要相信其中某句话的审查者，必须打开文件并找到对应代码行，然后对下一句话再做一遍。大多数审查者会停止核验，而 Agent 可能会更改一个它从未提及的文件。

GitPin 将描述转化为证据。Agent 会提交一份简短清单，其中每项重要声明都列出所涵盖的路径，并指向一段确切的代码行片段，同时附上其文本的 SHA-256 哈希。必需的检查会将此清单与实际差异进行比对。任何未被声明覆盖的已更改文件都会导致构建失败；每项通过检查的声明都可由人工使用 git show 重新核验，不需要 GitPin、Agent 或托管平台。

快速开始：30 秒运行门禁

git clone https://github.com/shmindmaster/gitpin.git && cd gitpin
corepack enable && pnpm install --frozen-lockfile
pnpm demo:gate

demo:gate 会构建 GitPin，在临时文件夹中创建一个一次性合成仓库，并运行两次真实的 gitpin gate。Agent 的首次提交更改了 docs/protocol.md，却没有对此作出声明，因此门禁以退出码 1 失败。Agent 添加一个证据定位符（第 5 行，带哈希）后，同一个门禁以退出码 0 通过：

$ gitpin gate --base <base> --head <agent-commit>
status: failed   exit code: 1
violation: uncovered-change: Changed path has no material claim: docs/protocol.md.
covered: synthetic-service/docs/overview.md:3 @ <agent-commit> (verified)
$ gitpin gate --base <base> --head <locator-commit>
status: ok   exit code: 0
covered: synthetic-service/docs/overview.md:3 @ <locator-commit> (verified)
covered: synthetic-service/docs/protocol.md:5 @ <locator-commit> (verified)

不会在临时文件夹之外写入任何内容，完成后该文件夹也会被删除。

查看运行演示

观看 90 秒影片 → · 观看 30 秒剪辑 →

在你的仓库中使用

1. 在默认分支上安装可信策略（作为单独审核的变更，确保拉取请求永远无法削弱自身的门禁）：

mkdir -p .gitpin
curl -fsSL https://raw.githubusercontent.com/shmindmaster/gitpin/v0.6.4/templates/gate.yml -o .gitpin/gate.yml

2. 将其设为必需检查：

name: Agent delivery assurance
on: pull_request            # never pull_request_target
permissions:
  contents: read
jobs:
  evidence:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          ref: ${{ github.event.pull_request.head.sha }}
      - uses: shmindmaster/gitpin@514799cb0eae55e965e51d510d5e7a0a7604c9cc # v0.6.4
        with:
          base-sha: ${{ github.event.pull_request.base.sha }}
          head-sha: ${{ github.event.pull_request.head.sha }}

3. 每个 Agent PR 都要提交 .gitpin/change-evidence.json，以 templates/change-evidence.json 为起点。完整设置（包括规则集）请见 docs/pr-evidence-gate.md。

为你的 Agent 提供证据工具。 本地 MCP 服务允许 Claude Code、 Codex、Cursor 和其他 MCP 客户端查找候选项，并生成门禁检查所需的证据包：

# Run inside any committed Git repository
npx -y [email protected] init --client codex      # or claude-code, cursor, windsurf, zed, continue

init 会在仓库之外写入 ~/.gitpin/repositories.yaml，运行 doctor，打印一条包含完整 SHA 的首条证据，并打印可直接粘贴的 MCP 配置。它绝不会修改所注册的仓库。

工作原理

flowchart LR
  subgraph BASE["Trusted: base commit"]
    POL[".gitpin/gate.yml<br/>policy"]
  end
  subgraph HEAD["Submitted: head commit"]
    MAN[".gitpin/change-evidence.json<br/>claims → path, lines, sha256"]
  end
  DIFF["git diff merge-base..head<br/>the real change"]
  POL --> GATE{"gitpin gate<br/>read-only, never runs PR code"}
  MAN --> GATE
  DIFF --> GATE
  GATE -- "uncovered path, wrong hash,<br/>sensitive path" --> FAIL(["exit 1: check fails"])
  GATE -- "every changed path covered,<br/>every slice re-hashed" --> PASS(["exit 0: report with full-SHA citations"])
  PASS -.-> HUMAN(["Reviewer: git show &lt;sha&gt;:&lt;path&gt;"])

门禁通过 git show 读取可信基准提交中的策略，以及头部提交中的清单，绝不从工作树读取。它会比较合并基准差异，重新哈希每个引用的行片段，并生成一份引用中包含完整 SHA 的报告。

MCP 端遵循一个循环。搜索返回候选项，而非答案。证明会将候选项转为证据包。验证会通过 git show 重新检查：

pin.search_docs / pin.search_code   candidates only, with a forced next step
          → pin.prove               evidence pack: path, line, full SHA, content hash
          → pin.verify              independent git show re-check, HEAD match report
          → you: git show <sha>:<path>

工作	工具（12 个，全部只读）
发现	pin.catalog
查找候选项	pin.search_docs、pin.search_code
证明	pin.prove、pin.prove_set（1 到 8 条引用）、pin.get_doc、pin.read
验证	pin.verify、pin.verify_set
决策	pin.analyze → EvidenceBrief（已知事实、缺口、稳定的 evidenceSetId）
检查和比较差异	pin.inspect、pin.compare

资源 gitpin://catalog；提示词 prove-with-git-head。引用格式见 docs/cite-spec.md；Agent 技能模板见 templates/gitpin-skill.md。

防护措施与非目标

• 始终只读。 GitPin 绝不会向其读取的仓库写入、提交或推送内容，门禁也绝不会执行拉取请求代码。
• PR 无法削弱自身的门禁。 策略来自基准提交；证据来自头部提交；绝不读取有未提交更改的工作树。
• 未提交的工作绝不作为证据。 脏文件和未跟踪内容不会纳入 HEAD 引用。
• 敏感路径始终受到保护。 拒绝规则适用于证据，清单也不能引用自身。
• 候选项不是论据。 搜索输出会标记为 evidence-candidates，必须经过 pin.prove 处理。
• 无需嵌入、数据库或重新索引。 证据来自 Git 对象，因此可离线使用，也适用于私有仓库。

非目标：语义搜索、编写或提交代码、取代 GitHub Issues 或 PR 自动化，以及将非 Git 文件夹视为一个仓库。

状态与限制

此源代码树及其打包文档描述的是 GitPin 0.6.4，不代表其已发布。请分别查看各渠道：npm、MCP Registry（io.github.shmindmaster/gitpin）和 GitHub Releases。 需要 Node 20 或更高版本。网站：shmindmaster.github.io/gitpin。

GitPin 会验证覆盖范围、位置、修订版本和内容哈希。它能证明提交了什么，却不能证明论据为真：它无法验证语义正确性、运行时行为、作者身份、授权或合规性。这些判断仍由审核者负责，他们现在只需阅读一条引用行，无需再四处查找。计划中的工作见路线图。

配置

变量	用途
GITPIN_REGISTRY	注册表 YAML 路径（旧版兼容别名：REPOCONTEXT_REGISTRY）
GITPIN_MCP_TOKEN	HTTP bearer 令牌（旧版兼容别名：REPOCONTEXT_MCP_TOKEN）
GITPIN_ALLOWED_HOSTS	HTTP 主机允许列表（旧版兼容别名：REPOCONTEXT_ALLOWED_HOSTS）；当 HOST 不是环回地址时必需
HOST	HTTP 绑定地址；默认为 127.0.0.1。Dockerfile.remote 设置为 0.0.0.0

默认注册表：~/.gitpin/repositories.yaml（旧版兼容回退路径：若 ~/.repocontext/... 存在，则使用该路径）。

此前名为 RepoContext 0.3.x。请参阅迁移指南。

文档

工具 · PR 证据门禁 · 客户端 · 架构 · 对比 · 常见问题 · 故障排除 · 路线图 · 治理

贡献、安全与许可证

• 贡献： 报告 Bug 和提出建议时，请先创建 issue，然后遵循 CONTRIBUTING.md。适合新手的 issue 会标记为 good first issue。 提交拉取请求前，请运行：pnpm validate && pnpm build && pnpm verify:package。
• 安全： 请通过 GitHub 安全公告 私下报告漏洞，具体说明见 SECURITY.md。请勿公开创建 issue。
• 许可证： MIT。

由 Sarosh Hussain 创建并维护。相关开源项目： Assay 可避免 Agent 的决策产生副作用；CrewScore 会检查 Agent 的提示词是否写明了安全防护措施。