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

package/src/session/soul.ts

@@ -0,0 +1,180 @@
+import { readFile } from "node:fs/promises"
+import { existsSync, statSync, watch, type FSWatcher } from "node:fs"
+import { dirname, isAbsolute, join, resolve } from "node:path"
+import type { Logger } from "../logger"
+import { buildSystemPrompt } from "./prompt"
+
+/** 角色设定目录名。 */
+export const SOUL_DIR = "souls"
+
+/** 默认角色设定文件名。 */
+export const DEFAULT_SOUL_NAME = "default.txt"
+
+/** 文件变化后的合并等待时间，避免编辑器连续写盘时重复读取。 */
+const RELOAD_DEBOUNCE_MS = 150
+
+export interface SoulOptions {
+  /** 显式指定的角色设定文件或目录，优先于 soulName。 */
+  soulPath?: string
+  /** souls 目录里的文件名。 */
+  soulName?: string
+  /** 插件所在目录，用于向上查找包内 souls 目录。 */
+  moduleDir: string
+  /** 相对路径的基准目录。 */
+  cwd: string
+}
+
+/** 从 startDir 向上逐级查找 souls/<name>。 */
+export function findSoulFile(
+  startDir: string,
+  name: string = DEFAULT_SOUL_NAME,
+  maxDepth = 5,
+): string | undefined {
+  let current = resolve(startDir)
+  for (let depth = 0; depth <= maxDepth; depth += 1) {
+    const candidate = join(current, SOUL_DIR, name)
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return undefined
+}
+
+/** 找不到文件时给出预期路径，文件补齐后可被监听器捡到。 */
+export function expectedSoulPath(startDir: string, name: string, maxDepth = 5): string {
+  let current = resolve(startDir)
+  for (let depth = 0; depth <= maxDepth; depth += 1) {
+    const directory = join(current, SOUL_DIR)
+    if (existsSync(directory)) return join(directory, name)
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return join(resolve(startDir), SOUL_DIR, name)
+}
+
+/** 定位角色设定文件：显式路径优先，其次 souls 目录里的指定文件。 */
+export function resolveSoulPath(options: SoulOptions): string {
+  const name = options.soulName?.trim() || DEFAULT_SOUL_NAME
+  const explicit = options.soulPath?.trim()
+  if (!explicit) {
+    return findSoulFile(options.moduleDir, name) ?? expectedSoulPath(options.moduleDir, name)
+  }
+
+  const target = isAbsolute(explicit) ? explicit : resolve(options.cwd, explicit)
+  if (existsSync(target) && statSync(target).isDirectory()) return join(target, name)
+  return target
+}
+
+/** 读取角色设定，失败时返回空字符串。 */
+export async function loadSoul(path: string | undefined): Promise<string> {
+  if (!path) return ""
+  try {
+    return await readFile(path, "utf-8")
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * 角色设定持有者：读取生效的设定文件，并在文件变化后热更新。
+ *
+ * 提示词在每轮组装时读取当前内容，所以文件改动会在下一轮立即生效。
+ */
+export class SoulStore {
+  #path: string | undefined
+  #text = ""
+  #watcher: FSWatcher | undefined
+  #timer: ReturnType<typeof setTimeout> | undefined
+  #logger: Logger
+
+  constructor(
+    private readonly options: SoulOptions,
+    logger: Logger,
+  ) {
+    this.#logger = logger
+  }
+
+  /** 生效的角色设定文件路径。 */
+  get path(): string | undefined {
+    return this.#path
+  }
+
+  /** 当前角色设定文本。 */
+  get text(): string {
+    return this.#text
+  }
+
+  /** 角色设定与固定守则组装出的系统提示词。 */
+  get prompt(): string {
+    return buildSystemPrompt(this.#text)
+  }
+
+  /** 解析路径、读取内容并开始监听文件变化。 */
+  async load(): Promise<void> {
+    this.#path = resolveSoulPath(this.options)
+    this.#text = await loadSoul(this.#path)
+    if (!this.#text) this.#logger.warn(`角色设定读取失败：${this.#path}`)
+    else this.#logger.info(`角色设定已加载：${this.#path}`)
+    this.#watch()
+  }
+
+  /** 重新读取角色设定文件，内容有变化时返回 true。 */
+  async reload(): Promise<boolean> {
+    if (!this.#path) return false
+    const text = await loadSoul(this.#path)
+    if (text === this.#text) return false
+    this.#text = text
+    this.#logger.info(`角色设定已更新：${this.#path}`)
+    return true
+  }
+
+  dispose(): void {
+    if (this.#timer) {
+      clearTimeout(this.#timer)
+      this.#timer = undefined
+    }
+    this.#watcher?.close()
+    this.#watcher = undefined
+  }
+
+  /** 监听所在目录：编辑器多为替换文件，只盯目录才能捕捉到。 */
+  #watch(): void {
+    if (!this.#path) return
+    const directory = dirname(this.#path)
+    if (!existsSync(directory)) return
+    try {
+      this.#watcher = watch(directory, (_event, filename) => {
+        const name = filename ? String(filename) : undefined
+        if (name && !this.#matches(name, directory)) return
+        this.#scheduleReload()
+      })
+    } catch (error) {
+      this.#logger.warn("角色设定监听失败，改动后需要重载插件", error)
+      return
+    }
+    const handle = this.#watcher as { unref?: () => void }
+    handle.unref?.()
+  }
+
+  #matches(filename: string, directory: string): boolean {
+    if (!this.#path) return false
+    return resolve(directory, filename) === this.#path
+  }
+
+  #scheduleReload(): void {
+    if (this.#timer) clearTimeout(this.#timer)
+    this.#timer = setTimeout(() => {
+      this.#timer = undefined
+      void this.reload()
+    }, RELOAD_DEBOUNCE_MS)
+    const handle = this.#timer as { unref?: () => void }
+    handle.unref?.()
+  }
+}
+
+/** 供测试与其它模块定位插件包目录。 */
+export function packageDirectory(): string {
+  return import.meta.dirname
+}

package/src/tools/ask-guard.ts

@@ -0,0 +1,32 @@
+import type { Plugin } from "@opencode/plugin"
+import { targetLabel } from "../chat"
+import type { Logger } from "../logger"
+import type { SessionManager } from "../session/manager"
+
+/** OpenCode 内置的“向用户提问”工具 id。 */
+export const QUESTION_TOOL = "question"
+
+/** 拒绝提问工具时回给模型的说明。 */
+export const ASK_REFUSAL =
+  "不允许调用 question 工具：QQ 会话里请直接用 qq_send_message 询问用户（Code Mode 下调用方式为 tools.qq.send_message）。"
+
+export interface AskGuardDeps {
+  ctx: Plugin.Context
+  logger: Logger
+  manager: SessionManager
+}
+
+/**
+ * 在 QQ 会话里拦截内置 question 工具，要求模型改用 qq_send_message 询问用户。
+ * 非 QQ 会话不受影响。
+ */
+export async function registerAskGuard(deps: AskGuardDeps): Promise<{ dispose(): Promise<void> }> {
+  const { ctx, logger, manager } = deps
+  return await ctx.tool.hook("execute.before", async (event) => {
+    if (event.tool !== QUESTION_TOOL) return
+    const target = manager.targetForSession(event.sessionID)
+    if (!target) return
+    logger.warn(`${targetLabel(target)} 会话里模型尝试调用 ${QUESTION_TOOL} 工具，已拒绝`)
+    throw new Error(ASK_REFUSAL)
+  })
+}

package/src/tools/qq.ts

@@ -0,0 +1,421 @@
+import type { Plugin } from "@opencode/plugin"
+import { type ChatTarget, isTargetEnabled, targetLabel } from "../chat"
+import type { QQBotConfig } from "../config"
+import type { Logger } from "../logger"
+import type { QQClient } from "../naplink/client"
+import type { SessionManager } from "../session/manager"
+
+/** 工具命名空间，最终工具名为 qq_send_message 等。 */
+export const TOOL_NAMESPACE = "qq"
+
+export interface ToolDeps {
+  ctx: Plugin.Context
+  config: QQBotConfig
+  logger: Logger
+  manager: SessionManager
+  client: QQClient
+}
+
+interface SendMessageInput {
+  content?: string
+  reply?: boolean
+  unlimit_length?: boolean
+}
+
+interface MediaInput {
+  file?: string
+  base64?: string
+}
+
+interface ForwardNodeInput {
+  user_id?: number | string
+  nickname?: string
+  content?: string
+}
+
+interface ForwardInput {
+  nodes?: ForwardNodeInput[]
+}
+
+interface UserInput {
+  user_id?: number | string
+}
+
+interface MessageIdInput {
+  message_id?: number | string
+}
+
+/** QQ 单条消息的保守长度上限，超过时按段发送。 */
+export const MAX_MESSAGE_CHARS = 4000
+
+function text(value: string) {
+  return { content: value }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/** 从 OneBot 发送结果里取出 message_id。 */
+function messageIdOf(response: unknown): string | undefined {
+  if (!response || typeof response !== "object") return undefined
+  const record = response as { message_id?: unknown; data?: { message_id?: unknown } }
+  const value = record.message_id ?? record.data?.message_id
+  return value === undefined || value === null ? undefined : String(value)
+}
+
+/** 按长度切分消息，保留原有换行与空行。 */
+export function splitMessage(content: string, max = MAX_MESSAGE_CHARS): string[] {
+  if (Array.from(content).length <= max) return [content]
+  const chunks: string[] = []
+  let current = ""
+  for (const line of content.split("\n")) {
+    const candidate = current ? `${current}\n${line}` : line
+    if (Array.from(candidate).length <= max) {
+      current = candidate
+      continue
+    }
+    if (current) chunks.push(current)
+    let rest = line
+    while (Array.from(rest).length > max) {
+      const part = Array.from(rest).slice(0, max).join("")
+      chunks.push(part)
+      rest = Array.from(rest).slice(max).join("")
+    }
+    current = rest
+  }
+  if (current) chunks.push(current)
+  return chunks.length > 0 ? chunks : [content]
+}
+
+/**
+ * 注册 QQ 命名空间下的工具。
+ *
+ * 全部工具都是对 NapCat OneBot API 的透传，
+ * 只暴露消息收发与只读查询，不提供封禁/踢人等破坏性操作。
+ */
+export async function registerTools(deps: ToolDeps): Promise<{ dispose(): Promise<void> }> {
+  const { ctx, config, logger, manager, client } = deps
+
+  const requireTarget = (sessionID: string): ChatTarget | undefined => {
+    const target = manager.targetForSession(sessionID)
+    if (!target) return undefined
+    if (!isTargetEnabled(config, target)) {
+      logger.warn(`${targetLabel(target)} 已不在配置中，拒绝工具调用`)
+      return undefined
+    }
+    if (!manager.hasActiveTurn(sessionID)) {
+      logger.warn(`会话 ${sessionID} 当前没有 QQ 消息轮次，拒绝工具调用`)
+      return undefined
+    }
+    return target
+  }
+
+  const sendText = (target: ChatTarget, chunk: string) =>
+    target.kind === "group"
+      ? client.api.sendGroupMessage(target.id, chunk)
+      : client.api.sendPrivateMessage(target.id, chunk)
+
+  const sendSegments = (target: ChatTarget, segments: unknown[]) =>
+    target.kind === "group"
+      ? client.api.sendGroupMessage(target.id, segments)
+      : client.api.sendPrivateMessage(target.id, segments)
+
+  const sendForward = (target: ChatTarget, nodes: unknown[]) =>
+    target.kind === "group"
+      ? client.api.sendGroupForwardMessage(target.id, nodes)
+      : client.api.sendPrivateForwardMessage({ user_id: target.id, messages: nodes })
+
+  const sendPoke = (target: ChatTarget, userId: string | number) =>
+    target.kind === "group"
+      ? client.api.sendGroupPoke(target.id, userId)
+      : client.api.sendFriendPoke(userId)
+
+  return await ctx.tool.transform((editor) => {
+    editor.namespace({
+      name: TOOL_NAMESPACE,
+      description:
+        "QQ 聊天工具：发送消息、图片、语音、合并转发，以及查询用户信息。仅在 QQ 群聊或私聊会话里可用，其他会话调用会返回错误。",
+    })
+
+    editor.add({
+      name: "send_message",
+      description:
+        "向当前 QQ 群聊或私聊发送一条消息。每轮必须调用一个发送工具。content: 要发送的文本；reply: true 表示发送，false 表示选择不发送（已读不回）；unlimit_length: 设为 true 可解除默认的长度告警限制。",
+      input: {
+        type: "object",
+        properties: {
+          content: { type: "string", description: "要发送的文本内容；reply=false 时可省略" },
+          reply: { type: "boolean", description: "true 表示发送，false 表示本轮不回复" },
+          unlimit_length: { type: "boolean", description: "解除默认的消息长度限制" },
+        },
+        additionalProperties: false,
+      },
+      options: { namespace: TOOL_NAMESPACE },
+      execute: async (raw, context) => {
+        const input = (raw ?? {}) as SendMessageInput
+        const target = requireTarget(context.sessionID)
+        if (!target) return text("error: 当前会话没有绑定 QQ 群聊或私聊")
+        const label = targetLabel(target)
+
+        if (input.reply === false) {
+          logger.info(`${label} 模型选择不回复`)
+          manager.markMessageSent(context.sessionID)
+          return text("skipped")
+        }
+        const content = (input.content ?? "").trim()
+        if (!content) {
+          logger.info(`${label} 回复内容为空`)
+          manager.markMessageSent(context.sessionID)
+          return text("skipped")
+        }
+
+        if (content.length > config.warnLength && input.unlimit_length !== true) {
+          logger.warn(`send_message 内容长度 ${content.length} 超过 ${config.warnLength}`)
+        }
+
+        const chunks = splitMessage(content)
+        let sent = 0
+        try {
+          for (const [index, chunk] of chunks.entries()) {
+            const response = await sendText(target, chunk)
+            const messageId = messageIdOf(response)
+            if (messageId) manager.rememberOutgoing(target, messageId)
+            sent += 1
+            if (index < chunks.length - 1 && config.sendDelayMs > 0) {
+              await delay(config.sendDelayMs)
+            }
+          }
+        } catch (error) {
+          if (sent > 0) manager.markMessageSent(context.sessionID)
+          logger.error(`${label} 发送消息失败，已发送 ${sent}/${chunks.length} 段`, error)
+          return text(`error: 消息只发送了 ${sent}/${chunks.length} 段`)
+        }
+        manager.markMessageSent(context.sessionID)
+        logger.info(`${label} 已发送 ${content.length} 字`)
+        return text("sent")
+      },
+    })
+
+    editor.add({
+      name: "send_image",
+      description:
+        "向当前 QQ 群聊或私聊发送一张图片。file 可以是本地路径或 http(s) 图片地址；base64 传 base64:// 形式的数据。",
+      input: {
+        type: "object",
+        properties: {
+          file: { type: "string", description: "本地文件路径或图片 URL" },
+          base64: { type: "string", description: "base64 编码的图片数据" },
+        },
+        additionalProperties: false,
+      },
+      options: { namespace: TOOL_NAMESPACE },
+      execute: async (raw, context) => {
+        const input = (raw ?? {}) as MediaInput
+        const target = requireTarget(context.sessionID)
+        if (!target) return text("error: 当前会话没有绑定 QQ 群聊或私聊")
+        const file = input.file ?? (input.base64 ? `base64://${input.base64}` : undefined)
+        if (!file) return text("error: 缺少 file 或 base64")
+        const response = await sendSegments(target, [{ type: "image", data: { file } }])
+        const messageId = messageIdOf(response)
+        if (messageId) manager.rememberOutgoing(target, messageId)
+        manager.markMessageSent(context.sessionID)
+        return text("sent")
+      },
+    })
+
+    editor.add({
+      name: "send_record",
+      description: "向当前 QQ 群聊或私聊发送一条语音。file 可以是本地路径或 http(s) 音频地址。",
+      input: {
+        type: "object",
+        properties: {
+          file: { type: "string", description: "本地文件路径或音频 URL" },
+        },
+        additionalProperties: false,
+      },
+      options: { namespace: TOOL_NAMESPACE },
+      execute: async (raw, context) => {
+        const input = (raw ?? {}) as MediaInput
+        const target = requireTarget(context.sessionID)
+        if (!target) return text("error: 当前会话没有绑定 QQ 群聊或私聊")
+        if (!input.file) return text("error: 缺少 file")
+        const response = await sendSegments(target, [
+          { type: "record", data: { file: input.file } },
+        ])
+        const messageId = messageIdOf(response)
+        if (messageId) manager.rememberOutgoing(target, messageId)
+        manager.markMessageSent(context.sessionID)
+        return text("sent")
+      },
+    })
+
+    editor.add({
+      name: "send_forward",
+      description:
+        "向当前 QQ 群聊或私聊发送一条合并转发消息。nodes 为节点列表，每个节点包含 user_id、nickname 和纯文本 content。",
+      input: {
+        type: "object",
+        properties: {
+          nodes: {
+            type: "array",
+            description: "合并转发的节点列表",
+            items: {
+              type: "object",
+              properties: {
+                user_id: { type: "string", description: "发送者 QQ 号" },
+                nickname: { type: "string", description: "发送者昵称" },
+                content: { type: "string", description: "节点文本内容" },
+              },
+              required: ["content"],
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ["nodes"],
+        additionalProperties: false,
+      },
+      options: { namespace: TOOL_NAMESPACE },
+      execute: async (raw, context) => {
+        const input = (raw ?? {}) as ForwardInput
+        const target = requireTarget(context.sessionID)
+        if (!target) return text("error: 当前会话没有绑定 QQ 群聊或私聊")
+        const nodes: {
+          user_id: number
+          nickname: string
+          content: { type: string; data: { text: string } }[]
+        }[] = []
+        for (const node of input.nodes ?? []) {
+          const userId = node.user_id === undefined ? 0 : Number(node.user_id)
+          if (!Number.isInteger(userId) || userId < 0) {
+            return text(`error: 非法 user_id：${String(node.user_id)}`)
+          }
+          nodes.push({
+            user_id: userId,
+            nickname: node.nickname?.trim() || "未知用户",
+            content: [{ type: "text", data: { text: node.content ?? "" } }],
+          })
+        }
+        if (nodes.length === 0) return text("error: nodes 为空")
+        const response = await sendForward(target, nodes)
+        const messageId = messageIdOf(response)
+        if (messageId) manager.rememberOutgoing(target, messageId)
+        manager.markMessageSent(context.sessionID)
+        return text("sent")
+      },
+    })
+
+    editor.add({
+      name: "send_poke",
+      description: "在当前 QQ 会话戳一下某个用户。",
+      input: {
+        type: "object",
+        properties: {
+          user_id: { type: "string", description: "被戳的 QQ 号" },
+        },
+        required: ["user_id"],
+        additionalProperties: false,
+      },
+      options: { namespace: TOOL_NAMESPACE },
+      execute: async (raw, context) => {
+        const input = (raw ?? {}) as UserInput
+        const target = requireTarget(context.sessionID)
+        if (!target) return text("error: 当前会话没有绑定 QQ 群聊或私聊")
+        if (!input.user_id) return text("error: 缺少 user_id")
+        await sendPoke(target, input.user_id)
+        manager.markMessageSent(context.sessionID)
+        return text("sent")
+      },
+    })
+
+    editor.add({
+      name: "delete_message",
+      description: "撤回一条机器人自己发过的消息。",
+      input: {
+        type: "object",
+        properties: {
+          message_id: { type: "string", description: "要撤回的消息 ID" },
+        },
+        required: ["message_id"],
+        additionalProperties: false,
+      },
+      options: { namespace: TOOL_NAMESPACE },
+      execute: async (raw, context) => {
+        const input = (raw ?? {}) as MessageIdInput
+        const target = requireTarget(context.sessionID)
+        if (!target) return text("error: 当前会话没有绑定 QQ 群聊或私聊")
+        if (input.message_id === undefined) return text("error: 缺少 message_id")
+        if (!manager.isOutgoing(target, String(input.message_id))) {
+          return text("error: 只能撤回机器人自己发送过的消息")
+        }
+        await client.api.deleteMessage(input.message_id)
+        return text("deleted")
+      },
+    })
+
+    editor.add({
+      name: "get_group_member_info",
+      description: "查询用户资料：群聊返回群名片与昵称，私聊返回 QQ 昵称。",
+      input: {
+        type: "object",
+        properties: {
+          user_id: { type: "string", description: "QQ 号" },
+        },
+        required: ["user_id"],
+        additionalProperties: false,
+      },
+      options: { namespace: TOOL_NAMESPACE },
+      execute: async (raw, context) => {
+        const input = (raw ?? {}) as UserInput
+        const target = requireTarget(context.sessionID)
+        if (!target) return text("error: 当前会话没有绑定 QQ 群聊或私聊")
+        if (!input.user_id) return text("error: 缺少 user_id")
+        const info =
+          target.kind === "group"
+            ? await client.api.getGroupMemberInfo(target.id, input.user_id)
+            : await client.api.getStrangerInfo(input.user_id)
+        return text(JSON.stringify(info))
+      },
+    })
+
+    editor.add({
+      name: "fetch_ptt_text",
+      description: "把一条语音消息转写成文字。",
+      input: {
+        type: "object",
+        properties: {
+          message_id: { type: "string", description: "语音消息的 ID" },
+        },
+        required: ["message_id"],
+        additionalProperties: false,
+      },
+      options: { namespace: TOOL_NAMESPACE },
+      execute: async (raw, context) => {
+        const input = (raw ?? {}) as MessageIdInput
+        const target = requireTarget(context.sessionID)
+        if (!target) return text("error: 当前会话没有绑定 QQ 群聊或私聊")
+        if (input.message_id === undefined) return text("error: 缺少 message_id")
+        if (!manager.isKnownMessage(target, String(input.message_id))) {
+          return text("error: 只能转写当前会话最近收到的消息")
+        }
+        const result = await client.api.fetchPttText(input.message_id)
+        return text(result?.text ?? "")
+      },
+    })
+
+    editor.add({
+      name: "get_login_info",
+      description: "获取机器人自身的 QQ 号与昵称。",
+      input: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+      },
+      options: { namespace: TOOL_NAMESPACE },
+      execute: async () => {
+        const info = await client.api.getLoginInfo()
+        return text(JSON.stringify(info))
+      },
+    })
+  })
+}