DeepSeek Harness 启动报 Unexpected token:profile BOM 修复
DeepSeek Harness(DSH)在 Windows 上启动即崩、报 Unexpected token '',崩溃弹窗里的「恢复重启」按了又崩——这类故障最值得先做的一步不是重装,而是看一眼 profile 清单的前 3 个字节。 按 UTF-8 读取时,readFileSync(path, 'utf8') 会把文件开头的 BOM 当成普通字符保留下来,紧接着 JSON.parse(raw) 就在第一个字符上报错。正常情况下 profiles/<name>/package.json 的前 3 字节应该是 7B 0A 20(左花括号、换行、两个空格),带 BOM 时则是 EF BB BF 7B。判据就这么一步:前 3 字节是不是 EF BB BF(#11731)。
一步判据:先看前 3 字节,别先重装
关键判据是:EF BB BF = BOM,7B 0A 20 = 正常,两种开头对应完全不同的排查方向。 三个平台各给一条命令:
- Windows(PowerShell)读前 3 字节。
$p = "$env:USERPROFILE\.dsh\profiles\desktop\package.json"
[BitConverter]::ToString([IO.File]::ReadAllBytes($p)[0..2])
# 期望 7B-0A-20;若输出 EF-BB-BF 则带 BOM
- macOS / Linux 用 hexdump。
hexdump -C ~/.dsh/profiles/desktop/package.json | head -1
# 期望行首 7b 0a 20;若出现 ef bb bf 则带 BOM
-
看文件大小做一个交叉验证。 正常清单在讨论中是 1108 字节,坏掉的备份是 950 字节——注意大小差异不能单独作为判据,因为内容本身也会变,只用来辅助判断「是不是同一份文件」。
-
确认崩溃日志里的报错原文。 预期:
Unexpected token ''后面那个不可见字符就是 BOM。如果报错指向别的 token(比如}或数字),那就不是 BOM 这条,转去查 JSON 语法。
为什么 BOM 会让启动直接崩
一句话结论:读侧不剥 BOM、直接 JSON.parse,把一个可选容错变成了致命失败。 社区对 master ce7073d5 的只读核对给出了两处位置:
packages/boot/app-boot/src/profile.ts:552:readFileSync(path, 'utf8')按 UTF-8 读取,BOM 会作为内容的一部分返回。- 同一文件
:557:JSON.parse(raw)直接解析,中间没有trimStart或 BOM 剥离。
按 RFC 8259 §8.1 的口径:写入方 MUST NOT 加 BOM,解析方 MAY 忽略 BOM。这里是写侧违规、读侧又把「可选忽略」做成了「一遇就崩」。所以它不是某个插件的问题,也不是 Node 版本的问题——任何会写 BOM 的工具都能触发。
修法:剥掉 BOM 后用无 BOM 的 UTF-8 重写
一句话结论:把开头字符剥掉、用不带 BOM 的 UTF-8 编码写回,前三字节回到 7B 0A 20 就能启动。 PowerShell 命令(社区给出、报告者实测):
-
先复制一份原始文件到工作区外,万一改坏还能回退。
-
读全文并剥掉开头 BOM。
$p = "$env:USERPROFILE\.dsh\profiles\desktop\package.json"
$t = [IO.File]::ReadAllText($p).TrimStart([char]0xFEFF)
- 用无 BOM 的 UTF-8 编码写回。
[IO.File]::WriteAllText($p, $t, (New-Object System.Text.UTF8Encoding($false)))
- 立刻验字节。
[BitConverter]::ToString([IO.File]::ReadAllBytes($p)[0..2])
# 期望 7B-0A-20
- 启动 DSH。 预期:不再报
Unexpected token,正常进入界面。报告者按这条命令处理后,机器恢复正常,清单 1108 B、前三字节7B 0A 20。
两个注意点:不要用 PowerShell 5.1 的
Out-File/Set-Content默认写法「顺手保存」,它们正是常见的 BOM 来源;也不要用编辑器「另存为 UTF-8 with BOM」。要的是「UTF-8 无 BOM」。
纠正一个误判:恢复流程不会重写清单,但它也没有出路
一句话结论:崩溃弹窗的「恢复重启」不会再次写坏清单,但它对「清单不可解析」这种情形同样无能为力;原帖那句「恢复会再次写坏」已被回复者纠正、报告者也收回。 依据是源码路径:
packages/boot/app-boot/src/profile-sanitize.ts:19第一步就是读同一份清单。- 解析失败在
:27的renameSync之前抛出,所以根本走不到「写清单」那一步。 packages/boot/app-boot/README.md:71的原文是Invalid profile JSON fails before mutation,与源码一致。
所以「恢复会再次写坏」这个因果链不成立,原帖把它写得太硬,报告者在回复里明确收回。但真正的缺口反而更值得记住:这条恢复路径读同一个坏文件、失败即抛,没有隔离坏文件、没有回退上一次可用备份、也没有任何命令行入口。界面里本来就有「恢复失败」的文案,说明这在预期内——可失败之后用户手里什么都没有,只能像报告者那样去外部工具改字节。
这里还有一个细节容易被误读:报告者看到 cordis.patch.yml.bak-1793378185239,说明那一刻清单是能 parse 的(备份动作成功了)。所以「恢复按钮点了 9 次都崩」只能证明「恢复救不了」,不能证明「恢复把文件写坏了」(#11731)。
BOM 是谁写进来的:写侧不写,来源在 DSH 之外
一句话结论:DSH 自己的 writeProfileManifest 不写 BOM,主动写 BOM 的代码只有一处且与 profile 无关,因此来源是外部编辑器、PowerShell 5.1 或手工操作。 证据如下:
- 写侧实现干净。
profile.ts:569-571的writeProfileManifest是JSON.stringify(..., 2) + '\n',不写 BOM。 - 全仓搜索只命中一处主动写 BOM。 按
FEFF|ufeff|utf8-sig搜packages与apps,主动写 BOM 的只有packages/util/native-command/src/file-applications-windows.ts:268(给 Windows 脚本用的),其余命中都是解析前剥掉或拒绝。在 182MB 的发出包上全量搜,30 处命中全在 yaml / ajv / yaml-ast / eventsource / devtools。 - 对照组支持「不是每次写都加」。 同日 12:41 应用自己重写清单(1108 字节),首三字节是
7B 0A 20,此后 21 小时零崩溃。 - 时间线里仍有一处未定:00:26:46 清单能 parse,00:27:41 与 00:27:46 renderer / host 各崩一次,00:31:03 再看开头又是
ef bb bf。这段四分钟内的变化,报告者标明「来源未定」,只把字节与时间戳交出来,不作主张。
排查时正确的姿态是:先按字节修好、让机器能起,再把「谁写的」作为独立问题记录,不要为了等一个来源结论而卡在无法启动的状态里。
恢复按钮的代价,以及该往哪修
一句话结论:崩溃弹窗里的「禁用第三方插件」会把 bundles 从 8 条砍到 2 条,用更大的损失换一次重启;真正该修的是读侧容错、恢复侧隔离与一个不依赖 GUI 的入口。 讨论里给出的建议按优先级:
- 读侧止血(P0):配置读取收口到统一函数,
JSON.parse前剥离 BOM,顺带兼容 UTF-16 BOM。 - 恢复侧兜底(P0):坏文件先隔离为
.bad-<ts>,再从 last-known-good 恢复,并用同一加载器校验能 parse 再启动;同时加崩溃循环检测与安全模式。 - 写侧根因(P1):定位带 BOM 的写入路径,改成原子写(临时文件 + rename),写完回读校验。
- 用户侧认知:恢复按钮不是「万能重启」,它在清单不可解析时没有出路;按下去还可能改动你的 plugins 配置,先想清楚再点。
- 报告者的补充建议:给一个不依赖 GUI 的入口(启动参数或安全模式),让起不来的人能在里面重置清单、禁用插件。
排查注意事项
启动即崩这类问题,先做「字节级判据」再做「版本级猜测」,能省掉大量重装。 六条要点:
- 前 3 字节优先于一切:
EF BB BF就是 BOM,7B 0A 20就是正常。 - 别用默认编码「另存」:PowerShell 5.1 的
Out-File/Set-Content、编辑器的 UTF-8 with BOM 都会重新引入 BOM。 - 修完必须验字节,不要只看「能启动了」——下次写入可能又带回来。
- 恢复按钮不会重写清单,但也救不了不可解析的清单,别把两次崩溃解释成「恢复越修越坏」。
- 文件大小变化不能当判据,只能配合字节与时间戳交叉验证。
- 修好 BOM 后仍崩,换方向查:把报错原文与该文件前 8 字节一起贴出来,若前三字节已正常,就是普通 JSON 语法或文件截断问题。
常见问题
DeepSeek Harness 的这个报错很可能是文件开头带了 UTF-8 BOM。读取时用 readFileSync(path, 'utf8') 会把 BOM 当成普通字符保留,紧接着直接 JSON.parse 就会在第一个字符上报 Unexpected token。用十六进制看一眼文件前 3 字节,如果是 EF BB BF,就确认是 BOM 问题。
在 DeepSeek Harness 里看文件前 3 个字节即可,正常 JSON 应以 7B 0A 20 开头(左花括号、换行、两个空格),带 BOM 则是 EF BB BF 7B。Windows 上可以用 PowerShell 读字节数组再转十六进制,macOS 与 Linux 上直接 hexdump 或 xxd 看前 3 字节。
DeepSeek Harness 的这条恢复重启不会再次写坏清单。profile-sanitize 的第一步就是读同一份清单,解析失败会在 renameSync 之前抛出,走不到写清单那一步;官方 README 也写明 Invalid profile JSON fails before mutation。但这个恢复路径对「清单不可解析」同样没有出路,它既不隔离坏文件,也不回退上一次可用备份。
在 DeepSeek Harness 里,先把报错那一行的原文和当时的文件前 8 字节贴出来。前 8 字节是 EF BB BF 7B 0A 20 22 时才是纯 BOM 问题;如果前三字节已经是 7B 0A 20 却仍解析失败,就要按普通 JSON 语法错误排查,比如缺逗号、引号不配对,或者文件被截断。
相关术语
- UTF-8 BOM
- UTF-8 BOM 是文件开头三个字节 EF BB BF,历史上用于标记文件采用 UTF-8 编码。RFC 8259 规定 JSON 写入方不应添加 BOM,解析方可以忽略它;但很多解析器不做这层容错,于是 BOM 会变成第一个「非法字符」。— https://github.com/deepseek-ai/deepseek-harness/discussions/11731
- readProfileManifest
- readProfileManifest 是 DeepSeek Harness 启动时读取 profile 清单的实现,位于 packages/boot/app-boot/src/profile.ts 约 552 行,用 readFileSync(path, 'utf8') 读出内容后在 557 行直接 JSON.parse,中间没有剥离 BOM 的步骤。— https://github.com/deepseek-ai/deepseek-harness/discussions/11731
- profile-sanitize
- profile-sanitize 是 DeepSeek Harness 崩溃恢复流程的实现,位于 packages/boot/app-boot/src/profile-sanitize.ts。它先读同一份 profile 清单,解析失败会在 renameSync 之前抛出,因此不会重写清单,但也不会为不可解析的清单提供任何回退路径。— https://github.com/deepseek-ai/deepseek-harness/discussions/11731
来源
- #11731 — profile 清单被写入 UTF-8 BOM 后加载器解析即崩,且恢复流程会再次写坏,无法自救· deepseek-ai(GitHub Discussions)