中国象棋游戏

简介

这是一个功能完整的中国象棋（Xiangqi）游戏，使用原生 HTML、CSS 和 JavaScript 实现。游戏具有真实的木质棋子音效、分类棋谱演示功能、棋谱爬虫集成和响应式设计。项目分为游戏核心、爬虫功能和测试开发三个模块，架构清晰，易于扩展。

功能特性

🎮 游戏功能

1. 完整象棋规则实现 - 包括所有棋子的移动规则和特殊约束
2. 精美界面设计 - 仿木质棋盘和棋子设计，视觉效果逼真
3. 真实音效 - 程序生成的木质棋子音效，提升游戏体验
4. 棋谱分类展示 - 爬取的棋谱按开局类型自动分类，直接显示分类界面
5. 响应式布局 - 适配不同屏幕尺寸，支持移动设备
6. 音效控制 - 可调节的背景音乐和音效独立控制

🕷️ 爬虫功能

1. 在线棋谱爬取 - 从 xqipu.com 网站自动爬取最新棋谱
2. 数据格式转换 - 自动转换为游戏可用的 JSON 格式
3. 无缝集成 - 爬取的棋谱可直接在游戏中演示
4. 批量处理 - 支持批量下载和处理多个棋谱

🧪 开发支持

1. 完整测试套件 - 覆盖所有游戏功能的自动化测试
2. 模块化架构 - 清晰的目录结构，便于维护和扩展
3. 跨平台兼容 - 支持主流浏览器的功能测试

项目结构

xiangqi/
├── 📖 README.md              # 项目说明（本文件）
├── 📖 CLAUDE.md              # 开发指导文档
│
├── 🎮 main/                 # 核心游戏模块
│   ├── index.html          # 游戏主页面
│   ├── chess.js            # 游戏主逻辑 (69KB)
│   ├── style.css           # 样式文件 (16KB)
│   ├── audio-manager.js    # 音频管理器 (13KB)
│   ├── classic_openings.json # 传统开局数据 (8KB - 兼容保留)
│   └── data/               # 游戏数据目录
│       ├── qipu-games/    # 爬取的棋谱文件
│       └── database/      # 包含分类棋谱数据的数据库文件
│
├── 🕷️ scraper/             # 爬虫功能模块
│   ├── complete-scraper.js # 完整爬虫 (32KB)
│   └── SCRAPER_README.md   # 爬虫使用文档
│
└── 🧪 test/                # 测试开发模块
    ├── package.json        # 项目配置
    ├── jest.config.js      # Jest配置
    ├── jest.setup.js       # 测试环境设置
    ├── mock-browser-env.js # 浏览器环境模拟
    └── tests/              # 具体测试文件

快速开始

🎮 运行游戏

方法1：直接在浏览器中打开

1. 进入 main/ 目录
2. 双击 index.html 文件直接运行

方法2：使用本地服务器

如果跨域限制，推荐使用本地服务器：

# 使用 Python
python -m http.server 8000 --directory main

# 或使用 Node.js (需要安装 http-server)
npm install -g http-server
http-server main/

# 然后在浏览器中访问 http://localhost:8000

🕷️ 运行爬虫

# 进入爬虫目录
cd scraper

# 运行棋谱爬虫
node complete-scraper.js

# 爬取的棋谱将自动保存到 main/data/qipu-games/ 目录

🧪 运行测试

# 进入测试目录
cd test

# 安装依赖（首次运行）
npm install

# 运行所有测试
npm test

# 监听模式运行测试（开发时推荐）
npm run test:watch

# 生成测试覆盖率报告
npm run test:coverage

游戏操作指南

1. 开始游戏 - 点击棋子选择，然后点击目标位置移动
2. 新游戏 - 点击"新游戏"按钮重置棋局
3. 悔棋 - 点击"悔棋"按钮撤销上一步
4. 全局棋谱 - 点击"全局棋谱"按钮直接显示分类的爬取棋谱，按开局类型自动分类
5. 棋谱演示 - 选择分类棋谱后，可播放、暂停、控制速度，自动进入演示模式
6. 音效控制 - 点击"音效"按钮开关音效，使用滑块调节音量

技术实现

前端技术栈

• HTML5 - 语义化标签，游戏结构
• CSS3 - Flexbox + Grid 布局，动画效果
• JavaScript (ES6+) - 面向对象编程，模块化设计
• Web Audio API - 程序化音频生成
• Canvas/SVG - 棋盘和棋子的精确渲染

架构特点

• 模块化设计 - 游戏核心、爬虫功能、测试体系分离
• 事件驱动 - 响应式的用户交互
• 状态管理 - 完整的游戏状态跟踪和管理
• 测试覆盖 - 单元测试、集成测试、UI测试

游戏规则细节

棋子移动规则

• 将/帅：九宫格内移动一格，不能出宫
• 士/仕：九宫格内斜线移动一格，不能出宫
• 象/相：田字移动，不能过河，蹩象腿检查
• 马：日字移动，蹩马腿检查
• 车：直线移动，不限格数
• 炮：直线移动，吃子需隔一子
• 兵/卒：向前移动一格，过河后可左右移动

特殊规则

1. 将帅照面：双方将帅不能直接对面
2. 将军应将：被将军时必须应将
3. 困毙：无子可动时判负
4. 长将：禁止连续将军扰局

开发指南

目录说明

• main/ - 游戏核心代码，修改游戏功能主要在这里
• scraper/ - 爬虫相关代码，扩展爬虫功能在此修改
• test/ - 测试相关代码，添加测试用例和维护测试配置

常见开发任务

添加新游戏功能

1. 修改 main/chess.js 添加游戏逻辑
2. 更新 main/style.css 调整样式
3. 修改 main/index.html 如需要新增UI元素

扩展爬虫功能

1. 在 scraper/complete-scraper.js 基础上开发
2. 更新 scraper/SCRAPER_README.md 说明新功能
3. 确保数据格式与游戏兼容

编写测试用例

1. 在 test/tests/ 目录下添加 .test.js 文件
2. 遵循现有测试模式和命名规范
3. 运行 cd test && npm test 确保测试通过

数据管理

• 棋谱数据：存储在 main/data/qipu-games/ 目录
• 数据库文件：存储在 main/data/database/ 目录
• 分类棋谱：按开局类型分类的棋谱数据 main/data/database/classified-games.json
• 传统开局：兼容保留数据 main/classic_openings.json

棋谱系统说明

分类棋谱展示

游戏现在采用智能分类系统，将棋谱按开局类型自动分组：

• 中炮对屏风马系列 - 经典开局体系
• 中炮对顺炮系列 - 对攻型开局
• 飞相系列 - 布局稳健型开局
• 仙人指路系列 - 挺兵开局变化

示例棋谱数据

当爬取棋谱数据不可用时，系统会自动加载示例数据保持功能可用：

• 中炮对屏风马实战对局
• 飞相对右中炮对抗
• 仙人指路对兵局实例

浏览器兼容性

• Chrome 60+ - 完全支持
• Firefox 55+ - 完全支持
• Safari 12+ - 完全支持
• Edge 79+ - 完全支持
• 移动端 - iOS Safari, Chrome Mobile 基本支持

常见问题

Q: 游戏无法运行？

A: 确保直接双击 main/index.html 或使用本地服务器访问。

Q: 音效没有声音？

A: 检查浏览器音量设置，点击音效按钮确保开启。

Q: 爬虫运行失败？

A: 检查网络连接，查看爬虫目录的详细错误信息。

Q: 测试运行失败？

A: 先运行 cd test && npm install 安装依赖。

贡献指南

欢迎提交 Issue 和 Pull Request！

1. 功能开发：请在对应模块目录下进行开发
2. 测试要求：确保所有测试通过，新功能添加对应测试
3. 代码规范：遵循现有代码风格，添加必要的中文注释
4. 文档更新：重大变更请同步更新相关文档

许可证

MIT License

联系方式

如遇到任何问题，请：

1. 查看详细的开发文档 CLAUDE.md
2. 提交 GitHub Issue
3. 联系开发者

---

提示：这是一个独立应用程序，无构建步骤。修改代码后直接刷新浏览器即可看到效果。