企业官网建设流程全解析

MaaNTE开源贡献完整路线图：从搭环境到第一个PR被合并，真实开发案例全流程

【免费下载链接】MaaNTEMaaNTE. Nevertheless to Everless automatic assistant 异环小助手项目地址: https://gitcode.com/gh_mirrors/maa/MaaNTE

MaaNTE 是基于 MaaFramework 的《异环》（Neverless）游戏自动辅助工具，通过识别游戏画面模拟常规交互，实现自动钓鱼、做咖啡、收家具等日常功能。本文以真实开发案例（"自动抚摸小动物"功能，Issue #223 → PR #231）为主线，带你走完从搭建开发环境、编写 Pipeline 到 PR 被合并的完整开源贡献流程，新手照着做即可提交第一个 PR。

🗺️ 动手前：MaaNTE 仓库结构与贡献方式

MaaNTE 采用"Pipeline 管流程，Python 管难点"的架构，理解这一点是贡献的起点：

仓库全局约定（构建、测试、Git 规范）集中在 AGENTS.md，新增一个功能通常需要配套修改任务 JSON + Pipeline JSON + 5 个语言文件 +assets/interface.json注册四处。

🛠️ 一键搭环境：5分钟跑起 MaaNTE 开发环境

环境要求极简：Git + Python 3.11+，推荐搭配 VS Code 使用。

git clone --recurse-submodules https://gitcode.com/gh_mirrors/maa/MaaNTE cd MaaNTE git submodule update --init --recursive # 拉取模型子模块，避免模型缺失 python -m venv .venv && .venv\Scripts\activate pip install -r requirements.txt

💡 仓库包含assets/MaaCommonAssets和assets/MaaNTEModels两个子模块。若克隆后提示模型缺失或子模块"被修改"，执行上面那条git submodule update命令即可。

开发利器：在 VS Code 安装Maa Pipeline Support插件，可以对任意 Pipeline 节点右键单步执行，直接验证识别是否命中、动作是否正确，还能自动完成截图与 1280×720 坐标换算。

📖 阅读路线：开发者文档按这个顺序看

官方开发者文档位于 docs/zh_cn/develop/，建议按以下顺序阅读，不要跳步：

1. 快速开始 —— 真实案例走一遍完整开发流程（本文即是它的延伸）
2. PR 规范 —— PR 标题、描述、验证记录要求
3. Pipeline 编写指南 —— 识别/动作类型与流程控制
4. 编码规范 —— 常见坑与提交前检查
5. 需要 Python 逻辑时再看 自定义动作开发 与 节点测试

🐱 选第一个任务：真实案例"自动抚摸小动物"

新人第一个 PR 建议选小而完整的功能。以 快速开始 中的真实案例为例：用户在 Issue #223 提出"自动循环抚摸小动物"需求，最终由社区开发者实现并合并为 PR #231。整个功能的 Pipeline 只有 4 个节点：

TouchDetect（OCR识别"抚摸"按钮） → TouchPressF（按 F 键） → TouchClickCenter（点击屏幕中央） → TouchPressEsc（按 Esc 关闭）→ 回到 TouchDetect 循环

流程很简单，但完整覆盖了Pipeline 节点、任务配置、i18n 文案、测试、PR全部环节——这正是最佳练手题型。

⚙️ 核心心法：Pipeline "识别 → 操作 → 再识别"

这是 MaaNTE 编码规范中最重要的一条铁律（详见 coding-standards.md）：

永远先识别、再操作。不能假设"点了按钮，下一个画面一定出现"。

推荐：识别 A → 点击 A → 识别 B → 点击 B 禁止：整体识别一次 → 连续点击 A、B、C

为什么这么严格？因为游戏随时可能弹出公告、弹窗（如上图这类"确认退出"对话框）。如果你的流程只走主线不处理弹窗，在真实用户设备上就会点偏甚至误操作。好流程的next列表会覆盖主线之外的所有可能画面，例如挂载[JumpBack]SceneLoading、[JumpBack]SceneClickBlankToExit等公共节点——优先复用 场景管理器 的公开接口，禁止直接引用__ScenePrivate*私有节点。

其他几条必须遵守的约定：

• 所有坐标、ROI、模板图片基于1280×720基准
• 避免硬延迟：用中间识别节点代替sleep，不需要时显式设pre_delay: 0
• 禁止盲目重试：节点失败要找根因，而不是加max_hit硬扛
• OCR 的expected必须写完整中文文本（多语言由 CI 工作流自动同步翻译）

📝 配套四件套：一个功能改哪些文件

以抚摸功能为例，一次完整贡献涉及：

⚠️ 高频踩坑：改了任务却忘了在interface.json注册、或漏补某一种语言文案——这两种问题评审时几乎必被指出。

🌿 提交规范：分支命名与约定式提交

仓库禁止直接改dev分支，所有改动走独立分支 + PR 合并：

分支命名（按类型选前缀）：

• feat/<name>：新增功能，如feat/touch-animal
• fix/<name>：修复 Bug
• docs/<name>/refactor/<name>/chore/<name>：文档、重构、构建维护

提交信息遵循 Conventional Commits 格式<type>(<scope>): <subject>，例如：

feat: 添加抚摸功能

尽早创建 Draft PR——需求未完全确定时先开草稿，方便维护者提前纠正方向，避免白干。

📮 写好 PR：让第一个 PR 快速被合并

PR 提交前请对照 PR 规范 自查，一份能加速合并的 PR 描述至少包含三部分：

1. 关联 Issue：Closes #223或Related #223（没有 Issue 就说明需求来源）
2. 变更摘要：2~5 条 bullet，如"新增Touch.jsonPipeline 实现循环抚摸""新增 3 个可配置选项""补充五语言文案"
3. 验证记录：别只写"已测试"，写清测试入口、控制器、结论，例如"使用 Maa Pipeline Support 测试TouchDetect稳定命中；Win32-Front 完整运行 3 次均正常结束"

涉及识别、点击的改动，尽量附上标注 ROI 的游戏截图或失败前后的maa.log关键片段。评审意见涉及设计方向时，先回复确认方案再动手改，避免反复返工。

💡 关于 AI 辅助开发：可以用 AI 做增量开发，但必须理解并能解释 PR 中的每处改动。在未提供游戏截图、界面跳转逻辑的情况下让 AI 直接"盲写" Pipeline 的 PR 会被直接关闭（见 编码规范）。

✅ 提交前检查清单

• PR 目标分支是dev
• 标题符合约定式提交格式
• 变更范围单一，未混入无关改动，已同步最新origin/dev
• 任务已在assets/interface.json注册，5 个语言文件文案齐全
• 识别/点击改动附带截图、ROI 标注或日志证据
• 已说明验证方式与结果

🚀 下一步

合并第一个 PR 后，可以挑战这些进阶内容：

• 复杂 Python 动作开发 → custom-action.md（如 MapTeleport 地图传送、SoundTrigger 音效闪避）
• 单节点调试技巧 → node-testing.md
• 场景跳转机制 → scene-manager.md

MaaNTE 项目仍在快速迭代中，社区欢迎 PR 与 Issue。现在就可以 fork 仓库、拉个feat/分支，从一个小弹窗处理或一个文档勘误开始你的第一个贡献。祝合并顺利！🎉

【免费下载链接】MaaNTEMaaNTE. Nevertheless to Everless automatic assistant 异环小助手项目地址: https://gitcode.com/gh_mirrors/maa/MaaNTE