write-good 使用指南:基于 Node.js 的英语散文 Naive Linter——API、CLI、九大检查与自定义扩展
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):
- 去重合并(dedup):同一位置被多个检查同时命中时,只保留一条建议,并把多个原因用
and拼接。例如测试中的"extremely" is a weasel word and can weaken meaning,正是因为extremely同时命中了 weasel 与 adverb 两个检查(实现见 write-good.js); - 白名单过滤:如上节所述;
- 按位置排序:最终建议按
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]+) 逐个切词,再与前一个词做大小写不敏感的比对,命中即回报第二个词的位置与长度。因此:
the the、跨行的the\nthe、大小写混合的The the都会被命中(见 test/basic.spec.js);- 非单词(如
// //)不会被误报(见 test/basic.spec.js)。
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 脚本乃至你自己的写作流程都能轻松消费;而其"朴素"的定位也提醒使用者:工具负责提示,是否采纳建议、如何与人沟通写作意见,始终是使用者自己的判断。