koishi-plugin-oni-sync-bot 0.10.1 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/readme.md CHANGED
@@ -27,6 +27,19 @@
27
27
  - **QQ 平台按钮** — QQ 会话下返回 markdown + 可点击按钮;其它平台返回纯文本
28
28
  - **序号选择** — 非 QQ 平台列出候选并要求 15 秒内回复序号
29
29
 
30
+ ### 🤖 AI 问答(本地向量检索 + DeepSeek)
31
+
32
+ - **渲染文本抽取** — 同步成功后调用 BWiki `action=parse&prop=text` 取渲染结果,用 cheerio 清洗:
33
+ **信息框(右侧的关键数值)抽成 `电力:消耗 1200 瓦` 这样的「标签:值」行**,
34
+ 正文数表压平为 `单元格 | 单元格`,导航框 / 目录 / 脚本 / 脚注标记才丢弃,结果写入 `wikitexts` 表
35
+ - **本地向量库** — 纯 TS 的 [vectra](https://github.com/Stevenic/vectra) 文件索引,不引入任何数据库进程
36
+ - **本地 Embedding** — `@huggingface/transformers` 在 CPU 上跑 `bge-small-zh-v1.5`(默认 q8 量化),不依赖外部 Embedding API
37
+ - **防幻觉** — 检索片段进 system 提示词,模型被要求「严格且仅根据资料回答,资料未提及就直接说未提及」
38
+ - **追问** — 自己最近 2 轮问答会被带进上下文;开启 `aiChannelMemory` 时,别人刚问过的题目也能承接(「那它耗电多少」)
39
+ - **降级检索** — 向量库不可用(未启用 / 还没建索引 / 模型加载失败)时,退化为既有的拼音标题匹配,再取该页正文
40
+
41
+ > Wikitext 源码**只**用于同步,永远不会进入 AI 检索链路。AI 只看到渲染后的纯文本。
42
+
30
43
  ### 📋 模块同步 TodoList
31
44
 
32
45
  - **自动纳管** — 每周一 00:00 拉取原站全部 Module 写入待办
@@ -47,16 +60,48 @@ npm install koishi-plugin-oni-sync-bot
47
60
  yarn add koishi-plugin-oni-sync-bot
48
61
  ```
49
62
 
63
+ ### AI 相关依赖
64
+
65
+ AI 问答功能依赖三个包(已随插件声明为 `dependencies`,正常安装即可):
66
+
67
+ ```bash
68
+ npm install vectra cheerio @huggingface/transformers
69
+ # 或
70
+ yarn add vectra cheerio @huggingface/transformers
71
+ ```
72
+
73
+ | 包 | 用途 | 体积说明 |
74
+ | -- | ---- | -------- |
75
+ | `vectra` | 本地文件向量索引 | 纯 JS,无独立进程 |
76
+ | `cheerio` | 解析 `action=parse` 返回的 HTML | 纯 JS |
77
+ | `@huggingface/transformers` | 本地 CPU 推理 Embedding 模型 | 含 onnxruntime,约 300MB 安装体积 |
78
+
79
+ 首次运行 `ai.sync` / `ai.reindex` 时会从 `embeddingRemoteHost`(默认 `https://hf-mirror.com`)下载模型,
80
+ `bge-small-zh-v1.5` 的 q8 量化模型约 25MB,缓存在 `embeddingCacheDir`。
81
+
82
+ > 运行环境:`vectra@0.15` 声明 `engines: node >= 22`,建议使用 **Node 22 / 24**(本仓库测试环境为 Node 26)。
83
+ > 2 核 2G 的机器建议保持 `embeddingDtype="q8"`、`embedBatchSize=4`,Embedding 常驻内存约 100~200MB。
84
+
50
85
  ### 依赖服务
51
86
 
52
87
  插件需要以下 Koishi 插件(通常已随 Koishi 提供):
53
88
 
54
- - `@koishijs/plugin-database`(`wikipages` / `onitodos` 持久化)
89
+ - `@koishijs/plugin-database`(`wikipages` / `wikitexts` / `onitodos` 持久化)
55
90
  - `@koishijs/plugin-server`(短链路由)
56
91
  - `@koishijs/plugin-console`(控制台页面与日志查看)
57
- - `koishi-plugin-cron`(定时任务)
92
+ - `@koishijs/plugin-http`(`.ai` 抓取 BWiki 渲染文本、调用 DeepSeek)
93
+ - `koishi-plugin-cron`(定时任务,**可选**:未启用时 `sync.*` / `update` / `todolist` 命令照常可用,
94
+ 只是不会自动跑增量同步等定时任务,启动时会打一条警告)
58
95
  - 任意适配器(可选;QQ 适配器才能看到 markdown 按钮效果)
59
96
 
97
+ > 若需要定时任务,请在 `koishi.yml` 里补一项(插件名 `cron`):
98
+ >
99
+ > ```yaml
100
+ > plugins:
101
+ > group:basic:
102
+ > cron:xxxxxxxx: {}
103
+ > ```
104
+
60
105
  ## ⚙️ 配置项
61
106
 
62
107
  配置 schema 的**唯一声明处**是 [`src/config.ts`](src/config.ts),分为四个分组:账号、站点、通知、定时任务。
@@ -75,6 +120,41 @@ yarn add koishi-plugin-oni-sync-bot
75
120
  | `notifyBotPlatform` | 通知 | 发送通知所用的 bot 平台标识 | `qq` |
76
121
  | `updateCron` | 定时 | 页面缓存自动更新的 cron 表达式 | `0 2 * * *`(每天 02:00) |
77
122
 
123
+ ### 🤖 AI 相关配置
124
+
125
+ | 参数 | 分组 | 说明 | 默认值 |
126
+ | --------------------- | -------- | ------------------------------------------------------------ | ----------------------------------- |
127
+ | `textSyncOnChange` | 渲染文本 | 同步成功后自动抓取渲染文本并写索引 | `true` |
128
+ | `textApiUrl` | 渲染文本 | BWiki 的 `api.php` 地址 | 空(由 `bwiki_site` 拼出) |
129
+ | `textTableMode` | 渲染文本 | `flatten` 保留信息框+压平数据表 / `drop` 丢弃全部表格(会丢数值) | `flatten` |
130
+ | `textMaxLength` | 渲染文本 | 单页最多保留字数 | `20000` |
131
+ | `textSyncInterval` | 渲染文本 | 批量抓取时的页间间隔(毫秒) | `300` |
132
+ | `vectorEnabled` | 向量 | 启用本地向量库 | `true` |
133
+ | `vectorIndexPath` | 向量 | vectra 索引目录 | `data/oni-vector` |
134
+ | `embeddingModel` | 向量 | 本地 Embedding 模型 | `Xenova/bge-small-zh-v1.5` |
135
+ | `embeddingDtype` | 向量 | `q8` / `fp32` / `fp16` / `q4` | `q8` |
136
+ | `embeddingCacheDir` | 向量 | 模型缓存目录 | `data/oni-models` |
137
+ | `embeddingRemoteHost` | 向量 | 模型下载源 | `https://hf-mirror.com` |
138
+ | `chunkSize` | 向量 | 单块目标字数 | `350` |
139
+ | `chunkOverlap` | 向量 | 相邻块重叠字数 | `60` |
140
+ | `maxChunksPerPage` | 向量 | 单页最多块数(决定索引体积,2G 建议 12) | `16` |
141
+ | `retrieveTopK` | 向量 | 检索返回块数 | `3` |
142
+ | `retrieveMinScore` | 向量 | 最低余弦相似度 | `0.2` |
143
+ | `queryInstruction` | 向量 | BGE 查询指令前缀 | `为这个句子生成表示以用于检索相关文章:` |
144
+ | `embedBatchSize` | 向量 | 单批 Embedding 条数 | `4` |
145
+ | `aiEnabled` | AI | 启用 `.ai` 命令 | `true` |
146
+ | `deepseekApiKey` | AI | DeepSeek API Key(也可用环境变量 `DEEPSEEK_API_KEY`) | 空 |
147
+ | `deepseekBaseUrl` | AI | API 地址 | `https://api.deepseek.com` |
148
+ | `deepseekModel` | AI | 模型名 | `deepseek-chat` |
149
+ | `aiTemperature` | AI | 采样温度 | `0.2` |
150
+ | `aiMaxTokens` | AI | 回答最大 token | `700` |
151
+ | `aiTimeout` | AI | 请求超时(毫秒) | `60000` |
152
+ | `aiCooldown` | AI | 同一用户提问冷却(秒) | `5` |
153
+ | `aiMaxQuestionLength` | AI | 问题最大长度 | `200` |
154
+ | `aiMemoryTurns` | AI | 追问记忆保留的轮数(0 = 关闭) | `2` |
155
+ | `aiMemoryTtl` | AI | 追问记忆过期时间(秒),超时视为新话题 | `600` |
156
+ | `aiChannelMemory` | AI | 群内话题承接:别人刚问过,自己接着问也能懂「那它…」 | `true` |
157
+
78
158
  > **默认值形同虚设**:账号默认值是 `1`,必须改成真实账号,否则登录一定失败。
79
159
 
80
160
  ## 📚 命令列表
@@ -86,6 +166,65 @@ yarn add koishi-plugin-oni-sync-bot
86
166
  | 命令 | 别名 | 说明 | 权限 |
87
167
  | ------------------- | --------- | -------------------------------- | ---- |
88
168
  | `x <itemName:text>` | `/查wiki` | 查询页面(标题 / 全拼 / 首字母) | - |
169
+ | `ai <question:text>`| `/问缺氧` | 基于 BWIKI 资料的 AI 问答 | - |
170
+ | `ai.status` | - | 查看 AI / 向量索引状态 | 1 |
171
+ | `ai.sync [pageTitle]` | - | 抓取渲染文本(不填则全量) | 4 |
172
+ | `ai.reindex` | - | 用本地正文重建向量索引 | 4 |
173
+
174
+ > 首次部署顺序:`update`(拉页面列表)→ `ai.sync`(抓渲染文本 + 建索引);
175
+ > 之后每小时增量同步会自动维护文本与索引,无需再手动执行。
176
+ >
177
+ > `ai.sync` 不依赖 `update`:本地 `wikipages` 为空时会自动改用 bwiki 的 `list=allpages` 枚举页面。
178
+ > 抓取时优先走已登录的 bwiki 客户端(mwn,自带 Referer/Cookie);退回 `ctx.http` 时也会自动补 `Referer`——
179
+ > 缺少 `Referer` 会被 bwiki 的 WAF 以 **HTTP 567** 拦掉。
180
+ >
181
+ > **追问**:`.ai` 会按「平台 + 频道 + 用户」记住最近 2 轮(默认 10 分钟内有效)。
182
+ > 先问「电解器耗电多少」,再问「那它能干什么」时,上一轮的问题会被并入检索串,模型也能从历史里知道「它」指谁。
183
+ >
184
+ > **群内承接**(`aiChannelMemory`,默认开):自己还没提问记录时,会承接**群里上一条被回答的问题**。
185
+ > 比如 alice 问「氧石精炼炉是什么」,bob 接着问「那他耗电多少」,bob 这一问会以「氧石精炼炉是什么」为语境检索,
186
+ > 回复里会附一行 `💭 承接群内上一问:…` 说明依据;答「未提及」的轮次不会成为群话题。
187
+ >
188
+ > 记忆只存在内存里,重启即清空;`aiMemoryTurns=0` 可整体关闭。
189
+
190
+ ### 🧠 2G 内存够不够(实测数据)
191
+
192
+ 在本机(Windows / Node 26 / q8 量化模型)分段实测 RSS:
193
+
194
+ | 阶段 | RSS |
195
+ | ---- | --- |
196
+ | Koishi + sqlite + http + cron 基线 | 103 MB |
197
+ | 加载 `bge-small-zh` q8 Embedding 模型后 | 216 MB(模型约占 113 MB) |
198
+ | 再挂 1 万个文本块的索引(`index.json` 81 MB),检索后常驻 | 282 MB |
199
+ | 释放模型后 | 255 MB(onnxruntime 的原生内存不一定立刻归还系统) |
200
+
201
+ > 建索引的过程中会有临时峰值(实测写入 1 万块时到过 376 MB,含构建批量数组的开销),
202
+ > 所以 `ai.sync` / `ai.reindex` 尽量低峰执行。
203
+
204
+ 结论与经验值:
205
+
206
+ - **索引常驻内存 ≈ 每个文本块 6~7 KB**(384 维 float);1 万块 ≈ 66 MB,3 万块 ≈ 200 MB。
207
+ - 索引体积取决于「页面数 × 单页块数」,所以 `maxChunksPerPage` / `textMaxLength` 就是内存阀门。
208
+ - 模型只在第一次问答时才加载(之后常驻),不会影响普通同步命令。
209
+
210
+ > **改过 `renderText` / `textTableMode` 之后必须重跑 `ai.sync`**:
211
+ > `wikitexts` 里存的是**已抽好的纯文本**,`ai.reindex` 只会用旧文本重建向量,不会重新抓页面。
212
+
213
+ **2G Windows Server 推荐档**(`ai.status` 里「索引体积」超过 150 MB 时按此收紧):
214
+
215
+ | 参数 | 建议值 |
216
+ | ---- | ------ |
217
+ | `textMaxLength` | `8000` |
218
+ | `maxChunksPerPage` | `12` |
219
+ | `chunkSize` / `chunkOverlap` | `350` / `60` |
220
+ | `embedBatchSize` | `2` |
221
+ | `aiMemoryTurns` | `2`(记忆本身很小,不用关) |
222
+
223
+ 另外两点务必做:
224
+
225
+ 1. **Windows 虚拟内存(页面文件)保持 ≥ 4GB**,避免瞬时峰值直接 OOM;
226
+ 2. `ai.sync` / `ai.reindex` 不要和「同步所有页面」、定时任务撞车,放在低峰跑;
227
+ 3. Windows Server 若加载模型时报 onnxruntime 相关的 DLL 错误,装一下 **Visual C++ 2015-2022 运行库**(x64)即可。
89
228
 
90
229
  ### 🔄 同步
91
230
 
@@ -157,9 +296,13 @@ yarn add koishi-plugin-oni-sync-bot
157
296
  | 表名 | 字段 |
158
297
  | ----------- | --------------------------------------------------------------------------------------------------------------- |
159
298
  | `wikipages` | `id`、`title`、`pinyin_full`、`pinyin_first`、`contributor`、`change_time` |
299
+ | `wikitexts` | `id`(主键=页面标题)、`title`、`pageid`、`revid`、`hash`、`text`、`updated_at` |
160
300
  | `onitodos` | `id`、`title`、`content`、`completed`、`createdBy`、`createdAt`、`updatedAt` |
161
301
 
162
- `wikipages` 通过 `Tables` 接口增强声明(见 `databaseExtension.ts`);`onitodos` 目前**没有**做接口增强。
302
+ `wikipages` / `wikitexts` 通过 `Tables` 接口增强声明(见 `databaseExtension.ts`);`onitodos` 目前**没有**做接口增强。
303
+
304
+ `wikitexts.text` 存的是 BWiki **渲染后的纯文本**(不是 Wikitext 源码),`hash` 是正文的 sha1,
305
+ 用于在增量同步时跳过未变化的页面、避免重复 Embedding。
163
306
 
164
307
  ## 🎨 控制台界面
165
308
 
@@ -176,24 +319,30 @@ yarn add koishi-plugin-oni-sync-bot
176
319
  ```
177
320
  src/
178
321
  ├── index.ts # 组合根:SUB_PLUGINS 注册表 + 控制台入口
179
- ├── config.ts # 配置的唯一声明处(账号 / 站点 / 通知 / 定时 四组)
322
+ ├── config.ts # 配置的唯一声明处(账号 / 站点 / 通知 / 定时 / 渲染文本 / 向量 / AI)
180
323
  ├── services/
181
324
  │ ├── wikiBotService.ts # wikiBot 服务:登录、代理、透明重登录
325
+ │ ├── vectorService.ts # vector 服务:本地 Embedding + vectra 索引(检索/写入)
326
+ │ ├── aiService.ts # DeepSeek 客户端 + 防幻觉提示词组装
327
+ │ ├── aiMemory.ts # 追问记忆(用户 / 群话题)与上下文选择
182
328
  │ ├── messageRenderer.ts # QQ markdown+按钮 / 纯文本 的渲染
183
329
  │ └── consoleLogProvider.ts # 控制台日志服务(onilogs)
184
330
  ├── plugins/
185
- │ ├── databaseExtension.ts # wikipages 表定义
331
+ │ ├── databaseExtension.ts # wikipages / wikitexts 表定义
186
332
  │ ├── queryCommands.ts # x / 查wiki
187
- │ ├── syncCommands.ts # sync.* 命令 + 同步相关定时任务
333
+ │ ├── aiQueryCommands.ts # ai / ai.status / ai.sync / ai.reindex
334
+ │ ├── syncCommands.ts # sync.* 命令 + 同步相关定时任务 + 同步后抽取渲染文本
188
335
  │ ├── updateCommands.ts # update.* / redirect / relogin
189
336
  │ ├── routeRedirect.ts # 短链路由
190
337
  │ └── todoList.ts # TodoList 命令 + 控制台监听 + 定时任务
191
338
  ├── sync/
192
- │ ├── pageSync.ts # PageSyncer:单页 / 全量 / 增量更新
339
+ │ ├── pageSync.ts # PageSyncer:单页 / 全量 / 增量更新(含 onSynced 钩子)
340
+ │ ├── textSync.ts # RenderedTextSyncer:action=parse → 纯文本 → wikitexts → 向量库
193
341
  │ ├── moduleSync.ts # ModuleSyncer:模块同步
194
342
  │ └── imgSync.ts # ImageSyncer:图片同步
195
343
  └── utils/
196
- ├── tools.ts # 拼音、时间格式化、标题规范化等
344
+ ├── tools.ts # 拼音、时间格式化、标题规范化、站点 URL 规范化等
345
+ ├── renderText.ts # HTML → 纯文本、文本切块(纯函数,可单测)
197
346
  ├── async.ts # sleep + withRetry(全项目统一的重试语义)
198
347
  └── matcher.ts # 查询打分与模糊匹配(纯函数,可单测)
199
348
 
@@ -210,13 +359,33 @@ client/ # 控制台前端(Vue)
210
359
  ```
211
360
  WikiBotService(提供 wikiBot 服务,必须最先)
212
361
  ↓
362
+ VectorService(提供 vector 服务:本地 Embedding + 索引)
363
+ ↓
213
364
  ConsoleLogProvider / DatabaseExtension(提供 console 数据源与数据表)
214
365
  ↓
215
- RouteRedirect / SyncCommands / QueryCommands / UpdateCommands / TodoList
366
+ RouteRedirect / SyncCommands / QueryCommands / UpdateCommands / TodoList / AiQueryCommands
216
367
  ```
217
368
 
218
369
  所有子插件共享**同一个配置对象**,因此注册时统一传 `config`;不需要配置的子插件会忽略它。
219
370
 
371
+ ### AI 数据流
372
+
373
+ ```
374
+ GG 原站 Wikitext ──(PageSyncer)──> bwiki
375
+ │
376
+ (onSynced 钩子,同步成功后)
377
+ ↓
378
+ BWiki action=parse&prop=text ──> HTML ──(cheerio)──> 纯文本
379
+ │
380
+ wikitexts 表(hash 去重)
381
+ ↓
382
+ chunkText ──> bge-small-zh Embedding ──> vectra 索引
383
+ ↓
384
+ .ai 提问 ──> 检索 top 2-3 片段 ──> DeepSeek ──> QQ 回复
385
+ ```
386
+
387
+ Wikitext 源码只用于同步,**不会**进入检索链路;`onSynced` 钩子的失败只记日志,不影响同步结果。
388
+
220
389
  ### 如何新增一个子插件
221
390
 
222
391
  1. 新建一个类,用 `static readonly inject` 声明它依赖哪些服务(例如 `["database", "wikiBot"]`);
@@ -298,6 +467,34 @@ yarn test # tsc 编译到 .test-build/,再用 mocha 跑
298
467
  **`❌ 未找到ID为【…】的页面`**
299
468
  页面不在本地缓存中(可能是新增页面),先执行 `update`。
300
469
 
470
+ **`.ai` 一直回答「抱歉,资料中未提及相关信息」**
471
+ 1. 执行 `ai.status`,确认「已入库页面」不是 0;为 0 时先执行 `ai.sync`(会自动枚举页面,也可先 `update` 补缓存);
472
+ 2. 「索引文本块」为 0 时执行 `ai.reindex`(索引被清空或模型刚就绪);
473
+ 3. 检索命中率低可调小 `retrieveMinScore`(如 0.15)、调大 `retrieveTopK`。
474
+
475
+ **`ai.sync` 报 HTTP 567 / 返回一串 HTML**
476
+ bwiki 的 WAF 拦截。抓取请求必须带 `Referer`(插件会自动补 `https://<bwiki_site>/`),
477
+ 优先使用已登录的 bwiki 客户端;若仍被拦,先执行 `relogin` 再重试,或把 `textSyncInterval` 调大(如 1000)。
478
+
479
+ **`sync` / `update` / `todo` 命令在控制台里「消失」了**
480
+ 这些子插件依赖 `wikiBot` / `database`,并把 `cron` 声明为**可选**依赖。
481
+ 若一个必需服务没就绪,整组命令都不会注册。排查:
482
+ 1. 控制台日志里是否有 `WikiBotService 初始化失败`;
483
+ 2. 是否安装了 `@koishijs/plugin-http`(`.ai` 需要);
484
+ 3. 未启用 `koishi-plugin-cron` 只影响定时任务,会在启动日志里打一条黄色警告。
485
+
486
+ **模型下载失败 / 卡住**
487
+ `embeddingRemoteHost` 默认走 `https://hf-mirror.com`;若网络环境不同,可改为 `https://huggingface.co`,
488
+ 或把模型文件手动放到 `embeddingCacheDir` 后把 `embeddingRemoteHost` 留空(离线)。
489
+
490
+ **内存占用偏高**
491
+ - 保持 `embeddingDtype="q8"`、调小 `embedBatchSize`;
492
+ - 调小 `maxChunksPerPage` / `textMaxLength` 以压缩索引体积(索引会整体载入内存);
493
+ - `ai.status` 会显示「索引体积」,超过 150 MB 建议按上文的 2G 推荐档收紧后 `ai.reindex`。
494
+
495
+ **Windows 上加载模型报 onnxruntime / DLL 找不到**
496
+ 安装 **Visual C++ 2015-2022 运行库(x64)**;另外确认页面文件(虚拟内存)足够大。
497
+
301
498
  **QQ 下只显示纯文本**
302
499
  markdown 与按钮依赖 `session.platform === "qq"`,请确认适配器正确上报平台。
303
500