host

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Jun 11, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Package host 提供 AnyBot 面向最终用户的运行框架层。

本包负责读取机器人工作目录配置,管理基于 PluginID 的插件安装锁, 同步 config/<PluginID>.yaml,渲染生成宿主,并按框架拥有的持久化边界 装配 core.App。

普通插件模块应依赖 github.com/tty00a381/anybot/sdk。本包主要供 anybot CLI、 生成宿主和明确拥有机器人工作目录的高级嵌入代码使用。

Index

Constants

View Source
const (
	// ConfigDirName 是机器人工作目录下的配置目录。
	ConfigDirName = "config"
	// ConfigFileName 是 AnyBot 框架配置文件名。
	ConfigFileName = "anybot.yaml"
	// DefaultConfigPath 是工作目录内默认框架配置路径。
	DefaultConfigPath = ConfigDirName + "/" + ConfigFileName
	// PluginLockFile 是 AnyBot 插件安装锁文件。
	PluginLockFile = "plugins.lock"
)

Variables

This section is empty.

Functions

func BuiltinDefaultEnabled

func BuiltinDefaultEnabled(source string) bool

BuiltinDefaultEnabled 返回内置插件在新工作目录中的默认启用状态。

func BuiltinFactory

func BuiltinFactory(source string) (absdk.Factory, bool)

BuiltinFactory 返回指定内置插件来源的工厂。

func CheckGeneratedHostWritable

func CheckGeneratedHostWritable(dir string, force bool) error

CheckGeneratedHostWritable 检查 anybot 生成文件是否可安全写入。

func ConfigPath

func ConfigPath(dir string) string

ConfigPath 返回机器人工作目录中的默认框架配置路径。

func EmptyRegistry

func EmptyRegistry() absdk.Registry

EmptyRegistry 返回不包含任何已构建外部插件的注册表。

func EnabledPlugins

func EnabledPlugins(cfg Config, registry absdk.Registry) ([]string, error)

EnabledPlugins 返回按插件 ID 排序的已启用插件 ID。

func EnabledPluginsWithLock

func EnabledPluginsWithLock(cfg Config, registry absdk.Registry, lock PluginLock) ([]string, error)

EnabledPluginsWithLock 返回按插件 ID 排序的已启用插件 ID。

func EnsurePluginConfigEntry

func EnsurePluginConfigEntry(path, id string) (bool, error)

EnsurePluginConfigEntry 确保 config/<id>.yaml 占位项存在。

func InstallPlugins

func InstallPlugins(app *core.App, cfg Config, registry absdk.Registry, lock PluginLock, env absdk.Environment) error

InstallPlugins 按配置启用插件。

func NewApp

func NewApp(cfg Config, registry absdk.Registry, logger *slog.Logger, appOptions ...AppOption) (*core.App, error)

NewApp 根据框架配置和插件注册表创建 AnyBot 运行时。

func NewLogger

func NewLogger(level, format string, out io.Writer) (*slog.Logger, error)

NewLogger 创建 anybot 使用的结构化日志器。

func NewPluginID

func NewPluginID() (string, error)

NewPluginID 生成一个新的本地 PluginID。

func NewUnknownBuiltinError

func NewUnknownBuiltinError(source string) error

NewUnknownBuiltinError 创建未知内置插件来源错误。

func ParsePluginConfigPath

func ParsePluginConfigPath(input string) ([]string, error)

ParsePluginConfigPath 解析插件 config 下的点分路径。

func ParsePluginModuleSpec

func ParsePluginModuleSpec(spec string) (module string, version string, err error)

ParsePluginModuleSpec 解析 module 或 module@version 形式的插件来源。

func PluginConfigCheckFailed

func PluginConfigCheckFailed(checks []PluginConfigCheck) bool

PluginConfigCheckFailed 判断检查结果里是否存在会阻止运行的插件配置问题。

func PluginConfigDir

func PluginConfigDir(configPath string) string

PluginConfigDir 返回插件实例配置目录。

func PluginLockPath

func PluginLockPath(dir string) string

PluginLockPath 返回机器人工作目录中的插件锁路径。

func RegistryForLock

func RegistryForLock(lock PluginLock, external absdk.Registry) (absdk.Registry, error)

RegistryForLock 根据插件安装锁和已构建的外部插件注册表创建运行时注册表。

func RemovePluginConfigEntry

func RemovePluginConfigEntry(path, id string) (bool, error)

RemovePluginConfigEntry 删除 config/<id>.yaml。

func RemovePluginConfigValues

func RemovePluginConfigValues(path, id string, paths [][]string) (bool, error)

RemovePluginConfigValues 删除 config/<id>.yaml 里的 config 字段覆盖。

func RemovePluginInstall

func RemovePluginInstall(opts RemovePluginInstallOptions) (PluginInstall, PluginLock, error)

RemovePluginInstall 从插件锁移除插件记录并重写生成宿主。

func RenderPluginHost

func RenderPluginHost(dir string, lock PluginLock) error

RenderPluginHost 重写生成宿主插件注册代码,并在缺失时创建最小生成宿主。

func ResolvePluginID

func ResolvePluginID(cfg Config, registry absdk.Registry, lock PluginLock, target string, allowConfigured bool) (string, error)

ResolvePluginID 把用户输入解析为插件 ID;支持完整 ID 或唯一前缀。

func RunPluginCommand

func RunPluginCommand(opts PluginCommandOptions) error

RunPluginCommand 执行生成运行框架内置的 plugin 子命令。

func SavePluginLock

func SavePluginLock(path string, lock PluginLock) error

SavePluginLock 写入插件安装锁。

func SetPluginConfigValues

func SetPluginConfigValues(path, id string, assignments []PluginConfigAssignment) (bool, error)

SetPluginConfigValues 写入 config/<id>.yaml 中的 config 字段。

func SetPluginEnabled

func SetPluginEnabled(path, id string, enabled bool) (bool, error)

SetPluginEnabled 设置 config/<id>.yaml 中的 enabled。

func ShortPluginID

func ShortPluginID(id string) string

ShortPluginID 返回适合命令行首列展示的插件 ID。

func SyncPluginConfigEntries

func SyncPluginConfigEntries(path string, registry absdk.Registry) (int, error)

SyncPluginConfigEntries 把 registry 中的插件默认配置同步到插件配置文件。

func UpdatePluginInstall

func UpdatePluginInstall(opts UpdatePluginInstallOptions) (PluginInstall, PluginLock, bool, error)

UpdatePluginInstall 就地更新外部插件元数据并重写生成文件。

func ValidateConfig

func ValidateConfig(cfg Config, registry absdk.Registry) error

ValidateConfig 静态校验框架配置,不执行插件安装逻辑。

func ValidateConfigWithLock

func ValidateConfigWithLock(cfg Config, registry absdk.Registry, lock PluginLock) error

ValidateConfigWithLock 静态校验框架配置,并按插件安装锁解析可加载插件。

func ValidatePluginID

func ValidatePluginID(id string) error

ValidatePluginID 校验插件 ID 能安全用于锁文件、配置文件、状态前缀和数据目录。

func ValidatePluginInstall

func ValidatePluginInstall(item PluginInstall) error

ValidatePluginInstall 校验单个插件记录。

func ValidatePluginInstallSource

func ValidatePluginInstallSource(item PluginInstall) error

ValidatePluginInstallSource 校验单个插件记录。

func ValidatePluginLock

func ValidatePluginLock(lock PluginLock) error

ValidatePluginLock 校验插件安装锁是否可生成稳定 Go 代码。

func WorkDirForConfig

func WorkDirForConfig(configPath string) string

WorkDirForConfig 返回配置文件所属的机器人工作目录。

func WritePluginConfigCheckTable

func WritePluginConfigCheckTable(w io.Writer, checks []PluginConfigCheck) error

WritePluginConfigCheckTable 输出稳定的插件配置检查表。

func WritePluginConfigSyncSummary

func WritePluginConfigSyncSummary(w io.Writer, result PluginConfigSyncResult) error

WritePluginConfigSyncSummary 输出插件配置同步结果摘要。

func WritePluginInspect

func WritePluginInspect(w io.Writer, inspect PluginInspect) error

WritePluginInspect 输出单个插件的配置与默认值,便于最终用户直接编辑。

func WritePluginStatusTable

func WritePluginStatusTable(w io.Writer, statuses []PluginStatus) error

WritePluginStatusTable 以稳定的表格格式输出插件状态。

Types

type AdapterConfig

type AdapterConfig struct {
	Protocol  string                   `yaml:"protocol"`
	Transport onebot11.TransportConfig `yaml:"transport"`
}

AdapterConfig 描述框架使用的协议适配器。

type AddPluginInstallOptions

type AddPluginInstallOptions struct {
	Dir     string
	ID      string
	Builtin string
	Module  string
	Version string
	Replace string
}

AddPluginInstallOptions 描述 anybot plugin add 的插件锁更新参数。

type AppOption

type AppOption func(*AppOptions)

AppOption 调整框架运行时装配。

func WithConfigPath

func WithConfigPath(path string) AppOption

WithConfigPath 注入当前框架配置文件路径,供插件运行期写回自身配置。

func WithPluginConfigWriteback

func WithPluginConfigWriteback() AppOption

WithPluginConfigWriteback 授予插件运行期写回自身部署配置的能力。 普通外部插件默认不应得到该能力;运行期状态应优先使用 State、Session 或 DataDir。

func WithPluginLock

func WithPluginLock(lock PluginLock) AppOption

WithPluginLock 注入当前工作目录的插件安装锁。

func WithRuntimeState

func WithRuntimeState() AppOption

WithRuntimeState 启用框架托管的运行时状态资源,包括 Store 和插件数据目录。

type AppOptions

type AppOptions struct {
	ConfigPath            string
	RuntimeState          bool
	PluginConfigWriteback bool
	PluginLock            PluginLock
	HasPluginLock         bool
}

AppOptions 描述框架运行时的附加参数。

type BuiltinPlugin

type BuiltinPlugin struct {
	Source         string
	Factory        absdk.Factory
	DefaultEnabled bool
}

BuiltinPlugin 描述 AnyBot 随框架发布的一种内置插件来源。

func BuiltinPlugins

func BuiltinPlugins() []BuiltinPlugin

BuiltinPlugins 返回 AnyBot 随框架发布的内置插件来源。

type Config

type Config struct {
	Runtime  RuntimeConfig          `yaml:"runtime"`
	Adapter  AdapterConfig          `yaml:"adapter"`
	Security SecurityConfig         `yaml:"security"`
	Plugins  map[string]PluginEntry `yaml:"-"`
	// contains filtered or unexported fields
}

Config 是 anybot 的框架配置。

func LoadConfig

func LoadConfig(path string) (Config, error)

LoadConfig 从 YAML 文件读取 anybot 配置。

type PluginCommandOptions

type PluginCommandOptions struct {
	Args       []string
	Output     io.Writer
	ConfigPath string
	LockPath   string
	Registry   absdk.Registry
}

PluginCommandOptions 描述生成运行框架内置 plugin 子命令的运行参数。

type PluginConfigAssignment

type PluginConfigAssignment struct {
	Path  []string
	Value yaml.Node
}

PluginConfigAssignment 描述一次插件 config 下的字段写入。

func ParsePluginConfigAssignment

func ParsePluginConfigAssignment(input string) (PluginConfigAssignment, error)

ParsePluginConfigAssignment 解析 key=value 形式的插件配置写入项。value 使用 YAML 语义解析。

type PluginConfigChange

type PluginConfigChange struct {
	Assignments []PluginConfigAssignment
	ResetPaths  [][]string
}

PluginConfigChange 描述一次插件配置命令中的写入或重置。

func ParsePluginConfigChanges

func ParsePluginConfigChanges(args []string) (PluginConfigChange, error)

ParsePluginConfigChanges 解析 plugin config 的变更参数。

func (PluginConfigChange) Empty

func (change PluginConfigChange) Empty() bool

Empty 判断配置命令是否没有实际变更。

type PluginConfigChangeResult

type PluginConfigChangeResult struct {
	Reset   bool
	Changed bool
	Count   int
}

PluginConfigChangeResult 描述一次插件配置变更的执行结果。

func ApplyPluginConfigChange

func ApplyPluginConfigChange(path, id string, change PluginConfigChange) (PluginConfigChangeResult, error)

ApplyPluginConfigChange 执行一次插件配置写入或重置。

type PluginConfigCheck

type PluginConfigCheck struct {
	ID     string
	Source string
	State  string
	Detail string
}

PluginConfigCheck 是一个插件配置项的静态检查结果。

func PluginConfigChecks

func PluginConfigChecks(cfg Config, registry absdk.Registry, lock PluginLock) []PluginConfigCheck

PluginConfigChecks 校验当前配置中的插件项。禁用插件只报告状态,不要求可加载。

type PluginConfigEntrySyncResult

type PluginConfigEntrySyncResult struct {
	Changed   bool
	Available bool
}

PluginConfigEntrySyncResult 描述单个插件配置同步结果。

func SyncPluginConfigEntry

func SyncPluginConfigEntry(path string, registry absdk.Registry, id string) (PluginConfigEntrySyncResult, error)

SyncPluginConfigEntry 同步单个可加载插件的默认配置。

type PluginConfigSyncResult

type PluginConfigSyncResult struct {
	Changed         int
	Skipped         []string
	UnknownDisabled []string
}

PluginConfigSyncResult 描述插件配置同步结果。

func SyncPluginConfigEntriesForLock

func SyncPluginConfigEntriesForLock(path string, registry absdk.Registry, lock PluginLock) (PluginConfigSyncResult, error)

SyncPluginConfigEntriesForLock 同步插件配置,并允许插件锁中的外部插件等待生成宿主补全默认配置。

type PluginEntry

type PluginEntry struct {
	Enabled *bool     `yaml:"enabled"`
	Config  yaml.Node `yaml:"config"`
}

PluginEntry 描述一个插件的启用状态和原始配置。

type PluginInspect

type PluginInspect struct {
	Name              string
	ID                string
	Source            string
	Version           string
	Description       string
	Module            string
	Configured        bool
	Enabled           bool
	Available         bool
	ConfigPath        string
	ConfigYAML        string
	DefaultAvailable  bool
	DefaultConfigYAML string
	CheckState        string
	CheckDetail       string
}

PluginInspect 是单个插件面向用户的完整配置视图。

func InspectPlugin

func InspectPlugin(configPath string, registry absdk.Registry, lock PluginLock, id string) (PluginInspect, error)

InspectPlugin 合并注册表、插件安装锁和配置文件,返回单个插件的可读视图。

type PluginInstall

type PluginInstall struct {
	ID      string `yaml:"id"`
	Builtin string `yaml:"builtin,omitempty"`
	Module  string `yaml:"module,omitempty"`
	Version string `yaml:"version,omitempty"`
	Replace string `yaml:"replace,omitempty"`
}

PluginInstall 描述一个插件记录及其来源。ID 是该插件的唯一 PluginID。

type PluginLock

type PluginLock struct {
	Module  string          `yaml:"module"`
	Plugins []PluginInstall `yaml:"plugins"`
}

PluginLock 描述 plugins.lock 中锁定的插件记录。

func AddPluginInstall

func AddPluginInstall(opts AddPluginInstallOptions) (PluginLock, error)

AddPluginInstall 把插件记录写入插件锁并重写生成宿主。

func EnsurePluginHost

func EnsurePluginHost(dir string) (PluginLock, error)

EnsurePluginHost 确保目录中存在可构建的插件宿主。

func EnsurePluginHostForce

func EnsurePluginHostForce(dir string, force bool) (PluginLock, error)

EnsurePluginHostForce 确保插件宿主存在;force 允许接管同名非生成文件。

func LoadPluginLock

func LoadPluginLock(path string) (PluginLock, error)

LoadPluginLock 读取插件安装锁;文件不存在时返回空锁。

func NewDefaultPluginLock

func NewDefaultPluginLock() (PluginLock, error)

NewDefaultPluginLock 创建包含首发内置插件记录的新插件锁。

type PluginStatus

type PluginStatus struct {
	ID          string
	Name        string
	Source      string
	Version     string
	Description string
	Module      string
	Configured  bool
	Enabled     bool
	Available   bool
}

PluginStatus 是 anybot 对一个插件的运行视图。

func PluginStatuses

func PluginStatuses(cfg Config, registry absdk.Registry, lock PluginLock) []PluginStatus

PluginStatuses 合并注册表、插件安装锁和配置文件,生成稳定排序的插件状态。

type RemovePluginInstallOptions

type RemovePluginInstallOptions struct {
	Dir string
	ID  string
}

RemovePluginInstallOptions 描述 anybot plugin remove 的插件锁更新参数。

type RuntimeConfig

type RuntimeConfig struct {
	LogLevel  string      `yaml:"log_level"`
	LogFormat string      `yaml:"log_format"`
	Workers   string      `yaml:"workers"`
	Buffer    int         `yaml:"buffer"`
	Serial    string      `yaml:"serial"`
	DataDir   string      `yaml:"data_dir"`
	Store     StoreConfig `yaml:"store"`
}

RuntimeConfig 描述框架运行时参数。

type SecurityConfig

type SecurityConfig struct {
	SuperUsers []string `yaml:"superusers"`
}

SecurityConfig 描述框架级安全策略。

type StoreConfig

type StoreConfig struct {
	Type string `yaml:"type"`
	Path string `yaml:"path"`
}

StoreConfig 描述框架会话状态存储。

type UnknownBuiltinError

type UnknownBuiltinError struct {
	Source string
}

UnknownBuiltinError 表示插件锁引用了当前框架不存在的内置插件来源。

func (UnknownBuiltinError) Error

func (err UnknownBuiltinError) Error() string

type UnknownPluginError

type UnknownPluginError struct {
	ID string
}

UnknownPluginError 表示配置启用了当前注册表不可加载的插件。

func (UnknownPluginError) Error

func (err UnknownPluginError) Error() string

type UpdatePluginInstallOptions

type UpdatePluginInstallOptions struct {
	Dir          string
	ID           string
	Version      string
	Replace      string
	SetVersion   bool
	SetReplace   bool
	ClearReplace bool
}

UpdatePluginInstallOptions 描述 anybot plugin update 的插件锁更新参数。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL