@zhin.js/adapter-qq 6.0.0 → 6.0.1

package/lib/qq-endpoint-commands.js

@@ -1,74 +1,44 @@
 /**
  * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
+ * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
+ * @zhin.js/adapter 的 createEndpointCommands 套件；本文件保留 QQ 特化的
+ * 扫码绑定 add 流程（经套件 bindFlow 钩子接入）与 cancel，并导出
+ * qqEndpointCommands 供 commands/endpoint/ 下的命令文件默认导出。
  */
+import { createEndpointCommands, endpointCommandForbidden, extractEndpointCommandReply, formatEndpointList, isEndpointOperator, removeEndpointByName, } 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 { addQqEndpointToConfig, listQqEndpointEntries } from './qq-endpoint-config.js';
+import { qqRuntimeStateToken } from './qq-runtime-state.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);
+    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) {
-    const reply = input?.$reply;
-    if (typeof reply === 'function') {
-        return (text) => reply.call(input, text);
-    }
-    return async () => undefined;
+    return extractEndpointCommandReply(input);
 }
 /** `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');
+    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) => `appid: ${String(entry.appid)}`,
+};
 /**
  * `qq endpoint add [name]`：启动扫码绑定流程。
  * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
@@ -130,18 +100,23 @@ export function runQqEndpointCancel(state) {
 }
 /** `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)}`;
-    }
+    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/lib/qq-endpoint-config.js

@@ -1,110 +1,22 @@
 /**
  * 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 } from 'yaml';
-import { resolveProjectRoot } from './qq-bind-persist.js';
-const CONFIG_BASENAME = 'zhin.config';
-const YAML_EXTENSIONS = ['.yml', '.yaml'];
+import { addEndpointToConfig, findEndpointConfigFile, listConfiguredEndpoints, removeEndpointFromConfig, } from '@zhin.js/adapter';
 /** 定位项目配置文件：ZHIN_CONFIG 指定优先，否则发现 zhin.config.yml/.yaml，都没有则默认新建 zhin.config.yml */
 export function findQqConfigFile(projectRoot) {
-    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']) {
-        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`);
-}
-function readConfigDocument(projectRoot) {
-    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 }) {
-    fs.writeFileSync(filePath, doc.toString());
+    return findEndpointConfigFile('qq', projectRoot);
 }
 /** 读取 plugins.qq.endpoints（plain JS）；plugins/qq 缺失或形态不符时返回 [] */
 export function listQqEndpointEntries(projectRoot) {
-    const { doc } = readConfigDocument(projectRoot);
-    const plugins = doc.toJS()?.plugins;
-    if (!plugins || typeof plugins !== 'object' || Array.isArray(plugins))
-        return [];
-    const endpoints = plugins.qq?.endpoints;
-    if (!Array.isArray(endpoints))
-        return [];
-    return endpoints.filter((entry) => !!entry && typeof entry === 'object' && typeof entry.name === 'string');
-}
-function entryName(item) {
-    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) {
-    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']);
+    return listConfiguredEndpoints('qq', projectRoot);
 }
 /** 追加 endpoint 到 plugins.qq.endpoints；name 已存在时报错 */
 export function addQqEndpointToConfig(entry, projectRoot) {
-    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 */
 export function removeQqEndpointFromConfig(name, projectRoot) {
-    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);
 }

package/lib/webhook.js

@@ -21,20 +21,13 @@ export async function handleQqWebhookRequest(request, response, handler) {
         return;
     }
     try {
-        let parsedBody;
-        const raw = await readRequestBodyText(request);
-        if (raw) {
-            try {
-                parsedBody = JSON.parse(raw);
-            }
-            catch {
-                parsedBody = undefined;
-            }
-        }
+        // 不预消费请求流：库的验签必须基于原始字节（JSON.parse → JSON.stringify
+        // 会改变空白/转义/键序导致 401），body 留 undefined 让库自己读流；
+        // 预消费还会让非 JSON body 时库监听已结束的 end 事件而挂死。
         await bot.middleware({
             req: request,
             res: response,
-            request: { body: parsedBody },
+            request: { body: undefined },
         }, async () => undefined);
     }
     catch (error) {

package/lib/ws.d.ts

@@ -1,3 +1,4 @@
+import type { QqOutboundMessage } from './outbound.js';
 import type { QqInboundMessage, ResolvedQqWebsocketConfig } from './protocol.js';
 /** Minimal bot surface used by the endpoint (real qq-official-bot or test mock). */
 export interface QqBotTransport {
@@ -5,10 +6,10 @@ export interface QqBotTransport {
     stop(): Promise<void>;
     on(event: string, listener: (...args: unknown[]) => void): void;
     removeAllListeners(): void;
-    sendPrivateMessage(userId: string, message: string): Promise<unknown>;
-    sendGroupMessage(groupId: string, message: string): Promise<unknown>;
-    sendGuildMessage(channelId: string, message: string): Promise<unknown>;
-    sendDirectMessage?(guildId: string, message: string): Promise<unknown>;
+    sendPrivateMessage(userId: string, message: QqOutboundMessage): Promise<unknown>;
+    sendGroupMessage(groupId: string, message: QqOutboundMessage): Promise<unknown>;
+    sendGuildMessage(channelId: string, message: QqOutboundMessage): Promise<unknown>;
+    sendDirectMessage?(guildId: string, message: QqOutboundMessage): Promise<unknown>;
     getGuilds(): Promise<unknown[]>;
     getChannels(guildId: string): Promise<unknown[]>;
     getChannelInfo(channelId: string): Promise<unknown>;
@@ -19,6 +20,26 @@ export interface QqBotTransport {
     removeMemberRole(guildId: string, channelId: string, userId: string, roleId: string): Promise<boolean>;
 }
 export type CreateQqBot = (config: ResolvedQqWebsocketConfig) => QqBotTransport;
+interface QqOfficialBotLifecycle {
+    stop(): Promise<unknown>;
+    readonly sessionManager: {
+        userClose: boolean;
+        readonly connectionManager?: {
+            destroy(): void;
+        };
+        readonly authManager?: {
+            destroy(): void;
+        };
+    };
+}
+/**
+ * qq-official-bot 1.2.x keeps a second `userClose` flag in Connection.
+ * Session.stop() does not update it, so a normal shutdown is treated as an
+ * unexpected disconnect and starts a reconnect loop. Destroy both managers at
+ * the SDK boundary until upstream exposes a complete public shutdown method.
+ */
+export declare function stopQqOfficialBot(bot: QqOfficialBotLifecycle): Promise<void>;
 export declare function bindQqBotInboundEvents(bot: QqBotTransport, admitRaw: (raw: unknown) => void): void;
 export declare function normalizeQqMessage(raw: unknown): QqInboundMessage | null;
 export declare function defaultCreateBot(config: ResolvedQqWebsocketConfig): QqBotTransport;
+export {};

package/lib/ws.js

@@ -4,6 +4,23 @@
 import path from 'node:path';
 import { Bot, ReceiverMode } from 'qq-official-bot';
 import { getLevel, toLog4jsLevel } from '@zhin.js/logger';
+/**
+ * qq-official-bot 1.2.x keeps a second `userClose` flag in Connection.
+ * Session.stop() does not update it, so a normal shutdown is treated as an
+ * unexpected disconnect and starts a reconnect loop. Destroy both managers at
+ * the SDK boundary until upstream exposes a complete public shutdown method.
+ */
+export async function stopQqOfficialBot(bot) {
+    const session = bot.sessionManager;
+    session.userClose = true;
+    session.connectionManager?.destroy();
+    try {
+        await bot.stop();
+    }
+    finally {
+        session.authManager?.destroy();
+    }
+}
 export function bindQqBotInboundEvents(bot, admitRaw) {
     bot.on('message.group', admitRaw);
     bot.on('message.guild', admitRaw);
@@ -89,7 +106,7 @@ export function defaultCreateBot(config) {
     });
     return {
         start: () => bot.start().then(() => undefined),
-        stop: () => bot.stop().then(() => undefined),
+        stop: () => stopQqOfficialBot(bot),
         on: (event, listener) => {
             bot.on(event, listener);
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "6.0.0",
+  "version": "6.0.1",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,21 +35,20 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.2.3",
-    "yaml": "^2.9.0",
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/host-http": "1.0.2",
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/command": "1.0.3",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.0",
-    "@zhin.js/command": "1.0.2"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/agent": "1.0.5",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/plugin-runtime": "1.1.0",
-    "zhin.js": "5.0.0"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -67,9 +66,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.5",
-    "@zhin.js/host-http": "1.0.2",
-    "zhin.js": "5.0.0"
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/host-http": "1.0.3",
+    "zhin.js": "5.0.1"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -10,11 +10,11 @@ import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { formatOutbound } from './outbound.js';
 import { registerQqAgentEndpoint } from './qq-agent-deps.js';
 import {
   formatInboundContent,
   formatInboundTarget,
-  formatOutboundText,
   parseSendTarget,
   resolveOutboundMessageId,
   senderDisplayName,
@@ -84,7 +84,11 @@ export class QqWebsocketEndpoint implements EndpointInstance {
     } catch (error) {
       await this.stop();
       logger.error('Failed to connect QQ websocket:', error);
-      throw error;
+      const raw = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `QQ WebSocket 连接失败：请检查 appid/secret 是否配对、网关地址（gatewayUrl/accessTokenUrl）是否可达（原始错误：${raw}）`,
+        { cause: error },
+      );
     }
   }
 
@@ -114,7 +118,7 @@ export class QqWebsocketEndpoint implements EndpointInstance {
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
-    const body = formatOutboundText(payload);
+    const body = formatOutbound(payload);
     const parsed = parseSendTarget(target);
     const bot = this.#requireBot();
     let result: unknown;
@@ -301,7 +305,7 @@ export class QqHttpEndpoint implements EndpointInstance {
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
-    const body = formatOutboundText(payload);
+    const body = formatOutbound(payload);
     const parsed = parseSendTarget(target);
     const bot = this.#requireBot();
     let result: unknown;

package/src/index.ts

@@ -16,6 +16,13 @@ export {
   type ResolvedQqWebsocketConfig,
 } from './protocol.js';
 
+export {
+  formatOutbound,
+  resolveMediaFile,
+  type QqOutboundElem,
+  type QqOutboundMessage,
+} from './outbound.js';
+
 export {
   QqHttpEndpoint,
   QqWebsocketEndpoint,