说「help」的语言

背景：脚本城邦 40+ 位官员各说各的方言——--help 有时被当标题（new-adr 曾误占 ADR 号）、有时静默空转（fix-adr-dates）、有时直接执行主流程（gen-docs-index 曾真的写盘）。共享解析器 parseArgs 对未知 flag 只 warn 不退出。

过程：parseArgs 内置 --help 识别（返回 help:true）与 unknown 收集；22 个 parseArgs 消费脚本 + 8 个手写解析脚本统一插守卫（help 退 0、未知 flag 退 1）；--help 从「看文件头」偷懒提示升级为自吐 JSDoc（真实用法）。

---

脚本城邦的档案室里，躺着一份奇怪的 ADR。

编号是正经编号，标题却不对劲——adr-027-help.md。

那是很久以前的事：一位年轻的脚本官想查询用法，敲了句 --help。他的解析器不认识这个词，当成了标题——于是档案室多了一篇叫"help"的 ADR。后来人们把它删了，但坑还在：谁也不知道下一个敲 --help 的人，会不会又留下一份奇怪的档案。

我蹲在城邦门口，看着来往的官员，发现一件更麻烦的事：

四十多位官员，四十多种方言。

一、方言普查

我挨家挨户敲了门。

第一位是 fix-adr-dates 官。我敲 --help，他抬头看了我一眼，然后继续干活——把面前的一摞 ADR 挨个改日期。敲完才问我："你刚说什么？"

"help。"

"哦。"他挠头，"我以为你是来让我改文件的。反正我听着不像文件名，就顺手全改了。"

第二位是 gen-docs-index 官。我敲 --help，他直接把整个索引重写了一遍——磁盘上全是他的墨迹。他擦着手说："help？那不是个参数，我当没看见。"

第三位是 new-adr 官。我敲 --help，他抓起笔就要往档案册上写："新 ADR 一篇，标题……help？"

"停下！"我按住他的笔，"那不是标题，那是求救信号！"

"求救？"他茫然，"你的方言里，'help'不是标题吗？"

我忽然明白了问题有多深：不是某个官员听不懂 help，而是整个城邦没有统一的"求救语言"。 有人说 help 是标题，有人说 help 是空气，有人说 help 是开工铃。

二、统一语言

我回到档案室，翻出那份共享的《参数解析宪章》——parse-args.mjs。

宪章说：遇到不认识的 --xxx，警告一声，继续放行。

"放行？"我指着宪章上那行字，"放行到哪去？放到位置参数位？让 fix-adr-dates 把'help'当文件名？"

宪章沉默。

我提笔修改：

--help / -h   → 内置识别，标记 help:true（绝不进入参数位）
未知 --flag   → 收集到 unknown 清单（仍警告，但调用方可决定）

然后，我带着宪章走遍四十家，给每一位官员装上一道统一的喉咙：

听到 --help：停下，念出自己的出身（JSDoc 文件头），退场，退出码 0。 听到不认识的 --xxx：报错，退出码 1，绝不把它当成文件名、标题或开工铃。

"为什么退出码是 1？"fix-adr-dates 官问。

"因为报错不是干活，"我说，"报错是承认'我听不懂'。承认听不懂，比假装听懂了乱干，安全得多。"

三、敷衍的喉咙

语言统一了。但第二周，外交官来验收，敲了一声 --help。

一位官员站直，用标准的新喉咙念道：

"用法见文件头 JSDoc。"

然后退场。

外交官等了三秒："……就这？"

"就这。"官员回答。

外交官转向我，语气很平："我敲 --help 是想知道怎么用。他告诉我'看文件头'——跟告诉一个迷路的人'看地图'一样。连提示效果都发挥不出来，这个喉咙要它何用？"

我脸上有点挂不住。喉咙是装了，可喉咙里只有一句敷衍。

回去重做。这次不是装喉咙，是给喉咙接上肺——让每位官员在听到 --help 时，翻开自己的出身卷（用 fs.readFileSync 读自己的文件头），把真实的用法、参数、示例，一字一句念出来。

"你刚才念的是什么？"外交官再次敲响那扇门。

官员翻开卷轴，缓缓念道：

用法: node scripts/fix-adr-dates.mjs [adr-NNN-*.md ...]
  无参 = 处理全部 ADR；可传文件名限定范围。

"这才是 help。"外交官点头，"不是'去看地图'，是'地图就在你面前'。"

尾声

现在，四十多位官员都说同一种语言了。

你敲 --help，他们停下来，翻开卷轴，念出真实的用法——不是敷衍的指路，是摊开的地图。你敲一个不认识的 --xxx，他们报错退场，绝不把你的话当标题、当文件名、当开工铃。

语言统一的意义，不是让所有人都说一样的话。

是让**「我听不懂」成为一句可以被说出口、被认真对待的话**——而不是被当成「help」写成档案，被当成空气继续干活，被当成开工铃把整座城重写一遍。

就像联邦的街道：每条路都可以叫不同的名字，但迷路的人喊「help」，必须每家每户都听得懂。

（附录·文档演进 · 第 14 篇，2026-08-06）