From 6d77f67a4ef5c4ce30bb849dc7d1e4f0819bf1c0 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 26 Jul 2026 02:57:16 +0000 Subject: [PATCH 1/3] =?UTF-8?q?fix(docs):=20=E4=BF=AE=E6=AD=A3=20MkDocs=20?= =?UTF-8?q?=E9=A6=96=E9=A1=B5=E4=BB=93=E6=A0=B9=E8=B7=AF=E5=BE=84=E8=AF=AF?= =?UTF-8?q?=E8=B4=B4=E5=B9=B6=E5=8A=A0=E5=A5=91=E7=BA=A6=E6=A3=80=E6=9F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/index.md 从 README 复制了 ./docs/... 链接，在 docs_dir=docs 下站内导航全断； 改为 docs 相对路径，恢复按角色入口，并对 docs/*.md 禁止再出现 ](./docs/) 误贴。 Co-authored-by: Shiroha --- docs/index.md | 87 ++++++++++++++++++++++++++++--------------- mkdocs.yml | 3 +- tools/docs-mkdocs.mjs | 42 ++++++++++++++++++++- 3 files changed, 100 insertions(+), 32 deletions(-) diff --git a/docs/index.md b/docs/index.md index fd4cad9..8168bb9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,24 +1,26 @@ -# **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**及其路由服务 +在线地址： + +* 提供基于 [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桥接服务，轻松实现群服互通 +* 依赖于 [LLBot](https://www.llonebot.com/zh-CN/) 的 QQ 桥接服务，轻松实现群服互通 -[模块仓库 →](https://github.com/Tanya7z/sfmc-modules) +[模块仓库 →](https://github.com/Tanya7z/sfmc-modules) [![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 +30,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 +51,54 @@ flowchart LR SFMC["sfmc CLI"] -. 管理 .-> BDS & DB & QQ ``` -## 快速入门 +## 按角色入口 + +| 你是谁 | 从这里开始 | +|--------|------------| +| 服主 / 运维 | [使用指南](./guide/index.md) | +| 写业务模块 | [开发指南 · 模块开发](./dev/module-author.md) | +| 改平台 | [开发指南 · 平台开发](./dev/platform.md) | +| 查 HTTP / 模块服务 | [接口指南](./api/index.md) | +| 查 SDK 类型 | [SDK 类型参考](./reference/index.md)（CI / `npm run docs:api` 生成） | + +## 文档目录 | 分类 | 入口 | -| ------ | ------ | -| 使用指南 | [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`） | +|------|------| +| 使用指南 | [guide/](./guide/index.md) | +| 开发指南 | [dev/](./dev/index.md) | +| 接口指南 | [api/](./api/index.md) | +| SDK 类型参考 | [reference/](./reference/index.md)（`npm run docs:api`） | + +## 本地预览 + +在仓库根目录： + +```bash +pip install -r docs/requirements.txt +npm install +npm run docs:serve +``` + +浏览器打开 http://127.0.0.1:8000 。 + +- `npm run docs:api` — 仅 TypeDoc → `docs/reference/sdk/` +- `npm run docs:build` — TypeDoc + MkDocs → `site/` ## 路线图 -* ✅ **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, From 0c0e0fb903f038afe164562e6757b613aba18bc8 Mon Sep 17 00:00:00 2001 From: Shiroha <65802880+Tanya7z@users.noreply.github.com> Date: Sun, 26 Jul 2026 11:05:16 +0800 Subject: [PATCH 2/3] Revise documentation layout and remove role-based entries Updated the documentation structure by adding a new directory table and removing the role-based entry section. --- docs/index.md | 42 ++++++++---------------------------------- 1 file changed, 8 insertions(+), 34 deletions(-) diff --git a/docs/index.md b/docs/index.md index 8168bb9..88738bb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,6 +5,14 @@ > 在**原生 BDS**即可获得类似插件服的**高效、安全、扩展丰富**的体验 在线地址： +## 文档目录 + +| 分类 | 入口 | +|------|------| +| 使用指南 | [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) @@ -51,40 +59,6 @@ flowchart LR SFMC["sfmc CLI"] -. 管理 .-> BDS & DB & QQ ``` -## 按角色入口 - -| 你是谁 | 从这里开始 | -|--------|------------| -| 服主 / 运维 | [使用指南](./guide/index.md) | -| 写业务模块 | [开发指南 · 模块开发](./dev/module-author.md) | -| 改平台 | [开发指南 · 平台开发](./dev/platform.md) | -| 查 HTTP / 模块服务 | [接口指南](./api/index.md) | -| 查 SDK 类型 | [SDK 类型参考](./reference/index.md)（CI / `npm run docs:api` 生成） | - -## 文档目录 - -| 分类 | 入口 | -|------|------| -| 使用指南 | [guide/](./guide/index.md) | -| 开发指南 | [dev/](./dev/index.md) | -| 接口指南 | [api/](./api/index.md) | -| SDK 类型参考 | [reference/](./reference/index.md)（`npm run docs:api`） | - -## 本地预览 - -在仓库根目录： - -```bash -pip install -r docs/requirements.txt -npm install -npm run docs:serve -``` - -浏览器打开 http://127.0.0.1:8000 。 - -- `npm run docs:api` — 仅 TypeDoc → `docs/reference/sdk/` -- `npm run docs:build` — TypeDoc + MkDocs → `site/` - ## 路线图 * ✅ **Stage I**: per-module `sapi/manifest.json` + db-server reader From 036e4549b7c5f7bc8390ee2aa872a0d5947d058e Mon Sep 17 00:00:00 2001 From: Shiroha <65802880+Tanya7z@users.noreply.github.com> Date: Sun, 26 Jul 2026 11:06:56 +0800 Subject: [PATCH 3/3] Revise online links in documentation Updated links for online resources and module repository. --- docs/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 88738bb..292fd64 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,8 @@ > > 在**原生 BDS**即可获得类似插件服的**高效、安全、扩展丰富**的体验 -在线地址： +[在线地址 →](https://dogelakedev.github.io/ScriptsForMinecraftServer) +[模块仓库 →](https://github.com/Tanya7z/sfmc-modules) ## 文档目录 | 分类 | 入口 | @@ -21,8 +22,6 @@ * 自建工作流，使模组/模块开发更轻松 * 依赖于 [LLBot](https://www.llonebot.com/zh-CN/) 的 QQ 桥接服务，轻松实现群服互通 -[模块仓库 →](https://github.com/Tanya7z/sfmc-modules) - [![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)](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)