@cmach_socket/opencode-qq-bot 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,245 @@
+import { Plugin } from "@opencode/plugin"
+import type { GroupMessageEvent, MessageEvent } from "@naplink/naplink"
+import { type ChatTarget, configuredTargets, isTargetEnabled, targetKey, targetLabel } from "./chat"
+import { resolveConfig, type QQBotConfig } from "./config"
+import { claimInstance } from "./instance"
+import { createLogger } from "./logger"
+import { QQClient } from "./naplink/client"
+import { createMediaStore } from "./naplink/media"
+import { mentionsUser, renderMessage, resolveUserName, shouldProcess } from "./naplink/render"
+import { SessionManager } from "./session/manager"
+import {
+  buildSystemPrompt,
+  currentTimeText,
+  loadSoul,
+  PROACTIVE_HINT,
+  resolveSoulPath,
+  packageDirectory,
+} from "./session/prompt"
+import { proactiveTickProbability } from "./session/proactive"
+import { registerTools } from "./tools/qq"
+
+const RETRY_DELAY_MS = 1000
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+export default Plugin.define({
+  id: "opencode-qq-bot",
+  async setup(ctx) {
+    const logger = createLogger("[qq-bot]")
+    let config: QQBotConfig
+    try {
+      config = resolveConfig(ctx.options, process.env, (message) => logger.warn(message))
+    } catch (error) {
+      logger.error(error instanceof Error ? error.message : String(error))
+      return
+    }
+
+    if (config.groups.length === 0 && config.users.length === 0) {
+      logger.warn(
+        "未配置目标群号或私聊 QQ 号，插件不会响应任何消息（请设置 groups/users 或 QQ_TARGET_GROUPS/QQ_TARGET_USERS）",
+      )
+    }
+
+    // OpenCode 重新加载插件时未必调用旧的清理函数，接管同一连接的单例并主动卸载旧实例。
+    const { previous, lease } = claimInstance(`${ctx.location.directory}\n${config.napcat.url}`)
+    if (previous?.dispose) {
+      try {
+        await previous.dispose()
+      } catch (error) {
+        logger.error("卸载旧插件实例失败", error)
+      }
+    }
+
+    const soulPath = resolveSoulPath(config.soulPath, packageDirectory(), process.cwd())
+    const soul = await loadSoul(soulPath)
+    if (!soul) logger.warn(`角色设定读取失败：${soulPath ?? "(未找到)"}`)
+    const systemPrompt = buildSystemPrompt(soul)
+
+    const client = new QQClient(config.napcat, logger)
+    const manager = new SessionManager(ctx, config, logger)
+    await manager.load()
+    const media = await createMediaStore(logger)
+    const mediaCleanup = setInterval(
+      () => {
+        void media.cleanup()
+      },
+      60 * 60 * 1000,
+    )
+    const mediaHandle = mediaCleanup as { unref?: () => void }
+    mediaHandle.unref?.()
+    const toolRegistration = await registerTools({ ctx, config, logger, manager, client })
+    const nameCache = new Map<string, { name: string; expires: number }>()
+
+    // 系统提示：角色设定、当前时间、本轮是否必须回复。
+    const contextRegistration = await ctx.session.hook("context", (event) => {
+      const target = manager.targetForSession(event.sessionID)
+      if (target === undefined) return
+      event.system.push({ type: "text", text: systemPrompt })
+      event.system.push({ type: "text", text: `当前时间：${currentTimeText()}` })
+      const turn = manager.currentTurn(event.sessionID)
+      const destination = target.kind === "group" ? "群里" : "私聊里"
+      event.system.push({
+        type: "text",
+        text: turn?.proactive
+          ? `这是一次主动发起话题，必须调用 qq_send_message 把话题发到${destination}。`
+          : turn?.atMe
+            ? target.kind === "private"
+              ? "这是一条私聊消息，必须回复。"
+              : "你被 @ 了，必须回复。"
+            : "你没有被 @，可以选择不回复。",
+      })
+    })
+
+    // 会话空闲：冲刷缓存消息，或提醒模型补一次发送。
+    const idleRegistration = await ctx.session.hook("experimental.idle", async (event) => {
+      await manager.handleIdle(event.sessionID, event.background)
+    })
+
+    // 真正空闲（含后台任务结束）后，把忙碌期间缓存的消息合并成新的一轮。
+    // 失败或中断不会触发 idle 钩子，也要在这里释放状态；订阅断掉后自动重连。
+    const idleAbort = new AbortController()
+    void (async () => {
+      while (!idleAbort.signal.aborted) {
+        try {
+          for await (const event of ctx.event.subscribe({
+            types: ["session.idle", "session.execution.failed", "session.execution.interrupted"],
+            signal: idleAbort.signal,
+          })) {
+            if (event.type === "session.idle") {
+              await manager.flushBuffered(event.data.sessionID)
+            } else {
+              await manager.handleExecutionEnd(event.data.sessionID, event.type)
+            }
+          }
+        } catch (error) {
+          if (idleAbort.signal.aborted) break
+          logger.error("订阅会话事件失败，稍后重试", error)
+        }
+        if (!idleAbort.signal.aborted) await delay(RETRY_DELAY_MS)
+      }
+    })()
+
+    const isGroupEvent = (event: MessageEvent): event is GroupMessageEvent =>
+      event.message_type === "group"
+
+    const eventTarget = (event: MessageEvent): ChatTarget =>
+      isGroupEvent(event)
+        ? { kind: "group", id: event.group_id }
+        : { kind: "private", id: event.user_id }
+
+    const handleMessage = async (event: MessageEvent, target: ChatTarget, selfId: string) => {
+      try {
+        if (!isTargetEnabled(config, target)) return
+        if (!shouldProcess(event.message, selfId)) return
+
+        await client.hydrate(event.message)
+        const renderCtx = {
+          api: client.api,
+          target,
+          logger,
+          media,
+          names: nameCache,
+        }
+        const rendered = await renderMessage(renderCtx, event)
+        if (!rendered.text.trim()) return
+
+        const userName = await resolveUserName(renderCtx, String(event.user_id))
+        // 私聊消息默认都是对机器人说的，群聊只有被 @ 时才必须回复。
+        const atMe = target.kind === "private" || mentionsUser(event.message, selfId)
+
+        await manager.enqueue(target, {
+          text: `${userName}: ${rendered.text}`,
+          files: rendered.files,
+          atMe,
+        })
+      } catch (error) {
+        logger.error(`处理 ${targetLabel(target)} 消息失败`, error)
+      }
+    }
+
+    // 同一会话内串行处理，避免图片下载、成员查询等异步操作打乱消息顺序。
+    const processing = new Map<string, Promise<void>>()
+    const scheduleMessage = (event: MessageEvent) => {
+      const target = eventTarget(event)
+      if (!isTargetEnabled(config, target)) return
+      const selfId = String(event.self_id ?? client.selfId ?? "")
+      if (selfId && String(event.user_id) === selfId) return
+
+      manager.touch(target)
+      manager.rememberIncoming(target, String(event.message_id))
+
+      const key = targetKey(target)
+      const previous = processing.get(key) ?? Promise.resolve()
+      const task = previous
+        .then(() => handleMessage(event, target, selfId))
+        .catch((error: unknown) => logger.error(`处理 ${targetLabel(target)} 消息失败`, error))
+      processing.set(key, task)
+      void task.finally(() => {
+        if (processing.get(key) === task) processing.delete(key)
+      })
+    }
+
+    // 先注册监听再连接：NapCat 连接期间推送的消息也会被收到。
+    client.onGroupMessage(scheduleMessage)
+    client.onPrivateMessage(scheduleMessage)
+
+    await client.connectSafe()
+
+    // 主动说话心跳。
+    let timer: ReturnType<typeof setInterval> | undefined
+    let ticking = false
+    if (config.proactive.enabled) {
+      const tick = async () => {
+        if (ticking) return
+        ticking = true
+        try {
+          await manager.recoverStale()
+          for (const target of configuredTargets(config)) {
+            const probability = proactiveTickProbability(
+              config.proactive,
+              manager.silenceSeconds(target),
+            )
+            if (probability <= 0 || Math.random() >= probability) continue
+            logger.info(`${targetLabel(target)} 沉默达到阈值，主动发起话题`)
+            await manager.proactive(target, PROACTIVE_HINT)
+          }
+        } finally {
+          ticking = false
+        }
+      }
+      timer = setInterval(() => {
+        void tick()
+      }, config.proactive.tickSeconds * 1000)
+      const handle = timer as { unref?: () => void }
+      handle.unref?.()
+    }
+
+    logger.info("插件已加载", {
+      groups: config.groups,
+      users: config.users,
+      napcat: config.napcat.url,
+      agent: config.agent ?? "(默认)",
+    })
+
+    let disposed = false
+    const dispose = async () => {
+      if (disposed) return
+      disposed = true
+      if (timer) clearInterval(timer)
+      clearInterval(mediaCleanup)
+      idleAbort.abort()
+      await manager.flush()
+      await toolRegistration.dispose()
+      await contextRegistration.dispose()
+      await idleRegistration.dispose()
+      client.dispose()
+      lease.release()
+      logger.info("插件已卸载")
+    }
+    lease.setDispose(dispose)
+    return dispose
+  },
+})

package/src/instance.ts

@@ -0,0 +1,60 @@
+/**
+ * Cross-reload singleton registry.
+ *
+ * OpenCode may load a plugin again without invoking the previous instance's
+ * cleanup, which would leave duplicate WebSocket connections and duplicate
+ * message handlers behind. The registry lives on globalThis so it survives
+ * module reloads within the same server process.
+ */
+
+export interface PluginInstance {
+  dispose?: () => Promise<void>
+}
+
+export interface InstanceLease {
+  /** Registers the cleanup used when a newer instance takes over or the plugin unloads. */
+  setDispose(dispose: () => Promise<void>): void
+  /** Clears the slot only when this lease still owns it. */
+  release(): void
+}
+
+interface Host {
+  active?: { key: string; instance: PluginInstance }
+}
+
+const HOST_KEY = "__opencodeQQBotHost__"
+
+function host(): Host {
+  const global = globalThis as Record<string, unknown>
+  const existing = global[HOST_KEY]
+  if (existing && typeof existing === "object") return existing as Host
+  const created: Host = {}
+  global[HOST_KEY] = created
+  return created
+}
+
+/**
+ * Claims the singleton slot for `key` and returns any previous instance with
+ * the same key so the caller can dispose it. Instances with different keys
+ * (for example another project) are left untouched.
+ */
+export function claimInstance(key: string): {
+  previous: PluginInstance | undefined
+  lease: InstanceLease
+} {
+  const state = host()
+  const previous = state.active?.key === key ? state.active.instance : undefined
+  const instance: PluginInstance = {}
+  state.active = { key, instance }
+  return {
+    previous,
+    lease: {
+      setDispose(dispose) {
+        instance.dispose = dispose
+      },
+      release() {
+        if (state.active?.instance === instance) state.active = undefined
+      },
+    },
+  }
+}

package/src/logger.ts

@@ -0,0 +1,30 @@
+export type LogLevel = "debug" | "info" | "warn" | "error"
+
+const LEVEL_ORDER: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40 }
+
+export interface Logger {
+  debug(message: string, ...meta: unknown[]): void
+  info(message: string, ...meta: unknown[]): void
+  warn(message: string, ...meta: unknown[]): void
+  error(message: string, ...meta: unknown[]): void
+}
+
+/** 创建带前缀的日志器，插件运行在 OpenCode 服务端，直接写 stdout/stderr。 */
+export function createLogger(prefix: string, level: LogLevel = "info"): Logger {
+  const threshold = LEVEL_ORDER[level]
+  const write = (lvl: LogLevel, stream: "log" | "error", message: string, meta: unknown[]) => {
+    if (LEVEL_ORDER[lvl] < threshold) return
+    const stamp = new Date().toISOString()
+    const line = `[${stamp}] ${lvl.toUpperCase()} ${prefix} ${message}`
+    const details = meta.filter((entry) => entry !== undefined)
+    if (details.length > 0) console[stream](line, ...details)
+    else console[stream](line)
+  }
+
+  return {
+    debug: (message, ...meta) => write("debug", "log", message, meta),
+    info: (message, ...meta) => write("info", "log", message, meta),
+    warn: (message, ...meta) => write("warn", "log", message, meta),
+    error: (message, ...meta) => write("error", "error", message, meta),
+  }
+}

package/src/naplink/client.ts

@@ -0,0 +1,118 @@
+import {
+  NapLink,
+  type GroupMessageEvent,
+  type MessageSegment,
+  type OneBotApi,
+  type PrivateMessageEvent,
+} from "@naplink/naplink"
+import type { Logger } from "../logger"
+import type { NapcatConfig } from "../config"
+
+/** NapCat 的连接与 API 门面，屏蔽 SDK 细节。 */
+export class QQClient {
+  private readonly link: NapLink
+  private botId: string | undefined
+  private botIdRequest: Promise<void> | undefined
+
+  constructor(
+    private readonly config: NapcatConfig,
+    private readonly logger: Logger,
+  ) {
+    this.link = new NapLink({
+      connection: {
+        url: config.url,
+        ...(config.token ? { token: config.token } : {}),
+        timeout: 15_000,
+      },
+      reconnect: {
+        enabled: true,
+        maxAttempts: Number.POSITIVE_INFINITY,
+        backoff: { initial: 1000, max: 30_000, multiplier: 2 },
+      },
+      logging: { level: "info", logger },
+    })
+    // 每次（重）连成功都刷新机器人 QQ 号，自动重连后 selfId 依然可用。
+    this.link.on("connect", () => {
+      void this.refreshBotId().then(() => {
+        this.logger.info("NapCat 已连接", this.config.url, this.botId ? `bot=${this.botId}` : "")
+      })
+    })
+  }
+
+  get api(): OneBotApi {
+    return this.link.api
+  }
+
+  get connected(): boolean {
+    return this.link.isConnected()
+  }
+
+  async connect(): Promise<void> {
+    await this.link.connect()
+    await this.refreshBotId()
+  }
+
+  /** 读取机器人自己的 QQ 号，并发调用时复用同一个请求。 */
+  private refreshBotId(): Promise<void> {
+    this.botIdRequest ??= this.loadBotId().finally(() => {
+      this.botIdRequest = undefined
+    })
+    return this.botIdRequest
+  }
+
+  private async loadBotId(): Promise<void> {
+    try {
+      const info = (await this.api.getLoginInfo()) as { user_id?: number | string } | undefined
+      this.botId = info?.user_id !== undefined ? String(info.user_id) : undefined
+    } catch (error) {
+      this.logger.warn("读取机器人 QQ 号失败", error)
+    }
+  }
+
+  /**
+   * 连接 NapCat，失败时只记录日志。
+   *
+   * 后续重连由 NapLink 自己负责，插件加载不应该因为 NapCat 暂时离线而失败。
+   */
+  async connectSafe(): Promise<boolean> {
+    try {
+      await this.connect()
+      return true
+    } catch (error) {
+      this.logger.error("连接 NapCat 失败", error)
+      return false
+    }
+  }
+
+  dispose(): void {
+    try {
+      this.link.dispose()
+    } catch (error) {
+      this.logger.warn("关闭 NapCat 连接失败", error)
+    }
+  }
+
+  /** 订阅群消息事件。 */
+  onGroupMessage(handler: (event: GroupMessageEvent) => void): void {
+    this.link.on("message.group.normal", handler)
+  }
+
+  /** 订阅私聊消息事件（好友、临时会话等）。 */
+  onPrivateMessage(handler: (event: PrivateMessageEvent) => void): void {
+    this.link.on("message.private", handler)
+  }
+
+  /** 补全消息里媒体段的直链，便于下载图片。 */
+  async hydrate(message: MessageSegment[]): Promise<void> {
+    try {
+      await this.link.hydrateMessage(message)
+    } catch (error) {
+      this.logger.warn("补全媒体直链失败", error)
+    }
+  }
+
+  /** 机器人自己的 QQ 号，未连接时返回 undefined。 */
+  get selfId(): string | undefined {
+    return this.botId
+  }
+}