Annotation-based Development¶

Suitable for simple plugins. Define features declaratively through annotations, with plugin code auto-generated by the KSP annotation processor.

Install Annotation Processor Dependency¶

// erii-plugins/my-plugin/build.gradle.kts
plugins {
    id("uesugi.erii-plugin")
}

dependencies {
    // Annotation processor (KSP)
    add("ksp", project(":erii-spi:erii-spi-annotation"))
    // Annotation definitions
    compileOnly(project(":erii-spi:erii-spi-annotation"))
}

Define Plugin¶

Use @Definition (file-level annotation) to define plugin metadata:

// MyPlugin.kt
@file:Definition(
    pluginId = "my-annotation-plugin",
    version = "0.0.1",
    description = "A plugin defined via annotations",
    provider = "your-name"
)

package myplugin

Function Annotations¶

@Route -- Route Extension @Cmd -- Command Extension @Passive -- Passive Extension @LLMTool -- LLM Tool @OnLoad / @OnUnload -- Lifecycle

@Route(method = "GET", path = "/api/hello")
suspend fun helloRoute() {
    val http = useHttp()
    // Handle request
}

@Cmd(name = "hello", alias = ["hi", "hey"])
suspend fun helloCommand() {
    val meta = useMeta()
    val llm = useLLM()
    // Handle command
}

@Passive
suspend fun backgroundTask() {
    val scheduler = useScheduler()
    scheduler.scheduleRecurrently("bg", "0 */1 * * *") {
        // Periodic execution
    }
}

@LLMTool(name = "search_images", set = "default")
@LLMDesc("Search for images based on a query string")
suspend fun searchImages(
    @LLMDesc("The search query") query: String
): String {
    // Implement search logic
    return "results..."
}

@OnLoad
suspend fun init() {
    // Executed when plugin loads
    val config = useConfig()
}

@OnUnload
suspend fun cleanup() {
    // Cleanup when plugin unloads
}

Context Functions¶

In annotation-marked functions, use the following suspend functions to access PluginContext:

Function	Corresponding Capability
`useMeta()`	Get current message metadata
`useMem()`	In-memory cache
`useKv()`	Key-value storage
`useBlob()`	File storage
`useVector()`	Vector embedding and retrieval
`useConfig()`	Configuration reading
`useDatabase()`	Database queries
`useScheduler()`	Task scheduling
`useLLM()`	LLM invocation
`useHttp()`	HTTP client
`useServer()`	HTTP server routes