@chanlerdev/scorel 0.0.2 → 0.0.3

package/docs/spec/ship/S0092-im-message-media-and-human-cadence.md

@@ -0,0 +1,83 @@
+# S0092: IM Message Media And Human Cadence
+
+## Goal
+
+Make IM conversations feel alive and trustworthy by improving outgoing message capability and IM-specific response cadence.
+
+The business value is user confidence. In IM, silence for minutes reads as failure; Scorel needs visible progress and short human-style replies without compromising the existing agent loop.
+
+## Scope
+
+### SendChannelMessage Payload
+
+Extend `SendChannelMessage` from text-only to a structured outgoing message:
+
+```ts
+type SendChannelMessageInput = {
+  text?: string;
+  attachments?: Array<{
+    type: "image" | "file";
+    path?: string;
+    url?: string;
+    mimeType?: string;
+    caption?: string;
+  }>;
+  channel?: string;
+  target?: "current";
+};
+```
+
+Rules:
+
+- At least one of `text` or `attachments` is required.
+- Adapters may downgrade unsupported attachments to a clear tool error.
+- Local file paths must be explicit and must not be guessed from raw platform ids.
+- Tool result details report per-attachment status.
+
+### Adapter Capability Contract
+
+- Add optional adapter capabilities for outgoing attachment support.
+- Telegram/QQ/WeChat can initially support text and explicitly reject unsupported media.
+- Loopback should support structured capture of text and attachment metadata for tests.
+
+### IM System Prompt / Harness Guidance
+
+Add IM-specific guidance to channel context:
+
+- acknowledge quickly when work will take time;
+- send brief progress updates through `SendChannelMessage` during long tasks;
+- prefer concise, conversational wording;
+- do not wait until every tool finishes before sending any reply;
+- avoid exposing internal tool names unless useful to the user;
+- keep business-critical facts and file references precise.
+
+This guidance must enter through the existing channel harness item / skill path, not a second provider-level system prompt.
+
+## Not In Scope
+
+- Full media upload implementation for every platform.
+- Voice, stickers, albums, interactive buttons, or payments.
+- Cross-conversation proactive messages.
+- A new IM runtime loop or queue.
+- Fake progress timers outside the agent loop.
+
+## Acceptance Criteria
+
+- `SendChannelMessage` accepts text, image, and file attachment metadata.
+- Text-only calls remain backward compatible.
+- Unsupported attachment sends fail as tool errors, not silent no-ops.
+- IM channel reminders tell the agent to respond early and keep long-running users informed.
+- Built-in IM skills include platform-specific response cadence guidance.
+- Tests prove the model-facing tool schema rejects empty sends and preserves attachment metadata.
+
+## Testing Requirements
+
+- Core channel tool tests for structured payload parsing.
+- Loopback adapter tests for captured attachment metadata.
+- Telegram/QQ/WeChat tests for unsupported media errors or implemented send mapping.
+- Instruction/channel context tests for IM cadence guidance.
+- Full `pnpm typecheck && pnpm test`.
+
+## Status
+
+Done.

package/docs/spec/ship/S0093-gui-im-settings-platform-layout.md

@@ -0,0 +1,66 @@
+# S0093: GUI IM Settings Platform Layout
+
+## Goal
+
+Redesign GUI IM Settings so multiple platforms fit without crowding the page.
+
+The business value is scale. Telegram was one provider; Telegram + QQ + WeChat needs a repeatable platform row pattern where details expand only when the user asks.
+
+## Scope
+
+- Replace the current Telegram-only large form with a platform list.
+- Each platform row shows:
+  - platform name;
+  - enabled/disabled toggle;
+  - active/inactive status;
+  - concise credential/config summary;
+  - expand/collapse affordance.
+- Clicking a row expands its detailed config below that row.
+- Clicking the expanded row again collapses it.
+- The page defaults to all platforms collapsed unless a previous expanded platform is stored locally.
+- The last expanded platform is remembered locally; collapsing clears that remembered state.
+- Support Telegram, QQ, and WeChat using one reusable component shape.
+- Preserve existing Telegram config fields and persistence behavior.
+- Add QQ and WeChat config fields that match S0091/S0094.
+- For QQ and WeChat, expose the current quick setup fields only: QQ `App ID` / `App Secret`, WeChat `Outbound Webhook` plus inbound callback `Callback Token` / `Callback Host` / `Callback Port`.
+- Keep settings stored through the existing `getExtensionSettings` / `upsertExtensionSettings` IPC path.
+- Absorb immediate GUI review fixes found before push:
+  - expanded platform details must have a visible ownership boundary;
+  - the composer must not submit while an IME composition is active.
+
+## Not In Scope
+
+- Remote Relay IM settings.
+- Diagnostics timeline.
+- Live credential validation beyond existing adapter refresh behavior.
+- Account OAuth or QR login.
+
+## Acceptance Criteria
+
+- The IM Settings page renders three compact platform rows.
+- The first render does not expand Telegram by default.
+- No single disabled platform consumes a full settings page height.
+- Expanding Telegram reveals the existing credential/poll/allow-list fields.
+- Expanding QQ or WeChat reveals their S0091 config fields.
+- QQ and WeChat do not expose env-var-first credential fields in the default Settings flow.
+- Re-clicking the expanded platform collapses details.
+- Re-opening IM Settings restores the previously expanded platform when one was stored.
+- Toggling a platform writes the correct extension config and refreshes local Host IM extensions.
+- Direct secret fields are password inputs and are never displayed in summaries.
+- Layout remains readable in narrow GUI widths.
+- Expanded fields are visually grouped under the active platform, not blended into sibling platform rows.
+- Pressing Enter while Chinese/Japanese/Korean IME composition is active does not submit or block candidate selection.
+- Plain Enter still submits when enabled; Shift+Enter remains available for newline input.
+
+## Testing Requirements
+
+- GUI render tests for compact rows and expansion.
+- GUI interaction tests for default-collapsed, toggle-to-collapse, and stored expansion restore.
+- GUI interaction tests for toggling and field blur persistence.
+- Existing Telegram settings behavior remains covered.
+- GUI composer tests cover IME composition Enter, plain Enter, and Shift+Enter.
+- Full `pnpm typecheck && pnpm test`.
+
+## Status
+
+Done.

package/docs/spec/ship/S0094-im-inbound-runtime.md

@@ -0,0 +1,67 @@
+# S0094: IM Inbound Runtime
+
+## Goal
+
+Make built-in QQ and WeChat IM integrations actually receive user messages at runtime and route them through the shared Scorel IM session bridge.
+
+## Scope
+
+- Implement QQ Bot inbound receive through the official WebSocket Gateway.
+- Implement WeChat inbound receive through an official HTTP callback surface for official-account style plaintext text messages.
+- Keep WeCom group robot webhook as an outbound-only sender because that official webhook surface does not deliver user messages back to Scorel.
+- Keep adapters platform-IO only. They call `ctx.onMessage(...)`; daemon session creation stays in the existing IM bridge.
+- Update GUI settings and docs so outbound webhook configuration is not presented as if it enables inbound WeChat chat.
+
+## Not In Scope
+
+- Consumer personal WeChat reverse engineering, browser automation, or Web WeChat scraping.
+- Hosted public ingress, TLS certificates, relay tunneling, or automatic public URL provisioning.
+- Full WeChat encrypted callback decrypt/encrypt support. Plaintext callback is the S0094 receive baseline.
+- QQ sharding beyond one local gateway connection.
+
+## Acceptance Criteria
+
+- QQ adapter `start(ctx)` fetches an access token, fetches `/gateway`, opens a WebSocket, identifies with `QQBot <access_token>`, sends heartbeats, and calls `ctx.onMessage(...)` for text dispatch events normalized by `normalizeQQEvent`.
+- QQ adapter `stop()` closes the WebSocket and heartbeat timer.
+- WeChat adapter starts a local HTTP callback server when callback config is present, responds to GET URL verification, accepts text POST callbacks, normalizes them, and calls `ctx.onMessage(...)`.
+- WeChat adapter can still send outbound text to a configured WeCom group robot webhook; if only webhook URL is configured, inbound is explicitly not started.
+- Tests cover QQ gateway identify/heartbeat/dispatch/stop and WeChat callback verification/message routing.
+
+## Test Requirements
+
+- Add focused adapter tests before implementation.
+- Run:
+
+```bash
+pnpm --filter @scorel/daemon test -- qq-adapter.test.ts wechat-adapter.test.ts
+pnpm typecheck
+pnpm test
+```
+
+## Impacted Files
+
+- `extensions/builtin/qq/adapter.js`
+- `extensions/builtin/qq/adapter.d.ts`
+- `extensions/builtin/wechat/adapter.js`
+- `extensions/builtin/wechat/adapter.d.ts`
+- `packages/daemon/src/qq-adapter.test.ts`
+- `packages/daemon/src/wechat-adapter.test.ts`
+- `apps/gui/src/renderer/settings/sections/ImSection.tsx`
+- `docs/spec/ship/S0091-built-in-qq-and-wechat-im-extensions.md`
+
+## Risks And Boundaries
+
+- QQ event delivery also depends on the bot's platform-side event subscriptions and permissions. Scorel can connect to the gateway, but QQ may still omit events that are not enabled for the bot.
+- WeChat callback receive requires a URL Tencent can reach. Local-only callback ports are useful for tunnels and tests, but are not publicly reachable by themselves.
+- WeCom group robot webhook remains outbound-only by official product design; Scorel must not imply that it can receive user chat through that webhook.
+
+## References
+
+- QQ Bot event delivery and WebSocket gateway: <https://bot.q.qq.com/wiki/develop/api-v2/dev-prepare/interface-framework/event-emit.html>
+- QQ Bot gateway URL API: <https://bot.q.qq.com/wiki/develop/api-v2/openapi/wss/url_get.html>
+- WeCom group robot outbound webhook: <https://developer.work.weixin.qq.com/document/path/91770>
+- WeChat official account callback verification and normal messages: <https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Access_Overview.html>, <https://developers.weixin.qq.com/doc/offiaccount/Message_Management/Receiving_standard_messages.html>
+
+## Status
+
+Done.

package/docs/spec/ship/S0095-gui-im-session-list-refresh.md

@@ -0,0 +1,36 @@
+# S0095: GUI IM Session List Refresh
+
+## Goal
+
+Make GUI sidebars show IM sessions that are created in the background by Telegram, QQ, or WeChat inbound messages.
+
+## Scope
+
+- Notify GUI when the local Host creates a session, including IM sessions created in the background.
+- Refresh only the affected Project session list in response to that notification.
+- Keep IM session storage and Project binding unchanged.
+- Cover the selected/default IM workspace Project so background QQ/Telegram sessions appear without app restart.
+
+## Not In Scope
+
+- Changing where session JSONL files are stored.
+- Creating per-platform Projects.
+- Relay or hosted notification push for remote devices.
+
+## Acceptance Criteria
+
+- A GUI Project refreshes when the local Host reports a new session for that Project.
+- The refresh does not clear the active transcript.
+- Renderer test covers a background session appearing after initial load.
+
+## Test Requirements
+
+```bash
+pnpm --filter @scorel/app-gui test -- src/renderer/app-session-preload.test.tsx
+pnpm typecheck
+pnpm test
+```
+
+## Status
+
+Done.

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, "\\$&");

package/extensions/builtin/qq/scorel.extension.json

@@ -0,0 +1,7 @@
+{
+  "id": "qq",
+  "kind": "im",
+  "displayName": "QQ Bot",
+  "adapter": "./adapter.js",
+  "skills": ["./skills"]
+}

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

@@ -0,0 +1,9 @@
+# QQ Bot
+
+Use this skill when replying through the QQ Bot IM channel.
+
+- Treat QQ messages as short conversational turns.
+- In groups, assume the user intentionally mentioned the bot when the channel context says `mentioned_bot: true`.
+- Reply with `SendChannelMessage` to the current conversation instead of exposing raw QQ ids.
+- If work will take more than a brief moment, send a short acknowledgement first, then follow with progress or the final result.
+- Keep replies concise and avoid dumping internal tool logs unless the user asked for technical detail.