Skip to content

Commit cabe440

Browse files
EeeMaoYclaude
EeeMaoY
and
claude
authored
docs: 新建 MaaNTE 中文开发者文档 (#239)
* docs: 新建 MaaNTE 中文开发者文档 参考 MaaEnd 开发者文档结构，基于本项目实际代码和 skills 内容编写： - README.md: 文档总索引，Tier 1/2/3 分层结构 - getting-started.md: 以 #223 → #231 Touch 功能为真实案例 - pipeline-guide.md: Pipeline JSON 编写指南 - coding-standards.md: AI 规范、Pipeline 规范、Python 规范 - custom-action.md: Custom 公共组件参考（click_override、alt_click） - scene-manager.md: 场景跳转接口与 JumpBack 机制 - in-scene.md: InScene 场景识别节点速查 - node-testing.md: Maa Pipeline Support 调试指南 - common-buttons.md: 通用按钮节点（待完善） Co-Authored-By: DeepSeek v4 pro <noreply@anthropic.com> * 修改readme到开发文档的导航 * readme相应翻译，以及其他补充 --------- Co-authored-by: DeepSeek v4 pro <noreply@anthropic.com>
1 parent 5482bc0 commit cabe440

16 files changed

Lines changed: 1031 additions & 340 deletions

‎README.md‎

Lines changed: 2 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -120,36 +120,9 @@
120120

121121
## 💻开发指南
122122

123-
<details><summary>点击展开</summary>
123+
想参与开发或深入了解项目？来这里吧 👉 [开发者文档索引](docs/zh_cn/develop/README.md)
124124

125-
MaaNTE开发者群: 1092630280
126-
127-
### 快速开始
128-
129-
0. 配置环境
130-
131-
- 安装 python>=3.11
132-
- 建议使用vscode作为IDE进行开发，并安装 [vscode插件“maa-support”](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support) 进行调试
133-
134-
1. Fork项目
135-
136-
- 点击 `Fork`，继续点击 `Create Fork`
137-
138-
2. 克隆自己 fork 的项目到本地，并拉取子模块
139-
140-
```bash
141-
git clone --recursive https://github.com/<你的用户名>/MaaNTE.git
142-
```
143-
144-
3. 下载MaaFramework的 [release包](https://github.com/MaaXYZ/MaaFramework/releases)，解压到 `deps` 文件夹中
145-
146-
4. 提交PR
147-
148-
- 新功能开发请提交到dev分支
149-
150-
更多开发文档可以参考 [M9A文档站](https://1999.fan/zh_cn/develop/development.html)
151-
152-
</details>
125+
欢迎各路大佬贡献代码，一起让 MaaNTE 变得更强！💪
153126

154127
## ❤️鸣谢
155128

‎docs/README_zh-tw.md‎

Lines changed: 2 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -109,36 +109,9 @@
109109

110110
## 💻開發指南
111111

112-
<details><summary>點擊展開</summary>
112+
想參與開發或深入了解專案？來這裡吧 👉 [開發者文件索引](https://github.com/1bananachicken/MaaNTE/blob/dev/docs/zh_cn/develop/README.md)
113113

114-
MaaNTE 開發者群：1092630280
115-
116-
### 快速開始
117-
118-
0. 設定環境
119-
120-
- 安裝 Python >= 3.11
121-
- 建議使用 VS Code 作為 IDE 進行開發，並安裝 [vscode 外掛「maa-support」](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support) 進行除錯
122-
123-
1. Fork 專案
124-
125-
- 點選 `Fork`，繼續點選 `Create Fork`
126-
127-
2. 複製自己 fork 的專案到本機，並拉取子模組
128-
129-
```bash
130-
git clone --recursive https://github.com/<你的使用者名稱>/MaaNTE.git
131-
```
132-
133-
3. 下載 MaaFramework 的 [release 包](https://github.com/MaaXYZ/MaaFramework/releases)，解壓縮到 `deps` 資料夾中
134-
135-
4. 提交 PR
136-
137-
- 新功能開發請提交到 dev 分支
138-
139-
更多開發文件可以參考 [M9A 文件站](https://1999.fan/zh_cn/develop/development.html)
140-
141-
</details>
114+
歡迎各路大佬貢獻程式碼，一起讓 MaaNTE 變得更強！💪
142115

143116
## ❤️鳴謝
144117

‎docs/eng/README_en.md‎

Lines changed: 2 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -124,36 +124,9 @@ The game must run in windowed mode at 1280×720 resolution. The new fishing algo
124124

125125
## 💻Development Guide
126126

127-
<details><summary>Click to expand</summary>
127+
Want to contribute or dive deeper into the project? Start here 👉 [Developer Documentation Index](https://github.com/1bananachicken/MaaNTE/blob/dev/docs/zh_cn/develop/README.md)
128128

129-
MaaNTE Developer QQ Group: 1092630280
130-
131-
### Quick Start
132-
133-
0. Set up environment
134-
135-
- Install Python >= 3.11
136-
- It is recommended to use VS Code as your IDE and install the [vscode extension "maa-support"](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support) for debugging.
137-
138-
1. Fork the project
139-
140-
- Click `Fork`, then click `Create Fork`.
141-
142-
2. Clone your forked repository and pull submodules
143-
144-
```bash
145-
git clone --recursive https://github.com/<your-username>/MaaNTE.git
146-
```
147-
148-
3. Download the [release package of MaaFramework](https://github.com/MaaXYZ/MaaFramework/releases) and extract it into the `deps` folder.
149-
150-
4. Submit a PR
151-
152-
- New feature development should be submitted to the `dev` branch.
153-
154-
For more development documentation, refer to the [M9A documentation site](https://1999.fan/zh_cn/develop/development.html).
155-
156-
</details>
129+
All contributions are welcome — let's make MaaNTE even better together! 💪
157130

158131
## ☕Acknowledgements
159132

‎docs/jp/README_jp.md‎

Lines changed: 3 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -108,38 +108,11 @@
108108

109109
ゲームは1280x720の解像度でウィンドウモードで実行する必要があり、釣りの新しいアルゴリズムは120フレームでの実行をサポートしています。
110110

111-
## 💻开发指南
111+
## 💻開発ガイド
112112

113-
<details><summary>点击展开</summary>
113+
開発に参加したい、またはプロジェクトを詳しく知りたい方はこちら 👉 [開発者ドキュメント](https://github.com/1bananachicken/MaaNTE/blob/dev/docs/zh_cn/develop/README.md)
114114

115-
MaaNTE开发者群: 1092630280
116-
117-
### 快速开始
118-
119-
0. 配置环境
120-
121-
- 安装 python>=3.11
122-
- 建议使用vscode作为IDE进行开发，并安装 [vscode插件“maa-support”](https://marketplace.visualstudio.com/items?itemName=nekosu.maa-support) 进行调试
123-
124-
1. Fork项目
125-
126-
- 点击 `Fork`，继续点击 `Create Fork`
127-
128-
2. 克隆自己 fork 的项目到本地，并拉取子模块
129-
130-
```bash
131-
git clone --recursive https://github.com/<你的用户名>/MaaNTE.git
132-
```
133-
134-
3. 下载MaaFramework的 [release包](https://github.com/MaaXYZ/MaaFramework/releases)，解压到 `deps` 文件夹中
135-
136-
4. 提交PR
137-
138-
- 新功能开发请提交到dev分支
139-
140-
更多开发文档可以参考 [M9A文档站](https://1999.fan/zh_cn/develop/development.html)
141-
142-
</details>
115+
コントリビューションをお待ちしています！一緒に MaaNTE をもっと強力にしましょう！💪
143116

144117
## ❤️謝辞
145118

‎docs/zh_cn/develop/README.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# MaaNTE 开发者文档
2+
3+
本目录包含 MaaNTE 项目的全部开发者文档。
4+
5+
## 阅读路线
6+
7+
建议按以下顺序阅读：
8+
9+
1. 搭环境、跑起来、完成第一次改动和 PR → `getting-started.md`
10+
2. 了解 Pipeline 编写规范 → `pipeline-guide.md`
11+
3. 查阅编码规范 → `coding-standards.md`
12+
4. 需要编写 Python 自定义逻辑 → `custom-action.md`
13+
5. 理解场景跳转机制 → `scene-manager.md`
14+
6. 需要调试单节点 → `node-testing.md`
15+
16+
## 文档索引
17+
18+
### Tier 1 — 快速上手
19+
20+
| 文档 | 说明 |
21+
|------|------|
22+
| [快速开始](./getting-started.md) | 以真实案例（#223 → #231）走一遍完整开发流程 |
23+
24+
### Tier 2 — 参考手册
25+
26+
| 文档 | 说明 |
27+
|------|------|
28+
| [自定义动作开发](./custom-action.md) | Python CustomAction 编写、Controller API、Pipeline 集成 |
29+
| [节点测试](./node-testing.md) | 如何编写和运行节点测试，验证识别是否稳定命中 |
30+
| [DeepWiki — MaaNTE](https://deepwiki.com/1bananachicken/MaaNTE) | 带 AI 的在线项目文档速览 |
31+
| [Pipeline 协议](https://maafw.com/docs/3.1-PipelineProtocol/) | MaaFramework 官方 Pipeline 协议全文 |
32+
33+
### Tier 3 — 规范与约束
34+
35+
| 文档 | 说明 |
36+
|------|------|
37+
| [编码规范](./coding-standards.md) | Pipeline / Python 编码规则、提交前检查、常见坑 |
38+
39+
## Pipeline 基础组件
40+
41+
日常开发最常用的可复用节点，建议所有 Pipeline 开发者查询以便复用。
42+
43+
| 文档 | 说明 | 路径 |
44+
|------|------|------|
45+
| [场景管理器](./scene-manager.md) | 从任意界面自动导航到目标场景 | `Interface/Scene/` |
46+
| [InScene 场景识别](./in-scene.md) | 判断当前画面所在场景 | `Interface/Scene/Status.json` |
47+
| [通用按钮](./common-buttons.md) | 各场景入口按钮 | `Common/Button/` |
48+
| [Custom 动作与识别](./custom-action.md) | 通用 Python 工具：alt_click等 | `agent/custom/action/Common/` |
49+
50+
## 高级组件参考
51+
52+
按需查阅。仅在使用对应组件时需要阅读。
53+
54+
| 文档 | 说明 |
55+
|------|------|
56+
| 自动战斗 | ⚠ 开发中 |
57+
| 自动导航 | ⚠ 开发中 |
58+
59+
## 任务维护文档
60+
61+
仅在维护对应任务时需要阅读。
62+
63+
| 文档 | 说明 |
64+
|------|------|
65+
| 待补充 | 待补充 |
66+
67+
## 快速跳转
68+
69+
| 我想做什么 | 该看哪里 |
70+
|-----------|---------|
71+
| 第一次参与，从零开始 | [getting-started.md](./getting-started.md) |
72+
| 改 Pipeline 节点 | [pipeline-guide.md](./pipeline-guide.md) |
73+
| 写 Python 自定义逻辑 | [custom-action.md](./custom-action.md) |
74+
| 场景跳转/界面导航 | [scene-manager.md](./scene-manager.md) |
75+
| 调试单个节点 | [node-testing.md](./node-testing.md) |
76+
| 查阅编码规范 | [coding-standards.md](./coding-standards.md) |
77+
78+
## 参考
79+
80+
- [MaaFramework 文档](https://maafw.com/docs/1.1-QuickStarted)
81+
82+
## 交流
83+
84+
开发QQ群：1092630280

‎docs/zh_cn/develop/coding-standards.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# 编码规范
2+
3+
## AI 编程规范
4+
5+
### 禁止无脑使用 AI 开发
6+
7+
- 直接向 AI 下达笼统指令，例如「帮我开发 xxx 功能并提 PR」「帮我修这个 bug 并提 PR」。
8+
- 在关键模块中，用 AI 生成大量难以维护、难以理解的「黑盒」代码。
9+
- 在关键模块中提交自己看不懂、无法掌控的代码。
10+
11+
> [!CAUTION]
12+
> 禁止在未向 AI 提供游戏界面截图、界面跳转逻辑等上下文的情况下，让 AI 直接编写 Pipeline。
13+
> MaaFramework 的 Pipeline 强依赖游戏界面与业务逻辑，缺乏界面信息的 AI 只能依赖幻觉和项目已有代码拼凑，产出代码质量极低。
14+
> 充分的信息至少包括：每个识别节点需提供 `roi` 与模板图片，并说明界面间的跳转关系（从哪个界面、点击什么、跳转到何处）。
15+
> 不满足以上条件的 PR 将被直接关闭。
16+
17+
### 推荐的 AI 开发方式
18+
19+
- 先学习本项目的编码规范，自行做架构设计，或将 AI 的建议作为参考。
20+
- 用 AI 做有目标的增量开发，自行 review 生成代码是否符合预期。
21+
- 确认无误后再提交 PR。
22+
23+
## Pipeline 低代码规范
24+
25+
### 命名：PascalCase
26+
27+
节点名称使用 PascalCase，同一任务内以任务名或模块名为前缀。例如 `FishNewEntrance`、`WithdrawMoneyEntrance`、`TouchDetect`。内部/私有节点以 `__` 开头：`__ScenePrivateWorldEnterBag`。
28+
29+
### 禁止硬延迟
30+
31+
尽可能少使用 `pre_delay`、`post_delay`、`timeout`。通过增加中间识别节点避免盲目 sleep。
32+
33+
只在必须等待画面稳定时使用 `pre_wait_freezes` / `post_wait_freezes`，其他时候应尽量避免延迟。
34+
**不要为了执行稳定而使用延迟，而是通过增加中间节点判断，因为延迟实际上是在掩盖问题，在用户设备存在高延迟时仍然不会稳定。**
35+
36+
### `next` 第一轮即命中
37+
38+
尽可能扩充 `next` 列表，保证任何游戏画面都处于预期中，实现一次截图就命中目标节点。
39+
**项目一般拒绝一切形式的重试机制，一定要保证在一次流程中完成所有任务，除非遇到无法解决的问题。**
40+
41+
### 识别 → 操作 → 再识别
42+
43+
每一步操作都基于识别。
44+
45+
**推荐：** 识别 A → 点击 A → 识别 B → 点击 B
46+
47+
**禁止：** 整体识别一次 → 点击 A → 点击 B → 点击 C
48+
49+
例如：
50+
51+
1. 界面跳转中，需要 识别跳转按钮 → 点击跳转按钮 → 识别界面已跳转完成。
52+
_你没法保证点完关闭按钮之后画面是否还和之前一样。极端情况下游戏弹出新池子公告，直接点下一个节点可能点到抽卡里去。_
53+
2. 点击会更改账号数据的按钮时，需要 识别提交按钮 → 点击提交按钮 → 识别按钮点击成功。
54+
_你没法保证每个用户的网络都是顺畅的，点击按钮事件未与服务器成功交互，整个交互界面会卡死不动。_
55+
56+
### 不要盲目重试、添加限制
57+
58+
**推荐：** 遇到 bug 时找问题根因，详细到具体哪个节点失败、哪个识别不符合预期，去修补对应节点的识别、操作问题。
59+
60+
**禁止：** 同样的操作再试一次、盲目添加 `max_hit`。
61+
62+
1. 当点击没反应时再点一次 → 通过 `pre_wait_freezes`、`post_wait_freezes` 等待画面静止，或增加中间节点确认按钮可点击后再执行。
63+
2. 当某个子任务失败后再跑一次 → 重试只能略微提高成功率，并不能根本解决问题，只会让代码变得难以维护。
64+
3. 当一个节点出现死循环后加 `max_hit` → 出现死循环一般是识别问题、逻辑缺陷导致，盲目加 `max_hit` 只会让逻辑中断。
65+
66+
### 处理弹窗和加载
67+
68+
好的流程不是"主线能跑就行"，而是：正常主线能跑、弹窗能处理、加载能等过去、不在目标场景时能自动跳过去。
69+
70+
常见做法是在 `next` 里挂：
71+
72+
- `[JumpBack]SceneAnyEnterWorld`
73+
- `[JumpBack]SceneClickBlankToExit`
74+
- `[JumpBack]SceneLoading`
75+
76+
### OCR 写完整文本
77+
78+
`expected` 写完整文本，不写半截。多语言处理由 CI 工作流自动完成。需要片段或手写正则时添加 `// @i18n-skip` 标记。
79+
80+
### 先复用，再新增
81+
82+
写新节点前，先查已有 Pipeline 是否已有现成能力。优先使用 [场景管理器](./scene-manager.md) 的公共接口，禁止直接引用 `__ScenePrivate*` 内部节点。
83+
84+
## Python CustomAction 规范
85+
86+
Python CustomAction 仅用于处理 Pipeline 难以实现的复杂逻辑。**流程控制由 Pipeline 负责，Python 只处理难点。**
87+
88+
一句话：**Pipeline 管流程，Python 管难点。**
89+
90+
_没有必要的 Python 逻辑会大大增加代码复杂度，造成下一位开发者开发调试极其困难。_
91+
92+
## 配套文件
93+
94+
MaaNTE 里一个功能改动常常不只改一个地方。
95+
96+
### 新增或修改任务
97+
98+
- `assets/resource/tasks/*.json`
99+
- `assets/resource/base/pipeline/**/*.json`
100+
- `assets/resource/locales/interface/zh_cn.json` 等五种语言文件
101+
- `assets/interface.json`（需注册 task 文件）
102+
103+
### 新增 Python CustomAction
104+
105+
- 在 `agent/custom/action/` 下新建 Python 文件
106+
- 在 `agent/custom/action/__init__.py` 中导入并加入 `__all__`
107+
108+
## 资源规范
109+
110+
### 分辨率：720p 基准
111+
112+
所有图片、坐标（`roi`、`target`、`box`）均以 **1280×720** 为基准。MaaFramework 在运行时会根据用户设备自动转换。推荐使用 **Maa Pipeline Support** 插件进行截图和坐标换算。
113+
114+
### HDR / 颜色管理
115+
116+
当被提示 "HDR" 或 "自动管理应用的颜色" 等功能已开启时，不要进行截图、取色等操作，可能导致模板效果与用户实际显示不符。
117+
118+
## 常见坑
119+
120+
| 坑 | 处理 |
121+
|-----|------|
122+
| 模型或依赖目录缺失 | `git submodule update --init --recursive` |
123+
| 直接引用了 `__ScenePrivate*` 节点 | 应引用 `Interface/Scene/` 目录暴露的公共接口节点 |
124+
| 只顾主线，不处理弹窗/加载 | 把弹窗、加载、中间态视为正常情况 |
125+
| 改了任务但没补文案 | 五种语言文件都要添加 i18n key |
126+
| OCR `expected` 写了片段 | 写完整文本，需要跳过时加 `@i18n-skip` |
127+
| 本地能跑但用户不行 | 检查帧率、颜色滤镜、HDR、分辨率是否与基准一致 |

‎docs/zh_cn/develop/common-buttons.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# 开发手册 - 通用按钮节点参考
2+
3+
> [!NOTE]
4+
> 异环中可复用图形类按钮标志较少，目前常用仅有关闭与主界面按钮一类，不多作说明

0 commit comments

Comments
 (0)