chore: skeleton

Author: kqcoxn

.gitignore

@@ -1,3 +1,6 @@
+# dev
+MFAAvalonia/*
+
 # docs
 docs/node_modules
 docs/.vuepress/.temp
@@ -448,4 +451,4 @@ install
 tools/ImageCropper/**/*.png
 
 config
-debug
+debug

.qoder/commands/comments.md

@@ -0,0 +1,10 @@
+---
+type: project_command
+description: 
+---
+
+对注释进行生成或规范化，使用中文，要点如下：
+
+- 遵循 PEP 8 — Style Guide for Python Code（Python 官方代码风格指南）以及 PEP 257 — Docstring Conventions（文档字符串约定）
+- 如果文件太长，可以按逻辑分组，使用 `# ====================  模块名  ====================` 格式的对称分隔符
+- 注释符号也使用中文

README.md

@@ -8,7 +8,7 @@
 
 **请您不要在任何官方社区/评论区提及 MDDL！**
 
-基于全新架构的 [**嘟嘟脸恶作剧**](https://xytx.firewick.net/home) 小助手<br/>图像技术 + 模拟控制，解放双手，由 [MaaFramework](https://github.com/MaaXYZ/MaaFramework) 与 [MFAAvalonia](https://github.com/SweetSmellFox/MFAAvalonia) 强力驱动！
+基于全新架构的 [**嘟嘟脸恶作剧**](https://game.bilibili.com/trickcal/) 小助手<br/>图像技术 + 模拟控制，解放双手，由 [MaaFramework](https://github.com/MaaXYZ/MaaFramework) 与 [MFAAvalonia](https://github.com/SweetSmellFox/MFAAvalonia) 强力驱动！
 
 <p align="center">
   <a href="https://github.com/MaaXYZ/MaaFramework/blob/main/docs/zh_cn/3.1-%E4%BB%BB%E5%8A%A1%E6%B5%81%E6%B0%B4%E7%BA%BF%E5%8D%8F%E8%AE%AE.md" target="_blank"><img alt="pipeline" src="https://img.shields.io/badge/Pipeline-%23876f69?logo=paddypower&logoColor=%23FFFFFF"></a>

agent/customs/__init__.py

@@ -0,0 +1,47 @@
+"""MaaDuDuL Agent 主入口。
+
+负责初始化环境、检查依赖、启动 Agent 服务器。
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# 将项目根目录添加到 Python 路径
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(PROJECT_ROOT))
+
+from agent.preprocess import check_and_install_dependencies
+
+# 设置控制台编码
+sys.stdout.reconfigure(encoding="gbk")
+sys.stderr.reconfigure(encoding="gbk")
+
+
+def main():
+    """启动 MaaDuDuL Agent 服务"""
+    from maa.agent.agent_server import AgentServer
+    from maa.toolkit import Toolkit
+    from agent.preprocess import clear
+    import customs
+
+    try:
+        # 清理调试文件
+        clear()
+        # 初始化 MaaFW 工具包
+        Toolkit.init_option("./")
+        # 获取 socket ID 并启动服务
+        socket_id = sys.argv[-1]
+        AgentServer.start_up(socket_id)
+        AgentServer.join()
+        AgentServer.shut_down()
+
+    except Exception as e:
+        print(f"Agent 启动失败：{e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    if not os.getenv("MDDL_DEV_MODE"):
+        check_and_install_dependencies()
+    main()

agent/customs/utils/__init__.py

@@ -0,0 +1,3 @@
+from .clear import clear
+from .report import punch_in
+from .setup import check_and_install_dependencies

agent/main.py

@@ -0,0 +1,40 @@
+"""预处理清理模块。
+
+本模块负责在任务执行前清理调试产生的临时文件。
+"""
+
+import shutil
+from pathlib import Path
+
+
+def _clear_on_error_images():
+    """清理错误时产生的调试图片。
+
+    删除 debug/on_error 目录及其所有内容。
+    该目录用于存储任务执行出错时的截图，清理可避免历史图片占用空间。
+    """
+    # 获取项目根目录（当前文件的上两级目录）
+    root = Path(__file__).resolve().parent.parent
+
+    # 构建调试图片文件夹路径
+    on_error_folder = root / "debug" / "on_error"
+
+    # 如果文件夹存在则删除整个目录树
+    if on_error_folder.exists():
+        try:
+            shutil.rmtree(on_error_folder)
+        except Exception:
+            # 删除失败时静默处理，避免中断预处理流程
+            pass
+
+
+def clear():
+    """执行预处理清理操作。
+
+    该函数是清理模块的对外接口，负责调用所有内部清理函数。
+    即使清理过程出错也不会中断程序，仅输出提示信息。
+    """
+    try:
+        _clear_on_error_images()
+    except Exception as e:
+        print(f"预处理时出现问题：\n{e}\n这可能不影响使用，但建议在交流群内反馈！")

agent/preprocess/__init__.py

@@ -0,0 +1,33 @@
+"""数据上报模块。
+
+该模块负责向远程服务器发送使用统计信息。
+"""
+
+import requests
+
+
+def punch_in():
+    """发送打卡数据到远程服务器。
+
+    向指定的统计服务器发送项目使用信息，包括来源标识和版本号。
+
+    Returns:
+        dict: 服务器返回的 JSON 响应数据。
+        Exception: 当请求失败时返回异常对象。
+
+    Note:
+        请求超时时间设置为 3 秒，失败时不会中断程序执行。
+    """
+    try:
+        # 发送 POST 请求到统计服务器
+        response = requests.post(
+            "http://ts.codax.site/repo",
+            json={"from": "mddl", "version": "v0.0.1"},
+            headers={"Content-Type": "application/json"},
+            timeout=3,
+        )
+        response.raise_for_status()
+        return response.json()
+
+    except requests.exceptions.RequestException as e:
+        return e

agent/preprocess/clear.py

@@ -0,0 +1,203 @@
+"""依赖环境自动安装模块。
+
+本模块负责检测项目版本变化，并在必要时自动安装或更新 Python 依赖包。
+通过读取 interface.json 中的版本号与本地配置进行比对，
+决定是否需要执行 pip install 操作。
+"""
+
+import os
+import sys
+import json
+import subprocess
+from pathlib import Path
+
+# ====================  路径初始化  ====================
+
+current_file_path = os.path.abspath(__file__)
+current_dir = os.path.dirname(current_file_path)
+parent_dir = os.path.dirname(current_dir)
+os.chdir(parent_dir)
+
+if current_dir not in sys.path:
+    sys.path.insert(0, current_dir)
+
+
+# ====================  全局路径常量  ====================
+
+PIP_CONFIG_PATH = Path("./config/mddl/pip_config.json")
+
+
+# ====================  配置文件读写  ====================
+
+
+def _read_interface_version() -> str:
+    """读取 interface.json 中的版本号。
+
+    Returns：
+        版本号字符串，若文件不存在或读取失败则返回 "unknown"
+    """
+    interface_path = Path("./interface.json")
+    if not interface_path.exists():
+        return "unknown"
+
+    try:
+        with open(interface_path, "r", encoding="utf-8") as f:
+            interface_data = json.load(f)
+            return interface_data.get("version", "unknown")
+    except Exception:
+        return "unknown"
+
+
+def _read_pip_config() -> dict:
+    """读取 pip 安装配置文件。
+
+    若配置文件不存在，则自动创建并使用默认配置。
+    默认配置包括：
+    - enable_pip_install：是否启用自动安装，默认 True
+    - last_version：上次安装时的版本号，默认 "unknown"
+    - mirrors：pip 镜像源地址列表，按顺序尝试，失败后用默认源兜底
+
+    Returns：
+        包含 pip 配置的字典
+    """
+    config_dir = Path("./config/mddl")
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    default_config = {
+        "enable_pip_install": True,
+        "last_version": "unknown",
+        "mirrors": [
+            "https://pypi.tuna.tsinghua.edu.cn/simple",
+            "https://mirrors.ustc.edu.cn/pypi/simple",
+            "https://mirrors.aliyun.com/pypi/simple",
+        ],
+    }
+
+    if not PIP_CONFIG_PATH.exists():
+        with open(PIP_CONFIG_PATH, "w", encoding="utf-8") as f:
+            json.dump(default_config, f, indent=4)
+        return default_config
+
+    try:
+        with open(PIP_CONFIG_PATH, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return default_config
+
+
+def _update_pip_config(version) -> bool:
+    """更新 pip 配置文件中的版本号。
+
+    Args：
+        version：要更新的版本号
+
+    Returns：
+        更新成功返回 True，失败返回 False
+    """
+    try:
+        config = _read_pip_config()
+        config["last_version"] = version
+
+        with open(PIP_CONFIG_PATH, "w", encoding="utf-8") as f:
+            json.dump(config, f, indent=4)
+        return True
+    except Exception:
+        return False
+
+
+# ====================  依赖安装  ====================
+
+
+def _install_requirements(req_file=None, mirrors=None) -> bool:
+    """安装 requirements.txt 中列出的依赖包。
+
+    Args：
+        req_file：依赖文件路径，默认为 "requirements.txt"
+        mirrors：pip 镜像源地址列表，按顺序尝试，最后用默认源兜底
+
+    Returns：
+        安装成功返回 True，失败或文件不存在返回 False
+    """
+    req_path = Path(req_file) if req_file else Path("requirements.txt")
+    if not req_path.exists():
+        return False
+
+    # 准备镜像源列表，最后添加默认源作为兜底
+    mirror_list = []
+    if mirrors:
+        if isinstance(mirrors, list):
+            mirror_list.extend(mirrors)
+        else:
+            mirror_list.append(mirrors)
+
+    # 默认源兜底（PyPI 官方源）
+    mirror_list.append(None)
+
+    # 逐个尝试镜像源
+    for idx, mirror in enumerate(mirror_list):
+        try:
+            if mirror:
+                print(
+                    f"正在使用镜像源安装或更新环境... ({idx + 1}/{len(mirror_list)}): {mirror}"
+                )
+            else:
+                print(f"正在使用默认源安装或更新环境... ({idx + 1}/{len(mirror_list)})")
+
+            cmd = [
+                sys.executable,
+                "-m",
+                "pip",
+                "install",
+                "-r",
+                str(req_path),
+                "--no-warn-script-location",
+            ]
+
+            if mirror:
+                cmd.extend(["-i", mirror])
+
+            subprocess.check_call(
+                cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
+            )
+            print("安装完成！")
+            return True
+        except Exception as e:
+            if idx < len(mirror_list) - 1:
+                print(f"当前镜像源失败，尝试下一个...")
+                continue
+            else:
+                print("环境加载失败，请检查网络与环境后重新尝试！")
+                return False
+
+    return False
+
+
+# ====================  主入口函数  ====================
+
+
+def check_and_install_dependencies():
+    """检查并自动安装或更新项目依赖。
+
+    该函数会：
+    1、读取当前项目版本号（从 interface.json）
+    2、读取上次安装时的版本号（从 pip_config.json）
+    3、若版本号不一致或当前版本为 unknown，则执行依赖安装
+    4、安装成功后更新配置文件中的版本号
+
+    注意：
+    - 可通过修改 config/pip_config.json 中的 enable_pip_install 字段禁用自动安装
+    - 可通过修改 mirrors 字段自定义 pip 镜像源列表，支持多个镜像源，按顺序尝试
+    - 所有镜像源失败后会自动使用 PyPI 官方默认源兜底
+    """
+    pip_config = _read_pip_config()
+    current_version = _read_interface_version()
+    last_version = pip_config.get("last_version", "unknown")
+    enable_pip_install = pip_config.get("enable_pip_install", True)
+    mirrors = pip_config.get("mirrors", None)
+
+    # 版本不一致时触发依赖安装
+    if enable_pip_install and (
+        current_version != last_version or current_version == "unknown"
+    ):
+        if _install_requirements(mirrors=mirrors):
+            _update_pip_config(current_version)