run_code 的 code 参数按 JS 转义处理，写正则/路径/heredoc 经常报错，建议描述里加个提示

[Jokerautowrite]

最近用 run_code 写东西经常踩一个坑，来反馈一下。

run_code 的 code 参数是当成 JS/TS 源码字符串处理的：JSON 传过去之后，worker 那边用 new AsyncFunction("'use strict';\n" + code) 来编译（在 @deepseek-ai/dsh-code-runtime-worker-thread/lib/worker.cjs 里）。所以 code 里写的字符串字面量/模板字符串，全都按 JS 的转义规则来，这就坑了——只要在代码里嵌了带反斜杠或 ${} 的外部内容（正则、路径、heredoc、Python/Shell 片段），很容易炸。

具体症状我碰到过好几种：

• 字符串里写 \s、\d 这种，严格模式下直接报 SyntaxError: Invalid escape sequence / Expected unicode escape；
• 模板字符串里写 \n、\t，被悄悄变成真正的换行/制表符，嵌入的源码就坏了；
• \\ 变成单个 \，内容被吞一半；
• 内容里有个反引号，模板字符串提前闭合，报的错完全看不懂；
• bash 命令里写 ${PORT}，被 JS 先插值了，根本没到 shell。

最难受的是报错特别隐晦（比如 Expected unicode escape），模型拿到这个错误根本想不到是转义问题，只能反复试。我试了 String.raw、用 String.fromCharCode(92) 拼反斜杠、先写个引导脚本再执行……最后才搞明白是这么回事。

建议：run_code 的 code 参数描述里（TYPESCRIPT_FLAVOR / PYTHON_FLAVOR 的 codeDescription）加一句提示，告诉使用者 code 是按源码编译的、字符串里的转义是宿主语言的规则（\s/\d 严格模式下非法、\n 会变换行、${} 会插值），写带反斜杠的内容尽量用 tools.write。另外 worker 编译报错时如果能顺带提示一句"可能是字符串转义问题"就更好了，不然真的一头雾水。

用的版本：@deepseek-ai/dsh v0.1.0-rc.8，Ubuntu 24.04。

如果觉得这个建议 OK，我可以帮忙提个 PR 改描述。

[lws2004]

补充一条实测修正:这类报错其实来自类型剥离层,不是 worker 编译层。

定位

在 packages/ptc-runtime/ptc-runtime-node/src/index.ts 中,stripTypeScriptTypes 失败走的是外层 catch,
靠 parsing 标志把 kind 判为 exception(约 350 行)。也就是说,带反引号或转义引号的程序根本没机会走到 worker 的 AsyncFunction 编译。
报错文本本身也印证了这一点:

• 剥离层(V8 的 TS 剥离)报的是:Expression expected、Expected ',', got '}'
• worker 的 AsyncFunction 编译会报的是:SyntaxError: Unexpected token ...

所以只在 worker 侧加提示收不到效果 —— 提示要打在剥离失败的出口。

本机实测

在 parsing 分支的失败消息后追加一句提示后,同一段程序的报错从

Expression expected

变成

Expression expected [hint] The code string is compiled as source, so escape sequences are
processed twice (JSON transport + source): a backtick closes a template literal early, an
escaped quote ends a string early, and a backslash-n inside a string literal becomes a real
newline. For content containing backslashes, regexes, heredocs or script fragments, write it
to a file with the write tool and read it back instead of inlining it.

模型看到这句会立刻转向检查转义,而不是反复改逻辑。

建议的两处改动

1. packages/core/tools/src/ptc.ts 的 TYPESCRIPT_FLAVOR.codeDescription:加一句「code 按源码编译,转义会被处理两次」,让模型在写之前就规避。
2. packages/ptc-runtime/ptc-runtime-node/src/index.ts 的失败出口:parsing === true(即剥离阶段失败)时给 message 追加同一句提示。

另:C 侧同样受益于第 1 条 —— 描述是模型唯一能在犯错前看到的提示位。

CONTRIBUTING 说明当前暂不接受外部 PR,故把实测结论与建议放在这里,供维护者取舍。