阶段四 · 新增设计面
状态与路由 —— 数据存哪、请求给谁
会话要落盘,可"落到哪里"未必只有一种答案;模型要选,可"选哪个"未必该写死在配置里。这一章讲近几个版本的两处可替换点:存储后端与虚拟模型路由。它们看起来无关,但都在回答同一个架构问题——怎么把"用哪个实现"的决定从调用方手里抽走。
学习目标
- 理解可替换存储的接口边界:换后端,调用方一行不改。
- 知道四种存储后端各自适合什么场景,以及换后端会改变什么语义。
- 理解虚拟模型路由解决什么问题,以及它为什么必须可观测。
- 分清"配置里写死一个模型"和"运行时路由"在成本与可回退性上的差别。
一、两个看似无关的问题
第一个问题:会话存在哪儿?
内置答案是一个本地文件,够用。但一旦场景变了——想在浏览器里跑、想让多个进程共享、想放到数据库里做审计——同一个问题就有了不同答案。如果"存哪儿"写死在代码里,换一次就要动一遍上层。
第二个问题:这次请求该给哪个模型?
配置里写一个模型,够用。但真实情况是:写代码用强的、改文案用便宜的、重试时别再用刚才失败的那个、主模型不可用时想自动换一个。如果"用哪个"写死在配置里,就只能人工改配置。
两个问题的共同点是:调用方只想说"存一下""问一句",不想关心背后是谁。 于是两处都留了同样的口子——定义一个窄接口,把实现换掉。
二、存储:把"存哪"抽出来
最小接口只需要两个动作:追加一条记录、读出全部记录。
def replay(store):
return "\n".join(f"{record.role}: {record.content}" for record in store.load())
注意这个函数不知道背后是内存、文件还是数据库。四种后端各有各的适用场景:
| 后端 | 适合什么 | 换来什么 | 失去什么 |
|---|---|---|---|
| 内存 | 一次性任务、测试 | 快、无副作用 | 进程退出即丢 |
| 追加式文件 | 日常使用、可审计 | 崩溃只丢最后一行 | 多进程并发要自己处理 |
| 数据库 | 多端、多人共享 | 事务、并发控制 | 部署与运维成本 |
| 只读视图 | 审计、回放、演示 | 结构性保证"不会写" | 不能继续对话 |
"只读视图"这个后端值得注意:它不是"把权限关小一点",而是在类型层面就不提供写操作。审计工具套上它,就不存在"误写进去"这种事故。
换后端会改变什么?最容易被忽略的是一致性语义:内存后端天然串行;文件后端在多个写者下可能交错;数据库后端取决于隔离级别。接口一样,不代表行为一样——这一点必须在文档里说清,否则"换个后端"会成为一次事故。
三、路由:一个名字,多个真身
虚拟模型解决的是"一个名字,多个真身"。
配置里你仍然只写一个名字,但这个名字不是具体模型,而是一张路由表:什么样的请求交给哪个真实模型。
reason = user → 强模型(要写代码)
reason = retry → 便宜的模型(重试时降低成本)
reason = continuation → 保持上一次的选择(别中途换脑子)
reason = direct → 调用方明确指定(不路由)
四种理由基本覆盖了日常情形:用户发起的、系统续跑的、失败重试的、直接指定的。
三个设计要点:
- 路由状态跟着会话分支走。回退到历史点时,路线也回到当时的选择,而不是用现在的规则重算。否则同一个分支在不同时间会得到不同结果,回放就不成立。
- 计费按真实模型算。路由是个便利层,不是计价单位;报表里必须能按物理模型归因。
- 必须能看见"实际用了谁"。否则用户以为在用 A,其实一直在用 B——成本、能力、合规全都说不清。
这也解释了为什么虚拟模型不是"一个 if 判断就能实现"的小功能:它把"模型选择"从一个配置项变成了一个有时序、有状态、需要归因的运行时决策。
四、共同约束:可观测与可回退
两处可替换点都带来同一类风险:你以为的运行和你实际的运行不一致。
所以两者都有一条不写在接口里、但必须实现的要求:
- 存储要能回答"这条记录什么时候写进来的、从哪个后端读的";
- 路由要能回答"这次为什么选它、如果它不可用退到谁"。
反过来说,如果换了后端却没有迁移策略,或者加了路由却没有可观测性,那这次"架构升级"其实是在制造一个更难排查的系统。
当前 Pi 行为
- 会话默认落到本地追加式文件;存储位置可配置,也可以完全不落盘。
- 另有一个独立的持久化包,提供四种后端:内存、浏览器数据库、SQLite、追加式文件;它们共享同一个会话管理接口。
- 可以在不打开文件的情况下,用外部条目在内存里重建一个会话——这让"从别处恢复会话"成为可能,也是可替换后端的实际用法。
- 虚拟模型通过扩展注册:给名字、给路由函数,函数按请求返回真实模型与思考强度。
- 请求理由分四类(用户、续跑、重试、直接),路由状态随分支保存;界面上显示当前路由到的真实模型,计费按物理模型统计。
- 存储后端与模型路由都不改变循环与协议:换的是实现与决策,不是机制。
代码里的名字
| 通俗说法 | 代码里的名字 |
|---|---|
| 持久化包 | @earendil-works/pi-durable |
| 会话管理接口 | SessionManager |
| 内存重建 | SessionManager.inMemory(cwd, { id }, entries) |
| 存储位置配置 | --session-dir / sessionDir / 环境变量 |
| 虚拟模型注册 | registerVirtualModel({ provider, id, route }) |
| 请求理由 | user / continuation / retry / direct |
源码位置
packages/durable/:四种后端与统一接口。packages/coding-agent/docs/virtual-models.md:路由的行为与配置。packages/coding-agent/src/core/session-manager.ts:内置会话管理的读、写、投影。
失败与边界实验
| 场景 | 会发生什么 | 为什么要这样设计 |
|---|---|---|
| 最后一行写一半 | 读出时跳过坏行,前面的历史仍在 | 追加式存储的容错红利 |
| 换成"只读视图"后继续对话 | 写入被拒绝,读正常 | 只读是结构性保证,不是靠自觉 |
| 路由规则没命中 | 退到兜底模型,并标记"未命中" | 没命中必须可见,不能悄悄发生 |
| 虚拟模型被回退到旧分支 | 路线也回到当时的选择 | 否则同一分支不同时间结果不同,回放失效 |
| 换后端未做迁移 | 旧会话"消失" | 换了存储不等于换了数据 |
python3 -m learn_pi_lab lab storage-routing
python3 -m unittest tests.test_16_storage_routing -v
在 Pi 里怎么操作
- 换会话目录:命令行参数、环境变量或设置文件三选一。
- 不落盘:用一次性模式跑,历史只在内存里。
- 定义虚拟模型:在扩展里注册,写好路由规则与兜底。
- 看当前路由:界面上会显示实际使用的模型;账单按真实模型分组。
Python 实验
storage_and_routing.py 把两处可替换点放在同一个模块里,因为它们的形状是同一个。
先是存储。三种后端,同一个调用方:
def replay(store):
return "\n".join(f"{record.role}: {record.content}" for record in store.load())
replay 完全不知道背后是内存、文件还是只读视图。测试里把三种后端都喂进去,断言输出一致——"换后端不改调用方"这句话,要靠测试钉住。
文件后端还演示了追加式的容错:读到半行 JSON 时跳过它,前面的历史照样读出来。
try:
payload = json.loads(line)
records.append(Record(...))
except json.JSONDecodeError:
continue # 半行就跳过,别让它毁掉整份历史
然后是路由。一张规则表加一个兜底:
router = VirtualModel(
rules=(
RouteRule("user", "anthropic", "claude-opus"),
RouteRule("retry", "anthropic", "claude-haiku"),
),
fallback=Selection("openai", "gpt-mini", "fallback", False),
)
router.choose("user") # claude-opus,matched=True
router.choose("compaction") # gpt-mini,matched=False ← 没命中也要说清楚
Selection 里特意带了一个 matched 字段。这不是多余:路由最危险的失败是"看起来正常"——用户以为在用强模型,实际一直在用兜底模型。把"未命中"做成返回值的一部分,就能在日志和界面里暴露出来。
两处简化要说明:存储只存"角色 + 内容"两个字段,不是真实的十一类会话记录;路由是一张"首个命中"的规则表,而 Pi 的路由是一个按请求计算的函数(可以依据上下文、成本、可用性做判断)。教学模型证明的是接口形状与失败可见性,不是完整实现。
python3 -m learn_pi_lab lab storage-routing
验证方式
python3 -m unittest tests.test_16_storage_routing -v
边界与安全
- 换存储 = 换一致性语义:接口不变,但并发、事务、崩溃恢复的行为都可能变,迁移与回滚要一起设计。
- 只读视图要真只读:用类型或接口保证,而不是靠调用方自觉。
- 路由要可归因:谁被选中、为什么、退到了谁,必须能在日志里还原。
- 路由不是权限:换个模型不会带来新的数据访问权;反过来,别用"路由到便宜模型"来掩盖敏感数据的处理。
- 会话里的密钥:换后端可能把会话搬到远端,脱敏策略要跟着搬。
自测三问
- 为什么"只读视图"要比"限制写权限"更可靠?
- 虚拟模型的路由状态为什么要跟着分支保存?
- 如果路由未命中却没有任何提示,会在什么场景下造成真实损失?
回顾
- 两处可替换点:存储后端与模型路由,换的都是实现与决策,不是机制。
- 存储:窄接口(追加/读取)+ 多种后端;换后端会换掉一致性语义。
- 路由:一个名字多个真身;理由分四类;状态随分支;计费按真实模型。
- 共同要求:可观测、可回退、可归因。