[维护者确认] #4728 插件 Library 基座改动需确认存量兼容 #4772

Activity

1. dash-s-cindy commented on Sep 20, 2026

   

   dash-s-cindybot

   on Sep 20, 2026 – with Dash's Cindy

   More actions

   判断：自定义 Library 的持久 binding、owner 隔离和协议兼容基础已经存在，正常升级不应要求已安装插件重新安装、重新确认权限或重新配置；本次真正需要处理的是缓存会话在自定义目标暂时消失后的绑定复核，避免把原库误当成可重新创建的空库。行动：建议对 #4728 Request Changes，暂不 Approve；待跨平台、并发和恢复场景补齐后再进行维护者放行。

   已确认的现状

   当前主线已有以下产品约束：

   • apps/desktop/src/main/cindy-brain/libraryBinding.ts 将自定义位置持久化在 owner-scoped binding 中，并在解析时区分 disk-missing 与 binding-moved；路径消失或授权对象被替换时不应静默跟随、不应回退到默认根。
   • apps/desktop/src/main/cindy-brain/librarySlot.ts 已有 owner scope 复核、opaque library identity、extraDir 会话同步和漂移状态的 unavailable 结果；这些接口设计支持存量插件继续工作，也不要求重新授权。
   • docs/dev-rules/plugin-library-storage.md 已明确“不可用 ≠ 空库”、卸载不删除 Library、binding 漂移不得自动重建，并保留了 Windows 上 st_ino 不可靠的已知限制。
   • 现有测试已覆盖默认根/自定义 binding、目录删除后的 disk-missing、同名对象替换、owner 切换、旧插件忽略新增握手字段等场景。

   对问题现象的核验

   进一步检查发现，当前主线的 binding 漂移保护主要发生在创建或重建 session 时：GhostLibrarySlot.getOrCreateSession() 在没有缓存 session 时调用 resolveLibraryRoot()；已有 session 被复用时，不会在每个请求前重新解析自定义 binding。与此同时，LibraryVault.open() 会对 rootDir() 执行 mkdir(..., { recursive: true })。因此，一个已经打开的 custom Library 在原目录暂时消失后，后续请求仍可能沿用旧缓存 session 并重新创建路径，形成与原件无关的空库。这与 #4728 要解决的核心现象一致。

   不过，是否可直接合并不能只看这个修复目标。#4728 的公开说明称其新增 fd-relative helper，并已通过 80 项定向库测试、related tests、typecheck 和 diff 检查；但同时明确没有做真实 Cindy 冷启动、断盘桌面操作、Windows 实机或真实模型消费验证。

   合并前必须澄清或修正的风险

   1. Windows 可用性是阻塞项。 fix(library): 自定义媒体库暂时不可用时不重建空库 #4728 的审查讨论指出，新增 helper 在 Windows 上可能返回 UNSUPPORTED，而 LibraryVault.open() 对已有和新建 custom Library 都会经过该路径，结果可能是 Windows 自定义 Library 全部不可用，而不只是“同路径替换无法识别”的既有限制。请提供 Windows 的安全实现，或让已存在的 custom Library 走不依赖首次建库 helper 的验证路径；不能把所有 Windows custom Library 变成 unavailable 后再合并。
   2. 同一 ghost 的并发 session 竞态需要修复或证明不会发生。 审查讨论指出，两个并发请求可能同时复核旧 session；其中一个请求创建新 session 后，另一个请求随后按当前 Map 值执行 teardown，可能把刚创建的 session 一并作废，导致恢复期间 open/status 交错失败。建议将 binding 复核、teardown、session 创建和自动 open 放入 per-ghost 临界区，或仅条件性作废调用方此前持有的 session，并增加并发回归测试。
   3. 断盘修复不应退化其它 Library 保障。 审查讨论还指出 custom open 可能绕过原有 sweepStaleTmp()，以及正常 custom open 可能重复全量扫描 usage。两点都需要对照 PR 实际 diff 和行为确认：临时 .tmp/.stream 文件仍应有安全清理路径，已有有效 usage.json 不应被无条件绕过，否则会引入长期磁盘占用或重复 I/O。

   建议的验证门槛

   • macOS/Linux：已打开 custom Library 后移走目标，连续执行 open、status、read、write，确认只返回 unavailable，不创建空目录、不修改 binding、generation 或 identity。
   • 恢复场景：将同一原目标恢复后，既有原件可读、写入可继续；创建同名但不同 identity 的目录时保持 binding-moved，不得跟随新目录。
   • 冷启动：目标消失期间退出并重新启动 Cindy，确认仍是 unavailable；原目标恢复后无需重新安装插件或重新授权即可恢复。
   • Windows：验证已有 custom Library、新建 custom Library、目标暂时不可用和同路径对象替换，分别确认可用性及文档所述限制。
   • 并发：对同一 ghost 同时发起 open/status/恢复请求，确认新 session 不会被另一请求误作废；同时确认不同 ghost 的 extraDir 槽不会互相撤销。
   • 运行仓库规则规定的最小检查：pnpm --filter desktop exec vitest run src/main/cindy-brain/__tests__/library 与 pnpm --filter desktop typecheck，并在 PR 中列出 Windows/冷启动/并发测试结果。

   相关记录

   • #4728：当前修复的直接实现记录，覆盖 cached session 的 binding 复核、不可用语义、fd-relative 初始化、回归测试和规则文档；其审查讨论同时暴露了 Windows 可用性与并发 session 风险，因此应在该 PR 内 Request Changes 后继续推进，而不是直接放行。
2. MagicLizi commented on Sep 21, 2026

   

   MagicLizi

   on Sep 21, 2026

   ContributorAuthor

   More actions

   维护者确认已通过,讨论结束,PR 恢复正常推进。关联 PR:#4728(https://github.com/makecindy/cindy/pull/4728)。本 issue 由 review-pr 流程自动关闭。
3. MagicLizi

   closed this as completedon Sep 21, 2026