@zhin.js/adapter-qq 5.0.3 → 6.0.0

package/lib/qq-endpoint-commands.js

@@ -0,0 +1,147 @@
+/**
+ * `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';
+/**
+ * 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);
+}
+export const QQ_ENDPOINT_FORBIDDEN = '仅 master 可执行 QQ endpoint 管理命令';
+/**
+ * 从命令 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;
+}
+/** `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');
+}
+/**
+ * `qq endpoint add [name]`：启动扫码绑定流程。
+ * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
+ * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
+ */
+export function runQqEndpointAdd(state, name, reply, projectRoot) {
+    if (state.bindFlow) {
+        return Promise.resolve('已有进行中的 QQ 机器人绑定，请先发送 qq endpoint cancel 取消后再试');
+    }
+    const endpointName = name?.trim() || undefined;
+    return new Promise((resolve) => {
+        let firstReplied = false;
+        const settle = (text) => {
+            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) {
+    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, 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)}`;
+    }
+}

package/lib/qq-endpoint-config.d.ts

@@ -0,0 +1,17 @@
+export interface QqEndpointConfigEntry {
+    name: string;
+    appid: string;
+    secret: string;
+    [key: string]: unknown;
+}
+/** 定位项目配置文件：ZHIN_CONFIG 指定优先，否则发现 zhin.config.yml/.yaml，都没有则默认新建 zhin.config.yml */
+export declare function findQqConfigFile(projectRoot?: string): string;
+/** 读取 plugins.qq.endpoints（plain JS）；plugins/qq 缺失或形态不符时返回 [] */
+export declare function listQqEndpointEntries(projectRoot?: string): QqEndpointConfigEntry[];
+/** 追加 endpoint 到 plugins.qq.endpoints；name 已存在时报错 */
+export declare function addQqEndpointToConfig(entry: QqEndpointConfigEntry, projectRoot?: string): string;
+/** 按 name 移除 plugins.qq.endpoints 项；不存在返回 false */
+export declare function removeQqEndpointFromConfig(name: string, projectRoot?: string): {
+    removed: boolean;
+    filePath: string;
+};

package/lib/qq-endpoint-config.js

@@ -0,0 +1,110 @@
+/**
+ * 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 } from 'yaml';
+import { resolveProjectRoot } from './qq-bind-persist.js';
+const CONFIG_BASENAME = 'zhin.config';
+const YAML_EXTENSIONS = ['.yml', '.yaml'];
+/** 定位项目配置文件：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());
+}
+/** 读取 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']);
+}
+/** 追加 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;
+}
+/** 按 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 };
+}

package/lib/qq-runtime-state.d.ts

@@ -0,0 +1,17 @@
+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 declare function createQqRuntimeState(): QqRuntimeState;
+export declare const qqRuntimeStateToken: import("@zhin.js/plugin-runtime").Token<QqRuntimeState>;

package/lib/qq-runtime-state.js

@@ -0,0 +1,13 @@
+/**
+ * QQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表 +
+ * 扫码绑定流程的全局单例。由 plugin.ts setup() provide，
+ * adapter create 与 commands 通过 use(qqRuntimeStateToken) 共享（同一 owner generation）。
+ */
+import { createToken } from '@zhin.js/plugin-runtime';
+export function createQqRuntimeState() {
+    return {
+        endpoints: new Map(),
+        bindFlow: null,
+    };
+}
+export const qqRuntimeStateToken = createToken('zhin.qq.runtime-state', 'QQ adapter runtime state (running endpoints + bind flow singleton)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "5.0.3",
+  "version": "6.0.0",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,19 +35,21 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.2.3",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
+    "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/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.0.1"
+    "@zhin.js/plugin-runtime": "1.1.0",
+    "@zhin.js/command": "1.0.2"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/agent": "1.0.4",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@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"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -65,12 +67,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.4",
-    "@zhin.js/host-http": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@zhin.js/agent": "1.0.5",
+    "@zhin.js/host-http": "1.0.2",
+    "zhin.js": "5.0.0"
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -96,6 +99,10 @@
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.ts

@@ -1,12 +1,15 @@
 import { definePlugin } from '@zhin.js/plugin-runtime';
 import { registerQqPlatformPermitChecker } from './src/platform-permit.js';
+import { createQqRuntimeState, qqRuntimeStateToken } from './src/qq-runtime-state.js';
 
 export default definePlugin({
   name: 'qq',
   metadata: {
     displayName: 'QQ Official WebSocket Adapter',
   },
-  setup() {
+  setup(context) {
+    // 运行中 endpoint 注册表 + 扫码绑定单例，供 adapter create 与 `qq endpoint` 命令共享
+    context.resources.provide(qqRuntimeStateToken, createQqRuntimeState());
     // 平台权限门禁：guild_owner / guild_admin / manage_roles / manage_channels（agent 工具 platformPermit）
     return registerQqPlatformPermitChecker();
   },

package/schema.json

@@ -3,19 +3,13 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "name": {
-      "type": "string",
-      "default": "qq-bot"
-    },
-    "appid": {
-      "type": "string"
-    },
-    "secret": {
-      "type": "string"
-    },
     "mode": {
       "type": "string",
-      "enum": ["websocket", "webhook", "middleware"],
+      "enum": [
+        "websocket",
+        "webhook",
+        "middleware"
+      ],
       "default": "websocket",
       "description": "WebSocket gateway (default). webhook/middleware use httpHostToken POST."
     },
@@ -23,9 +17,15 @@
       "type": "boolean",
       "default": false
     },
+    "master": {
+      "type": ["string", "number"],
+      "description": "Endpoint Owner（qq endpoint 管理命令权限、AI master 角色）；endpoints[i] 可逐项覆盖"
+    },
     "intents": {
       "type": "array",
-      "items": { "type": "string" }
+      "items": {
+        "type": "string"
+      }
     },
     "accessTokenUrl": {
       "type": "string"
@@ -45,7 +45,41 @@
     "path": {
       "type": "string",
       "description": "Legacy standalone webhook path (unused with httpHostToken)."
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "QQ bot name"
+          },
+          "appid": {
+            "type": "string",
+            "description": "QQ official bot app ID"
+          },
+          "secret": {
+            "type": "string",
+            "description": "QQ official bot secret"
+          }
+        },
+        "required": [
+          "name",
+          "appid",
+          "secret"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
     }
   },
-  "required": ["appid", "secret"]
+  "required": [
+    "endpoints"
+  ]
 }

package/src/endpoint.ts

@@ -1,7 +1,11 @@
 /**
  * QQ endpoints — lifecycle, outbound, admit, agent tool surface.
  */
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type {
+  EndpointChannel,
+  EndpointInstance,
+  EndpointManagement,
+} from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -51,12 +55,18 @@ export class QqWebsocketEndpoint implements EndpointInstance {
   #open = false;
   #started = false;
   #unregisterAgent?: () => void;
+  readonly management: EndpointManagement = createQqEndpointManagement(this);
 
   constructor(options: QqEndpointOptions) {
     this.#options = options;
     this.#createBot = options.createBot ?? defaultCreateBot;
   }
 
+  /** Live endpoint 名（Console/AdapterIndex 展示用，如 bot appid 别名）。 */
+  get name(): string {
+    return this.#options.config.name;
+  }
+
   async start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
@@ -227,12 +237,18 @@ export class QqHttpEndpoint implements EndpointInstance {
   #open = false;
   #started = false;
   #unregisterAgent?: () => void;
+  readonly management: EndpointManagement = createQqEndpointManagement(this);
 
   constructor(options: QqHttpEndpointOptions) {
     this.#options = options;
     this.#createBot = options.createBot ?? defaultCreateHttpBot;
   }
 
+  /** Live endpoint 名（Console/AdapterIndex 展示用）。 */
+  get name(): string {
+    return this.#options.config.name;
+  }
+
   async start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
@@ -387,3 +403,39 @@ export class QqHttpEndpoint implements EndpointInstance {
     return this.#bot;
   }
 }
+
+function createQqEndpointManagement(endpoint: {
+  getGuilds(): Promise<unknown[]>;
+  getChannels(guildId: string): Promise<unknown[]>;
+}): EndpointManagement {
+  return Object.freeze<EndpointManagement>({
+    async listChannels(): Promise<readonly EndpointChannel[]> {
+      const channels: EndpointChannel[] = [];
+      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: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+    ? value as Record<string, unknown>
+    : {};
+}