dsh-skill-filesystem 的目录监视在 Windows 上导致 bundle 插件无法在线更新（ERR_PNPM_EPERM: rename …_tmp_…）

[Euezb]

摘要

@deepseek-ai/dsh-skill-filesystem 在 watch: true（默认）下用 chokidar 以深度 1 监视每个注册的技能根，在 Windows 上会为该目录持有句柄。结果是：注册了技能根的 bundle 插件，在 DSH 运行期间永远无法在插件市场里更新 —— pnpm 落地新版本的最后一步 rename <pkg>_tmp_<n> -> <pkg> 被 Windows 拒绝。

环境

• Windows

• DSH Desktop 2.0.10 / @deepseek-ai/dsh 0.1.5-rc.2

• @deepseek-ai/dsh-skill-filesystem 0.1.5-rc.2

• Node v24.18.0 / pnpm 11.8.0

• profile desktop（nodeLinker: hoisted，autoInstallPeers: false）

复现

1. 安装 @openviking/dsh-memory-plugin@0.3.0 并保持 DSH 运行。

2. 更新到 0.3.2：

   dsh plugin --profile desktop add @openviking/dsh-memory-plugin@latest

实际结果

ERR_PNPM_EPERM: [importPackage ...\node_modules\@openviking\dsh-memory-plugin]
EPERM: operation not permitted, rename
'...\node_modules\@openviking\dsh-memory-plugin_tmp_15548_10' -> '...\node_modules\'

同一进程内改名探测（Rename-Item + 立刻改回）：

插件（同期在线更新均成功） | 子目录 | 包根 -- | -- | -- dsh-context | lib、node_modules 均 OK | ✅ OK dshmarket | client/lib/src 全 OK | ✅ OK @gausszhou/dsh-opencode-session-id | lib OK | ✅ OK @openviking/dsh-memory-plugin | shared OK、servers OK、skills LOCKED | ❌ LOCKED

补充：包内新建/删除文件成功、改名 README.md 成功、skills/openviking-memory 内部改名成功 —— 即锁的粒度是目录句柄，不是「文件被占用」。

根因

@openviking/dsh-memory-plugin 的 skills.mjs 注册了包内技能根，且未传 watch：

export const SKILLS_DIR = fileURLToPath(new URL("./skills", import.meta.url));export function buildSkillsConfig() {  return { providerName: SKILL_PROVIDER_NAME, includeDefaultRoots: false, customSkillDirs: [SKILLS_DIR] };}export function mountOpenVikingSkills(ctx) {  return ctx.plugin(skillFilesystem, buildSkillsConfig());}

该插件由自己的 bundle patch 以默认配置挂载（其 cordis.patch.yml 只写 name:，无 config），用户的 profile patch 也未覆盖，因此走默认值：

• lib/index.js:37 → watch 默认 true

• lib/index.js:38 → watchUsePolling 默认 false

• lib/index.js:372-386 → openRootWatcher() 用 chokidar.watch(mode.anchor, { …, usePolling })，深度 1

chokidar 底层 fs.watch() 在 Windows 上持有该目录句柄且不带 FILE_SHARE_DELETE，于是：

• skills/ 本身不可改名（watcher 钉住它）

• 其子项可改名（深度 1）

• 包里其他目录可改名（无 watcher）

而 pnpm 更新一个包要 rename 的正是该目录的父包目录，故必然 EPERM。这也解释了为什么 dsh-context / dshmarket / dsh-opencode-session-id 同期都能在线更新：它们加载后不留任何持续句柄。

影响面

不限于 OpenViking：任何在 Windows 上注册文件系统监视根的 bundle 插件都无法在线更新，且用户得到的提示是「检查 profile」，与实际原因无关。

期望

1. Windows 上更新此类插件应成功，或至少一次性给出可执行指引（完全退出 DSH 后命令行更新 / 停用该插件并重启后再更新）。

2. 不应为了更新而要求用户「停用插件」——这属于平台实现细节泄漏。

建议修复

A（根治，推荐） Windows 上对注册根默认 usePolling: true。fs.watchFile 只周期性 stat 目标路径，不持有目录句柄，因此 rename 不再被拒。现有 watchPollIntervalMs（默认 100ms）与 watchUsePolling 开关使这只是一处策略切换。代价是轮询开销，可配合 watchMaxProjects 限流。

B 改为监视技能根的父目录而非根自身，使技能根可被整体替换。

C 若 A/B 有额外权衡，至少提供可显式 watch: false 的途径并写入文档：随发行版发布、运行时不会被磁盘编辑的技能目录（如本 bundle 的 skills/）并不需要 watcher。

[PerryLink]

在 master（c291e7961）核实：诊断成立，且你提的"建议 C"（提供开关）其实已经存在，只是没文档明示。

• 默认开启监视：watch: z.boolean().default(true)、watchUsePolling: z.boolean().default(false)（packages/skill/skill-filesystem/src/index.ts:82-83）。
• chokidar 打开根监视时 persistent: true, depth: 1（:491-506），usePolling/interval 已 plumb（:504-505）；Windows 下持久目录句柄挡住 pnpm 的原子 rename 符合已知平台行为（未验证：我未在 Windows 实测句柄语义，以你的实测为准）。
• watch: false 逃生舱已存在（:82）——技能目录改完插件后重开/重载即可，只是 README 没写清楚。
• 顺带：watchMaxProjects（:69）可限制同时监视的项目数。

建议：认可你的建议 A——Windows 默认走 polling（策略里一处平台判断），同时把 watch: false 写进文档；建议 B（unlink 目录就自动关闭监视）会碰到现有 unlinkDir 重挂逻辑（:555-558 会 scheduleRewatch），改动面更大，短期不建议。合起来是一个"Windows 默认 polling + 文档化 watch:false"的小 PR，值得提。

[Euezb]

skill-filesystem-windows-polling-master-ddefc45fb.patch

建议 A（Windows 默认走 polling）+ 文档化 watch: false。

补丁：附件 skill-filesystem-windows-polling-master-ddefc45fb.patch

项 | 值 -- | -- 基线 | ddefc45（当前 master） 规模 | 11 个文件，+160 −12 SHA256 | EDC0C9025130D6697F1FCB78DBE6A6E8E03EE682637334876236FB439277AFF4 git apply --check | 在独立 worktree 的 origin/master 上验证：exit 0，11 个文件全部干净

改动要点

源码 packages/skill/skill-filesystem/src/index.ts

• watchUsePolling: z.boolean().default(false) → z.boolean()，平台默认放进 resolveWatchConfig()：config.watchUsePolling ?? platform() === 'win32'。
• 去掉 schema 默认值是必要的：apply() 拿到的是已解析配置，.default(false) 会把「用户没设」和「用户显式 false」压成同一个值，Windows 用户就无法选择原生事件。docs/config-catalog.md 里该字段本来就是 watchUsePolling?: boolean（无默认），改完与文档一致。

测试 tests/skill-filesystem-watcher.spec.ts

• mock node:os 的 platform()，新增四个用例：Windows 未设置 → usePolling: true；Windows 显式 false → false；Linux 未设置 → false；Linux 显式 true → true。该文件 11/11 通过。

文档（中英配对，i18n 哈希已按新内容重算）

• README 中英：watch* 段落补上「Windows 默认轮询」及其原因；新增 watch: false 的适用场景（随包发布、运行时不在磁盘上编辑的技能根，例如 bundle 自带的 skills/），并说明代价是新增/改名/删除的 skill 要在宿主插件重载后才进入目录。
• docs/config-catalog 中英随 JSDoc 同步。
• .agents/notes/proposed/bug-fix/2026-09-15-windows-polling-default-for-skill-roots.{md,zh.md,i18n.yaml}：按仓库要求附 Agent Note。

你标为「未验证」的 Windows 句柄语义，已实测

隔离 A/B，除 usePolling 外其余选项与 openRootWatcher() 一致（persistent: true, ignoreInitial: true, depth: 1, awaitWriteFinish）：

复制

platform: win32
usePolling: false -> LOCKED (EPERM)   # 原生 fs.watch 持目录句柄，rename 被拒
usePolling: true  -> OK               # 轮询不持句柄，rename 成功

所以建议 A 不只是规避，而是直接消除 EPERM：pnpm 的 rename(tmp -> pkg) 在 polling 下能通过。这也说明不必动 unlinkDir 的重挂逻辑。

补充：这个 bug 的后果已经升级了

9/15 那次的表现是「更新失败但磁盘完好、重启即可」。9/21 又发生了一次，结果更糟：pnpm 在重试 rename 之前把目标目录清掉了，旧构建没能恢复（dshmarket 1.52.0 如实报告 the previous build is incomplete (package.json or its entry file is missing)），而被清掉的包仍然留在 profile 的 dependencies 与 dsh.profile.bundles 里，于是应用每次启动都卡在 profile-composition 阶段失败——6 次启动全部起不来，最后只能卸载该插件才恢复。

也就是说：这个 bug 会从「无法在线更新」升级成「应用无法启动」。启动期那一环（已声明但目录残缺的 bundle 直接让整个 profile 合成失败，且绕过已有的 recovery 路径）我已单独报给桌面仓库 anywhere-labs/dsh-desktop。

如果这个补丁你希望收窄成最小版本（只改平台判断 + 文档，去掉 Agent Note 或测试），或者按仓库规范拆成多笔，告诉我即可。