Harper for Obsidian在笔记库内离线运行的隐私优先语法检查插件实战指南【免费下载链接】harperOffline, privacy-first grammar checker. Fast, open-source, Rust-powered项目地址: https://gitcode.com/GitHub_Trending/har/harper导读本文面向 Obsidian 重度用户与隐私敏感型写作者系统讲解 Harper Obsidian 插件的核心设计理念、安装流程、与 LanguageTool 等在线方案的差异以及基于 packages/obsidian-plugin 源码实现的完整功能与配置能力。阅读本文后你将掌握如何在 Obsidian 中搭建完全本地、不离开 Vault 的实时英文语法检查环境并理解其底层在编辑器内的工作机制Web Worker 引擎、CodeMirror 诊断管线、词库与规则管理等能够独立排查安装问题、按需定制检查规则与忽略策略。一、Harper 是什么把语法检查引擎搬进 Obsidian 内部Harper 是一个不侵犯隐私的语法检查插件原文档原话 a grammar checking plugin that doesnt violate your privacy。与 LanguageTool 等需要把写作内容经由互联网上传到中心化服务器的方案不同Harper 将整个语法检查引擎直接运行在 Obsidian 进程内部。这意味着你的笔记数据不会流向任何你不想让它去的地方你的 Obsidian Vault 依然保持封闭、私有locked down and private的预期状态由于全程在本机计算不存在网络延迟Harper 的实际检查响应速度明显快于依赖网络的替代方案。从源码结构看这一引擎内嵌承诺由两件事保证插件通过 harper.js 的WorkerLinter/LocalLinter加载 Rust 编译而来的 WASM 二进制见 State.ts 中new WorkerLinter({ binary: slimBinaryInlined })引擎作为 npm workspace 依赖被打包进插件不在运行时访问网络。此外Harper 与 Grammarly 之类的产品不同它会显式跳过代码围栏code fences与行内代码块inline code blocks的内容不会对你的代码片段报无意义的错误这对常在笔记中贴代码的开发者尤为友好。开源与可审计性Harper 完全开源任何人都可以审查其代码库并参与贡献从而提升功能与透明度开发者可以直接审查全部实现代码社区可以通过提交 issue 与 PR 参与改进官方文档中明确引导开发者前往主仓库仓库参与贡献。二、Harper 与其他插件的对比原文档给出了 Harper 与 LanguageTool 的对比表要点如下特性HarperLanguageTool隐私100% 离线需要自托管才能保证隐私实时检查是是语言支持英语可扩展30 种语言开源是部分易用性安装简单需要 API / 自托管部署性能快速且轻量资源消耗较大补充一点理解两者都支持实时检查差异集中在数据去向、部署复杂度与语言覆盖范围上。Harper 走引擎内置、数据不出库的路线代价是目前以英语为主引擎在方言层面支持 American/British/Canadian/Australian/Indian见下文方言选择而 LanguageTool 以多语言覆盖见长、隐私则需要自托管来保证。选择哪一款取决于你对隐私、语言种类与部署成本的权衡。三、安装指南在原文档的步骤基础上结合当前仓库的实际交付物完整安装流程如下打开 Obsidian进入Settings → Community Plugins → Browse在插件库中搜索 Harper点击Install然后点击Enable启用直接在笔记中开始输入——Harper 会随输入自动高亮错误并可在错误处悬停查看建议、一键应用替换。WarningHarper 期望较新版本的 Obsidian 安装器。如果遇到异常请重新安装 Obsidian 或更新安装器版本再重试启用插件。如果你希望手动构建插件例如参与开发或验证最新代码当前仓库通过just提供了统一的构建命令见 justfilejust build-obsidian该命令会先构建 harper.js再进入packages/obsidian-plugin执行 vite 构建并将main.js、manifest.json与插件资源打包为harper-obsidian-plugin.zip产物可直接用于手动安装或发布流程。测试命令为just test-obsidian对应插件的 npm 脚本见 package.json为buildvite 构建、devwatch 模式与testvitest 运行单元测试。四、安装后从设置面板到状态栏的完整使用界面Harper 启用后会把自身能力组织为几个可交互入口全部由 index.ts 中的HarperPlugin主类注册编辑器内实时高亮通过registerEditorExtension注入 CodeMirror 扩展见 index.ts错误以下划线标记直接出现在笔记正文中状态栏指示器setupStatusBar在 Obsidian 状态栏加入一个可点击区域显示 Harper logo启用为彩色 logo、停用为灰色 logo与当前方言旗帜US/GB/AU/CA 等由getDialectStatus将方言映射为国旗 emoji点击可弹出菜单快速切换自动检查开/关与忽略文件内所有错误见 index.ts拼写检查侧边栏通过命令打开右侧harper-sidebar-viewSidebarView.ts以卡片列表形式列出当前文档的全部问题每张卡片展示出错单词及前后三个单词的上下文、规则类型标题并提供应用建议忽略诊断禁用规则按钮通过harper:lint-updated事件与编辑器诊断同步见 SidebarView.ts设置页HarperSettingTab提供全部可配置项详见下文。命令面板中的快捷命令插件注册了下列命令见 index.ts可直接在 Obsidian 命令面板中调用或绑定热键命令 ID名称作用harper-toggle-auto-lintToggle automatic grammar checking开/关自动语法检查harper-toggle-sidebarToggle spellcheck sidebar开/关拼写检查侧边栏harper-ignore-all-in-bufferIgnore all errors in the open file忽略当前打开文件中的全部错误带确认弹窗见doIgnoreAllFlowharper-jump-to-next-suggestionJump to next suggestion跳到下一个建议harper-jump-to-previous-suggestionJump to previous suggestion跳到上一个建议harper-apply-suggestion-1~-3Apply suggestion #n直接应用当前悬停提示中的第 13 条建议harper-add-word-to-dictionaryAdd current word to dictionary将当前单词加入个人词典harper-ignore-focused-diagnosticIgnore focused diagnostic忽略当前聚焦的诊断harper-dismiss-focused-tooltipDismiss focused suggestion tooltip关闭当前建议提示框这些命令大多以checkCallback注册仅在满足条件如编辑器有可见诊断时才可用确保键盘操作安全无副作用相关实现见 lint.ts 中的navigateDiagnostic、applySuggestionFromVisibleTooltip等函数。五、设置面板详解方言、词典、延迟与规则管理设置面板由 HarperSettingTab.ts 实现全部配置项如下1. Use Web Worker是否将 Harper 引擎运行在独立线程Web Worker中。默认开启官方描述为以内存为代价换取稳定性与速度。关闭时插件改用同线程的LocalLinter两者的切换逻辑见 State.ts——WorkerLinter与LocalLinter均来自 harper.js加载同一个内置的 slim WASM 二进制slimBinaryInlined。2. English Dialect英语方言下拉框可选五种方言American美式默认、Canadian加式、British英式、Australian澳式、Indian印式。切换后会重建引擎见 State.ts并同步更新状态栏的方言旗帜。3. Activate Harper总开关对应lintEnabled设置用于整体启用或禁用编辑器内的自动检查见 HarperSettingTab.ts。4. Use Web-Style Lints切换错误下划线的渲染样式默认是仿波浪线squiggly underline开启后改为带背景色的直下划线。两种样式以及按 lint 类型分色的主题均定义在 lint.ts 中——每种 lint 类型Spelling、Grammar、Punctuation、Capitalization 等约 20 类都有专属颜色完整配色表见 lintKindColor.ts。5. Mask正则屏蔽用一个符合Rust 正则语法的表达式把某些文本从 Harper 的检查中隐藏起来Hide certain text from Harpers pedantic gaze。该配置会以regex_mask参数传给引擎的organizedLints调用见 State.ts底层对应 harper-core 的 RegexMasker 机制harper-core/src/mask/regex_masker.rs。例如你想跳过形如TODO: xxx的文本可以填写对应的正则。6. Personal Dictionary个人词典以每行一个词的格式维护个人词库人名、地名、惯用术语等。编辑后通过importWords导入引擎见 State.ts文本区与字符串数组的转换由 textUtils.ts 的linesToString/stringToLines完成。你还可以在拼写错误提示上直接点击按钮把当前单词一键加入词典见 State.ts。7. Ignored Files忽略文件按glob 匹配让 Harper 忽略 Vault 中的某些文件例如folder/**忽略单个文件时务必带上扩展名如journal_entry.md。匹配逻辑在编辑器 linter 内用minimatch实现见 State.ts命中忽略规则的文件直接返回空诊断不做任何检查。8. Delay延迟设置改动后到开始检查之间的等待毫秒数滑条范围为-1 10000ms步长 50默认 -1即无延迟立即检查。该值最终传入 CodeMirror linter 的delay配置见 State.ts。9. Rules规则管理设置页底部提供完整的规则管理能力搜索按规则名、显示名或描述实时过滤规则列表单个规则每个规则下拉可选On / Off未显式设置时显示为On (default)或Off (default)即继承引擎默认值分组规则规则按类别分组如拼写、语法、标点等每个分组提供Default / On / Off三态下拉可批量控制组内所有规则并显示mixed混合状态Toggle All Rules一键启用或禁用全部规则覆盖个别设置直到再次修改Reset All to Defaults将全部规则覆盖值重置为默认null不影响其他设置。这些交互背后对应 State.ts 中的几个关键方法getEffectiveLintConfig默认值与覆盖值合并计算实际生效配置、setAllRulesEnabled批量设置、resetAllRulesToDefaults重置、areAnyRulesEnabled判断是否存在启用规则用于切换按钮文案。10. The Danger Zone危险区提供Forget Ignored Suggestions按钮一键清空所有已忽略的诊断记录ignoredLints undefined让之前被忽略的提示重新出现。六、底层原理数据如何在编辑器内完成一次检查结合源码Harper 在 Obsidian 内的工作链路可以概括为一条完整的本地管线引擎初始化插件加载时创建WorkerLinter将 Rust 编译的 WASM 二进制slimBinaryInlined注入 Worker 线程State.tsState类同时充当整个插件的状态中心与业务逻辑层刻意不直接触碰 Obsidian API 以便单元测试见其类注释与 State.test.ts。编辑器扩展注入constructEditorLinter返回一个 CodeMirror linter 扩展State.ts在每次文档变更后按设定的delay调度执行执行时先检查忽略 glob再取全文调用harper.organizedLints(text, { regex_mask })获得结构化诊断。诊断转译引擎返回的每条 lint 被转换为 CodeMirrorDiagnostic包括起止位置、severity、markClass按 lint 类型着色的 CSS 类、HTML 消息渲染函数以及一组可执行ActionReplace/Remove/InsertAfter 三种建议分别对应不同的编辑器 dispatch 逻辑见 State.ts。拼写类错误还会追加一个加入词典动作。渲染与交互诊断由 lint.ts 中的 lint 插件ViewPlugin渲染为下划线/工具提示悬停或键盘聚焦侧边栏通过harper:lint-updated事件见 lint.ts同步刷新错误卡片列表。忽略与禁用诊断提供两级操作——Ignore把该条具体 lint 加入忽略清单并持久化见ignoreLints与Disable把对应规则在lintSettings中设为false相当于在设置面板关闭该规则见 State.ts。整个过程中没有任何一步需要网络请求——这正是隐私优先、快速轻量两点的实现根基。七、代码在哪里Harper Obsidian 插件的全部源码位于主仓库的 packages/obsidian-plugin 目录下核心文件包括src/index.ts插件主类HarperPlugin负责生命周期、命令、状态栏与侧边栏注册src/State.ts状态中心与核心业务逻辑引擎管理、设置初始化、编辑器 linter 构造src/HarperSettingTab.ts设置面板的全部 UI 与配置读写src/lint.tsCodeMirror 诊断渲染、工具提示、键盘导航与命令的底层实现src/SidebarView.ts拼写检查侧边栏视图src/lintKindColor.ts各类 lint 的配色表src/textUtils.ts个人词典/忽略列表与多行文本的转换工具配套单元测试 State.test.ts、lint.test.ts、lintKindColor.test.ts、textUtils.test.ts依赖引擎 harper.js 位于 packages/harper.js其构建脚本与发布配置见 package.json。需要说明的是为了满足 Obsidian 官方对插件发布仓库的要求主仓库同时承担了插件的发布职责——所有代码都集中在当前这个 monorepo 中安装与发布链路统一维护。八、遇到问题或想提功能需求如果在使用中遇到任何问题、有功能需求或任何形式的反馈可以直接在主仓库的 Issues 区新建 issue 提交维护团队会据此跟进。提交时建议附上以下信息以便排查Obsidian 版本Harper 依赖较新的安装器版本升级前请先更新 ObsidianHarper 插件版本问题出现的场景文件类型、是否启用了 Web Worker、是否设置了 Mask 正则或 Ignored Files 等可复现的最小示例文本。结语Harper for Obsidian 的价值主张非常清晰把完整的语法检查能力以开源、离线、内嵌的方式交付给笔记用户让写作辅助与数据隐私不再二选一。通过本文介绍的安装流程、设置面板各项配置以及源码级的工作管线分析你已经能够独立完成插件的安装、调优与问题排查并可根据个人词典、忽略规则、方言与规则开关等维度把 Harper 打磨成贴合自己写作习惯的本地检查工具。更进一步你还可以顺着 packages/obsidian-plugin 的源码与单元测试深入理解甚至参与改进这个插件本身。【免费下载链接】harperOffline, privacy-first grammar checker. Fast, open-source, Rust-powered项目地址: https://gitcode.com/GitHub_Trending/har/harper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考