Vale 是一個(gè)面向自然語(yǔ)言文本的 Linter英文定位就叫 Linter for Prose。簡(jiǎn)單說(shuō)它用命令行方式幫你檢查散文、技術(shù)文檔、博客文章里的用詞、術(shù)語(yǔ)、一致性和風(fēng)格問(wèn)題而不是檢查語(yǔ)法錯(cuò)誤或者做排版。這個(gè)定位讓它和拼寫(xiě)檢查器、Markdown 格式化工具完全不一樣。如果你寫(xiě)英文技術(shù)文檔或者團(tuán)隊(duì)有明確的中英文寫(xiě)作規(guī)范又不想每次 review 都靠人工去抓“這個(gè)術(shù)語(yǔ)前后不一致”“這個(gè)詞不該用”“那個(gè)表達(dá)太口語(yǔ)化”這類(lèi)問(wèn)題Vale 值得認(rèn)真了解一下。這篇文章按我自己的落地順序?qū)懴戎v它到底適合解決什么問(wèn)題再講怎么安裝、怎么配置、怎么寫(xiě)自己的規(guī)則最后是批量任務(wù)和實(shí)測(cè)中最容易踩到的坑。我不會(huì)把項(xiàng)目 README 復(fù)述一遍只會(huì)寫(xiě)我實(shí)際用下來(lái)覺(jué)得關(guān)鍵的環(huán)節(jié)。1. 先搞清楚 Vale 到底解決寫(xiě)作里的什么問(wèn)題1.1 它不是拼寫(xiě)檢查器也不是排版神器很多人第一次接觸 Vale 會(huì)誤以為它是“高級(jí)版拼寫(xiě)檢查”。實(shí)際上它的定位更接近“基于規(guī)則的文本檢查器”。拼寫(xiě)檢查器解決的是“這個(gè)單詞是否拼錯(cuò)了”排版工具解決的是“代碼塊縮進(jìn)是否統(tǒng)一、空行是否一致”。Vale 更關(guān)心的是這句話里是不是用了某個(gè)團(tuán)隊(duì)禁用的詞某個(gè)術(shù)語(yǔ)的大小寫(xiě)是不是統(tǒng)一某個(gè)動(dòng)詞的搭配是否更符合你所在領(lǐng)域的慣例。舉幾個(gè)典型場(chǎng)景文檔里既有JavaScript又出現(xiàn)Javascript規(guī)則可以自動(dòng)標(biāo)記后者。團(tuán)隊(duì)要求避免使用utilize這類(lèi)詞統(tǒng)一寫(xiě)成use規(guī)則可以提醒。文案里出現(xiàn)whether if、in order to這類(lèi)冗長(zhǎng)或錯(cuò)誤的表達(dá)規(guī)則可以建議替換。產(chǎn)品文檔規(guī)定必須寫(xiě)Windows 11不能寫(xiě)成Win11規(guī)則可以校驗(yàn)。這類(lèi)檢查靠人工 review 也能做但問(wèn)題是文檔一多、團(tuán)隊(duì)一大人人工 review 很難保持標(biāo)準(zhǔn)一致。Vale 的價(jià)值就是把這些機(jī)械、可枚舉的判斷寫(xiě)成規(guī)則提交代碼時(shí)自動(dòng)跑一遍。順便說(shuō)一個(gè)它在工程上的好處Vale 是本地執(zhí)行的命令行工具默認(rèn)情況下檢查的是本地文件不會(huì)把文檔內(nèi)容上傳到別的服務(wù)。對(duì)內(nèi)部文檔和隱私要求較高的項(xiàng)目這個(gè)特性比在線語(yǔ)法檢查工具更可控。1.2 適合誰(shuí)不適合誰(shuí)如果你屬于下面這幾類(lèi)人Vale 會(huì)很有用技術(shù)文檔工程師需要維護(hù)大量 Markdown、HTML、reStructuredText 文檔。開(kāi)源項(xiàng)目維護(hù)者希望 contributors 提交的文檔能和項(xiàng)目風(fēng)格保持一致。團(tuán)隊(duì)里有文檔評(píng)審環(huán)節(jié)經(jīng)常因?yàn)樾g(shù)語(yǔ)不統(tǒng)一、禁用詞反復(fù)提意見(jiàn)。獨(dú)立博主或?qū)懽髡呦Ｍo自己建立一個(gè)固定的寫(xiě)作用詞規(guī)范。如果你只是偶爾想檢查一段英文的語(yǔ)法和拼寫(xiě)那在線工具可能更省事。Vale 本身不提供 AI 式的句子改寫(xiě)也不做語(yǔ)法樹(shù)分析。它更像一個(gè)“白名單和黑名單管理器”你把約定寫(xiě)成規(guī)則它替你嚴(yán)格執(zhí)行。還有一點(diǎn)需要提前理解Vale 默認(rèn)只提供引擎不提供現(xiàn)成規(guī)則。你可以通過(guò)內(nèi)置的樣式包機(jī)制拉取一些社區(qū)維護(hù)的規(guī)則也可以自己寫(xiě)規(guī)則但不能裝完就直接用。這個(gè)設(shè)計(jì)既是門(mén)檻也是它可定制的來(lái)源。2. 在電腦上把 Vale 跑起來(lái)安裝和環(huán)境準(zhǔn)備2.1 Windows / macOS / Linux 安裝Vale 提供全局二進(jìn)制安裝方式取決于你的系統(tǒng)。macOS 且使用 Homebrew可以直接安裝brew install valeWindows 如果使用 Chocolatey 或 Scoop也可以從包管理器安裝例如choco install vale不想用包管理器也沒(méi)關(guān)系。去它的 GitHub Releases 頁(yè)面下載對(duì)應(yīng)系統(tǒng)的壓縮包解壓后得到一個(gè)vale可執(zhí)行文件把它放到PATH目錄或者放指定目錄后在命令里寫(xiě)全路徑。安裝完成后先確認(rèn)命令可用vale --version能正常打印版本號(hào)說(shuō)明環(huán)境沒(méi)問(wèn)題。后面所有配置都和這個(gè)命令聯(lián)動(dòng)所以這一步別跳過(guò)。2.2 驗(yàn)證命令和最小示例Vale 不是裝完就能檢查文本的。它要求目錄里有一個(gè).vale.ini配置文件并且配置文件里指定的樣式目錄存在。如果直接對(duì)沒(méi)有配置的目錄執(zhí)行會(huì)提示缺少配置或樣式。我建議把第一次嘗試拆成三步建目錄、放配置、跑一個(gè)測(cè)試文件。先創(chuàng)建一個(gè)臨時(shí)目錄mkdir vale-demo cd vale-demo在目錄里新建一個(gè)最簡(jiǎn)單的.vale.iniStylesPath styles MinAlertLevel suggestion [*.md] BasedOnStyles Demo再創(chuàng)建樣式目錄和測(cè)試文件mkdir -p styles/Demo touch styles/Demo/example.yml touch test.mdtest.md里隨便寫(xiě)一段英文This is a demo document for testing Vale.然后運(yùn)行vale test.md如果styles/Demo/example.yml是空文件Vale 會(huì)認(rèn)為該目錄下沒(méi)有可用的規(guī)則輸出會(huì)顯示“沒(méi)有發(fā)現(xiàn)問(wèn)題”或者提示規(guī)則為空。這很正常因?yàn)橐?guī)則還沒(méi)寫(xiě)。2.3 文件格式和第一份配置Vale 默認(rèn)支持常見(jiàn)文檔格式包括 Markdown、HTML、LaTeX、AsciiDoc、reStructuredText、純文本等。它會(huì)根據(jù)文件擴(kuò)展名自動(dòng)判斷解析方式。如果你項(xiàng)目的文檔不是默認(rèn)擴(kuò)展名可以在配置里加一個(gè)[formats]段做映射[formats] myext md這樣.myext文件會(huì)按 Markdown 解析。這里有個(gè)容易忽略的點(diǎn)Vale 的配置是分作用域的。[*.md]表示只對(duì) Markdown 文件啟用后面的規(guī)則但如果不加[*.md]而直接寫(xiě)B(tài)asedOnStyles通常對(duì)所有文件生效。實(shí)際項(xiàng)目中我建議按文件類(lèi)型區(qū)分因?yàn)榧夹g(shù)文檔和 HTML 頁(yè)面的寫(xiě)法規(guī)范往往不一樣。.vale.ini里幾個(gè)核心字段需要先理解StylesPath規(guī)則目錄路徑也就是存放樣式文件的目錄。MinAlertLevel最低告警級(jí)別可以是suggestion、warning、error。Vocab項(xiàng)目詞匯表用于處理人名、產(chǎn)品名、專(zhuān)有名詞。Packages需要從遠(yuǎn)程拉取的樣式包列表。[*.md]glob 匹配模式指定規(guī)則作用于哪些文件。基礎(chǔ)配置不需要一次全部寫(xiě)滿先跑通最小集更好。3. 配置 .vale.ini把規(guī)則目錄和檢查范圍理清楚3.1 StylesPath 和基礎(chǔ)字段StylesPath是 Vale 最核心的配置。它指向一個(gè)目錄里面放所有.yml規(guī)則文件和Vocab詞匯目錄。路徑可以用相對(duì)路徑也可以寫(xiě)絕對(duì)路徑。我習(xí)慣用相對(duì)路徑比如項(xiàng)目根目錄下的styles目錄這樣對(duì)應(yīng)倉(cāng)庫(kù)遷移時(shí)配置不會(huì)失效StylesPath styles如果你的團(tuán)隊(duì)成員各自 clone 項(xiàng)目路徑是相對(duì)項(xiàng)目根的維系列表就少踩坑。MinAlertLevel的作用是過(guò)濾告警級(jí)別。比如MinAlertLevel warning那么suggestion級(jí)別的提示就不會(huì)輸出。這個(gè)字段很適合剛引入 Vale 時(shí)使用。團(tuán)隊(duì)第一次接入可以先只輸出error避免一堆 suggestion 刷屏等大家接受之后再把級(jí)別放開(kāi)。BasedOnStyles的作用是快速加載某個(gè)樣式目錄下的所有規(guī)則。比如[*.md] BasedOnStyles DemoVale 會(huì)加載styles/Demo下的所有.yml文件。這個(gè)機(jī)制的好處是不用每條規(guī)則單獨(dú)列壞處是目錄里的規(guī)則如果沒(méi)整理好可能誤傷很多文檔。如果你只想啟用某幾條規(guī)則不推薦無(wú)腦加載整個(gè)目錄?？梢愿某蒣*.md] Demo.禁用詞 YES Demo.術(shù)語(yǔ)一致性 NO這里Demo是樣式目錄名禁用詞和術(shù)語(yǔ)一致性是目錄里的規(guī)則文件名。實(shí)際使用時(shí)規(guī)則名建議用英文或拼音避免不同終端在文件名處理上出問(wèn)題。3.2 按文件類(lèi)型啟用規(guī)則我給文檔項(xiàng)目做配置時(shí)通常會(huì)區(qū)分幾個(gè)文件類(lèi)型[*.md] BasedOnStyles Demo [*.html] BasedOnStyles Demo Demo.html-specific YES [*.txt] BasedOnStyles Demo Demo.術(shù)語(yǔ)一致性 NO這種寫(xiě)法適合一個(gè)倉(cāng)庫(kù)里同時(shí)存在多種文檔格式的情況。比如md是給開(kāi)發(fā)看的文檔html是給外部用戶看的幫助頁(yè)面兩者的用詞和語(yǔ)氣可以分開(kāi)控制。值得注意的是 glob 匹配是走 Vale 自己的文件匹配邏輯。[*.md]匹配根目錄下的 md 文件[docs/**/*.md]匹配docs目錄下的 md 文件。如果你在子目錄里跑vale .全局文件都會(huì)按對(duì)應(yīng)段配置檢查。配置的優(yōu)先級(jí)是這個(gè)階段最容易混亂的地方同一類(lèi)文件同時(shí)命中多個(gè)配置段時(shí)更具體的匹配會(huì)覆蓋通用配置。如果某條規(guī)則意外沒(méi)生效先看是否被更具體的配置段關(guān)閉了。3.3 Vocab 處理人名、產(chǎn)品名和術(shù)語(yǔ)Vocab是 Vale 處理專(zhuān)有名詞和術(shù)語(yǔ)的機(jī)制。它解決的核心問(wèn)題是規(guī)則里標(biāo)記了某個(gè)詞是錯(cuò)的但文檔里確實(shí)需要出現(xiàn)這個(gè)詞怎么辦。詞匯表目錄結(jié)構(gòu)如下styles/ Vocab/ MyDocs/ accept.txt reject.txt在.vale.ini里聲明使用這個(gè)詞匯表Vocab MyDocsaccept.txt里放允許出現(xiàn)的詞VSCode TypeScript JavaScript GitHubreject.txt里放強(qiáng)制不允許出現(xiàn)的詞VSCode Typescript Javascript Jscript這個(gè)機(jī)制配合spelling類(lèi)規(guī)則很好用內(nèi)置的拼寫(xiě)規(guī)則會(huì)認(rèn)為不在詞典里的詞是拼寫(xiě)錯(cuò)誤accept.txt相當(dāng)于給拼寫(xiě)規(guī)則加白名單而reject.txt明確列出即使拼寫(xiě)正確也不允許使用的形式。實(shí)際項(xiàng)目中我建議把產(chǎn)品名、人名、縮寫(xiě)、團(tuán)隊(duì)內(nèi)部叫法都維護(hù)到accept.txt。這樣規(guī)則報(bào)錯(cuò)時(shí)你一眼就能看出是真正的錯(cuò)誤還是專(zhuān)有名詞沒(méi)登記。注意Vocab 不是萬(wàn)能開(kāi)關(guān)。如果你沒(méi)有啟用任何與拼寫(xiě)相關(guān)的規(guī)則reject.txt 不會(huì)自動(dòng)檢測(cè)。它是在規(guī)則引擎讀取單詞時(shí)參與候選判斷的不是獨(dú)立檢查器。4. 用手寫(xiě)一個(gè)樣式文件來(lái)理解 Vale 的規(guī)則機(jī)制4.1 YAML 規(guī)則的核心字段規(guī)則文件是 YAML 格式每個(gè)文件通常代表一條規(guī)則。一個(gè)最簡(jiǎn)單的existence規(guī)則長(zhǎng)這樣extends: existence message: 不要使用 %s。 level: warning ignorecase: true tokens: - very - really - basically這種規(guī)則表示只要文本中出現(xiàn)very、really、basically這些詞就產(chǎn)生一條 warning 級(jí)別的提示。message里的%s會(huì)被替換成實(shí)際匹配到的文本。字段含義extends規(guī)則類(lèi)型。message告警時(shí)輸出的提示文字。level告警級(jí)別可以是suggestion、warning、error。ignorecase匹配時(shí)是否忽略大小寫(xiě)。tokens需要匹配的詞或正則表達(dá)式。scope檢查范圍常見(jiàn)取值有text、sentence、heading等。scope的作用很關(guān)鍵。比如你想只檢查標(biāo)題里有沒(méi)有某個(gè)詞就寫(xiě)extends: existence message: 標(biāo)題里不要使用 %s。 level: error scope: heading tokens: - TODO這樣正文里出現(xiàn) TODO 不會(huì)報(bào)警只有標(biāo)題里出現(xiàn)才會(huì)提示。這種細(xì)化能讓規(guī)則更精準(zhǔn)避免誤報(bào)。4.2 從 existence 到 substitutionexistence只能檢測(cè)某個(gè)詞是否存在適合“禁用詞”場(chǎng)景。但更多時(shí)候你希望不僅提示“這個(gè)詞不對(duì)”還要告訴作者“應(yīng)該改成什么”這時(shí)候用substitution類(lèi)型的規(guī)則。一個(gè)典型例子extends: substitution message: 建議使用 %s不要使用 %s。 level: warning swap: utilize: use a lot of: many in order to: toswap是一個(gè)映射表左邊是應(yīng)該避免的詞右邊是建議替換的詞。Vale 在匹配到utilize時(shí)會(huì)輸出一條替換建議且提示文本里會(huì)帶上兩個(gè)詞。這種規(guī)則特別適合團(tuán)隊(duì)術(shù)語(yǔ)表落地。比如禁止使用click on要求使用click。禁止使用login作為名詞要求使用log in。禁止使用info要求使用information。每一條都可以寫(xiě)成swap里的一個(gè)映射積累一段時(shí)間后一份很厚的術(shù)語(yǔ)表就變成了一套可自動(dòng)執(zhí)行的規(guī)則。existence和substitution是寫(xiě)規(guī)則時(shí)最常用的兩種先把它們用熟比堆很多復(fù)雜類(lèi)型更有價(jià)值。4.3 用 occurrence、conditional 處理上下文existence只能判斷是否存在無(wú)法判斷“出現(xiàn)幾次”和“前后文關(guān)系”。如果你希望限制某個(gè)詞的出現(xiàn)次數(shù)比如一個(gè)句子里however最多出現(xiàn)一次可以寫(xiě)occurrence類(lèi)型規(guī)則extends: occurrence message: 不要在一句話里使用超過(guò)一次 %s。 level: warning scope: sentence max: 1 tokens: - howeveroccurrence會(huì)統(tǒng)計(jì)tokens在指定scope內(nèi)出現(xiàn)的次數(shù)超過(guò)max時(shí)觸發(fā)提示。這類(lèi)規(guī)則適合處理“用詞重復(fù)”或者“某一類(lèi)連接詞過(guò)密”的問(wèn)題。如果你需要處理“前面出現(xiàn)了某個(gè)詞后面就不能出現(xiàn)另一個(gè)詞”的場(chǎng)景可以看conditional類(lèi)型規(guī)則。它的用途是表達(dá)上下文限制比如“如果標(biāo)題里出現(xiàn)了will后面就不要跟著be able to”。這類(lèi)規(guī)則的字段會(huì)比 existence 多一點(diǎn)常見(jiàn)的是first、second、exceptions。實(shí)際使用中我會(huì)先手寫(xiě)一個(gè)簡(jiǎn)單的 existence 規(guī)則驗(yàn)證思路再慢慢換成 conditional。原因是 conditional 涉及前后順序和匹配范圍調(diào)起來(lái)更容易遇到邊界問(wèn)題。把這個(gè)機(jī)制想明白之后你就會(huì)發(fā)現(xiàn) Vale 的規(guī)則不是一成不變的死字典而是可以表達(dá)比較復(fù)雜判斷的檢查器。理解了這個(gè)后面批量接入就不慌了。5. 從單文件檢查到批量文檔與 CI 集成5.1 命令行批量操作和輸出格式Vale 最簡(jiǎn)單的用法是檢查單個(gè)文件vale test.md也可以一次檢查多個(gè)文件vale docs/api.md docs/guide.md目錄檢查更常用vale docs/如果要匹配某個(gè)目錄下的所有 Markdown 文件建議加引號(hào)防止 shell 先展開(kāi)vale docs/**/*.md批量任務(wù)里我一般會(huì)在命令最后加上--no-wrap避免輸出被終端寬度自動(dòng)換行一方面看起來(lái)亂另一方面不方便復(fù)制告警內(nèi)容。Vale 還支持不同輸出格式。默認(rèn)輸出是適合人看的格式但在腳本里解析不好用。如果你想把檢查結(jié)果接到自己的流程里可以輸出 JSONvale --outputJSON docs/JSON 結(jié)果包含文件路徑、行號(hào)、列號(hào)、規(guī)則名、消息、級(jí)別等信息。這樣無(wú)論是給 CI 做統(tǒng)計(jì)還是給內(nèi)部工具做展示都方便。如果想在腳本里只關(guān)心錯(cuò)誤級(jí)別可以覆蓋配置里的最低告警級(jí)別vale --min-alert-levelerror docs/這樣只輸出 error 級(jí)別的告警suggestion 和 warning 一律忽略。CI 階段用這個(gè)命令最合適。5.2 編輯器插件與本地反饋命令行適合批量跑和 CI但寫(xiě)文檔時(shí)最好還是在編輯器里直接看到提示。Vale 官方提供 VS Code 擴(kuò)展。安裝后它會(huì)在你打開(kāi)項(xiàng)目時(shí)讀取.vale.ini并在編輯 Markdown 文件時(shí)不斷給出告警。效果很像代碼編輯器里的 lint 提示哪一行有問(wèn)題鼠標(biāo)放上去就能看到規(guī)則說(shuō)明。我用下來(lái)覺(jué)得編輯器插件的最大價(jià)值是規(guī)則能從“CI 報(bào)錯(cuò)”變成“寫(xiě)的時(shí)候就知道”。尤其是新成員不熟悉團(tuán)隊(duì)寫(xiě)作規(guī)范時(shí)邊寫(xiě)邊被提示能減少大量返工。如果你用的不是 VS Code也可以通過(guò)命令行和編輯器任務(wù)機(jī)制接入。具體能不能做到最低延遲要看你編輯器的任務(wù)運(yùn)行方式但 Vale 的命令行接口足夠小接入并不復(fù)雜。5.3 CI 中配置 Vale 的通用思路把 Vale 接入 CI是讓團(tuán)隊(duì)統(tǒng)一寫(xiě)作規(guī)范的最關(guān)鍵一步。沒(méi)有 CI 強(qiáng)制執(zhí)行本地跑不跑全看個(gè)人自覺(jué)。基礎(chǔ)流程是安裝 Vale。拉取或檢查樣式包。運(yùn)行 Vale 檢查文檔目錄。根據(jù)退出碼判斷是否中斷流水線。GitHub 項(xiàng)目里官方提供errata-ai/vale-action可以直接在 workflow 中使用。通用的做法是讓 action 讀取項(xiàng)目根目錄下的.vale.ini檢查docs/目錄并將注釋寫(xiě)回 PR。如果你不用 GitHub也完全可以自己在 Jenkins、GitLab CI 里跑命令。核心就三步vale sync vale docs/vale sync會(huì)根據(jù).vale.ini里的Packages字段拉取遠(yuǎn)程樣式包。如果團(tuán)隊(duì)不需要遠(yuǎn)程包只使用本地 styles 目錄這一步可以跳過(guò)。CI 接入有個(gè)建議第一次不要開(kāi)全部規(guī)則。哪怕你已經(jīng)寫(xiě)了很多規(guī)則也先只用warning級(jí)別跑幾天讓團(tuán)隊(duì)成員理解和適應(yīng)規(guī)則再慢慢收緊。規(guī)則質(zhì)量遠(yuǎn)比規(guī)則數(shù)量重要一堆誤報(bào)很容易讓大家對(duì) Vale 失去信任。6. 實(shí)測(cè)時(shí)最容易踩的幾個(gè)坑6.1 默認(rèn)配置不夠用包也要有取舍Vale 安裝后并沒(méi)有內(nèi)置任何文本規(guī)則。這意味著你需要自己提供樣式或者從樣式倉(cāng)庫(kù)拉取別人維護(hù)的規(guī)則。常見(jiàn)的做法是在.vale.ini里配置Packages然后執(zhí)行vale sync拉取。比如引入一些社區(qū)維護(hù)的英文寫(xiě)作風(fēng)格包。這些包的好處是開(kāi)箱即用壞處是規(guī)則噪音比想象中大。我自己實(shí)測(cè)的感受是不要一次引入太多包。兩個(gè)風(fēng)格包疊加經(jīng)常會(huì)出現(xiàn)同一句話報(bào)三四個(gè)不同建議里面一半是“可以用更好表達(dá)”這類(lèi)主觀提醒對(duì)團(tuán)隊(duì)沒(méi)有實(shí)際約束力反而讓真正需要關(guān)注的 error 被淹沒(méi)。建議選一個(gè)包跑完整批文檔把誤報(bào)規(guī)則關(guān)掉或降級(jí)再?zèng)Q定要不要引入第二個(gè)包。6.2 中文場(chǎng)景的邊界Vale 面向英文散文設(shè)計(jì)對(duì)中文的支持是有邊界的。這一點(diǎn)在接入前就要想清楚。中文文本的問(wèn)題是英文按空格分詞Vale 的很多默認(rèn) scope 和詞邊界邏輯依賴空格和標(biāo)點(diǎn)。中文沒(méi)有空格句子拆分會(huì)變得不確定。如果你寫(xiě)一條規(guī)則要求“一句話中不能出現(xiàn)某個(gè)詞超過(guò)一次”對(duì)中文文檔可能不會(huì)按預(yù)期觸發(fā)。但這不意味著中文場(chǎng)景完全不能用。像“禁用詞”“術(shù)語(yǔ)統(tǒng)一”“需要改為指定寫(xiě)法”這類(lèi)基于 token 的檢查中文也能跑。前提是規(guī)則里直接寫(xiě)中文 token并保存為 UTF-8 編碼extends: existence message: 文檔中不要使用 %s。 level: error tokens: - 非常 - 我們 - 請(qǐng)注意還要注意Vale 的正則引擎支持一些 Unicode 屬性但不要指望它做中文分詞和句法分析。如果團(tuán)隊(duì)文檔以中文為主我建議把 Vale 定位成“術(shù)語(yǔ)和禁用詞檢查器”不要拿它當(dāng)完整的中文語(yǔ)法檢查工具。6.3 先看日志和退出碼再改規(guī)則接入過(guò)程中遇到問(wèn)題先別急著改規(guī)則。Vale 的報(bào)錯(cuò)一般分幾類(lèi)配置找不到、樣式目錄不存在、規(guī)則文件名對(duì)不上、規(guī)則語(yǔ)法錯(cuò)誤。我的排查順序是先確認(rèn)vale --version正常。檢查當(dāng)前目錄是否存在.vale.ini以及字段拼寫(xiě)是否正確。確認(rèn)StylesPath指向的目錄真實(shí)存在。運(yùn)行單個(gè)測(cè)試文件并用--outputJSON看完整輸出。如果規(guī)則沒(méi)有生效檢查規(guī)則文件名和你配置里引用的名字是否完全一致。如果規(guī)則報(bào)語(yǔ)法錯(cuò)誤單獨(dú)打開(kāi).yml文件檢查 YAML 縮進(jìn)和引號(hào)。一個(gè)很常見(jiàn)的坑是在.vale.ini里寫(xiě)了BasedOnStyles Demo但實(shí)際目錄名是demo大小寫(xiě)不一致。Vale 在區(qū)分大小寫(xiě)的系統(tǒng)上會(huì)直接找不到樣式。另一個(gè)常見(jiàn)問(wèn)題是規(guī)則文件里用到了正則特殊字符比如*或.結(jié)果匹配范圍比預(yù)期大很多。此時(shí)建議在 tokens 里給特殊字符加轉(zhuǎn)義或者先用一個(gè)非常簡(jiǎn)單的 token 驗(yàn)證規(guī)則路徑通不通。記得先造一個(gè)一定能命中的測(cè)試文本再驗(yàn)證規(guī)則是否真正觸發(fā)。很多時(shí)候規(guī)則沒(méi)報(bào)錯(cuò)不是配置問(wèn)題而是測(cè)試文本里根本沒(méi)有規(guī)則要匹配的詞。7. 更進(jìn)一步的規(guī)則把團(tuán)隊(duì)自己的寫(xiě)作規(guī)范沉淀成 Vale 樣式7.1 從風(fēng)格手冊(cè)到 YAML 規(guī)則團(tuán)隊(duì)如果已經(jīng)有人工維護(hù)的文檔風(fēng)格手冊(cè)那 Vale 規(guī)則可以直接從手冊(cè)里提取。比如手冊(cè)里寫(xiě)著“不要使用 please kindly 這種過(guò)于客套的表達(dá)”就可以轉(zhuǎn)成一條 existence 規(guī)則。寫(xiě)著“產(chǎn)品名稱(chēng)統(tǒng)一使用DataSync不要使用Datasync或data sync”就可以轉(zhuǎn)成 substitution 規(guī)則。我建議按優(yōu)先級(jí)分三批整理第一批硬性錯(cuò)誤。拼寫(xiě)不一致、產(chǎn)品名寫(xiě)錯(cuò)、嚴(yán)重禁用詞。這些規(guī)則直接設(shè)為error。第二批風(fēng)格偏好。冗長(zhǎng)表達(dá)、口語(yǔ)化表達(dá)、建議替換的搭配。這些規(guī)則先設(shè)為warning讓作者自己決定是否修改。第三批需要上下文的檢查。比如標(biāo)題不要用某些詞、正文某類(lèi)詞出現(xiàn)次數(shù)不能過(guò)多。這些規(guī)則比較敏感需要更多測(cè)試再啟用。分批的好處是能控制告警數(shù)量。如果第一次就導(dǎo)入 80 條規(guī)則文檔滿屏飄紅團(tuán)隊(duì)成員很難接受。7.2 維護(hù)和版本管理Vale 的配置和規(guī)則本質(zhì)上是文本文件完全可以納入 Git 倉(cāng)庫(kù)管理。我建議把.vale.ini和整個(gè)styles/目錄放在文檔項(xiàng)目根目錄這樣任何 clone 項(xiàng)目的人都能得到相同的規(guī)則。當(dāng)規(guī)則越來(lái)越復(fù)雜后可以考慮為規(guī)則單獨(dú)建立倉(cāng)庫(kù)然后用 Vale 的Packages機(jī)制按版本拉取Packages https://github.com/your-org/vale-styles然后執(zhí)行vale sync這樣文檔項(xiàng)目只需要維護(hù)一份配置規(guī)則升級(jí)走單獨(dú)倉(cāng)庫(kù)更適合中大型團(tuán)隊(duì)。規(guī)則的變更也應(yīng)該像代碼一樣走 review。每次增加或修改規(guī)則時(shí)最好附上一條能命中的測(cè)試文本和一條不應(yīng)該命中的文本。比如# good: Please read the guide. # bad: Please kindly read the guide.這種注釋看起來(lái)簡(jiǎn)單但后面維護(hù)的人看一眼就知道這條規(guī)則的意圖和邊界。7.3 讓 Vale 成為文檔評(píng)審的一部分而不是替代最后說(shuō)一個(gè)我比較深的體會(huì)Vale 再?gòu)?qiáng)也只能替代文檔評(píng)審里的機(jī)械部分。真正需要人判斷的問(wèn)題比如結(jié)構(gòu)是否合理、內(nèi)容是否準(zhǔn)確、讀者是否能理解這些它做不了。但把術(shù)語(yǔ)、拼寫(xiě)、禁用詞、風(fēng)格偏好這些是是而非的問(wèn)題交給 Vale 處理之后人工 review 的時(shí)間可以更集中在內(nèi)容本身。我實(shí)踐下來(lái)的路徑是先跑一個(gè)最小配置只檢查最重要的幾十個(gè)詞用幾天時(shí)間觀察誤報(bào)率然后把確定性的規(guī)則提升到error接入 CI再根據(jù)團(tuán)隊(duì)反饋慢慢擴(kuò)充規(guī)則集。這個(gè)節(jié)奏比一開(kāi)始就配一個(gè)超全的規(guī)則包要舒服很多。如果你正準(zhǔn)備在項(xiàng)目里引入 Vale我建議你也從最小集開(kāi)始跑通一個(gè)文件再鋪開(kāi)。Linter 的價(jià)值不在于規(guī)則多而在于每一條規(guī)則都穩(wěn)定、可解釋、真的對(duì)團(tuán)隊(duì)有幫助。