@zhin.js/adapter-qq 5.0.3 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @zhin.js/adapter-qq
 
+## 6.0.0
+
+### Minor Changes
+
+- 3ea88d8: 恢复 legacy 的聊天命令添加 endpoint 能力（随适配器发布）：`qq endpoint add [name]`（手机 QQ 扫码绑定 → 凭据写 `.env` 的 `QQ_<NAME>_APPID/SECRET` → 追加 `plugins.qq.endpoints` 配置，重启生效）、`qq endpoint cancel`（中止绑定）、`qq endpoint list`（运行中 + 配置内 endpoints）、`qq endpoint remove <name>`（移除配置项）。add/cancel/remove 受 `master` 限制（顶层或 `endpoints[i]` 声明时仅 master 可执行，未配置则放行）；schema 新增顶层共享字段 `master`。绑定协议（create_bind_task / poll_bind_result / AES-256-GCM 解密）自 legacy 移植，二维码当前以链接文本下发（QQ 出站富媒体待迁移）。
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- e5c84ed: Adapter 多账号：插件实例 config 支持 `endpoints: [{name, ...覆盖}]` 数组，`expandEndpointConfigs` 将一个实例展开为多个 endpoint record（id 为 `<slotId>~<name>`，顶层字段共享、逐项覆盖），替代多 `instanceKey` 方案；Console `/api/plugins` 收敛为一个插件卡片 + 多 endpoint。icqq / qq schema 与 README 补 `endpoints` 配置。
+
+  Plugin Runtime Console Host：补 `/esm/*` React/router ESM 代理路由（legacy `consoleApiRouter` 对齐），TypeScriptClientBuilder 裸导入改写为 `/esm/<enc>.mjs`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- f32c424: 适配器配置统一为 endpoints 数组格式：`plugins.<adapter>` 为该 adapter 所有 endpoint 的通用配置，`plugins.<adapter>.endpoints[i]` 为单个 endpoint 的特殊配置（逐项覆盖，`name` 必填）。slack / github schema 新增 `endpoints` 属性；icqq / qq / slack 顶层必填改为 `anyOf`（单 endpoint 字段或 `endpoints` 数组二选一，兼容 Ajv strictRequired）。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/agent@1.0.5
+  - @zhin.js/host-http@1.0.2
+  - zhin.js@5.0.0
+  - @zhin.js/command@1.0.2
+
 ## 5.0.3
 
 ### Patch Changes

package/README.md

@@ -36,7 +36,7 @@ pnpm add @zhin.js/adapter-qq
 | **WebSocket（默认）** | `qq-official-bot` 正向连接；无需公网回调 |
 | **host-http** | WebSocket **不需要**；Webhook / middleware 模式需要（经 `httpHostToken`） |
 
-必填字段：`appid`、`secret`。
+必填字段（`endpoints[i]`）：`name`、`appid`、`secret`。
 
 ## 最小配置
 
@@ -44,14 +44,46 @@ pnpm add @zhin.js/adapter-qq
 # zhin.config.yml（Plugin Runtime）
 plugins:
   qq:
-    name: my-qq-bot
-    appid: ${QQ_APPID}
-    secret: ${QQ_SECRET}
     # mode: websocket   # 默认
+    endpoints:
+      - name: my-qq-bot
+        appid: ${QQ_APPID}
+        secret: ${QQ_SECRET}
+```
+
+多账号：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`name` 必填）：
+
+```yaml
+plugins:
+  qq:
+    mode: websocket
+    intents: [GUILDS, GROUP_AND_C2C_EVENT]
+    endpoints:
+      - name: main-bot
+        appid: ${QQ_APPID}
+        secret: ${QQ_SECRET}
+      - name: second-bot
+        appid: ${QQ_APPID_2}
+        secret: ${QQ_SECRET_2}
 ```
 
 根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-qq`（`instanceKey: qq`）。
 
+## Endpoint 管理命令
+
+适配器自带 `qq endpoint` 命令组（聊天内直接使用，默认无前缀；受 `commandPrefix` 影响）：
+
+| 命令 | 说明 |
+|------|------|
+| `qq endpoint add [name]` | 手机 QQ 扫码绑定：下发二维码链接 → 确认后凭据写入 `.env`（`QQ_<NAME>_APPID/SECRET`），并追加 `plugins.qq.endpoints`（重启生效） |
+| `qq endpoint cancel` | 取消进行中的扫码绑定（同时只允许一个流程） |
+| `qq endpoint list` | 列出运行中与配置中的 endpoints |
+| `qq endpoint remove <name>` | 从配置移除 endpoint（`.env` 键保留，可手动清理） |
+
+add/cancel/remove 受 `master` 限制：实例配置声明了 `master`（顶层或 `endpoints[i]`）时仅
+master 可执行；未配置则放行（首个扫码绑定者即 owner）。二维码当前以链接文本下发
+（出站富媒体待迁移），用手机 QQ 打开链接即可扫码。
+
 ## 环境变量
 
 | 变量 | 说明 |

package/adapters/qq.ts

@@ -9,6 +9,7 @@ import {
   resolveQqConfig,
   type QqAdapterConfig,
 } from '../src/protocol.js';
+import { qqRuntimeStateToken } from '../src/qq-runtime-state.js';
 
 export {
   QqHttpEndpoint,
@@ -28,6 +29,11 @@ export default defineAdapter<QqAdapterConfig>({
   create(context) {
     const config = resolveQqConfig(context.config);
     const gateway = context.use(messageGatewayToken);
+    // 注册到插件运行时状态（qq endpoint list 的"运行中"数据源）
+    context.use(qqRuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: config.mode,
+    });
     if (config.mode === 'webhook' || config.mode === 'middleware') {
       return new QqHttpEndpoint({
         id: context.id,

package/commands/endpoint/add/[name:string=].ts

@@ -0,0 +1,21 @@
+import { defineCommand } from '@zhin.js/command';
+import {
+  extractQqCommandReply,
+  isQqEndpointOperator,
+  QQ_ENDPOINT_FORBIDDEN,
+  runQqEndpointAdd,
+} from '../../../src/qq-endpoint-commands.js';
+import { qqRuntimeStateToken } from '../../../src/qq-runtime-state.js';
+
+export default defineCommand({
+  description: '手机 QQ 扫码绑定机器人，凭据写入 .env 并追加到 zhin.config.yml（重启生效）',
+  execute({ config, input, params, use }) {
+    if (!isQqEndpointOperator(config, input)) return QQ_ENDPOINT_FORBIDDEN;
+    const name = typeof params.name === 'string' && params.name.trim() ? params.name.trim() : undefined;
+    return runQqEndpointAdd(
+      use(qqRuntimeStateToken),
+      name,
+      extractQqCommandReply(input),
+    );
+  },
+});

package/commands/endpoint/cancel.ts

@@ -0,0 +1,15 @@
+import { defineCommand } from '@zhin.js/command';
+import {
+  isQqEndpointOperator,
+  QQ_ENDPOINT_FORBIDDEN,
+  runQqEndpointCancel,
+} from '../../src/qq-endpoint-commands.js';
+import { qqRuntimeStateToken } from '../../src/qq-runtime-state.js';
+
+export default defineCommand({
+  description: '取消进行中的 QQ 扫码绑定流程',
+  execute({ config, input, use }) {
+    if (!isQqEndpointOperator(config, input)) return QQ_ENDPOINT_FORBIDDEN;
+    return runQqEndpointCancel(use(qqRuntimeStateToken));
+  },
+});

package/commands/endpoint/list.ts

@@ -0,0 +1,10 @@
+import { defineCommand } from '@zhin.js/command';
+import { runQqEndpointList } from '../../src/qq-endpoint-commands.js';
+import { qqRuntimeStateToken } from '../../src/qq-runtime-state.js';
+
+export default defineCommand({
+  description: '列出 QQ endpoints（运行中 + zhin.config.yml 配置）',
+  execute({ use }) {
+    return runQqEndpointList(use(qqRuntimeStateToken));
+  },
+});

package/commands/endpoint/remove/[name:string].ts

@@ -0,0 +1,15 @@
+import { defineCommand } from '@zhin.js/command';
+import {
+  isQqEndpointOperator,
+  QQ_ENDPOINT_FORBIDDEN,
+  runQqEndpointRemove,
+} from '../../../src/qq-endpoint-commands.js';
+import { qqRuntimeStateToken } from '../../../src/qq-runtime-state.js';
+
+export default defineCommand({
+  description: '从 zhin.config.yml 的 plugins.qq.endpoints 移除指定 endpoint（重启生效）',
+  execute({ config, input, params, use }) {
+    if (!isQqEndpointOperator(config, input)) return QQ_ENDPOINT_FORBIDDEN;
+    return runQqEndpointRemove(use(qqRuntimeStateToken), String(params.name ?? ''));
+  },
+});

package/lib/endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -18,7 +18,10 @@ export interface QqEndpointOptions {
 }
 export declare class QqWebsocketEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: QqEndpointOptions);
+    /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
+    get name(): string;
     start(): Promise<void>;
     open(): void;
     close(): void;
@@ -48,7 +51,10 @@ export interface QqHttpEndpointOptions {
 /** Webhook / middleware inbound via httpHostToken POST (qq-official-bot Middleware receiver). */
 export declare class QqHttpEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: QqHttpEndpointOptions);
+    /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
+    get name(): string;
     start(): Promise<void>;
     open(): void;
     close(): void;

package/lib/endpoint.js

@@ -11,10 +11,15 @@ export class QqWebsocketEndpoint {
     #open = false;
     #started = false;
     #unregisterAgent;
+    management = createQqEndpointManagement(this);
     constructor(options) {
         this.#options = options;
         this.#createBot = options.createBot ?? defaultCreateBot;
     }
+    /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
+    get name() {
+        return this.#options.config.name;
+    }
     async start() {
         if (this.#started)
             return;
@@ -166,10 +171,15 @@ export class QqHttpEndpoint {
     #open = false;
     #started = false;
     #unregisterAgent;
+    management = createQqEndpointManagement(this);
     constructor(options) {
         this.#options = options;
         this.#createBot = options.createBot ?? defaultCreateHttpBot;
     }
+    /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
+    get name() {
+        return this.#options.config.name;
+    }
     async start() {
         if (this.#started)
             return;
@@ -313,3 +323,36 @@ export class QqHttpEndpoint {
         return this.#bot;
     }
 }
+function createQqEndpointManagement(endpoint) {
+    return Object.freeze({
+        async listChannels() {
+            const channels = [];
+            const guilds = await endpoint.getGuilds();
+            for (const guildValue of Array.isArray(guilds) ? guilds : []) {
+                const guild = asRecord(guildValue);
+                const guildId = String(guild.id ?? guild.guild_id ?? guildValue ?? '');
+                if (!guildId)
+                    continue;
+                const guildName = String(guild.name ?? guild.guild_name ?? guildId);
+                const rows = await endpoint.getChannels(guildId);
+                for (const channelValue of Array.isArray(rows) ? rows : []) {
+                    const channel = asRecord(channelValue);
+                    const id = String(channel.id ?? channel.channel_id ?? channelValue ?? '');
+                    if (!id)
+                        continue;
+                    channels.push({
+                        id,
+                        name: String(channel.name ?? channel.channel_name ?? id),
+                        parent: { type: 'guild', id: guildId, name: guildName },
+                    });
+                }
+            }
+            return channels;
+        },
+    });
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}

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/qq-bind-api.js

@@ -0,0 +1,89 @@
+/**
+ * QQ Bot 扫码绑定协议（内联）
+ * Protocol aligned with @tencent-connect/qqbot-connector@1.1.0 qqbot-session — inlined to avoid runtime dependency.
+ */
+import { createDecipheriv, randomBytes } from 'node:crypto';
+const HOSTS = {
+    production: 'q.qq.com',
+    test: 'test.q.qq.com',
+};
+export var BindStatus;
+(function (BindStatus) {
+    BindStatus[BindStatus["NONE"] = 0] = "NONE";
+    BindStatus[BindStatus["PENDING"] = 1] = "PENDING";
+    BindStatus[BindStatus["COMPLETED"] = 2] = "COMPLETED";
+    BindStatus[BindStatus["EXPIRED"] = 3] = "EXPIRED";
+})(BindStatus || (BindStatus = {}));
+export function getQQBotHost(env = 'production') {
+    return HOSTS[env];
+}
+export function generateBindKey() {
+    return randomBytes(32).toString('base64');
+}
+export function buildConnectUrl(taskId, source = 'zhin') {
+    return `https://${getQQBotHost('production')}/qqbot/openclaw/connect.html?task_id=${encodeURIComponent(taskId)}&source=${encodeURIComponent(source)}&_wv=2`;
+}
+/**
+ * AES-256-GCM 解密 base64 密文。
+ * 密文格式: IV(12 bytes) + ciphertext + AuthTag(16 bytes)
+ */
+export function decryptSecret(encryptedBase64, keyBase64) {
+    const key = Buffer.from(keyBase64, 'base64');
+    const payload = Buffer.from(encryptedBase64, 'base64');
+    const iv = payload.subarray(0, 12);
+    const authTag = payload.subarray(payload.length - 16);
+    const ciphertext = payload.subarray(12, payload.length - 16);
+    const decipher = createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(authTag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+}
+async function postJson(url, body, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status} from ${url}`);
+        }
+        return (await res.json());
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function createBindTask(env = 'production', timeoutMs = 10_000) {
+    const url = `https://${getQQBotHost(env)}/lite/create_bind_task`;
+    const key = generateBindKey();
+    const res = await postJson(url, { key }, timeoutMs);
+    if (res.retcode !== 0) {
+        throw new Error(res.msg ?? 'create_bind_task failed');
+    }
+    if (!res.data?.task_id) {
+        throw new Error('create_bind_task: missing task_id');
+    }
+    return { taskId: res.data.task_id, key };
+}
+export function parsePollBindResultData(data) {
+    return {
+        status: (data?.status ?? BindStatus.NONE),
+        botAppId: String(data?.bot_appid ?? ''),
+        botEncryptSecret: data?.bot_encrypt_secret ?? '',
+        userOpenId: String(data?.user_openid ?? data?.userOpenid ?? data?.openid ?? ''),
+    };
+}
+export async function pollBindResult(taskId, env = 'production', timeoutMs = 10_000) {
+    const url = `https://${getQQBotHost(env)}/lite/poll_bind_result`;
+    const res = await postJson(url, { task_id: taskId }, timeoutMs);
+    if (res.retcode !== 0) {
+        throw new Error(res.msg ?? 'poll_bind_result failed');
+    }
+    return parsePollBindResultData(res.data);
+}

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/qq-bind-flow.js

@@ -0,0 +1,85 @@
+/**
+ * QQ Bot 扫码绑定流程（内联，等价 qqbot-connector startQrConnect）
+ */
+import { BindStatus, buildConnectUrl, createBindTask, decryptSecret, pollBindResult, } from './qq-bind-api.js';
+const POLL_INTERVAL_MS = 2000;
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new DOMException('Aborted', 'AbortError'));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(new DOMException('Aborted', 'AbortError'));
+        }, { once: true });
+    });
+}
+async function pollUntilResult(taskId, key, signal) {
+    while (!signal?.aborted) {
+        let result;
+        try {
+            result = await pollBindResult(taskId);
+        }
+        catch {
+            await sleep(POLL_INTERVAL_MS, signal);
+            continue;
+        }
+        if (result.status === BindStatus.COMPLETED) {
+            const appSecret = decryptSecret(result.botEncryptSecret, key);
+            return {
+                outcome: 'scanned',
+                appId: result.botAppId,
+                appSecret,
+                userOpenId: result.userOpenId,
+            };
+        }
+        if (result.status === BindStatus.EXPIRED) {
+            return { outcome: 'expired' };
+        }
+        await sleep(POLL_INTERVAL_MS, signal);
+    }
+    throw new DOMException('Aborted', 'AbortError');
+}
+/**
+ * 轮询等待扫码结果（回调风格）。返回 stop 函数可中止流程。
+ */
+export function startQqBindFlow(callbacks, options = {}) {
+    const controller = new AbortController();
+    const signal = options.signal
+        ? AbortSignal.any([controller.signal, options.signal])
+        : controller.signal;
+    void (async () => {
+        for (;;) {
+            if (signal.aborted) {
+                throw new DOMException('Aborted', 'AbortError');
+            }
+            let task;
+            try {
+                task = await createBindTask();
+            }
+            catch (err) {
+                throw new Error(`获取绑定任务失败: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+            const connectUrl = buildConnectUrl(task.taskId, options.source ?? 'zhin');
+            await callbacks.onQrDisplayed?.(connectUrl);
+            const pollResult = await pollUntilResult(task.taskId, task.key, signal);
+            if (pollResult.outcome === 'scanned') {
+                callbacks.onSuccess([{
+                        appId: pollResult.appId,
+                        appSecret: pollResult.appSecret,
+                        userOpenId: pollResult.userOpenId || undefined,
+                    }]);
+                return;
+            }
+            await callbacks.onQrExpired?.();
+        }
+    })().catch((err) => {
+        if (err instanceof DOMException && err.name === 'AbortError') {
+            return;
+        }
+        callbacks.onFailure(err instanceof Error ? err : new Error(String(err)));
+    });
+    return () => controller.abort();
+}

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/qq-bind-persist.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** 按 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`;
+    const secretKey = `QQ_${slug}_SECRET`;
+    return {
+        appidKey,
+        secretKey,
+        appidRef: `\${${appidKey}}`,
+        secretRef: `\${${secretKey}}`,
+    };
+}
+/** 项目根：ZHIN_PROJECT_ROOT 优先，缺省 process.cwd()（替代 legacy runtimeCwd） */
+export function resolveProjectRoot() {
+    const envRoot = process.env.ZHIN_PROJECT_ROOT?.trim();
+    return path.resolve(envRoot || process.cwd());
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function upsertEnvLine(content, key, value) {
+    const lineRe = new RegExp(`^${escapeRegExp(key)}\\s*=.*$`, 'm');
+    const newLine = `${key}=${value}`;
+    if (lineRe.test(content)) {
+        return content.replace(lineRe, newLine);
+    }
+    const trimmed = content.replace(/\s*$/, '');
+    if (trimmed.length === 0) {
+        return `${newLine}\n`;
+    }
+    return `${trimmed}\n${newLine}\n`;
+}
+/** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
+export function persistQqCredentialsToEnv(endpointName, appId, appSecret, projectRoot) {
+    const keys = buildQqCredentialEnvKeys(endpointName);
+    const root = projectRoot ?? resolveProjectRoot();
+    const envPath = path.join(root, '.env');
+    let content = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf-8') : '';
+    const entries = {
+        [keys.appidKey]: appId,
+        [keys.secretKey]: appSecret,
+    };
+    for (const [key, value] of Object.entries(entries)) {
+        content = upsertEnvLine(content, key, value);
+        process.env[key] = value;
+    }
+    fs.writeFileSync(envPath, content);
+    return keys;
+}

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;