DogeLakeDev · Tanya7z · Jul 27, 2026 · Jul 26, 2026
diff --git a/docs/CONTRIBUTING-DOCS.md b/docs/CONTRIBUTING-DOCS.md
@@ -54,6 +54,12 @@ npm run docs:build    # TypeDoc + mkdocs build → site/
 2. 写入该目录 `.pages` 的 `nav` 列表
 3. 从章节 `index.md` 加链接
 
+### 链接约定（契约）
+
+- **站内页**：用相对 `docs/` 的路径（`./guide/`、`../dev/`），**不要**写成仓根的 `./docs/...`。
+- **仓外目标**（源码、workflow、LICENSE、`configs/` 等）：用 GitHub 绝对 URL（`https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/...`）。相对 `../../sfmc/...` 在 Pages 上会 404。
+- `npm run docs:build` / `docs:serve` 会解析手写 `.md` 相对链接；逃出 `docs/` 即失败。
+
 ## 扩展 TypeDoc 入口
 
 在根目录 `typedoc.json` 的 `entryPoints` 追加 SDK 公开入口（与 `package.json#exports` 对齐）。
diff --git a/docs/dev/npm-publish.md b/docs/dev/npm-publish.md
@@ -19,7 +19,7 @@
 | `@sfmc-bds/tools` | `tools/` | 开发/安装工具脚本 |
 | `@sfmc-bds/sfmc` | `sfmc-meta/` | **聚合包**：一条命令装齐平台 |
 
-可发包清单权威来源：[`tools/lib/npm-publish-packages.mjs`](../../tools/lib/npm-publish-packages.mjs)。
+可发包清单权威来源：[`tools/lib/npm-publish-packages.mjs`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/tools/lib/npm-publish-packages.mjs)。
 
 `@sfmc-bds/remote-controller` 为内部实验包，**不发布**（已在 `.changeset/config.json#ignore`）。
 
@@ -36,7 +36,7 @@
 ## 日常开发流程
 
 1. 改可发包代码后：`npm run changeset`，选包 + type，写中文摘要。
-2. PR 合入 `main` 后，[changeset-release.yml](../../.github/workflows/changeset-release.yml) 会开/更新 **Version Packages** PR。
+2. PR 合入 `main` 后，[changeset-release.yml](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/.github/workflows/changeset-release.yml) 会开/更新 **Version Packages** PR。
 3. 维护者审查并合并 Version PR → CI 跑 `ci-release-packages`（publish + tag + GitHub Release；pre mode → npm **`beta`**）。
 
 ### Version PR 权限（必读）
@@ -73,7 +73,7 @@ npm run prerelease-packages
 
 ## Beta-only（硬约束）
 
-- 仓库含 [`.changeset/pre.json`](../../.changeset/pre.json)：`mode: pre`, `tag: beta`。
+- 仓库含 [`.changeset/pre.json`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/.changeset/pre.json)：`mode: pre`, `tag: beta`。
 - 安装文档与脚手架一律写 `@beta`。
 - 已存在的 `latest` 上的 `0.1.0` **保留不动**；稳定通道未开放。
 - **退出 beta → latest 门槛（全部满足才 `changeset pre exit`）**：
@@ -92,7 +92,7 @@ npx changeset publish    # → latest
 
 ## 应急单包补发
 
-[npm-publish.yml](../../.github/workflows/npm-publish.yml) 仅 `workflow_dispatch`：
+[npm-publish.yml](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/.github/workflows/npm-publish.yml) 仅 `workflow_dispatch`：
 
 - 默认 `dist_tag=beta`
 - 若仍处于 pre mode，选择 `latest` 会被 workflow 拒绝

diff --git a/docs/guide/config.md b/docs/guide/config.md
@@ -2,7 +2,7 @@
 
 首次启动时，**各服务用代码内默认值 ensure 生成**缺失配置文件，并写入 `$schema` ，使用 IDE 时便可查看**详细的悬停说明**。
 
-> IDE：工作区 [`.vscode/settings.json`](../../.vscode/settings.json) 已按文件名绑定 schema；也可用文件内 `$schema` 指向 `@sfmc-bds/sdk/schemas/*.schema.json`。
+> IDE：工作区 [`.vscode/settings.json`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/.vscode/settings.json) 已按文件名绑定 schema；也可用文件内 `$schema` 指向 `@sfmc-bds/sdk/schemas/*.schema.json`。
 
 ## 平台配置
 

diff --git a/docs/guide/pack-update.md b/docs/guide/pack-update.md
@@ -6,12 +6,12 @@
 
 | 路径 | 职责 |
 |------|------|
-| [`sfmc/src/pack-update/`](../../sfmc/src/pack-update/) | 配置、绑定、CF Provider、探测/检查/应用 |
-| [`sfmc/src/world-packs.ts`](../../sfmc/src/world-packs.ts) | CLI 接线、安装后探测钩子 |
-| [`sfmc/src/services.ts`](../../sfmc/src/services.ts) | BDS `beforeStart` 检查/应用 |
-| [`bds-tools/src/world-packs.ts`](../../bds-tools/src/world-packs.ts) | 安装/enable/抬版权威实现 |
-| [`modules/sdk/@sfmc-sdk/src/logs/terminal-progress.ts`](../../modules/sdk/@sfmc-sdk/src/logs/terminal-progress.ts) | 进度条与日志共存 |
-| [`configs/pack-update.json`](../../configs/pack-update.json) | 运行时配置（首次由 sfmc ensure 写入内置 DEFAULTS） |
+| [`sfmc/src/pack-update/`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/tree/main/sfmc/src/pack-update) | 配置、绑定、CF Provider、探测/检查/应用 |
+| [`sfmc/src/world-packs.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/sfmc/src/world-packs.ts) | CLI 接线、安装后探测钩子 |
+| [`sfmc/src/services.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/sfmc/src/services.ts) | BDS `beforeStart` 检查/应用 |
+| [`bds-tools/src/world-packs.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/bds-tools/src/world-packs.ts) | 安装/enable/抬版权威实现 |
+| [`modules/sdk/@sfmc-sdk/src/logs/terminal-progress.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/modules/sdk/@sfmc-sdk/src/logs/terminal-progress.ts) | 进度条与日志共存 |
+| `configs/pack-update.json` | 运行时配置（gitignore；首次由 sfmc ensure 写入内置 DEFAULTS，见 [`config.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/sfmc/src/pack-update/config.ts)） |
 
 通用收件箱安装见 [资源包管理](./world-packs.md)。
 
@@ -71,7 +71,7 @@ flowchart TD
 
 不再从 `configs-default` 拷贝。`createServices()` / `ensurePackUpdateConfigFile()` 在文件缺失时写入代码内 `DEFAULTS`，并附带 `$schema`（见 `@sfmc-bds/sdk/schemas/pack_update.schema.json`）。
 
-权威实现：[`sfmc/src/pack-update/config.ts`](../../sfmc/src/pack-update/config.ts) 的 `ensurePackUpdateConfigFile`。
+权威实现：[`sfmc/src/pack-update/config.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/sfmc/src/pack-update/config.ts) 的 `ensurePackUpdateConfigFile`。
 
 ### 3.3 `pack-update.json` 关键字段
 
@@ -189,7 +189,7 @@ JSON 中 `$` **无需**加倍；仅当把 key 放进 **shell / docker-compose
 | `GET /v1/mods/search?...` | **部分 key 恒 403**（`Forbidden: API Key missing or invalid`） |
 | `GET https://api.curse.tools/v1/cf/mods/search?...` | 200（社区镜像，路径约定与官方类似） |
 
-实现策略（[`providers/curseforge.ts`](../../sfmc/src/pack-update/providers/curseforge.ts)）：
+实现策略（[`providers/curseforge.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/sfmc/src/pack-update/providers/curseforge.ts)）：
 
 1. 先打官方 `baseUrl` + `/v1/mods/search`。
 2. 若返回 403 → 静默改打 `searchBaseUrl`（默认 `https://api.curse.tools/v1/cf`）的 `/mods/search`。

diff --git a/tools/docs-mkdocs.mjs b/tools/docs-mkdocs.mjs
@@ -18,44 +18,60 @@ if (!["serve", "build"].includes(mode)) {
 }
 
 /**
- * MkDocs docs_dir=docs：页面内相对链接不应再带 ./docs/ 前缀。
- * 把 README（仓根路径）原样贴进 docs/*.md 会导致站内导航全断，且默认
- * unrecognized_links=ignore 时 CI 不会拦。在此做契约检查。
+ * MkDocs docs_dir=docs：手写页相对链接解析后必须落在 docs/ 内。
+ * 同时拦住两类误用（单一权威规则，避免再为每种前缀打洞）：
+ * 1) README 仓根路径误贴：](./docs/guide/…) → 站内变成双重 docs/
+ * 2) 指向仓内其它目录：](../../sfmc/…) → Pages 上 404；应改 GitHub 绝对 URL
+ * TypeDoc 生成目录跳过；mkdocs exclude（plan/archive/reviews）仍检查，防草稿误贴。
  */
-function assertNoRepoRootDocsLinks(docsDir) {
+function assertDocsRelativeLinksStayInDocs(docsDir) {
   const bad = [];
+  const linkRe = /\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
   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;
+        // 仅跳过 TypeDoc 输出（生成物，非手写契约）
+        if (rel === "reference/sdk") 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));
+      const fileRel = path.relative(root, full).replace(/\\/g, "/");
+      let m;
+      linkRe.lastIndex = 0;
+      while ((m = linkRe.exec(text))) {
+        const raw = m[1].replace(/^<|>$/g, "");
+        // 锚点 / 协议链接 / 协议相对 URL 不参与 docs_dir 解析
+        if (!raw || raw.startsWith("#") || /^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith("//")) {
+          continue;
+        }
+        const targetPath = raw.split("#")[0].split("?")[0];
+        if (!targetPath) continue;
+        const resolved = path.resolve(path.dirname(full), targetPath);
+        const relToDocs = path.relative(docsDir, resolved);
+        if (relToDocs.startsWith("..") || path.isAbsolute(relToDocs)) {
+          bad.push(`${fileRel}: ](${raw})`);
+        }
       }
     }
   }
   if (bad.length) {
     console.error(
       [
-        "[docs-mkdocs] 发现仓根相对路径 docs/…（MkDocs 下应写成 ./guide/、./dev/ 等）：",
-        ...bad.map((f) => `  - ${f}`),
+        "[docs-mkdocs] 相对链接逃出 docs/（站内应写 ./guide/ 等；仓外目标用 GitHub 绝对 URL）：",
+        ...bad.map((line) => `  - ${line}`),
       ].join("\n")
     );
     process.exit(1);
   }
 }
 
-assertNoRepoRootDocsLinks(path.join(root, "docs"));
+assertDocsRelativeLinksStayInDocs(path.join(root, "docs"));
 
 // 先生成 API 文档
 const gen = spawnSync(process.execPath, [path.join(root, "tools", "docs-typedoc.mjs")], {