@chanlerdev/scorel 0.0.2 → 0.0.4

package/docs/spec/ship/S0099-gui-connection-device-settings.md

@@ -0,0 +1,85 @@
+# S0099: GUI Connection And Device Settings
+
+## Goal
+
+Make GUI connection setup match the hosted Relay product path, so users can pair devices, rename paired devices, and inspect connection details.
+
+S0101 supersedes the original settings-scope part of this spec: settings configuration is device-scoped, not Project-scoped.
+
+## Scope
+
+- GUI Relay pairing:
+  - default to the official Relay without showing an editable URL field;
+  - expose Relay URL editing only behind an explicit edit affordance;
+  - rename the pairing action from `Pair` to `Get Pair Code`.
+- GUI paired devices:
+  - allow users to rename a paired Relay Device locally in GUI state;
+  - preserve the Relay-reported label as fallback when no local name exists;
+  - show device details from the generic device view: status, Device ID, IP when available, and Relay URL.
+- GUI Settings scope:
+  - superseded by S0101;
+  - the correct product model is device-scoped configuration.
+- Tests and docs:
+  - cover local device rename persistence;
+  - cover the connection section rendering contract;
+  - keep ROADMAP in sync.
+
+## Not In Scope
+
+- Relay protocol changes or IP discovery in Relay V1. The UI may expose an optional IP field, but Relay currently does not guarantee one.
+- SSH Remote Device, remote installation, or SSH stdio proxy.
+- Direct WS + token GUI setup.
+- Account/OAuth identity.
+- Importing every remote Host Project automatically into the GUI Project list.
+- Moving IM extension settings to remote scope; IM settings remain local GUI/Host extension settings in this spec.
+
+## Acceptance Criteria
+
+- Opening GUI Settings -> Connections shows the official Relay as the default endpoint and does not show a Relay URL input until the user chooses edit.
+- The pair action reads `Get Pair Code`.
+- A pair code is still created with the default official Relay when the URL field has not been edited.
+- Paired devices can be renamed from the Connections page, and the local name persists in `~/.scorel/gui-store.json`.
+- Paired device details expose status, Device ID, Relay URL, and an IP row that is populated only when the device view has IP information.
+- Settings nav behavior is governed by S0101: it shows devices, not Projects.
+
+## Test Requirements
+
+```bash
+pnpm --filter @scorel/app-gui test -- src/main/gui-store.test.ts src/renderer/gui-shell.test.tsx
+pnpm typecheck
+pnpm test
+```
+
+Manual:
+
+- Open GUI Settings -> Connections.
+- Confirm the Relay URL input is hidden by default and `Get Pair Code` returns a pair code against the official Relay.
+- Click edit, change Relay URL, and confirm pair/refresh use the edited URL.
+- Pair or seed a Relay Device, rename it, refresh, and confirm the local name remains.
+- Open Settings and confirm the settings selector follows S0101 device-scoped behavior.
+
+## Impacted Files
+
+- `apps/gui/src/main/gui-store.ts`
+- `apps/gui/src/main.ts`
+- `apps/gui/src/preload.ts`
+- `apps/gui/src/shared/ipc.ts`
+- `apps/gui/src/renderer/App.tsx`
+- `apps/gui/src/renderer/settings/SettingsShell.tsx`
+- `apps/gui/src/renderer/settings/SettingsNav.tsx`
+- `apps/gui/src/renderer/settings/sections/ConfigSection.tsx`
+- `apps/gui/src/renderer/styles.css`
+- `apps/gui/src/main/gui-store.test.ts`
+- `apps/gui/src/renderer/gui-shell.test.tsx`
+- `docs/CHANGELOG.md`
+- `docs/ROADMAP.md`
+
+## Risks And Boundaries
+
+- Device rename is GUI-local metadata, not a Relay identity mutation. Refresh must not overwrite a user's local name with a Relay label.
+- Settings scope is device-based as of S0101. Projects are workspace/session objects, not configuration owners.
+- IP is optional because the current Relay protocol does not report it; the UI contract must tolerate absence without inventing a fake value.
+
+## Status
+
+Done.

package/docs/spec/ship/S0100-gui-provider-danger-zone.md

@@ -0,0 +1,57 @@
+# S0100: GUI Provider Danger Zone Placement
+
+## Goal
+
+Move destructive Provider management actions out of the primary Provider edit form, so normal configuration fields remain the first visual focus and deletion is clearly presented as a secondary dangerous action.
+
+S0101 supersedes the final placement: `删除提供商` now lives in the Provider configuration block's lower-right action area instead of a bottom danger row.
+
+## Scope
+
+- In GUI Settings -> Provider:
+  - this spec recorded the first placement pass;
+  - S0101 defines the current placement in the Provider configuration block;
+  - keep the existing `removeModelProvider` behavior unchanged.
+- Add rendering coverage that verifies the destructive action is below normal model-management controls.
+
+## Not In Scope
+
+- Changing Provider deletion semantics, confirmation behavior, or daemon/client APIs.
+- Redesigning the Provider page layout beyond the destructive-action placement.
+- Changing model catalog, model selection, or provider form fields.
+
+## Acceptance Criteria
+
+- Current acceptance is governed by S0101: `删除提供商` appears in the Provider configuration block.
+- Existing Provider add/edit/model actions remain unchanged.
+- GUI rendering tests cover the current placement.
+
+## Test Requirements
+
+```bash
+pnpm --filter @scorel/app-gui test -- src/renderer/gui-shell.test.tsx
+pnpm --filter @scorel/app-gui typecheck
+```
+
+Manual:
+
+- Start the GUI with a Project that has a configured Provider.
+- Open Settings -> Provider.
+- Confirm S0101 current behavior: the delete button appears in the Provider configuration block's lower-right action area.
+
+## Impacted Files
+
+- `apps/gui/src/renderer/settings/sections/ProviderSection.tsx`
+- `apps/gui/src/renderer/styles.css`
+- `apps/gui/src/renderer/gui-shell.test.tsx`
+- `docs/CHANGELOG.md`
+- `docs/ROADMAP.md`
+
+## Risks And Boundaries
+
+- The delete action remains destructive and immediate, matching existing behavior. This spec only changes placement.
+- The danger row should not introduce another card nested inside the Provider card; it stays as an inline separated row.
+
+## Status
+
+Done.

package/docs/spec/ship/S0101-gui-device-settings-polish.md

@@ -0,0 +1,66 @@
+# S0101 GUI Device Settings Polish
+
+## Goal
+
+Fix GUI settings so configuration is device-scoped, not Project-scoped, and polish the settings interactions surfaced by the latest Provider / Token / Connection review.
+
+One device has one configuration. The Settings scope selector chooses a device:
+
+- `此电脑` configures the local device.
+- A Relay device configures that remote device.
+- Projects remain workspace/session objects and must not appear as the settings configuration scope.
+
+## Scope
+
+- Settings left scope selector becomes device-based.
+- GUI settings IPC for model profile, Provider catalog/deletion, memory settings, and runtime settings targets only a device.
+- Daemon/client config requests used by GUI are device-level and write the device user config at `~/.scorel/config.toml` for that daemon.
+- Provider deletion moves into the top Provider configuration form area, aligned to the lower-right of the Provider parameter block.
+- Runtime token statistics use understandable Chinese labels and expose both output token total and saved token estimate.
+- Relay device rows have an explicit expand affordance.
+- Relay device rename is inline: a small edit icon next to the device name turns the name into an input.
+
+## Not In Scope
+
+- Changing session/project ownership: sessions still belong to Projects.
+- Redesigning Project registry or remote Project selection.
+- Creating per-Project settings overrides.
+- Reworking IM extension settings beyond existing user-config behavior.
+- Changing RTK savings math.
+
+## Acceptance Criteria
+
+- Settings selector labels are device names only, for example `此电脑` and `Remote Device`; it does not render `此电脑 / ProjectName` or `Device / ProjectName`.
+- Settings Provider/Model/Memory/Runtime mutations do not accept a Project in GUI IPC.
+- Daemon writes GUI settings requests to device-level user config.
+- Provider delete is visually close to Provider credentials/configuration, not in a separate bottom danger row.
+- Runtime token stats are Chinese and self-explanatory.
+- Relay device rows visibly indicate expand/collapse and rename through a name-adjacent edit icon.
+
+## Test Requirements
+
+- Update renderer tests for device settings scope, Provider delete placement, Runtime labels, and inline Relay device rename affordance.
+- Add or update daemon/local-host tests proving projectless settings write `config.toml` under device user config.
+- Run targeted GUI/protocol/daemon tests covering changed paths.
+- Run `pnpm typecheck && pnpm test` before shipping.
+
+## Impacted Files
+
+- `packages/protocol/src/events.ts`
+- `packages/protocol/src/wire.ts`
+- `packages/client/src/index.ts`
+- `packages/daemon/src/index.ts`
+- `apps/gui/src/main.ts`
+- `apps/gui/src/main/local-host.ts`
+- `apps/gui/src/main/relay-service.ts`
+- `apps/gui/src/preload.ts`
+- `apps/gui/src/shared/ipc.ts`
+- `apps/gui/src/renderer/App.tsx`
+- `apps/gui/src/renderer/settings/*`
+- `apps/gui/src/renderer/styles.css`
+- `docs/ROADMAP.md`
+- `docs/CHANGELOG.md`
+
+## Risks And Boundaries
+
+- Memory status is a Project activity/status concept; this spec keeps Settings focused on Memory configuration, not Project activity status.

package/docs/spec/ship/S0102-device-only-config.md

@@ -0,0 +1,58 @@
+# S0102 Device Only Config
+
+## Goal
+
+Remove project-level config as a product concept. A Scorel device has exactly one editable config, stored at that device's Scorel home `config.toml`.
+
+Projects are workspace/session objects. They do not own Provider, Model, Memory, Runtime, or Extension settings.
+
+## Scope
+
+- Core config loading reads only the device/user config file.
+- Remove `.scorel/config.toml` from the public config schema and runtime loading contract.
+- Settings writes always target the device config, even if an older request still includes a `projectId`.
+- CLI daemon, CLI chat, GUI local host, and daemon fallback config reads pass the device `scorelHomeDir` explicitly so custom device roots do not read the process user's real `~/.scorel/config.toml`.
+- Update current config docs/specs that describe project-scoped config.
+
+## Not In Scope
+
+- Changing Project/session ownership.
+- Removing Project registry or remote Project selection.
+- Adding migration for old project `.scorel/config.toml` files.
+- Changing project-scoped Memory status or runtime stats, which are activity/status data, not config ownership.
+
+## Acceptance Criteria
+
+- `loadScorelConfig` and `loadScorelConfigProfile` ignore project `.scorel/config.toml`.
+- If device config is missing, config loading reports the missing device config path.
+- Provider/model/memory/runtime/extension Settings writes go to device `config.toml`.
+- Requests with `projectId` do not create or mutate project `.scorel/config.toml`.
+- Runtime creation for a Project still uses that device's single config.
+- Docs describe config as device-only.
+
+## Test Requirements
+
+- Core config tests load from device/user config and prove project `.scorel/config.toml` is ignored.
+- Daemon embedded tests prove Settings writes with `projectId` still write device config only.
+- CLI daemon idle test continues to prove custom device state roots do not inherit active IM from the real user config.
+- Run `pnpm typecheck && pnpm test`.
+
+## Impacted Files
+
+- `packages/core/src/config/index.ts`
+- `packages/core/src/config/config.test.ts`
+- `packages/daemon/src/index.ts`
+- `packages/daemon/src/embedded/embedded.test.ts`
+- `apps/cli/src/index.ts`
+- `apps/cli/src/daemon-cli.ts`
+- `apps/gui/src/main/local-host.ts`
+- `docs/spec/extensions.md`
+- `docs/spec/ship/S0097-rtk-token-saving-settings.md`
+- `docs/spec/ship/S0086-auto-compact-and-session-memory.md`
+- `docs/ROADMAP.md`
+- `docs/CHANGELOG.md`
+
+## Risks And Boundaries
+
+- Pre-1.0 development rules allow removing this stale config surface rather than preserving compatibility.
+- Old project `.scorel/config.toml` files may remain on disk, but runtime no longer treats them as config.

package/extensions/builtin/loopback/skills/loopback/SKILL.md

@@ -5,3 +5,5 @@ description: Reply to the current loopback IM conversation with SendChannelMessa
 # Loopback IM
 
 When a message comes from the loopback IM channel, use `SendChannelMessage` to reply to the current conversation. Do not ask for raw channel ids.
+
+If work will take more than a brief moment, send a short acknowledgement first, then follow with concise progress or the final result.

package/extensions/builtin/qq/adapter.d.ts

@@ -0,0 +1,27 @@
+export type QQAdapterOptions = {
+  appId: string;
+  appSecret: string;
+  apiBaseUrl: string;
+  accessTokenUrl?: string;
+  gatewayUrl?: string;
+  botId?: string;
+  intents?: number;
+  heartbeatIntervalMs?: number;
+  dedupeTtlMs?: number;
+};
+
+export type QQTarget = {
+  externalConversationId: string;
+  data?: Record<string, unknown>;
+};
+
+export type QQAdapter = {
+  start(ctx: unknown): Promise<void>;
+  stop(): Promise<void>;
+  sendMessage(target: QQTarget, message: { text?: string; attachments?: Array<Record<string, unknown>> }): Promise<void>;
+};
+
+export function createAdapter(options?: { config?: Record<string, string | number | boolean> }): QQAdapter;
+export function createQQAdapter(options: QQAdapterOptions): QQAdapter;
+export function normalizeQQEvent(event: unknown, options?: { botId?: string }): unknown;
+export function redactQQSecret(value: string): string;

package/extensions/builtin/qq/adapter.js

@@ -0,0 +1,384 @@
+import WebSocket from "ws";
+
+const DEFAULT_QQ_API_BASE_URL = "https://api.sgroup.qq.com";
+const DEFAULT_QQ_ACCESS_TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
+const DEFAULT_QQ_INTENTS = (1 << 9) | (1 << 25) | (1 << 30);
+const DEFAULT_DEDUPE_TTL_MS = 5 * 60_000;
+
+export const createAdapter = ({ config = {} } = {}) => {
+  return createQQAdapter({
+    appId: requiredStringConfig(config.appId, "QQ App ID"),
+    appSecret: requiredStringConfig(config.appSecret, "QQ App Secret"),
+    apiBaseUrl: stringConfig(config.apiBaseUrl, DEFAULT_QQ_API_BASE_URL),
+    accessTokenUrl: stringConfig(config.accessTokenUrl, DEFAULT_QQ_ACCESS_TOKEN_URL),
+    gatewayUrl: stringConfig(config.gatewayUrl, ""),
+    botId: optionalStringConfig(config.botId, "QQ botId"),
+  });
+};
+
+export const createQQAdapter = (options) => {
+  let accessToken;
+  let accessTokenExpiresAt = 0;
+  let ctx;
+  let running = false;
+  let socket;
+  let heartbeatTimer;
+  let lastSequence = null;
+  let sessionId;
+  const recentMessageIds = new Map();
+
+  const getAccessToken = async () => {
+    const refreshAt = accessTokenExpiresAt - 60_000;
+    if (accessToken && Date.now() < refreshAt) {
+      return accessToken;
+    }
+    const response = await fetch(options.accessTokenUrl ?? DEFAULT_QQ_ACCESS_TOKEN_URL, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        appId: options.appId,
+        clientSecret: options.appSecret,
+      }),
+    });
+    const payload = await response.json().catch(() => undefined);
+    if (!response.ok || typeof payload?.access_token !== "string" || !payload.access_token.trim()) {
+      throw new Error(redactQQSecret(`qq access token failed: ${payload?.message ?? payload?.errmsg ?? response.status}`));
+    }
+    const expiresIn = Number(payload.expires_in);
+    accessToken = payload.access_token.trim();
+    accessTokenExpiresAt = Date.now() + (Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn * 1000 : 7200_000);
+    return accessToken;
+  };
+
+  const fetchGatewayUrl = async (token) => {
+    const configured = typeof options.gatewayUrl === "string" && options.gatewayUrl.trim() ? options.gatewayUrl.trim() : undefined;
+    const response = await fetch(configured ?? `${options.apiBaseUrl.replace(/\/+$/, "")}/gateway`, {
+      method: "GET",
+      headers: { authorization: `QQBot ${token}` },
+    });
+    const payload = await response.json().catch(() => undefined);
+    if (!response.ok || typeof payload?.url !== "string" || !payload.url.trim()) {
+      throw new Error(redactQQSecret(`qq gateway failed: ${payload?.message ?? response.status}`));
+    }
+    return payload.url.trim();
+  };
+
+  const sendSocket = (payload) => {
+    if (socket?.readyState === WebSocket.OPEN) {
+      socket.send(JSON.stringify(payload));
+    }
+  };
+
+  const sendHeartbeat = () => {
+    sendSocket({ op: 1, d: lastSequence });
+  };
+
+  const clearHeartbeat = () => {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = undefined;
+    }
+  };
+
+  const identify = async () => {
+    sendSocket({
+      op: 2,
+      d: {
+        token: `QQBot ${await getAccessToken()}`,
+        intents: numberConfig(options.intents, DEFAULT_QQ_INTENTS),
+        shard: Array.isArray(options.shard) ? options.shard : [0, 1],
+        properties: {
+          "$os": process.platform,
+          "$browser": "scorel",
+          "$device": "scorel",
+        },
+      },
+    });
+  };
+
+  const handleGatewayPayload = async (payload) => {
+    if (typeof payload?.s === "number") {
+      lastSequence = payload.s;
+    }
+    if (payload?.op === 10) {
+      const interval = numberConfig(options.heartbeatIntervalMs, Number(payload?.d?.heartbeat_interval) || 45_000);
+      clearHeartbeat();
+      sendHeartbeat();
+      heartbeatTimer = setInterval(sendHeartbeat, interval);
+      heartbeatTimer.unref?.();
+      await identify();
+      return;
+    }
+    if (payload?.op === 1) {
+      sendHeartbeat();
+      return;
+    }
+    if (payload?.op === 0) {
+      if (payload.t === "READY" && typeof payload.d?.session_id === "string") {
+        sessionId = payload.d.session_id;
+        return;
+      }
+      const incoming = normalizeQQEvent(payload.d, { botId: options.botId });
+      if (!incoming || isDuplicateMessage(incoming, recentMessageIds, numberConfig(options.dedupeTtlMs, DEFAULT_DEDUPE_TTL_MS))) {
+        return;
+      }
+      await ctx?.onMessage(incoming);
+      return;
+    }
+    if (payload?.op === 7 || payload?.op === 9) {
+      ctx?.logger?.error("qq_gateway_reconnect_required", { op: payload.op, sessionId });
+    }
+  };
+
+  return {
+    async start(startCtx) {
+      ctx = startCtx;
+      running = true;
+      const token = await getAccessToken();
+      const url = await fetchGatewayUrl(token);
+      await new Promise((resolve, reject) => {
+        const ws = new WebSocket(url);
+        socket = ws;
+        let settled = false;
+        const settle = (error) => {
+          if (settled) return;
+          settled = true;
+          error ? reject(error) : resolve();
+        };
+        ws.once("open", () => settle());
+        ws.once("error", (error) => {
+          ctx?.logger?.error("qq_gateway_error", { message: safeErrorMessage(error) });
+          settle(error);
+        });
+        ws.on("message", (data) => {
+          void handleGatewayPayload(parseGatewayMessage(data)).catch((cause) => {
+            ctx?.logger?.error("qq_gateway_message_failed", { message: redactQQSecret(safeErrorMessage(cause)) });
+          });
+        });
+        ws.on("close", () => {
+          clearHeartbeat();
+          if (running) {
+            ctx?.logger?.error("qq_gateway_closed", {});
+          }
+        });
+      });
+    },
+    async stop() {
+      running = false;
+      clearHeartbeat();
+      const closing = socket;
+      socket = undefined;
+      if (closing && closing.readyState !== WebSocket.CLOSED) {
+        await new Promise((resolve) => {
+          closing.once("close", () => resolve());
+          closing.close();
+          setTimeout(resolve, 250).unref?.();
+        });
+      }
+    },
+    async sendMessage(target, message) {
+      rejectUnsupportedAttachments("QQ", message);
+      const route = qqSendRoute(target);
+      await qqRequest(options, route, await getAccessToken(), {
+        msg_type: 0,
+        content: String(message.text).trim(),
+        ...(target?.data?.messageId ? { msg_id: target.data.messageId } : {}),
+        msg_seq: 1,
+      });
+    },
+  };
+};
+
+const parseGatewayMessage = (data) => {
+  const text = Buffer.isBuffer(data) ? data.toString("utf8") : String(data);
+  return JSON.parse(text);
+};
+
+export const normalizeQQEvent = (event, options = {}) => {
+  const text = typeof event?.content === "string" ? event.content.trim() : "";
+  if (!text) {
+    return undefined;
+  }
+  const groupOpenId = optionalEventString(event.group_openid);
+  const userOpenId = optionalEventString(event.user_openid ?? event.author?.user_openid ?? event.author?.id);
+  const channelId = optionalEventString(event.channel_id);
+  const guildId = optionalEventString(event.guild_id);
+  const messageId = optionalEventString(event.id);
+  const mentionedBot = isQQBotMentioned(text, options.botId) || Boolean(groupOpenId || guildId);
+  if (groupOpenId) {
+    return qqIncoming({
+      kind: "group",
+      id: groupOpenId,
+      text: stripQQMention(text, options.botId),
+      senderDisplayName: senderDisplayName(event.author ?? event.member),
+      mentionedBot,
+      messageId,
+    });
+  }
+  if (userOpenId) {
+    return qqIncoming({
+      kind: "private",
+      id: userOpenId,
+      text,
+      senderDisplayName: senderDisplayName(event.author),
+      mentionedBot: false,
+      messageId,
+    });
+  }
+  if (channelId) {
+    return qqIncoming({
+      kind: "channel",
+      id: channelId,
+      text: stripQQMention(text, options.botId),
+      senderDisplayName: senderDisplayName(event.author ?? event.member),
+      mentionedBot,
+      messageId,
+      extraData: guildId ? { guildId } : {},
+    });
+  }
+  return undefined;
+};
+
+export const redactQQSecret = (value) =>
+  String(value)
+    .replace(/(clientSecret"\s*:\s*")[^"]+/g, "$1[REDACTED]")
+    .replace(/QQBot\s+[A-Za-z0-9._-]+/g, "QQBot [REDACTED]");
+
+const qqIncoming = ({ kind, id, text, senderDisplayName, mentionedBot, messageId, extraData = {} }) => {
+  const conversationType = kind === "private" ? "private" : kind;
+  const externalConversationId = `qq:${conversationType}:${id}`;
+  return {
+    externalConversationId,
+    text,
+    conversationType,
+    senderDisplayName,
+    mentionedBot,
+    target: {
+      externalConversationId,
+      data: { kind, id, ...(messageId ? { messageId } : {}), ...extraData },
+    },
+    data: {
+      ...(messageId ? { messageId } : {}),
+      ...extraData,
+    },
+  };
+};
+
+const qqSendRoute = (target) => {
+  const kind = target?.data?.kind;
+  const id = target?.data?.id;
+  if (typeof id !== "string" || !id) {
+    throw new Error("QQ target is missing id");
+  }
+  if (kind === "group") {
+    return `/v2/groups/${encodeURIComponent(id)}/messages`;
+  }
+  if (kind === "private") {
+    return `/v2/users/${encodeURIComponent(id)}/messages`;
+  }
+  if (kind === "channel") {
+    return `/channels/${encodeURIComponent(id)}/messages`;
+  }
+  throw new Error("QQ target kind must be group, private, or channel");
+};
+
+const qqRequest = async (options, route, accessToken, body) => {
+  const response = await fetch(`${options.apiBaseUrl.replace(/\/+$/, "")}${route}`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `QQBot ${accessToken}`,
+    },
+    body: JSON.stringify(body),
+  });
+  const payload = await response.json().catch(() => undefined);
+  if (!response.ok) {
+    throw new Error(redactQQSecret(`qq send failed: ${payload?.message ?? response.status}`));
+  }
+  return payload;
+};
+
+const isQQBotMentioned = (text, botId) =>
+  Boolean(botId && new RegExp(`<@!?${escapeRegExp(botId)}>`, "i").test(text));
+
+const stripQQMention = (text, botId) => {
+  if (!botId) {
+    return text.trim();
+  }
+  return text.replace(new RegExp(`<@!?${escapeRegExp(botId)}>`, "gi"), " ").trim();
+};
+
+const senderDisplayName = (value) => {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+  return optionalEventString(value.username ?? value.nick ?? value.name);
+};
+
+const optionalEventString = (value) => typeof value === "string" && value.trim() ? value.trim() : undefined;
+
+const requiredStringConfig = (value, name) => {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${name} is required`);
+  }
+  return value.trim();
+};
+
+const stringConfig = (value, fallback) => {
+  if (value === undefined || value === "") {
+    return fallback;
+  }
+  if (typeof value !== "string") {
+    throw new Error("QQ config value must be a string");
+  }
+  return value;
+};
+
+const optionalStringConfig = (value, name) => {
+  if (value === undefined || value === "") {
+    return undefined;
+  }
+  if (typeof value !== "string") {
+    throw new Error(`${name} must be a string`);
+  }
+  return value;
+};
+
+const numberConfig = (value, fallback) => {
+  if (value === undefined || value === "") {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error("QQ config value must be a positive number");
+  }
+  return parsed;
+};
+
+const isDuplicateMessage = (incoming, recentMessageIds, ttlMs) => {
+  const messageId = optionalEventString(incoming?.data?.messageId ?? incoming?.target?.data?.messageId);
+  if (!messageId) {
+    return false;
+  }
+  const now = Date.now();
+  for (const [id, expiresAt] of recentMessageIds) {
+    if (expiresAt <= now) {
+      recentMessageIds.delete(id);
+    }
+  }
+  if (recentMessageIds.has(messageId)) {
+    return true;
+  }
+  recentMessageIds.set(messageId, now + ttlMs);
+  return false;
+};
+
+const safeErrorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+
+const rejectUnsupportedAttachments = (platform, message) => {
+  if (Array.isArray(message.attachments) && message.attachments.length > 0) {
+    throw new Error(`${platform} attachment sending is not supported yet`);
+  }
+};
+
+const escapeRegExp = (value) => String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");