@cmach_socket/opencode-qq-bot 0.2.0 → 0.3.1

package/README.md

@@ -6,7 +6,7 @@
 - 群聊 / 私聊消息 → OpenCode 会话 → 模型回复 → 对应聊天
 - 每个聊天固定对应一个会话，会话忙碌时新消息先缓存，空闲后合并成一轮再投进去；绑定写入插件存储，重启后自动沿用原会话
 - 语音自动转写、图片落盘后以文件引用进入会话、引用与合并转发展开成文本块
-- 角色设定放在 `SOUL.txt`
+- 角色设定放在 `souls/` 目录，可放多份，按文件名切换，改动后下一轮立即生效
 
 ## 环境要求
 
@@ -54,26 +54,27 @@ bun install
 插件不会读取项目 `.env`。如果选择用环境变量配置，必须把变量注入 OpenCode 服务进程本身，
 可参考 `.env.example`；`cp .env.example .env` 不会生效。
 
-| 选项                                | 环境变量                        | 默认值          | 说明                                            |
-| ----------------------------------- | ------------------------------- | --------------- | ----------------------------------------------- |
-| `napcat.url`                        | `NAPCAT_WS_URL`                 | 无（必填）      | NapCat 正向 WebSocket 地址                      |
-| `napcat.token`                      | `NAPCAT_WS_TOKEN`               | 无              | NapCat 访问令牌                                 |
-| `groups`                            | `QQ_TARGET_GROUPS`              | `[]`            | 参与对话的群号，逗号分隔                        |
-| `users`                             | `QQ_TARGET_USERS`               | `[]`            | 参与对话的私聊 QQ 号，逗号分隔                  |
-| `soulPath`                          | `QQ_BOT_SOUL_PATH`              | 包内 `SOUL.txt` | 角色设定文件路径                                |
-| `agent`                             | `QQ_BOT_AGENT`                  | OpenCode 默认   | 会话使用的 agent                                |
-| `model`                             | `QQ_BOT_MODEL`                  | OpenCode 默认   | 会话使用的模型，格式 `provider/model[/variant]` |
-| `sendDelayMs`                       | `QQ_SEND_DELAY_MS`              | `1000`          | 超长消息分段发送时每段之间的间隔                |
-| `warnLength`                        | `QQ_WARN_LENGTH`                | `20`            | 一轮回复总长度超过该值时告警                    |
-| `reuseSession`                      | `QQ_REUSE_SESSION`              | `false`         | 没有保存的绑定时，按会话标记找回上一次的会话    |
-| `busyTimeoutMs`                     | `QQ_BUSY_TIMEOUT_MS`            | `300000`        | 会话超过该时长未结束视为卡死，强制放行缓存消息  |
-| `proactive.enabled`                 | `QQ_PROACTIVE_ENABLED`          | `true`          | 是否启用主动说话                                |
-| `proactive.silenceThresholdSeconds` | `QQ_PROACTIVE_SILENCE_SECONDS`  | `10800`         | 沉默多久后才开始计算主动说话概率                |
-| `proactive.startProbability`        | `QQ_PROACTIVE_P_START`          | `0.01`          | 刚跨过阈值时的概率                              |
-| `proactive.probabilityPerHour`      | `QQ_PROACTIVE_P_SLOPE_PER_HOUR` | `0.05`          | 每多沉默一小时概率的增量                        |
-| `proactive.tickSeconds`             | `QQ_PROACTIVE_TICK_SECONDS`     | `3600`          | 心跳间隔，必须大于 0                            |
-| `reminder.enabled`                  | `QQ_REMINDER_ENABLED`           | `true`          | 模型一轮没调用发送工具时是否提醒                |
-| `reminder.max`                      | `QQ_REMINDER_MAX`               | `2`             | 连续提醒次数上限                                |
+| 选项                                | 环境变量                        | 默认值        | 说明                                            |
+| ----------------------------------- | ------------------------------- | ------------- | ----------------------------------------------- |
+| `napcat.url`                        | `NAPCAT_WS_URL`                 | 无（必填）    | NapCat 正向 WebSocket 地址                      |
+| `napcat.token`                      | `NAPCAT_WS_TOKEN`               | 无            | NapCat 访问令牌                                 |
+| `groups`                            | `QQ_TARGET_GROUPS`              | `[]`          | 参与对话的群号，逗号分隔                        |
+| `users`                             | `QQ_TARGET_USERS`               | `[]`          | 参与对话的私聊 QQ 号，逗号分隔                  |
+| `soulPath`                          | `QQ_BOT_SOUL_PATH`              | 包内 `souls/` | 角色设定文件或目录路径                          |
+| `soulName`                          | `QQ_BOT_SOUL_NAME`              | `default.txt` | `souls` 目录里的角色设定文件名                  |
+| `agent`                             | `QQ_BOT_AGENT`                  | OpenCode 默认 | 会话使用的 agent                                |
+| `model`                             | `QQ_BOT_MODEL`                  | OpenCode 默认 | 会话使用的模型，格式 `provider/model[/variant]` |
+| `sendDelayMs`                       | `QQ_SEND_DELAY_MS`              | `1000`        | 超长消息分段发送时每段之间的间隔                |
+| `warnLength`                        | `QQ_WARN_LENGTH`                | `20`          | 一轮回复总长度超过该值时告警                    |
+| `reuseSession`                      | `QQ_REUSE_SESSION`              | `false`       | 没有保存的绑定时，按会话标记找回上一次的会话    |
+| `busyTimeoutMs`                     | `QQ_BUSY_TIMEOUT_MS`            | `300000`      | 会话超过该时长未结束视为卡死，强制放行缓存消息  |
+| `proactive.enabled`                 | `QQ_PROACTIVE_ENABLED`          | `true`        | 是否启用主动说话                                |
+| `proactive.silenceThresholdSeconds` | `QQ_PROACTIVE_SILENCE_SECONDS`  | `10800`       | 沉默多久后才开始计算主动说话概率                |
+| `proactive.startProbability`        | `QQ_PROACTIVE_P_START`          | `0.01`        | 刚跨过阈值时的概率                              |
+| `proactive.probabilityPerHour`      | `QQ_PROACTIVE_P_SLOPE_PER_HOUR` | `0.05`        | 每多沉默一小时概率的增量                        |
+| `proactive.tickSeconds`             | `QQ_PROACTIVE_TICK_SECONDS`     | `3600`        | 心跳间隔，必须大于 0                            |
+| `reminder.enabled`                  | `QQ_REMINDER_ENABLED`           | `true`        | 模型一轮没调用发送工具时是否提醒                |
+| `reminder.max`                      | `QQ_REMINDER_MAX`               | `2`           | 连续提醒次数上限                                |
 
 没配置 `groups` 和 `users` 时插件不会响应任何消息（默认全部关闭）。
 
@@ -81,6 +82,34 @@ bun install
 写错的配置项会输出告警并回退到默认值，不会静默失效。
 取值规则与图片内联限制见 [docs/configuration.md](docs/configuration.md)。
 
+### 角色设定
+
+角色设定文件放在 `souls/` 目录，一个目录里可以放多份，用 `soulName` 选生效的那份：
+
+```
+souls/
+  default.txt     默认角色
+  白羽桃.txt      另一份角色
+```
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "./",
+      "options": {
+        "soulName": "白羽桃.txt",
+      },
+    },
+  ],
+}
+```
+
+- `soulName` 填 `souls` 目录里的文件名，默认 `default.txt`。
+- `soulPath` 可以直接给文件路径（相对路径按进程工作目录解析），也可以给目录，目录时同样用 `soulName` 选文件。
+- 生效文件的内容改动会被监听，下一轮就用新设定，不需要重启插件。
+- 改 `soulName` 换角色：写进 `opencode.json(c)` 保存后 OpenCode 会重载插件，随即生效。
+
 ## 工具
 
 模型只能操作当前会话绑定的群聊或私聊，工具都带 `qq_` 前缀：
@@ -158,6 +187,7 @@ bun run format      # prettier --write .
 ## 目录
 
 ```
+souls/               角色设定文件（可多份，按文件名切换）
 src/
   config.ts          配置合并与校验
   index.ts           插件入口
@@ -165,8 +195,10 @@ src/
   logger.ts          日志
   naplink/client.ts  NapLink 连接与 API 门面
   naplink/render.ts  消息段 → 文本与图片附件
-  session/prompt.ts  角色设定与系统提示
+  session/prompt.ts  固定守则与系统提示
+  session/soul.ts    角色设定定位、读取与热更新
   session/manager.ts 群聊 / 私聊 ↔ 会话映射、消息缓存
+  tools/ask-guard.ts 拦截内置 question 工具
   tools/qq.ts        QQ 工具注册
 docs/
   configuration.md   配置取值规则与限制

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmach_socket/opencode-qq-bot",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "OpenCode V2 plugin bridging a QQ group chat (NapCat via NapLink) to an OpenCode session.",
   "type": "module",
   "main": "./src/index.ts",
@@ -13,7 +13,7 @@
   },
   "files": [
     "src",
-    "SOUL.txt",
+    "souls",
     "README.md"
   ],
   "scripts": {

package/src/config.ts

@@ -52,8 +52,10 @@ export interface QQBotConfig {
   groups: number[]
   /** 参与 AI 对话的私聊 QQ 号。 */
   users: number[]
-  /** 角色设定文件路径，默认使用插件包内的 SOUL.txt。 */
+  /** 角色设定文件路径，默认使用插件包内的 souls 目录。 */
   soulPath?: string
+  /** souls 目录里的角色设定文件名，默认 default.txt。 */
+  soulName?: string
   /** QQ 会话使用的 OpenCode agent。 */
   agent?: string
   /** QQ 会话使用的模型。 */
@@ -279,6 +281,7 @@ function createConfigSchema(
     groups,
     users,
     soulPath: text("soulPath", defaults.soulPath),
+    soulName: text("soulName", defaults.soulName),
     agent: text("agent", defaults.agent),
     model,
     sendDelayMs: nonNegative("sendDelayMs", defaults.sendDelayMs),
@@ -320,6 +323,7 @@ const ENV_VARS = {
   groups: "QQ_TARGET_GROUPS",
   users: "QQ_TARGET_USERS",
   soulPath: "QQ_BOT_SOUL_PATH",
+  soulName: "QQ_BOT_SOUL_NAME",
   agent: "QQ_BOT_AGENT",
   model: "QQ_BOT_MODEL",
   sendDelayMs: "QQ_SEND_DELAY_MS",
@@ -340,6 +344,7 @@ const OPTION_KEYS = new Set([
   "groups",
   "users",
   "soulPath",
+  "soulName",
   "agent",
   "model",
   "sendDelayMs",

package/src/index.ts

@@ -8,15 +8,10 @@ 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 { currentTimeText, PROACTIVE_HINT } from "./session/prompt"
 import { proactiveTickProbability } from "./session/proactive"
+import { packageDirectory, SoulStore } from "./session/soul"
+import { registerAskGuard } from "./tools/ask-guard"
 import { registerTools } from "./tools/qq"
 
 const RETRY_DELAY_MS = 1000
@@ -53,10 +48,17 @@ export default Plugin.define({
       }
     }
 
-    const soulPath = resolveSoulPath(config.soulPath, packageDirectory(), process.cwd())
-    const soul = await loadSoul(soulPath)
-    if (!soul) logger.warn(`角色设定读取失败：${soulPath ?? "(未找到)"}`)
-    const systemPrompt = buildSystemPrompt(soul)
+    // 角色设定：读取生效文件并监听改动，改完下一轮即生效。
+    const soul = new SoulStore(
+      {
+        soulPath: config.soulPath,
+        soulName: config.soulName,
+        moduleDir: packageDirectory(),
+        cwd: process.cwd(),
+      },
+      logger,
+    )
+    await soul.load()
 
     const client = new QQClient(config.napcat, logger)
     const manager = new SessionManager(ctx, config, logger)
@@ -71,13 +73,15 @@ export default Plugin.define({
     const mediaHandle = mediaCleanup as { unref?: () => void }
     mediaHandle.unref?.()
     const toolRegistration = await registerTools({ ctx, config, logger, manager, client })
+    // QQ 会话里禁止模型调用内置 question 工具，改用 qq_send_message 询问用户。
+    const askGuardRegistration = await registerAskGuard({ ctx, logger, manager })
     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: soul.prompt })
       event.system.push({ type: "text", text: `当前时间：${currentTimeText()}` })
       const turn = manager.currentTurn(event.sessionID)
       const destination = target.kind === "group" ? "群里" : "私聊里"
@@ -232,7 +236,9 @@ export default Plugin.define({
       clearInterval(mediaCleanup)
       idleAbort.abort()
       await manager.flush()
+      soul.dispose()
       await toolRegistration.dispose()
+      await askGuardRegistration.dispose()
       await contextRegistration.dispose()
       await idleRegistration.dispose()
       client.dispose()

package/src/naplink/client.ts

@@ -8,6 +8,83 @@ import {
 import type { Logger } from "../logger"
 import type { NapcatConfig } from "../config"
 
+const MEDIA_SEGMENT_TYPES = ["image", "video", "record", "audio", "file"] as const
+
+type MediaSegmentType = (typeof MEDIA_SEGMENT_TYPES)[number]
+
+interface MediaSegmentData {
+  file?: string
+  file_id?: string
+  url?: string
+}
+
+interface MediaFileLike {
+  file?: unknown
+  url?: unknown
+}
+
+function isMediaSegmentType(type: string): type is MediaSegmentType {
+  return (MEDIA_SEGMENT_TYPES as readonly string[]).includes(type)
+}
+
+/** 取第一个可下载的 http(s) 直链，忽略本地路径与 base64。 */
+export function pickRemoteUrl(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string" && /^https?:\/\//i.test(value)) return value
+  }
+  return undefined
+}
+
+/**
+ * 补全单个媒体段的远程直链。
+ *
+ * NapCat 同时返回本地路径（`file`）和 CDN 直链（`url`），SDK 自带的补全逻辑
+ * 会优先选用本地路径，导致插件无法下载。这里只写入 `url`，且优先使用 http(s) 地址。
+ */
+export async function hydrateSegment(
+  api: OneBotApi,
+  segment: MessageSegment,
+  logger: Logger,
+): Promise<void> {
+  if (!isMediaSegmentType(segment.type)) return
+  const data = segment.data as MediaSegmentData
+  // 已有可用的远程直链时不要覆盖。
+  if (pickRemoteUrl(data.url)) return
+  const fileId = data.file ?? data.file_id
+  if (typeof fileId !== "string" || fileId.length === 0) return
+  if (/^(file|base64|data):/i.test(fileId)) return
+
+  try {
+    const file = (await api.getFile(fileId)) as MediaFileLike | undefined
+    const direct = pickRemoteUrl(file?.url, file?.file)
+    if (direct) {
+      data.url = direct
+      return
+    }
+    if (segment.type === "image") {
+      const image = (await api.getImage(fileId)) as MediaFileLike | undefined
+      const imageUrl = pickRemoteUrl(image?.url, image?.file)
+      if (imageUrl) data.url = imageUrl
+    } else if (segment.type === "record" || segment.type === "audio") {
+      const record = (await api.getRecord(fileId, "mp3")) as MediaFileLike | undefined
+      const recordUrl = pickRemoteUrl(record?.url, record?.file)
+      if (recordUrl) data.url = recordUrl
+    }
+  } catch (error) {
+    logger.debug(`补全媒体直链失败 type=${segment.type} file=${fileId}`, error)
+  }
+}
+
+/** 补全一条消息里所有媒体段的远程直链。 */
+export async function hydrateMedia(
+  api: OneBotApi,
+  message: MessageSegment[],
+  logger: Logger,
+): Promise<void> {
+  if (!Array.isArray(message)) return
+  await Promise.all(message.map((segment) => hydrateSegment(api, segment, logger)))
+}
+
 /** NapCat 的连接与 API 门面，屏蔽 SDK 细节。 */
 export class QQClient {
   private readonly link: NapLink
@@ -105,7 +182,7 @@ export class QQClient {
   /** 补全消息里媒体段的直链，便于下载图片。 */
   async hydrate(message: MessageSegment[]): Promise<void> {
     try {
-      await this.link.hydrateMessage(message)
+      await hydrateMedia(this.api, message, this.logger)
     } catch (error) {
       this.logger.warn("补全媒体直链失败", error)
     }

package/src/naplink/media.ts

@@ -83,6 +83,11 @@ function truncateCodePoints(text: string, max: number): string {
   return Array.from(text).slice(0, max).join("")
 }
 
+/** 截断过长的地址，避免日志被超长 URL 淹没。 */
+function truncateForLog(value: string, max = 120): string {
+  return value.length > max ? `${value.slice(0, max)}…` : value
+}
+
 /** 判断主机名是否指向本机或内网，避免下载请求打内网服务。 */
 export function isPrivateHost(hostname: string): boolean {
   let host = hostname.trim().toLowerCase()
@@ -199,7 +204,10 @@ export class MediaStore {
       return { bytes, mime }
     }
     if (url.startsWith("data:")) return parseDataUrl(url)
-    if (!url.startsWith("http://") && !url.startsWith("https://")) return undefined
+    if (!url.startsWith("http://") && !url.startsWith("https://")) {
+      this.logger.warn(`不支持的图片地址，跳过下载 url=${truncateForLog(url)}`)
+      return undefined
+    }
 
     let parsed: URL
     try {

package/src/naplink/render.ts

@@ -2,6 +2,7 @@ import type { MessageEvent, MessageSegment, OneBotApi } from "@naplink/naplink"
 import type { ChatTarget } from "../chat"
 import { targetKey } from "../chat"
 import type { Logger } from "../logger"
+import { hydrateSegment } from "./client"
 import {
   MAX_IMAGE_BYTES,
   inlineImageBytes,
@@ -174,8 +175,10 @@ async function renderForwardSegments(
           break
         case "image": {
           parts.push("[图片]")
+          if (budget.images <= 0) break
+          await hydrateSegment(ctx.api, segment, ctx.logger)
           const url = segment.data.url || segment.data.file
-          if (!url || budget.images <= 0) break
+          if (!url) break
           const stored = await ctx.media.storeImage(url)
           if (!stored || !takeImage(budget, stored)) break
           images.push(stored)
@@ -363,8 +366,10 @@ export async function renderMessage(
           break
         case "image": {
           textBuffer.push("[图片] ")
+          if (budget.images <= 0) break
+          await hydrateSegment(ctx.api, segment, ctx.logger)
           const url = segment.data.url || segment.data.file
-          if (!url || budget.images <= 0) break
+          if (!url) break
           const stored = await ctx.media.storeImage(url)
           if (!stored || !takeImage(budget, stored)) break
           imageIndex += 1

package/src/session/prompt.ts

@@ -1,7 +1,3 @@
-import { readFile } from "node:fs/promises"
-import { existsSync } from "node:fs"
-import { dirname, isAbsolute, join, resolve } from "node:path"
-
 /** 发消息用的工具名（命名空间 qq 下的 send_message）。 */
 export const SEND_MESSAGE_TOOL = "qq_send_message"
 
@@ -23,41 +19,6 @@ export const PROACTIVE_HINT = `
 你需要调用 ${SEND_MESSAGE_TOOL} 工具把话题发到当前聊天。
 `
 
-/** 从模块所在目录向上查找 SOUL.txt，兼容 src/ 与 dist/ 两种布局。 */
-export function findSoulFile(startDir: string, maxDepth = 5): string | undefined {
-  let current = resolve(startDir)
-  for (let depth = 0; depth <= maxDepth; depth += 1) {
-    const candidate = join(current, "SOUL.txt")
-    if (existsSync(candidate)) return candidate
-    const parent = dirname(current)
-    if (parent === current) break
-    current = parent
-  }
-  return undefined
-}
-
-/** 定位角色设定文件：显式路径优先，否则用包内默认。 */
-export function resolveSoulPath(
-  explicitPath: string | undefined,
-  moduleDir: string,
-  cwd: string,
-): string | undefined {
-  if (explicitPath) {
-    return isAbsolute(explicitPath) ? explicitPath : resolve(cwd, explicitPath)
-  }
-  return findSoulFile(moduleDir)
-}
-
-/** 读取角色设定，失败时返回空字符串。 */
-export async function loadSoul(path: string | undefined): Promise<string> {
-  if (!path) return ""
-  try {
-    return await readFile(path, "utf-8")
-  } catch {
-    return ""
-  }
-}
-
 /** 组装完整的系统提示词。 */
 export function buildSystemPrompt(soul: string): string {
   const base = soul.trim()
@@ -78,8 +39,3 @@ const TIME_FORMAT = new Intl.DateTimeFormat("sv-SE", {
 export function currentTimeText(now = new Date()): string {
   return TIME_FORMAT.format(now)
 }
-
-/** 供测试与其它模块定位包内 SOUL.txt。 */
-export function packageDirectory(): string {
-  return import.meta.dirname
-}

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)
+  })
+}