Agency Agents 确定性渲染器揭秘:1160 个文件的字节级一致性是如何做到的
Agency Agents 确定性渲染器揭秘:1160 个文件的字节级一致性是如何做到的
Agency Agents 是一款小巧的原生应用,负责浏览、安装并追踪 AI 编程工具的 Agent 角色(persona),而它最"硬核"的能力,藏在一段叫确定性渲染器的代码里。所谓确定性渲染器,就是同一个 Agent、同一个工具,永远渲染出一模一样的文件——没有任何时间戳、没有随机数。正是靠这个能力,Agency Agents 实现了 1160 个文件的字节级一致性:把 232 个 Agent 分别转换成 5 种不同工具格式,每一份输出都和上游转换脚本 convert.sh 逐字节相同。
这篇文章带你拆解:这个数字是怎么来的,为什么它对一款"安装包管理器"如此关键,以及它背后的工程约束。
为什么"字节级一致"是这款应用的命门
很多工具管理器都依赖一个隐藏的假设:我知道这个文件是我装的。Homebrew 靠自己的数据库知道哪些包是它装的,但 AI 编程工具之间没有统一的包数据库——Claude Code、Codex、Cursor、Gemini CLI、opencode 各写各的目录、各用各的格式。
Agency Agents 的解法很聪明:既然没有共享数据库,应用本身就当数据库。它维护一个本地台账(ledger),记录每一次安装的"来源哈希"和"渲染哈希"。当它需要判断某个磁盘上的文件是不是"自己装的、且是最新的"时,它不做任何猜测,而是——
用当前语料(corpus)里同一个 Agent、同一个工具重新渲染一遍,再把字节逐一对比。
这里的关键就来了:只有当渲染器是确定性的,"重新渲染"才有意义。如果渲染结果会因为时间、随机数或字段顺序而抖动,那么一个用上游脚本安装的文件就会被误判为"外来的(foreign)"或"已修改(modified)"。换句话说,字节级一致性不是锦上添花,而是整个安装状态模型(current / outdated / modified / removed / foreign)的承重墙。
这套规则被明确写进了 memory-bank/contracts.md 的"E. Determinism rules"部分,被标记为"non-negotiable"(不可妥协)。
1160 这个数字是怎么算出来的
答案藏在一次校验结果里:232 个 Agent × 5 种转换工具 = 1160。
这里的"转换工具"(transform tools)指的是那些需要把源 .md 文件重建成目标格式的工具,而不是原样透传的工具。目前参与对比的 5 种是:
| 工具 | 渲染格式 | 输出 |
|---|---|---|
| Cursor | cursor-mdc |
.cursor/rules/*.mdc |
| Codex | codex-toml |
~/.codex/agents/*.toml |
| Gemini CLI | gemini-md |
~/.gemini/agents/*.md |
| opencode | opencode-md |
.opencode/agents/*.md |
| Qwen Code | qwen-md |
~/.qwen/agents/*.md |
每个 Agent 对每种工具各渲染一份文件,232 个 Agent 乘以 5 种工具,就是 1160 份待比对文件。测试脚本会真正调用上游的 scripts/convert.sh 生成"标准答案",再和 Rust 渲染器的输出逐字节 diff——1160/1160 全部相同才通过。
确定性渲染器的核心规则
打开渲染器的核心实现 src-tauri/src/render/mod.rs,文件头部把契约写得明明白白:
每个渲染器都是
(Agent, raw source)的纯函数——没有时间戳、没有随机、键顺序稳定,所以rendered_hash可复现。
具体到代码,几条规则环环相扣:
- 无时间戳、无随机:输出只由输入决定,重跑多少次都一样。
- 哈希规范统一:所有哈希都是 UTF-8 字节的 SHA-256、小写十六进制(见
sha256_hex),保证前后端算出来的值一致。 - 逐字节复刻 shell 语义:这是最容易被忽视、也最难的部分。渲染器不是"大意上像"
convert.sh,而是把它每一行 shell 行为都精确移植过来——包括awk每行输出一个换行、命令替换会剥掉尾部所有换行、heredoc 只补回一个换行这些细枝末节。任何一个换行符的漂移,都会让整批文件对不上。 - 键顺序稳定:TOML、frontmatter 的字段顺序都是固定的,不依赖运行时环境。
一个有趣的细节:Qwen 的工具名会做一次"重命名"(比如 Read → read_file),因为 Qwen 只认它自己的工具名;OpenCode 的 color 字段也会被解析成标准的 #RRGGBB 十六进制。这些规则看似琐碎,却都是"字节级一致"必须钉死的细节。
工具注册表:一份 JSON 决定一切
所有工具的"安装契约"集中存放在 src-tauri/data/tools.json——这是后端和前端共享的唯一事实来源(single source of truth)。每个工具条目都携带:
format:渲染格式名。同一个format名保证字节级相同的输出,所以两个工具只有当它们渲染出的文件完全一致时才允许共享format。dest:安装路径模板(区分 user 级和 project 级)。scope/installKind:作用域和安装机制。
也就是说,"某个工具能不能被原生安装"是由它是否有对应的 format 渲染器推导出来的,而不是手写开关。新增一个工具,本质上是往这份 JSON 里加一个条目、在转换脚本里加一个 convert_<tool>。
字节级一致性测试如何被锁定
防止"今天一致、下周又漂了"的关键,是一个专门标注为 --ignored 的测试:upstream_convert_sh_is_byte_identical_for_transform_tools。它默认不随普通测试跑,需要在本地准备一份上游 agency-agents 克隆、设置 AGENCY_AGENTS_PARITY_ROOT 环境变量后显式触发,会真实调用上游转换脚本并逐工具 diff。
它的运行命令写在了发布清单 docs/BUILD.md 里,预期结果就是 1160/1160。这个测试在 memory-bank/tasks/2026-06/260614_phase-c-parity-safety.md 中被正式记录为一次里程碑:"Parity is the contract"(一致性就是契约)——转换脚本或语料任何改动之后,都必须重跑它。
除了一致性测试,Rust 侧还有 258 个常规单元测试覆盖渲染边界(引号转义、TOML 控制字符、颜色回退、slug 规则等),前端则有独立的校验流程,组合成 npm run build:phase-c 一键验证。
对普通用户意味着什么
对日常使用者来说,这些工程细节最终只兑现成一个体验:
- 装进去的文件,就是上游官方脚本会写出的文件——不是"近似",而是逐字节相同。你完全可以混用上游脚本和应用,两边产出的文件互相认得出、互相不冲突。
- 状态判断是可信的:Dashboard 上"安装健康度"显示的 In sync / Modified / Outdated,建立在可复现的字节比对之上,不会因为你没动过文件就莫名变红。
- 更新、移除、备份都有据可依:台账里存的就是渲染哈希,恢复时知道该还原成什么。
一句话总结:Agency Agents 用确定性渲染器 + 字节级一致性测试,把"AI 工具没有统一包数据库"这个尴尬的前提,变成了一个可验证、可回归、可放心依赖的本地安装数据库。
延伸阅读
- 渲染器核心实现:src-tauri/src/render/mod.rs
- 工具注册表(唯一事实来源):src-tauri/data/tools.json
- 确定性规则契约:memory-bank/contracts.md
- 一致性里程碑记录:memory-bank/tasks/2026-06/260614_phase-c-parity-safety.md
- 构建与校验流程:docs/BUILD.md


