# 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                 # 配置模板
```

## 快速开始

### 本地运行

```bash
# 安装依赖
go mod download

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

# 运行
go run .
```

### Docker 运行

```bash
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`：

```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` 中添加导入：

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

### Plugin 接口

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

## 请求格式

```json
POST /

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

## 响应格式

文本回复：

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

图片回复：

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

## License

MIT