自制象棋打谱与AI分析软件：从录谱到复盘的工程实践

原本只是想在电脑上打开一份很久以前的对局记录，复盘一下中局那个疑问手。结果光是把棋谱从老软件里导出来、再导进另一个版本，就浪费了一个晚上。更无语的是，很多打谱工具界面还停留在十年前的设计，功能能用，但分析要么要付费，内置引擎也不太顺手。后来我决定自己做一套“象棋打谱与AI分析软件”。目标不复杂：录入方便、复盘直观、能调用AI给提示，还要让新手也能看懂代码。

做完之后回头看，这个方向最大的收获不是“我写了一个会下棋的程序”，而是把棋谱管理、棋局分析、AI辅助和复盘流程拼成了一条自己真正会用的工作链。这篇文章就聊聊我理解的自制路径、核心取舍和容易踩坑的地方。

1. 先想明白：你要做的不是分析引擎，而是一套复盘工作台

很多初学者的第一反应是，既然要做AI分析，就得从算法开始写。比如局面评估、搜索树、开局库、残局库……这个方向很容易让人兴奋，但也最容易让人放弃。象棋引擎是几十年算法积累的结果，靠个人从零实现一个能超过开源引擎的版本，难度极大，而且对“打谱软件”这个需求来说，并不是重点。

1.1 打谱软件真正解决什么问题

打谱这个动作，本质是把棋谱变成可管理、可回放、可研究的数据。你需要的不只是“能显示棋盘”，还应该包括：

• 录入一步棋，生成新的局面。
• 保存整盘棋，方便下次继续看。
• 在任意局面停住，回到之前某个分支。
• 加入自己的注解，记录当时的想法。
• 需要时调用AI计算，给出候选走法和评估。
• 导出成常见棋谱格式，和朋友或软件交流。

这些功能里，真正核心的是“棋谱结构”和“局面管理”，而不是“谁更会下棋”。如果你能先把棋盘画出来，把走法存在一个结构里，再把AI分析作为外部能力接进来，就已经完成了一个打谱工具的大部分价值。

1.2 为什么AI分析可以放后面接入

对初学者来说，AI分析最大的难点不是“用AI”，而是“把AI接到软件里”这件事还没有想清楚。这需要一个前提：你的棋谱数据结构是稳定的，AI无论返回“最佳走法”还是“局面评分”，你都知道该往哪里填。

如果一开始就陷入算法细节，你会在棋盘绘制、走法校验、界面交互都没做完的时候，就开始调试搜索树参数，最后界面半成品、算法也半成品。更稳妥的做法是：先用一个最小的棋盘界面完成“录入—保存—复盘”，把AI接口留成可替换的模块。等主流程通了，再选择接入本地引擎或者云端API。

1.3 初学者的最小可行闭环

我做这个项目时，给自己定的第一个目标是完成下面这条链路：

打开一局棋 -> 手动录谱 -> 保存为本地文件 -> 重新打开 -> 走到某个局面 -> 调用AI分析 -> 显示结果

这不是一个复杂的工程目标，但它包含了一个完整软件需要的所有关键层：数据模型、界面交互、持久化、异步任务、外部接口。把这条链路跑通，比一开始就堆功能重要得多。

如果你也想做类似项目，建议先不要碰这些功能：多线程搜索、神经网络评估、自对弈、开局库学习。不是说它们不重要，而是它们会让你的项目变成“算法研究项目”，而不是“打谱分析软件”。

2. 第一步：把棋谱变成电脑能处理的格式

打谱软件的数据结构是整个项目的地基。很多初学者搭界面很快，但保存、导入、复盘时总出问题，多半是数据结构没设计好。

2.1 不要让界面依赖特殊格式，先定义数据模型

中国象棋棋盘是9条竖线、10条横线，棋子落在交叉点上。表示一个局面最通用的方式是FEN（Forsyth-Edwards Notation）。FEN用一段字符串记录每个位置上的棋子、当前走棋方、是否可以王车易位等状态。虽然中国象棋的FEN和国象略有差别，但核心思路一样：把棋盘序列化成一个字符串。

在一次对局里，除了初始局面，还需要按顺序保存每一步走法。常见走法格式是“a2a4”，表示棋子从a2坐标移动到a4坐标。有些格式会加兵种或附加信息，但对初学者来说，只要是能和棋盘坐标对应，就会很好处理。

我建议的棋谱存储结构大致是这样的：

{ "meta": { "title": "先手对后手-中炮对屏风马", "redPlayer": "我", "blackPlayer": "朋友", "date": "2025-01-15" }, "startFen": "rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w - - 0 1", "moves": [ "h2e2", "h9g7" ] }

这里的startFen是初始局面，moves是行棋坐标序列。程序里只要维护一个“当前走棋索引”，从初始局面开始，依次应用走法，就能还原任意一步后的棋盘状态。这个方法看起来简单，但非常可靠，也方便做撤销、重做、分支跳转。

2.2 画棋盘和交互：Canvas 还是 DOM

棋盘绘制有两条常用路线：

• 用Canvas画图，适合需要频繁刷新棋盘、显示箭头、高亮棋子的场景。
• 用DOM加CSS画棋盘，适合交互逻辑简单、想快速上手的项目。

我个人在初学时更建议Canvas，因为棋盘的动画和标记（比如分析器给出的最佳走法箭头）用Canvas画会直观很多，像素坐标也能和走法坐标直接换算。

一个简单的做法是：把棋盘分成9列10行，用鼠标点击时，判断点击点落在哪个交叉点附近，然后记录“选中棋子”和“目标位置”。交互流程如下：

1. 点击一个棋子，标记选中。
2. 点击一个目标交叉点，检查走法是否合法。
3. 合法则应用走法，更新moves数组，刷新棋盘。
4. 不合法则提示，保持原局面。

这里要注意，初学者容易陷进“自己实现所有走子规则”。比如车不能穿越棋子、马腿被蹩、象眼被塞、士不能出九宫、过河兵路线变化等等。规则很多，自己实现容易漏。更稳妥的方式是：先只做“允许任意移动”，把完整规则放在后面的版本，或者直接调用开源库/引擎来校验走法。

2.3 一个能跑通的手动录谱流程

录谱时，我习惯把一次走法封装成一个函数：

function applyMove(moves, fen, from, to) { const nextFen = calculateNextFen(fen, from, to); moves.push({ from: from, to: to, fenBefore: fen, fenAfter: nextFen }); return nextFen; }

虽然上面的代码中calculateNextFen需要根据棋盘规则实现，但它至少给了你一个清晰的结构。问题是：不要在最开始就追求规则完整性。第一版可以先允许“无规则限制”的移动，只要能保存和回放棋谱，就达到了打谱工具的基本要求。后续可以把“走法校验”交给一个已经成熟的开源库或本地引擎来处理。

注意：第一版千万不要一边写界面，一边想着把走法规则写到完美。先让用户能点击棋子完成移动，再把错误提示补上。否则你会花大量时间在“马怎么不能过去了”这类规则调试上，而不是在整体流程上。

3. 接入AI分析：不从头写引擎，而是学会调用现成能力

当你的打谱流程能跑通后，就可以开始接入AI分析了。但这里要先搞清楚一件事：象棋里的“AI分析”到底由谁来提供。

3.1 理解象棋AI在软件里的定位

象棋AI至少包含两层能力：

• 引擎层：负责计算局面评分、搜索最佳走法。它往往是一个独立程序，通过标准协议输出结果。
• 解释层：把计算出的走法和评分转成人话，比如“红方目前稍优，建议走炮二平五”。这一层可以由大语言模型完成，也可以由你自己写的模板完成。

对初学者来说，最容易混淆的就是把“大模型”和“象棋引擎”当成同一个东西。实际上，大模型更擅长生成自然语言解释，但不一定擅长精确计算复杂象棋局面；引擎擅长精确计算，但输出很干、不直观。一个完整的“象棋打谱与AI分析软件”，通常是把两者结合起来。

3.2 本地引擎与云端API的取舍

接入AI分析，核心问题不是“用哪个AI”，而是“在什么环境里调用”。

这两种方式没有绝对好坏。我的建议是：如果你本地已经有开源象棋引擎，或者机器配置还不错，优先尝试本地引擎，因为调试更直观，也更容易理解“引擎给出候选走法”这个过程。如果你希望AI分析结果更稳定，不想折腾环境，可以选云端API。

无论选哪种，都要把“AI调用”设计成一个独立模块。比如：

def analyze_position(fen, depth=20): # 调用本地引擎或云端API # 返回 candidates: [{move: "h2e2", score: 80, pv: [...]}] pass

这样以后替换引擎或切换API时，界面层不需要跟着改。

3.3 把引擎输出变成人能看懂的棋评

引擎输出往往是这样：

info depth 20 score cp 45 pv h2e2 h9g7 bestmove h2e2 ponder h9g7

score cp 45表示红方领先45个分值（约0.45个兵），pv是主要变化线。普通人直接看会非常吃力，这时你可以做一个“棋评转换层”：

• 把h2e2还原为“炮二平五”。
• 把score cp 45翻译成“红方略占先”。
• 把pv中的一系列走法转成简短的棋谱文本。

如果你接入大模型，可以用类似这样的提示词：

给定一个中国象棋局面和分析结果： 局面：{fen} 候选走法：{candidates} 请用通俗语言解释当前局势和最优走法，控制在100字以内。

但要注意，大模型有时会“一本正经地胡说八道”，它给出的棋理解释不一定准确。实际落地时，最好把引擎的计算结果作为主要依据，大模型只负责润色语言，不要让它修改走法。

4. 真正决定体验的不是功能，而是工程细节

界面能画棋盘、AI能返回结果，这只是第一步。一个打谱软件能不能长期用，往往取决于几个容易被忽略的工程细节。

4.1 棋谱存取、撤销重做和局面校验

对打谱工具来说，用户一定会误操作。没有撤销重做，会让人非常崩溃。我建议在数据结构里维护一个“历史栈”：

• undoStack：存放已经走的棋步。
• redoStack：存放被撤销的棋步。

每次应用走法时，把当前走法压入undoStack，清空redoStack。撤销时从undoStack弹出，恢复到上一步局面。重做则反过来。

局面校验同样重要。虽然第一版可以允许任意移动，但一旦要把棋谱分享给别人，错误走法就会带来问题。比较成熟的方案是：把棋谱里的移动，交给一个开源引擎来判断是否合法。不需要自己实现规则，只需要调用引擎的“合法走法”接口，再比较目标走法是否在其中。这样既节省时间，又不容易出错。

4.2 把AI分析做成异步任务，不要卡死界面

象棋引擎思考一局棋，可能需要几百毫秒到几秒，甚至更久。如果直接在主线程里等待引擎返回，界面会变得很卡，用户会以为程序崩溃了。好的做法是：

1. 用户在某个局面点击“分析”。
2. 程序把分析任务提交到一个队列，显示“分析中……”状态。
3. 引擎在后台线程运行，完成后通过回调或事件通知界面更新。
4. 如果用户中途切换局面，旧结果要丢弃或标记为“过期”。

这个流程其实和很多后台任务一样，核心是“不要阻塞界面”。你用Python可以开线程或进程，用前端可以配合后端服务，用Node.js可以用子进程。哪怕是一个本地小工具，也要尽早养成异步处理习惯。

4.3 数据与AI结果分开存储

一个很容易犯的错，是把AI分析结果写进原始棋谱文件。比如给每一步都塞进一串很长的引擎注释、评分、更新信息，最后棋谱文件变得非常大，而且和别人交换棋谱时还容易不兼容。

建议分成两部分：

• 棋谱文件：只保存对局信息，例如标题、日期、走法序列。
• 分析结果缓存：单独保存到另一个文件或数据库，用棋谱文件名加局面哈希做索引。

这样做的原因有三个：

1. 棋谱文件保持干净，可以随时导出。
2. 分析结果可以重新生成，不用反复污染原始数据。
3. 以后换AI引擎，只需要清理缓存，不用动棋谱。

5. 从能用到长期用：批量复盘、对局库和可维护性

当你已经有一个能打谱、能分析的软件后，下一步就是把它变成真正属于你的对局库。

5.1 批量导入棋谱，建立自己的对局库

手动一盘一盘录入会有上限，但如果你能导入已有的棋谱文件，就能快速积累一个对局库。哪怕刚开始只支持一种格式，也比没有强。

我建议在棋谱数据模型上增加标签字段，比如“开局名”“红方”“黑方”“结果”“日期”。这样后续可以做很多有价值的事：

• 按开局筛选：看看你执红时最常用什么布局。
• 按对手筛选：复盘你和某个棋友的所有对局。
• 按胜率统计：知道自己哪些开局容易吃亏。

这些功能都需要一开始就保住数据的结构化。如果棋谱只是几张图片或PDF，后面的统计就无从谈起。

5.2 用“复盘三遍法”把AI分析变成学习流程

工具做得再好，如果没有使用流程，也不会带来进步。我给自己定的复盘流程很简单，分三遍：

第一遍，快速过谱：不看AI，只看自己当时为什么这么走，有没有明显漏招。 第二遍，选定重点分支：把某个中局疑问手截停，展开几步候选走法，看看有没有更好的进攻或防守方案。 第三遍，用AI验证：请引擎对“当前局面”和“假想走法”分别评分，确认自己的直觉是否和计算结果一致。

这个流程里，AI不是导师，而是验证工具。它能告诉你“这一步可能有问题”，但不会自动告诉你“为什么当时没有看到”。这个为什么，还是要你自己复盘。

5.3 不要忽略版本、权限、日志和备份

一个长期使用的打谱工具，即使只是个人项目，也要考虑可维护性。否则三个月后你想继续开发，可能连上次的代码逻辑都忘记了。

几个比较实用的工程习惯：

• 用版本控制管理代码，哪怕只有自己一个人。
• 保存棋谱文件时，设置清晰的编码格式（UTF-8），避免中文乱码。
• 给关键操作写日志，比如导入导出、AI调用的起始时间、是否成功。
• 定期备份棋谱文件和分析缓存。
• 如果软件要给别人用，还要考虑权限问题：谁能读，谁能写，谁能执行AI分析。

这些听起来不花哨，但实际使用中，问自己最多的问题往往是：“我之前那盘棋存到哪了？”“为什么打开棋谱是乱码？”“为什么AI分析突然没结果？”这些问题大部分都能靠日志、备份和明确的文件结构避免。

6. 常见问题排查与避坑清单

新手做到后面，遇到问题不要慌。排查问题有一套顺序，和具体功能无关，但它能帮你少走弯路。

6.1 排查顺序：现象、输入、环境、参数、边界

我通常按这个顺序排查：

1. 先看现象：是报错、卡住、无输出，还是输出明显不对？
2. 再看输入：棋谱文件格式对不对？FEN字符串是否完整？路径是否带中文？
3. 再看环境：Python版本、Node版本、引擎是否安装、依赖是否齐全。
4. 再看参数：搜索深度设置、API Key、超时时间、并发数。
5. 最后看边界：功能本身是否支持这个场景，或者是我用错了用法。

很多时候，问题不是出在AI模块，而是出在输入文件编码或路径上。比如从Windows记事本另存的时候，文件编码变成了带BOM的UTF-8，棋谱解析器没处理BOM，于是第一行就报错。这类问题只要在日志里打印“接收到的文件前50个字节”，很快就能定位。

6.2 真实项目里最常碰到的几类问题

这些坑不是AI特有，而是数据流和异步处理里常见的问题。只要把数据流转画出来，多数问题都能一眼看出来。

6.3 什么时候不该自己造轮子

说了这么多自制的好处，也要说点清醒的。如果你的目的只是“想复盘棋局，看看谁优谁劣”，那直接用现成的棋谱软件或在线平台，效率更高。你自己造轮子的价值，不在“避免花钱”，而在以下几点：

• 你希望完全掌控棋谱数据。
• 你想把复盘和分析流程定制成自己的习惯。
• 你想学习工程化实践，或者想做一个面向特定人群的工具。
• 你希望离线使用，不想依赖某个平台。

反过来，如果这些都不是你的需求，那还是把时间留给下棋本身更划算。自制工具不是目的，帮自己更好地复盘才是。

回到最初那个问题。当你掌握了一套“从录谱到AI分析”的最小实现后，你会发现它带来的不仅是棋力提升，更是一种把想法变成工具的掌控感。先做一个小而完整的闭环，再逐步加功能，这可能是所有技术项目里最值得坚持的一条路径。