command-server/README.md

NcatBot Command Server

基于 Go 的 Bot 命令处理服务器，支持插件化扩展命令。

项目结构

command-server/
├── main.go                      # 入口
├── config/
│   └── config.go                # 配置加载（从 .env）
├── command/
│   ├── types.go                 # 共享类型（Req, Resp, Message）
│   ├── plugin.go                # Plugin 接口定义
│   ├── registry.go              # 命令注册表
│   ├── admin.go                 # 管理员权限检查
│   ├── init.go                  # 内置命令初始化
│   └── builtin.go               # 内置命令（菜单/启用/禁用/时间）
├── plugins/
│   ├── plugins.go               # 统一导入所有插件
│   └── image/
│       └── image.go             # 图片生成插件
├── Dockerfile
├── docker-compose.yml
├── .env                         # 环境变量配置
└── .env.example                 # 配置模板

快速开始

本地运行

# 安装依赖
go mod download

# 复制配置文件并填写
cp .env.example .env

# 运行
go run .

Docker 运行

docker compose up -d --build

docker login gitea.kmux.cn
docker buildx build --platform linux/amd64,linux/arm64 -t gitea.kmux.cn/ncatbot/command-server:0.0.1 --no-cache .
docker push gitea.kmux.cn/ncatbot/command-server:0.0.1

配置说明

复制 .env.example 为 .env，按需修改：

变量	默认值	说明
SERVER_ADDR	127.0.0.1:8000	服务监听地址
OPENAI_API_KEY	-	OpenAI API 密钥
OPENAI_BASE_URL	https://api.openai.com	API 基础地址
OPENAI_MODEL	gpt-image-2	图片生成模型
REQUEST_TIMEOUT	120	请求超时（秒）
IMAGE_COUNT	1	单次生成图片数
IMAGE_OUTPUT_DIR	images	图片本地暂存目录
UPLOAD_URL	-	图片上传接口地址
UPLOAD_API_KEY	-	上传接口 API Key
PROXY	-	HTTP 代理地址
ADMIN_USERS	-	管理员用户ID，逗号分隔

内置命令

命令	说明	权限
菜单	显示所有可用命令	所有人
启用 <命令名>	启用指定命令	管理员
禁用 <命令名>	禁用指定命令	管理员
时间	查询当前时间	所有人

插件命令

命令	说明	权限
生图 <描述>	根据描述生成图片	所有人

添加新插件

1. 创建插件文件

新建 plugins/weather/weather.go：

package weather

import (
    "ncatbot-command-server/command"
)

type Plugin struct{}

func init() {
    command.RegisterPlugin(&Plugin{})
}

func (p *Plugin) Name() string        { return "天气" }
func (p *Plugin) Description() string  { return "查询天气" }
func (p *Plugin) Usage() string        { return "天气 <城市>" }
func (p *Plugin) Run(req *command.Req) command.Resp {
    return command.Resp{Reply: "今天晴天"}
}

2. 注册插件

在 plugins/plugins.go 中添加导入：

import (
    _ "ncatbot-command-server/plugins/image"
    _ "ncatbot-command-server/plugins/weather"  // 新增
)

Plugin 接口

接口	方法	必须实现
Plugin	Name(), Description(), Usage(), Run()	是
PluginWithInit	加 Init()	需要初始化时
PluginAdmin	加 IsAdminOnly()	管理员专用时

请求格式

POST /

{
    "command": "生图",
    "content": "一只猫",
    "raw_message": "生图 一只猫",
    "user_id": "123456",
    "group_id": "789",
    "message_id": "abc"
}

响应格式

文本回复：

{
    "reply": "当前时间是: 2026-05-04 16:00:00"
}

图片回复：

{
    "messages": [
        {
            "type": "image",
            "url": "https://example.com/image.png"
        }
    ]
}

License

MIT