seo-internal-linking

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

seo-internal-linking (M10)

Internal links distribute crawl priority and topical authority and tell search engines (and AI crawlers) how your pages relate. Reference:

references/schema-tier1.md

for the entity/

@id

linkage this topology should mirror; M6/seo-entity-linking owns external

sameAs

内部链接用于分配抓取优先级、传递主题权威性，并告诉搜索引擎（以及 AI 爬虫）各页面之间如何关联。参考：

references/schema-tier1.md

中此拓扑应映射的实体/

@id

关联；外部

sameAs

由 M6/seo-entity-linking 负责。

Inputs

Work from the PageSnapshot named in your dispatch envelope: read

parsed

from

<run_dir>/pages/<slug>.json

(

anchors[]

with

region

internal

anchor

landmarks

) and the crawl graph in

<run_dir>/crawl.json

(

graph.edges

pages[].inlinks

templates[]

); Grep

pages/<slug>.html

for verbatim evidence; site artifacts live in

<run_dir>/site/{robots.json,sitemaps.json,discovery.json}

. Deterministic findings already emitted by

audit.mjs

are listed in

<run_dir>/findings.deterministic.json

— do not re-emit those ids; add model-judged findings only. If invoked directly with a URL/path and no snapshot exists, first run

node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"

and use the printed snapshot path.

以调度信封中指定的 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/路径调用且不存在 snapshot，请先运行

node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"

，并使用打印出的 snapshot 路径。

Audits

Working from the PageSnapshot (

parsed_rendered

when

render.used

is not

none

, else

parsed

Pillar/cluster topology: classify each URL (pillar hub vs. cluster page) and confirm clusters link up to their pillar and the pillar links down to its cluster — gaps break the hub-and-spoke model.
Contextual in-body links: count links inside
```
<main>
```
/
```
<article>
```
prose (target ~3-5 descriptive in-content links per page); flag pages with zero in-body internal links.
Anchor-text descriptiveness: flag generic anchors ("click here", "read more", "learn more", bare URLs) and over-optimized exact-match repetition; anchors should describe the destination.
Orphan pages: list URLs in the sitemap/crawl with no incoming internal links from other crawled pages.
Nav-vs-in-content ratio: flag templates where boilerplate nav/footer links overwhelm contextual links, diluting per-page link signal.
Semantic HTML: check for
```
<main>
```
,
```
<article>
```
,
```
<nav>
```
,
```
<header>
```
,
```
<footer>
```
, one
```
<h1>
```
, and a logical heading order — semantic structure helps both parsers and accessibility.

根据 PageSnapshot 开展审计（当

render.used

不为

none

时使用

parsed_rendered

，否则使用

parsed

）：

Pillar/cluster 拓扑：将每个 URL 归类为 pillar hub 或 cluster page，并确认 cluster 向上链接到对应 pillar，同时 pillar 向下链接到对应 cluster——链接缺口会破坏 hub-and-spoke 模型。
上下文正文链接：统计
```
<main>
```
/
```
<article>
```
正文内容中的链接（目标为每个页面约 3–5 个具有描述性的内容内链接）；标记没有正文内部链接的页面。
锚文本描述性：标记通用锚文本（“click here”“read more”“learn more”、裸 URL）以及过度优化的精确匹配重复；锚文本应描述目标页面。
孤立页面：列出 sitemap/crawl 中没有来自其他已抓取页面的入站内部链接的 URL。
Nav 与内容内链接之比：标记样板 nav/footer 链接压倒上下文链接的模板，因为这会稀释单页链接信号。
语义化 HTML：检查是否具备
```
<main>
```
、
```
<article>
```
、
```
<nav>
```
、
```
<header>
```
、
```
<footer>
```
、唯一的
```
<h1>
```
以及逻辑清晰的标题层级——语义结构有助于解析器和无障碍访问。

Fixes

PROPOSED (
```
fixable: proposed
```
): concrete internal-link insertions — a specific source page, the target URL, the suggested anchor text, and the sentence/selector to attach it to — emitted as a unified diff for
```
fix
```
. These require per-item accept because auto-injecting body links can alter meaning, tone, or reading flow.
ADVISORY (
```
fixable: advisory
```
): wrapping content in semantic tags (
```
<main>
```
/
```
<article>
```
/
```
<nav>
```
) and heading-order corrections — described, never written by the tool, since they touch template structure.
Never invent target URLs, anchor wording, or topology you cannot observe in the snapshot/crawl — ask the user or leave a clearly-marked TODO placeholder. (Severity for this module's findings: 3.)

PROPOSED（
```
fixable: proposed
```
）：具体的内部链接插入建议——包括具体来源页面、目标 URL、建议锚文本以及要附加链接的句子/选择器——以 unified diff 的形式输出，供
```
fix
```
使用。由于自动向正文注入链接可能改变含义、语气或阅读流畅性，因此必须逐项接受这些建议。
ADVISORY（
```
fixable: advisory
```
）：使用语义化标签包裹内容（
```
<main>
```
/
```
<article>
```
/
```
<nav>
```
）以及修正标题顺序——仅作说明，绝不由工具写入，因为这些修改会触及模板结构。
绝不能捏造在 snapshot/crawl 中无法观察到的目标 URL、锚文本措辞或拓扑；应询问用户，或保留明确标记的 TODO 占位符。（本模块发现的严重级别：3。）

Verification

Per page:

node "${CLAUDE_PLUGIN_ROOT}/scripts/link-graph.mjs" --snapshot <pages/<slug>.json>

(or

--url <u>

--file <path> --base <origin>

) returns that page's link profile (

verification.method: link_graph

total_links

internal_unique

external_unique

in_content_target

generic_anchors

empty_anchors

dropped

. It does not compute topology from one page.

Site topology: read
```
<run_dir>/crawl.json
```
(
```
graph.edges
```
,
```
pages[].inlinks
```
,
```
templates[]
```
) — the crawl already built it.
```
--crawl [--max 25] [--max-depth 3] [--no-robots] [--ua <preset>]
```
runs a fresh shallow same-site crawl and adds a
```
crawl
```
block with
```
potential_orphans
```
(a crawled page with no inbound internal link from another crawled page; the start page is never one, and the script itself calls the list non-authoritative). Pillar/cluster judgement is model work on top of those edges, not a script output.
The full topology/orphan check needs a site-wide crawl tier. When that crawl data is unavailable, status is
```
needs_api
```
— never a false
```
pass
```
.

逐页执行：

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
```
块（已抓取但没有来自其他已抓取页面的入站内部链接的页面；起始页永远不会属于该列表，且脚本自身称此列表不具权威性）。Pillar/cluster 判断是在这些边之上由模型完成的工作，而不是脚本输出。
完整的拓扑/孤立页面检查需要全站点范围的抓取层级。当抓取数据不可用时，状态应为
```
needs_api
```
——绝不能给出虚假的
```
pass
```
。

Findings

Emit findings per

schema/finding.schema.json

. Examples:

```
M10.contextual.too_few_inbody_links
```
— fewer than ~3 contextual in-body links (status
```
warn
```
, severity 3,
```
fixable: proposed
```
, axis
```
search
```
, confidence
```
directional
```
).
```
M10.anchor.generic_text
```
— anchor reads "click here"/"read more" (status
```
warn
```
, severity 3,
```
fixable: proposed
```
, axis
```
search
```
, confidence
```
directional
```
).
```
M10.orphan.no_incoming_links
```
— page has no internal inlinks from the crawl (status
```
fail
```
, severity 3,
```
fixable: advisory
```
, axis
```
search
```
, confidence
```
established
```
).
```
M10.semantic.missing_main
```
— no
```
<main>
```
/
```
<article>
```
landmark around primary content (status
```
warn
```
, severity 3,
```
fixable: advisory
```
, axis
```
search
```
, confidence
```
directional
```
). Each finding:
```
evidence.observed
```
quotes the page (the anchor text, the link count, the offending element);
```
verification.reproduce
```
is the runnable
```
link-graph.mjs
```
command above;
```
expected_impact
```
is banded + confidence-tagged (no naked percentages).

按照

schema/finding.schema.json

输出发现。示例：

```
M10.contextual.too_few_inbody_links
```
——少于约 3 个上下文正文链接（状态
```
warn
```
，严重级别 3，
```
fixable: proposed
```
，轴
```
search
```
，置信度
```
directional
```
）。
```
M10.anchor.generic_text
```
——锚文本为“click here”/“read more”（状态
```
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
```
使用分档和置信度标签（不得使用无依据的百分比）。

Honesty

A fixed "3-5 links per page" is a usability/structure heuristic, not a ranking law — treat the count as directional and never cap a score on it alone.
Exact-match anchor stuffing and "more links = more authority" are myths: relevance and editorial context matter more than raw count, and excess can look manipulative. Recommend links only where they genuinely help the reader.

固定的“每页 3–5 个链接”是可用性/结构方面的启发式规则，而非排名法则——应将其视为方向性指标，绝不能仅依据该指标对分数设上限。
精确匹配锚文本堆砌和“链接越多，权威性越高”是误区：相关性和编辑语境比原始数量更重要，过量链接还可能显得具有操纵性。仅在链接确实能帮助读者时提出建议。