Refactor code structure for improved readability and maintainability

2026-11-09 02:53:10 +08:00
1 parent 6bfd8009a2
commit a710477be2
@@ -0,0 +1,178 @@
+# 校准报告（0.2）
+
+<!-- stc:off -->
+
+本报告记录 0.2 版把检查脚本放到真实中文技术文档上校准的方法、数据和决定。校准量的是**误报率**：脚本报出来的提示里，有多少是按规则确实该改的。它不量读者的理解速度和出错率。
+
+## 结论
+
+1. 草案 0.1 的脚本在公认写得好的文档上每万字报 194 条提示，约每 50 个字一条。answer-me-with-html 的维护者在他的 1000 篇中文稿上实测到的「30 条对 3 条」不是他的文档特殊，是草案的真实水平。
+2. 校准后降到每万字 88 条。其中一半以上是句长提示（2.1）。不算句长，从 151 条降到 40 条。
+3. 6 条规则从脚本移除：1.6 缩写写法、2.7 定语长度、2.8 指代、4.3 步骤里的警告、4.5 括号里的前置条件、4.6 步骤里的原因。它们的精确率在 0% 到 34% 之间。脚本用的代理信号（大小写不同的英文词、「的」的数量、指代词的数量、编号列表项里的「注意」「因为」「（版本）」）分不出合规和违规。规则本身不变，由人判断。
+4. 2.4 被动句只查操作句，级别降为【建议】。描述句里的被动有 58% 是「执行者未知或不重要」的合规用法；操作句里「被拒绝的请求」这类是定语不是谓语。脚本都分不出来。2.5 条件后置只查操作句。3.3 正文串联步骤降为【建议】：正文里的「首先……然后……」多数在描述执行顺序，不是在写步骤。
+5. 程度词（1.5）、情态词（2.3）、估计词（5.4）只在操作句和参数表格里查。描述句里的「很多」「大部分」「输出应该是」「大约 16 KB」多数是正常表述。
+6. 句长上限：操作句从 25 字改为 30 字，描述句保持 40 字。好文档里 90% 的操作句不超过 33 字，90% 的描述句不超过 41 字。
+7. 20 处跨词误匹配加了排除条件。例如「传入参数」里的「入参」、「不准确」里的「不准」、「添加以下」里的「加以」、「不得不」里的「不得」、「为其实施」里的「其实」、「规约」里的「约」、「相等」里的「等」。
+8. 词表里 8 个禁用词和 8 行选词表同义词改为不自动检查：相关、必要时、同时、落地、方面、所谓、不得、兜底（改为一词一义限定）；去除 / 去掉、剔除 / 拿掉、拉起 / 跑起来、杀掉 / 干掉、调出 / 唤起、展示 / 呈现、回传 / 吐出、挂了。它们在真实文档里多数是别的意义或正常用法。
+
+## 方法
+
+流程和脚本在 [tools/calibration/](../tools/calibration/)。
+
+1. 选 8 个公认写得好的中文技术文档仓库作语料，只取正文以中文为主的 Markdown 文件。大仓库稀疏检出中文文档目录。语料版本记录在 `corpora.json`。
+2. 用检查脚本跑全部语料，统计每条规则、每个词的命中数，以及句长分布。
+3. 每条规则抽最多 50 条命中（第二轮 60 条）。词表类规则先按词分层，每个词最多 8 条（第二轮 10 条），再在语料库之间轮流取。每条样本附命中行前后各一行原文。
+4. 用模型（deepseek-v4-flash，温度 0）按规则原文和词表条目判定每条样本：**真**（规则按字面确实被违反，而且按规则改写后这句话不会变得更不准确）、**误**（命中的词或句在这里是正常用法、固定术语、引用的界面文字或代码，或者按规则改写会损害意思）、**不确定**。本报告的精确率是模型初判，作者抽查过每条规则的误报样本和理由。模型的判定偏宽松：它倾向把「描述句里本来就这么写」判为正常用法。所以这里的精确率是下限。
+5. 精确率 = 真 / (真 + 误)。不低于 80% 保留；50% 到 79% 加匹配条件或降为【建议】；低于 50% 从脚本移除，规则只留在文本里。
+6. 按结果修脚本和词表，再跑一轮，确认命中数下降、精确率上升。
+
+## 语料
+
+| 语料库 | 来源 | 文件 | 句子 | 字数 |
+| --- | --- | ---: | ---: | ---: |
+| tidb-docs-cn | pingcap/docs-cn | 1085 | 73933 | 1525798 |
+| k8s-zh-cn | kubernetes/website，content/zh-cn/docs/{concepts,tasks} | 359 | 26401 | 604671 |
+| mdn-zh-cn | mdn/translated-content，files/zh-cn/web/{javascript,http} | 927 | 32239 | 596778 |
+| trpl-zh-cn | KaiserY/trpl-zh-cn（《Rust 程序设计语言》） | 110 | 8109 | 234618 |
+| es6tutorial | ruanyf/es6tutorial | 36 | 5579 | 142026 |
+| vue-docs-zh-cn | vuejs-translations/docs-zh-cn | 107 | 6349 | 141378 |
+| ant-design | ant-design/ant-design，components 和 docs 的 zh-CN 文件 | 169 | 6672 | 132856 |
+| vite-docs-cn | vitejs/docs-cn | 63 | 4417 | 92739 |
+| 合计 | | 2856 | 163699 | 3470864 |
+
+句子数按校准后的脚本统计（多行拼成一句）。
+
+TiDB 文档占 44%，k8s 和 MDN 各占 17%。这三个是产品手册和参考文档，操作步骤多，和本规范的目标文体最接近。Rust 书和 ES6 教程是教材，句子长、设问多，是最「不像手册」的两个。
+
+## 校准前后每条规则的命中
+
+校准前是 0.1 的脚本，校准后是 0.2 的脚本。两者字数略有差别：0.2 跳过 HTML 注释和整行 HTML 标签，去掉了 k8s 文档注释里的英文原文。
+
+| 规则 | 校准前命中 | 每万字 | 校准后命中 | 每万字 | 处理 |
+| --- | ---: | ---: | ---: | ---: | --- |
+| 2.1 句长 | 14814 | 42.2 | 16720 | 48.2 | 操作句上限 25 → 30；多行拼成一句后命中反而变多，见下文 |
+| 1.3 禁用词 | 11374 | 32.4 | 5351 | 15.4 | 情况只查「的情况」且后面不是「下」；相关、必要时、方面、所谓不自动检查；跨词误匹配加排除 |
+| 2.4 被动 | 8476 | 24.2 | 156 | 0.4 | 只查操作句，降为建议；「被 X 的 Y」不算 |
+| 1.4 进行 / 加以 / 作出 | 5855 | 16.7 | 5422 | 15.6 | 加以、予以、做出贡献的误匹配加排除；「进行 + 英文词」不查 |
+| 1.5 程度词 | 4537 | 12.9 | 383 | 1.1 | 只查操作句（比较、较为、基本、相对除外）；合适 / 适当 / 适量、很 / 非常 / 极其 / 相当 / 十分不自动检查 |
+| 2.8 指代 | 3751 | 10.7 | 0 | 0.0 | 移除 |
+| 1.1 一词一义 | 3122 | 8.9 | 186 | 0.5 | 11 行同义词和不得、应该 / 应当改为不自动检查；点选、一定要加排除 |
+| 1.6 缩写写法 | 2942 | 8.4 | 0 | 0.0 | 移除 |
+| 2.7 长定语 | 2575 | 7.3 | 0 | 0.0 | 移除 |
+| 5.4 估计词 | 2247 | 6.4 | 11 | 0.0 | 只查操作句和表格；一些、多次不自动检查；「规约」里的「约」加排除 |
+| 2.3 祈使句 | 1885 | 5.4 | 71 | 0.2 | 请见 / 请参阅 / 请注意不查；你、应该、应当不自动检查 |
+| 5.1 数字写法 | 1665 | 4.7 | 158 | 0.5 | 一次、两次、一行、几十行、百分之百、二十四小时制不查；px 不查空格 |
+| 3.5 开放列举 | 1141 | 3.3 | 654 | 1.9 | 「例如……等」「相等」「不等」和括号里的列举不查 |
+| 2.6 否定 | 722 | 2.1 | 55 | 0.2 | 只查双重否定，降为建议 |
+| 2.9 问句感叹句 | 683 | 1.9 | 673 | 1.9 | 保留 |
+| 3.2 段落句数 | 561 | 1.6 | 80 | 0.2 | 只数有句末标点的句子；整行 HTML 标签跳过 |
+| 6.1 界面元素名 | 388 | 1.1 | 386 | 1.1 | 保留 |
+| 2.5 条件后置 | 291 | 0.8 | 3 | 0.0 | 只查操作句句尾的条件；括号不查 |
+| 4.1 一步一动作 | 187 | 0.5 | 152 | 0.4 | 同时不自动检查；然后、接着降为建议 |
+| 2.2 一句一事 | 152 | 0.4 | 71 | 0.2 | 之后、随后不算连接词；降为建议 |
+| 3.3 正文串联步骤 | 131 | 0.4 | 0 | 0.0 | 移除 |
+| 5.2 范围端点 | 121 | 0.3 | 122 | 0.4 | 保留 |
+| 1.7 黑话 | 107 | 0.3 | 12 | 0.0 | 透传、兜底改为一词一义；落地、打通不自动检查；对标加排除；心智模型、心智负担不查；痛点降为建议 |
+| 5.3 相对时间 | 85 | 0.2 | 8 | 0.0 | 稍后、近期、不久、上个月、下个月不查，只查相对日期词；降为建议 |
+| 4.6 步骤里的原因 | 56 | 0.2 | 0 | 0.0 | 移除 |
+| 4.3 步骤里的警告 | 16 | 0.0 | 0 | 0.0 | 移除 |
+| 4.5 括号里的前置条件 | 16 | 0.0 | 0 | 0.0 | 移除 |
+| 5.5 倍数 | 1 | 0.0 | 1 | 0.0 | 保留 |
+| 合计 | 67901 | 193.5 | 30675 | 88.4 | |
+
+校准后的 30675 条里，【必须】级别 29775 条（每万字 85.8），其余是【建议】。
+
+## 句长
+
+0.1 的脚本把 Markdown 的硬换行当句子边界。k8s、MDN、Rust 书都按 80 列左右硬换行，一句常被切成两三段，所以 0.1 量出来的句长偏短，而且被切开的片段还会触发 2.5 条件后置和 2.2 一句多事的误报。0.2 先把一个段落的多行拼起来再分句。下面是拼行后的分布。
+
+| 语料库 | 句型 | n | 均值 | p50 | p75 | p90 | p95 | p99 | 超过上限（操作 30 / 描述 40） |
+| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| k8s-zh-cn | 操作 | 1143 | 18.8 | 16 | 25 | 34 | 43 | 58 | 15.7% |
+| k8s-zh-cn | 描述 | 25258 | 23.1 | 21 | 31 | 41 | 48 | 63 | 10.5% |
+| tidb-docs-cn | 操作 | 3012 | 17.6 | 16 | 23 | 31 | 38 | 56 | 11.1% |
+| tidb-docs-cn | 描述 | 70921 | 20.8 | 19 | 28 | 40 | 48 | 67 | 9.4% |
+| mdn-zh-cn | 描述 | 32010 | 18.5 | 16 | 28 | 39 | 47 | 63 | 8.9% |
+| trpl-zh-cn | 描述 | 8065 | 29.0 | 28 | 37 | 48 | 55 | 69 | 19.4% |
+| es6tutorial | 描述 | 5570 | 25.5 | 24 | 33 | 43 | 50 | 68 | 12.6% |
+| 全部 | 操作 | 4799 | 18.3 | 16 | 24 | 33 | 40 | 58 | 13.1% |
+| 全部 | 描述 | 158900 | 21.3 | 19 | 29 | 41 | 48 | 66 | 10.2% |
+
+各阈值下超限的句子比例（全部语料）：
+
+| 上限 | 30 字 | 35 字 | 40 字 | 45 字 | 50 字 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| 操作句 | 13.1% | 7.9% | 4.9% | 3.2% | 1.9% |
+| 描述句 | 22.9% | 15.4% | 10.2% | 6.5% | 4.2% |
+
+决定：操作句 30 字（85 到 90 分位之间），描述句 40 字（90 分位附近）。两个数字都会让好文档里约 10% 的句子收到提示。这是本规范有意比常规文档更严的地方：句长是 STE 方法的核心约束。手册类文档（k8s、TiDB）的 p90 比教材（Rust 书、ES6 教程）低 7 到 8 字，上限按手册定。
+
+## 每条规则的精确率
+
+三轮抽样。第一轮量 0.1 的脚本；第二轮量第一次修正后的脚本；第三轮量 0.2 的脚本（第三轮之后还有少量调整，见下）。第三轮的提示词补了附录 A 的字数算法，所以 2.1 的判定比前两轮准。每轮每条规则最多 60 条样本，样本少于 10 条的规则不下结论。
+
+| 规则 | 第一轮 | 第二轮 | 第三轮 | 第三轮样本 | 0.2 里的级别 |
+| --- | ---: | ---: | ---: | ---: | --- |
+| 2.1 句长 | 64% | 73% | 92% | 60 | 必须 |
+| 1.3 禁用词 | 60% | 80% | 80% | 60 | 必须 |
+| 1.4 进行 / 加以 / 作出 | 69% | 87% | 82% | 45 | 必须 |
+| 2.9 问句感叹句 | 84% | 82% | 80% | 60 | 必须 |
+| 6.1 界面元素名 | 94% | 90% | 95% | 60 | 建议 |
+| 3.2 段落句数 | 47% | 92% | 100% | 60 | 必须 |
+| 5.2 范围端点 | 71% | 83% | 80% | 30 | 必须 |
+| 4.1 一步一动作 | 42% | 64% | 64% | 22 | 并且必须，然后建议 |
+| 2.2 一句一事 | 54% | 65% | 53% | 60 | 建议 |
+| 2.6 双重否定 | 22% | 41% | 53% | 55 | 建议 |
+| 1.1 一词一义 | 26% | 63% | 48% | 60 | 必须，只剩高精确率的词 |
+| 5.1 数字写法 | 4% | 45% | 47% | 60 | 阿拉伯数字必须，单位空格建议 |
+| 1.5 程度词 | 44% | 42% | 47% | 60 | 必须，只查操作句，只剩高精确率的词 |
+| 2.3 祈使句 | 51% | 60% | 45% | 47 | 必须，只查操作句，去掉你和应该 |
+| 5.4 估计词 | 16% | 33% | 39% | 28 | 必须，只查操作句和表格，去掉一些和多次 |
+| 1.7 黑话 | 22% | 32% | 44% | 16 | 必须，去掉打通、落地、兜底 |
+| 2.4 被动 | 42% | 43% | 35% | 60 | 建议，只查操作句 |
+| 3.5 开放列举 | 50% | 60% | 30% | 10 | 必须，括号里的列举不查 |
+| 5.3 相对时间 | 26% | 33% | 38% | 8 | 建议 |
+| 3.3 正文串联步骤 | 12% | 40% | 30% | 10 | 脚本不查 |
+| 2.5 条件后置 | 34% | 35% | 100% | 3 | 必须，只查操作句 |
+| 2.8 指代 | 0% | – | – | | 脚本不查 |
+| 1.6 缩写写法 | 0% | – | – | | 脚本不查 |
+| 2.7 长定语 | 2% | – | – | | 脚本不查 |
+| 4.3 / 4.5 / 4.6 步骤里的警告、前置条件、原因 | 19% / 12% / 34% | – | – | | 脚本不查 |
+
+第三轮之后的调整：2.2、2.6、5.3 降为建议；3.3 从脚本移除；1.1、1.5、2.3、5.4、1.7 里精确率低的词改为不自动检查（挑选 / 选取、应答 / 回包、入参的选词表条目；很 / 非常 / 极其 / 相当 / 十分、合适 / 适当 / 适量；你、应该 / 应当；一些、多次；打通）。这些词的命中占这几条规则命中的大半，所以调整后的精确率会高于表里的数字，但没有再量。
+
+作者和模型判定不一致的地方：模型把「不得不」「合适的命令」「（MySQL、PostgreSQL 等）」判为正常用法，作者认为按规则该改。这三类按作者意见处理：2.6 保留为建议，1.5 的合适不自动检查，3.5 括号里的列举不查、其余保留。
+
+## 词表条目的精确率
+
+命中最多的词单独抽了 25 条（第二轮脚本的命中）。精确率决定了它们在 0.2 里的处理。
+
+| 词 | 命中 | 精确率 | 处理 |
+| --- | ---: | ---: | --- |
+| 进行 | 5246 | 100%（10 条） | 保留 |
+| 报错 | 1407 | 96% | 保留。TiDB 文档把它当名词用，模型仍判为该改 |
+| 开启 | 1914 | 76% | 保留。误报是「开启 / 关闭」对举和标题引用 |
+| 做出 | 111 | 88% | 保留。「做出贡献」「做出反应」加排除 |
+| 的话 | 214 | 76% | 保留。误报是「如果有的话」「可能的话」 |
+| 然后 | 122 | 76% | 降为建议：编号列表项不一定是步骤 |
+| 等 | 782 | 72% | 保留。「相等」「不等」「例如……等」加排除 |
+| 比较 | 193 | 72% | 保留 |
+| 一定要 | 60 | 56% | 保留。「不是一定要」「是否一定要」加排除 |
+| 应该 | 32 | 52% | 保留，只查操作句 |
+| 不得 | 74 | 52% | 不自动检查：「不得超过 256 KiB」是规范文体的正常写法 |
+| 你 | 434 | 44% | 降为建议：步骤里的「你可以……」是文体问题 |
+| 所谓 | 22 | 36% | 不自动检查：「所谓幻读是指……」引出定义是正常用法 |
+| 情况 | 1292 | 32% | 只查「的情况」且后面不是「下」：「在……的情况下」是固定搭配 |
+| 方面 | 163 | 8% | 不自动检查 |
+| 不准 | 12 | 0% | 只查「不准 + 动词」：剩下的命中全是「统计不准」这种「不准确」 |
+
+每条规则抽样里出现的其余词，见第三轮报告表。
+
+## 局限
+
+- 判定由模型做，作者只抽查。模型偏宽松，精确率是下限。欢迎在 issue 里对任何一条判定提出异议。
+- 语料全是开源项目的文档和教材，没有企业内部文档和 AI 生成的回答。后者正是本规范的主要使用场景之一，它们的黑话和虚词密度可能高得多。
+- 操作句靠「编号列表项」识别。k8s 和 MDN 大量用编号列表做说明性列举，脚本把它们当步骤检查，是 2.1、2.3、4.1 剩余误报的主要来源。
+- 没有量阅读效果。校准只回答「脚本报的对不对」，不回答「按规范改写后读者是否读得更快、错得更少」。
+
+<!-- stc:on -->