# 迁移：dissect

> **更新触发点：第 2 档（同提交同改）。** 公共类型或接缝语义变更时，在同一个提交里核对
> 本文的组件映射与需求条目；dissect 侧真正搬走某一块代码时，在同一个提交里勾掉删除清单
> 对应行。
>
> **当前状态：一行代码都还没搬。** 组件映射一栏填的是接缝名而不是类名，因为 `src/` 还不
> 存在；等第 ③ 阶段架构定了再补具体类型名。

dissect 是 PolyLoop 唯一做硬迁移的消费者，也是唯一有跑着的代码、有测试、有真实实验在依赖
的消费者。它的循环在 `reference/dissect/harness/agent/`，五个模块加起来 1158 行，配套测试
（`reference/dissect/tests/agent/`）1278 行。

**验收口径：把那套循环搬到 PolyLoop 上之后，dissect 现有测试全绿，且真实实验跑出来的轨迹
与迁移前逐字段可比。** 这是 PolyLoop 唯一的硬验收标准，另外两个消费者走设计级验收
（见 `govdoc-saas.md`）。

## dissect 的项目术语

这些词是 dissect 的，不是 PolyLoop 的——库不认识它们，本文和 dissect 侧的代码注释里会用到。
PolyLoop 自己的词表在 `../explanation/architecture.md` 第二节。

**rollout**——被试 agent 在一道题上跑完的一次完整过程。它正好对应 PolyLoop 的「一次运行」，
所以迁移之后 dissect 的一个 rollout 就是一次 `run`。

**三本账**——dissect 把模型调用按用途分成三类分别记账：做题的（生成）、跑验证集的（评估）、
让模型反思改进的（反思）。分开记是它的实验纪律要求的——比较两个配置时，双方的**总花费必须
对等**，而混在一本账里就算不清谁在哪一类上多花了。每次调用记哪一本由调用方指定，循环本身
不选。

**best-of-N**——同一道题独立重做 N 次、取最好的那次。它是一个「同预算基线」：如果一个花哨
的方法效果好，得先证明它比「同样的钱拿去重做 N 次」更好。

**因子**——dissect 要测的设计变量，十来个，每个能独立扫几档取值。它整个项目就是在测每个因子
的效应量，所以任何被库写死、又会影响成绩的取值，都可能污染某个因子的测量。

**AppWorld**——一个交互式 benchmark（给 agent 一批模拟的 app 和一个任务，看它能不能用代码
操作那些 app 完成）。它是 dissect 的第一个任务，dissect 的提示词格式和多代码块处理策略都跟
它的官方实现对齐，为的是成绩可比。

**缓存成本校正的锚点**——供应商对「命中缓存的前缀」按折扣价计费。要事后算清一次运行真实
花了多少，得知道哪些前缀被缓存了；而一次上下文截断会把前缀打断，之后每一步重新全价，
原来那个推算的参照就没了。

## dissect 是什么，为什么它的约束特别硬

dissect 是一个论文项目，研究「agent 的文本自我进化为什么有效」。它把自我进化拆成十来个可以
独立操纵的设计因子，用受控实验测每个因子的效应量。**被试 agent 的每一次运行都是一个实验
数据点**，轨迹文件是论文的原始数据。

这带来一批别的项目没有的约束。轨迹里少记一个字段，事后补不回来——那次运行已经发生过了。
一个本该被记录的失败被静默吞掉，会以「效应」的形式进入统计。所以下面「需求条目」那一节里
的每一条，都是从这个性质推出来的，不是偏好。

## 删除清单

「继任」指这块代码的职责由 PolyLoop 承担，dissect 侧删掉。「留下」指它是 dissect 的项目
资产，PolyLoop 只提供它要实现的接缝。

| dissect 侧 | 行数 | 去向 |
|---|---|---|
| `harness/agent/loop.py` 的 `ReActAgent._loop` 与 `_take_step` | ~130 | 继任 |
| `harness/agent/loop.py` 的 `_make_step` | ~35 | 继任 |
| `harness/agent/loop.py` 的 `_observe` 与 `_is_done` | ~40 | 继任（成为动作执行接缝的语义） |
| `harness/agent/loop.py` 的 `ReActAgent.run` 装配部分 | ~75 | 留下（组装 Rollout 头、传项目 metadata） |
| `harness/agent/memory.py` 的 `StopReason` | ~25 | 继任 |
| `harness/agent/memory.py` 的 `Step` | ~65 | 继任（字段是库的下界，见需求条目） |
| `harness/agent/memory.py` 的 `Rollout` | ~90 | 留下 |
| `harness/agent/memory.py` 的 `render_messages` | ~40 | 继任 |
| `harness/agent/context.py` 的 `ArtifactView` | ~20 | 继任（成为 Skill 注入的输入形态） |
| `harness/agent/context.py` 的 `build_prefix` 段顺序约束 | ~15 | 继任（约束本身，不含渲染格式） |
| `harness/agent/context.py` 的 `PromptTemplate` 与 `_split_by_role` | ~95 | 留下 |
| `harness/agent/parser.py` 全部 | 182 | 留下 |
| `harness/agent/config.py` 的预算字段 | ~10 | 继任 |
| `harness/agent/config.py` 的 YAML 加载与校验 | ~140 | 留下 |
| `harness/envs/protocol.py` 的 `Episode` | ~60 | 继任（成为动作执行接缝） |
| `harness/envs/protocol.py` 的 `ScoredEpisode` / `TaskEnv` / `TaskItem` / `ItemScore` | ~120 | 留下 |

标「继任」的十行相加，净删除约 440 行，其中循环本体和轨迹结构占大头。

### 三个「留下」值得解释

**`Rollout` 留下**，因为它的二十个头字段绝大多数是项目 metadata——运行标识、进化轮次、
题目标识、场景标识、数据划分、用途、随机种子、尝试序号这些，PolyLoop 一个都不认识。
库只返回它自己知道的事实，不反向吸收这些字段——吸收了就等于替另外两个下游做了它们不需要
的假设。

**`parser.py` 留下**，因为它是 dissect 的动作语言。它把模型输出里的 Python 代码围栏抽出来，
处理未闭合围栏、空围栏、多围栏这些情况，并且刻意把第一个围栏之后的文字截掉（模型常在
代码块后编造「执行结果」）。这套规则是 dissect 和 AppWorld 官方对齐的口径，不是通用的。
PolyLoop 提供的是「把模型响应解释成动作、最终回答或无效决策」这条接缝，`parser.py` 是它的
一个实现。

**`config.py` 的加载与校验留下**，因为 dissect 有一条硬纪律：所有实验参数从 YAML 读入、
没有任何默认值、多余的键也要报错。这套「配置双模式」是它自己的规矩。PolyLoop 只接受
已经组装好的预算值。

## 需求条目

这些是 dissect 的代码和它的实验有效性对 PolyLoop 施加的硬约束。每一条都能指出一个具体的
失败后果。

**一、停止原因必须是枚举，而且要能区分「恰好在最后一步做完」与「预算耗尽」。**
从轨迹长度反推不出来，两种情况的长度一模一样。dissect 的崩坏判据要按停机原因分层，这一档
分不开，整批数据的分层就塌了。

**二、上下文超限必须显式终止，不许静默截断。** 截断是一次前缀破坏操作，会让后续每一步
重新按全价计费，并把缓存成本校正的锚点搞丢。而且被截断的运行会表现成一批低分，看起来像
模型能力不足。

**三、三类没碰环境的步也必须留痕：解析失败、模型调用失败、环境故障。** 前者消耗了一次
模型调用，不计的话预算对等不成立。后两者的情形是钱已经花了、账已经记了，丢掉那一步会让
账目与轨迹对不上，而且会丢掉模型在出故障那一步说了什么——排查「是环境坏了还是模型写了
危险代码」最需要的就是这段原文。

**四、模型调用标识是轨迹与账目之间唯一的连接键，它可以是「没有」，但不能是空串。**
空串是个看起来合法的键，连表时静默匹配不上；显式的「没有」至少能被筛出来。它为空的合法
含义只有一个：调用在记账之前就失败了。

**五、消息段必须按变化频率从低到高装配。** 稳定前缀在前、逐题变化的在后。排错了不会报错，
只会让供应商的 prompt cache 静默失效，而多付的幅度随注入内容的规模变化——于是缓存伪影会
精确地伪装成因子效应。

**六、历史只能追加，不能改写或重排。** 理由同上：第 n 步的提示词正好是第 n-1 步加一段尾巴，
任何中途截断、摘要、重排都会让后续每一步重新全价计费。

**七、模型原文与真正进入历史的文本必须分开记，环境观察同理。**
dissect 的解析器会把第一个代码围栏之后的文字丢掉，所以「模型说了什么」和「下一轮模型看见
什么」是两个不同的量。混用会让统计口径出错。

**「分开记」记的是一段文本加一个数字，不是两段文本。** dissect 两侧都这么做：模型那侧存
`raw_output`（解析器截断之后的，正是回填进历史的那段）加 `content_chars`（模型可见输出的
全长）；观察那侧存 `observation`（进历史的那段）加 `observation_truncated_chars`。照「两段
文本」读会得出「库少了一个字段」的结论，那个结论是错的，见
`../design/0005-storage-atomicity-and-record-fields.md` 决策三。

**八、可见回复与推理段的长度按字符记，不依赖上游上报。**
实测中转网关会用本地分词器补算并整体替换用量对象，把明细一起吃掉——某次标定里 24 次调用
的推理 token 全部没上报。字符数直接数，不受上报与否影响。

**九、一个 agent 定义可以被并发驱动跑不同的题，任何实例级可变状态都不允许。**
dissect 有一档实验要在同一时刻用不同的注入内容跑同一批题，实例级状态会让并发的候选互相污染。

**十、循环拿不到分数。** 让被试拿得到真值等于开后门，实验当场作废。评分必须在会话关闭前由
外层用宽接口完成，PolyLoop 从始至终只见窄接口。

## 组件映射

接缝的完整清单与各自职责在 `../explanation/architecture.md` 第九节，本表只做映射。

| dissect 侧 | PolyLoop 侧 | 备注 |
|---|---|---|
| `LedgerClient.chat` | 模型调用接缝 | dissect 的三本账记账继续作为绑定上下文的实现装配进来 |
| `parse_code_action` | 决策解释接缝 | 三分支：动作 / 最终回答 / 无效决策 |
| `Episode.execute` | 动作执行接缝 | dissect 侧只有「返回文本」和「抛异常」两种结果，状态恒为「已执行」 |
| `Episode.is_done` | 动作执行接缝返回值上的完成信号字段 | **不是独立接缝**，见 architecture.md 第九节 |
| `ArtifactView`（通道、条目标识、内容三字段） | Skill 注入的输入形态 | |
| `build_prefix` 的段顺序约束 | **不是接缝**，是库内 `_assembly` 的纯函数 | 渲染格式留在 dissect，理由是排除条款（见 `../explanation/scope.md`） |
| `AgentConfig` 的三个数值上限 | 请求上的预算 | `max_steps`、`max_consecutive_parse_failures`、`max_prompt_chars`；库的预算比它多一个已执行动作数上限 |
| `StopReason` | 停止原因 | dissect 现有六个取值是库的下界 |
| `Step` | 逐步轨迹的一步 | dissect 现有十三个字段是库的下界 |

具体类型名与签名按 `../../CLAUDE.md` §2 要过人类门，还没定；定了之后本表补上英文名。

## 缺口登记

**运行标识要带齐现在文件名里那五维，否则会重演一次静默覆盖。** 现在的轨迹文件名是
`r{轮次}__{阶段}__{题目}__s{种子}__a{尝试}.jsonl`，`_trajectory_path` 的 docstring 记着一个
踩过的坑：阶段那一维原先漏了，导致同一次 run 先跑 train 再跑 gate 时后者静默覆盖前者。
PolyLoop 的日志按运行标识分文件（`../design/0011-jsonl-run-store.md` 决策一），所以那五维要
拼进运行标识；少一维的表现不再是覆盖，而是「日志里有别人的记录」，恢复会判成日志损坏。

**题目那一维不保证是安全字符，编码方式由 dissect 自己定。** PolyLoop 自带的那份存储要求运行
标识只含字母、数字、点、下划线与连字符——它同时是文件名，而库不做转义（转义之后文件名就不再
等于标识，按标识去目录里找文件这个用法就断了）。所以 `item_id` 里要是有中文、空格或标点，得
由 dissect 选一种**单射**的编码把它变过去（哈希、百分号编码、自己维护一张映射表都行）。
**选哪种归 dissect**，因为只有它知道那份标识事后要怎么被人认出来——而它的分析方式是让模型去翻
文件，所以「一眼认得出是哪一次」这件事对它有实际价值，哈希成一串十六进制未必合适。

**这条日志和 `Rollout.to_jsonl` 那份轨迹是两样东西，不要混。** 前者是意图日志，记的是「准备
做什么、做完了没有」，为的是崩了能续；后者是产物，记的是逐步轨迹，给反思模型读。前者由库写，
后者迁移后由 dissect 自己从 `RunResult.steps` 重组（见下一条）。

**轨迹文件的格式是反思模型的唯一输入界面，迁移后要由 dissect 自己重组。**
`Rollout.to_jsonl` 现在把项目 metadata 头和逐步轨迹写在同一个文件里，第一行是头、后面每行
一步。PolyLoop 只返回运行标识和步序列，所以 dissect 要自己把两者拼回那个格式，而且格式
不能变——现有的分析代码和不变量检查器都在读它。这是一笔真实的迁移成本，不是设计缺陷。

**模型是正常收尾还是被输出长度上限砍断，现在拿不到。** dissect 的 `Step` 里没有这个字段，
原因是 PolyGateway 的响应类型不透出它。这个信息有实际价值——输出被砍断时代码只写了一半，
表现成解析失败或语法错误，会与「模型不会做」混淆。迁移后仍然拿不到，要补得给 PolyGateway
提 PR。登记在这里是为了迁移时不要误以为是 PolyLoop 弄丢的。

**动作被拒绝这个概念 dissect 侧没有。** 它的环境执行只有两种结果：返回文本（代码报错也算
正常观察）或者抛异常（环境故障）。PolyLoop 的动作执行接缝要区分「已执行」和「未执行」，
是因为另一个消费者需要。dissect 侧的实现状态恒为「已执行」，这一点要在迁移时确认不会改变
它的步数统计口径。

### 由 `../design/0003-public-api-shape.md` 新产生的四项成本

**每个 episode 要写一个包装类。** dissect 现有的 `Episode` 协议与 PolyLoop 的动作执行接缝
**不构成结构化子类型**：那边是 `execute(action: str) -> str` 与 `is_done() -> bool`，
而库这边要的是一个返回结构体（状态、观察、是否合成、完成信号、截断字符数）的方法。
所以不能直接把 `Episode` 传进去，每个 benchmark 的适配器要多一层薄包装。

**续跑路径要改。** dissect 的 runner 现在把「没有结果行的尝试」重新排进待办，用完全相同
的六维主键第二次调用循环。迁移后这条路要改成调「接着跑」而不是「再跑一次」——按
`../design/0003` 的前置条件，用同一个运行标识第二次调「跑一次」会直接报错。

**要选一个存储实现并给它一个目录。** 存储接缝是必填的，不传就装配不起来。dissect 要恢复
能力，所以装 `JsonlRunStore`，给它一个目录。

**「不提供恢复的内存实现」叫 `VolatileRunStore`。** `../design/0003` 的否决方案那一节定过：
存储接缝必填，另外给一个明确命名的、不提供恢复的实现，好让「我不要恢复」成为一次看得见的
选择而不是一个可以忘记传的参数。它现在和 `JsonlRunStore` 一起住在 `polyloop.stores`，两个
实现跑的是同一套契约套件。它不提供的是**跨进程恢复**：日志随进程一起消失，选它就是选「我
不要跨进程恢复」。名字为什么落在「易失」而不是「不提供恢复」上，见
`../design/0014-contract-suite-distribution.md` 决策五。这一条对 dissect 不构成阻塞——它本来
就要恢复。

**模型绑定要从关键字参数还原。** dissect 现在给每次调用传五个关键字参数（账本、轮次、
阶段、题目、尝试序号）。库这边接的是一个字符串映射，所以适配器要做一次还原（把账本那个
字符串转回枚举、把轮次和尝试序号转回整数）。这是适配器该干的活，收益是这五维能原样进
参数快照。