@gakr-gakr/qqbot 0.1.0

package/src/engine/config/credentials.ts

@@ -0,0 +1,76 @@
+/**
+ * QQBot credential management (pure logic layer).
+ * QQBot 凭证管理（纯逻辑层）。
+ *
+ * Credential clearing and field-level cleanup for logout and setup
+ * flows. All functions operate on plain objects (Record<string, unknown>)
+ * and stay framework-agnostic.
+ */
+
+import { asOptionalObjectRecord as asRecord } from "../utils/string-normalize.js";
+import { DEFAULT_ACCOUNT_ID } from "./resolve.js";
+
+// ---- Logout: clear all credential fields for an account ----
+
+interface ClearCredentialsResult {
+  nextCfg: Record<string, unknown>;
+  cleared: boolean;
+  changed: boolean;
+}
+
+/**
+ * Remove clientSecret / clientSecretFile from a QQBot account config.
+ *
+ * Returns a shallow-cloned config with credentials removed, plus flags
+ * indicating whether anything actually changed.
+ */
+export function clearAccountCredentials(
+  cfg: Record<string, unknown>,
+  accountId: string,
+): ClearCredentialsResult {
+  const nextCfg = { ...cfg };
+  const channels = asRecord(cfg.channels);
+  const nextQQBot = channels?.qqbot ? { ...asRecord(channels.qqbot) } : undefined;
+  let cleared = false;
+  let changed = false;
+
+  if (nextQQBot) {
+    const qqbot = nextQQBot as Record<string, unknown>;
+    if (accountId === DEFAULT_ACCOUNT_ID) {
+      if (qqbot.clientSecret) {
+        delete qqbot.clientSecret;
+        cleared = true;
+        changed = true;
+      }
+      if (qqbot.clientSecretFile) {
+        delete qqbot.clientSecretFile;
+        cleared = true;
+        changed = true;
+      }
+    }
+    const accounts = qqbot.accounts as Record<string, Record<string, unknown>> | undefined;
+    if (accounts && accountId in accounts) {
+      const entry = accounts[accountId] as Record<string, unknown> | undefined;
+      if (entry && "clientSecret" in entry) {
+        delete entry.clientSecret;
+        cleared = true;
+        changed = true;
+      }
+      if (entry && "clientSecretFile" in entry) {
+        delete entry.clientSecretFile;
+        cleared = true;
+        changed = true;
+      }
+      if (entry && Object.keys(entry).length === 0) {
+        delete accounts[accountId];
+        changed = true;
+      }
+    }
+  }
+
+  if (changed && nextQQBot) {
+    nextCfg.channels = { ...channels, qqbot: nextQQBot };
+  }
+
+  return { nextCfg, cleared, changed };
+}

package/src/engine/config/group.ts

@@ -0,0 +1,227 @@
+import { asOptionalObjectRecord as asRecord } from "../utils/string-normalize.js";
+import { resolveAccountBase } from "./resolve.js";
+
+type GroupToolPolicy = "full" | "restricted" | "none";
+
+interface GroupConfig {
+  requireMention: boolean;
+  ignoreOtherMentions: boolean;
+  toolPolicy: GroupToolPolicy;
+  name: string;
+  prompt?: string;
+  historyLimit: number;
+}
+
+export const DEFAULT_GROUP_HISTORY_LIMIT = 50;
+
+export const DEFAULT_GROUP_PROMPT =
+  "If the sender is a bot, respond only when they explicitly @mention you to ask a question or request assistance with a specific task; keep your replies concise and clear, avoiding the urge to race other bots to answer or engage in lengthy, unproductive exchanges. In group chats, prioritize responding to messages from human users; bots should maintain a collaborative rather than competitive dynamic to ensure the conversation remains orderly and does not result in message flooding.";
+
+const DEFAULT_GROUP_CONFIG: Readonly<Omit<GroupConfig, "prompt">> = {
+  requireMention: true,
+  ignoreOtherMentions: false,
+  toolPolicy: "restricted",
+  name: "",
+  historyLimit: DEFAULT_GROUP_HISTORY_LIMIT,
+};
+
+function readGroupsMap(
+  cfg: Record<string, unknown>,
+  accountId?: string | null,
+): Record<string, Record<string, unknown>> {
+  const account = resolveAccountBase(cfg, accountId);
+  const groups = asRecord(account.config.groups);
+  if (!groups) {
+    return {};
+  }
+  const normalized: Record<string, Record<string, unknown>> = {};
+  for (const [key, value] of Object.entries(groups)) {
+    const sub = asRecord(value);
+    if (sub) {
+      normalized[key] = sub;
+    }
+  }
+  return normalized;
+}
+
+function readBoolean(obj: Record<string, unknown>, key: string): boolean | undefined {
+  const v = obj[key];
+  return typeof v === "boolean" ? v : undefined;
+}
+
+function readString(obj: Record<string, unknown>, key: string): string | undefined {
+  const v = obj[key];
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function readToolPolicy(obj: Record<string, unknown>, key: string): GroupToolPolicy | undefined {
+  const v = obj[key];
+  return v === "full" || v === "restricted" || v === "none" ? v : undefined;
+}
+
+function readHistoryLimit(obj: Record<string, unknown>, key: string): number | undefined {
+  const v = obj[key];
+  if (typeof v !== "number" || !Number.isFinite(v)) {
+    return undefined;
+  }
+  return Math.max(0, Math.floor(v));
+}
+
+export function resolveGroupConfig(
+  cfg: Record<string, unknown>,
+  groupOpenid?: string | null,
+  accountId?: string | null,
+): GroupConfig {
+  const groups = readGroupsMap(cfg, accountId);
+  const wildcard = groups["*"] ?? {};
+  const specific = groupOpenid ? (groups[groupOpenid] ?? {}) : {};
+
+  return {
+    requireMention:
+      readBoolean(specific, "requireMention") ??
+      readBoolean(wildcard, "requireMention") ??
+      DEFAULT_GROUP_CONFIG.requireMention,
+    ignoreOtherMentions:
+      readBoolean(specific, "ignoreOtherMentions") ??
+      readBoolean(wildcard, "ignoreOtherMentions") ??
+      DEFAULT_GROUP_CONFIG.ignoreOtherMentions,
+    toolPolicy:
+      readToolPolicy(specific, "toolPolicy") ??
+      readToolPolicy(wildcard, "toolPolicy") ??
+      DEFAULT_GROUP_CONFIG.toolPolicy,
+    name: readString(specific, "name") ?? readString(wildcard, "name") ?? DEFAULT_GROUP_CONFIG.name,
+    prompt: readString(specific, "prompt") ?? readString(wildcard, "prompt"),
+    historyLimit:
+      readHistoryLimit(specific, "historyLimit") ??
+      readHistoryLimit(wildcard, "historyLimit") ??
+      DEFAULT_GROUP_CONFIG.historyLimit,
+  };
+}
+
+export function resolveHistoryLimit(
+  cfg: Record<string, unknown>,
+  groupOpenid?: string | null,
+  accountId?: string | null,
+): number {
+  return resolveGroupConfig(cfg, groupOpenid, accountId).historyLimit;
+}
+
+export function resolveRequireMention(
+  cfg: Record<string, unknown>,
+  groupOpenid?: string | null,
+  accountId?: string | null,
+): boolean {
+  return resolveGroupConfig(cfg, groupOpenid, accountId).requireMention;
+}
+
+export function resolveIgnoreOtherMentions(
+  cfg: Record<string, unknown>,
+  groupOpenid?: string | null,
+  accountId?: string | null,
+): boolean {
+  return resolveGroupConfig(cfg, groupOpenid, accountId).ignoreOtherMentions;
+}
+
+/** Resolve tool policy for a given group. */
+export function resolveGroupToolPolicy(
+  cfg: Record<string, unknown>,
+  groupOpenid?: string | null,
+  accountId?: string | null,
+): GroupToolPolicy {
+  return resolveGroupConfig(cfg, groupOpenid, accountId).toolPolicy;
+}
+
+/**
+ * Resolve the behaviour prompt (PE) for a group. Falls back to the built-in
+ * default when neither specific nor wildcard configuration provides one.
+ */
+export function resolveGroupPrompt(
+  cfg: Record<string, unknown>,
+  groupOpenid?: string | null,
+  accountId?: string | null,
+): string {
+  return resolveGroupConfig(cfg, groupOpenid, accountId).prompt ?? DEFAULT_GROUP_PROMPT;
+}
+
+/**
+ * Resolve the display name for a group.
+ *
+ * When no name is configured, the first 8 characters of the openid are used
+ * as a short identifier so log lines stay compact.
+ */
+export function resolveGroupName(
+  cfg: Record<string, unknown>,
+  groupOpenid: string,
+  accountId?: string | null,
+): string {
+  const name = resolveGroupConfig(cfg, groupOpenid, accountId).name;
+  return name || groupOpenid.slice(0, 8);
+}
+
+// ============ GroupSettings (aggregate) ============
+
+/**
+ * Per-inbound aggregate of everything the pipeline needs about a group.
+ *
+ * Built once at the top of the group-gate stage so downstream consumers
+ * don't repeatedly re-parse the same `cfg` tree. Superset of
+ * {@link GroupConfig}: also includes the effective `mentionPatterns`
+ * (which depend on `agentId`, not on the group itself) and a
+ * pre-computed display name for logging.
+ */
+interface GroupSettings {
+  /** Merged group config (specific > wildcard > defaults). */
+  config: GroupConfig;
+  /** Display name — `config.name` or the first 8 chars of the openid. */
+  name: string;
+  /** Raw mentionPatterns (agent > global > []). */
+  mentionPatterns: string[];
+}
+
+export function resolveGroupSettings(params: {
+  cfg: Record<string, unknown>;
+  groupOpenid: string;
+  accountId?: string | null;
+  agentId?: string | null;
+}): GroupSettings {
+  const config = resolveGroupConfig(params.cfg, params.groupOpenid, params.accountId);
+  const name = config.name || params.groupOpenid.slice(0, 8);
+  const mentionPatterns = resolveMentionPatterns(params.cfg, params.agentId);
+  return { config, name, mentionPatterns };
+}
+
+interface AgentEntry {
+  id?: unknown;
+  groupChat?: { mentionPatterns?: unknown };
+}
+
+export function resolveMentionPatterns(
+  cfg: Record<string, unknown>,
+  agentId?: string | null,
+): string[] {
+  if (agentId) {
+    const agents = asRecord(cfg.agents);
+    const list = Array.isArray(agents?.list) ? (agents?.list as AgentEntry[]) : [];
+    const entry = list.find(
+      (a) => typeof a.id === "string" && a.id.trim().toLowerCase() === agentId.trim().toLowerCase(),
+    );
+    const agentGroupChat = entry?.groupChat;
+    if (agentGroupChat && Object.hasOwn(agentGroupChat, "mentionPatterns")) {
+      const patterns = agentGroupChat.mentionPatterns;
+      return Array.isArray(patterns)
+        ? patterns.filter((p): p is string => typeof p === "string")
+        : [];
+    }
+  }
+
+  const messages = asRecord(cfg.messages);
+  const globalGroupChat = asRecord(messages?.groupChat);
+  if (globalGroupChat && Object.hasOwn(globalGroupChat, "mentionPatterns")) {
+    const patterns = globalGroupChat.mentionPatterns;
+    return Array.isArray(patterns)
+      ? patterns.filter((p): p is string => typeof p === "string")
+      : [];
+  }
+
+  return [];
+}

package/src/engine/config/resolve.ts

@@ -0,0 +1,283 @@
+/**
+ * QQBot config resolution (pure logic layer).
+ * QQBot 配置解析（纯逻辑层）。
+ *
+ * Resolves account IDs, default account selection, and base account
+ * info from raw config objects. Secret/credential resolution is
+ * intentionally left to the outer layer (src/bridge/config.ts) so that
+ * this module stays framework-agnostic and self-contained.
+ */
+
+import { getPlatformAdapter } from "../adapter/index.js";
+import {
+  asOptionalObjectRecord as asRecord,
+  normalizeOptionalLowercaseString,
+  normalizeStringifiedOptionalString,
+  readStringField as readString,
+} from "../utils/string-normalize.js";
+
+/**
+ * Default account ID, used for the unnamed top-level account.
+ * 默认账号 ID，用于顶层配置中未命名的账号。
+ */
+export const DEFAULT_ACCOUNT_ID = "default";
+
+/**
+ * Internal shape of the channels.qqbot config section.
+ * channels.qqbot 配置节的内部结构。
+ */
+interface QQBotChannelConfig {
+  appId?: unknown;
+  clientSecret?: unknown;
+  clientSecretFile?: string;
+  accounts?: Record<string, Record<string, unknown>>;
+  defaultAccount?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * Base account resolution result (without credentials).
+ * 账号基础解析结果（不含凭证信息）。
+ *
+ * The outer config.ts layer extends this with clientSecret / secretSource.
+ */
+interface ResolvedAccountBase {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  appId: string;
+  systemPrompt?: string;
+  markdownSupport: boolean;
+  config: Record<string, unknown>;
+}
+
+function normalizeAppId(raw: unknown): string {
+  if (typeof raw === "string") {
+    return raw.trim();
+  }
+  if (typeof raw === "number") {
+    return String(raw);
+  }
+  return "";
+}
+
+function normalizeAccountConfig(
+  account: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  if (!account) {
+    return {};
+  }
+  const audioPolicy = asRecord(account.audioFormatPolicy);
+  return {
+    ...account,
+    ...(audioPolicy ? { audioFormatPolicy: { ...audioPolicy } } : {}),
+  };
+}
+
+function readQQBotSection(cfg: Record<string, unknown>): QQBotChannelConfig | undefined {
+  const channels = asRecord(cfg.channels);
+  return asRecord(channels?.qqbot) as QQBotChannelConfig | undefined;
+}
+
+/**
+ * List all configured QQBot account IDs.
+ * 列出所有已配置的 QQBot 账号 ID。
+ */
+export function listAccountIds(cfg: Record<string, unknown>): string[] {
+  const ids = new Set<string>();
+  const qqbot = readQQBotSection(cfg);
+
+  if (qqbot?.appId || process.env.QQBOT_APP_ID) {
+    ids.add(DEFAULT_ACCOUNT_ID);
+  }
+
+  if (qqbot?.accounts) {
+    for (const accountId of Object.keys(qqbot.accounts)) {
+      if (qqbot.accounts[accountId]?.appId) {
+        ids.add(accountId);
+      }
+    }
+  }
+
+  return Array.from(ids);
+}
+
+/**
+ * Resolve the default QQBot account ID.
+ * 解析默认 QQBot 账号 ID（优先级：defaultAccount > 顶层 appId > 第一个命名账号）。
+ */
+export function resolveDefaultAccountId(cfg: Record<string, unknown>): string {
+  const qqbot = readQQBotSection(cfg);
+  const configuredDefaultAccountId = normalizeOptionalLowercaseString(qqbot?.defaultAccount);
+  if (
+    configuredDefaultAccountId &&
+    (configuredDefaultAccountId === DEFAULT_ACCOUNT_ID ||
+      Boolean(qqbot?.accounts?.[configuredDefaultAccountId]?.appId))
+  ) {
+    return configuredDefaultAccountId;
+  }
+  if (qqbot?.appId || process.env.QQBOT_APP_ID) {
+    return DEFAULT_ACCOUNT_ID;
+  }
+  if (qqbot?.accounts) {
+    const ids = Object.keys(qqbot.accounts);
+    if (ids.length > 0) {
+      return ids[0];
+    }
+  }
+  return DEFAULT_ACCOUNT_ID;
+}
+
+/**
+ * Resolve base account info (without credentials).
+ * 解析账号基础信息（不含凭证）。
+ *
+ * Resolves everything except Secret/credential fields. The outer
+ * config.ts layer calls this and adds Secret handling on top.
+ */
+export function resolveAccountBase(
+  cfg: Record<string, unknown>,
+  accountId?: string | null,
+): ResolvedAccountBase {
+  const resolvedAccountId = accountId ?? resolveDefaultAccountId(cfg);
+  const qqbot = readQQBotSection(cfg);
+
+  let accountConfig: Record<string, unknown> = {};
+  let appId = "";
+
+  if (resolvedAccountId === DEFAULT_ACCOUNT_ID) {
+    accountConfig = normalizeAccountConfig(asRecord(qqbot));
+    appId = normalizeAppId(qqbot?.appId);
+  } else {
+    const account = qqbot?.accounts?.[resolvedAccountId];
+    accountConfig = normalizeAccountConfig(asRecord(account));
+    appId = normalizeAppId(asRecord(account)?.appId);
+  }
+
+  if (!appId && process.env.QQBOT_APP_ID && resolvedAccountId === DEFAULT_ACCOUNT_ID) {
+    appId = normalizeAppId(process.env.QQBOT_APP_ID);
+  }
+
+  return {
+    accountId: resolvedAccountId,
+    name: readString(accountConfig, "name"),
+    enabled: accountConfig.enabled !== false,
+    appId,
+    systemPrompt: readString(accountConfig, "systemPrompt"),
+    markdownSupport: accountConfig.markdownSupport !== false,
+    config: accountConfig,
+  };
+}
+
+// ---- Account config apply ----
+
+interface ApplyAccountInput {
+  appId?: string;
+  clientSecret?: string;
+  clientSecretFile?: string;
+  name?: string;
+}
+
+/** Apply account config updates into a raw config object. */
+export function applyAccountConfig(
+  cfg: Record<string, unknown>,
+  accountId: string,
+  input: ApplyAccountInput,
+): Record<string, unknown> {
+  const next = { ...cfg };
+  const channels = asRecord(cfg.channels) ?? {};
+  const existingQQBot = asRecord(channels.qqbot) ?? {};
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    const allowFrom = (existingQQBot.allowFrom as unknown[]) ?? ["*"];
+    next.channels = {
+      ...channels,
+      qqbot: {
+        ...existingQQBot,
+        enabled: true,
+        allowFrom,
+        ...(input.appId ? { appId: input.appId } : {}),
+        ...(input.clientSecret
+          ? { clientSecret: input.clientSecret, clientSecretFile: undefined }
+          : input.clientSecretFile
+            ? { clientSecretFile: input.clientSecretFile, clientSecret: undefined }
+            : {}),
+        ...(input.name ? { name: input.name } : {}),
+      },
+    };
+  } else {
+    const accounts = (existingQQBot.accounts ?? {}) as Record<string, Record<string, unknown>>;
+    const existingAccount = accounts[accountId] ?? {};
+    const allowFrom = (existingAccount.allowFrom as unknown[]) ?? ["*"];
+    next.channels = {
+      ...channels,
+      qqbot: {
+        ...existingQQBot,
+        enabled: true,
+        accounts: {
+          ...accounts,
+          [accountId]: {
+            ...existingAccount,
+            enabled: true,
+            allowFrom,
+            ...(input.appId ? { appId: input.appId } : {}),
+            ...(input.clientSecret
+              ? { clientSecret: input.clientSecret, clientSecretFile: undefined }
+              : input.clientSecretFile
+                ? { clientSecretFile: input.clientSecretFile, clientSecret: undefined }
+                : {}),
+            ...(input.name ? { name: input.name } : {}),
+          },
+        },
+      },
+    };
+  }
+
+  return next;
+}
+
+// ---- Account status helpers ----
+
+/** Resolved account shape expected by isAccountConfigured / describeAccount. */
+interface AccountSnapshot {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  appId: string;
+  clientSecret?: string;
+  secretSource?: string;
+  config: Record<string, unknown> & {
+    clientSecret?: unknown;
+    clientSecretFile?: string;
+  };
+}
+
+/** Check whether a QQBot account has been fully configured. */
+export function isAccountConfigured(account: AccountSnapshot | undefined): boolean {
+  return Boolean(
+    account?.appId &&
+    (Boolean(account?.clientSecret) ||
+      getPlatformAdapter().hasConfiguredSecret(account?.config?.clientSecret) ||
+      Boolean(account?.config?.clientSecretFile?.trim())),
+  );
+}
+
+/** Build a summary description of an account. */
+export function describeAccount(account: AccountSnapshot | undefined) {
+  return {
+    accountId: account?.accountId ?? DEFAULT_ACCOUNT_ID,
+    name: account?.name,
+    enabled: account?.enabled ?? false,
+    configured: isAccountConfigured(account),
+    tokenSource: account?.secretSource,
+  };
+}
+
+/** Normalize allowFrom entries into uppercase strings without the qqbot: prefix. */
+export function formatAllowFrom(allowFrom: Array<string | number> | undefined | null): string[] {
+  return (allowFrom ?? [])
+    .map((entry) => normalizeStringifiedOptionalString(entry))
+    .filter((entry): entry is string => Boolean(entry))
+    .map((entry) => entry.replace(/^qqbot:/i, ""))
+    .map((entry) => entry.toUpperCase());
+}

package/src/engine/config/setup-logic.ts

@@ -0,0 +1,84 @@
+/**
+ * QQBot setup business logic (pure layer).
+ * QQBot setup 相关纯业务逻辑。
+ *
+ * Token parsing, input validation, and setup config application.
+ * All functions are framework-agnostic and operate on plain objects.
+ */
+
+import { applyAccountConfig } from "./resolve.js";
+import { DEFAULT_ACCOUNT_ID } from "./resolve.js";
+
+/** Parse an inline "appId:clientSecret" token string. */
+function parseInlineToken(token: string): { appId: string; clientSecret: string } | null {
+  const colonIdx = token.indexOf(":");
+  if (colonIdx <= 0 || colonIdx === token.length - 1) {
+    return null;
+  }
+
+  const appId = token.slice(0, colonIdx).trim();
+  const clientSecret = token.slice(colonIdx + 1).trim();
+  if (!appId || !clientSecret) {
+    return null;
+  }
+
+  return { appId, clientSecret };
+}
+
+interface SetupInput {
+  token?: string;
+  tokenFile?: string;
+  useEnv?: boolean;
+  name?: string;
+}
+
+/** Validate setup input for a QQBot account. Returns an error string or null. */
+export function validateSetupInput(accountId: string, input: SetupInput): string | null {
+  if (!input.token && !input.tokenFile && !input.useEnv) {
+    return "QQBot requires --token (format: appId:clientSecret) or --use-env";
+  }
+
+  if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
+    return "QQBot --use-env only supports the default account";
+  }
+
+  if (input.token && !parseInlineToken(input.token)) {
+    return "QQBot --token must be in appId:clientSecret format";
+  }
+
+  return null;
+}
+
+/** Apply setup input to account config. Returns updated config. */
+export function applySetupAccountConfig(
+  cfg: Record<string, unknown>,
+  accountId: string,
+  input: SetupInput,
+): Record<string, unknown> {
+  if (input.useEnv && accountId !== DEFAULT_ACCOUNT_ID) {
+    return cfg;
+  }
+
+  let appId = "";
+  let clientSecret = "";
+
+  if (input.token) {
+    const parsed = parseInlineToken(input.token);
+    if (!parsed) {
+      return cfg;
+    }
+    appId = parsed.appId;
+    clientSecret = parsed.clientSecret;
+  }
+
+  if (!appId && !input.tokenFile && !input.useEnv) {
+    return cfg;
+  }
+
+  return applyAccountConfig(cfg, accountId, {
+    appId,
+    clientSecret,
+    clientSecretFile: input.tokenFile,
+    name: input.name,
+  });
+}