Front-End-Checklist 规则解析：Affiliate Disclosure 联盟链接披露规则的落地与验证

本文围绕 Front-End-Checklist 仓库中的 affiliate-disclosure 这条 SEO 规则展开，讲清它「检查什么、如何修复、为什么重要、如何验证」的完整闭环，并结合仓库里从 MDX 规则到 Agent Skill 的生成链路（generate-skills.ts）说明该规则如何被机器检索与消费。读完你能掌握：披露文案的合规写法与放置位置、如何对渲染后的 HTML 做自动化核查，以及这条规则在规则目录、Skill、相关规则（disclaimers/ymyl）中的定位关系。

一、这条规则解决什么问题

联盟链接（affiliate link）与赞助内容页面，如果不在读者接触链接之前就明确告知「本页面包含推广链接，我们可能获得佣金」，就会触碰消费者保护法规（如 FTC 指引）并损害用户信任，还可能被搜索引擎判定为隐藏广告、进而影响收录与排名。

仓库用一句话概括了这条规则的意图，出自规则正文的 whyItMatters：

Clear disclosures are required by law (e.g., FTC guidelines) and are essential for maintaining user trust and preventing search engine penalties for hidden advertisements.

它属于 seo 分类、content 子类，优先级为 medium、难度 intermediate、预计耗时 10 分钟。这些元数据直接写在 MDX 的 frontmatter 中（affiliate-disclosure.mdx）。

二、规则的三处载体：MDX 源、Skill 入口、Skill 参考

在 Front-End-Checklist 中，同一条规则会以三种形态存在于仓库里，理解它们的关系有助于「既能人读、也能被 Agent 检索」：

1. 规则源文件（单一事实来源）：affiliate-disclosure.mdx，以 YAML frontmatter + MDX 正文承载全部元数据、tldr、prompts（check/fix/explain/codeReview）以及 sources、resources、relatedRules。
2. Agent Skill 入口：SKILL.md，供 LLM/Agent 做意图匹配与快速指令调用，文件短小，只放 frontmatter 派生出的「Quick Reference / Check / Fix / Explain / Code Review」。
3. Agent Skill 参考正文：rule.md，是 MDX 正文剥离 JSX 后的纯 Markdown 版本，含完整代码示例、Why It Matters、Exceptions、Verification。

2.1 SKILL.md 的 frontmatter 字段

SKILL.md 顶部的 frontmatter 决定 Agent 何时「命中」这条技能，各字段含义如下：

字段	当前取值	作用
name	affiliate-disclosure	技能唯一标识，需与目录名一致（skill-check 校验 name_matches_directory）
description	Use when auditing metadata, crawlability, structured data, or indexability ...	供 Agent 做意图匹配，需以 Use when 开头，且建议 ≥ 50 字符
metadata.category	seo	所属规则大类
metadata.priority	medium	优先级（critical/high/medium/low）
metadata.difficulty	intermediate	难度（beginner/intermediate/advanced/expert）
metadata.estimatedTime	10	预估耗时（分钟）
metadata.source / metadata.url	frontendchecklist.io	来源站点与规则页地址

其中 description 并非手写，而是从 MDX 的 aiContext 字段派生而来——这正是「以规则为源、生成技能」这一设计的关键。

2.2 MDX frontmatter 的关键字段

affiliate-disclosure.mdx 中，除 title、description、categories、priority、difficulty、estimatedTime 外，还有几个驱动下游产出的核心字段：

• tldr：三条「快速参考」要点，直接成为 SKILL.md 的 ## Quick Reference。
• prompts.check / fix / explain / codeReview：四个指令段落，分别成为 SKILL.md 的同名小节。
• aiContext：被提升为 SKILL.md 的 description（见 2.1）。
• sources：标注了 Google Search Central 相关文档作为一级（primary）依据，role 区分 search / implementation。
• resources：指向 Google Search Console 这类可用工具。
• relatedRules：列出 disclaimers、about-page、anchor-text、author-byline 等常一起审查的规则。

三、Quick Reference：披露文案的三条硬性要求

这部分来自 MDX 的 tldr，也是 SKILL.md 的 ## Quick Reference：

• Add a clear and conspicuous disclosure for any affiliate or sponsored links（为任何联盟/赞助链接添加清晰且醒目的披露）。
• Place the disclosure at the top of the page, before any affiliate links appear（披露要放在页面顶部、任何联盟链接出现之前）。
• Use simple, unambiguous language to explain the financial relationship（用简单、无歧义的语言说明经济关系）。

要点是「位置在前、措辞明确、视觉醒目」三者缺一不可：披露不能埋在页脚或折叠在「阅读全文」之后，也不能用极小字号（对应 disclaimers 规则中「不要 8pt 字号、不要折叠」的要求）。

四、Check / Fix / Explain / Code Review：四个操作指令

SKILL.md 把规则拆成四个可直接执行的指令段落，分别回答「查什么」「怎么改」「为什么」「代码审查怎么做」。

4.1 Check（检查什么）

Verify that all pages containing affiliate links or sponsored content have a clear, visible disclosure before the links appear.

即：逐一核对包含联盟链接或赞助内容的页面，确认在链接出现之前存在一条清晰可见的披露。

4.2 Fix（如何修复）

Add a standardized disclosure statement at the beginning of your content or near affiliate links to inform users of the partnership.

即：在内容开头或联盟链接附近，加入一段标准化的披露声明。落地时建议全站统一同一份披露文案，避免不同页面措辞不一致。

4.3 Explain（为什么重要）

Explain the legal and ethical importance of affiliate disclosures and how they impact user trust and SEO.

对应正文 Why It Matters 的四个维度（见第五节），用于向非技术读者/业务方解释合规与信任价值。

4.4 Code Review（代码层面如何审）

Review metadata generation, rendered HTML, structured data, and response headers related to Provide clear affiliate disclosures. Flag exact routes or templates where search-facing output violates the rule, and describe how to verify the final page output.

这一条强调两点：不要只看源码文件，而要核对最终面向搜索的输出（渲染后的 HTML、结构化数据、响应头）；并且要精确到具体路由或模板指出违规处，同时说明如何验证最终页面输出。这也呼应了 frontmatter 中 aiContext 的提醒——「Verify the rendered HTML and HTTP response rather than relying only on source files」。

五、完整代码示例与 Why It Matters

下面这段 HTML 示例同时出现在 rule.md 与 affiliate-disclosure.mdx，是「披露放在标题之后、正文与联盟链接之前」的标准形态：

<article>
  <header>
    <h1>The Best Laptops for Developers in 2024</h1>
    <div class="disclosure" style="background: #f9f9f9; padding: 10px; border-radius: 4px;">
      <p><small><em>Disclaimer: This post contains affiliate links. If you click on one and make a purchase, we may receive a small commission at no extra cost to you.</em></small></p>
    </div>
  </header>

  <p>Looking for a new laptop? Here are our top recommendations...</p>
</article>

要点拆解：

• 披露块放在 <header> 内、紧跟 <h1>，早于任何正文与外链出现；
• 使用带背景色、内边距、圆角的独立 <div class="disclosure">，视觉与正文区分开；
• 文案同时说明「含联盟链接 + 点击购买我们可能获得佣金 + 对用户不额外收费」，信息完整无歧义。

与之形成对照的，是 disclaimers.mdx 中给出的更「强约束」版本——把披露放在 <h1> 之前，并额外链接到完整的 affiliate policy：

<article>
  <p class="affiliate-disclosure">
    <em>Disclosure: This post contains affiliate links. If you purchase
    through these links, we earn a small commission at no extra cost to you.
    <a href="/affiliate-policy">Read our full affiliate policy.</a></em>
  </p>

  <h1>Best Project Management Tools in 2024</h1>
  <p>We recommend <a href="https://example.com/?ref=affiliate">ToolName</a>
     for its ease of use...</p>
</article>

这里额外做了两件事：用 ?ref=affiliate 这类可识别的推荐参数标识联盟链接；用 <a href="/affiliate-policy"> 把简短行内披露升级到完整政策页——这正是 disclaimers 规则中「当简短行内披露不够时，链接到更完整的政策页」这一放置准则的体现。

Why It Matters（四个维度）

• Legal Compliance（合规）：符合 FTC 及其他国际针对在线广告的监管要求。
• User Trust（用户信任）：坦诚与透明长期可带来更高的转化率。
• SEO Quality（搜索质量）：避免被判定为「sneaky redirects」或隐藏联盟计划而影响排名。
• E-E-A-T：支撑其中的「Trust（可信度）」支柱，证明没有隐藏经济动机。

六、Exceptions：哪些情况应放宽判定

rule.md 与 MDX 的 Exceptions 段落列出了三条需要「避免过度判定」的边界，审查时不应机械套用同一标准：

• 必要的工具页/合规页可以刻意简短，不应以「排名向内容」的编辑深度标准去衡量。
• AI 辅助起草本身不算失败；应关注的是「无支撑的断言、缺少编辑复核、原创度低」等问题。
• 当某页面同时存在「信任信号问题」和「抓取/收录问题」时，应先让页面具备可排名资格（eligible to rank），再逐步优化内容质量信号。

七、Verification：自动化与人工核查

规则把验证分为两类，直接继承了 rule.md 的 Verification 段落：

7.1 Automated Checks（自动化）

• Inspect rendered HTML and HTTP headers to confirm the expected metadata or crawlability signal is present（检查渲染后的 HTML 与 HTTP 头，确认预期的元数据/可抓取信号确实存在）。
• Test the affected URL with Google Search Console or equivalent tooling where relevant（在相关时用 Search Console 或等价工具测试受影响 URL）。
• Re-crawl a representative page set after deployment（部署后对代表性页面集重新爬取）。

落到实操上，最核心的一条是「看渲染结果而非源码」。可以这样组织核查：对目标页面抓取渲染后的 HTML，确认披露文本出现在 DOM 中、且其位置早于第一个带联盟参数的 <a> 节点；再用 Search Console 的 URL 检查确认该页可被正常抓取与收录。

7.2 Manual Checks（人工）

• Confirm the change does not create conflicting canonical-url, robots, or structured-data signals（确认改动没有制造相互冲突的 canonical-url、robots 或结构化数据信号）。

这一步提醒：补披露只是内容改动，需顺带确认没有破坏 canonical/robots/结构化数据等其它 SEO 信号，避免「治一个、坏两个」。

八、从 MDX 到 Skill 的生成链路（仓库如何产出这条技能）

上面三处文件并非手工各自维护，而是由 generate-skills.ts 统一从 packages/content/rules/en 下的规则 MDX 生成。理解这条链路能解释「为什么 SKILL.md 这么短、rule.md 是 MDX 的纯 Markdown 化」。关键逻辑：

• 读取与解析：processRuleFile 用 gray-matter 解析 MDX，取出 data（frontmatter）与 content（正文）。
• 生成 SKILL.md：buildSkillMd 从 frontmatter 组装——whyItMatters 直接成段，tldr 展开为 ## Quick Reference，prompts.check/fix/explain/codeReview 展开为对应小节；description 优先取 aiContext，并以 Use when 开头、不足 50 字符时补全。
• 生成 rule.md：buildReferencesMd 生成标题、描述与 **Priority:** … **Difficulty:** … **Time:** … min 的元信息头，再拼接正文；正文经 stripMdxToMarkdown 去除 import/export、JSX 组件标签，保留代码块、标题、列表、表格，得到纯 Markdown。
• 目录与命名：输出到 skills/{skillName}/（扁平结构，满足 skill-check 的 name_matches_directory）；当同一 slug 在多个分类下重复时，findDuplicateSlugs 会为其加分类前缀以避免冲突。
• 运行方式（仓库只读，仅供查看/执行）：
  • pnpm generate:skills 全量重新生成所有规则；
  • pnpm generate:skills path/to/rule.mdx ... 针对指定文件增量生成（Lefthook 钩子会传入被暂存的 MDX）。

因此 SKILL.md 末尾那句「For full implementation details, code examples, and framework-specific guidance, see references/rule.md」是模板固定输出的跳转提示，指向本技能目录下的 rule.md。

此外还有一条全局聚合技能 frontend-checklist-global/SKILL.md，把所有规则接入统一的 MCP 检索入口；affiliate-disclosure 作为 seo 分类下的一条规则，会被纳入该入口的覆盖范围，供 Agent 通过 search_rules/get_rule/fix_rule 等工具按需检索，而非要求模型「凭记忆」复述规则内容。

九、与相关规则的边界：何时用 affiliate-disclosure，何时用 disclaimers

affiliate-disclosure.mdx 的 relatedRules 把 disclaimers 等列为常一起审查的规则，二者容易混淆，区别在于关注点：

• affiliate-disclosure（本篇主题）：只聚焦「联盟/赞助关系」的披露——是否在前、是否醒目、措辞是否说明经济关系，依据是 FTC 这类联盟广告披露规范。
• disclaimers：覆盖面更广，针对医疗、法律、金融、安全（YMYL）以及 AI 生成内容等敏感类型，要求「非专业建议」类免责声明，并依据 E-E-A-T 的可信度评估；其 codeReview 还会具体扫描 <a> 中是否带推荐参数或联盟域名。

可以这样判断：页面核心问题是「有没有告诉读者这里含推广链接、我们可能拿佣金」→ 用 affiliate-disclosure；问题是「敏感内容是否给了免责/不构成专业建议的声明」→ 用 disclaimers。两者常在同一页同时成立，审查时一并过即可。

十、小结

affiliate-disclosure 这条规则的价值不在于一段固定文案，而在于一套「位置在前 + 措辞明确 + 视觉醒目 + 验证看渲染结果」的可执行标准，并通过 MDX 源 → SKILL.md/rule.md 的生成链路（generate-skills.ts）让同一套标准既能被开发者阅读、又能被 Agent 精确检索与落地。实际执行时，记住四条：核对每个含联盟链接的页面、把披露放在链接之前、用统一且无歧义的文案、最后用渲染后 HTML（而非源码）验证披露确实出现在第一个联盟链接之前，同时不引入 canonical/robots/结构化数据的冲突信号。