Add plugin 五子棋 3D v1.0.1

plugins/gomoku-3d-ztools/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+src-ztools/dist/
+test-results/
+.DS_Store
+*.log
+*.tsbuildinfo

plugins/gomoku-3d-ztools/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 crper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plugins/gomoku-3d-ztools/NOTICE

@@ -0,0 +1,15 @@
+Gomoku 3D for ZTools
+
+This plugin is a ZTools port and adaptation of:
+  crper/gomoku-3d
+  https://github.com/crper/gomoku-3d
+
+Upstream baseline commit:
+  fa6e266e4e9135aebb80e1487de88a6438380cf7
+
+The upstream project is Copyright (c) 2026 crper and licensed under the MIT License.
+The original LICENSE text is included in this distribution.
+
+ZTools-specific adaptations include plugin manifest and lifecycle integration,
+host-backed persistence, native save-dialog export, packaging, validation and
+Electron end-to-end tests.

plugins/gomoku-3d-ztools/README.md

@@ -0,0 +1,32 @@
+# 五子棋 3D · ZTools 插件
+
+这是 [`crper/gomoku-3d`](https://github.com/crper/gomoku-3d) 的 ZTools 插件移植版，基于上游提交 `fa6e266e4e9135aebb80e1487de88a6438380cf7`。
+
+## 功能
+
+- 15×15 五子棋，2D/3D 双视图
+- 简单、中等、困难、大师四档本地 AI
+- 落子、悬停、获胜与 AI 思考动效
+- 一整回合悔棋
+- 棋局回放与速度调节
+- SGF、JSON、TXT 棋谱导出
+- 战绩、连胜和成就
+- 中英文界面与 Web Audio 合成音效
+- ZTools 宿主存储、进入/退出生命周期和原生保存对话框适配
+
+## 开发
+
+```bash
+npm install
+npm run dev
+npm test
+npm run build
+npm run validate:plugin
+npm run test:e2e
+```
+
+可安装插件目录为 `src-ztools/`，生产页面位于 `src-ztools/dist/`。
+
+## 许可与来源
+
+本项目保留上游 MIT 许可证，详见 `LICENSE` 与 `NOTICE`。上游原始说明保存在 `README.upstream.md` 和 `README.upstream.zh.md`。

plugins/gomoku-3d-ztools/README.upstream.md

@@ -0,0 +1,143 @@
+<div align="center">
+
+# ⚫⚪ Gomoku 3D
+
+**A 3D Gomoku (Five-in-a-Row) game with an AI opponent, replay & game-record export — built with React, Three.js & TypeScript.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![React](https://img.shields.io/badge/React-18-61dafb.svg)](https://react.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6.svg)](https://www.typescriptlang.org/)
+[![Vite](https://img.shields.io/badge/Vite-5-646cff.svg)](https://vitejs.dev/)
+[![Three.js](https://img.shields.io/badge/Three.js-169-black.svg)](https://threejs.org/)
+
+🎮 **Live Demo:** <https://crper.github.io/gomoku-3d/>
+
+[English](./README.md) · [简体中文](./README.zh.md)
+
+</div>
+
+---
+
+## ✨ Features
+
+- **15×15 Gomoku (Five-in-a-Row)** rendered on an interactive 3D board.
+- **AI opponent** with four difficulties — Easy / Medium / Hard / **Master** (a depth-limited alpha-beta negamax search).
+- **Dual view modes** — a locked 2D top-down board for clean play, and a free-orbit 3D view, with a smooth camera tween between them.
+- **Juicy animations** — stone drop-bounce with dust ripple, hover breathing preview, last-move pulse, victory line shimmer & hop, AI-thinking glow. All respect `prefers-reduced-motion`.
+- **Synthesized sound** via the Web Audio API — place / hover / undo / victory / defeat / achievement cues, with a mute toggle. Zero audio asset files.
+- **Game stats & achievements** persisted to `localStorage` (wins/losses/draws, win streaks, speed-win, beat-hard, etc.).
+- **Undo** a full round (your move + the AI's reply).
+- **Replay** any game — step forward/back, jump to any move, play/pause with 0.5×–4× speed, draggable progress bar. A read-only scrubbing mode that leaves the live game untouched.
+- **Game-record export** — save a finished or in-progress game as **SGF** (the de-facto standard for Go/Gomoku/Renju software), **JSON**, or human-readable **TXT**, with a custom filename.
+- **Fully responsive** — desktop sidebar layout and a mobile bottom action bar, no overlap or overflow.
+- **Keyboard shortcuts** and screen-reader-friendly controls (ARIA labels, `aria-live` move info, focus-managed dialogs).
+
+## 🧱 Tech Stack
+
+| Layer | Choice |
+| --- | --- |
+| UI framework | [React 18](https://react.dev/) + [TypeScript 5](https://www.typescriptlang.org/) (strict mode) |
+| Build tool | [Vite 5](https://vitejs.dev/) |
+| 3D rendering | [Three.js](https://threejs.org/) via [`@react-three/fiber`](https://github.com/pmndrs/react-three-fiber) + [`@react-three/drei`](https://github.com/pmndrs/drei) |
+| Styling | [Tailwind CSS](https://tailwindcss.com/) + hand-written shadcn/ui-style components |
+| Audio | Web Audio API (synthesized — no asset files, no audio dependency) |
+| State | React hooks — no external state library |
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Node.js **≥ 18** (developed on 22)
+- npm
+
+### Install & run
+
+```bash
+git clone https://github.com/crper/gomoku-3d.git
+cd gomoku-3d
+npm install
+npm run dev          # http://localhost:5173
+```
+
+### Scripts
+
+| Command | Description |
+| --- | --- |
+| `npm run dev` | Start the Vite dev server |
+| `npm run build` | Type-check (`tsc -b`) + production build to `dist/` |
+| `npm run preview` | Preview the production build locally |
+| `npm run typecheck` | Run `tsc --noEmit` |
+
+## 🧪 Tests
+
+Tests are plain TypeScript under `scripts/` and run with [esbuild](https://esbuild.github.io/) bundling + Node (no test runner dependency):
+
+```bash
+# Engine + AI logic (20 cases)
+./node_modules/.bin/esbuild scripts/engine.test.ts --bundle --platform=node --format=esm --outfile=/tmp/e.mjs && node /tmp/e.mjs
+
+# AI strength matrix
+./node_modules/.bin/esbuild scripts/strength.test.ts --bundle --platform=node --format=esm --outfile=/tmp/s.mjs && node /tmp/s.mjs
+
+# Replay & export (SGF/JSON/TXT) — 37 cases
+./node_modules/.bin/esbuild scripts/replay.test.ts --bundle --platform=node --format=esm --outfile=/tmp/r.mjs && node /tmp/r.mjs
+
+# 50-game self-play simulation (no stalls / illegal moves)
+./node_modules/.bin/esbuild scripts/sim.ts --bundle --platform=node --format=esm --outfile=/tmp/sim.mjs && node /tmp/sim.mjs
+```
+
+## 🎯 How to Play
+
+- Black moves first. Click any intersection to place your stone.
+- Connect **five** of your stones in a row (horizontally, vertically, or diagonally) to win.
+- Use the sidebar (desktop) or bottom bar (mobile) to switch difficulty, swap who plays first, toggle 2D/3D, undo, mute, replay, or export.
+
+### Keyboard shortcuts (during replay)
+
+| Key | Action |
+| --- | --- |
+| `←` / `→` | Previous / next move |
+| `Space` | Play / pause |
+| `Home` / `End` | First / last move |
+| `Esc` | Exit replay |
+
+## 📁 Project Structure
+
+```
+src/
+├── App.tsx                  # Layout, state wiring, replay/export integration
+├── main.tsx                 # Entry
+├── components/
+│   ├── GameBoard.tsx        # 3D board (R3F) + all stone/board animations
+│   ├── ReplayPanel.tsx      # Replay transport controls
+│   ├── ExportDialog.tsx     # SGF/JSON/TXT export modal
+│   └── ui/                  # Hand-written shadcn/ui-style primitives
+├── hooks/
+│   ├── useGomoku.ts         # Game state, AI scheduling, stats, sound
+│   ├── useReplay.ts         # Read-only replay state machine
+│   └── useViewMode.ts       # 2D/3D view persistence
+└── lib/
+    ├── gomoku/
+    │   ├── types.ts         # Board, Move, Player, win detection
+    │   ├── engine.ts        # Immutable game state + transitions
+    │   ├── ai.ts            # Heuristic + alpha-beta search
+    │   ├── replay.ts        # Move derivation & board-at-step
+    │   ├── export.ts        # SGF/JSON/TXT serialization + download
+    │   └── stats.ts         # Stats & achievements model
+    ├── audio/sfx.ts         # Web Audio synthesized SFX
+    └── achievementIcons.ts
+```
+
+## 📦 Deployment
+
+A GitHub Actions workflow (`.github/workflows/deploy.yml`) builds the app and deploys `dist/` to **GitHub Pages** on every push to `main`. The Vite base path is derived from `GITHUB_REPOSITORY`, so it works for any repo name.
+
+## 📄 License
+
+[MIT](./LICENSE) © [crper](https://github.com/crper)
+
+<div align="center">
+
+Made with ⚛️ React · 🧊 Three.js · 💛 TypeScript
+
+</div>

plugins/gomoku-3d-ztools/README.upstream.zh.md

@@ -0,0 +1,143 @@
+<div align="center">
+
+# ⚫⚪ Gomoku 3D · 五子棋 3D
+
+**一款带 AI 对手、棋局回放与棋谱导出的 3D 五子棋——基于 React、Three.js 与 TypeScript 构建。**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![React](https://img.shields.io/badge/React-18-61dafb.svg)](https://react.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6.svg)](https://www.typescriptlang.org/)
+[![Vite](https://img.shields.io/badge/Vite-5-646cff.svg)](https://vitejs.dev/)
+[![Three.js](https://img.shields.io/badge/Three.js-169-black.svg)](https://threejs.org/)
+
+🎮 **在线体验：** <https://crper.github.io/gomoku-3d/>
+
+[English](./README.md) · [简体中文](./README.zh.md)
+
+</div>
+
+---
+
+## ✨ 功能特性
+
+- **15×15 五子棋**，落子在可交互的 3D 棋盘交叉点上。
+- **AI 对手四档难度**——简单 / 中等 / 困难 / **大师**（深度受限的 alpha-beta negamax 搜索）。
+- **双视图模式**——2D 平面锁视角（清爽下棋）与 3D 自由轨道视角，切换有平滑相机补间。
+- **丰富动效**——落子弹跳 + 尘埃波纹、悬停呼吸预览、最后一手脉冲、胜利连线流光跳动、AI 思考微光；全部尊重 `prefers-reduced-motion` 降级。
+- **Web Audio 合成音效**——落子 / 悬停 / 悔棋 / 胜负 / 成就提示，可静音；**无音频文件、零音频依赖**。
+- **战绩与成就**持久化到 `localStorage`（胜/负/和、连胜、速胜、击败困难等）。
+- **悔棋**一整回合（你的一手 + AI 的应手）。
+- **棋局回放**——逐步前进 / 后退、跳转任意手、播放-暂停（0.5×–4× 调速）、可拖动进度条；只读观察模式，不影响实时对局。
+- **棋谱导出**——把已结束或进行中的对局导出为 **SGF**（围棋/五子棋/连珠软件通用格式）、**JSON** 或人类可读的 **TXT**，文件名可自定义。
+- **全面响应式**——桌面侧栏布局 + 移动端底部操作条，无重叠、无溢出。
+- **键盘快捷键**与无障碍支持（ARIA 标签、`aria-live` 当前手信息、焦点管理的对话框）。
+
+## 🧱 技术栈
+
+| 层 | 选型 |
+| --- | --- |
+| UI 框架 | [React 18](https://react.dev/) + [TypeScript 5](https://www.typescriptlang.org/)（strict 严格模式） |
+| 构建工具 | [Vite 5](https://vitejs.dev/) |
+| 3D 渲染 | [Three.js](https://threejs.org/)，经 [`@react-three/fiber`](https://github.com/pmndrs/react-three-fiber) + [`@react-three/drei`](https://github.com/pmndrs/drei) |
+| 样式 | [Tailwind CSS](https://tailwindcss.com/) + 手写 shadcn/ui 风格组件 |
+| 音频 | Web Audio API（合成，无资源文件、无音频依赖） |
+| 状态 | React Hooks——无外部状态库 |
+
+## 🚀 快速开始
+
+### 前置要求
+
+- Node.js **≥ 18**（开发环境为 22）
+- npm
+
+### 安装与运行
+
+```bash
+git clone https://github.com/crper/gomoku-3d.git
+cd gomoku-3d
+npm install
+npm run dev          # http://localhost:5173
+```
+
+### 脚本
+
+| 命令 | 说明 |
+| --- | --- |
+| `npm run dev` | 启动 Vite 开发服务器 |
+| `npm run build` | 类型检查（`tsc -b`）+ 生产构建到 `dist/` |
+| `npm run preview` | 本地预览生产构建 |
+| `npm run typecheck` | 运行 `tsc --noEmit` |
+
+## 🧪 测试
+
+`scripts/` 下的测试是纯 TypeScript，用 [esbuild](https://esbuild.github.io/) 打包后由 Node 运行（不依赖测试框架）：
+
+```bash
+# 引擎 + AI 逻辑（20 项）
+./node_modules/.bin/esbuild scripts/engine.test.ts --bundle --platform=node --format=esm --outfile=/tmp/e.mjs && node /tmp/e.mjs
+
+# AI 强度矩阵
+./node_modules/.bin/esbuild scripts/strength.test.ts --bundle --platform=node --format=esm --outfile=/tmp/s.mjs && node /tmp/s.mjs
+
+# 回放与导出（SGF/JSON/TXT）— 37 项
+./node_modules/.bin/esbuild scripts/replay.test.ts --bundle --platform=node --format=esm --outfile=/tmp/r.mjs && node /tmp/r.mjs
+
+# 50 局自对弈模拟（无卡死、无非法落子）
+./node_modules/.bin/esbuild scripts/sim.ts --bundle --platform=node --format=esm --outfile=/tmp/sim.mjs && node /tmp/sim.mjs
+```
+
+## 🎯 玩法
+
+- 黑棋先行。点击任意交叉点落子。
+- 横、竖、斜任意方向连成 **五子** 即胜。
+- 通过侧栏（桌面）或底栏（移动端）切换难度、先手、2D/3D 视图，以及悔棋、静音、回放、导出。
+
+### 回放键盘快捷键
+
+| 键 | 动作 |
+| --- | --- |
+| `←` / `→` | 上一手 / 下一手 |
+| `空格` | 播放 / 暂停 |
+| `Home` / `End` | 首手 / 末手 |
+| `Esc` | 退出回放 |
+
+## 📁 项目结构
+
+```
+src/
+├── App.tsx                  # 布局、状态接线、回放/导出集成
+├── main.tsx                 # 入口
+├── components/
+│   ├── GameBoard.tsx        # 3D 棋盘（R3F）+ 棋子/棋盘全部动效
+│   ├── ReplayPanel.tsx      # 回放传输控件
+│   ├── ExportDialog.tsx     # SGF/JSON/TXT 导出对话框
+│   └── ui/                  # 手写 shadcn/ui 风格基础组件
+├── hooks/
+│   ├── useGomoku.ts         # 对局状态、AI 调度、战绩、音效
+│   ├── useReplay.ts         # 只读回放状态机
+│   └── useViewMode.ts       # 2D/3D 视图持久化
+└── lib/
+    ├── gomoku/
+    │   ├── types.ts         # 棋盘、着法、玩家、胜判定
+    │   ├── engine.ts        # 不可变对局状态 + 状态转换
+    │   ├── ai.ts            # 启发式 + alpha-beta 搜索
+    │   ├── replay.ts        # 着法推导与"第 k 手盘面"
+    │   ├── export.ts        # SGF/JSON/TXT 序列化 + 下载
+    │   └── stats.ts         # 战绩与成就模型
+    ├── audio/sfx.ts         # Web Audio 合成音效
+    └── achievementIcons.ts
+```
+
+## 📦 部署
+
+仓库内置 GitHub Actions 工作流（`.github/workflows/deploy.yml`），每次推送到 `main` 会自动构建并把 `dist/` 部署到 **GitHub Pages**。Vite 的 base 路径由 `GITHUB_REPOSITORY` 动态推导，因此任意仓库名都能正确解析资源。
+
+## 📄 许可证
+
+[MIT](./LICENSE) © [crper](https://github.com/crper)
+
+<div align="center">
+
+用 ⚛️ React · 🧊 Three.js · 💛 TypeScript 打造
+
+</div>

plugins/gomoku-3d-ztools/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>五子棋 · Gomoku 3D</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>