PolyLoop/research-wiki/design/0015-parameter-snapshot-contract.md

Design 0015 · 参数快照的内容契约

日期 2026-08-26 · 状态 已接受（2026-08-26 项目负责人确认）

回答 实验室 Gitea 上 PolyLoop 仓库的两个 issue，提出者都是下游项目 dissect2：#3 标题是 「提示词模板的哈希在参数快照里没有位置」，#4 标题是「注入的『通道』维度在参数快照里被拍平」。 两份指的是同一类缺口——一件影响这次运行的事实没有进参数快照。

补充 0003-public-api-shape.md 决策三里请求那张字段表，往上加一个字段；以及 0006-public-names-and-signatures.md 定的公共名字与签名，本文给新增的快照键定形状。这两份的 其余部分不受影响。

触及 ../../src/polyloop/session/__init__.py 里 RunRequest 的字段与两处 parameter_snapshot、../../src/polyloop/_assembly/__init__.py 里 injected_entry_ids 的返回 类型、../../src/polyloop/types/__init__.py 里 Injection.entry_id 的注释，以及 ../explanation/architecture.md 第十节「装配形态」里讲请求持有什么的那一段。不回写这几处， 本文就是死的——写代码的人读的是代码和常青文档，不会为了传一个字段跑来翻 design/。

背景

一次运行的配置分成两半，各是一个不可变对象，两个合起来叫这次运行的装配。跨运行不变、 可以并发复用的那一半是 AgentDefinition：模型调用、决策解释、存储、事件出口四个接缝，以及 库在动作被拒绝或环境故障时合成的那几段观察。每次运行都不同的那一半是 RunRequest：运行 标识、预算、动作执行接缝、本次可见的工具集、上下文、注入内容、模型绑定等等。参数快照就是从 这两个装配对象上现算出来的一份「这次跑的是什么设置」。

参数快照是续跑守卫的全部依据。resume 把当前装配现算的快照和日志里存着的那份逐字段比对， 任何一项对不上就抛 ParameterDriftError，拒绝往下跑。它拦的是一种没有失败现场的事故：崩溃 之后用同一个运行标识、换一份配置续跑，前几步和后几步来自两套配置，而全程零报错，两段轨迹在 文件里看起来是同一次运行。

守卫的强度完全由快照的内容决定。一件影响这次运行的事实没有进快照，等于它换了也不会有人 知道——比对的时候那一项根本不在场。

现在快照里有这些：预算的四项、模型调用的重放策略、观察模板、取消宽限期、本次可见的工具名 清单、模型绑定的全部键值、这次贴进上下文的那些注入条目的标识（键 request.injected_entry_ids）， 以及五个接缝各自上报的参数（四个挂在定义上，动作执行接缝挂在请求上）。issue #3 与 #4 各指出 一处漏在外面的事实，两份都来自同一个下游、同一档实验需求。

决策一：请求上开一个 fingerprints 字段，收「这次运行用的是哪一版配方」

RunRequest 新增字段 fingerprints: Mapping[str, str]，默认空映射。它的每一个键值都进快照， 键形如 request.fingerprint.<name>——单数，与已有的 request.binding.<key> 对齐。

默认空映射时快照里一个键都不写，不是写一个值为空串的键。这样今天已经在跑的配置算出来的 快照逐字节不变，只有真的传了指纹的运行才多出那几项。

为什么需要它

上下文的正文与注入条目的正文是刻意不进快照的，理由是它们属于这次运行的输入数据而不是 参数：进快照会让快照变成一份数据副本，而它们可能很大。

注入这一侧不进快照的只有正文，条目的标识是进的。 正文和标识是两样东西：正文是贴给模型 看的那段文本，标识是这条注入的名字。所以「这次贴了哪几条」事后查得到，查不到的只是那几条各自 写了什么。上下文那一侧没有对应的标识可以留，它是一段已经渲染好的消息序列，本身不带名字。

把正文挡在外面这条理由没错，但它顺手把生成这些数据的东西也挡在了外面。提示词模板不是 数据，是参数——它是一份跨运行复用的配方，每次运行拿它渲染出这一次的上下文。

提 issue 的下游研究的正是「改这份文本会让 agent 表现好多少」，模板是被系统地改动的东西之一。 不记的话，「这次用的是哪一版提示词」就只剩下 harness 的 git 提交这一个粒度，而同一个提交下 完全可以试好几份不同的模板。具体的失败场景是：换一份模板、用同一个运行标识续跑，前几步用 A、后几步用 B，全程零报错，那次运行的数据已经废了却没有任何东西提示。

为什么放请求不放定义

请求级能表达定义级能表达的一切，反过来不行。一样东西每次运行都一样，把它放在请求上、每次传 同样的值就是了，快照比对照样成立；而一样东西每次运行都不同，放在定义上就没有办法表达——定义 是跨运行并发复用的，它上面的值不能随运行变。

库无从知道下游会往 fingerprints 里放什么。已知的那个需求（提示词模板的 sha）确实跨运行不 变，但同一个字段将来会收「这次注入的技能库是哪一版」这类每次都变的东西。既然要选一个位置， 就选能覆盖两种情况的那个。

辅一条：缺口的位置本来就在请求这一侧。定义上那四个接缝各有一个 parameters() 方法，能自报 自己的指纹；请求这边只有动作执行接缝有。剩下没有人能替它们说话的是上下文和注入内容——它们是 纯数据，没有一个对象可以发问，而模板正是生成上下文的东西。

那定义与请求那个「跨运行变不变」的切点怎么办？它是切分两个装配对象的依据，但它不是一条能 逐字段套用的规则，Context.run_level 就是现成的反例：那一段装的是角色说明、示例演示、能力 描述，在一批运行里通常一字不变，它却住在请求上——因为它和逐题变化的 goal_level 是同一份 渲染的产物，拆到两个装配对象上会逼调用方在两个地方保持一致。模板的指纹和它渲染出来的上下文 是同一件事的两面，同理。

它和 model_binding 的区别

两个字段形状相同：都是下游自由定义键名的字符串映射，都进快照，库都不解释内容。含义不同。

字段	记的是什么	库怎么用
model_binding	这次运行属于哪一格：哪个账本、第几轮、哪道题、第几次尝试	进快照，并原样透传给每次模型调用
fingerprints	这次运行用的材料是哪一版	只进快照

坐标和配方版本混在一个字段里，事后分不开：一组键值里既有「第 3 轮」又有一个 sha，要靠键名的 命名约定去猜哪个是哪个，而命名约定不在任何一处被断言。提 issue 的下游已经在考虑把模板的 sha 塞进 model_binding——那样功能上是通的，透传出去的绑定里多一个键，网关也不在乎；但语义不 对，而且下一个下游看见了会跟着学，几个月后这个字段里什么都有。

值的形状库不解释，但 docstring 里给一条建议

建议值里带上算法前缀，形如 sha256:<hex>。理由是换算法的那天，不带前缀的旧记录和新记录会以 「两个不同的十六进制串」的形式参与比对，报出来的漂移看不出是换了算法还是内容真的变了；带前 缀则一眼看得出。

这是建议，不是校验。库不解释这个值，也就没有立场规定它长什么样——真去校验，等于替下游定了它 能用哪几种哈希。

业界怎么用 fingerprint 这个词

最贴的先例是实验记录框架 Sacred。它把「这次用到的源文件及其 md5」放在 sources 里，与参数 config 平级分开，而不是塞进同一个字典——和这里让 fingerprints 与 model_binding 各占一个 字段是同一个形状，理由也一样：材料版本和参数坐标混在一处，事后分不开。带算法前缀那条跟的是 OCI 镜像摘要的写法。

决策二：注入的通道维度在快照里保留，一个通道一个键

请求上的注入内容是一个映射：键是通道名，值是这个通道里的一串条目，每个条目由一个标识 和一段正文组成。通道名由调用方自己定，库里没有任何预定义的通道，也不校验通道名的形状；一个 通道里放几条同样由调用方决定。通道存在的意义是把来源不同的注入分开——同一次运行里，来自两个 不同挑选过程的材料各占一个通道。

库只负责贴和记录贴了什么，不负责生成、评测、挑选。 装配时 _assembly.injection_messages() 把这些条目摊平成一串消息贴进提示词，一个条目一条消息，正文原样，前后不加任何标题或分隔符； _assembly.injected_entry_ids() 把同一批条目的标识收成快照要写的那份记录。挑哪几条进来是调用 方在调 run() 之前就做完的事。所以「声明了这个通道但一条都没选中」这种情形，从库这一侧看到的 只是一个条目为空的通道，那次筛选的过程库全程不在场。

注入按通道分组进快照，一个通道一项：键是 request.injected_entry_ids.<通道名>，值是那个通道 里的条目标识按 injection_messages 的同一顺序拼成的逗号串。原来那个把所有通道拍平成一个键的 写法作废。

_assembly.injected_entry_ids() 的返回类型跟着改：从扁平元组改成按通道名字典序排好的映射。

两个排序的理由不一样

通道内的条目跟着 injection_messages 排，因为这个顺序有意义。 它决定这几条注入贴进提示词 的先后，也就决定了模型看到的是什么。顺序变了就是配置变了，续跑该报漂移。两个函数同序还有一条 更硬的理由：不同序的话，快照记的贴入顺序和模型真正看到的顺序是两回事，而续跑守卫照样全绿。

通道之间按通道名字典序，纯粹是为了确定性，这个顺序本身不承载任何含义。 调用方传进来的是一 个映射，它的迭代顺序取决于调用方怎么构造它——用推导式从一个集合建出来的话，Python 的字符串哈希 每进程随机，于是同一份配置在不同进程里摊平出的消息顺序不同，渲染出来的提示词也就不同。字典序 把这个不确定性去掉。

拍平之后丢掉的两样东西

通道名在拍平的写法里只用来定顺序，排完就没了，于是「哪几条来自哪个通道」事后查不到。

更要紧的是另一样：「声明了这个通道但一条都没选中」和「压根没有这个通道」在拍平之后是同一个 结果——两种情况下这个通道对快照的贡献都是零，它在记录里彻底不出现。提 issue 的下游有一档实验 要测「注入的内容到底起没起作用」，它要比较的正是这两种情形：一组运行声明了通道而选中零条， 另一组连通道都不声明。两者在记录里长得一样，那一档就测不了。

按通道成键之后这两种情形分得开：声明了通道但为空，是一个值为空串的键；压根没有这个通道，是 这个键不存在。

为什么不在 RunResult 上另透一份

issue 里提到的另一个做法是把带通道的结构挂到 RunResult 上。否掉，两条理由。RunResult 是会 被下游存进数据库和实验数据集的持久化结构，往它上面加字段要同时抬 schema 版本，代价高一档。 而且同一个事实放两处，迟早有一处被改而另一处没改，到那时两处不一致，谁对没有答案。快照已经 承载了这个事实，让它承载全。

顺带改正三处把快照说成轨迹的 docstring

代码里有三处说条目标识「进轨迹」：types/__init__.py 里 Injection.entry_id 的字段注释、 session/__init__.py 里 RunRequest.parameter_snapshot 的 docstring、_assembly/__init__.py 里 injected_entry_ids 的 docstring。这个说法是错的，本次一并改正。

轨迹是步记录的序列，一步一条，记的是这一步模型说了什么、动作是什么、观察是什么。条目标识不 在里面。它进的是运行开始记录里的参数快照，一次运行只写一条，写在开工之前。照现在的 docstring 去找，下游会在步记录里翻一个不存在的列，翻不到之后多半会得出「库没记这件事」的结论，而它 明明记了。

改正和决策二本来就要做的事发生在同一处：Injection.entry_id 那段注释还要补上下面那条分隔符 约束。

分隔符是一个已知的、不打算修的限制

快照的值是字符串，把一串条目标识压进一个值里就得选一个分隔符。条目标识里如果真含逗号，两组 不同的注入可能拼出同一个串，于是一次本该报出来的漂移没有报。通道名同理。

不修的理由是：快照的值只用于逐字段比对，从来不被解析回列表；而人要肉眼看快照排查漂移，换成 JSON 编码会让它读不动——一份几十行的快照里混着转义引号和方括号，「哪一项变了」这个问题的答案 就得靠工具才看得出来。已有的 request.tools 是同样的形状、同样的限制，这里不为新键单独定 一套。

代价是给下游留一句约束：标识里不要放逗号。这句话写进 Injection.entry_id 的注释，因为那是 写代码的人会读到的地方。

决策三：快照的取值必须是字符串，在开跑之前就守住

两个校验点。RunRequest.__post_init__ 校验 fingerprints 与 model_binding 的每一个键和每 一个值都是 str。两处 parameter_snapshot()——AgentDefinition 那个和 RunRequest 那个——在 聚合接缝上报的参数时，校验接缝返回的键值都是 str。不合格用显式异常拒绝。

用异常不用 assert：python -O 会把断言整条移除，下游拿 -O 跑的那天这道校验就静默消失 了，而它守的正是一件静默出错的事。

只有第一个校验点在构造期

RunRequest.__post_init__ 那个是真正的构造期：此时什么都还没发生，没有 I/O、没有日志、没有 模型调用，拒绝的代价是零。

聚合那个不在构造期。AgentDefinition.parameter_snapshot() 是方法不是字段，构造定义时不向任何 接缝发问，发问发生在首次算快照的时候，而那时 run() 已经读过一次存储日志了。它保证的不是零 代价，是校验发生在写运行开始记录之前，也就是在任何一次模型调用之前：不会跑完一整次运行、 把钱花光，才在续跑时发现快照里有一项存不下去。

两个点的强度不同：一个构造得出来的定义对象并不保证算得出合法快照——构造它的时候那四个 接缝一次都没被问过。某个接缝的 parameters() 返回一个整数，定义照样构造成功，要到首次算 快照时才被拒绝。

为什么要提前到这里

快照的取值类型已经是持久化契约的一部分：反序列化那一侧读到非字符串会直接失败， tests/unit/test_serialization.py 有一条测试钉着它。但那个失败发生在续跑读日志的时候—— 这次运行已经完整跑过一遍，钱花完了，日志也已经写下去了，才发现里面有一项读不回来。而且发现 它的前提是真的有人来续跑；没人续跑，那份存坏了的日志就一直躺着，直到有人拿它做统计。

为什么连接缝上报的参数一起校验

接缝实现由下游写，它返回什么算外部输入（../../CLAUDE.md §6：适配器返回算外部输入）。五个 接缝里任何一个的 parameters() 返回一个整数，症状都一样：这次运行照常跑完，续跑时才炸。

校验放在聚合的那一处，而不是分散到五个实现里，是为了让「快照的取值都是字符串」成为一条真的 被守住的不变量。写在五个实现里的话，它只是五份各自的自觉，而下游写的适配器根本不在我们的 自觉范围内。

model_binding 一起改是有意的

它和 fingerprints 语义同族、形状相同，只给新字段加校验会让两个看起来一样的字段行为不一样。 那种不一致比两个都不校验更难查——查的人会先怀疑自己传错了字段，而不是怀疑库对两个同形状的 字段处置不同。

代价

快照的键形状变了，跨版本续跑会报漂移。 用旧版本跑到一半的运行，升级本库之后再 resume， 会因为 request.injected_entry_ids 这个键消失、request.injected_entry_ids.<通道名> 那几个键 出现而抛 ParameterDriftError。这个失败是响亮的，不是静默的：错误信息会把漂移的键逐个列 出来。

这不构成 ../../CLAUDE.md §1.3 意义上的破坏性变更。 快照的键集合从来不是公共承诺。下游 换一个存储实现、改一个接缝的 parameters() 返回什么，快照就变、续跑就报漂移——这本来就是 这套设计的一部分，也是它该有的行为。库自己改快照的键属于同一类事件，处置也一样：那次运行 重新开始，或者接受它跑不完。

fingerprints 有变成垃圾桶的风险。 一个「什么都能塞」的自由映射，判据不写清楚就会长成 第二个 model_binding：今天进去一个模板 sha，明天进去一个「本次实验的备注」，后天进去一个 时间戳，而时间戳每次都不同，续跑必然报漂移。缓解只有两条，都不是机器能查的——docstring 里 那条「坐标还是配方版本」的分界，以及评审。

决策三的第一个校验点让请求的构造多了一次遍历。 请求承诺构造廉价：无 I/O、无网络校验、 无哈希计算。遍历两个通常只有个位数条目的映射不违背这条承诺，但它确实不是零成本。记在这里， 是为了下次有人往 __post_init__ 里加东西时能看见这笔账已经开过一次。

留给后续的

快照的键空间没有任何机器保证不撞车。 request.binding.<key>、request.fingerprint.<name>、 request.injected_entry_ids.<通道名> 三处的后半截都是下游给的自由字符串，库不校验它们的形状。 现在三个前缀互不相同，所以撞不了；再往快照里加一个带自由后缀的前缀时，要重新检查这件事。

0003 决策三的请求字段表有一笔没做的欠账，而它即将被盖掉。 那张表里有「工具段渲染 样式」这一项，architecture.md 第十节跟着写请求持有十一样数据；代码里 RunRequest 只有十个 字段，搜不到任何对应物。这是那张表里唯一一笔有表无码的欠账。0014 处理的另外两笔不在这张 表里：承诺过的内存存储实现来自 0003 否决方案那一节，契约套件发不出去则和 0003 无关。

危险不在这处漂移本身，在于它即将被盖住：加上 fingerprints 之后请求的字段数恰好变成十一， 第十节那个数字会重新对上，而组成完全不同。所以回写第十节时要照代码把那一段的字段逐项重写， 不是把数字改对——数字对上的那天，这笔欠账就再也没人看得见了。