koishi-plugin-oni-sync-bot 0.8.5 → 0.8.7

package/lib/index.js

@@ -1424,18 +1424,21 @@ var QueryCommands = class {
   }
   static inject = ["database"];
   config;
+  ctx;
   constructor(ctx, config) {
+    this.ctx = ctx;
     this.config = config;
     this.registerCommands(ctx);
   }
   registerCommands(ctx) {
-    ctx.command("x <itemName>", "查询缺氧中文wiki，精准匹配+拼音模糊匹配").alias("/查wiki").action(async ({ session }, itemName = "") => {
+    ctx.command("x <itemName:text>", "查询缺氧中文wiki，精准匹配+拼音模糊匹配").alias("/查wiki").action(async ({ session }, itemName = "") => {
       const queryKey = itemName.trim().toLowerCase();
       if (!queryKey) {
-        return this.getUsageMessage();
+        return this.renderUsageMessage(session);
       }
       if (SPECIAL_CASES.has(queryKey)) {
-        return SPECIAL_CASES.get(queryKey);
+        const content = SPECIAL_CASES.get(queryKey);
+        return this.sendResponse(session, content);
       }
       const { pinyin_full: queryPinyinFull, pinyin_first: queryPinyinFirst } = generatePinyinInfo(queryKey);
       const preciseMatch = await this.findPreciseMatch(
@@ -1445,14 +1448,18 @@ var QueryCommands = class {
         queryPinyinFirst
       );
       if (preciseMatch) {
-        return this.formatResultMessage(
+        return this.renderResultMessage(
+          session,
           preciseMatch,
           preciseMatch.prefix
         );
       }
       const allPages = await ctx.database.get("wikipages", {});
       if (allPages.length === 0) {
-        return `❌ 本地缓存为空，请联系管理员执行【update】指令更新缓存！`;
+        return this.sendResponse(
+          session,
+          "❌ 本地缓存为空，请联系管理员执行【update】指令更新缓存！"
+        );
       }
       const fuzzyMatches = this.findFuzzyMatches(
         allPages,
@@ -1461,23 +1468,139 @@ var QueryCommands = class {
         queryPinyinFirst
       );
       if (fuzzyMatches.length === 0) {
-        return `❌ 未找到【${queryKey}】相关内容，请按游戏内标准名称重新查询！`;
+        return this.sendResponse(
+          session,
+          `❌ 未找到【${queryKey}】相关内容，请按游戏内标准名称重新查询！`
+        );
       }
       return await this.handleSelection(session, fuzzyMatches);
     });
   }
-  getUsageMessage() {
+  isQQPlatform(session) {
+    return session?.platform === "qq";
+  }
+  buildLinkButton(idSuffix, label, url) {
+    return {
+      id: `btn-${idSuffix}`,
+      render_data: {
+        label,
+        visited_label: "已打开",
+        style: 1
+      },
+      action: {
+        type: 0,
+        permission: {
+          type: 2
+        },
+        data: url
+      }
+    };
+  }
+  buildQQKeyboard(matches) {
+    const rows = [];
+    for (let i = 0; i < matches.length; i += 2) {
+      const buttonsInRow = matches.slice(i, i + 2).map((item) => {
+        const label = item.title.length > 10 ? item.title.slice(0, 10) : item.title;
+        return this.buildLinkButton(
+          `${item.id}`,
+          label,
+          `https://${this.config.domain}/bw/${item.id}`
+        );
+      });
+      rows.push({ buttons: buttonsInRow });
+    }
+    return {
+      content: { rows }
+    };
+  }
+  async sendResponse(session, content, keyboard) {
+    if (this.isQQPlatform(session)) {
+      try {
+        const payload = {
+          msg_id: session.messageId,
+          msg_type: 2,
+          markdown: {
+            content
+          }
+        };
+        if (keyboard) {
+          payload.keyboard = keyboard;
+        }
+        await session.bot.internal.sendMessage(session.channelId, payload);
+        return;
+      } catch (e) {
+        this.ctx.logger("oni-sync-bot").warn("QQ Markdown 发送失败，降级为纯文本:", e);
+        return content;
+      }
+    }
+    return content;
+  }
+  renderUsageMessage(session) {
+    if (this.isQQPlatform(session)) {
+      const md = `**以下是使用说明：**
+> GG原站点: [https://${this.config.domain}/gg/88888888](https://${this.config.domain}/gg/88888888)
+
+> bwiki: [https://${this.config.domain}/bw/88888888](https://${this.config.domain}/bw/88888888)
+`;
+      return this.sendResponse(session, md);
+    }
     return `以下是使用说明：
-原站点: https://${this.config.domain}/gg/88888888
+GG原站点: https://${this.config.domain}/gg/88888888
 
 bwiki: https://${this.config.domain}/bw/88888888`;
   }
-  formatResultMessage(match, prefix) {
+  buildResultKeyboard(match) {
+    return {
+      content: {
+        rows: [
+          {
+            buttons: [
+              this.buildLinkButton(
+                `gg-${match.id}`,
+                "GG 原站",
+                `https://${this.config.domain}/gg/${match.id}`
+              )
+            ]
+          },
+          {
+            buttons: [
+              this.buildLinkButton(
+                `bw-${match.id}`,
+                "Bwiki 镜像",
+                `https://${this.config.domain}/bw/${match.id}`
+              )
+            ]
+          },
+          {
+            buttons: [
+              this.buildLinkButton(
+                `wiki-${match.id}`,
+                "GG直链",
+                `https://oxygennotincluded.wiki.gg/zh/${encodeURIComponent(match.title)}`
+              )
+            ]
+          }
+        ]
+      }
+    };
+  }
+  renderResultMessage(session, match, prefix) {
+    if (this.isQQPlatform(session)) {
+      let md = "";
+      if (prefix) {
+        md += `**${prefix}**
+`;
+      }
+      md += `**📖 ${match.title}**
+`;
+      const keyboard = this.buildResultKeyboard(match);
+      return this.sendResponse(session, md, keyboard);
+    }
     let message = "";
     if (prefix) {
       message += prefix + "\n";
     }
-    message += `原站点: https://${this.config.domain}/gg/${match.id}
+    message += `GG原站点: https://${this.config.domain}/gg/${match.id}
 
 bwiki: https://${this.config.domain}/bw/${match.id}`;
     return message;
@@ -1544,7 +1667,20 @@ bwiki: https://${this.config.domain}/bw/${match.id}`;
   }
   async handleSelection(session, matches) {
     const resultCount = matches.length;
-    let replyMsg = `🔍 未找到精准匹配，为你找到【 ${resultCount} 】个相似结果，请输入序号选择（10秒内有效）：
+    let replyMsg;
+    if (this.isQQPlatform(session)) {
+      let md = `**🔍 为你找到【 ${resultCount} 】个相似结果，请点击下方按钮查看详情：**
+`;
+      matches.forEach((item, index) => {
+        md += `
+> \`${index + 1}\`. **${item.title}**
+`;
+      });
+      const keyboard = this.buildQQKeyboard(matches);
+      await this.sendResponse(session, md, keyboard);
+      return;
+    }
+    replyMsg = `🔍 未找到精准匹配，为你找到【 ${resultCount} 】个相似结果，请输入序号选择（10秒内有效）：
 `;
     matches.forEach((item, index) => {
       replyMsg += `${index + 1}. ${item.title}
@@ -1552,15 +1688,19 @@ bwiki: https://${this.config.domain}/bw/${match.id}`;
     });
     replyMsg += `
 ❗️ 提示：超时将静默结束，无任何回应`;
-    await session.send(replyMsg);
+    await this.sendResponse(session, replyMsg);
     const userInput = await session.prompt(15e3);
     if (!userInput) return;
     const selectNum = parseInt(userInput.trim(), 10);
     if (isNaN(selectNum) || selectNum < 1 || selectNum > resultCount) {
-      return `❌ 输入无效！请输入 1-${resultCount} 之间的数字序号`;
+      return this.sendResponse(
+        session,
+        `❌ 输入无效！请输入 1-${resultCount} 之间的数字序号`
+      );
     }
     const selected = matches[selectNum - 1];
-    return this.formatResultMessage(
+    return this.renderResultMessage(
+      session,
       selected,
       "✅ 选择成功"
     );

package/lib/plugins/queryCommands.d.ts

@@ -5,10 +5,16 @@ export interface QueryCommandsConfig {
 export declare class QueryCommands {
     static readonly inject: string[];
     config: QueryCommandsConfig;
+    private ctx;
     constructor(ctx: Context, config: QueryCommandsConfig);
     private registerCommands;
-    private getUsageMessage;
-    private formatResultMessage;
+    private isQQPlatform;
+    private buildLinkButton;
+    private buildQQKeyboard;
+    private sendResponse;
+    private renderUsageMessage;
+    private buildResultKeyboard;
+    private renderResultMessage;
     private findPreciseMatch;
     private calculateScore;
     private findFuzzyMatches;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-oni-sync-bot",
   "description": "缺氧Wiki站镜像点同步-测试",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [

package/readme.md

@@ -2,235 +2,311 @@
 
 [![npm](https://img.shields.io/npm/v/koishi-plugin-oni-sync-bot?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-oni-sync-bot)
 [![Koishi](https://img.shields.io/badge/koishi-plugin-42b983?style=flat-square)](https://koishi.chat)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-缺氧 Wiki 站镜像点同步插件 - 自动同步两个缺氧 Wiki 站点的内容，同时提供 TodoList 管理功能。
+**缺氧 Wiki 镜像站同步机器人插件** — 实现 [oxygennotincluded.wiki.gg](https://oxygennotincluded.wiki.gg) 与 B站 Wiki 镜像的双向内容同步、拼音匹配页面查询、模块同步管理，以及页面短链接重定向服务。
 
-## 功能特性
+## ✨ 核心功能
 
-### 核心功能
+### 📄 Wiki 同步
 
-- 🚀 **自动登录** - 支持 WIKIGG 和 bwiki 双站点登录
-- 🔄 **自动重连** - 登录过期时自动重新登录并重试
-- 📄 **页面同步** - 单个页面同步到目标站点
-- 📦 **模块同步** - 批量同步指定前缀的页面
-- 🖼️ **图片同步** - 同步页面引用的图片文件
-- 🔍 **页面查询** - 查询页面历史版本和当前版本
-- ⚡ **增量更新** - 定时检测并同步最近修改的内容
+- **双向登录** — 自动登录 wiki.gg 与 B站 Wiki（bwiki）两个站点
+- **页面同步** — 单个/批量页面从 wiki.gg 同步到 bwiki
+- **模块同步** — 批量同步 Module 命名空间页面
+- **图片同步** — 同步页面引用的图片文件（支持单个/批量）
+- **增量更新** — 每小时自动检测最近编辑并同步到镜像站
+- **自动重连** — 登录过期自动检测并重新登录（3次重试机制）
+- **登录重试** — 单次登录失败自动重试（最多3次，间隔5秒）
 
-### TodoList 功能
+### 🔍 页面查询
 
-- ✅ **待办事项管理** - 增删改查待办事项
-- 📋 **控制台页面** - 可视化管理 TodoList
-- 🔄 **模块同步** - 自动同步 wiki.gg 模块到 TodoList
-- 📊 **同步状态检查** - 自动检查模块同步状态
-- 🕐 **定时任务** - 每周一同步模块，每周二检查状态
-- 🎨 **可爱风格** - 萌系风格的 UI 设计
-- 🔍 **搜索筛选** - 支持关键词搜索和状态筛选
-- 📄 **分页显示** - 支持分页和自定义每页条数
-- 📱 **移动端适配** - 响应式设计，支持手机访问
+- **精准匹配** — 标题/全拼/首字母精确匹配
+- **拼音模糊匹配** — 支持中文名称的拼音搜索
+- **QQ Markdown 按钮** — QQ群查询结果以可点击按钮形式呈现（点击即跳转页面）
+- **命令别名** — `x` / `查wiki` 快捷命令
 
-## 安装
+### 📋 模块同步 TodoList
 
-```bash
-npm install koishi-plugin-oni-sync-bot
-# 或
-yarn add koishi-plugin-oni-sync-bot
-```
-
-## 配置
-
-在 Koishi 控制台中配置以下参数：
+- **自动同步** — 每周一 00:00 自动同步 wiki.gg 所有 Module 到待办
+- **状态检查** — 每周二 00:00 自动检查模块同步状态（对比修订时间）
+- **控制台管理** — 萌系风格可视化管理界面，支持搜索/筛选/分页
+- **增删改查** — 完整的待办管理命令和控制台操作
+- **权限控制** — 删除/清空操作需权限 2，删除缓存需权限 4
 
-| 参数            | 说明          | 默认值 |
-| --------------- | ------------- | ------ |
-| `ggUsername`    | WIKIGG 用户名 | 1      |
-| `ggPassword`    | WIKIGG 密码   | 1      |
-| `bwikiusername` | bwiki 用户名  | 1      |
-| `bwikipassword` | bwiki 密码    | 1      |
+### � 路由重定向
 
-## 命令列表
+- **短链接服务** — `/:id` → 跳转至完整 Wiki 页面 URL
+- **GG 原站跳转** — `/gg/:id` → 跳转至 oxygennotincluded.wiki.gg 对应页面
+- **Bwiki 镜像跳转** — `/bw/:id` → 跳转至 wiki.biligame.com/oni 对应页面
+- **通配路径转发** — `/ggwiki/*` → 转发任意路径和查询参数到原站
+- **持久化缓存** — 页面标题和页面ID映射保存在本地数据库，首次启动需执行 `update`
 
-### 同步命令
+### 🎮 特殊指令
 
-| 命令                 | 说明                   |
-| -------------------- | ---------------------- |
-| `sync.page <标题>`   | 同步单个页面到 bwiki   |
-| `sync.gg <标题>`     | 同步单个页面到 WIKIGG  |
-| `sync.module <前缀>` | 同步指定前缀的所有页面 |
-| `sync.img <标题>`    | 同步页面引用的图片     |
-| `sync.update`        | 执行增量更新           |
+- **火箭计算器** — 查询 "火箭计算器" 返回计算器工具链接提示
 
-### TodoList 命令
+## 📦 项目结构
 
-| 命令                   | 说明                                  | 权限要求 |
-| ---------------------- | ------------------------------------- | -------- |
-| `todo.list`            | 查看 TodoList（重定向到网页）        | -        |
-| `todo.add <标题>`      | 添加待办事项                          | -        |
-| `todo.edit <id>`       | 编辑待办事项                          | -        |
-| `todo.complete <id>`   | 标记待办事项为完成                    | -        |
-| `todo.uncomplete <id>` | 标记待办事项为未完成                  | -        |
-| `todo.delete <id>`     | 删除待办事项                          | 2        |
-| `todo.clear`           | 清空 TodoList                          | 2        |
-| `todo.syncmodules`     | 同步 wiki.gg 模块到 TodoList          | -        |
-| `todo.checksync`       | 检查模块同步状态                      | -        |
-
-### 管理命令
+```
+oni-sync-bot/
+├── src/
+│   ├── index.ts                 # 插件入口（子插件注册表）
+│   ├── services/
+│   │   ├── wikiBotService.ts    # Wiki 机器人核心服务（登录、重连、代理）
+│   │   └── consoleLogProvider.ts # 控制台日志服务
+│   ├── plugins/
+│   │   ├── databaseExtension.ts # 数据库模型扩展（wikipages 表）
+│   │   ├── queryCommands.ts     # 页面查询命令（x / 查wiki）
+│   │   ├── syncCommands.ts      # Wiki 同步命令（sync.*）+ 定时任务
+│   │   ├── updateCommands.ts    # 缓存管理命令（update.* / redirect / relogin）
+│   │   ├── routeRedirect.ts    # 路由重定向服务（/gg / /bw / /ggwiki）
+│   │   └── todoList.ts          # TodoList 模块同步管理（命令 + 控制台 + 定时任务）
+│   ├── sync/
+│   │   ├── pageSync.ts          # 页面同步逻辑（单页、全量、增量）
+│   │   ├── moduleSync.ts        # 模块同步逻辑
+│   │   └── imgSync.ts           # 图片同步逻辑
+│   └── utils/
+│       └── tools.ts             # 工具函数（拼音生成、日志、错误处理）
+├── client/
+│   ├── Rocketcalculator/        # 火箭计算器前端页面
+│   │   ├── calculator.ts
+│   │   ├── calculator.vue
+│   │   ├── config.ts
+│   │   ├── index.vue
+│   ├── onitodolist/             # TodoList 管理前端页面
+│   │   ├── index.vue
+│   │   └── todolist.vue
+│   ├── index.ts
+│   ├── page.vue                 # 日志查看页面
+│   └── tsconfig.json
+├── package.json
+├── tsconfig.json
+└── README.md
+```
 
-| 命令      | 说明                   |
-| --------- | ---------------------- |
-| `relogin` | 手动重新登录两个机器人 |
+## 🔧 架构设计
 
-## TodoList 命令示例
+### 子插件模式
 
-### 添加待办
+主入口 `src/index.ts` 采用依赖顺序注册子插件：
 
 ```
-/todo.add 同步模块 -c "同步 Module:Data" -u "管理员"
+Service 层（数据库、WikiBot 服务）
+  ↓
+Core 层（同步逻辑、路由重定向）
+  ↓
+Command 层（查询命令、同步命令、更新命令、TodoList）
+  ↓
+UI 层（控制台日志、TodoList 可视化面板、火箭计算器）
 ```
 
-### 编辑待办
+### 数据库模型
+
+| 表名        | 字段                                                                                                                                                     | 说明                            |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| `wikipages` | `id` (integer), `title` (string), `pinyin_full` (string), `pinyin_first` (string)                                                                        | Wiki 页面索引缓存，支持拼音检索 |
+| `onitodos`  | `id` (unsigned, auto), `title` (string), `content` (text), `completed` (boolean), `createdBy` (string), `createdAt` (timestamp), `updatedAt` (timestamp) | 模块同步待办事项                |
+
+### 核心技术
+
+| 技术                         | 用途                                         |
+| ---------------------------- | -------------------------------------------- |
+| **TypeScript**               | 完整类型支持，严格模式编译                   |
+| **Koishi 4**                 | 机器人框架，基于 Service 和 Plugin 架构      |
+| **Mwn**                      | MediaWiki API 客户端（wiki.gg / bwiki 交互） |
+| **pinyin-pro**               | 中文转拼音，支持页面名称模糊匹配             |
+| **koishi-plugin-cron**       | 定时任务调度（每小时增量更新、每周同步等）   |
+| **@koishijs/plugin-console** | Koishi 控制台（提供可视化管理界面）          |
+| **@koishijs/plugin-server**  | HTTP 服务器（提供短链接重定向路由）          |
+
+## ⚙️ 配置项
+
+| 参数            | 说明                | 默认值                         | 必需 |
+| --------------- | ------------------- | ------------------------------ | ---- |
+| `ggUsername`    | WIKIGG 用户名       | `1`                            | ✅   |
+| `ggPassword`    | WIKIGG 密码         | `1`                            | ✅   |
+| `bwikiusername` | Bwiki 用户名        | `1`                            | ✅   |
+| `bwikipassword` | Bwiki 密码          | `1`                            | ✅   |
+| `domain`        | 你的短链域名        | `klei.vip`                     | ✅   |
+| `main_site`     | 主站域名（wiki.gg） | `oxygennotincluded.wiki.gg/zh` | ✅   |
+| `bwiki_site`    | 镜像站域名（bwiki） | `wiki.biligame.com/oni`        | ✅   |
+| `logsUrl`       | 日志查看地址        | `https://klei.vip/onilogs`     | -    |
+
+## 📚 命令列表
+
+### 🔍 查询命令
+
+| 命令            | 别名     | 说明                           | 权限 |
+| --------------- | -------- | ------------------------------ | ---- |
+| `x <itemName>`  | `查wiki` | 查询页面（标题/拼音/模糊匹配） | -    |
+| `查询 <关键词>` | -        | 同上（备用命令名）             | -    |
+
+### 🔄 同步命令
+
+| 命令                     | 别名       | 说明                 | 权限 |
+| ------------------------ | ---------- | -------------------- | ---- |
+| `sync <标题>`            | -          | 同步单个页面到 bwiki | 2    |
+| `sync.allpages`          | -          | 同步所有页面         | 2    |
+| `sync.module <模块名>`   | -          | 同步单个模块         | 2    |
+| `sync.allmodules`        | -          | 同步所有模块         | 2    |
+| `sync.img <图片名>`      | -          | 同步单张图片         | 2    |
+| `sync.allimgs`           | -          | 同步所有图片         | 2    |
+| `sync.incrementalUpdate` | `增量更新` | 执行增量更新         | 2    |
+
+### 📝 缓存管理
+
+| 命令                           | 别名       | 说明                                | 权限 |
+| ------------------------------ | ---------- | ----------------------------------- | ---- |
+| `update`                       | -          | 更新本地页面缓存（从 wiki.gg 获取） | 2    |
+| `update.status`                | -          | 查询缓存数量和状态                  | 1    |
+| `update.delete`                | -          | 清空页面缓存                        | 4    |
+| `redirect <原页面> <目标页面>` | `重定向`   | 在 wiki.gg 创建重定向页面           | 2    |
+| `relogin`                      | `重新登录` | 手动重新登录两个 Wiki 机器人        | 2    |
+
+### ✅ TodoList 命令
+
+| 命令                   | 别名     | 说明                                     | 权限 |
+| ---------------------- | -------- | ---------------------------------------- | ---- |
+| `todolist`             | `todo`   | 查看 TodoList（跳转网页）                | -    |
+| `todo.list`            | `todo.l` | 查看 TodoList（跳转网页）                | -    |
+| `todo.add <标题>`      | `todo.a` | 添加待办事项（支持 `-c` `-u` 选项）      | -    |
+| `todo.edit <id>`       | `todo.e` | 编辑待办事项（支持 `-t` `-c` `-u` 选项） | -    |
+| `todo.complete <id>`   | `todo.c` | 标记待办为完成                           | -    |
+| `todo.uncomplete <id>` | `todo.u` | 标记待办为未完成                         | -    |
+| `todo.delete <id>`     | `todo.d` | 删除待办事项                             | 2    |
+| `todo.clear`           | -        | 清空 TodoList                            | 2    |
+| `todo.syncmodules`     | -        | 手动同步 wiki.gg 模块到 TodoList         | -    |
+| `todo.checksync`       | -        | 手动检查模块同步状态                     | -    |
+
+## ⏰ 定时任务
+
+| 时间             | 任务                | 说明                                   |
+| ---------------- | ------------------- | -------------------------------------- |
+| **每小时 15 分** | 增量更新            | 获取最近编辑并同步到 bwiki             |
+| **每周四 08:30** | 同步所有页面        | 从 wiki.gg 全量同步页面到 bwiki        |
+| **每周三 08:30** | 同步所有图片        | 从 wiki.gg 全量同步图片资源            |
+| **每周一 00:00** | 同步模块到 TodoList | 获取所有 Module 命名空间页面并写入待办 |
+| **每周二 00:00** | 检查模块同步状态    | 对比修订时间，自动标记完成/未完成      |
+
+## 🔌 路由接口
+
+| 路径        | 方法 | 说明                                                      |
+| ----------- | ---- | --------------------------------------------------------- |
+| `/gg/:id`   | GET  | 跳转至 oxygennotincluded.wiki.gg 对应页面（自动编码标题） |
+| `/bw/:id`   | GET  | 跳转至 wiki.biligame.com/oni 对应页面                     |
+| `/ggwiki/*` | GET  | 通配路径转发至 oxygennotincluded.wiki.gg，保留查询参数    |
+
+> � **提示**：首次部署请先执行 `update` 命令填充 `wikipages` 表，否则路由跳转将返回"未找到页面"提示。
+
+## 🚀 安装
 
-```
-/todo.edit 1 -t "新标题" -c "新内容" -u "编辑者"
+```bash
+npm install koishi-plugin-oni-sync-bot
+# 或
+yarn add koishi-plugin-oni-sync-bot
 ```
 
-### 同步模块
+## 🔨 开发
 
-```
-/todo.syncmodules
-```
+```bash
+# 克隆项目
+git clone https://github.com/Charles-LF/oni-sync-bot.git
 
-### 检查同步状态
+# 安装依赖
+yarn install
 
-```
-/todo.checksync
+# 构建
+yarn build
+
+# 开发模式
+yarn dev
 ```
 
-## 控制台功能
+### 依赖服务
 
-插件提供了两个可视化的控制台界面：
+插件正常运行需以下 Koishi 核心插件（Koishi 默认已提供）：
 
-### 日志控制台
+- **@koishijs/plugin-database** — 数据持久化（wikipages / onitodos）
+- **@koishijs/plugin-server** — HTTP 服务器（短链接路由）
+- **@koishijs/plugin-console** — 控制台 UI（TodoList 管理界面）
+- **koishi-plugin-cron** — 定时任务调度
+- **@koishijs/plugin-adapter-\*（可选）** — 如 QQ 适配器，以获得 Markdown 按钮效果
 
-- 📋 **日志查看** - 按级别（全部/信息/警告/错误）筛选日志
-- 🔍 **搜索功能** - 快速搜索日志内容
-- ⏬ **自动滚动** - 新日志自动滚动到底部
-- 🎯 **一键滚动** - 手动跳转到顶部或底部
+## 📊 使用示例
 
-### TodoList 控制台
+### 🔍 查询页面
 
-- ✨ **可爱风格** - 萌系设计的 UI 界面
-- ➕ **新增待办** - 弹窗表单添加待办
-- ✏️ **编辑待办** - 修改待办内容和状态
-- ✅ **完成标记** - 一键标记完成/未完成
-- 🔍 **搜索筛选** - 支持按标题、内容搜索，按状态筛选
-- 📄 **分页显示** - 超过 8 条自动分页，支持自定义每页条数
-- 📊 **统计信息** - 显示总数、已完成、未完成数量
-- 📱 **移动端适配** - 响应式布局，完美支持手机访问
+```
+> x 精炼器
 
-**注意：控制台界面无法删除待办事项，删除操作仅可通过命令完成（需要权限 2）。**
+🔍 为你找到【3】个相似结果，请点击下方按钮查看详情：
 
-## 定时任务
+ 1. [精炼器]
+ 2. [蒸汽精炼器]
+ 3. [岩浆精炼器]
 
-插件使用 `koishi-plugin-cron` 提供定时任务功能：
+（QQ 平台显示可点击按钮，点击即跳转 Wiki 页面；非 QQ 平台返回纯文本）
+```
 
-- **每周一 00:00** - 自动同步 wiki.gg 所有模块到 TodoList
-- **每周二 00:00** - 自动检查模块同步状态，更新完成标记
+### 🔄 同步页面
 
-## 技术特性
+```
+> sync 精炼器
 
-- ✅ **TypeScript** - 完整的类型支持
-- 🎯 **面向对象** - 基于类的插件架构
-- 🔌 **服务化设计** - 核心功能封装为独立服务
-- 🧩 **模块化** - 功能拆分为独立子插件
-- 🔄 **自动重试** - 登录失败自动重试（最多 3 次）
-- 🔐 **自动重连** - 登录过期自动重新登录
-- 🛡️ **错误处理** - 完善的错误处理和日志记录
-- ⏱️ **API 限流** - 模块同步时请求间隔 1 秒
-- 🔄 **API 重试** - API 调用失败自动重试（最多 3 次）
-- 📦 **数据库持久化** - TodoList 数据存储在数据库中
+✅ 已尝试同步页面：精炼器，请前往控制台查看
+```
 
-## 项目结构
+### ✅ 标记待办完成
 
 ```
-koishi-plugin-oni-sync-bot/
-├── src/
-│   ├── services/         # 服务层
-│   │   ├── wikiBotService.ts    # Wiki 机器人服务
-│   │   └── consoleLogProvider.ts # 日志控制台服务
-│   ├── plugins/          # 插件层
-│   │   ├── queryCommands.ts     # 查询命令插件
-│   │   ├── syncCommands.ts      # 同步命令插件
-│   │   ├── updateCommands.ts    # 更新命令插件
-│   │   ├── todoList.ts          # TodoList 插件
-│   │   ├── databaseExtension.ts  # 数据库扩展
-│   │   └── routeRedirect.ts     # 路由重定向
-│   ├── sync/             # 同步逻辑
-│   │   ├── pageSync.ts          # 页面同步
-│   │   ├── moduleSync.ts        # 模块同步
-│   │   └── imgSync.ts           # 图片同步
-│   ├── utils/            # 工具函数
-│   │   └── tools.ts             # 通用工具
-│   ├── client/           # 前端
-│   │   ├── page.vue             # 日志页面
-│   │   ├── onitodolist/         # TodoList 页面
-│   │   │   └── todolist.vue     # TodoList 主组件
-│   │   └── index.ts             # 入口
-│   └── index.ts          # 主入口
-├── package.json
-└── tsconfig.json
+> todo.complete 5
+
+✅ 已标记完成，请访问 https://klei.vip/onitodos 查看
 ```
 
-## TodoList 模块同步逻辑
+## 🎨 控制台界面
 
-### 模块同步流程
+插件在 Koishi 控制台提供以下管理页面：
 
-1. 从 wiki.gg 获取命名空间 828（Module）的所有页面
-2. 逐个获取每个模块的最新修订信息（用户、时间、注释）
-3. 将模块信息存入 TodoList：
-   - `title` = 模块名称
-   - `content` = 修订注释
-   - `createdBy` = 修订用户
-   - `createdAt` / `updatedAt` = 修订时间
-   - `completed` = false（默认未完成）
+| 页面                                 | 功能                                                 |
+| ------------------------------------ | ---------------------------------------------------- |
+| **日志控制台** (`page.vue`)          | 按级别筛选日志，搜索内容，自动滚动，快速跳转         |
+| **TodoList 管理** (`onitodolist/`)   | 萌系 UI 设计，新增/编辑/标记完成，搜索筛选，分页显示 |
+| **火箭计算器** (`Rocketcalculator/`) | ONI 火箭设计计算器                                   |
 
-### 同步状态检查
+## 🔒 安全与权限
 
-1. 获取所有 TodoList 中的待办事项
-2. 对每个待办：
-   - 从 wiki.gg 获取最新修订时间
-   - 从 bwikia 获取最新修订时间
-   - 对比时间：
-     - 如果 bwikia 时间 ≥ wiki.gg 时间 → 标记为已完成
-     - 如果 bwikia 时间 < wiki.gg 时间 → 标记为未完成
+- 所有 Wiki 编辑操作（同步、创建重定向）需权限 **2**
+- 删除页面缓存需权限 **4**
+- 登录凭证（用户名/密码）仅保存在 Koishi 配置中，不会写入日志
+- WikiBotService 通过 **Proxy** 模式透明处理登录过期，自动重新登录后继续执行原请求
 
-## 开发
+## 🐛 故障排查
 
-```bash
-# 创建 KOISHI 项目
-yarn create koishi
+### "❌ 本地缓存为空"
 
-# 克隆项目
-git clone https://github.com/Charles-LF/oni-sync-bot.git
+请管理员执行 `update` 命令从 wiki.gg 获取页面列表。
 
-# 安装依赖
-yarn install
+### "❌ Wiki 机器人未就绪"
 
-# 构建
-yarn build
+检查配置中的账号密码是否正确；可执行 `relogin` 手动重新登录。
 
-# 开发模式
-yarn dev
-```
+### "❌ 未找到ID为【...】的页面"
+
+页面ID不在本地缓存中，可能是最近新增的页面。执行 `update` 更新缓存后再试。
+
+### QQ 机器人只显示纯文本
+
+QQ 平台的 Markdown 与按钮效果需要 `session.platform === "qq"` 检测生效。请确认适配器正确上报平台信息。
 
-## License
+## 📜 License
 
 MIT License
 
-## 贡献
+## 🤝 贡献
 
 欢迎提交 Issue 和 Pull Request！
 
-## 支持
+## 📧 支持
 
-如有问题，请在 GitHub 上提交 Issue。
+如有问题，请在 GitHub 上提交 Issue，或访问 <https://klei.vip>。