如何构建无外部泄露的离线语法检查器 Harper
TuBrief 편집팀
2026년 7월 25일
0
Computing/Software원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
커뮤니티의 다른 글
댓글 (0)
Log in to leave a comment
아직 작성된 글이 없습니다
원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
Log in to leave a comment
아직 작성된 글이 없습니다
受限于公司的安全策略，如果封禁了 Grammarly 等外部 AI 工具，开发者往往会感到头疼。如果在技术文档或代码注释中留下错别字就直接发布，会降低专业可信度；但如果全靠人工肉眼排查，又太浪费时间。
Harper 可以干净利落地解决这个问题。它是一个采用 Rust 开发的离线专用语法检查引擎，完全切断了与外部服务器的通信。与基于 Java 运行、动辄占用数百兆内存的 LanguageTool 不同，Harper 的内存占用仅有十几兆。并且它的响应速度低于 10ms，完全不会导致编辑器变卡。
harper-ls 在终端内部仅使用本地 CPU 资源来进行语法分析。只需使用适配您操作系统的包管理器安装二进制文件，并在编辑器中注册为标准 LSP 即可。
在终端中运行命令以安装二进制文件。
brew install harpercargo install harper-ls --lockedscoop install harper在 Neovim 中，可以使用 nvim-lspconfig 配置目标文件类型和 Linter 规则。
`lua
local lspconfig = require('lspconfig')
lspconfig.harper_ls.setup({
filetypes = { 'markdown', 'gitcommit', 'rust', 'go', 'typescript', 'python' },
settings = {
["harper-ls"] = {
userDictPath = "~/config/harper/user_dict.txt",
workspaceDictPath = ".harper-dictionary.txt",
linters = {
SpellCheck = true,
SpelledNumbers = false,
AnA = true,
SentenceCapitalization = false,
UnclosedQuotes = true,
WrongApostrophe = false,
LongSentences = true,
RepeatedWords = true,
Spaces = true,
CorrectNumberSuffix = true
}
}
}
})
`
在使用 Neovim 0.11 及以上版本的原生 LSP API 时，请配置 vim.lsp.config['harper'] 并调用 vim.lsp.enable('harper')。VS Code 用户只需安装 elijah-potter.harper 扩展程序，然后在 .vscode/settings.json 中指定 "harper.path": "/usr/local/bin/harper-ls" 路径即可。
Harper 内置了 Tree-sitter AST 解析器，因此会跳过实际源代码，仅挑选注释块中的英文文本进行检查。如果您想将某个特定函数的注释完全排除在检查范围之外，可以插入内联指令。
`javascript
// harper:ignore
function processInternalSecurityToken() {
// spellcheck:ignore
// 内部安全令牌逻辑
}
`
如果仅使用默认的英文字典，gRPC、OAuth2、Prometheus 等技术术语都会被判定为错误。利用分层字典结构可以快速消除这些警告噪音。
Harper 通过 4 个层级来校验单词。
| 字典层级 | 保存位置 | 目的 |
|---|---|---|
| Static Dictionary | 内置于 harper-ls 二进制文件中 |
不可修改的默认英文字典数据库 |
| User Dictionary | ~/.config/harper-ls/dictionary.txt |
用于个人开发环境的全域字典 |
| Workspace Dictionary | 项目根目录 .harper-dictionary.txt |
项目专用术语字典（Git 管理） |
| File-Local Dictionary | 保存于 OS 数据路径内 | 单个文件专用的标识符保存 |
.harper-dictionary.txt 文件。`text
Kubernetes
gRPC
OAuth2
OpenTelemetry
Prometheus
mTLS
Netty
Etcd
`
Ctrl + .，Neovim: Code Action 快捷键绑定），即可将该单词直接添加到 .harper-dictionary.txt 中。只需将此文件提交到 Git 仓库，团队所有成员就能共享同一份单词列表。
编写注释时，可以关闭一些繁琐的规则。
SentenceCapitalization: 若要关闭强制要求注释首字母大写的规则，请设置为 false。LongSentences: 考虑到技术文档的特性，若要关闭长句警告，请设置为 false。SpellCheck 及 UnclosedQuotes: 拼写错误和未闭合引号检查请保持为 true。开发者在编辑器中遗漏的错别字应当在 PR 阶段被拦截。将 CLI 工具 harper-cli 连接到流水线中，即可在合并到主分支之前自动过滤语法错误。
在 .github/workflows/harper-lint.yml 文件中定义仅挑选已修改的 Markdown 文件进行检查的任务。
`yaml
name: Technical Documentation Linting
on:
pull_request:
paths:
- 'docs/'
- '.md'
jobs:
harper-grammar-check:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Rust Toolchain
uses: dtolnay/rust-toolchain@stable
- name: Cache Harper CLI Binary
uses: actions/cache@v3
with:
path: ~/.cargo/bin/harper-cli
key: ${{ runner.os }}-harper-cli-${{ hashFiles('**/Cargo.lock') }}
- name: Install Harper CLI
run: |
if ! command -v harper-cli &> /dev/null; then
cargo install harper-cli --locked
fi
- name: Get Changed Markdown Files
id: changed-files
run: |
git fetch origin ${{ github.base_ref }}
FILES=$(git diff --name-only --diff-filter=AM origin/${{ github.base_ref }} HEAD | grep '\.md$' || true)
echo "files=$FILES" >> $GITHUB_OUTPUT
- name: Run Harper Lint Check
if: steps.changed-files.outputs.files != ''
run: |
ERRORS=0
for file in ${{ steps.changed-files.outputs.files }}; do
echo "Linting $file with Harper..."
harper-cli lint "$file" || ERRORS=$((ERRORS+1))
done
if [ $ERRORS -gt 0 ]; then
echo "Harper validation failed with $ERRORS error(s)."
exit 1
fi
`
如果将项目根目录下的 .harper-dictionary.txt 一并提交，CI Runner 也会基于与编辑器相同的单词列表来进行检查。如果您使用的是 MkDocs 或 Docusaurus 等静态网站生成器（SSG），最好配置为在执行构建脚本之前先运行 harper-cli lint docs/ 命令，这样会更加安全。