深入解析 Harper：离线隐私语法检查器

本章要解决的问题是如何理解 Harper 这款离线隐私语法检查器的设计理念及其优势。通过阅读本章，你能明白 Harper 为何而生以及它与其他工具的不同之处。

首先，确保你对基本的语法检查工具有一定的了解，并且对隐私保护有基本的认识。

我们先来看一下 Harper 的设计理念。Harper 是一款设计得“刚刚好”的英语语法检查工具。我创建它的原因是厌倦了现有工具的各种缺点。

Grammarly 太贵而且过于干涉用户，建议缺乏上下文并且经常错误百出。此外，使用 Grammarly 意味着你的所有写作都会被发送到他们的服务器上，这引发了严重的隐私问题。

LanguageTool 虽然功能强大，但它需要大量的内存和庞大的数据集，并且速度较慢。

这就是为什么我开发了 Harper：它速度快、占用内存少且完全私密。Harper 可以在几毫秒内完成文档校验，并且只需要不到 LanguageTool 十分之一的内存。

接着看性能方面。Harper 认为任何显著的延迟都是 bug。如果你遇到性能问题，请提交 issue 并尝试修复它。

最后提一下支持的语言和贡献方式。目前 Harper 只支持英语，但核心架构是可以扩展支持其他语言的。如果你有兴趣添加新语言的支持，请查阅贡献指南并提交 PR。

记住一点：选择合适的工具可以大大提高工作效率并保护个人隐私。

本章小结

• Harper 设计理念是提供快速、轻量级且私密的语法检查。
• 相比 Grammarly 和 LanguageTool，Harper 更加高效和安全。
• 性能问题是不可接受的，应该积极反馈并参与改进。
• 支持英语之外的新语言可以通过贡献来实现。

本章要解决的问题是如何在本地环境中快速安装和运行 Harper，确保你可以立即开始进行语法检查。读完本章后，你将能够在自己的机器上设置 Harper，并对文本文件进行基本的语法检查。

前置条件：你需要有一个已经安装 Node.js 和 npm 的环境。确保你的 Node.js 版本至少是 v14.x 或更高。

第一步操作：首先全局安装 harper-ls，这是 Harper 提供的语言服务器接口。

npm install -g harper-ls

这条命令会下载并安装 harper-ls，这样你就可以通过命令行调用它来进行语法检查。

接着验证安装是否成功。

harper-ls --version

如果一切正常，你应该能看到 harper-ls 的版本号输出。

如果你遇到权限问题，可以在命令前加上 sudo：

sudo npm install -g harper-ls

然后我们可以测试一下 harper-ls 是否能正常工作。创建一个简单的文本文件 test.txt，里面包含一些拼写或语法错误的内容。

Thi is a smple text with erors.

接着运行以下命令来检查这个文件：

cat test.txt | harper-ls

预期的结果是在终端中看到类似如下的错误信息：

[error] Thi (line 1, col 1): Did you mean 'This'?
[error] smple (line 1, col 9): Did you mean 'simple'?
[error] erors (line 1, col 23): Did you mean 'errors'?

记住一点：每次修改完代码或者重新启动系统后，都需要确认 harper-ls 是否仍然可以正常使用。

一个小例子：假设你在编写一篇关于技术的文章，保存为 article.md 文件。你可以随时使用以下命令来检查文章中的语法错误：

cat article.md | harper-ls

这样可以帮助你在写作过程中及时发现并修正潜在的错误。

本章小结

• 使用 npm install -g harper-ls 全局安装 Harper 的语言服务器接口。
• 验证安装是否成功的方法是查看版本号。
• 使用 cat filename | harper-ls 来检查文件中的语法错误。
• 注意权限问题可能需要使用 sudo 进行安装。

本章要解决的问题是如何理解 Harper 如何实现快速语法检查。读完这章，你会明白 Harper 的设计原理以及它是如何高效地进行语法检查的。

前置条件：你需要已经全局安装了 harper-ls 并且能够通过命令行调用它。

我们先来看一下 Harper 的性能优势。首先，运行以下命令来检查一个较大的文本文件：

time cat large_text_file.txt | harper-ls > /dev/null

这条命令会输出处理时间，帮助你感受 Harper 的速度。预期结果是你应该能看到非常短的时间值，比如几十毫秒到几百毫秒之间。

接着，我们看看 Harper 是怎么做到如此高效的。打开项目的 GitHub 页面，在 README 中找到 "Performance Issues" 部分。这里提到了几个关键点：

• Harper 认为任何显著的延迟都是 bug。
• 如果你遇到性能问题，请创建 issue 报告。
• 如果你能解决问题，请贡献修复代码。

为了更好地理解这些信息，我们可以通过查看源码来探究一下。首先克隆项目仓库：

git clone https://github.com/Automattic/harper.git
cd harper

然后我们可以查看一些主要的文件和目录：

• src/core/: 这里包含了核心逻辑。
• src/languages/en/: 英语语法规则的具体实现。

如果你想进一步了解具体的实现细节，可以从 src/core/parser.ts 开始看起。这是一个 TypeScript 文件，定义了基本的解析逻辑。

一个小例子：假设你想知道某个单词被标记为拼写错误的原因。你可以尝试修改一个已知正确的单词，让它变成错误的形式，然后再次运行检查命令：

echo "Thi is a simple test." > test_error.txt
cat test_error.txt | harper-ls

你应该会看到类似 [error] Thi (line 1, col 1): Did you mean 'This'? 的输出。这意味着 Harper 内部有一个词典或者某种匹配算法来检测拼写错误，并给出建议。

如果你遇到 [error] Thi (line 1, col 1): Did you mean 'This'? 类似的错误但是不确定为什么会被标记为错误，可以尝试在 src/languages/en/spelling.ts 查找相关的拼写检查逻辑。

本章小结

• 使用 time cat filename | harper-ls > /dev/null 测试 Harpers 处理大型文本文件的速度。
• 性能问题是 Harpers 视为 bug 的一部分，并鼓励用户报告和修复这些问题。
• 查看项目的 GitHub 源码可以深入了解 Harpers 的内部工作原理。
• 修改测试文件内容可以帮助理解具体哪些部分触发了语法错误提示。

本章要解决的问题是在 VSCode 中集成 Harper，让你能够在编辑文本时实时获得语法检查。完成本章后，你可以在 VSCode 中直接使用 Harper 进行语法检查。

前置条件：确保你已经安装了 VSCode 和 Harper CLI 工具，并且熟悉基本的 VSCode 使用方法。

第一步操作：打开 VSCode 并进入扩展市场。

code --install-extension ms-vscode.cpptools # 示例命令，实际不需要运行

这个命令只是示例，真正要在 VSCode 内部操作。点击左侧活动栏中的扩展图标，搜索 "Harper" 或者 "Language Server Protocol" 插件。

第二步操作：安装适用于 VSCode 的 LSP（Language Server Protocol）客户端插件。

code --install-extension golang.go # 示例命令，实际不需要运行

同样，在扩展市场中找到并安装 "Language Server Protocol" 相关插件，例如 "vscode-languageclient"。

第三步操作：创建一个配置文件来连接 Harper 作为 LSP 服务器。

// .vscode/settings.json
{
    "languageserver": {
        "harperls": {
            "command": "harper-ls",
            "filetypes": ["markdown", "plaintext"],
            "rootPatterns": [],
            "trace.server": "verbose"
        }
    }
}

这段代码添加到你的项目 .vscode/settings.json 文件中。如果没有该目录或文件，请手动创建。

第四步操作：重启 VSCode 使设置生效。

code .

直接运行上述命令重新启动 VSCode，或者通过菜单栏选择 File -> Restart.

第五步操作：打开一个文本文件进行测试。

echo "# Test Document\nThis is a simple test." > test.md && code test.md

这条命令创建了一个简单的 Markdown 文件并在 VSCode 中打开它。你应该能看到实时的语法检查效果。

如果你遇到 command not found: harper-ls 错误，请确认 Harper CLI 是否正确安装并且路径已添加到系统 PATH 环境变量中。可以通过以下命令验证：

which harper-ls

一个小例子：假设你在编写一篇 Markdown 文档时输入了错误的语法，比如少了个引号导致链接格式不对。保存文件后，VSCode 应该会高亮显示错误位置，并提供修正建议。

本章小结

• 在 VSCode 扩展市场中寻找合适的 LSP 客户端插件。
• 配置 .vscode/settings.json 来指定 Harper 作为 LSP 服务器。
• 确保 Harper CLI 正确安装并且路径在系统 PATH 变量内。
• 创建并测试一个 Markdown 文件以验证集成是否成功。

本章要解决的问题是在 Neovim 中集成 Harper，让你能够利用它的语法检查功能来提高写作效率。读完这章后，你能够在 Neovim 编辑 Markdown 或其他支持的语言文件时享受到实时的语法检查。

前置条件：确保你已经按照上一章完成了 Harper 的安装，并且 Neovim 已经正确安装在你的系统上。

第一步操作：安装 Neovim 插件管理器。这里推荐使用 packer.nvim。

git clone --depth 1 https://github.com/wbthomason/packer.nvim\
 ~/.local/share/nvim/site/pack/packer/start/packer.nvim

这条命令克隆了 packer.nvim 到你的 Neovim 插件目录下。

接着，编辑你的 init.lua 文件（如果没有则创建一个）。

-- init.lua
require('packer').startup(function(use)
  use 'wbthomason/packer.nvim'
end)

这段代码初始化了 Packer 并将其自身列为第一个插件。

第二步操作：重启 Neovim 后，运行 PackerSync 来同步插件。

:PackerSync

执行这个命令会在终端中看到 Packer 下载并安装所需的插件。

第三步操作：在 init.lua 中添加 Harper 相关的配置。

-- init.lua 继续添加
use {
  'neovim/nvim-lspconfig',
  config = function()
    require'lspconfig'.harper.setup{}
  end
}

这段代码引入了 nvim-lspconfig 插件，并设置了 Harper 作为 LSP 服务器。

第四步操作：保存并退出 init.lua，然后再次运行 PackerSync 来安装新添加的插件。

:PackerSync

这次会下载并设置好 nvim-lspconfig 和 Harper 的配置。

第五步操作：打开一个 Markdown 文件进行测试。

echo "# Test Document\nThis is a simple test." > test.md && nvim test.md

这条命令创建了一个简单的 Markdown 文件并在 Neovim 中打开它。你应该能看到实时的语法检查效果。

如果你遇到 E5108: Error executing lua ... 错误，请确认 nvim-lspconfig 是否正确安装并且 Harper CLI 是否在系统 PATH 内。可以通过以下命令验证：

which harper-ls

一个小例子：假设你在编写一篇 Markdown 文档时输入了错误的语法，比如少了个引号导致链接格式不对。保存文件后，Neovim 应该会高亮显示错误位置，并提供修正建议。

本章小结

• 使用 Packer 管理 Neovim 插件。
• 添加并配置 nvim-lspconfig 插件以启用 Harper 的 LSP 支持。
• 创建并测试一个 Markdown 文件以验证集成是否成功。

本章要解决的问题是在 Emacs 中集成 Harper，让你能在编辑 Markdown 或其他文本文件时享受到实时语法检查的好处。完成本章后，你将在 Emacs 中成功配置 Harper 并能即时看到语法错误提示。

前置条件：确保你已经安装了 Emacs，并且熟悉基本操作。此外，你需要有一个可以正常工作的 Harper CLI 工具，可以通过以下命令检查：

which harper-ls

如果没有输出路径，请先按照前几章的方法安装 Harper。

第一步操作：安装 lsp-mode 和 lsp-ui 插件。首先打开你的 Emacs 配置文件（通常是 ~/.emacs.d/init.el），然后添加以下代码：

(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)

(unless (package-installed-p 'use-package)
  (package-refresh-contents)
  (package-install 'use-package))

(eval-and-compile
  (setq use-package-always-ensure t))

(use-package lsp-mode
  :commands lsp-deferred
  :hook ((markdown-mode . lsp-deferred)))

(use-package lsp-ui
  :after lsp-mode)

这段代码会自动下载并安装 lsp-mode 和 lsp-ui 插件，并在 Markdown 模式下启动 LSP 支持。

第二步操作：配置 lsp-mode 使用 Harper 作为语言服务器。继续在你的 Emacs 配置文件中添加以下内容：

(setq lsp-clients-harper-executable "/path/to/harper-ls")
(defun setup-harper ()
  (setq-local lsp-enabled-clients '(harper)))
(add-hook 'markdown-mode-hook #'setup-harper)

记得将 /path/to/harper-ls 替换为你实际的 harper-ls 可执行文件路径。这行代码设置了 Harper 的可执行路径，并将其指定为 Markdown 模式的默认 LSP 客户端。

第三步操作：重新加载 Emacs 配置以应用更改。你可以通过按 Ctrl+x Ctrl+f ~/.emacs.d/init.el 打开配置文件，然后按 Ctrl-x Ctrl-s 保存并退出，最后按 Alt+x eval-buffer 运行整个缓冲区中的所有 Elisp 代码来完成这一步。

第四步操作：打开一个 Markdown 文件进行测试。

echo "# Test Document\nThis is a simple test." > test.md && emacsclient -n test.md

这条命令创建了一个简单的 Markdown 文件并通过 EmacsClient 在后台实例中打开它。你应该能看到实时的语法检查效果。

如果你遇到 (void-function lsp-deferred) 错误，请确认是否正确安装了 use-package 和相关依赖包。可以通过 MELPA 包管理器手动安装这些包：

M-x package-refresh-contents RET
M-x package-install RET use-package RET
M-x package-install RET lsp-mode RET
M-x package-install RET lsp-ui RET

一个小例子：假设你在编写一篇 Markdown 文档时输入了错误的语法，比如少了个引号导致链接格式不对。保存文件后，Emacs 应该会在有问题的地方显示错误标记，并可能弹出修正建议窗口。

本章小结

• 在 Emacs 中使用 use-package 安装并配置了 lsp-mode 和 lsp-ui。
• 设置了 Harper CLI 路径并将其指定为 Markdown 模式的默认 LSP 客户端。
• 创建并测试了一个 Markdown 文件以验证集成是否成功。

本章要解决的问题是帮助你处理在使用 Harper 过程中可能会遇到的一些常见问题，并提供一些优化技巧来提升你的使用体验。

前提是你已经按照前几章的步骤成功安装并配置了 Harper，在不同的编辑器中进行了集成，并且能够看到基本的语法检查效果。

第一步操作：检查性能问题

time harper check test.md

这个命令会输出检查 test.md 文件所需的时间。如果时间超过几秒钟，说明可能存在性能问题。

如果你遇到长检查时间，可以尝试以下方法：

1. 减少文件大小：确保每次检查的文件不是特别大。
2. 更新软件：确保你使用的 Harper 是最新版本。
3. 禁用不必要的插件：有时候其他插件会影响性能。

第二步操作：处理内存占用过高

htop

运行这个命令查看系统资源使用情况，特别是内存占用。如果发现 Harper 占用了过多内存，考虑以下优化：

• 减少同时打开的大文件数量。
• 使用轻量级的编辑器或 IDE。
• 如果是在服务器环境中运行，增加物理内存或调整虚拟内存设置。

第三步操作：调试常见错误信息 例如，如果你遇到了类似 Error: ENOENT: no such file or directory 的错误：

ls -l /path/to/file

这表明指定路径下的文件不存在。请检查文件路径是否正确。

第四步操作：利用 WebAssembly 提升速度和便携性

npm install @writewithharper/webassembly

通过 npm 安装 WebAssembly 版本的 Harper 可以让你在浏览器或其他支持 WebAssembly 的环境中更快地进行语法检查。

一个小例子：假设你在开发过程中经常需要对大量文档进行快速检查。你可以结合 WebAssembly 版本和脚本来批量处理这些文档：

const { run } = require('@writewithharper/webassembly');

async function checkDocuments() {
    const files = ['doc1.md', 'doc2.md'];
    for (let file of files) {
        try {
            let result = await run(file);
            console.log(`Check results for ${file}:`, result);
        } catch (error) {
            console.error(`Error checking ${file}:`, error);
        }
    }
}

checkDocuments();

本章小结

• 学习了如何检测和解决 Harper 的性能问题。
• 掌握了监控内存使用的方法，并了解了一些优化策略。
• 知道了如何调试常见的错误信息。
• 尝试了使用 WebAssembly 来提高语法检查的速度和便携性。

安装报错：如何解决 "missing dependencies" 错误？

在安装 Harper 时遇到 "missing dependencies" 错误通常是因为缺少必要的库或工具。请确保你已经安装了 Rust 编译器和 Cargo 包管理器。可以通过以下命令安装：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

然后重新尝试安装 Harper。

环境/依赖：Harper 是否需要特定版本的 Rust？

Harper 是用 Rust 编写的，建议使用最新稳定版的 Rust 来避免兼容性问题。你可以通过以下命令更新你的 Rust 版本：

rustup update stable

配置：如何配置 Harper 在 Visual Studio Code 中使用？

要在 Visual Studio Code 中使用 Harper，请先确保你已经安装了 harper-ls 插件。然后，在 VSCode 的设置中搜索 harper 并根据提示进行配置。详细步骤可以参考 VSCode 文档。

使用误区：为什么我在使用 Harper 时没有看到任何语法检查结果？

如果未看到语法检查结果，请确认已正确安装并启动了语言服务器 (harper-ls)，并且编辑器已连接到该服务。此外，确保正在编辑的是支持的语言文件（目前仅支持英文）。如仍有问题，请查看编辑器的日志以获取更多信息。

性能问题：Harper 检查文档速度慢怎么办？

如果发现 Harper 检查文档的速度较慢，首先确认是否为大型文档导致的问题。对于普通大小的文档，Harper 应该能在毫秒级完成检查。若持续存在性能问题，请提交一个 issue 到项目的 GitHub 页面，并提供相关细节以便我们诊断。

私隐保护：Harper 如何保证用户数据的安全性和隐私？

Harper 设计为离线运行的应用程序，不会将用户的文本发送至远程服务器进行处理。这意味着所有语法检查都在本地设备上完成，从而有效保护了用户的隐私安全。

与其他工具对比：相比 Grammarly 和 LanguageTool，Harper 的优势是什么？

与 Grammarly 相比，Harper 提供免费且私密的服务，无需担心个人数据被上传；相较于 LanguageTool，则具有更快的速度及更低的内存占用率（约为其 1/50）。同时它还支持 WebAssembly 加载方式，在浏览器端也能实现高效的语法校验功能。

支持的语言：除了英语之外，未来还会增加对哪些语言的支持？

目前 Harper 主要针对英语进行了优化和支持开发工作。不过由于其架构设计良好、具备扩展性，因此欢迎社区贡献者加入进来共同完善其他语种的功能模块建设。具体进度可关注项目的官方动态或参与其中贡献力量。