pluginkit

pluginkit

启动期插件装配库：插件作者只注册类型，使用方用实例图和 root id 构造根插件；插件依赖既可以引用已有实例，也可以直接内联私有插件。

github.com/lengzhao/pluginkit          插件类型：Register / Lookup / Describe
github.com/lengzhao/pluginkit/config   配置识别：PluginUse / Parse
github.com/lengzhao/pluginkit/build    实例化：Build / BuildInto / Scaffold / GetByID / Collect
github.com/lengzhao/pluginkit/manager  Web 配置管理 UI（可选）

根包不读配置、不构造实例。config 不查注册表、不调用 New。build 不解释 agent / workflow / etl 等业务字段。

安装

go get github.com/lengzhao/pluginkit

插件作者

init() 只登记 kind 和构造函数：

func init() {
    pluginkit.Register("openai", New)
}

func New(cfg Config) (*OpenAI, error) {
    return &OpenAI{model: cfg.Model}, nil
}

构造函数只支持：

func New() (T, error)
func New(cfg Config) (T, error)
func New(cfg Config, deps Deps) (T, error)

使用方

默认用 root id 构造一张插件实例图：

workflow, _, err := build.Build[Workflow](ctx, cfg, "workflow")

workflow:
  use: sequential-workflow
  deps:
    steps:
      - use: http-step
      - use: save-step
        deps:
          store:
            use: sqlite-store

如果 workflow.deps.steps 里引用了不实现 Step 的实例，Build[Workflow] 会在 deps 阶段失败。

Agent 也可以建模成 root plugin：

agent:
  use: agent
  deps:
    llm:
      use: openai
      config:
        model: gpt-5.5
    tools:
      - use: read-file
      - use: shell

内联实例未写 id 时按路径生成，例如 workflow.steps[0]。需要复用的实例放到顶层并用 id 引用。插件自己的 config 按 JSON 解到构造函数参数，未知字段会失败。

BuildInto 仍可用于直接填充 target struct，但 workflow、agent、ETL 这类编排应优先建模为 root plugin，把引用和内联子插件放进插件 Deps。

按类型收集与后置装配

Build 返回的 Result 保存本次 root 可达且已成功构造的全部实例。运行期入口可以按接口筛选贡献者，再装配到收集器，例如 slash command provider：

app, result, err := build.Build[*App](ctx, graph, "app")
if err != nil {
    return err
}

// 约定式：收集器实现 SetContributions([]T)
if err := build.WireSetter[command.Provider](result); err != nil {
    return err
}

// 自定义装配函数：适合 SetCommands 这类宿主自定义方法名
if err := build.WireContributions(
    result,
    func(collector command.Collector, providers []command.Provider) error {
        return collector.SetCommands(providers)
    },
); err != nil {
    return err
}

Collect[T] 只负责从 Result 筛选实例，不执行装配。CollectInstances[T] 会额外保留实例 id 和 kind，便于诊断或冲突报错。收集范围是当前这次 build result，不是全局 registry，也不会扫描所有已注册 kind。

当多个插件向同一个 registry 贡献能力、又不想在 deps 里形成环时，把收集器建模为独立插件实例，build 完成后再 wire。没有贡献者时不会调用收集器；有贡献者但找不到可装配的收集器时返回 build.ErrNoContributionsCollector；nil result 是 no-op。

查看插件配置与扩展点

按 kind 查看已注册插件类型的配置字段和依赖扩展点：

desc, ok := pluginkit.Describe("openai")
if !ok {
    // 未注册
}
for _, field := range desc.Config {
    // field.Name 对应 config 里的 key
}
for _, ext := range desc.Extensions {
    // ext.Name 对应 deps 里的 key；ext.List 表示多值；ext.Optional 表示可选
}

init() 注册后、New() 之前，可导出可填写的配置骨架：

desc, ok := pluginkit.Describe("agent")
if !ok {
    // 未注册
}
tmpl := desc.Template()

Template() 返回 map[string]any，格式与 build.Build 接受的 PluginUse 一致。Config 实现 Defaulter 时 config 填 SetDefaults 后的真实默认值，否则为零值占位；必填 deps 用 use: "" 占位，可选 deps 会省略。需要 YAML 时由使用方自行 yaml.Marshal(tmpl)。

插件的 Config 类型可选实现两个接口，build 在 decode 之后、New 之前依次调用：

type Defaulter interface{ SetDefaults() }    // 填充默认值，不返回 error
type Validator interface{ Validate() error } // 校验失败作为 validate 阶段错误响亮报出

约定零值视为未配置；需要区分显式零值时使用指针字段。详见 docs/2026-10-02-config-defaults-validation.md。

use: agent
config:
  model: ""
deps:
  llm:
    use: ""
  tools:
    - use: ""

按接口类型查找可用插件、列出全部 kind：

for _, kind := range pluginkit.ListKinds() {
    // ...
}
for _, kind := range pluginkit.CompatibleKinds(reflect.TypeOf((*agent.Tool)(nil)).Elem()) {
    // ...
}

Web Manager

可嵌入宿主 binary 的可视化配置编辑器（内联 root 实例图）：

import "github.com/lengzhao/pluginkit/manager"

func main() {
    // 先 import 自己的插件包，触发 init Register
    manager.Run(manager.Options{Addr: ":8080"})
}

Demo：

go run ./examples/manager
# 打开 http://localhost:8080

详见 docs/2026-08-21-web-manager.md。

示例

cd examples/agent && go run .
cd examples/agent && go run . config.flat.yaml

cd examples/workflow && go run .
cd examples/workflow && go run . config.flat.yaml

cd examples/commands && go run .
cd examples/commands && go run . compact

go run ./examples/manager