builder

Documentation

Overview

Package builder 提供插件本地构建能力。

当云端插件未编译进当前二进制时，可通过本包自动完成： 源码下载 → go.work 更新 → import 文件生成 → 重新编译 → 提示重启。

Index

• func AddToWorkspace(workspaceDir, pluginRelPath string) error
• func DownloadAndExtract(ctx context.Context, archiveURL, destDir string) error
• func GenerateImportFile(targetDir, code, buildTag, goModule string) error
• func GitClone(ctx context.Context, repoURL, destDir string) error
• func RemoveFromWorkspace(workspaceDir, pluginRelPath string) error
• type BuildResult
• type BuildStrategy
• type Builder
• type EnvironmentInfo
  • func DetectEnvironment() EnvironmentInfo
• type LocalBuilder
  • func NewLocalBuilder() *LocalBuilder
  • func (b *LocalBuilder) Build(ctx context.Context, cfg PluginBuildConfig) (*BuildResult, error)
  • func (b *LocalBuilder) CanBuild() bool
• type PluginBuildConfig

Functions

func AddToWorkspace

func AddToWorkspace(workspaceDir, pluginRelPath string) error

AddToWorkspace 向 go.work 文件添加新的 use 条目。

pluginRelPath 是相对于 workspace 根目录的路径（如 "./MRGuild/plugin"）。 如果条目已存在则跳过，不重复添加。

func DownloadAndExtract

func DownloadAndExtract(ctx context.Context, archiveURL, destDir string) error

DownloadAndExtract 从 URL 下载 tar.gz 压缩包并解压到目标目录。

安全防护：

• 解压时对每个条目进行路径清洗，防止 ../ 路径遍历攻击
• 校验解压后的最终路径必须在 destDir 内

func GenerateImportFile

func GenerateImportFile(targetDir, code, buildTag, goModule string) error

GenerateImportFile 在目标目录生成 import_{code}.go 文件（带 build tag 控制）。

生成的文件遵循现有 import_mrguild.go 的格式：

//go:build {buildTag} || all_plugins
package plugin
import _ "{goModule}"

targetDir 为 import 文件的存放目录（通常是 internal/plugin/）。

func GitClone

func GitClone(ctx context.Context, repoURL, destDir string) error

GitClone 从 Git 仓库克隆源码到目标目录。

如果目标目录已存在，会先删除再克隆（确保源码干净）。

func RemoveFromWorkspace

func RemoveFromWorkspace(workspaceDir, pluginRelPath string) error

RemoveFromWorkspace 从 go.work 文件中移除指定 use 条目。

pluginRelPath 是相对于 workspace 根目录的路径。

Types

type BuildResult

type BuildResult struct {
	Success    bool          // 是否构建成功
	BinaryPath string        // 编译产物路径
	BuildLog   string        // 完整构建日志（stdout + stderr）
	Duration   time.Duration // 构建耗时
}

BuildResult 构建执行结果。

type BuildStrategy

type BuildStrategy string

BuildStrategy 构建策略类型。

const (
	// StrategyManual 手动构建，需用户自行下载源码并编译。
	StrategyManual BuildStrategy = "manual"
	// StrategyLocalBuild 本地自动构建，由内核自动下载源码并编译。
	StrategyLocalBuild BuildStrategy = "local_build"
	// StrategyCloudBuild 云端构建（尚未实现），由云端编译后下发二进制。
	StrategyCloudBuild BuildStrategy = "cloud_build"
)

type Builder

type Builder interface {
	// CanBuild 检测当前环境是否具备本地构建条件（Go 工具链可用等）。
	CanBuild() bool
	// Build 执行一次本地构建，包含后端编译和可选的前端构建。
	Build(ctx context.Context, cfg PluginBuildConfig) (*BuildResult, error)
}

Builder 构建器接口，定义本地构建的抽象能力。

type EnvironmentInfo

type EnvironmentInfo struct {
	GoAvailable   bool   `json:"go_available"`   // Go 编译器是否可用
	GoVersion     string `json:"go_version"`     // Go 版本号
	NodeAvailable bool   `json:"node_available"` // Node.js 是否可用
	NodeVersion   string `json:"node_version"`   // Node.js 版本号
	PnpmAvailable bool   `json:"pnpm_available"` // pnpm 是否可用
	PnpmVersion   string `json:"pnpm_version"`   // pnpm 版本号
	NpmAvailable  bool   `json:"npm_available"`  // npm 是否可用
	NpmVersion    string `json:"npm_version"`    // npm 版本号
	GitAvailable  bool   `json:"git_available"`  // Git 是否可用
	GitVersion    string `json:"git_version"`    // Git 版本号
}

EnvironmentInfo 构建环境检测结果，记录各工具链的可用性和版本。

func DetectEnvironment

func DetectEnvironment() EnvironmentInfo

DetectEnvironment 检测当前环境的编译工具链，返回各工具的可用状态与版本。

type LocalBuilder

type LocalBuilder struct{}

LocalBuilder 基于本地 Go 工具链的构建器实现。

func NewLocalBuilder

func NewLocalBuilder() *LocalBuilder

NewLocalBuilder 构造 LocalBuilder。

func (*LocalBuilder) Build

func (b *LocalBuilder) Build(ctx context.Context, cfg PluginBuildConfig) (*BuildResult, error)

Build 执行本地构建：后端 go build + 可选前端 pnpm build。

安全措施：

• 使用 context.WithTimeout 控制超时
• 构建在指定目录内执行，不污染其他目录
• 命令输出完整捕获用于排障

func (*LocalBuilder) CanBuild

func (b *LocalBuilder) CanBuild() bool

CanBuild 检测 go 命令是否可用。

type PluginBuildConfig

type PluginBuildConfig struct {
	PluginCode   string        // 插件 code（如 mrguild）
	SourceDir    string        // 源码目录（已解压/克隆）
	WorkspaceDir string        // Go workspace 根目录（go.work 所在目录）
	KernelDir    string        // 内核 module 目录（go build 的工作目录）
	BuildTag     string        // Go build tag（如 plugin_mrguild）
	GoModule     string        // Go module path（如 cnb.cool/jiangzeyu0531/MRGuild/plugin）
	HasAdminUI   bool          // 是否有前端需要构建
	AdminDir     string        // 前端项目目录（HasAdminUI=true 时有效）
	Timeout      time.Duration // 构建超时时间，默认 600s
}

PluginBuildConfig 单次构建所需的插件参数。