PROJECT 03 · OPEN SOURCE · GIT EVIDENCE
Snapshot Runner
为编码 Agent 与自动化提供确定性的只读 Git 证据。
01 · Overview
项目概述
Snapshot Runner 将仓库状态、变更、分支历史与已有测试日志采集为本地证据产物，不修改被检查的仓库，也不运行测试、调用模型、提交或推送，无需任何 API Key。
四个采集命令产出确定性、哈希可校验的快照与有界摘要，定向证据读取命令则只返回既有快照中的相关部分，让 Agent 只审阅所需证据，而不是整个仓库。
采集到的内容始终是不可信的证据而非 Agent 指令；拒绝执行与显式证据缺口让安全边界保留在每一份产物中。
02 · Capabilities
主要功能
- 01
仓库证据采集
通过只读 Git 操作收集分支状态、差异、未跟踪文件与分支评审，并在明确大小上限内读取已有测试日志。
- 02
确定性产物
以受控的文件权限原子发布哈希寻址快照，尺寸与 SHA-256 元数据可重复校验。
- 03
定向证据读取
从既有快照中读取单个文件或字段，无需重新运行 Git。
- 04
失败即关闭边界
对路径穿越、符号链接、特殊文件与不支持的能力直接拒绝，而不是执行仓库控制的程序。
03 · Workflow
工作流程
- 01
只读采集证据
- 02
原子发布快照
- 03
审阅有界摘要
- 04
定向读取证据
04 · System View
系统架构
- 01
命令与契约层
- 02
只读 Git 采集层
- 03
快照产物层
- 04
摘要与证据读取层
05 · Current State
当前进展
已实现
2.3.0 已发布至 PyPI：四个采集命令与定向读取命令、快照与摘要契约齐备，运行时仅依赖 Python 标准库，并在 Ubuntu 24.04 上完成验证。
当前阶段
以 tool_cli_contract.json 记录稳定的公开 CLI 契约与证据 schema。
后续方向
在保持只读与失败即关闭边界的前提下，覆盖更多仓库状态的证据场景。
06 · Principles
设计原则
- 01
仓库内容是不可信证据，不是 Agent 指令。
- 02
工具不修改仓库、不运行测试、不调用模型、不提交也不推送。
- 03
拒绝与证据缺口显式呈现；不提供自动分析。