seo-internal-linking

seo-internal-linking (M10)

内链会分配抓取优先级和主题权威性，并告诉搜索引擎（以及 AI 爬虫）页面之间的关联方式。参考：references/schema-tier1.md，了解此拓扑应遵循的实体/@id 链接关系；外部 sameAs 由 M6/seo-entity-linking 负责。

输入

使用调度信封中指定的 PageSnapshot：从 <run_dir>/pages/<slug>.json 读取 parsed（anchors[] 包含 region/internal/anchor，以及 landmarks），并读取 <run_dir>/crawl.json 中的抓取图（graph.edges、pages[].inlinks、templates[]）；对 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. 支柱页/集群页拓扑：对每个 URL 分类（支柱页中心页或集群页），并确认集群页链接到其支柱页，且支柱页链接到其集群页——缺失会破坏中心辐射模型。
2. 正文中的上下文链接：统计 <main>/<article> 正文中的链接（每页目标约为 3-5 个描述性内容内链）；标记正文中没有内链的页面。
3. 锚文本描述性：标记通用锚文本（“点击此处”“阅读更多”“了解更多”、裸 URL）以及过度优化的精确匹配重复；锚文本应描述目标页面。
4. 孤立页面：列出站点地图/抓取图中没有来自其他已抓取页面的入站内链的 URL。
5. 导航与正文链接比例：标记模板中影响上下文链接、稀释单页链接信号的样板导航/页脚链接过多的情况。
6. 语义 HTML：检查是否包含 <main>、<article>、<nav>、<header>、<footer>、一个 <h1>，以及逻辑合理的标题顺序——语义结构有助于解析器和无障碍访问。

修复

• PROPOSED（fixable: proposed）：提出具体的内链插入方案——指定来源页面、目标 URL、建议的锚文本，以及插入链接的句子/选择器——并以统一差异格式输出，供 fix 使用。由于自动插入正文链接可能改变原意、语气或行文流畅度，每项都需要单独接受。
• ADVISORY（fixable: advisory）：描述将内容包裹在语义标签（<main>/<article>/<nav>）中以及修正标题顺序的建议；工具只描述，不会实际修改，因为这些操作会影响模板结构。
• 切勿臆造快照/抓取数据中无法观察到的目标 URL、锚文本或拓扑——应询问用户，或留下明确标注的 TODO 占位符。（此模块发现项的严重性：3。）

验证

• 单页：node "${CLAUDE_PLUGIN_ROOT}/scripts/link-graph.mjs" --snapshot <pages/<slug>.json>（或 --url <u> / --file <path> --base <origin>）会返回该页面的链接概况（verification.method: link_graph）：total_links、internal_unique、external_unique、in_content_target、generic_anchors、empty_anchors、dropped。它不会根据单个页面计算网站拓扑。
• 网站拓扑：读取 <run_dir>/crawl.json（graph.edges、pages[].inlinks、templates[]）——爬取过程已构建这些数据。--crawl [--max 25] [--max-depth 3] [--no-robots] [--ua <preset>] 会重新执行一次浅层的同站点爬取，并添加一个包含 potential_orphans 的 crawl 块（指被爬取但没有来自其他被爬取页面的入站内部链接的页面；起始页面永远不会列入其中，而且脚本本身说明该列表不具权威性）。支柱页/集群页的判断属于基于这些链接边进行的模型工作，并非脚本输出。
• 完整的拓扑/孤立页检查需要进行全站爬取。当无法获取此类爬取数据时，状态为 needs_api——绝不能错误地判定为 pass。

发现项

按 schema/finding.schema.json 输出发现项。示例：

• M10.contextual.too_few_inbody_links——正文中的上下文链接少于约 3 个（状态 warn，严重性 3，fixable: proposed，轴 search，置信度 directional）。
• M10.anchor.generic_text——锚文本为“点击此处”/“阅读更多”（状态 warn，严重性 3，fixable: proposed，轴 search，置信度 directional）。
• M10.orphan.no_incoming_links——该页面没有来自爬取结果的内部入站链接（状态 fail，严重性 3，fixable: advisory，轴 search，置信度 established）。
• M10.semantic.missing_main——主要内容周围没有 <main>/<article> 地标（状态 warn，严重性 3，fixable: advisory，轴 search，置信度 directional）。 每项发现：evidence.observed 引用页面内容（锚文本、链接数量、存在问题的元素）；verification.reproduce 是上文可运行的 link-graph.mjs 命令；expected_impact 采用分档并标注置信度（不能只给出百分比）。

保持准确

• “每页固定 3-5 个链接”是可用性/结构方面的启发式建议，并非排名规则——应将链接数量视为方向性指标，绝不能仅凭这一点给分数设上限。
• 精确匹配锚文本堆砌以及“链接越多 = 权威性越高”都是误区：相关性和编辑语境比单纯数量更重要，过多链接还可能显得像是在操纵排名。只有在确实能帮助读者时才推荐添加链接。