✨ feat(core): 初始化 Bot 命令处理服务器

- 基于 Gin 框架搭建 HTTP 服务，接收并处理 Bot 命令请求 - 实现插件化命令系统，支持通过 Plugin 接口扩展新命令 - 内置菜单、启用/禁用、时间查询等基础命令 - 新增图片生成插件，对接 OpenAI Images API - 支持管理员权限控制、命令动态启禁用 - 提供完整配置管理（.env）与 Docker 部署方案
2026-05-05 13:41:44 +08:00
commit e8c641414e
18 changed files with 1071 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,173 @@
+# 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