用 Go 编写原生插件

curl https://<平台入口地址>/api/v1/deployment \
  -H "Cookie: <控制台会话凭证>"

{
  "deploy_mode": "private",
  "deploy_status": "ready",
  "capabilities": {
    "dynamic_plugins": true
  }
}

access-guard/
├── go.mod          # 模块定义 + SDK 依赖（版本须与平台运行环境一致）
├── plugin.go       # package main，导出 GetName/Init/PreHook/PostHook/Cleanup
└── Makefile        # 可选：封装 go build -buildmode=plugin

module access-guard

go 1.22

// SDK 版本须与平台运行环境一致（属于构建参数对齐的一部分，见 §7）
require lingqu.dev/pipeline-sdk v1.4.0

import "lingqu.dev/pipeline-sdk/plugin"

package plugin

// HookContext 承载前置（pre）与后置（post）两阶段的治理上下文。
// Phase 标明当前阶段；按阶段读取对应字段，跨阶段状态走 Context 通道。
type HookContext struct {
	Phase     string         `json:"phase"`       // "pre" | "post"
	RequestID string         `json:"request_id"`  // 全流一致（含流式各 chunk）
	APIKeyID  string         `json:"api_key_id"`  // 归属子账户标识
	Request   *Request       `json:"request,omitempty"`  // pre 阶段
	Routing   *Routing       `json:"routing,omitempty"`  // pre 阶段
	Response  *Response      `json:"response,omitempty"` // post 阶段
	Usage     *Usage         `json:"usage,omitempty"`    // post 阶段
	Stream    *Stream        `json:"stream,omitempty"`   // post 阶段（流式逐 chunk）
	Metadata  *Metadata      `json:"metadata,omitempty"`
	Context   map[string]any `json:"context,omitempty"`  // 前置写入、配对后置回传
}

type Request struct {
	Model    string    `json:"model"`
	Messages []Message `json:"messages"`
	Stream   bool      `json:"stream"`
}

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type Routing struct {
	Complexity     string `json:"complexity"`      // 简单 / 复杂
	CandidateModel string `json:"candidate_model"` // 路由当前选定上游模型中性名
}

type Response struct {
	Model        string `json:"model"`
	Content      string `json:"content"`       // 非流式整段；流式为当前 chunk
	FinishReason string `json:"finish_reason"`
}

type Usage struct {
	InputTokens  int    `json:"input_tokens"`
	OutputTokens int    `json:"output_tokens"`
	CacheHit     bool   `json:"cache_hit"`  // 上游输入缓存命中（不触发短路）
	Thinking     bool   `json:"thinking"`
	PriceTier    string `json:"price_tier"` // 6 档之一
}

type Stream struct {
	IsStream   bool `json:"is_stream"`
	ChunkIndex int  `json:"chunk_index"`
	IsLast     bool `json:"is_last"`
}

type Metadata struct {
	ReceivedAt string `json:"received_at"`
	NodeID     string `json:"node_id"`
}

package plugin

// 前置 Hook 出参：决定请求是否继续、改写、短路或拒绝。
type PreResult struct {
	Action               string         `json:"action"`  // 见 Action 常量
	Request              *Request       `json:"request,omitempty"`                // Action=ActionRewrite 时
	ShortCircuitResponse *Response      `json:"short_circuit_response,omitempty"` // Action=ActionShortCircuit 时
	RejectReason         *Reason        `json:"reject_reason,omitempty"`          // Action=ActionReject 时
	Context              map[string]any `json:"context,omitempty"`                // 传给配对后置 Hook
}

// 后置 Hook 出参：决定出站响应放行、脱敏或拦截。
type PostResult struct {
	Action      string    `json:"action"` // 见 Action 常量
	Response    *Response `json:"response,omitempty"`     // Action=ActionRedact 时
	BlockReason *Reason   `json:"block_reason,omitempty"` // Action=ActionBlock 时
}

type Reason struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

// Config 携带注册时的 config 字段；用 Unmarshal 解析到自定义结构。
type Config struct{ /* SDK 内部持有原始配置 */ }

func (c Config) Unmarshal(v any) error { /* 由 SDK 实现 */ return nil }

// 前置动作常量
const (
	ActionContinue     = "continue"
	ActionRewrite      = "rewrite"
	ActionShortCircuit = "short_circuit"
	ActionReject       = "reject"
)

// 后置动作常量
const (
	ActionPass   = "pass"
	ActionRedact = "redact"
	ActionBlock  = "block"
)

package main

import (
	"lingqu.dev/pipeline-sdk/plugin"
)

// GetName 返回插件全局唯一标识，须与注册时的 name 一致。
func GetName() string {
	return "passthrough-go"
}

// Init 在加载后、首次处理请求前调用一次，接收注册时的 config。
func Init(cfg plugin.Config) error {
	// 一次性初始化：解析配置、建立外部连接、前置校验等
	return nil
}

// PreHook 入站直通：不改写、不短路，放行后续节点，并向 context 写一个标记。
func PreHook(ctx *plugin.HookContext) (*plugin.PreResult, error) {
	return &plugin.PreResult{
		Action: plugin.ActionContinue,
		Context: map[string]any{
			"passthrough_go_seen": ctx.RequestID,
		},
	}, nil
}

// PostHook 出站直通：放行响应，逆序回收前置写入的 context。
func PostHook(ctx *plugin.HookContext) (*plugin.PostResult, error) {
	_ = ctx.Context["passthrough_go_seen"] // 配对前置写入的标记在此回传
	return &plugin.PostResult{
		Action: plugin.ActionPass,
	}, nil
}

// Cleanup 在卸载 / 停机时调用一次，释放资源。
func Cleanup() error {
	return nil
}

加载阶段：  GetName → Init
每次请求：  PreHook →（内建段：上游推理）→ PostHook
卸载阶段：  Cleanup

package main

import (
	"strings"

	"lingqu.dev/pipeline-sdk/plugin"
)

// 注册时通过 config 传入的策略清单。
type guardConfig struct {
	BlockKeywords  []string `json:"block_keywords"`  // 命中即拒绝
	RedactKeywords []string `json:"redact_keywords"` // 命中则剥离片段后继续
}

var cfg guardConfig

func GetName() string { return "access-guard" }

func Init(c plugin.Config) error {
	// 把注册时的 config 解析进策略结构；解析失败即 Init 失败、插件不纳入编排
	return c.Unmarshal(&cfg)
}

// PreHook 入站访问控制：仅在治理面做拦截 / 片段剥离，不生成任何内容。
func PreHook(ctx *plugin.HookContext) (*plugin.PreResult, error) {
	last := lastUserContent(ctx)

	// （1）命中拦截清单 → 结构化拒答，不再转发上游
	for _, kw := range cfg.BlockKeywords {
		if kw != "" && strings.Contains(last, kw) {
			return &plugin.PreResult{
				Action: plugin.ActionReject,
				RejectReason: &plugin.Reason{
					Code:    "guardrail_blocked",
					Message: "请求命中访问控制策略，已被入站护栏拦截。",
				},
			}, nil
		}
	}

	// （2）命中需剥离的敏感片段 → 治理面改写后继续（只剥离片段，不补写语义）
	rewritten := last
	for _, kw := range cfg.RedactKeywords {
		if kw != "" {
			rewritten = strings.ReplaceAll(rewritten, kw, "[已按策略剥离]")
		}
	}
	if rewritten != last {
		return &plugin.PreResult{
			Action:  plugin.ActionRewrite,
			Request: cloneRequestWithLastUser(ctx, rewritten),
			Context: map[string]any{"access_guard": "rewritten"},
		}, nil
	}

	// （3）未命中任何策略 → 放行
	return &plugin.PreResult{
		Action:  plugin.ActionContinue,
		Context: map[string]any{"access_guard": "pass"},
	}, nil
}

// PostHook 直通收尾：访问控制在前置段已完成，后置仅逆序回收上下文。
func PostHook(ctx *plugin.HookContext) (*plugin.PostResult, error) {
	_ = ctx.Context["access_guard"]
	return &plugin.PostResult{Action: plugin.ActionPass}, nil
}

func Cleanup() error { return nil }

// 取末条用户消息内容。
func lastUserContent(ctx *plugin.HookContext) string {
	if ctx.Request == nil {
		return ""
	}
	for i := len(ctx.Request.Messages) - 1; i >= 0; i-- {
		if ctx.Request.Messages[i].Role == "user" {
			return ctx.Request.Messages[i].Content
		}
	}
	return ""
}

// 基于入参请求克隆一份、替换末条用户内容，作为改写后的入站请求返回。
func cloneRequestWithLastUser(ctx *plugin.HookContext, content string) *plugin.Request {
	src := ctx.Request
	msgs := make([]plugin.Message, len(src.Messages))
	copy(msgs, src.Messages)
	for i := len(msgs) - 1; i >= 0; i-- {
		if msgs[i].Role == "user" {
			msgs[i].Content = content
			break
		}
	}
	return &plugin.Request{Model: src.Model, Messages: msgs, Stream: src.Stream}
}

go build -buildmode=plugin -o access-guard.so .

PLUGIN := access-guard.so

.PHONY: build clean
build:
	go build -buildmode=plugin -o $(PLUGIN) .

clean:
	rm -f $(PLUGIN)

curl https://<平台入口地址>/api/v1/pipeline/extensions \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "name": "access-guard",
    "artifact_ref": "<access-guard.so 的加载位置@版本标识>",
    "node_id": "<挂载的安全护栏节点>",
    "hook_type": "pre",
    "placement": "pre",
    "order": 10,
    "enabled": true,
    "config": {
      "block_keywords": ["<拦截关键词1>", "<拦截关键词2>"],
      "redact_keywords": ["<待剥离片段1>"]
    },
    "fail_policy": "fail_closed"
  }'