Files
apes-sidebar/docs/plans/2026-09-28-native-files-takeover-reload-leak.md
T
Menghuan1918 a18e0f000d docs(release): 修正 v0.22.1 条目里的测试计数与「3/3」措辞(独立 review 发现)
- 单测计数:`122 files / 1292 passed / 9 skipped` → **1293**。1292 是 #785 当时的数字,
  本 commit 自己的 `make check` 两次都报 1293(`tests/` 与 main 逐字相同,122 个 spec +
  `it.each` 展开 = 1293)。涉及 CHANGELOG.md / CHANGELOG_EN.md / README.md / README_EN.md
  与事故文档。
- 「3/3 红 / 3/3 绿」措辞改为「连续 3 次运行全红 / 全绿」并注明该 lane 里只有 1 个用例、
  是重复跑三次——原措辞会被读成「3 个用例各红一次」。涉及上述四份发布文档 + 事故文档
  + AGENTS.md §2(同一句话在那边也有)。
- 其余 review 结论均已满足:版本三处锁步 + 两个守护用例绿、无遗留 0.22.0 引用、
  zh/en 段落一一对应、「最近更新」保持两条并把指针下移为 v0.21.1 → v0.12.3、
  release.yml 的 tag 校验与 `latest` dist-tag 都能过、lockfile 无需改动。
2026-09-28 11:30:29 +08:00

6.3 KiB
Raw Blame History

files 接管 id 泄漏:客户端条目替换后报错刷屏 + 文件树空态

日期:2026-09-28 分支:fix/native-registration-leak-v2(PR #777,已合并)→ 后续 fix/native-leak-guard-tests

关联 issue:#771(同串报错的独立复现与定位)、#770(同串报错,另一条 inject re-prove 猜测)、#766(「吸收」方案,已按本文结论关闭)

现象

[dsh-better-sidebar] native register files error: sidebarRight: tab type id "dsh-better-sidebar:files" is already registered

红色诊断条钉在页面左下角、触发时同一毫秒刷出多条;不致命,但 files(文件树)接管会静默缺位——原生右侧栏的「文件」入口渲染成宿主的空态,直到刷新页面才恢复。0.21.1 与 0.22.0(npm latest)都带此缺陷。

根因(真机日志 + 代码双向验证)

官方桌面壳日志 ~/Library/Application Support/dsh-tauri/logs/desktop.frontdesk.log:2370(2026-09-27 15:51:39.338)第一条就是完整栈:

native register files error: Error: cannot create effect on inactive context
  assertActive ← effect ← inject(slots) ← registerSlots ← registerFilesKind ← sync ← notify

随后同一毫秒(.339–.340)7 条 already registered(栈:register ← registerFilesKind ← sync ← notify),13 秒后新激活的 _reload 路径又报 2 条(该 burst 合计 9 条,与「7 个内置描述符注销 → 7 次 notify」一一对应)。链条:

  1. service.notify() 是同步内联(src/client/service.ts:696),而 registerNativeSurface 把 sync() 订阅到它和 store 上(src/client/native/index.ts:353;本文行号按 v0.22.0,main 因 #777 的插入而顺移)。
  2. sync() 的清理循环把 live 里两类归属不同的条目一视同仁:描述符类型(键 = descriptor id)与 files 接管(键 = FILES_KIND,永远不在 wanted 里)。于是每次通知都会释放接管、并在同一轮里重建它。
  3. 插件 teardown 时,内置描述符逐个注销 → 每次注销 notify → sync() 在已经 inactive 的插件 ctx 上运行。此时 tabs.register 建在宿主 ctx 上(宿主 ctx 仍活着)→ id 被取走且返回了 disposer;紧随的 ctx.slots.inject 建在插件 ctx 上 → cordis assertActive() 抛 INACTIVE_EFFECT(@deepseek-ai/cordis@4.0.4 effect() 首行)→ live.set(FILES_KIND, …) 永不执行 → 该 id 在本页生命周期内再也不能注册。
  4. 之后每次 notify(同一 burst 里还有 6 次)都重试同一个被占用的 id → already registered 刷屏;新一次激活同样注册不上 → 文件树空态。

两条一般化的不变量(已写进 AGENTS.md §3.4 第 9 条):

  • 清理循环必须跳过 FILES_KIND;接管只由编辑器类型的 wantsFiles/hasFiles 分支与 seat disposer 管理。
  • 「注册成功一半」是可达状态(宿主 ctx 与插件 ctx 的寿命不同),因此任何在宿主取走 id 之后失败的注册必须回滚释放该 type(并释放已建槽位),插件侧只留一个下次通知可重试的失败。

修复

PR #777(贡献者 @yanzhaohui1999)落地上面两条:sync() 的清理循环跳过 FILES_KIND;registerSlots 失败时释放已建槽位;registerDescriptor / registerFilesKind 在槽位注册失败后回滚已占用的 type;teardown / 清理循环逐个安全释放(一个释放抛错不再中断其余)。

否决备选方案(PR #766 的「吸收」):把宿主抛出的 already registered 当作「宿主已持有该行」继续注册槽位。它能让日志安静,但会在 live 里记下一份不拥有的注册(空 disposer)——旧持有者随后释放该 id 时无人补注册,files 接管可能永久缺位;而且在 tabs.register 抛错(id 守卫,原子,未取走任何东西)与「取走后才失败」两种情形之间不做区分,掩盖了真正的账本错误。

验证

  • 单测红→绿(实测):tests/native-registration.spec.ts 在 v0.22.0 源码上 4/4 红,在修复分支上 4/4 绿;pnpm typecheck / pnpm lint / pnpm test 全绿(修复分支的 base 早于 #781,故为 114 files / 1136 passed;合入 main 后为 122 files / 1293 passed / 9 skipped)。
  • 部署级红→绿(实测):tests/e2e/native-reload.e2e.ts 在 scratch profile 里对 npm 上的 dsh-better-sidebar@0.22.0 触发页面内条目替换(utimesSync 已安装的 lib/client.js),连续 3 次运行全红且每次都是本文那两条栈;换成本地打包的修复版连续 3 次全绿(该用例只有 1 个 test,重复跑三次)。该用例已随本 PR 进入挂载 lane(CI plugin-mount 绿),触发方式依赖钉住的宿主 0.1.7-rc.1 的 rev 规则(mtime/ctime/size 的 sha1)——pin 上调时需同步复核。
  • 首版用例的两处断言(「失败后还能重新注册」)写在活着的 id 集合上,在未修复代码上会同样通过(泄漏的 id 恰好构成同一个集合)。跟进 PR 把它们改写到注册表的事件日志上,并把槽位失败判据从 key 改成 name::key —— 两个槽位共用一个 key,按 key 失败时第一个槽就抛,回收循环虽然进了、但手里的 disposer 列表永远是空的(即 registerSlots 的部分回滚释放动作从未被执行);改后可以让某个描述符的第二个槽失败,回收列表非空、释放路径真正被覆盖,且 4 例在 v0.22.0 上仍全部红。

已知限制 / 未做

  • 跨激活的瞬时重复仍未消除:页面内条目替换时,新激活可能先于旧激活释放 id 而撞上 already registered(一次日志噪音,随后自愈)。要消掉它需要「吸收 + 旧持有者释放后补注册」的机制,与上面否决的方案同源,暂不做。
  • disposeSafely 的释放失败只写 console.error、不弹诊断条(teardown 阶段弹条是噪音;真被占住的 id 会在下一次注册尝试里经 reportFailure 显式报出)。理由写在源码注释里。