@lf_maple/koishi-plugin-phi-plugin-full 0.1.80

package/core/model/api/aliasProposalService.js

@@ -0,0 +1,151 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import YAML from 'yaml'
+import { redisPath } from '../game/constNum.js'
+import { dataPath } from '../filesystem/path.js'
+import { UserCredentials } from '../user/userCredentials.js'
+import getInfo from '../game/getInfo.js'
+import { redis } from '../../components/platform/index.js'
+import logger from '../../components/Logger.js'
+import Config from '../../components/Config.js'
+import makeRequest from './makeRequest.js'
+import { isApiVersionBlocked } from './apiVersion.js'
+
+/** @import {AliasBotEvent, AliasProposalCreateInput, AliasProposalRecord, AliasVoteValue} from '../type/aliasProposal.js' */
+
+const snapshotPath = path.join(dataPath, 'alias', 'approved-nicklist.yaml')
+const lastApprovedSyncKey = `${redisPath}:aliasApproved:lastSync`
+
+/**
+ * 严格校验公开 YAML 快照，拒绝非对象、非数组和空别名。
+ * @param {unknown} value YAML 解析结果
+ * @returns {Record<string, string[]>} 可安全合并的正式别名快照
+ */
+export function validateApprovedAliasSnapshot(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid alias snapshot')
+    /** @type {Record<string, string[]>} */
+    const result = {}
+    for (const [songId, aliases] of Object.entries(value)) {
+        if (!songId.trim() || !Array.isArray(aliases)) throw new Error('Invalid alias snapshot')
+        result[songId] = aliases.map(alias => {
+            if (typeof alias !== 'string' || !alias.trim()) throw new Error('Invalid alias snapshot')
+            return alias.trim()
+        })
+    }
+    return result
+}
+
+class AliasProposalService {
+    /** 初始化任务状态；不会在构造阶段写入用户数据。 */
+    constructor() {
+        this.runningTask = false
+        this.initialized = false
+    }
+
+    /**
+     * 取得事件用户本地保存的 sessionToken。
+     * @param {AliasBotEvent} e 当前 Bot 事件
+     * @returns {Promise<phigrosToken>} 当前用户的 sessionToken
+     */
+    async tokenForEvent(e) {
+        const token = await UserCredentials.fromEvent(e).getSessionToken()
+        if (!token) throw new Error('请先绑定 sessionToken。')
+        return token
+    }
+
+    /**
+     * 创建别名提案；API 失败时不写本地待处理记录。
+     * @param {AliasBotEvent} e 当前 Bot 事件
+     * @param {AliasProposalCreateInput} input 提案内容
+     * @returns {Promise<AliasProposalRecord | null>} 新提案
+     */
+    async create(e, input) {
+        return UserCredentials.fromEvent(e).createAliasProposal(input)
+    }
+
+    /**
+     * @param {AliasBotEvent} e 当前 Bot 事件
+     * @returns {Promise<AliasProposalRecord[]>} 当前用户的提案
+     */
+    async mine(e) {
+        const token = await this.tokenForEvent(e)
+        return makeRequest.getAliasProposalsMine({ token, limit: 50 })
+    }
+
+    /**
+     * @param {AliasBotEvent} e 当前 Bot 事件
+     * @returns {Promise<AliasProposalRecord[]>} 正在公投的提案
+     */
+    async publicList(e) {
+        const token = await this.tokenForEvent(e)
+        return makeRequest.getAliasPublicProposals({ token, limit: 50 })
+    }
+
+    /**
+     * @param {AliasBotEvent} e 当前 Bot 事件
+     * @param {string} proposalId 提案 UUID
+     * @param {string} reason 10-500 字公审理由
+     * @returns {Promise<AliasProposalRecord | null>} 更新后的提案
+     */
+    async requestPublicReview(e, proposalId, reason) {
+        const token = await this.tokenForEvent(e)
+        return makeRequest.requestAliasPublicReview(proposalId, { token, reason })
+    }
+
+    /**
+     * 设置、修改或撤回公开投票。
+     * @param {AliasBotEvent} e 当前 Bot 事件
+     * @param {string} proposalId 提案 UUID
+     * @param {AliasVoteValue} value 1 赞成、-1 反对、0 撤票
+     * @returns {Promise<AliasProposalRecord | null>} 更新后的提案
+     */
+    async vote(e, proposalId, value) {
+        const token = await this.tokenForEvent(e)
+        return makeRequest.voteAliasProposal(proposalId, { token, value })
+    }
+
+    /**
+     * 下载并原子替换 Approved 快照，然后重建运行时别名索引。
+     * @param {boolean} [force=false] 是否忽略六小时成功间隔
+     * @returns {Promise<boolean>} 是否实际替换了快照
+     */
+    async syncApprovedSnapshot(force = false) {
+        const last = Number(await redis.get(lastApprovedSyncKey) || 0)
+        if (!force && Date.now() - last < 6 * 60 * 60 * 1000) return false
+        const parsed = validateApprovedAliasSnapshot(await makeRequest.getApprovedAliasSnapshot())
+        fs.mkdirSync(path.dirname(snapshotPath), { recursive: true })
+        const tempPath = `${snapshotPath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`
+        try {
+            fs.writeFileSync(tempPath, YAML.stringify(parsed), 'utf8')
+            fs.renameSync(tempPath, snapshotPath)
+        } finally {
+            if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath)
+        }
+        getInfo.setApprovedAliasSnapshot(parsed)
+        await redis.set(lastApprovedSyncKey, String(Date.now()))
+        return true
+    }
+
+    /** @returns {Promise<void>} 完成一次正式别名快照同步任务 */
+    async scheduledTask() {
+        if (!Config.getUserCfg('config', 'openPhiPluginApi') || isApiVersionBlocked()) return
+        if (this.runningTask) return
+        this.runningTask = true
+        try {
+            await this.syncApprovedSnapshot(false).catch(() => logger.warn('[phi-plugin] approved alias sync failed'))
+        } finally {
+            this.runningTask = false
+        }
+    }
+
+    /** @returns {Promise<void>} 启动时尝试拉取一次正式别名快照 */
+    async initialize() {
+        if (!Config.getUserCfg('config', 'openPhiPluginApi') || isApiVersionBlocked()) return
+        if (this.initialized) return
+        this.initialized = true
+        await this.syncApprovedSnapshot(true).catch(() => logger.warn('[phi-plugin] initial approved alias sync failed'))
+    }
+}
+
+export default new AliasProposalService()

package/core/model/api/apiVersion.js

@@ -0,0 +1,67 @@
+/** 插件当前支持的 phi-plugin-api 协议版本。 */
+export const SUPPORTED_API_VERSION = '1.1.0'
+
+let versionBlocked = false
+
+/**
+ * @typedef {'compatible'|'minor_mismatch'|'major_mismatch'|'invalid'} ApiVersionCompatibility
+ */
+
+/**
+ * 解析严格的三段式语义版本号，可接受可选的 `v` 前缀。
+ * @param {unknown} value 待解析的版本号
+ * @returns {{major: number, minor: number, patch: number, normalized: string} | null} 解析结果
+ */
+export function parseApiVersion(value) {
+    if (typeof value !== 'string') return null
+    const match = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(value.trim())
+    if (!match) return null
+    const major = Number(match[1])
+    const minor = Number(match[2])
+    const patch = Number(match[3])
+    return { major, minor, patch, normalized: `${major}.${minor}.${patch}` }
+}
+
+/**
+ * 主版本不同视为不兼容；主版本外的任一版本差异仅提示更新。
+ * @param {unknown} apiVersion API 返回的协议版本
+ * @param {string} [supportedVersion] 插件支持的协议版本
+ * @returns {{status: ApiVersionCompatibility, apiVersion: string, supportedVersion: string}}
+ */
+export function compareApiVersion(apiVersion, supportedVersion = SUPPORTED_API_VERSION) {
+    const actual = parseApiVersion(apiVersion)
+    const supported = parseApiVersion(supportedVersion)
+    if (!actual || !supported) {
+        return {
+            status: 'invalid',
+            apiVersion: typeof apiVersion === 'string' ? apiVersion.trim() : '',
+            supportedVersion,
+        }
+    }
+    const status = actual.major !== supported.major
+        ? 'major_mismatch'
+        : actual.minor !== supported.minor || actual.patch !== supported.patch
+            ? 'minor_mismatch'
+            : 'compatible'
+    return {
+        status,
+        apiVersion: actual.normalized,
+        supportedVersion: supported.normalized,
+    }
+}
+
+/**
+ * 更新当前运行周期的 API 协议阻断状态。
+ * @param {boolean} blocked 是否阻止所有 API 请求
+ */
+export function setApiVersionBlocked(blocked) {
+    versionBlocked = blocked
+}
+
+/**
+ * 查询当前运行周期是否已因协议版本不兼容而关闭 API。
+ * @returns {boolean}
+ */
+export function isApiVersionBlocked() {
+    return versionBlocked
+}

package/core/model/api/autoSeekApi.js

@@ -0,0 +1,165 @@
+import chalk from "chalk"
+import logger from "../../components/Logger.js"
+import { APIBASEURL } from "../game/constNum.js"
+import https from 'node:https';
+import axios from "axios";
+import { Config } from "../../components/index.js";
+import Version from "../../components/Version.js";
+import botApiAuth from "./botApiAuth.js";
+import { classifyApiConnectionError, getPhiApiUserMessage, isFatalBotIdentityError } from "./phiApiErrors.js";
+import {
+  compareApiVersion,
+  isApiVersionBlocked,
+  setApiVersionBlocked,
+  SUPPORTED_API_VERSION,
+} from './apiVersion.js';
+
+
+
+export class AutoSeekApi {
+
+  constructor() {
+    //是否在等待API状态测试结果
+    this.waitApi = false;
+    //是否在轮询检测API状态
+    this.seekingApi = false;
+
+    this.openPhiPluginApi = false;
+    // 主版本不兼容或版本响应无效时阻止所有 API 业务请求。
+    this.remoteApiVersion = '';
+  }
+
+  /**
+   * 判断当前运行周期是否因 API 协议版本不兼容而被关闭。
+   * @returns {boolean}
+   */
+  isVersionBlocked() {
+    return isApiVersionBlocked()
+  }
+
+  /**
+   * 校验状态接口返回的 API 协议版本并更新运行时开关。
+   * @param {unknown} version API 返回的版本号
+   * @returns {boolean} 是否允许继续初始化 API 客户端
+   */
+  validateApiVersion(version) {
+    const result = compareApiVersion(version)
+    this.remoteApiVersion = result.apiVersion
+
+    if (result.status === 'major_mismatch') {
+      setApiVersionBlocked(true)
+      this.openPhiPluginApi = false
+      this.seekingApi = false
+      logger.error(
+        `[phi-plugin] API大版本不兼容：API ${result.apiVersion}，插件支持 ${result.supportedVersion}。` +
+        '已自动关闭 API 功能，请更新 phi-plugin 后重启。'
+      )
+      return false
+    }
+
+    if (result.status === 'invalid') {
+      setApiVersionBlocked(true)
+      this.openPhiPluginApi = false
+      this.seekingApi = false
+      logger.error(
+        `[phi-plugin] API未返回有效的协议版本，插件支持 ${SUPPORTED_API_VERSION}。` +
+        '已自动关闭 API 功能，请更新 phi-plugin 后重启。'
+      )
+      return false
+    }
+
+    setApiVersionBlocked(false)
+    if (result.status === 'minor_mismatch') {
+      logger.warn(
+        `[phi-plugin] API小版本不一致：API ${result.apiVersion}，插件支持 ${result.supportedVersion}。` +
+        '当前仍可继续使用，建议尽快更新 phi-plugin。'
+      )
+    }
+    return true
+  }
+
+  async testStatus() {
+    if (!Config.getUserCfg('config', 'openPhiPluginApi')) {
+      this.openPhiPluginApi = false
+      this.waitApi = false
+      this.seekingApi = false
+      return
+    }
+    if (this.waitApi) {
+      return
+    }
+
+    this.waitApi = true
+
+    logger.mark(chalk.yellow(`正在测试API链接...`))
+    let url = `${APIBASEURL}/status`
+    try {
+      const agent = new https.Agent({ rejectUnauthorized: false })
+      const res = await axios.get(url, { httpsAgent: agent, timeout: 5000 })
+      if (res.status != 200) {
+        logger.error(`[phi-plugin] API状态接口返回 HTTP ${res.status}`)
+        logger.mark(chalk.red(`API状态接口异常（HTTP ${res.status}），插件将在30秒后重试`))
+        this.openPhiPluginApi = false
+        this.seekApi()
+      } else {
+        // 当前接口使用 data 包装；保留对早期扁平响应的读取兼容。
+        const resdata = res.data?.data ?? res.data
+        if (!this.validateApiVersion(resdata?.version)) {
+          this.waitApi = false
+          return
+        }
+        logger.mark(chalk.green(`API地址测试成功！${resdata?.id || 'phi-plugin-api'} ${resdata.version}`))
+        this.openPhiPluginApi = true
+        try {
+          const identity = await botApiAuth.recoverAfterReconnect(Version.ver)
+          logger.mark(chalk.green(`API Bot身份已就绪：${identity.clientId}`))
+          const { default: botSyncService } = await import('./botSyncService.js')
+          await botSyncService.recoverAfterReconnect()
+          const { default: aliasProposalService } = await import('./aliasProposalService.js')
+          await aliasProposalService.initialize()
+          this.seekingApi = false
+        } catch (/** @type {any} */ error) {
+          logger[isFatalBotIdentityError(error) ? 'error' : 'warn'](
+            `[phi-plugin] API已恢复，但Bot身份恢复失败：${error?.code || getPhiApiUserMessage(error)}`
+          )
+          if (isFatalBotIdentityError(error)) {
+            this.seekingApi = false
+          } else {
+            this.seekApi()
+          }
+        }
+      }
+    } catch (e) {
+      const error = classifyApiConnectionError(e)
+      logger.error(`[phi-plugin] API连接检测失败：${error.code}`)
+      logger.mark(chalk.red(`${getPhiApiUserMessage(error)} 插件将在30秒后重试`))
+      this.openPhiPluginApi = false
+      this.seekApi()
+    }
+    this.waitApi = false
+  }
+
+  async seekApi() {
+    if (!Config.getUserCfg('config', 'openPhiPluginApi')) {
+      this.openPhiPluginApi = false
+      this.waitApi = false
+      this.seekingApi = false
+      return
+    }
+    if (isApiVersionBlocked()) {
+      this.openPhiPluginApi = false
+      this.seekingApi = false
+      return
+    }
+    if (this.seekingApi) {
+      return
+    }
+    this.seekingApi = true
+    while (this.seekingApi) {
+      await new Promise(resolve => setTimeout(resolve, 1000 * 30));
+      await this.testStatus()
+    }
+  }
+}
+
+export default new AutoSeekApi();

package/core/model/api/botApiAuth.js

@@ -0,0 +1,208 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import axios from 'axios';
+import YAML from 'yaml';
+import Config from '../../components/Config.js';
+import logger from '../../components/Logger.js';
+import { configPath } from '../filesystem/path.js';
+import { APIBASEURL } from '../game/constNum.js';
+import { classifyApiConnectionError, isFatalBotIdentityError, PhiApiError } from './phiApiErrors.js';
+import { isApiVersionBlocked } from './apiVersion.js';
+import { SUPPORTED_API_VERSION } from './apiVersion.js';
+
+const TIMEOUT = 5000;
+
+function configIdentity() {
+    return {
+        clientId: String(Config.getUserCfg('config', 'apiBotClientId') || '').trim(),
+        secret: String(Config.getUserCfg('config', 'apiBotClientSecret') || '').trim(),
+        secretVersion: Number(Config.getUserCfg('config', 'apiBotSecretVersion') || 0),
+    };
+}
+
+/** @param {{clientId: string, secret: string, secretVersion: number}} identity */
+function writeIdentityAtomic(identity) {
+    const target = path.join(configPath, 'config.yaml');
+    const current = YAML.parse(fs.readFileSync(target, 'utf8')) || {};
+    current.apiBotClientId = identity.clientId;
+    current.apiBotClientSecret = identity.secret;
+    current.apiBotSecretVersion = identity.secretVersion;
+    const temp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temp, YAML.stringify(current), { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(temp, target);
+    delete Config.config['config.config'];
+}
+
+/** @param {any} response */
+function parseResponse(response) {
+    const data = response.data;
+    const nestedError = data?.error && typeof data.error === 'object' ? data.error : null;
+    if (response.status < 200 || response.status >= 300 || data?.error) {
+        throw new PhiApiError(
+            nestedError?.message || data?.message || (typeof data?.error === 'string' ? data.error : '') || `API request failed (${response.status})`,
+            response.status,
+            nestedError?.code || data?.code || data?.errorCode || 'api_request_failed',
+            { body: data, retryAfter: response.headers?.['retry-after'] },
+        );
+    }
+    return data;
+}
+
+export class BotApiAuth {
+    constructor() {
+        this.ready = false;
+        this.initializing = null;
+        this.fatalError = null;
+        this.fatalIdentity = '';
+    }
+
+    /** @returns {string} 本地配置中的 API 签发 Bot clientId，不发起网络请求 */
+    getClientId() {
+        return configIdentity().clientId;
+    }
+
+    async initialize(pluginVersion = SUPPORTED_API_VERSION) {
+        if (isApiVersionBlocked()) {
+            throw new PhiApiError(
+                'API协议大版本不兼容，请更新 phi-plugin 后重启',
+                0,
+                'api_version_incompatible',
+            );
+        }
+        if (this.ready) return configIdentity();
+        const current = configIdentity();
+        const fingerprint = `${current.clientId}:${current.secretVersion}:${crypto.createHash('sha256').update(current.secret).digest('hex')}`;
+        if (this.fatalError && this.fatalIdentity === fingerprint) throw this.fatalError;
+        if (this.fatalIdentity !== fingerprint) {
+            this.fatalError = null;
+            this.fatalIdentity = '';
+        }
+        if (this.initializing) return this.initializing;
+        this.initializing = this.initializeOnce(pluginVersion).finally(() => { this.initializing = null; });
+        return this.initializing;
+    }
+
+    /** @param {string} pluginVersion */
+    async initializeOnce(pluginVersion) {
+        const identity = configIdentity();
+        if (!identity.clientId || !identity.secret || !Number.isSafeInteger(identity.secretVersion) || identity.secretVersion < 1) {
+            return this.register(pluginVersion);
+        }
+        try {
+            await this.signedRequest('/bot-clients/self', undefined, 'GET', identity);
+            this.ready = true;
+            this.fatalError = null;
+            return identity;
+        } catch (/** @type {any} */ error) {
+            this.ready = false;
+            if (isFatalBotIdentityError(error)) {
+                this.fatalError = error;
+                this.fatalIdentity = `${identity.clientId}:${identity.secretVersion}:${crypto.createHash('sha256').update(identity.secret).digest('hex')}`;
+                logger.error(`[phi-plugin] API Bot凭证不可用，新平台API操作已停止：${error.code || error.message}`);
+            } else {
+                this.fatalError = null;
+                this.fatalIdentity = '';
+                logger.warn(`[phi-plugin] API Bot身份暂时无法验证，将在API恢复后重试：${error.code || error.message}`);
+            }
+            throw error;
+        }
+    }
+
+    async register(pluginVersion = SUPPORTED_API_VERSION) {
+        let response;
+        try {
+            response = await axios.post(`${APIBASEURL}/bot-clients/register`, JSON.stringify({
+                pluginName: 'phi-plugin',
+                pluginVersion,
+            }), {
+                headers: { 'Content-Type': 'application/json' },
+                timeout: TIMEOUT,
+                validateStatus: () => true,
+            });
+        } catch (error) {
+            throw classifyApiConnectionError(error);
+        }
+        const data = parseResponse(response);
+        const identity = {
+            clientId: String(data.clientId || ''),
+            secret: String(data.secret || ''),
+            secretVersion: Number(data.secretVersion || 0),
+        };
+        if (!identity.clientId || !identity.secret || identity.secretVersion < 1) {
+            throw new PhiApiError('API returned an invalid Bot credential', 502, 'invalid_registration_response');
+        }
+        writeIdentityAtomic(identity);
+        this.ready = true;
+        this.fatalError = null;
+        this.fatalIdentity = '';
+        logger.mark(`[phi-plugin] API Bot身份已签发：${identity.clientId}`);
+        if (data.claimUrl) logger.mark(`[phi-plugin] Bot认领链接（15分钟有效）：${data.claimUrl}`);
+        return { ...identity, claimUrl: data.claimUrl, claimExpiresAt: data.claimExpiresAt };
+    }
+
+    async recoverAfterReconnect(pluginVersion = SUPPORTED_API_VERSION) {
+        return this.initialize(pluginVersion);
+    }
+
+    async reset(pluginVersion = SUPPORTED_API_VERSION) {
+        this.ready = false;
+        return this.register(pluginVersion);
+    }
+
+    async getClaimLink() {
+        await this.initialize();
+        return this.signedRequest('/bot-clients/self/claim-code', {}, 'POST');
+    }
+
+    /** @param {string} method @param {string} originalPath @param {string} rawBody @param {{clientId:string, secret:string, secretVersion:number}} [identity] @returns {Record<string, string>} */
+    sign(method, originalPath, rawBody, identity = configIdentity()) {
+        if (!identity.clientId || !identity.secret || identity.secretVersion < 1) {
+            throw new PhiApiError('API Bot身份尚未初始化', 0, 'bot_identity_missing');
+        }
+        const timestamp = Math.floor(Date.now() / 1000).toString();
+        const nonce = crypto.randomBytes(18).toString('base64url');
+        const bodyHash = crypto.createHash('sha256').update(rawBody || '').digest('hex');
+        const canonical = [method.toUpperCase(), originalPath, timestamp, nonce, bodyHash].join('\n');
+        const signature = crypto.createHmac('sha256', identity.secret).update(canonical).digest('base64url');
+        return {
+            'X-Phi-Bot-Client-Id': identity.clientId,
+            'X-Phi-Bot-Key-Version': String(identity.secretVersion),
+            'X-Phi-Bot-Timestamp': timestamp,
+            'X-Phi-Bot-Nonce': nonce,
+            'X-Phi-Bot-Signature': signature,
+        };
+    }
+
+    /** @param {string} originalPath @param {any} body @param {string} [method] @param {{clientId:string, secret:string, secretVersion:number}} [identity] @param {Record<string,string>} [extraHeaders] @param {{timeout?:number}} [requestOptions] */
+    async signedRequest(originalPath, body, method = 'POST', identity = configIdentity(), extraHeaders = {}, requestOptions = {}) {
+        if (isApiVersionBlocked()) {
+            throw new PhiApiError(
+                'API协议大版本不兼容，请更新 phi-plugin 后重启',
+                0,
+                'api_version_incompatible',
+            );
+        }
+        const upperMethod = method.toUpperCase();
+        const rawBody = upperMethod === 'GET' ? '' : JSON.stringify(body ?? {});
+        const headers = { ...this.sign(upperMethod, originalPath, rawBody, identity), ...extraHeaders };
+        if (upperMethod !== 'GET') headers['Content-Type'] = 'application/json';
+        let response;
+        try {
+            response = await axios.request({
+                url: `${APIBASEURL}${originalPath}`,
+                method: upperMethod,
+                headers,
+                data: upperMethod === 'GET' ? undefined : rawBody,
+                timeout: requestOptions.timeout ?? TIMEOUT,
+                validateStatus: () => true,
+            });
+        } catch (error) {
+            throw classifyApiConnectionError(error);
+        }
+        return parseResponse(response);
+    }
+
+}
+
+export default new BotApiAuth();

package/core/model/api/botSyncService.js

@@ -0,0 +1,78 @@
+import logger from '../../components/Logger.js'
+import Version from '../../components/Version.js'
+import Config from '../../components/Config.js'
+import platform from '../../components/platform/index.js'
+import makeRequest from './makeRequest.js'
+import { isApiVersionBlocked } from './apiVersion.js'
+import themePolicy from '../theme/policy.js'
+
+export class BotSyncService {
+    constructor() {
+        this.running = false
+        this.initialized = false
+        this.reportRenderPressure = false
+        /** @type {Set<string>} */
+        this.pendingAcknowledgements = new Set()
+    }
+
+    /**
+     * 执行一次 Bot 状态同步；成功送达的消息在下一次请求中确认。
+     * @returns {Promise<void>}
+     */
+    async sync() {
+        if (this.running) return
+        this.running = true
+        const acknowledgedMessageIds = [...this.pendingAcknowledgements]
+        try {
+            // 始终在本地滚动采样；服务端许可只决定是否把匿名压力历史放入请求。
+            const renderPressure = (await import('../render/picmodle.js')).default.takeRenderPressureSnapshot()
+            const response = await makeRequest.syncBot({
+                pluginVersion: Version.ver,
+                acknowledgedMessageIds,
+                ...(this.reportRenderPressure ? { renderPressure } : {}),
+            })
+            for (const id of acknowledgedMessageIds) this.pendingAcknowledgements.delete(id)
+            this.reportRenderPressure = response?.reporting?.renderPressure === true
+            if (response?.themePolicy) themePolicy.apply(response.themePolicy)
+
+            for (const message of response?.messages || []) {
+                try {
+                    const sent = await platform.relpyPrivate(message.target.platformId, message.text)
+                    if (sent !== false && sent != null) this.pendingAcknowledgements.add(message.id)
+                } catch (error) {
+                    logger.warn(`[phi-plugin] Bot消息私聊失败，将在下次同步重试：${message.id}`, error)
+                }
+            }
+        } finally {
+            this.running = false
+        }
+    }
+
+    /** 启动时立即同步一次；失败由一分钟周期和 API 重连流程继续恢复。 */
+    async initialize() {
+        if (!Config.getUserCfg('config', 'openPhiPluginApi') || isApiVersionBlocked()) return
+        if (this.initialized) return
+        this.initialized = true
+        await this.sync().catch(error => {
+            logger.warn('[phi-plugin] 初始 Bot状态同步失败，将稍后重试', error)
+        })
+    }
+
+    /** API 恢复连接后立即补发心跳并拉取消息。 */
+    async recoverAfterReconnect() {
+        this.initialized = true
+        await this.sync().catch(error => {
+            logger.warn('[phi-plugin] API恢复后的 Bot状态同步失败', error)
+        })
+    }
+
+    /** @returns {Promise<void>} 一分钟平台任务入口 */
+    async scheduledTask() {
+        if (!Config.getUserCfg('config', 'openPhiPluginApi') || isApiVersionBlocked()) return
+        await this.sync().catch(error => {
+            logger.warn('[phi-plugin] Bot状态同步失败', error)
+        })
+    }
+}
+
+export default new BotSyncService()