@sfmc-bds/qq-bridge 0.2.0-beta.9 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 SFMC QQ ↔ MC 桥接，支持双后端：
 
-- **official**（默认）：QQ 开放平台 Gateway，转发群内 @机器人消息
+- **official**（默认）：QQ 开放平台 WebSocket Gateway 或 Webhook；开启「接收所有消息」后，群内指令无需 @，普通聊天仍需 @ 才转发游戏
 - **llbot**：LLBot OneBot 11 reverse-WS（端口 3002）
 
 消息统一 POST 到 db-server `/api/sfmc/messages`。MC→QQ 出站由 db-server 按同一 `qq_backend` 处理。
@@ -14,12 +14,44 @@ QQ 侧指令（`菜单` / `ping` / `whoami`）在桥内拦截，不依赖 MC；o
 ## 安装
 
 ```bash
-npm install @sfmc-bds/qq-bridge
+pnpm add @sfmc-bds/qq-bridge
 node node_modules/@sfmc-bds/qq-bridge/dist/index.js
 ```
 
 通常由 `@sfmc-bds/sfmc` / `@sfmc-bds/cli` 统一拉起。
 
+## 官方机器人 Webhook 云端部署
+
+Webhook 模式只改变 QQ→桥的事件接收。MC→QQ 仍由游戏机上的 db-server 调用 QQ OpenAPI。云端仅运行 `qq-bridge`，不需要复制游戏世界或数据库。
+
+游戏机 `configs/qq_config.json` 中设置 `qq_backend: "official"`、`qq_enabled: true` 和 `official.transport: "webhook"`。官方凭据、目标群、管理员及回调参数集中放在 `official` 对象；LLBot 参数集中放在 `llbot` 对象。CLI 看到 Webhook 模式后跳过游戏机上的 QQ 桥进程，保留 db-server 与 BDS。
+
+```json
+{
+  "qq_enabled": true,
+  "qq_backend": "official",
+  "official": {
+    "transport": "webhook",
+    "app_id": "填入 AppID",
+    "app_secret": "填入 AppSecret",
+    "group_openid": "填入目标群 OpenID",
+    "admin_openids": [],
+    "webhook": { "port": 3005, "path": "/qqbot/webhook" }
+  },
+  "llbot": { "enabled": false }
+}
+```
+
+`deploy/qq-config-sync.ps1` 在游戏机登录后持续检查配置。仅当 `official.transport` 为 `webhook` 时，它经 SSH 标准输入同步官方凭据、目标群、管理员、频道和公开服务器信息；云端保留自己的 Webhook 监听、隧道端口与面板 ID。切回 `websocket` 或禁用 QQ 时，同步任务停止云端桥；切换接收方式后还需重启游戏机上的 SFMC CLI，并在 QQ 开放平台修改消息接收方式。同步失败时云端保留上一版配置。
+
+当前阿里云部署使用 SSH 别名 `aliyun`、云端同步程序 `/opt/sfmc-qq-bridge/deploy/sync-qq-config.mjs`，游戏机任务名为 `SFMC QQ Config Sync`。同步任务登录后启动，每 30 秒检查一次；游戏机重启后需先登录该用户。日志在运行目录的 `qq-config-sync.log`，只记录状态。回调端口与路径在此部署中固定为 `3005` 和 `/qqbot/webhook`；修改这两个值须同步调整 Nginx 和 QQ 开放平台回调地址。
+
+Webhook 进程仅监听云机 `127.0.0.1:3005`。用同机 HTTPS 反向代理把 `https://你的域名/qqbot/webhook` 转给它，然后在 QQ 开放平台「消息接收方式」选择 HTTP 回调，填写同一 URL。回调先完成平台 `op:13` 地址验证，正式事件再校验签名；反向代理须保留请求体原始字节与 `X-Bot-Appid`、`X-Signature-Timestamp`、`X-Signature-Ed25519` 请求头。
+
+云端桥需要访问游戏机 db-server 的多个本地 API。db-server 只监听游戏机 `127.0.0.1:3001`，不要开放其端口。游戏机 SFMC CLI 的 `tunnel` 服务主动建立 SSH 反向隧道，将云机 `127.0.0.1:13001` 转发到游戏机 `127.0.0.1:3001`；云端配置 `db_host: "127.0.0.1"`、`db_port: 13001`。在 `qq_config.json` 的 `official.tunnel` 配置 `{ "enabled": true, "host": "aliyun", "remotePort": 13001 }`，其中 `host` 是本机 SSH 配置中的别名。SFMC 启动 db-server 后启动隧道，异常退出时重试，并通过 `status`、`start tunnel`、`stop tunnel`、`restart tunnel` 和 `logs tunnel` 管理。远端只监听回环地址；不要同时运行旧的 `deploy/qq-tunnel.ps1`，否则两者会争抢云端端口。配置同步任务仍负责同步云端机器人配置，与隧道的生命周期分开。
+
+回调成功接收后会尽快确认，事件在单进程内按序处理并限制待处理数量。当前待处理队列位于内存中，进程在确认后立即崩溃时，尚未处理的事件可能丢失；如需跨进程故障恢复，应再增加持久化队列。
+
 ## 依赖
 
 - `@sfmc-bds/sdk`
@@ -30,3 +62,38 @@ node node_modules/@sfmc-bds/qq-bridge/dist/index.js
 
 <https://github.com/DogeLakeDev/ScriptsForMinecraftServer/tree/main/packages/qq-bridge>
 
+## 玩家服务交互（第一期）
+
+首页分为「服务器」「我的账号」「入服」「帮助」，管理权限核验成功才显示「管理」。两端保留原有文字命令和斜杠别名，子菜单均可返回首页。官方机器人开启「接收所有消息」后，群内可直接发送指令；未开启时仍需 @机器人。LLBot 菜单编号只对打开菜单的本人有效，60 秒过期，错误编号不会消费菜单。
+
+- `查服` / `状态` / `/status`：玩家可见的运行、在线与世界摘要；主机与进程信息位于管理员「自检」。
+- `版本` / `/version`：优先显示 SFMC CLI 捕获的本次 BDS 启动日志版本。须部署新版 CLI 并重启 BDS 才能产生记录；外部启动、停止运行或启动记录无法核验时，不冒充当前版本。
+- `ip` / `地址`：只显示 `qq_config.json` 的公开连接配置，不使用数据库地址或主机名。
+- `绑定`：获取验证码后，在游戏内执行 `/c:bind`，随后发送纯数字验证码。
+- 解绑等需确认的操作：先显示对象与影响，60 秒内本人确认；取消、新命令或超时后失效。确认时重新核验权限，重复确认不重复提交。
+- 管理员在「管理 → 事件推送」中可切换事件总开关、BDS 启停与异常退出、玩家进出和死亡通知，并设置 5–600 秒的聚合间隔；关闭总开关需本人确认。设置写入 `configs/qq_config.json` 并用于后续推送。
+- 在线名单自动连续分段。官方富文本发送失败时，降级文本保留可直接发送的完整命令。
+
+公开信息配置示例（域名仅为占位，请填写自己的公开地址）：
+
+```json
+{
+  "public_server": {
+    "address": "play.example.com",
+    "port": 19132,
+    "version": ""
+  }
+}
+```
+
+`version` 是无法获取实际版本时的备用入服说明，回复会明确标注来源；留空时提示联系管理员。修改后重启 QQ 桥接服务。权限仍由 db-server 最终校验，群管理员是否具有管理权限取决于现有 `treat_group_admins_as_admins` 设置；查询失败时隐藏受限入口。
+
+本期不改变入服规则。申请提交、审核通过和 BDS 写入白名单分别提示，不将审核通过视作已生效。下一阶段再完善自助入服进度和玩家数据服务。
+
+
+### 本次验证记录（2026-09-23）
+
+- QQ 桥接、db-server、CLI 与 SDK 类型检查通过；前三个包构建通过，SDK 配置入口与类型产物已更新。
+- 基于构建产物的 73 项本地模拟检查通过：菜单排版与权限、数字会话、确认取消/过期/重复/角色变化、错误拦截、版本与公开地址、120 人名单、UTF-8 分段、官方 Markdown 失败降级、LLBot HTTP 连续发送、旧按钮回调与 BDS 版本记录核验。
+- HTTP/QQ 发送均使用本地模拟服务或替代实现；没有向真实群发送测试消息。临时验证脚本已清理。
+- 尚未部署到运行目录，未重启实际 BDS，真实官方 QQ 与 LLBot 客户端联调待完成。公开地址需要填写 `public_server`；实际版本需要新版 CLI 捕获一次 BDS 启动日志。

package/deploy/install-nginx-webhook.sh

@@ -0,0 +1,34 @@
+#!/bin/sh
+set -eu
+
+site_file="${1:?请提供 Nginx 站点配置路径}"
+server_name="${2:?请提供 HTTPS 站点域名}"
+snippet=/etc/nginx/snippets/sfmc-qq-webhook.conf
+backup="${site_file}.bak-$(date +%Y%m%d%H%M%S)"
+
+test -f "$site_file"
+install -m 0644 "$(dirname "$0")/nginx-webhook-location.conf" "$snippet"
+cp -p "$site_file" "$backup"
+
+python3 - "$site_file" "$server_name" <<'PY'
+from pathlib import Path
+import sys
+
+path = Path(sys.argv[1])
+server_name = sys.argv[2]
+text = path.read_text()
+include_line = "    include /etc/nginx/snippets/sfmc-qq-webhook.conf;\n"
+if include_line not in text:
+    marker = f"server_name {server_name};\n"
+    if marker not in text:
+        raise SystemExit(f"未找到站点 {server_name}")
+    text = text.replace(marker, marker + include_line, 1)
+    path.write_text(text)
+PY
+
+if ! nginx -t; then
+    cp -p "$backup" "$site_file"
+    exit 1
+fi
+systemctl reload nginx
+printf 'Nginx 回调路径已安装；站点备份：%s\n' "$backup"

package/deploy/nginx-webhook-location.conf

@@ -0,0 +1,10 @@
+location = /qqbot/webhook {
+    client_max_body_size 64k;
+    proxy_pass http://127.0.0.1:3005;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Bot-Appid $http_x_bot_appid;
+    proxy_set_header X-Signature-Timestamp $http_x_signature_timestamp;
+    proxy_set_header X-Signature-Ed25519 $http_x_signature_ed25519;
+    proxy_read_timeout 10s;
+}

package/deploy/qq-bridge.service

@@ -0,0 +1,23 @@
+[Unit]
+Description=SFMC official QQ bridge (Webhook)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=qqbridge
+Group=qqbridge
+UMask=0027
+WorkingDirectory=/opt/sfmc-qq-bridge
+Environment=SFMC_ROOT=/var/lib/sfmc-qq-bridge
+ExecStart=/usr/bin/node /opt/sfmc-qq-bridge/node_modules/@sfmc-bds/qq-bridge/dist/index.js
+Restart=always
+RestartSec=3
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/sfmc-qq-bridge
+
+[Install]
+WantedBy=multi-user.target

package/deploy/qq-config-sync.ps1

@@ -0,0 +1,106 @@
+# 游戏机 qq_config.json 是唯一人工编辑入口；仅 official.transport=webhook 时同步云端桥配置。
+param(
+  [string]$Root = $PSScriptRoot,
+  [switch]$Once
+)
+
+$ErrorActionPreference = 'Stop'
+$OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+$configPath = Join-Path $Root 'configs\qq_config.json'
+$logPath = Join-Path $Root 'qq-config-sync.log'
+$mutex = New-Object System.Threading.Mutex($false, 'Global\SFMCQQConfigSync')
+if (-not $mutex.WaitOne(0)) { exit 0 }
+
+function Write-SyncLog([string]$message) {
+  if ((Test-Path -LiteralPath $logPath) -and (Get-Item -LiteralPath $logPath).Length -gt 1048576) {
+    Clear-Content -LiteralPath $logPath
+  }
+  "$(Get-Date -Format o) $message" | Add-Content -LiteralPath $logPath -Encoding UTF8
+}
+
+function Read-StableConfig {
+  $first = [IO.File]::ReadAllText($configPath, [Text.Encoding]::UTF8)
+  Start-Sleep -Seconds 1
+  $second = [IO.File]::ReadAllText($configPath, [Text.Encoding]::UTF8)
+  if ($first -ne $second) { throw '配置仍在写入' }
+  try { return $second | ConvertFrom-Json } catch { throw 'qq_config.json 不是有效 JSON' }
+}
+
+function New-SyncPayload($config) {
+  if ($null -eq $config.qq_backend -or $null -eq $config.official -or $null -eq $config.official.transport) {
+    throw '缺少显式的 qq_backend 或 official.transport'
+  }
+  $backend = [string]$config.qq_backend
+  $transport = [string]$config.official.transport
+  if ($backend -notin @('official', 'llbot') -or $transport -notin @('websocket', 'webhook')) {
+    throw 'qq_backend 或 official.transport 无效'
+  }
+  if ($backend -ne 'official' -or $config.qq_enabled -eq $false -or $transport -ne 'webhook') {
+    return [ordered]@{ mode = 'websocket' }
+  }
+  if ([string]::IsNullOrWhiteSpace($config.official.app_id) -or
+      [string]::IsNullOrWhiteSpace($config.official.app_secret)) {
+    throw 'official.app_id 或 official.app_secret 未配置'
+  }
+  if (($null -ne $config.official.webhook.port -and [int]$config.official.webhook.port -ne 3005) -or
+      ($null -ne $config.official.webhook.path -and $config.official.webhook.path -ne '/qqbot/webhook')) {
+    throw '当前阿里云反向代理固定使用 3005 和 /qqbot/webhook'
+  }
+  $publicServer = $config.public_server
+  $publicPort = if ($null -ne $publicServer -and $null -ne $publicServer.port) { [int]$publicServer.port } else { 19132 }
+  $shared = [ordered]@{
+    official = [ordered]@{
+      app_id = [string]$config.official.app_id
+      app_secret = [string]$config.official.app_secret
+      sandbox = ($config.official.sandbox -eq $true)
+      group_openid = [string]$config.official.group_openid
+      admin_openids = @($config.official.admin_openids | Where-Object { $null -ne $_ })
+      sync_menu_panel = ($config.official.sync_menu_panel -ne $false)
+    }
+    public_server = [ordered]@{
+      address = [string]$publicServer.address
+      port = $publicPort
+      version = [string]$publicServer.version
+    }
+  }
+  return [ordered]@{ mode = 'webhook'; shared = $shared }
+}
+
+try {
+  $lastSuccess = ''
+  $hadError = $false
+  while ($true) {
+    try {
+      $payload = New-SyncPayload (Read-StableConfig)
+      $json = ConvertTo-Json -InputObject $payload -Depth 8 -Compress
+      $bytes = [Text.Encoding]::UTF8.GetBytes($json)
+      $sha = [Security.Cryptography.SHA256]::Create()
+      try { $fingerprint = [Convert]::ToBase64String($sha.ComputeHash($bytes)) } finally { $sha.Dispose() }
+      if ($fingerprint -ne $lastSuccess) {
+        $previousErrorPreference = $ErrorActionPreference
+        $ErrorActionPreference = 'Continue'
+        try {
+          $json | & 'C:\Windows\System32\OpenSSH\ssh.exe' -T `
+            -o BatchMode=yes -o ConnectTimeout=10 aliyun `
+            'flock -w 30 /run/lock/sfmc-qq-config-sync.lock node /opt/sfmc-qq-bridge/deploy/sync-qq-config.mjs' 2>&1 | Out-Null
+          $result = $LASTEXITCODE
+        } finally {
+          $ErrorActionPreference = $previousErrorPreference
+        }
+        if ($result -ne 0) { throw "阿里云同步失败（SSH 退出码 $result）" }
+        $lastSuccess = $fingerprint
+        Write-SyncLog "云端同步成功（mode=$($payload.mode)）"
+      }
+    } catch {
+      # 异常可能包含解析位置，日志只记录固定原因，避免泄露配置内容。
+      $hadError = $true
+      Write-SyncLog '本轮未同步；请检查 QQ 配置、SSH 连接和阿里云服务状态'
+    }
+    if ($Once) { break }
+    Start-Sleep -Seconds 30
+  }
+} finally {
+  $mutex.ReleaseMutex()
+  $mutex.Dispose()
+}
+if ($Once -and $hadError) { exit 1 }

package/deploy/qq-tunnel.ps1

@@ -0,0 +1,15 @@
+# 游戏机主动连接阿里云，只在云机回环地址暴露 db-server 转发端口。
+$logPath = Join-Path $PSScriptRoot 'qq-tunnel.log'
+
+while ($true) {
+  if ((Test-Path -LiteralPath $logPath) -and (Get-Item -LiteralPath $logPath).Length -gt 1048576) {
+    Clear-Content -LiteralPath $logPath
+  }
+  "$(Get-Date -Format o) 尝试建立 QQ 反向隧道" | Add-Content -LiteralPath $logPath
+  & 'C:\Windows\System32\OpenSSH\ssh.exe' -N -T `
+    -o BatchMode=yes -o ConnectTimeout=10 -o ExitOnForwardFailure=yes `
+    -o ServerAliveInterval=30 -o ServerAliveCountMax=3 `
+    -R 127.0.0.1:13001:127.0.0.1:3001 aliyun 2>> $logPath
+  "$(Get-Date -Format o) SSH 退出，代码 $LASTEXITCODE" | Add-Content -LiteralPath $logPath
+  Start-Sleep -Seconds 5
+}

package/deploy/sync-qq-config.mjs

@@ -0,0 +1,229 @@
+/** 游戏机通过 SSH 标准输入提交共享 QQ 配置；只在本机原子更新云端桥配置。 */
+import { execFileSync } from "node:child_process";
+import { createPrivateKey, createPublicKey, randomBytes, verify } from "node:crypto";
+import { chownSync, chmodSync, readFileSync, renameSync, statSync, writeFileSync, rmSync } from "node:fs";
+import { request } from "node:http";
+import { dirname, join } from "node:path";
+
+const CONFIG_PATH = "/var/lib/sfmc-qq-bridge/configs/qq_config.json";
+const SERVICE = "sfmc-qq-bridge.service";
+const PKCS8_ED25519_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+
+function service(action) {
+  execFileSync("systemctl", [action, SERVICE], { stdio: "ignore", timeout: 15_000 });
+}
+
+function readConfig() {
+  return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+}
+
+function privateKey(secret) {
+  const source = Buffer.from(secret, "utf8");
+  const seed = Buffer.alloc(32);
+  for (let i = 0; i < seed.length; i++) seed[i] = source[i % source.length];
+  return createPrivateKey({ key: Buffer.concat([PKCS8_ED25519_PREFIX, seed]), format: "der", type: "pkcs8" });
+}
+
+function checkChallenge(config) {
+  return new Promise((resolve, reject) => {
+    const eventTs = String(Math.floor(Date.now() / 1000));
+    const plainToken = randomBytes(12).toString("hex");
+    const body = JSON.stringify({ op: 13, d: { event_ts: eventTs, plain_token: plainToken } });
+    const req = request(
+      {
+        hostname: "127.0.0.1",
+        port: 3005,
+        path: "/qqbot/webhook",
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(body),
+          "X-Bot-Appid": config.official.app_id,
+        },
+        timeout: 1500,
+      },
+      (res) => {
+        let answer = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => (answer += chunk));
+        res.on("end", () => {
+          try {
+            const value = JSON.parse(answer);
+            const signature = String(value.signature ?? "");
+            const valid =
+              res.statusCode === 200 &&
+              value.plain_token === plainToken &&
+              /^[0-9a-f]{128}$/i.test(signature) &&
+              verify(
+                null,
+                Buffer.from(eventTs + plainToken),
+                createPublicKey(privateKey(config.official.app_secret)),
+                Buffer.from(signature, "hex")
+              );
+            if (valid) resolve();
+            else reject(new Error("回调校验未通过"));
+          } catch {
+            reject(new Error("回调响应无效"));
+          }
+        });
+      }
+    );
+    req.on("timeout", () => req.destroy(new Error("回调超时")));
+    req.on("error", reject);
+    req.end(body);
+  });
+}
+
+async function waitUntilHealthy(config) {
+  let lastError;
+  for (let attempt = 0; attempt < 8; attempt++) {
+    try {
+      service("is-active");
+      await checkChallenge(config);
+      return;
+    } catch (error) {
+      lastError = error;
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+  }
+  throw lastError ?? new Error("服务未就绪");
+}
+
+function writeAtomic(value, previousStat) {
+  const temporary = join(dirname(CONFIG_PATH), `.qq_config.sync-${process.pid}.tmp`);
+  try {
+    writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    chownSync(temporary, previousStat.uid, previousStat.gid);
+    chmodSync(temporary, 0o640);
+    renameSync(temporary, CONFIG_PATH);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+function expectString(value, name, required = false) {
+  if (typeof value !== "string" || (required && !value.trim())) throw new Error(`${name} 无效`);
+  return value;
+}
+
+function sharedFields(payload) {
+  const source = payload.shared;
+  if (!source || typeof source !== "object" || Array.isArray(source)) throw new Error("共享配置无效");
+  const official = source.official;
+  if (!official || typeof official !== "object" || Array.isArray(official)) throw new Error("official 无效");
+  if (!Array.isArray(official.admin_openids) || !official.admin_openids.every((id) => typeof id === "string")) {
+    throw new Error("official.admin_openids 无效");
+  }
+  if (typeof official.sandbox !== "boolean" || typeof official.sync_menu_panel !== "boolean") {
+    throw new Error("QQ 开关配置无效");
+  }
+  const publicServer = source.public_server;
+  if (publicServer && (typeof publicServer !== "object" || Array.isArray(publicServer))) {
+    throw new Error("public_server 无效");
+  }
+  const publicAddress = expectString(publicServer?.address ?? "", "public_server.address");
+  const publicVersion = expectString(publicServer?.version ?? "", "public_server.version");
+  const publicPort = publicServer?.port ?? 19132;
+  if (!Number.isInteger(publicPort) || publicPort < 1 || publicPort > 65535) {
+    throw new Error("public_server.port 无效");
+  }
+  return {
+    official: {
+      app_id: expectString(official.app_id, "official.app_id", true),
+      app_secret: expectString(official.app_secret, "official.app_secret", true),
+      sandbox: official.sandbox,
+      group_openid: expectString(official.group_openid, "official.group_openid"),
+      admin_openids: official.admin_openids,
+      sync_menu_panel: official.sync_menu_panel,
+    },
+    public_server: { address: publicAddress, port: publicPort, version: publicVersion },
+  };
+}
+
+async function main() {
+  if (process.getuid?.() !== 0) throw new Error("同步程序必须由云端 root 执行");
+  if (process.argv[2] === "--health") {
+    await waitUntilHealthy(readConfig());
+    process.stdout.write("Webhook 回调校验通过\n");
+    return;
+  }
+  let input = "";
+  for await (const part of process.stdin) {
+    input += part;
+    if (input.length > 65_536) throw new Error("同步请求过大");
+  }
+  const payload = JSON.parse(input);
+  if (payload?.mode === "websocket") {
+    service("stop");
+    process.stdout.write("云端 Webhook 已停止\n");
+    return;
+  }
+  if (payload?.mode !== "webhook") throw new Error("接收方式无效");
+
+  const shared = sharedFields(payload);
+  const current = readConfig();
+  const next = {
+    ...current,
+    public_server: shared.public_server,
+    qq_enabled: true,
+    qq_backend: "official",
+    official: {
+      ...current.official,
+      ...shared.official,
+      transport: "webhook",
+      webhook: { port: 3005, path: "/qqbot/webhook" },
+      group_panel_id:
+        current.official?.group_openid === shared.official.group_openid ? current.official?.group_panel_id ?? "" : "",
+    },
+    db_host: "127.0.0.1",
+    db_port: 13001,
+  };
+  delete next.bridge_channel_id;
+  delete next.mctoqq_prefix;
+  if (JSON.stringify(next) === JSON.stringify(current)) {
+    try {
+      service("is-active");
+      await checkChallenge(current);
+    } catch {
+      service("start");
+      await waitUntilHealthy(current);
+    }
+    process.stdout.write("云端配置未变化，服务正常\n");
+    return;
+  }
+
+  // 停止写回面板 ID 的进程后重读，避免覆盖同步期间刚生成的 ID。
+  service("stop");
+  let stoppedConfig;
+  let previousStat;
+  try {
+    stoppedConfig = readConfig();
+    next.official.group_panel_id =
+      stoppedConfig.official?.group_openid === shared.official.group_openid
+        ? stoppedConfig.official?.group_panel_id ?? ""
+        : "";
+    previousStat = statSync(CONFIG_PATH);
+    const backupPath = `${CONFIG_PATH}.bak-sync`;
+    writeFileSync(backupPath, readFileSync(CONFIG_PATH), { mode: 0o600 });
+    chmodSync(backupPath, 0o600);
+    writeAtomic(next, previousStat);
+    service("restart");
+    await waitUntilHealthy(next);
+    process.stdout.write("云端 QQ 配置已更新，Webhook 校验通过\n");
+  } catch {
+    try {
+      if (stoppedConfig && previousStat) writeAtomic(stoppedConfig, previousStat);
+      service("restart");
+      if (stoppedConfig) await waitUntilHealthy(stoppedConfig);
+    } catch {
+      throw new Error("云端配置应用失败，回滚未完成，请检查服务");
+    }
+    throw new Error("云端配置应用失败，已恢复上一版");
+  }
+}
+
+main().catch((error) => {
+  // 错误消息只包含字段名和状态，不输出收到的配置或凭据。
+  process.stderr.write(`QQ 配置同步失败：${error.message}\n`);
+  process.exitCode = 1;
+});

package/dist/commands/account-format.js

@@ -0,0 +1,41 @@
+function cell(value) {
+  return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ").trim() || "\u2014";
+}
+function balanceText(profile) {
+  if (profile.balance == null) return "\u6682\u65F6\u8BFB\u4E0D\u5230";
+  const unit = profile.unit?.trim() || "\u8282\u64CD";
+  return `${profile.balance} ${unit}`;
+}
+function formatAccountCard(opts) {
+  if (!opts.bound) {
+    const text2 = ["\u6211\u7684\u8D26\u53F7", "", "\u7ED1\u5B9A\u72B6\u6001\uFF1A\u672A\u7ED1\u5B9A"].join("\n");
+    return { text: text2, markdown: ["## \u6211\u7684\u8D26\u53F7", "", "\u7ED1\u5B9A\u72B6\u6001\uFF1A\u672A\u7ED1\u5B9A"].join("\n") };
+  }
+  const name = opts.playerName?.trim() || "\u672A\u547D\u540D\u89D2\u8272";
+  const head = ["\u7ED1\u5B9A\u72B6\u6001\uFF1A\u5DF2\u7ED1\u5B9A", `\u6E38\u620F\u89D2\u8272\uFF1A${name}`];
+  if (!opts.profile) {
+    const text2 = ["\u6211\u7684\u8D26\u53F7", "", ...head].join("\n");
+    return { text: text2, markdown: ["## \u6211\u7684\u8D26\u53F7", "", ...head].join("\n") };
+  }
+  const rows = [
+    ["\u4F59\u989D", balanceText(opts.profile)],
+    ["\u4ECA\u65E5\u5728\u7EBF", opts.profile.today_text || "\u6682\u65F6\u8BFB\u4E0D\u5230"],
+    ["\u672C\u6708\u5728\u7EBF", opts.profile.month_text || "\u6682\u65F6\u8BFB\u4E0D\u5230"],
+    ["\u7D2F\u8BA1\u5728\u7EBF", opts.profile.total_text || "\u6682\u65F6\u8BFB\u4E0D\u5230"]
+  ];
+  const text = ["\u6211\u7684\u8D26\u53F7", "", ...head, "", ...rows.map(([label, value]) => `${label}\uFF1A${value}`)].join("\n");
+  const markdown = [
+    "## \u6211\u7684\u8D26\u53F7",
+    "",
+    ...head,
+    "",
+    "| \u9879\u76EE | \u6570\u503C |",
+    "| --- | --- |",
+    ...rows.map(([label, value]) => `| ${cell(label ?? "")} | ${cell(value ?? "")} |`)
+  ].join("\n");
+  return { text, markdown };
+}
+export {
+  formatAccountCard
+};
+//# sourceMappingURL=account-format.js.map

package/dist/commands/account-format.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/commands/account-format.ts"],
+  "sourcesContent": ["/**\n * account-format.ts \u2014 QQ\u300C\u6211\u7684\u8D26\u53F7\u300D\u6B63\u6587\u3002\n *\n * \u5DF2\u7ED1\u5B9A\u65F6\u7528 Markdown \u8868\u683C\u5217\u51FA\u4F59\u989D\u548C\u5728\u7EBF\u65F6\u957F\uFF1B\u7EAF\u6587\u672C\u4FDD\u7559\u540C\u6837\u7684\u5B57\u6BB5\uFF0C\u4F9B Markdown \u53D1\u9001\u5931\u8D25\u65F6\u964D\u7EA7\u3002\n */\n\nexport type AccountProfileView = {\n  unit?: string;\n  balance?: number | null;\n  today_text?: string;\n  month_text?: string;\n  total_text?: string;\n};\n\nfunction cell(value: string): string {\n  return value.replace(/\\|/g, \"\\\\|\").replace(/\\r?\\n/g, \" \").trim() || \"\u2014\";\n}\n\nfunction balanceText(profile: AccountProfileView): string {\n  if (profile.balance == null) return \"\u6682\u65F6\u8BFB\u4E0D\u5230\";\n  const unit = profile.unit?.trim() || \"\u8282\u64CD\";\n  return `${profile.balance} ${unit}`;\n}\n\n/** \u8D26\u53F7\u9875\u7684\u7EAF\u6587\u672C\u548C Markdown\u3002\u672A\u7ED1\u5B9A\u6216\u65E7\u63A5\u53E3\u6CA1\u6709 profile \u65F6\u4E0D\u7F16\u9020\u6570\u5B57\u3002 */\nexport function formatAccountCard(opts: {\n  bound: boolean;\n  playerName?: string;\n  profile?: AccountProfileView | null;\n}): { text: string; markdown: string } {\n  if (!opts.bound) {\n    const text = [\"\u6211\u7684\u8D26\u53F7\", \"\", \"\u7ED1\u5B9A\u72B6\u6001\uFF1A\u672A\u7ED1\u5B9A\"].join(\"\\n\");\n    return { text, markdown: [\"## \u6211\u7684\u8D26\u53F7\", \"\", \"\u7ED1\u5B9A\u72B6\u6001\uFF1A\u672A\u7ED1\u5B9A\"].join(\"\\n\") };\n  }\n  const name = opts.playerName?.trim() || \"\u672A\u547D\u540D\u89D2\u8272\";\n  const head = [\"\u7ED1\u5B9A\u72B6\u6001\uFF1A\u5DF2\u7ED1\u5B9A\", `\u6E38\u620F\u89D2\u8272\uFF1A${name}`];\n  if (!opts.profile) {\n    const text = [\"\u6211\u7684\u8D26\u53F7\", \"\", ...head].join(\"\\n\");\n    return { text, markdown: [\"## \u6211\u7684\u8D26\u53F7\", \"\", ...head].join(\"\\n\") };\n  }\n  const rows = [\n    [\"\u4F59\u989D\", balanceText(opts.profile)],\n    [\"\u4ECA\u65E5\u5728\u7EBF\", opts.profile.today_text || \"\u6682\u65F6\u8BFB\u4E0D\u5230\"],\n    [\"\u672C\u6708\u5728\u7EBF\", opts.profile.month_text || \"\u6682\u65F6\u8BFB\u4E0D\u5230\"],\n    [\"\u7D2F\u8BA1\u5728\u7EBF\", opts.profile.total_text || \"\u6682\u65F6\u8BFB\u4E0D\u5230\"],\n  ];\n  const text = [\"\u6211\u7684\u8D26\u53F7\", \"\", ...head, \"\", ...rows.map(([label, value]) => `${label}\uFF1A${value}`)].join(\"\\n\");\n  const markdown = [\n    \"## \u6211\u7684\u8D26\u53F7\",\n    \"\",\n    ...head,\n    \"\",\n    \"| \u9879\u76EE | \u6570\u503C |\",\n    \"| --- | --- |\",\n    ...rows.map(([label, value]) => `| ${cell(label ?? \"\")} | ${cell(value ?? \"\")} |`),\n  ].join(\"\\n\");\n  return { text, markdown };\n}\n"],
+  "mappings": "AAcA,SAAS,KAAK,OAAuB;AACnC,SAAO,MAAM,QAAQ,OAAO,KAAK,EAAE,QAAQ,UAAU,GAAG,EAAE,KAAK,KAAK;AACtE;AAEA,SAAS,YAAY,SAAqC;AACxD,MAAI,QAAQ,WAAW,KAAM,QAAO;AACpC,QAAM,OAAO,QAAQ,MAAM,KAAK,KAAK;AACrC,SAAO,GAAG,QAAQ,OAAO,IAAI,IAAI;AACnC;AAGO,SAAS,kBAAkB,MAIK;AACrC,MAAI,CAAC,KAAK,OAAO;AACf,UAAMA,QAAO,CAAC,4BAAQ,IAAI,kDAAU,EAAE,KAAK,IAAI;AAC/C,WAAO,EAAE,MAAAA,OAAM,UAAU,CAAC,+BAAW,IAAI,kDAAU,EAAE,KAAK,IAAI,EAAE;AAAA,EAClE;AACA,QAAM,OAAO,KAAK,YAAY,KAAK,KAAK;AACxC,QAAM,OAAO,CAAC,oDAAY,iCAAQ,IAAI,EAAE;AACxC,MAAI,CAAC,KAAK,SAAS;AACjB,UAAMA,QAAO,CAAC,4BAAQ,IAAI,GAAG,IAAI,EAAE,KAAK,IAAI;AAC5C,WAAO,EAAE,MAAAA,OAAM,UAAU,CAAC,+BAAW,IAAI,GAAG,IAAI,EAAE,KAAK,IAAI,EAAE;AAAA,EAC/D;AACA,QAAM,OAAO;AAAA,IACX,CAAC,gBAAM,YAAY,KAAK,OAAO,CAAC;AAAA,IAChC,CAAC,4BAAQ,KAAK,QAAQ,cAAc,gCAAO;AAAA,IAC3C,CAAC,4BAAQ,KAAK,QAAQ,cAAc,gCAAO;AAAA,IAC3C,CAAC,4BAAQ,KAAK,QAAQ,cAAc,gCAAO;AAAA,EAC7C;AACA,QAAM,OAAO,CAAC,4BAAQ,IAAI,GAAG,MAAM,IAAI,GAAG,KAAK,IAAI,CAAC,CAAC,OAAO,KAAK,MAAM,GAAG,KAAK,SAAI,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI;AACtG,QAAM,WAAW;AAAA,IACf;AAAA,IACA;AAAA,IACA,GAAG;AAAA,IACH;AAAA,IACA;AAAA,IACA;AAAA,IACA,GAAG,KAAK,IAAI,CAAC,CAAC,OAAO,KAAK,MAAM,KAAK,KAAK,SAAS,EAAE,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC,IAAI;AAAA,EACnF,EAAE,KAAK,IAAI;AACX,SAAO,EAAE,MAAM,SAAS;AAC1B;",
+  "names": ["text"]
+}