@zhin.js/adapter-qq 5.0.3 → 6.0.0

package/src/qq-bind-api.ts

@@ -0,0 +1,145 @@
+/**
+ * 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';
+
+export type QQBotEnv = 'production' | 'test';
+
+const HOSTS: Record<QQBotEnv, string> = {
+  production: 'q.qq.com',
+  test: 'test.q.qq.com',
+};
+
+export enum BindStatus {
+  NONE = 0,
+  PENDING = 1,
+  COMPLETED = 2,
+  EXPIRED = 3,
+}
+
+export function getQQBotHost(env: QQBotEnv = 'production'): string {
+  return HOSTS[env];
+}
+
+export function generateBindKey(): string {
+  return randomBytes(32).toString('base64');
+}
+
+export function buildConnectUrl(taskId: string, source = 'zhin'): string {
+  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: string, keyBase64: string): string {
+  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');
+}
+
+interface LiteApiResponse<T> {
+  retcode: number;
+  msg?: string;
+  data?: T;
+}
+
+async function postJson<T>(
+  url: string,
+  body: Record<string, unknown>,
+  timeoutMs: number,
+): Promise<LiteApiResponse<T>> {
+  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()) as LiteApiResponse<T>;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export interface BindTaskResult {
+  taskId: string;
+  key: string;
+}
+
+export async function createBindTask(
+  env: QQBotEnv = 'production',
+  timeoutMs = 10_000,
+): Promise<BindTaskResult> {
+  const url = `https://${getQQBotHost(env)}/lite/create_bind_task`;
+  const key = generateBindKey();
+  const res = await postJson<{ task_id?: string }>(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 interface PollBindResultOk {
+  status: BindStatus;
+  botAppId: string;
+  botEncryptSecret: string;
+  /** 扫码绑定开发者 QQ 的 OpenID（poll_bind_result 返回） */
+  userOpenId: string;
+}
+
+export function parsePollBindResultData(data: {
+  status?: number;
+  bot_appid?: string | number;
+  bot_encrypt_secret?: string;
+  user_openid?: string;
+  userOpenid?: string;
+  openid?: string;
+} | undefined): PollBindResultOk {
+  return {
+    status: (data?.status ?? BindStatus.NONE) as BindStatus,
+    botAppId: String(data?.bot_appid ?? ''),
+    botEncryptSecret: data?.bot_encrypt_secret ?? '',
+    userOpenId: String(
+      data?.user_openid ?? data?.userOpenid ?? data?.openid ?? '',
+    ),
+  };
+}
+
+export async function pollBindResult(
+  taskId: string,
+  env: QQBotEnv = 'production',
+  timeoutMs = 10_000,
+): Promise<PollBindResultOk> {
+  const url = `https://${getQQBotHost(env)}/lite/poll_bind_result`;
+  const res = await postJson<{
+    status?: number;
+    bot_appid?: string | number;
+    bot_encrypt_secret?: string;
+    user_openid?: string;
+    userOpenid?: string;
+    openid?: string;
+  }>(url, { task_id: taskId }, timeoutMs);
+  if (res.retcode !== 0) {
+    throw new Error(res.msg ?? 'poll_bind_result failed');
+  }
+  return parsePollBindResultData(res.data);
+}

package/src/qq-bind-flow.ts

@@ -0,0 +1,127 @@
+/**
+ * QQ Bot 扫码绑定流程（内联，等价 qqbot-connector startQrConnect）
+ */
+import {
+  BindStatus,
+  buildConnectUrl,
+  createBindTask,
+  decryptSecret,
+  pollBindResult,
+} from './qq-bind-api.js';
+
+const POLL_INTERVAL_MS = 2000;
+
+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;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  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: string,
+  key: string,
+  signal?: AbortSignal,
+): Promise<{ outcome: 'scanned'; appId: string; appSecret: string; userOpenId: string } | { outcome: 'expired' }> {
+  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: QqBindCallbacks,
+  options: QqBindFlowOptions = {},
+): () => void {
+  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/src/qq-bind-persist.ts

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface QqCredentialEnvKeys {
+  appidKey: string;
+  secretKey: string;
+  appidRef: string;
+  secretRef: string;
+}
+
+/** 按 endpoint 名称生成唯一 env 键（如 `QQ_MY_BOT_APPID`） */
+export function buildQqCredentialEnvKeys(endpointName: string): QqCredentialEnvKeys {
+  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(): string {
+  const envRoot = process.env.ZHIN_PROJECT_ROOT?.trim();
+  return path.resolve(envRoot || process.cwd());
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function upsertEnvLine(content: string, key: string, value: string): string {
+  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: string,
+  appId: string,
+  appSecret: string,
+  projectRoot?: string,
+): QqCredentialEnvKeys {
+  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: Record<string, string> = {
+    [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/src/qq-endpoint-commands.ts

@@ -0,0 +1,174 @@
+/**
+ * `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';
+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 function isQqEndpointOperator(config: unknown, input: unknown): boolean {
+  const cfg = (config ?? {}) as { master?: unknown; endpoints?: unknown };
+  const masters = new Set<string>();
+  const collect = (value: unknown) => {
+    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 as { master?: unknown } | null | undefined)?.master);
+    }
+  }
+  if (masters.size === 0) return true;
+  const sender = String((input as { sender?: unknown } | null | undefined)?.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: unknown): QqCommandReply {
+  const reply = (input as { $reply?: unknown } | null | undefined)?.$reply;
+  if (typeof reply === 'function') {
+    return (text) => (reply as (content: string) => Promise<unknown>).call(input, text);
+  }
+  return async () => undefined;
+}
+
+/** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
+export function runQqEndpointList(state: QqRuntimeState, projectRoot?: string): string {
+  const running = [...state.endpoints.values()];
+  const configured = listQqEndpointEntries(projectRoot);
+  const lines: string[] = [];
+  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: QqRuntimeState,
+  name: string | undefined,
+  reply: QqCommandReply,
+  projectRoot?: string,
+): Promise<string> {
+  if (state.bindFlow) {
+    return Promise.resolve('已有进行中的 QQ 机器人绑定，请先发送 qq endpoint cancel 取消后再试');
+  }
+  const endpointName = name?.trim() || undefined;
+  return new Promise<string>((resolve) => {
+    let firstReplied = false;
+    const settle = (text: string) => {
+      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: QqRuntimeState): string {
+  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: QqRuntimeState,
+  name: string,
+  projectRoot?: string,
+): string {
+  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/src/qq-endpoint-config.ts

@@ -0,0 +1,135 @@
+/**
+ * zhin.config.yml 中 plugins.qq.endpoints 的读写（Plugin Runtime 版）。
+ * 用 yaml Document 操作以保留现有注释；仅支持 .yml/.yaml，其它格式报错提示手动处理。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isMap, isSeq, parseDocument, type YAMLSeq } from 'yaml';
+import { resolveProjectRoot } from './qq-bind-persist.js';
+
+export interface QqEndpointConfigEntry {
+  name: string;
+  appid: string;
+  secret: string;
+  [key: string]: unknown;
+}
+
+const CONFIG_BASENAME = 'zhin.config';
+const YAML_EXTENSIONS = ['.yml', '.yaml'] as const;
+
+/** 定位项目配置文件：ZHIN_CONFIG 指定优先，否则发现 zhin.config.yml/.yaml，都没有则默认新建 zhin.config.yml */
+export function findQqConfigFile(projectRoot?: string): string {
+  const root = projectRoot ?? resolveProjectRoot();
+  const envConfig = process.env.ZHIN_CONFIG?.trim();
+  if (envConfig) return path.resolve(root, envConfig);
+  for (const ext of YAML_EXTENSIONS) {
+    const candidate = path.join(root, `${CONFIG_BASENAME}${ext}`);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  for (const ext of ['.json', '.toml', '.ts'] as const) {
+    const candidate = path.join(root, `${CONFIG_BASENAME}${ext}`);
+    if (fs.existsSync(candidate)) {
+      throw new Error(`暂不支持写入 ${ext} 配置文件，请手动在 ${CONFIG_BASENAME}${ext} 的 plugins.qq.endpoints 中维护`);
+    }
+  }
+  return path.join(root, `${CONFIG_BASENAME}.yml`);
+}
+
+interface QqConfigDocument {
+  filePath: string;
+  doc: ReturnType<typeof parseDocument>;
+}
+
+function readConfigDocument(projectRoot?: string): QqConfigDocument {
+  const filePath = findQqConfigFile(projectRoot);
+  const content = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : '';
+  const doc = parseDocument(content || '{}');
+  return { filePath, doc };
+}
+
+function writeConfigDocument({ filePath, doc }: QqConfigDocument): void {
+  fs.writeFileSync(filePath, doc.toString());
+}
+
+/** 读取 plugins.qq.endpoints（plain JS）；plugins/qq 缺失或形态不符时返回 [] */
+export function listQqEndpointEntries(projectRoot?: string): QqEndpointConfigEntry[] {
+  const { doc } = readConfigDocument(projectRoot);
+  const plugins = doc.toJS()?.plugins;
+  if (!plugins || typeof plugins !== 'object' || Array.isArray(plugins)) return [];
+  const endpoints = (plugins as { qq?: { endpoints?: unknown } }).qq?.endpoints;
+  if (!Array.isArray(endpoints)) return [];
+  return endpoints.filter(
+    (entry): entry is QqEndpointConfigEntry =>
+      !!entry && typeof entry === 'object' && typeof (entry as { name?: unknown }).name === 'string',
+  );
+}
+
+function entryName(item: unknown): string | undefined {
+  if (!isMap(item)) return undefined;
+  const name = item.get('name');
+  return typeof name === 'string' && name ? name : undefined;
+}
+
+/**
+ * 确保 plugins.qq.endpoints 存在并返回其 YAMLSeq（节点级操作，保留既有条目与注释）。
+ * `plugins: []`（legacy 空列表，Runtime 忽略）可直接替换为 map；非空数组拒绝写入。
+ */
+function ensureEndpointsSeq(doc: ReturnType<typeof parseDocument>): YAMLSeq {
+  const plugins = doc.get('plugins');
+  if (isSeq(plugins) && plugins.items.length > 0) {
+    throw new Error('配置的 plugins 是数组形态（legacy 插件名列表），请手动迁移为 map 后再试');
+  }
+  if (plugins !== undefined && !isMap(plugins) && !isSeq(plugins)) {
+    throw new Error('配置的 plugins 字段形态异常，请手动检查 zhin.config.yml');
+  }
+  if (!isMap(doc.get('plugins'))) {
+    // 注意：空对象 {} 不会被 doc.set 自动包装为 YAMLMap，必须显式 createNode
+    doc.set('plugins', doc.createNode({}));
+  }
+  const qq = doc.getIn(['plugins', 'qq']);
+  if (qq !== undefined && !isMap(qq)) {
+    throw new Error('配置的 plugins.qq 字段形态异常，请手动检查 zhin.config.yml');
+  }
+  if (!isMap(doc.getIn(['plugins', 'qq']))) {
+    doc.setIn(['plugins', 'qq'], doc.createNode({}));
+  }
+  const endpoints = doc.getIn(['plugins', 'qq', 'endpoints']);
+  if (endpoints !== undefined && !isSeq(endpoints)) {
+    throw new Error('配置的 plugins.qq.endpoints 字段形态异常，请手动检查 zhin.config.yml');
+  }
+  if (!isSeq(doc.getIn(['plugins', 'qq', 'endpoints']))) {
+    doc.setIn(['plugins', 'qq', 'endpoints'], doc.createNode([]));
+  }
+  return doc.getIn(['plugins', 'qq', 'endpoints']) as YAMLSeq;
+}
+
+/** 追加 endpoint 到 plugins.qq.endpoints；name 已存在时报错 */
+export function addQqEndpointToConfig(
+  entry: QqEndpointConfigEntry,
+  projectRoot?: string,
+): string {
+  const document = readConfigDocument(projectRoot);
+  const seq = ensureEndpointsSeq(document.doc);
+  if (seq.items.some((item) => entryName(item) === entry.name)) {
+    throw new Error(`配置中已存在 qq endpoint「${entry.name}」，可先 qq endpoint remove ${entry.name} 再重新添加`);
+  }
+  seq.items.push(document.doc.createNode(entry));
+  writeConfigDocument(document);
+  return document.filePath;
+}
+
+/** 按 name 移除 plugins.qq.endpoints 项；不存在返回 false */
+export function removeQqEndpointFromConfig(
+  name: string,
+  projectRoot?: string,
+): { removed: boolean; filePath: string } {
+  const document = readConfigDocument(projectRoot);
+  const seq = ensureEndpointsSeq(document.doc);
+  const next = seq.items.filter((item) => entryName(item) !== name);
+  if (next.length === seq.items.length) {
+    return { removed: false, filePath: document.filePath };
+  }
+  seq.items = next;
+  writeConfigDocument(document);
+  return { removed: true, filePath: document.filePath };
+}

package/src/qq-runtime-state.ts

@@ -0,0 +1,36 @@
+/**
+ * QQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表 +
+ * 扫码绑定流程的全局单例。由 plugin.ts setup() provide，
+ * adapter create 与 commands 通过 use(qqRuntimeStateToken) 共享（同一 owner generation）。
+ */
+import { createToken } from '@zhin.js/plugin-runtime';
+
+export interface QqRunningEndpoint {
+  name: string;
+  mode: string;
+}
+
+export interface QqBindFlowHandle {
+  /** 绑定期望的 endpoint 名（未指定时为 undefined，成功后取 appId） */
+  name?: string;
+  stop: () => void;
+}
+
+export interface QqRuntimeState {
+  /** 当前 generation 已成功创建的 endpoint（name → 描述） */
+  readonly endpoints: Map<string, QqRunningEndpoint>;
+  /** 全局单例：同一时间只允许一个扫码绑定流程 */
+  bindFlow: QqBindFlowHandle | null;
+}
+
+export function createQqRuntimeState(): QqRuntimeState {
+  return {
+    endpoints: new Map(),
+    bindFlow: null,
+  };
+}
+
+export const qqRuntimeStateToken = createToken<QqRuntimeState>(
+  'zhin.qq.runtime-state',
+  'QQ adapter runtime state (running endpoints + bind flow singleton)',
+);