企业官网建设流程全解析

• 人工智能
• 搜索引擎
• 本地部署
• 后端
• MCP 服务

XERJ 仓库中有一套自动化的营销文章事实核查门禁（fact-check gate）：任何对外发布的性能数字，都必须能在demo/playbooks/SCORECARD.md等既定结果文件中找到出处，且"赢"的数字必须在其所在段落内同时携带规定的"同伴事实"——通常是对应的败绩或平局结论。本文以负面测试夹具scripts/seo/testdata/factcheck/bad_numbers.md为切入点，拆解这条门禁的规则体系（Tier A/B/C 三层可引用数字、FC-NUM-COMPANION 与 FC-NUM-UNKNOWN 两条引擎检查），并结合官方记分板与合规范本，说明如何写出能通过门禁的基准数字引用。读完你将掌握 XERJ 基准面板的正确读法，以及让任何性能声明"可溯源、不片面"的可复制的工程做法。

这篇文档是什么：一张"错误示范"的负面测试夹具

scripts/seo/testdata/factcheck/bad_numbers.md并不是一篇会被发布出去的文章，而是一张负面测试夹具（bad fixture）：它模拟了一篇把所有基准数字都写错的文章，用来验证事实核查门禁确实能拦下这些错误。它的 frontmatter 明确声明了期望触发的规则：

--- title: "What does the XERJ benchmark board say?" evidence: - claim: "Board generated by bench-matrix.mjs" source: "demo/playbooks/SCORECARD.md" expect: [FC-NUM-COMPANION, FC-NUM-UNKNOWN] ---

expect表示运行门禁后，这篇文章必须触发两条规则：

• FC-NUM-COMPANION（WARN）：Tier A 数字发布时缺少强制随行的同伴事实；
• FC-NUM-UNKNOWN（WARN）：出现了既不在可引用清单、也不在evidence:条目中的数字。

与之配套的scripts/seo/testdata/factcheck/good_benchmarks.md则是同一主题的合规范本，同样的数字换一种写法就能全数过关。这两张夹具由scripts/seo/factcheck.py的--fixture-check统一跑完并输出混淆矩阵——夹具机制保证了规则本身也有测试覆盖，规则改坏了会被bad_/good_夹具当场抓住。

门禁的架构很清晰：scripts/seo/factcheck.py只是引擎（检查器），所有"什么话不能说、哪个数字可引用"的决策数据都沉淀在scripts/seo/claims_rules.py。作者发现新的不可支持声明时，改的是规则数据而不是引擎逻辑；--self-test还会校验每条规则都带file:line证据引用、有合规改写建议。

基准数字的源头：bench-matrix.mjs 与 SCORECARD.md

夹具正文引用的数字全部来自 XERJ 的官方基准面板。demo/playbooks/SCORECARD.md的题注写明，这份记分板由demo/playbooks/bench-matrix.mjs生成：同一台机器、同一个合成语料，XERJ（:9200）与 Elasticsearch 8.13.4（:9201）跑完全相同的工作负载，每个维度一行，输出 XERJ 值、ES 值、比值和 WIN/LOSE/TIE 判定，其中任何意外的 LOSE 都会让进程以非零码退出（可挂 CI）。

记分板本身的方法论约束直接决定了"哪些数字可以怎么引用"：

• 读延迟用 Node corehttp的 keep-alive 客户端（maxSockets: 256，按host:port共享 Agent）而非全局fetch/undici——后者每个请求约 1.5ms 的客户端开销会把两台引擎亚毫秒级的服务端耗时压进同一噪声带；keep-alive 客户端揭示的是引擎真实的服务端往返；
• 非缓存执行（honesty）：所有读请求带request_cache=false，XERJ 以XERJ_DISABLE_QUERY_CACHE=1运行，两台引擎每次都真实执行查询；
• 噪声带即 TIE：|Δ| ≤ max(0.30ms, 20%)的行判为 TIE，只有 LOSE 会失败 CI；
• mixed 读-写并发用开环（open-loop）写入器：每 250ms 发起一批 10k 的_bulk，提供 40,000 docs/s 的绝对截止时间负载，两台引擎都达到目标的约 5% 以内才声明 iso-load。

在 100k 文档、1 个客户端的配置下，面板共88 个单元：55 WIN / 26 TIE / 4 LOSE / 3 N/A。其中 4 个 LOSE 全部集中在"持续写入下的读 p99"（mixed 系列），记分板将其标注为已知的架构性差距（live-memtable 读在写入端 per-shard 锁下排队），并单独追踪、不计入 CI 门禁。

三层可引用数字体系：Tier A / Tier B / Tier C

claims_rules.py把"哪些数字能写进文章"分成三个层级，这是 FC-NUM-UNKNOWN 判定的事实基础。数字键按规范化规则存储：去掉千位逗号、去掉小数尾零（100.0%→100%、1.20x→1.2x）、单位小写、×归一为x（见 claims_rules.py 与 factcheck.py 的 iter_numbers）。

Tier A（claims_rules.py）：有结果文件、有 harness、可复现的核心基准，全部来自SCORECARD.md。例如：

Tier B：来自 case study 与专项评测的可引用数字（如 WordPress 审计的 token 比例、autoindex 语料吞吐等），同样必须携带各自的限定条件。

Tier C（claims_rules.py）：无证据或已被项目在 2026-07-28 明确撤回的数字，写出来就是 ERROR 级违规FC-NUM-TIERC。典型如11.5x（bool 查询，现值为 1.64x）、6.9x（query_string，现 2.41x）、6.8x（wildcard，现 4.01x）、3.4x（kNN，现 1.18x 平局）、1.2x（磁盘比，现 1.61x 且是不同测量）、以及无方法无日期的 SQ8 向量内存数字（18 GB / 92 GB / 5.1x）和"~80% 基础设施成本下降"这类纯散文。撤回的核心原因之一是旧数字的量级被重新评估为饱和伪影（saturation artifact）——例如曾宣称"ES 2-19 ms vs XERJ 60-150 ms"的 p99 对比，实测范围其实是 3.45-20.13 ms（ES）vs 10.27-13.57 ms（XERJ），60-150 ms 来自开环 harness 报的排队时长而非引擎延迟。

FC-NUM-COMPANION：赢的数字必须带着输一起发布

这是夹具正文踩得最集中的规则。规则意图（FC-NUM-COMPANION）是"losses and caveats must travel with the win they qualify"——仓库里每个实测工件都已经这么做了：四个 mixed 写压下 p99 的败绩、doc-index 的 0.23x 字面反转、agent-gate analytics 场景 109.78x 的 token 反超等。规则原话点明："That habit is the project's most valuable credibility asset——do not break it"，并特别强调kNN 1.18x 是在 100% recall 下的平局，不是胜利。

bad_numbers.md正文的三行正好是三个不同维度的反面示范：

XERJ ingests 1.72× faster than Elasticsearch 8.13.4 and its index is 1.61× smaller on disk. … kNN search at k=10 comes in at 1.18× on the same board.

引擎侧的检查逻辑在 factcheck.py 的 check_numbers：命中 Tier A/B 条目后，若该条目声明了companion（一个needs正则 + 一个window字符窗口），就在匹配位置前后取窗口文本，找不到必需短语就记一条 WARN。三条 Tier A 数字的同伴事实要求是：

• 1.72x（窗口 900 字符）：必须出现p99 | lose | loss | slower | under sustained write | 13.57 | four losses之一——即把"持续写入下读 p99 的四个败绩"讲出来；
• 1.61x（窗口 600 字符）：必须出现different measurement | not better / like-for-like | 176.2 | 283 | 100k | not the (old | 1.20)之一——因为1.20x → 1.61x 是换了测量口径的新数字，不是"旧数字被改进成更好"；
• 1.18x（窗口 400 字符）：必须出现tie | draw | 100% recall | recall@10 | not a win之一。

夹具正文三句全都没有这些限定词，因此三条各记一次FC-NUM-COMPANION。这也是为什么夹具 frontmatter 的expect里只有这两条规则而没有FC-NUM-TIERC：1.72x、1.61x、1.18x 本身都是 Tier A 的合法数字，错不在数字，而在发布的姿态。

FC-NUM-UNKNOWN：没有出处就不能发布

夹具正文最后一行是问题的另一半：

Our internal runs also showed 7.3× on filtered aggregations and a 44% drop in p95 latency.

7.3x和44%这两个数字：不在 Tier A/B/C 任何一层（记分板上 filter 类聚合没有 7.3x 这一行，也没有 44% p95 下降），也不在NUMBER_ALLOW（端口、堆内存、常见超时等结构性常量白名单，见 claims_rules.py），而 frontmatter 的evidence:条目只声明了"面板由 bench-matrix.mjs 生成"，并未携带任何数字。于是两条都触发FC-NUM-UNKNOWN："number has no provenance"——它没有来源文件可指认，就不得发布。

引擎的处理顺序值得注意（check_numbers）：先查 Tier C（命中即 ERROR），再查 Tier A/B（命中还要再过同伴事实），随后检查该数字是否出现在evidence:条目文本里（a.ev_numbers）——这是 FC-NUM-UNKNOWN 的唯一豁免通道：只要你在 frontmatter 的evidence:里写清数字出自哪个文件，未知数字就变成有出处数字。规则给出的合规改写也只有两条路：要么补evidence:条目指明来源文件，要么删掉这个数字。

合规范本：同样的数字，换一种发布姿态

把bad_numbers.md和good_benchmarks.md并排看，门禁要的"正确写法"一目了然。合规版（good_benchmarks.md）的 frontmatter 把证据写全：

--- title: "What does the XERJ benchmark board actually say?" evidence: - claim: "55 WIN / 26 TIE / 4 LOSE / 3 N/A across 88 cells at 100k docs" source: "Tier A: demo/playbooks/SCORECARD.md" - claim: "The four losses are read p99 under a sustained open-loop writer" source: "demo/playbooks/SCORECARD.md" ---

正文则逐条把同伴事实放回同一段落：

• "XERJ ingests 1.72× faster" 之后立刻补上"it also loses four cells: read p99 under a sustained open-loop writer, 13.57 ms against 3.45 ms"；
• "The index is 1.61× smaller on disk, 176.2 MB against 283.0 MB at 100k docs" 之后立刻声明"That is a different measurement from the older disk ratio, not a better result"；
• "kNN at k=10 lands at 1.18×" 之后立刻补上"which the board scores as a tie, with recall@10 at 100% on both engines"；
• 涉及一致性数字时带上"on a curated 200-file subset"这一强制限定。

这正是FC-BENCH-8191规则（claims_rules.py）给出的推荐句式："55 wins, 26 ties, 4 losses and 3 not-applicable across 88 cells against a live Elasticsearch 8.13.4 at 100,000 documents——one of those wins is a recall draw, so read it as 54 W / 27 draws"。旧版"81 of 91 cells at 1M-doc corpus"的分子分母都已被 2026-07-28 更正为 88 cells @ 100k docs，仓库内只以带日期的归档形式保留。

门禁工程实践：如何让你的数字声明过检

factcheck.py是纯标准库的 Python 3.8+ 脚本，无第三方依赖，既可以直接跑单篇，也可以挂进发布流水线（默认扫描content/answers/*.md与content/compare/*.md）：

python3 scripts/seo/factcheck.py # 扫默认目录，ERROR 即失败 python3 scripts/seo/factcheck.py content/answers/x.md # 只查一篇 python3 scripts/seo/factcheck.py --fail-on warn # WARN 也置非零退出码 python3 scripts/seo/factcheck.py --explain FC-NUM-COMPANION # 打印规则的证据与合规改写 python3 scripts/seo/factcheck.py --list-rules # 列出全部规则与层级统计 python3 scripts/seo/factcheck.py --self-test # 校验规则数据自洽 python3 scripts/seo/factcheck.py --fixture-check # 跑 bad_/good_ 夹具，输出混淆矩阵

• 退出码：0 = 无达到--fail-on级别的 finding；1 = 有；2 = 用法或 I/O 错误。severity 分 ERROR（不可支持、必须拦下）与 WARN（启发式或需要人工判断的缺失限定）。
• 数字检查的边界：代码围栏内的数字不参与判定；evidence:条目里出现的数字自动豁免FC-NUM-UNKNOWN。
• 来源必须真实可解析：FC-EV-DANGLING会校验evidence:里的 source 是本仓库存在的路径（支持:line）、https://URL 或Tier A/B: <file>引用；FC-EV-TIERC禁止把 Tier C/已撤回文件写进证据块。
• 禁止引用源（standing rule 7）：landing/product.html第 09 节、demo/playbooks/BENCHMARK_VS_ES.md（仍称合成语料为"真实"）、docs/recipes/migrate-from-elasticsearch.md:214-218都是过时或已撤回的数字来源，一律不得作为数字出处。
• 可复现承诺要谨慎：FC-BENCH-REPRO记录了一个真实教训——曾宣称"四条命令即可复现、意外 LOSE 会失败 CI"，但仓库内没有任何 CI job 运行bench-matrix.mjs，两个命令还引用了 gitignored 的scratchpad/目录。诚实说法是：harness（demo/playbooks/bench-matrix.mjs）与结果文件（demo/playbooks/SCORECARD.md）已提交，包装脚本未提交，也没有 CI 任务跑这套矩阵。

把以上规则收拢成一条写作纪律：引用基准数字前，先查它在TIER_A/TIER_B表里的条目，把what字段的完整测量口径照抄进文章，再把companion.needs要求的限定短语放进同一段落；查不到就删，或者用evidence:指明来源文件。这条纪律同时满足搜索引擎与 LLM 对"可溯源事实"的偏好——每句话都能指回仓库里真实存在的文件与行号。

从数字治理到发布文化

bad_numbers.md这张小小的负面夹具，浓缩的是 XERJ 内容流水线最核心的一条信任机制：数字不是营销资产，而是需要每天维护的证据链。Tier C 名单上那些被撤回的数字（11.5x、6.9x、3.4x、80% 成本下降……）不是被悄悄删掉的，而是被公开登记为"撤回、原因、现值"三要素齐全的档案；四个 mixed 败绩没有从记分板上消失，而是被固定在表格里、注明是已知架构差距并单独追踪。这种"赢的旁边必须站着输"的做法，正是FC-NUM-COMPANION规则反复强调的——发布败绩这个习惯，是项目最值钱的可信度资产。对任何想把性能声明写进文档、博客或营销页的工程师，这套夹具+引擎+分层数字表的组合，都是一个可以直接照搬的参考实现：规则数据与引擎分离、每条规则自带证据与合规改写、负面与正面夹具双轨回归，让"诚实"变成可测试的工程约束，而不是写作时的自觉。

• 人工智能
• 搜索引擎
• 本地部署
• 后端
• MCP 服务