/**
 * 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;
}