Skip to content

Commit 9d8a7c7

Browse files
author
Natsuu
authored
docs: reorganize development documentation structure (#35)
1 parent d340115 commit 9d8a7c7

7 files changed

Lines changed: 1176 additions & 92 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -16,56 +16,7 @@
1616
1717
## 即刻开始
1818

19-
- [📄 快速开始](https://maafw.com/docs/1.1-QuickStarted)
20-
- ~~[🎞️ 视频教程](https://www.bilibili.com/video/BV1yr421E7MW)~~ 视频中使用的MaaFramework版本较老，建议以文档为准。
21-
22-
## 如何开发
23-
24-
0. 使用右上角 `Use this template` - `Create a new repository` 来基于本模板创建您自己的项目。
25-
26-
1. 克隆本项目（地址请修改为您基于本模板创建的新项目地址）。
27-
28-
```bash
29-
git clone https://github.com/MaaXYZ/MaaPracticeBoilerplate.git
30-
```
31-
32-
2. 下载 OCR（文字识别）资源文件 [ppocr_v5.zip](https://download.maafw.xyz/MaaCommonAssets/OCR/ppocr_v5/ppocr_v5-zh_cn.zip) 解压到 `assets/resource/model/ocr/` 目录下，确保路径如下：
33-
34-
```tree
35-
assets/resource/model/ocr/
36-
├── det.onnx
37-
├── keys.txt
38-
└── rec.onnx
39-
```
40-
41-
_请注意，您不需要将 OCR 资源文件上传到您的代码仓库中。`.gitignore` 已经忽略了 `assets/resource/model/ocr/` 目录，且 GitHub workflow 在发布版本时会自动配置这些资源文件。_
42-
43-
3. 进行开发工作。请参考 [MaaFramework 相关文档](https://maafw.com/docs/1.1-QuickStarted)，并按您的业务需求修改 `assets` 目录下的 `resource` 资源文件以及 `interface.json` 文件，然后使用 [开发工具](https://maafw.com/docs/1.1-QuickStarted#%E8%B0%83%E8%AF%95)进行调试。
44-
45-
4. 完成开发后，上传您的代码并发布版本。
46-
47-
```bash
48-
# 配置 git 信息（仅第一次需要，后续不用再配置）
49-
git config user.name "您的 GitHub 昵称"
50-
git config user.email "您的 GitHub 邮箱"
51-
52-
# 提交修改
53-
git add .
54-
git commit -m "XX 新功能"
55-
git push origin HEAD -u
56-
```
57-
58-
5. 发布您的版本
59-
60-
需要**先**修改仓库设置 `Settings` - `Actions` - `General` - `Read and write permissions` - `Save`
61-
62-
```bash
63-
# CI 检测到 tag 会自动进行发版
64-
git tag v1.0.0
65-
git push origin v1.0.0
66-
```
67-
68-
6. 更多操作，请参考 [个性化配置](./docs/zh_cn/个性化配置.md)（可选）
19+
请阅读[如何开发](./docs/zh_cn/develop/how_to_develop.md)
6920

7021
## 生态共建
7122

@@ -75,48 +26,9 @@ MAA 正计划建设为一类项目，而非舟的单一软件。
7526

7627
同时，我们也非常欢迎您提出 PR，在 [社区项目列表](https://github.com/MaaXYZ/MaaFramework#%E7%A4%BE%E5%8C%BA%E9%A1%B9%E7%9B%AE) 中添加上您的项目！
7728

78-
## FAQ
79-
80-
### 0. 我是第一次使用 git，这是什么？视频演示中那个黑框框命令行哪来的？
81-
82-
黑框框是 git bash，几乎任何现代软件的开发都离不开 git，建议先参考 [菜鸟教程](https://www.runoob.com/git/git-install-setup.html) 或搜索一些视频，学习完 git 后再来进行后续开发工作。
83-
84-
### 1. 我是第一次使用 Python，在命令行输入 `python ./configure.py` 或 `python -m pip install MaaFW` 之后没有反应？没有报错，也没有提示成功，什么都没有
85-
86-
Win10 或者 Win11 系统自带了一份 "Python"，但它其实只是一个安装器，是没法用的。
87-
你需要做的是关闭它或者删除它的环境变量，然后自己去 Python 官网下载并安装一份 Python。
88-
[参考方法](https://www.bilibili.com/read/cv24692025/)
89-
90-
### 2. 使用 MaaDebugger 或 MaaPicli 时弹窗报错，应用程序错误：应用程序无法正常启动
91-
92-
![缺少运行库](https://github.com/user-attachments/assets/942df84b-f47d-4bb5-98b5-ab5d44bc7c2a)
93-
94-
一般是电脑缺少某些运行库，请安装一下 [vc_redist](https://aka.ms/vs/17/release/vc_redist.x64.exe) 。
95-
96-
### 3. 我应该如何打包我的项目？
97-
98-
你需要按照项目推荐的[开发流程](#如何开发)发布一个版本，[CI](/.github/workflows/install.yml) 会自动完成打包工作。具体的工作方式请参考 [GitHub Actions 文档](https://docs.github.com/zh/actions)。
99-
100-
### 4. 我在这个仓库里提了 Issue 很久没人回复
101-
102-
这里是《项目模板》仓库，它仅仅是一个模板，一般很少会修改，开发者也较少关注。
103-
在此仓库请仅提问模板相关问题，其他问题最好前往对应的仓库提出，如果有 log，最好也带上它（`debug/maa.log` 文件）
104-
105-
- MaaFW 本身及 MaaPiCli 的问题：[MaaFramework/issues](https://github.com/MaaXYZ/MaaFramework/issues)
106-
- MaaDebugger 的问题：[MaaDebugger/issues](https://github.com/MaaXYZ/MaaDebugger/issues)
107-
- 不知道算是哪里的、其他疑问等：[讨论区](https://github.com/MaaXYZ/MaaFramework/discussions)
108-
109-
### 5. OCR 文字识别一直没有识别结果，报错 "Failed to load det or rec", "ocrer_ is null"
110-
111-
**请仔细阅读文档**，你无视了前面步骤的报错。我不想解释了，请再把本文档仔细阅读一遍！
112-
113-
### 6. 在开发过程中遇到了其他问题
114-
115-
闭门造车大概率无法解决任何问题，你可以加入 [MaaFramework 开发交流群](http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&k=9sleK6URhEG0v3QeTmpFueCjF26wibEH&authKey=LBZc5FxWa3M%2BiWj3rpBfRmqg9PD9jJNaxpp3xTqTcGxsp1Am3kd1uzxQXiP4w8w4&noverify=0&group_code=595990173) 以寻求帮助。
29+
## 常见问题
11630

117-
> [!WARNING]
118-
> 在提问前，请完整阅读 [MaaFramework 开发文档](https://maafw.com/docs/1.1-QuickStarted)以及[如何开发](#如何开发)，通常情况下他们能解决大多数问题。
119-
> 在提问时，请 **具体指出文档中困惑的章节** / **分享你的项目文件中的具体内容** / **提供完整的报错信息** ，不然你能得的大概率只有类似 _“请先读文档”_ 这样的回答。
31+
请阅读[常见问题](./docs/zh_cn/develop/faq.md)
12032

12133
## 鸣谢
12234

docs/zh_cn/个性化配置.md renamed to docs/zh_cn/develop/custom_configure.md

File renamed without changes.

‎docs/zh_cn/develop/faq.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# FAQ
2+
3+
## 0. 我是第一次使用 git，这是什么？视频演示中那个黑框框命令行哪来的？
4+
5+
黑框框是 git bash，几乎任何现代软件的开发都离不开 git，建议先参考 [菜鸟教程](https://www.runoob.com/git/git-install-setup.html) 或搜索一些视频，学习完 git 后再来进行后续开发工作。
6+
7+
## 1. 我是第一次使用 Python，在命令行输入 `python ./configure.py` 或 `python -m pip install MaaFW` 之后没有反应？没有报错，也没有提示成功，什么都没有
8+
9+
Win10 或者 Win11 系统自带了一份 "Python"，但它其实只是一个安装器，是没法用的。
10+
你需要做的是关闭它或者删除它的环境变量，然后自己去 Python 官网下载并安装一份 Python。
11+
[参考方法](https://www.bilibili.com/read/cv24692025/)
12+
13+
## 2. 使用 MaaDebugger 或 MaaPiCli 时弹窗报错，应用程序错误：应用程序无法正常启动
14+
15+
![缺少运行库](https://github.com/user-attachments/assets/942df84b-f47d-4bb5-98b5-ab5d44bc7c2a)
16+
17+
一般是电脑缺少某些运行库，请安装一下 [vc_redist](https://aka.ms/vs/17/release/vc_redist.x64.exe) 。
18+
19+
## 3. 我应该如何打包我的项目？
20+
21+
你需要按照项目推荐的[开发流程](./how_to_develop.md)发布一个版本，[CI](/.github/workflows/install.yml) 会自动完成打包工作。具体的工作方式请参考 [GitHub Actionss 文档](https://docs.github.com/zh/actions)。
22+
23+
## 4. 我在这个仓库里提了 Issue 很久没人回复
24+
25+
这里是《项目模板》仓库，它仅仅是一个模板，一般很少会修改，开发者也较少关注。
26+
在此仓库请仅提问模板相关问题，其他问题最好前往对应的仓库提出，如果有 log，最好也带上它（`debug/maa.log` 文件）
27+
28+
- MaaFW 本身及 MaaPiCli 的问题：[MaaFramework/issues](https://github.com/MaaXYZ/MaaFramework/issues)
29+
- MaaDebugger 的问题：[MaaDebugger/issues](https://github.com/MaaXYZ/MaaDebugger/issues)
30+
- 不知道算是哪里的、其他疑问等：[讨论区](https://github.com/MaaXYZ/MaaFramework/discussions)
31+
32+
## 5. OCR 文字识别一直没有识别结果，报错 "Failed to load det or rec", "ocrer_ is null"
33+
34+
**请仔细阅读文档**，你无视了前面步骤的报错。我不想解释了，请再把本文档仔细阅读一遍！
35+
36+
## 6. 在开发过程中遇到了其他问题
37+
38+
闭门造车大概率无法解决任何问题，你可以加入 [MaaFramework 开发交流群](http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&k=9sleK6URhEG0v3QeTmpFueCjF26wibEH&authKey=LBZc5FxWa3M%2BiWj3rpBfRmqg9PD9jJNaxpp3xTqTcGxsp1Am3kd1uzxQXiP4w8w4&noverify=0&group_code=595990173) 以寻求帮助。
39+
40+
> [!WARNING]
41+
> 在提问前，请完整阅读 [MaaFramework 开发文档](https://maafw.com/docs/1.1-QuickStarted)以及[如何开发](./how_to_develop.md)，通常情况下他们能解决大多数问题。
42+
> 在提问时，请 **具体指出文档中困惑的章节** / **分享你的项目文件中的具体内容** / **提供完整的报错信息** ，不然你能得的大概率只有类似 _“请先读文档”_ 这样的回答。

‎docs/zh_cn/develop/how_to_develop.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# 如何开发
2+
3+
在开始开发前请先阅读 MaaFramework 开发文档的[快速开始](https://maafw.com/docs/1.1-QuickStarted)章节，以便你对MaaFramework 有一个基本的了解。
4+
5+
~~同时，我们还提供了一个[🎞️ 视频教程](https://www.bilibili.com/video/BV1yr421E7MW)以供参考。~~ 视频中使用的版本较老，一切问题须以最新版文档为准。
6+
7+
## 开发前提
8+
9+
使用本教程进行开发则默认你遵守MaaFramework衍生项目的相关开发规范以及共识，所有的讨论也将基于以下前提。
10+
11+
1. 使用基于 git 作为版本控制工具
12+
如果你还不会用，可以先在[菜鸟教程](https://www.runoob.com/git/git-tutorial.html)进行学习。
13+
2. 使用 GitHub 托管代码并使用相关 [CI/CD 工作流](https://docs.github.com/zh/actions)
14+
项目中附带了一些基于 [GitHub Actions](https://docs.github.com/zh/actions) 的 CI/CD 工作流配置，你可以通过他们来自动进行测试以及将项目打包和发布。
15+
3. 了解本框架中一些常见的术语
16+
MaaFramework 手册中的[术语解释](https://maafw.com/docs/1.2-ExplanationOfTerms)章节介绍了一些基本的专有术语。
17+
18+
## 开发步骤
19+
20+
0. 使用右上角 `Use this template` - `Create a new repository` 来基于本模板创建您自己的项目。
21+
22+
1. 克隆你的项目（地址请修改为您基于本模板创建的新项目地址）。
23+
24+
```bash
25+
git clone https://github.com/MaaXYZ/MaaPracticeBoilerplate.git
26+
```
27+
28+
2. 下载 OCR（文字识别）资源文件 [ppocr_v5.zip](https://download.maafw.xyz/MaaCommonAssets/OCR/ppocr_v5/ppocr_v5-zh_cn.zip) 解压到 `assets/resource/model/ocr/` 目录下，确保路径如下：
29+
30+
```tree
31+
assets/resource/model/ocr/
32+
├── det.onnx
33+
├── keys.txt
34+
└── rec.onnx
35+
```
36+
37+
> [!WARNING]
38+
> 请注意，您不需要将 OCR 资源文件上传到您的代码仓库中。`.gitignore` 已经忽略了 `assets/resource/model/ocr/` 目录，且 GitHub workflow 在发布版本时会自动配置这些资源文件。
39+
40+
_如果希望使用其他版本的模型，可以参考[这个说明](https://github.com/MaaXYZ/MaaCommonAssets/tree/main/OCR)。_
41+
42+
3. 进行开发工作。请参考 [MaaFramework 相关文档](https://maafw.com/docs/1.1-QuickStarted)，并按您的业务需求修改 `assets` 目录下的 `resource` 资源文件以及 `interface.json` 文件，然后使用 [开发工具](https://maafw.com/docs/1.1-QuickStarted#%E8%B0%83%E8%AF%95)进行调试。
43+
44+
4. 完成开发后，上传您的代码并发布版本。
45+
46+
```bash
47+
# 配置 git 信息（仅第一次需要，后续不用再配置）
48+
git config user.name "您的 GitHub 昵称"
49+
git config user.email "您的 GitHub 邮箱"
50+
51+
# 提交修改
52+
git add .
53+
git commit -m "XX 新功能"
54+
git push origin HEAD -u
55+
```
56+
57+
5. 发布您的版本
58+
59+
本模板附带 GitHub Actionss 工作流的配置文件，CI 检测到 tag 会自动将 [MFAAvalonia](https://github.com/SweetSmellFox/MFAAvalonia) 与你的项目一同打包和发版。
60+
61+
> [!NOTE]
62+
> 第一次操作前，需要**先**修改 Github 仓库设置 `Settings` - `Actions` - `General` - `Read and write permissions` - `Save`
63+
64+
```bash
65+
# CI 检测到 tag 会自动进行发版
66+
git tag v1.0.0
67+
git push origin v1.0.0
68+
```
69+
70+
执行上述命令后，CI 会自动进行打包和发布，你可以在项目仓库的 `Actions` 页面中看到工作流的执行情况。如果一切顺利，运行结束后你可以在项目仓库的 `Releases` 页面中看到新发布的版本。
71+
72+
## 常见问题
73+
74+
请参考 [FAQ](./faq.md)
75+
76+
## 更多操作
77+
78+
请参考 [个性化配置](./custom_configure.md)（可选）

‎maatools.config.mts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,13 @@ const config: FullConfig = {
44
cwd: import.meta.dirname,
55
maaVersion: 'latest',
66
interfacePath: 'assets/interface.json',
7-
check: {}
7+
check: {
8+
override: {
9+
// 忽略 mpe-config 带来的报错
10+
// ignore warning caused by mpe-config
11+
// 'mpe-config': 'ignore'
12+
}
13+
}
814
}
915

1016
export default config

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"devDependencies": {
33
"@nekosu/maa-tools": "1.0.23",
4+
"@types/node": "^25.5.2",
45
"prettier-plugin-multiline-arrays": "^3.0.6"
56
}
67
}

0 commit comments

Comments
 (0)