寻找 deepening 机会

"provider" 是根裸 string。装配 Pi 子进程要读 piProvider + 拼 piRpcArgs + 注 piChildEnv + 存 credentials + 报 /api/models + 校 visibility.KNOWN_MODELS——六处硬编码 anthropic 假设。加 MiniMax 需要同时改六处，且没有一处告诉你"下一个是啥"。上周回滚坐实。

把"什么是一个 provider"提成 ProviderAdapter interface，anthropic 是第一个 adapter；MiniMax 加一个文件就够。config.piProvider 变 provider registry 的 key，其它模块从 providers.get(key) 拿字段——不再各自 if (cfg.piProvider === 'anthropic')。

• locality：provider 差异集中在一个 adapter 文件
• leverage：加 provider = 加一个 adapter，不动 6 处 caller
• 两个 adapter 出现 = 真 seam（LANGUAGE 原则）
• 可测：mock adapter 单测 client-pool 全流程

删掉这个 adapter 层？六处硬编码复现。这就是 "complexity reappears across N callers" 的教科书信号。seam 该有。

项目里已有 6 个 *-routes.ts 分域文件，唯独 routes.ts 是一锅端。guessMime 40 行文件类型表塞在路由文件末尾，countTurns 派生的 batch-summary 计算也在路由里手滚 for 循环。路由层不该做业务派生。

照现有 *-routes.ts 骨架剖 4 刀，guessMime 提到 shared 或独立 mime.ts。batch-summary 那段搬进 store/threads.ts 变 summarizeThreads(dir)——规则回到规则该在的地方。

• locality：改文件预览只碰 artifact-routes
• leverage：接口没变，callers 零改动
• 删 4 个上帝方法的 co-location friction
• 路由风格与已有 6 兄弟对齐

拆完后每片能不能删？每片对应一片 UI 面板（设置页 / 项目 / 线程 / 产出），删任一片对应功能消失——不是 pass-through。四片都是真 seam。

watermark（CONTEXT.md 命名的域概念）的"只增不减"规则理论上在 store/mirror.planMirror——但实际执行需要 caller 依序读 meta → plan → append → bump。任一步遗漏或顺序错都会破坏"永不 truncate"。这不是 mirror.ts 的 5 行数学，而是 client-pool.mirrorSession 里的 20 行编排。

把 4 步收进 ThreadMirror.absorb(client, projectDir, threadId)——interface 就一个动词。store/mirror.ts 保留纯 planMirror 作为内部 seam（可单测），appendMirrorBatch / bumpSessionMirrored 变私有辅助或保留但降级为内部调用。

• locality：watermark 不变式集中一处
• test surface = 一个 absorb 调用（不再 mock 4 步）
• 删 client-pool 里 20 行编排 → deep 得多

删掉 ThreadMirror？20 行编排在 client-pool 里复现，且不变式再度"靠约定"。seam 该有。

三处独立函数做同一件事：从 Pi AgentMessage.content 走 type==='text' 抽字符串。store/threads.messageText 已经比 event-translator.extractText 多"string content 兜底"——三份实现已经在漂了。Pi 若改 content shape（thinking part、多模态），改三处。

提到 @yunzhan/shared/message-text.ts——它反正只跟 Pi 的 AgentMessage shape 挂钩，跟三个 caller 的业务无关。三处 import。

• locality：Pi content 形状变化只改一处
• leverage：3 callers, 1 impl
• 纯函数，零风险

删掉 shared/message-text？三处都会重新写一遍——就是现状。seam 该有。

模型 id 是 前端 composer 下拉 / 后端 setModel / visibility 别名 map / 迁移表 四方约定的 wire。当前存在两个 known 列表，一处漂了另一处不知道；visibility.ts 里的 LEGACY_ID_MIGRATION 注释里明确坐实过一次生产事故（Opus 静默 fallback 到 Sonnet）。

@yunzhan/shared 建 models.ts 一个 as const 表，两处 import。跟候选 1 (Provider Adapter) 天然合流：models 就是每个 adapter 的一个字段。

• locality：新增/改名一处改
• 已咬过一口的 bug 类别消失
• 与 candidate 1 天然合流

删掉 shared/models？两处再写一遍——就是现状。seam 该有。

377 行里同时住着域规则（countTurns 是 CONTEXT.md 命名的 turn；watermark 是 CONTEXT.md 命名的 watermark）、纯 CRUD、以及三个旁路（agent-loop marks / meta / tagged read）。想找"什么算一轮"要在 CRUD 里翻；三个旁路又跟 messages.jsonl 语义耦合但没被 mark 出来。

按角色分三文件：thread-rules.ts（规则单点）· threads.ts（保留名字，只做 CRUD）· thread-sidecar.ts（旁路）。appendMirrorBatch 应属 rules。同时把候选 3 的 ThreadMirror 组合起来，rules 只留内部原语。

• locality：规则集中在 rules 文件
• test surface：rules 是纯函数 easy 单测（现在 countTurns 没测）
• 旁路的耦合性变可见

rules 一片能删吗？删了 countTurns，两个 caller（routes meta / batch summary）复现相同 8 行 for 循环——过 deletion test。sidecar 相对边缘，可作 Worth exploring 而非 Strong。

"builtin 永远开"这个规则出现在 L145（读时 hardcode）和 setSkillEnabled（写时抛）两处。规则一致但没有 policy 模块承载——文档描述在 L192-196 注释里，容易漂。

建 skillEnablementPolicy 小 module（一个函数一个 error class），读/写两条路径都经它。是"internal seam"，接口小 leverage 也小，但把 invariant 挂到一个可搜索名字上。

• locality：invariant 有名字，grep 得到
• 可测：policy 是纯函数
• 降"builtin 悄悄改 policy" 风险

删掉 policy 模块？两处 hardcode 复现——但当前两处只有共 3 行代码，locality 未必比现在差多少。边界 candidate。若发现第二个 "永远开" 规则（比如某个 builtin skill 想强制勾选组合），policy 就赚回本。

WS 层是 CockpitEvent seam（CONTEXT.md 命名的域概念）的实际下推口，但当前是 pool "回调进" WS——WS 不知道自己何时被喂事件，也没法 backpressure。断线时 setSink(undefined) 只切开 fn，pool 内的事件仍可能在飞。

把 pool.setSink 换成 pool.events(key) 返回 AsyncIterable<RawPiEvent>。WS 一个 for await 循环全权控制翻译/派生/下推；断线 break。

• WS 是 CockpitEvent seam 的唯一消费者，对齐 ADR-0001 精神
• backpressure 显式化
• Test：feed 事件 → WS 顺序断言，不再 mock sink 注入

当前 sink-injection 已经算是 seam，问题是"反向"。改造收益是清晰化而非从零建 seam——所以 Worth exploring 而非 Strong。仅在下一个 event 消费方（比如后台 archiver）出现时才真正赚回 leverage。

deriveBusinessEvents 是"每个 tool → 派生哪个业务事件"的编排，但当前长成"手写两次 if(x)push"。Pi 迟早会加第三/第四个 customTool（比如 memo_write / skill_note），每次都得改 deriveBusinessEvents 加一段。

toolName → derivation 的 map，加新 tool = 加一行注册。跟 event-translator 的 switch 呼应（那边处理 event.type，这边处理 tool.name），扩展的地方一目了然。

• 加 tool derivation = 加一行
• test：derivation map 每 entry 单测

目前只有 2 条 derivation。删掉 map，两个 if 复现——现状。只有出现第 3 条 derivation 时才真正赚。标 Worth exploring，等触发器。

loose-threads.ts：6 个函数全是 listLoose = (home, u) => listThreads(looseChatRoot(home, u))。credentials.ts：2 个函数，全在 AuthStorage.create(...) 上加薄壳。interface 面≈实现面——典型 shallow。CONTEXT.md 里 "Loose thread" 是域概念——但域概念的落点其实是 looseChatRoot 常量 + projectId=null 语义，不是这 6 个 wrapper。

把两个文件删了：loose-routes.ts 直接算 dir = join(home, u, LOOSE_CHAT_DIR) 传 store/threads；/api/config 直接 import Pi.AuthStorage。LOOSE_CHAT_DIR 常量提到 shared。

• 119 行 shallow 代码消失
• Pi AuthStorage 依赖显式（现在被 credentials.ts 藏了）

删掉 loose-threads？6 行 join(home, u, 'chat') 在 loose-routes 的 5 个 handler 里复现——只在一个 caller 文件。删掉 credentials？2 行 AuthStorage.create(...).get(...) 在 /api/config 一处复现。都不过 deletion test 的另一半——但删了没啥损失（因为原本就没藏东西）。

当前 88 个 skill 都是自家写的，格式稳定。库依赖是净新增。deletion test：删掉 parseFrontmatter → 20 行 regex 在一个 caller (readSkillDir) 内复现——就是现状。

出现第一个"用户自装 skill frontmatter 解析错"的 issue，或加第二个字段（tags、version）时。

与 ADR-0003 同调：没证据别动。当前监控输出质量没投诉。抽到 config 是理论好，但引入新 config 表面积（会有第七个 env 变量）。

出现"监控总结不够长"/"选错模型"的具体投诉；或候选 1 落地后 provider adapter 里天然把 summarizeModel 表达进来——那时顺手就做。