[Bug] read 工具按 UTF-16 码元截断会切开代理对，产生非法 JSON 并使会话永久 400

[TommeyChang]

Summary

@deepseek-ai/dsh-tool-fs 的 read 工具在截断超长行时按 UTF-16 码元 下标切割。当第 2000 个码元落在一个代理对（astral 平面字符：emoji、CJK 扩展 B 等）中间时，结果以孤立的高代理项结尾。这段文本被持久化进会话日志后，JSON.stringify 会把它写成 \ud83d —— 语法合法、语义非法的 JSON。

此后该会话每一次请求都会被 DeepSeek Messages 端点整体拒绝（HTTP 400）。因为脏数据永远留在历史里，会话不可恢复：后续每个 turn 都失败，UI 上没有任何出路。我这边一台机器上有 4 个会话 / 5 个会话文件被污染。

复现版本：@deepseek-ai/dsh 0.2.0-rc.2 / dsh-tool-fs 同版本；Linux Ubuntu 24.04、Node v22.23.2。已由 PerryLink 核对：HEAD（0.2.1-alpha.1）上 READ_MAX_LINE_LENGTH = 2000 仍在（packages/fs/tool-fs/src/read-render.ts:11）⇒ 当前存活项。

Reproduction

1. 用 read 工具读取一个含超长行的文件，且该行第 2000 个 UTF-16 码元正好切在一个 astral 字符中间。

   触发点（@deepseek-ai/dsh-tool-fs/lib/index.js）：

   const READ_MAX_LINE_LENGTH = 2e3;
   
   function truncateLine(line, maxLineLength) {
       return line.length > maxLineLength
           ? `${line.substring(0, maxLineLength)}... (line truncated to ${maxLineLength} chars)`
           : line;
   }

   String.prototype.substring 按 UTF-16 码元索引，不感知代理对。

2. 工具结果写入会话日志，其中包含孤立的 \ud83d 转义。

3. 之后该会话的任意一次模型请求都返回 400。

Current behavior

请求体被整体拒绝：

HTTP 400
Failed to parse the request body as JSON: messages[0].content: invalid unicode code point

两个加重问题的细节：

① 该 400 的响应体不是标准错误信封（不是 {"error":{"message":...}}），所以 dsh-llm-deepseek 的 providerError() 取不到 error.message，最终只显示兜底文案：

DeepSeek Messages request failed (400)

真实原因（invalid unicode code point）对用户完全不可见，极难自行定位。

② 脏数据持久化后会被一直重发，所以会话永久卡死 —— 每个 turn 都是同一个 400。

用最小请求可以稳定复现：

curl -X POST https://api.deepseek.com/anthropic/v1/messages \
  -H "x-api-key: $KEY" -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  --data-binary '{"model":"deepseek-flash","max_tokens":32,"messages":[{"role":"user","content":"cut emoji: \ud83d"}]}'
# -> HTTP 400  Failed to parse the request body as JSON: ... invalid unicode code point

对照实验：把同一段会话历史里的孤立代理项替换成 U+FFFD 后，整段历史重放返回 HTTP 200。也就是说会话数据本身没问题，卡点纯粹是这个字符。

机制补充："非法"到底在哪一层（PerryLink 实测，2026-10-05）

这一节修正了一个容易走错的直觉：问题不在编码层。

const line = 'a'.repeat(1999) + '\u{1F600}'   // 码元数 2001
const t = line.substring(0, 2000)
t.charCodeAt(t.length - 1) === 0xD83D          // ✅ 末位是孤立高代理项

JSON.stringify({ content: t }).slice(-14)
// -> '…aaaa\ud83d"}'   即 6 个 ASCII 字符，不是原始字节
Buffer.from(body, 'utf8')                       // 无 ED A0 BD（不存在 CESU-8 形态）
new TextDecoder('utf-8', { fatal: true })       // ✅ 通过
JSON.parse(body)                                // ✅ 本地通过

即：孤立代理项被 JSON.stringify 写成 6 个 ASCII 字符 \ud83d；字节流是合法 UTF-8；严格解码通过、JSON.parse 也通过。服务端成功解析 JSON 后，该转义解码为一个不属于任何 Unicode 标量值的孤立代理项，内容校验因而拒绝整个请求 ⇒ 400。

这条结论直接改变修法优先级：任何"这一行能不能 JSON.parse"的检查都是无效的（脏行是合法 JSON）。定位只能在解析后按码元扫，或直接在原始文本里找转义序列。

临时处置：已污染会话的恢复配方

来自同族先例 #8352（xiaoyuyu6420 提供），经 PerryLink 复核并补充三条前提：

1. 先整份复制文件再改——这是用户资产，且修复过程本身要写回；
2. 逐行 JSON.parse 后按 code unit 扫孤立代理，定位坏行；
3. 替换为 U+FFFD 或删除该字符；
4. 只重编所在帧、不重编号（⚠ 最关键：重编号会让引用错位）；
5. 全文件复扫后放回。

效率提示：坏值在文件里是可见的 ASCII 文本（\ud83d 这 6 个字符），所以可以先用正则粗筛 \ud[89abAB]… 而后面没有配对的 \ud[c-fC-F]…，再逐行确认——比全量解析快得多。本次 4 个被污染的会话正是这么定位并修复的。

Expected behavior

建议按下列三级收紧（第一级根治，第二级覆盖面最大）：

第一级 · 不再制造孤立代理项（根治）：截断按码点而非码元。

const truncated = [...line].slice(0, READ_MAX_LINE_LENGTH).join('')

按码元切是语言保证会切坏的（JS 字符串下标＝码元）；改成码点感知可从源头消除本工具的制造源。

第二级 · 持久化/发送边界兜底（成本最低、覆盖最广）：

const safe = text.toWellFormed()   // ES2024 / Node 20+ 内置：孤立代理项 -> U+FFFD

放在"写会话日志"与"序列化请求体"这两条边界上。理由是孤立代理项的来源不止截断一处（用户脚本按码元 slice、第三方工具输出、外部导入、粘贴都可能），边界兜底一次性覆盖；只改 read 的截断只堵一个口。这一层是本报告最希望被采纳的一项。

第三级 · 让已污染会话可救：脏数据留在历史里就永远 400。要么在读取时清洗，要么提供一个显式修复入口（例如"清理本会话中的非法字符"）。原报告写"没有任何出路"——这一级就是给出出路。

此外建议读取/发送路径遇到非法标量时能指出是哪一条，否则下次仍只能靠"逐行扫"来定位（见上面配方）。

Environment

• @deepseek-ai/dsh 0.2.0-rc.2（dsh-tool-fs 同版本）
• Linux（Ubuntu 24.04）、Node v22.23.2
• provider deepseek-official，Messages 协议，model deepseek-flash
• 触发文件的行内含 emoji；受影响会话 4 个 / 文件 5 个（含 v3 与 v4）

[PerryLink]

你这条可复现性强、机制清楚——而且最该修的位置不在截断，而在持久化边界

1. 常量我核到了

packages/fs/tool-fs/src/read-render.ts：

export const READ_MAX_LINE_LENGTH = 2000      // :11
export const READ_MAX_BYTES = 50 * 1024       // :14

⇒ 你说的"按 2000 个 UTF-16 码元"这个量级就是这里的 READ_MAX_LINE_LENGTH。

2. 机制为什么必然成立（语言层面，无需复现即可确认一半）

JavaScript 的字符串下标是码元（UTF-16 code unit），因此任何 slice/substring 在第 2000 个码元处切割，只要那里正好是代理对的中点，结果就以孤立高代理项结尾——这是语言保证的行为，不是某个实现的怪癖。⇒ "能切出孤立代理项"这一半是确定的。

3. ⚠️ 但真正致命的是后半段，所以修法应当前移

你的因果链是：孤立代理项 → 落进会话日志 → JSON.stringify 写成 \ud83d（语法合法、语义非法）→ Messages 端点每一轮都 400 → 会话不可恢复（你已有 4 会话 / 5 文件被污染）。

⇒ "不可恢复"才是这条的分量。而它意味着修法不该只改截断：

1. 首选：在持久化/编码边界做一次代理对清理（丢弃或替换孤立代理项）。理由——孤立代理项的来源不止这一处（粘贴、外部日志导入、其它工具的写入都可能产生）；在边界清理等于一次性堵住一类，而只改 read 的截断只堵住一个来源；
2. 同时把截断改成按码点（[...line]、或 Array.from、或 Intl.Segmenter 之类的码点/字素感知切法），避免制造新的孤立代理项；
3. 可选但值得：既然脏数据会让会话砖化，端点在收到非法 JSON 时应当在客户端侧先被拦住并提示"历史中存在非法字符"，而不是让它变成永久 400。

建议把第 1 条写成主诉求（它同时覆盖"已污染的会话能否救回"这个问题）——你写"没有出路"，而"边界清理 + 一次修数据"正好给出出路。

4. 请补两样（让可复现性变成别人也能跑）

1. 那个"第 2000 个码元正好切在 astral 字符中间"的最小文件（或一段能生成它的脚本）——你已给了触发条件，把生成脚本附上，任何人 30 秒可复现；
2. 400 的响应体原文——它能把"端点拒绝非法 JSON"这一环钉死（目前是推断，虽然非常合理）。

5. 版本口径

你未写版本。⚠️ 当前最新是 0.2.1-alpha.1（latest/next = 0.2.0-rc.2）⇒ 请补上你复现的版本；0.1.7-rc.2 → 0.2.1-alpha.1 有 714 个提交，packages/fs 也在其中。

一条边界

我确认的是两个常量的存在与**"按码元切割可以产生孤立代理项"这一语言层事实**。**"端点因此整体 400 且会话不可恢复"**以你的实测为准——我没有可测的端点。

[TommeyChang]

补两样（PerryLink 要的）。

1. 最小复现（自包含，不需要 DSH）

# 第 2000 个 UTF-16 码元正好切开一个代理对
line = "a" * 1999 + "\U0001F600"        # 😀 = U+1F600 = \ud83d\ude00
truncated = line[:2000]                 # 与 read-render.ts 的 line.substring(0, 2e3) 等价
assert truncated[-1] == "\ud83d"        # 语言层保证：以孤立高代理项结尾

import json
body = json.dumps({"messages": [{"role": "user", "content": truncated}]})
print(body[-20:])                       # 以 \ud83d 结尾 —— 语法合法、语义非法
body.encode("utf-8")                    # UnicodeEncodeError: surrogates not allowed

把探针字符放在下标 1999 就必现，不需要碰运气：任何 "a" * 1999 + <astral 字符> 都会在第 2000 个码元处被切开。不只是 emoji——CJK 扩展 B 区汉字（如 U+20000）同样触发，任何 astral 平面字符都行。

2. 400 响应原文

HTTP 400
Failed to parse the request body as JSON: messages[0].content: invalid unicode code point

两端各验过一次，互为对照：

请求体	结果
原始历史（含孤立 \ud83d 转义）	连 UTF-8 都编不出来（UnicodeEncodeError: surrogates not allowed），请求根本发不出去
把孤立代理项转义替换为 \ufffd（6 字符换 6 字符）后重放同一历史	HTTP 200

第二行同时说明：这个 400 完全由这一个字符决定。定位过程中我逐一排除过 max_tokens、请求体大小、模型目录、空 system 消息，全部无关。

3. 版本基线

@deepseek-ai/dsh 0.2.0-rc.2（dsh-tool-fs 同版本），升级自 0.1.5-rc.1。Linux Ubuntu 24.04 / Node v22.23.2。

4. 影响面与现状

同一台机器上 4 个会话 / 5 个会话文件被污染，每个都每轮 400、无法自行恢复。处置方式是把孤立代理项转义替换为 \ufffd（字节长度不变、JSON 结构不动）后重启服务；之后重放同一历史得到 200。现已加了一个每 10 分钟扫描会话目录的检测器，命中即告警。

5. 关于你提的修法前移

同意"真正该修的是持久化边界"这一判断，而且理由比我原报告的更充分：孤立代理项的来源不止 read 截断一处。我这边的检测器就是按"边界清理"写的——它不关心脏数据从哪来，只在落盘数据上扫描 \udXXX 转义里是否配不成对。补上码点感知的截断（[...line] / Array.from / Intl.Segmenter）可以堵住已知来源，两者不冲突。

[PerryLink]

你的复现我跑过了——并补上了机制里最关键的一环（我原先的猜测是错的）

1. 我本机模拟的结果（逐条）

const line = 'a'.repeat(1999) + '\u{1F600}'      // 码元数 2001
const t = line.substring(0, 2000)
t.charCodeAt(t.length - 1) === 0xD83D            // ✅ 末位是孤立高代理项

⇒ 你"把探针放在下标 1999 就必现"这一句成立，我这边一次即中。

2. ⚠️ 关键一环：JSON.stringify 转义了它（不是原样输出）

我原以为问题出在"UTF-8 编码层"，实测否掉了这个猜测：

JSON.stringify({ content: t }) 的末 12 字节
  = 61 61 61 61 5c 75 64 38 33 64 22 7d      // 也就是 ASCII 的  aaaa\ud83d"}
Buffer.from(body, 'utf8') 里 没有 ED A0 BD   // 不存在 CESU-8 形态
new TextDecoder('utf-8', { fatal: true })    // 严格解码：通过
JSON.parse(body)                             // 本地：通过

⇒ 所以真正的情况是：

1. 孤立代理项被 JSON.stringify 写成 6 个 ASCII 字符 \ud83d；
2. JSON 语法合法、字节流也是合法 UTF-8；
3. 服务端成功解析 JSON，但 \ud83d 解码后是一个不属于任何 Unicode 标量值的孤立代理项 ⇒ 其内容校验拒绝整个请求 ⇒ 400。

这正好印证你标题里那句"语法合法、语义非法"，而且把"非法"的层次钉在了 Unicode 标量值这一层（不是语法、不是编码）。建议把这一点写进报告——它会改变修法的优先级（见下）。

3. ⇒ 解决方案（两级，第一级是根治）

第一级·不再产生孤立代理项：截断按码点而非码元。
按码元切是语言保证会切坏的（JS 字符串下标＝码元）；改成码点感知即可从源头消除：

// 以码点为单位截断（等价于把 2000 码元的上限换成 2000 码点）
const truncated = [...line].slice(0, READ_MAX_LINE_LENGTH).join('')

第二级·持久化边界兜底（成本最低、覆盖最广）：

const safe = text.toWellFormed()   // ES2024：把孤立代理项替换为 U+FFFD

toWellFormed() 是标准方法，Node 20+ 已内置 ⇒ 一行即可。建议把它放在"写日志/发请求"这条边界上，理由我上一轮已说过、现在有了实证支持：孤立代理项的来源不止截断这一处（粘贴、外部导入、其它工具写入都可能），边界兜底一次性覆盖。

第三级·让已污染的会话可救：既然脏数据留在历史里就永远 400，要么在读取时清洗（代价是"改了用户的记录"），要么提供一次显式修复（例如"清理本会话中的非法字符"入口）。你写"没有任何出路"——这一级就是给出出路。

4. 你给的 400 原文的价值

你补的 HTTP 400 Failed to parse the request body as JSON: messages[0].content: i… 让链条闭合（截断 → 落盘 → 每次请求被拒）。建议把它放在正文最前面，因为它证明了"不是偶发、而是必然失败"。

5. 版本

你未写版本，但这不影响：我核到的当前最新 HEAD（0.2.1-alpha.1）里 READ_MAX_LINE_LENGTH = 2000 仍在（read-render.ts:11）⇒ 这条是当前存活项。

一条边界

我确认的是截断机制（模拟复现）、转义行为、JSON 合法性与严格 UTF-8 解码通过这三件事。服务端拒绝的具体校验规则以你的 400 原文为准——我看不到那侧的代码。

[xiaoyuyu6420]

机制侧你们已经挖得很全了。给作者补一句最急的：你那 4 个被污染的会话能救回来——这和 #8352 是完全同族的形态（孤立代理持久化进 tool/result），那帖里有完整的行级恢复配方：逐行 JSON.parse 后按 code unit 扫孤立代理定位坏行 → 替换成 U+FFFD 或删除 → 只重编所在帧、不重编号 → 全文件复扫后放回。你连触发条件都定位到了（第 2000 个码元切在代理对中间），恢复时会更快——直接优先扫 read 工具产出的超长行就行。

上游修复的落点参考：#8352 文末建议的「tool/result 入库前清洗配对代理」和你这里说的「改 read 截断逻辑」是两层防线——清洗层能顺带兜住其他来源（用户脚本按码元 slice、第三方工具输出），单改 read 的截断只堵一个口。两层都做最稳。

[PerryLink]

你给的恢复配方是对的——而我能补一句"为什么必须这样做"的实证

1. 我用模拟验证过：语法检查抓不到它

我本机跑过这条链（HEAD 的常量是 READ_MAX_LINE_LENGTH = 2000）：

const t = ('a'.repeat(1999) + '\u{1F600}').substring(0, 2000)
t.charCodeAt(1999) === 0xD83D          // ✅ 末位是孤立高代理项
JSON.stringify({content: t}).slice(-14) // → '…aaaa\\ud83d"}'  （ASCII 转义！）
JSON.parse(body)                        // ✅ 成功
new TextDecoder('utf-8',{fatal:true})   // ✅ 通过

⇒ 两个直接后果，正好解释了你那套配方为什么必须那样写：

1. JSON.parse 会成功 ⇒ "这一行能不能解析"这个检查完全无效——脏行是合法 JSON。所以定位必须在解析之后按码元扫（如你说的），或者直接在原始文本里找转义序列；
2. 它是可见的 ASCII 文本：坏值在文件里长成 \ud83d 这 6 个字符 ⇒ 可以先用正则粗筛（找 \ud[89ab]… 而后面没有配对的 \ud[c-f]…），再逐行确认。⇒ 比全量解析快得多，对 4 个被污染的会话尤其划算。

2. 你引的 #8352 那套"行级恢复"我支持，并建议加一条安全前提

你给的步骤（逐行 JSON.parse → 按 code unit 扫孤立代理定位坏行 → 换 U+FFFD 或删除 → 只重编所在帧、不重编号 → 全文件复扫后放回）——"不重编号"这一点是最关键的一步，请务必保留在配方里（重编号会让引用错位）。

建议加一条：先复制整份文件再改（你已隐含，但请写明）——因为这份数据是用户资产，且修复过程本身要写回。

3. 关于"两层防线"，我同意，并补充分工

你写：tool/result 入库前清洗 + 改 read 截断 = 两层。⇒ 我认同，并建议把两层的职责写清：

• 清洗层（边界）：覆盖所有来源（用户脚本按码元 slice、第三方工具输出、粘贴等）⇒ 成本最低、覆盖面最大，应作为必须的一项；
• 截断层（源头）：把按码元切改成按码点切 ⇒ 消除本工具的制造源；
• （可加第三层）可诊断：既然脏数据会让会话永久 400，读取/发送路径遇到非法标量值时应能指出是哪一条，否则下次仍要靠"逐行扫"。

4. 一点方法论上的肯定

你这条没有重复报告人已经给出的机制，而是直接给可执行的恢复路径 + 同族先例（#8352）。⇒ 这正是"报告已经挖得很全"之后最有用的补充形态。建议报告人把它并入正文的"临时处置"一节，让后来者不必再翻评论区。

一条边界

我确认的是截断机制、JSON.stringify 的转义行为、JSON.parse 与严格 UTF-8 解码均通过这三点（本机模拟）。你那套行级恢复的具体命令以你与 #8352 的实测为准——我没有在被污染的会话文件上跑过。