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

10 KiB
Raw Permalink Blame History

一、接口概述

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. 当头炮(炮二平五)

   - 意图:快速威胁对方中路

   - 后续:可配合车、马进攻

  1. 仙人指路(兵三进一)

   - 意图:活通马路,控制河界

   - 后续:灵活多变

  1. 飞相局(相三进五)

   - 意图:稳健防守,伺机反击

   - 后续:巩固阵地后出动大子

黑方应对策略:

  1. 屏风马(马8进7、马2进3)

   - 应对当头炮的经典防守

   - 左右均衡,可刚可柔

  1. 反宫马(马2进3、炮8平6)

   - 灵活多变,可转多种布局

   - 注意保护中路

  1. 顺手炮(炮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 | 深度策略,精确计算 |