chore: prepare pnpm stable release workflow

.changeset/pnpm-stable-release-prep.md

@@ -0,0 +1,7 @@
+---
+"@sfmc-bds/cli": patch
+"@sfmc-bds/create-module": patch
+"@sfmc-bds/devkit": patch
+---
+
+统一模块模板和公开文档的 pnpm 工作流，并将 registry 模块下载改为 pnpm，补齐公开包仓库元数据。

.github/workflows/module-publish.yml

@@ -0,0 +1,148 @@
+name: module-publish
+
+# 从主仓发布独立模块。NPM_TOKEN 只配置在主仓；源代码必须是模块仓 main 上的指定提交。
+on:
+  workflow_dispatch:
+    inputs:
+      module:
+        description: 模块仓后缀
+        required: true
+        type: choice
+        options:
+          - activity-log
+          - afk
+          - area
+          - chat
+          - chat-sounds
+          - clean
+          - coop
+          - data-backup
+          - economy
+          - fly-area
+          - gamemode-area
+          - inventory-switcher
+          - land
+          - monitor
+          - online-time
+          - peace-area
+          - qa
+          - qq-link
+          - spawn-protect
+      commit:
+        description: 模块仓 main 上的完整提交 SHA
+        required: true
+        type: string
+      version:
+        description: 与 package.json 一致的正式版本
+        required: true
+        type: string
+      dry_run:
+        description: 仅检查并上传打包产物
+        required: true
+        default: true
+        type: boolean
+
+permissions:
+  contents: read
+
+concurrency:
+  group: module-publish-${{ inputs.module }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          repository: Tanya7z/sfmc-module-${{ inputs.module }}
+          ref: ${{ inputs.commit }}
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.8.0
+          run_install: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22.14"
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+
+      - name: 校验来源与版本
+        env:
+          MODULE: ${{ inputs.module }}
+          COMMIT: ${{ inputs.commit }}
+          VERSION: ${{ inputs.version }}
+        run: |
+          git fetch origin main
+          node -e 'const fs=require("node:fs");const p=JSON.parse(fs.readFileSync("package.json","utf8"));const m=process.env.MODULE;const v=process.env.VERSION;const c=process.env.COMMIT;if(!/^[0-9a-f]{40}$/.test(c)||!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(v)||p.name!==`@sfmc-bds/module-${m}`||p.version!==v||p.private===true){throw new Error("模块名称、提交或正式版本与输入不符")}';
+          test "$(git rev-parse HEAD)" = "${COMMIT}"
+          git merge-base --is-ancestor HEAD origin/main
+
+      - name: 校验主仓发布凭据
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          GH_TOKEN: ${{ secrets.SFMC_GITHUB_TOKEN }}
+          MODULE: ${{ inputs.module }}
+        run: |
+          if [ -z "${NODE_AUTH_TOKEN}" ] || [ -z "${GH_TOKEN}" ]; then
+            echo "::error::主仓发布凭据未配置"
+            exit 1
+          fi
+          pnpm whoami >/dev/null
+          can_push="$(gh api "repos/Tanya7z/sfmc-module-${MODULE}" --jq '.permissions.push')"
+          if [ "${can_push}" != "true" ]; then
+            echo "::error::SFMC_GITHUB_TOKEN 无法写入模块仓"
+            exit 1
+          fi
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run typecheck
+      - run: pnpm run lint
+      - run: pnpm run test
+      - name: 打包候选产物
+        run: mkdir -p artifacts && pnpm pack --pack-destination artifacts
+      - uses: actions/upload-artifact@v4
+        with:
+          name: module-${{ inputs.module }}-${{ inputs.version }}
+          path: artifacts/*.tgz
+          retention-days: 14
+
+      - name: 发布到 npm
+        if: inputs.dry_run == false
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [ -z "${NODE_AUTH_TOKEN}" ]; then
+            echo "::error::主仓 NPM_TOKEN 未配置"
+            exit 1
+          fi
+          pnpm publish --access public --tag latest --no-git-checks
+
+      - name: 创建模块版本标签与 GitHub Release
+        if: inputs.dry_run == false
+        env:
+          GH_TOKEN: ${{ secrets.SFMC_GITHUB_TOKEN }}
+          MODULE: ${{ inputs.module }}
+          VERSION: ${{ inputs.version }}
+          COMMIT: ${{ inputs.commit }}
+        run: |
+          repo="Tanya7z/sfmc-module-${MODULE}"
+          tag="v${VERSION}"
+          if [ -z "${GH_TOKEN}" ]; then
+            echo "::error::主仓 SFMC_GITHUB_TOKEN 未配置"
+            exit 1
+          fi
+          existing="$(gh api "repos/${repo}/git/ref/tags/${tag}" --jq .object.sha 2>/dev/null || true)"
+          if [ -n "${existing}" ] && [ "${existing}" != "${COMMIT}" ]; then
+            echo "::error::${tag} 已指向其他提交"
+            exit 1
+          fi
+          if [ -z "${existing}" ]; then
+            gh api -X POST "repos/${repo}/git/refs" -f ref="refs/tags/${tag}" -f sha="${COMMIT}"
+          fi
+          gh release view "${tag}" --repo "${repo}" >/dev/null 2>&1 || \
+            gh release create "${tag}" --repo "${repo}" --target "${COMMIT}" --title "${tag}" --generate-notes

CONTRIBUTING.md

@@ -10,7 +10,6 @@
 
 ```bash
 pnpm install && pnpm run build && pnpm run verify
-npm install && npm run build --workspaces --if-present && npm run verify
 ```
 
 文档站维护见 [docs/CONTRIBUTING-DOCS.md](./docs/CONTRIBUTING-DOCS.md)。

README.en.md

@@ -84,7 +84,7 @@ Ensure **Node.js ≥ 22.13.0** is installed (required for native `node:sqlite` s
 
 ```bash
 # 1. Install SFMC CLI globally
-npm install -g @sfmc-bds/sfmc
+pnpm add -g @sfmc-bds/sfmc@beta
 
 # 2. Create and enter your server workspace
 mkdir my-bedrock-server && cd my-bedrock-server
@@ -105,7 +105,7 @@ You don't need to clone this monorepo! Scaffold your standalone module repositor
 
 ```bash
 # 1. Interactively scaffold your author repository
-npm create @sfmc-bds/module@latest
+pnpm dlx @sfmc-bds/create-module@latest
 
 # 2. Open the created project in VS Code or Cursor
 # 3. Install the official "SFMC Module" extension
@@ -127,7 +127,7 @@ This repository houses the SFMC core platform and tooling packages, organized wi
 | `packages/db-server` | `@sfmc-bds/db-server` | High-performance SQLite HTTP data hub, transaction engine, and token sandbox |
 | `packages/qq-bridge` | `@sfmc-bds/qq-bridge` | Tencent QQ Official Bot and OneBot 11 two-way communication gateway |
 | `packages/bds-tools` | `@sfmc-bds/bds-tools` | BDS version updater and add-on inbox deployment pipeline |
-| `packages/create-module` | `@sfmc-bds/create-module` | Official module scaffolding engine (`npm create @sfmc-bds/module`) |
+| `packages/create-module` | `@sfmc-bds/create-module` | Official module scaffolding engine (`pnpm dlx @sfmc-bds/create-module`) |
 | `packages/devkit` | `@sfmc-bds/devkit` | Incremental transpiler (esbuild), file watcher, and reload core |
 | `packages/sfmc-extension`| `@sfmc-bds/sfmc-extension` | Official VS Code / Cursor IDE extension ("SFMC Module") |
 | `packages/meta` | `@sfmc-bds/sfmc` | Meta-package aggregator distribution |

README.md

@@ -34,17 +34,14 @@ SFMC 希望通过模块化架构补充基岩版的原生开发体验。
 
 ## 快速开始
 
-### 使用 npm 安装
+### 使用 pnpm 安装
 
 ```bash
 # 检查 Node.js 版本（需要 v22.13+）
 node -v
 
-# 安装 SFMC CLI
-npm install -g @sfmc-bds/sfmc
-
-# Beta 版本
-npm install -g @sfmc-bds/sfmc@beta
+# 安装当前公测版 SFMC CLI
+pnpm add -g @sfmc-bds/sfmc@beta
 
 # 创建服务器目录
 mkdir my-server && cd my-server

docs/en/guide/backup-upgrade.mdx

@@ -31,7 +31,7 @@ Do not copy `.db` files while db-server is running.
   <Tab label="Global npm">
 
 ```bash
-npm i -g @sfmc-bds/sfmc@beta
+pnpm add -g @sfmc-bds/sfmc@beta
 ```
 
   </Tab>
@@ -40,7 +40,6 @@ npm i -g @sfmc-bds/sfmc@beta
 ```bash
 git pull
 pnpm install && pnpm run build
-npm install && npm run build --workspaces --if-present
 ```
 
   </Tab>

docs/en/guide/index.mdx

@@ -35,7 +35,7 @@ flowchart LR
   <Tab label="npm (recommended)">
 
 ```bash
-npm i -g @sfmc-bds/sfmc@beta
+pnpm add -g @sfmc-bds/sfmc@beta
 mkdir my-server && cd my-server
 sfmc
 ```
@@ -47,7 +47,6 @@ sfmc
 git clone https://github.com/DogeLakeDev/ScriptsForMinecraftServer.git
 cd ScriptsForMinecraftServer
 pnpm install && pnpm run build
-npm install && npm run build --workspaces --if-present
 sfmc
 ```
 
@@ -117,12 +116,10 @@ sfmc> mod reload
   </Tab>
   <Tab label="Develop your own module">
 
-Create with `npm create @sfmc-bds/module@latest`:
+Create with `pnpm dlx @sfmc-bds/create-module@latest`:
 
 ```bash
-npm create @sfmc-bds/module@latest
 cd my-feature && pnpm install && pnpm run typecheck
-cd my-feature && npm install && npm run typecheck
 ```
 
 Link into your SFMC workspace (module short id required). Authors use extension Link / Watch; on the server:

docs/superpowers/specs/modules/AGENT_BRIEF.md

@@ -5,8 +5,7 @@
 ## 1. 脚手架
 
 ```bash
-npm create @sfmc-bds/module@latest -- --official
-# 或: npx @sfmc-bds/create-module@latest --official
+pnpm dlx @sfmc-bds/create-module@latest --official
 ```
 
 - install id = 规格中的短名（kebab-case）

docs/zh/CONTRIBUTING-DOCS.mdx

@@ -29,11 +29,8 @@ i18n.json
 
 ```bash
 pnpm install
-npm install
-pnpm run docs -- serve
-npm run docs -- serve
-pnpm run docs -- build
-npm run docs -- build
+pnpm run docs serve
+pnpm run docs build
 ```
 
 ## 配置入口
@@ -52,4 +49,3 @@ npm run docs -- build
 ## 扩展 TypeDoc 入口
 
 在 `website/rspress.config.ts` 的 `pluginTypeDoc({ entryPoints })` 与根目录 `typedoc.json` 同步追加 SDK 公开入口。
-

docs/zh/api/sdk/index.md

@@ -1,6 +1,6 @@
 # SDK 导读
 
-包名 `@sfmc-bds/sdk`。本文是**用法导读**；完整签名见 [SDK 类型参考](../reference/index.md)（`pnpm run docs -- api` / `npm run docs -- api`）。
+包名 `@sfmc-bds/sdk`。本文是**用法导读**；完整签名见 [SDK 类型参考](../reference/index.md)（`pnpm run docs api`）。
 
 ## 四抽屉
 

docs/zh/dev/architecture.md

@@ -168,7 +168,7 @@ ScriptsForMinecraftServer/
 │   ├── devkit/                    # 模块文件监听（Watch）与脚手架转译引擎
 │   ├── cli/                       # @sfmc-bds/cli 终端交互与进程 Supervisor
 │   ├── meta/                      # @sfmc-bds/sfmc 全局命令行入口包装
-│   ├── create-module/             # npm create @sfmc-bds/module 脚手架生成器
+│   ├── create-module/             # pnpm dlx @sfmc-bds/create-module 脚手架生成器
 │   ├── sfmc-extension/            # VS Code / Cursor 官方开发专属扩展
 │   └── tools/                     # 仓内专用测试、验证与文档生成工具集
 └── docs/                          # 基于 Rspress 2 的多语言文档站源码

docs/zh/dev/contributing.md

@@ -7,57 +7,55 @@
 ## 环境
 
 - **Node.js ≥ 22.13**
-- **pnpm workspace**（`pnpm-workspace.yaml`，主仓推荐）或 **npm workspaces**；本地 `@sfmc-bds/*` 用 `^<version>`，禁止 `workspace:*`
+- **pnpm workspace**（`pnpm-workspace.yaml`）；本地 `@sfmc-bds/*` 用 `^<version>`，禁止 `workspace:*`
 - 可选：Python 3.12 + `pip install -r docs/requirements.txt`
 
 ```bash
 pnpm install && pnpm run build && pnpm run verify
-npm install && npm run build --workspaces --if-present && npm run verify
 ```
 
 ## 根脚本
 
-下文 **pnpm / npm 等价**（单包 filter 写法见第二列）。
+以下命令统一使用 pnpm。
 
 ### 日常
 
-| pnpm | npm | 说明 |
-| ------ | ------ | ------ |
-| `pnpm run build` | `npm run build --workspaces --if-present` | 各 workspace build |
-| `pnpm run typecheck` | `npm run typecheck` | 各 workspace typecheck |
-| `pnpm run lint` | `npm run lint` | build eslint-plugin 后 `eslint .` |
-| `pnpm start` | `npm start` | CLI |
+| 命令 | 说明 |
+| ------ | ------ |
+| `pnpm run build` | 各 workspace build |
+| `pnpm run typecheck` | 各 workspace typecheck |
+| `pnpm run lint` | build eslint-plugin 后 `eslint .` |
+| `pnpm start` | CLI |
 
-单包：`pnpm --filter @sfmc-bds/sdk run build` / `npm run build -w @sfmc-bds/sdk`。
+单包：`pnpm --filter @sfmc-bds/sdk run build`。
 
 ### 自检
 
-| pnpm | npm | 说明 |
-| ------ | ------ | ------ |
-| `pnpm run verify` | `npm run verify` | 平台集成自检 |
+| 命令 | 说明 |
+| ------ | ------ |
+| `pnpm run verify` | 平台集成自检 |
 
 ### 文档
 
 ```bash
-pnpm run docs -- api|serve|build
-npm run docs -- api|serve|build
+pnpm run docs api
+pnpm run docs serve
+pnpm run docs build
 ```
 
 ### 依赖对齐
 
 ```bash
 pnpm run syncpack:fix
-npm run syncpack:fix
 pnpm exec syncpack format --check
-npx syncpack format --check
 ```
 
 ### 平台发包
 
-| pnpm | npm | 说明 |
-| ------ | ------ | ------ |
-| `pnpm run changeset` | `npm run changeset` | 添加 changeset；push `main` 后 CI 开 Version PR |
-| `node packages/tools/pack-verify.mjs` | 同上 | 可选：`pnpm pack` / `npm pack` 冒烟 |
+| 命令 | 说明 |
+| ------ | ------ |
+| `pnpm run changeset` | 添加 changeset；push `main` 后 CI 开 Version PR |
+| `node packages/tools/pack-verify.mjs` | 检查发布包内容 |
 
 日常发版：**合并 Version PR 即可**，无需本地 `prerelease` / `release`。当前 **beta-only**。模块作者发包见 [发布你的模块](./publish.md)。