Squire

Squire

Squire 是面向编码 Agent 的透明本地执行与验证层。它会让常用的仓库读取保持热状态，并持续维护当前声明的工作区状态是否已通过验证。

Agent 继续使用普通终端命令。Codex 启动本地只读命令前，Squire 会检查当前状态，并选择重放已证明的 mmap 观测结果，或基于经过哈希验证的当前文件字节执行小型有界操作。命中有效结果时，会返回完全一致的标准输出、标准错误和退出状态。每次未命中都会沿用 Codex 原有的原生执行路径。

安装

curl -fsSL https://raw.githubusercontent.com/reidgoodbar/squire/main/install.sh | bash

安装程序会验证 Squire 与 Squire-Codex 的发布归档是否匹配，并将驱动程序、Codex 运行时辅助程序和适用于主机原生环境的 Squire 运行时安装到 ~/.local/bin。它不会更改 Codex 身份验证或配置。支持的主机为运行于 amd64 或 arm64 的 macOS 和 Linux。

检查安装：

squire doctor

如果缺少任何必需的驱动程序、辅助程序、运行时或 ABI 组件，doctor 会以非零状态退出。

使用

从任意目录启动：

squire codex

这就是完整的用户操作流程。无需设置命令、全局 shell shim、提示词更改、MCP 工具、预加载注入或 VM 配置步骤。如果 Codex 随后进入某个仓库，Squire 会根据命令实际的 cwd 发现并准备该仓库。

squire-codex 也会作为便捷命令直接安装。

检查当前仓库和运行时：

squire status
squire status --json
squire explain -- git status --short

持续验证

在仓库编辑操作完成后，Squire Green 会在后台以原生方式运行声明的测试、lint、类型检查和构建。每项结果都与确切的声明输入字节、检查配置、环境和可执行文件绑定。之后的相关编辑会使该结果过期；无关编辑则不会。

# .squire/checks.toml
[[check]]
name = "tests"
command = ["go", "test", "./..."]
inputs = ["**/*.go", "go.mod", "go.sum"]
timeout = "10m"

首次使用时，仓库提供的命令绝不会静默运行。请先检查文件，再信任其确切哈希：

squire green trust
squire verify

任何配置更改都会撤销信任。随后，squire codex 会自动安排已信任的检查；无需第二个守护进程或预热命令。有关配置和证明语义，请参阅 docs/GREEN.md。

加速范围

生产通道受有界约束，但涵盖常见的只读命令范围：

• Git 元数据：受支持的 git rev-parse 形式和分支发现。
• 仓库读取：受支持的 git status、git ls-files 和 git diff 形式，包括路径限定的差异以及 git diff --check，还包括有界的 git log -N --oneline -- <literal paths> 历史记录。
• 文件和搜索读取：有界的 cat、有序的单范围或多范围 sed -n、head、tail、nl -ba、file、固定字符串 grep/rg、按需准备的有界仓库 rg 搜索，以及受限的 ls 形式。
• 环境发现：受支持的版本探测、which/command -v、安全的 printenv、whoami、id、hostname 和 uname 形式。
• 组合操作：针对受支持来源和过滤器的完整只读计划，包括管道、序列、重定向到 /dev/null、head、tail、有界的 sed -n、grep -F、wc -l 和 sort。

不会移除任何操作。构建、测试、编辑、安装、会更改状态的 Git 命令、展开、未知 shell 语法、敏感探测和不受支持的变体会立即沿用 Codex 不变的原生路径。安全的冷未命中也会沿用该路径，同时在后台请求精确准备。rg --files 不在有界准备策略范围内，会沿用原生路径。

受支持的命令会编译为类型化的有界计划，而非精确命令模板。来源证明与执行彼此独立：同一份已证明的文件快照可以满足不同的行选择、过滤器和组合操作，无需为每个命令字符串单独建立缓存条目。Go 引擎和原生运行时实现了相同的计划表示，使后续新增读取操作时只需扩展，同时通过差分测试确保 ABI 边界上的行为一致。

为什么命中是当前的

Squire 缓存的是观测结果，而非权威信息。前台重放要么重新计算可能影响该命令的输入，要么在完整的 kqueue/inotify 监视器报告依赖项未发生变化时，复用加密指纹。已准备的 epoch 仍必须匹配。证明输入包括规范化后的命令和 cwd、Git refs/index/config 及外部行为文件、相关工作区状态、规范路径、内容哈希、特定命令的环境证明，以及可执行文件身份。监视器一旦失效，驻留证明就会失效。

对于有界文件读取，epoch 不匹配时也可以改用当前文件通道：Squire 在计算前台 SHA-256 证明时保留读取到的确切字节，并且只对这些字节应用固定的字节语法。此过程无需重新预热，也不会持久化文件或结果。缓存中仍可能包含过时记录，但证明不匹配后绝不会重放这些记录。状态缺失、数据损坏、语法不受支持、ABI 不匹配或证明无利可图，都会触发原生回退。

失效测试套件会在不改变大小或 mtime 的情况下更改文件字节，修改 Git 索引和未跟踪文件集，更改大小相同的差异，编辑 Git 配置，创建提交，重命名分支，更改松散和打包对象命名空间，更改环境输入，并探测工作区外的符号链接。若返回旧字节或发生不安全命中，发布就会失败。

完整的不变量请参见 SQUIRE_CONTRACT.md。

当前运行时检查

2026 年 7 月 16 日，一次包含 500 条命令的随机化生产 ABI 运行记录到 421 次精确命中、79 次安全回退、468 次原生对比、零次不匹配和零次不安全命中。命中延迟 p50/p95/p99 为 0.315/0.630/0.933ms；相同命令以原生方式运行时为 8.084/27.692/51.820ms。另一次包含 500 个查询的仓库搜索差分测试得到 500 次精确或顺序等价命中，语义不匹配为零。有界路径历史记录的 28 次查询全部精确，p50 为 0.333ms、p99 为 0.492ms，而原生 p50 为 20.060ms。全部 2,048 次稳定状态调用均精确，墙钟时间 p99 为 0.433ms。在 8 路负载下，CPU p99 为 0.334ms；受调度器竞争影响的墙钟时间 p99 为 3.242ms。

新鲜的实时 gpt-5.6-luna 测试分别重放了 2/3 次 Express 调用（66.7%）、5/5 次 Flask 调用（100%）和 4/5 次 fmt 调用（80%）。每次测试均通过了 50% 的所有终端调用门槛，记账有效且诊断不匹配为零。这些小规模实时样本用于验证覆盖率，而非整项任务的因果墙钟时间；模型在看到工具结果前，其执行轨迹便已出现分歧。

一项确定性的 40 对 Codex 归因测试固定了模型响应、命令、工作区和终端负载。6 次串行调用的耗时从 374.876ms 降至 103.600ms，节省 271.277ms（72.4%，配对 95% 区间为 265.630-276.540ms）。两个并行批次节省了 52.6%。AB 和 BA 顺序均保持正向收益，而交错的 A/A 和 B/B 区间则包含零。

完整方法和历史表格：docs/BENCHMARKS.md。

架构和后端说明：docs/ADVANCED.md。