无名江湖服务端（wumingmud）

无名江湖服务端是一个基于 Go 的 MUD 游戏后端，提供 WebSocket 会话、核心玩法逻辑、持久化与可选 LLM 能力。

提示：可以使用wumingmud-tui客户端进行游戏体验。

技术栈

• Go 1.21+
• SQLite 3 + GORM
• WebSocket
• OpenAI 兼容 LLM 接口（可选）

目录结构

.
├── cmd/                 # 程序入口
├── internal/            # 核心实现（engine/transport/storage/...）
├── config/              # 服务配置
├── world/               # 世界定义与规则配置
├── deploy/              # 生产部署示例（systemd/nginx）
├── scripts/             # 开发/构建脚本
├── data/                # SQLite 数据文件
├── bin/                 # 构建产物
├── go.mod
└── .env.example

环境要求

• Go 1.21+
• SQLite 3（用于备份脚本）

快速开始

cp .env.example .env
go mod tidy
go run cmd/main.go

或使用脚本：

./scripts/setup-env.sh
./scripts/deps.sh
./scripts/run.sh

setup-env.sh 会直接复制 .env.example 为 .env，避免双份配置模板长期漂移。

环境变量

请参考 .env.example，常用项如下：

变量名	默认值	说明
CONFIG_DIR	./config	服务配置目录
WORLD_DIR	./world	世界配置目录
SERVER_PORT	8080	服务监听端口
SERVER_HOST	0.0.0.0	服务监听地址
DATABASE_PATH	data/game.db	SQLite 文件路径
LLM_ENABLED	true	是否开启 LLM 能力
LLM_API_KEY	空	LLM API Key
LLM_BASE_URL	https://api.openai.com/v1	LLM 基地址
LLM_MODEL	gpt-5.2	LLM 模型名称
LLM_TIMEOUT	5	LLM 请求超时（秒，影响指令解析与战斗叙事）
LOG_OUTPUT	logs/server.log	日志输出文件

启动参数

服务支持通过启动参数覆盖路径：

./bin/wumingmud \
  --config-dir /opt/wumingmud/config \
  --world-dir /opt/wumingmud/world \
  --env-file /etc/wumingmud/wumingmud.env

优先级：命令行参数 > 环境变量（CONFIG_DIR/WORLD_DIR/ENV_FILE）> 默认值。

监听与日志行为

• 服务监听地址为 SERVER_HOST:SERVER_PORT（例如 0.0.0.0:8080）
• LOG_OUTPUT=stdout 或 LOG_OUTPUT=-：输出到标准输出
• LOG_OUTPUT=logs/server.log 这类文件路径：自动创建目录并追加写入文件

常用命令

./scripts/run.sh      # 运行服务
./scripts/dev.sh      # 开发模式
./build.sh            # 构建二进制（bin/wumingmud）
./scripts/test.sh     # 测试
./scripts/lint.sh     # 格式化 + 静态检查
./scripts/migrate.sh  # 数据迁移
./scripts/backup.sh   # 备份数据库
./scripts/world-check.sh # 世界配置检查（引用/可达性/任务关联）
./scripts/world-gen.sh   # 使用 LLM 生成世界配置草案

配置说明

• 服务配置：config/server.yaml
• 世界配置：world/config/game.yaml
• .env 会在启动时自动加载（若存在），并覆盖 server.yaml 对应项
• 生产部署模板：deploy/systemd/wumingmud.service、deploy/nginx/wumingmud.conf
• 战斗描述支持 LLM 增强，由 world/config/game.yaml 中 game.llm.scenarios.combat_narrative 控制

LLM 排查

• 启动后先看 server.startup 与 llm.init 日志：
• llm_enabled=true
• llm_has_api_key=true
• llm_base_url、llm_model 是否符合预期
• 指令解析链路看：
• llm.intent.success（命中）
• llm.intent.failed / llm.intent.parse_failed（失败原因）
• 战斗叙事链路看：
• llm.combat.success（命中）
• llm.combat.failed / llm.combat.empty / llm.combat.skipped（降级原因）

世界配置生成与检查

1) 批量生成剧情/NPC/任务

./scripts/world-gen.sh --kind quest --count 5 --theme "金庸武侠，偏江湖恩怨"
./scripts/world-gen.sh --kind location --count 3
./scripts/world-gen.sh --kind npc --count 8 --output world/generated/npcs_batch.yaml

• 生成结果默认写到 world/generated/
• --kind 支持：quest|location|npc|item|faction
• 依赖 LLM_ENABLED=true 与有效 LLM_API_KEY

2) 批量检查配置

./scripts/world-check.sh
./scripts/world-check.sh --strict
./scripts/world-check.sh --world-dir ./world

• 默认校验：位置/NPC 双向引用、任务依赖与奖励引用、安全区一致性、地点可达性
• --strict 会将 warning 也视为失败

试验性生产建议

• 使用 systemd 运行服务，启用自动重启（模板已提供）
• 通过 nginx 反代并保留 WebSocket 升级头（模板已提供，含 HTTPS/WSS）
• 将数据库与日志目录放在独立可写路径（如 /opt/wumingmud/data、/opt/wumingmud/logs）
• 优先把日志输出到 stdout 并交给 journald/systemd 管理
• 使用 http://127.0.0.1:8080/healthz 作为基础健康检查