koishi-plugin-chatluna-character-buffer-backup 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 妖祀
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# koishi-plugin-chatluna-character-buffer-backup
+
+> 把 [chatluna-character](https://github.com/ChatLunaLab/chatluna-character) **只存在内存里**的近期对话缓冲
+> 持久化到数据库,**重启 / 控制台保存配置后自动灌回**,避免 bot 忘记刚刚聊到一半的上下文。
+
+chatluna-character 的「角色对话」近期消息缓冲只放在内存(`MessageCollector`)。一旦重启 koishi、
+或在控制台改配置触发热重载,这段缓冲就清空了——bot 会突然「忘了刚才在聊什么」。本插件:
+
+- 每次收到新消息 → 防抖把该会话的缓冲快照写进数据库;
+- `dispose`(正常重启 / 控制台保存)时再补一次刷盘,抓上 bot 的最后一条回复;
+- 启动就绪后,把数据库里**够新**的存档灌回内存缓冲(按 messageId 去重合并、尾部截断到上限);
+- 收到 chatluna-character 的「清除记忆」事件 → 同步删存档,保持诚实。
+
+## 依赖
+
+- `koishi` ^4.17
+- **`koishi-plugin-chatluna-character`**(提供 `chatluna_character` 服务,本插件的硬依赖)——必须先装好并启用。
+- 一个 koishi `database` 实现(如 `koishi-plugin-database-sqlite`),用来存档。
+
+> ⚠️ 本插件读写 chatluna-character 的内部消息缓冲(私有字段 `_messages` 与 `chatluna_character/*` 事件)。
+> 已做防御:字段结构不符时只告警、不崩溃。但若 chatluna-character 有**大版本改动**改了这些内部结构,
+> 恢复可能静默失效——届时更新本插件即可。建议与你实际测试过的 chatluna-character 版本搭配使用。
+
+## 启用
+
+1. 在 Koishi 控制台的**插件市场**搜 `chatluna-character-buffer-backup` 安装并启用;或命令行
+   ```bash
+   npm i koishi-plugin-chatluna-character-buffer-backup
+   ```
+   (从源码用:放到 koishi app 的 `external/` 下,再 `npm i ./external/koishi-plugin-chatluna-character-buffer-backup`。)
+2. 确保 `chatluna-character` 与一个 `database` 插件已启用,然后启用本插件即可——无需改预设。
+3. 重启或保存配置后,日志出现 `上下文恢复完成：N 个会话` 即生效。
+
+## 配置项
+
+| 配置 | 默认 | 说明 |
+|---|---|---|
+| `debounceMs` | `3000` | 收到消息后多久把缓冲快照写库(毫秒,防抖;最小 500)。 |
+| `maxAgeHours` | `24` | 启动恢复时,超过这个小时数的旧存档不再灌回(`0` = 不限)。 |
+| `restoreCap` | `100` | 每个会话恢复的最大消息条数(对齐 chatluna-character 的 `maxMessages` 上限,3–100)。 |
+| `debug` | `false` | 打印每次快照 / 恢复的条数。 |
+
+## 工作原理(简)
+
+- 存档表 `chatluna_character_buffer`,主键 = 会话 key(`private:<userId>` / `group:<guildId>`,与 chatluna-character 内部键一致)。
+- 恢复时把数据库存档与当前内存缓冲按 messageId 去重合并、按时间升序、尾部保留最新 `restoreCap` 条。
+- 全程 try/catch 兜底:存档读写失败、字段结构变化都只告警,不影响 bot 正常对话。
+
+## 许可
+
+MIT

package/index.js

@@ -0,0 +1,168 @@
+const { Schema } = require('koishi')
+const { deriveKey, mergeById, isFresh } = require('./lib')
+
+exports.name = 'chatluna-character-buffer-backup'
+
+exports.inject = ['database', 'chatluna_character']
+
+exports.Config = Schema.object({
+  debounceMs: Schema.number()
+    .default(3000)
+    .min(500)
+    .description('收到消息后多久把缓冲快照写入数据库（毫秒，防抖）'),
+  maxAgeHours: Schema.number()
+    .default(24)
+    .min(0)
+    .description('启动恢复时，超过这个小时数的旧存档不再灌回（0 = 不限）'),
+  restoreCap: Schema.number()
+    .default(100)
+    .min(3)
+    .max(100)
+    .description('每个会话恢复的最大消息条数（对齐 chatluna-character 的 maxMessages 上限）'),
+  debug: Schema.boolean().default(false).description('打印每次快照 / 恢复的条数')
+})
+
+const TABLE = 'chatluna_character_buffer'
+
+exports.apply = (ctx, config) => {
+  const logger = ctx.logger('chatluna-character-buffer-backup')
+  const svc = ctx.chatluna_character
+
+  ctx.database.extend(
+    TABLE,
+    {
+      sessionKey: { type: 'string', length: 255 },
+      messages: { type: 'text', nullable: true },
+      updatedAt: { type: 'timestamp', nullable: false, initial: new Date() }
+    },
+    { autoInc: false, primary: 'sessionKey', unique: ['sessionKey'] }
+  )
+
+  // ---- 读 chatluna-character 内部缓冲（带 guard）----
+  function getBuffer(key) {
+    try {
+      const arr = svc.getMessages(key)
+      return Array.isArray(arr) ? arr : []
+    } catch (e) {
+      return []
+    }
+  }
+
+  // 写私有字段 _messages：结构不对就告警 no-op，绝不让插件崩。
+  function setBuffer(key, arr) {
+    const store = svc && svc._messages
+    if (store == null || typeof store !== 'object') {
+      logger.warn('chatluna_character._messages 不可写（插件结构可能已变），跳过恢复 %s', key)
+      return false
+    }
+    store[key] = arr
+    return true
+  }
+
+  // ---- 快照写库（防抖）----
+  const timers = {}
+  async function snapshot(key) {
+    try {
+      const arr = getBuffer(key)
+      if (arr.length < 1) return
+      await ctx.database.upsert(TABLE, [
+        { sessionKey: key, messages: JSON.stringify(arr), updatedAt: new Date() }
+      ])
+      if (config.debug) logger.info('快照 %s：%d 条', key, arr.length)
+    } catch (e) {
+      logger.warn('快照失败 %s：%s', key, (e && e.message) || e)
+    }
+  }
+  function scheduleSnapshot(key) {
+    if (timers[key]) clearTimeout(timers[key])
+    timers[key] = setTimeout(() => {
+      delete timers[key]
+      snapshot(key)
+    }, config.debounceMs)
+  }
+
+  // 每次有消息被收集 → 安排一次防抖快照
+  ctx.on('chatluna_character/message_collect', (session) => {
+    try {
+      scheduleSnapshot(deriveKey(session))
+    } catch (e) {
+      logger.warn('调度快照失败：%s', (e && e.message) || e)
+    }
+  })
+
+  // /清除记忆 → 删存档，保持诚实
+  ctx.on('chatluna_character/clear-chat-history', (payload) => {
+    const key = payload && payload.sessionKey
+    if (!key) return
+    if (timers[key]) {
+      clearTimeout(timers[key])
+      delete timers[key]
+    }
+    ctx.database.remove(TABLE, { sessionKey: key }).catch((e) =>
+      logger.warn('删存档失败 %s：%s', key, (e && e.message) || e)
+    )
+  })
+
+  // ---- 启动恢复（只跑一次）----
+  let restored = false
+  async function restore() {
+    if (restored) return
+    restored = true
+    let rows
+    try {
+      rows = await ctx.database.get(TABLE, {})
+    } catch (e) {
+      logger.warn('读取存档失败，跳过恢复：%s', (e && e.message) || e)
+      return
+    }
+    const now = Date.now()
+    let ok = 0
+    for (const row of rows) {
+      if (!isFresh(row.updatedAt, config.maxAgeHours, now)) {
+        if (config.debug) logger.info('跳过过期存档 %s', row.sessionKey)
+        continue
+      }
+      let parsed
+      try {
+        parsed = JSON.parse(row.messages)
+      } catch (e) {
+        continue
+      }
+      if (!Array.isArray(parsed) || parsed.length < 1) continue
+      const merged = mergeById(getBuffer(row.sessionKey), parsed, config.restoreCap)
+      if (setBuffer(row.sessionKey, merged)) {
+        ok++
+        if (config.debug) logger.info('恢复 %s：%d 条', row.sessionKey, merged.length)
+      }
+    }
+    logger.info('上下文恢复完成：%d 个会话', ok)
+  }
+
+  // chatluna_character + database 就绪后恢复。late-registered 的 ready
+  // 监听器（热重载场景）koishi 会立即触发，故冷启动与保存配置都覆盖。
+  ctx.on('ready', () => {
+    restore()
+  })
+
+  // ---- dispose 兜底刷盘：正常重启 / 控制台 save 时抓最新态（含 bot 最后回复）----
+  ctx.on('dispose', () => {
+    let keys = []
+    try {
+      const store = svc && svc._messages
+      if (store && typeof store === 'object') keys = Object.keys(store)
+    } catch (e) {
+      keys = []
+    }
+    for (const key of keys) {
+      const arr = getBuffer(key)
+      if (arr.length < 1) continue
+      // fire-and-forget：dispose 不保证 await
+      ctx.database
+        .upsert(TABLE, [
+          { sessionKey: key, messages: JSON.stringify(arr), updatedAt: new Date() }
+        ])
+        .catch(() => {})
+    }
+    for (const k of Object.keys(timers)) clearTimeout(timers[k])
+  })
+}

package/lib.js

@@ -0,0 +1,40 @@
+// 纯逻辑：不依赖 koishi 运行时，可离线 node 测。
+
+// 会话 key：与 chatluna-character 内部 `_messages` 的键格式一致。
+function deriveKey(session) {
+  const isDirect = !!session.isDirect
+  return `${isDirect ? 'private' : 'group'}:${isDirect ? session.userId : session.guildId}`
+}
+
+// 合并两份 Message[]：按 messageId 去重（缺则回退 id|timestamp），
+// incoming 覆盖同键的 existing；按 timestamp 升序；尾部截断到 cap（保留最新）。
+function mergeById(existing, incoming, cap) {
+  const map = new Map()
+  const list = []
+  if (Array.isArray(existing)) list.push(...existing)
+  if (Array.isArray(incoming)) list.push(...incoming)
+  for (const msg of list) {
+    if (msg == null) continue
+    const key =
+      msg.messageId != null ? `mid:${msg.messageId}` : `fb:${msg.id}|${msg.timestamp}`
+    map.set(key, msg) // 后写覆盖 → incoming 在 existing 之后入队，故覆盖同键
+  }
+  const merged = [...map.values()].sort(
+    (a, b) => (a.timestamp ?? 0) - (b.timestamp ?? 0)
+  )
+  if (Number.isFinite(cap) && cap > 0) {
+    while (merged.length > cap) merged.shift()
+  }
+  return merged
+}
+
+// 存档是否够新：maxAgeHours<=0 视为不限（永远 fresh）；updatedAt 缺失则保守判 false。
+function isFresh(updatedAt, maxAgeHours, now) {
+  if (!(maxAgeHours > 0)) return true
+  if (updatedAt == null) return false
+  const t = updatedAt instanceof Date ? updatedAt.getTime() : new Date(updatedAt).getTime()
+  if (Number.isNaN(t)) return false
+  return now - t <= maxAgeHours * 3600000
+}
+
+module.exports = { deriveKey, mergeById, isFresh }

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "koishi-plugin-chatluna-character-buffer-backup",
+  "version": "0.1.0",
+  "description": "Persist chatluna-character's in-memory message buffer to the database and restore it on restart / config-save, so the bot keeps recent context across reloads.",
+  "main": "index.js",
+  "license": "MIT",
+  "author": "妖祀",
+  "homepage": "https://github.com/ningningningning0420-ui/koishi-chatluna-plugins/tree/main/packages/koishi-plugin-chatluna-character-buffer-backup#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ningningningning0420-ui/koishi-chatluna-plugins.git",
+    "directory": "packages/koishi-plugin-chatluna-character-buffer-backup"
+  },
+  "bugs": {
+    "url": "https://github.com/ningningningning0420-ui/koishi-chatluna-plugins/issues"
+  },
+  "files": [
+    "index.js",
+    "lib.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "koishi",
+    "plugin",
+    "chatluna",
+    "chatluna-character",
+    "chatbot",
+    "memory",
+    "context"
+  ],
+  "peerDependencies": {
+    "koishi": "^4.17.0",
+    "koishi-plugin-chatluna-character": "*"
+  },
+  "koishi": {
+    "description": {
+      "zh": "把 chatluna-character 只存在内存里的近期对话缓冲持久化到数据库，重启 / 保存配置后自动灌回，避免 bot 忘记刚刚聊的上下文。",
+      "en": "Persist chatluna-character's in-memory recent-message buffer to the database and auto-restore it after a restart / config-save, so the bot doesn't forget the conversation it was just having."
+    },
+    "service": {
+      "required": [
+        "database",
+        "chatluna_character"
+      ]
+    }
+  }
+}