diff --git a/docs/index.md b/docs/index.md
index fd4cad9..292fd64 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,24 +1,33 @@
-# **S**cripts**F**or**M**ine**c**raftServer
+# ScriptsForMinecraftServer
 
 > 一套 Minecraft Bedrock Script API (SAPI) 行为包 + Node.js 仓顶服务的 monorepo。
 >
-> 🎉 在**原生BDS**即可获得类似插件服的**高效、安全、扩展丰富**的体验
+> 在**原生 BDS**即可获得类似插件服的**高效、安全、扩展丰富**的体验
 
-* 提供基于[Minecraft Script API](https://learn.microsoft.com/zh-cn/minecraft/creator/scriptapi/?view=minecraft-bedrock-stable)的**原生脚本SDK**
-* 外置可拆卸的**模块化管理**服务，拥有类似插件服的舒适体验；目前已开发[22+实用模块](https://github.com/Tanya7z/sfmc-modules)
-* 为BDS服务器提供的多功能、易用的cli工具，涵盖**自动更新**，**模块管理**，**资源包管理**，**远程控制**等功能
-* 为模块提供**Sqlite数据库管理SDK**及其路由服务
-* 自建工作流，使模组/模块开发更轻松
-* 依赖于[LLBOT](https://www.llonebot.com/zh-CN/)的QQ桥接服务，轻松实现群服互通
+[在线地址 →](https://dogelakedev.github.io/ScriptsForMinecraftServer)
+[模块仓库 →](https://github.com/Tanya7z/sfmc-modules)
+## 文档目录
 
-[模块仓库 →](https://github.com/Tanya7z/sfmc-modules)  
+| 分类 | 入口 |
+|------|------|
+| 使用指南 | [guide/](./guide/index.md) |
+| 开发指南 | [dev/](./dev/index.md) |
+| 接口指南 | [api/](./api/index.md) |
+| SDK 类型参考 | [reference/](./reference/index.md)（`npm run docs:api`） |
+
+* 提供基于 [Minecraft Script API](https://learn.microsoft.com/zh-cn/minecraft/creator/scriptapi/?view=minecraft-bedrock-stable) 的**原生脚本 SDK**
+* 外置可拆卸的**模块化管理**服务，拥有类似插件服的舒适体验；目前已开发 [22+ 实用模块](https://github.com/Tanya7z/sfmc-modules)
+* 为 BDS 服务器提供的多功能、易用的 CLI 工具，涵盖**自动更新**、**模块管理**、**资源包管理**、**远程控制**等功能
+* 为模块提供 **SQLite 数据库管理 SDK** 及其路由服务
+* 自建工作流，使模组/模块开发更轻松
+* 依赖于 [LLBot](https://www.llonebot.com/zh-CN/) 的 QQ 桥接服务，轻松实现群服互通
 
 [![version](https://img.shields.io/github/v/tag/DogeLakeDev/ScriptsForMinecraftServer?style=flat-square&label=version)](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/tags)
-[![license](https://img.shields.io/github/license/DogeLakeDev/ScriptsForMinecraftServer?style=flat-square)](./LICENSE)
+[![license](https://img.shields.io/github/license/DogeLakeDev/ScriptsForMinecraftServer?style=flat-square)](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/LICENSE)
 [![node](https://img.shields.io/badge/node-22.13%2B-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
 [![typescript](https://img.shields.io/badge/TypeScript-6.0.2-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 [![npm](https://img.shields.io/badge/npm-@sfmc--bds%2Fsfmc-CB3837?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@sfmc-bds/sfmc)
-[![modules](https://img.shields.io/badge/modules-25-7B68EE?style=flat-square&logo=cube&logoColor=white)](./modules/catalog.json)
+[![modules](https://img.shields.io/badge/modules-25-7B68EE?style=flat-square&logo=cube&logoColor=white)](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/modules/catalog.json)
 [![bd](https://img.shields.io/badge/BDS-1.26.x-00BC8C?style=flat-square&logo=minecraft)](https://www.minecraft.net/en-us/download/server/bedrock)
 
 ---
@@ -28,15 +37,15 @@
 ### npm 聚合包
 
 ```bash
-> node -v   # 需要 v22.13+
-> npm install -g @sfmc-bds/sfmc # 或 beta 版：npm install -g @sfmc-bds/sfmc@beta
-> mkdir my-server && cd my-server
-> sfmc
+node -v   # 需要 v22.13+
+npm install -g @sfmc-bds/sfmc@beta
+mkdir my-server && cd my-server
+sfmc
 ```
 
-> 当前阶段仅发 **beta**；请带 `@beta` 安装。见 [npm 发布指南](./docs/dev/npm-publish.md)。
+> 当前阶段仅发 **beta**；请带 `@beta` 安装。见 [npm 发布指南](./dev/npm-publish.md)。
 
-开发者也可克隆本仓 monorepo，见 [安装指南](./docs/guide/install.md)。
+开发者也可克隆本仓 monorepo，见 [安装指南](./guide/install.md)。
 
 ## 架构图
 
@@ -49,29 +58,20 @@ flowchart LR
   SFMC["sfmc CLI"] -. 管理 .-> BDS & DB & QQ
 ```
 
-## 快速入门
-
-| 分类 | 入口 |
-| ------ | ------ |
-| 使用指南 | [docs/guide/](./docs/guide/index.md) |
-| 开发指南 | [docs/dev/](./docs/dev/index.md) |
-| 接口指南 | [docs/api/](./docs/api/index.md) |
-| SDK 类型参考 | [docs/reference/](./docs/reference/index.md)（`npm run docs:api`） |
-
 ## 路线图
 
-* ✅ **Stage I**:per-module `sapi/manifest.json` + db-server reader
-* ✅ **Stage J**:`shared/*` 迁入 `@sfmc-bds/sdk`,22 模块迁出
-* ✅ **Stage K**:模块按需安装 —— populate 由 `tools/fetch-module.mjs` / `sfmc module install` 完成
-* 🚧 **Stage L**:模块 zip 自动解压、`sfmc module install --enable-and-deploy` 一条龙
-* 🚧 **Stage M**:模块签名 / 公钥验证(取代纯 SHA-256 指纹)
-* 🚧 **Stage N+**:服务网格(多 BDS 实例 / 跨节点)
+* ✅ **Stage I**: per-module `sapi/manifest.json` + db-server reader
+* ✅ **Stage J**: `shared/*` 迁入 `@sfmc-bds/sdk`，22 模块迁出
+* ✅ **Stage K**: 模块按需安装 —— populate 由 `tools/fetch-module.mjs` / `sfmc module install` 完成
+* 🚧 **Stage L**: 模块 zip 自动解压、`sfmc module install --enable-and-deploy` 一条龙
+* 🚧 **Stage M**: 模块签名 / 公钥验证（取代纯 SHA-256 指纹）
+* 🚧 **Stage N+**: 服务网格（多 BDS 实例 / 跨节点）
 
 ## 许可证
 
-[AGPL-3.0](./LICENSE)  
+[AGPL-3.0](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/LICENSE)
 
 * **自由**：您可以运行、复制、分发、修改程序，但必须保持这些自由。
 * **Copyleft**：如果您分发修改后的版本，必须以相同许可证（AGPL v3）提供完整的源代码。
-* **源代码**：必须提供“对应源代码”（Corresponding Source），包括所有脚本、接口定义、共享库等，以便他人能重新构建和修改。
+* **源代码**：必须提供「对应源代码」（Corresponding Source），包括所有脚本、接口定义、共享库等，以便他人能重新构建和修改。
 * **附加条款**：您可以添加额外许可，但不能增加限制（第 7 条）。
diff --git a/mkdocs.yml b/mkdocs.yml
index 5c34d4b..4c70f17 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -94,5 +94,6 @@ extra:
 validation:
   omitted_files: warn
   absolute_links: ignore
-  unrecognized_links: ignore
+  # warn：暴露 README→docs 误贴等坏链；不 fail，以免外部/生成页误伤 CI
+  unrecognized_links: warn
   anchors: warn
diff --git a/tools/docs-mkdocs.mjs b/tools/docs-mkdocs.mjs
index 2c9a933..fa249fa 100644
--- a/tools/docs-mkdocs.mjs
+++ b/tools/docs-mkdocs.mjs
@@ -7,7 +7,7 @@
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const mode = process.argv[2] ?? "serve";
@@ -17,6 +17,46 @@ if (!["serve", "build"].includes(mode)) {
   process.exit(1);
 }
 
+/**
+ * MkDocs docs_dir=docs：页面内相对链接不应再带 ./docs/ 前缀。
+ * 把 README（仓根路径）原样贴进 docs/*.md 会导致站内导航全断，且默认
+ * unrecognized_links=ignore 时 CI 不会拦。在此做契约检查。
+ */
+function assertNoRepoRootDocsLinks(docsDir) {
+  const bad = [];
+  const stack = [docsDir];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const ent of readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        // TypeDoc 输出目录跳过；plan/archive 由 mkdocs exclude
+        const rel = path.relative(docsDir, full).replace(/\\/g, "/");
+        if (rel === "reference/sdk" || ent.name === "plan" || ent.name === "archive") continue;
+        stack.push(full);
+        continue;
+      }
+      if (!ent.name.endsWith(".md")) continue;
+      const text = readFileSync(full, "utf8");
+      // Markdown 链接目标：](./docs/...) 或 ](docs/...)
+      if (/\]\(\.?\/?docs\//.test(text)) {
+        bad.push(path.relative(root, full));
+      }
+    }
+  }
+  if (bad.length) {
+    console.error(
+      [
+        "[docs-mkdocs] 发现仓根相对路径 docs/…（MkDocs 下应写成 ./guide/、./dev/ 等）：",
+        ...bad.map((f) => `  - ${f}`),
+      ].join("\n")
+    );
+    process.exit(1);
+  }
+}
+
+assertNoRepoRootDocsLinks(path.join(root, "docs"));
+
 // 先生成 API 文档
 const gen = spawnSync(process.execPath, [path.join(root, "tools", "docs-typedoc.mjs")], {
   cwd: root,