diff --git a/docs/conversation/the-loop.mdx b/docs/conversation/the-loop.mdx
index 976a57a869..5757a92ce6 100644
--- a/docs/conversation/the-loop.mdx
+++ b/docs/conversation/the-loop.mdx
@@ -13,7 +13,7 @@ Claude Code 不一样：你说一个需求，它可能连续执行十几步操
这背后的机制叫做 **Agentic Loop**（智能体循环），核心实现在 `src/query.ts` 的 `queryLoop()` 异步生成器函数（第 241 行）。它是一个 `while(true)` 无限循环，每次迭代代表一次"思考→行动→观察"周期。
-> 图示：[`Agentic Loop 循环图（PNG）`](/docs/images/agentic-loop.png)
+> 图示：[`Agentic Loop 循环图（PNG）`](../../images/agentic-loop.png)
## 循环的完整结构
diff --git a/docs/internals/three-tier-gating.mdx b/docs/internals/three-tier-gating.mdx
index d639faa56b..578e6fc2ec 100644
--- a/docs/internals/three-tier-gating.mdx
+++ b/docs/internals/three-tier-gating.mdx
@@ -72,16 +72,16 @@ keywords: ["门禁系统", "功能门控", "feature flag", "灰度发布", "可
后续四篇文章将分别深入每一层门禁的细节：
-
+
构建时 Feature Flags 的完整分类与解读
-
+
GrowthBook A/B 测试体系的运作机制
-
+
KAIROS、PROACTIVE 等 8 大隐藏功能深度解析
-
+
Anthropic 员工专属的工具、命令与 API
diff --git a/docs/introduction/architecture-overview.mdx b/docs/introduction/architecture-overview.mdx
index 62279198a5..a5b44c4206 100644
--- a/docs/introduction/architecture-overview.mdx
+++ b/docs/introduction/architecture-overview.mdx
@@ -10,7 +10,7 @@ keywords: ["Claude Code 架构", "五层架构", "QueryEngine", "Agentic Loop",
Claude Code 从上到下分为五个层次，每一层职责清晰、边界分明：
-> 图示：[`Claude Code 五层架构图（PNG）`](/docs/images/architecture-layers.png)
+> 图示：[`Claude Code 五层架构图（PNG）`](../../images/architecture-layers.png)
| 层次 | 职责 | 入口源码 | 关键词 |
|------|------|---------|--------|
@@ -22,7 +22,7 @@ Claude Code 从上到下分为五个层次，每一层职责清晰、边界分
## 一条主数据流的源码追踪
-> 图示：[`Claude Code 核心数据流图（PNG）`](/docs/images/data-flow.png)
+> 图示：[`Claude Code 核心数据流图（PNG）`](../../images/data-flow.png)
整个系统的运转可以浓缩为一条核心数据流，以下是每一步对应的源码路径：
diff --git a/docs/research/project-capability-atlas.mdx b/docs/research/project-capability-atlas.mdx
index f5f59c1c16..693f1f7578 100644
--- a/docs/research/project-capability-atlas.mdx
+++ b/docs/research/project-capability-atlas.mdx
@@ -24,7 +24,7 @@ keywords: ["Claude Code", "reverse engineering", "能力图谱", "skills", "MCP"
## 核心图谱区
-> 图示：[`Claude Code 能力全景图（SVG）`](/docs/images/research/capability-overview.svg)
+> 图示：[`Claude Code 能力全景图（SVG）`](../../images/research/capability-overview.svg)
```mermaid
flowchart LR
@@ -48,7 +48,7 @@ flowchart LR
## 模块地图区
-> 图示：[`Claude Code 能力矩阵图（SVG）`](/docs/images/research/capability-matrix.svg)
+> 图示：[`Claude Code 能力矩阵图（SVG）`](../../images/research/capability-matrix.svg)
```mermaid
flowchart TD
@@ -99,7 +99,7 @@ flowchart TD
## 社区核验区
-> 图示：[`Claude Code 社区观点核验图（SVG）`](/docs/images/research/community-verdicts.svg)
+> 图示：[`Claude Code 社区观点核验图（SVG）`](../../images/research/community-verdicts.svg)
| 社区共识 | Verdict | 当前仓库里的证据 |
|---|---|---|
@@ -118,10 +118,10 @@ flowchart TD
建议按 `cli.tsx -> main.tsx -> query.ts -> QueryEngine.ts -> tools.ts -> commands.ts -> loadSkillsDir.ts -> mcp/client.ts -> AppStateStore.ts -> REPL.tsx` 进入。
-
+
继续看 `query.ts` 的 agentic loop 状态机。
-
+
继续看 feature gate、GrowthBook 与 ant-only 的层次关系。
diff --git a/scripts/docs-static-compat.test.mjs b/scripts/docs-static-compat.test.mjs
index 2fae23d8cd..c008502e95 100644
--- a/scripts/docs-static-compat.test.mjs
+++ b/scripts/docs-static-compat.test.mjs
@@ -37,4 +37,20 @@ describe('docs static export compatibility', () => {
expect(offenders).toEqual([]);
});
+
+ it('avoids root-relative /docs links inside MDX content', async () => {
+ const files = await listMdxFiles(join(process.cwd(), 'docs'));
+ const offenders = [];
+ const rootRelativeDocsPattern = /(\]\(\/docs\/|href="\/docs\/|src="\/docs\/)/;
+
+ for (const file of files) {
+ const content = await readFile(file, 'utf8');
+
+ if (rootRelativeDocsPattern.test(content)) {
+ offenders.push(file);
+ }
+ }
+
+ expect(offenders).toEqual([]);
+ });
});