2026 秋软件工程个人作业（第二次）

项目	内容
这个作业属于哪个课程	H202601软件工程与软件工程实践
这个作业要求在哪里	2026 秋软件工程个人作业（第二次）
这个作业的目标	使用 Python 独立开发一款点击式箭头解谜小游戏，掌握界面设计、交互处理、游戏状态管理与算法实现
学号	102402114
姓名	谢慧彬
github链接	https://github.com/Xasteroid-star/ruan_task

---

「一箭又一箭」小游戏开发博客

一、项目展示

视频链接https://pan.baidu.com/s/19k6zobYbtqXqGIILElq1Xg?pwd=zxmg

开始界面

游戏界面

碰撞反馈

箭头飞出

通关界面

失败界面

二、项目介绍

游戏规则

「一箭又一箭」是一款点击式箭头解谜小游戏，规则非常简单：

1. 棋盘是一个网格，格内放有朝向上、下、左、右四个方向的箭头；
2. 点击某个箭头：若它朝向前方到棋盘边界之间没有其他箭头阻挡，箭头就飞出棋盘并被消除；
3. 若路径上有其他箭头阻挡，则无法消除，箭头会抖动变红提示碰撞，并消耗一次失误机会；
4. 清空当前关卡全部箭头即可进入下一关；失误次数耗尽则本关失败，可重新开始。

界面设计

界面整体采用浅色简洁风，参考了微信小游戏《一箭又一箭》：暖白渐变背景、白色棋盘面板、深色细线箭头、碰撞时变红。界面分三个区域：

• 顶部信息栏：左列显示关卡名、剩余箭头数、剩余失误次数，右列显示累计得分和用时；
• 中部棋盘：白色圆角面板，箭头悬停时格子高亮；
• 底部工具栏：撤销、提示、AI 求解、重新开始、保存五个按钮。

主要功能与特色

在基础玩法之上，额外实现了以下功能：

• 撤销上一步：可回退「成功飞出」或「碰撞失误」，自动恢复箭头或返还失误次数；
• 提示功能：高亮当前任意一个可安全飞出的箭头；
• AI 自动求解：一键按求解顺序自动消除全部箭头，直接通关演示；
• 计时 / 得分 / 星级：每关计时，按失误与用时结算单关得分与 1~3 星评价，累计总分；
• 音效：飞出、碰撞、通关、失败等程序化合成音效（无外部素材，不涉及版权）；
• 保存进度：进度写入本地 save.json，主界面可「继续游戏」。

三、实现思路

数据表示

• 方向 Direction（models.py）：一个枚举，值为行进方向向量 (dr, dc)，如 UP = (-1, 0)、RIGHT = (0, 1) 等；
• 箭头 Arrow（models.py）：冻结数据类，包含网格坐标 (row, col) 与朝向 direction；
• 关卡 Level（models.py）：网格行列数、箭头列表、允许失误次数；
• 棋盘 Board（board.py）：用字典 {位置: 箭头} 保存剩余箭头，click() 处理点击命中、消除与失误判定，并维护撤销历史；
• 游戏流程 Game（state.py）：状态机（开始/游戏中/通关/全部通关/失败）+ 关卡推进 + 计时计分 + 存档序列化。

路径检测方法（重点）

路径检测是本游戏的核心算法，位于 pathing.py，全部写成无 pygame 依赖的纯函数，便于单元测试。判断一个箭头能否飞出，只需检查它前进方向上、到棋盘边界之间的所有格子是否还有其他箭头：

def cells_in_front(arrow, rows, cols):
    """返回箭头前进方向上、到棋盘边界之间的所有网格坐标（不含自身）。"""
    dr, dc = arrow.direction.vector
    cells = []
    r, c = arrow.row + dr, arrow.col + dc
    while 0 <= r < rows and 0 <= c < cols:
        cells.append((r, c))
        r += dr
        c += dc
    return cells

def can_fly(arrow, remaining, rows, cols):
    """前进路径上没有其他箭头即可飞出。"""
    return all(pos not in remaining for pos in cells_in_front(arrow, rows, cols))

例如 → · · ↑ · 中第一个箭头朝右，其右侧还有箭头，因此 can_fly 返回 False；而 ↑ · · · → 中最后一个箭头朝右，右侧无箭头，返回 True。

在此基础上，我又实现了一个「剥洋葱」式贪心求解器 solve()：只要当前存在路径畅通的箭头就消除它，因为消除箭头只会让更多箭头变得可消除，所以贪心能保证找到顺序当且仅当关卡可解。这个求解器同时服务于「AI 自动求解」「提示」和关卡可解性校验，一石三鸟。

四、AIGC 使用过程

本次开发借助 Claude Code 完成，下面是 4 次有代表性的协作记录：

子任务	借助何种 AIGC 技术	AI 实现或提供了什么	效果如何	人工修改
架构与路径检测	Claude Code	分层目录（models/pathing/board/levels/state/renderer），实现四方向路径检测与「剥洋葱」贪心求解器	四方向、边界、阻挡判断均正确	把 find_clear_order 重构为更通用的 solve()，供 AI 演示与提示复用
附加功能	Claude Code	撤销栈、提示、AI 自动求解、计时计分星级、本地存档、程序合成音效	功能全部跑通，集成测试通过	音效改为程序合成，避免版权问题
界面优化与视觉改版	Claude Code	三段式布局 + 浅色简洁主题 + 背景点阵纹理与箭头水印	布局清晰，风格接近微信原版	反馈「背景太空」后补加纹理装饰
测试与 Bug 修复	Claude Code	30 个单元测试；修复中文字体加载、数组越界、关卡不可解等问题	30 个测试全部通过	逐条核对断言，覆盖作业关键点

以下选择3个协作过程记录。

协作一：需求解析与项目骨架初始化

我的 Prompt（指令）：

根据我的要求文档在仓库根目录建 AGENTS.md，写项目总规则，制定这个项目架构，启用planning模式`

AI 的执行过程：
AI 首先阅读了 要求.txt，并没有急于生成代码，而是主动执行了 Bash 指令来探查当前仓库状态（发现当前目录还没有 .git，且没有 commit）。随后，AI 自动切换到了 Planning 模式，开始梳理项目结构。

我的思考与收获：
使用 AI 的 Planning 模式。它“先探索、后设计”的思维方式非常像人类架构师。它自动总结出这是一个全新的空项目，并生成了 AGENTS.md 文件，为后续的代码生成定下了基调（如规定了 Pygame 图形库、目录结构、代码规范等）。这让后续的代码生成非常规范，避免了 AI 随意发挥。

协作二：技术选型与架构设计

Planning模式：
AI 会询问使用哪个 Python 图形库时，以及实现范围等，需要人工选择。

AI 的执行过程：
AI 随后生成了详细的实现计划，包括：

1. 环境准备：明确了需要 Python 3.9.25 以及 pygame、pytest。
2. 目录结构：极其清晰地划分了模块，将纯数据模型（models.py）、路径检测纯函数（pathing.py）、游戏主逻辑（board.py）与渲染层（renderer.py）解耦。
3. 核心设计：给出了箭头、方向和关卡的数据模型设计思路。

我的思考与收获：
在这个阶段，我看到了 AI 在架构设计上的优势。如果我自己写，很容易把所有逻辑塞进一个 main.py 里。AI 划分的 game/ 目录结构和 tests/ 单元测试目录，符合软件工程的高内聚低耦合原则。尤其是将路径检测单独放在 pathing.py，极大地方便了后续写单元测试。

协作三：功能扩展规划与界面优化

Planning模式

你提到的「前端页面布局」我理解为游戏界面（开始/游戏/通关/失败各屏）的布局优化。在动手前，我想确认一下你希望优先实现哪些附加功能（这会明显影响工作量和改动范围）。

AI 的执行过程：
AI 准确理解了当前项目已经跑通基础要求，并给出了清晰的附加功能菜单供我勾选（撤销+提示+AI求解、计时+得分+星级、更多关卡、音效+保存进度等），并且给出了工作量和改动范围的评估。

我的思考与收获：
在基础功能达标后，很容易陷入盲目堆砌功能的误区。AI 通过选择题的方式，引导我根据“工作量和改动范围”来评估功能优先级。我最终根据课程要求（基础功能的完整性和正确性优先），有选择地实现了“撤销+提示”和“计时+星级”功能。这种受控的 AI 协作，让项目迭代非常有序。

五、测试结果

采用自动化测试（python -m pytest tests/ -v）与逐关手工试玩相结合，覆盖作业要求的全部测试项：

编号	测试内容	预期结果	实际结果	是否通过
T01	点击前方无阻挡的箭头	箭头飞出棋盘并消失	一致	✅ 通过
T02	点击前方有阻挡的箭头	箭头不消失，失误次数减 1	一致	✅ 通过
T03	点击位于边缘且朝向棋盘外的箭头	箭头正常消失，不发生越界错误	一致	✅ 通过
T04	消除本关全部箭头	显示通关并进入下一关	一致	✅ 通过
T05	失误次数耗尽	显示失败并允许重新开始	一致	✅ 通过
T06	游戏进行中重新开始	箭头布局和失误次数恢复	一致	✅ 通过

以上 6 项均有对应的自动化测试用例（tests/ 目录共 30 例，全部通过），分布如下：

测试模块	用例数	覆盖内容	是否通过
test_pathing.py	9	四方向路径检测、边界、阻挡、题目示例	✅ 通过
test_levels.py	4	关卡数量、可解性、箭头合法性、失误次数	✅ 通过
test_board.py	5	飞出移除、碰撞扣失误、清空/失败判定	✅ 通过
test_game_flow.py	3	通关全流程、失败、重开复位	✅ 通过
test_features.py	9	撤销/提示/求解/计分/存档	✅ 通过

除自动化测试外，我也逐关手工试玩，确认每个关卡都存在合理通关顺序（4 关均可通关）。

六、PSP 表格

阶段	预计耗时（h）	实际耗时（h）
需求分析与设计	2	2.5
核心玩法（棋盘 / 箭头 / 路径检测）	4	4
界面与渲染	3	4
状态机与关卡	2	2
附加功能（撤销/提示/AI/计分/存档/音效）	5	6
测试与调试	3	3.5
文档与博客	2	2.5
合计	21	24.5

七、心得体会

这次作业让我完整经历了一个小游戏从 0 到 1 的开发过程，也真实体会到了 AIGC 工具的强项与局限。

AI 带来的帮助：最大的帮助是把「重复且容易出错」的细节交给它——四方向的路径检测、动画帧管理、按钮命中区域、中文系统字体兼容这类繁琐代码，AI 都能快速给出可运行、可测试的实现，让我能把精力放在游戏设计和需求理解上。尤其是「剥洋葱」式贪心求解器的正确性，AI 讲清楚后，一个求解器就同时支撑了 AI 演示、提示和关卡校验三个功能，代码复用度很高。

出现的问题：AI 的代码并非拿来即用。开发中先后遇到了 Windows 字体加载异常、某个关卡实际不可解、深色主题下提示文字对比度不够等问题，这些都需要我实际运行、试玩才能发现。另外 AI 有时会「想当然」，比如一开始把「前端」理解成网页，经沟通后才确认是游戏界面本身。

自己的收获：一是学会了把「界面 / 交互 / 状态 / 算法」分层解耦，让核心逻辑可独立测试；二是认识到测试是 AI 协作的锚点——只要把单元测试写清楚，就能快速发现 AI 代码的问题并放心重构；三是明白 AIGC 是「放大器」而不是「替代者」，最终对代码的理解、试玩验证和方向判断仍然得靠人自己完成。