---
name: solitaire.aigameplay
description: Klondike 纸牌接龙核心玩法封包 - 标准 7 列牌堆、翻牌堆、4 个花色目标堆的 PGS 实现
triggers: 纸牌,solitaire,接龙,klondike,扑克,poker,cards,牌堆,tableau,foundation,stock,waste,翻牌,移牌
---

# solitaire.aigameplay

Klondike 纸牌接龙核心玩法封包。实现标准 Klondike 单人纸牌接龙的 PGS (PlayCraft Gameplay Schema, 玩法定义规范) JSON 和 reducer。7 列牌堆（交替颜色降序叠放）+ 翻牌堆 + 4 个花色目标堆（A→K），将所有牌移到目标堆则胜利。

## Recipe

- **玩法类型**：solitaire（Klondike 纸牌接龙）
- **参考文件**：
  - `ref/pgs-schema.json`：PGS 规则骨架（entities、rules、algorithm、testCases）
  - `ref/reducer.template.ts`：reducer 接口约束模板
- **核心规则**：
  - `tableauColumns`: 7（7 列牌堆，第 i 列初始有 i 张牌，最上面翻开）
  - `foundationPiles`: 4（4 个花色目标堆：♠♥♦♣）
  - `drawCount`: 1（翻牌堆每次翻 1 张）
  - `stockRecycleLimit`: -1（-1 表示无限次循环翻牌堆）
- **移牌规则**：
  - `move_to_tableau`：目标列顶牌 face_up，且颜色交替（红↔黑），数值恰好比移动牌大 1
  - `move_to_foundation`：目标堆同花色，数值比当前堆顶大 1（空堆只接受 A）
  - 空列（tableau）只接受 K 作为起始牌
- **PGS Agent 操作流程**：
  1. 读取 `ref/pgs-schema.json` 作为规则骨架起点
  2. 读取 `ref/reducer.template.ts` 了解接口约束
  3. 实现 `reducer.ts`，导出所有必需函数
  4. 翻牌逻辑：移走 tableau 顶牌后，若新顶牌 face_down → 自动翻开
  5. 运行 `ref/pgs-schema.json` 中的所有 `testCases`，全部通过后才算完成
- **自动完成（auto_complete）**：
  - 当所有牌都已翻面（face_up）时，可启用自动完成
  - 自动将可移到目标堆的牌逐一移入
- **可 fork 变体**：
  - Spider Solitaire：2副牌，8列，可同色叠放
  - FreeCell：4个自由格，不同叠牌规则
  - 计时/计分模式：添加时间奖励分、撤销惩罚

## Result

- **产物文件**：`reducer.ts`
- **格式**：TypeScript，导出 `init(config)`、`dispatch(action)`、`getState()` + 分步函数接口
- **验证**：所有 testCases 必须通过

## 渲染集成（⚠️ 场景层必读）

### 设计原则：逻辑校验先行，动画后置

```ts
// ✅ 正确做法：先验证合法性，再播放动画
// Step 1: 玩家拖动一组牌到目标列
const targetCol = getDropTargetColumn(dragPos);
const movingCards = state.tableau[fromCol].slice(-count);

// Step 2: 验证是否合法
const canMove = canMoveToTableau(state, movingCards[0], targetCol);
if (!canMove) {
  await playSnapbackAnimation(movingCards);
  return;
}

// Step 3: 执行移牌
const newState = moveCards(state, { zone: 'tableau', col: fromCol }, { zone: 'tableau', col: targetCol }, count);

// Step 4: 若源列有牌需要翻面
if (newState.lastFlipped) {
  await playFlipAnimation(fromCol);
}

// Step 5: 检查是否可以自动完成
if (newState.allFaceUp) {
  triggerAutoComplete(newState);
}
```

## Binding

- **Binding Role**：`gameplayRule`
- **挂载目标**：`game/gameplay/solitaire/reducer.ts`
- **引用类型**：`gameplay-module-reference`
- **接口契约**：`init(config)` / `dispatch(action)` / `getState()` / `canMoveToTableau()` / `canMoveToFoundation()` / `moveCards()` / `drawFromStock()` / `getValidMoves()`

## Skill Definition

tools:
  - bash
  - write
  - read
prompt_extension: |
  You are implementing a Klondike Solitaire gameplay module following the PGS specification.
  Write the PGS JSON with entities, rules, algorithm, and testCases.
  Implement the reducer.ts with:
    - init/dispatch/getState (一体化接口，用于测试)
    - canMoveToTableau/canMoveToFoundation/moveCards/drawFromStock/getValidMoves (分步函数)
  Card suits: 'S' (Spades♠), 'H' (Hearts♥), 'D' (Diamonds♦), 'C' (Clubs♣)
  Card colors: Spades+Clubs = black, Hearts+Diamonds = red
  Tableau rule: alternating color, descending value (K=13, Q=12, J=11, A=1)
  Foundation rule: same suit, ascending from A (1) to K (13)
  After moving cards, auto-flip the new top card of source column if face_down.
  Run the testCases to verify the logic before finalizing.