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