避坑指南！DeepSeek Harness 0.1.3-alpha.1 这 6 类坑我帮你整理好了

DeepSeek Harness 0.1.3-alpha.1 发布以后，我这两天一直在盯官方仓库和社区反馈。

刚发布时，我最关注的是它新增的几个能力：

任意文件上传统一代理Intel Mac Runtimeread_image 直接显示图片第三方模型自动发现

这些更新确实都挺实用。

但 Alpha 版本有一个很现实的特点：

功能先跑起来，真实用户一上量，各种边边角角的问题才会慢慢冒出来。

现在距离 0.1.3-alpha.1 发布大约两天，社区已经陆续挖出了一批很有代表性的问题。

有 Windows 安装失败的，有升级后插件把整个 Web 拖死的，有 Firefox 打不开历史会话的，还有跑了很久的 Session 卡在 Context Window 里进退两难的。

更值得注意的是，有些问题并不能简单归结为“这个版本有 Bug”。

有的是新版本底层改动带来的兼容问题，有的是长期存在的边界在这两天被用户真正跑出来了。

所以这篇我不准备做一份单纯的 Bug 清单。

我更想回答一个实际问题：

如果你现在已经在用 0.1.3-alpha.1，这些坑怎么判断、怎么绕、哪些操作最好提前做？

先说我的结论。

如果 DSH 是你的主力生产工具，而且里面已经有很多重要的长期 Session，我仍然建议以稳定为先。

如果你就是想体验文件上传、统一代理、模型自动发现这些新能力，那么 0.1.3-alpha.1 完全可以玩。

只是下面这 6 类坑，最好提前知道。

一、Windows 源码安装先卡住：Node 26 暂时别急着上

这两天最直接的一类反馈来自 Windows。

有人拿 0.1.3-alpha.1 源码执行：

pnpm install

结果安装过程直接倒在：

fs-extnode-gypMSBuild原生模块编译失败

这里为什么突然冒出一个 fs-ext？

原因其实和这次新加入的 Session Lock 有关。

DSH 现在开始防止：

进程 A同一个 Session进程 B

同时往一份 Session 日志里写数据。

在 Linux / macOS 这一类 POSIX 系统上，它需要使用类似：

flock

这样的系统级文件锁。

fs-ext 就参与了这里。

Windows 本身的 Session Lock 走的是另一套 Named Semaphore，也就是 Windows 内核信号量。

问题在于：

Windows 运行时未必需要 fs-ext 去完成最终加锁，但源码安装阶段仍然可能需要编译这个原生依赖。

于是 Node、node-gyp、Visual Studio Build Tools、MSBuild 这些东西就全被卷进来了。

目前社区复现里有一个很明显的共同点：

Node 26

虽然 DSH 自己的版本约束写的是：

^22.19.0或者>=24.0.0

理论上没有排除 Node 26，但从目前的实际兼容情况看，我更建议 Windows 用户先守在 Node 24。

尤其是自己 clone 源码运行的朋友。

可以先检查：

node -vpnpm -v

我现在更倾向于：

Node 24pnpm 11.7.0

这一组。

社区确实有人通过关闭一部分 LTO 编译参数暂时绕过 fs-ext 构建问题，但后面又出现了历史 Session 读取异常。

所以我不建议刚接触的朋友照着各种环境变量一个个硬改。

更稳的原则很简单：

Windows + Alpha + 原生依赖，先使用项目当前验证得比较充分的 Node 版本。

还有一点要注意。

这个坑目前主要针对：

源码安装本地开发自己构建 DSH

如果你只是正常使用已经发布的包，别看到 fs-ext 三个字就先把自己的环境全部推倒重装。

先看错误日志是不是同一类问题。

二、升级完 Web 直接打不开？先把第三方插件关掉

这一条我觉得普通用户一定要记住。

以后 DSH 每次 Alpha 大改，我甚至建议把它变成固定操作：

升级核心前先禁用第三方插件

为什么？

0.1.3 这一轮底层 API 又调整了一些。

有旧插件还在调用以前的：

settingsNamespaceinstallSettingsSection

一类接口。

核心升级以后，这些旧接口发生变化，插件加载时就可能直接出现类似：

does not provide an export named ...

然后最麻烦的事情发生了。

你以为只是：

某个插件坏了。

实际可能变成：

DSH 启动加载插件树某个旧插件 import 失败整个插件树启动失败Web 都打不开

这时候很多人的第一反应是：

清 npm 缓存重装 Node删除 lockfile重新安装 DSH

折腾半天以后发现问题还在。

以后看到这一类报错，我建议第一检查项直接改成：

最近是不是升级过 DSH，但插件还是旧版本？

最稳的升级顺序应该是：

备份暂停 / 移除第三方插件升级 DSH确认纯净 DSH 正常插件一个一个装回来

如果加回某个插件以后立刻挂掉，问题就非常容易定位了。

尤其是：

SidebarMarketUI 增强Provider 扩展Settings 页面扩展

这类和内部接口耦合比较深的插件，Alpha 跨版本升级尤其需要注意。

我的建议甚至更激进一点：

核心版本和插件版本不要一起批量升级。

一次只改一个变量。

这样出问题以后，至少知道是谁干的。

三、Firefox 一直 Loading history，先别碰你的 Session 文件

这一条很容易把人吓到。

社区出现了这样的复现：

同一个 DSH同一个 Workspace同一个历史 Session

在：

ChromeEdgeBrave

里面正常。

换成：

FirefoxZen

却一直停在：

Loading history…

如果不知道这个问题，很容易得出一个错误判断：

我的 Session 升级到 v2 以后坏了。

然后开始删缓存、迁移 Session，甚至直接删历史数据。

先别这么干。

因为这个问题目前已经有人追到了一个非常细的浏览器差异。

DSH 某段逻辑会使用：

Function.prototype.toString()

去判断对象。

可 Chromium 背后的 V8 和 Firefox 背后的 SpiderMonkey，对原生函数转成字符串以后的格式并不完全相同。

看起来只是换行、空白这种很不起眼的区别。

结果却可能导致：

正常 JSON 对象被错误分类Assistant Stream 校验失败历史会话无法正常渲染

所以如果你遇到：

Firefox 永远 Loading history

第一步特别简单：

换 Chrome / Edge 打开同一个 Session。

如果 Chromium 浏览器能正常打开：

数据大概率还在Session 大概率没有坏

这时候别去动底层文件。

等浏览器兼容修复会更安全。

所以 0.1.3-alpha.1 这一阶段，我自己的建议是：

主力 Web UI优先 Chrome / Edge / Brave

Firefox 用户可以继续关注后续版本。

四、长 Session 是目前最大的雷区：该压的时候没压，真超窗以后又压不动

如果你经常让 DSH：

跑几小时跑一天长期 Goal大量工具调用不断读文件不断搜网页

这一节建议认真看。

这两天长 Session 暴露出来的问题，我认为比界面 Bug 更值得重视。

因为它可能直接让一个跑了很久的任务进入：

无法继续

的状态。

目前社区出现了两类互相关联的 Compaction 问题。

恢复长 Session 后，第一轮自动压缩可能没有触发

有用户恢复一个非常长的历史 Session。

Token 已经到了六十多万，后来甚至继续涨到八十多万。

但 Session 日志里一直没看到预期的：

compaction/startcompaction/summarycompaction/end

也就是说：

上下文已经非常大理论上该自动压缩压缩却没有正常发生

社区目前的分析指向“恢复后的第一轮上下文状态和 Route 判断”这一类边界。

第二类更加麻烦。

真正超出 Context Window 后，Compaction 自己也会超窗

有一份复现非常直观。

Session：

291025 tokens

模型 Context Window：

262144

已经超了。

DSH 于是准备压缩历史。

正常理解应该是：

历史太大总结一下缩短 Context继续工作

可 Compaction 自己也需要请求模型。

如果它拿着已经超过 26 万 Token 的历史去请求一个只有 26 万窗口的模型：

Compaction 请求Context Overflow压缩失败

然后正常聊天再请求：

Context Overflow

于是出现一个非常尴尬的闭环：

因为超窗所以需要压缩因为已经超窗所以压缩不了

这才是我觉得目前长 Session 最危险的地方。

怎么避免？

关键只有一句：

不要等 Context Window 已经撞墙以后，再想起 /compact。

特别是恢复一个长期 Session 后。

如果你发现 Token 已经明显接近上限，我反而建议先：

检查当前任务状态主动 /compact确认压缩完成再继续跑

而不是：

再问最后十个问题应该没事。

长任务特别容易：

一个 Web Search几个大文件几个 Subagent一轮工具输出

突然又塞进几万 Token。

如果已经进入：

正常请求超窗/compact 也超窗

这种状态，我不建议连续 Retry。

更现实的恢复办法是把：

当前任务目标已经完成什么关键结论重要文件路径剩余工作

整理出来，开一个新 Session 继续。

这虽然不够优雅，但至少比让已经锁死的 Session 一遍遍烧 Token 强。

五、自建模型跑到 300 秒突然 terminated，先查 HTTP 超时

这条主要给使用：

vLLM本地大模型自建推理服务超长上下文模型

的朋友。

普通 OpenAI、DeepSeek 之类云端 API 用户不一定容易碰到。

社区有一个非常有规律的现象：

模型开始处理请求Prefill 特别慢一直没有第一个 Token大约 300～302 秒terminated

最开始很容易怀疑：

显存炸了？模型崩了？vLLM 死了？代理断了？

结果最后追到了 Node 网络栈里面一个很熟悉的数字：

300000 ms

也就是大约：

5 分钟

如果 HTTP Header 已经回来了，但模型长时间没有 Body 数据，undici 的 Body Timeout 就可能先一步终止连接。

更麻烦的是，这种错误还可能被上层当成：

可重试的网络错误

然后：

第 1 次等 5 分钟失败第 2 次又等 5 分钟失败第 3 次继续……

真正烧掉的可能不只是时间，后端还在重复做大 Context Prefill。

所以以后如果错误时间特别规律：

每次都差不多 300 秒

请先检查 Timeout。

暂时怎么绕？

最直接的办法还是减少一次请求需要 Prefill 的内容：

提前 compact减少大段无关历史新开 Session降低输入 Context使用 Prefill 更快的模型

社区已经提出把 Headers Timeout、Body Timeout 做成可配置项的方向。

但截至 0.1.3-alpha.1，不要看到网上有人贴：

httpBodyTimeoutMs

就以为这是当前正式版已经支持的配置。

目前更适合作为后续修复方向理解。

六、两个最香的新功能，也各有一个隐藏边界

最后这一类特别值得讲。

因为它们恰好就是 0.1.3-alpha.1 最吸引人的新能力：

任意文件上传模型自动发现

功能没有问题。

只是用之前最好知道边界在哪里。

第一个：任意文件上传没有大小限制，也还没有自动垃圾回收

官方这套文件上传设计其实挺有意思。

文件上传以后，并不会一股脑把全部文件内容塞进 Prompt。

大致是：

上传文件保存原始字节生成只读路径给 Agent 一个文件 Handle需要时再调用文件工具读取

这非常合理。

甚至相同内容的文件还会通过内容摘要做去重，避免重复保存同一份字节。

但当前实现同时有几个很现实的问题。

官方实现说明自己就写得很清楚：

没有文件类型白名单没有文件大小上限

更关键的是：

已经上传的文件目前不会自动删除

也就是说：

DSH_HOME

可能持续增长。

这让我第一时间想到以前最容易被忽视的一个问题：

AI Agent 不一定先把 Token 烧完，很可能先把你的硬盘写满。

尤其以后大家开始往 DSH 里面拖：

PDF视频素材ZIP数据集日志代码包

文件量会比以前图片时代大得多。

所以我建议增加一个固定维护动作。

macOS / Linux 可以偶尔看一下：

du -sh ~/.dsh

Windows 用户也可以定期检查：

用户目录\.dsh

占了多少磁盘。

另外当前上传：

没有真正的断点续传

网络断了，重新来可能还是从第一个字节开始。

如果文件已经上传完成，但还没有真正发送进 Session，这时候 Host 重启，还有可能碰到：

FILE_NOT_STAGED

这种暂存状态丢失问题。

所以特别大的文件，我目前反而不建议一股脑拿 DSH 当网盘用。

第二个：模型自动发现，也可能碰到“目录比 Provider 慢一步”

这条更反常识。

我们前面刚说 0.1.3-alpha.1 加强了：

Model Discovery

现在可以从 Provider 自动查询模型。

但社区又发现：

部分内置 Catalog 路径仍然会使用：

构建时打包的模型快照

问题就来了。

假设 Provider 今天刚上线一个新模型。

实时接口：

已经有

DSH 自己打包时的 Catalog：

还没有

于是可能出现：

Provider 实际能调用DSH 列表找不到

甚至某些情况下：

你手工填了 Model IDCatalog 不认识配置阶段先被拒绝

这时候最容易误判：

API Key 有问题。

然后换 Key、换 Base URL、重配半天。

以后碰到新模型，我建议多做一步：

先去 Provider 自己的 /models 或官方模型列表确认，它到底有没有。

如果 Provider 明确存在，而 DSH 内置目录没有：

别急着怪 API Key

可以尝试 Custom Provider / Endpoint Discovery 这一条路。

如果仍然被 Catalog 校验挡住，那基本只能等目录更新或者相关逻辑进一步放宽。

这里有一句特别值得记住：

DSH 列表里没有，不代表 Provider 一定不能调用。

研究完这两天出现的问题，我反而更加理解为什么官方把版本号写成：

0.1.3-alpha.1

它的几个新能力确实很香：

任意文件上传统一代理模型自动发现Session v2Session Lock

但这一版同时动到了：

存储网络Session原生依赖插件 APIProvider Catalog

这些都属于 Agent 工具真正长期使用以后最容易出问题的基础层。

所以 0.1.3-alpha.1 我依然建议：

可以体验，别闭眼迁移全部生产环境。

尤其你手里已经有很长的历史 Session、装了不少插件，或者 DSH 本身承担着每天都在跑的重要任务，更应该慢一点。

Alpha 的价值本来就是让这些问题尽早暴露出来。

对于普通用户来说，我们要做的并不是完全不碰 Alpha。

而是知道：

什么可以试什么要备份什么先别动出了问题先查哪里

这才是真正有用的避坑。

干货提炼

• Windows 源码构建 0.1.3-alpha.1，优先 Node 24，暂时别急着追 Node 26
• 升级 DSH 前先禁用第三方插件，确认核心正常以后一个个恢复
• Firefox / Zen 卡 Loading history，先用 Chrome / Edge 打开同一 Session 验证，别急着删数据
• 长 Session 不要等 Context Window 爆满以后再压缩
• 恢复超长历史 Session 后，优先检查 Token，必要时主动 /compact
• 如果普通请求和 /compact 都已经 Context Overflow，整理状态后开新 Session 更稳
• 自建慢模型固定在约 300 秒出现 terminated，优先排查 HTTP Body Timeout
• 任意文件上传目前没有类型和大小上限，上传对象也还不会自动清理
• 定期检查 DSH_HOME 磁盘占用，别让文件上传悄悄吃满硬盘
• 上传大文件目前没有完整断点续传，重要文件别把 DSH 当唯一存储
• DSH 模型目录没有某个新模型，不代表 Provider 一定不支持
• 0.1.3-alpha.1 适合尝鲜，重要生产环境建议先小范围验证再迁移