摸鱼棋乐开发文档

这个项目是什么

摸鱼棋乐（仓库 jinghui/moyu-qile）是象棋 / 五子棋 / 军棋（陆战棋翻棋）三合一的网页棋类游戏，定位"益智 · 摸鱼 · 小憩"：浏览器打开即玩，手机/平板/电脑通用，也可以一条 Docker 命令跑在自己的 NAS 上。游戏本体为纯 Node.js 自研、MIT 开源，无账号无遥测；在此之上叠加了 8 大 AI 扩展功能（AI 教练、走法点评、每日一题、棋风画像、自适应难度、战绩海报、军棋记牌推理、对手嘴炮等），并且模型 Key 只存浏览器、不上传服务器。

技术栈与架构

运行时：Node.js ≥ 20，服务端唯一 npm 依赖为 ws（WebSocket 库，package.json 中包名 fnos-games）；游戏引擎全部是自研纯 JavaScript。
服务端：server.js 单文件——HTTP 静态资源服务 + WebSocket 房间（象棋/五子棋/军棋双人对局）+ REST 接口 /api/{rank,save,config,fs,ai-hint}，HTTP 与 WebSocket 同端口（默认 7025）。
前端：单页应用（app/index.html，hash 路由），三个游戏视图共用工具栏/存档/排行/倒计时/离开守卫/AI 教练等公共组件（app/js/common.js）。
引擎分层：chess.js（象棋规则：蹩马腿、塞象眼、照面等）+ chessAI.js（α-β 搜索）、gomoku.js（15×15 评分 AI + 前瞻堵四）、junqi.js（标准 12×5 棋盘/行营/大本营/铁路规则）。
数据：运行时数据全部落在 data/ 目录（已 gitignore）——存档 *-saves.json、战绩 *-ranks.json、路径配置 config.json。

仓库结构

路径	说明
`server.js`	HTTP 静态服务 + WS 房间 + REST 接口
`app/index.html`	单页应用（三个游戏视图）
`app/about.html`	使用说明页
`app/css/style.css`	样式（含移动端竖屏适配）
`app/js/chess.js` / `chessAI.js`	象棋规则引擎与搜索 AI
`app/js/gomoku.js`	五子棋引擎 + 评分 AI
`app/js/junqi.js`	军棋翻棋引擎
`app/js/*_client.js`	三个游戏的界面逻辑 + 存档钩子（GAMEHOOKS）
`app/js/common.js`	公共 UI：工具栏/存档/排行/倒计时/离开守卫/AI 教练
`data/`	运行时数据（存档、战绩、配置），gitignore
`tests/`	Node 单元测试（无测试框架，直接 `node` 运行）
`fpk/`	飞牛 NAS 应用商店打包工程（moyu-qile.fpk）+ 截图 + FnDepot 分发
`Dockerfile` / `package.json`	容器构建与依赖声明

本地开发环境

# 本地直跑（不用 Docker）
npm install
node server.js        # 端口可用 PORT 环境变量覆盖，默认 7025

# 运行测试（各测试文件独立执行）
node tests/engine.test.js      # 引擎回归
node tests/chess_state.test.js # 象棋局面序列化往返（存档正确性）
node tests/jq_rules.test.js    # 军棋规则（行营/大本营/铁路/山界）
node tests/jq_camp.test.js     # 军棋入营与营内免疫
node tests/jq_shown.test.js    # 军棋翻开状态同步

配置项说明

配置键	位置	含义
`PORT`	环境变量	HTTP/WS 端口，默认 `7025`
`saveDir`	`data/config.json`（可在界面「💾 存档 → ⚙ 存档路径」修改）	存档目录，默认 `<数据卷>/saves`，换目录自动迁移
模型 Base URL / Key / 模型名	浏览器 localStorage（⚙ 模型设置）	AI 教练与扩展功能的 OpenAI 兼容接口配置，不填不影响对局

服务端接口：/api/rank（战绩排行）、/api/save（存档）、/api/config（路径配置）、/api/fs、/api/ai-hint（AI 提示接口）。

构建与发布

# 源码构建镜像
git clone https://gitea.88531.cn/jinghui/moyu-qile.git
cd moyu-qile
docker build -t moyu-qile:latest .

docker run -d --name moyu-qile --restart unless-stopped \
  -p 7025:7025 \
  -v "$PWD/data:/app/data" \
  moyu-qile:latest

公开镜像渠道：gitea.88531.cn/jinghui/moyu-qile:latest 与固定版本 tag（如 :1.0.0），国内直连、匿名可拉（Docker Hub 渠道已下线；ghcr.io/personal82555/moyu-qile 因 GitHub 账号临时暂停暂不可拉）。局域网可用直连地址加速。飞牛 NAS 另有 fpk/moyu-qile/moyu-qile.fpk 安装包（appcenter-cli install-fpk moyu-qile.fpk 离线直装，或经 FnDepot 社区商店安装）。

二次开发要点

数据卷必须挂：存档（*-saves.json）、战绩（*-ranks.json）与路径配置都在 /app/data，不挂卷重建容器即丢数据。
存档钩子：三个游戏的界面逻辑通过 GAMEHOOKS 挂接存档/恢复，新增游戏功能时要保持钩子同步（悔棋、存档、残局切换都依赖它）。
AI 隐私设计：模型 Key 仅存浏览器 localStorage，绝不上传服务器，设置页有明确安心提示；扩展功能均有本地引擎兜底，不填 Key 也全部可用，二开时不要引入必须联网才能用的功能。
军棋规则细节：行营内棋子不可被吃、大本营进入后不可再移动、工兵可沿铁路直行——tests/jq_*.test.js 是这些规则的回归保障，改引擎必跑。
授权系统：v1.1.0 起接入授权系统（auth.88531.cn），提供安装量/在线统计、公告推送、版本角标与新版本红点提示。
发布渠道：CI（GitHub Actions）保留，镜像主通道为自建 GiteA；飞牛打包细节见 fpk/README.md。

摸鱼棋乐 开发文档