Skip to main content

auto-mas-maafw-interface

MaaFramework ProjectInterface(interface.json)的解析与运行计划库,从 AUTO-MAS 宿主的 MFW 引擎原样搬出。运行时只依赖 pydantic、json5。

对外接口

按子模块导入;包根只惰性导出 MaaFWInterfaceService,import maafw_interface.log_redact 不会连带加载 pydantic、json5。

模块 提供
maafw_interface.interface load_interface_model、load_interface_model_cached、MaaFWInterfaceService、interface 模型、快照归一化函数(interface/__init__.py 的 __all__);子模块 loader、models、preview、task_config、plan_rules、agent_command、agent_entry、password_values、host_path、service
maafw_interface.runner 惰性导出计划模型与 build_maafw_run_plan、MaaFWRunPlanError;子模块 run_plan(建计划、选控制器与资源、默认快照)、task_selection(展开任务快照)、plan_transforms(周期与重试)、pipeline_override、hotkey、models
maafw_interface.controller_win32 MaaFWWin32ControllerService、MaaFWWin32Window、MaaFWWindowMatch;service.controller_has_window_rules
maafw_interface.embedded_labels Labels、Translate、mxu_option_values(宿主原私有名 _Labels、_mxu_option_values)
maafw_interface.log_redact DETAIL_LOG_PREFIX、HOME_TOKEN、mask_home_path 等

和宿主原代码不同的地方(其余一律照搬):

  • build_maafw_run_plan(..., client_version="")、build_arranged_plan(..., client_version=""):AUTO-MAS 客户端版本由调用方传入,写进 piEnv["PI_CLIENT_VERSION"];库不去找宿主的 res/version.json。
  • MaaFWWin32ControllerService.match_controller_windows(controller, list_windows=None):第二个参数是返回窗口列表的函数,只在控制器有窗口规则时才调用;需要扫描却没传时抛 RuntimeError。库不自己扫描窗口。

interface.loader 在工作目录下用 data/cache/maafw_interface_loader 做磁盘缓存。PI_CLIENT_MAAFW_VERSION 与预览里的 emulatorExtras 是对已安装 maafw 的可选探测,没装就是空。

开发

以下命令都在仓库根 D:\MAS\code\blocks 运行。uv 不在 PATH 时用 D:\MAS\code\main\environment\python\Scripts\uv.exe。

uv venv .venv-dev --python 3.12
uv pip install --python .venv-dev\Scripts\python.exe -e packages\auto-mas-maafw-native -e packages\auto-mas-maafw-interface pytest build ruff
.\.venv-dev\Scripts\python.exe -m pytest packages\auto-mas-maafw-interface\tests -q -p no:cacheprovider --basetemp "$env:TEMP\blk-pytest"
.\.venv-dev\Scripts\python.exe -m ruff check .
.\.venv-dev\Scripts\python.exe -m ruff format --check .

--basetemp 指到自己能写的目录:默认的 %TEMP%\pytest-of-<用户> 若是管理员终端建的,非提权会话写不进去。

等价对拍(tests\test_equivalence.py)

拿宿主快照里的原函数和本库的同名函数对 D:\MAS\test\walkref 的六个项目逐字节比较。要一个能跑宿主代码的环境 .venv-eqhost(由 _src 的 uv.lock 建出)和 _src\res\version.json:

$env:UV_PROJECT_ENVIRONMENT = "$PWD\.venv-eqhost"
Push-Location _src; uv sync --frozen --group dev; Pop-Location
Remove-Item Env:UV_PROJECT_ENVIRONMENT
New-Item -ItemType Directory -Force _src\res | Out-Null
cmd /c "git -C D:\MAS\code\main show 048993fca:res/version.json > _src\res\version.json"
.\.venv-dev\Scripts\python.exe -m pytest tests -q -p no:cacheprovider --basetemp "$env:TEMP\blk-pytest"

用 cmd /c 重定向是为了按原字节写出(PowerShell 管道会改换行和编码),写完 git hash-object _src\res\version.json 应为 be7df643153350027ed930edc33a75aa577fc5d0。_src 是迁移分支 048993fca 的 app/、tests/、pyproject.toml、uv.lock 导出(只读素材,不进版本库)。宿主解释器放在别处时用环境变量 MAAFW_EQ_HOST_PYTHON 指定。不带参数在仓库根跑 python -m pytest 会按 pytest.ini 收三处测试(两个包的 tests 和根 tests)。

打包

.\.venv-dev\Scripts\python.exe scripts\build_all.py

两个包的 wheel 和 sdist 写进 dist\。只装 wheel 验收:

uv venv "$env:TEMP\blk-wheels" --python 3.12
uv pip install --python "$env:TEMP\blk-wheels\Scripts\python.exe" (Get-ChildItem dist\*.whl).FullName pytest
Push-Location $env:TEMP
& "$env:TEMP\blk-wheels\Scripts\python.exe" -m pytest D:\MAS\code\blocks\packages\auto-mas-maafw-native\tests D:\MAS\code\blocks\packages\auto-mas-maafw-interface\tests -q -p no:cacheprovider --rootdir $env:TEMP --basetemp "$env:TEMP\blk-pytest"
Pop-Location

在仓库外跑,保证导入到的是 site-packages 里的那份;导入守卫测试扫的也是已安装的包。

Metadata

Release files for auto-mas-maafw-interface 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for auto-mas-maafw-interface 0.2.0
File Size Uploaded Provenance Actions
auto_mas_maafw_interface-0.2.0.tar.gz 119.9 kB With provenance Details for auto_mas_maafw_interface-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for auto-mas-maafw-interface 0.2.0
File Interpreter ABI Platform Actions
auto_mas_maafw_interface-0.2.0-py3-none-any.whl Python 3 none any Details for auto_mas_maafw_interface-0.2.0-py3-none-any.whl

Total release size: 248.7 kB

Release files / auto_mas_maafw_interface-0.2.0.tar.gz

Download URL auto_mas_maafw_interface-0.2.0.tar.gz
Size 119.9 kB
Tags Source
SHA-256 checksum
How to use checksums
05c7a5ff47e2ed5c3814e5bcf16c4e6ed0c4712ce7bc792b7c9b4f1a57d7aa87
BLAKE2b-256 checksum
How to use checksums
6d2048ad1c5cf55f7ae61dc8dab38c54f18f799ba0dc5b4caf254a2ba8a78f64
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

Release files / auto_mas_maafw_interface-0.2.0-py3-none-any.whl

Download URL auto_mas_maafw_interface-0.2.0-py3-none-any.whl
Size 128.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b73f8d5a6ee9906d4e2899bd9451e02c886434cee2e066fbaddb6c47e9217ced
BLAKE2b-256 checksum
How to use checksums
34d60d74125f6ea6bd6a0053ff665801ca33f7344cbb0a9dc2f0bb92fa033538
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

Security for auto-mas-maafw-interface 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for auto_mas_maafw_interface-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page