v3.7.3

3.7.3 - 2026-10-18

修复

• --add android 不再把 extend-exclude 叠成重复 key。项目自己的 [tool.ruff] 已有
  extend-exclude 时，Android/MaaFwApp 会并进现有数组（单行、空数组、多行都支持）；早期版本留下
  的重复 key 会在下一次 --add android / --add agent 时折回成一个。重复 key 会让 pyproject.toml
  变成非法 TOML，连带 --update python-deps 的 tomllib 解析一起失败（Cannot overwrite a value）

已有项目：手工删掉重复的那行 extend-exclude（保留项目自己的并补上 "Android/MaaFwApp"），或升级后
重跑 create-maa-project --add android 自动修复。

v3.7.2

3.7.2 - 2026-10-17

修复

• Android 的 beta 配对现在能真正匹配上。预发布版本在三个地方拼写不同：requirements.txt 是 uv 导出的
  PEP 440 归一形式（maafw==5.15.0b1），内核 tag 是发布原文（3.13.15-maafw5.15.0-beta.1），
  MaaFramework release tag 是 v5.15.0-beta.1。resolver 的配对正则原先不认 -，5.15.0b1 会被判成
  "内核还没发配对"而降级回上一个正式版；现在 tag 解析放行预发布后缀，配对、AGENT_CORE_TAG 校验以及
  maa-project.json / requirements.txt 的一致性比较都先按 PEP 440 归一再比，maafw_tag 取 release
  的真实拼写而不是 v 加归一版本。--doctor 的 android 钉版检查同样归一后再比，maafw.version 写
  5.15.0b1 或 5.15.0-beta.1 不再互相误报。桌面侧 --update maafw 把 maafw.version 当 tag 查时，
  归一形式查不到会补试发布拼写（5.15.0b1 → v5.15.0-beta.1）

变更

• --update python-deps 成为 android 项目的版本对齐点。启用 android 的 Agent 项目里，它先确定
  MaaFramework 目标版本（maa-project.json 的精确 maafw.version 优先，为空则按 maafw.channel 解析
  最新发布，beta / alpha 含预发布），把 maafw==X 钉进 pyproject.toml 后再 uv lock /
  uv export，最后校验 requirements.txt 导出的是同一版本（PEP 440 归一后比较），不一致直接报错。
  没有 android 的 Agent 项目保持原行为：maafw 浮动，由 uv 与 Dependabot 的 lockfile-only 更新
  驱动，不会和自动更新打架。--add android 现在也会改写已有的 maafw 钉版（原来只填未钉版的依赖），
  maafw.version 改了重跑即可
• 发版 workflow 自己重导 Python 依赖。Dependabot 的 uv 更新只动 uv.lock，而桌面包与 APK 都从
  requirements.txt 装依赖；现在 release.yml 在 pnpm sync:runtime 之前、android-build.yml 在两个
  job 的 tools/android-packaging.mjs 之前都会先跑 uv export --frozen，从 lock 重新导出工作区里的
  requirements.txt。合并 Dependabot 的 uv PR 后不必再手工跑 --update python-deps 才能发版；仓库里
  那份仍是提交物，本地开发想更新时再跑。--frozen 在 pyproject.toml 与 uv.lock 不一致时直接失败，
  不会悄悄用旧 lock

已有项目：tools/android-packaging.mjs 是受管文件，重跑 create-maa-project --add android 即更新。
要出 beta 包不用再手改 pyproject.toml：把 maa-project.json 的 maafw.channel 改成 beta（或把
maafw.version 写成精确版本）后跑一次 --update python-deps，它会自己把 maafw==5.15.0-beta.1 钉进
pyproject.toml、导出 requirements.txt，内核已有 3.13.15-maafw5.15.0-beta.1 配对时 APK 就会用它。

v3.7.1

3.7.1 - 2026-10-13

修复

• Android 的 Agent 项目不再因为 vendored 外壳而红。release.yml 以 submodules 检出子模块，ruff check . 会一路扫进 Android/MaaFwApp/scripts/*.py，撞上上游脚本的 UTF-8 编码声明（UP009）——6 个桌面 package job 全挂在 pnpm check:py，release job 随之 skipped；同一个 commit 上 check.yml（不检子模块）反而是绿的。现在 Agent 项目的 pyproject.toml 在 [tool.ruff] 里带上 extend-exclude = ["Android/MaaFwApp"]（用 extend-exclude 而不是重写整个文件：pyproject.toml 还装着项目自己的 [project].dependencies）。启用 android 时创建即写入，--add android 与重跑 --add agent 也会把这行插进项目已有的 pyproject.toml；没启用 android 的项目逐字节不变

已有项目：跑一次 create-maa-project --add android（或 --add agent）即补上这行，--update 的 8 个目标都不刷新 pyproject.toml。手工加等价：在 [tool.ruff] 里写 extend-exclude = ["Android/MaaFwApp"]。

v3.7.0

3.7.0 - 2026-10-12

新增

• 新增 android add-on：把项目接上 MaaFwApp 外壳（Kotlin/Gradle）并由 CI 出 Android APK。create-maa-project --add android 写入二选一的 Android/profile.yaml（纯 pipeline / 带 agent，之后手维护）、Android/README.md（本地出包、签名 Secrets、升外壳）、tools/android-packaging.mjs（解析 MaaFW 版本、内核 tag、资产前缀与 Chaquopy 参数）与 android.yml / android-build.yml 两个 workflow，并把 Aliothmoon/MaaFwApp 以 submodule 浅克隆进 Android/MaaFwApp（同时写 .gitmodules 与 gitlink，CI 用 submodules: recursive 检出）。debug 出 arm64-v8a 单包，release 出 universal + arm64-v8a + x86_64 三包，命名为 <前缀>-android-<tag>.apk（universal 刻意不带 ABI 段，应用内更新按资产名选包）与 <前缀>-android-<abi>-<tag>.apk，前缀取 project.displayName、非 ASCII 或带空白时退回 project.slug。该 add-on 不依赖别的 add-on：入口 workflow 自带，没有 github 也能出 debug 包；启用 github 时 release.yml 多一个与桌面 package 并行的 android job，Release 等两者齐再建，资产带上 release-assets/*.apk（tag 上缺 KEYSTORE_BASE64 直接失败，手动 dispatch 仍出未签名包，未启用 android 时 release.yml 逐字节不变）。交互式「全部」预设不含它（要拉一个约 5 MB 的外壳仓库），在「自定义」里勾选或用 --add android。--doctor 的 android-packaging 检查覆盖上述文件、配方的 assets 与 app.id、外壳的登记/检出/gitlink 状态、.gitignore 段落，以及 agent 项目的 maafw 钉版一致性
• Agent 项目的 Android 出包自带版本配对。Android 的 Python 绑定只随内核（MaaAgentCoreAndroid 的 X-maafwY tag）发布，所以 APK 需要 requirements.txt 里的精确 maafw==X：拿不到时登记 android-version pending（把 maa-project.json 的 maafw.version 写成精确版本后重跑 --add android 会一并钉住 pyproject.toml，再 --update python-deps 让 uv 导出）。上游发了补丁版而内核还没跟上时降级到不高于固定版本的最高配对并打 ::warning::（APK 内前后端仍是同版本，只是比 requirements 固定得旧），固定版本比内核所有配对都旧才报错。带原生 .so 的 Python 包在 Android 上要按 Chaquopy 索引钉版，这里不再用硬编码降级表：resolver 逐包探测——桌面 pin 在索引上没有当前 CPython 的构建就钉到索引最高可用版，索引上没有该包（纯 Python）不钉，索引有构建但没有当前 CPython 时直接失败，而不是让 pip 在构建中途报错

变更

• 教程示例 pipeline 从 resource/base/pipeline/tutorial.json 移到 resource/base/pipeline/Tutorial/Tutorial.json。MaaFW 加载 pipeline 目录下的所有文件，两处路径都能跑；这是 once 文件，只有新建项目拿到新路径，已有项目保留原文件即可

修复

• agent 的多行日志不再丢内容。MFAAvalonia 逐行解析 agent 输出、只认带 level 前缀的行，多行消息的第二行起会被丢进 GUI 内部日志；现在逐行补前缀，并丢掉结尾换行造成的空尾行。loguru 与标准 logging 两条控制台路径合并到唯一渲染分支（_CONSOLE_FORMAT 走字段值，避免 callable format 的返回值被再当格式串去解析颜色标记），文件 sink 不再挂控制台 filter；MXU 侧补上转义白名单还原，只放行 <font color="#RRGGBB">、其余内容保持转义。agent/utils/logger.py 现将与上游 M9A 该版本逐字节一致

已有项目：android 是独立 add-on，要用就执行 create-maa-project --add android——它会浅克隆外壳，克隆失败不阻断创建，只登记 android-submodule pending 与恢复命令。Agent 项目按上一条把 maafw.version 写成精确版本再 --update python-deps，否则会一直挂着 android-version pending。logger 修复在受管文件里，重跑 create-maa-project --add agent 即可获得（与模板不一致的受管文件会整体重写，手改过先确认；--update 的 8 个目标都不刷新 agent 文件）；tutorial 路径变更不用处理。

v3.6.3

3.6.3 - 2026-10-08

新增

• 发布构建新增 welcome 公告文件的校验与打包。PI 2.10 的 welcome 协议里 interface.json 的 welcome 条目是 $Key，公告 markdown 的真实路径由各语言的翻译文件解析，既有的 resource / import / languages 校验列表都看不到这些文件——发布脚本漏带公告目录时包是静默缺内容的，用户侧表现为 GUI 欢迎页空白。现在 $Key 条目会经全部语言文件解析成文件路径（每种语言文件名不同、中文文件名均支持），字面量条目直接透传，带 scheme 的远程公告 URL 不是仓库文件、跳过；仓库预检与打包 smoke 都会校验解析出的公告文件存在，缺失则构建失败而不是发坏包；项目存在 announcement/ 目录时整目录随包（含被公告引用的 images/ 等子目录，条件包含、不强制建目录）

已有项目：tools/build-release.mjs 为受管文件，重跑 create-maa-project --add github 即可获得该行为（--update 的目标里没有 github）；公告不在 announcement/ 目录的项目把 releasePackagePaths 里的目录名改成实际目录即可。

v3.6.2

3.6.2 - 2026-10-04

新增

• community add-on 的 bug report 模板重写为收集能定位问题的证据：「相关任务」改问界面上选择的任务名称与进行到哪一步时出错，编写或修改 pipeline / 资源包的作者仍可注明相关节点（普通用户不必再面对 render: json 的 JSON 代码块）；新增必填的「问题出现时间」，示例精确到分钟（每次复现可写「每次」），报告从此带有可在日志中定位事发记录的时间窗口；「日志文件」改为必填并写明收集口径——本地运行打包上传整个 debug/ 目录（至少 debug/maafw.log，存在 debug/maafw.bak.log 时一并上传，事发记录可能已轮转进备份文件），启动器或自定义程序写入的 logs/ 等其他日志目录一并打包；由 GUI 导出的日志压缩包若分成多个文件或分卷则需全部上传，缺少任何一部分都可能丢失事发记录

变更

• community 的 issue 侧栏（.github/ISSUE_TEMPLATE/config.yml）不再提供 MaaFramework 文档链接：issue chooser 是应用项目的入口，不应把应用用户引导去框架开发文档；blank_issues_enabled: false 保持不变

已有项目：community 的模板文件是 once（创建后归项目所有），重跑 --add community 不会覆盖已有版本。想要新版 bug report 的项目删除 .github/ISSUE_TEMPLATE/bug_report.yml（侧栏链接则是 .github/ISSUE_TEMPLATE/config.yml）后再执行一次 create-maa-project --add community，缺失的文件会按新版补回；不更新也完全不影响使用。

v3.6.1

3.6.1 - 2026-10-01

修复

• 重跑 --add agent 现在会把与模板不一致的受管文件整体重写。此前对已启用 agent 的项目，该命令只补缺失的文件、外加两处版本漂移的就地修复，模板更新过的受管文件永远不会刷新——3.6.0 的迁移恰好踩中：旧项目按说明执行 create-maa-project --add agent 后，agent/maafw_paths.py 写进来了，agent/main.py 却还是旧的（没人调用解析器），再 --add github 换上剥离原生库的发布脚本后 Agent 起不来（package-smoke 会先在 CI 里失败，不会静默发坏包）。现在与模板不一致的受管文件随重跑整体重写（照常进入 managed-files 备份，手改过可用 --restore 回退）；once 文件仍归项目所有、只在缺失时补回；pyproject.toml 仍只就地修 requires-python，因为 [project].dependencies 是项目自己声明依赖的地方
• 生成的 agent_runtime.py 改为报告实际加载的 MaaFramework 版本。importlib.metadata.version("maafw") 读的是 dist-info，而 MFAAvalonia 的增量更新写下新的 dist-info 却不删旧的，两份并存时读到的可能是旧版本——GUI 日志报着旧版本、实际加载的原生库却是新的（实测 maafw-5.12.3 与 5.14.0 并存）。现在优先记 Library.version()，原生查询失败才回退 pip 元数据。版本日志同时移到 maa.agent 导入之后（version() 会初始化 API 属性，Library.open 初始化过就提前返回，更早调用会把 Library 钉死在非 agent 模式），两条诊断降为 debug：GUI 日志保持干净，debug/custom/*.log 里仍然可见

已有项目：两条都改在生成文件里。3.6.0 之后跑过 --add agent 的项目再跑一次 create-maa-project --add agent 即可——上一版的刷新缺口也挡住了第二个修复生效，这次会一并刷回 agent/main.py 与 agent/agent_runtime.py。受管文件是整体重写，手改过的话先确认一下。

v3.6.0

3.6.0 - 2026-09-26

新增

• Agent 项目新增 agent/maafw_paths.py：在 agent_runtime 之前解析客户端那份 MaaFramework 原生库并把 MAAFW_BINARY_PATH 指过去，因为 utils 一导入就连带 import maa、库目录在那一刻已经定死，解析必须更早。进程自己设过该变量的一律不动（Android runner 会指向 APK 的 nativeLibraryDir），候选目录按发行包布局排序（runtimes/<平台>/native、maafw/、包根），且要求两个库文件都在——开发机上空的 runtimes/<tag>/native 不会被当成可用副本。--doctor 已把它列入必需文件，缺失会报 [ERR]
• 生成的 check workflow 增加 pnpm release:dry-run：interface.json 的路径写错、发布引用的文件缺失这类问题在 push / PR 阶段就会失败，不必等到推了 tag 才发现
• 发布构建会校验并打包 interface.json 的 languages 翻译文件，缺失时构建失败，不再让客户端把 $Key 原样显示出来

变更

• Agent 发布包不再重复携带 MaaFramework 运行时。客户端包本来就已经带了同一份（MFAA 在 runtimes/<平台>/native、MXU 在 maafw/、CLI 壳平铺在包根），而包内解释器的 maa wheel 里还压着第二份，每个包因此多出几十 MiB；现在构建时剥离解释器里那份，Agent 通过 MAAFW_BINARY_PATH 复用客户端那份。包校验（package-smoke）改为先解析运行时、注册全部自定义动作与识别，再确认解释器里已无副本、客户端侧的 MaaFramework / MaaAgentServer 两个库与 plugins/ 目录都在，于是接不上运行时的包会在构建阶段失败，而不是等到用户手里
• 客户端原生库目录下现在总有 plugins/（空目录也算）。MaaFramework 的 PluginMgr 把「目录不存在」当成加载失败，每次启动刷 4 行 ERR，空目录不会
• 发布构建开始前清空 dist/package-*：发布 workflow 会归档所有 dist/package-*，此前上一轮构建遗留的包（例如当时还启用、现在已经关掉的 GUI）会被一并发出去
• MXU 包标题不再带空白的 label：label 为空或只有空白时回退到项目 slug

修复

• 发布前对 interface.json 的 resource 校验此前只检查对象形式的条目，写成字符串的（"resource/base"）整个被跳过，而这两种写法实际都会被打包。现在两种都检查，且校验与打包共用同一份路径列表
• 找不到可剥离的原生库副本时发布直接失败，不再只留一条 warning：包内解释器每次都是新拷贝且已装好 Agent 依赖，找不到 site-packages/maa/bin 说明 wheel 布局变了，必须失败，否则重复的原生库会再次悄悄发出去
• 客户端原生库的存在性校验改为按 MaaFramework 的命名约定（<name>.<dll|so|dylib>）匹配，不再维护一份平台清单：清单会漏掉库名不同的平台，现在库改名会让构建失败，而不是发布一个运行时缺失的包

已有项目：改动都在 CLI 与生成文件里，不重跑 add-on 的项目行为不变（仍旧用旧的发布脚本，包内仍自带原生库）。要启用新行为，Agent 项目执行 create-maa-project --add agent，装 github add-on 的执行 create-maa-project --add github。Agent 项目请先 --add agent 再 --add github：顺序反了会先换上新发布脚本、而项目里还是没有 maafw_paths.py 的旧 Agent，包内原生库被剥离后 Agent 起不来（新的 package-smoke workflow 会在 CI 里先失败，不会静默发出去）。受管文件是整体重写，手改过的话先确认一下；已发布的 tag 不受影响，下次发版生效。

v3.5.2

3.5.2 - 2026-09-16

修复

• --update maafw 以及 --update runtime:mfa / runtime:mxu 不再要求版本 pin 写成上游 tag 的 v 前缀。此前把 maafw.version 写成 5.13.0 会原样拼进 .../releases/tags/5.13.0，拿到一个不解释任何原因的 404 并终止更新，而上游的标签其实是 v5.13.0；现在先按原样查，查不到再试另一种拼法，两种都不存在时才按你写下的那个报错。日期型 tag（如 python-build-standalone 的 20260610）仍在第一次查询就命中，不会多发请求。docs/commands.md 与 docs/commands.en.md 已写明前缀可省略
• 生成的 release 工作流能在 macOS 上打包了。Package 步骤此前用 bash 4 的大小写展开给产物命名，而 macOS runner 的 shell: bash 指的是系统自带的 bash 3.2，不认识这个语法，于是两个 macOS 目标都在写出产物之前以 bad substitution 失败——Linux 与 Windows 正常，所以发布包里只缺 macOS。改用 tr 展开后六个目标一致
• 发布说明不再因为取不到 GitHub 元数据而卡住整次发布。仓库关掉 Pull Requests 时拉取 PR 列表会返回 404，git-cliff 对此直接 panic（退出 101），而 notes job 是发布 job 的依赖，于是包全部构建成功却一直发不出 Release；现在在线取不到元数据时会自动改用 --offline 重跑同一区间，照样写出发布说明（少 PR 号、@用户名 与新贡献者段落），并在运行页面留一条 warning。两次都失败时依旧是失败，不会被吞掉。同时删掉了生成的 cliff.toml 里无效的 [git.github] commits = true：git-cliff 从没有这个配置项，它一直被静默忽略，真正打开远端数据的是工作流里的 GITHUB_REPO

已有项目：第 1 条改在 CLI 里，项目本身不用动——CI 的 pnpm sync:runtime 走的是 pnpm dlx create-maa-project@latest，CLI 升级后下次跑就带上。第 2、3 条改的是生成文件，要用上得重跑一次对应的 add-on：只装 github add-on 的跑 create-maa-project --add github，装了 git-cliff add-on 的跑 create-maa-project --add git-cliff（它会一并重写 .github/cliff.toml 与 release 工作流）。受管文件是整体重写，手改过的话先确认一下。没碰上这三个问题的项目不用做任何事

v3.5.1

3.5.1 - 2026-09-15

新增

• --doctor 会指出 interface.json 里 type 不是 MaaFW 控制器类型的条目（例如 3.5.0 之前生成的项目里的 "type": "WlRoots"）—— 这类条目本来就会被项目自身的 check:schema 与编辑器拒绝，而此前 doctor 不做任何提示。提示执行 --sync metadata 就地修好；项目自行扩展、type 合法的控制器不受影响

变更

• 控制器 kind 改用 MaaFW 自己的叫法 Linux。此前 CLI 自造了 WlRoots，它是六个 kind 里唯一与上游枚举不一致的一个，也是 maa-project.json 与 interface.json 口径对不上的唯一来源。--controller、maa-project.json 的 controller.kinds 与 MCP 的 controllers 参数都仍接受 WlRoots 并归一化为 Linux，新项目两边都写 Linux，已有项目执行 --sync metadata 即完成迁移。反向不成立：3.5.1 生成的项目其 controller.kinds 为 Linux，更早版本的 CLI 会拒绝该值

修复

• --sync 不再删除 interface.json 里手写的内容。此前每条 sync 命令都会把 controller 与 resource 整段替换成 CLI 生成的版本，导致：控制器上的 attach_resource_path、icon、option、按类型的子块与调过的 display_short_side 被重置；label 被改回默认值；配置表达不出的控制器（例如第二个 Adb 客户端）被删除；maa-project.json 未记录仓库地址时手写的 github 被删除（现在 --doctor 由报错改为 [INFO]，并提示用 --sync github-url 记录）；非 Agent 项目手写的 agent 块被删除。现在只修由配置派生的部分：控制器的标识（含早期写出的 Android、WlRoots，就地改名而不再多出一条）与 type
• --sync 与 --add 不再重写归项目所有的文件。maatools.config.mts 与 .vscode/ 下标记为 once 的 settings.json、extensions.json、launch.json 此前会被整体重生成，自定义的键、扩展推荐、嵌套配置与调试配置都会丢。现在只合并 CLI 自己生成的部分：--add vscode 保留其余键并按 name 合并调试配置，--add agent 只把 vscode.agents.uv 补进已有的 MaaTools 配置（已配好则完全不写），--sync 只在 maatools.config.mts 缺失时重建它
• --add resource-pack 不再按配置重生成 interface.json 的 resource 数组，改为追加新资源包，hash、description、icon 等字段以及手工添加的资源包都会保留
• --doctor 的修复提示不再指向做不到的命令。此前 maatools.config.mts 的三类问题、以及 interface.json 的 import 路径问题都提示执行 --sync metadata，而该命令并不会改写它们（import 列表从来不由 CLI 写入）；现在按问题给出可执行的修复路径