write-good 使用指南:基于 Node.js 的英语散文 Naive Linter——API、CLI、九大检查与自定义扩展

原创2026-10-14 13:05:482,500 阅读
文章标签:开发工具

write-good 使用指南:基于 Node.js 的英语散文 Naive Linter——API、CLI、九大检查与自定义扩展

write-good 是一个面向开发者的英语散文(English prose)Naive Linter,以字符串为输入、以建议数组为输出,帮助你在提交文档、README 或博客之前快速发现被动语态、weasel words(模糊修饰词)、词句重复等常见行文问题。本文以仓库 README.md 为骨架,结合 write-good.js 主模块、bin/write-good.js CLI 入口、lib 目录下的内置检查实现与 test 目录的测试用例,系统讲解它的 JavaScript API、命令行用法、九个内置检查、自定义检查扩展接口以及 Docker 运行方式,读完即可把它接入自己的文档工作流。

一、项目定位与安装

write-good 在 package.json 中的自我描述是 "Naive linter for English prose"(面向英语散文的朴素 linter)。它并不试图做语法纠错,而是基于一组预设的文体规则(被动语态、weasel words、词句重复、陈词滥调等)对文本做启发式扫描,把命中的片段连同位置和原因作为"建议"(suggestion)返回。README 的开篇调侃道:这是为"写不好英文、又想学着把其他事情也做好"的开发者准备的——它定位为写作辅助而非写作裁判,因此 README 特别强调:

Important: Do not use this tool to be a jerk to other people about their writing. (重要:不要用这个工具去苛责他人的写作。)

安装方式非常简单,作为本地依赖使用:

npm install write-good

仓库声明的最低运行环境为 Node.js >= 6、npm >= 5(见 package.json),并且同时暴露了两个命令别名 write-good 与 writegood(见 package.json),两种写法都可以在命令行调用。

二、JavaScript API:从调用到返回结构

writeGood 是一个接收字符串、返回建议数组的函数。这是 README 给出的最基础用法:

var writeGood = require('write-good');

var suggestions = writeGood('So the cat was stolen.');

// suggestions:
//
// [{
//   reason: "omit 'So' from the beginning of sentences",
//   index: 0, offset: 2
// }, {
//   reason: "'was stolen' is passive voice",
//   index: 11, offset: 10
// }]

每条建议对象包含三个字段,它们的语义在 write-good.js 的主函数与扩展接口文档中有明确约定:

  • index:命中片段在输入文本中的起始位置(从 0 计);
  • offset:命中片段的长度;
  • reason:人类可读的解释文本,由主模块通过 reasonable() 函数生成——它会把命中片段原文与检查自带的标准解释拼接,形如 "was stolen" may be passive voice(见 write-good.js)。

注意上面的示例中 reason 文案与当前源码略有出入:仓库当前版本由各检查自带 explanation 字段统一生成(如被动语态的固定文案是 "was stolen" may be passive voice),具体映射见下文"内置检查"一节,以实际运行输出为准。

2.1 通过第二个参数禁用指定检查

writeGood 接受可选的第二个参数对象,允许关闭任意组合的内置检查。例如关闭被动语态检查:

var writeGood = require('write-good');

var suggestions = writeGood('So the cat was stolen', { passive: false });
// suggestions: []

这背后的逻辑在主模块中实现:finalOpts 会剔除 checks 保留字,然后在遍历每个检查时判断 finalOpts<a href="https://link.gitcode.com/i/7e03312d8331890a257e66ca03401042" target="_blank">checkName] !== false 才执行对应检查函数(见 [write-good.js)。也就是说,把任何检查键设为 false 即可停用它;不传任何选项时,唯一默认停用的是 eprime(见 write-good.js 的 disabledChecks)。

2.2 用 checks 属性替换整组检查(非英语文本)

第二个参数的 checks 属性可以把内置检查整体替换为自定义检查集,典型场景是检查非英语文档——README 以德语扩展 schreib-gut] 为例(该扩展也是仓库的 devDependency,见 [package.json):

var schreibGut = require('schreib-gut');

writeGood('Aller Wahrscheinlichkeit nach können Entwickler nicht gut schreiben', { weasel-words: false, checks: schreibGut });

// suggestions
// [{index : 0, offset : 29, reason : '"Aller Wahrscheinlichkeit nach" is wordy or unneeded' }]

主模块对 checks 的处理是:const finalChecks = opts.checks || defaultChecks;——只要提供了 checks,就完全用它替换内置检查集(见 write-good.js)。因此你仍可以用普通选项关闭其中某几项,只是这些选项名必须以扩展所暴露的检查键为准。仓库测试 test/customChecks.spec.js 验证了这一点:使用德语检查集时,能命中 "komplett" is a weasel word 与 "Aller Wahrscheinlichkeit nach" is wordy or unneeded,而英语的 "Remarkably" 不会再被标记。

2.3 用 whitelist 属性豁免特定词

第二个参数的 whitelist 属性接受一个字符串数组,把其中出现的片段从建议中过滤掉。README 的例子是:默认情况下 only 会被判为"削弱语义"的副词,但你可能希望豁免 read-only 这个合法复合词:

var writeGood = require('write-good');

var suggestions = writeGood('Never write read-only sentences.');
// suggestions: [{ index: 17, offset: 4, reason: '"only" can weaken meaning' }]

var filtered = writeGood('Never write read-only sentences.', { whitelist: ['read-only'] });
// filtered: []

白名单的过滤实现位于主模块的 filter() 函数(write-good.js):它先在原文本中找出白名单词出现的所有区间,然后丢弃任何与这些区间"完全覆盖、起点落在其中或终点落在其中"有重叠的建议。也就是说,豁免是基于文本区间的重叠判定,而不是简单的字符串包含——只要建议命中位置与白名单词区间存在交集,该建议就会被移除,这对处理 read-only 这类含连字符的复合词尤为重要。对应的行为有测试用例背书(test/basic.spec.js)。

2.4 去重、合并与排序:返回结果的三个后处理步骤

在把建议返回给你之前,主模块还依次做了三件事(见 write-good.js):

  1. 去重合并(dedup):同一位置被多个检查同时命中时,只保留一条建议,并把多个原因用 and 拼接。例如测试中的 "extremely" is a weasel word and can weaken meaning,正是因为 extremely 同时命中了 weasel 与 adverb 两个检查(实现见 write-good.js);
  2. 白名单过滤:如上节所述;
  3. 按位置排序:最终建议按 index 升序排列,保证输出顺序与文本阅读顺序一致(见 write-good.js)。

三、CLI 命令行:从安装到完整参数

3.1 安装方式与 npx

可以全局安装后作为命令行工具使用:

npm install -g write-good

如果你的 npm 版本在 5.2.0 及以上,也可以用 npx 免安装直接运行:

npx write-good *.md

3.2 文件输入、glob 与输出格式

write-good 接收一个 [glob] 模式,把每个文件中命中的问题打印到 stdout。README 的示例输出长这样(以下方为 write-good *.md 的部分输出):

$ write-good *.md

In README.md
=============
 = writeGood('So the cat was stolen.');
                         ^^^^^^^^^^
"was stolen" is passive voice on line 20 at column 40
-------------
//   suggestion: "'was stolen' is passive voice",
                   ^^^^^^^^^^
"was stolen" is passive voice on line 28 at column 19

每个命中都会输出三行:所在行的文本片段、用 ^ 标记命中位置的下划线,以及 "...reason..." on line N at column M 的位置说明。这个可视化的"注解"输出由 lib/annotate.js 实现:它把 index 换算成行/列坐标,从命中处截取最长 80 字符的行片段(若列号超过 25 会自动回退,见 lib/annotate.js),再叠加数量等于 offset 的 ^ 字符。块与块之间用 ------------- 分隔。

CLI 入口的完整实现见 bin/write-good.js,它基于 commander 解析参数,逐文件读入内容后调用 writeGood(contents, opts) 并把结果交给 annotate 渲染(见 bin/write-good.js)。

3.3 只运行特定检查

只运行你关心的检查,其他检查会被静默关闭:

write-good *.md --weasel --so

3.4 排除(停用)检查

write-good *.md --no-passive

3.5 激活默认关闭的检查

E-Prime(to be 动词)检查默认关闭,需要显式开启:

# E-Prime is disabled by default.
write-good *.md --yes-eprime

注意:--yes 前缀只对 E-Prime 生效,因为其余检查默认就是开启的。这里的参数语义需要结合 bin/write-good.js 的解析逻辑理解:

  • --no-<check>:把对应检查设为 false(停用);
  • --<check>:把对应检查设为 true,同时把 include 置为 false,意味着只运行显式指定的这些检查(这正是"只运行特定检查"的实现机制);
  • --yes-<check>:把对应检查设为 true,但不触碰 include,因此只用于在"全部默认检查 + E-Prime"的组合下追加激活,而不干扰其他检查。

3.6 直接传入文本(--text)

不提供文件也能检查文本,适合快速试验:

write-good --text="It should have been defined there."

多行文本同样支持:

write-good --text="I can't see a problem there that's not been defined yet.
Should be defined again."

还可以与其他参数组合:

write-good --text="It should have been defined there." --no-passive

甚至可以从远程文件抓取内容后检查:

write-good --text="$(curl https://raw.githubusercontent.com/btford/write-good/master/README.md)"

(该命令依赖本机 curl,且网络可用性由使用者环境决定。)--text 在 CLI 入口中的处理方式是:把 --text= 后的整段字符串塞进 opts.text,并标记 textInputSupplied,随后走与文件相同的 displaySuggestions 渲染路径(见 bin/write-good.js)。

3.7 解析友好的输出与退出码(--parse)

write-good *.md --parse

--parse 会切换到"解析友好"输出:每条建议以 源文件:行号:列号:原因 的冒号分隔格式打印(例如 README.md:20:40:"was stolen" may be passive voice),同时退出码变为更符合 Unix 惯例的语义——只要有任何建议,进程就以非零码(-1,即 shell 中的 255)退出,否则以 0 退出(见 bin/write-good.js 与 lib/annotate.js)。这一模式非常适合接入脚本、CI 或编辑器插件做机器化处理。

3.8 指定自定义检查扩展(--checks)

npm install -g schreib-gut
write-good *.md --checks=schreib-gut

当检测到 --checks=<module> 时,CLI 会尝试 require(checksModule) 加载该模块,并动态为该模块暴露的每个检查生成 --<check> 与 --no-<check> 选项(见 bin/write-good.js)。加载失败时给出明确报错:

Could not import custom check module. Check for spelling errors and make sure you have the module installed.

这一行为在 test/cli.spec.js 中有对应测试。仓库的测试文本 test/texts/German.md 展示了德语场景:write-good ./test/texts/German.md --checks=schreib-gut --weasel --tooWordy 能同时命中德语 weasel word 与冗余短语(见 test/cli.spec.js)。

3.9 帮助信息与其他边界行为

查看全部可用选项:

write-good --help

CLI 还有几个值得注意的边界行为(均有测试佐证,见 test/cli.spec.js):

  • 不提供任何文件且没有 --text 时,输出 You did not provide any files to check. 并以退出码 1 结束(bin/write-good.js);
  • 非法参数输出 "--nonsense" is not a valid argument.(test/cli.spec.js);
  • 非 --parse 模式下,进程退出码等于所有文件累计的建议总数(exitCode += suggestions.length),因此可以简单地用 $? 判断是否有问题(bin/write-good.js)。

四、九个内置检查详解

writeGood 默认启用 8 项检查,外加 1 项默认关闭的 E-Prime 检查。总览如下(键名即 API 第二参数中可用的停用键名,也即 CLI 的 --no-<check> 参数名):

检查键 检测内容 默认状态
passive 被动语态 开启
illusion 词汇错觉(lexical illusion)——相邻重复的单词 开启
so 句首的 so 开启
thereIs 句首的 there is / there are 开启
weasel weasel words(模糊、空洞的修饰词) 开启
adverb 削弱语义的副词(really、very、extremely 等) 开启
tooWordy 冗余短语与不必要的词 开启
cliches 常见陈词滥调 开启
eprime to be 系动词(E-Prime 规范) 关闭(需显式开启)

这些检查的注册与各自的标准解释文案(explanation)集中在主模块的 defaultChecks 中(见 write-good.js):例如 weasel 的解释是 'is a weasel word'、illusion 是 'is repeated'、tooWordy 是 'is wordy or unneeded'。其中四项是仓库自研实现(位于 lib 目录),其余依赖独立的 npm 包(见 package.json)。

4.1 passive:被动语态

检测被动语态,底层使用 npm 包 passive-voice。触发文案为 "was stolen" may be passive voice。典型示例:The script was killed 会命中 "was killed" may be passive voice(见 test/basic.spec.js)。它同样能识别连字符复合动词短语,例如 A transfer visa may be required at check-in... 会命中 "be required"(见 test/basic.spec.js)。

4.2 illusion:词汇错觉(相邻词重复)

检测"词汇错觉"——同一个词相邻重复时,大脑容易自动忽略第二处,典型如跨行重复的 the the。实现位于 lib/lexical-illusions.js:用正则 (\s*)([^\s]+) 逐个切词,再与前一个词做大小写不敏感的比对,命中即回报第二个词的位置与长度。因此:

4.3 so:句首的 so

检测以 so 开头的句子。实现位于 lib/starts-with-so.js:先用正则 ([^\n\.;!?]+)([\.;!?]+) 把文本切分成"以句点、分号、感叹号、问号结尾的句子/分句",再检查每个片段是否以 so 开头(忽略前导空白与大小写)。因此:

  • So the best thing to do is wait. 命中 "So" adds no meaning(见 test/basic.spec.js);
  • So? 不会命中(独立成句且后无内容);
  • 句中部的 so(如 This changes the code so that it works.)不会命中;
  • 以 so 开头的其他单词(Some、Sorry)不会命中;
  • 分号后的分句也会被检测:This is a test; so it should pass or fail. 命中分号后的 "so"(见 test/basic.spec.js);
  • 文本前的空行不影响检测(\n\nSo adds no meaning. 仍能命中,见 test/basic.spec.js)。

4.4 thereIs:句首的 there is / there are

检测句首的 there is / there are 冗余结构,实现位于 lib/there-is.js,切句逻辑与 so 相同,再用 ^(\s)*there\b\s(is|are)\b 匹配片段开头。触发文案为 "There is" is unnecessary verbiage:

  • There is a use for this construction. 命中 index 0, offset 8;
  • There are uses for this construction. 命中 index 0, offset 9(见 test/basic.spec.js)。

4.5 weasel:weasel words

检测模糊、空洞、缺乏信息量的"weasel words"(如 few、Remarkably 等),底层使用 npm 包 weasel-words。注意它可能与 adverb 检查产生重叠:extremely 同时被 weasel 与 adverb 命中,经过去重合并输出 "extremely" is a weasel word and can weaken meaning(见 test/basic.spec.js)。

4.6 adverb:削弱语义的副词

检测 really、very、extremely、simply、only 等可能弱化语气的副词,底层使用 adverb-where。例如 This sentence is simply terrible 命中 "simply" can weaken meaning;Never write read-only sentences. 默认命中 "only" can weaken meaning(这就是 README 中 whitelist 示例的由来)。

4.7 tooWordy:冗余短语

检测冗长、可简化的表达,底层使用 too-wordy。典型命中:

  • As a matter of fact, this sentence could be simpler. → "As a matter of fact" is wordy or unneeded;
  • Your readers will be adversely impacted by this sentence. → "impacted" is wordy or unneeded(见 test/basic.spec.js)。

4.8 cliches:陈词滥调

检测常见陈词滥调,底层使用 no-cliches。例如 Writing specs puts me at loose ends. 命中 "at loose ends" is a cliche(见 test/basic.spec.js);测试文本 test/texts/English2.md 中的 Playing the field is a cliché. 也会被命中(见 test/cli.spec.js)。

4.9 eprime:to be 系动词(默认关闭)

检测 to be 系动词(is、are、was、been、be 以及 There's 这类缩写),底层使用 e-prime 包,对应 E-Prime 写作规范(即主张避免使用 to be 动词的文体约束)。它默认关闭,API 中需传 { eprime: true },CLI 中需传 --yes-eprime 或 --eprime:

  • NodeJs is awesome ;) + { eprime: true } → "is" is a form of 'to be';
  • There's no place like localhost + { eprime: true } → "There's" is a form of 'to be';
  • 以 is 开头的普通单词不会被误报:Isle of Man 不命中(见 test/basic.spec.js)。

CLI 侧的行为测试同样覆盖了 E-Prime:默认不检查(test/cli.spec.js),显式 --eprime 后会对测试文本 test/texts/English.md 报出 9 处 to be 形式(test/cli.spec.js)。

五、自定义检查扩展:接口契约与示例

扩展机制是 write-good 面向非英语文本与个性化规则的核心能力。README 明确指出:扩展就是一个 Node.js 模块,导出形如"检查名 → { fn, explanation }"的对象:

module.exports = {
  check1: {
    fn: function(text) {
      …
    },
    explanation: '…'
  },
  check2: {
    fn: function(text) {
      …
    },
    explanation: '…'
  }
}

每个检查函数接收一个字符串输入,返回一组文体违规对象的列表,每个对象带 index 与 offset:

/**
* @param {text} text  Input text
* @return {{index:number, offset:number}[]}  List of all violations
*/

index 表示命中位置在输入文本中的起点,offset 表示命中片段的长度。检查函数不需要负责生成人类可读的 reason——主模块会取命中片段原文并拼上你的 explanation 字符串(见 write-good.js),这与内置检查完全一致。

README 给出了一个完整的示例扩展:检测文本中是否出现一组禁用的名字(Tom Riddle 与 Voldemort):

module.exports = {
  voldemort: {
    fn: function (text) {
      var positives = ['Tom Riddle', 'Voldemort']
      var re = new RegExp('\\b(' + positives.join('|') + ')\\b', 'gi');
      var suggestions = [];
      while (match = re.exec(text)) {
        suggestions.push({
          index: match.index,
          offset: match[0].length,
        });
      }
      return suggestions;
    },
    explanation: 'You must not name Him-Who-Must-Not-Be-Named'
  }
}

这个示例展示了扩展检查的完整写法:用正则逐次匹配(注意 re.exec 配合 g 标志的循环写法)、收集 index/offset、返回数组。使用时有两条接入路径:

  • API 路径:writeGood(text, { checks: myModule })——整体替换内置检查;
  • CLI 路径:write-good *.md --checks=my-module——加载模块并为其中每个检查动态生成 --voldemort / --no-voldemort 选项(见 bin/write-good.js)。

已有的第三方扩展示例是德语检查包 schreib-gut(德语版 weasel word 与冗余短语检测,见 test/customChecks.spec.js)。如果你知道其他未被收录的扩展,README 欢迎通过 Pull Request 补充。

六、Docker 运行

6.1 使用预构建镜像

若本机安装了 Docker,可以直接拉取预构建镜像运行(把当前目录挂载为 /app,*.md 由镜像内的 write-good 命令消费):

docker run --rm --volume $PWD:/app hochzehn/write-good *.md

6.2 本地构建并运行

也可以先在本地构建镜像:

docker build -t btford/write-good .

然后运行(挂载当前目录、以 /srv/app 为工作目录):

docker run -it --rm -v "$(pwd)":/srv/app -w /srv/app btford/write-good:latest *.md

Dockerfile 的实现思路很清晰:基于 node:dubnium 基础镜像,把仓库复制进 /tmp/write-good,用 yarn global add 全局安装,设置 /srv/app 为工作目录,ENTRYPOINT ["write-good"] 让容器直接以 write-good 命令为入口,默认命令是 --help(即不带参数运行容器会打印帮助信息)。

七、测试与验证

仓库用 Jasmine(jasmine-node)组织测试,运行 npm test 会先执行 ESLint 再跑测试(见 package.json)。三个测试文件分别覆盖:

  • test/basic.spec.js:API 层——各类检查的命中与不命中、停用检查、白名单、E-Prime、结果排序、去重合并,以及 annotate 的格式化输出(行片段 + ^ 标记 + 行列信息);
  • test/cli.spec.js:CLI 层——冒烟测试、--weasel 只跑指定检查、--no-weasel 停用、E-Prime 默认关闭与显式开启、--checks=schreib-gut 德语扩展、非法参数与扩展导入失败的错误信息、无文件输入的错误提示、glob 通配符(test/**/*.md);
  • test/customChecks.spec.js:自定义检查集——验证 checks 替换后能正确命中德语内容、且不再命中英语 weasel word。

配套的测试语料在 test/texts 目录:覆盖九类检查的 English.md、含陈词滥调的 English2.md,以及德语样例 German.md,可作为手工运行 CLI 的现成输入。

八、在编辑器与写作工具生态中的集成

write-good 的轻量定位(纯函数 + CLI)让它被多家编辑器生态项目集成,README 的 "Other projects using write good" 一节列出过:Atom 的 linter-write-good、Drafts iOS 应用的动作、VS Code 的 Write Good Linter 扩展、基于 coc.nvim 的 Vim 版本、Vim 的 ALE 实时 linter、用于 Google Docs 的 Write Better(Chrome 扩展),以及 Statick 插件(用于与其他 linter 结果合并)。另外 README 的 "See also" 部分也记录了一批作者研究本模块时参考的资料,包括 Matt Might 的"规避 weasel words"shell 脚本(初始实现即基于此)、《Elements of Style》、Flesch–Kincaid 可读性测试、LanguageTool 等——这些资源的具体链接可在仓库 README.md 中查看。

九、小结

write-good 的完整使用路径可以概括为四步:npm install write-good 安装 → 用 API 的 writeGood(text, opts) 或 CLI 的 write-good <glob> 跑检查 → 按需用 { passive: false } / --no-passive 停用检查、用 --weasel --so 只跑指定检查、用 --yes-eprime 开启 E-Prime → 面对非英语文本时编写自己的 { fn, explanation } 扩展并通过 checks / --checks 接入。它返回的每条建议都带有精确的 index/offset/reason,让编辑器插件、CI 脚本乃至你自己的写作流程都能轻松消费;而其"朴素"的定位也提醒使用者:工具负责提示,是否采纳建议、如何与人沟通写作意见,始终是使用者自己的判断。

登录后查看全文
write-good