Files
Ubuntu 32b43f85bd a
2026-07-03 16:58:28 +08:00

9.7 KiB
Raw Permalink Blame History

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步)

红方常见开局:

  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 中配置:

const DEEPSEEK_API_KEY = "your-api-key-here";

8.2 难度配置

难度 temperature 提示语特点
容易 0.8 简单策略,允许随机性
一般 0.5 平衡策略,适度计算
困难 0.2 深度策略,精确计算