基于计算机视觉的冒险岛怀旧服（国服）自动练级脚本。不读取游戏内存，只截取游戏窗口画面、识别怪物与角色位置，再模拟键盘操作控制角色。

「我只想用，不想碰代码」→ 看 用户版说明 那里是下载、安装、首次配置、常见问题的完整图文步骤，不含任何源码内容。

不想装 Python？ 直接下载免安装版（Windows 64 位，解压即用）： ⬇ MapleStoryAutoLevelUp-CN v1.0

免安装包是 PyInstaller 打包的 --onedir 目录，必须整个文件夹解压后使用，不要只拿 exe。

本页（README.md）是给开发者看的：源码运行、打包发版、配置体系、项目结构。

本项目是 MapleStoryAutoLevelUp（台服 Artale 版，MIT）的国服怀旧服 fork。 国服客户端是 Unity 重制版，与台服差异较大，本 fork 做了针对性改造，详见下文「与上游的差异」。

这个项目最初是应朋友之托写的挂机脚本 —— 结果好不容易做完了，他怕封号，一直没敢用。我自己也弃坑得比较早，角色只练到 25 级就没再玩了。

开发期间一直拿自己的账号边测边改，前后测了大约一个星期，账号到现在还是正常的 —— 不过这只是我一个人的样本，仅供参考，不代表你的号也一定安全。

另外要说明的是：我本机的依赖环境是完整装好的，所以没法复现「一台干净机器上第一次安装运行」会遇到什么。因此初次使用很可能碰到各种 bug，我会持续修，也欢迎提 issue —— 只是请多担待。

请自行评估风险。使用本工具造成的任何后果由使用者自负（详见文末免责声明）。

一句话：它叫 Interception，是一个开源、免费、公开可审计的键盘鼠标驱动，装机量很大（大量自动化测试、按键精灵类需求都在用），不是外挂作者写的黑箱。 它不做任何联网、不读游戏内存、也不藏在暗处，装完之后就是一个普通驱动，你在设备管理器里能直接看到它。装它是为了「发按键」，不装发不出去 —— 就这么一个用途。

先说清楚这个工具是怎么操作的：它不读游戏内存、不改游戏文件，做法跟人一样 —— 看游戏画面 → 认出怪和自己在哪 → 按键盘。

问题就出在最后一步「按键盘」。

背景：上游台服版用的是 KMbox，一种需要单独花钱买的硬件外设（插在电脑上的一个盒子，由它替你在硬件层面"冒充"键盘）。台服能用，是因为人家走的是这条路。

我试下来发现，用 Interception 这个软件驱动方案可以绕开 KMbox —— 不需要额外买任何硬件，装一个驱动就够。这是本 fork 相对上游最大的实现差异之一，也正是它「免安装包解压即用」的前提。

那为什么普通按键不行？

Windows 有两套发按键的路子：

打个比方：普通模拟按键像是别人替你签了个名，笔迹不对就会被认出来；Interception 则是把签名这个动作本身交给了系统底层去做，系统收到时它和真人签的没有区别。

所以不装驱动会怎样？程序照常能打开、也能点「开始」，但按键一个都送不进游戏 —— 表现就是「角色一动不动」。这不是 bug，是这一步没做。

这是你最该关心的，逐条说：

• 开源可审计：Interception 的源码、二进制、安装包全部公开放 在 GitHub（oblitum/Interception，MIT/BSD 类宽松协议，star 上万），世界上任何人可以去看它到底干了什么。它没有闭源部分，也不是破解版；
• 不做坏事：它不联网、不上传数据、不采集你的账号信息。它的功能就是把按键送进系统，仅此而已 —— 一个只干这件事的驱动，没有别的地方可用；
• 可卸载、可回滚：装错了、不想要了，用同一条命令 install-interception.exe /uninstall 就能卸掉，重启即恢复；
• 它不是外挂本体：驱动只管"发按键"，判断打哪只怪、走哪条路线的逻辑在本程序里。驱动本身不知道你在玩什么游戏，你把它装在记事本上也是同样的用法。

它和游戏外挂的本质区别：内存挂、注入挂要钻进游戏进程去改数据，那种才危险。Interception 从头到尾没碰游戏进程一个字节，它只是让系统按了几下键盘。

⚠️ 必须说明的一点：驱动本身安全，不代表用它玩游戏就不违规。游戏官方禁止的是"自动化操作"这件事，不在于你用什么方式实现。它是驱动还是 KMbox，对封号判定没有豁免作用 —— 这一点请务必知悉，风险仍由你自己评估。

这一步不能跳过。 驱动是独立的，装完程序还要单独装它一次。

1. 打开 https://github.com/oblitum/Interception/releases/latest ，下载 Interception.zip 并解压；
2. 进解压出来的文件夹，在地址栏输入 cmd 回车（用管理员身份打开命令提示符）；
3. 执行：

   install-interception.exe /install
   

4. 重启电脑（不重启不生效），再打开本程序。

装对了的话，程序日志里不会再出现 Interception 初始化失败。

✅ Win11 上看到报错别慌：安装时如果最后卡在 Could not write to \system32\drivers，这其实是装成功了，不用重试也不用管它。这个报错是安装器写完驱动后清理临时文件失败留下的（上游 issue #215），驱动本体已经就位——直接重启电脑，然后开本程序验证即可。判断装没装成的唯一标准是：程序日志里不再出现 Interception 初始化失败，以这个为准，不要以安装时的报错为准。

💡 从 v1.0.6 起，驱动没装的话，你点「开始」时程序会直接弹窗告诉你怎么装，不用自己找。

⚠️ 极少数机器装完会出现键鼠异常。万一遇到：开机进安全模式，删掉 C:\Windows\System32\drivers\ 下的 keyboard.sys 和 mouse.sys 即可恢复。装之前先记一下这条。

想卸载：install-interception.exe /uninstall，然后重启。

仓库本身只放源码，不放 exe —— PyInstaller 的成品有 250MB，超过 GitHub 单文件 100MB 硬限，且二进制进 git 历史会让仓库迅速膨胀。成品一律走 Release 附件。

国服客户端与台服 Artale 不是同一套东西，以下改造不是可选优化，而是必须：

• Windows 10 / 11（不支持虚拟机，也不支持 macOS）
• Python 3.12
• 依赖见 requirements.txt：

pip install -r requirements.txt

其中 interception-python 用于内核级按键模拟，需要管理员权限运行；windows-capture 用于抓帧。

⚠️ 两个依赖的门槛不一样，别混为一谈（2026-09-27 实测确认）：

用途	依赖	额外要装系统组件吗
发按键	interception-python	要 —— 它是内核驱动的 Python 封装，光 pip 装包不够，还得单独下载安装 Interception 驱动 并重启电脑
看画面	windows-capture + opencv-python	不要 —— windows-capture 调的是 Windows 自带的 Graphics Capture API，opencv 是纯算法库（只处理内存里的图片数组）

缺驱动的症状是「程序能开、能点开始，但角色一动不动」——见 src/input/InterceptionController.py 的 driver_status()。 抓帧唯一的限制是游戏必须窗口模式（系统接口抓不到独占全屏），与驱动无关。

一句话：游戏要窗口化 + 1366x768 + Windows 缩放 100%，三条都满足才能用自动喝药。

为什么这么严：自动喝药靠"看画面上的血条"来判断。血条的位置是一个像素一个像素量出来的，窗口大小或缩放一变，量的位置就不对了，读出来的血量就是错的。与其让它读错，不如把环境卡死在一套量准了的配置上。

游戏的最大化按钮是灰的、点不了，不用管；全屏不行 —— 全屏会直接使用显示器的物理分辨率，就不是 1366x768 了。

环境的这三条不同时满足时，工具会拦住并告诉你该怎么改（不会悄悄读错）。不满足时挂机打怪照常，只是不自动喝药。

如果工具提示"游戏画面大小不对"，把上面三条逐条对一遍即可 —— 尤其注意缩放 100% 这一条，多屏用户的画面尺寸对不上多半是它造成的。

用免安装包的跳过这一节 —— 你要做的是 用户版说明 里的四步。

1. 启动国服怀旧服客户端，切换到窗口模式
2. 打开游戏左上角的小地图（角色定位依赖它）
3. 把角色走到要挂机的地图
4. 双击 启动界面.bat，在主界面「配置方案」里调好按键与地图
5. 按 Start 或 F1 开始

界面没反应时双击 诊断启动.bat，它用带控制台的 Python 启动，报错会留在窗口里。

首次使用需要自己做模板：monster/（怪物模板）、minimaps/（地图与路线）、nametag/（角色名标签）三个目录出厂是空的。上游台服的模板与国服画面不通用，必须用本项目的工具从国服真机截图重做。界面上的 F2（标定名字）/ F3（截怪）/ F4（录路线）就是干这个的 —— 这四步的面向用户版说明见 README_用户版.md。

三个 bat 都不写死 Python 路径，按以下顺序自动查找：环境变量 MAPLEBOT_PY → PATH 里的 pythonw.exe / python.exe。想固定用某个虚拟环境：

setx MAPLEBOT_PY "D:\你的venv\Scripts\pythonw.exe"

python -m src.main          # 带界面（推荐）

不带界面：

python -m src.engine.MapleStoryAutoLevelUp
python -m src.engine.MapleStoryAutoLevelUp --cfg my_config   # 指定配置
python -m src.engine.MapleStoryAutoLevelUp --disable_viz     # 关掉调试视窗
python -m src.engine.MapleStoryAutoLevelUp --record          # 录制调试视窗

快捷键：F1 暂停/继续，F2 截图（存 screenshot/），F12 退出。

产物是 --onedir 目录，整个文件夹拷走才能用（只拷 exe 会因为找不到资源目录而失败，原因见 src/utils/paths.py）。

⚠️ 发版前必须先过 CI 门禁（2026-09-27 加，因一次真实翻车）：

python -m tools.verify_ci_green

它按当前 commit 的 sha 查最近一次 CI，只有结论是 success 才放行。 不是 success（含还在跑、查不到、failure）一律拦住并指出怎么查。

为什么必须这一步：本地 13 项自检绿 不代表 CI 绿 —— 本地有 CI 环境没有的文件（典型：config/config_data.yaml 是用户数据、 不进仓库），这类问题本地永远测不出来。2026-09-27 发 v1.1.0-beta.1 时 就是"本地绿 → 直接发版 → CI 随后变红"，说明发版流程里当时没有看 CI 这一步。 ⇒ 现在做成机器检查，不靠人记得去点 Actions 页面。

完整包约 106MB，但其中 250MB+ 是 Python 运行时与第三方库（_internal/），我们自己的代码只有约 6MB（内嵌在 exe 里）。所以小改动不该让用户重下整个包 —— 发版时两个都传：

# 1) 打完整包（照常）
python -m tools.make_release_zip "dist/冒险岛自动练级" "MapleStoryAutoLevelUp-CN-vX.Y.Z.zip"

# 2) 生成增量补丁（只含变化的文件，实测约 6MB）
#    ★ 用 --universal：一份覆盖**所有**比 --to 旧的版本，
#      不必为 v1.0 / v1.0.1 / v1.0.2 各发一份（那只会让用户困惑）。
#      原理：业务代码（600+ 模块）全内嵌在 exe 里，补丁整包替换 exe，
#      所以不论从哪个旧版本出发，需要的东西完全一样。
python -m tools.make_patch --to v1.0.3 --universal \
    --dist "dist/冒险岛自动练级" --out "patch-to-vX.Y.Z-universal.zip"

# 3) 两个附件一起传
gh release upload vX.Y.Z MapleStoryAutoLevelUp-CN-vX.Y.Z.zip patch-to-vX.Y.Z-universal.zip

补丁 zip 里含 patch.json（版本、适用版本清单、sha256）和 应用补丁.bat（老用户双击即完成覆盖，会先把被覆盖的文件备份到 _backup_补丁前）。

两条硬约束（脚本会自检并拒绝违规的补丁）：

1. 依赖有变化时不许发补丁（requirements.txt 等变过）—— 那时用户 _internal/ 里的库对不上，必须走完整包。--universal 会逐个检查所有旧版本。
2. 补丁文件必须放在 zip 的子目录 _补丁文件/ 里，不能与用户程序同级 —— 同级会导致「解压即覆盖」：用户还没双击 bat，程序就被改了，备份拿到的是新文件（还原无意义），且解压中断会留下半新半旧的损坏安装（2026-09-27 实测复现）。

补丁不会包含用户自己的数据：config/config_custom.yaml、config/config_data.yaml、log/、minimaps/、monster/、nametag/ 一律排除，覆盖升级不会毁掉配置和路线。

• config/config_default.yaml —— 全部默认值与注释说明（基准，一般不改）
• config/config_custom.yaml —— 用户配置的出厂回退值
• config/config_data.yaml —— 地图 / 怪物登记表（录完路线、截完怪会自动写入）
• 主界面「配置方案」另存的自定义方案（如 config/你的方案名.yaml）—— 个人数据，不要提交到仓库，.gitignore 已按规则挡住

配置的加载语义是深合并：config_default.yaml 铺底，你的方案覆盖改过的键。所以方案文件里只写你改过的项就够了。

路线录制的操作键位：

录完的原始路线通常不够好，需要用画图工具微调；tools/homeRouteDrawer.py 提供了界面化的回正线绘制。

tools/verify_*.py 是一批离线自检，不开游戏也能验证核心逻辑：

python -m tools.verify_load_config        # 配置加载链路（异常不静默）
python -m tools.verify_navigation         # 导航与路线
python -m tools.verify_home_route         # 回正线
python -m tools.verify_recorder_action    # 录制器动作读取
python -m tools.verify_bars_potions       # 血蓝监控 + 自动喝药（含"不在前台不发键"回归）
python -m tools.verify_ci_green_check     # 发版门禁的判据本身（离线，不联网）

CI 里登记的那批在 .github/workflows/ci.yml，改动 src/ 后请一并跑一遍。

• 使用问题、报错、跑不动 → 先看 用户版说明（有完整排查步骤），再考虑开 issue，务必附日志文件；
• 想提问、提建议、聊两句 → 都去 Discussions，已置顶发帖指引；
• 怎么分 → 需要改代码的走 issue；只是想问点什么的走 Discussion。这样 issue 列表里留下的才是真 bug。

• 本项目基于 kenyu910645/MapleStoryAutoLevelUp（MIT License，Copyright (c) 2025 Ken Yu）修改而来，遵循同一 MIT 协议。
• 血蓝监控 + 自动喝药的三个核心模块（src/utils/bars.py、src/utils/bar_smoothing.py、src/utils/potions.py） 移植自 Alan-xzwzz 的 PR #3（MIT License）。 本 fork 按国服的固定运行环境做了改造（只支持 1366x768 窗口化、出厂预置 roi、 补 span 支持、给按键补前台守卫），改造点见各文件头的说明。 感谢原作者的思路，尤其是血条闪烁的处理（低血量时血条会闪，直接读 0 会被误判成"快死了"而疯狂喝药）。
• 原项目的 Discord 群与赞助链接属于上游作者，本 fork 不继承。
• 上游 README 中的台服数据与说明已不适用于国服，请以本文件为准。

本项目仅供个人娱乐与技术学习使用，不得用于商业用途。使用自动化脚本可能违反游戏服务条款并导致账号被封禁，风险自负。作者不对任何账号处罚或数据损失负责。