feat(agent): 优化 Agent 工具系统和会话管理

- 新增 ToolManagementTool 用于动态管理工具状态
- 支持工具注册和注销后缓存更新，避免重复构建工具列表
- 引入 CoroutineScope 管理后台任务生命周期，支持自动取消
- 优化 ConversationStore，添加 LRU 淘汰策略和单会话消息上限控制
- 调整 MessageBuffer 支持全局最大消息条数和 raw 字段截断
- 调整 OneBot 缓存策略，限制 messageSourceCache 大小，避免内存膨胀
- 改进 QdrantMemoryStore 的数据加载方式，提升性能并支持批量更新
- 完善 AgentConfig 支持工具状态与会话存储限制配置
- 引入 KSP 插件支持，重构示例工具声明方式，简化工具开发流程
- 优化文件索引服务，改用更高效的删除过滤接口
- 调整 ContextCompactor 中的消息列表复制方式，避免不必要的深拷贝关闭资源时安全取消相关协程和存储组件

Author: ZenthXSin

.gitignore

@@ -1,10 +1,11 @@
 .gradle
-build/
+build
 !gradle/wrapper/gradle-wrapper.jar
 !**/src/main/**/build/
 !**/src/test/**/build/
 /other
 /config
+src/main/vicky-ksp/build/
 
 ### IntelliJ IDEA ###
 .idea/modules.xml
@@ -47,4 +48,5 @@ bin/
 .mimocode/
 
 ### Mac OS ###
-.DS_Store
+.DS_Store
+/src/main/vicky-ksp/build/kotlin/compileKotlin/cacheable/caches-jvm/jvm/kotlin/class-attributes.tab

.idea/gradle.xml

@@ -2,6 +2,7 @@ plugins {
     kotlin("jvm") version "2.3.20"
     kotlin("plugin.serialization") version "2.3.20"
     id("com.gradleup.shadow") version "9.0.0-beta12"
+    id("com.google.devtools.ksp")
     `maven-publish`
 }
 
@@ -14,15 +15,20 @@ repositories {
 
 dependencies {
     implementation("com.aallam.openai:openai-client:4.1.0")
+
     implementation("io.ktor:ktor-client-okhttp:3.0.0")
     implementation("io.ktor:ktor-client-content-negotiation:3.0.0")
     implementation("io.ktor:ktor-serialization-kotlinx-json:3.0.0")
+
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
-    implementation("ch.qos.logback:logback-classic:1.5.12")
+
+    implementation("ch.qos.logback:logback-classic:1.5.13")
 
     implementation("top.mrxiaom.mirai:overflow-core:1.1.0")
 
+    ksp(project(":src:main:vicky-ksp"))
+
     testImplementation(kotlin("test"))
 }
 

build.gradle.kts

@@ -1,4 +1,15 @@
-plugins {
-    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        mavenCentral()
+        google()   // KSP 插件托管在 Google Maven，必须加
+    }
+    plugins {
+        id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
+        id("com.google.devtools.ksp") version "2.3.9"
+    }
 }
-rootProject.name = "Vicky"
+
+rootProject.name = "Vicky"
+
+include("src:main:vicky-ksp")

settings.gradle.kts

@@ -10,6 +10,8 @@ import com.aallam.openai.api.chat.ToolType
 import com.aallam.openai.client.OpenAI
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
 import kotlinx.coroutines.launch
 import kotlinx.serialization.json.Json
 import org.example.vicky.context.ContextBuilder
@@ -31,6 +33,8 @@ import org.example.vicky.tool.ToolContext
 import org.example.vicky.tool.ToolRegistry
 import org.example.vicky.tool.ToolResult
 import org.example.vicky.tool.builtin.BuiltinTools
+import org.example.vicky.tool.builtin.ToolManagementTool
+import org.example.vicky.config.ConfigManager
 import org.example.vicky.vector.QdrantVectorStore
 import com.aallam.openai.api.chat.Tool as OAITool
 
@@ -42,10 +46,16 @@ abstract class Agent(
     protected val config: AgentConfig,
     private val openAi: OpenAI = OpenAiClientFactory.create(config),
     protected val contextBuilder: ContextBuilder = ContextBuilder(config.agentMd),
-    protected val store: ConversationStore = ConversationStore(),
-) {
+    protected val store: ConversationStore = ConversationStore(
+        maxConversations = config.conversationStoreMaxConversations,
+        maxMessages = config.conversationStoreMaxMessages,
+    ),
+) : AutoCloseable {
     val tools: ToolRegistry = ToolRegistry()
     private val compactor = ContextCompactor(config, openAi)
+    private lateinit var toolManagementTool: ToolManagementTool
+    private var cachedOaiTools: List<OAITool>? = null
+    private val scope = CoroutineScope(Dispatchers.Default + SupervisorJob())
 
     // 向量存储组件（Qdrant 不可用时自动禁用记忆功能）
     private val vectorStore: QdrantVectorStore? = run {
@@ -103,12 +113,18 @@ abstract class Agent(
         if (config.builtinTools) {
             val baseDir = java.io.File(System.getProperty("user.dir"))
             BuiltinTools.all(baseDir, memoryStore, fileIndexService, distillationScheduler).forEach { tools.register(it) }
+            toolManagementTool = ToolManagementTool { persistToolStates() }
+            tools.register(toolManagementTool)
+            for ((toolName, enabled) in config.toolStates) {
+                if (!enabled) tools.unregister(toolName)
+            }
+            cachedOaiTools = null
         }
 
         // 启动时后台自动索引文件（不阻塞主线程）
         if (fileIndexService != null && config.fileIndexAutoIndexOnStart) {
             println("[Vicky] 开始后台索引文件...")
-            CoroutineScope(Dispatchers.IO).launch {
+            scope.launch(Dispatchers.IO) {
                 try {
                     val result = fileIndexService.indexAll { current, success, skipped ->
                         print("\r[Vicky] 索引中: 已处理 $current 个文件，$success 个已索引，$skipped 个已跳过")
@@ -137,8 +153,24 @@ abstract class Agent(
     protected open val buffer: org.example.vicky.channel.onebot.MessageBuffer? = null
 
     /** 运行时注册工具。 */
-    fun registerTool(tool: Tool) = tools.register(tool)
-    fun unregisterTool(name: String): Tool? = tools.unregister(name)
+    fun registerTool(tool: Tool) {
+        tools.register(tool)
+        cachedOaiTools = null
+    }
+
+    fun unregisterTool(name: String): Tool? {
+        val result = tools.unregister(name)
+        if (result != null) cachedOaiTools = null
+        return result
+    }
+
+    private fun persistToolStates() {
+        val activeStates = tools.snapshot().filter { it.name != "manage_tools" }.map { it.name to true }
+        val disabledStates = toolManagementTool.getDisabledToolNames().map { it to false }
+        val allStates = (activeStates + disabledStates).toMap()
+        val configData = ConfigManager.loadOrCreate().config
+        ConfigManager.save(configData.copy(toolStates = allStates))
+    }
 
     /**
      * 入口：外部把收到的消息丢进来。
@@ -303,6 +335,8 @@ abstract class Agent(
             if (clearContextAfter) {
                 store.clear(msg.conversationId)
                 log("cleared context for '${msg.conversationId}' after reply")
+            } else {
+                store.trimIfNeeded(msg.conversationId)
             }
         }
     }
@@ -352,15 +386,26 @@ abstract class Agent(
         }
     }
 
-    private fun buildOpenAiTools(): List<OAITool> = tools.snapshot().map { t ->
-        OAITool(
-            type = ToolType.Function,
-            function = FunctionTool(
-                name = t.name,
-                description = t.description,
-                parameters = Parameters.fromJsonString(Json.encodeToString(kotlinx.serialization.json.JsonObject.serializer(), t.parameters)),
-            ),
-        )
+    private fun buildOpenAiTools(): List<OAITool> {
+        cachedOaiTools?.let { return it }
+        val result = tools.snapshot().map { t ->
+            OAITool(
+                type = ToolType.Function,
+                function = FunctionTool(
+                    name = t.name,
+                    description = t.description,
+                    parameters = Parameters.fromJsonString(Json.encodeToString(kotlinx.serialization.json.JsonObject.serializer(), t.parameters)),
+                ),
+            )
+        }
+        cachedOaiTools = result
+        return result
+    }
+
+    override fun close() {
+        distillationScheduler?.stop()
+        scope.cancel()
+        vectorStore?.close()
     }
 
     private companion object {

src/main/kotlin/org/example/vicky/agent/Agent.kt

@@ -4,19 +4,31 @@ import com.aallam.openai.api.model.ModelId
 
 /**
  * Agent 运行时配置。
- *
- * @property model OpenAI / 兼容服务的模型 id (例如 "gpt-4o-mini" 或 "deepseek-chat")。
- * @property apiKey API key (可空仅用于 mock 测试)。
- * @property baseUrl 兼容 OpenAI 协议的自定义 host，例如 "https://api.deepseek.com/v1/"。null = 官方。
- * @property maxSteps 单次 receive 最多走多少轮 LLM 推理，防死循环。
- * @property maxMemoryRounds 最多保留多少轮用户消息（1轮 = user + assistant），超过则截断旧消息。0 = 不限制。
- * @property maxContextLength 上下文总字符数上限，超过则触发 LLM 压缩生成摘要。0 = 不限制。
- * @property mode 模式 1 (SILENT) 或模式 2 (VERBOSE)。
- * @property temperature 透传给 chat completion。
- * @property agentMd 基础系统提示文本 (人设/指令)，直接内联，不再读文件。
- * @property debug 打开后输出框架运行日志 (每轮推理 / 工具调用) 及底层 HTTP 日志。
- * @property think 打开后把 agent 每轮的中间思考文本 (调用工具前的 content) 打到日志。
- * @property embedding 语义模型配置；null = 未启用。内置 / 外置互斥，见 [EmbeddingConfig]。
+ * @property model OpenAI / 兼容服务的模型 id，例如 `"gpt-4o-mini"`、`"deepseek-chat"`。
+ *                 直接作为 `ModelId` 透传给 chat completion 接口。
+ * @property apiKey 调用 LLM 用的 API Key。仅在 mock 测试场景下可为空字符串。
+ * @property baseUrl 兼容 OpenAI 协议的自定义服务地址，例如 `"https://api.deepseek.com/v1/"`。
+ *                   设为 `null` 表示走 OpenAI 官方端点。
+ * @property maxSteps 单次 `receive` 内允许的最大 LLM 推理轮数，用于防止工具调用死循环。
+ *                    达到上限后框架会强制终止并返回当前结果。
+ * @property maxMemoryRounds 短期上下文窗口中最多保留的对话轮数。
+ *                           此处 1 轮 = 1 条 user 消息 + 1 条 assistant 消息。
+ *                           超出后按时间序截断最早的整轮消息。
+ *                           设为 `0` 表示不限制条数（仍受 [maxContextLength] 约束）。
+ * @property maxContextLength 上下文总字符数上限。超过该阈值时触发 LLM 摘要压缩，
+ *                           将旧消息合并为一段摘要后再继续对话。
+ *                           设为 `0` 表示不启用基于长度的摘要压缩。
+ * @property mode 运行模式：[AgentMode.SILENT]（模式 1，静默）或 [AgentMode.VERBOSE]（模式 2，详尽输出）。
+ * @property temperature 采样温度，透传给 chat completion。
+ *                        设为 `null` 表示使用服务端默认值；值越大输出越发散，越小越确定。
+ * @property agentMd 基础系统提示文本（人设 / 指令），以字符串内联方式提供，不再从文件读取。
+ * @property debug 是否开启框架运行日志（每轮推理、工具调用）及底层 HTTP 日志。
+ * @property think 是否将 Agent 每轮的中间思考文本（调用工具前的 content）输出到日志。
+ *                 仅在 [debug] 或独立排查场景下有意义。
+ * @property builtinTools 是否注册框架内置工具集。设为 `false` 时 Agent 仅依赖外部注入的工具。
+ * @property embedding 语义向量模型配置，用于记忆与文件索引的向量化。
+ *                      设为 `null` 表示未启用语义能力，此时长期记忆与文件索引均不可用。
+ *                      内置与外置 Embedding 互斥，详见 [EmbeddingConfig]。
  */
 data class AgentConfig(
     val model: ModelId,
@@ -31,12 +43,11 @@ data class AgentConfig(
     val debug: Boolean = false,
     val think: Boolean = false,
     val builtinTools: Boolean = true,
+    val toolStates: Map<String, Boolean> = emptyMap(),
     val embedding: EmbeddingConfig? = null,
-    // Qdrant 配置
     val qdrantHost: String? = null,
     val qdrantGrpcPort: Int = 6334,
     val qdrantHttpPort: Int = 6333,
-    // 记忆配置
     val memoryEnabled: Boolean = false,
     val memoryTopK: Int = 5,
     val memoryTokenBudget: Int = 800,
@@ -46,18 +57,22 @@ data class AgentConfig(
     val memoryDistilledRetentionDays: Int = 7,
     val memoryCollection: String = "vicky_memories",
     val memoryRawCollection: String = "vicky_memories_raw",
-    // 蒸馏配置
     val distillationEnabled: Boolean = true,
     val distillationSchedule: String = "0 2 * * *",
     val distillationMaxConversations: Int = 10,
     val distillationTemperature: Double = 0.1,
     val distillationMaxTokens: Int = 1000,
-    // 文件索引配置
     val fileIndexEnabled: Boolean = false,
     val fileIndexCollection: String = "vicky_files",
     val fileIndexChunkSize: Int = 500,
     val fileIndexChunkOverlap: Int = 50,
     val fileIndexIgnorePatterns: List<String> = listOf(".git", ".gradle", "build", "node_modules"),
     val fileIndexPaths: List<String> = emptyList(),
     val fileIndexAutoIndexOnStart: Boolean = true,
-)
+    // 会话存储限制
+    val conversationStoreMaxConversations: Int = 500,
+    val conversationStoreMaxMessages: Int = 200,
+    // 消息缓冲区限制
+    val messageBufferMaxGlobalEntries: Int = 10000,
+    val messageBufferRawTruncate: Int = 500,
+)

src/main/kotlin/org/example/vicky/agent/AgentConfig.kt

@@ -0,0 +1,4 @@
+package org.example.vicky.annotations
+
+@Target(AnnotationTarget.CLASS)
+annotation class ToolGroup(val name: String)

src/main/kotlin/org/example/vicky/annotations/ToolGroup.kt

@@ -0,0 +1,6 @@
+package org.example.vicky.annotations
+
+annotation class ToolParam(
+    val description: String = "",
+    val required: Boolean = true
+)

src/main/kotlin/org/example/vicky/annotations/ToolParam.kt

@@ -0,0 +1,6 @@
+package org.example.vicky.annotations
+
+annotation class VickyTool(
+    val name: String,
+    val description: String
+)

src/main/kotlin/org/example/vicky/annotations/VickyTool.kt

@@ -43,35 +43,49 @@ data class RichMediaItem(
  *
  * - TTL 过期自动清理 (查询时惰性触发)。
  * - 单会话超过 [maxEntries] 条时丢弃最早的。
+ * - 全局超过 [maxGlobalEntries] 条时按 FIFO 淘汰最旧会话。
  * - 支持 unread 游标：每次查询 unread 后自动推进。
  *
  * @property ttlMs 消息存活时间，默认 1 小时。
  * @property maxEntries 单会话最大消息条数，默认 500。
+ * @property maxGlobalEntries 全局最大消息条数，默认 10000。
+ * @property rawTruncate raw 字段截断长度，默认 500。
  */
 class MessageBuffer(
     private val ttlMs: Long = 3_600_000L,
     private val maxEntries: Int = 500,
+    private val maxGlobalEntries: Int = 10000,
+    private val rawTruncate: Int = 500,
 ) {
     private val buffers = ConcurrentHashMap<String, MutableList<BufferedMessage>>()
     private val cursors = ConcurrentHashMap<String, Long>()
 
     /** 存入一条消息。 */
     fun store(conversationId: String, message: BufferedMessage) {
+        val truncatedRaw = if (rawTruncate > 0 && message.raw.length > rawTruncate) {
+            message.raw.take(rawTruncate)
+        } else {
+            message.raw
+        }
+        val truncated = if (truncatedRaw !== message.raw) message.copy(raw = truncatedRaw) else message
+
         val list = buffers.getOrPut(conversationId) { mutableListOf() }
         synchronized(list) {
-            list.add(message)
+            // 存入时清理过期消息
+            val cutoff = System.currentTimeMillis() - ttlMs
+            list.removeAll { it.timestamp < cutoff }
+            list.add(truncated)
             // 超过上限，丢弃最早的
             while (list.size > maxEntries) list.removeAt(0)
         }
+        // 全局清理
+        evictIfNeeded()
     }
 
-    /** 获取未过期的消息列表 (惰性清理 + 游标过滤)。 */
+    /** 获取未过期的消息列表 (游标过滤)。 */
     private fun getValid(conversationId: String, since: Long = 0L): List<BufferedMessage> {
         val list = buffers[conversationId] ?: return emptyList()
-        val cutoff = System.currentTimeMillis() - ttlMs
         synchronized(list) {
-            // 惰性清理过期
-            list.removeAll { it.timestamp < cutoff }
             return list.filter { it.timestamp > since }
         }
     }
@@ -108,4 +122,19 @@ class MessageBuffer(
     /** 指定会话当前缓冲的消息条数。 */
     fun size(conversationId: String): Int =
         buffers[conversationId]?.size ?: 0
+
+    private fun totalEntries(): Int = buffers.values.sumOf { it.size }
+
+    private fun evictIfNeeded() {
+        if (totalEntries() <= maxGlobalEntries) return
+        // 按最旧消息时间排序，淘汰最旧的会话
+        val sorted = buffers.entries.sortedBy { entry ->
+            entry.value.minOfOrNull { it.timestamp } ?: 0L
+        }
+        for (entry in sorted) {
+            if (totalEntries() <= maxGlobalEntries) break
+            buffers.remove(entry.key)
+            cursors.remove(entry.key)
+        }
+    }
 }