【Bug】rc 原地升级 alpha.5 后所有会话历史加载失败：cache.hydratePrepared is not a function (gateway/internal)

[SunshineR04]

EN TL;DR: After upgrading in-place from 0.1.1-rc.2 to 0.1.2-alpha.5, every existing session fails to load with failed to project session "...": cache.hydratePrepared is not a function (gateway/internal). Root cause: third-party profile plugins pull @deepseek-ai/dsh-session-projection-cache@0.1.0-rc.8 (peer range >=0.1.0-rc.5 <0.2.0 can never match the alpha line), whose old-shaped sessionProjectionCache service is then consumed by the alpha host's dsh-session-query, which expects the new hydratePrepared API. Verified workaround included below — no rollback needed.

环境

• OS: Windows 10 Pro (26200 x64)
• Node: v24.19.0，pnpm 11.22.0
• 版本路径：@deepseek-ai/dsh 0.1.1-rc.2（latest 通道）→ 原地升级 0.1.2-alpha.5（alpha 通道）
• profile：web（含 dshmarket、dsh-better-sidebar、@michengai/dsh-archive-manager、@liustack/modlens）

现象

升级后每个会话（旧会话与新建会话）打开即报错，无法加载历史：

历史加载失败：failed to project session "session-…": cache.hydratePrepared is not a function（gateway/internal）

原始会话日志（session.jsonl.zstd）完好无损，仅读取/投影阶段崩溃。

根因分析（本机已逐层验证）

1. dsh-session-query@0.1.2-alpha.5 的调用点（lib/index.js L392-393）：

   const cache = this.ctx.get("sessionProjectionCache");
   return cache === void 0 ? registry.hydrate(prepared, {}, events, SessionLogOffset(0))
                           : cache.hydratePrepared(prepared, events);

   服务不存在时会走正常回退分支（不报错）；存在但是旧形时才会崩。出问题的机器属于后者。

2. dsh-session-projection-cache 两个版本的差异：0.1.2-alpha.5 定义了 hydratePrepared；0.1.0-rc.8 完全没有该函数（全文 0 处），只有旧 API cachedSnapshot。

3. 插件把 rc.8 拉进了 profile 依赖树：@michengai/dsh-archive-manager（0.1.23 与 0.1.24 均如此）声明 peer @deepseek-ai/dsh-session-projection-cache: ">=0.1.0-rc.5 <0.2.0"。按 semver 预发布规则，该范围只能命中 0.1.0-rc.8，永远选不中 0.1.2-alpha.x（tuple 不同）。插件加载 rc.8 副本后，旧形服务注册进共享上下文，被 alpha 主程序消费即崩。

4. 连带问题：alpha.5 家族包之间的互相依赖写成稳定范围 ^0.1.2，而 0.1.2 稳定版从未发布，pnpm 解析直接失败（No matching version found for @deepseek-ai/dsh-client-locale@>=0.1.2 <0.2.0-0、@deepseek-ai/dsh-agent-presets@>=0.1.2 <0.2.0-0 等）。另：pnpm v11 已不读 package.json 的 pnpm.overrides（需写入 pnpm-workspace.yaml），排查时容易绕弯路。

已验证的解决方案（保留 alpha，无需回滚）

1. 插件升级到已适配 alpha 的版本：dshmarket@1.40.0、dsh-better-sidebar@0.18.0-alpha.0、@michengai/dsh-archive-manager@0.1.24（注意 archive-manager 0.1.24 的 peer 范围仍是旧的，见上）。
2. 在 profile 的 pnpm-workspace.yaml 增加 overrides，把家族包强制对齐到与主程序一致的 alpha.5（本机覆盖了 86 个 @deepseek-ai/* 包，关键包括 dsh-session-projection-cache、dsh-client-locale、dsh-agent-presets、dsh-session 等），重新 pnpm install。
3. 重启 profile。实测：此前全部报错的会话历史恢复正常（含最初复现此错误的那个会话），后端日志无任何报错。

对上游的建议

1. host 侧核心服务（sessionProjectionCache 等）能否由 host 保证提供/屏蔽 profile 内旧版副本的注册，避免"alpha 宿主 + rc 插件树"混装即崩；或在 loader 层检测版本错配并给出明确提示（比如启动时校验 profile 树内 @deepseek-ai/* 与宿主版本的一致性）。
2. 家族内部依赖建议改用预发布兼容范围（如 >=0.1.2-alpha.2，dsh-better-sidebar@0.18.0-alpha.0 已是这种写法），否则在稳定版发布前，alpha 通道的 profile 依赖树无法自然解析。
3. 与 Alpha(0.1.2-alpha.2) 写盘的区间 sourceEventSeqs 导致 rc.2(0.1.1-rc.2) 加载会话报 SessionPersistenceCorruptionError #5160（alpha 写盘 sourceEventSeqs 区间导致 rc 读不回）同属"alpha/rc 混用无防护"问题，可统一考虑磁盘格式版本化与读取端的版本护栏。
4. CLI 参考已写明 "launcher does not check freshness, so existing stale bundles can run older browser code until rebuilt"——升级后 profile 插件树不同步的问题，或可考虑在升级路径上自动 reconcile。

相关讨论：#5160（alpha/rc 写读格式不兼容）、#2438（pnpm 隔离布局）、#2933（web 孤儿进程）。

[argszero]

分析得非常扎实——你给出的证据链我逐层复核，全部成立（源码 + npm registry 实测）。补充几处源码级确认、一个方向性细节，和一个给上游的最小补丁方向。

1. Consumer 调用点（alpha.4 源码与你的引用逐行一致）
packages/session-query/session-query/src/observation.ts（preparedProjections，~L183-189）：

const cache = this.ctx.get('sessionProjectionCache')
return cache === undefined
  ? registry.hydrate(prepared, {}, events, 0)
  : cache.hydratePrepared(prepared, observation.inspection.meta, events)

关键点：cache 缺席是一条一等公民路径（直接回退全量 hydrate）——崩溃只发生在「服务存在但旧形」这一种中间态。

2. semver 元组规则的 registry 实测
我直接查了该 peer 范围能匹配哪些已发布版本：

npm view "@deepseek-ai/dsh-session-projection-cache@>=0.1.0-rc.5 <0.2.0" version
→ 0.1.0-rc.6 / 0.1.0-rc.7 / 0.1.0-rc.8   （仅此三个）

预发布匹配规则：候选版本只有在范围中存在同 (major,minor,patch) 元组且带预发布号的 comparator 时才被接受。>=0.1.0-rc.5 的元组是 (0,1,0)，于是不仅 0.1.2-alpha.* 全部落选，连 rc 线内部的 0.1.1-rc.2 也永远选不到。所以这不是 alpha 专属问题：任何 0.1.0-rc.5 时代写下的开放式预发布 peer 范围都会把整个家族永久冻结在 0.1.0-rc.x。archive-manager@0.1.24 的 17 个 @deepseek-ai/* peer 全是这个范围（npm 实测确认），这就是整棵依赖树被压到 rc.8 的完整机制。

3. 值得上游注意的方向性细节：provider 是加性演化，坏在单方向
alpha.4 的 provider（packages/session/session-projection-cache/src/index.ts）同时保留 cachedSnapshot（旧 API，~L120）并新增 hydratePrepared（~L154）——同一个 Service 类里两代 API 共存。也就是说上游改 provider 时是向后兼容的：新 provider + 旧 consumer 不崩（旧方法还在），唯独旧 provider + 新 consumer 这一个方向崩。缺的恰好是 consumer 侧半行能力守卫：

return cache?.hydratePrepared === undefined
  ? registry.hydrate(prepared, {}, events, 0)
  : cache.hydratePrepared(prepared, observation.inspection.meta, events)

这符合既有设计意图而非 shim：provider 头注释写明「The cache is a fold shortcut, never an authority」，写路径全部 fail-soft；缺席时走全量 hydrate 本就是设计内路径。旧形 cache 语义上等价于「不可用的 cache」，归入既有缺席分支即可——代价只是冷读多一段尾重放，不会错。磁盘格式零迁移：provider 文档明言 ver 不匹配的行直接丢弃（不迁移），所以即便 rc.8 时代写过 checkpoint，换 alpha.5 provider 后首读即自愈。

4. 分级修复建议

• host 侧（最小改动，建议优先）：上述 consumer 能力探测。把「旧形 cache」折叠进既有的「无 cache」路径，一行恢复可加载。
• 插件侧（治本）：peer 范围改预发布写法（如 >=0.1.2-alpha.2 <0.2.0-0，dsh-better-sidebar@0.18.0-alpha.0 已是这种）。但插件作者难以预知每个未来 alpha 版本——上游若给出官方推荐的兼容范围模板，能省大量社区返工。
• 发布线（结构性根因）：这些包的 dist-tags 现状是 latest=0.0.1-rc.1（冻结在最老）、next=0.1.1-rc.2、alpha=0.1.2-alpha.5。第三方以 latest 为参照写 peer 时天然落在 rc 线，与前进中的 alpha 主程序混装是结构风险（与 Alpha(0.1.2-alpha.2) 写盘的区间 sourceEventSeqs 导致 rc.2(0.1.1-rc.2) 加载会话报 SessionPersistenceCorruptionError #5160、能不能npm和代码发布一致啊 #5417 同源：rc 冻结 + alpha 前进，社区 profile 夹在中间）。你建议的 loader 启动时校验 profile 树内 @deepseek-ai/* 与主程序版本一致性是长期正解，但错误消息最好落到「哪个插件把哪个包压到了哪个版本」，否则用户只能盲猜。

5. 附带事实（实测）

• alpha.5 主包 @deepseek-ai/dsh@0.1.2-alpha.5 全量 manifest 已统一为 ^0.1.2-alpha.5 预发布写法，^0.1.2 风格的家族内部依赖在当前 alpha.5 已不存在；你遇到的 >=0.1.2 <0.2.0-0 解析错误应来自较早 alpha 发布物或解析中间态。若全新安装（无 override）仍复现，请贴具体包名+版本——那是另一处发布卫生问题，值得单独开帖。
• pnpm v11 不读 package.json 的 pnpm.overrides 属实（pnpm 10 起只读 pnpm-workspace.yaml），这条对 Windows 用户排查很有价值。

你的 workaround（pnpm-workspace.yaml overrides 对齐 86 包 + 插件升级）是当前唯一正确路径，验证完备。上面的一行守卫是给上游的补丁方向，用户侧无需等它。

[SunshineR04]

跟进（0.1.2-rc.1 实测）：根因可以进一步收窄——llm-pi-ai 的设置命名空间在运行时从未注册

已按楼上的方向继续排查。环境更新：从 0.1.1-rc.2 原地升级到 0.1.2-rc.1（next 标签），三插件同步升到适配版（dshmarket@1.41.0 / dsh-better-sidebar@0.18.0 / @michengai/dsh-archive-manager@0.1.29），profile 依赖树用 pnpm overrides 与主程序对齐到 0.1.2-rc.1。启动干净、stdout/stderr 零报错，但模型层仍然不可用。进一步定位到硬证据：

1. 运行时实测（settings.describe RPC，经认证会话调用）：

writable=true, hasDocument=true
registered namespaces (16): agent-default-model, subagent-model-selection, ui-theme, locale,
ui-onboarding, ui-conversation, ui-chat, web-search-deepseek, llm-deepseek, modlens,
agent-loop, agent-presets, shell, permission, dsh-market, dsh-better-sidebar
llm-pi-ai: NOT REGISTERED

设置文件可读可写、16 个命名空间全部正常注册，唯独 llm-pi-ai 缺席——即 @deepseek-ai/dsh-llm-pi-ai 的 apply() 没有执行到 installSection（或插件整体未启动，静默挂起）。

2. 模型目录实测（session/modelCatalog RPC）：

routableProviders: ["deepseek-official", "deepseek-modlens"]
groups: deepseek-official(3 models), deepseek-modlens(2 models)
failures: []

settings.yaml 里声明的 tokenrhythm（7 模型）与 opencode-go（15 模型）路由静默缺席，无任何 failure 记录。用户可感知的后果：新建会话输入框直接禁用（"当前模型不可用"），唯一显示的 modlens 包装路由（modlens-tokenrhythm/deepseek-v4-flash-0731）因底层 provider 未注册而是死路由。

3. 配置本身无问题（已排除三个常见嫌疑）：

• 直接导入本机安装的 @deepseek-ai/dsh-llm-pi-ai@0.1.2-rc.1 的 Config，对 settings.yaml 的 llm-pi-ai 段做解析：VALID，providers = [tokenrhythm, opencode-go]；
• --dump-config 组合树中 llm-pi-ai bundle 正常列出、无 disabled 标记；
• 启动日志（stdout/stderr 重定向捕获）零警告零报错。

4. 顺带修正一个表象误读： 模型设置页"添加自定义提供方"按钮呈禁用态，源码条件是 disabled: protocols.length === 0 || !state.writable，其中 protocols 来自 protocolChoices(state.namespaces.get("llm-pi-ai"), schema)——命名空间未注册时 protocols 必为空，按钮必然灰。所以它不是独立的功能开关，而是同一个根因的症状。

结论与请求： rc.1 的 llm-pi-ai 适配器在本机静默未完成启动注册（无报错、无 failure、schema 校验通过、bundle 已列入组合树）。为帮助定位，想请官方/其他用户确认：在干净环境（全新 profile、无第三方插件）安装 0.1.2-rc.1 后，settings.describe 里 llm-pi-ai 是否正常注册？若同样缺席，则是 rc.1 的启动缺陷；若正常，则是某种本机状态触发，我愿配合提供进一步环境信息。

补充基线说明：settings.yaml 中的 llm-pi-ai 段写于 0.1.1-rc.2 时代（该版本不含 llm-pi-ai 组件，推测为迁移前预写的 0.1.2 格式配置），因此在 rc.2 下从未生效，无法提供"rc.2 正常加载同一配置"的对照基线。