@zhin.js/adapter-qq 6.0.0 → 6.0.2

package/src/outbound.ts

@@ -0,0 +1,262 @@
+/**
+ * QQ 官方出站富媒体归一化：把渲染后的 payload 转为 qq-official-bot 可识别的
+ * Sendable 结构（文本串 + 消息段）。移植自 legacy 版 outbound-media /
+ * outbound-markdown / outbound-keyboard。
+ *
+ * 移植面：
+ * - image：http(s) URL 直发（data.url）；base64://、data:...;base64、本地路径
+ *   归一到 data.file，由 SDK formatMediaData 走媒体上传（v2 /files）。
+ * - markdown：data.content 原文，或 custom_template_id + params 模板。
+ * - keyboard：data.rows 按钮矩阵展开为 button 段（SDK processButtons 组装
+ *   keyboard 载荷）；按钮消息必须带 markdown，故同行文本合并为 markdown 段。
+ *   data.id 模板键盘原样透传。
+ * 不可映射的段一律降级为文本并 warn（保持既有 fallback 行为）。
+ */
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type { QqWireSegment } from './protocol.js';
+
+const logger = getLogger('qq');
+
+/** qq-official-bot Sendable 的最小结构子集（字符串模板或消息段）。 */
+export interface QqOutboundElem {
+  readonly type: string;
+  readonly data: Record<string, unknown>;
+}
+
+export type QqOutboundMessage = string | QqOutboundElem | readonly (string | QqOutboundElem)[];
+
+interface QqOutboundButtonSpec {
+  readonly id?: string;
+  readonly label?: string;
+  readonly payload?: string;
+  readonly disabled?: boolean;
+  readonly mode?: string;
+  readonly command?: { readonly enter?: boolean; readonly reply?: boolean };
+}
+
+function isRemoteUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+function isInlineBase64(value: string): boolean {
+  return value.startsWith('base64://') || /^data:[^/]+\/[^;]+;base64,/i.test(value);
+}
+
+/**
+ * 解析 image/audio/video/file 段的本地或内联 payload。
+ * qq-official-bot 的 formatMediaData 对 data.url 直接当远程 URL；
+ * base64:// / data:...;base64 / 本地路径须走 data.file 才会解析为 file_data。
+ */
+export function resolveMediaFile(data: Record<string, unknown>): string | undefined {
+  const url = typeof data.url === 'string' ? data.url : undefined;
+  const file = typeof data.file === 'string' ? data.file : undefined;
+  const base64 = typeof data.base64 === 'string' ? data.base64 : undefined;
+
+  if (file && !isRemoteUrl(file)) return file;
+  if (url && isInlineBase64(url)) return url;
+  if (url && !isRemoteUrl(url) && (url.startsWith('file://') || url.startsWith('/'))) return url;
+  if (base64) return base64.startsWith('base64://') ? base64 : `base64://${base64}`;
+  return undefined;
+}
+
+function normalizeMediaSegment(seg: QqWireSegment): QqOutboundElem | null {
+  const data = { ...(seg.data ?? {}) };
+  const file = resolveMediaFile(data);
+  if (file) {
+    delete data.url;
+    delete data.base64;
+    data.file = file;
+    return { type: seg.type, data };
+  }
+  const url = typeof data.url === 'string' ? data.url
+    : typeof data.file === 'string' ? data.file
+      : undefined;
+  if (url && isRemoteUrl(url)) {
+    delete data.base64;
+    return { type: seg.type, data: { ...data, url } };
+  }
+  // 既无远程 URL 也无本地上传源：无法投递，降级留痕
+  logger.warn(formatCompact({
+    op: 'qq_outbound_media_dropped',
+    type: seg.type,
+    reason: 'missing_source',
+  }));
+  return null;
+}
+
+function normalizeMarkdownSegment(seg: QqWireSegment): QqOutboundElem | null {
+  const data = seg.data ?? {};
+  const templateId = typeof data.custom_template_id === 'string' && data.custom_template_id
+    ? data.custom_template_id
+    : typeof data.template_id === 'string' && data.template_id
+      ? data.template_id
+      : undefined;
+  if (templateId) {
+    return {
+      type: 'markdown',
+      data: {
+        custom_template_id: templateId,
+        params: Array.isArray(data.params) ? data.params : [],
+      },
+    };
+  }
+  const content = String(data.content ?? data.text ?? '');
+  if (!content.trim()) {
+    logger.warn(formatCompact({ op: 'qq_outbound_markdown_dropped', reason: 'empty_content' }));
+    return null;
+  }
+  return { type: 'markdown', data: { content } };
+}
+
+function coreButtonToQq(btn: QqOutboundButtonSpec): Record<string, unknown> {
+  const isCommand = btn.mode === 'command';
+  const action: Record<string, unknown> = {
+    type: isCommand ? 2 : 1,
+    permission: { type: 2 },
+    data: btn.payload ?? '',
+    click_limit: btn.disabled ? 0 : 10,
+    unsupport_tips: btn.disabled ? '该按钮不可用' : '',
+  };
+  if (isCommand) {
+    if (btn.command?.enter != null) action.enter = btn.command.enter;
+    if (btn.command?.reply != null) action.reply = btn.command.reply;
+  }
+  return {
+    id: btn.id ?? '',
+    render_data: {
+      label: btn.label ?? '',
+      visited_label: btn.label ?? '',
+      style: 0,
+    },
+    action,
+  };
+}
+
+/** keyboard 段 → 模板键盘（data.id）或 button 行段（data.rows） */
+function expandKeyboardSegment(seg: QqWireSegment): QqOutboundElem[] {
+  const data = seg.data ?? {};
+  if (typeof data.id === 'string' && data.id) {
+    return [{ type: 'keyboard', data: { id: data.id } }];
+  }
+  if (!Array.isArray(data.rows)) {
+    logger.warn(formatCompact({ op: 'qq_outbound_keyboard_dropped', reason: 'missing_rows' }));
+    return [];
+  }
+  const out: QqOutboundElem[] = [];
+  for (const row of data.rows) {
+    if (!Array.isArray(row)) continue;
+    out.push({
+      type: 'button',
+      data: {
+        buttons: row.map((btn) => coreButtonToQq((btn ?? {}) as QqOutboundButtonSpec)),
+      },
+    });
+  }
+  return out;
+}
+
+function toSegmentList(payload: unknown): Array<string | QqWireSegment> {
+  if (Array.isArray(payload)) return payload as Array<string | QqWireSegment>;
+  if (payload && typeof payload === 'object' && 'type' in payload) {
+    return [payload as QqWireSegment];
+  }
+  return [];
+}
+
+function textFromUnknownSegment(seg: QqWireSegment): string {
+  const data = seg.data ?? {};
+  return data.text != null ? String(data.text) : '';
+}
+
+/**
+ * 渲染后 payload → QQ Sendable。
+ * 纯文本输入原样返回（与既有行为一致）；含富媒体段时返回段数组。
+ */
+export function formatOutbound(payload: unknown): QqOutboundMessage {
+  if (typeof payload === 'string') return payload;
+
+  const segments = toSegmentList(payload);
+  if (segments.length === 0) {
+    return payload == null
+      ? ''
+      : typeof payload === 'object'
+        ? JSON.stringify(payload)
+        : String(payload);
+  }
+
+  // QQ 按钮消息必须携带 markdown（msg_type=2），keyboard 存在时文本合并为 markdown 段
+  const hasKeyboard = segments.some(
+    (item) => typeof item !== 'string' && item.type === 'keyboard',
+  );
+
+  const parts: Array<string | QqOutboundElem> = [];
+  let textBuf = '';
+  const flushText = (): void => {
+    if (!textBuf) return;
+    parts.push(hasKeyboard
+      ? { type: 'markdown', data: { content: textBuf } }
+      : textBuf);
+    textBuf = '';
+  };
+
+  for (const item of segments) {
+    if (typeof item === 'string') {
+      textBuf += item;
+      continue;
+    }
+    const data = item.data ?? {};
+    switch (item.type) {
+      case 'text':
+        textBuf += String(data.text ?? data.content ?? '');
+        break;
+      case 'at': {
+        const id = String(data.user_id ?? data.qq ?? data.id ?? '');
+        if (!id) break;
+        flushText();
+        parts.push({ type: 'at', data: { user_id: id } });
+        break;
+      }
+      case 'image':
+      case 'audio':
+      case 'video':
+      case 'file': {
+        flushText();
+        const media = normalizeMediaSegment(item);
+        if (media) parts.push(media);
+        break;
+      }
+      case 'markdown': {
+        flushText();
+        const markdown = normalizeMarkdownSegment(item);
+        if (markdown) parts.push(markdown);
+        break;
+      }
+      case 'keyboard': {
+        flushText();
+        parts.push(...expandKeyboardSegment(item));
+        break;
+      }
+      case 'reply': {
+        const id = data.id ?? data.event_id;
+        if (id == null || id === '') break;
+        flushText();
+        parts.push({
+          type: 'reply',
+          data: data.event_id != null
+            ? { event_id: String(data.event_id) }
+            : { id: String(id) },
+        });
+        break;
+      }
+      default:
+        // 未识别段：保持既有文本降级
+        textBuf += textFromUnknownSegment(item);
+        break;
+    }
+  }
+  flushText();
+
+  if (parts.length === 0) return '';
+  if (parts.length === 1) return parts[0]!;
+  return parts;
+}

package/src/protocol.ts

@@ -4,6 +4,9 @@
  */
 
 import { pickCredential } from '@zhin.js/adapter';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('qq');
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface QqAdapterConfig {
@@ -193,8 +196,19 @@ export function formatOutboundText(payload: unknown): string {
           const id = String(data.user_id ?? data.qq ?? data.id ?? '');
           return id ? `<@!${id}>` : '';
         }
-        case 'image':
-          return String(data.url || data.file || '');
+        case 'image': {
+          const src = String(data.url || data.file || '');
+          // base64/本地路径由 formatOutbound 走媒体上传，文本视图静默省略；
+          // 仅当彻底缺少来源时留痕，避免出站静默降级排障无头绪。
+          if (!src) {
+            logger.warn(formatCompact({
+              op: 'qq_outbound_image_dropped',
+              reason: 'missing_source',
+            }));
+            return '';
+          }
+          return /^https?:\/\//.test(src) ? src : '';
+        }
         case 'reply':
           return '';
         default:

package/src/qq-bind-persist.ts

@@ -1,5 +1,10 @@
-import fs from 'node:fs';
-import path from 'node:path';
+import {
+  buildEndpointEnvKey,
+  persistEndpointEnvValues,
+  resolveProjectRoot,
+} from '@zhin.js/adapter';
+
+export { resolveProjectRoot };
 
 export interface QqCredentialEnvKeys {
   appidKey: string;
@@ -10,9 +15,8 @@ export interface QqCredentialEnvKeys {
 
 /** 按 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`;
+  const appidKey = buildEndpointEnvKey('qq', endpointName, 'appid');
+  const secretKey = buildEndpointEnvKey('qq', endpointName, 'secret');
   return {
     appidKey,
     secretKey,
@@ -21,29 +25,6 @@ export function buildQqCredentialEnvKeys(endpointName: string): QqCredentialEnvK
   };
 }
 
-/** 项目根：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,
@@ -52,20 +33,12 @@ export function persistQqCredentialsToEnv(
   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);
+  persistEndpointEnvValues(
+    {
+      [keys.appidKey]: appId,
+      [keys.secretKey]: appSecret,
+    },
+    projectRoot,
+  );
   return keys;
 }

package/src/qq-endpoint-commands.ts

@@ -1,16 +1,27 @@
 /**
  * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
+ * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
+ * @zhin.js/adapter 的 createEndpointCommands 套件；本文件保留 QQ 特化的
+ * 扫码绑定 add 流程（经套件 bindFlow 钩子接入）与 cancel，并导出
+ * qqEndpointCommands 供 commands/endpoint/ 下的命令文件默认导出。
  */
+import {
+  createEndpointCommands,
+  endpointCommandForbidden,
+  extractEndpointCommandReply,
+  formatEndpointList,
+  isEndpointOperator,
+  removeEndpointByName,
+  type ConfiguredEndpointEntry,
+  type EndpointCommandReply,
+} from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
 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';
+import { addQqEndpointToConfig, listQqEndpointEntries } from './qq-endpoint-config.js';
+import { qqRuntimeStateToken, type QqRuntimeState } from './qq-runtime-state.js';
 
-export type QqCommandReply = (text: string) => Promise<unknown>;
+export type QqCommandReply = EndpointCommandReply;
 
 /**
  * endpoint 管理命令的操作者校验：实例配置声明了 master（顶层或任一端点项）时
@@ -18,64 +29,33 @@ export type QqCommandReply = (text: string) => Promise<unknown>;
  * 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);
+  return isEndpointOperator(config, input);
 }
 
-export const QQ_ENDPOINT_FORBIDDEN = '仅 master 可执行 QQ endpoint 管理命令';
+export const QQ_ENDPOINT_FORBIDDEN = endpointCommandForbidden('QQ');
 
 /**
  * 从命令 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;
+  return extractEndpointCommandReply(input);
 }
 
 /** `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');
+  return formatEndpointList(qqEndpointListSpec, {
+    running: state.endpoints.values(),
+    configured: listQqEndpointEntries(projectRoot),
+    footer: state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消' : undefined,
+  });
 }
 
+const qqEndpointListSpec = {
+  adapterKey: 'qq',
+  adapterDisplayName: 'QQ',
+  describeEntry: (entry: ConfiguredEndpointEntry) => `appid: ${String(entry.appid)}`,
+} as const;
+
 /**
  * `qq endpoint add [name]`：启动扫码绑定流程。
  * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
@@ -157,18 +137,24 @@ export function runQqEndpointRemove(
   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)}`;
-  }
+  return removeEndpointByName(qqEndpointListSpec, name, projectRoot);
 }
+
+/**
+ * 通用套件生成的 QQ endpoint 命令（add 经 bindFlow 钩子走扫码绑定）。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项；cancel 为 QQ 特化，单独定义。
+ */
+export const qqEndpointCommands = createEndpointCommands({
+  ...qqEndpointListSpec,
+  fields: [
+    { key: 'appid', required: true, env: true, description: 'QQ 机器人 appid' },
+    { key: 'secret', required: true, env: true, description: 'QQ 机器人 secret' },
+  ],
+  running: (use) => use(qqRuntimeStateToken).endpoints.values(),
+  listFooter: (use) => {
+    const state = use(qqRuntimeStateToken);
+    return state.bindFlow ? '⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消' : undefined;
+  },
+  addDescription: '手机 QQ 扫码绑定机器人，凭据写入 .env 并追加到 zhin.config.yml（重启生效）',
+  bindFlow: ({ name, reply, use }) => runQqEndpointAdd(use(qqRuntimeStateToken), name, reply),
+}, defineCommand);

package/src/qq-endpoint-config.ts

@@ -1,11 +1,14 @@
 /**
  * zhin.config.yml 中 plugins.qq.endpoints 的读写（Plugin Runtime 版）。
- * 用 yaml Document 操作以保留现有注释；仅支持 .yml/.yaml，其它格式报错提示手动处理。
+ * 实现已泛化到 @zhin.js/adapter 的 endpoint-commands 套件（Document 节点级保留注释）；
+ * 本文件仅保留 QQ 专用签名以兼容既有调用与测试。
  */
-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';
+import {
+  addEndpointToConfig,
+  findEndpointConfigFile,
+  listConfiguredEndpoints,
+  removeEndpointFromConfig,
+} from '@zhin.js/adapter';
 
 export interface QqEndpointConfigEntry {
   name: string;
@@ -14,93 +17,14 @@ export interface QqEndpointConfigEntry {
   [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());
+  return findEndpointConfigFile('qq', projectRoot);
 }
 
 /** 读取 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;
+  return listConfiguredEndpoints('qq', projectRoot) as QqEndpointConfigEntry[];
 }
 
 /** 追加 endpoint 到 plugins.qq.endpoints；name 已存在时报错 */
@@ -108,14 +32,7 @@ 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;
+  return addEndpointToConfig('qq', entry, projectRoot);
 }
 
 /** 按 name 移除 plugins.qq.endpoints 项；不存在返回 false */
@@ -123,13 +40,5 @@ 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 };
+  return removeEndpointFromConfig('qq', name, projectRoot);
 }