企业官网建设流程全解析

如何向 Harper 的精选词典提交新词？

【免费下载链接】harperOffline, privacy-first grammar checker. Fast, open-source, Rust-powered项目地址: https://gitcode.com/GitHub_Trending/har/harper

Harper 的精选词典（curated dictionary）是它分析英文文本时使用的内置参考词典，收录了通用英语词汇。遇到技术术语等未收录的词时，官方提供的路径是直接向仓库提交一个 PR 把词加进去。本文给出从环境准备、加词、本地验证到提交 PR 的完整操作路径。

先了解要改的哪两个文件

贡献文档明确说明，向词典加词只需要关心仓库里的两个文件：

• harper-core/dictionary.dict：词表本体，每行一个词条，格式是单词/标志位，例如文件开头的ADHD/N、AES/N。
• harper-core/annotations.json（旧名affixes.json）：定义上面那些标志位。它分affixes和properties两个区段：affixes 是变形规则（如加前缀/后缀派生出新词形），properties 只给词附元数据（词性、是否专有名词等）。

举文档里的例子：affixes中的L定义为-ment后缀规则，所以任何带L标记的词（如 "move"）都会额外展开出 "movement" 这一个词典条目：

{ "L": { "#": "'-ment' suffix", "kind": "suffix", "cross_product": true, "replacements": [ { "remove": "", "add": "ment", "condition": "." } ], "target": {}, "base_metadata": {} } }

这套格式和hunspell的词典格式有些相似，主要差别在元数据字段。加名词这类常见操作不需要手写这些规则，仓库自带了工具。

准备环境

在 环境文档 中，Harper 说明：如果只操作核心语法引擎、harper-ls或harper-cli，只需要安装cargo，项目遵循标准 Rust 约定。但加词流程会用到根目录 justfile 里的 recipe，这些 recipe 是 bash 脚本，因此还需要just和bash在$PATH中可用。

clone 仓库后，用just --list确认工具链能正常工作：

just --list

Nix 用户可以直接nix develop进入自带全部工具的 shell。文档还建议在动手前跑just setup填充构建缓存并下载依赖——该命令会执行全部构建和测试，耗时长，如果只是加词，按需执行即可。

先确认这个词是否已收录

添加前先检索，避免重复提交：

just search-dict-for <word>

<word>替换为要查询的单词。这个 recipe 用harper-cli输出词典全部单词并过滤（有rg时走rg，否则走grep），有输出即说明词已在词典里。

还可以看词已有元数据与全部变形：

just get-metadata <word> just get-forms <word>

get-forms会按annotations.json中的词缀规则列出该词的所有派生形式。

用 addnoun 添加名词

加名词的主路径是一条命令：

just addnoun <word>

<word>替换为要添加的名词。这条 recipe 会修改 harper-core/dictionary.dict，在文件末尾追加一行word/flags；如果grep "^word/"已能命中，它会打印 "That noun may already be in the dictionary." 并直接退出，不改动文件。

从 justfile 的实现可以看出标志位是自动决定的：

• 所有词都加g：共同名词与专有名词的's所有格后缀；
• 首字母大写时追加O（专有名词，通常无复数），视为 proper noun；
• 其余情况追加NS（普通单数名词 +-es复数变形）。

所以小写的普通名词会写入word/gNS，大写的专有名词会写入Word/gO。

本地验证

添加后按下面顺序检查：

just get-metadata <word> just get-forms <word>

前者输出该词在词典中的元数据（JSON），后者确认gNS/gO等标志位按预期展开出所有格与复数形式。

再跑一次词典审计，它会检查精选词典本身的问题：

just audit-dictionary

该 recipe 等价于cargo run --bin harper-cli -- audit-dictionary harper-core。注意check-rust这个 recipe 也依赖audit-dictionary，说明词典健康检查是项目格式检查的一部分。

可选：手动编辑词条以获得派生词形

addnoun只给名词加上所有格和复数。如果这个词还有-ment、-ly、un-等派生形式需要入库，需要手动编辑dictionary.dict里该行，追加对应 affix 标志位（如L、Y、U），标志位的完整含义可以用下面的命令查看：

just print-annotations

它会打印annotations.json中affixes与properties两区的每个标志位及其#描述，并列出仍可用的字母、数字、符号，方便为新规则挑一个未占用的标志。properties区还有专门只附加元数据的规则（如N名词、O专有名词、J形容词、V动词），文档原文示例中 "move" 带L展开出 "movement" 即属这类用法。

提交 PR

提交规范文档要求：

1. commit 遵循 conventional commit 规范；
2. 提交前本地运行just format和just precommit。precommit会执行全量格式/类型检查、全部测试和各前端构建，耗时较长，且包含会打开 VSCode 窗口的集成测试；
3. 如果本地跑不了这些脚本，PR 的 CI 也会跑just precommit，可以按失败结果修改后再 push；
4. 变更需要所有检查通过并经 committer 审阅后才能合入。

PR 合并前，可以用下面的命令回看词典文件的最近改动，确认自己实际提交的内容（--show-diff可显示完整 diff）：

just newest-dict-changes

它基于git log/git diff --word-diff解析 harper-core/dictionary.dict 的变更，逐条打印 ADD/DEL/CHG 及对应标志位的变化，适合在 PR 描述前自查。

局限

这条路径面向名词类新词。文档原文也只说 "You don't need to know any of the nitty-gritty details to add nouns"；处理动词变位、形容词比较级等更复杂的词类时，需要直接读懂annotations.json的 affix 规则再手工编辑dictionary.dict，没有对应的自动化 recipe。

【免费下载链接】harperOffline, privacy-first grammar checker. Fast, open-source, Rust-powered项目地址: https://gitcode.com/GitHub_Trending/har/harper