profile 清单带 UTF-8 BOM 时 DSH 启动硬失败，报错不指向病因

[lire1131]

环境

• DSH 0.1.5-rc.2，Windows 11
• Node v24.19.0，npm 全局安装
• 相关包 @deepseek-ai/dsh-app-boot@0.1.5-rc.2

现象

profile 的清单 ~/.dsh/profiles/<name>/package.json 只要带 UTF-8 BOM（EF BB BF），DSH 就再也起不来，直接硬失败退出。控制台只留下这样一条：

SyntaxError: Unexpected token '锘?, "锘縶
    "n"... is not valid JSON
    at JSON.parse (<anonymous>)
    at readProfileManifest (.../@deepseek-ai/dsh-app-boot/lib/index.js:754:22)
    at loadProfile (.../@deepseek-ai/dsh-app-boot/lib/index.js:893:37)
    at prepareProfile (.../dsh/lib/profile-boot-*.js:208:18)

GBK 控制台把 BOM 那三个字节渲染成了「锘縶」，报错信息里看不出是编码问题。

复现

$p = "$env:USERPROFILE\.dsh\profiles\web\package.json"
Get-Content $p -Raw | Set-Content $p -Encoding UTF8   # PS 5.1 的 -Encoding UTF8 默认写 BOM
dsh web                                              # 启动即硬失败

无 BOM 写回即可恢复：

$t = [IO.File]::ReadAllText($p, [Text.Encoding]::UTF8)
[IO.File]::WriteAllText($p, $t, (New-Object Text.UTF8Encoding($false)))

原因

readProfileManifest() 读文件后直接 JSON.parse，没有剥掉开头的 U+FEFF：

packages/boot/app-boot/lib/index.js:750   raw = readFileSync(path, "utf8");
packages/boot/app-boot/lib/index.js:754   const parsed = JSON.parse(raw);

同一文件里还有几处读 package.json 后直接 parse 的写法，都会因为 BOM 走到硬失败或静默失败：

• 401 行 readModuleProxyRecord：抛错被 catch 吞掉，模块代理记录静默变成 undefined
• 582 行 readModuleFallbackManifest：直接抛错
• 851 行 bundle 硬检查读 dsh.bundle.patch 声明：直接抛错

也就是说任一 package.json 被外部工具写成带 BOM，都可能在引导期变成启动失败。

建议

在统一读 JSON 的位置去掉前导 BOM，例如 JSON.parse(raw.replace(/^\uFEFF/, ''))，或抽一个小 helper 复用。顺带把错误信息补一句「文件可能带 BOM」，现在这条报错完全看不出病因。

影响

不涉及安全与数据损坏，但代价不对等。Windows 上 PowerShell 5.1 的 Set-Content -Encoding UTF8、Out-File -Encoding UTF8，以及部分编辑器另存为 UTF-8 时默认都带 BOM；用户一旦用这些工具碰过 profile 清单，DSH 就启动不了，而报错不指向病因，只能靠手工排查字节。DSH 自己写回清单（writeProfileManifest，763 行）是无 BOM 的，所以问题只在外部编辑之后出现。

（这条是我在做插件启动失败路径自测时踩到的，附的报错就是当时的原始输出。）

[moonquake2004]

能被离线判出来，而且这个输入也照出了我们自己的同一个错判——两边都值得记一下。

一、判据本身很简单，缺的只是有人把它写下来。 BOM 对 JSON.parse 是硬失败（我在本机复核过：JSON.parse('\uFEFF{"a":1}') → Unexpected token '', "{"a":1}" is not valid JSON；剥掉前三个字节即正常），而宿主在 readProfileManifest 里是直接 parse、不剥 BOM，所以你看到的行为在 0.1.5-rc.2 与 0.1.6-alpha.1 上应当一致。

你说的"报错不指向病因"有两个叠加原因，值得分开：

1. 错误文本里带的是原始字节被解码后的字符（锘? 就是 GBK 控制台对 EF BB BF 的渲染），而不是"文件以 BOM 开头"；
2. 没人告诉用户这是编码问题——Unexpected token '锘?, "锘縶"n"... is not valid JSON 读起来完全像 JSON 语法写错了，而不是"你的编辑器/脚本给它加了 BOM"。

我们把这一条做成了检查（dsh-doctor@0.6.0 的 P22）：检出 BOM、点名 #6758、并给出无 BOM 保存的具体做法——因为你复现里的那个坑很典型，值得直接写进报错里：

# PowerShell 5.1 的 -Encoding UTF8 默认写 BOM，改用：
[IO.File]::WriteAllText($p, (Get-Content $p -Raw), (New-Object Text.UTF8Encoding $false))

二、我们此前在同一个输入上给出了错误结论。 我们的诊断工具也读这个 manifest，写法是：

const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));   // 带 BOM 时抛错 → 整段"检查异常"
// 另一处：try { ... } catch { profManifest = null }  → P18 报"未找到 profile manifest"

也就是说——用户的 profile 起不来，而我们的工具要么自己崩、要么告诉他"这个文件不存在"。对一个诊断工具来说这是最糟的失败方式：它被它要诊断的那份输入打败了。现在所有 manifest 读取改成带 BOM 感知：剥掉 BOM 后继续工作，把"有没有 BOM"单独交给 P22 报出。这样即使 profile 因为 BOM 起不来，其余 20 多项检查仍然能给出结论——包括那些与 BOM 无关的真实问题。

三、给你的一个附带好处：这类"文件看起来没问题、但序列化层不接受"的坑通常不止一处。如果你身边还有别的 JSON 清单是脚本生成的（例如某个工具的配置文件），值得顺手确认它们的编码——BOM 在 Windows 上尤其容易从 PowerShell 5.1、Out-File、以及部分编辑器的"UTF-8 with BOM"默认值里混进来，而在 Linux/macOS 上几乎不会出现，所以跨平台协作时最容易变成"只有我这边起不来"。

[moonquake2004]

更正我上一条回复里的一个说法，同时把真实的失败讲清楚——后者对这条线程更有用。

我说错的地方：我写"我们把这一条做成了检查（P22）……补的正是报错不指向病因缺的那一句"。不对。
我们早就有一条检查在管这件事：P15「关键文件 BOM 检查」，注释里的出处是 #5176（package.json 被意外加 BOM 头导致 JSON 解析失败），而且它的扫描列表第一项就是 profile 的 package.json。我实测过：给 profile manifest 加上 BOM，P15 会报

P15: 检测到 BOM 头（#5176：JSON/YAML 解析将失败）: package.json

也就是说——诊断一直都在，是我没查自己的清单就新加了一条重复的。这条已经撤掉了（#6758 特有的信息——PowerShell 5.1 的 -Encoding UTF8 默认写 BOM、JSON.parse 硬失败、报错被 GBK 渲染成乱码——并入了 P15）。

而真实的失败其实更有意思，也更值得记：在修复之前，你那种 profile 上我们的工具根本走不到 P15。因为主读取点是直接 JSON.parse manifest，BOM 让它抛错 → 整个 profile 段中断 →

P0: profile 检查异常: Unexpected token '', "{"name":"…"

P15 没有机会执行。 所以这不是"我们缺一条检查"，而是"一条正确的检查被上游一个无关故障静默了"。"有检查"和"用户看得到"是两件事——这个区别我此前没有当成一回事，今天它咬了两次（另一次是变量作用域错误掐掉整段）。

因此这轮改了三件事（dsh-doctor@0.7.0）：

1. 外部读取一律不抛（manifest 走带 BOM 感知的读取）→ 现在带 BOM 的 profile 上，P15 会真的报出来，其余 20 多项检查也照常给结论；
2. 两条回归测试钉住：带 BOM 时 P15 必须报出；manifest 无法解析时其余检查仍须给出结论（早期失败不得掐断整段）；
3. 覆盖不变量——这条超出了你这个 case：实测我们曾在"零 bundle、无会话库"的空环境下给出 18 项 pass，其中 14 项连一个"检查了多少"都没有。也就是说 "我什么都没看"和"我全看过、很干净"打印出来是一样的。现在 examined === 0 的通过一律自动降为 skip（"无可检查对象"），pass 必须报告检查了多少对象。同一个病在别处也发作过：--boot-check 对"bundle 缺 dsh.bundle"（零 entry 可探）报过"✓ 全部可导入"（[Bug] v0.1.6-alpha.1: computer-use packages missing dsh.bundle break profile boot #6788）。

还欠着的：环境段仍有 10 项没报告覆盖量（E1-*/E3/E4/E5/E6/E10/E12/E13）。补起来是机械的，但我把它写进了 release note 而不是留在心里——否则下一个读它的人会以为这块已经干净了。

最后一句给你：你这条报告改掉的不只是一条检查，而是我们造检查的方式——它让我意识到我们前几轮修的每一个 bug（判错视图、成片误报、假绿灯、重复检查）根因都相同：用一个"看起来合理"的模型，代替了权威来源。原则只有落成机制才算数，写在文档里就只剩运气。