diff --git a/docs/components/manager.md b/docs/components/manager.md index 1b5f543..cc5dd5b 100644 --- a/docs/components/manager.md +++ b/docs/components/manager.md @@ -13,11 +13,28 @@ ModAVD 0.36.0 起包里带两个管理程序,源码在 [ModAVDManager](https:/ 双击包根的 `ModAVD.exe`:起一个只听 127.0.0.1 的本地服务,再用 Edge 的应用模式开一个窗口(Windows 10 / 11 自带 Edge);找不到 Edge 时用默认浏览器。页面内嵌在程序里,不联网。 -- 功能:实例卡片(在线时有画面缩略图)、开关机(带进度)、新建、设置、删除、电脑检查、活动面板、画面查看(点击即点按,返回 / 主页 / 最近任务)、日志、安装 APK、打开目录;浅色 / 深色 / 跟随系统。管理器 0.4.0 起还有[按应用走代理](./app-proxy)。 +- 功能:实例卡片(在线时有画面缩略图)、开关机(带进度)、新建、设置、删除、电脑检查、[组件与问题反馈](#组件与问题反馈)(管理器 0.3.0 起)、活动面板、画面查看(点击即点按,返回 / 主页 / 最近任务)、日志、安装 APK、打开目录;浅色 / 深色 / 跟随系统。管理器 0.4.0 起还有[按应用走代理](./app-proxy)。 - 管理器开机一律带窗口;无头开机用命令行或 MCP。无头运行的实例也能在这里关机。 - 一个根目录只开一个服务,再双击只是把窗口重新打开;日志在 `<根>\logs\modavd-ui.log`。 - 关掉窗口后,等正在跑的任务做完再退出。 +## 组件与问题反馈 + +版本号提醒:下面写的「管理器 0.3.0 起」是 ModAVDManager 自己的版本(管理器和命令行共用一个版本号),和 ModAVD 整包的版本(如 0.38.2)是两套编号;整包里带的是哪一版管理器,见整包的发布说明。 + +管理器的「设置」→「组件与问题反馈」面板把三件事放在一起,命令行有对应的命令: + +| 在面板里 | 命令行 | 做什么 | +| --- | --- | --- | +| 组件状态 | `components status` | 看 adb 和系统镜像装没装,可选的 Google Play 商店服务有没有(只读) | +| 补全组件 | `components fetch` | 从官方渠道下载 adb 和系统镜像:选下载源、读 Google 许可协议、同意后才下载,有进度和「取消」 | +| 收集问题信息 | `collect-info` | 把日志、配置和电脑信息打成一个 zip 放在桌面,做完显示路径和隐私提示(只读,不联网、不上传) | +| 复制配置信息 | `report-config` | 把电脑配置和开着的实例里装的游戏整理成一段文字,复制到剪贴板并显示(只读) | + +- 面板里的「组件状态」只显示状态。缺组件时,首页上有一条带「补全组件」按钮的横幅,「电脑检查」里没通过的「组件」一项下面也有这个按钮。完整步骤、下载源和出错处理见[安装](../guide/install#_2-补全组件)。 +- 收集的内容、哪些能公开贴,见[反馈问题](../guide/feedback)和[隐私](../guide/privacy)。 +- 0.38.1 及更早的整包里,这三件事是包根的三个 `.bat`;0.38.2 起没有了,由管理器和命令行做。 + ## 命令行 ``` @@ -36,6 +53,9 @@ modavd [--root <目录>] [--json] [--quiet] [--verbose] <命令> [参数] | `bridge install\|uninstall\|verify` | 装、卸、检查 arm64 执行桥 | | `proxy [on\|off\|test] [--server URL\|auto] [--add 包名] [--remove 包名] [--apps 包名]` | 管理器 0.4.0 起:[按应用走代理](./app-proxy),名单里的应用走代理,其余直连 | | `check [--memory M]` | 开机前的电脑检查 | +| `components [status]`、`components source [auto\|googledownloads_cn\|tencent\|google]`、`components fetch [--accept-license] [--keep-downloads]` | 管理器 0.3.0 起:查看组件状态、选下载源、补全 Google 组件。`fetch` 先显示许可协议,输入 `y` 才下载;`--json` 时必须带 `--accept-license`。只有 Windows 有组件清单,其他系统返回 `unsupported` | +| `collect-info [--out-dir D] [--no-explorer]` | 管理器 0.3.0 起:收集问题信息,生成 zip,默认放桌面并在资源管理器里选中 | +| `report-config [--no-clipboard]` | 管理器 0.3.0 起:复制配置信息,默认复制到剪贴板 | | `window show\|hide` | 显示 / 隐藏带窗口开机的实例;无头实例没有窗口 | | `install `、`shell <命令>`、`adb -- <参数>` | 装 APK、客体命令、adb 透传 | | `servers`、`version`、`mcp`、`help [命令]` | | diff --git a/docs/develop/manager.md b/docs/develop/manager.md index dffbf2e..cffa5e9 100644 --- a/docs/develop/manager.md +++ b/docs/develop/manager.md @@ -36,7 +36,7 @@ pwsh -NoProfile -File build.ps1 -Test # 先跑 go vet 和 go test ## 验证 - `gofmt -l .` 为空,`go vet ./...`、`go test ./...` 通过; -- 有一部分测试用 Python 3 运行 AUTO-MAS 的原始逻辑,和 Go 的输出逐字节对照,所以要装 Python 3; +- 有一部分测试用 Python 3 运行 AUTO-MAS 的原始逻辑,和 Go 的输出逐字节对照,所以要装 Python 3:环境变量 `MODAVD_TEST_PYTHON` 指向它,不设就用 PATH 上的 `python`,找不到就跳过那几个对照测试; - 实测要一个 ModAVD 根目录:Release 包解压,再补全组件; - 实测用新建的实例、私有 adb 端口; - 开发、测试用的根目录换一段端口:同一台电脑上还有日常在用的根目录(比如 AUTO-MAS 用的那个)时,在开发根目录的 `mas-avd.json` 里写 `"portBase": 21000`,这个根目录的实例就从 21000 起算端口,不和那边同编号的实例抢。要带 [ModAVD/ModAVD#75](https://github.com/ModAVD/ModAVD/issues/75) 的管理器。 @@ -45,7 +45,28 @@ pwsh -NoProfile -File build.ps1 -Test # 先跑 go vet 和 go test - 改之前先关掉这个根目录的所有实例。AUTO-MAS 还不认 `portBase`,设了的根目录不要加进 AUTO-MAS。 - 不要对放着重要实例的根目录开实机测试开关(`MODAVD_TEST_LIVE=1`)。 -CI 在 PR 上跑格式检查、`go vet`、`go test`、`build.ps1`、隐私扫描和作者检查。 +CI 在 PR 上跑: + +- Windows:全套,包括格式检查、`go vet`、`go test`、`build.ps1`、隐私扫描和作者检查,另外用 `GOOS=darwin GOARCH=arm64`、`GOOS=linux GOARCH=amd64` 各交叉 `go vet` 一遍; +- macOS 和 Linux:只在对应系统上跑 `go vet` 和 `go test`,不编出可发布的程序,也不开模拟器。 + +## 平台层 + +管理器目前以 Windows x64 为主,平台相关的部分拆在两处: + +- `internal/win`:Windows 的进程、命令行、端口、脱离进程树的启动、文件锁、窗口等操作。这些文件都带 `//go:build windows`,别的系统编译时不包含它们; +- `internal/root/platform.go`:平台表。`Platform` 结构按宿主系统和架构给出一行固定的值:模拟器、adb、QEMU(含无头版)的文件名,QEMU 所在的子目录,整包文件名的后缀,Mirror 酱的系统和架构标识,客体的 ABI 和架构、目标 API,以及系统镜像的目录和名字。`CurrentPlatform()` 现在有 Windows x64、macOS arm64、Linux x64 三行,其余组合返回空表,`Supported()` 为 `false`,不会沿用 Windows 的名字。共用的代码查这张表,不要在里面写死 `.exe` 或 x86_64。 + +这张表只管文件名和标识,不管根目录布局、端口和实例路径的规则(那些在 `internal/root` 的其他文件里)。 + +非 Windows 的部分放在各包的 `*_other.go` 这类文件里(宿主相关的在 `internal/host`),多数先是返回 `Unsupported` 的桩,各命令照实报 `unsupported`(退出码 4);比如组件清单只有 Windows 有。要给一个新平台补上,大致是: + +1. 在平台表里加这一行(或改现有的行),补上该平台的测试; +2. 把 Windows 专有的操作(`internal/win` 里的,以及各包 `*_other.go` 里的桩)写成对应平台的实现,用构建标签区分,替换掉桩; +3. 组件下载、整包更新、打包和签名按平台各做一份; +4. 在对应系统的 CI 上跑 `go vet`、`go test`。 + +总体安排和各平台的分工见 [ModAVD/ModAVD#27](https://github.com/ModAVD/ModAVD/issues/27),macOS 平台层的具体做法见 [ModAVD/ModAVD#68](https://github.com/ModAVD/ModAVD/issues/68)。 ## 契约 diff --git a/docs/en/components/manager.md b/docs/en/components/manager.md index 1e0c3ef..9c9aef5 100644 --- a/docs/en/components/manager.md +++ b/docs/en/components/manager.md @@ -13,11 +13,28 @@ Instance files and `mas-avd.json` are written the same way as in AUTO-MAS, so in Double-click `ModAVD.exe` in the package root. It starts a local server that listens only on 127.0.0.1, then opens a window in Edge app mode (Edge comes with Windows 10 / 11); if Edge is not found, it uses the default browser. The page is embedded in the program and does not use the network. -- Features: instance cards (with a screen thumbnail when the instance is online), start and stop (with progress), create, settings, delete, PC check, activity panel, screen view (a click is a tap; Back / Home / Recents), logs, install APK, open folder; light / dark / follow system. Since manager 0.4.0 there is also the [per-app proxy](./app-proxy). +- Features: instance cards (with a screen thumbnail when the instance is online), start and stop (with progress), create, settings, delete, PC check, [components and feedback](#components-and-feedback) (since manager 0.3.0), activity panel, screen view (a click is a tap; Back / Home / Recents), logs, install APK, open folder; light / dark / follow system. Since manager 0.4.0 there is also the [per-app proxy](./app-proxy). - The manager always starts instances with a window; use the CLI or MCP for headless starts. Headless instances can also be shut down here. - One server runs per root folder; double-clicking again only reopens the window. The log is at `\logs\modavd-ui.log`. - After you close the window, it waits for the running tasks to finish before it exits. +## Components and feedback + +A note on version numbers: "since manager 0.3.0" below is the version of ModAVDManager itself (the manager and the CLI share one version number). It is a different numbering from the ModAVD package version (such as 0.38.2); the package's release notes say which manager version it contains. + +**设置 → 组件与问题反馈** (Settings → Components and feedback) in the manager puts three jobs in one panel, and the CLI has matching commands: + +| In the panel | CLI | What it does | +| --- | --- | --- | +| Component status | `components status` | Shows whether adb and the system image are installed, and whether the optional Google Play Store services are present (read-only) | +| **补全组件** (Fetch components) | `components fetch` | Downloads adb and the system image from the official source: pick a download source, read Google's license, and only after you agree does it download; shows progress and a Cancel button | +| **收集问题信息** (Collect a problem report) | `collect-info` | Packs logs, configuration and computer info into one zip on the desktop, then shows its path and a privacy note (read-only; no network, no upload) | +| **复制配置信息** (Copy configuration info) | `report-config` | Puts the computer's configuration and the games installed in running instances into one block of text, copies it to the clipboard and shows it (read-only) | + +- The component status in the panel is display-only. When components are missing, the home page shows a banner with a **补全组件** button, and the same button is under the failed **组件** (Components) item of **电脑检查** (Computer check). For the full steps, download sources and error handling, see [Install](../guide/install#_2-fetch-the-google-components). +- For what is collected and what is safe to post publicly, see [Reporting problems](../guide/feedback) and [Privacy](../guide/privacy). +- In packages 0.38.1 and earlier these three jobs were three `.bat` files in the package root; from 0.38.2 they are gone and the manager and CLI do them. + ## The CLI ``` @@ -36,6 +53,9 @@ modavd [--root ] [--json] [--quiet] [--verbose] [args] | `bridge install\|uninstall\|verify` | Install, uninstall or check the arm64 execution bridge | | `proxy [on\|off\|test] [--server URL\|auto] [--add pkg] [--remove pkg] [--apps pkg]` | Since manager 0.4.0: the [per-app proxy](./app-proxy); the listed apps use the proxy, the others go direct | | `check [--memory M]` | PC check before starting | +| `components [status]`, `components source [auto\|googledownloads_cn\|tencent\|google]`, `components fetch [--accept-license] [--keep-downloads]` | Since manager 0.3.0: show component status, choose the download source, fetch the Google components. `fetch` shows the license first and downloads only after you type `y`; with `--json` it requires `--accept-license`. Only Windows has a component list; other systems return `unsupported` | +| `collect-info [--out-dir D] [--no-explorer]` | Since manager 0.3.0: collect a problem report as a zip, placed on the desktop and selected in File Explorer by default | +| `report-config [--no-clipboard]` | Since manager 0.3.0: copy the configuration info, to the clipboard by default | | `window show\|hide` | Show or hide the window of an instance started with one; headless instances have no window | | `install `, `shell `, `adb -- ` | Install an APK, guest command, adb passthrough | | `servers`, `version`, `mcp`, `help [command]` | | diff --git a/docs/en/develop/manager.md b/docs/en/develop/manager.md index 03acd6f..8827806 100644 --- a/docs/en/develop/manager.md +++ b/docs/en/develop/manager.md @@ -36,7 +36,7 @@ It uses `-trimpath -buildvcs=false` and does not write the version number with ` ## Verification - `gofmt -l .` prints nothing, and `go vet ./...` and `go test ./...` pass; -- Some tests run AUTO-MAS's original logic with Python 3 and compare it with Go's output byte by byte, so Python 3 must be installed; +- Some tests run AUTO-MAS's original logic with Python 3 and compare it with Go's output byte by byte, so Python 3 must be installed: point the environment variable `MODAVD_TEST_PYTHON` at it; if it is not set, `python` on PATH is used, and if that is not found, those comparison tests are skipped; - Testing on a real instance needs a ModAVD root folder: extract the release package, then fetch the Google components; - Use newly created instances and a private adb port for these tests; - Give root folders for development and testing their own port range: when the same computer also has a root folder in daily use (for example the one AUTO-MAS uses), write `"portBase": 21000` in the `mas-avd.json` of the development root folder. Its instances then count their ports from 21000 and do not fight with the instances of the same number over there. This needs a manager with [ModAVD/ModAVD#75](https://github.com/ModAVD/ModAVD/issues/75). @@ -45,7 +45,28 @@ It uses `-trimpath -buildvcs=false` and does not write the version number with ` - Shut down every instance of the root folder before you change it. AUTO-MAS does not know `portBase` yet, so do not add a root folder that sets it to AUTO-MAS. - Do not turn on the live-test switch (`MODAVD_TEST_LIVE=1`) against a root folder that holds important instances. -CI runs the format check, `go vet`, `go test`, `build.ps1`, the privacy scan and the author check on PRs. +On PRs, CI runs: + +- Windows: the full set: the format check, `go vet`, `go test`, `build.ps1`, the privacy scan and the author check, plus a cross `go vet` with `GOOS=darwin GOARCH=arm64` and with `GOOS=linux GOARCH=amd64`; +- macOS and Linux: only `go vet` and `go test` on the matching system. They do not build a releasable program or start an emulator. + +## Platform layer + +The manager is mainly for Windows x64 today. The platform-specific parts are split into two places: + +- `internal/win`: the Windows operations for processes, command lines, ports, starting outside the process tree, file locks and windows. These files carry `//go:build windows`, so other systems do not compile them; +- `internal/root/platform.go`: the platform table. The `Platform` struct gives one fixed row of values per host system and architecture: the file names of the emulator, adb and QEMU (including the headless one), the subdirectory QEMU lives in, the suffix of the package file name, the MirrorChyan system and architecture ids, the guest ABI and architecture and the target API, and the system image directory and name. `CurrentPlatform()` currently has three rows, Windows x64, macOS arm64 and Linux x64; any other combination returns an empty table, `Supported()` is `false`, and it does not inherit the Windows names. Shared code looks things up in this table; do not hard-code `.exe` or x86_64 in it. + +The table covers only file names and identifiers. The rules for the root folder layout, ports and instance paths are not in it (they are in the other files of `internal/root`). + +The non-Windows side lives in files such as `*_other.go` in each package (the host-related part is in `internal/host`). Most of it is first a stub that returns `Unsupported`, and commands report `unsupported` (exit code 4) honestly; for example, only Windows has a component list. To add a new platform you roughly need to: + +1. Add its row to the platform table (or change the existing one) and add tests for it; +2. Write the Windows-only operations (those in `internal/win` and the stubs in each package's `*_other.go`) for that platform, separated by build tags, replacing the stubs; +3. Do component download, package update, packaging and signing once per platform; +4. Run `go vet` and `go test` in CI on that system. + +The overall plan and who takes which platform are in [ModAVD/ModAVD#27](https://github.com/ModAVD/ModAVD/issues/27); how the macOS platform layer is done is in [ModAVD/ModAVD#68](https://github.com/ModAVD/ModAVD/issues/68). ## Contract