插件

​

概览

​

阶段

​

链式执行

• 各步骤按升序运行。后面的步骤可以看到前面步骤所做的修改。
• 在同一步骤内，manifest 声明为 Mutates: false 的实例会在交互（exchange）的浅拷贝上并发运行 （其 Values 和响应头会被合并回来）。每个步骤最多只能有一个 Mutates: true 的实例，它在只读实例之后运行。同一步骤中出现两个修改型实例属于配置错误。
• 同一步骤的决策按严重程度合并：block > respond > warn > allow。第一个阻断决策会在其所在步骤结束后终止整个链。

​

决策

​

审计记录

​

失败模式与超时

​

实例生命周期

​

流式传输

​

Exchange 对象

​

配置

​

启用插件系统

plugins:
  enabled: true    # PLUGINS_ENABLED；默认值：false

​

实例

guardrails:
  enabled: true
  rules:
    - name: "mask-keys"
      type: "string_replace"      # 内置插件，或已加载插件的 manifest 名称
      phase: "response"           # prompt（默认）| response | stream
      order: 10                   # 阶段内的步骤
      fail_mode: "open"           # closed（默认）| open
      timeout_ms: 500             # 0 = 不设实例级超时（默认）
      config:                     # 根据插件的 ConfigSchema 进行校验
        mode: "regex"
        rules: |
          sk-[A-Za-z0-9]{20,} => [redacted]

​

加载 .so 文件

plugins:
  search_paths: ["/etc/gomodel/plugins"]   # PLUGINS_SEARCH_PATHS，逗号分隔；默认值：空
  load:
    - file: acme_guard.so                  # 相对于某个搜索路径，或使用绝对路径
      sha256: "3b1f..."                    # 可选的摘要固定；不匹配时启动失败

​

控制台

• Plugins & Guardrails 页面：Create Guardrail 会列出所有实现了 prompt、response 或 stream Hook 的插件。表单根据插件的 ConfigSchema 生成：text、textarea、number、select、 checkboxes、bool（开关）、list（自由文本条目，每行一个，以字符串数组存储）、secret（掩码显示；GET 返回 ********， 将该字面值原样发回会保留已存储的值），以及 model（与 Playground 和虚拟模型编辑器相同的可搜索模型选择器，列出网关的模型；别名或虚拟模型需手动输入）。 Advanced 部分包含 Fail mode（Default、Closed、Open） 和 Timeout (ms)；它们作用于所有引用该实例的工作流中的该实例。
• 插件列表：位于 Plugins & Guardrails 页面底部，列出每个已加载的插件类型及其标题和名称（先是 Header Edit，然后是 header_edit，配置中引用的是名称）、版本、Hook、来源（内置、注册，或 .so 路径）以及健康状态。护栏插件（其实例会对提示词、响应或流应用策略） 带有盾牌标识并排在最前面；路由策略也是插件，但不属于护栏。加载失败的插件会连同其错误一起列出。只要插件系统开启，该页面就会显示。
• Workflows 页面：每个步骤都有一个 Phase 选择器；实例下拉列表只提供其插件实现了该阶段的实例。

​

共享对象插件

• 平台：Linux、macOS 和 FreeBSD，且仅适用于使用 CGO_ENABLED=1 构建的二进制文件。默认的 GoModel 二进制文件和镜像是静态链接的，会拒绝 .so 文件并给出相应的错误提示。 请使用 make build-plugins （bin/gomodel-plugins）或 gomodel:<version>-plugins 镜像 （make image-plugins，基于 Dockerfile.plugins 构建，glibc 运行时）。
• 完全一致的工具链：插件必须使用相同的 Go 版本、相同的构建参数（-trimpath、-race、-tags）以及所有共享包完全相同的源码进行构建。 只有标准库和 pluginapi 是共享的，因此 GoModel 的内部变更永远不会影响插件， 但每个 GoModel 版本和每次 Go 工具链更新（包括补丁版本）都需要重新构建。请将其作为 CI 步骤。
• 无法卸载：.so 会一直保持加载状态，直到重启。修改已加载的文件需要重启才能生效； 编辑实例的配置则会在新的值上重新运行 Init，无需重启。
• 受信任的代码：加载 .so 等同于修改二进制文件。在生产环境中，请确保 search_paths 归 root 所有，并固定 sha256。

​

构建与检查

gomodel plugin build ./docs/example_plugins/keywordblock -o plugins/keyword_block.so
gomodel plugin inspect plugins/keyword_block.so
shasum -a 256 plugins/keyword_block.so     # 用作 plugins.load[].sha256 的值

plugin file /app/plugins/x.so was built with a different toolchain, flags, or
pluginapi sources: it was built with go1.27.3, gomodel v0.1.90, flags -trimpath;
this binary was built with go1.27.3, gomodel v0.1.91, flags (none). Rebuild it
with `gomodel plugin build` from this GoModel version

docker build -f Dockerfile.plugins --target plugin-builder -t gomodel-plugin-builder .
docker run --rm -v "$PWD/my-plugin:/src" -v "$PWD/plugins:/out" \
  gomodel-plugin-builder -o /out/my-plugin.so /src

​

编写插件

package main

import (
	"context"
	"encoding/json"
	"strings"

	"github.com/enterpilot/gomodel/pluginapi"
)

type wordBlock struct {
	words   []string
	enforce pluginapi.Enforcement
}

func (p *wordBlock) Manifest() pluginapi.Manifest {
	return pluginapi.Manifest{
		Name:      "word_block",
		Version:   "1.0.0",
		Kinds:     []pluginapi.Kind{pluginapi.KindPrompt},
		Guardrail: true,
		ConfigSchema: []pluginapi.Field{
			{
				Key: "words", Label: "Blocked words", Input: pluginapi.InputList,
				Required: true, Help: "One word per line.",
			},
			{
				Key: "action", Label: "On match", Input: pluginapi.InputSelect, Default: "block",
				Help: "Block rejects, respond answers with the message, warn records the match.",
				Options: []pluginapi.Option{{Value: "block", Label: "Block"}, {Value: "respond", Label: "Respond"}, {Value: "warn", Label: "Warn"}},
			},
			{Key: "message", Label: "Message", Input: pluginapi.InputText, Default: "request blocked by policy", Help: "Error, reply, or audit note."},
			pluginapi.BlockStatusField(),
		},
	}
}

func (p *wordBlock) Init(_ context.Context, raw json.RawMessage, _ pluginapi.Host) error {
	cfg, err := pluginapi.ParseConfig("word_block", p.Manifest().ConfigSchema, raw)
	if err != nil {
		return err
	}
	for _, w := range cfg.List("words") {
		p.words = append(p.words, strings.ToLower(w))
	}
	p.enforce = pluginapi.Enforcement{
		Action:      pluginapi.Action(cfg.Choice("action", "block", "block", "respond", "warn")),
		Message:     cfg.String("message", "request blocked by policy"),
		BlockStatus: cfg.BlockStatus("block_status"),
	}
	return cfg.Err()
}

func (p *wordBlock) Close(context.Context) error { return nil }

func (p *wordBlock) OnPrompt(_ context.Context, x *pluginapi.Exchange) (pluginapi.Decision, error) {
	if x.Prompt == nil || x.Prompt.LastUser() == nil {
		return pluginapi.Allow(), nil
	}
	text := strings.ToLower(x.Prompt.LastUser().Text())
	for _, w := range p.words {
		if strings.Contains(text, w) {
			return p.enforce.Enforce("word_block", map[string]any{"word": w}), nil
		}
	}
	return pluginapi.Allow(), nil
}

func GoModelPlugin() pluginapi.Plugin { return &wordBlock{} }

func main() {}

• Init 收到的配置已根据 ConfigSchema 校验：已应用默认值，数字、布尔值和列表已完成类型转换，未知键会被拒绝，必填键已检查。 面向行的 textarea 字段既接受 YAML 字符串列表，也接受块标量；list 字段接受列表或一行逗号分隔的内容，并以 JSON 数组形式传入；bool 字段接受布尔值或文本形式的 true/false，并以 JSON 布尔值传入。每个已配置的实例都会调用一次该方法，编辑实例时会再次调用。
• 请使用 pluginapi.ParseConfig 及其类型化读取器 （String、Choice、Bool、Int、Float、OptionalFloat、List、 Lines、Roles、BlockStatus）读取配置，而不是使用结构体：每个读取器都会执行控制台和 config.yaml 所需的相同类型转换， 出现问题时返回其默认值，Err() 会报告第一个问题并指明对应的键，因此解码器只需一串赋值语句加一次检查。 RoleOptions() 是 Roles 可识别的复选框列表。
• 通过 pluginapi.Enforcement 输出检测结果：将 action、 message、block_status 以及可选的 respond_text 读入其中，然后 Enforce(code, detail) 会给出阻断错误、respond 补全结果或警告，而 Reject(code, detail) 即使在动作为 warn 时也会给出 block 或 respond （用于绝不能放行的检测结果）。BlockStatusField() 是约定俗成的 block_status 字段。内置护栏都共用这套机制，因此它们的 block、respond 和 warn 行为一致。
• 导出一个构造函数（func GoModelPlugin() pluginapi.Plugin），这样一个文件就可以支持多个实例。var GoModelPlugin pluginapi.Plugin 也可以使用，但会将该文件限制为单个实例。
• 当插件会修改 Prompt、Response 或流时，请设置 Mutates: true。非修改型插件可以共享同一步骤并发运行。
• 当插件的实例属于护栏时，请设置 Guardrail: true：护栏是应用于提示词、响应或流的策略，无论其作用是阻断、回答、警告还是改写。 所有内置的流量插件都设置了该标志（llm_judge、 string_replace、tag_replace、header_edit、system_prompt、 llm_based_altering）； 像 cheapest_healthy 这样的路由策略从不接触流量，因此保持为 false。运行时会忽略该标志；控制台会用盾牌标识护栏插件及其实例，并将其排在最前面。
• 传给 Init 的 Host 提供 Logger()（已预先标记插件和实例）、Inference().Complete(...)（通过网关进行的聊天补全，来源为 plugin， 在预算和审计中归属于 <user path>/guardrails/<instance>）、Metrics()（名称以 plugin_<name>_ 为前缀），以及 HTTPClient()，用于调用分类器或 PII 检测器等外部服务。该客户端由所有实例共享，使用网关的代理环境和连接池，并以 60 s 超时作为兜底； 请使用 http.NewRequestWithContext 构建请求，以便实例的 timeout_ms 限制每次调用。在当前版本中，History() 会返回错误。
• 宿主还实现了可选的 pluginapi.DecisionsHost。请在 Host 上对其进行类型断言，然后调用 Decisions().Decide(ctx, req)， 像 POST /v1/decisions 那样向决策模型提出关于某个输入的类型化问题。问题可以是谓词（“是”的概率）、选择或评分。该调用的作用域和用量计算方式与 Inference().Complete 相同。 Decisions().DecisionModel(model) 用于判断某个模型是否只回答决策（例如任何 jev 模型）。llm_judge 同时使用这两者， 依据概率进行拦截，而不是解析聊天裁决：
  if dh, ok := host.(pluginapi.DecisionsHost); ok {
  	result, err := dh.Decisions().Decide(ctx, pluginapi.DecisionRequest{
  		Model:     "jev/jev-latest",
  		Input:     []pluginapi.Message{pluginapi.TextMessage(pluginapi.RoleUser, text)},
  		Questions: []pluginapi.Question{{Type: pluginapi.QuestionPredicate, Name: "spam", Instructions: "Is this spam?"}},
  	})
  	// result.Answers[0].Probability, unless result.Answers[0].Refused()
  }
  
• 添加 Summarize(config json.RawMessage) string 可在护栏列表中显示一行摘要，添加 Normalize(config) (json.RawMessage, error) 可在存储配置之前将其规范化。两者都是可选的。
• 当实例依赖进程外部的组件（例如分类器 sidecar）时，请实现 pluginapi.HealthChecker（Health(ctx) error）。 GoModel 会在请求路径之外对其进行探测：实例构建完成时探测一次，之后每次护栏刷新时（workflows.refresh_interval，默认一分钟）再探测， 截止时间为 5 s。探测失败会在 GET /admin/guardrails 和控制台中将该实例标记为 degraded，并以错误作为原因，每次状态切换时记录一次日志；错误文本不得包含 Secret，且会被截断为 256 个字符。健康状态仅供参考： 流量仍会按该实例的 fail_mode 经过它。
• 当声明了 Mutates 的插件可以被配置为不修改内容时（例如设置为仅标记而不改写的检测器），请实现 pluginapi.ContentEditor（EditsContent() bool）。 GoModel 在执行仅针对修改型插件的工作之前会询问已配置的实例，即重放链式 Responses 请求的已存储历史，而不是让提供商自行解析 previous_response_id。它从不改变 Hook 的运行方式，未实现该接口的修改型插件会被视为会修改内容。
• 字段输入类型 secret 和 model 分别用于外部分类器的 API 密钥和模型选择器；secret 值在所有管理响应中都会被掩码处理。 开关请使用 bool，开放式字符串列表（实体类型、允许列表）请使用 list，而不要将它们编码在 select 或 textarea 中。
• 对属于虚拟模型而非实例的字段，请添加 Scope: pluginapi.ScopeRoute（仅限路由策略）。

​

测试插件

• plugintest.NewHost(replies...) 是一个模拟的 Host：提供预设的推理回复（或 Reply 函数，或 Err）、由 Answer 函数作答的决策（未提供该函数时，所有问题都会被拒绝回答）、用于 DecisionModel 的 DecisionModels、记录的 Requests() 和 DecisionRequests()、 记录的 Recorded() 指标，以及一个可设置的 HTTP 客户端，用于通过 httptest 启动的模拟 sidecar。
• plugintest.Init、Text、Prompt、Completion 和 Exchange 用于构建 Hook 调用所需的测试数据，带有干净的变更跟踪和一个 Values 集合。
• plugintest.RunStream(ctx, hook, x, events) 会按照宿主在其 StreamPolicy 下的方式驱动 StreamHook：分块合并、通过 Overlap 再次呈现扣留的回看尾部、 对整个窗口应用 pass、replace、drop 和 terminate，以及在缓冲模式下为 OnResponse 组装补全结果。结果中包含客户端在每个选项上会收到的文本、 已投递的事件、terminate 决策以及结束决策。

p := plugintest.Init(t, New, `{"rules": "secret => [x]", "stream_lookbehind": 4}`, nil)
res, err := plugintest.RunStream(ctx, p.(pluginapi.StreamHook), plugintest.Exchange(nil, nil), []*pluginapi.StreamEvent{
	plugintest.TextDelta("my se"), plugintest.TextDelta("cret is safe"),
})
// res.Text[0] == "my [x] is safe"：被拆分在两个增量中的匹配只被改写了一次。

​

路由策略插件

type RouteStrategy interface {
	Select(ctx context.Context, req RouteRequest) (RouteChoice, error)
	OnAttemptEnd(outcome RouteOutcome)
}

virtual_models:
  - source: smart-router
    strategy: plugin                    # round_robin | cost | failover | adaptive | plugin
    strategy_plugin: cheapest_healthy   # 插件名称；使用 strategy: plugin 时必填
    strategy_config:                    # 插件中 Scope: route 的字段；省略时使用默认值
      prefer: cheapest                  # cheapest | fastest
      max_error_rate: 0.2
    targets:
      - openai/gpt-4o-mini
      - anthropic/claude-haiku-4-5

• strategy_config 会根据插件的路由作用域字段（GET /admin/plugins 中的 route_fields）进行校验。使用 strategy: plugin 但未设置 strategy_plugin 属于校验错误，PUT /admin/virtual-models 也会拒绝不是已加载且带有 route Hook 的插件名称。
• 在插件策略下，目标的 weight 会被忽略。
• 路由插件的实例作用域字段（端点、API 密钥）来自一个名称和类型都等于插件名称的护栏定义；如果没有这样的定义，插件会以 {} 初始化。 目前，实例作用域的 secret 值传给路由插件时是脱敏后的。保存该定义会重建实例；之前的实例会在其进行中的 Select 调用返回后关闭。
• 当插件缺失、不是路由插件、初始化失败、strategy_config 无效，或者 Select 出错、panic、耗时超过 250 ms、 或返回的目标不在可用池中时，GoModel 会回退到加权轮询，并为每个虚拟模型记录一条警告。

​

管理端点

​

GET /admin/plugins

[
  {
    "name": "string_replace",
    "label": "String Replace",
    "version": "1.0.0",
    "description": "Replaces, flags, or blocks text matching literal or regex rules in prompts, responses, and streams.",
    "kinds": ["prompt", "response", "stream"],
    "mutates": true,
    "guardrail": true,
    "source": "builtin",
    "fields": [{ "key": "rules", "label": "Rules", "input": "textarea", "required": true }],
    "route_fields": [],
    "health": "ok",
    "error": ""
  }
]

​

GET /admin/guardrails/types

{
  "type": "llm_judge",
  "label": "LLM Judge",
  "description": "Asks a judge model whether prompts and responses violate a policy, then blocks, answers, or flags them.",
  "defaults": { "action": "block", "max_tokens": 256, "target": "auto" },
  "fields": [{ "key": "model", "label": "Judge model", "input": "model", "required": true }],
  "phases": ["prompt", "response", "stream"],
  "source": "builtin",
  "mutates": false,
  "guardrail": true
}

​

GET, PUT, DELETE /admin/guardrails

​

GET /admin/workflows/guardrails

[{ "name": "pii-redact", "type": "llm_based_altering", "phases": ["prompt", "response"], "summary": "openai/gpt-4o-mini • user • default prompt" }]

​

工作流负载版本 2