9.7 KiB
9.7 KiB
Deepseek API 中国象棋接口文档
一、接口概述
1.1 API基本信息
| 项目 | 内容 |
|---|---|
| API端点 | https://api.deepseek.com/v1/chat/completions |
| 请求方法 | POST |
| 认证方式 | Bearer Token |
| 模型 | deepseek-chat |
1.2 认证方式
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 完整请求数据结构
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 标准响应格式
{
"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响应后,系统会验证走法的合法性:
function validateMove(棋盘, from, to, 当前方颜色):
1. 检查from位置是否有己方棋子
2. 检查to位置是否在棋盘范围内
3. 检查是否符合该棋子的走法规则
4. 检查移动后是否会被将军
5. 返回验证结果:{valid: boolean, reason?: string}
验证失败处理:
- 如果Deepseek返回的走法不合法,系统会记录警告
- 自动回退到本地A* AI进行走棋
- 保证游戏能够继续进行
五、Deepseek下棋策略
5.1 开局策略(前10步)
红方常见开局:
-
当头炮(炮二平五)
- 意图:快速威胁对方中路
- 后续:可配合车、马进攻
-
仙人指路(兵三进一)
- 意图:活通马路,控制河界
- 后续:灵活多变
-
飞相局(相三进五)
- 意图:稳健防守,伺机反击
- 后续:巩固阵地后出动大子
黑方应对策略:
-
屏风马(马8进7、马2进3)
- 应对当头炮的经典防守
- 左右均衡,可刚可柔
-
反宫马(马2进3、炮8平6)
- 灵活多变,可转多种布局
- 注意保护中路
-
顺手炮(炮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 中配置:
const DEEPSEEK_API_KEY = "your-api-key-here";
8.2 难度配置
| 难度 | temperature | 提示语特点 |
|---|---|---|
| 容易 | 0.8 | 简单策略,允许随机性 |
| 一般 | 0.5 | 平衡策略,适度计算 |
| 困难 | 0.2 | 深度策略,精确计算 |