koishi-plugin-emoji-recall 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,74 @@
+# koishi-plugin-emoji-recall
+
+> 按轮语义召回表情包。给 [chatluna](https://github.com/ChatLunaLab/chatluna) 的角色对话注册一个
+> `{emojis_smart}` 函数变量:每次生成回复时,用**当前对话内容**向量检索 [emojiluna](https://github.com/koishijs)
+> 的表情库,只把**最相关的 K 张**表情塞进提示词。
+
+库越大也不会让每轮成本失控,而且 bot 发的图贴合当下话题(在聊猫,就浮现猫的表情)。
+
+完整的安装 / 配置 / 预设接入(含「以髭切为例」的可复制片段)见仓库的
+[**安装与使用指南**](https://github.com/ningningningning0420-ui/koishi-chatluna-plugins/blob/main/docs/emoji-recall-安装与使用指南.md)。这里只放速查。
+
+## 它解决什么
+
+emojiluna 原生的 `{emojis}` 会把**全部表情**(每张:名称 + 完整 URL + 分类 + 标签)塞进**每一轮**回复;
+库越大越贵,而且与当前对话无关。本插件改成「按当前对话语义,只挑最相关的几张」。
+
+机制与 livingmemory 的 `{living_memory}` 完全一致:都是 chatluna 的 function-provider,
+能在渲染时拿到 `configurable.session`(当前消息)作查询。
+
+## 依赖
+
+- `koishi` ^4.18
+- `chatluna`(核心,提供 promptRenderer 与 embeddings)
+- `chatluna-character`(角色对话,渲染预设;非本插件 service 硬依赖,但角色场景需要)
+- `emojiluna`(表情库与 `/get` `/tags` 端点)
+- 一个 chatluna 能调用的 **embeddings 向量模型**(默认 `ollama/bge-m3:latest`)
+
+## 三步启用
+
+1. 安装:在 Koishi 控制台的**插件市场**搜 `emoji-recall` 直接安装;或命令行
+   ```bash
+   npm i koishi-plugin-emoji-recall
+   ```
+   (从源码用:把本目录放到 koishi app 的 `external/` 下,再 `npm i ./external/koishi-plugin-emoji-recall`。)
+2. `koishi.yml` 启用(`selfUrl` 必须 = 本 bot 自己的端口,与 emojiluna 一致):
+   ```yaml
+     emoji-recall:main:
+       selfUrl: http://127.0.0.1:5140
+       backendPath: /emojiluna
+       topK: 6
+       embeddingModel: ollama/bge-m3:latest
+       minScore: 0
+       useReranker: false
+       fallbackToRecent: true
+       debug: true        # 首次开,日志看命中表情+分数,稳了再关
+   ```
+3. 改预设:把输出用的 `{emojis}` 换成 `{emojis_smart}`,`{if emojis}…{/if}` 外壳保留当「库里有没有图」的门。重启 koishi 生效。
+
+## 配置项
+
+| 配置 | 默认 | 说明 |
+|---|---|---|
+| `selfUrl` | `http://127.0.0.1:5140` | 本 bot 服务器地址,**必须 = 本 bot 端口**,与 emojiluna.selfUrl 一致 |
+| `backendPath` | `/emojiluna` | emojiluna 后端路径,与 emojiluna.backendPath 一致 |
+| `topK` | `6` | 每轮注入多少张最相关的表情 |
+| `functionName` | `emojis_smart` | 注册的函数变量名,预设里用 `{该名}` 引用 |
+| `embeddingModel` | `ollama/bge-m3:latest` | 向量模型 id,`platform/model`,需是 chatluna 能调用的 embeddings |
+| `minScore` | `0` | 相似度下限;`0` = 永远取 topK,调高可在「没够相关的图」时少注入 |
+| `useReranker` | `false` | 是否再用 reranker 精排(多一次网络调用) |
+| `rerankModel` | `siliconflow/BAAI/bge-reranker-v2-m3` | reranker 模型 id(`useReranker` 开时用) |
+| `maxQueryChars` | `200` | 查询文本最大长度(取当前消息尾部) |
+| `fallbackToRecent` | `true` | 无对话文本 / embeddings 不可用时,退化为注入最近 K 张(关 = 注入空) |
+| `debug` | `false` | 打印每轮的查询与命中表情 + 分数 |
+
+`{emojis_smart(8)}` 可临时指定数量;无参则用配置的 `topK`。
+
+## 验证
+
+启动日志应出现:`emoji-recall ready (function {emojis_smart}, base=…)`。
+开 `debug: true` 后,每轮日志:`query="…" → 名称(分数), …`。
+
+## 许可
+
+MIT

package/index.js

@@ -0,0 +1,166 @@
+const { Schema } = require('koishi')
+
+exports.name = 'emoji-recall'
+
+// 按轮语义召回:每次生成回复、渲染预设时,用当前对话文本做查询,
+// 经 embeddings(默认 ollama bge-m3)对 emojiluna 表情库做向量相似度检索,
+// 只注入最相关的 K 张表情。
+// 用 chatluna 的 function-provider 实现 {emojis_smart}(与 livingmemory 的 {living_memory} 同机制),
+// 每轮即时计算。token 只占 K 张、且与当前对话相关。
+//
+// 不在 koishi.yml 启用 + 预设不引用 {emojis_smart} = 完全不生效、零影响。
+// 安装/配置/使用见同目录 README.md 或发布包根目录的《安装与使用指南.md》。
+
+exports.Config = Schema.intersect([
+  Schema.object({
+    selfUrl: Schema.string()
+      .default('http://127.0.0.1:5140')
+      .description('本 bot 的服务器地址,必须 = 本 bot 自己的端口,且与该 bot 的 emojiluna.selfUrl 完全一致'),
+    backendPath: Schema.string().default('/emojiluna').description('emojiluna 后端路径,与 emojiluna.backendPath 一致'),
+    topK: Schema.number().min(1).max(30).default(6).description('每轮注入多少张最相关的表情'),
+    functionName: Schema.string()
+      .default('emojis_smart')
+      .description('注册的函数变量名;预设里用 {函数名} 引用(无参用配置的 topK)')
+  }).description('基础'),
+  Schema.object({
+    embeddingModel: Schema.string()
+      .default('ollama/bge-m3:latest')
+      .description('向量模型 id,格式 platform/model;需是你的 chatluna 能调用的 embeddings(建议与 livingmemory 用同一个)'),
+    minScore: Schema.number()
+      .min(0).max(1).role('slider').step(0.01).default(0)
+      .description('相似度下限。0=永远取 topK;调高可在"没有够相关的图"时少注入甚至不注入'),
+    useReranker: Schema.boolean().default(false).description('是否再用 reranker 精排(多一次网络调用,默认关)'),
+    rerankModel: Schema.string()
+      .default('siliconflow/BAAI/bge-reranker-v2-m3')
+      .description('reranker 模型 id(useReranker 开时用)')
+  }).description('检索模型'),
+  Schema.object({
+    maxQueryChars: Schema.number().min(20).max(2000).default(200).description('查询文本最大长度(取当前消息尾部)'),
+    fallbackToRecent: Schema.boolean()
+      .default(true)
+      .description('当无对话文本(如定时触发)或 embeddings 不可用时,是否退化为注入最近 K 张(关=注入空)'),
+    debug: Schema.boolean().default(false).description('打印每轮的查询与命中表情+分数')
+  }).description('其它')
+])
+
+function cosineSimilarity(a, b) {
+  if (!a || !b || a.length !== b.length) return 0
+  let dot = 0, na = 0, nb = 0
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i]
+    na += a[i] * a[i]
+    nb += b[i] * b[i]
+  }
+  if (na === 0 || nb === 0) return 0
+  return dot / (Math.sqrt(na) * Math.sqrt(nb))
+}
+
+exports.apply = (ctx, config) => {
+  const logger = ctx.logger('emoji-recall')
+
+  ctx.inject(['chatluna', 'emojiluna'], (ctx2) => {
+    const base = config.selfUrl.replace(/\/+$/, '') + config.backendPath
+
+    // 过滤记账标签(自动获取 / 来自群:xxx),它们是噪声,不进向量、不展示
+    const isNoiseTag = (t) => t === '自动获取' || (typeof t === 'string' && t.startsWith('来自群'))
+    const cleanTags = (tags) => (tags || []).filter((t) => t && !isNoiseTag(t))
+
+    // 表情向量缓存:id -> { hash, vector }。仅在表情文本变化时重算。
+    const cache = new Map()
+    const emojiText = (e) => [e.name, e.category, cleanTags(e.tags).join(' ')].filter(Boolean).join(' ')
+    const textHash = (s) => {
+      let h = 0
+      for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) | 0
+      return h
+    }
+    const escapeMd = (t) => String(t).replace(/([[\]()])/g, '\\$1')
+    const fmtList = (emojis) =>
+      emojis
+        .map(
+          (e) =>
+            `- [${escapeMd(e.name)}](${base}/get/${encodeURIComponent(e.id)}) - 分类: ${e.category}, 标签: ${cleanTags(e.tags).join(', ')}`
+        )
+        .join('\n')
+
+    ctx2.on('emojiluna/emoji-deleted', (id) => cache.delete(id))
+    ctx2.on('emojiluna/emoji-updated', (e) => e && cache.delete(e.id))
+
+    const ensureVectors = async (embeddings, emojis) => {
+      const missing = []
+      for (const e of emojis) {
+        const t = emojiText(e)
+        const h = textHash(t)
+        const c = cache.get(e.id)
+        if (!c || c.hash !== h) missing.push({ id: e.id, t, h })
+      }
+      if (!missing.length) return
+      const vectors = await embeddings.embedDocuments(missing.map((m) => m.t))
+      missing.forEach((m, i) => cache.set(m.id, { hash: m.h, vector: vectors[i] }))
+    }
+
+    ctx2.effect(() =>
+      ctx2.chatluna.promptRenderer.registerFunctionProvider(
+        config.functionName,
+        async (args, _variables, configurable) => {
+          try {
+            const K = Math.max(1, parseInt(args && args[0], 10) || config.topK)
+            const emojis = await ctx2.emojiluna.getEmojiList()
+            if (!emojis.length) return ''
+
+            // 查询文本 = 当前消息(去掉 <at/>、<img/> 等元素噪声与 URL,取尾部 maxQueryChars)
+            const session = configurable && configurable.session
+            let query = ((session && session.content) || '')
+              .replace(/<[^>]*>/g, ' ')
+              .replace(/https?:\/\/\S+/g, ' ')
+              .replace(/\s+/g, ' ')
+              .trim()
+            if (query.length > config.maxQueryChars) query = query.slice(-config.maxQueryChars)
+
+            const embeddings = await ctx2.chatluna.createEmbeddings(config.embeddingModel)
+            const embOk = embeddings && embeddings.value != null
+
+            // 无查询文本 / embeddings 不可用 → 优雅降级
+            if (!query || !embOk) {
+              if (config.debug) logger.info(`fallback (query=${!!query}, emb=${embOk}) → ${config.fallbackToRecent ? 'recent ' + K : 'empty'}`)
+              return config.fallbackToRecent ? fmtList(emojis.slice(0, K)) : ''
+            }
+
+            await ensureVectors(embeddings.value, emojis)
+            const queryVector = await embeddings.value.embedQuery(query)
+
+            let scored = emojis
+              .map((e) => ({ e, score: cosineSimilarity(queryVector, (cache.get(e.id) || {}).vector) }))
+              .sort((a, b) => b.score - a.score)
+            if (config.minScore > 0) scored = scored.filter((s) => s.score >= config.minScore)
+
+            let top = scored.slice(0, config.useReranker ? K * 3 : K)
+
+            if (config.useReranker && top.length > 1) {
+              try {
+                const reranker = await ctx2.chatluna.createReranker(config.rerankModel)
+                if (reranker && reranker.value != null) {
+                  const rr = await reranker.value.rerank(top.map((s) => emojiText(s.e)), query, { topN: K })
+                  top = rr.map((r) => top[r.index]).filter(Boolean)
+                }
+              } catch (err) {
+                logger.warn(`rerank failed: ${err.message}`)
+              }
+            }
+            top = top.slice(0, K)
+
+            if (config.debug) {
+              logger.info(`query="${query.slice(0, 30)}" → ${top.map((s) => `${s.e.name}(${(s.score || 0).toFixed(2)})`).join(', ') || '(空)'}`)
+            }
+            if (!top.length) return ''
+            return fmtList(top.map((s) => s.e))
+          } catch (e) {
+            logger.warn(`emoji recall failed: ${e.message}`)
+            return ''
+          }
+        }
+      )
+    )
+
+    logger.info(`emoji-recall ready (function {${config.functionName}}, base=${base})`)
+  })
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "koishi-plugin-emoji-recall",
+  "description": "按轮语义召回:用当前对话向量检索 emojiluna 表情库,每轮只注入最相关的 K 张(token 少且贴合上下文),经 {emojis_smart} 注入 chatluna 预设",
+  "version": "0.1.0",
+  "main": "index.js",
+  "license": "MIT",
+  "author": "妖祀",
+  "homepage": "https://github.com/ningningningning0420-ui/koishi-chatluna-plugins/tree/main/packages/koishi-plugin-emoji-recall#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ningningningning0420-ui/koishi-chatluna-plugins.git",
+    "directory": "packages/koishi-plugin-emoji-recall"
+  },
+  "bugs": {
+    "url": "https://github.com/ningningningning0420-ui/koishi-chatluna-plugins/issues"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "koishi",
+    "plugin",
+    "chatluna",
+    "emojiluna",
+    "emoji",
+    "embedding",
+    "rag"
+  ],
+  "peerDependencies": {
+    "koishi": "^4.18.0",
+    "koishi-plugin-chatluna": "*",
+    "koishi-plugin-emojiluna": "*"
+  },
+  "koishi": {
+    "description": {
+      "zh": "按轮语义召回表情包:向量检索当前对话最相关的 K 张,经 {emojis_smart} 注入",
+      "en": "Per-turn semantic recall of emojiluna stickers: vector-search the K most relevant stickers for the current conversation and inject them into chatluna presets via {emojis_smart}."
+    },
+    "service": {
+      "required": [
+        "chatluna",
+        "emojiluna"
+      ]
+    }
+  }
+}