# 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 | 深度策略,精确计算 |