工具层进化建议：pwsh 多行命令 / 无参工具 / write 转义 / 中文 GBK 编码 4 项缺陷

[lhbsaa]

工具层进化建议：4 个 PowerShell/中文环境相关缺陷（实测复现）

来源：在 Windows + 中文 locale + ESP-IDF 5.5.2 环境下的 esp-claw / T-Display-S3 AMOLED 适配实战（2026-08）。
全部为可复现的工具调用缺陷或改进点，与具体项目无关，对任何 Windows PowerShell 会话普适。

---

1. pwsh 工具 command 参数不支持多行（最高频）

• 现象：command 传多行字符串时抛 JS 解析错误 Expected ';', '}' or <eof>，无定位信息。
• 最小复现：

await tools.pwsh({
  command: 'Get-Content "a.txt"
Write-Host "x"'   // 多行单引号字符串 → 解析崩溃
})

• 根因：工具签名把整个 shell 脚本当单一字符串，模型被迫拼单行（; 分隔）。
• 建议：command 允许传字符串数组（每行一个元素），运行时 join('\n')；或增加 script_path 支持。
• 影响：一次会话中 >10 次失败源于此。

2. 无参工具必须显式传 {} 才不报错

• 现象：tools.job_list() 报 binding arguments must be lossless JSON（应为 "no arguments"）。
• 最小复现：await tools.job_list() 报错；await tools.job_list({}) 正常。
• 建议：无参工具允许省略参数；或改进报错文案为 "this tool accepts no arguments, pass {}"。

3. write 工具写脚本时反斜杠/美元符被剥离

• 现象：write 生成 .ps1，内容中 D:\Espressif 变 D:Espressif、$env:X 被吞，执行报
  Import-Module : A positional parameter cannot be found。
• 最小复现：

await tools.write({ file_path: "t.ps1",
  content: 'Import-Module D:\Espressif\x.ps1' })
// 写入后内容变成 Import-Module D:Espressifx.ps1

• 建议：write 内容按字面量写入（raw 语义），或文档明确转义规则。

4. 中文 Windows 下 python 工具链 GBK 编码崩溃

• 现象：打印 emoji/中文的 python 工具（esp_board_manager 生成器等）报
  UnicodeEncodeError: 'gbk' codec can't encode character ...。
• 最小复现：中文 locale 控制台运行 python -c "print(chr(0x1f4cb))"。
• 建议：pwsh 工具执行前默认设 $env:PYTHONIOENCODING="utf-8"，或
  [Console]::OutputEncoding=[Text.UTF8Encoding]::new()。

---

附：非 DSH 问题（无需处理）

• idf.py bmgr -c 不存在 → esp-bmgr-assist 占位符与 ESP-IDF 5.5 兼容（扩展自动加载需 IDF v6），属上游工具链。
• set-target 输出被 Out-Null 吞导致目标仍是 esp32 → 模型脚本写法，靠预设规则约束。
• 硬件 API 差异（sub_type=spi、panel_io、flush_ready）→ 板卡适配本身。

[lhbsaa]

实现进展（代码已就绪）

感谢官方把 issues/PR 渠道收紧为 Discussions。作为回应，我已把这 4 项中的 3 项可改项完整实现为代码，并推送到 fork，供团队审查或 cherry-pick：

Fork 分支：lhbsaa/deepseek-harness @ fix/shell-tool-args-and-encoding（提交 3be686d）

已实现（3/4）

1. bash/pwsh 工具 command 支持数组（packages/shell/tool-bash + tool-pwsh）

   • command: string | string[]，数组按行 join 成多行脚本
   • schema 用 oneOf: [string, array-of-string]，validate/presentCall 统一 normalize
   • 消除"多行命令需内嵌转义"这一最高频失败源

2. 无参工具报错区分 undefined（packages/code-runtime/code-runtime-worker-thread）

   • tools.x()（args === undefined）现在提示"accepts no arguments"+ 显式 ({}) 提示
   • 其他非 JSON 值（函数/Date/循环引用）保留原 lossless-JSON 错误，安全边界不变

3. pwsh-local 固定 PYTHONIOENCODING=utf-8（packages/shell/pwsh-local）

   • 中文 Windows 下 python 子进程不再因 GBK 崩溃（UnicodeEncodeError）
   • 子进程收集器按 UTF-8 解码，与既有 ENCODING_PREAMBLE 互补

未改代码（1/4，经核实非工具缺陷）

4. write 工具"剥离反斜杠" — 排查确认 content 参数在 JSON 边界原样透传（tool-fs/src/write.ts 无任何字符处理），根因是模型侧 JS 模板字符串转义，已在嵌入式模式预设的工具规则中缓解，无需改上游。

验证

• pnpm run typecheck ✅
• pnpm run lint ✅
• 受影响包单测：bootstrap.spec.ts（28）、tool-bash、tool-pwsh、pwsh-local executor（98 通过 / 1 平台跳过）✅

PR 创建因上游策略被拒（pulls API 404 + push 权限 false，与 CONTRIBUTING 声明一致），故改动保留在 fork。若团队开放 PR 或需要 cherry-pick，随时可取。

[lhbsaa]

更新：根据社区反馈改进 + 本地已生效

思路 2 落实：oneOf → 独立参数名（感谢 #2376 的提醒）

阅读 #2376 后发现，部分 LLM provider（如 PI-AI）会把 oneOf 参数序列化成 JSON 字符串导致验证永久失败。
因此把改动 1 从 oneOf: [string, array] 改为普通对象 schema：

• command: string（主参数，保持原样）
• command_lines: string[]（新增可选：多行脚本，非空时优先于 command）

无 union 参数，任何 provider 都不需要做 JSON 字符串往返。bash/pwsh 对称更新，
测试覆盖脚本形式、空数组回退、schema 形状。

Fork 分支更新：lhbsaa/deepseek-harness @ fix/shell-tool-args-and-encoding（提交 2d725d8）
验证：typecheck ✅ / lint ✅ / tool-bash + tool-pwsh 单测 62 通过 ✅

思路 1 落实：本地立即生效（绕过 PR 限制）

调研发现本地 npm 安装的 rc.6 与仓库 master 的 tool-bash/tool-pwsh/pwsh-local/
code-runtime-worker-thread 字节级一致（仅版本号不同），因此把 fork 分支的构建产物
覆盖到本地 node_modules 是安全无回退的。已应用并验证 4 个补丁：

• dsh-tool-bash：command_lines ✅
• dsh-tool-pwsh：command_lines ✅
• dsh-pwsh-local：PYTHONIOENCODING=utf-8 ✅
• dsh-code-runtime-worker-thread：无参调用友好提示 ✅

备份在 ~/.dsh/patched-lib-backup-20260816，可一键还原；重跑脚本：
powershell -File tools/apply_dsh_patch.ps1（已存入本机工具集）。

OS 适配结论

按"平台感知而非平台分叉"处理：改动 2/3 在共享层（code-runtime / 模型侧）一次修改三端受益；
改动 1 在 bash（mac/Linux）+ pwsh（Windows）对称实现；改动 4 是 Windows 特有痛点但修复放共享的
ENV_OVERRIDES，mac/Linux 下 python 忽略该变量零副作用。平台分流交给已有的 !!js process.platform 机制。

重启 dsh 会话后上述改动即在本机生效。

[weijiafu14]

这份跟进的质量很高——尤其是读了 #2376 之后主动把 oneOf 改成独立参数名（因为部分 provider 会把 union 参数序列化成 JSON 字符串导致验证永久失败），以及第 4 项自查后判定不是工具缺陷、如实撤回。这两件在社区里都很少见。

我只补一件很具体的、关于你那套本地补丁的运维风险，因为这个坑我们踩过而且很难发现。

覆盖 node_modules 的补丁会被静默还原

你的做法是把 fork 的构建产物覆盖到本地 node_modules，并备份在 ~/.dsh/patched-lib-backup-20260816、留了一键还原脚本。备份解决了"改坏了怎么退"，但没解决另一个方向的问题：补丁在你不知情的时候消失。

会触发还原的动作比想象中多：

• dsh plugin add <任何东西>（它内部会跑 pnpm，按 lockfile 重建 node_modules）；
• 任何一次 profile 的重装或修复；
• 升级 DSH 本身。

pnpm 是从 store 硬链接/复制出 node_modules 的，store 里那份始终是官方版本。所以上述任何一次操作之后，你的四个包会悄悄变回原样——没有报错，没有提示。

表现会非常迷惑人：多行命令突然又开始报 Expected ';', '}' or <eof>、中文 Windows 下 python 又开始 GBK 崩溃。而你此时多半正在排查别的东西，第一反应不会是"我的补丁没了"。

我们自己在回归装置里为同一类问题吃过亏：本地以 file: 方式装进 profile 的包其实是一份拷贝，pnpm 对它有缓存、update 不会重新拷贝，于是我改了源码、构建完、跑测试，测的还是旧的那份。查了很久才反应过来。从那以后我们的规矩是：装完必须回读装到的那份、和期望的比对，不一致就 fail。

建议：给 apply_dsh_patch.ps1 加一步"验证"

现在它是"应用"，建议再加一个只读的"检查"模式：读一下那四个包里的特征字符串（比如 command_lines、PYTHONIOENCODING），不在就明确报出来。

# 伪代码：能跑就行，重点是它必须能 fail loud
$probe = @{
  'dsh-tool-bash'  = 'command_lines'
  'dsh-tool-pwsh'  = 'command_lines'
  'dsh-pwsh-local' = 'PYTHONIOENCODING'
}
# 逐个读 lib 里的文件，缺了就 Write-Error 并给出重新应用的命令

然后把这一步放进你日常的入口（会话启动脚本、或者每次 dsh plugin add 之后手动跑一次）。成本几乎为零，换来的是"补丁没了"这件事变成一句显式报错，而不是一串莫名其妙的回归。

顺带一个小提醒：判断打包后的 .mjs 里有没有某个字符串时，别用 grep——BSD 系的 grep 对打包产物那种超长单行会静默失败（返回空而不是报错），我们为此误判过。用 node -e 读文件再 includes() 最稳。你在 Windows/PowerShell 上用 Select-String 大概率没这个问题，但如果你的脚本要跨到 mac/Linux 用，这一条值得记一下。

关于第 4 项你撤回的那条

你查完确认 content 在 JSON 边界原样透传、根因在模型侧的 JS 模板字符串转义——这个结论我认为是对的，而且它其实指向一个比工具 bug 更普遍的东西：模型在生成 'D:\Espressif\x.ps1' 这种字面量时，反斜杠会不会活下来，取决于它写的是哪种引号、以及中间经过了几层字符串。你用工具规则预设去缓解是务实的做法。

如果想让它更稳，另一个思路是让路径根本不经过字符串字面量（比如让模型用数组拼路径、或者用正斜杠——PowerShell 接受 / 作路径分隔符）。这不属于你这四条的范畴，只是既然撤回了这一条，留个替代方向给后面读到的人。

边界与利益相关

我们不修 DSH 自家组件——tool-bash / tool-pwsh / pwsh-local / code-runtime-worker-thread 全在 DSH 里。上面全是运维建议，不是我能替你落地的东西。上面关于 pnpm 还原行为的部分是按 pnpm 的通用行为和我们自己踩过的同类坑推的，我没有在你这套 Windows 环境上实测——但验证脚本那一步不管我说得对不对都值得加，因为它的成本接近零。

利益相关：我维护 pi2dsh（Pi 生态兼容层）。这条不推销——你在改 DSH 自家的 shell 工具，装什么第三方插件都替代不了那四个补丁。