seo-entity-linking

seo-entity-linking (M6)

实体关联会告诉搜索引擎和 AI 系统，页面介绍的是哪个现实世界中的事物，并将其关联到知识图谱。参考：references/schema-tier1.md（sameAs/@id/Person+Organization 规则）。本模块负责 M5 延后到此处处理的 sameAs 细节。

输入

根据调度信封中指定的 PageSnapshot 开展工作：从 <run_dir>/pages/<slug>.json 读取 parsed（jsonld[]、anchors[]）；在 pages/<slug>.html 中使用 Grep 查找逐字证据；站点资料位于 <run_dir>/site/{robots.json,sitemaps.json,discovery.json}。audit.mjs 已输出的确定性检查结果列在 <run_dir>/findings.deterministic.json 中——不要重复输出这些 ID；只添加由模型判定的检查结果。如果直接使用 URL/路径调用，且不存在快照，则先运行 node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"，并使用打印出的快照路径。

审计

基于 PageSnapshot 开展工作（当 render.used 不为 none 时使用 parsed_rendered，否则使用 parsed）：

1. sameAs 身份链接：对于 Organization/Person 实体，检查 sameAs[] 是否指向可解析的身份资料——Wikidata QID、Wikipedia、LinkedIn、Crunchbase、官方社交账号/公司资料。Wikidata 是最有力的知识图谱目标。
2. 主要实体定义：确认每个页面恰好有一个明确的主要实体（通过 @id + mainEntity/mainEntityOfPage），不存在主体模糊或缺失的情况。
3. 实体一致性（本地）：对于 LocalBusiness，验证 schema 中的 NAP（名称、地址、电话）是否与页面上可见的 NAP 一致，并确保不同区块之间内容一致。
4. 实体密度：统计不同的已关联/已标记实体（带 @id 的节点、sameAs 目标、about/mentions）——对于没有可解析实体引用的内容单薄页面发出标记。

修复

• AUTO（fixable: auto）：仅使用用户确认的 URL，为 Organization/Person 注入 sameAs[] 数组，并为现有 schema 添加 about/mentions 实体引用。为 fix 提供增量、确定性的差异。绝不虚构身份链接——如果 URL 未经确认，则留下清晰标记的 TODO 占位符，由用户填写。
• PROPOSED（fixable: proposed）：通过查找发现候选 Wikidata/LinkedIn 匹配项——拟定后由人工逐项接受，绝不自动写入。
• ADVISORY（fixable: advisory）：在不存在实体时提供“建立 Wikidata 实体 / 认领资料”的建议——仅提供指导，工具不会写入任何内容。

验证

• dom_assert：确认解析后的 JSON-LD 中存在格式正确的 sameAs/@id/mainEntity。
• 解析每个 sameAs URL（Tier 1 Wikidata 查找），确认链接有效且指向所声明的实体——失效或不匹配的链接应判定为失败，而非通过。
• 当无法使用实时查找层时，状态应为 needs_api，绝不能错误地标记为 pass。

发现

按照 schema/finding.schema.json 输出发现；轴为 ai；置信度始终为 directional——这些内容均未得到供应商文档证实。严重性策略：5 仅用于网站／模板层面具有灾难性、会导致失去资格的事实；4 为重大 · 3 为中等 · 2 为轻微 · 1 为表面 · 0 为信息性——且只有处于活跃类别中的 established 严重性 5 fail 才能限制评分（references/scoring-model.md）。

• M6.organization.missing_sameas — Organization 没有 sameAs[]（fail，严重性 3，fixable: proposed）。
• M6.page.no_primary_entity — 页面上没有单一且明确定义的主要实体（@id / mainEntity）（warn，严重性 3，fixable: advisory）。
• M6.entity.thin_density — 页面提到了真实组织、人物或产品，但标记中没有任何可解析的实体引用（warn，严重性 3，fixable: advisory）。
• M6.person.no_wikidata_link — 作者 Person 没有 Wikidata/LinkedIn 身份链接（warn，严重性 2，fixable: proposed）。
• M6.sameas.unresolvable — 声明的 sameAs URL 返回 404，或指向不同实体（fail，严重性 3，fixable: proposed）。 每项发现：evidence.observed 引用页面内容（实体块或其缺失情况）；verification.reproduce 是可运行的断言／查询；expected_impact 按范围划分并标注置信度（不得只写百分比）。

诚信原则

• sameAs 链接不会强制实体进入知识图谱，也不保证排名提升——它只是消歧信号，因此影响始终为 directional，绝不能标为 established。
• 绝不捏造、猜测或以“尽力而为”的方式填写身份 URL 来提高实体密度——错误的 sameAs 会主动误导搜索引擎，其危害大于空数组。只使用已确认的信息，否则保留为 TODO。
• 实体密度只是“此页面关于某个特定且可解析的事物”的代理指标，并非任何搜索引擎发布的指标；不要为了追求数值而盲目优化。