Harper 语料库快照测试体系以tests/text/Computer science.md维基百科语料为例【免费下载链接】harperOffline, privacy-first grammar checker. Fast, open-source, Rust-powered项目地址: https://gitcode.com/GitHub_Trending/har/harperHarper 的harper-core/tests/text/目录存放着一批真实英文语料其中 Computer science.md 是一份节选自维基百科的计算机科学条目508 行约 1.3 万字符。这篇文章以它为主体讲清它在 Harper 测试体系中的真实身份——不是文档而是一份驱动「词性标注快照」与「Lint 结果快照」两套回归测试的黄金语料——并基于该语料对应的两份快照产物1064 行的 POS 标注文件与 1358 行的 Lint 报告文件完整还原 Harper 如何对一段 500 行 Markdown 做分词、标注、拼写、风格与可读性检查以及 CI 如何用快照不一致来拦截回归。一、语料文件本体来源、许可与被遮蔽的头部注释先看语料本身的结构。Computer science.md 的前 4 行是一个 HTML 注释声明了出处与许可证!-- source: https://en.wikipedia.org/w/index.php?titleComputer_scienceoldid1286173304 license: CC BY-SA 4.0 --随后是一级标题# Computer science与正文覆盖 History、Etymology and scope、Philosophy含 Epistemology、Paradigms 两节、Fields理论计算机科学、应用计算机科学、计算机系统等三级小节、Discoveries、Programming paradigms、Research 等完整章节。选维基百科条目做语料是有意为之文本中密集出现历史人名地名Wilhelm Schickard、Gottfried Leibniz、Ada Lovelace、Thomas de Colmar、Percy Ludgate、Leonardo Torres Quevedo、专业术语arithmometer、Stepped Reckoner、Analytical Engine、引号与脚注标记[note 1]、长句与多范式例句几乎能同时压测 Harper 的拼写检查器、大小写检查器、标点风格检查器和长句可读性检查器。一个容易被忽略的细节头部那段 HTML 注释在标注快照中被整体打上了Unlintable标记见 tagged/Computer science.md 第 1–8 行Unlintable连续出现在source:与license:各行上方。也就是说 Harper 的词法层会把该注释识别为一种不可 lint 的 token许可声明不会进入拼写/风格检查这避免了w/index.php、CC BY-SA这类内容产生噪声。二、语料在测试流水线中的位置tests/text是唯一的语料入口Harper 并没有为这份语料手写断言而是通过一套「目录扫描 快照比对」机制自动消费它。核心调度逻辑在 snapshot.rsget_text_dir()固定指向harper-core/tests/textget_text_files()遍历该目录只收集扩展名为txt或md的顶层文件——Computer science.md正被此规则命中snapshot_all_text_files(out_dir, ext, create_snapshot)用 rayon 的par_iter()并行处理每个文件先调用回调生成快照内容再与tests/text/out_dir/文件名中已有的快照逐字节比对。一致则通过不一致则覆写快照文件并返回错误最终panic!汇总所有失败文件snapshot.rs 的tag_file函数。这个「失败即重写」的设计有两个后果开发者本地跑一次测试就能看到最新行为并人工确认快照 diff而在 CI 中由于不允许提交漂移任何改变标注或 lint 行为的改动都会直接让测试红掉——linters.rs 与 pos_tags.rs 的模块文档都明确写了「This test will fail if the snapshot files are not up to date」这是有意设置的回归闸门。两条快照生产线分别由两个测试目标驱动测试目标入口函数消费语料方式快照输出目录快照扩展名pos_tagstest_pos_taggerpos_tags.rsDocument::new_markdown_defaultfat_string_tokens()逐 token 输出词性标注tests/text/tagged.mdlinterstest_most_lintslinters.rsLintGroup::new_curated跑完整 lint 管线按 span 排序后输出诊断tests/text/linters.snap.yml因此Computer science.md这一个源文件同时对应 tagged/Computer science.md1064 行与 linters/Computer science.snap.yml1358 行两份产物——前者记录「每个词被标成什么词性」后者记录「每个 lint 规则在哪些行列触发、给出什么建议」。三、POS 快照格式逐词对齐的标注与本文档实例pos_tags测试的快照格式在 pos_tags.rs 的模块文档中有完整定义原文每个词性词对占两行第一行以开头放原文第二行以#开头放标注二者按字符数互相补空格对齐。以本文档第 13–14 行为例摘自 tagged/Computer science.md Computer science is the study of computation , information , and automation . # NSg NSg/VB VL3 D NSg/VB P NSg . Nᴹ .is标为VL3第三人称单数现在时系动词study标为NSg/VB单数名词或动词斜杠表示 tagger 保留的不确定性information与automation标为Nᴹ不可数名词、且是名词短语成员。标题Computer science则被标为NSg / NSg/VB前者是普通单数名词后者中的表示「既可按不可数、也可按可数处理」的名词用法同时该词还能作动词VB。标注体系本身由DictWordMetadata词元元数据推导format_word_tagpos_tags.rs完整取值规则如下这也是阅读任何tagged/快照的通用图例标注含义NPr名词 / 专有名词Sg/Pl单数 / 复数Sg$/Pl$$后缀属格所有格ᴹ上标不可数名词上标不可数且可数两可的名词ISg/Pl/$代词单数/复数/属格VL/X/B/P/Pr/Pt/Pp/3动词系动词 / 助动词 / 原形lemma/ 过去时过去分词合并 / 进行时 / 简单过去时 / 过去分词 / 第三人称单数JC/S形容词比较级 / 最高级R/C副词 / 连词Ddem/q/$限定词指示 / 量化 / 属格P介词AmBrCaAuNoAmComm方言标注美式、英式、加式、澳式、北美区、英联邦区名词短语成员B粗口词badK/W?含撇号但字典未收录的缩合形 / 未收录词无元数据则输出?./#/#d/#r标点 / 数字 / 年代decade/ 罗马数字SpaceNewlineParagraphBreakHeadingStartEmailUrlHostnameUnlintableRegexish其他 token 种类直接打印变体名对Computer science.md这份语料而言标注快照同时暴露了若干值得注意的词法行为HTML 注释整体成为Unlintable[note 1]这类脚注标记被逐词标注NSg/VB # . NSg/VB中的#即数字1数字年份如1623、1673标为#。任何一次改动分词器、词典或元数据而导致的标注漂移都会在这 1064 行里留下可逐行审查的 diff——这正是该快照的引用价值。四、Lint 快照这份语料实际触发了哪些检查test_most_lints 先确定方言默认Dialect::try_guess_from_document猜不出则回退美式再运行LintGroup::new_curated的完整 lint 组把结果按span.start、span.end排序后写入快照。Computer science.snap.yml 中每条记录由三部分组成Lint: 规则 (优先级)、Message:代码块带行号、^~~下划线与前后文、Suggest:建议列表。从该快照可以确认这份语料至少触发了四类规则规则名与优先级均直接摘自快照原文Capitalization优先级 127首条 lint 就命中一级标题——# Computer science被提示「Try to use title case in headings.」建议替换为# Computer Science快照第 1–6 行。Style优先级 31Oxford 逗号缺失——第 27 行planning and处提示「An Oxford comma is necessary here.」并给出Insert ,建议。Spelling优先级 63这是本语料产出 lint 最多的一类。语料中的历史人名与专业词大多不在策展词典中于是产生了密集的真阴性对照例如Schickard建议 Schicks / Shipyard / Schick、GottfriedGuttered / Lotteries / Notified、ReckonerReckoned / Rickover / Reasoner、ColmarCollar / Cellar / Clear、arithmometerarithmetic / anemometer出现两次、Ludgate、Quevedo等。这些条目恰好构成「拼写检查器面对罕见专有名词时的候选建议质量」的基准样本。Readability优先级 127长句检测。快照中至少标记了两处第 59–62 行的句子被判定 48 词「This sentence is 48 words long.」、第 74–79 行 53 词下划线~跨行延续表示 lint 的 span 跨越多行。快照中Message的排版并非随意linters.rs 的print_error会按字节偏移把 span 反解为行列输出带行号{number:6} | {line}的原文行、^~~定位线并在命中位置离行首/行尾超过 40 列时自动补一行上文或下文。也就是说快照不仅锁定「有哪些 lint」还锁定「lint 的呈现方式」——连下划线渲染逻辑的改动都会触发回归。五、方言约定与语料命名规则同一目录下可以看到Spell.US.md、Spell.md这样的命名对。这不是随意取的snapshot.rs 的try_get_dialect_override会从文件主名里解析方言缩写——按.切分后尝试Dialect::try_from_abbr恰好解析出唯一一个时生效。于是Spell.US.md强制以美式英语方言跑 lint而Computer science.md不含缩写后缀走Dialect::try_guess_from_document的自动推断路径推断失败回退美式。该机制还有一条保护若文件名能解析出多个方言缩写则视为非意图忽略覆盖。从语料组合看tests/text/顶层共 11 份.md语料Alices Adventures in Wonderland、Difficult sentences、Part-of-speech tagging、Spell/Spell.US、Swear、The Constitution of the United States、The Great Gatsby、this and that 以及本文的 Computer science加上 test_sources 中由 run_tests.rs 的create_test!宏逐一点名的回归用例如create_test!(title_case_errors.md, 2, Dialect::American)断言精确的 lint 数量。两类测试互补run_tests管「特定 issue 的定点回归」tests/text快照体系管「全量语料的行为基线」Computer science.md属于后者中最重的一份通用英文长文基线。六、运行方式与扩展该语料库的正确姿势运行与本文相关的全部验证只需两条命令在仓库根目录执行cargo test -p harper-core --test pos_tags cargo test -p harper-core --test linters两个测试目标都会并行扫描tests/text下所有.md/.txt文件Computer science.md及其两份快照会自然被包含在处理列表中测试运行时会println!打印Processing ...逐文件进度。给语料库新增一份文档的流程由 pos_tags.rs 的文档直接写明把文件放进tests/text跑一次测试快照即自动生成到tagged/或linters/子目录已有快照的更新同样是重跑测试。但要注意语义边界本地「重跑即更新」是便利CI 中「不一致即失败」才是约束。因此提交前必须人工核对快照 diff——如果 diff 里出现了你并不期望的标注或 lint 变化比如某个历史人名突然不再被标记那正说明词典或规则层发生了行为漂移应当先查因再提交快照而不是盲目接受新快照。小结Computer science.md 是 Harper 词法标注与 lint 管线的黄金回归语料CC BY-SA 4.0 许可的维基条目节选头部注释被词法层识别为Unlintable以屏蔽噪声它由 snapshot.rs 的目录扫描机制统一调度产出 tagged 快照逐词 POS 对齐标注图例见 pos_tags.rs与 lint 快照Capitalization 127、Style 31、Spelling 63、Readability 127 四类规则的真实触发记录快照不一致即测试失败的设计使这份 508 行语料成为 CI 回归闸门的一部分任何分词、词典、标注或 lint 规则的行为漂移都会以可逐行审查的 diff 形式暴露出来。【免费下载链接】harperOffline, privacy-first grammar checker. Fast, open-source, Rust-powered项目地址: https://gitcode.com/GitHub_Trending/har/harper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Harper 语料库快照测试体系：以 `tests/text/Computer science.md` 维基百科语料为例
Harper 语料库快照测试体系以tests/text/Computer science.md维基百科语料为例【免费下载链接】harperOffline, privacy-first grammar checker. Fast, open-source, Rust-powered项目地址: https://gitcode.com/GitHub_Trending/har/harperHarper 的harper-core/tests/text/目录存放着一批真实英文语料其中 Computer science.md 是一份节选自维基百科的计算机科学条目508 行约 1.3 万字符。这篇文章以它为主体讲清它在 Harper 测试体系中的真实身份——不是文档而是一份驱动「词性标注快照」与「Lint 结果快照」两套回归测试的黄金语料——并基于该语料对应的两份快照产物1064 行的 POS 标注文件与 1358 行的 Lint 报告文件完整还原 Harper 如何对一段 500 行 Markdown 做分词、标注、拼写、风格与可读性检查以及 CI 如何用快照不一致来拦截回归。一、语料文件本体来源、许可与被遮蔽的头部注释先看语料本身的结构。Computer science.md 的前 4 行是一个 HTML 注释声明了出处与许可证!-- source: https://en.wikipedia.org/w/index.php?titleComputer_scienceoldid1286173304 license: CC BY-SA 4.0 --随后是一级标题# Computer science与正文覆盖 History、Etymology and scope、Philosophy含 Epistemology、Paradigms 两节、Fields理论计算机科学、应用计算机科学、计算机系统等三级小节、Discoveries、Programming paradigms、Research 等完整章节。选维基百科条目做语料是有意为之文本中密集出现历史人名地名Wilhelm Schickard、Gottfried Leibniz、Ada Lovelace、Thomas de Colmar、Percy Ludgate、Leonardo Torres Quevedo、专业术语arithmometer、Stepped Reckoner、Analytical Engine、引号与脚注标记[note 1]、长句与多范式例句几乎能同时压测 Harper 的拼写检查器、大小写检查器、标点风格检查器和长句可读性检查器。一个容易被忽略的细节头部那段 HTML 注释在标注快照中被整体打上了Unlintable标记见 tagged/Computer science.md 第 1–8 行Unlintable连续出现在source:与license:各行上方。也就是说 Harper 的词法层会把该注释识别为一种不可 lint 的 token许可声明不会进入拼写/风格检查这避免了w/index.php、CC BY-SA这类内容产生噪声。二、语料在测试流水线中的位置tests/text是唯一的语料入口Harper 并没有为这份语料手写断言而是通过一套「目录扫描 快照比对」机制自动消费它。核心调度逻辑在 snapshot.rsget_text_dir()固定指向harper-core/tests/textget_text_files()遍历该目录只收集扩展名为txt或md的顶层文件——Computer science.md正被此规则命中snapshot_all_text_files(out_dir, ext, create_snapshot)用 rayon 的par_iter()并行处理每个文件先调用回调生成快照内容再与tests/text/out_dir/文件名中已有的快照逐字节比对。一致则通过不一致则覆写快照文件并返回错误最终panic!汇总所有失败文件snapshot.rs 的tag_file函数。这个「失败即重写」的设计有两个后果开发者本地跑一次测试就能看到最新行为并人工确认快照 diff而在 CI 中由于不允许提交漂移任何改变标注或 lint 行为的改动都会直接让测试红掉——linters.rs 与 pos_tags.rs 的模块文档都明确写了「This test will fail if the snapshot files are not up to date」这是有意设置的回归闸门。两条快照生产线分别由两个测试目标驱动测试目标入口函数消费语料方式快照输出目录快照扩展名pos_tagstest_pos_taggerpos_tags.rsDocument::new_markdown_defaultfat_string_tokens()逐 token 输出词性标注tests/text/tagged.mdlinterstest_most_lintslinters.rsLintGroup::new_curated跑完整 lint 管线按 span 排序后输出诊断tests/text/linters.snap.yml因此Computer science.md这一个源文件同时对应 tagged/Computer science.md1064 行与 linters/Computer science.snap.yml1358 行两份产物——前者记录「每个词被标成什么词性」后者记录「每个 lint 规则在哪些行列触发、给出什么建议」。三、POS 快照格式逐词对齐的标注与本文档实例pos_tags测试的快照格式在 pos_tags.rs 的模块文档中有完整定义原文每个词性词对占两行第一行以开头放原文第二行以#开头放标注二者按字符数互相补空格对齐。以本文档第 13–14 行为例摘自 tagged/Computer science.md Computer science is the study of computation , information , and automation . # NSg NSg/VB VL3 D NSg/VB P NSg . Nᴹ .is标为VL3第三人称单数现在时系动词study标为NSg/VB单数名词或动词斜杠表示 tagger 保留的不确定性information与automation标为Nᴹ不可数名词、且是名词短语成员。标题Computer science则被标为NSg / NSg/VB前者是普通单数名词后者中的表示「既可按不可数、也可按可数处理」的名词用法同时该词还能作动词VB。标注体系本身由DictWordMetadata词元元数据推导format_word_tagpos_tags.rs完整取值规则如下这也是阅读任何tagged/快照的通用图例标注含义NPr名词 / 专有名词Sg/Pl单数 / 复数Sg$/Pl$$后缀属格所有格ᴹ上标不可数名词上标不可数且可数两可的名词ISg/Pl/$代词单数/复数/属格VL/X/B/P/Pr/Pt/Pp/3动词系动词 / 助动词 / 原形lemma/ 过去时过去分词合并 / 进行时 / 简单过去时 / 过去分词 / 第三人称单数JC/S形容词比较级 / 最高级R/C副词 / 连词Ddem/q/$限定词指示 / 量化 / 属格P介词AmBrCaAuNoAmComm方言标注美式、英式、加式、澳式、北美区、英联邦区名词短语成员B粗口词badK/W?含撇号但字典未收录的缩合形 / 未收录词无元数据则输出?./#/#d/#r标点 / 数字 / 年代decade/ 罗马数字SpaceNewlineParagraphBreakHeadingStartEmailUrlHostnameUnlintableRegexish其他 token 种类直接打印变体名对Computer science.md这份语料而言标注快照同时暴露了若干值得注意的词法行为HTML 注释整体成为Unlintable[note 1]这类脚注标记被逐词标注NSg/VB # . NSg/VB中的#即数字1数字年份如1623、1673标为#。任何一次改动分词器、词典或元数据而导致的标注漂移都会在这 1064 行里留下可逐行审查的 diff——这正是该快照的引用价值。四、Lint 快照这份语料实际触发了哪些检查test_most_lints 先确定方言默认Dialect::try_guess_from_document猜不出则回退美式再运行LintGroup::new_curated的完整 lint 组把结果按span.start、span.end排序后写入快照。Computer science.snap.yml 中每条记录由三部分组成Lint: 规则 (优先级)、Message:代码块带行号、^~~下划线与前后文、Suggest:建议列表。从该快照可以确认这份语料至少触发了四类规则规则名与优先级均直接摘自快照原文Capitalization优先级 127首条 lint 就命中一级标题——# Computer science被提示「Try to use title case in headings.」建议替换为# Computer Science快照第 1–6 行。Style优先级 31Oxford 逗号缺失——第 27 行planning and处提示「An Oxford comma is necessary here.」并给出Insert ,建议。Spelling优先级 63这是本语料产出 lint 最多的一类。语料中的历史人名与专业词大多不在策展词典中于是产生了密集的真阴性对照例如Schickard建议 Schicks / Shipyard / Schick、GottfriedGuttered / Lotteries / Notified、ReckonerReckoned / Rickover / Reasoner、ColmarCollar / Cellar / Clear、arithmometerarithmetic / anemometer出现两次、Ludgate、Quevedo等。这些条目恰好构成「拼写检查器面对罕见专有名词时的候选建议质量」的基准样本。Readability优先级 127长句检测。快照中至少标记了两处第 59–62 行的句子被判定 48 词「This sentence is 48 words long.」、第 74–79 行 53 词下划线~跨行延续表示 lint 的 span 跨越多行。快照中Message的排版并非随意linters.rs 的print_error会按字节偏移把 span 反解为行列输出带行号{number:6} | {line}的原文行、^~~定位线并在命中位置离行首/行尾超过 40 列时自动补一行上文或下文。也就是说快照不仅锁定「有哪些 lint」还锁定「lint 的呈现方式」——连下划线渲染逻辑的改动都会触发回归。五、方言约定与语料命名规则同一目录下可以看到Spell.US.md、Spell.md这样的命名对。这不是随意取的snapshot.rs 的try_get_dialect_override会从文件主名里解析方言缩写——按.切分后尝试Dialect::try_from_abbr恰好解析出唯一一个时生效。于是Spell.US.md强制以美式英语方言跑 lint而Computer science.md不含缩写后缀走Dialect::try_guess_from_document的自动推断路径推断失败回退美式。该机制还有一条保护若文件名能解析出多个方言缩写则视为非意图忽略覆盖。从语料组合看tests/text/顶层共 11 份.md语料Alices Adventures in Wonderland、Difficult sentences、Part-of-speech tagging、Spell/Spell.US、Swear、The Constitution of the United States、The Great Gatsby、this and that 以及本文的 Computer science加上 test_sources 中由 run_tests.rs 的create_test!宏逐一点名的回归用例如create_test!(title_case_errors.md, 2, Dialect::American)断言精确的 lint 数量。两类测试互补run_tests管「特定 issue 的定点回归」tests/text快照体系管「全量语料的行为基线」Computer science.md属于后者中最重的一份通用英文长文基线。六、运行方式与扩展该语料库的正确姿势运行与本文相关的全部验证只需两条命令在仓库根目录执行cargo test -p harper-core --test pos_tags cargo test -p harper-core --test linters两个测试目标都会并行扫描tests/text下所有.md/.txt文件Computer science.md及其两份快照会自然被包含在处理列表中测试运行时会println!打印Processing ...逐文件进度。给语料库新增一份文档的流程由 pos_tags.rs 的文档直接写明把文件放进tests/text跑一次测试快照即自动生成到tagged/或linters/子目录已有快照的更新同样是重跑测试。但要注意语义边界本地「重跑即更新」是便利CI 中「不一致即失败」才是约束。因此提交前必须人工核对快照 diff——如果 diff 里出现了你并不期望的标注或 lint 变化比如某个历史人名突然不再被标记那正说明词典或规则层发生了行为漂移应当先查因再提交快照而不是盲目接受新快照。小结Computer science.md 是 Harper 词法标注与 lint 管线的黄金回归语料CC BY-SA 4.0 许可的维基条目节选头部注释被词法层识别为Unlintable以屏蔽噪声它由 snapshot.rs 的目录扫描机制统一调度产出 tagged 快照逐词 POS 对齐标注图例见 pos_tags.rs与 lint 快照Capitalization 127、Style 31、Spelling 63、Readability 127 四类规则的真实触发记录快照不一致即测试失败的设计使这份 508 行语料成为 CI 回归闸门的一部分任何分词、词典、标注或 lint 规则的行为漂移都会以可逐行审查的 diff 形式暴露出来。【免费下载链接】harperOffline, privacy-first grammar checker. Fast, open-source, Rust-powered项目地址: https://gitcode.com/GitHub_Trending/har/harper创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考