Merge branch 'main' of https://github.com/DogeLakeDev/ScriptsForMinecraftServer

Author: Tanya7z

.github/workflows/ootb.yml

@@ -31,24 +31,14 @@ jobs:
         shell: pwsh
         run: npm run build --workspaces --if-present
 
-      - name: Ensure configs via db-server defaults
+      - name: Seed configs via SDK ensure
         shell: pwsh
         env:
           SFMC_ROOT: ${{ github.workspace }}
         run: |
-          # 各服务 ensure 写入 configs/；此处预跑 db-server 一次生成骨架后退出
+          # 直接走 @sfmc-bds/sdk/node/config.ensureCoreConfigs，不启 db-server HTTP
           New-Item -ItemType Directory -Force -Path configs | Out-Null
-          $p = Start-Process -FilePath node -ArgumentList "db-server/dist/index.js" -WorkingDirectory $PWD -WindowStyle Hidden -PassThru -RedirectStandardOutput "db-server/_seed.out" -RedirectStandardError "db-server/_seed.err"
-          $ok = $false
-          for ($i = 0; $i -lt 40; $i++) {
-            Start-Sleep -Milliseconds 250
-            try {
-              $r = Invoke-WebRequest -Uri "http://127.0.0.1:3001/api/health" -UseBasicParsing -TimeoutSec 1
-              if ($r.StatusCode -eq 200) { $ok = $true; break }
-            } catch {}
-          }
-          if ($p -and !$p.HasExited) { Stop-Process -Id $p.Id -Force -ErrorAction SilentlyContinue }
-          if (-not $ok) { Write-Host "WARN: db-server seed health not ready; configs may be partial" }
+          node tools/seed-configs.mjs
           Get-ChildItem configs -Filter *.json | ForEach-Object { Write-Host "seeded $($_.Name)" }
 
       - name: Run check-ootb

bds-tools/src/paths.ts

@@ -8,11 +8,8 @@
 import {
   configPath,
   DEFAULT_BDS_UPDATER_CONFIG,
-  ensureJsonConfig,
-  isConfigMetaKey,
+  loadEnsuredConfig,
   resolveRuntimeRoot,
-  stripConfigMeta,
-  withConfigSchema,
   type BdsUpdaterConfig,
 } from "@sfmc-bds/sdk/node/config";
 import fs from "node:fs";
@@ -32,15 +29,12 @@ export const ROLLBACK_MARKER: string = path.join(SCRIPT_DIR, ".last_update_rollb
 /** 加载并解析 bds_updater.json。
  *  启动时 ensure 文件存在,避免 wizard 没跑时 bds_updater.json 缺失导致 loadConfig 抛错。 */
 export function loadConfig(): BdsUpdaterConfig {
-  const raw = ensureJsonConfig<Record<string, unknown>>(
+  return loadEnsuredConfig(
     ROOT_DIR,
     "bds_updater.json",
-    withConfigSchema({ ...DEFAULT_BDS_UPDATER_CONFIG } as Record<string, unknown>, "bds_updater")
-  );
-  for (const k of Object.keys(raw)) {
-    if (isConfigMetaKey(k)) delete raw[k];
-  }
-  return stripConfigMeta(raw) as BdsUpdaterConfig;
+    "bds_updater",
+    { ...DEFAULT_BDS_UPDATER_CONFIG } as Record<string, unknown>
+  ) as BdsUpdaterConfig;
 }
 
 /** 解析后的 BDS 路径 / 备份目录 */

db-server/src/env.ts

@@ -3,16 +3,12 @@
  */
 
 import {
-  configPath,
-  DEFAULT_DB_CONFIG,
-  DEFAULT_PERMISSIONS,
-  DEFAULT_QQ_CONFIG,
-  ensureJson,
-  ensureJsonConfig,
-  isConfigMetaKey,
+  ensureCoreConfigs,
+  loadEnsuredConfig,
   modulePath,
   resolveRuntimeRoot,
-  withConfigSchema,
+  DEFAULT_DB_CONFIG,
+  DEFAULT_QQ_CONFIG,
 } from "@sfmc-bds/sdk/node/config";
 import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -46,32 +42,31 @@ export interface EnvConfig {
 
 export function loadEnv(): EnvConfig {
   const PROJECT_ROOT = resolveRuntimeRoot(resolve(__dirname, "..", ".."));
-  /* 启动时确认 db/qq config 存在;不存在就写带默认值的骨架。
+  /* 启动时确认 db/qq/permissions 存在;不存在就写带默认值的骨架。
    * 不依赖 wizard:wizard 只填字段,骨架由服务自己 ensure。 */
-  const dbconfig = ensureJsonConfig<Record<string, unknown>>(
+  ensureCoreConfigs(PROJECT_ROOT, ["db_config", "qq_config", "permissions"]);
+  const dbconfig = loadEnsuredConfig(
     PROJECT_ROOT,
     "db_config.json",
-    withConfigSchema({ ...DEFAULT_DB_CONFIG } as Record<string, unknown>, "db_config")
+    "db_config",
+    { ...DEFAULT_DB_CONFIG } as Record<string, unknown>
   );
-  const qqconfig = ensureJsonConfig<Record<string, unknown>>(
+  const qqconfig = loadEnsuredConfig(
     PROJECT_ROOT,
     "qq_config.json",
-    withConfigSchema({ ...DEFAULT_QQ_CONFIG } as Record<string, unknown>, "qq_config")
+    "qq_config",
+    { ...DEFAULT_QQ_CONFIG } as Record<string, unknown>
   );
-  ensureJson(configPath(PROJECT_ROOT, "permissions.json"), DEFAULT_PERMISSIONS);
 
   // ── 优先级:JSON > 系统环境变量 > 默认值 ───────────────────────
   const envBaseline = { ...process.env };
 
-  // 元数据键:`$schema`、`_` 前缀(如 _comment)不写 env、不打日志
   for (const [k, v] of Object.entries(dbconfig)) {
-    if (isConfigMetaKey(k)) continue;
     const envKey = k.replace(/([A-Z])/g, "_$1").toUpperCase();
     process.env[envKey] = String(v);
     log.info(`db_config::${k} -> process.env.${envKey} = ${String(v)}`);
   }
   for (const [k, v] of Object.entries(qqconfig)) {
-    if (isConfigMetaKey(k)) continue;
     const envKey = k.replace(/([A-Z])/g, "_$1").toUpperCase();
     if (process.env[envKey] === undefined) {
       process.env[envKey] = String(v);

modules/sdk/@sfmc-sdk/src/logs/terminal-progress.ts

@@ -26,6 +26,11 @@ export interface TerminalProgressOptions {
 export interface ProgressHandle {
   start(total: number, startValue?: number, payload?: Record<string, string>): void;
   update(value: number, payload?: Record<string, string>): void;
+  /**
+   * 修正总量刻度（未知→已知 Content-Length / finish 补总量）。
+   * LSP：勿用重 start 冒充改 total；实现须保留当前 value，并允许随后 update 按新刻度出帧。
+   */
+  setTotal(total: number): void;
   stop(): void;
   /** 当前是否已 start 且未 stop */
   readonly active: boolean;
@@ -115,7 +120,7 @@ export interface DownloadProgressBinderOptions {
  * BDS 更新与 CF 包下载共用，避免两处复制 lastTime/lastLoaded 环路（DRY）。
  *
  * LSP：与 httpDownload 契约对齐——中途 total=0（无 Content-Length）仍可回调；
- * 总量一旦变为已知（含 finish 用 finalBytes 补总量），须重设 bar 刻度，避免一直卡在占位 1MB。
+ * 总量一旦变为已知（含 finish 用 finalBytes 补总量），经 setTotal 修正刻度，避免卡在占位 1MB。
  */
 export function bindByteProgressToBar(
   bar: ProgressHandle,
@@ -138,16 +143,17 @@ export function bindByteProgressToBar(
     const speedText = formatDownloadSpeed(speed);
 
     if (!started) {
-      bar.start(totalMb, 0, { speed: "0 KB/s" });
+      /* 首帧 startValue=已下载量，避免非 TTY 先打出虚假 0%（LSP） */
+      bar.start(totalMb, dlMb, { speed: speedText });
       started = true;
       knownTotal = hasTotal;
     } else if (hasTotal && !knownTotal) {
-      /* 未知→已知：重 start 以修正 total（ProgressHandle 无独立 setTotal） */
-      bar.start(totalMb, dlMb, { speed: speedText });
+      /* 未知→已知：setTotal 修正刻度，勿重 start（OCP/LSP） */
+      bar.setTotal(totalMb);
       knownTotal = true;
-    } else {
-      bar.update(dlMb, { speed: speedText });
     }
+    /* 始终 update：TTY 重绘 / 非 TTY 步进日志与 payload 对齐 */
+    bar.update(dlMb, { speed: speedText });
 
     if (speedSampleMs <= 0 || now - lastTime >= speedSampleMs) {
       lastTime = now;
@@ -250,11 +256,21 @@ export function createTerminalProgress(opts: TerminalProgressOptions = {}): Prog
       if (useBar) {
         if (!id) register();
         draw();
-      } else if (opts.logger) {
-        opts.logger(`进度 0% (0/${total})`);
-        lastLoggedPct = 0;
+      } else {
+        /* 尊重 startValue（LSP）；与 update 共用 emitNonTty（DRY） */
+        emitNonTty(true);
       }
     },
+    setTotal(t) {
+      if (!started || stopped) return;
+      total = t > 0 ? t : 1;
+      /* 刻度变更后允许按新百分比再出帧（含从错误占位%回落到真实%） */
+      lastLoggedPct = -1;
+      if (useBar) {
+        draw();
+      }
+      /* 非 TTY：留给随后 update 打一条正确刻度日志，避免 start+update 双打 */
+    },
     update(v, p) {
       if (!started || stopped) return;
       value = v;
@@ -263,16 +279,7 @@ export function createTerminalProgress(opts: TerminalProgressOptions = {}): Prog
         draw();
         return;
       }
-      if (!opts.logger) return;
-      const pct = total > 0 ? (value / total) * 100 : 0;
-      const stepped = Math.floor(pct / stepPercent) * stepPercent;
-      if (stepped !== lastLoggedPct && (stepped > lastLoggedPct || pct >= 100)) {
-        lastLoggedPct = stepped;
-        const speed = payload.speed ? ` ${payload.speed}` : "";
-        opts.logger(
-          `进度 ${Math.min(100, Math.round(pct))}% (${value.toFixed(1)}/${total.toFixed(1)})${speed}`
-        );
-      }
+      emitNonTty(false);
     },
     stop() {
       if (stopped) return;
@@ -286,6 +293,24 @@ export function createTerminalProgress(opts: TerminalProgressOptions = {}): Prog
     },
   };
 
+  /** 非 TTY 百分比日志唯一出口（start / update 共用 — DRY） */
+  function emitNonTty(force: boolean): void {
+    if (!opts.logger) return;
+    const pct = total > 0 ? (value / total) * 100 : 0;
+    const stepped = Math.floor(pct / stepPercent) * stepPercent;
+    if (
+      !force &&
+      !(stepped !== lastLoggedPct && (stepped > lastLoggedPct || pct >= 100))
+    ) {
+      return;
+    }
+    lastLoggedPct = stepped;
+    const speed = payload.speed ? ` ${payload.speed}` : "";
+    opts.logger(
+      `进度 ${Math.min(100, Math.round(pct))}% (${value.toFixed(1)}/${total.toFixed(1)})${speed}`
+    );
+  }
+
   return handle;
 }
 

modules/sdk/@sfmc-sdk/src/node/config/index.ts

@@ -53,10 +53,12 @@ export interface DBConfig {
   [key: string]: unknown;
 }
 
-export interface PermissionsConfig {
-  permissions?: Array<{ player_name?: string; level?: number; [key: string]: unknown }>;
+/** permissions.json 根为数组（与 permissions.schema.json 一致；勿写成 { permissions: [] }） */
+export type PermissionsConfig = Array<{
+  player_name: string;
+  level: number;
   [key: string]: unknown;
-}
+}>;
 
 export interface RuntimeConfig {
   runtime_root?: string;
@@ -137,20 +139,15 @@ export type ConfigSchemaId =
   | "module_catalog";
 
 /**
- * 生成文件内 `$schema` 相对路径（相对 configs/ 或 packs/）。
- * IDE 用；运行时加载器应忽略该键。
+ * 生成文件内 `$schema` 相对路径。
+ * configs/、packs/、modules/ 均在仓顶下一层，相对 node_modules 深度相同；
+ * `from` 仅作调用点语义标注，便于日后若布局分叉再按位置扩展（OCP）。
  */
 export function configSchemaRef(
   schemaId: ConfigSchemaId,
-  from: "configs" | "packs" | "modules" = "configs"
+  _from: "configs" | "packs" | "modules" = "configs"
 ): string {
-  const rel =
-    from === "configs"
-      ? "../node_modules/@sfmc-bds/sdk/schemas"
-      : from === "packs"
-        ? "../node_modules/@sfmc-bds/sdk/schemas"
-        : "../node_modules/@sfmc-bds/sdk/schemas";
-  return `${rel}/${schemaId}.schema.json`;
+  return `../node_modules/@sfmc-bds/sdk/schemas/${schemaId}.schema.json`;
 }
 
 /** 在对象根写入 `$schema`（不覆盖已有）；数组根勿调用。 */
@@ -215,7 +212,7 @@ export const DEFAULT_BDS_UPDATER_CONFIG: BdsUpdaterConfig = {
 };
 
 /** permissions.json 根为数组；默认空表 */
-export const DEFAULT_PERMISSIONS: Array<{ player_name: string; level: number }> = [];
+export const DEFAULT_PERMISSIONS: PermissionsConfig = [];
 
 /** remote.json 骨架（enroll 前） */
 export const DEFAULT_REMOTE_CONFIG: RemoteConfig = {
@@ -341,4 +338,78 @@ export function ensureJson<T>(filePath: string, seed: T = {} as T): T {
  */
 export function ensureJsonConfig<T>(root: string, name: ConfigName, seed: T = {} as T): T {
   return ensureJson<T>(configPath(root, name), seed);
+}
+
+/**
+ * ensure 带 `$schema` 的配置对象（DRY：禁止各服务手写 ensureJsonConfig+withConfigSchema）。
+ * 返回磁盘内容（可能含元数据键）；运行时业务请用 {@link loadEnsuredConfig}。
+ */
+export function ensureSchemaConfig<T extends Record<string, unknown>>(
+  root: string,
+  name: ConfigName,
+  schemaId: ConfigSchemaId,
+  defaults: T,
+  from: "configs" | "packs" | "modules" = "configs"
+): T & { $schema?: string } {
+  return ensureJsonConfig(
+    root,
+    name,
+    withConfigSchema({ ...defaults } as Record<string, unknown>, schemaId, from)
+  ) as T & { $schema?: string };
+}
+
+/**
+ * ensure 后剥离元数据，返回可交给业务逻辑的纯配置（LSP：与无 `$schema` 的契约一致）。
+ */
+export function loadEnsuredConfig<T extends Record<string, unknown>>(
+  root: string,
+  name: ConfigName,
+  schemaId: ConfigSchemaId,
+  defaults: T,
+  from: "configs" | "packs" | "modules" = "configs"
+): T {
+  return stripConfigMeta(
+    ensureSchemaConfig(root, name, schemaId, defaults, from) as Record<string, unknown>
+  ) as T;
+}
+
+/** 平台核心配置种子集合（扩展新文件时只改此处 + switch） */
+export type CoreConfigKind = "db_config" | "qq_config" | "bds_updater" | "permissions" | "remote";
+
+/**
+ * 按需 ensure 平台核心配置。新种类加到 CoreConfigKind + switch 即可（OCP）。
+ * permissions 根为数组，不能走 withConfigSchema。
+ */
+export function ensureCoreConfigs(root: string, kinds: readonly CoreConfigKind[]): void {
+  for (const kind of kinds) {
+    switch (kind) {
+      case "db_config":
+        ensureSchemaConfig(root, "db_config.json", "db_config", {
+          ...DEFAULT_DB_CONFIG,
+        } as Record<string, unknown>);
+        break;
+      case "qq_config":
+        ensureSchemaConfig(root, "qq_config.json", "qq_config", {
+          ...DEFAULT_QQ_CONFIG,
+        } as Record<string, unknown>);
+        break;
+      case "bds_updater":
+        ensureSchemaConfig(root, "bds_updater.json", "bds_updater", {
+          ...DEFAULT_BDS_UPDATER_CONFIG,
+        } as Record<string, unknown>);
+        break;
+      case "permissions":
+        ensureJson(configPath(root, "permissions.json"), DEFAULT_PERMISSIONS);
+        break;
+      case "remote":
+        ensureSchemaConfig(root, "remote.json", "remote", {
+          ...DEFAULT_REMOTE_CONFIG,
+        } as Record<string, unknown>);
+        break;
+      default: {
+        const _exhaustive: never = kind;
+        void _exhaustive;
+      }
+    }
+  }
 }