【BUG】DSH底层问题详细Bug报告

[TomDarkWay]

DeepSeek Harness / DSH Desktop Bug Report

1. 报告摘要

本报告记录在 DSH Desktop 中观察到的两个相关但相互独立的问题，供 DeepSeek Harness 官方维护者定位和修复：

1. 工具调用参数兼容性问题：普通调用因空字符串 justification 被错误拒绝。
2. Windows/Synology Drive 工作区中的文件版本误报：内容未被用户修改时，write / edit 可能错误抛出 FS_STALE_VERSION。

其中，第一个问题已经通过当前官方源码确认仍然存在，且能够从源码直接推导出稳定复现路径；第二个问题的源码机制也仍然存在，但“本机实际触发是否由 Synology Drive 元数据变化导致”需要在运行中的 Desktop 重启后通过集成测试最终确认。

本报告不要求官方接受现有用户级 workaround 作为长期方案，重点请求官方确认参数归一化、版本 token 语义及对应回归测试策略。

2. 报告环境与源码基线

2.1 用户环境

• 操作系统：Windows
• DSH Desktop：2.0.1
• DSH runtime：0.1.0-rc.7
• 当前工作区：D:\SynologyDrive\Obsidian
• 工作区由 Synology Drive 管理；D:\SynologyDrive 带 Windows ReparsePoint 属性。
• Synology Drive 相关进程在现场观察时处于运行状态：cloud-drive-connect、cloud-drive-daemon、cloud-drive-ui。
• 对照现象：同一 Synology Drive 目录在 Codex 与 Hana 中可以正常编辑。

2.2 官方源码仓库

• 仓库：deepseek-ai/deepseek-harness
• 本地完整源码副本：E:\CodeFile\DSHsource
• 分支：master
• 分析时远端 master 与本地副本一致。
• 提交：b150a551b8d465e31e418e1b2eaf5e79bbb7d28e
• 提交时间：2026-08-21T20:03:37+08:00
• 对应 release 合并提交：0.1.1-rc.2

2.3 运行实例与源码的关系

运行实例位于：

D:\Program Files\DSH\DSH Desktop\resources\app.asar.unpacked\

其中可以看到打包后的 @deepseek-ai\dsh-sandbox\lib\index.js。该目录仅用于对照确认 Desktop 当前运行代码的行为，不应作为正式源码修复位置，因为安装更新可能覆盖其中的修改。

3. 问题 A：空 justification 导致普通工具调用失败

3.1 用户可见症状

新建 DSH 对话后，普通工具调用失败，返回：

Error: invalid justification: expected a non-empty sentence

该调用没有请求权限升级，也没有意图访问工作区外资源。现场推断工具适配层在序列化可选字符串字段时，将未填写的 justification 传成了空字符串 ""。

3.2 预期行为

普通工具调用不携带权限升级参数时，应当正常执行。例如：

{
  "command": "Get-Location",
  "description": "Show current workspace location"
}

如果适配层因为 schema 或序列化原因传入：

{
  "command": "Get-Location",
  "description": "Show current workspace location",
  "justification": ""
}

在没有 sandbox_permissions 的情况下，空字符串应当被视为“未提供”，而不是被当作一次真实的权限升级理由校验。

3.3 实际行为

官方当前源码中的共享校验函数位于：

E:\CodeFile\DSHsource\packages\sandbox\sandbox\src\escalation.ts

当前实现：

export function validateEscalationArgs(
  sandboxPermissions: string | undefined,
  justification: string | undefined,
): void {
  if (sandboxPermissions !== undefined && justification === undefined) {
    throw new Error('invalid escalation: sandbox_permissions requires a justification')
  }
  if (justification !== undefined && sandboxPermissions === undefined) {
    throw new Error('invalid escalation: justification is only valid together with sandbox_permissions')
  }
  if (justification !== undefined && justification.trim().length === 0) {
    throw new Error('invalid justification: expected a non-empty sentence')
  }
}

当输入为：

validateEscalationArgs(undefined, '')

执行结果为：

invalid justification: expected a non-empty sentence

原因是 justification !== undefined 对空字符串成立，随后 ''.trim().length === 0 也成立。也就是说，当前实现区分了 undefined 与 ""，但工具参数适配层可能无法稳定保持这种区分。

3.4 影响范围

该共享函数被以下工具链调用：

packages/shell/tool-pwsh/src/index.ts:99
packages/shell/tool-bash/src/index.ts:67
packages/fs/tool-fs/src/sandbox.ts:88

因此问题潜在影响：

• pwsh 普通调用；
• bash 普通调用；
• 文件系统 write / edit 等调用在其 sandbox 参数处理路径上的普通调用。

这是一个跨工具共享的参数处理问题，不应只在某一个工具包中添加临时特判。

3.5 当前测试覆盖情况

测试文件：

E:\CodeFile\DSHsource\packages\sandbox\sandbox\tests\escalation.spec.ts

当前已经覆盖：

validateEscalationArgs(undefined, undefined)
validateEscalationArgs('workspace-write', 'because the workspace needs it')
validateEscalationArgs('workspace-write', undefined)
validateEscalationArgs(undefined, 'orphan reason')
validateEscalationArgs('workspace-write', '   ')

但没有覆盖关键输入：

validateEscalationArgs(undefined, '')

因此当前测试不会捕获普通调用因空字符串字段失败的问题。

3.6 建议修复方向

优先建议在工具参数归一化层统一处理：

const sandboxPermissions = args.sandbox_permissions?.trim() || undefined
const justification = args.justification?.trim() || undefined
validateEscalationArgs(sandboxPermissions, justification)

同时，dsh-sandbox 的共享校验入口建议保留防御式兼容，至少使以下输入满足预期：

validateEscalationArgs(undefined, undefined) // 允许
validateEscalationArgs(undefined, '')        // 允许，按未提供处理

如果选择只在校验函数中兼容，也应明确其行为等价于：

if (
  sandboxPermissions === undefined &&
  (justification === undefined || justification.trim() === '')
) {
  return
}

但不建议仅修改某个 Desktop 打包后的 lib/index.js，因为这无法修复源码构建产物以外的部署方式，也无法提供正式回归保护。

3.7 必须保持的安全语义

修复不能把空字符串兼容扩大成无条件允许权限升级。以下规则应保持：

sandbox_permissions	justification	预期结果
未提供	未提供	允许普通调用
未提供	"" 或仅空白	按未提供处理，允许普通调用
未提供	非空	拒绝：理由不能脱离升级目标单独出现
非空	未提供	拒绝：升级目标必须有理由
非空	"" 或仅空白	拒绝：升级理由必须非空
非空	非空	进入原有严格权限阶梯和 approval 流程

5.2 NAS stale-version 验证

1. 完全退出 DSH Desktop；
2. 确认 C:\Users\lucif\.dsh\profiles\desktop\cordis.patch.yml 内容仍正确；
3. 重启现有 Desktop，不启动替代 Web 服务器；
4. 创建新会话；
5. read 一个 Synology Drive 工作区中的已有文本文件；
6. 对同一文件执行精确 edit；
7. 记录是否仍出现 FS_STALE_VERSION；
8. 同时测试工作区外读取/写入；
9. 确认越界访问仍受 sandbox 和 approval 控制；
10. 如要确认源码根因，记录 read 与 edit 前后各 stat token 分量，尤其是 ctimeNs。

6. 建议官方关注的最小修复范围

对问题 A

最小正确修复应包括：

• 统一参数归一化；
• 共享校验函数对“无升级目标 + 空理由”兼容；
• 保持严格升级配对和权限阶梯；
• 增加单元测试；
• 增加至少一条真实工具链回归测试；
• 重新构建并验证 Desktop 运行产物。

对问题 B

建议先区分两个层次：

• 短期：确认 Desktop profile patch 是否按预期生效，并提供明确的风险说明；
• 长期：在 dsh-fs-local / dsh-fs-observation-policy 上游重新定义跨平台 freshness token，配套并发写入和同步文件系统测试。

7. 相关文件索引

本地运行实例

D:\Program Files\DSH\DSH Desktop\resources\app.asar.unpacked\node_modules\@deepseek-ai\dsh-sandbox\lib\index.js

官方源码

E:\CodeFile\DSHsource\packages\sandbox\sandbox\src\escalation.ts
E:\CodeFile\DSHsource\packages\sandbox\sandbox\tests\escalation.spec.ts
E:\CodeFile\DSHsource\packages\shell\tool-pwsh\src\index.ts
E:\CodeFile\DSHsource\packages\shell\tool-bash\src\index.ts
E:\CodeFile\DSHsource\packages\fs\tool-fs\src\sandbox.ts
E:\CodeFile\DSHsource\packages\fs\fs-local\src\fsio.ts
E:\CodeFile\DSHsource\packages\fs\fs-local\src\index.ts

用户 profile

C:\Users\lucif\.dsh\profiles\desktop\cordis.patch.yml
C:\Users\lucif\.dsh\profiles\desktop\cordis.yml

8. 给官方维护者的简短结论

在提交 b150a551b8d465e31e418e1b2eaf5e79bbb7d28e 的官方 master 源码中，validateEscalationArgs(undefined, '') 仍然会抛出 invalid justification: expected a non-empty sentence。这确认了普通工具调用的空字符串兼容 Bug 尚未修复。

同一提交中，Windows 本地文件系统版本 token 仍包含 ctimeNs，并且 write / edit 仍对完整 token 做严格相等比较。因此 Synology Drive 工作区的 stale-version 误报机制仍然存在，建议官方进一步确认同步目录的实际 stat 变化，并重新评估版本 token 设计。

建议官方首先修复问题 A 并添加回归测试，再单独处理问题 B；两个问题共享文件工具使用场景，但不应通过关闭整个 sandbox 或 approval 栈来解决。

[weijiafu14]

问题 A 我在另一份 0.1.1-rc.2 线的源码副本上独立核过一遍，函数体与你贴的一字不差，两个调用点也确实是裸传（packages/fs/tool-fs/src/sandbox.ts:88、packages/shell/tool-bash/src/index.ts:67 都直接把 args.sandbox_permissions / args.justification 交进去），所以你 3.6 把修法放在参数归一化层是对的。

三点补充，第一点是对你报告的更正。

1. validateEscalationArgs(undefined, '') 抛的不是你写的那一条。

把三个判断照原样跑一遍真值表：

sandbox_permissions	justification	实际抛出
undefined	undefined	通过
undefined	''	justification is only valid together with sandbox_permissions
undefined	' '	justification is only valid together with sandbox_permissions
''	undefined	sandbox_permissions requires a justification
''	''	invalid justification: expected a non-empty sentence
''	' '	invalid justification: expected a non-empty sentence

第二条判断在第三条之前就命中了，所以 (undefined, '') 永远走不到"非空句子"那一条。

这对你的定位有影响：你现场看到的是 invalid justification: expected a non-empty sentence，按上表，能产生这句话的输入是 sandbox_permissions 自己也是空串（或者模型真的发了非空的 sandbox_permissions 配一个空 justification）。也就是说丢失 undefined 与 '' 区分的不止 justification 一个字段，两个都丢了。结论对你有利——修法不变，但"只归一化 justification"不够，必须两个字段一起，而这正好是你 3.6 写的形状。

2. 测试盲区比你写的还大，而且是"行覆盖率骗人"的标准形态。

escalation.spec.ts 覆盖了 ('workspace-write', ' ')，没覆盖任何空串。关键在于：' ' 和 '' 走的是同一行 justification.trim().length === 0。所以那一行的覆盖率是 100%，而四个空串组合一个都没进过测试——覆盖率门禁量的是行，不是输入空间。

同一天 #4676 报的 redactSecrets 是一模一样的形状：default 分支被普通叶子类型（z.string()、z.number()）跑满，于是"分支跑过了"，而危险场景（secret 藏在 union/tuple/lazy 下面）从未被测过。两处不是巧合，是同一类门禁盲区，建议一起考虑。

3. 一条硬边界，给任何想"先用插件绕过去"的人（也说明 A 只能上游修）。

外部插件改不了 DSH 原生工具已经发出的 arguments。我们自己的兼容层里这条是写死并显式拒绝的：Pi 侧的 tool_call 钩子若改写了原生工具的 event.input，我们直接返回 deny，理由原话是 "DSH logs arguments before policy, so this mutation cannot be honored" —— 核心在策略执行之前就把 arguments 记进日志了，这是有意为之。所以"在插件层把空 justification 归一化掉"这条路不存在。

反方向倒是成立：system-prompt/assemble 是 awaited waterfall，改写已注册工具的 schema 可行（我实测改过一个已注册工具的 description、删过 parameters.properties 里的字段，两处改动都出现在 assemble 的返回值里）。但那只决定模型看到什么，而这个 bug 出在 undefined 与 '' 的区分在参数适配层丢失，不是模型填错了字段。所以 A 确实只能在你指的那两个调用点修，用户侧没有等价替代路径。

问题 B 我给不了实证，只能指个方向：mtime/ctime 类 freshness token 撞上会改元数据的同步守护进程（Synology Drive、OneDrive、以及 ReparsePoint 这一层），属于"写入时宽松、读取时严格"的一族——写的时候没记下 token 是怎么算出来的，读的时候却拿一个更严格的等式去比。你 5.2 里记 ctimeNs 分量的做法是对的，那个差值应该能直接把责任定到守护进程还是 token 定义上。

利益相关：我维护一个第三方 DSH 插件（Pi 生态兼容层）。上面第 3 点是我们自己代码里的实测结论，其余是对官方源码的核证——这两个 bug 都在 DSH 自家组件里，我们修不了，也不该修。