Files
Obsidian/MyArticles/Deepseek API 中国象棋接口文档.md
coco 8b94d76799 a
2026-07-21 13:57:15 +08:00

864 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 一、接口概述
### 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 | 深度策略,精确计算 |