plugin

package
v1.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 4, 2026 License: AGPL-3.0 Imports: 29 Imported by: 0

Documentation

Overview

authoring.go — 用户自建 Lua 插件：落盘 data/plugins/local/<name>/，仅 main.lua 可在线编辑。

host.go — 核心侧 ClawHost 服务：插件经 broker 反调的统一入口。

install.go — .cphplugin 包的安装与卸载。 包格式（zip）：manifest.json + plugin-<os>-<arch>[.exe] 二进制（可多平台）。

luahost.go — lua 插件的共享 luahost 管理（P1）：一份 luahost 二进制置于 data/hosts/， 各 lua 插件进程以 `--dir <插件目录>` 启动，避免逐插件拷贝；也是 P0（升级刷新）的落点。

Package plugin — 插件管理器：子进程生命周期、gRPC 握手、目录扫描。 采用 hashicorp/go-plugin：插件是独立二进制，经 stdout 握手 + gRPC on localhost 通信。

Package plugin — 平台与进程辅助（manager.go 依赖，拆分以保持单文件聚焦）。

Index

Constants

View Source 
const (
	PhaseStopping   = "stopping"   // 升级：停旧进程
	PhaseInstalling = "installing" // 解压落盘
	PhaseStarting   = "starting"   // 启动子进程 + 握手
)

Install 阶段（InstallZip 的进度回调值）。

View Source 
const LocalNamespace = "local"

LocalNamespace 自建插件命名空间目录名（<dir>/local/<name>/）。

Variables

View Source 
var CoreVersion = version.Core

CoreVersion 核心版本（握手时告知插件，供 min_core_version 校验）。

Functions

func ManifestMultiInstance added in v1.1.3 

func ManifestMultiInstance(m *pb.Manifest, protocol int32) bool

ManifestMultiInstance 按 manifest + 契约版本判定多实例能力（停止的插件用 DB 快照判定时复用）。

func ParseLuaIdentity added in v1.3.0 

func ParseLuaIdentity(content string) (name, label string)

ParseLuaIdentity 提取 main.lua 顶部的 PLUGIN_NAME / PLUGIN_LABEL_ZH 声明（保存时回显表单）。

Types

type ClawPluginPlugin 

type ClawPluginPlugin struct {
	goplugin.Plugin
	// contains filtered or unexported fields
}

ClawPluginPlugin 实现 goplugin.Plugin，把 gRPC 服务暴露给 go-plugin 框架。

func (*ClawPluginPlugin) GRPCClient 

func (p *ClawPluginPlugin) GRPCClient(ctx context.Context, broker *goplugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

GRPCClient 核心侧拿到插件客户端桩，同时挂出宿主回调服务。

func (*ClawPluginPlugin) GRPCServer 

func (p *ClawPluginPlugin) GRPCServer(broker *goplugin.GRPCBroker, s *grpc.Server) error

GRPCServer 核心进程不作为插件运行，此路不走。

type HostService 

type HostService struct {
	pb.UnimplementedClawHostServer
	// contains filtered or unexported fields
}

HostService ClawHost gRPC 实现。每个插件实例经 forPlugin 派生独立视图，store 按插件名隔离并持久化到 DB。

func NewHostService 

func NewHostService(db *gorm.DB) *HostService

func (*HostService) GetProxy 

func (h *HostService) GetProxy(ctx context.Context, r *pb.GetProxyRequest) (*pb.ProxyConfig, error)

GetProxy 取出站代理：account_id 非空时账号级绑定优先，再回退 group_id 的分组绑定。

func (*HostService) GetSettings 

func (h *HostService) GetSettings(ctx context.Context, r *pb.GetSettingsRequest) (*pb.GetSettingsResponse, error)

GetSettings 读插件设置（管理界面在线修改，保存即生效）。 instance_id>0 时返回合并视图：插件设置 ← 实例设置 ← {"base_url": 实例地址, "instance_name": 实例名}（后者覆盖前者）。 另注入保留键 sdk.SettingBrowserUserAgent（全局浏览器 UA，非空才给）。

func (*HostService) Log 

func (h *HostService) Log(ctx context.Context, e *pb.LogEntry) (*pb.Empty, error)

func (*HostService) ServeHost 

func (h *HostService) ServeHost(broker interface {
	AcceptAndServe(id uint32, f func([]grpc.ServerOption) *grpc.Server)
})

ServeHost 在 broker 上挂出宿主服务（由 ClawPluginPlugin.GRPCClient 调用）。

func (*HostService) StoreGet 

func (h *HostService) StoreGet(ctx context.Context, r *pb.StoreGetRequest) (*pb.StoreGetResponse, error)

func (*HostService) StorePut 

func (h *HostService) StorePut(ctx context.Context, r *pb.StorePutRequest) (*pb.Empty, error)

type Instance 

type Instance struct {
	Name     string
	Manifest *pb.Manifest
	Protocol int32 // 协商到的契约版本（旧插件为 1：无实例维度，字段被忽略）
	// contains filtered or unexported fields
}

Instance 一个运行中的插件子进程。

func (*Instance) Client 

func (i *Instance) Client() pb.ClawPluginClient

Client 返回插件的 gRPC 客户端。

func (*Instance) MultiInstance added in v1.1.0 

func (i *Instance) MultiInstance() bool

MultiInstance 插件是否支持多实例：契约 ≥2 且声明 instances 能力；否则只有默认实例。

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager 持有全部已启动的插件实例。

func NewManager 

func NewManager(dir string, db *gorm.DB) *Manager

NewManager 创建插件管理器。

func (*Manager) AutoStarts added in v1.1.3 

func (m *Manager) AutoStarts() ([]string, error)

AutoStarts 开机自动启动的插件目录列表：Scan 结果排除持久化停止的插件（enabled=0）。 DB 不可用 / 插件无记录（新装的）照常拉起。

func (*Manager) Chat 

func (m *Manager) Chat(ctx context.Context, req *pb.ChatRequest, pluginName string, cred *pb.CredentialBlob) (<-chan *pb.StreamEvent, error)

Chat 实现 gateway.PluginRegistry：按插件路由并泵出事件流。 ctx 取消后事件泵退出，消费者无需 drain。pluginName 为空时按模型目录解析。

func (*Manager) Configure added in v1.5.2 

func (m *Manager) Configure(settings *setting.Store, decrypt func([]byte) ([]byte, error))

Configure 在启动插件前注入共享设置与凭据解密能力。

func (*Manager) CreateLocalPlugin added in v1.3.0 

func (m *Manager) CreateLocalPlugin(ctx context.Context, name, label, lua string, icon []byte) (string, error)

CreateLocalPlugin 新建自建插件：校验 → 落盘（manifest 脚手架 + 用户 main.lua + 可选 icon）→ ensureLuahost → 启动。同名拒绝。lua 为空时用内置脚手架。

func (*Manager) Endpoints 

func (m *Manager) Endpoints(name string) []string

Endpoints 插件声明的对外端点方言（空 = 全支持）。

func (*Manager) Get 

func (m *Manager) Get(name string) (*Instance, bool)

Get 按名称取运行中的插件实例；进程已崩溃时自动重启。

func (*Manager) IconFile 

func (m *Manager) IconFile(name string) (string, bool)

IconFile 插件图标文件路径：以落盘 manifest.json 的 icon 声明为准（文件存在才返回）。

func (*Manager) InstallZip 

func (m *Manager) InstallZip(ctx context.Context, zipPath, namespace string, onPhase func(string)) (string, error)

InstallZip 安装一个 .cphplugin 包：校验 → 解压到插件目录 → 启动。 namespace 为来源命名空间（官方源/手动上传为空 → <dir>/<name>；其他源 → <dir>/<namespace>/<name>）。 返回插件名。同名同命名空间时覆盖安装（升级）；同名插件已装在其他命名空间时拒绝。 onPhase 非 nil 时在各阶段开始前回调（前端进度展示）。

func (*Manager) Installed added in v1.1.3 

func (m *Manager) Installed() []PackageManifest

Installed 磁盘上已安装的全部插件（含未运行的），按落盘 manifest.json 读取；管理页据此列出可启动项。

func (*Manager) IsLocalPlugin added in v1.3.0 

func (m *Manager) IsLocalPlugin(name string) bool

IsLocalPlugin 插件是否用户自建（落盘在 local 命名空间下）。

func (*Manager) Models 

func (m *Manager) Models() map[string]string

Models 返回聚合模型目录。

func (*Manager) Names 

func (m *Manager) Names() []string

Names 运行中的插件名列表。

func (*Manager) ReadLocalSource added in v1.3.0 

func (m *Manager) ReadLocalSource(name, file string) (string, error)

ReadLocalSource 读自建插件源码（仅 main.lua；manifest 由核心建档生成，不开放编辑）。

func (*Manager) RefreshCatalog 

func (m *Manager) RefreshCatalog(ctx context.Context)

RefreshCatalog 从各插件拉取模型目录（无需凭据的部分）。

func (*Manager) ReplaceLuahost added in v1.2.0 

func (m *Manager) ReplaceLuahost(data []byte) error

ReplaceLuahost 手动替换共享 luahost：先停在跑的 lua 插件（释放文件锁），覆盖二进制并打 .manual 标记 （此后不被内置字节自动刷新），再拉起原先在跑的插件以启用新二进制。

func (*Manager) ResolveModel 

func (m *Manager) ResolveModel(model string) (string, bool)

ResolveModel 模型名 → 插件名（gateway.PluginRegistry 实现）。

func (*Manager) Resume added in v1.1.3 

func (m *Manager) Resume(name string)

Resume 清除持久化停止状态（enabled=1，下次重启核心照常拉起）。

func (*Manager) ScaffoldLua added in v1.3.0 

func (m *Manager) ScaffoldLua(label string) string

ScaffoldLua 渲染脚手架 main.lua（真实插件名由 PLUGIN_NAME 行在保存时回显）。

func (*Manager) ScaffoldManifestFile added in v1.3.0 

func (m *Manager) ScaffoldManifestFile(name, label string) string

ScaffoldManifestFile 按插件名/品牌名渲染 manifest 内容。

func (*Manager) Scan 

func (m *Manager) Scan() ([]string, error)

Scan 扫描插件目录，返回可启动的二进制路径列表（目录不存在视为空）。

func (*Manager) Start 

func (m *Manager) Start(ctx context.Context, dir string) (*Instance, error)

Start 启动一个插件子进程并完成契约握手。 go-plugin 层按 [MinProtocolVersion, ProtocolVersion] 协商版本，旧契约插件按协商到的版本握手（线格式向后兼容）。

func (*Manager) Stop 

func (m *Manager) Stop(name string, persists bool)

Stop 停止一个插件。persists 为 true 时写持久化状态（enabled=0，重启核心保持停止； 用户手动停用）；false 仅停本次进程（升级/卸载前临时停，重启照常拉起）。

func (*Manager) StopAll 

func (m *Manager) StopAll()

StopAll 停止全部插件（进程退出前调用；仅停进程，不写持久化状态）。

func (*Manager) StopLua added in v1.5.2 

func (m *Manager) StopLua()

StopLua 关闭总开关后停止既有 Lua 进程；Start 同样检查开关。

func (*Manager) Uninstall 

func (m *Manager) Uninstall(name string) error

Uninstall 停止并删除一个插件的全部本地文件（根目录或命名空间目录；仅停进程，插件记录随级联删除清库）。

func (*Manager) WriteLocalSource added in v1.3.0 

func (m *Manager) WriteLocalSource(ctx context.Context, name, file, content string) error

WriteLocalSource 写自建插件 main.lua 并重启生效；代码侧 PLUGIN_NAME 须与身份一致（改名拒绝）， PLUGIN_LABEL_ZH/EN 变更自动同步进 manifest.json。

type PackageManifest 

type PackageManifest struct {
	Name            string            `json:"name"`
	Version         string            `json:"version"`
	Author          string            `json:"author"`
	Label           map[string]string `json:"label"` // 品牌名（多语言）
	ProtocolVersion int32             `json:"protocol_version"`
	MinCoreVersion  string            `json:"min_core_version"`
	// Runtime 运行时：空=Go 插件（包内自带二进制）；"lua"=脚本插件（包内只含脚本，
	// 安装时由核心注入内置 luahost 作为 plugin-<os>-<arch>）。
	Runtime string `json:"runtime"`
	// Entry 脚本入口（lua 固定 main.lua）；luahost 读同目录 main.lua，此字段仅声明。
	Entry string `json:"entry"`
	// Icon 插件图标：包内相对路径（如 "icon.png"，建议正方形 PNG 128–256px）。
	// 安装时解出到插件目录，前端经 /assets/plugins/<name>/icon 读取。
	Icon string `json:"icon"`
}

PackageManifest 包内 manifest.json。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.