@cxyhhhhh/openclaw-qqbot 2.0.0-dev.202607101541 → 2.0.0-dev.202607101939

package/openclaw.plugin.json

@@ -4,7 +4,7 @@
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
   "extensions": ["./preload.cjs"],
-  "skills": ["skills/qqbot-channel", "skills/qqbot-group", "skills/qqbot-remind", "skills/qqbot-upgrade"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-remind", "skills/qqbot-upgrade"],
   "contracts": {
     "tools": ["qqbot_platform_api", "qqbot_remind"]
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxyhhhhh/openclaw-qqbot",
-  "version": "2.0.0-dev.202607101541",
+  "version": "2.0.0-dev.202607101939",
   "description": "QQ Bot channel plugin for OpenClaw",
   "publishConfig": {
     "access": "public"

package/src/adapter/contract.ts

@@ -8,7 +8,7 @@
 import type { PluginRuntime } from 'openclaw/plugin-sdk';
 import { createPluginLogger } from '../utils/plugin-logger.js';
 
-const log = createPluginLogger({ prefix: '[contract]', forceConsole: true });
+const log = createPluginLogger({ prefix: '[contract]', forceConsole: false });
 
 interface ApiProbe {
   name: string;

package/src/adapter/resolve.ts

@@ -285,6 +285,44 @@ export function getAdapters(
   return _cachedAdapters;
 }
 
+/**
+ * 持久化配置（auth.login 场景，兼容高低版本）。
+ *
+ * 探测顺序：
+ *   1. config.mutateConfigFile  — 新版原子操作
+ *   2. config.writeConfigFile   — 旧版整体覆盖
+ *   3. writeConfigFile          — 更旧的顶层 API
+ */
+export async function persistAuthConfig(
+  runtime: Record<string, unknown>,
+  cfg: Record<string, unknown>,
+  afterWrite = 'restart',
+): Promise<void> {
+  const config: Record<string, unknown> | undefined = runtime.config as any;
+
+  if (typeof config?.mutateConfigFile === 'function') {
+    await (config.mutateConfigFile as Function)({
+      mutate: () => cfg,
+      afterWrite,
+    });
+    return;
+  }
+  if (typeof config?.writeConfigFile === 'function') {
+    await (config.writeConfigFile as Function)(cfg);
+    return;
+  }
+  if (typeof runtime.writeConfigFile === 'function') {
+    await (runtime.writeConfigFile as Function)(cfg);
+    return;
+  }
+
+  // 最后兜底：裸写文件
+  const { homedir } = await import('node:os');
+  const { join } = await import('node:path');
+  const { writeFileSync } = await import('node:fs');
+  writeFileSync(join(homedir(), '.openclaw', 'openclaw.json'), JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+}
+
 /**
  * 强制清除 adapter 缓存（仅测试用）
  */

package/src/channel.ts

@@ -29,6 +29,7 @@ import { sendText, getGateway } from './outbound/outbound-service.js';
 import { sendMedia } from './outbound/media-send.js';
 import type { PluginLogger } from './utils/plugin-logger.js';
 import { qqbotSetupWizard } from './setup/surface.js';
+import { qqbotLogin, startQrLogin, waitQrLogin } from './setup/login.js';
 import { normalizeTarget, isQQBotTarget } from './outbound/target.js';
 import { sanitizeQQBotText } from './outbound/sanitize.js';
 import { startAccountWithCredentialRecovery, logoutAndClearCredentials, stopAccountGracefully } from './gateway/lifecycle.js';
@@ -72,6 +73,7 @@ export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
     threads: false,
     blockStreaming: false,
   },
+  gatewayMethods: ['web.login.start', 'web.login.wait'],
   reload: { configPrefixes: ['channels.qqbot'] },
 
   // ── 群消息策略 ──
@@ -266,6 +268,19 @@ export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
       });
     },
     logoutAccount: (params) => logoutAndClearCredentials(params),
+    loginWithQrStart: async ({ accountId }: { accountId?: string }) => startQrLogin(accountId),
+    loginWithQrWait: async ({ accountId }: { accountId?: string }) => {
+      const result = await waitQrLogin(accountId);
+      return { connected: result.connected, message: result.message };
+    },
+  },
+
+  // ── 登录认证 ──
+  auth: {
+    login: qqbotLogin as any,
+    // 审批权限（从 approvalStubs 迁移）
+    authorizeActorAction: () => ({ authorized: true } as const),
+    getActionAvailabilityState: () => ({ kind: 'enabled' as const } as const),
   },
 
   // ── 状态 ──

package/src/features/approval-utils.ts

@@ -28,10 +28,6 @@ export const approvalStubs = {
     buildPendingPayload: () => null,
     buildResolvedPayload: () => null,
   },
-  auth: {
-    authorizeActorAction: () => ({ authorized: true }),
-    getActionAvailabilityState: () => ({ kind: 'enabled' as const }),
-  },
   approvals: {
     delivery: {
       hasConfiguredDmRoute: () => true,

package/src/openclaw-plugin-sdk.d.ts

@@ -691,7 +691,23 @@ declare module "openclaw/plugin-sdk/setup" {
   export interface ChannelSetupWizard {
     channel: string;
     status: ChannelSetupWizardStatus;
+    /** 解析配置时使用哪个账户 ID：无账户时默认 'default' */
+    resolveAccountIdForConfigure?: (params: {
+      cfg: unknown;
+      prompter: unknown;
+      options?: unknown;
+      accountOverride?: string;
+      shouldPromptAccountIds: boolean;
+      listAccountIds: (cfg: unknown) => string[];
+      defaultAccountId: string;
+    }) => string | Promise<string>;
+    resolveShouldPromptAccountIds?: (params: {
+      cfg: unknown;
+      options?: unknown;
+      shouldPromptAccountIds: boolean;
+    }) => boolean;
     credentials?: Array<{ id: string; label: string }>;
+    textInputs?: Array<{ id: string; label: string; placeholder?: string }>;
     onStatusChange?: (params: { cfg: unknown }) => void | Promise<void>;
     configure?: (params: { cfg: unknown; accountId: string; prompter: unknown; runtime: unknown }) => Promise<unknown>;
     finalize: (params: { cfg: unknown; accountId: string; prompter: unknown; runtime: unknown }) => Promise<unknown>;

package/src/outbound/media-send.ts

@@ -78,14 +78,51 @@ function resolveTempRoots(): string[] {
   return [...roots];
 }
 
-const ALLOWED_MEDIA_ROOTS = [
-  path.join(os.homedir(), '.openclaw', 'media'),
-  path.join(os.homedir(), '.openclaw', 'workspace'),
-  // 框架 outbound 目录（saveMediaBuffer 写入）
-  path.join(os.homedir(), '.openclaw', 'outbound'),
-  // TTS 语音临时目录（deliver-pipeline 已通过 isTtsPathSafe 预检）
-  ...resolveTempRoots(),
-];
+/**
+ * 构建动态白名单目录列表。
+ *
+ * 从 openclaw 核心已解析的 workspaceDir 反向推导配置目录，
+ * 同时保留已知配置目录名以向后兼容。
+ */
+function buildDynamicAllowedRoots(workspaceDir?: string): string[] {
+  const home = os.homedir();
+  const derivedBase = workspaceDir ? path.dirname(workspaceDir) : path.join(home, '.openclaw');
+  const roots: string[] = [];
+  const added = new Set<string>();
+
+  const addRoot = (p: string) => {
+    try {
+      const real = fs.existsSync(p) ? fs.realpathSync(p) : p;
+      if (!added.has(real)) {
+        added.add(real);
+        roots.push(real);
+      }
+    } catch { /* skip */ }
+  };
+
+  // 已知配置目录名（包括默认和开发模式）
+  const knownBases = [path.join(home, '.openclaw'), path.join(home, '.openclaw-dev')];
+
+  // 当前配置目录优先（从 workspaceDir 反推）
+  if (workspaceDir) {
+    addRoot(path.join(derivedBase, 'media'));
+    addRoot(path.join(derivedBase, 'workspace'));
+    addRoot(path.join(derivedBase, 'outbound'));
+    addRoot(workspaceDir);
+  }
+
+  // 所有已知配置目录（去重，确保向后兼容）
+  for (const base of knownBases) {
+    addRoot(path.join(base, 'media'));
+    addRoot(path.join(base, 'workspace'));
+    addRoot(path.join(base, 'outbound'));
+  }
+
+  // 临时目录
+  for (const t of resolveTempRoots()) addRoot(t);
+
+  return roots;
+}
 
 /** 入站 Base64 / Data URL 最大字节数（10MB） */
 const MAX_DATA_URL_BYTES = 10 * 1024 * 1024;
@@ -198,7 +235,9 @@ async function resolveMediaPath(source: string, log?: SendMediaParams['log'], wo
     return { ok: false, error: `Cannot resolve path: ${resolved}` };
   }
 
-  const allowed = isPathInAllowedRoots(real, ALLOWED_MEDIA_ROOTS);
+  // 动态白名单：静态根目录 + 当前 agent 工作区
+  const dynamicRoots = buildDynamicAllowedRoots(workspaceDir);
+  const allowed = isPathInAllowedRoots(real, dynamicRoots);
 
   if (!allowed) {
     log?.warn(`path blocked — not in allowed directory: ${real}`);

package/src/setup/account-key.ts

@@ -0,0 +1,41 @@
+/**
+ * 账户键解析 — setup / login 共用
+ *
+ * 统一确定扫码/绑定凭据应写入哪个账户键。
+ */
+
+import type { OpenClawConfig } from 'openclaw/plugin-sdk';
+import { listQQBotAccountIds, resolveQQBotAccount } from '../config.js';
+
+/**
+ * 解析凭据写入的目标账户键。
+ *
+ * @param cfg    当前配置
+ * @param appId  扫码或输入的 AppID
+ * @param resolvedId  用户显式指定的账户名（如 --account / setup wizard），可选
+ * @returns 账户键
+ *
+ * 优先级：
+ *   1. resolvedId 指定 → 直接使用
+ *   2. 已有同 appId 的账户 → 刷新凭据（复用该账户键）
+ *   3. 零账户 → 'default'（首次配置）
+ *   4. 已有其他账户 → appId（新增独立账户）
+ */
+export function resolveAccountKey(
+  cfg: OpenClawConfig,
+  appId: string,
+  resolvedId?: string | null,
+): string {
+  if (resolvedId) return resolvedId;
+
+  // 同 appId → 刷新
+  for (const id of listQQBotAccountIds(cfg)) {
+    if (resolveQQBotAccount(cfg, id).appId === appId) return id;
+  }
+
+  // 零账户 → default
+  if (listQQBotAccountIds(cfg).length === 0) return 'default';
+
+  // 新增账户
+  return appId;
+}

package/src/setup/finalize.ts

@@ -5,6 +5,7 @@ import type { OpenClawConfig } from 'openclaw/plugin-sdk';
 import { DEFAULT_ACCOUNT_ID, formatDocsLink } from '../adapter/setup.js';
 import { qrConnect } from '@tencent-connect/qqbot-connector';
 import { applyQQBotAccountConfig, resolveQQBotAccount } from '../config.js';
+import { resolveAccountKey } from './account-key.js';
 
 type Prompter = {
   select: (opts: { message: string; options: Array<{ value: string; label: string; hint?: string }> }) => Promise<string>;
@@ -22,7 +23,7 @@ function isConfigured(cfg: OpenClawConfig, accountId: string): boolean {
   return Boolean(account.appId && account.clientSecret);
 }
 
-async function linkViaQrCode(cfg: OpenClawConfig, accountId: string, prompter: Prompter, rt: Runtime): Promise<OpenClawConfig> {
+async function linkViaQrCode(cfg: OpenClawConfig, _accountId: string, prompter: Prompter, rt: Runtime): Promise<OpenClawConfig> {
   try {
     const accounts: Array<{ appId: string; appSecret: string; userOpenid?: string }> = await qrConnect({ source: 'openclaw' });
 
@@ -33,15 +34,13 @@ async function linkViaQrCode(cfg: OpenClawConfig, accountId: string, prompter: P
 
     let next = cfg;
     for (const { appId, appSecret, userOpenid } of accounts) {
-      next = applyQQBotAccountConfig(next, appId, { appId, clientSecret: appSecret });
-      next = applyAccountDefaults(next, appId, userOpenid);
+      // 同 appId 刷新；零账户 default；已有账户新增 appId
+      const key = resolveAccountKey(cfg, appId);
+      next = applyQQBotAccountConfig(next, key, { appId, clientSecret: appSecret });
+      next = applyAccountDefaults(next, key, userOpenid);
+      rt.log(`绑定成功！账户: ${key} (AppID: ${appId})`);
     }
 
-    if (accounts.length === 1) {
-      rt.log(`✔ QQ Bot 绑定成功！(AppID: ${accounts[0].appId})`);
-    } else {
-      rt.log(`✔ ${accounts.length} 个 QQ Bot 绑定成功！(AppID: ${accounts.map((a) => a.appId).join(', ')})`);
-    }
     return next;
   } catch (err) {
     rt.error(`QQ Bot 绑定失败: ${String(err)}`);
@@ -50,11 +49,13 @@ async function linkViaQrCode(cfg: OpenClawConfig, accountId: string, prompter: P
   }
 }
 
-async function linkViaManual(cfg: OpenClawConfig, prompter: Prompter): Promise<OpenClawConfig> {
-  const appId = await prompter.text({ message: '请输入 QQ Bot AppID', validate: (v) => v.trim() ? undefined : 'AppID 不能为空' });
+async function linkViaManual(cfg: OpenClawConfig, _accountId: string, prompter: Prompter): Promise<OpenClawConfig> {
+  const appIdInput = await prompter.text({ message: '请输入 QQ Bot AppID', validate: (v) => v.trim() ? undefined : 'AppID 不能为空' });
   const secret = await prompter.text({ message: '请输入 QQ Bot AppSecret', validate: (v) => v.trim() ? undefined : 'AppSecret 不能为空' });
-  let next = applyQQBotAccountConfig(cfg, appId.trim(), { appId: appId.trim(), clientSecret: secret.trim() });
-  next = applyAccountDefaults(next, appId.trim());
+  const appId = appIdInput.trim();
+  const key = resolveAccountKey(cfg, appId);
+  let next = applyQQBotAccountConfig(cfg, key, { appId, clientSecret: secret.trim() });
+  next = applyAccountDefaults(next, key);
   await prompter.note('✔ QQ Bot 配置完成！', 'QQ Bot');
   return next;
 }
@@ -81,7 +82,7 @@ export async function finalizeQQBotSetup(params: {
   if (mode === 'qr') {
     next = await linkViaQrCode(next, accountId, params.prompter, params.runtime);
   } else if (mode === 'manual') {
-    next = await linkViaManual(next, params.prompter);
+    next = await linkViaManual(next, accountId, params.prompter);
   } else if (!configured) {
     await params.prompter.note('您可以稍后运行以下命令重新配置：\n  openclaw channels add', 'QQ Bot');
   }
@@ -89,7 +90,7 @@ export async function finalizeQQBotSetup(params: {
   return { cfg: next };
 }
 
-function applyAccountDefaults(cfg: OpenClawConfig, accountId: string, userOpenid?: string): OpenClawConfig {
+export function applyAccountDefaults(cfg: OpenClawConfig, accountId: string, userOpenid?: string): OpenClawConfig {
   const next = { ...cfg, channels: { ...cfg.channels } };
   const qqbot = { ...(next.channels?.qqbot as Record<string, unknown> ?? {}) } as Record<string, unknown>;
 

package/src/setup/login.ts

@@ -0,0 +1,197 @@
+/**
+ * QQ Bot QR 登录 — 两阶段接口适配
+ *
+ * 使用 @tencent-connect/qqbot-connector 的 startQrConnect 回调 API，
+ * 将扫码绑定流程拆分为 start / wait 两个阶段，对接 ChannelPlugin 的
+ * gateway.loginWithQrStart / loginWithQrWait。
+ */
+import { startQrConnect, type QrConnectCredentials } from '@tencent-connect/qqbot-connector';
+
+// ── 类型 ──
+
+export interface QrLoginStartResult {
+  qrDataUrl?: string;
+  message: string;
+}
+
+export interface QrLoginWaitResult {
+  connected: boolean;
+  message: string;
+  credentials?: QrConnectCredentials[];
+}
+
+// ── 挂起的登录会话 ──
+
+interface PendingSession {
+  /** 等待扫码结果的 Promise（onSuccess resolve, onFailure reject） */
+  credentialsPromise: Promise<QrConnectCredentials[]>;
+  /** 取消当前流程 */
+  dispose: () => void;
+}
+
+const pendingSessions = new Map<string, PendingSession>();
+
+// ── 启动 QR 登录 ──
+
+export function startQrLogin(accountId?: string, source = 'openclaw'): Promise<QrLoginStartResult> {
+  const key = accountId ?? 'default';
+
+  // 清理旧会话
+  pendingSessions.get(key)?.dispose();
+  pendingSessions.delete(key);
+
+  return new Promise((resolve) => {
+    let credentialsResolve: (creds: QrConnectCredentials[]) => void;
+    let credentialsReject: (err: Error) => void;
+
+    // 凭据 Promise — 在 onSuccess/onFailure 中 settle
+    const credentialsPromise = new Promise<QrConnectCredentials[]>((res, rej) => {
+      credentialsResolve = res;
+      credentialsReject = rej;
+    });
+
+    const dispose = startQrConnect(
+      {
+        onQrDisplayed(url) {
+          resolve({
+            qrDataUrl: url,
+            message: '请使用手机 QQ 扫描二维码完成绑定',
+          });
+        },
+        onSuccess: (creds) => credentialsResolve!(creds),
+        onFailure: (err) => credentialsReject!(err),
+      },
+      { displayQrCodeToConsole: true, source },
+    );
+
+    pendingSessions.set(key, { dispose, credentialsPromise });
+  });
+}
+
+// ── 等待扫码结果 ──
+
+export async function waitQrLogin(accountId?: string): Promise<QrLoginWaitResult> {
+  const key = accountId ?? 'default';
+  const session = pendingSessions.get(key);
+
+  if (!session) {
+    return { connected: false, message: '没有正在进行的登录会话，请先运行 login 命令。' };
+  }
+
+  try {
+    const credentials = await session.credentialsPromise;
+    pendingSessions.delete(key);
+
+    if (credentials.length === 0) {
+      return { connected: false, message: '未获取到 QQ Bot 凭据。' };
+    }
+
+    return {
+      connected: true,
+      message: `绑定成功！AppID: ${credentials.map((c) => c.appId).join(', ')}`,
+      credentials,
+    };
+  } catch (err) {
+    pendingSessions.delete(key);
+    return {
+      connected: false,
+      message: `绑定失败: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+// ── 主动取消 ──
+
+export function cancelQrLogin(accountId?: string): void {
+  const key = accountId ?? 'default';
+  pendingSessions.get(key)?.dispose();
+  pendingSessions.delete(key);
+}
+
+// ── 解析 channelInput (appId:clientSecret) ──
+
+export function parseChannelInput(channelInput?: string | null): { appId: string; clientSecret: string } | null {
+  if (!channelInput) return null;
+  const parts = channelInput.trim().split(':');
+  if (parts.length === 2 && parts[0] && parts[1]) {
+    return { appId: parts[0], clientSecret: parts[1] };
+  }
+  return null;
+}
+
+// ── auth.login 入口 ──
+
+export interface QqbotLoginParams {
+  cfg: Record<string, unknown>;
+  accountId?: string | null;
+  channelInput?: string | null;
+  verbose?: boolean;
+  /** 框架注入的 runtime（含 config 持久化 API） */
+  [key: string]: unknown;
+}
+
+/**
+ * auth.login 完整实现。
+ *
+ * 账号策略：
+ *   --account <id>  → 写入指定账户
+ *   channelInput     → 用 appId 作为账户键
+ *   QR 扫码         → 用扫码返回的 appId 作为新账户键
+ */
+export async function qqbotLogin({
+  cfg,
+  accountId,
+  channelInput,
+  verbose,
+  ...rest
+}: QqbotLoginParams): Promise<void> {
+  // 延迟导入，避免循环依赖
+  const { applyQQBotAccountConfig } = await import('../config.js');
+  const { persistAuthConfig } = await import('../adapter/resolve.js');
+  const { applyAccountDefaults } = await import('./finalize.js');
+  const { resolveAccountKey } = await import('./account-key.js');
+
+  const runtime: Record<string, unknown> = rest as any;
+  const resolvedId = accountId ? accountId.trim().toLowerCase() : null;
+
+  // 如果传了 appId:clientSecret，直接写入配置
+  const parsed = parseChannelInput(channelInput);
+  if (parsed) {
+    const key = resolveAccountKey(cfg as any, parsed.appId, resolvedId);
+    const result = applyQQBotAccountConfig(cfg as any, key, {
+      appId: parsed.appId,
+      clientSecret: parsed.clientSecret,
+    });
+    Object.assign(cfg, result);
+    // 对齐 setup：写入默认 streaming/dmPolicy
+    const withDefaults = applyAccountDefaults(cfg as any, key);
+    Object.assign(cfg, withDefaults);
+    await persistAuthConfig(runtime, cfg, 'restart');
+    if (verbose) console.log(`QQ Bot 已配置 (${key}) AppID: ${parsed.appId}`);
+    return;
+  }
+
+  // QR 扫码登录
+  const { qrDataUrl, message } = await startQrLogin(resolvedId || 'pending');
+  console.log(`\n${message}`);
+  if (qrDataUrl) console.log(`QR 链接: ${qrDataUrl}`);
+
+  const result = await waitQrLogin(resolvedId || 'pending');
+  if (!result.connected || !result.credentials) {
+    throw new Error(result.message);
+  }
+
+  for (const cred of result.credentials) {
+    const key = resolveAccountKey(cfg as any, cred.appId, resolvedId);
+    const next = applyQQBotAccountConfig(cfg as any, key, {
+      appId: cred.appId,
+      clientSecret: cred.appSecret,
+    });
+    Object.assign(cfg, next);
+    // 对齐 setup：写入默认 streaming/dmPolicy，扫码用户加入白名单
+    const withDefaults = applyAccountDefaults(cfg as any, key, cred.userOpenid);
+    Object.assign(cfg, withDefaults);
+  }
+  await persistAuthConfig(runtime, cfg, 'restart');
+  console.log(`QQ Bot 登录成功！`);
+}

package/src/setup/surface.ts

@@ -3,7 +3,7 @@
  */
 import type { ChannelSetupWizard } from '../adapter/setup.js';
 import { createStandardChannelSetupStatus, setSetupChannelEnabled } from '../adapter/setup.js';
-import { listQQBotAccountIds, resolveQQBotAccount } from '../config.js';
+import { listQQBotAccountIds, resolveQQBotAccount, resolveDefaultQQBotAccountId } from '../config.js';
 import { finalizeQQBotSetup } from './finalize.js';
 
 const CHANNEL = 'qqbot' as const;
@@ -24,6 +24,14 @@ export const qqbotSetupWizard: ChannelSetupWizard = {
         return Boolean(account.appId && account.clientSecret);
       }),
   }),
+  // 未配置时默认使用 default 账号，有账户时框架会提示选择
+  resolveAccountIdForConfigure: async ({ cfg, shouldPromptAccountIds, accountOverride, defaultAccountId }) => {
+    if (accountOverride) return accountOverride;
+    const ids = listQQBotAccountIds(cfg as any);
+    if (ids.length === 0) return 'default';
+    if (!shouldPromptAccountIds) return ids[0];
+    return defaultAccountId || resolveDefaultQQBotAccountId(cfg as any);
+  },
   credentials: [],
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   finalize: (async ({ cfg, accountId, prompter, runtime }: any) =>

package/skills/qqbot-group/SKILL.md

@@ -1,75 +0,0 @@
----
-name: qqbot-group
-description: QQ 群管理技能。查询群基础信息、群成员信息、机器人群内状态。使用 qqbot_platform_api 工具调用接口，自动鉴权。当用户需要查询群信息、查看群成员、检查机器人群内状态时使用此技能。
-metadata: {"openclaw":{"emoji":"👥","requires":{"config":["channels.qqbot"]}}}
----
-
-# QQ 群 API 请求指导
-
-通过 `qqbot_platform_api` 工具调用群相关接口，鉴权由工具自动处理。
-
-详细字段说明见 `references/api_reference.md`。
-
----
-
-## ⭐ 接口速查
-
-| 操作 | 方法 | 路径 |
-|------|------|------|
-| 获取机器人群内状态 | `GET` | `/v2/groups/{group_id}/bot_state` |
-| 获取群成员信息 | `GET` | `/v2/groups/{group_id}/members/{member_id}` |
-| 获取群基础信息 | `GET` | `/v2/groups/{group_id}/info` |
-
----
-
-## 💡 调用示例
-
-### 获取机器人群内状态
-
-```json
-{
-  "method": "GET",
-  "path": "/v2/groups/G_123456789/bot_state"
-}
-```
-
-返回字段：`joined_at`（入群时间）、`allow_proactive_msg`（是否允许主动推送）、`recv_msg_setting`（`all`/`only_mention`/`mention_and_context`）、`member_role`（`member`/`owner`/`admin`）。
-
-### 获取群成员信息
-
-```json
-{
-  "method": "GET",
-  "path": "/v2/groups/G_123456789/members/o_xxxxxxxx"
-}
-```
-
-返回字段：`username`（昵称）、`member_role`、`joined_at`、`bot` 等。昵称仅在单个查询时返回。
-
-### 获取群基础信息
-
-```json
-{
-  "method": "GET",
-  "path": "/v2/groups/G_123456789/info"
-}
-```
-
-返回字段：`group_name`、`group_finger_memo`（简介）、`group_class_text`（分类）、`group_tags`（标签）、`group_member_num`（成员数）。
-
----
-
-## 💬 @群成员
-
-发送消息时使用 `<@member_id>` 语法 @指定群成员：
-
-- 格式：`<@member_id>`，例如 `<@o_xxxxxxxx>`
-- 文本消息中直接拼接即可：`你好 <@o_xxxxxxxx>，欢迎入群！`
-
----
-
-## ⚠️ 注意事项
-
-1. 路径占位符 `{group_id}`、`{member_id}` 需替换为实际值
-2. 返回时间格式为 RFC3339（如 `2026-06-23T22:03:09+08:00`）
-3. 群 openid 与频道 guild_id 是不同的概念，不要混淆