@zhin.js/adapter-qq 5.0.2 → 6.0.0

package/lib/protocol.d.ts

@@ -0,0 +1,96 @@
+/**
+ * QQ Official Bot protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface QqAdapterConfig {
+    readonly name?: string;
+    readonly appid?: string;
+    readonly secret?: string;
+    /** Default `websocket`. `webhook` / `middleware` use httpHostToken POST. */
+    readonly mode?: 'websocket' | 'webhook' | 'middleware';
+    readonly sandbox?: boolean;
+    readonly intents?: readonly string[];
+    readonly accessTokenUrl?: string;
+    readonly gatewayUrl?: string;
+    readonly webhookPath?: string;
+    readonly port?: number;
+    readonly path?: string;
+    /** Transitional: legacy root `endpoints[]` with `context: qq`. */
+    readonly endpoints?: ReadonlyArray<{
+        readonly context?: string;
+        readonly name?: string;
+        readonly appid?: string;
+        readonly secret?: string;
+        readonly mode?: 'websocket' | 'webhook' | 'middleware';
+        readonly sandbox?: boolean;
+        readonly intents?: readonly string[];
+        readonly accessTokenUrl?: string;
+        readonly gatewayUrl?: string;
+        readonly webhookPath?: string;
+        readonly port?: number;
+        readonly path?: string;
+    }>;
+}
+export interface ResolvedQqWebsocketConfig {
+    readonly context: 'qq';
+    readonly mode: 'websocket';
+    readonly name: string;
+    readonly appid: string;
+    readonly secret: string;
+    readonly sandbox: boolean;
+    readonly intents?: readonly string[];
+    readonly accessTokenUrl?: string;
+    readonly gatewayUrl?: string;
+}
+export interface ResolvedQqHttpConfig {
+    readonly context: 'qq';
+    readonly mode: 'webhook' | 'middleware';
+    readonly name: string;
+    readonly appid: string;
+    readonly secret: string;
+    readonly webhookPath: string;
+    readonly sandbox: boolean;
+}
+export type ResolvedQqConfig = ResolvedQqWebsocketConfig | ResolvedQqHttpConfig;
+export type QqChannelKind = 'private' | 'group' | 'channel' | 'direct';
+export interface QqInboundMessage {
+    readonly id: string;
+    readonly content: string;
+    readonly channelKind: QqChannelKind;
+    readonly channelId: string;
+    readonly authorId: string;
+    readonly authorName: string;
+    readonly authorRoles?: string[];
+    readonly timestamp: number;
+    readonly guildId?: string;
+    readonly rawMessage?: string;
+    /**
+     * 入站即 @ 机器人（AT_MESSAGE_CREATE 的 mentions[].bot，或群 GROUP_AT_MESSAGE_CREATE
+     * 事件本身仅 @ 时下发）。新 Runtime 纯文本 content 需经 metadata 传递。
+     */
+    readonly mentioned?: boolean;
+}
+export interface QqWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface ParsedSendTarget {
+    readonly kind: QqChannelKind;
+    readonly id: string;
+}
+export declare function resolveQqConfig(config?: QqAdapterConfig): ResolvedQqConfig;
+/**
+ * Gateway reply target：`private:uid` / `group:gid` / `channel:cid` / `direct:guildId`.
+ */
+export declare function formatInboundTarget(msg: QqInboundMessage): string;
+export declare function parseSendTarget(target: string): ParsedSendTarget;
+export declare function senderDisplayName(msg: QqInboundMessage): string;
+export declare function formatInboundContent(msg: QqInboundMessage): string;
+/**
+ * Wire-encode an already-rendered outbound payload into a plain text / QQ Sendable string.
+ * Segment canonicalization is intentionally not done here.
+ */
+export declare function formatOutboundText(payload: unknown): string;
+/** 从 QQ API SendResult / 审核回包中解析出站消息 ID */
+export declare function resolveOutboundMessageId(result: unknown): string;

package/lib/protocol.js

@@ -0,0 +1,129 @@
+/**
+ * QQ Official Bot protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { pickCredential } from '@zhin.js/adapter';
+export function resolveQqConfig(config = {}) {
+    const entry = config.endpoints?.find((item) => item.context === 'qq' || !item.context);
+    const appid = pickCredential(config.appid, entry?.appid, process.env.QQ_APPID, process.env.QQ_BOT_APPID);
+    const secret = pickCredential(config.secret, entry?.secret, process.env.QQ_SECRET, process.env.QQ_BOT_SECRET);
+    if (!appid || !secret) {
+        throw new TypeError('QQ adapter requires appid + secret (plugins.<key>.appid/secret or endpoints with context: qq)');
+    }
+    const name = (typeof config.name === 'string' && config.name)
+        || (typeof entry?.name === 'string' && entry.name)
+        || process.env.QQ_BOT_NAME
+        || 'qq-bot';
+    const mode = config.mode ?? entry?.mode ?? 'websocket';
+    if (mode === 'webhook' || mode === 'middleware') {
+        const webhookPathRaw = config.webhookPath ?? entry?.webhookPath ?? '/qq/webhook';
+        const webhookPath = webhookPathRaw.startsWith('/') ? webhookPathRaw : `/${webhookPathRaw}`;
+        return {
+            context: 'qq',
+            mode,
+            name,
+            appid,
+            secret,
+            webhookPath,
+            sandbox: config.sandbox === true || entry?.sandbox === true,
+        };
+    }
+    return {
+        context: 'qq',
+        mode: 'websocket',
+        name,
+        appid,
+        secret,
+        sandbox: config.sandbox === true || entry?.sandbox === true,
+        intents: config.intents ?? entry?.intents,
+        accessTokenUrl: config.accessTokenUrl ?? entry?.accessTokenUrl,
+        gatewayUrl: config.gatewayUrl ?? entry?.gatewayUrl,
+    };
+}
+/**
+ * Gateway reply target：`private:uid` / `group:gid` / `channel:cid` / `direct:guildId`.
+ */
+export function formatInboundTarget(msg) {
+    return `${msg.channelKind}:${msg.channelId}`;
+}
+export function parseSendTarget(target) {
+    const sep = target.indexOf(':');
+    if (sep <= 0) {
+        return { kind: 'private', id: target };
+    }
+    const head = target.slice(0, sep);
+    const rest = target.slice(sep + 1);
+    if (head === 'private' || head === 'group' || head === 'channel' || head === 'direct') {
+        return { kind: head, id: rest };
+    }
+    return { kind: 'private', id: target };
+}
+export function senderDisplayName(msg) {
+    return msg.authorName || msg.authorId;
+}
+export function formatInboundContent(msg) {
+    const text = (msg.content || msg.rawMessage || '').trim();
+    return text || '(Empty message)';
+}
+/**
+ * Wire-encode an already-rendered outbound payload into a plain text / QQ Sendable string.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundText(payload) {
+    if (typeof payload === 'string')
+        return payload;
+    const segments = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && 'type' in payload
+            ? [payload]
+            : [];
+    if (segments.length === 0) {
+        return payload == null
+            ? ''
+            : typeof payload === 'object'
+                ? JSON.stringify(payload)
+                : String(payload);
+    }
+    return segments
+        .map((item) => {
+        if (typeof item === 'string')
+            return item;
+        const data = item.data ?? {};
+        switch (item.type) {
+            case 'text':
+                return String(data.text ?? data.content ?? '');
+            case 'at': {
+                const id = String(data.user_id ?? data.qq ?? data.id ?? '');
+                return id ? `<@!${id}>` : '';
+            }
+            case 'image':
+                return String(data.url || data.file || '');
+            case 'reply':
+                return '';
+            default:
+                return data.text != null ? String(data.text) : '';
+        }
+    })
+        .filter(Boolean)
+        .join('');
+}
+/** 从 QQ API SendResult / 审核回包中解析出站消息 ID */
+export function resolveOutboundMessageId(result) {
+    if (!result || typeof result !== 'object') {
+        throw new Error('QQ 发送消息失败：响应为空');
+    }
+    const row = result;
+    const nested = row.data && typeof row.data === 'object'
+        ? row.data
+        : undefined;
+    const audit = (row.message_audit ?? nested?.message_audit);
+    const id = row.id ?? row.message_id ?? audit?.audit_id;
+    if (id == null || id === '') {
+        const code = row.code;
+        const msg = row.message;
+        throw new Error(code != null
+            ? `QQ 发送消息失败（${String(code)}）${msg ? `: ${String(msg)}` : ''}`
+            : 'QQ 发送消息失败：响应缺少消息 ID');
+    }
+    return String(id);
+}

package/lib/qq-agent-deps.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Agent tool deps for qq.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+export interface QqAgentEndpoint {
+    getGuilds(): Promise<unknown[]>;
+    getChannels(guildId: string): Promise<unknown[]>;
+    getChannelInfo(channelId: string): Promise<unknown>;
+    getGuildMember(guildId: string, userId: string): Promise<unknown>;
+    getGuildRoles(guildId: string): Promise<unknown[]>;
+    createGuildRole(guildId: string, name: string, color?: number): Promise<unknown>;
+    addMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
+    removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
+}
+export interface QqAgentDeps {
+    getEndpoint: (endpointId: string) => QqAgentEndpoint;
+}
+export declare function registerQqAgentEndpoint(endpointId: string, endpoint: QqAgentEndpoint): () => void;
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export declare function setQqAgentDeps(deps: QqAgentDeps | null): void;
+export declare function getQqAgentDeps(): QqAgentDeps;

package/lib/qq-agent-deps.js

@@ -0,0 +1,30 @@
+/**
+ * Agent tool deps for qq.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+const endpoints = new Map();
+let override = null;
+export function registerQqAgentEndpoint(endpointId, endpoint) {
+    endpoints.set(endpointId, endpoint);
+    return () => {
+        if (endpoints.get(endpointId) === endpoint) {
+            endpoints.delete(endpointId);
+        }
+    };
+}
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setQqAgentDeps(deps) {
+    override = deps;
+}
+export function getQqAgentDeps() {
+    if (override)
+        return override;
+    return {
+        getEndpoint(endpointId) {
+            const registered = endpoints.get(endpointId);
+            if (!registered)
+                throw new Error(`Endpoint ${endpointId} 不存在`);
+            return registered;
+        },
+    };
+}

package/lib/qq-bind-api.d.ts

@@ -0,0 +1,36 @@
+export type QQBotEnv = 'production' | 'test';
+export declare enum BindStatus {
+    NONE = 0,
+    PENDING = 1,
+    COMPLETED = 2,
+    EXPIRED = 3
+}
+export declare function getQQBotHost(env?: QQBotEnv): string;
+export declare function generateBindKey(): string;
+export declare function buildConnectUrl(taskId: string, source?: string): string;
+/**
+ * AES-256-GCM 解密 base64 密文。
+ * 密文格式: IV(12 bytes) + ciphertext + AuthTag(16 bytes)
+ */
+export declare function decryptSecret(encryptedBase64: string, keyBase64: string): string;
+export interface BindTaskResult {
+    taskId: string;
+    key: string;
+}
+export declare function createBindTask(env?: QQBotEnv, timeoutMs?: number): Promise<BindTaskResult>;
+export interface PollBindResultOk {
+    status: BindStatus;
+    botAppId: string;
+    botEncryptSecret: string;
+    /** 扫码绑定开发者 QQ 的 OpenID（poll_bind_result 返回） */
+    userOpenId: string;
+}
+export declare function parsePollBindResultData(data: {
+    status?: number;
+    bot_appid?: string | number;
+    bot_encrypt_secret?: string;
+    user_openid?: string;
+    userOpenid?: string;
+    openid?: string;
+} | undefined): PollBindResultOk;
+export declare function pollBindResult(taskId: string, env?: QQBotEnv, timeoutMs?: number): Promise<PollBindResultOk>;

package/lib/{src/qq-bind-api.js → qq-bind-api.js}

@@ -87,4 +87,3 @@ export async function pollBindResult(taskId, env = 'production', timeoutMs = 10_
     }
     return parsePollBindResultData(res.data);
 }
-//# sourceMappingURL=qq-bind-api.js.map

package/lib/qq-bind-flow.d.ts

@@ -0,0 +1,19 @@
+export interface QqBindCredentials {
+    appId: string;
+    appSecret: string;
+    userOpenId?: string;
+}
+export interface QqBindCallbacks {
+    onSuccess: (credentials: QqBindCredentials[]) => void;
+    onFailure: (error: Error) => void;
+    onQrDisplayed?: (url: string) => void | Promise<void>;
+    onQrExpired?: () => void | Promise<void>;
+}
+export interface QqBindFlowOptions {
+    signal?: AbortSignal;
+    source?: string;
+}
+/**
+ * 轮询等待扫码结果（回调风格）。返回 stop 函数可中止流程。
+ */
+export declare function startQqBindFlow(callbacks: QqBindCallbacks, options?: QqBindFlowOptions): () => void;

package/lib/{src/qq-bind-flow.js → qq-bind-flow.js}

@@ -83,4 +83,3 @@ export function startQqBindFlow(callbacks, options = {}) {
     });
     return () => controller.abort();
 }
-//# sourceMappingURL=qq-bind-flow.js.map

package/lib/qq-bind-persist.d.ts

@@ -0,0 +1,12 @@
+export interface QqCredentialEnvKeys {
+    appidKey: string;
+    secretKey: string;
+    appidRef: string;
+    secretRef: string;
+}
+/** 按 endpoint 名称生成唯一 env 键（如 `QQ_MY_BOT_APPID`） */
+export declare function buildQqCredentialEnvKeys(endpointName: string): QqCredentialEnvKeys;
+/** 项目根：ZHIN_PROJECT_ROOT 优先，缺省 process.cwd()（替代 legacy runtimeCwd） */
+export declare function resolveProjectRoot(): string;
+/** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
+export declare function persistQqCredentialsToEnv(endpointName: string, appId: string, appSecret: string, projectRoot?: string): QqCredentialEnvKeys;

package/lib/{src/qq-bind-persist.js → qq-bind-persist.js}

@@ -1,7 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { runtimeCwd } from 'zhin.js';
-/** 按 endpoint 名称生成唯一 env 键（如 `QQ_MOCK_QQ_BOT_APPID`） */
+/** 按 endpoint 名称生成唯一 env 键（如 `QQ_MY_BOT_APPID`） */
 export function buildQqCredentialEnvKeys(endpointName) {
     const slug = endpointName.replace(/[^a-zA-Z0-9_]/g, '_').toUpperCase();
     const appidKey = `QQ_${slug}_APPID`;
@@ -13,9 +12,10 @@ export function buildQqCredentialEnvKeys(endpointName) {
         secretRef: `\${${secretKey}}`,
     };
 }
-function resolveProjectRoot() {
+/** 项目根：ZHIN_PROJECT_ROOT 优先，缺省 process.cwd()（替代 legacy runtimeCwd） */
+export function resolveProjectRoot() {
     const envRoot = process.env.ZHIN_PROJECT_ROOT?.trim();
-    return path.resolve(envRoot || runtimeCwd());
+    return path.resolve(envRoot || process.cwd());
 }
 function escapeRegExp(text) {
     return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -49,4 +49,3 @@ export function persistQqCredentialsToEnv(endpointName, appId, appSecret, projec
     fs.writeFileSync(envPath, content);
     return keys;
 }
-//# sourceMappingURL=qq-bind-persist.js.map

package/lib/qq-endpoint-commands.d.ts

@@ -0,0 +1,25 @@
+import type { QqRuntimeState } from './qq-runtime-state.js';
+export type QqCommandReply = (text: string) => Promise<unknown>;
+/**
+ * endpoint 管理命令的操作者校验：实例配置声明了 master（顶层或任一端点项）时
+ * 仅 master 可执行 add/cancel/remove；未配置则放行（首个扫码绑定者即为 owner，
+ * legacy applyBindOwnership 会把 operator 写为新端点的 master）。
+ */
+export declare function isQqEndpointOperator(config: unknown, input: unknown): boolean;
+export declare const QQ_ENDPOINT_FORBIDDEN = "\u4EC5 master \u53EF\u6267\u884C QQ endpoint \u7BA1\u7406\u547D\u4EE4";
+/**
+ * 从命令 input（Runtime Message）提取 $reply；非消息来源（如 Host API 调用）降级为 no-op。
+ */
+export declare function extractQqCommandReply(input: unknown): QqCommandReply;
+/** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
+export declare function runQqEndpointList(state: QqRuntimeState, projectRoot?: string): string;
+/**
+ * `qq endpoint add [name]`：启动扫码绑定流程。
+ * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
+ * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
+ */
+export declare function runQqEndpointAdd(state: QqRuntimeState, name: string | undefined, reply: QqCommandReply, projectRoot?: string): Promise<string>;
+/** `qq endpoint cancel`：中止进行中的绑定流程 */
+export declare function runQqEndpointCancel(state: QqRuntimeState): string;
+/** `qq endpoint remove <name>`：从 zhin.config.yml 移除对应 endpoints 项 */
+export declare function runQqEndpointRemove(_state: QqRuntimeState, name: string, projectRoot?: string): string;

package/lib/qq-endpoint-commands.js

@@ -0,0 +1,147 @@
+/**
+ * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
+ */
+import { startQqBindFlow } from './qq-bind-flow.js';
+import { persistQqCredentialsToEnv } from './qq-bind-persist.js';
+import { addQqEndpointToConfig, listQqEndpointEntries, removeQqEndpointFromConfig, } from './qq-endpoint-config.js';
+/**
+ * endpoint 管理命令的操作者校验：实例配置声明了 master（顶层或任一端点项）时
+ * 仅 master 可执行 add/cancel/remove；未配置则放行（首个扫码绑定者即为 owner，
+ * legacy applyBindOwnership 会把 operator 写为新端点的 master）。
+ */
+export function isQqEndpointOperator(config, input) {
+    const cfg = (config ?? {});
+    const masters = new Set();
+    const collect = (value) => {
+        if (value === undefined || value === null)
+            return;
+        const text = String(value).trim();
+        if (text)
+            masters.add(text);
+    };
+    collect(cfg.master);
+    if (Array.isArray(cfg.endpoints)) {
+        for (const entry of cfg.endpoints) {
+            collect(entry?.master);
+        }
+    }
+    if (masters.size === 0)
+        return true;
+    const sender = String(input?.sender ?? '').trim();
+    return !!sender && masters.has(sender);
+}
+export const QQ_ENDPOINT_FORBIDDEN = '仅 master 可执行 QQ endpoint 管理命令';
+/**
+ * 从命令 input（Runtime Message）提取 $reply；非消息来源（如 Host API 调用）降级为 no-op。
+ */
+export function extractQqCommandReply(input) {
+    const reply = input?.$reply;
+    if (typeof reply === 'function') {
+        return (text) => reply.call(input, text);
+    }
+    return async () => undefined;
+}
+/** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
+export function runQqEndpointList(state, projectRoot) {
+    const running = [...state.endpoints.values()];
+    const configured = listQqEndpointEntries(projectRoot);
+    const lines = [];
+    lines.push('【运行中的 QQ endpoints】');
+    if (running.length === 0) {
+        lines.push('  （无）');
+    }
+    else {
+        for (const endpoint of running) {
+            lines.push(`  - ${endpoint.name}（${endpoint.mode}）`);
+        }
+    }
+    lines.push('【配置中的 QQ endpoints】（zhin.config.yml → plugins.qq.endpoints）');
+    if (configured.length === 0) {
+        lines.push('  （无）');
+    }
+    else {
+        for (const entry of configured) {
+            lines.push(`  - ${entry.name}（appid: ${entry.appid}）`);
+        }
+    }
+    if (state.bindFlow) {
+        lines.push('⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消');
+    }
+    return lines.join('\n');
+}
+/**
+ * `qq endpoint add [name]`：启动扫码绑定流程。
+ * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
+ * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
+ */
+export function runQqEndpointAdd(state, name, reply, projectRoot) {
+    if (state.bindFlow) {
+        return Promise.resolve('已有进行中的 QQ 机器人绑定，请先发送 qq endpoint cancel 取消后再试');
+    }
+    const endpointName = name?.trim() || undefined;
+    return new Promise((resolve) => {
+        let firstReplied = false;
+        const settle = (text) => {
+            if (!firstReplied) {
+                firstReplied = true;
+                resolve(text);
+                return;
+            }
+            void reply(text);
+        };
+        const stop = startQqBindFlow({
+            onQrDisplayed: (url) => {
+                // QQ 出站当前仅支持纯文本（富媒体未迁移），二维码只能发链接文本
+                settle(`请用手机 QQ 打开以下链接完成扫码绑定（二维码图片出站暂未支持，故发送链接）：\n${url}`);
+            },
+            onQrExpired: async () => {
+                await reply('二维码已过期，正在刷新，请扫描新链接…');
+            },
+            onSuccess: async (credentials) => {
+                state.bindFlow = null;
+                try {
+                    const [{ appId, appSecret }] = credentials;
+                    const finalName = endpointName ?? appId;
+                    const envKeys = persistQqCredentialsToEnv(finalName, appId, appSecret, projectRoot);
+                    const filePath = addQqEndpointToConfig({ name: finalName, appid: envKeys.appidRef, secret: envKeys.secretRef }, projectRoot);
+                    settle(`✅ 绑定成功！endpoint「${finalName}」的凭据已写入 .env，并已追加到 ${filePath} 的 plugins.qq.endpoints。\n` +
+                        '⚠️ 需重启 zhin 后新 endpoint 才会生效。');
+                }
+                catch (error) {
+                    settle(`绑定成功但写入配置失败：${error instanceof Error ? error.message : String(error)}`);
+                }
+            },
+            onFailure: (error) => {
+                state.bindFlow = null;
+                settle(`❌ QQ 绑定失败：${error.message}`);
+            },
+        }, { source: 'zhin' });
+        state.bindFlow = { name: endpointName, stop };
+    });
+}
+/** `qq endpoint cancel`：中止进行中的绑定流程 */
+export function runQqEndpointCancel(state) {
+    if (!state.bindFlow) {
+        return '当前没有进行中的 QQ 绑定流程';
+    }
+    state.bindFlow.stop();
+    state.bindFlow = null;
+    return '已取消进行中的 QQ 绑定流程';
+}
+/** `qq endpoint remove <name>`：从 zhin.config.yml 移除对应 endpoints 项 */
+export function runQqEndpointRemove(_state, name, projectRoot) {
+    const trimmed = name.trim();
+    if (!trimmed)
+        return '用法：qq endpoint remove <name>';
+    try {
+        const { removed, filePath } = removeQqEndpointFromConfig(trimmed, projectRoot);
+        if (!removed) {
+            return `配置中不存在 qq endpoint「${trimmed}」（${filePath} → plugins.qq.endpoints）`;
+        }
+        return (`已从 ${filePath} 的 plugins.qq.endpoints 移除「${trimmed}」。\n` +
+            '⚠️ 需重启 zhin 后生效（运行中的连接届时才会断开）；.env 中的凭据键未删除，可手动清理。');
+    }
+    catch (error) {
+        return `移除失败：${error instanceof Error ? error.message : String(error)}`;
+    }
+}

package/lib/qq-endpoint-config.d.ts

@@ -0,0 +1,17 @@
+export interface QqEndpointConfigEntry {
+    name: string;
+    appid: string;
+    secret: string;
+    [key: string]: unknown;
+}
+/** 定位项目配置文件：ZHIN_CONFIG 指定优先，否则发现 zhin.config.yml/.yaml，都没有则默认新建 zhin.config.yml */
+export declare function findQqConfigFile(projectRoot?: string): string;
+/** 读取 plugins.qq.endpoints（plain JS）；plugins/qq 缺失或形态不符时返回 [] */
+export declare function listQqEndpointEntries(projectRoot?: string): QqEndpointConfigEntry[];
+/** 追加 endpoint 到 plugins.qq.endpoints；name 已存在时报错 */
+export declare function addQqEndpointToConfig(entry: QqEndpointConfigEntry, projectRoot?: string): string;
+/** 按 name 移除 plugins.qq.endpoints 项；不存在返回 false */
+export declare function removeQqEndpointFromConfig(name: string, projectRoot?: string): {
+    removed: boolean;
+    filePath: string;
+};