PolyLoop/research-wiki/explanation/scope.md

PolyLoop 管什么、不管什么

更新触发点：第 2 档（同提交同改）。 三种事情发生时，本文在同一个提交里改：新消费者 接入并带来了新的裁决；某项因为凑齐了两个真实消费者而从界外移进界内；某项被实现时发现 判据用错了。判据本身的变更走人类门，并新写一份 design doc 标 supersedes。

当前状态：本文描述的是已经定下来的边界，src/ 还不存在。 界内的东西大部分还没有代码。 这段说明在库本体落地后删掉。

一个新项目来问「我要的这个东西，PolyLoop 管不管」，答案在这里。

这个问题不好答，因为「agent 框架」这个词罩着两种不同的东西。一种是执行内核：持有 「模型做决策 → 执行动作 → 写回观察 → 再决策」这个循环，管预算、停止判定、逐步轨迹、取消。 另一种是阶段编排：把一个大任务切成几个固定阶段，每个阶段跑一次执行内核，阶段之间交换 状态，并检查每个阶段的产物合不合格。

PolyLoop 是前者。 阶段编排留在项目侧。这个划分和它的理由记在 ../design/0001-scope-boundary.md。

判据

一句话是：管「一个目标之内」的事，不管「多个目标之间」的事。 一次 run 等于一个目标。

这句话自己判不了案，配三条判据，三条全中才在界内：

1. 时机 —— 它发生在一次运行开始之后、返回之前。
2. 信息 —— 它不需要知道这次运行之外的任何事：上一次运行的结果、下一次运行是什么、 此刻还有几次运行在跑、这个目标是谁派下来的。
3. 性质 —— 它回答「怎么跑」，不回答「跑什么」「为什么跑」「跑得好不好」。

再配一条补充规则：只认接缝，不认接缝后面是什么。 检索、沙箱、容器、工作区目录，库一概 不知道——它只知道有一个环境接口，交给它一个动作、拿回一段观察。没有这条，第一条判据会被 滥用成「检索发生在一次运行之内，所以检索该进库」。

补充规则有个更好用的等价说法：能表达成「环境提供的一个动作」的，就在界外。 检索能， 沙箱执行能，写文件能，调外部 API 能。而「记这一步花了多少预算」不能——没有任何环境会提供 这么个动作，那是库自己的算法。

排除条款：不夺走下游要调的那个旋钮

三条判据都过、补充规则也不适用，仍然可能不该进库——如果它是下游要扫的实验因子或要调的 业务刺激。

Skill 的渲染形态是这一条唯一的现役例子。把注入内容用什么格式贴进提示词，按三条判据全过： 它发生在一次运行之内、不需要知道运行之外的事、回答的是「怎么跑」。但 dissect 要扫这个因子 来测它的效应量。库一旦把格式写死，那段文本就成了库定的实验刺激，而且它逃出了项目的 参数快照——扫不动了。

判据是：这个取值变一下，下游的实验结论或业务结果会不会跟着变？ 会，就留在项目侧， 哪怕它长得再像库该管的事。

当前裁决

「已落地」一栏区分两件不同的事：某项归本库管（在界内），和本库现在真的做了它。凡是标 「未落地」的，第一版不实现、不设接缝、不预留字段——归属不变，只是还没到做的时候。

界内

事项	已落地	说明
主循环：决策、执行、观察、再决策	待落地	结构已定，代码未写
预算与停止判定	待落地	判定顺序与预算计数语义还没定，见第十四节缺口
停止原因的分类与取值	待落地	取值还没定
逐步轨迹	待落地	字段清单还没定
取消传播	待落地
决策解释接缝	待落地	把模型回复解释成动作 / 最终回答 / 无效决策
动作执行接缝	待落地	含完成信号查询
工具的注册、模型可见 schema 生成、存在性与参数校验、分发	待落地	四者必须同源
通用工具的现成实现	待落地	可选装配；读写文件、grep、跑 shell 这类
Skill 的注入与注入顺序快照	待落地	只注入和记录
崩溃后「接着跑」	待落地	见 ../design/0002-step-level-resume.md
意图日志与恢复状态判定	待落地	同上
运行结果的持久化存储端口	待落地	同上
最终输出对项目所给 schema 的校验，以及校验失败后的有界重问	不做	凑不齐两个真实消费者
上下文压缩	不做	同上。做的时候必须是显式策略，基线关闭

后两项标「不做」而不是「待落地」，区别在于前面那些只是排期问题，这两项是准入问题—— 它们要等第二个真实消费者出现，见下一节。

界外

事项	栽在哪一条
评分、业务正确性判定	性质
阶段编排	信息、性质
阶段产物是否齐全、合不合格	性质
崩溃后「判断该不该续、历史存哪、怎么读回来」	时机、信息
阶段级的跳过与续跑	时机、信息
并行调度、批量运行、结果汇总	时机、信息
跨运行的长期记忆	信息
Skill 的生成、评测、进化、审批、激活	时机、信息、性质
Skill 的选择规则（这次注入哪几条）	信息
Skill 的渲染形态	排除条款
上下文的渲染格式	排除条款
检索、文本切分、向量库、重排	接缝后面
工作区目录的建立、快照与清理	接缝后面
沙箱与容器的生命周期	接缝后面
业务工具的实现	接缝后面
任务队列、租约、心跳、多租户规则	时机、信息
模型调用的重试、换源、限流、熔断、缓存、遥测	归 PolyGateway
一次模型调用失败之后要不要再来一次	见下

最后一条要说清楚，因为它容易被读成「库要做一层重试」。 重试分两个尺度，两个都不归 本库：一次模型调用之内的重试与换源归 PolyGateway；整次运行失败之后要不要重跑， 归下游的 runner。中间那一层——「这一步的模型调用失败了，库自己再调一次」——举不出两个 消费者，所以不做。预算口径一并定死：PolyGateway 内部换源重试不消耗任何预算，因为库数的 是一次模型调用接缝的调用，口径必须是库自己能观测的量。

三个容易判错的地方

「校验」这个词底下压着三件不同的事，两件在界内。 模型吐的文本能不能解析成一个动作—— 那是决策解释接缝，界内。动作的参数合不合法、这个工具存不存在——那是动作执行接缝裁决、 库定语义，界内。一次运行结束后文件系统上的产物齐不齐、合不合格——那是「跑得好不好」，界外。

接缝的完整清单、各自的职责、以及为什么恰好是这几个，在 architecture.md 第九节。本文只 判归属，不定形状。

工具调用在界内，某个具体工具的实现不一定。 模型说要调 search，库解析它、校验它、分发 它、把结果变成观察，这一整套在界内。search 本身怎么实现在界外，由项目注册进来。库自带 的通用工具是个例外，判据是不含业务概念且有两个以上消费者需要——读写文件过得了，检索过不了。

恢复要拆成两件事。 拿着一段已有历史从中间接着跑，界内。判断该不该续、历史存在哪、怎么 读回来，界外。

界外的东西怎么进来

先有两个真实消费者，并且它们的语义稳定一致。「真实消费者」指有跑着的代码或已冻结的 设计，不包括「将来可能需要」。

在满足这个条件之前，界外的需求只登记不实现，也不为它预留结构。不预留是刻意的：预留一个 接缝要占公共类型的位置、受兼容性约束、还要有人维护它的测试，而它守护的那个形状是猜出来的， 等真需求到了多半不合用，那时候拆比重写贵。

登记的地方是 ../migrations/ 下对应那份。

边界之外，库仍然要为它们留出余地

不做某件事，不等于可以挡住别人做。三条已知的、由界外功能反向施加给界内设计的约束：

阶段编排要给每次运行配不同的预算。 一份 agent 定义在三个阶段里可能要用三个不同的步数 上限，所以预算不能只挂在定义上。

阶段编排要按阶段收窄工具集。 每个阶段可见的工具不同，所以工具集要能按次运行装配，而 不是固定在定义里。这条和「四者同源」不冲突：每次运行构造一个窄的注册表就行。

阶段级续跑要能判断上一次运行是不是真的跑完了。 所以运行结果必须是可持久化、可读回、 可判定的结构，而且「结束了」这个事实要由库自己写下来，不能跨两个存储。这条已经落进 ../design/0002-step-level-resume.md。

已知没有机器兜底的部分

pyproject.toml 的 import-linter 契约将来能守住其中一部分——不反向 import 下游、业务概念 不进内核。但「这个机制该不该进库」这类判断守不住，只能靠 ../../CLAUDE.md §3 的评审。 那些契约现在还没写，要等 src/ 落地。