release: 紧急更新 0.2.1 版本.

由于 Launcher 比 initialFiles 更早的执行, 调用 Const 导致更早的访问了未初始化的文件, 导致第一次启动会出现错误.
改动中将 Launcher 移入 main 方法不会有影响, 相比于在 AppPaths.<init> 中初始化会更安全.

.gitignore

@@ -3,6 +3,7 @@
 
 # Log file
 *.log
+*.log.gz
 
 # BlueJ files
 *.ctxt

README.md

@@ -9,13 +9,26 @@ on [rubenlagus/TelegramBots](https://github.com/rubenlagus/TelegramBots).
 是按 Bot 融入应用的方式设计的， 且 AbilityExtension 对 ReplyFlow 不太支持（因为无法获取所属 AbilityBot 的 StateDB）， 所以我尝试提供了一个 Factory 接口，在创建
 AbilityExtension 对象时提供扩展将要服务的 AbilityBot 对象，这样 AbilityExtension 就可以不受限的实现功能了。
 
+## 开发版本警告
+
+当前应用处于开发版本状态，在 1.0.0 发布前，任何功能都可能存在不兼容更改，在升级版本前，请仔细阅读更新日志， （如果有）按照迁移指南迁移数据后方可升级；  
+由于不遵循迁移指南而导致的损失，本项目相关开发人员不会对此负责。
+
+### 版本号
+
+本项目遵循 SemVer 版本号规范，但在正式版（1.0.0）发布前，可能会存在次版本号更新不向下兼容的问题，请仔细阅读迁移指南进行升级！
+
 ## 使用
 
-1. 首先，在 Telegram 中联系 [BotFather](https://t.me/BotFather) ，申请机器人账号。
+1. （如果没有准备机器人账号）首先，在 Telegram 中联系 [BotFather](https://t.me/BotFather) ，申请机器人账号。
-2. 下载 [最新版本](https://github.com/LamGC/ScalaBot/releases/latest) 的 ScalaBot， 将发行包解压到某个目录中，然后准备一个用于存储 ScalaBot 运行数据的目录。
+2. 运行环境需要安装好 Java 11（或更高版本）；
-3. 在作为数据存储位置的目录中，执行从分发包中解压出来的 `bin/ScalaBot` 脚本以打开 ScalaBot。 由于首次启动缺少配置文件，ScalaBot 将会初始化配置文件（`config.json` 和 `bot.json`）
+3. 下载 [最新版本](https://github.com/LamGC/ScalaBot/releases/latest) 的 ScalaBot 发行包， 将发行包解压到某个目录中，然后准备一个用于存储 ScalaBot
-4. 将配置文件配置好后，如已下载好需要使用的扩展包，将扩展包移至 `extensions` 文件夹即可。（无需下载的扩展包将由 ScalaBot 自动下载）
+   运行数据的目录；
-5. 如果一切正常，ScalaBot 正常运行，绑定好的 Telegram Bot 账号将会对消息有所反应。
+4. （可选）如果有需要在非运行目录的路径上运行 ScalaBot（例如以 Service 形式启动，或者使用 Docker），可通过环境变量 `BOT_DATA_PATH` 指定 ScalaBot 的运行目录；
+5. 在作为数据存储位置的目录中，执行从分发包中解压出来的 `bin/ScalaBot` 脚本以打开 ScalaBot。 由于首次启动缺少配置文件，ScalaBot 将会初始化配置文件（`config.json` 和 `bot.json`
+   ），可按照 [配置文件示例](https://github.com/LamGC/ScalaBot/wiki/Configuration) 进行配置。
+6. 将配置文件配置好后，如已下载好需要使用的扩展包，将扩展包移至 `extensions` 文件夹即可。（无需下载的扩展包将由 ScalaBot 自动下载）
+7. 如果一切正常，ScalaBot 正常运行，绑定好的 Telegram Bot 账号将会对消息有所反应。
 
 ## 开发扩展包
 

build.gradle.kts

@@ -7,5 +7,5 @@ allprojects {
 
     }
     group = "net.lamgc"
-    version = "0.0.1"
+    version = "0.2.1"
 }

scalabot-app/build.gradle.kts

@@ -11,7 +11,7 @@ dependencies {
 
     implementation("org.slf4j:slf4j-api:1.7.36")
     implementation("io.github.microutils:kotlin-logging:2.1.21")
-    implementation("ch.qos.logback:logback-classic:1.2.10")
+    implementation("ch.qos.logback:logback-classic:1.2.11")
 
     val aetherVersion = "1.1.0"
     implementation("org.eclipse.aether:aether-api:$aetherVersion")
@@ -22,13 +22,14 @@ dependencies {
     implementation("org.eclipse.aether:aether-connector-basic:$aetherVersion")
     implementation("org.apache.maven:maven-aether-provider:3.3.9")
 
-    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.1")
+    implementation("org.jetbrains.kotlin:kotlin-reflect:1.6.20")
     implementation("com.google.code.gson:gson:2.9.0")
 
     implementation("org.jdom:jdom2:2.0.6.1")
 
-    implementation("org.telegram:telegrambots-abilities:5.6.0")
+    implementation("org.telegram:telegrambots-abilities:6.0.1")
-    implementation("org.telegram:telegrambots:5.6.0")
+    implementation("org.telegram:telegrambots:6.0.1")
 
     implementation("io.prometheus:simpleclient:0.15.0")
     implementation("io.prometheus:simpleclient_httpserver:0.15.0")

scalabot-app/src/main/kotlin/AppConfigs.kt

@@ -1,15 +1,22 @@
 package net.lamgc.scalabot
 
+import ch.qos.logback.core.PropertyDefinerBase
 import com.google.gson.Gson
 import com.google.gson.GsonBuilder
 import com.google.gson.reflect.TypeToken
 import mu.KotlinLogging
 import net.lamgc.scalabot.util.ArtifactSerializer
+import net.lamgc.scalabot.util.AuthenticationSerializer
+import net.lamgc.scalabot.util.MavenRepositoryConfigSerializer
 import net.lamgc.scalabot.util.ProxyTypeSerializer
 import org.eclipse.aether.artifact.Artifact
+import org.eclipse.aether.repository.Authentication
 import org.eclipse.aether.repository.Proxy
+import org.eclipse.aether.repository.RemoteRepository
 import org.telegram.telegrambots.bots.DefaultBotOptions
+import org.telegram.telegrambots.meta.ApiConstants
 import java.io.File
+import java.net.URL
 import java.nio.charset.StandardCharsets
 import java.util.concurrent.atomic.AtomicBoolean
 
@@ -25,7 +32,14 @@ internal data class BotAccount(
     val name: String,
     val token: String,
     val creatorId: Long = -1
-)
+) {
+
+    val id
+        // 不要想着每次获取都要从 token 里取出有性能损耗.
+        // 由于 Gson 解析方式, 如果不这么做, 会出现 token 设置前 id 初始化完成, 就只有"0"了,
+        // 虽然能过单元测试, 但实际使用过程是不能正常用的.
+        get() = token.substringBefore(":").toLong()
+}
 
 /**
  * 机器人配置.
@@ -37,16 +51,17 @@ internal data class BotAccount(
 internal data class BotConfig(
     val enabled: Boolean = true,
     val account: BotAccount,
-    val disableBuiltInAbility: Boolean = true,
+    val disableBuiltInAbility: Boolean = false,
+    val autoUpdateCommandList: Boolean = false,
     /*
      * 使用构件坐标来选择机器人所使用的扩展包.
      * 这么做的原因是我暂时没找到一个合适的方法来让开发者方便地设定自己的扩展 Id,
-     * 而构件坐标(POM Reference 或者叫 GAV 坐标)是开发者创建 Maven/Gradle 项目所一定会设置的,
+     * 而构件坐标(POM Reference 或者叫 GAV 坐标)是开发者创建 Maven/Gradle 项目时一定会设置的,
      * 所以就直接用了. :P
      */
     val extensions: Set<Artifact>,
-    val proxy: ProxyConfig? = null,
+    val proxy: ProxyConfig? = ProxyConfig(),
-    val baseApiUrl: String? = null
+    val baseApiUrl: String? = ApiConstants.BASE_URL
 )
 
 /**
@@ -74,35 +89,105 @@ internal data class ProxyConfig(
 internal data class MetricsConfig(
     val enable: Boolean = false,
     val port: Int = 9386,
-    val bindAddress: String? = null
+    val bindAddress: String? = "0.0.0.0"
 )
 
+/**
+ * Maven 远端仓库配置.
+ * @property url 仓库地址.
+ * @property proxy 访问仓库所使用的代理, 仅支持 http/https 代理.
+ * @property layout 仓库布局版本, Maven 2 及以上使用 `default`, Maven 1 使用 `legacy`.
+ */
+internal data class MavenRepositoryConfig(
+    val url: URL,
+    val proxy: Proxy? = Proxy("http", "127.0.0.1", 1080),
+    val layout: String = "default",
+    // 可能要设计个 type 来判断解析成什么类型的 Authentication.
+    val authentication: Authentication? = null
+) {
+
+    fun toRemoteRepository(): RemoteRepository {
+        val builder = RemoteRepository.Builder(null, checkRepositoryLayout(layout), url.toString())
+        if (proxy != null) {
+            builder.setProxy(proxy)
+        } else if (Const.config.proxy.type == DefaultBotOptions.ProxyType.HTTP) {
+            builder.setProxy(Const.config.proxy.toAetherProxy())
+        }
+        return builder.build()
+    }
+
+    private companion object {
+        fun checkRepositoryLayout(layoutType: String): String {
+            val type = layoutType.trim().lowercase()
+            if (type != "default" && type != "legacy") {
+                throw IllegalArgumentException("Invalid layout type (expecting 'default' or 'legacy')")
+            }
+            return type
+        }
+    }
+}
+
 /**
  * ScalaBot App 配置.
  *
  * App 配置信息与 BotConfig 分开, 分别存储在各自单独的文件中.
  * @property proxy Telegram API 代理配置.
+ * @property metrics 运行指标数据配置. 可通过时序数据库记录运行数据.
+ * @property mavenRepositories Maven 远端仓库配置.
+ * @property mavenLocalRepository Maven 本地仓库路径. 相对于运行目录 (而不是 DATA_ROOT 目录)
  */
 internal data class AppConfig(
     val proxy: ProxyConfig = ProxyConfig(),
-    val metrics: MetricsConfig = MetricsConfig()
+    val metrics: MetricsConfig = MetricsConfig(),
+    val mavenRepositories: List<MavenRepositoryConfig> = emptyList(),
+    val mavenLocalRepository: String? = null
 )
 
 /**
  * 需要用到的路径.
+ *
+ * 必须提供 `pathSupplier` 或 `fileSupplier` 其中一个, 才能正常提供路径.
  */
 internal enum class AppPaths(
-    private val pathSupplier: () -> String,
+    private val pathSupplier: () -> String = { fileSupplier.invoke().canonicalPath },
-    private val initializer: AppPaths.() -> Unit = AppPaths::defaultInitializer
+    private val initializer: AppPaths.() -> Unit = AppPaths::defaultInitializer,
+    private val fileSupplier: () -> File = { File(pathSupplier()) }
 ) {
-    DEFAULT_CONFIG_APPLICATION({ "./config.json" }, {
+    /**
+     * 数据根目录.
+     *
+     * 所有运行数据的存放位置.
+     *
+     * 提示: 结尾不带 `/`.
+     */
+    DATA_ROOT(fileSupplier = {
+        File(
+            System.getProperty(PathConst.PROP_DATA_PATH) ?: System.getenv(PathConst.ENV_DATA_PATH)
+            ?: System.getProperty("user.dir") ?: "."
+        )
+    }, initializer = {
+        val f = file
+        if (!f.exists()) {
+            f.mkdirs()
+        }
+    }),
+
+    DEFAULT_CONFIG_APPLICATION({ "$DATA_ROOT/config.json" }, {
         if (!file.exists()) {
             file.bufferedWriter(StandardCharsets.UTF_8).use {
-                GsonConst.botConfigGson.toJson(AppConfig(), it)
+                GsonConst.botConfigGson.toJson(
+                    AppConfig(
+                        mavenRepositories = listOf(
+                            MavenRepositoryConfig(
+                                URL(MavenRepositoryExtensionFinder.MAVEN_CENTRAL_URL)
+                            )
+                        )
+                    ), it
+                )
             }
         }
     }),
-    DEFAULT_CONFIG_BOT({ "./bot.json" }, {
+    DEFAULT_CONFIG_BOT({ "$DATA_ROOT/bot.json" }, {
         if (!file.exists()) {
             file.bufferedWriter(StandardCharsets.UTF_8).use {
                 GsonConst.botConfigGson.toJson(
@@ -121,15 +206,15 @@ internal enum class AppPaths(
             }
         }
     }),
-    DATA_DB({ "./data/db/" }),
+    DATA_DB({ "$DATA_ROOT/data/db/" }),
-    DATA_LOGS({ "./data/logs/" }),
+    DATA_LOGS({ "$DATA_ROOT/data/logs/" }),
-    EXTENSIONS({ "./extensions/" }),
+    EXTENSIONS({ "$DATA_ROOT/extensions/" }),
-    DATA_EXTENSIONS({ "./data/extensions/" }),
+    DATA_EXTENSIONS({ "$DATA_ROOT/data/extensions/" }),
-    TEMP({ "./tmp/" })
+    TEMP({ "$DATA_ROOT/tmp/" })
     ;
 
     val file: File
-        get() = File(pathSupplier.invoke())
+        get() = fileSupplier.invoke()
     val path: String
         get() = pathSupplier.invoke()
 
@@ -138,7 +223,7 @@ internal enum class AppPaths(
     @Synchronized
     fun initial() {
         if (!initialized.get()) {
-            initializer(this)
+            initializer()
             initialized.set(true)
         }
     }
@@ -146,6 +231,21 @@ internal enum class AppPaths(
     override fun toString(): String {
         return path
     }
+
+    private object PathConst {
+        const val PROP_DATA_PATH = "bot.path.data"
+        const val ENV_DATA_PATH = "BOT_DATA_PATH"
+    }
+
+}
+
+/**
+ * 为 LogBack 提供日志目录路径.
+ */
+internal class LogDirectorySupplier : PropertyDefinerBase() {
+    override fun getPropertyValue(): String {
+        return AppPaths.DATA_LOGS.path
+    }
 }
 
 internal object Const {
@@ -153,14 +253,16 @@ internal object Const {
 }
 
 private fun AppPaths.defaultInitializer() {
-    if (!file.exists()) {
+    val f = file
-        val result = if (path.endsWith("/")) {
+    val p = path
-            file.mkdirs()
+    if (!f.exists()) {
+        val result = if (p.endsWith("/")) {
+            f.mkdirs()
         } else {
-            file.createNewFile()
+            f.createNewFile()
         }
         if (!result) {
-            log.warn { "初始化文件(夹)失败: $path" }
+            log.warn { "初始化文件(夹)失败: $p" }
         }
     }
 }
@@ -179,6 +281,8 @@ private object GsonConst {
 
     val appConfigGson: Gson = baseGson.newBuilder()
         .registerTypeAdapter(DefaultBotOptions.ProxyType::class.java, ProxyTypeSerializer)
+        .registerTypeAdapter(MavenRepositoryConfig::class.java, MavenRepositoryConfigSerializer)
+        .registerTypeAdapter(Authentication::class.java, AuthenticationSerializer)
         .create()
 
     val botConfigGson: Gson = baseGson.newBuilder()

scalabot-app/src/main/kotlin/AppMain.kt

@@ -4,6 +4,7 @@ import io.prometheus.client.exporter.HTTPServer
 import kotlinx.coroutines.runBlocking
 import mu.KotlinLogging
 import net.lamgc.scalabot.util.registerShutdownHook
+import org.eclipse.aether.repository.LocalRepository
 import org.telegram.telegrambots.bots.DefaultBotOptions
 import org.telegram.telegrambots.meta.TelegramBotsApi
 import org.telegram.telegrambots.meta.generics.BotSession
@@ -12,13 +13,14 @@ import kotlin.system.exitProcess
 
 private val log = KotlinLogging.logger { }
 
-private val launcher = Launcher()
-    .registerShutdownHook()
-
 fun main(args: Array<String>): Unit = runBlocking {
     log.info { "ScalaBot 正在启动中..." }
+    log.info { "数据目录: ${AppPaths.DATA_ROOT}" }
     log.debug { "启动参数: ${args.joinToString(prefix = "[", postfix = "]")}" }
     initialFiles()
+
+    val launcher = Launcher()
+        .registerShutdownHook()
     if (Const.config.metrics.enable) {
         startMetricsServer()
     }
@@ -52,6 +54,16 @@ internal class Launcher : AutoCloseable {
 
     private val botApi = TelegramBotsApi(DefaultBotSession::class.java)
     private val botSessionMap = mutableMapOf<ScalaBot, BotSession>()
+    private val mavenLocalRepository =
+        if (Const.config.mavenLocalRepository != null && Const.config.mavenLocalRepository.isNotEmpty()) {
+            val repoPath = AppPaths.DATA_ROOT.file.toPath()
+                .resolve(Const.config.mavenLocalRepository)
+                .toRealPath()
+                .toFile()
+            LocalRepository(repoPath)
+        } else {
+            LocalRepository("${System.getProperty("user.home")}/.m2/repository")
+        }
 
     @Synchronized
     fun launch(): Boolean {
@@ -61,7 +73,11 @@ internal class Launcher : AutoCloseable {
             return false
         }
         for (botConfig in botConfigs) {
+            try {
                 launchBot(botConfig)
+            } catch (e: Exception) {
+                log.error(e) { "机器人 `${botConfig.account.name}` 启动时发生错误." }
+            }
         }
         return true
     }
@@ -93,25 +109,57 @@ internal class Launcher : AutoCloseable {
             }
         }
         val account = botConfig.account
+
+        val remoteRepositories = Const.config.mavenRepositories
+            .map(MavenRepositoryConfig::toRemoteRepository)
+            .toMutableList().apply {
+                add(MavenRepositoryExtensionFinder.getMavenCentralRepository(proxy = Const.config.proxy.toAetherProxy()))
+            }.toList()
+        val extensionPackageFinders = setOf(
+            MavenRepositoryExtensionFinder(
+                localRepository = mavenLocalRepository,
+                remoteRepositories = remoteRepositories,
+                proxy = Const.config.proxy.toAetherProxy()
+            )
+        )
+
         val bot = ScalaBot(
-            account.name,
+            BotDBMaker.getBotDbInstance(account),
-            account.token,
-            account.creatorId,
-            BotDBMaker.getBotMaker(account),
             botOption,
-            botConfig.extensions,
+            extensionPackageFinders,
-            botConfig.disableBuiltInAbility
+            botConfig
         )
         botSessionMap[bot] = botApi.registerBot(bot)
         log.info { "机器人 `${bot.botUsername}` 已启动." }
+
+        if (botConfig.autoUpdateCommandList) {
+            log.debug { "[Bot ${botConfig.account.name}] 正在自动更新命令列表..." }
+            try {
+                val result = bot.updateCommandList()
+                if (result) {
+                    log.info { "[Bot ${botConfig.account.name}] 已成功更新 Bot 命令列表." }
+                } else {
+                    log.warn { "[Bot ${botConfig.account.name}] 自动更新 Bot 命令列表失败!" }
+                }
+            } catch (e: Exception) {
+                log.warn(e) { "命令列表自动更新失败." }
+            }
+        }
     }
 
     @Synchronized
     override fun close() {
         botSessionMap.forEach {
+            try {
+                if (!it.value.isRunning) {
+                    return@forEach
+                }
                 log.info { "正在关闭机器人 `${it.key.botUsername}` ..." }
                 it.value.stop()
                 log.info { "已关闭机器人 `${it.key.botUsername}`." }
+            } catch (e: Exception) {
+                log.error(e) { "机器人 `${it.key.botUsername}` 关闭时发生异常." }
+            }
         }
     }
 

scalabot-app/src/main/kotlin/BotDBMaker.kt

@@ -1,23 +1,190 @@
 package net.lamgc.scalabot
 
+import com.google.common.io.Files
+import mu.KotlinLogging
 import net.lamgc.scalabot.util.toHaxString
+import org.mapdb.DB
+import org.mapdb.DBException
 import org.mapdb.DBMaker
 import org.telegram.abilitybots.api.db.DBContext
 import org.telegram.abilitybots.api.db.MapDBContext
+import java.io.File
 import java.nio.charset.StandardCharsets
 import java.security.MessageDigest
 
+/**
+ * 数据库适配器.
+ *
+ * 应按照新到旧的顺序放置, 新的适配器应该在上面.
+ */
+private val adapters = arrayListOf<DbAdapter>(
+    BotAccountIdDbAdapter, // since [v0.2.0 ~ latest)
+    BotTokenDbAdapter // since [v0.0.1 ~ v0.2.0)
+)
+private const val FIELD_DB_VERSION = "::DB_VERSION"
+
 internal object BotDBMaker {
-    fun getBotMaker(botAccount: BotAccount): DBContext {
+    private val logger = KotlinLogging.logger { }
-        val digest: MessageDigest = MessageDigest.getInstance("SHA-256")
+
-        val digestBytes = digest.digest(botAccount.token.toByteArray(StandardCharsets.UTF_8))
+    fun getBotDbInstance(botAccount: BotAccount): DBContext {
-        val dbPath = AppPaths.DATA_DB.path + "${digestBytes.toHaxString()}.db"
+        for (adapter in adapters) {
-        val db = DBMaker.fileDB(dbPath)
+            val botDb = try {
+                adapter.getBotDb(botAccount, create = false) ?: continue
+            } catch (e: Exception) {
+                logger.error(e) { "适配器 ${adapter::class.java} 打开数据库时发生异常." }
+                continue
+            }
+            if (!adapter.dbVersionMatches(botDb)) {
+                logger.warn {
+                    "数据库版本号与适配器不符. " +
+                            "(Adapter: ${adapter::class.java};(${adapter.dbVersion})," +
+                            " DatabaseVer: ${adapter.getDbVersion(botDb)})"
+                }
+                botDb.close()
+                continue
+            } else {
+                if (adapter != adapters[0]) {
+                    logger.debug {
+                        "数据库适配器不是最新的, 正在升级数据库... " +
+                                "(Old: ${adapter::class.java}; New: ${adapters[0]::class.java})"
+                    }
+                    val db = try {
+                        botDb.close()
+                        val newDb = adapters[0].migrateDb(botAccount, adapter)
+                        logger.debug { "数据库版本升级完成." }
+                        newDb
+                    } catch (e: Exception) {
+                        logger.warn(e) { "Bot 数据库版本升级失败, 将继续使用旧版数据库." }
+                        adapter.getBotDb(botAccount, create = false) ?: continue
+                    }
+                    return MapDBContext(db)
+                }
+                return MapDBContext(botDb)
+            }
+        }
+
+        logger.debug { "没有适配器成功打开数据库, 使用最新的适配器创建数据库. (Adapter: ${adapters[0]::class.java})" }
+        val newDb = adapters[0].getBotDb(botAccount, create = true)
+            ?: throw IllegalStateException("No adapter is available to get the database.")
+        adapters[0].setDbVersion(newDb, adapters[0].dbVersion)
+        return MapDBContext(newDb)
+    }
+
+}
+
+/**
+ * 数据库适配器.
+ *
+ * 用于解决数据库格式更新带来的问题, 通过迁移机制, 将数据库从旧版本迁移到新版本, 或者只通过旧版本适配器访问而不迁移.
+ * @param dbVersion 数据库格式版本. 格式为: `{格式标识}_{最后使用的版本号}`, 如果为最新版适配器, 则不需要填写最后使用的版本号.
+ */
+private abstract class DbAdapter(val dbVersion: String) {
+
+    /**
+     * 获取 Bot 专有的 [DBContext].
+     * @param botAccount Bot 账号信息.
+     */
+    abstract fun getBotDb(botAccount: BotAccount, create: Boolean = false): DB?
+
+    /**
+     * 通过 Bot 账号信息获取数据库文件.
+     */
+    abstract fun getBotDbFile(botAccount: BotAccount): File
+
+    /**
+     * 将旧版数据库迁移到当前版本.
+     *
+     * 实现时请注意不要直接修改原数据库, 以防升级过程出错导致无法回退到旧版本.
+     */
+    abstract fun migrateDb(botAccount: BotAccount, oldDbAdapter: DbAdapter): DB
+
+    /**
+     * 数据库版本是否匹配.
+     */
+    open fun dbVersionMatches(db: DB): Boolean {
+        return getDbVersion(db) == dbVersion
+    }
+
+    fun getDbVersion(db: DB): String? {
+        if (!db.exists(FIELD_DB_VERSION)) {
+            return null
+        }
+        val dbVersionField = try {
+            db.atomicString(FIELD_DB_VERSION).open()
+        } catch (e: DBException.WrongConfiguration) {
+            return null
+        }
+        return dbVersionField.get()
+    }
+
+    fun setDbVersion(db: DB, version: String) {
+        db.atomicString(FIELD_DB_VERSION).createOrOpen().set(version)
+    }
+
+}
+
+/**
+ * 抽象文件数据库适配器.
+ *
+ * 只有文件有变化的适配器.
+ */
+private abstract class FileDbAdapter(
+    dbVersion: String,
+    private val fileProvider: (BotAccount) -> File
+) : DbAdapter(dbVersion) {
+
+    @Suppress("unused")
+    constructor(dbVersion: String) : this(dbVersion,
+        { throw NotImplementedError("When using this constructor, the \"getBotDbFile\" method must be implemented") })
+
+    override fun getBotDb(botAccount: BotAccount, create: Boolean): DB? {
+        val dbFile = getBotDbFile(botAccount)
+        if (!dbFile.exists() && !create) {
+            return null
+        }
+        return DBMaker.fileDB(dbFile)
             .closeOnJvmShutdownWeakReference()
             .checksumStoreEnable()
             .fileChannelEnable()
             .make()
-        return MapDBContext(db)
     }
 
+    override fun getBotDbFile(botAccount: BotAccount): File = fileProvider(botAccount)
+
+    override fun migrateDb(botAccount: BotAccount, oldDbAdapter: DbAdapter): DB {
+        val oldFile = oldDbAdapter.getBotDbFile(botAccount)
+        val newFile = getBotDbFile(botAccount)
+        try {
+            @Suppress("UnstableApiUsage")
+            Files.copy(oldFile, newFile)
+        } catch (e: Exception) {
+            if (newFile.exists()) {
+                // 删除新文件以防止异常退出后直接读取新文件.
+                newFile.delete()
             }
+            throw e
+        }
+        oldFile.delete()
+        return getBotDb(botAccount)!!.apply {
+            setDbVersion(this, this@FileDbAdapter.dbVersion)
+        }
+    }
+}
+
+/**
+ * 使用 Bot Token 中的 Account Id 命名数据库文件名.
+ */
+private object BotAccountIdDbAdapter : FileDbAdapter("BotAccountId", { botAccount ->
+    File(AppPaths.DATA_DB.file, "${botAccount.id}.db")
+})
+
+/**
+ * 使用 Bot Token, 经过 Sha256 加密后得到文件名.
+ *
+ * **已弃用**: 由于 Token 可以重新生成, 当 Token 改变后数据库文件名也会改变, 故弃用该方法.
+ */
+private object BotTokenDbAdapter : FileDbAdapter("BotToken_v0.1.0", { botAccount ->
+    val digest: MessageDigest = MessageDigest.getInstance("SHA-256")
+    val digestBytes = digest.digest(botAccount.token.toByteArray(StandardCharsets.UTF_8))
+    File(AppPaths.DATA_DB.file, "${digestBytes.toHaxString()}.db")
+})

scalabot-app/src/main/kotlin/ExtensionComponents.kt

@@ -4,7 +4,6 @@ import mu.KotlinLogging
 import net.lamgc.scalabot.extension.BotExtensionFactory
 import net.lamgc.scalabot.util.getPriority
 import org.eclipse.aether.artifact.Artifact
-import org.eclipse.aether.repository.LocalRepository
 import org.telegram.abilitybots.api.util.AbilityExtension
 import java.io.File
 import java.io.FileNotFoundException
@@ -18,18 +17,15 @@ import java.util.concurrent.atomic.AtomicInteger
 internal class ExtensionLoader(
     private val bot: ScalaBot,
     private val extensionsDataFolder: File = AppPaths.DATA_EXTENSIONS.file,
-    private val extensionsPath: File = AppPaths.EXTENSIONS.file
+    private val extensionsPath: File = AppPaths.EXTENSIONS.file,
+    private val extensionFinders: Set<ExtensionPackageFinder> = setOf()
 ) {
     private val log = KotlinLogging.logger { }
 
-    private val finders: Set<ExtensionPackageFinder> = setOf(
+    private val finders: Set<ExtensionPackageFinder> = mutableSetOf(
         FileNameFinder,
-        MavenMetaInformationFinder,
+        MavenMetaInformationFinder
-        MavenRepositoryExtensionFinder(
+    ).apply { addAll(extensionFinders) }.toSet()
-            LocalRepository("${System.getProperty("user.home")}/.m2/repository"),
-            proxy = Const.config.proxy.toAetherProxy()
-        )
-    )
 
     fun getExtensions(): Set<LoadedExtensionEntry> {
         val extensionEntries = mutableSetOf<LoadedExtensionEntry>()
@@ -94,6 +90,10 @@ internal class ExtensionLoader(
             try {
                 val extension =
                     factory.createExtensionInstance(bot, getExtensionDataFolder(extensionArtifact))
+                if (extension == null) {
+                    log.debug { "Factory ${factory::class.java} 创建插件时返回了 null, 已跳过. (BotName: ${bot.botUsername})" }
+                    continue
+                }
                 factories.add(LoadedExtensionEntry(extensionArtifact, factory::class.java, extension))
             } catch (e: Exception) {
                 log.error(e) { "创建扩展时发生异常. (ExtArtifact: `$extensionArtifact`, Factory: ${factory::class.java.name})" }
@@ -103,13 +103,11 @@ internal class ExtensionLoader(
     }
 
     private fun allFoundedPackageNumber(filesMap: Map<ExtensionPackageFinder, Set<FoundExtensionPackage>>): Int {
-        val result = mutableSetOf<URL>()
+        var number = 0
         for (files in filesMap.values) {
-            for (file in files) {
+            number += files.size
-                result.add(file.getRawUrl())
         }
-        }
+        return number
-        return result.size
     }
 
     private fun findExtensionPackage(

scalabot-app/src/main/kotlin/ExtensionFinders.kt

@@ -234,7 +234,7 @@ internal object MavenMetaInformationFinder : ExtensionPackageFinder {
  */
 @FinderRules(priority = FinderPriority.REMOTE)
 internal class MavenRepositoryExtensionFinder(
-    private val localRepository: LocalRepository,
+    private val localRepository: LocalRepository = LocalRepository("${System.getProperty("user.home")}/.m2/repository"),
     private val proxy: Proxy? = null,
     private val remoteRepositories: List<RemoteRepository> = listOf(getMavenCentralRepository(proxy)),
 ) : ExtensionPackageFinder {
@@ -354,14 +354,14 @@ internal class MavenRepositoryExtensionFinder(
                 RepositoryPolicy(
                     true,
                     RepositoryPolicy.UPDATE_POLICY_DAILY,
-                    RepositoryPolicy.CHECKSUM_POLICY_WARN
+                    RepositoryPolicy.CHECKSUM_POLICY_FAIL
                 )
             )
             builder.setSnapshotPolicy(
                 RepositoryPolicy(
                     true,
                     RepositoryPolicy.UPDATE_POLICY_ALWAYS,
-                    RepositoryPolicy.CHECKSUM_POLICY_WARN
+                    RepositoryPolicy.CHECKSUM_POLICY_FAIL
                 )
             )
             if (authentication != null) {

scalabot-app/src/main/kotlin/ScalaBot.kt

@@ -7,32 +7,116 @@ import mu.KotlinLogging
 import org.eclipse.aether.artifact.Artifact
 import org.telegram.abilitybots.api.bot.AbilityBot
 import org.telegram.abilitybots.api.db.DBContext
+import org.telegram.abilitybots.api.objects.Ability
 import org.telegram.abilitybots.api.toggle.BareboneToggle
 import org.telegram.abilitybots.api.toggle.DefaultToggle
 import org.telegram.telegrambots.bots.DefaultBotOptions
+import org.telegram.telegrambots.meta.api.methods.commands.DeleteMyCommands
+import org.telegram.telegrambots.meta.api.methods.commands.SetMyCommands
 import org.telegram.telegrambots.meta.api.objects.Update
+import org.telegram.telegrambots.meta.api.objects.commands.BotCommand
 
 /**
  * 可扩展 Bot.
- * @param name 机器人名称. 建议设为机器人用户名.
- * @param token 机器人 API 令牌.
  * @property creatorId 机器人所有人的 Telegram 用户 Id. 可通过联系部分机器人来获取该信息.
  * (e.g. [@userinfobot](http://t.me/userinfobot))
  * @param db 机器人数据库对象. 用于状态机等用途.
  * @param options AbilityBot 设置对象.
  * @property extensions 扩展坐标集合.
- * @param disableBuiltInAbility 是否禁用 [AbilityBot] 内置命令.
  */
 internal class ScalaBot(
-    name: String,
-    token: String,
-    private val creatorId: Long,
     db: DBContext,
     options: DefaultBotOptions,
-    val extensions: Set<Artifact>,
+    extensionFinders: Set<ExtensionPackageFinder>,
-    disableBuiltInAbility: Boolean
+    botConfig: BotConfig,
+    private val creatorId: Long = botConfig.account.creatorId,
+    val accountId: Long = botConfig.account.id,
+    val extensions: Set<Artifact> = botConfig.extensions
 ) :
-    AbilityBot(token, name, db, if (disableBuiltInAbility) DefaultToggle() else BareboneToggle(), options) {
+    AbilityBot(
+        botConfig.account.token,
+        botConfig.account.name,
+        db,
+        if (botConfig.disableBuiltInAbility)
+            BareboneToggle()
+        else
+            DefaultToggle(),
+        options
+    ) {
+
+    private val extensionLoader = ExtensionLoader(
+        bot = this,
+        extensionFinders = extensionFinders
+    )
+
+    init {
+        log.info { "[Bot $botUsername] 正在加载扩展..." }
+        val extensionEntries = extensionLoader.getExtensions()
+        for (entry in extensionEntries) {
+            addExtension(entry.extension)
+            log.debug {
+                "[Bot $botUsername] 扩展包 `${entry.extensionArtifact}` 中的扩展 `${entry.extension::class.qualifiedName}` " +
+                        "(由工厂类 `${entry.factoryClass.name}` 创建) 已注册."
+            }
+        }
+        log.info { "[Bot $botUsername] 扩展加载完成." }
+    }
+
+    override fun creatorId(): Long = creatorId
+
+    override fun onUpdateReceived(update: Update?) {
+        botUpdateCounter.labels(botUsername).inc()
+        botUpdateGauge.labels(botUsername).inc()
+
+        val timer = updateProcessTime.labels(botUsername).startTimer()
+        try {
+            super.onUpdateReceived(update)
+        } catch (e: Exception) {
+            exceptionHandlingCounter.labels(botUsername).inc()
+            throw e
+        } finally {
+            timer.observeDuration()
+            botUpdateGauge.labels(botUsername).dec()
+        }
+    }
+
+    /**
+     * 更新 Telegram Bot 的命令列表.
+     *
+     * 本方法将根据已注册的 [Ability] 更新 Telegram 中机器人的命令列表.
+     *
+     * 调用本方法前, 必须先调用一次 [registerAbilities], 否则无法获取 Ability 信息.
+     * @return 更新成功返回 `true`.
+     */
+    fun updateCommandList(): Boolean {
+        if (abilities() == null) {
+            throw IllegalStateException("Abilities has not been initialized.")
+        }
+
+        val botCommands = abilities().values.map {
+            val abilityInfo = if (it.info() == null || it.info().trim().isEmpty()) {
+                log.warn { "[Bot $botUsername] Ability `${it.name()}` 没有说明信息." }
+                "(The command has no description)"
+            } else {
+                log.debug { "[Bot $botUsername] Ability `${it.name()}` info `${it.info()}`" }
+                it.info().trim()
+            }
+            BotCommand(it.name(), abilityInfo)
+        }
+        val setMyCommands = SetMyCommands()
+        setMyCommands.commands = botCommands
+        return execute(DeleteMyCommands()) && execute(setMyCommands)
+    }
+
+    override fun onRegister() {
+        super.onRegister()
+        onlineBotGauge.inc()
+    }
+
+    override fun onClosing() {
+        super.onClosing()
+        onlineBotGauge.dec()
+    }
 
     companion object {
         @JvmStatic
@@ -83,45 +167,4 @@ internal class ScalaBot(
             .subsystem("telegrambots")
             .register()
     }
-
-    private val extensionLoader = ExtensionLoader(this)
-
-    init {
-        val extensionEntries = extensionLoader.getExtensions()
-        for (entry in extensionEntries) {
-            addExtension(entry.extension)
-            log.debug {
-                "[Bot ${botUsername}] 扩展包 `${entry.extensionArtifact}` 中的扩展 `${entry.extension::class.qualifiedName}` " +
-                        "(由工厂类 `${entry.factoryClass.name}` 创建) 已注册."
-            }
-        }
-    }
-
-    override fun creatorId(): Long = creatorId
-
-    override fun onUpdateReceived(update: Update?) {
-        botUpdateCounter.labels(botUsername).inc()
-        botUpdateGauge.labels(botUsername).inc()
-
-        val timer = updateProcessTime.labels(botUsername).startTimer()
-        try {
-            super.onUpdateReceived(update)
-        } catch (e: Exception) {
-            exceptionHandlingCounter.labels(botUsername).inc()
-            throw e
-        } finally {
-            timer.observeDuration()
-            botUpdateGauge.labels(botUsername).dec()
-        }
-    }
-
-    override fun onRegister() {
-        super.onRegister()
-        onlineBotGauge.inc()
-    }
-
-    override fun onClosing() {
-        super.onClosing()
-        onlineBotGauge.dec()
-    }
 }

scalabot-app/src/main/kotlin/util/Serializers.kt

@@ -1,12 +1,18 @@
 package net.lamgc.scalabot.util
 
 import com.google.gson.*
+import mu.KotlinLogging
+import net.lamgc.scalabot.MavenRepositoryConfig
 import org.eclipse.aether.artifact.Artifact
 import org.eclipse.aether.artifact.DefaultArtifact
+import org.eclipse.aether.repository.Authentication
+import org.eclipse.aether.repository.Proxy
+import org.eclipse.aether.util.repository.AuthenticationBuilder
 import org.telegram.telegrambots.bots.DefaultBotOptions
 import java.lang.reflect.Type
+import java.net.URL
 
-object ProxyTypeSerializer : JsonDeserializer<DefaultBotOptions.ProxyType>,
+internal object ProxyTypeSerializer : JsonDeserializer<DefaultBotOptions.ProxyType>,
     JsonSerializer<DefaultBotOptions.ProxyType> {
 
     override fun deserialize(
@@ -34,7 +40,7 @@ object ProxyTypeSerializer : JsonDeserializer<DefaultBotOptions.ProxyType>,
     }
 }
 
-object ArtifactSerializer : JsonSerializer<Artifact>, JsonDeserializer<Artifact> {
+internal object ArtifactSerializer : JsonSerializer<Artifact>, JsonDeserializer<Artifact> {
     override fun serialize(src: Artifact, typeOfSrc: Type?, context: JsonSerializationContext?): JsonElement {
         val gavBuilder = StringBuilder("${src.groupId}:${src.artifactId}")
         if (!src.extension.equals("jar")) {
@@ -55,3 +61,105 @@ object ArtifactSerializer : JsonSerializer<Artifact>, JsonDeserializer<Artifact>
 
 }
 
+internal object AuthenticationSerializer : JsonDeserializer<Authentication> {
+
+    private val log = KotlinLogging.logger { }
+
+    override fun deserialize(json: JsonElement, typeOfT: Type, context: JsonDeserializationContext): Authentication? {
+        val builder = AuthenticationBuilder()
+        when (json) {
+            is JsonArray -> {
+                for (element in json) {
+                    if (element is JsonArray) {
+                        builder.addCustom(jsonArrayToAuthentication(element))
+                    } else if (element is JsonObject) {
+                        jsonToAuthentication(element, builder)
+                    }
+                }
+            }
+            is JsonObject -> {
+                jsonToAuthentication(json, builder)
+            }
+            else -> {
+                throw JsonParseException("Unsupported JSON data type: ${json::class.java}")
+            }
+        }
+        return builder.build()
+    }
+
+    private fun jsonArrayToAuthentication(jsonArray: JsonArray): Authentication {
+        val builder = AuthenticationBuilder()
+        for (element in jsonArray) {
+            when (element) {
+                is JsonObject -> jsonToAuthentication(element, builder)
+                is JsonArray -> builder.addCustom(jsonArrayToAuthentication(element))
+                else -> log.warn { "不支持的 Json 类型: ${element::class.java}" }
+            }
+        }
+        return builder.build()
+    }
+
+    private const val KEY_TYPE = "type"
+
+    private fun jsonToAuthentication(json: JsonObject, builder: AuthenticationBuilder) {
+        if (!json.has(KEY_TYPE)) {
+            log.warn { "缺少 type 字段, 无法判断 Maven 认证信息类型." }
+            return
+        } else if (!json.get(KEY_TYPE).isJsonPrimitive) {
+            log.warn { "type 字段类型错误(应为 Primitive 类型), 无法判断 Maven 认证信息类型.(实际类型: `${json::class.java}`)" }
+            return
+        }
+
+        when (json.get(KEY_TYPE).asString.trim().lowercase()) {
+            "string" -> {
+                builder.addString(checkJsonKey(json, "key"), checkJsonKey(json, "value"))
+            }
+            "secret" -> {
+                builder.addSecret(checkJsonKey(json, "key"), checkJsonKey(json, "value"))
+            }
+        }
+
+    }
+}
+
+private fun checkJsonKey(json: JsonObject, key: String): String {
+    if (!json.has(key)) {
+        throw JsonParseException("Required field does not exist: $key")
+    } else if (!json.get(key).isJsonPrimitive) {
+        throw JsonParseException("Wrong field `$key` type: ${json.get(key)::class.java}")
+    }
+    return json.get(key).asString
+}
+
+internal object MavenRepositoryConfigSerializer
+    : JsonDeserializer<MavenRepositoryConfig> {
+
+    override fun deserialize(
+        json: JsonElement,
+        typeOfT: Type,
+        context: JsonDeserializationContext
+    ): MavenRepositoryConfig {
+        return when (json) {
+            is JsonObject -> {
+                MavenRepositoryConfig(
+                    url = URL(checkJsonKey(json, "url")),
+                    proxy = if (json.has("proxy") && json.get("proxy").isJsonObject)
+                        context.deserialize<Proxy>(
+                            json.getAsJsonObject("proxy"), Proxy::class.java
+                        ) else null,
+                    layout = json.get("layout").asString ?: "default",
+                    authentication = if (json.has("authentication") && json.get("authentication").isJsonObject)
+                        context.deserialize<Authentication>(
+                            json.getAsJsonObject("authentication"), Authentication::class.java
+                        ) else null
+                )
+            }
+            is JsonPrimitive -> {
+                MavenRepositoryConfig(URL(json.asString))
+            }
+            else -> {
+                throw JsonParseException("Unsupported Maven warehouse configuration type.")
+            }
+        }
+    }
+}

scalabot-app/src/main/kotlin/util/Utils.kt

@@ -34,11 +34,7 @@ internal fun File.deepListFiles(
         this.listFiles(filenameFilter)
     } else {
         this.listFiles()
-    }
+    } ?: return null
-
-    if (files == null) {
-        return null
-    }
 
     val result = if (addSelf) mutableSetOf(this) else mutableSetOf()
     for (file in files) {
@@ -48,12 +44,10 @@ internal fun File.deepListFiles(
             if (!onlyFile) {
                 result.add(file)
             }
-            val subFiles = file.deepListFiles(false, onlyFile, fileFilter, filenameFilter)
+            val subFiles = file.deepListFiles(false, onlyFile, fileFilter, filenameFilter) ?: continue
-            if (subFiles != null) {
             result.addAll(subFiles)
         }
     }
-    }
     return result.toTypedArray()
 }
 

scalabot-app/src/main/resources/base-logback.xml

@@ -1,5 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <included>
+    <define name="DATA_LOGS" class="net.lamgc.scalabot.LogDirectorySupplier"/>
+
     <appender name="STD_OUT" class="ch.qos.logback.core.ConsoleAppender">
         <encoder>
             <pattern>[%d{HH:mm:ss.SSS} %5level][%logger{36}][%thread]: %msg%n</pattern>
@@ -20,7 +22,7 @@
     </appender>
 
     <appender name="FILE_OUT" class="ch.qos.logback.core.rolling.RollingFileAppender">
-        <file>data/logs/latest.log</file>
+        <file>${DATA_LOGS}/latest.log</file>
         <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
             <fileNamePattern>data/logs/%d{yyyy-MM-dd}.log.gz</fileNamePattern>
             <maxHistory>30</maxHistory>

scalabot-app/src/main/resources/logback-test.xml

@@ -5,6 +5,8 @@
     <logger name="org.eclipse.aether.internal.impl.DefaultTransporterProvider" level="INFO"/>
     <logger name="org.eclipse.aether.internal.impl.DefaultRepositoryConnectorProvider" level="INFO"/>
     <logger name="org.eclipse.aether.internal.impl.EnhancedLocalRepositoryManager" level="INFO"/>
+    <logger name="org.telegram.telegrambots.facilities.proxysocketfactorys" level="INFO"/>
+    <logger name="org.eclipse.aether.internal.impl.DefaultUpdateCheckManager" level="INFO"/>
 
     <root level="DEBUG">
         <appender-ref ref="FILE_OUT"/>

scalabot-app/src/test/kotlin/AppConfigTest.kt

@@ -0,0 +1,31 @@
+package net.lamgc.scalabot
+
+import com.google.gson.Gson
+import java.util.*
+import kotlin.math.abs
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class BotAccountTest {
+
+    @Test
+    fun deserializerTest() {
+        val accountId = abs(Random().nextInt()).toLong()
+        val creatorId = abs(Random().nextInt()).toLong()
+        val botAccount = Gson().fromJson(
+            """
+            {
+                "name": "TestBot",
+                "token": "${accountId}:AAHErDroUTznQsOd_oZPJ6cQEj4Z5mGHO10",
+                "creatorId": $creatorId
+            }
+        """.trimIndent(), BotAccount::class.java
+        )
+        assertEquals("TestBot", botAccount.name)
+        assertEquals("${accountId}:AAHErDroUTznQsOd_oZPJ6cQEj4Z5mGHO10", botAccount.token)
+        assertEquals(accountId, botAccount.id, "Botaccount ID does not match expectations.")
+        assertEquals(creatorId, botAccount.creatorId)
+    }
+
+}
+

scalabot-ext-example/src/main/java/net/lamgc/scalabot/simple/SayHelloExtension.java

@@ -23,7 +23,12 @@ public class SayHelloExtension implements AbilityExtension {
                 .info("Say hello to you.")
                 .privacy(Privacy.PUBLIC)
                 .locality(Locality.ALL)
-                .action(ctx -> ctx.bot().silent().send("Hello! " + ctx.user().getUserName(), ctx.chatId()))
+                .action(ctx -> {
+                    String msg = "Hello! " + ctx.user().getUserName() +
+                            " ( " + ctx.user().getId() + " ) [ " + ctx.user().getLanguageCode() + " ]" + "\n" +
+                            "Current Chat ID: " + ctx.chatId();
+                    ctx.bot().silent().send(msg, ctx.chatId());
+                })
                 .build();
     }
 
@@ -32,11 +37,16 @@ public class SayHelloExtension implements AbilityExtension {
      */
     public Ability test() {
         ReplyFlow botHello = ReplyFlow.builder(bot.db())
+                .enableStats("say_hello")
                 .action((bot, upd) -> bot.silent().send("What is u name?", upd.getMessage().getChatId()))
-                .onlyIf(update -> "hello".equalsIgnoreCase(update.getMessage().getText()))
+                .onlyIf(update -> update.hasMessage()
+                        && update.getMessage().hasText()
+                        && "hello".equalsIgnoreCase(update.getMessage().getText()))
                 .next(Reply.of((bot, upd) -> bot.silent()
                                 .send("OK! You name is " + upd.getMessage().getText().substring("my name is ".length()), upd.getMessage().getChatId()),
-                        upd -> upd.getMessage().getText().startsWith("my name is ")))
+                        upd -> upd.hasMessage()
+                                && upd.getMessage().hasText()
+                                && upd.getMessage().getText().startsWith("my name is ")))
                 .build();
 
         return Ability.builder()

scalabot-extension/build.gradle.kts

@@ -7,11 +7,12 @@ plugins {
 }
 
 dependencies {
-    api("org.telegram:telegrambots-abilities:5.6.0")
+    api("org.telegram:telegrambots-abilities:6.0.1")
     api("org.slf4j:slf4j-api:1.7.36")
 
-    // There is nothing to test.
+    testImplementation("org.junit.jupiter:junit-jupiter-api:5.8.2")
-    // testImplementation(kotlin("test"))
+    testImplementation("org.mockito:mockito-core:4.4.0")
+    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine")
 }
 
 tasks.withType<Javadoc> {
@@ -23,6 +24,8 @@ tasks.withType<Javadoc> {
 java {
     withJavadocJar()
     withSourcesJar()
+    sourceCompatibility = JavaVersion.VERSION_11
+    targetCompatibility = JavaVersion.VERSION_11
 }
 
 tasks.test {

scalabot-extension/src/main/java/net/lamgc/scalabot/extension/BotExtensionFactory.java

@@ -13,6 +13,7 @@ import java.io.File;
  * 所以将通过该接口工厂来创建扩展对象.
  *
  * @author LamGC
+ * @since 0.0.1
  */
 public interface BotExtensionFactory {
 
@@ -21,11 +22,15 @@ public interface BotExtensionFactory {
      *
      * <p> 如扩展无使用 {@link org.telegram.abilitybots.api.db.DBContext} 的话,
      * 也可以返回扩展单例, 因为 AbilityBot 本身并不禁止多个机器人共用一个扩展对象
-     * (因为 AbilityBot 只是调用了扩展中的方法来创建了功能对象).
+     * (AbilityBot 只是调用了扩展中的方法来创建 Ability 对象).
      *
      * @param bot             机器人对象.
-     * @param shareDataFolder ScalaBot App 为扩展提供的数据目录, 建议存储在数据目录中, 便于数据的存储管理.
+     * @param shareDataFolder ScalaBot App 为扩展提供的共享数据目录.
-     * @return 返回为该 Bot 对象创建的扩展对象.
+     *                        <p>路径格式为:
+     *                        <pre> $DATA_ROOT/data/extensions/{GroupId}/{ArtifactId}</pre>
+     *                        <b>同一个扩展包的 Factory</b> 接收到的共享数据目录<b>都是一样的</b>,
+     *                        建议将数据存储在数据目录中, 便于数据的存储管理.
+     * @return 返回为该 Bot 对象创建的扩展对象, 如果不希望为该机器人提供扩展, 可返回 {@code null}.
      */
     AbilityExtension createExtensionInstance(BaseAbilityBot bot, File shareDataFolder);
 

scalabot-extension/src/main/java/net/lamgc/scalabot/extension/ScalaBotExtension.java

@@ -1,32 +0,0 @@
-package net.lamgc.scalabot.extension;
-
-import org.telegram.abilitybots.api.bot.BaseAbilityBot;
-import org.telegram.abilitybots.api.db.DBContext;
-import org.telegram.abilitybots.api.sender.MessageSender;
-import org.telegram.abilitybots.api.util.AbilityExtension;
-
-/**
- *
- */
-public abstract class ScalaBotExtension implements AbilityExtension {
-
-    /**
-     * 扩展所属的机器人对象.
-     *
-     * <p> 不要给该属性添加 Getter, 会被当成 Ability 添加, 导致出现异常.
-     */
-    protected final BaseAbilityBot bot;
-
-    public ScalaBotExtension(BaseAbilityBot bot) {
-        this.bot = bot;
-    }
-
-    protected MessageSender getSender() {
-        return bot.sender();
-    }
-
-    protected DBContext getDBContext() {
-        return bot.db();
-    }
-
-}

scalabot-extension/src/main/java/net/lamgc/scalabot/extension/util/AbilityBots.java

@@ -0,0 +1,52 @@
+package net.lamgc.scalabot.extension.util;
+
+import org.telegram.abilitybots.api.bot.BaseAbilityBot;
+
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+public class AbilityBots {
+
+    private final static Pattern botTokenPattern = Pattern.compile("([1-9]\\d+):([A-Za-z\\d_-]{35,})");
+
+    private AbilityBots() {
+    }
+
+    /**
+     * 获取 AbilityBot 的账户 Id.
+     *
+     * <p> 账户 Id 来自于 botToken 中, token 的格式为 "[AccountId]:[Secret]".
+     * <p> 账户 Id 的真实性与 botToken 的有效性有关, 本方法并不会确保 botToken 的有效性, 一般情况下也无需考虑 Id 的有效性,
+     * 如果有需要, 可尝试通过调用 {@link org.telegram.telegrambots.meta.api.methods.GetMe} 来确保 botToken 的有效性.
+     *
+     * @param bot 要获取账户 Id 的 AbilityBot 对象.
+     * @return 返回 AbilityBot 的账户 Id.
+     * @throws IllegalArgumentException 当 AbilityBot 的 botToken 格式错误时抛出该异常.
+     */
+    public static long getBotAccountId(BaseAbilityBot bot) {
+        String botToken = bot.getBotToken();
+        Matcher matcher = botTokenPattern.matcher(botToken);
+        if (!matcher.matches()) {
+            throw new IllegalArgumentException("Invalid token format.");
+        }
+        return Long.parseLong(matcher.group(1));
+    }
+
+    /**
+     * 取消某一对话的状态机.
+     *
+     * @param bot    AbilityBot 实例.
+     * @param chatId 要删除状态机的聊天 Id.
+     * @return 如果状态机存在, 则删除后返回 true, 不存在(未开启任何状态机, 即没有触发任何 Reply)则返回 false.
+     */
+    public static boolean cancelReplyState(BaseAbilityBot bot, long chatId) {
+        Map<Long, Integer> stateMap = bot.db().getMap("user_state_replies");
+        if (!stateMap.containsKey(chatId)) {
+            return false;
+        }
+        stateMap.remove(chatId);
+        return true;
+    }
+
+}

scalabot-extension/src/test/java/net/lamgc/scalabot/extension/util/AbilityBotsTest.java

@@ -0,0 +1,121 @@
+package net.lamgc.scalabot.extension.util;
+
+import org.junit.jupiter.api.Test;
+import org.mapdb.DBMaker;
+import org.telegram.abilitybots.api.bot.AbilityBot;
+import org.telegram.abilitybots.api.bot.BaseAbilityBot;
+import org.telegram.abilitybots.api.db.MapDBContext;
+import org.telegram.abilitybots.api.objects.*;
+import org.telegram.abilitybots.api.sender.SilentSender;
+import org.telegram.telegrambots.meta.api.objects.Message;
+import org.telegram.telegrambots.meta.api.objects.Update;
+import org.telegram.telegrambots.meta.api.objects.User;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+public class AbilityBotsTest {
+
+    public static final User USER = new User(1L, "first", false, "last", "username", null, false, false, false);
+    public static final User CREATOR = new User(1337L, "creatorFirst", false, "creatorLast", "creatorUsername", null, false, false, false);
+
+    static Update mockFullUpdate(BaseAbilityBot bot, User user, String args) {
+        bot.users().put(USER.getId(), USER);
+        bot.users().put(CREATOR.getId(), CREATOR);
+        bot.userIds().put(CREATOR.getUserName(), CREATOR.getId());
+        bot.userIds().put(USER.getUserName(), USER.getId());
+
+        bot.admins().add(CREATOR.getId());
+
+        Update update = mock(Update.class);
+        when(update.hasMessage()).thenReturn(true);
+        Message message = mock(Message.class);
+        when(message.getFrom()).thenReturn(user);
+        when(message.getText()).thenReturn(args);
+        when(message.hasText()).thenReturn(true);
+        when(message.isUserMessage()).thenReturn(true);
+        when(message.getChatId()).thenReturn(user.getId());
+        when(update.getMessage()).thenReturn(message);
+        return update;
+    }
+
+    @Test
+    void getBotAccountIdTest() {
+        String expectToken = "1234567890:AAHXcNDBRZTKfyPED5Gi3PZDIKPOM6xhxwo";
+        long actual = AbilityBots.getBotAccountId(new TestingAbilityBot(expectToken, "test"));
+        assertEquals(1234567890, actual);
+
+        String badTokenA = "12c34d56a7890:AAHXcNDBRZTKfyPED5Gi3PZDIKPOM6xhxwo";
+        assertThrows(IllegalArgumentException.class, () ->
+                AbilityBots.getBotAccountId(new TestingAbilityBot(badTokenA, "test")));
+
+        String badTokenB = "12c34d56a7890AAHXcNDBRZTKfyPED5Gi3PZDIKPOM6xhxwo";
+        assertThrows(IllegalArgumentException.class, () ->
+                AbilityBots.getBotAccountId(new TestingAbilityBot(badTokenB, "test")));
+    }
+
+    @Test
+    void cancelReplyStateTest() {
+        User userA = new User(10001L, "first", false, "last", "username", null, false, false, false);
+        User userB = new User(10101L, "first", false, "last", "username", null, false, false, false);
+        SilentSender silent = mock(SilentSender.class);
+        BaseAbilityBot bot = new TestingAbilityBot("", "", silent);
+        bot.onRegister();
+        bot.onUpdateReceived(mockFullUpdate(bot, userA, "/set_reply"));
+        verify(silent, times(1)).send("Reply set!", userA.getId());
+        bot.onUpdateReceived(mockFullUpdate(bot, userA, "reply_01"));
+        verify(silent, times(1)).send("Reply 01", userA.getId());
+        assertTrue(AbilityBots.cancelReplyState(bot, userA.getId()));
+        bot.onUpdateReceived(mockFullUpdate(bot, userA, "reply_02"));
+        verify(silent, never()).send("Reply 02", userA.getId());
+
+        assertFalse(AbilityBots.cancelReplyState(bot, userB.getId()));
+
+        silent = mock(SilentSender.class);
+        bot = new TestingAbilityBot("", "", silent);
+        bot.onRegister();
+
+        bot.onUpdateReceived(mockFullUpdate(bot, userA, "/set_reply"));
+        verify(silent, times(1)).send("Reply set!", userA.getId());
+        bot.onUpdateReceived(mockFullUpdate(bot, userA, "reply_01"));
+        verify(silent, times(1)).send("Reply 01", userA.getId());
+        bot.onUpdateReceived(mockFullUpdate(bot, userA, "reply_02"));
+        verify(silent, times(1)).send("Reply 02", userA.getId());
+    }
+
+    public static class TestingAbilityBot extends AbilityBot {
+
+        public TestingAbilityBot(String botToken, String botUsername) {
+            super(botToken, botUsername, new MapDBContext(DBMaker.heapDB().make()));
+        }
+
+        public TestingAbilityBot(String botToken, String botUsername, SilentSender silentSender) {
+            super(botToken, botUsername, new MapDBContext(DBMaker.heapDB().make()));
+            this.silent = silentSender;
+        }
+
+        public Ability setReply() {
+            return Ability.builder()
+                    .name("set_reply")
+                    .enableStats()
+                    .locality(Locality.ALL)
+                    .privacy(Privacy.PUBLIC)
+                    .action(ctx -> ctx.bot().silent().send("Reply set!", ctx.chatId()))
+                    .reply(ReplyFlow.builder(db())
+                            .action((bot, upd) -> bot.silent().send("Reply 01", upd.getMessage().getChatId()))
+                            .onlyIf(upd -> upd.hasMessage() && upd.getMessage().getText().equals("reply_01"))
+                            .next(Reply.of((bot, upd) ->
+                                            bot.silent().send("Reply 02", upd.getMessage().getChatId()),
+                                    upd -> upd.hasMessage() && upd.getMessage().getText().equals("reply_02")))
+                            .build()
+                    )
+                    .build();
+        }
+
+        @Override
+        public long creatorId() {
+            return 0;
+        }
+    }
+
+}