- 单测计数:`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 无需改动。
6.3 KiB
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」一一对应)。链条:
service.notify()是同步内联(src/client/service.ts:696),而registerNativeSurface把sync()订阅到它和 store 上(src/client/native/index.ts:353;本文行号按 v0.22.0,main 因 #777 的插入而顺移)。sync()的清理循环把live里两类归属不同的条目一视同仁:描述符类型(键 = descriptor id)与files接管(键 =FILES_KIND,永远不在wanted里)。于是每次通知都会释放接管、并在同一轮里重建它。- 插件 teardown 时,内置描述符逐个注销 → 每次注销 notify →
sync()在已经 inactive 的插件 ctx 上运行。此时tabs.register建在宿主 ctx 上(宿主 ctx 仍活着)→ id 被取走且返回了 disposer;紧随的ctx.slots.inject建在插件 ctx 上 → cordisassertActive()抛INACTIVE_EFFECT(@deepseek-ai/cordis@4.0.4effect()首行)→live.set(FILES_KIND, …)永不执行 → 该 id 在本页生命周期内再也不能注册。 - 之后每次 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(CIplugin-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显式报出)。理由写在源码注释里。