deepseek-helper

io.github.hatoyuze.deepseek.toolcall.pipeline.plugins 下已经内置了四个插件, 可以使用: PLUGIN.install(host) 进行按照

内置插件速览

插件	挂载阶段	行为
RetryPlugin	EXECUTE	捕捉 PipelineException 异常，按指数退避自动重试；对于其他异常则会转换为PipelineException抛出；PipelineException(isRetryable = false) 不会被重试
TimeoutPlugin	EXECUTE	用 withTimeout 包裹内层执行，超时抛出 PipelineException
LoggingPlugin	全部阶段	记录每个阶段的进入/退出与耗时
SerializationPlugin	TRANSFORM	为 TypedToolExecutor 自动反序列化参数，写入 ctx.typedParams

这些插件默认并不会安装，你可以在 tools { } DSL 块中调用 retry() timeout() logging() 完成安装 (in io.github.hatoyuze.deepseek.toolcall.dsl.ToolCallBuilderKt)

注意: 这些插件只会作用于toolcall层次进行重试，并不会影响外部调用流

每一个管道插件只会在所指定的阶段被调用，且存在一定的调用顺序。

阶段之间是顺序执行的（前一个阶段跑完才进入下一个阶段），而同一阶段内的多个拦截器是嵌套包裹的：

flowchart LR
    subgraph PIPELINE["ToolCallPipeline 拦截器链"]
        direction TB
        V["VALIDATE<br/>参数校验"] --> A["AUTHORIZE<br/>权限鉴权"]
        A --> T["TRANSFORM<br/>参数反序列化"]
        T --> E["EXECUTE<br/>核心执行"]
        E --> P["POST_PROCESS<br/>后处理"]
        P --> R["ERROR<br/>收尾阶段"]
    end
    CALL["ToolCallHost.execute(call)"] --> PIPELINE
    PIPELINE --> RESULT["ToolResult"]

Loading

sequenceDiagram
    participant H as ToolCallHost
    participant OUT as 外层拦截器<br/>(后注册)
    participant IN as 内层拦截器<br/>(先注册)
    participant CORE as 核心执行器<br/>(EXECUTE 最内层)
    H->>OUT: execute(call, ctx)
    OUT->>IN: ctx.proceed()
    IN->>CORE: ctx.proceed()
    CORE-->>IN: ToolResult
    IN-->>OUT: 返回
    OUT-->>H: ToolResult

Loading

如果你想要自行注册一个管道插件，可以参照已有的代码完成编写.

一个简单的鉴权插件：

// import io.github.hatoyuze.deepseek.toolcall.pipeline.* / io.github.hatoyuze.deepseek.toolcall.dsl.toolHost
class AuthPlugin(private val requiredPermission: String) {

    fun install(host: ToolCallHost) {
        // 挂在 AUTHORIZE 阶段：所有工具调用都会先经过这里
        host.intercept(ToolCallPhase.AUTHORIZE) { ctx ->
            if (requiredPermission !in ctx.executionContext.permissions) {
                // 抛出业务异常：管道会将其转换为 ToolResult.error 回传给模型
                throw PipelineException(
                    "权限不足: 需要 $requiredPermission",
                    isRetryable = false, // 标记不可重试，避免被 RetryPlugin 反复执行
                )
            }
            ctx.proceed() // 校验通过，放行给内层
        }
    }
}

// 先构建 host，再安装自定义插件
val host = toolHost {
    tool("get_balance") {
        description = "查询账户余额"
        parameters { }
        execute { _, _ -> """{"balance": 100}""" }
    }
}
AuthPlugin("user:finance").install(host)

val ds = deepseek("sk-...") {
    executionContext = ToolExecutionContext("u", "s", permissions = setOf("user:finance"))
}
ds.toolHost = host

自定义插件需要在 host 构建完成后再 install，如上所示。

需要注意的是： 异常会中断整条调用链, 拦截器内抛出的异常会被管道捕获，先执行 ERROR 阶段的拦截器（可通过 ctx.error 拿到原始异常），再转成 ToolResult.error；CancellationException 会原样向上传播，不会被吞掉或重试。需要"失败重试"或"异常兜底"时，请像 RetryPlugin 一样用 try/catch 包住 ctx.proceed()。

完整示例：记录工具耗时的自定义插件

class TimingPlugin(private val onComplete: suspend (String, Long) -> Unit) {

    fun install(host: ToolCallHost) {
        // 挂在 EXECUTE 阶段，作为最后一个安装的 EXECUTE 拦截器，它位于最外层
        host.intercept(ToolCallPhase.EXECUTE) { ctx ->
            val start = System.currentTimeMillis()
            try {
                ctx.proceed() // 进入内层（可能是 retry / timeout / 核心执行器）
            } finally {
                onComplete(ctx.call.name, System.currentTimeMillis() - start)
            }
        }
    }
}

val host = toolHost {
    tool("search") {
        description = "搜索互联网"
        parameters { string("q") { required = true } }
        execute { bag, _ -> """{"query":"${bag.getString("q")}"}""" }
    }
    retry(maxAttempts = 3) // 先注册 → 更靠近核心执行器
    timeout(5_000)         // 后注册 → 包裹整个重试循环
}
// 最后安装 → 位于 EXECUTE 最外层，测量包含重试/超时在内的完整执行耗时
TimingPlugin { name, ms -> println("$name 耗时 ${ms}ms") }.install(host)