434 lines
9.7 KiB
Markdown
434 lines
9.7 KiB
Markdown
# Deepseek API 中国象棋接口文档
|
||
|
||
## 一、接口概述
|
||
|
||
### 1.1 API基本信息
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| API端点 | `https://api.deepseek.com/v1/chat/completions` |
|
||
| 请求方法 | POST |
|
||
| 认证方式 | Bearer Token |
|
||
| 模型 | `deepseek-chat` |
|
||
|
||
### 1.2 认证方式
|
||
|
||
```http
|
||
Authorization: Bearer {YOUR_API_KEY}
|
||
Content-Type: application/json
|
||
```
|
||
|
||
## 二、棋局数据格式
|
||
|
||
### 2.1 棋盘表示格式(FEN-like)
|
||
|
||
采用类FEN(Forsyth-Edwards Notation)格式表示棋盘状态:
|
||
|
||
```
|
||
第0行/第1行/第2行/.../第9行
|
||
```
|
||
|
||
**棋盘坐标说明:**
|
||
- 行号:0-9,0为黑方底线,9为红方底线
|
||
- 列号:0-8,0为左侧,8为右侧
|
||
|
||
**棋子编码:**
|
||
|
||
| 棋子 | 红方(大写) | 黑方(小写) |
|
||
|------|-------------|-------------|
|
||
| 帅/将 | K | k |
|
||
| 仕/士 | A | a |
|
||
| 相/象 | B | b |
|
||
| 马 | N | n |
|
||
| 车 | R | r |
|
||
| 炮 | C | c |
|
||
| 兵/卒 | P | p |
|
||
| 空位 | . | . |
|
||
|
||
**示例棋盘状态:**
|
||
|
||
```
|
||
rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR
|
||
```
|
||
|
||
对应棋盘:
|
||
```
|
||
第0行: r n b a k a b n r (黑方底线)
|
||
第1行: . . . . . . . . .
|
||
第2行: . c . . . . . c .
|
||
第3行: p . p . p . p . p
|
||
第4行: . . . . . . . . .
|
||
第5行: . . . . . . . . .
|
||
第6行: P . P . P . P . P
|
||
第7行: . C . . . . . C .
|
||
第8行: . . . . . . . . .
|
||
第9行: R N B A K A B N R (红方底线)
|
||
```
|
||
|
||
### 2.2 完整请求数据结构
|
||
|
||
```typescript
|
||
interface DeepseekRequest {
|
||
model: string; // "deepseek-chat"
|
||
messages: Message[];
|
||
temperature: number; // 0.0-1.0,难度相关
|
||
max_tokens: number; // 最大返回token数
|
||
}
|
||
|
||
interface Message {
|
||
role: "system" | "user";
|
||
content: string;
|
||
}
|
||
```
|
||
|
||
## 三、提示语(Prompt)详细说明
|
||
|
||
### 3.1 系统提示语(System Prompt)
|
||
|
||
#### 3.1.1 基础系统提示语模板
|
||
|
||
```
|
||
你是一个中国象棋AI助手。当前你是{颜色}方。
|
||
|
||
棋盘表示规则:
|
||
- 每行用"/"分隔,共10行
|
||
- 每行9个格子,空位用"."表示
|
||
- 棋子表示:K=帅 k=将 A=仕 a=士 B=相 b=象 N=马 n=马 R=车 r=车 C=炮 c=炮 P=兵 p=卒
|
||
- 红方用大写字母,黑方用小写字母
|
||
|
||
坐标规则:
|
||
- 行号:0-9,0是黑方底线,9是红方底线
|
||
- 列号:0-8,0是左侧,8是右侧
|
||
|
||
你必须以以下JSON格式回复你的走法:
|
||
{
|
||
"from": {"row": 起始行号(0-9), "col": 起始列号(0-8)},
|
||
"to": {"row": 目标行号(0-9), "col": 目标列号(0-8)},
|
||
"reason": "简要说明你的走法思路(20字以内)"
|
||
}
|
||
|
||
注意:
|
||
1. 只能移动己方棋子
|
||
2. 必须遵守中国象棋规则
|
||
3. 考虑进攻和防守的平衡
|
||
```
|
||
|
||
#### 3.1.2 不同难度的系统提示语
|
||
|
||
**容易难度:**
|
||
```
|
||
{基础系统提示语}
|
||
|
||
你是初级水平的棋手。请遵循以下策略:
|
||
1. 优先选择简单的进攻或防守走法
|
||
2. 避免复杂的战术组合
|
||
3. 优先考虑吃子和将军机会
|
||
4. 保持棋子安全,避免被吃
|
||
5. 适当出动大子(车、马、炮)
|
||
|
||
温度参数:0.8(允许一定随机性)
|
||
```
|
||
|
||
**一般难度:**
|
||
```
|
||
{基础系统提示语}
|
||
|
||
你是中级水平的棋手。请遵循以下策略:
|
||
1. 选择合理的战术走法
|
||
2. 注意保护重要棋子(车、马、炮)
|
||
3. 寻找吃子机会,但避免冒进
|
||
4. 保持子力协调,避免孤子
|
||
5. 控制中心区域(第3-5列)
|
||
6. 考虑2-3步后的局面变化
|
||
|
||
温度参数:0.5(适度确定性)
|
||
```
|
||
|
||
**困难难度:**
|
||
```
|
||
{基础系统提示语}
|
||
|
||
你是高级水平的棋手。请遵循以下策略:
|
||
1. 选择最优的战术走法,追求局面优势
|
||
2. 进行深度计算,考虑3-4步后的变化
|
||
3. 积极进攻,同时注意防守
|
||
4. 利用战术组合(抽将、牵制、双将等)
|
||
5. 控制中心,争夺主动权
|
||
6. 优先考虑将死对方的将/帅
|
||
7. 在优势时简化局面,劣势时制造复杂
|
||
|
||
温度参数:0.2(高度确定性)
|
||
```
|
||
|
||
### 3.2 用户提示语(User Prompt)
|
||
|
||
```
|
||
当前棋盘状态({颜色}方走):
|
||
{棋盘FEN字符串}
|
||
|
||
最近走棋记录:
|
||
{历史走法列表}
|
||
|
||
当前局面分析:
|
||
- 己方棋子:{列表}
|
||
- 对方棋子:{列表}
|
||
- 将军状态:{是否被将军}
|
||
|
||
请给出你的走法。
|
||
```
|
||
|
||
**完整示例:**
|
||
|
||
```
|
||
当前棋盘状态(红方走):
|
||
rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR
|
||
|
||
最近走棋记录:
|
||
1. 炮二平五
|
||
2. 马8进7
|
||
3. 马二进三
|
||
|
||
当前局面分析:
|
||
- 己方(红方)棋子:帅、仕、相、马、车、炮、兵各若干
|
||
- 对方(黑方)棋子:将、士、象、马、车、炮、卒各若干
|
||
- 将军状态:未被将军
|
||
|
||
请给出你的走法。
|
||
```
|
||
|
||
## 四、Deepseek反馈格式
|
||
|
||
### 4.1 标准响应格式
|
||
|
||
```json
|
||
{
|
||
"from": {
|
||
"row": 7,
|
||
"col": 1
|
||
},
|
||
"to": {
|
||
"row": 7,
|
||
"col": 4
|
||
},
|
||
"reason": "当头炮威胁对方中路"
|
||
}
|
||
```
|
||
|
||
### 4.2 响应字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| from.row | number | 起始位置行号 (0-9) |
|
||
| from.col | number | 起始位置列号 (0-8) |
|
||
| to.row | number | 目标位置行号 (0-9) |
|
||
| to.col | number | 目标位置列号 (0-8) |
|
||
| reason | string | 走法思路说明 |
|
||
|
||
### 4.3 走法验证
|
||
|
||
收到Deepseek响应后,系统会验证走法的合法性:
|
||
|
||
```typescript
|
||
function validateMove(棋盘, from, to, 当前方颜色):
|
||
1. 检查from位置是否有己方棋子
|
||
2. 检查to位置是否在棋盘范围内
|
||
3. 检查是否符合该棋子的走法规则
|
||
4. 检查移动后是否会被将军
|
||
5. 返回验证结果:{valid: boolean, reason?: string}
|
||
```
|
||
|
||
**验证失败处理:**
|
||
- 如果Deepseek返回的走法不合法,系统会记录警告
|
||
- 自动回退到本地A* AI进行走棋
|
||
- 保证游戏能够继续进行
|
||
|
||
## 五、Deepseek下棋策略
|
||
|
||
### 5.1 开局策略(前10步)
|
||
|
||
**红方常见开局:**
|
||
|
||
1. **当头炮(炮二平五)**
|
||
- 意图:快速威胁对方中路
|
||
- 后续:可配合车、马进攻
|
||
|
||
2. **仙人指路(兵三进一)**
|
||
- 意图:活通马路,控制河界
|
||
- 后续:灵活多变
|
||
|
||
3. **飞相局(相三进五)**
|
||
- 意图:稳健防守,伺机反击
|
||
- 后续:巩固阵地后出动大子
|
||
|
||
**黑方应对策略:**
|
||
|
||
1. **屏风马(马8进7、马2进3)**
|
||
- 应对当头炮的经典防守
|
||
- 左右均衡,可刚可柔
|
||
|
||
2. **反宫马(马2进3、炮8平6)**
|
||
- 灵活多变,可转多种布局
|
||
- 注意保护中路
|
||
|
||
3. **顺手炮(炮8平5)**
|
||
- 对攻激烈,双方互有机会
|
||
- 需要精确计算
|
||
|
||
### 5.2 中局策略
|
||
|
||
#### 5.2.1 进攻策略
|
||
|
||
**1. 中路突破**
|
||
```
|
||
条件:中路兵卒已打开,炮或车可配合
|
||
走法:炮/车占中路,配合其他子力进攻
|
||
目标:威胁对方将/帅
|
||
```
|
||
|
||
**2. 侧翼进攻**
|
||
```
|
||
条件:一侧子力占优,对方防守薄弱
|
||
走法:车、马、炮配合,从侧翼渗透
|
||
目标:制造杀势或得子
|
||
```
|
||
|
||
**3. 牵制战术**
|
||
```
|
||
条件:对方某子位置尴尬,移动会导致损失
|
||
走法:用炮或车牵制对方大子
|
||
目标:限制对方子力活动,谋取利益
|
||
```
|
||
|
||
#### 5.2.2 防守策略
|
||
|
||
**1. 应将方法**
|
||
```
|
||
优先级:
|
||
1. 吃掉攻击子(如果可能)
|
||
2. 垫将(用其他子挡住)
|
||
3. 避将(将/帅移动)
|
||
|
||
选择标准:
|
||
- 应将后的局面最优
|
||
- 避免应将后被连续攻击
|
||
```
|
||
|
||
**2. 兑子解围**
|
||
```
|
||
场景:己方处于被动,子力被牵制
|
||
策略:寻找兑子机会,简化局面
|
||
注意:劣势时避免兑子,优势时积极兑子
|
||
```
|
||
|
||
### 5.3 残局策略
|
||
|
||
#### 5.3.1 必胜残局
|
||
|
||
**单车胜单士:**
|
||
```
|
||
策略:
|
||
1. 车占中路或肋道
|
||
2. 逼对方将/帅到边路
|
||
3. 帅/将助攻,形成杀势
|
||
```
|
||
|
||
**单马胜单士:**
|
||
```
|
||
策略:
|
||
1. 马控制要点,限制对方将/帅
|
||
2. 帅/将占据中路
|
||
3. 逐步缩小对方活动空间
|
||
```
|
||
|
||
#### 5.3.2 和棋残局
|
||
|
||
**单马对单象:**
|
||
```
|
||
判断:通常和棋
|
||
策略:象方注意象不要被马捉死
|
||
```
|
||
|
||
**单车对单士象:**
|
||
```
|
||
判断:通常和棋
|
||
策略:士象方注意防守位置,不要让车各个击破
|
||
```
|
||
|
||
### 5.4 特殊战术
|
||
|
||
#### 5.4.1 抽将
|
||
|
||
```
|
||
定义:移动一个子,同时将军并威胁对方其他子
|
||
示例:车将军,同时捉对方马
|
||
应对:优先应将,必要时弃子
|
||
```
|
||
|
||
#### 5.4.2 牵制
|
||
|
||
```
|
||
定义:用炮或车盯住对方重要子力,使其无法移动
|
||
示例:炮牵制对方车马
|
||
应对:寻找解脱方法,或用其他子力支援
|
||
```
|
||
|
||
#### 5.4.3 双将
|
||
|
||
```
|
||
定义:两个子同时将军
|
||
应对:必须用将/帅移动应将,无法垫将或吃子
|
||
```
|
||
|
||
## 六、错误处理与降级机制
|
||
|
||
### 6.1 API错误处理
|
||
|
||
| 错误类型 | 处理方式 |
|
||
|----------|----------|
|
||
| API超时 | 回退到A* AI |
|
||
| 返回格式错误 | 解析JSON失败,回退到A* AI |
|
||
| 走法不合法 | 记录日志,回退到A* AI |
|
||
| 网络错误 | 重试1次,仍失败则回退到A* AI |
|
||
|
||
### 6.2 降级机制流程
|
||
|
||
```
|
||
调用Deepseek API
|
||
↓
|
||
成功?
|
||
↓ 否
|
||
解析响应
|
||
↓
|
||
成功?
|
||
↓ 否
|
||
验证走法
|
||
↓
|
||
合法?
|
||
↓ 否
|
||
使用本地A* AI
|
||
```
|
||
|
||
## 七、代码实现关键文件
|
||
|
||
- `app/lib/deepseekAPI.ts`:Deepseek API接口实现
|
||
- `app/lib/astarAI.ts`:A* AI(降级备用)
|
||
- `app/hooks/useChessGame.ts`:游戏状态管理
|
||
|
||
## 八、配置说明
|
||
|
||
### 8.1 API密钥配置
|
||
|
||
在 `app/lib/deepseekAPI.ts` 中配置:
|
||
|
||
```typescript
|
||
const DEEPSEEK_API_KEY = "your-api-key-here";
|
||
```
|
||
|
||
### 8.2 难度配置
|
||
|
||
| 难度 | temperature | 提示语特点 |
|
||
|------|-------------|-----------|
|
||
| 容易 | 0.8 | 简单策略,允许随机性 |
|
||
| 一般 | 0.5 | 平衡策略,适度计算 |
|
||
| 困难 | 0.2 | 深度策略,精确计算 |
|