@gakr-gakr/qqbot 0.1.0

package/src/bridge/logger.ts

@@ -0,0 +1,31 @@
+/**
+ * Bridge-layer logger — holds the framework logger injected at gateway startup.
+ *
+ * Bridge modules (approval, tools, etc.) use this instead of `console.log` or
+ * engine's `debugLog` so that all logs flow through the AutoBot log system.
+ */
+
+interface BridgeLogger {
+  info: (msg: string) => void;
+  error: (msg: string) => void;
+  warn?: (msg: string) => void;
+  debug?: (msg: string) => void;
+}
+
+let loggerInstance: BridgeLogger | null = null;
+
+/** Register the framework logger. Called once in startGateway(). */
+export function setBridgeLogger(logger: BridgeLogger): void {
+  loggerInstance = logger;
+}
+
+/** Get the bridge logger. Falls back to console if not yet registered. */
+export function getBridgeLogger(): BridgeLogger {
+  return (
+    loggerInstance ?? {
+      info: (msg) => console.log(msg),
+      error: (msg) => console.error(msg),
+      debug: (msg) => console.log(msg),
+    }
+  );
+}

package/src/bridge/narrowing.ts

@@ -0,0 +1,31 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import type { PluginRuntime } from "autobot/plugin-sdk/core";
+import type { GatewayAccount } from "../engine/types.js";
+import type { ResolvedQQBotAccount } from "../types.js";
+
+/**
+ * Map resolved plugin account to the engine gateway account shape (single assertion on nested config).
+ */
+export function toGatewayAccount(account: ResolvedQQBotAccount): GatewayAccount {
+  return {
+    accountId: account.accountId,
+    appId: account.appId,
+    clientSecret: account.clientSecret,
+    markdownSupport: account.markdownSupport,
+    systemPrompt: account.systemPrompt,
+    config: account.config as GatewayAccount["config"],
+  };
+}
+
+/**
+ * Persist AutoBot config through the injected plugin runtime (typed entry point).
+ */
+export async function writeAutoBotConfigThroughRuntime(
+  runtime: PluginRuntime,
+  cfg: AutoBotConfig,
+): Promise<void> {
+  await runtime.config.replaceConfigFile({
+    nextConfig: cfg,
+    afterWrite: { mode: "auto" },
+  });
+}

package/src/bridge/plugin-version.ts

@@ -0,0 +1,102 @@
+/**
+ * QQBot plugin version resolver.
+ *
+ * Reads the version field from this plugin's own `package.json` by
+ * walking up the directory tree starting from `import.meta.url` of the
+ * caller until a `package.json` whose `name` field matches the plugin
+ * package id is located.
+ *
+ * Why not a hardcoded relative path?
+ *   - The source file can live at different depths depending on whether
+ *     we run from raw sources (`src/bridge/gateway.ts`) or a future
+ *     compiled output. Hardcoding `"../../package.json"` breaks as soon
+ *     as the source layout changes, which is what caused the previous
+ *     `vunknown` regression.
+ *   - A `name` guard prevents accidentally reading the parent
+ *     `autobot/package.json` (the framework root) when the plugin
+ *     lives inside the monorepo.
+ *
+ * The lookup is performed only once per process at startup, so the
+ * synchronous file I/O is negligible.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** `name` field in this plugin's `package.json`. */
+const QQBOT_PLUGIN_PKG_NAME = "@gakr-gakr/qqbot";
+
+/** Sentinel used when the version cannot be resolved. */
+export const QQBOT_PLUGIN_VERSION_UNKNOWN = "unknown";
+
+/**
+ * Resolve the QQBot plugin version from `package.json`.
+ *
+ * @param startUrl — pass `import.meta.url` from the call site so the
+ *   lookup begins at the caller's file regardless of where this helper
+ *   itself lives. Falls back to this module's own location when omitted.
+ */
+export function resolveQQBotPluginVersion(startUrl?: string): string {
+  const entryUrl = startUrl ?? import.meta.url;
+  let dir: string;
+  try {
+    dir = path.dirname(fileURLToPath(entryUrl));
+  } catch {
+    return QQBOT_PLUGIN_VERSION_UNKNOWN;
+  }
+
+  const root = path.parse(dir).root;
+  while (dir && dir !== root) {
+    const candidate = path.join(dir, "package.json");
+    if (fs.existsSync(candidate)) {
+      const version = readQQBotVersionFromManifest(candidate);
+      if (version) {
+        return version;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+
+  return QQBOT_PLUGIN_VERSION_UNKNOWN;
+}
+
+/**
+ * Read the `version` field from a `package.json` file and return it
+ * only when the manifest describes the QQBot plugin itself.
+ *
+ * Returning `null` for mismatched or malformed manifests lets the
+ * caller keep walking up the directory tree until the correct package
+ * boundary is located.
+ */
+function readQQBotVersionFromManifest(manifestPath: string): string | null {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(manifestPath, "utf8");
+  } catch {
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== "object") {
+    return null;
+  }
+  const manifest = parsed as { name?: unknown; version?: unknown };
+  if (manifest.name !== QQBOT_PLUGIN_PKG_NAME) {
+    return null;
+  }
+  if (typeof manifest.version !== "string" || manifest.version.length === 0) {
+    return null;
+  }
+  return manifest.version;
+}

package/src/bridge/runtime.ts

@@ -0,0 +1,25 @@
+import type { PluginRuntime } from "autobot/plugin-sdk/core";
+import { createPluginRuntimeStore } from "autobot/plugin-sdk/runtime-store";
+import type { GatewayPluginRuntime } from "../engine/gateway/types.js";
+import { setAutoBotVersion } from "../engine/messaging/sender.js";
+
+// Single plugin runtime per process — concurrent multi-tenant qqbot runtimes are not supported.
+const { setRuntime: _setRuntime, getRuntime: getQQBotRuntime } =
+  createPluginRuntimeStore<PluginRuntime>({
+    pluginId: "qqbot",
+    errorMessage: "QQBot runtime not initialized",
+  });
+
+/** Set the QQBot runtime and inject the framework version into the User-Agent. */
+function setQQBotRuntime(runtime: PluginRuntime): void {
+  _setRuntime(runtime);
+  // Inject the framework version into the User-Agent string (same as standalone).
+  setAutoBotVersion(runtime.version);
+}
+
+export { getQQBotRuntime, setQQBotRuntime };
+
+/** Type-narrowed getter for engine/ modules that need GatewayPluginRuntime. */
+export function getQQBotRuntimeForEngine(): GatewayPluginRuntime {
+  return getQQBotRuntime() as GatewayPluginRuntime;
+}

package/src/bridge/sdk-adapter.ts

@@ -0,0 +1,164 @@
+import {
+  createChannelIngressResolver,
+  defineStableChannelIngressIdentity,
+} from "autobot/plugin-sdk/channel-ingress-runtime";
+import { resolveInboundMentionDecision } from "autobot/plugin-sdk/channel-mention-gating";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import {
+  createChannelHistoryWindow,
+  type HistoryEntry as SdkHistoryEntry,
+} from "autobot/plugin-sdk/reply-history";
+import { resolveQQBotEffectivePolicies } from "../engine/access/resolve-policy.js";
+import { normalizeQQBotAllowFrom, normalizeQQBotSenderId } from "../engine/access/sender-match.js";
+import type { HistoryPort, HistoryEntryLike } from "../engine/adapter/history.port.js";
+import type { AccessPort } from "../engine/adapter/index.js";
+import type { MentionGatePort } from "../engine/adapter/mention-gate.port.js";
+
+const qqbotIngressIdentity = defineStableChannelIngressIdentity({
+  key: "sender-id",
+  normalize: normalizeQQBotSenderId,
+  isWildcardEntry: (entry) => normalizeQQBotSenderId(entry) === "*",
+});
+
+function asSdkMap<T>(map: Map<string, T[]>): Map<string, SdkHistoryEntry[]> {
+  return map as unknown as Map<string, SdkHistoryEntry[]>;
+}
+
+export function createSdkHistoryAdapter(): HistoryPort {
+  return {
+    recordPendingHistoryEntry<T extends HistoryEntryLike>(params: {
+      historyMap: Map<string, T[]>;
+      historyKey: string;
+      entry?: T | null;
+      limit: number;
+    }) {
+      return createChannelHistoryWindow({ historyMap: asSdkMap(params.historyMap) }).record({
+        historyKey: params.historyKey,
+        entry: params.entry as SdkHistoryEntry | undefined,
+        limit: params.limit,
+      }) as T[];
+    },
+
+    buildPendingHistoryContext(params) {
+      return createChannelHistoryWindow({
+        historyMap: asSdkMap(params.historyMap),
+      }).buildPendingContext({
+        historyKey: params.historyKey,
+        limit: params.limit,
+        currentMessage: params.currentMessage,
+        formatEntry: params.formatEntry as (entry: SdkHistoryEntry) => string,
+        lineBreak: params.lineBreak,
+      });
+    },
+
+    clearPendingHistory(params) {
+      createChannelHistoryWindow({ historyMap: asSdkMap(params.historyMap) }).clear({
+        historyKey: params.historyKey,
+        limit: params.limit,
+      });
+    },
+  };
+}
+
+export function createSdkMentionGateAdapter(): MentionGatePort {
+  return {
+    resolveInboundMentionDecision(params) {
+      return resolveInboundMentionDecision(params);
+    },
+  };
+}
+
+export function createSdkAccessAdapter(): AccessPort {
+  return {
+    async resolveInboundAccess(input) {
+      const { dmPolicy, groupPolicy } = resolveQQBotEffectivePolicies(input);
+      const rawGroupAllowFrom =
+        input.groupAllowFrom && input.groupAllowFrom.length > 0
+          ? input.groupAllowFrom
+          : (input.allowFrom ?? []);
+      const normalizedAllowFrom = normalizeQQBotAllowFrom(input.allowFrom);
+      const dmAllowFromForIngress =
+        dmPolicy === "open" && normalizedAllowFrom.length === 0 ? ["*"] : (input.allowFrom ?? []);
+
+      const commandOwnerAllowFrom = input.isGroup
+        ? []
+        : input.allowFrom && input.allowFrom.length > 0
+          ? input.allowFrom
+          : ["*"];
+      const resolved = await createChannelIngressResolver({
+        channelId: "qqbot",
+        accountId: input.accountId,
+        identity: qqbotIngressIdentity,
+        cfg: input.cfg as AutoBotConfig,
+      }).message({
+        subject: { stableId: input.senderId },
+        conversation: {
+          kind: input.isGroup ? "group" : "direct",
+          id: input.conversationId,
+        },
+        event: {
+          mayPair: false,
+        },
+        dmPolicy,
+        groupPolicy,
+        policy: {
+          groupAllowFromFallbackToAllowFrom: false,
+        },
+        allowFrom: dmAllowFromForIngress,
+        groupAllowFrom: rawGroupAllowFrom,
+        command: {
+          commandOwnerAllowFrom,
+        },
+      });
+      return resolved;
+    },
+    async resolveSlashCommandAuthorization(input) {
+      return await resolveQQBotSlashCommandAuthorized(input);
+    },
+  };
+}
+
+async function resolveQQBotSlashCommandAuthorized(params: {
+  cfg: unknown;
+  accountId: string;
+  isGroup: boolean;
+  senderId: string;
+  conversationId: string;
+  allowFrom?: Array<string | number> | null;
+  groupAllowFrom?: Array<string | number> | null;
+  commandsAllowFrom?: Array<string | number> | null;
+}): Promise<boolean> {
+  const rawAllowFrom =
+    params.commandsAllowFrom ??
+    (params.isGroup && params.groupAllowFrom && params.groupAllowFrom.length > 0
+      ? params.groupAllowFrom
+      : params.allowFrom);
+  const explicitAllowFrom = normalizeQQBotAllowFrom(rawAllowFrom).filter((entry) => entry !== "*");
+  if (explicitAllowFrom.length === 0) {
+    return false;
+  }
+  const resolved = await createChannelIngressResolver({
+    channelId: "qqbot",
+    accountId: params.accountId,
+    identity: qqbotIngressIdentity,
+    cfg: params.cfg as AutoBotConfig,
+  }).message({
+    subject: { stableId: params.senderId },
+    conversation: {
+      kind: params.isGroup ? "group" : "direct",
+      id: params.conversationId,
+    },
+    event: {
+      kind: "slash-command",
+      authMode: "none",
+      mayPair: false,
+    },
+    dmPolicy: "allowlist",
+    groupPolicy: "open",
+    allowFrom: explicitAllowFrom,
+    command: {
+      modeWhenAccessGroupsOff: "configured",
+    },
+  });
+  return resolved.commandAccess.authorized;
+}

package/src/bridge/setup/finalize.ts

@@ -0,0 +1,144 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import type { ChannelSetupWizard } from "autobot/plugin-sdk/setup";
+import { DEFAULT_ACCOUNT_ID } from "autobot/plugin-sdk/setup";
+import { formatDocsLink } from "autobot/plugin-sdk/setup-tools";
+import { applyQQBotAccountConfig, resolveQQBotAccount } from "../config.js";
+
+type SetupPrompter = Parameters<NonNullable<ChannelSetupWizard["finalize"]>>[0]["prompter"];
+type SetupRuntime = Parameters<NonNullable<ChannelSetupWizard["finalize"]>>[0]["runtime"];
+
+function isQQBotAccountConfigured(cfg: AutoBotConfig, accountId: string): boolean {
+  const account = resolveQQBotAccount(cfg, accountId, { allowUnresolvedSecretRef: true });
+  return Boolean(account.appId && account.clientSecret);
+}
+
+async function linkViaQrCode(params: {
+  cfg: AutoBotConfig;
+  accountId: string;
+  prompter: SetupPrompter;
+  runtime: SetupRuntime;
+}): Promise<AutoBotConfig> {
+  try {
+    const { qrConnect } = await import("@tencent-connect/qqbot-connector");
+
+    const accounts: { appId: string; appSecret: string }[] = await qrConnect({
+      source: "autobot",
+    });
+
+    if (accounts.length === 0) {
+      await params.prompter.note("未获取到任何 QQ Bot 账号信息。", "QQ Bot");
+      return params.cfg;
+    }
+
+    let next = params.cfg;
+
+    for (let i = 0; i < accounts.length; i++) {
+      const { appId, appSecret } = accounts[i];
+      // use current account id for first account, and use app id for subsequent accounts
+      const targetAccountId = i === 0 ? params.accountId : appId;
+
+      next = applyQQBotAccountConfig(next, targetAccountId, {
+        appId,
+        clientSecret: appSecret,
+      });
+    }
+
+    if (accounts.length === 1) {
+      params.runtime.log(`✔ QQ Bot 绑定成功！(AppID: ${accounts[0].appId})`);
+    } else {
+      const idList = accounts.map((a) => a.appId).join(", ");
+      params.runtime.log(`✔ ${accounts.length} 个 QQ Bot 绑定成功！(AppID: ${idList})`);
+    }
+
+    return next;
+  } catch (error) {
+    params.runtime.error(`QQ Bot 绑定失败: ${String(error)}`);
+    await params.prompter.note(
+      [
+        "绑定失败，您可以稍后手动配置。",
+        `文档: ${formatDocsLink("/channels/qqbot", "qqbot")}`,
+      ].join("\n"),
+      "QQ Bot",
+    );
+    return params.cfg;
+  }
+}
+
+async function linkViaManualInput(params: {
+  cfg: AutoBotConfig;
+  accountId: string;
+  prompter: SetupPrompter;
+}): Promise<AutoBotConfig> {
+  const appId = await params.prompter.text({
+    message: "请输入 QQ Bot AppID",
+    validate: (value: string) => (value.trim() ? undefined : "AppID 不能为空"),
+  });
+
+  const appSecret = await params.prompter.text({
+    message: "请输入 QQ Bot AppSecret",
+    validate: (value: string) => (value.trim() ? undefined : "AppSecret 不能为空"),
+  });
+
+  const next = applyQQBotAccountConfig(params.cfg, params.accountId, {
+    appId: appId.trim(),
+    clientSecret: appSecret.trim(),
+  });
+
+  await params.prompter.note("✔ QQ Bot 配置完成！", "QQ Bot");
+  return next;
+}
+
+export async function finalizeQQBotSetup(params: {
+  cfg: AutoBotConfig;
+  accountId: string;
+  forceAllowFrom: boolean;
+  prompter: SetupPrompter;
+  runtime: SetupRuntime;
+}): Promise<{ cfg: AutoBotConfig }> {
+  const accountId = params.accountId.trim() || DEFAULT_ACCOUNT_ID;
+  let next = params.cfg;
+
+  const configured = isQQBotAccountConfigured(next, accountId);
+
+  const mode = await params.prompter.select({
+    message: configured ? "QQ 已绑定，选择操作" : "选择 QQ 绑定方式",
+    options: [
+      {
+        value: "qr",
+        label: "扫码绑定（推荐）",
+        hint: "使用 QQ 扫描二维码自动完成绑定",
+      },
+      {
+        value: "manual",
+        label: "手动输入 QQ Bot AppID 和 AppSecret",
+        hint: "需到 QQ 开放平台 q.qq.com 查看",
+      },
+      {
+        value: "skip",
+        label: configured ? "保持当前配置" : "稍后配置",
+      },
+    ],
+  });
+
+  if (mode === "qr") {
+    next = await linkViaQrCode({
+      cfg: next,
+      accountId,
+      prompter: params.prompter,
+      runtime: params.runtime,
+    });
+  } else if (mode === "manual") {
+    next = await linkViaManualInput({
+      cfg: next,
+      accountId,
+      prompter: params.prompter,
+    });
+  } else if (!configured) {
+    await params.prompter.note(
+      ["您可以稍后运行以下命令重新选择 QQ Bot 进行配置：", "  autobot channels add"].join("\n"),
+      "QQ Bot",
+    );
+  }
+
+  return { cfg: next };
+}

package/src/bridge/setup/surface.ts

@@ -0,0 +1,34 @@
+import {
+  createStandardChannelSetupStatus,
+  setSetupChannelEnabled,
+} from "autobot/plugin-sdk/setup";
+import type { ChannelSetupWizard } from "autobot/plugin-sdk/setup";
+import { isAccountConfigured } from "../../engine/config/resolve.js";
+import { listQQBotAccountIds, resolveQQBotAccount } from "../config.js";
+import { finalizeQQBotSetup } from "./finalize.js";
+
+const channel = "qqbot" as const;
+
+export const qqbotSetupWizard: ChannelSetupWizard = {
+  channel,
+  status: createStandardChannelSetupStatus({
+    channelLabel: "QQ Bot",
+    configuredLabel: "configured",
+    unconfiguredLabel: "needs AppID + AppSercet",
+    configuredHint: "configured",
+    unconfiguredHint: "needs AppID + AppSercet",
+    configuredScore: 1,
+    unconfiguredScore: 6,
+    resolveConfigured: ({ cfg, accountId }) =>
+      (accountId ? [accountId] : listQQBotAccountIds(cfg)).some((resolvedAccountId) => {
+        const account = resolveQQBotAccount(cfg, resolvedAccountId, {
+          allowUnresolvedSecretRef: true,
+        });
+        return isAccountConfigured(account as never);
+      }),
+  }),
+  credentials: [],
+  finalize: async ({ cfg, accountId, forceAllowFrom, prompter, runtime }) =>
+    await finalizeQQBotSetup({ cfg, accountId, forceAllowFrom, prompter, runtime }),
+  disable: (cfg) => setSetupChannelEnabled(cfg, channel, false),
+};

package/src/bridge/tools/channel.ts

@@ -0,0 +1,58 @@
+import type { AutoBotPluginApi } from "autobot/plugin-sdk/core";
+import { getAccessToken } from "../../engine/messaging/sender.js";
+import { ChannelApiSchema, executeChannelApi } from "../../engine/tools/channel-api.js";
+import type { ChannelApiParams } from "../../engine/tools/channel-api.js";
+import { listQQBotAccountIds, resolveQQBotAccount } from "../config.js";
+
+/**
+ * Register the QQ channel API proxy tool.
+ *
+ * The tool acts as an authenticated HTTP proxy for the QQ Open Platform
+ * channel APIs. Agents learn endpoint details from the skill docs and
+ * send requests through this proxy.
+ */
+export function registerChannelTool(api: AutoBotPluginApi): void {
+  const cfg = api.config;
+  if (!cfg) {
+    return;
+  }
+
+  const accountIds = listQQBotAccountIds(cfg);
+  if (accountIds.length === 0) {
+    return;
+  }
+
+  const firstAccountId = accountIds[0];
+  const account = resolveQQBotAccount(cfg, firstAccountId);
+
+  if (!account.appId || !account.clientSecret) {
+    return;
+  }
+
+  api.registerTool(
+    {
+      name: "qqbot_channel_api",
+      label: "QQBot Channel API",
+      description:
+        "Authenticated HTTP proxy for QQ Open Platform channel APIs. " +
+        "Common endpoints: " +
+        "list guilds GET /users/@me/guilds | " +
+        "list channels GET /guilds/{guild_id}/channels | " +
+        "get channel GET /channels/{channel_id} | " +
+        "create channel POST /guilds/{guild_id}/channels | " +
+        "list members GET /guilds/{guild_id}/members?after=0&limit=100 | " +
+        "get member GET /guilds/{guild_id}/members/{user_id} | " +
+        "list threads GET /channels/{channel_id}/threads | " +
+        "create thread PUT /channels/{channel_id}/threads | " +
+        "create announce POST /guilds/{guild_id}/announces | " +
+        "create schedule POST /channels/{channel_id}/schedules. " +
+        "See the qqbot-channel skill for full endpoint details.",
+      parameters: ChannelApiSchema,
+      async execute(_toolCallId, params) {
+        const accessToken = await getAccessToken(account.appId, account.clientSecret);
+        return executeChannelApi(params as ChannelApiParams, { accessToken });
+      },
+    },
+    { name: "qqbot_channel_api" },
+  );
+}

package/src/bridge/tools/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Aggregate QQBot plugin tool registrations.
+ *
+ * New tools should be added here rather than in the channel-entry contract
+ * file so that the plugin-level `index.ts` stays a pure declaration.
+ */
+
+import type { AutoBotPluginApi } from "autobot/plugin-sdk/core";
+import { registerChannelTool } from "./channel.js";
+import { registerRemindTool } from "./remind.js";
+
+export function registerQQBotTools(api: AutoBotPluginApi): void {
+  registerChannelTool(api);
+  registerRemindTool(api);
+}