koishi-plugin-oni-sync-bot 0.9.2 → 0.10.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/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "koishi-plugin-oni-sync-bot",
3
3
  "description": "缺氧Wiki站镜像点同步-测试",
4
- "version": "0.9.2",
4
+ "version": "0.10.0",
5
5
  "main": "lib/index.js",
6
6
  "typings": "lib/index.d.ts",
7
7
  "files": [
@@ -14,6 +14,9 @@
14
14
  "koishi",
15
15
  "plugin"
16
16
  ],
17
+ "scripts": {
18
+ "test": "tsc -p tsconfig.test.json && mocha --recursive .test-build/tests"
19
+ },
17
20
  "koishi": {
18
21
  "description": "缺氧Wiki站镜像点同步-测试",
19
22
  "service": {
@@ -22,7 +25,10 @@
22
25
  }
23
26
  },
24
27
  "devDependencies": {
25
- "@koishijs/client": "^5.30.11"
28
+ "@koishijs/client": "^5.30.11",
29
+ "@types/mocha": "^10.0.10",
30
+ "mocha": "^12.0.3",
31
+ "typescript": "^5.6.2"
26
32
  },
27
33
  "peerDependencies": {
28
34
  "@koishijs/plugin-console": "^5.30.11",
@@ -34,6 +40,6 @@
34
40
  "koishi-plugin-cron": "^3.1.0",
35
41
  "mwn": "^3.0.3",
36
42
  "node-fetch": "^3.3.2",
37
- "pinyin-pro": "^3.28.1"
43
+ "pinyin-pro": "^3.29.5"
38
44
  }
39
45
  }
package/readme.md CHANGED
@@ -4,300 +4,302 @@
4
4
  [![Koishi](https://img.shields.io/badge/koishi-plugin-42b983?style=flat-square)](https://koishi.chat)
5
5
  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
6
 
7
- **缺氧 Wiki 镜像站同步机器人插件** — 实现 [oxygennotincluded.wiki.gg](https://oxygennotincluded.wiki.gg) 与 B站 Wiki 镜像的双向内容同步、拼音匹配页面查询、模块同步管理,以及页面短链接重定向服务。
7
+ **缺氧 Wiki 镜像站同步机器人插件** — 把 [oxygennotincluded.wiki.gg](https://oxygennotincluded.wiki.gg)(下称 **GG 原站**)的内容**单向镜像**到 B站 Wiki(下称 **bwiki**),并提供拼音页面查询、模块同步待办管理、短链接跳转与通配转发。
8
+
9
+ > 同步方向是 **GG 原站 → bwiki 单向**,不会把 bwiki 的改动回写原站。
8
10
 
9
11
  ## ✨ 核心功能
10
12
 
11
13
  ### 📄 Wiki 同步
12
14
 
13
- - **双向登录** — 自动登录 wiki.gg 与 B站 Wiki(bwiki)两个站点
14
- - **页面同步** — 单个/批量页面从 wiki.gg 同步到 bwiki
15
- - **模块同步** — 批量同步 Module 命名空间页面
16
- - **图片同步** — 同步页面引用的图片文件(支持单个/批量)
17
- - **增量更新** — 每小时自动检测最近编辑并同步到镜像站
18
- - **自动重连** — 登录过期自动检测并重新登录(3次重试机制)
19
- - **登录重试** — 单次登录失败自动重试(最多3次,间隔5秒)
15
+ - **双站点登录** — 同时登录 GG 原站与 bwiki,登录失败自动重试(3 次,间隔 5 秒)
16
+ - **透明重登录** — 请求过程中一旦发现登录态失效(`assert=user`),自动重新登录并**重放该请求**,调用方无感知
17
+ - **页面同步** — 单个页面 / 全量页面
18
+ - **模块同步** — `Module:` 命名空间页面(含 `Dev:` → `Module:Dev/` 路径映射)
19
+ - **图片同步** — 下载原站图片并上传到 bwiki,支持 SHA1 比对跳过与旧版本清理
20
+ - **贡献者同步** — 单页 / 全量同步贡献者与最后修改时间
21
+ - **增量更新** — 每小时取最近 3 小时的 `recentchanges` 并同步
20
22
 
21
23
  ### 🔍 页面查询
22
24
 
23
- - **精准匹配** — 标题/全拼/首字母精确匹配
24
- - **拼音模糊匹配** — 支持中文名称的拼音搜索
25
- - **QQ Markdown 按钮** — QQ群查询结果以可点击按钮形式呈现(点击即跳转页面)
26
- - **命令别名** — `x` / `查wiki` 快捷命令
25
+ - **三段精准匹配** — 标题 → 全拼 → 首字母,逐级尝试
26
+ - **拼音模糊匹配** — 打分排序(标题包含 / 全拼前缀 / 公共前缀等),最多返回 5 条
27
+ - **QQ 平台按钮** — QQ 会话下返回 markdown + 可点击按钮;其它平台返回纯文本
28
+ - **序号选择** — 非 QQ 平台列出候选并要求 15 秒内回复序号
27
29
 
28
30
  ### 📋 模块同步 TodoList
29
31
 
30
- - **自动同步** — 每周一 00:00 自动同步 wiki.gg 所有 Module 到待办
31
- - **状态检查** — 每周二 00:00 自动检查模块同步状态(对比修订时间)
32
- - **控制台管理** — 萌系风格可视化管理界面,支持搜索/筛选/分页
33
- - **增删改查** — 完整的待办管理命令和控制台操作
34
- - **权限控制** — 删除/清空操作需权限 2,删除缓存需权限 4
35
-
36
- ### � 路由重定向
32
+ - **自动纳管** — 每周一 00:00 拉取原站全部 Module 写入待办
33
+ - **状态检查** — 每周二 00:00 对比两侧修订时间,自动标记完成 / 未完成
34
+ - **控制台界面** — 搜索、筛选、分页、增删改查
35
+ - **权限** — 删除 / 清空需权限 2,清空页面缓存需权限 4
37
36
 
38
- - **短链接服务** — `/:id` → 跳转至完整 Wiki 页面 URL
39
- - **GG 原站跳转** — `/gg/:id` → 跳转至 oxygennotincluded.wiki.gg 对应页面
40
- - **Bwiki 镜像跳转** — `/bw/:id` → 跳转至 wiki.biligame.com/oni 对应页面
41
- - **通配路径转发** — `/ggwiki/*` → 转发任意路径和查询参数到原站
42
- - **持久化缓存** — 页面标题和页面ID映射保存在本地数据库,首次启动需执行 `update`
37
+ ### 🔌 路由
43
38
 
44
- ### 🎮 特殊指令
39
+ - **短链跳转** — `/gg/:id`、`/bw/:id` 按数据库中的页面 ID 跳转
40
+ - **通配转发** — `/ggwiki/*` 转发任意路径与查询参数到原站(含路径遍历防护)
45
41
 
46
- - **火箭计算器** — 查询 "火箭计算器" 返回计算器工具链接提示
47
-
48
- ## 📦 项目结构
42
+ ## 🚀 安装
49
43
 
44
+ ```bash
45
+ npm install koishi-plugin-oni-sync-bot
46
+ # 或
47
+ yarn add koishi-plugin-oni-sync-bot
50
48
  ```
51
- oni-sync-bot/
52
- ├── src/
53
- │ ├── index.ts # 插件入口(子插件注册表)
54
- │ ├── services/
55
- │ │ ├── wikiBotService.ts # Wiki 机器人核心服务(登录、重连、代理)
56
- │ │ └── consoleLogProvider.ts # 控制台日志服务
57
- │ ├── plugins/
58
- │ │ ├── databaseExtension.ts # 数据库模型扩展(wikipages 表)
59
- │ │ ├── queryCommands.ts # 页面查询命令(x / 查wiki)
60
- │ │ ├── syncCommands.ts # Wiki 同步命令(sync.*)+ 定时任务
61
- │ │ ├── updateCommands.ts # 缓存管理命令(update.* / redirect / relogin)
62
- │ │ ├── routeRedirect.ts # 路由重定向服务(/gg / /bw / /ggwiki)
63
- │ │ └── todoList.ts # TodoList 模块同步管理(命令 + 控制台 + 定时任务)
64
- │ ├── sync/
65
- │ │ ├── pageSync.ts # 页面同步逻辑(单页、全量、增量)
66
- │ │ ├── moduleSync.ts # 模块同步逻辑
67
- │ │ └── imgSync.ts # 图片同步逻辑
68
- │ └── utils/
69
- │ └── tools.ts # 工具函数(拼音生成、日志、错误处理)
70
- ├── client/
71
- │ ├── Rocketcalculator/ # 火箭计算器前端页面
72
- │ │ ├── calculator.ts
73
- │ │ ├── calculator.vue
74
- │ │ ├── config.ts
75
- │ │ ├── index.vue
76
- │ ├── onitodolist/ # TodoList 管理前端页面
77
- │ │ ├── index.vue
78
- │ │ └── todolist.vue
79
- │ ├── index.ts
80
- │ ├── page.vue # 日志查看页面
81
- │ └── tsconfig.json
82
- ├── package.json
83
- ├── tsconfig.json
84
- └── README.md
85
- ```
86
-
87
- ## 🔧 架构设计
88
-
89
- ### 子插件模式
90
-
91
- 主入口 `src/index.ts` 采用依赖顺序注册子插件:
92
49
 
93
- ```
94
- Service 层(数据库、WikiBot 服务)
95
- ↓
96
- Core 层(同步逻辑、路由重定向)
97
- ↓
98
- Command 层(查询命令、同步命令、更新命令、TodoList)
99
- ↓
100
- UI 层(控制台日志、TodoList 可视化面板、火箭计算器)
101
- ```
50
+ ### 依赖服务
102
51
 
103
- ### 数据库模型
52
+ 插件需要以下 Koishi 插件(通常已随 Koishi 提供):
104
53
 
105
- | 表名 | 字段 | 说明 |
106
- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
107
- | `wikipages` | `id` (integer), `title` (string), `pinyin_full` (string), `pinyin_first` (string) | Wiki 页面索引缓存,支持拼音检索 |
108
- | `onitodos` | `id` (unsigned, auto), `title` (string), `content` (text), `completed` (boolean), `createdBy` (string), `createdAt` (timestamp), `updatedAt` (timestamp) | 模块同步待办事项 |
54
+ - `@koishijs/plugin-database`(`wikipages` / `onitodos` 持久化)
55
+ - `@koishijs/plugin-server`(短链路由)
56
+ - `@koishijs/plugin-console`(控制台页面与日志查看)
57
+ - `koishi-plugin-cron`(定时任务)
58
+ - 任意适配器(可选;QQ 适配器才能看到 markdown 按钮效果)
109
59
 
110
- ### 核心技术
60
+ ## ⚙️ 配置项
111
61
 
112
- | 技术 | 用途 |
113
- | ---------------------------- | -------------------------------------------- |
114
- | **TypeScript** | 完整类型支持,严格模式编译 |
115
- | **Koishi 4** | 机器人框架,基于 Service 和 Plugin 架构 |
116
- | **Mwn** | MediaWiki API 客户端(wiki.gg / bwiki 交互) |
117
- | **pinyin-pro** | 中文转拼音,支持页面名称模糊匹配 |
118
- | **koishi-plugin-cron** | 定时任务调度(每小时增量更新、每周同步等) |
119
- | **@koishijs/plugin-console** | Koishi 控制台(提供可视化管理界面) |
120
- | **@koishijs/plugin-server** | HTTP 服务器(提供短链接重定向路由) |
62
+ 配置 schema 的**唯一声明处**是 [`src/config.ts`](src/config.ts),分为四个分组:账号、站点、通知、定时任务。
121
63
 
122
- ## ⚙️ 配置项
64
+ | 参数 | 分组 | 说明 | 默认值 |
65
+ | ------------------- | ---- | ---------------------------------------- | ------------------------------ |
66
+ | `ggUsername` | 账号 | GG 原站用户名 | `1` |
67
+ | `ggPassword` | 账号 | GG 原站密码 | `1` |
68
+ | `bwikiusername` | 账号 | bwiki 用户名 | `1` |
69
+ | `bwikipassword` | 账号 | bwiki 密码 | `1` |
70
+ | `domain` | 站点 | 短链域名(用于生成按钮与提示里的链接) | `klei.vip` |
71
+ | `main_site` | 站点 | 主站域名(GG 原站) | `oxygennotincluded.wiki.gg/zh` |
72
+ | `bwiki_site` | 站点 | 镜像站域名(bwiki) | `wiki.biligame.com/oni` |
73
+ | `logsUrl` | 通知 | 日志查看地址,出现在命令回复里 | `https://klei.vip/onilogs` |
74
+ | `notifyGroupIds` | 通知 | 增量更新成功后通知的群频道 ID 列表;留空则不通知 | `[]` |
75
+ | `notifyBotPlatform` | 通知 | 发送通知所用的 bot 平台标识 | `qq` |
76
+ | `updateCron` | 定时 | 页面缓存自动更新的 cron 表达式 | `0 2 * * *`(每天 02:00) |
123
77
 
124
- | 参数 | 说明 | 默认值 | 必需 |
125
- | --------------- | ------------------- | ------------------------------ | ---- |
126
- | `ggUsername` | WIKIGG 用户名 | `1` | ✅ |
127
- | `ggPassword` | WIKIGG 密码 | `1` | ✅ |
128
- | `bwikiusername` | Bwiki 用户名 | `1` | ✅ |
129
- | `bwikipassword` | Bwiki 密码 | `1` | ✅ |
130
- | `domain` | 你的短链域名 | `klei.vip` | ✅ |
131
- | `main_site` | 主站域名(wiki.gg) | `oxygennotincluded.wiki.gg/zh` | ✅ |
132
- | `bwiki_site` | 镜像站域名(bwiki) | `wiki.biligame.com/oni` | ✅ |
133
- | `logsUrl` | 日志查看地址 | `https://klei.vip/onilogs` | - |
78
+ > **默认值形同虚设**:账号默认值是 `1`,必须改成真实账号,否则登录一定失败。
134
79
 
135
80
  ## 📚 命令列表
136
81
 
137
- ### 🔍 查询命令
138
-
139
- | 命令 | 别名 | 说明 | 权限 |
140
- | --------------- | -------- | ------------------------------ | ---- |
141
- | `x <itemName>` | `查wiki` | 查询页面(标题/拼音/模糊匹配) | - |
142
- | `查询 <关键词>` | - | 同上(备用命令名) | - |
143
-
144
- ### 🔄 同步命令
145
-
146
- | 命令 | 别名 | 说明 | 权限 |
147
- | ------------------------ | ---------- | -------------------- | ---- |
148
- | `sync <标题>` | - | 同步单个页面到 bwiki | 2 |
149
- | `sync.allpages` | - | 同步所有页面 | 2 |
150
- | `sync.module <模块名>` | - | 同步单个模块 | 2 |
151
- | `sync.allmodules` | - | 同步所有模块 | 2 |
152
- | `sync.img <图片名>` | - | 同步单张图片 | 2 |
153
- | `sync.allimgs` | - | 同步所有图片 | 2 |
154
- | `sync.incrementalUpdate` | `增量更新` | 执行增量更新 | 2 |
155
-
156
- ### 📝 缓存管理
157
-
158
- | 命令 | 别名 | 说明 | 权限 |
159
- | ------------------------------ | ---------- | ----------------------------------- | ---- |
160
- | `update` | - | 更新本地页面缓存(从 wiki.gg 获取) | 2 |
161
- | `update.status` | - | 查询缓存数量和状态 | 1 |
162
- | `update.delete` | - | 清空页面缓存 | 4 |
163
- | `redirect <原页面> <目标页面>` | `重定向` | 在 wiki.gg 创建重定向页面 | 2 |
164
- | `relogin` | `重新登录` | 手动重新登录两个 Wiki 机器人 | 2 |
165
-
166
- ### ✅ TodoList 命令
167
-
168
- | 命令 | 别名 | 说明 | 权限 |
169
- | ---------------------- | -------- | ---------------------------------------- | ---- |
170
- | `todolist` | `todo` | 查看 TodoList(跳转网页) | - |
171
- | `todo.list` | `todo.l` | 查看 TodoList(跳转网页) | - |
172
- | `todo.add <标题>` | `todo.a` | 添加待办事项(支持 `-c` `-u` 选项) | - |
173
- | `todo.edit <id>` | `todo.e` | 编辑待办事项(支持 `-t` `-c` `-u` 选项) | - |
174
- | `todo.complete <id>` | `todo.c` | 标记待办为完成 | - |
175
- | `todo.uncomplete <id>` | `todo.u` | 标记待办为未完成 | - |
176
- | `todo.delete <id>` | `todo.d` | 删除待办事项 | 2 |
177
- | `todo.clear` | - | 清空 TodoList | 2 |
178
- | `todo.syncmodules` | - | 手动同步 wiki.gg 模块到 TodoList | - |
179
- | `todo.checksync` | - | 手动检查模块同步状态 | - |
82
+ > 命令名**不区分大小写**;下表中的「命令」是注册时的规范名称。
83
+
84
+ ### 🔍 查询
85
+
86
+ | 命令 | 别名 | 说明 | 权限 |
87
+ | ------------------- | --------- | -------------------------------- | ---- |
88
+ | `x <itemName:text>` | `/查wiki` | 查询页面(标题 / 全拼 / 首字母) | - |
89
+
90
+ ### 🔄 同步
91
+
92
+ | 命令 | 别名 | 说明 | 权限 |
93
+ | --------------------------- | ---------- | -------------------- | ---- |
94
+ | `sync <pageTitle:string>` | - | 同步单个页面到 bwiki | 2 |
95
+ | `sync.allpages` | - | 同步所有页面 | 2 |
96
+ | `sync.module <moduleTitle>` | - | 同步单个模块 | 2 |
97
+ | `sync.allmodules` | - | 同步所有模块 | 2 |
98
+ | `sync.img <imgTitle>` | - | 同步单张图片 | 2 |
99
+ | `sync.allimgs` | - | 同步所有图片 | 2 |
100
+ | `sync.contributor <title>` | - | 同步指定页面的贡献者 | 2 |
101
+ | `sync.allcontributors` | - | 同步所有页面的贡献者 | 2 |
102
+ | `sync.incrementalUpdate` | `增量更新` | 执行一次增量更新 | 2 |
103
+
104
+ ### 📝 缓存与登录
105
+
106
+ | 命令 | 别名 | 说明 | 权限 |
107
+ | ---------------------------------------- | ---------- | ------------------------------- | ---- |
108
+ | `update` | - | 从原站拉取页面列表更新本地缓存 | 2 |
109
+ | `update.status` | - | 查询缓存条目数量 | 1 |
110
+ | `update.delete` | - | 清空页面缓存 | 4 |
111
+ | `redirect <pageName> <targetPageName>` | `重定向` | 在原站创建 `#REDIRECT` 页面 | 2 |
112
+ | `relogin` | `重新登录` | 手动重新登录两个站点 | 2 |
113
+
114
+ ### ✅ TodoList
115
+
116
+ | 命令 | 别名 | 说明 | 权限 |
117
+ | ------------------------ | -------- | ---------------------------------------- | ---- |
118
+ | `todolist` | `todo` | 跳转 TodoList 网页 | - |
119
+ | `todolist.list` | `todo.l` | 同上 | - |
120
+ | `todolist.add <title>` | `todo.a` | 新增待办(`-c` 内容 / `-u` 创建人) | - |
121
+ | `todolist.edit <id>` | `todo.e` | 编辑待办(`-t` 标题 / `-c` 内容 / `-u`) | - |
122
+ | `todolist.complete <id>` | `todo.c` | 标记完成 | - |
123
+ | `todolist.uncomplete <id>`| `todo.u`| 标记未完成 | - |
124
+ | `todolist.delete <id>` | `todo.d` | 删除待办 | 2 |
125
+ | `todolist.clear` | - | 清空 TodoList | 2 |
126
+ | `todolist.syncmodules` | - | 手动把原站模块写入 TodoList | - |
127
+ | `todolist.checksync` | - | 手动检查模块同步状态 | - |
128
+
129
+ > 因为 `todolist` 的别名是 `todo`,Koishi 会把 `todo.list` 这类写法解析到 `todolist.list`,两种写法都能用。
130
+ >
131
+ > 另有 4 个命令来自 Koishi 核心插件而非本插件:`help`、`status`、`clear`、`command`。
180
132
 
181
133
  ## ⏰ 定时任务
182
134
 
183
- | 时间 | 任务 | 说明 |
184
- | ---------------- | ------------------- | -------------------------------------- |
185
- | **每小时 15 分** | 增量更新 | 获取最近编辑并同步到 bwiki |
186
- | **每周四 08:30** | 同步所有页面 | 从 wiki.gg 全量同步页面到 bwiki |
187
- | **每周三 08:30** | 同步所有图片 | 从 wiki.gg 全量同步图片资源 |
188
- | **每周一 00:00** | 同步模块到 TodoList | 获取所有 Module 命名空间页面并写入待办 |
189
- | **每周二 00:00** | 检查模块同步状态 | 对比修订时间,自动标记完成/未完成 |
135
+ | cron | 时间 | 任务 | 说明 |
136
+ | -------------- | --------------- | ----------------------- | -------------------------------------- |
137
+ | `15 * * * *` | 每小时第 15 分 | 增量更新 | 同步最近 3 小时的编辑 |
138
+ | `0 2 * * *` | 每天 02:00 | 页面缓存自动更新 | 由 `updateCron` 配置,默认值如左 |
139
+ | `30 8 * * 3` | 每周三 08:30 | 同步所有图片 | — |
140
+ | `30 8 * * 4` | 每周四 08:30 | 同步所有页面 | — |
141
+ | `0 0 2 * * 0` | 每周日 02:00 | 同步所有贡献者 | — |
142
+ | `0 0 * * 1` | 每周一 00:00 | 同步模块到 TodoList | 拉取 `Module:` 命名空间页面写入待办 |
143
+ | `0 0 * * 2` | 每周二 00:00 | 检查模块同步状态 | 对比两侧修订时间,自动标记完成 / 未完成 |
190
144
 
191
145
  ## 🔌 路由接口
192
146
 
193
- | 路径 | 方法 | 说明 |
194
- | ----------- | ---- | --------------------------------------------------------- |
195
- | `/gg/:id` | GET | 跳转至 oxygennotincluded.wiki.gg 对应页面(自动编码标题) |
196
- | `/bw/:id` | GET | 跳转至 wiki.biligame.com/oni 对应页面 |
197
- | `/ggwiki/*` | GET | 通配路径转发至 oxygennotincluded.wiki.gg,保留查询参数 |
198
-
199
- > � **提示**:首次部署请先执行 `update` 命令填充 `wikipages` 表,否则路由跳转将返回"未找到页面"提示。
147
+ | 路径 | 方法 | 说明 |
148
+ | ----------- | ------------------ | ----------------------------------------------------------- |
149
+ | `/gg/:id` | GET | 跳转至 `main_site` 对应页面(标题自动编码,附带 `?variant=zh`) |
150
+ | `/bw/:id` | GET | 跳转至 `bwiki_site` 对应页面 |
151
+ | `/ggwiki/*` | 任意(`server.use`)| 原样转发到 `main_site`,保留查询参数;带路径遍历与字符校验 |
200
152
 
201
- ## 🚀 安装
153
+ `/gg/:id` 与 `/bw/:id` 的 `:id` 是**数据库中的页面 ID**,不是标题。首次部署请先执行 `update` 填充缓存,否则会返回「未找到ID为【…】的页面」。
202
154
 
203
- ```bash
204
- npm install koishi-plugin-oni-sync-bot
205
- # 或
206
- yarn add koishi-plugin-oni-sync-bot
207
- ```
155
+ ## 🗄️ 数据库模型
208
156
 
209
- ## 🔨 开发
157
+ | 表名 | 字段 |
158
+ | ----------- | --------------------------------------------------------------------------------------------------------------- |
159
+ | `wikipages` | `id`、`title`、`pinyin_full`、`pinyin_first`、`contributor`、`change_time` |
160
+ | `onitodos` | `id`、`title`、`content`、`completed`、`createdBy`、`createdAt`、`updatedAt` |
210
161
 
211
- ```bash
212
- # 克隆项目
213
- git clone https://github.com/Charles-LF/oni-sync-bot.git
162
+ `wikipages` 通过 `Tables` 接口增强声明(见 `databaseExtension.ts`);`onitodos` 目前**没有**做接口增强。
214
163
 
215
- # 安装依赖
216
- yarn install
164
+ ## 🎨 控制台界面
217
165
 
218
- # 构建
219
- yarn build
166
+ 插件在 Koishi 控制台注册一个入口页与两个子页面(见 [`client/index.ts`](client/index.ts)):
220
167
 
221
- # 开发模式
222
- yarn dev
223
- ```
168
+ | 页面 | 源码位置 | 功能 |
169
+ | -------------- | ------------------------- | ------------------------------------------- |
170
+ | 同步机器人首页 | `client/onilogs/` | 查看 `oni-sync` 命名空间日志(最多保留 1000 条) |
171
+ | 缺氧 TodoList | `client/onitodolist/` | 待办的可视化增删改查 |
172
+ | 火箭计算器 | `client/Rocketcalculator/`| ONI 火箭设计计算器 |
224
173
 
225
- ### 依赖服务
174
+ ## 📦 项目结构
226
175
 
227
- 插件正常运行需以下 Koishi 核心插件(Koishi 默认已提供):
176
+ ```
177
+ src/
178
+ ├── index.ts # 组合根:SUB_PLUGINS 注册表 + 控制台入口
179
+ ├── config.ts # 配置的唯一声明处(账号 / 站点 / 通知 / 定时 四组)
180
+ ├── services/
181
+ │ ├── wikiBotService.ts # wikiBot 服务:登录、代理、透明重登录
182
+ │ ├── messageRenderer.ts # QQ markdown+按钮 / 纯文本 的渲染
183
+ │ └── consoleLogProvider.ts # 控制台日志服务(onilogs)
184
+ ├── plugins/
185
+ │ ├── databaseExtension.ts # wikipages 表定义
186
+ │ ├── queryCommands.ts # x / 查wiki
187
+ │ ├── syncCommands.ts # sync.* 命令 + 同步相关定时任务
188
+ │ ├── updateCommands.ts # update.* / redirect / relogin
189
+ │ ├── routeRedirect.ts # 短链路由
190
+ │ └── todoList.ts # TodoList 命令 + 控制台监听 + 定时任务
191
+ ├── sync/
192
+ │ ├── pageSync.ts # PageSyncer:单页 / 全量 / 增量更新
193
+ │ ├── moduleSync.ts # ModuleSyncer:模块同步
194
+ │ └── imgSync.ts # ImageSyncer:图片同步
195
+ └── utils/
196
+ ├── tools.ts # 拼音、时间格式化、标题规范化等
197
+ ├── async.ts # sleep + withRetry(全项目统一的重试语义)
198
+ └── matcher.ts # 查询打分与模糊匹配(纯函数,可单测)
199
+
200
+ tests/ # 单元测试
201
+ client/ # 控制台前端(Vue)
202
+ ```
228
203
 
229
- - **@koishijs/plugin-database** — 数据持久化(wikipages / onitodos)
230
- - **@koishijs/plugin-server** — HTTP 服务器(短链接路由)
231
- - **@koishijs/plugin-console** — 控制台 UI(TodoList 管理界面)
232
- - **koishi-plugin-cron** — 定时任务调度
233
- - **@koishijs/plugin-adapter-\*(可选)** — 如 QQ 适配器,以获得 Markdown 按钮效果
204
+ ## 🧩 架构与扩展
234
205
 
235
- ## 📊 使用示例
206
+ ### 组合根
236
207
 
237
- ### 🔍 查询页面
208
+ [`src/index.ts`](src/index.ts) 是唯一的组合根。它按**依赖顺序**注册一组子插件:
238
209
 
239
210
  ```
240
- > x 精炼器
211
+ WikiBotService(提供 wikiBot 服务,必须最先)
212
+ ↓
213
+ ConsoleLogProvider / DatabaseExtension(提供 console 数据源与数据表)
214
+ ↓
215
+ RouteRedirect / SyncCommands / QueryCommands / UpdateCommands / TodoList
216
+ ```
241
217
 
242
- 🔍 为你找到【3】个相似结果,请点击下方按钮查看详情:
218
+ 所有子插件共享**同一个配置对象**,因此注册时统一传 `config`;不需要配置的子插件会忽略它。
243
219
 
244
- 1. [精炼器]
245
- 2. [蒸汽精炼器]
246
- 3. [岩浆精炼器]
220
+ ### 如何新增一个子插件
247
221
 
248
- (QQ 平台显示可点击按钮,点击即跳转 Wiki 页面;非 QQ 平台返回纯文本)
249
- ```
222
+ 1. 新建一个类,用 `static readonly inject` 声明它依赖哪些服务(例如 `["database", "wikiBot"]`);
223
+ 2. 把它加进 `src/index.ts` 的 `SUB_PLUGINS` 数组;
224
+ 3. 如果需要配置,在 `src/config.ts` 的**对应分组**里补字段,再用 `Pick` / `extends` 引用。
250
225
 
251
- ### 🔄 同步页面
226
+ ```ts
227
+ // src/plugins/myFeature.ts
228
+ import { Context } from "koishi";
229
+ import type { SiteConfig } from "../config";
252
230
 
231
+ export class MyFeature {
232
+ public static readonly inject = ["database"];
233
+ constructor(ctx: Context, public config: Pick<SiteConfig, "domain">) {
234
+ // ...
235
+ }
236
+ }
253
237
  ```
254
- > sync 精炼器
255
238
 
256
- ✅ 已尝试同步页面:精炼器,请前往控制台查看
239
+ ```ts
240
+ // src/index.ts —— 只改这一行
241
+ const SUB_PLUGINS = [/* ... */, MyFeature] as const;
257
242
  ```
258
243
 
259
- ### ✅ 标记待办完成
244
+ > ⚠️ **不要**在子插件里重复声明已有的配置键。所有键只在 `src/config.ts` 声明一次,重复声明会在 `Schema.intersect` 合并时产生"同一字段多份",且后者静默覆盖前者。
260
245
 
261
- ```
262
- > todo.complete 5
246
+ ### 如何新增一条命令
247
+
248
+ 在对应子插件的 `registerCommands()` 里链式调用即可:
263
249
 
264
- ✅ 已标记完成,请访问 https://klei.vip/onitodos 查看
250
+ ```ts
251
+ ctx.command("my.cmd <arg:string>", "说明", { authority: 2 })
252
+ .alias("我的命令")
253
+ .action(async ({ session }, arg) => {
254
+ return "回复内容";
255
+ });
265
256
  ```
266
257
 
267
- ## 🎨 控制台界面
258
+ 要点:
268
259
 
269
- 插件在 Koishi 控制台提供以下管理页面:
260
+ - `session` 可能是 `undefined`(命令也可能被控制台/程序化调用),发送消息请用 `session?.send(...)`;
261
+ - `.option()` 声明过的选项在 action 里请用解构默认值 `options = {}`,避免 `undefined`;
262
+ - 回复内容用 `return` 即可;需要按平台渲染时用 `MessageRenderer`。
270
263
 
271
- | 页面 | 功能 |
272
- | ------------------------------------ | ---------------------------------------------------- |
273
- | **日志控制台** (`page.vue`) | 按级别筛选日志,搜索内容,自动滚动,快速跳转 |
274
- | **TodoList 管理** (`onitodolist/`) | 萌系 UI 设计,新增/编辑/标记完成,搜索筛选,分页显示 |
275
- | **火箭计算器** (`Rocketcalculator/`) | ONI 火箭设计计算器 |
264
+ ### 如何新增同步逻辑
276
265
 
277
- ## 🔒 安全与权限
266
+ `src/sync/` 下的三个类都是 `(source, target, deps?)` 的统一构造签名,选项通过 `deps.options` 注入并有默认值。新增一种同步器请沿用该形状,不要引入模块级可变状态。
278
267
 
279
- - 所有 Wiki 编辑操作(同步、创建重定向)需权限 **2**
280
- - 删除页面缓存需权限 **4**
281
- - 登录凭证(用户名/密码)仅保存在 Koishi 配置中,不会写入日志
282
- - WikiBotService 通过 **Proxy** 模式透明处理登录过期,自动重新登录后继续执行原请求
268
+ ## 🧪 测试与开发
283
269
 
284
- ## 🐛 故障排查
270
+ 本仓库**只有** `test` 脚本:
285
271
 
286
- ### "❌ 本地缓存为空"
272
+ ```bash
273
+ yarn test # tsc 编译到 .test-build/,再用 mocha 跑
274
+ ```
275
+
276
+ 测试用 `tsc` 进程内编译 + `mocha` 单进程加载,**不依赖 esbuild / ts-node**。
287
277
 
288
- 请管理员执行 `update` 命令从 wiki.gg 获取页面列表。
278
+ > `yarn build` 与 `yarn dev` 来自 **Koishi 实例根**,不在本仓库 —— 本插件按 Koishi 约定的
279
+ > workspace 方式放在实例的 `external/` 目录下,由实例的 yakumo 统一构建。
289
280
 
290
- ### "❌ Wiki 机器人未就绪"
281
+ ## 🔒 安全与权限
282
+
283
+ - 所有写操作(同步页面 / 创建重定向 / 删除待办)需要权限 **2**
284
+ - 清空页面缓存需要权限 **4**
285
+ - 账号密码只保存在 Koishi 配置中,不写入日志
286
+ - 登录过期由 `WikiBotService` 内部的代理透明处理,自动重登后重放原请求
287
+ - `/ggwiki/*` 做了路径遍历(`..`)与非法字符校验
291
288
 
292
- 检查配置中的账号密码是否正确;可执行 `relogin` 手动重新登录。
289
+ ## 🐛 故障排查
293
290
 
294
- ### "❌ 未找到ID为【...】的页面"
291
+ **`❌ WikiBotService 初始化失败,两个 Wiki 均无法登录`**
292
+ 检查 `ggUsername` / `ggPassword` / `bwikiusername` / `bwikipassword`。默认值 `1` 是占位符。
293
+ 可执行 `relogin` 手动重试。注意短时间内反复失败会触发服务端限流,需等待约 5 分钟。
295
294
 
296
- 页面ID不在本地缓存中,可能是最近新增的页面。执行 `update` 更新缓存后再试。
295
+ **`❌ 本地缓存为空,请联系管理员执行【update】指令更新缓存!`**
296
+ 执行 `update` 从原站拉取页面列表。
297
297
 
298
- ### QQ 机器人只显示纯文本
298
+ **`❌ 未找到ID为【…】的页面`**
299
+ 页面不在本地缓存中(可能是新增页面),先执行 `update`。
299
300
 
300
- QQ 平台的 Markdown 与按钮效果需要 `session.platform === "qq"` 检测生效。请确认适配器正确上报平台信息。
301
+ **QQ 下只显示纯文本**
302
+ markdown 与按钮依赖 `session.platform === "qq"`,请确认适配器正确上报平台。
301
303
 
302
304
  ## 📜 License
303
305
 
@@ -305,7 +307,7 @@ MIT License
305
307
 
306
308
  ## 🤝 贡献
307
309
 
308
- 欢迎提交 Issue 和 Pull Request!
310
+ 欢迎提交 Issue 和 Pull Request。
309
311
 
310
312
  ## 📧 支持
311
313
 
@@ -1,13 +0,0 @@
1
- import { Context, Logger } from "koishi";
2
- declare module "@koishijs/console" {
3
- namespace Console {
4
- interface Services {
5
- onilogs: DataService<Logger.Record[]>;
6
- }
7
- }
8
- }
9
- export declare class ConsoleLogProvider {
10
- static readonly inject: string[];
11
- constructor(ctx: Context);
12
- }
13
- export declare function apply(ctx: Context): void;
@@ -1,15 +0,0 @@
1
- import { Context } from "koishi";
2
- export interface ContributorConfig {
3
- }
4
- export declare class SyncContributor {
5
- private config;
6
- static readonly inject: string[];
7
- private logger;
8
- private ctx;
9
- constructor(ctx: Context, config: ContributorConfig);
10
- private setupWeeklySchedule;
11
- private executeSyncAllContributors;
12
- private registerCommands;
13
- private syncSinglePage;
14
- }
15
- export declare function apply(ctx: Context, config: ContributorConfig): void;