api

Documentation

Overview

Package api 提供 Remilia 框架的 RESTful 管理 API。

架构概述：

api.Server 封装了 HTTP 服务器和路由注册，对外暴露一组 /api/v1/* 端点。
所有端点（除 /health 和 /version）均通过 Bearer Token 认证。
统一响应格式为 { code, message, data }。

端点分类：

• Bot 管理：/api/v1/bots/*（列表、详情、启停）
• 插件管理：/api/v1/plugins/*（列表、详情、启用/禁用/重载）
• 配置：/api/v1/config（当前配置快照，只读）
• 系统：/api/v1/health, /version, /stats

使用方式：

deps := api.Deps{Bot: bot, PluginMgr: pm, Registry: reg}
srv := api.NewServer(":9002", "api-key", deps)
srv.Start()
defer srv.Stop(ctx)

Index

• func AppendLogEntry(level, msg string)
• func GetBuildInfo() (commit, date string)
• func SetBuildInfo(commit, date string)
• type APIResponse
• type BotInfo
• type Deps
• type LogBuffer
  • func NewLogBuffer(size int) *LogBuffer
  • func (b *LogBuffer) Append(entry LogEntry)
  • func (b *LogBuffer) Recent(n int) []LogEntry
• type LogCaptureWriter
  • func NewLogCaptureWriter() *LogCaptureWriter
  • func (w *LogCaptureWriter) Write(p []byte) (int, error)
• type LogEntry
• type PluginInfo
• type Server
  • func NewServer(addr, apiKey string, deps Deps) *Server
  • func (s *Server) Start()
  • func (s *Server) Stop(ctx context.Context) error
• type VersionInfo

Functions

func AppendLogEntry

func AppendLogEntry(level, msg string)

AppendLogEntry 直接向全局日志缓冲区追加条目（由 main 的 zerolog hook 调用）。

func GetBuildInfo

func GetBuildInfo() (commit, date string)

GetBuildInfo 返回 main 包注入的构建信息（Git commit 与构建时间）。 未经 SetBuildInfo 注入时两个返回值均为空字符串。

func SetBuildInfo

func SetBuildInfo(commit, date string)

SetBuildInfo 由 main 包在初始化时注入构建信息。 commit 和 date 是 -ldflags 传入的编译时变量。

Types

type APIResponse

type APIResponse struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data"`
}

APIResponse 是统一 API 响应结构。 所有端点均返回此格式：

成功：{ "code": 0,    "message": "ok",  "data": {...} }
失败：{ "code": 404,  "message": "...",  "data": null  }

type BotInfo

type BotInfo struct {
	Name        string   `json:"name"`
	Status      string   `json:"status"`              // "running" | "stopped"
	Uptime      string   `json:"uptime"`              // 人类可读的运行时长
	Version     string   `json:"version"`             // 框架版本
	Platforms   []string `json:"platforms,omitempty"` // 已接入的聊天平台列表
	PluginCount int      `json:"plugin_count"`        // 已注册插件数量
}

BotInfo 是 Bot 实例的公开摘要信息，用于列表和详情响应。

type Deps

type Deps struct {
	Bot              *remilia.Bot
	PluginMgr        *plugin.Manager
	Registry         *platform.Registry
	Engine           *engine.Engine
	FSMMgr           *fsm.Manager
	PermissionMgr    *permission.Manager
	ConfigPath       string
	DashboardHandler http.Handler
}

Deps 是 Server 的依赖注入容器。

type LogBuffer

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

LogBuffer 环形日志缓冲区

func NewLogBuffer

func NewLogBuffer(size int) *LogBuffer

func (*LogBuffer) Append

func (b *LogBuffer) Append(entry LogEntry)

func (*LogBuffer) Recent

func (b *LogBuffer) Recent(n int) []LogEntry

type LogCaptureWriter

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

LogCaptureWriter 实现 io.Writer，解析 zerolog JSON 输出并存入环形缓冲区。

func NewLogCaptureWriter

func NewLogCaptureWriter() *LogCaptureWriter

NewLogCaptureWriter 创建一个日志捕获 writer。 使用前调用 logger.SetExtraWriter(w)，然后 logger.Init()。

func (*LogCaptureWriter) Write

func (w *LogCaptureWriter) Write(p []byte) (int, error)

type LogEntry

type LogEntry struct {
	Time    string `json:"time"`
	Level   string `json:"level"`
	Message string `json:"message"`
}

LogEntry 日志条目

type PluginInfo

type PluginInfo struct {
	Name         string   `json:"name"`
	State        string   `json:"state"`                  // Loaded | Disabled | Error 等
	Version      string   `json:"version"`                // 插件版本
	Uptime       string   `json:"uptime"`                 // 运行时长
	Dependencies []string `json:"dependencies,omitempty"` // 依赖的其他插件
	MatcherCount int      `json:"matcher_count"`          // 注册的匹配器数量
	LastError    string   `json:"last_error,omitempty"`   // 最后错误信息
	LoadTime     string   `json:"load_time,omitempty"`    // RFC3339 格式的加载时间
}

PluginInfo 是插件的公开摘要信息，用于列表响应。 详情响应直接使用 plugin.Status，此处仅用于列表场景的轻量结构。

type Server

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

Server 封装了管理 API 的 HTTP 服务器。

func NewServer

func NewServer(addr, apiKey string, deps Deps) *Server

NewServer 创建并初始化管理 API 服务器。

func (*Server) Start

func (s *Server) Start()

Start 在后台 goroutine 中启动 HTTP 服务器。

func (*Server) Stop

func (s *Server) Stop(ctx context.Context) error

Stop 优雅关闭 HTTP 服务器。

type VersionInfo

type VersionInfo struct {
	Version   string `json:"version"`
	Commit    string `json:"commit,omitempty"`     // Git commit SHA
	BuildDate string `json:"build_date,omitempty"` // 构建时间
	GoVersion string `json:"go_version"`           // Go 运行时版本
}

VersionInfo 是版本信息响应。