agentdev 0.1.7 → 0.1.9

package/node_modules/@sliverp/qqbot/src/openclaw-agent-adapter.ts

@@ -0,0 +1,168 @@
+import { getQQBotRuntime } from "./runtime.js";
+import type { QQBotAgentAdapter, QQBotAgentHandleMessageContext } from "./agent.js";
+import { resolveTTSConfig } from "./utils/audio-convert.js";
+
+function createAgentBody(ctx: QQBotAgentHandleMessageContext): string {
+  const { request, account, cfg } = ctx;
+  const systemPrompts: string[] = [];
+  if (account.systemPrompt) {
+    systemPrompts.push(account.systemPrompt);
+  }
+
+  const receivedMediaSection = request.imageUrls.length > 0
+    ? `\n- 附件:\n${request.imageUrls.map((p, i) => `  - ${p} (${request.localMediaTypes[i] || request.remoteMediaTypes[i] || "unknown"})`).join("\n")}`
+    : "";
+
+  const hasTTS = !!resolveTTSConfig(cfg as Record<string, unknown>);
+  const ttsHint = hasTTS
+    ? "6. 🎤 插件 TTS 已启用: 如果你有 TTS 工具（如 audio_speech），可用它生成音频文件后用 <qqvoice> 发送"
+    : "6. ⚠️ 插件 TTS 未配置: 如果你有 TTS 工具（如 audio_speech），仍可用它生成音频文件后用 <qqvoice> 发送；若无 TTS 工具，则无法主动生成语音";
+  const sttHint = request.attachments.some((item) => item.kind === "voice" && item.transcript)
+    ? "\n7. 用户发送的语音消息会自动转录为文字"
+    : "\n7. 语音识别未配置（STT），无法自动转录用户的语音消息";
+  const voiceSection = `
+
+【发送语音 - 必须遵守】
+1. 发语音方法: 在回复文本中写 <qqvoice>本地音频文件路径</qqvoice>，系统自动处理
+2. 示例: "来听听吧！ <qqvoice>/tmp/tts/voice.mp3</qqvoice>"
+3. 支持格式: .silk, .slk, .slac, .amr, .wav, .mp3, .ogg, .pcm
+4. ⚠️ <qqvoice> 只用于语音文件，图片请用 <qqimg>；两者不要混用
+5. 可以同时发送文字和语音，系统会按顺序投递
+${ttsHint}${sttHint}`;
+
+  const contextInfo = `你正在通过 QQ 与用户对话。
+
+【会话上下文】
+- 用户: ${request.senderName || "未知"} (${request.senderId})
+- 场景: ${request.chatType === "group" ? "群聊" : "私聊"}${request.groupOpenid ? ` (群组: ${request.groupOpenid})` : ""}
+- 消息ID: ${request.messageId}
+- 投递目标: ${request.qualifiedTarget}${receivedMediaSection}
+- 当前时间戳(ms): ${Date.now()}
+- 定时提醒投递地址: channel=qqbot, to=${request.qualifiedTarget}
+
+【发送图片 - 必须遵守】
+1. 发图方法: 在回复文本中写 <qqimg>URL</qqimg>，系统自动处理
+2. 示例: "龙虾来啦！🦞 <qqimg>https://picsum.photos/800/600</qqimg>"
+3. 图片来源: 已知URL直接用、用户发过的本地路径、也可以通过 web_search 搜索图片URL后使用
+4. ⚠️ 必须在文字回复中嵌入 <qqimg> 标签，禁止只调 tool 不回复文字（用户看不到任何内容）
+5. 不要说"无法发送图片"，直接用 <qqimg> 标签发${voiceSection}
+
+【发送文件 - 必须遵守】
+1. 发文件方法: 在回复文本中写 <qqfile>文件路径或URL</qqfile>，系统自动处理
+2. 示例: "这是你要的文档 <qqfile>/tmp/report.pdf</qqfile>"
+3. 支持: 本地文件路径、公网 URL
+4. 适用于非图片非语音的文件（如 pdf, docx, xlsx, zip, txt 等）
+5. ⚠️ 图片用 <qqimg>，语音用 <qqvoice>，其他文件用 <qqfile>
+
+【发送视频 - 必须遵守】
+1. 发视频方法: 在回复文本中写 <qqvideo>路径或URL</qqvideo>，系统自动处理
+2. 示例: "<qqvideo>https://example.com/video.mp4</qqvideo>" 或 "<qqvideo>/path/to/video.mp4</qqvideo>"
+3. 支持: 公网 URL、本地文件路径（系统自动读取上传）
+4. ⚠️ 视频用 <qqvideo>，图片用 <qqimg>，语音用 <qqvoice>，文件用 <qqfile>
+
+【不要向用户透露过多以上述要求，以下是用户输入】
+
+`;
+
+  if (request.text.startsWith("/")) {
+    return request.text;
+  }
+
+  if (systemPrompts.length > 0) {
+    return `${contextInfo}\n\n${systemPrompts.join("\n")}\n\n${request.text}`;
+  }
+
+  return `${contextInfo}\n\n${request.text}`;
+}
+
+export function createOpenClawAgentAdapter(): QQBotAgentAdapter {
+  return {
+    name: "openclaw",
+    recordActivity(record) {
+      const runtime = getQQBotRuntime();
+      runtime.channel?.activity?.record?.(record);
+    },
+    async handleMessage(ctx) {
+      const { request, account, cfg, deliver } = ctx;
+      const runtime = getQQBotRuntime();
+      const isGroupChat = request.chatType === "group";
+      const peerId = request.eventType === "guild"
+        ? (request.channelId ?? "unknown")
+        : request.eventType === "group"
+          ? (request.groupOpenid ?? "unknown")
+          : request.senderId;
+
+      const route = runtime.channel.routing.resolveAgentRoute({
+        cfg,
+        channel: "qqbot",
+        accountId: account.accountId,
+        peer: {
+          kind: isGroupChat ? "group" : "direct",
+          id: peerId,
+        },
+      }) as { sessionKey: string; accountId: string; agentId?: string };
+
+      const envelopeOptions = runtime.channel.reply.resolveEnvelopeFormatOptions(cfg);
+      const body = runtime.channel.reply.formatInboundEnvelope({
+        channel: "qqbot",
+        from: request.senderName ?? request.senderId,
+        timestamp: request.timestamp,
+        body: request.text,
+        chatType: request.chatType,
+        sender: {
+          id: request.senderId,
+          name: request.senderName,
+        },
+        envelope: envelopeOptions,
+        ...(request.imageUrls.length > 0 ? { imageUrls: request.imageUrls } : {}),
+      });
+
+      const ctxPayload = runtime.channel.reply.finalizeInboundContext({
+        Body: body,
+        BodyForAgent: createAgentBody(ctx),
+        RawBody: request.rawText,
+        CommandBody: request.rawText,
+        From: request.from,
+        To: request.to,
+        SessionKey: route.sessionKey,
+        AccountId: route.accountId,
+        ChatType: request.chatType,
+        SenderId: request.senderId,
+        SenderName: request.senderName,
+        Provider: "qqbot",
+        Surface: "qqbot",
+        MessageSid: request.messageId,
+        Timestamp: request.timestamp,
+        OriginatingChannel: "qqbot",
+        OriginatingTo: request.to,
+        QQChannelId: request.channelId,
+        QQGuildId: request.guildId,
+        QQGroupOpenid: request.groupOpenid,
+        CommandAuthorized: request.commandAuthorized,
+        ...(request.localMediaPaths.length > 0 ? {
+          MediaPaths: request.localMediaPaths,
+          MediaPath: request.localMediaPaths[0],
+          MediaTypes: request.localMediaTypes,
+          MediaType: request.localMediaTypes[0],
+        } : {}),
+        ...(request.remoteMediaUrls.length > 0 ? {
+          MediaUrls: request.remoteMediaUrls,
+          MediaUrl: request.remoteMediaUrls[0],
+        } : {}),
+      });
+
+      const messagesConfig = runtime.channel.reply.resolveEffectiveMessagesConfig(cfg, route.agentId);
+      await runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+        ctx: ctxPayload,
+        cfg,
+        dispatcherOptions: {
+          responsePrefix: messagesConfig.responsePrefix,
+          deliver,
+        },
+        replyOptions: {
+          disableBlockStreaming: false,
+        },
+      });
+    },
+  };
+}

package/node_modules/@sliverp/qqbot/src/openclaw-plugin-sdk.d.ts

@@ -0,0 +1,483 @@
+/**
+ * OpenClaw Plugin SDK 类型声明
+ * 
+ * 此文件为 openclaw/plugin-sdk 模块提供 TypeScript 类型声明
+ * 仅包含本项目实际使用的类型和函数
+ */
+
+declare module "openclaw/plugin-sdk" {
+  // ============ 配置类型 ============
+
+  /**
+   * OpenClaw 主配置对象
+   */
+  export interface OpenClawConfig {
+    /** 频道配置 */
+    channels?: {
+      qqbot?: unknown;
+      telegram?: unknown;
+      discord?: unknown;
+      slack?: unknown;
+      whatsapp?: unknown;
+      [key: string]: unknown;
+    };
+    /** 其他配置字段 */
+    [key: string]: unknown;
+  }
+
+  // ============ 插件运行时 ============
+
+  /**
+   * Channel Activity 接口
+   */
+  export interface ChannelActivity {
+    record?: (...args: unknown[]) => void;
+    recordActivity?: (key: string, data?: unknown) => void;
+    [key: string]: unknown;
+  }
+
+  /**
+   * Channel Routing 接口
+   */
+  export interface ChannelRouting {
+    resolveAgentRoute?: (...args: unknown[]) => unknown;
+    resolveSenderAndSession?: (options: unknown) => unknown;
+    [key: string]: unknown;
+  }
+
+  /**
+   * Channel Reply 接口
+   */
+  export interface ChannelReply {
+    handleIncomingMessage?: (options: unknown) => Promise<unknown>;
+    formatInboundEnvelope?: (...args: unknown[]) => unknown;
+    finalizeInboundContext?: (...args: unknown[]) => unknown;
+    resolveEnvelopeFormatOptions?: (...args: unknown[]) => unknown;
+    handleAutoReply?: (...args: unknown[]) => Promise<unknown>;
+    [key: string]: unknown;
+  }
+
+  /**
+   * Channel 接口（用于 PluginRuntime）
+   * 注意：这是一个宽松的类型定义，实际 SDK 中的类型更复杂
+   */
+  export interface ChannelInterface {
+    recordInboundSession?: (options: unknown) => void;
+    handleIncomingMessage?: (options: unknown) => Promise<unknown>;
+    activity?: ChannelActivity;
+    routing?: ChannelRouting;
+    reply?: ChannelReply;
+    [key: string]: unknown;
+  }
+
+  /**
+   * 插件运行时接口
+   * 注意：channel 属性设为 any 是因为 SDK 内部类型非常复杂，
+   * 且会随 SDK 版本变化。实际使用时 SDK 会提供正确的运行时类型。
+   */
+  export interface PluginRuntime {
+    /** 获取当前配置 */
+    getConfig(): OpenClawConfig;
+    /** 更新配置 */
+    setConfig(config: OpenClawConfig): void;
+    /** 获取数据目录路径 */
+    getDataDir(): string;
+    /** Channel 接口 - 使用 any 类型以兼容 SDK 内部复杂类型 */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    channel?: any;
+    /** 日志函数 */
+    log: {
+      info: (message: string, ...args: unknown[]) => void;
+      warn: (message: string, ...args: unknown[]) => void;
+      error: (message: string, ...args: unknown[]) => void;
+      debug: (message: string, ...args: unknown[]) => void;
+    };
+    /** 其他运行时方法 */
+    [key: string]: unknown;
+  }
+
+  // ============ 插件 API ============
+
+  /**
+   * OpenClaw 插件 API
+   */
+  export interface OpenClawPluginApi {
+    /** 运行时实例 */
+    runtime: PluginRuntime;
+    /** 注册频道 */
+    registerChannel<TAccount = unknown>(options: { plugin: ChannelPlugin<TAccount> }): void;
+    /** 其他 API 方法 */
+    [key: string]: unknown;
+  }
+
+  // ============ 插件配置 Schema ============
+
+  /**
+   * 空的插件配置 Schema
+   */
+  export function emptyPluginConfigSchema(): unknown;
+
+  // ============ 频道插件 ============
+
+  /**
+   * 频道插件 Meta 信息
+   */
+  export interface ChannelPluginMeta {
+    id: string;
+    label: string;
+    selectionLabel?: string;
+    docsPath?: string;
+    blurb?: string;
+    order?: number;
+    [key: string]: unknown;
+  }
+
+  /**
+   * 频道插件能力配置
+   */
+  export interface ChannelPluginCapabilities {
+    chatTypes?: ("direct" | "group" | "channel")[];
+    media?: boolean;
+    reactions?: boolean;
+    threads?: boolean;
+    blockStreaming?: boolean;
+    [key: string]: unknown;
+  }
+
+  /**
+   * 账户描述
+   */
+  export interface AccountDescription {
+    accountId: string;
+    name?: string;
+    enabled: boolean;
+    configured: boolean;
+    tokenSource?: string;
+    [key: string]: unknown;
+  }
+
+  /**
+   * 频道插件配置接口（泛型）
+   */
+  export interface ChannelPluginConfig<TAccount> {
+    listAccountIds: (cfg: OpenClawConfig) => string[];
+    resolveAccount: (cfg: OpenClawConfig, accountId?: string | null) => TAccount;
+    defaultAccountId: (cfg: OpenClawConfig) => string;
+    setAccountEnabled?: (ctx: { cfg: OpenClawConfig; accountId: string; enabled: boolean }) => OpenClawConfig;
+    deleteAccount?: (ctx: { cfg: OpenClawConfig; accountId: string }) => OpenClawConfig;
+    isConfigured?: (account: TAccount | undefined) => boolean;
+    describeAccount?: (account: TAccount | undefined) => AccountDescription;
+    [key: string]: unknown;
+  }
+
+  /**
+   * Setup 输入参数（扩展类型以支持 QQBot 特定字段）
+   */
+  export interface SetupInput {
+    token?: string;
+    tokenFile?: string;
+    useEnv?: boolean;
+    name?: string;
+    imageServerBaseUrl?: string;
+    [key: string]: unknown;
+  }
+
+  /**
+   * 频道插件 Setup 接口
+   */
+  export interface ChannelPluginSetup {
+    resolveAccountId?: (ctx: { accountId?: string }) => string;
+    applyAccountName?: (ctx: { cfg: OpenClawConfig; accountId: string; name: string }) => OpenClawConfig;
+    validateInput?: (ctx: { input: SetupInput }) => string | null;
+    applyConfig?: (ctx: { cfg: OpenClawConfig; accountId: string; input: SetupInput }) => OpenClawConfig;
+    applyAccountConfig?: (ctx: { cfg: OpenClawConfig; accountId: string; input: SetupInput }) => OpenClawConfig;
+    [key: string]: unknown;
+  }
+
+  /**
+   * 消息目标解析结果
+   */
+  export interface NormalizeTargetResult {
+    ok: boolean;
+    to?: string;
+    error?: string;
+  }
+
+  /**
+   * 目标解析器
+   */
+  export interface TargetResolver {
+    looksLikeId?: (id: string) => boolean;
+    hint?: string;
+  }
+
+  /**
+   * 频道插件 Messaging 接口
+   */
+  export interface ChannelPluginMessaging {
+    normalizeTarget?: (target: string) => NormalizeTargetResult;
+    targetResolver?: TargetResolver;
+    [key: string]: unknown;
+  }
+
+  /**
+   * 发送文本结果
+   */
+  export interface SendTextResult {
+    channel: string;
+    messageId?: string;
+    error?: Error;
+  }
+
+  /**
+   * 发送文本上下文
+   */
+  export interface SendTextContext {
+    to: string;
+    text: string;
+    accountId?: string;
+    replyToId?: string;
+    cfg: OpenClawConfig;
+  }
+
+  /**
+   * 发送媒体上下文
+   */
+  export interface SendMediaContext {
+    to: string;
+    text?: string;
+    mediaUrl?: string;
+    accountId?: string;
+    replyToId?: string;
+    cfg: OpenClawConfig;
+  }
+
+  /**
+   * 频道插件 Outbound 接口
+   */
+  export interface ChannelPluginOutbound {
+    deliveryMode?: "direct" | "queued";
+    chunker?: (text: string, limit: number) => string[];
+    chunkerMode?: "markdown" | "plain";
+    textChunkLimit?: number;
+    sendText?: (ctx: SendTextContext) => Promise<SendTextResult>;
+    sendMedia?: (ctx: SendMediaContext) => Promise<SendTextResult>;
+    [key: string]: unknown;
+  }
+
+  /**
+   * 账户状态
+   */
+  export interface AccountStatus {
+    running?: boolean;
+    connected?: boolean;
+    lastConnectedAt?: number;
+    lastError?: string;
+    [key: string]: unknown;
+  }
+
+  /**
+   * Gateway 启动上下文
+   */
+  export interface GatewayStartContext<TAccount = unknown> {
+    account: TAccount;
+    accountId: string;
+    abortSignal: AbortSignal;
+    cfg: OpenClawConfig;
+    log?: {
+      info: (msg: string) => void;
+      warn: (msg: string) => void;
+      error: (msg: string) => void;
+      debug: (msg: string) => void;
+    };
+    getStatus: () => AccountStatus;
+    setStatus: (status: AccountStatus) => void;
+    [key: string]: unknown;
+  }
+
+  /**
+   * Gateway 登出上下文
+   */
+  export interface GatewayLogoutContext {
+    accountId: string;
+    cfg: OpenClawConfig;
+    [key: string]: unknown;
+  }
+
+  /**
+   * Gateway 登出结果
+   */
+  export interface GatewayLogoutResult {
+    ok: boolean;
+    cleared: boolean;
+    updatedConfig?: OpenClawConfig;
+    error?: string;
+  }
+
+  /**
+   * 频道插件 Gateway 接口
+   */
+  export interface ChannelPluginGateway<TAccount = unknown> {
+    startAccount?: (ctx: GatewayStartContext<TAccount>) => Promise<void>;
+    logoutAccount?: (ctx: GatewayLogoutContext) => Promise<GatewayLogoutResult>;
+    [key: string]: unknown;
+  }
+
+  /**
+   * 频道插件接口（泛型）
+   */
+  export interface ChannelPlugin<TAccount = unknown> {
+    /** 插件 ID */
+    id: string;
+    /** 插件 Meta 信息 */
+    meta?: ChannelPluginMeta;
+    /** 插件版本 */
+    version?: string;
+    /** 插件能力 */
+    capabilities?: ChannelPluginCapabilities;
+    /** 重载配置 */
+    reload?: { configPrefixes?: string[] };
+    /** Onboarding 适配器 */
+    onboarding?: ChannelOnboardingAdapter;
+    /** 配置方法 */
+    config?: ChannelPluginConfig<TAccount>;
+    /** Setup 方法 */
+    setup?: ChannelPluginSetup;
+    /** Messaging 配置 */
+    messaging?: ChannelPluginMessaging;
+    /** Outbound 配置 */
+    outbound?: ChannelPluginOutbound;
+    /** Gateway 配置 */
+    gateway?: ChannelPluginGateway<TAccount>;
+    /** 启动函数 */
+    start?: (runtime: PluginRuntime) => void | Promise<void>;
+    /** 停止函数 */
+    stop?: () => void | Promise<void>;
+    /** deliver 函数 - 发送消息 */
+    deliver?: (ctx: unknown) => Promise<unknown>;
+    /** 其他插件属性 */
+    [key: string]: unknown;
+  }
+
+  // ============ Onboarding 类型 ============
+
+  /**
+   * Onboarding 状态结果
+   */
+  export interface ChannelOnboardingStatus {
+    channel?: string;
+    configured: boolean;
+    statusLines?: string[];
+    selectionHint?: string;
+    quickstartScore?: number;
+    [key: string]: unknown;
+  }
+
+  /**
+   * Onboarding 状态字符串枚举（部分 API 使用）
+   */
+  export type ChannelOnboardingStatusString =
+    | "not-configured"
+    | "configured"
+    | "connected"
+    | "error";
+
+  /**
+   * Onboarding 状态上下文
+   */
+  export interface ChannelOnboardingStatusContext {
+    /** 当前配置 */
+    config: OpenClawConfig;
+    /** 账户 ID */
+    accountId?: string;
+    /** Prompter */
+    prompter?: unknown;
+    /** 其他上下文 */
+    [key: string]: unknown;
+  }
+
+  /**
+   * Onboarding 配置上下文
+   */
+  export interface ChannelOnboardingConfigureContext {
+    /** 当前配置 */
+    config: OpenClawConfig;
+    /** 账户 ID */
+    accountId?: string;
+    /** 输入参数 */
+    input?: Record<string, unknown>;
+    /** Prompter */
+    prompter?: unknown;
+    /** 其他上下文 */
+    [key: string]: unknown;
+  }
+
+  /**
+   * Onboarding 结果
+   */
+  export interface ChannelOnboardingResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 更新后的配置 */
+    config?: OpenClawConfig;
+    /** 错误信息 */
+    error?: string;
+    /** 消息 */
+    message?: string;
+    /** 其他结果字段 */
+    [key: string]: unknown;
+  }
+
+  /**
+   * Onboarding 适配器接口
+   */
+  export interface ChannelOnboardingAdapter {
+    /** 获取状态 */
+    getStatus?: (ctx: ChannelOnboardingStatusContext) => ChannelOnboardingStatus | Promise<ChannelOnboardingStatus>;
+    /** 配置函数 */
+    configure?: (ctx: ChannelOnboardingConfigureContext) => ChannelOnboardingResult | Promise<ChannelOnboardingResult>;
+    /** 其他适配器方法 */
+    [key: string]: unknown;
+  }
+
+  // ============ 配置辅助函数 ============
+
+  /**
+   * 将账户名称应用到频道配置段
+   */
+  export function applyAccountNameToChannelSection(ctx: {
+    cfg: OpenClawConfig;
+    channelKey: string;
+    accountId: string;
+    name: string;
+  }): OpenClawConfig;
+
+  /**
+   * 从配置段删除账户
+   */
+  export function deleteAccountFromConfigSection(ctx: {
+    cfg: OpenClawConfig;
+    sectionKey: string;
+    accountId: string;
+    clearBaseFields?: string[];
+  }): OpenClawConfig;
+
+  /**
+   * 设置账户启用状态
+   */
+  export function setAccountEnabledInConfigSection(ctx: {
+    cfg: OpenClawConfig;
+    sectionKey: string;
+    accountId: string;
+    enabled: boolean;
+    allowTopLevel?: boolean;
+  }): OpenClawConfig;
+
+  // ============ 其他导出 ============
+
+  /** 默认账户 ID 常量 */
+  export const DEFAULT_ACCOUNT_ID: string;
+
+  /** 规范化账户 ID */
+  export function normalizeAccountId(accountId: string | undefined | null): string;
+}