1. 从零到上架：一个假期项目的完整拆解
国庆七天假期，说长不长，说短也不短。出门看人海还是在家躺平，每年都是同样的选择题。今年我选了个第三条路——用 AI 编程助手 Codex，从零开始搓一款《中国象棋》App，并且赶在假期结束前把它送上了 App Store。听起来有点疯狂，但整个过程走下来，我发现这件事的可行性远比想象中高。这篇文章不是炫耀贴，而是一份完整的复盘记录，把从技术选型、核心逻辑实现、UI 设计、上架审核到踩坑排查的全流程都摊开来聊。
先说说这个项目到底做了什么。简单讲，它是一款单机版中国象棋应用，支持人机对战、双人对战、悔棋、棋谱记录、残局挑战这几个核心功能。目标用户是那些想随手下一盘棋、又不想注册账号、不想看广告的普通棋友。整个项目从第一行代码到 App Store 审核通过，实际投入时间大约五天半，其中编码占三天，调试和适配占一天半，上架材料准备和审核等待占一天。这个时间分配很关键，后面会详细展开。
为什么选中国象棋？原因很实际。第一，规则明确，边界清晰，AI 辅助编程最怕需求模糊，象棋的走法、胜负判定、和棋条件都有标准定义，不需要反复推敲产品逻辑。第二，棋盘和棋子的视觉元素相对简单，不需要复杂的美术资源，用代码绘制或者简单的矢量图就能搞定。第三，这类棋类应用在 App Store 上的竞品虽然多，但很多都充斥着广告和内购，一个干净、纯粹的单机版本反而有差异化空间。第四，也是最重要的一点——象棋的 AI 算法有大量成熟的开源方案可以参考，不需要从零发明轮子。
Codex 在这个项目里扮演的角色，更像是一个执行力极强但需要明确指令的搭档。它擅长根据清晰的描述生成代码片段、补全函数实现、解释报错信息，但它不会替你做架构决策，也不会主动告诉你“这里应该用状态机而不是一堆 if-else”。所以整个项目的推进方式是这样的：我来定架构、拆模块、写接口定义，Codex 来填充具体实现、生成测试用例、优化重复代码。这种分工模式在五天半的时间里被验证是高效的，后面会结合具体例子说明怎么跟 Codex 配合最顺手。
这篇文章适合谁看？如果你是有一定编程基础、想尝试用 AI 辅助工具快速做出一个完整产品的开发者，这里的流程和经验可以直接参考。如果你是象棋爱好者，对技术实现感兴趣，也能从中学到棋类应用的核心逻辑是怎么跑起来的。如果你纯粹是被“七天上架”这个标题吸引进来的，那我可以先泼一盆冷水：时间紧不代表质量差，但确实需要你在项目开始前就想清楚哪些功能必须做、哪些可以砍掉。取舍比编码更重要。
2. 技术选型与架构设计：为什么这么搭
2.1 开发框架的选择逻辑
移动端开发框架的选择，直接决定了后续的开发效率和上架难度。我最终选的是 SwiftUI + Swift 的组合，原因有三层。第一层是性能，象棋的棋盘渲染和 AI 计算都需要一定的计算资源，原生框架在这方面的优势明显，尤其是 AI 搜索算法需要频繁调用底层计算，跨平台框架的桥接开销在这种场景下会被放大。第二层是上架流程，App Store 对原生应用的审核标准虽然严格，但流程成熟，文档齐全，遇到问题容易找到解决方案。第三层是 Codex 对 Swift 的支持程度，实测下来它对 SwiftUI 的声明式语法理解得相当到位，生成的代码结构清晰，很少出现语法层面的低级错误。
这里插一句关于跨平台框架的取舍。Flutter 和 React Native 当然也能做象棋应用，而且开发速度可能更快，但考虑到 AI 计算模块需要较高的执行效率，以及上架时可能遇到的兼容性问题，原生方案在这个项目里是更稳妥的选择。如果你只是想做一个小型工具类应用，跨平台框架完全够用，但涉及到实时计算和复杂状态管理的场景，原生框架的调试成本更低。
2.2 核心模块的拆分方式
整个项目被拆成了四个核心模块，每个模块的职责边界非常清晰。第一个是棋盘模型层，负责存储棋盘状态、棋子位置、走子历史，以及胜负判定。这一层是纯数据结构，不涉及任何 UI 逻辑，方便单独测试。第二个是走法生成层，负责根据当前棋盘状态，计算出某一方所有合法走法。这一层是 AI 搜索的基础，也是整个项目里最容易出 bug 的地方，因为象棋的走法规则虽然明确，但边界情况很多，比如将帅不能照面、马腿被蹩、象眼被塞这些细节，稍不注意就会漏掉。
第三个是 AI 搜索层，负责根据当前局面评估优劣，并选择最佳走法。这一层用的是经典的 Alpha-Beta 剪枝算法配合局面评估函数。评估函数的权重设计直接决定了 AI 的棋力水平，这部分后面会详细展开。第四个是 UI 层，负责棋盘绘制、棋子渲染、触摸交互、动画效果。SwiftUI 的 Canvas 和 Gesture 组件在这里派上了大用场，棋盘和棋子都是用代码绘制的，没有引入任何图片资源，这样既减小了包体积，也避免了不同分辨率下的适配问题。
模块之间的通信通过一个统一的 GameState 对象来管理，这个对象遵循 ObservableObject 协议，任何状态变化都会自动触发 UI 更新。这种单向数据流的架构在 SwiftUI 里是标准做法，Codex 对这种模式的代码生成准确率很高，基本上描述清楚需求后，它就能给出符合规范的实现。
2.3 为什么不用现成的棋类引擎
市面上有不少开源的象棋引擎，比如一些基于 C++ 的高性能实现，直接集成进来当然能省不少事。但我最终选择自己实现 AI 搜索层，原因有两个。第一是包体积和依赖管理，引入第三方引擎意味着要处理编译、链接、跨语言调用等一系列问题，在七天的时间约束下，这些额外的工作量不划算。第二是可控性，自己实现的搜索算法虽然棋力不如专业引擎，但每一行代码都清楚在做什么，调试和优化都有明确的方向。对于一款面向普通棋友的休闲应用来说，AI 棋力达到“中等偏上”的水平就足够了，不需要追求极致性能。
实际测试下来，在 iPhone 13 上，搜索深度设为四层时，AI 的平均思考时间在 0.3 到 0.8 秒之间，这个响应速度对于休闲对局来说完全可以接受。如果开到五层，思考时间会上升到 2 到 3 秒，棋力提升明显，但等待感也会增强。最终我把难度分成了三档，简单档搜索两层，中等档三层，困难档四层，让用户自己选择。
3. 核心逻辑实现：棋盘、走法与 AI 搜索
3.1 棋盘状态的数据结构设计
棋盘状态用的是一个 10x9 的二维数组，每个元素是一个可选的 Piece 枚举值。Piece 枚举包含了棋子的类型（将、士、象、马、车、炮、卒）和所属方（红方、黑方）。这种设计的好处是直观，任何时刻棋盘的状态都可以用一个数组完整描述，序列化和反序列化都很方便，棋谱记录和悔棋功能直接基于这个数组的快照来实现。
走子历史的存储用的是栈结构，每走一步就压入一个记录，记录里包含走子前的棋盘快照、走子方、起始位置、目标位置。悔棋的时候直接弹出栈顶记录，恢复棋盘快照即可。这里有个细节需要注意：如果只是记录走子动作而不记录棋盘快照，悔棋时需要反向推算棋盘状态，逻辑会复杂很多，而且容易出错。用空间换时间的做法在这里是值得的，一个棋盘快照的内存占用很小，即使记录几百步也不会对性能产生影响。
胜负判定逻辑放在棋盘模型层，每次走子后都会检查三个条件：将帅是否被吃、是否被将死、是否形成和棋局面。将帅被吃的判定很简单，检查棋盘上是否还存在对方的将或帅即可。将死的判定需要生成被将方的所有合法走法，如果没有任何走法能解除被将状态，就是将死。和棋的判定稍微复杂一些，需要检查是否出现重复局面、是否双方都没有进攻能力等情况。这部分逻辑 Codex 生成得很快，但需要仔细测试边界情况。
3.2 走法生成的规则细节
走法生成是整个项目里最考验细节的部分。每种棋子的走法规则不同，而且都有各自的限制条件。将和帅只能在九宫格内移动，每次一步，而且不能走出九宫格的范围。士只能在九宫格内斜走一步。象走田字，但不能过河，而且象眼被塞时不能走。马走日字，但马腿被蹩时不能走。车走直线，路径上不能有棋子阻挡。炮走直线，但吃子时必须隔一个棋子。卒只能向前走，过河后可以横走，但不能后退。
这些规则单独看都不复杂，但组合在一起，再加上边界条件的处理，代码量并不小。我的做法是给每种棋子写一个独立的走法生成函数，输入是当前棋盘状态和棋子位置，输出是所有合法目标位置的列表。然后在一个统一的入口函数里，根据棋子类型调用对应的生成函数，最后再过滤掉那些会导致己方被将的走法。这个过滤步骤很重要，因为有些走法虽然符合棋子本身的移动规则，但走完之后己方将帅会被将军，这种走法是不合法的。
Codex 在生成这些走法函数时表现不错，但有几个地方需要特别注意。一个是马腿的判定，马走日字时，如果马腿位置有棋子，就不能往那个方向走。这个判定需要根据目标位置反推马腿的位置，逻辑上有点绕，Codex 第一次生成的代码就漏掉了这个检查。另一个是炮的吃子逻辑，炮在移动时不能吃子，只有在吃子时才能隔一个棋子，这个区别需要在代码里明确区分。还有一个是将帅照面的规则，双方将帅不能在同一条直线上直接相对，中间必须有其他棋子阻挡，这个规则在走法生成和胜负判定里都要考虑到。
3.3 AI 搜索算法的实现与调优
AI 搜索层用的是 Alpha-Beta 剪枝算法，这是博弈树搜索的经典算法，在象棋这种零和博弈场景下效果很好。算法的核心思想是，在搜索过程中，如果发现某个分支的结果已经不可能优于之前找到的最优结果，就提前剪掉这个分支，不再继续搜索。这样可以大幅减少需要评估的节点数量，在同样的时间内搜索更深的层数。
局面评估函数是 AI 棋力的关键。评估函数的作用是给一个棋盘局面打分，分数越高表示对某一方越有利。我的评估函数考虑了以下几个因素：棋子价值、棋子位置、机动性、将帅安全。棋子价值用的是经典的分值表，车 9 分、马 4 分、炮 4.5 分、象 2 分、士 2 分、卒 1 分（过河后 2 分）。棋子位置的分值是根据棋子在不同位置上的活跃程度来定的，比如马在中心位置比在边角位置更有价值，炮在中路比在边路更有威胁。
机动性指的是某一方所有合法走法的数量，走法越多说明棋子越活跃，分数相应提高。将帅安全是一个比较复杂的评估项，需要考虑将帅周围是否有己方棋子保护、对方是否有棋子威胁到将帅等情况。这部分的分值权重需要反复调试，权重太高会导致 AI 过于保守，权重太低又会让 AI 忽视防守。
调优过程中我踩过一个坑：一开始评估函数的权重设置得比较随意，结果 AI 的表现很不稳定，有时候会走出一些莫名其妙的棋。后来我把评估函数的各个因素分开测试，先只保留棋子价值，确认搜索算法本身没问题，然后逐步加入位置、机动性、将帅安全等因素，每加入一个就测试一批局面，观察 AI 的走法是否合理。这种增量式的调优方式虽然慢，但每一步都有明确的反馈，比一次性调好所有参数要靠谱得多。
还有一个优化点是走法排序。Alpha-Beta 剪枝的效率很大程度上取决于走法的搜索顺序，如果先搜索那些更可能产生好结果的走法，剪枝的效果会更好。我的做法是给每个走法一个简单的启发式评分，比如吃子的走法优先搜索，移动到大价值位置的走法优先搜索，这样可以在不增加太多计算量的情况下提升剪枝效率。实测下来，加入走法排序后，同样搜索深度下的节点访问数量减少了大约百分之三十到四十。
4. UI 设计与交互实现：用代码画出棋盘
4.1 棋盘和棋子的绘制方案
SwiftUI 的 Canvas 组件是绘制棋盘的最佳选择。棋盘的本质是一个 9 列 10 行的网格，用 Canvas 的 drawLine 方法画出横线和竖线，再在九宫格位置画出斜线，最后加上楚河汉界的文字标注，整个棋盘的绘制代码不到一百行。棋子的绘制稍微复杂一些，每个棋子是一个圆形，里面写上对应的汉字，红方棋子用红色，黑方棋子用黑色。圆形的绘制用 drawEllipse 方法，文字的绘制用 drawText 方法，配合合适的字体和字号，视觉效果相当不错。
用代码绘制而不是用图片资源的好处很明显。首先是包体积，一套棋盘和棋子的图片资源至少需要几百 KB 到几 MB 的空间，而代码绘制的增量几乎可以忽略不计。其次是适配性，代码绘制的棋盘可以自动适应不同尺寸的屏幕，不需要为每种屏幕尺寸准备不同的图片。最后是可定制性，如果想换一种棋盘配色或者棋子样式，只需要修改几个颜色参数，不需要重新导出图片资源。
不过代码绘制也有一个缺点：复杂的视觉效果实现起来比较麻烦。比如棋子的立体感、阴影效果、选中时的高亮动画，这些用代码实现需要额外的绘制逻辑。我的做法是保持简洁，棋子用纯色填充加边框，选中时改变边框颜色和粗细，走子时用一个简单的平移动画。这种简洁的风格反而更符合象棋应用的调性，不需要花哨的视觉效果。
4.2 触摸交互与走子逻辑
触摸交互的处理是 UI 层的核心。用户点击棋盘上的某个位置时，需要判断这个位置是否有棋子、是己方棋子还是对方棋子、当前是否轮到这一方走子。如果点击的是己方棋子，就选中这个棋子，并高亮显示所有合法走法。如果点击的是合法走法的目标位置，就执行走子操作。如果点击的是其他位置，就取消选中状态。
这个交互逻辑看起来简单，但实际实现时需要考虑很多细节。比如用户点击了一个己方棋子，然后又点击了另一个己方棋子，这时候应该切换选中状态而不是报错。再比如用户点击了一个合法目标位置，但走子之后会导致己方被将军，这种走法在走法生成阶段就已经被过滤掉了，所以不会出现在高亮显示里。还有拖拽走子的交互方式，虽然更直观，但实现起来比点击走子复杂不少，在时间有限的情况下，我选择了点击走子的方案。
走子动画用的是 SwiftUI 的 withAnimation 方法，给棋子的位置变化加上一个短暂的动画效果。动画时长设为 0.2 秒，既能让用户感知到走子动作，又不会拖慢对局节奏。吃子的时候，被吃的棋子用一个淡出动画消失，视觉上比较自然。这些动画效果虽然简单，但对用户体验的提升很明显，让整个应用感觉更精致。
4.3 棋谱记录与悔棋功能
棋谱记录用的是标准的象棋记谱法，比如“炮二平五”“马八进七”这种格式。实现方式是在每次走子后，根据起始位置和目标位置计算出对应的记谱字符串，然后追加到棋谱列表里。记谱法的规则需要仔细处理，比如同一条线上有两个相同的棋子时，要用前、后来区分，这个逻辑 Codex 生成得基本正确，但需要手动测试几个边界情况。
悔棋功能的实现基于之前提到的走子历史栈。用户点击悔棋按钮时，弹出栈顶记录，恢复棋盘快照，同时把棋谱列表的最后一条记录删掉。如果是人机对战模式，悔棋需要连续弹出两条记录，因为需要同时撤销玩家和 AI 的走子。这个逻辑在实现时容易出错，我一开始就忘了处理人机对战的情况，结果悔棋后轮到 AI 走子，但 AI 又走了一步，导致棋盘状态混乱。后来加了一个判断，如果当前模式是人机对战，悔棋时连续弹出两条记录，问题就解决了。
棋谱的展示用的是 List 组件，每一步棋显示一行，包含步数、走子方、记谱字符串。点击某一步棋可以跳转到那个局面，这个功能对于复盘很有用，实现方式是保存每一步的棋盘快照，点击时直接恢复对应的快照。这个功能在测试阶段发现了一个问题：如果棋谱很长，保存所有快照会占用较多内存。后来改成了只保存最近二十步的快照，更早的快照按需重建，内存占用就降下来了。
5. 上架流程与审核要点：从打包到通过
5.1 上架前的准备工作
App Store 上架需要准备的材料比想象中多。首先是应用图标，需要准备多种尺寸的版本，从 20x20 到 1024x1024 不等。我用的是一个简单的象棋棋子图标，用代码生成不同尺寸的版本，确保在各种设备上都能清晰显示。其次是截图，需要提供至少三张不同尺寸的截图，展示应用的主要界面和功能。截图的内容要真实反映应用的实际效果，不能过度美化或者展示未实现的功能。
应用描述和关键词的填写也有讲究。描述要简洁明了，突出核心功能，避免堆砌关键词。我写的描述大概是这样：一款干净纯粹的中国象棋应用，支持人机对战和双人对战，没有广告和内购，适合随时来一盘。关键词选了“中国象棋”“象棋”“单机象棋”“人机对战”这几个，覆盖了主要的搜索场景。分类选的是“游戏-棋类”，这个分类下的竞争虽然激烈，但目标用户更精准。
隐私政策的准备是很多独立开发者容易忽略的环节。即使应用不收集任何用户数据，也需要提供一份隐私政策说明。我的做法是写一份简单的声明，说明应用不收集任何个人信息，所有数据都存储在本地设备上。这份声明放在应用的设置页面里，同时在 App Store 的隐私信息填写环节如实申报。
5.2 打包与测试的注意事项
打包用的是 Xcode 的 Archive 功能，选择 Release 配置，确保开启优化。打包前需要检查几个关键点：版本号和构建号是否正确、签名证书是否有效、依赖库是否都正确链接。我第一次打包时就遇到了签名问题，原因是证书过期了，重新生成证书后解决。这个问题在 Codex 的帮助下排查得很快，把报错信息贴给它，它直接指出了证书相关的问题。
TestFlight 测试是上架前的最后一道关卡。我邀请了十几个朋友帮忙测试，收集到的反馈主要集中在两个方面：一是 AI 的思考时间在旧设备上偏长，二是个别棋子的走法规则有误。第一个问题通过降低旧设备的搜索深度解决，第二个问题通过补充测试用例修复。TestFlight 的测试周期建议至少留出两天，因为反馈收集和修复需要时间，而且 TestFlight 的构建处理本身也需要等待。
5.3 审核过程中的常见问题
App Store 的审核周期通常是 24 到 48 小时，但首次提交可能会更长。我这次提交后大约 36 小时收到了审核结果，是一次通过的。审核过程中没有遇到被拒的情况，但根据其他开发者的经验，棋类应用常见的被拒原因有几个：一是元数据不完整，比如截图不符合要求、描述里有误导性内容；二是功能不完整，比如有按钮点击没反应、有崩溃问题；三是版权问题，比如使用了未经授权的棋谱或棋局数据。
为了避免这些问题，我在提交前做了几件事：反复检查了所有界面的按钮和交互，确保没有死链接；用不同型号的模拟器跑了完整的对局流程，确认没有崩溃；棋谱数据用的是自己生成的示例数据，没有使用任何第三方来源。这些准备工作虽然繁琐，但比起被拒后重新提交，前期的投入是值得的。
6. 踩坑记录与经验总结
6.1 开发过程中遇到的典型问题
第一个坑是走法生成的边界情况。前面提到过马腿和炮的吃子逻辑，但还有一个更容易忽略的问题：将帅照面的判定。这个规则在走法生成和胜负判定里都要用到，但两处的判定逻辑不完全一样。走法生成时，如果走子后导致将帅照面，这个走法是非法的；胜负判定时，如果当前局面已经将帅照面，说明之前的走子有问题。我一开始把这两处的逻辑写混了，导致 AI 有时候会走出让将帅照面的棋。后来把判定逻辑抽成一个独立的函数，两处都调用这个函数，问题就解决了。
第二个坑是 AI 搜索的性能问题。在旧设备上，搜索深度开到四层时，思考时间会超过两秒，用户体验明显下降。我的优化方案是加入迭代加深，先搜索两层，如果时间还有余，再搜索三层，以此类推。这样在性能较弱的设备上，AI 会自然地选择较浅的搜索深度，保证响应速度。这个优化思路是 Codex 建议的，实现起来也不复杂，效果立竿见影。
第三个坑是 UI 的适配问题。SwiftUI 的布局系统在不同尺寸的屏幕上表现不一样，我一开始用的是固定尺寸的棋盘，结果在 iPad 上棋盘只占了屏幕的一小部分，在 iPhone SE 上又超出了屏幕范围。后来改用 GeometryReader 动态计算棋盘尺寸，根据可用空间自动调整，适配问题就解决了。这个问题的教训是，不要假设屏幕尺寸，要用相对布局而不是绝对布局。
6.2 与 Codex 配合的实用技巧
跟 Codex 配合了五天半，总结出几条实用技巧。第一条是描述需求时要具体，不要只说“实现一个走法生成函数”，而要说“实现一个函数，输入是棋盘数组和棋子位置，输出是所有合法目标位置的列表，需要考虑马腿、象眼、炮的隔子吃子这些规则”。描述越具体，Codex 生成的代码越接近可用状态，后续修改的工作量越小。
第二条是遇到报错时把完整的错误信息贴给 Codex，不要只贴一行。Codex 需要上下文才能准确判断问题所在，完整的错误信息包括调用栈、错误类型、相关代码行，这些信息越全，它给出的修复建议越准确。我遇到过一个内存访问越界的问题，只贴了错误类型时 Codex 给的建议比较泛，后来把调用栈和相关代码一起贴上去，它直接指出了数组索引越界的位置。
第三条是让 Codex 生成测试用例。走法生成和胜负判定这些逻辑，光靠人工测试很难覆盖所有边界情况。我让 Codex 根据走法规则生成了一批测试用例，包括各种棋子的正常走法、边界走法、非法走法，然后跑这些测试用例来验证实现的正确性。这个方法帮我发现了好几个隐藏的 bug，效率比手动测试高很多。
6.3 七天上架的时间分配建议
如果让我重新安排这七天，时间分配大概会是这样：第一天做技术选型和架构设计，把模块拆分和接口定义确定下来；第二天到第四天集中编码，先实现棋盘模型和走法生成，再实现 AI 搜索，最后做 UI；第五天调试和优化，重点测试边界情况和性能；第六天准备上架材料，包括图标、截图、描述、隐私政策；第七天提交审核并处理反馈。这个分配的关键是编码时间要留足，不要低估调试的工作量，实际调试花的时间往往比编码还多。
还有一个建议是，功能要砍到最少可用集。我一开始想做的功能很多，包括在线对战、残局挑战、棋谱分享等等，后来砍掉了在线对战和棋谱分享，只保留了人机对战、双人对战、悔棋、棋谱记录和残局挑战。即使这样，残局挑战也是在最后一天才勉强做完的。如果时间更紧，残局挑战也可以砍掉，核心功能就是人机对战和双人对战，这两个做好了，应用就有基本的使用价值。
7. 这个项目后续还能怎么扩展
上架不是终点，只是一个节点。这个项目后续有几个明确的扩展方向。第一个是增加更多的残局关卡，目前只做了十个残局，数量偏少，可以扩充到五十个甚至一百个，增加用户的留存时间。残局数据的格式是固定的，只需要准备棋局数据，代码层面不需要改动。第二个是增加棋力评估功能，在对局结束后给用户一个简单的评分，指出哪些走法比较好、哪些走法有问题。这个功能需要额外的分析逻辑，但技术上可行。
第三个方向是增加棋谱导入导出功能，让用户可以把自己下的棋保存下来，或者导入别人的棋谱进行复盘。这个功能需要定义棋谱的文件格式，以及实现解析和序列化的逻辑。第四个方向是适配更多平台，目前只做了 iOS 版本，Android 版本可以用 Kotlin 重写核心逻辑，UI 层用 Jetpack Compose 实现，AI 搜索层的算法是通用的，只需要做语言层面的移植。
不过这些都是后话，眼下最重要的是把当前版本维护好，收集用户反馈，修复发现的问题。独立开发者的精力有限，与其铺开做很多功能，不如把一个功能做精。象棋应用的核心价值在于对局体验，AI 的棋力、响应速度、交互流畅度，这些才是用户真正在意的。把这几件事做好，比增加十个花哨的功能更有意义。
