开发者文档中的代码块看起来完全正确不代表用户点击“复制”后拿到的文本也完全相同。真正难发现的问题往往不是整段内容丢失而是一个尾随换行、一级缩进、Tab 与空格、不可见字符、全角或 Unicode 标点甚至同一个字符的不同 Unicode 组合形式。截图测试看不出来普通的 DOM 断言也可能全部通过但用户粘贴到终端或配置文件后却会失败。问题到底发生在哪一层一段文档代码从维护者写下到进入用户剪贴板至少经过四个阶段规范源文件 - 页面渲染结果 - 复制处理器参数 - 浏览器剪贴板只检查code元素最多证明页面“显示正确”。复制按钮自己的处理函数仍可能执行trim()、删除提示符、转换换行或者读取了错误的元素。即便处理器传入的字符串正确浏览器和操作系统剪贴板层也可能发生行尾转换。因此可靠的检测不能只有“相等/不相等”一个结论还应说明差异第一次出现在哪一层。最小成本先对公开页面做侦察我把这套思路实现成了开源工具 Snippet Fidelity。最简单的用法是在 GitHub Actions 中提供一个公开文档地址name:snippet-fidelityon:workflow_dispatch:permissions:contents:readjobs:audit:runs-on:ubuntu-lateststeps:-uses:WLDKK/snippet-fidelityv0with:url:https://docs.example.com/getting-started/它会启动真实 Chromium寻找代码块附近可访问的复制按钮触发按钮并观察处理器与浏览器剪贴板。此时基准来自页面已经渲染出的code文本所以适合发现线索和回归问题但不能证明页面与源码完全一致。严格模式让仓库文件成为规范来源如果要把检测作为合并或发布门禁就应该在仓库中保存规范片段并明确复制按钮选择器{$schema:https://raw.githubusercontent.com/WLDKK/snippet-fidelity/v0/schema/config.schema.json,version:1,baseUrl:https://docs.example.com/,pages:[{url:getting-started/,checks:[{id:install-command,button:#install-command button[aria-labelCopy code],expected:{file:./snippets/install.sh},probe:both}]}]}这样才能分别回答源文件到页面渲染是否变化页面文本到复制处理器参数是否变化处理器参数到浏览器剪贴板是否变化。报告默认不输出完整代码只记录长度、SHA-256 指纹、差异类型以及第一个不同 Unicode 码点附近的有限上下文。这既便于 CI 定位也减少日志泄露代码片段的风险。在真实文档站点上得到的教训我曾对三个仍在维护的公开文档站点做侦察测试Starlight 的三个检查完全一致Material for MkDocs 的多个代码块在复制时稳定省略页面中的末尾换行Doc Detective 的复制结果省略了页面显示的 shell 提示符。后两种行为很可能是为了方便粘贴而有意设计的因此不能仅凭侦察结果就宣称它们是缺陷。只有维护者提供规范来源后差异才适合作为发布阻断条件。这次试点还反过来发现了工具自身的问题许多文档标签页会把未激活的代码块继续挂在 DOM 中早期版本因此尝试点击隐藏的重复按钮。修复后工具会排除未渲染的控件同时保留悬停后才显示的复制按钮并用端到端测试锁定这一行为。如何复现五类隐蔽错误仓库中提供了一个对抗性测试页面包含一个正确按钮和五个故意制造的错误pnpminstallpnpmbuildpnpmfixture# 另开一个终端nodedist/cli.js audit--configexamples/adversarial-fixture.config.json预期结果是 1 个通过、5 个失败。如果命令返回全部通过反而说明测试夹具失去了作用。工具边界这不是通用文档测试框架也不是剪贴板管理器。它不会执行复制出来的命令不会自动改写或“修复”剪贴板内容当基准来自渲染后的 DOM 时也不会夸大为源码一致性证明。当前 0.4 版本只驱动 Chromium自动发现仍是启发式能力严肃的发布门禁应使用明确选择器和规范源文件。项目采用 MIT 许可证仓库地址https://github.com/WLDKK/snippet-fidelity如果你维护公开的开发者文档也可以提交一个页面用于公开审计。尤其欢迎包含复杂空白、自动生成片段、标签页或 Unicode 内容的真实案例。
