@tencent-connect/openclaw-qqbot 1.7.2 → 2.0.0

package/src/outbound/outbound-service.ts

@@ -0,0 +1,222 @@
+/**
+ * 出站消息服务
+ *
+ * 负责将 AI 回复通过 QQBotGateway 发送到 QQ。
+ * 超时保护由 QQBotGateway 内部统一处理，本层做 target 解析 + 被动回复限额管控。
+ */
+import * as path from 'node:path';
+import { MediaFileType } from '@tencent-connect/qqbot-nodejs';
+import type { QQBotGateway } from '../gateway/index.js';
+import type { ResolvedQQBotAccount } from '../types.js';
+import { parseTarget } from './target.js';
+import { ReplyLimiter } from './reply-limiter.js';
+
+// ── Gateway + Limiter 注册表（生命周期由 channel.ts 管理）──
+
+const gateways = new Map<string, QQBotGateway>();
+const limiters = new Map<string, ReplyLimiter>();
+
+function getLimiter(accountId: string): ReplyLimiter {
+  let l = limiters.get(accountId);
+  if (!l) {
+    l = new ReplyLimiter();
+    limiters.set(accountId, l);
+  }
+  return l;
+}
+
+/**
+ * 解析 replyToId：超出被动回复限额时自动降级为主动消息（不传 msgId）。
+ * @returns 实际使用的 msgId（超限时为 undefined）
+ */
+function resolveMsgId(replyToId: string | undefined, accountId: string): string | undefined {
+  if (!replyToId) return undefined;
+  const limiter = getLimiter(accountId);
+  const result = limiter.checkLimit(replyToId);
+  if (!result.allowed) return undefined;
+  limiter.record(replyToId);
+  return replyToId;
+}
+
+export function registerGateway(accountId: string, gw: QQBotGateway): void {
+  gateways.set(accountId, gw);
+}
+
+export function unregisterGateway(accountId: string): void {
+  gateways.delete(accountId);
+  limiters.delete(accountId);
+}
+
+export function getGateway(accountId: string): QQBotGateway | undefined {
+  return gateways.get(accountId);
+}
+
+// ── 媒体类型映射 ──
+
+export type MediaKind = 'image' | 'voice' | 'video' | 'file';
+
+const MEDIA_KIND_TO_FILE_TYPE: Record<MediaKind, MediaFileType> = {
+  image: MediaFileType.IMAGE,
+  voice: MediaFileType.VOICE,
+  video: MediaFileType.VIDEO,
+  file: MediaFileType.FILE,
+};
+
+export interface SendResult {
+  messageId?: string;
+  error?: string;
+  errorCode?: string;
+  qqBizCode?: number;
+}
+
+// ── 公开 API（channel.ts / deliver-pipeline.ts 调用）──
+
+export async function sendText(params: {
+  to: string;
+  text: string;
+  accountId?: string;
+  replyToId?: string;
+  account: ResolvedQQBotAccount;
+}): Promise<SendResult> {
+  const accountId = params.account.accountId;
+  const gw = gateways.get(accountId);
+  if (!gw) return { error: `Bot "${accountId}" not running` };
+  try {
+    const target = parseTarget(params.to);
+    const msgId = resolveMsgId(params.replyToId, accountId);
+    const result = await gw.sendText(target, params.text, { msgId });
+    return { messageId: result.id };
+  } catch (err: unknown) { return formatError(err); }
+}
+
+export async function sendMedia(params: {
+  to: string;
+  text?: string;
+  mediaUrl: string;
+  mediaKind?: MediaKind;
+  accountId?: string;
+  replyToId?: string;
+  account: ResolvedQQBotAccount;
+}): Promise<SendResult> {
+  const accountId = params.account.accountId;
+  const gw = gateways.get(accountId);
+  if (!gw) return { error: `Bot "${accountId}" not running` };
+  try {
+    const target = parseTarget(params.to);
+    const kind = params.mediaKind ?? 'image';
+    const msgId = resolveMsgId(params.replyToId, accountId);
+    if (kind === 'voice') {
+      const source = resolveVoiceSource(params.mediaUrl);
+      const result = await gw.sendVoice(target, source, { text: params.text, msgId });
+      return { messageId: result.id };
+    }
+    if (kind === 'video') {
+      const result = await gw.sendVideo(target, params.mediaUrl, { text: params.text, msgId });
+      return { messageId: result.id };
+    }
+    if (kind === 'file') {
+      const result = await gw.sendFile(target, params.mediaUrl, { text: params.text, msgId });
+      return { messageId: result.id };
+    }
+    const fileType = MEDIA_KIND_TO_FILE_TYPE[kind];
+    const result = await gw.sendMedia(target, params.mediaUrl, { text: params.text, msgId, fileType });
+    return { messageId: result.id };
+  } catch (err: unknown) { return formatError(err); }
+}
+
+export async function sendVoice(params: {
+  to: string;
+  source: { url?: string; base64?: string };
+  accountId?: string;
+  replyToId?: string;
+  account: ResolvedQQBotAccount;
+}): Promise<SendResult> {
+  const accountId = params.account.accountId;
+  const gw = gateways.get(accountId);
+  if (!gw) return { error: `Bot "${accountId}" not running` };
+  try {
+    const target = parseTarget(params.to);
+    const msgId = resolveMsgId(params.replyToId, accountId);
+    const result = await gw.sendVoice(target, params.source, { msgId });
+    return { messageId: result.id };
+  } catch (err: unknown) { return formatError(err); }
+}
+
+export async function sendVideo(params: {
+  to: string;
+  videoUrl: string;
+  accountId?: string;
+  replyToId?: string;
+  account: ResolvedQQBotAccount;
+}): Promise<SendResult> {
+  const accountId = params.account.accountId;
+  const gw = gateways.get(accountId);
+  if (!gw) return { error: `Bot "${accountId}" not running` };
+  try {
+    const target = parseTarget(params.to);
+    const msgId = resolveMsgId(params.replyToId, accountId);
+    const result = await gw.sendVideo(target, params.videoUrl, { msgId });
+    return { messageId: result.id };
+  } catch (err: unknown) { return formatError(err); }
+}
+
+// ── OutboundService（deliver-pipeline 专用）──
+
+export class OutboundService {
+  constructor(private readonly gw: QQBotGateway, private readonly accountId: string) {}
+
+  async sendText(to: string, text: string, msgId?: string): Promise<SendResult> {
+    try {
+      const target = parseTarget(to);
+      const resolvedMsgId = resolveMsgId(msgId, this.accountId);
+      const result = await this.gw.sendText(target, text, { msgId: resolvedMsgId });
+      return { messageId: result.id };
+    } catch (err: unknown) { return formatError(err); }
+  }
+
+  async sendMedia(to: string, source: string, opts?: { text?: string; msgId?: string; mediaKind?: MediaKind }): Promise<SendResult> {
+    try {
+      const target = parseTarget(to);
+      const kind = opts?.mediaKind ?? 'image';
+      const resolvedMsgId = resolveMsgId(opts?.msgId, this.accountId);
+      if (kind === 'voice') {
+        const voiceSource = resolveVoiceSource(source);
+        const result = await this.gw.sendVoice(target, voiceSource, { text: opts?.text, msgId: resolvedMsgId });
+        return { messageId: result.id };
+      }
+      if (kind === 'video') {
+        const result = await this.gw.sendVideo(target, source, { text: opts?.text, msgId: resolvedMsgId });
+        return { messageId: result.id };
+      }
+      if (kind === 'file') {
+        const result = await this.gw.sendFile(target, source, { text: opts?.text, msgId: resolvedMsgId, fileName: path.basename(source) });
+        return { messageId: result.id };
+      }
+      const fileType = MEDIA_KIND_TO_FILE_TYPE[kind];
+      const result = await this.gw.sendMedia(target, source, { text: opts?.text, msgId: resolvedMsgId, fileType });
+      return { messageId: result.id };
+    } catch (err: unknown) { return formatError(err); }
+  }
+}
+
+// ── 辅助 ──
+
+function resolveVoiceSource(source: string): { url?: string; base64?: string; localPath?: string } {
+  if (source.startsWith('http://') || source.startsWith('https://')) return { url: source };
+  if (source.startsWith('/') || source.startsWith('./') || source.startsWith('../')) return { localPath: source };
+  if (source.startsWith('data:')) {
+    const i = source.indexOf(',');
+    return { base64: i > 0 ? source.slice(i + 1) : source };
+  }
+  return { base64: source };
+}
+
+function formatError(err: unknown): SendResult {
+  if (err instanceof Error) {
+    const result: SendResult = { error: err.message };
+    if ('code' in err) result.errorCode = String((err as any).code);
+    if ('qqBizCode' in err) result.qqBizCode = (err as any).qqBizCode;
+    return result;
+  }
+  return { error: String(err) };
+}

package/src/outbound/reply-limiter.ts

@@ -0,0 +1,128 @@
+/**
+ * 被动回复限额管理
+ *
+ * QQ Bot 被动回复有限额（同一条消息最多回复 N 次，超时后不能再被动回复）。
+ * 当限额耗尽或消息过期时，标记应降级为主动消息（proactive）。
+ */
+
+export interface ReplyLimiterConfig {
+  /** 每条消息最大被动回复次数（默认 4） */
+  limit?: number;
+  /** 消息 ID 过期时间 ms（默认 1 小时） */
+  ttlMs?: number;
+  /** 最大跟踪消息数（LRU 驱逐，默认 10000） */
+  maxTrackedMessages?: number;
+}
+
+export interface ReplyLimitResult {
+  allowed: boolean;
+  remaining: number;
+  shouldFallbackToProactive: boolean;
+  fallbackReason?: 'expired' | 'limit_exceeded';
+}
+
+interface TrackedMessage {
+  count: number;
+  firstSeenAt: number;
+}
+
+/**
+ * 被动回复限额管理器
+ *
+ * @example
+ * ```ts
+ * const limiter = new ReplyLimiter({ limit: 4, ttlMs: 3600_000 });
+ * const result = limiter.checkLimit(messageId);
+ * if (!result.allowed) {
+ *   // 降级为主动消息
+ * } else {
+ *   limiter.record(messageId);
+ *   // 正常被动回复
+ * }
+ * ```
+ */
+export class ReplyLimiter {
+  private readonly limit: number;
+  private readonly ttlMs: number;
+  private readonly maxTracked: number;
+  private readonly messages = new Map<string, TrackedMessage>();
+
+  constructor(config?: ReplyLimiterConfig) {
+    this.limit = config?.limit ?? 4;
+    this.ttlMs = config?.ttlMs ?? 3600_000; // 1 小时
+    this.maxTracked = config?.maxTrackedMessages ?? 10_000;
+  }
+
+  /**
+   * 检查是否允许对指定消息继续被动回复
+   */
+  checkLimit(messageId: string): ReplyLimitResult {
+    const now = Date.now();
+    const tracked = this.messages.get(messageId);
+
+    if (!tracked) {
+      return { allowed: true, remaining: this.limit, shouldFallbackToProactive: false };
+    }
+
+    // TTL 过期
+    if (now - tracked.firstSeenAt > this.ttlMs) {
+      this.messages.delete(messageId);
+      return {
+        allowed: false,
+        remaining: 0,
+        shouldFallbackToProactive: true,
+        fallbackReason: 'expired',
+      };
+    }
+
+    // 限额检查
+    const remaining = Math.max(0, this.limit - tracked.count);
+    if (remaining <= 0) {
+      return {
+        allowed: false,
+        remaining: 0,
+        shouldFallbackToProactive: true,
+        fallbackReason: 'limit_exceeded',
+      };
+    }
+
+    return { allowed: true, remaining, shouldFallbackToProactive: false };
+  }
+
+  /**
+   * 记录一次被动回复
+   */
+  record(messageId: string): void {
+    const now = Date.now();
+    const tracked = this.messages.get(messageId);
+
+    if (tracked) {
+      tracked.count++;
+    } else {
+      // LRU 驱逐
+      if (this.messages.size >= this.maxTracked) {
+        const firstKey = this.messages.keys().next().value;
+        if (firstKey) this.messages.delete(firstKey);
+      }
+      this.messages.set(messageId, { count: 1, firstSeenAt: now });
+    }
+  }
+
+  /**
+   * 获取统计信息
+   */
+  getStats(): { trackedMessages: number; totalReplies: number } {
+    let totalReplies = 0;
+    for (const [, v] of this.messages) {
+      totalReplies += v.count;
+    }
+    return { trackedMessages: this.messages.size, totalReplies };
+  }
+
+  /**
+   * 清除所有跟踪数据
+   */
+  clear(): void {
+    this.messages.clear();
+  }
+}

package/src/outbound/sanitize.ts

@@ -0,0 +1,32 @@
+/**
+ * QQBot 文本消毒
+ *
+ * 剥离框架内部脚手架标签（system-reminder、thinking、reasoning 等），
+ * 保留 Markdown/HTML 用于 QQ Bot Markdown 渲染。
+ */
+
+const INTERNAL_TAGS = [
+  // 框架脚手架标签
+  /<system-reminder\b[^>]*>[\s\S]*?<\/system-reminder>/gi,
+  /<previous_response\b[^>]*>[\s\S]*?<\/previous_response>/gi,
+  /<\s*\/?\s*(?:system-reminder|previous_response)\b[^>]*\/?\s*>/gi,
+  // 模型推理/思考内容
+  // deepseek: `think`...`/think` — 匹配完整标签块，标签名 think 必须完整
+  // 格式说明：deepseek 用 `` ` `` (反引号) 替代 XML 的 `<` `>` 作为标签定界符
+  //   `think`  ≡ <think>  开标签
+  //   `/think` ≡ </think> 闭标签
+  /`think`[\s\S]*?`\/think`/gi,
+  /<\s*\/?\s*think\b[^>]*\/?\s*>/gi,
+  // claude: <thinking>...</thinking>
+  /<thinking\b[^>]*>[\s\S]*?<\/thinking>/gi,
+  /<\s*\/?\s*thinking\b[^>]*\/?\s*>/gi,
+];
+
+/** 剥离内部运行时脚手架块 + 模型推理内容 */
+export function sanitizeQQBotText(text: string): string {
+  let result = text;
+  for (const re of INTERNAL_TAGS) {
+    result = result.replace(re, '');
+  }
+  return result.trim();
+}

package/src/outbound/streaming-controller.ts

@@ -0,0 +1,228 @@
+/**
+ * QQ Bot 流式消息控制器
+ *
+ * 核心约束：QQ 流式 API 替换模式下，已下发文本的**前缀不可变更**。
+ *
+ * 状态机：
+ *   IDLE → (first chunk) → STREAMING → (complete) → DONE
+ *                                      → (prefix changed) → DONE
+ *                                      → (new reply) → IDLE → …
+ *
+ * onPartialReply(text) 输入：模型全量文本，持续增长。
+ * finalize()           标记：框架通知回复结束，用 lastAccepted 收尾。
+ */
+
+import type { ReplyTarget, StreamSession } from '@tencent-connect/qqbot-nodejs';
+import type { PluginLogger } from '../utils/plugin-logger.js';
+import type { QQBotGateway } from '../gateway/qqbot-gateway.js';
+
+// ── 类型 ──
+
+export type StreamingPhase = 'idle' | 'streaming' | 'done' | 'failed';
+
+export interface StreamingControllerDeps {
+  gateway: QQBotGateway;
+  target: ReplyTarget;
+  accountId: string;
+  replyToId: string;
+  log?: PluginLogger;
+}
+
+// ── 控制器 ──
+
+export class StreamingController {
+  private phase: StreamingPhase = 'idle';
+  private session: StreamSession | null = null;
+
+  /** QQ 已接受的最新文本 — 单源真理 */
+  private lastAcceptedFull = '';
+
+  /** 已成功发送的分片数（降级：=0 则走静态消息兜底） */
+  private sentChunkCount = 0;
+
+  /** 同步标志：收到第一个 onPartialReply 即置 true（不等 async 完成） */
+  private _hasStarted = false;
+
+  /** 串行队列 */
+  private chain: Promise<unknown> = Promise.resolve();
+
+  constructor(private readonly deps: StreamingControllerDeps) {}
+
+  // ── 公共访问器 ──
+
+  get currentPhase(): StreamingPhase { return this.phase; }
+
+  /** 是否已成功发送至少一个流式分片 */
+  get hasSentChunks(): boolean { return this.sentChunkCount > 0; }
+
+  /** 同步标志：流式已启动（不等异步完成），用于 final 去重 */
+  get hasStarted(): boolean { return this._hasStarted; }
+
+  get isTerminal(): boolean {
+    return this.phase === 'done' || this.phase === 'failed';
+  }
+
+  get shouldFallbackToStatic(): boolean {
+    return this.isTerminal && this.sentChunkCount === 0;
+  }
+
+  // ── 入口 ──
+
+  onPartialReply(text: string): Promise<void> {
+    this._hasStarted = true; // 同步置位：不等异步发送，final 就能感知流式已启动
+    this.chain = this.chain.then(() => this.handleChunk(text)).catch((err) => {
+      this.deps.log?.error(`onPartialReply error: ${err instanceof Error ? err.message : String(err)}`);
+      this.transition('failed', 'chunk_error');
+    });
+    return this.chain as Promise<void>;
+  }
+
+  finalize(): Promise<void> {
+    this.chain = this.chain.then(() => this.handleFinalize()).catch((err) => {
+      this.deps.log?.error(`finalize error: ${err instanceof Error ? err.message : String(err)}`);
+      this.transition('failed', 'finalize_error');
+    });
+    return this.chain as Promise<void>;
+  }
+
+  async abort(reason?: string): Promise<void> {
+    if (this.isTerminal) return;
+    this.deps.log?.warn(`aborting stream reason=${reason ?? 'manual'} sent=${this.sentChunkCount}`);
+    if (this.session) {
+      try { await this.session.complete(); } catch (e) {
+        this.deps.log?.error(`abort complete failed: ${e instanceof Error ? e.message : String(e)}`);
+      }
+      this.session = null;
+    }
+    this.transition('failed', `abort:${reason ?? 'manual'}`);
+  }
+
+  // ── 核心逻辑 ──
+
+  private async handleChunk(text: string): Promise<void> {
+    if (this.isTerminal || !text) return;
+
+    // 正常续写：新文本前缀匹配（含空白归一化）
+    if (prefixMatches(this.lastAcceptedFull, text)) {
+      if (text.length !== this.lastAcceptedFull.length) {
+        await this.sendUpdate(text);
+      }
+      return;
+    }
+
+    // 无已下发内容 → 首发
+    if (!this.lastAcceptedFull) {
+      await this.sendUpdate(text);
+      return;
+    }
+
+    // 前缀不匹配 — 长度回退 → 新回复（工具调用后）
+    if (text.length < this.lastAcceptedFull.length) {
+      this.deps.log?.info(`new reply: lastAccepted=${this.lastAcceptedFull.length}→chunk=${text.length}`);
+      await this.completeSession('new_reply');
+      this.lastAcceptedFull = '';
+      await this.sendUpdate(text);
+      return;
+    }
+
+    // 前缀不匹配但长度增长 → 模型重写尾部，同一条流追加
+    const commonLen = longestCommonPrefix(this.lastAcceptedFull, text);
+    const extra = text.slice(Math.max(commonLen, 0));
+    const merged = this.lastAcceptedFull + extra;
+    this.deps.log?.warn(
+      `prefix retry: lastAccepted=${this.lastAcceptedFull.length}→chunk=${text.length} common=${commonLen} extra=${extra.length}, appending`,
+    );
+    await this.sendUpdate(merged);
+  }
+
+  private async handleFinalize(): Promise<void> {
+    if (this.isTerminal) return;
+
+    // 用已下发文本收尾 — 不用框架 deliver 的文本（框架可能追加 ⚠️ 标记）
+    if (this.session) {
+      await this.completeSession();
+      this.transition('done', 'finalize');
+      this.deps.log?.info(`stream done chunks=${this.sentChunkCount} chars=${this.lastAcceptedFull.length}`);
+      return;
+    }
+
+    // 无会话 — 视有无下发决定终态
+    if (this.sentChunkCount > 0) {
+      this.transition('done', 'finalize:no_session');
+    } else {
+      this.transition('failed', 'finalize:fallback');
+    }
+  }
+
+  // ── QQ 交互 ──
+
+  private async sendUpdate(text: string): Promise<void> {
+    if (!this.session) {
+      this.session = this.deps.gateway.openStream(this.deps.target, this.deps.replyToId);
+      this.transition('streaming', 'first_chunk');
+      this.deps.log?.info(`stream opened (firstChunk=${text.length})`);
+    }
+    try {
+      await this.session.update(text);
+      this.lastAcceptedFull = text;
+      this.sentChunkCount++;
+    } catch (err) {
+      this.deps.log?.error(`update failed (len=${text.length}): ${err instanceof Error ? err.message : String(err)}`);
+      this.session = null;
+      this.transition('failed', 'update_error');
+    }
+  }
+
+  private async completeSession(reason?: string): Promise<void> {
+    if (!this.session) return;
+    this.deps.log?.info(`completing stream (sent=${this.sentChunkCount} chars=${this.lastAcceptedFull.length} reason=${reason ?? 'done'})`);
+    try {
+      await this.session.complete();
+    } catch (err) {
+      this.deps.log?.error(`complete failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    this.session = null;
+  }
+
+  // ── 状态机 ──
+
+  private transition(next: StreamingPhase, reason: string): void {
+    if (this.phase === next) return;
+    this.deps.log?.info(`phase: ${this.phase} → ${next} (${reason})`);
+    this.phase = next;
+  }
+}
+
+/** 归一化空白符：连续换行/空格合并为单个空格 */
+function normalizeWs(s: string): string {
+  return s.replace(/\s+/g, ' ');
+}
+
+/** 忽略空白前缀比较 */
+function prefixMatches(accepted: string, incoming: string): boolean {
+  if (incoming.startsWith(accepted)) return true;
+  return normalizeWs(incoming).startsWith(normalizeWs(accepted));
+}
+
+function longestCommonPrefix(a: string, b: string): number {
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  return i;
+}
+
+// ── 入口判断 ──
+
+import type { ResolvedQQBotAccount } from '../types.js';
+
+export function shouldUseStreaming(
+  account: ResolvedQQBotAccount,
+  targetScope: 'c2c' | 'group' | 'channel',
+): boolean {
+  if (targetScope !== 'c2c') return false;
+  const streaming = account.config?.streaming;
+  if (typeof streaming === 'boolean') return streaming;
+  if (streaming && typeof streaming === 'object') {
+    return (streaming as any).mode !== 'off';
+  }
+  return false;
+}

package/src/outbound/target.ts

@@ -0,0 +1,63 @@
+/**
+ * 出站目标地址解析
+ *
+ * 将 OpenClaw 规范的目标地址字符串（如 qqbot:c2c:xxx / qqbot:group:xxx）
+ * 转换为 SDK 的 ReplyTarget 结构。
+ *
+ * 也导出共享的正则常量供 channel.ts messaging 段复用。
+ */
+import type { ReplyTarget } from '@tencent-connect/qqbot-nodejs';
+
+// ── 共享正则常量 ──
+
+/** 32 位十六进制 OpenID（不带连字符） */
+export const OPENID_HEX_RE = /^[0-9a-fA-F]{32}$/;
+
+/** UUID 格式的 OpenID（带连字符） */
+export const OPENID_UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+
+/** 带 qqbot: 前缀的目标格式 */
+export const QQBOT_PREFIX_RE = /^qqbot:(c2c|group|channel):/i;
+
+/** 不带前缀但有 scope 标识 */
+export const SCOPE_PREFIX_RE = /^(c2c|group|channel):/i;
+
+/**
+ * 判断 ID 是否看起来像 QQ Bot 目标格式
+ */
+export function isQQBotTarget(id: string): boolean {
+  if (QQBOT_PREFIX_RE.test(id)) return true;
+  if (SCOPE_PREFIX_RE.test(id)) return true;
+  if (OPENID_HEX_RE.test(id)) return true;
+  return OPENID_UUID_RE.test(id);
+}
+
+/**
+ * 规范化目标地址字符串
+ */
+export function normalizeTarget(target: string): string | undefined {
+  const id = target.replace(/^qqbot:/i, '');
+  if (id.startsWith('c2c:') || id.startsWith('group:') || id.startsWith('channel:')) {
+    return `qqbot:${id}`;
+  }
+  if (OPENID_HEX_RE.test(id)) return `qqbot:c2c:${id}`;
+  if (OPENID_UUID_RE.test(id)) return `qqbot:c2c:${id}`;
+  return undefined;
+}
+
+/**
+ * 解析目标地址字符串为 SDK ReplyTarget
+ */
+export function parseTarget(to: string): ReplyTarget {
+  const id = to.replace(/^qqbot:/i, '');
+
+  if (id.startsWith('c2c:')) {
+    return { scope: 'c2c', targetId: id.slice(4) };
+  }
+  if (id.startsWith('group:')) {
+    return { scope: 'group', targetId: id.slice(6) };
+  }
+
+  // 默认当作 c2c（32 位十六进制 / UUID 格式的 openid）
+  return { scope: 'c2c', targetId: id };
+}