[Bug] fs-local | asar 内路径 stat({bigint:true}) 抛 Cannot mix BigInt，filesystem 技能提供者整块被跳过

[renxiangquan]

环境
项 值
运行体 Electron 43.0.0 / Node 24.17.0 / win32
形态 桌面打包版（resources/app.asar，281,491,121 字节）
缺陷包 @deepseek-ai/dsh-fs-local（packages/fs/fs-local），打包副本；npx 缓存另有 0.1.5-rc.2 同样复现
触发条件 目标路径位于 app.asar 内（纯 Node / 非打包环境不复现）
English summary (for triage)

dsh-fs-local assumes fs.stat/lstat(path, { bigint: true }) always returns a BigIntStats. Inside a packaged Electron app, Electron's asar layer silently ignores the bigint option and returns a plain Stats (numeric mode) for paths inside app.asar. probe() / probeNoFollow() then evaluate Number(info.mode & 511n), which throws TypeError: Cannot mix BigInt and other types. The error is wrapped by listingIoError() into FsError: cannot list "…", which makes the whole filesystem skill provider get skipped and retry every ~15s. Fix: mode: Number(info.mode) & 0o777, in both places.
归类提示（给维护者）
这是 fs-local 的类型假设缺陷，不是归档损坏、不是路径不存在、不是 chokidar/readdirp 的问题。
纯 Node 环境不会复现：必须运行在 Electron 打包体中（asar 读取路径）。
同一根因在 Electron 上游也有同族表现：asar 构造的 Stats 是"数值型残缺对象"（参见 electron#42686，blksize/blocks 为 undefined）。
若维护者认为应由 Electron 侧修（让 asar 尊重 bigint），本方也接受；但 fs-local 无论如何都应对 Stats / BigIntStats 两种输入健壮。

---

1. 一句话
   dsh-fs-local 假定 fs.stat/lstat(path, { bigint: true }) 必然返回 BigIntStats，但 Electron 的 asar 层会静默忽略 bigint 选项，对 asar 内路径返回普通 Stats（mode 为 Number）。于是 Number(info.mode & 511n) 抛 TypeError，filesystem 技能提供者被整体跳过。

---

2. 症状
   harness.log 中以约 15 秒为周期持续重复（实测 8 分钟内 33 条，重启后仍复现）：

warn skill-registry: skill provider "filesystem" skipped:
  FsError: cannot list
  "C:\...\DSH Desktop\resources\app.asar\node_modules\@deepseek-ai\dsh-agent-preset\skills":
  Cannot mix BigInt and other types, use explicit conversions

可观察后果：该路径下确实存在的技能（实测 17 个文件、4 个技能目录：agent-experience、cordis-composition-reference、cordis-plugin-development、editing-cordis-compositions）无法挂载，技能目录不完整。仅日志刷屏，无崩溃。

3. 根因
   dsh-fs-local 中两处（lib/index.js，两处逻辑相同）：

async function probe(absolutePath) {
  const info = await probeStats(absolutePath, (path) => stat(path, { bigint: true }));
  if (!info) return null;
  return {
    version: versionOf(info),
    mode: Number(info.mode & 511n),   // <-- 抛 TypeError
    type: pathType(info),
    size: Number(info.size)
  };
}

async function probeNoFollow(absolutePath) {           // 同样问题
  const info = await probeStats(absolutePath, (path) => lstat(path, { bigint: true }));
  ...
    mode: Number(info.mode & 511n),   // <-- 同样抛 TypeError
  ...
}

实测对照（同一进程、同一 API，仅路径不同）：
路径 stat(p, {bigint:true}).constructor.name typeof mode Number(mode & 511n)
真实文件系统路径 BigIntStats bigint 438 ✅
app.asar 内路径 Stats number THROW TypeError: Cannot mix BigInt and other types ❌
即 Electron asar 层未实现 bigint 分支（其内部把 asar 元数据构造成普通 Stats；同族问题见 electron#42686）。异常随后被 listingIoError() 包装：

return new FsError(`cannot list "${displayPath}": ${errorMessage(error)}`, "FS_IO_ERROR", { cause: error });

→ 与 §2 的日志行逐字对应。

4. 建议修复（两种，任选）
   方案 A：调用方做类型归一（推荐，改动最小）

// before
mode: Number(info.mode & 511n),
// after
mode: Number(info.mode) & 0o777,

Number(...) 先把 BigInt/Number 统一成数字，再按位掩码。掩码仍是 511，语义不变。两处都要改。
方案 B：对缺失字段做防御（同时覆盖 §7 的次要问题）

function versionOf(info) {
  const m = info.mtimeNs ?? BigInt(Math.trunc(info.mtimeMs ?? 0)) * 1000000n;
  const c = info.ctimeNs ?? BigInt(Math.trunc(info.ctimeMs ?? 0)) * 1000000n;
  return FsVersion(`${info.dev}:${info.ino}:${info.size}:${m}:${c}`);
}

---

5. 最小复现
   在 Electron（ELECTRON_RUN_AS_NODE=1）下运行：

const { stat } = require('node:fs/promises');
const p = 'C:\\...\\DSH Desktop\\resources\\app.asar\\node_modules\\@deepseek-ai\\dsh-agent-preset\\skills';
const s = await stat(p, { bigint: true });
console.log(s.constructor.name, typeof s.mode);   // Stats number
Number(s.mode & 511n);                            // throws TypeError

对照：把同一路径换成一个普通目录，得到 BigIntStats 且不抛错。

6. 排除项（避免误判）
   嫌疑 结论 依据
   readdirp 无关 其 Windows 分支确实传 {bigint:true}，但自身无 BigInt 算术
   chokidar 无关 内部为 stats.mtimeMs === 0 严格相等，不抛
   归档损坏 无关 asar 索引与全部 19,623 个打包条目完整性校验 100% 通过
   路径不存在 无关 该目录在 asar 内确实存在（已确认 17 个文件）

---

7. 附带发现（次要，可选修）
   即使打上 §4 的补丁，versionOf() 仍不完整：
   普通 Stats 没有 mtimeNs / ctimeNs 字段 → 版本串里出现 undefined；
   且 asar 内条目的四个时间戳全部等于归档容器自身的时间（实测四者相同），因此版本/新鲜度标识实际退化为常量。
   影响：缓存失效判定、变更检测可能失准。不影响正确性，故列为次要。

---

8. 检索说明
   经检索未发现与本条完全对应的上游条目。已见的相关线索（仅标题级，未读正文）：
   electron#42686 —— .asar 的 fs.stat 返回的 blksize/blocks 为 undefined
   electron#50877 —— "return numeric blksize and blocks from asar fs.stat"
   二者同属"asar 构造的 Stats 是数值型残缺对象"这一族问题，但均未涉及 bigint 选项被忽略。本报告结论全部来自本机可复现实测，非文献引用。

---

9. 附件说明
   如需要，可提供两项本机证据：
   两路径对照实测的原始输出（BigIntStats vs Stats，含抛错堆栈）
   从 app.asar 中抽出的 dsh-fs-local/lib/index.js 源码（含上述两处，行 238–262）
   （本报告不含任何本地绕过改动；报表方未修改归档，桌面版为原始安装状态。）

[argszero]

Confirmed at source, and the defect is visible in the signature

Every claim of yours verifies against the tree at the current head (86a40220). The line numbers differ from your bundle because I read packages/fs/fs-local/src/fsio.ts, not lib/index.js:

• fsio.ts:252 — mode: Number(info.mode & 0o777n), in probe
• fsio.ts:268 — the same expression in probeNoFollow
• fsio.ts:75-77 — function versionOf(info: BigIntStats): FsVersion reading info.mtimeNs / info.ctimeNs

0o777n is 511n; your 511 reads the same. So both sites throw exactly as you describe, and your §7 is confirmed at the type level too: versionOf is typed BigIntStats, so a plain Stats is not merely missing those fields — the compiler was never given the chance to see it as a possibility.

The shape of the defect is one line above the throw

The helper both callers use already admits the wider type (fsio.ts:225):

async function probeStats<T extends Stats | BigIntStats>(
  absolutePath: string,
  readStats: (path: string) => Promise<T>,
): Promise<T | null>

T extends Stats | BigIntStats declares "either is possible", and the generic is threaded faithfully into the call sites — probe passes path => stat(path, { bigint: true }) and gets BigIntStats back, so at the type level nothing is wrong. The unhandled case is therefore not an oversight in one expression; it is a contract that was widened in the helper and not widened in the two bodies that consume it. The public interface has already made the same claim in the other direction — PathInfo.mode: number (fsio.ts:115-120) — so a plain number is what the API promises and a bigint is an implementation detail leaking out of the reader.

That is worth stating before the patch, because the minimal fix and the correct fix differ in where they land: masking with Number(info.mode) & 0o777 makes the two sites total, but versionOf stays wrong for a plain Stats (its version string becomes …:undefined:undefined, deterministically — it will not throw, it will silently lose time-based invalidation). Your §7 read is right, and this is its mechanism.

On the fix

Your option A is correct and semantics-preserving for both input types — Number() on a bigint is lossless at these magnitudes and the mask is unchanged. I would take A and a form of B: the mask sites can be fixed where they are, but versionOf's parameter type is what should widen (Stats | BigIntStats), with the ns fields derived from mtimeMs / ctimeMs when absent, since for a plain Stats there is nothing else to read. Otherwise the two undefineds land in FsVersion and the cache-invalidation half of the version quietly degrades on exactly the paths that motivated the probe.

One correction to the impact framing, in your favour: nothing here depends on the archive being damaged or the path being absent — probeStats rethrows anything that is not ENOENT/ENOTDIR (fsio.ts:225-240), so a TypeError from the mask is deliberately propagated as a real IO fault, which is precisely how it reached listingIoError() and became FsError: cannot list … with FS_IO_ERROR. A caller that distinguishes "absent" from "IO fault" — which this code does carefully — has no way to classify a type error as anything but the latter.

I have not run this in an Electron host, so the asar-side behaviour (stat(path, { bigint: true }) returning a plain Stats) is your measurement, not mine; what I verified is that the two expressions you quote are the ones in the tree, that the helper's generic admits the type they cannot handle, and that no existing code path normalises a plain Stats before masking.