gstack AskUserQuestion 中文/CJK 规则工具调用里为何必须写字面 UTF-8 而禁止 \uXXXX 转义【免费下载链接】gstackUse Garry Tans exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack本文基于 gstack 仓库的 docs/askuserquestion-cjk.md讲解该仓库为 LLM 的 AskUserQuestion 工具调用制定的非 ASCII中文繁简、日、韩书写规则任何字符串字段必须直接输出字面 UTF-8 字符严禁手工\uXXXX转义。结合仓库中生成器源码、技能文档注入链与回归测试你会掌握这条规则的完整依据、它在 gstack 中从“内联手册”演化为“按需文档”的工程过程以及在实战中避免 CJK 乱码如管理工具渲染成㄃3用箱的具体做法。核心规则CJK 字符直写禁止 \u 转义docs/askuserquestion-cjk.md 开篇即给出操作定义当 AskUserQuestion 的任何字符串字段——问题question、选项标签option label、选项描述option description——包含中文繁體/簡體、日文、韩文或其他非 ASCII 文本时必须在 JSON 字符串中输出字面 UTF-8 字符绝不写成\uXXXX转义。规则的唯一例外是 JSON 语法本身强制要求的转义序列文档明确只保留四个\n换行\t制表符\双引号\\反斜杠文档给出的原因很直接Claude Code 的工具参数管道tool parameter pipe是 UTF-8 原生的字符会原样通过不需要转义来保护。文档以一对正反例收尾错误: question: 請選擇\uXXXX\uXXXX\uXXXX\uXXXX 正确: question: 請選擇管理工具为何转义会失败凭记忆回忆码点不可靠这是该文档最有信息量的一节。它解释了这条规则不是风格偏好而是对模型失败模式的工程防御手工转义依赖模型从训练记忆中回忆每一个码点这对长 CJK 字符串不可靠。模型经常输出错误的码点。文档中的原始例子是模型想写管U7BA1却输出了㄃这个码点的转义于是用户看到的管理工具实际渲染为㄃3用箱——语义完全损坏且难以察觉。触发条件文档精确指出危险区间是长的、多行的、包含数百个 CJK 字符的问题。恰恰在这种场景下模型会条件反射式地开始逐字符转义reflexive escaping而恰恰在这种场景下转义错误造成的破坏最大。文档用一句话钉住这个判断Long ≠ escape长不等于要转义——保持字面字符。这里隐含的工程洞察是对 LLM 生成 JSON 而言文本越长、越该谨慎地编码这个人类直觉恰好是反的。字面 UTF-8 是唯一无失败路径的编码方式因为模型在生成自然语言 CJK 时不需要做任何码点计算。规则如何落地生成器、SKILL.md 注入链与自检清单文档自身声明自己是按需读取read on demand的真正生效的规则是每个技能 always-loaded 的 AskUserQuestion 自检中的一条Non-ASCII characters written directly, NOT \u-escaped本文档只是完整的论证材料。仓库源码证实了这条注入链1. 共享前置生成器。scripts/resolvers/preamble/generate-ask-user-format.ts 中的generateAskUserFormat()函数为所有交互式技能生成统一的## AskUserQuestion Format指令块。其中第 104–109 行就是 CJK 规则的一行规则 文档指针形态**Non-ASCII characters — write directly, never \u-escape.** When any string field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit the literal UTF-8 characters; never escape them as \uXXXX (the pipe is UTF-8 native, and manual escaping miscodes long CJK strings). Only \n, \t, \, \\ remain allowed. Full rationale worked example: see docs/askuserquestion-cjk.md. Read on demand when a question contains CJK.注意措辞分层always-loaded 部分只给可执行的操作规则写字面、只留四个转义和一句失败模式摘要manual escaping miscodes long CJK strings完整论证 反例被外置到docs/askuserquestion-cjk.md仅在问题包含 CJK 时按需读取。这是典型的 token 预算管理——操作规则常驻论证材料按需。2. 渲染进每个技能的 SKILL.md。经过生成管线gen-skill-docs这段指令出现在几乎所有会提问的技能文档中例如 document-generate/SKILL.md 第 443–448 行是规则本体紧随其后的 Self-check before emitting 自检清单第 462 行包含- [ ] Non-ASCII characters (CJK / accents) written directly, NOT \u-escaped自检清单意味着每次调用 AskUserQuestion 前模型必须逐条核验——CJK 规则不是读过就算而是每次发射前的强制检查项。仓库中 canary/SKILL.md、ios-qa/SKILL.md、ship/SKILL.md 等大量技能都带有同一条自检项且 test/fixtures/golden/ 目录下的 golden 快照claude-ship、codex-ship、factory-ship 三个宿主的 SKILL.md 黄金文件也固定了这段文本保证多宿主Claude/Codex/Factory渲染结果一致。规则演进从内联手册到按需文档以及测试如何钉住它CHANGELOG.md 记录了这条规则的两段式历史恰好说明了 gstack 的文档工程方法论第一阶段#1205引入规则。AskUserQuestion preamble forbids\uXXXXescaping of non-ASCII characters新增规则 12 加一条自检项理由是手工转义 CJK 的模型会搞错码点管理工具会渲染成㄃3用箱Long ≠ escape。该规则通过 gen-skill-docs 管线级联35 个 SKILL.md 重新生成同时 AskUserQuestion 前置的字节预算从 36,500 放宽到 39,000 以容纳新规则。第二阶段token 削减计划外置论证。后续版本中共享 AskUserQuestion 前置顺带甩掉了很少用到的 CJK 转义手册——内联手册被裁剪为一行操作规则 文档指针全仓库共削减约 29,524 字节每个交互技能约 900 字节完整论证迁入docs/askuserquestion-cjk.md按需读取always-loaded 的自检项保持不变。CHANGELOG 明确列出该文档为full non-ASCII / CJK escaping rationale worked example, read on demand。回归测试钉住契约。test/resolver-ask-user-format.test.ts 第 161–164 行有一条专门的回归测试test(regression: orphan 12. prefix removed from CJK rule, () { expect(out).not.toContain(12. **Non-ASCII); expect(out).toContain(**Non-ASCII characters); });这条测试的背景是规则曾是内联编号列表的第 12 条外置后编号前缀变成孤儿残留测试确保它被清掉。此外 test/gen-skill-docs.test.ts 第 407 行的注释表明生成管线测试也覆盖了\u-escape CJK 规则 自检项的注入完整性。这两层测试的意义在于规则文本一旦在未来编辑中丢失或漂移bun test毫秒级报警而不是等到周期性 eval 才暴露。实战要点生成含 CJK 的 AskUserQuestion 时的检查清单综合文档与仓库证据实际使用或仿照 gstack 设计自己的技能体系时的可操作要点任何 CJK 文本一律字面直写——问题、选项标签、选项描述三个字段同等适用JSON 中仅允许\n、\t、\、\\四个转义出现任何\u序列即违规长多行 CJK 问题是最危险场景字符越多越要保持字面禁止因为太长所以要认真转义的条件反射把直写而非转义做成发射前自检项而不是写进一次性手册——gstack 的验证方式是一行操作规则 一条自检项常驻完整论证如本文引用的㄃3用箱反例外置为按需文档用测试钉住规则文本对生成器输出断言关键短语**Non-ASCII characters存在、孤儿编号不存在防止规则在多宿主、多技能的再生成管线中静默漂移。规则本身只有一句话但它的价值在于配套的机制always-loaded 自检保证每次生效按需文档承载论证与反例生成器管线保证 35 个技能文本一致回归测试保证契约不漂移——这才是 gstack 处理模型行为规则这一类问题的完整范式。姊妹文档 docs/askuserquestion-split.md 以同样的按需读取模式处理 5 选项拆分规则两者共同构成 AskUserQuestion 前置指令中指向 docs 的两条外置指针。适用前提以上机制描述以当前仓库状态为准其中管道为 UTF-8 原生是仓库文档对 Claude Code 工具参数管道的表述转义失败的码点错误案例为文档给出的示例而非仓库中可复现的实测记录。【免费下载链接】gstackUse Garry Tans exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考