qiyinxi · Nov 5, 2026 · Nov 4, 2026
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -21,6 +21,7 @@ const guide: Page[] = [
 
 const components: Page[] = [
   ['/components/manager', '管理器和命令行', 'The manager and CLI'],
+  ['/components/app-proxy', '按应用走代理', 'Per-app proxy'],
   ['/components/bridge', 'arm64 执行桥', 'The arm64 execution bridge'],
   ['/components/ime', '宿主输入法', 'The host IME'],
 ]

diff --git a/docs/components/app-proxy.md b/docs/components/app-proxy.md
@@ -0,0 +1,111 @@
+# 按应用走代理
+
+管理器 0.4.0 起，可以让实例里指定的应用（按包名）经这台电脑上的代理软件联网，别的应用照旧直连。比如只让海外服的游戏走代理，国服游戏和系统照常。
+
+- 不用 VPN：实例里有一个以 root 运行的小程序（`modavd-proxyd`，随 `modavd.exe` 带着，开机时放进实例），按应用接走名单里应用的 TCP、UDP 和 DNS，应用和系统都看不到 VPN。
+- 代理软件（Clash 系之类）还是要你自己在电脑上开着，ModAVD 只负责把名单里应用的流量送过去。
+
+::: warning 代理断了就断网
+代理软件关了或连不上时，名单里的应用**断网**，不会悄悄改走直连。
+:::
+
+## 要准备什么
+
+- 电脑上开着代理软件，最好用它的 SOCKS5 端口或混合端口（Clash 系常见的 7890、7897），TCP、UDP、DNS 都能走。
+- 只有 HTTP 代理也能用，但只转 TCP 和 DNS：名单里应用的 UDP 不通，游戏里的语音、实时对战这类可能用不了。
+- 实例里的 `10.0.2.2` 就是这台电脑的 `127.0.0.1`。代理软件只听本机也行，不用打开「允许局域网连接」。
+- 实例要用管理器或命令行 `modavd` 开机才会挂上代理。不经过 modavd、由别的程序直接拉起的模拟器不会挂上。
+
+## 在管理器里设
+
+1. 实例卡片右下角的「⋯」→「按应用走代理…」。卡片上已经有「代理」标记时，点标记也能打开。
+2. 打开「名单里的应用走代理」。
+3. 代理地址：
+   - 点「从系统代理读取」，取这台电脑的代理设置（环境变量 `ALL_PROXY`、`HTTPS_PROXY`、`HTTP_PROXY`，或 Windows「Internet 选项」里手动设的代理）；
+   - 或者手填 `socks5://127.0.0.1:7890` 这样的地址，不写协议也行，点「检测」看它是什么协议、UDP 能不能用。
+   - `127.0.0.1`、`localhost` 会记成实例里看到的 `10.0.2.2`；混合端口写成了 `http://` 时会换成 `socks5://`。换了什么都写在检测结果下面。
+4. 应用名单：
+   - 实例开着时，列出装了的第三方应用和 Google Play 服务，打勾就行；认得的游戏写中文名。
+   - 实例没开时，在下面手填包名（比如 `com.example.game`），回车添加。
+   - 名单里有、但实例里还没装的应用标「没装」，装上就生效。名单最多 64 个。
+5. 点「保存」。实例开着就马上生效；没开就下次用管理器或 `modavd` 开机时生效。
+
+对话框底下的「现在」一栏写的是保存了的设置现在怎样，和卡片上的标记是同一个意思。
+
+::: tip 用 Google 登录的海外游戏
+把「Google Play 服务」（`com.google.android.gms`）也加进名单。名单里没有它时，对话框会提示，点「加进名单」就行。
+:::
+
+要关掉，取消「名单里的应用走代理」再保存。地址和名单会留着，下次打开不用重填。
+
+## 卡片上的「代理」标记 {#mark}
+
+设置打开、名单不空时，实例卡片的标题旁有「代理」标记，卡片和列表两种视图都有。鼠标停在上面能看到详情，点它打开设置。
+
+实例开着时，管理器窗口开着期间大约每 30 秒问一次实例里的状态；开机、关机或改了设置时马上再问。
+
+| 颜色 | 意思 |
+|---|---|
+| 灰 | 实例没开（写着几个应用、走哪个代理，下次开机生效）；正在开机或关机；或者正在问实例里的状态 |
+| 绿 | 已生效：几个应用（几个还没装）→ 代理地址。代理不转 UDP 时后面写「UDP 不通」 |
+| 黄 | 要留意，名单里的应用多半还能用：规则缺了几条、正在补上；最近一次经代理的连接没成功，但这台电脑能连到代理；这次没问到实例里的状态 |
+| 红 | 名单里的应用现在**断网或直连**：代理连不上；实例里的代理程序没在跑；规则挂不上；保存了但没生效 |
+
+## 命令行
+
+```powershell
+tools\modavd.exe proxy 3                                          # 查看
+tools\modavd.exe proxy 3 on --server auto --add com.example.game  # 打开，取这台电脑的代理设置
+tools\modavd.exe proxy 3 --add com.google.android.gms             # 往名单里加
+tools\modavd.exe proxy 3 test                                     # 在这台电脑上探测代理
+tools\modavd.exe proxy 3 off                                      # 关掉，地址和名单留着
+```
+
+- 不带别的参数是查看：开关、地址、名单；实例开着时附上实例里的实际状态（规则在不在、代理连没连上、名单里哪些还没装）。
+- `on` 打开、`off` 关掉；`--server` 改地址，`--add` / `--remove` 增删，`--apps` 整个换掉名单。这几个都能写多次或用逗号隔开，`--apps ""` 清空名单。可以和 `on` 一起给。
+- `--server` 的写法和对话框一样；`auto` 是取这台电脑的代理设置。第一次 `on` 没给地址时也按 `auto`。
+- `test` 在这台电脑上探测设好的代理：是什么协议、经它的 UDP 能不能用。探测不到是退出码 9（`proxy_unavailable`）。
+- 设置存在 `mas-avd.json` 的 `instances.<i>.appProxy` 里，删除实例时一起删掉。
+- MCP 里是 `get_app_proxy`、`set_app_proxy` 两个工具。
+
+完整的选项和 `--json` 输出见 [ModAVDManager 的 README](https://github.com/ModAVD/ModAVDManager#命令行)。
+
+## HTTP 接口
+
+管理器页面用的是本机的 HTTP 接口，只听 `127.0.0.1`：
+
+| 接口 | 做什么 |
+|---|---|
+| `GET` / `PUT /api/instances/{i}/proxy` | 读、改一台实例的设置；读的时候附上实例里的状态和标记 |
+| `GET /api/instances/{i}/packages` | 列出实例里装了的第三方应用和 Google Play 服务（实例要开着） |
+| `GET /api/proxy/suggest` | 这台电脑的代理设置，换成实例里看到的地址 |
+| `POST /api/proxy/probe` | 在这台电脑上探测一个代理地址 |
+| 事件 `proxy` | 各实例的标记有变化时推送 |
+
+字段、错误码和登录方式见 [API.md](https://github.com/ModAVD/ModAVDManager/blob/main/internal/ui/API.md)。
+
+## 常见问题 {#faq}
+
+### 标记是红的，写着「代理连不上」
+
+- 看代理软件开着没有、端口对不对：在对话框里点「检测」，或者跑 `tools\modavd.exe proxy <编号> test`。
+- 这时名单里的应用断网，这是故意的。代理软件恢复以后不用重开实例：名单里的应用下一次连上，标记就变回绿的，在那之前可能是黄的。
+
+### 标记是黄的，写着「最近一次经代理的连接没成功」
+
+这台电脑能连到代理，只是名单里的应用最近那一次连接没成功。多半是那次要连的服务器没回应，或者代理软件的规则把它拦了。应用能正常用就不用管；一直这样就看代理软件的日志。
+
+### 标记是红的，写着代理程序没在跑或者规则挂不上
+
+用管理器或 `modavd` 把实例关机再开一次。还是这样就[反馈问题](../guide/feedback)：在实例开着时收集，问题包会收进实例里代理程序的状态和日志。
+
+### 游戏还是连不上或者登录不了
+
+- 用 Google 登录的：把 Google Play 服务也加进名单。
+- 游戏要用 UDP（语音、实时对战）：换成代理软件的 SOCKS5 或混合端口，别用 HTTP 代理。
+- 名单里的应用没有 IPv6，只走 IPv4。
+- 名单里的应用一直标「没装」：包名可能写错了，或者游戏的包名和你写的不一样。在实例开着时打开对话框，从列出的应用里勾。
+
+### 名单外的应用会不会受影响
+
+不会，照常直连。
diff --git a/docs/components/manager.md b/docs/components/manager.md
@@ -13,7 +13,7 @@ ModAVD 0.36.0 起包里带两个管理程序，源码在 [ModAVDManager](https:/
 
 双击包根的 `ModAVD.exe`：起一个只听 127.0.0.1 的本地服务，再用 Edge 的应用模式开一个窗口（Windows 10 / 11 自带 Edge）；找不到 Edge 时用默认浏览器。页面内嵌在程序里，不联网。
 
-- 功能：实例卡片（在线时有画面缩略图）、开关机（带进度）、新建、设置、删除、电脑检查、活动面板、画面查看（点击即点按，返回 / 主页 / 最近任务）、日志、安装 APK、打开目录；浅色 / 深色 / 跟随系统。
+- 功能：实例卡片（在线时有画面缩略图）、开关机（带进度）、新建、设置、删除、电脑检查、活动面板、画面查看（点击即点按，返回 / 主页 / 最近任务）、日志、安装 APK、打开目录；浅色 / 深色 / 跟随系统。管理器 0.4.0 起还有[按应用走代理](./app-proxy)。
 - 一个根目录只开一个服务，再双击只是把窗口重新打开；日志在 `<根>\logs\modavd-ui.log`。
 - 关掉窗口后，等正在跑的任务做完再退出。
 
@@ -34,6 +34,7 @@ modavd [--root <目录>] [--json] [--quiet] [--verbose] <命令> [参数]
 | `stop <i> [--force]`、`stop --all` | 关机：先让安卓正常关机，不成再 sync + kill；`--force` 是 sync + 强杀 |
 | `restart <i> [--window] [--timeout 300] [--force] [--no-bridge]` | 关机再开机 |
 | `bridge <i> install\|uninstall\|verify` | 装、卸、检查 arm64 执行桥 |
+| `proxy <i> [on\|off\|test] [--server URL\|auto] [--add 包名] [--remove 包名] [--apps 包名]` | 管理器 0.4.0 起：[按应用走代理](./app-proxy)，名单里的应用走代理，其余直连 |
 | `check [--memory M]` | 开机前的电脑检查 |
 | `window <i> show\|hide`、`install <i> <apk>`、`shell <i> <命令>`、`adb <i> -- <参数>` | 窗口、装 APK、客体命令、adb 透传 |
 | `servers`、`version`、`mcp`、`help [命令]` | |
@@ -51,7 +52,7 @@ modavd [--root <目录>] [--json] [--quiet] [--verbose] <命令> [参数]
 modavd mcp --root D:\ModAVD
 ```
 
-工具：`list_instances`、`get_instance`、`check_host`、`create_instance`、`update_instance`、`delete_instance`、`start_instance`（带进度）、`stop_instance`、`set_window_visible`、`shell`、`install_apk`。
+工具：`list_instances`、`get_instance`、`check_host`、`create_instance`、`update_instance`、`delete_instance`、`start_instance`（带进度）、`stop_instance`、`set_window_visible`、`shell`、`install_apk`。管理器 0.4.0 起还有 `get_app_proxy`、`set_app_proxy`（[按应用走代理](./app-proxy)）。
 
 在 Claude Code 里注册（PowerShell 里 `--` 要加引号，否则会被吞掉）：
 

diff --git a/docs/en/components/app-proxy.md b/docs/en/components/app-proxy.md
@@ -0,0 +1,111 @@
+# Per-app proxy
+
+Since manager 0.4.0, you can send chosen apps in an instance (by package name) through a proxy program on this computer, while every other app goes direct as before. For example, only the overseas server of a game goes through the proxy, and the domestic games and the system stay as they are.
+
+- No VPN: a small program in the instance that runs as root (`modavd-proxyd`, carried by `modavd.exe` and put into the instance at boot) takes the TCP, UDP and DNS of the listed apps. Neither the apps nor the system see a VPN.
+- You still run the proxy program (a Clash-style one, for example) on your computer yourself; ModAVD only sends the listed apps' traffic to it.
+
+::: warning No proxy, no network
+When the proxy program is closed or cannot be reached, the listed apps **have no network**. They never quietly fall back to direct.
+:::
+
+## What you need
+
+- A proxy program running on your computer, best through its SOCKS5 port or mixed port (7890 and 7897 are common in Clash-style programs), so TCP, UDP and DNS all go through.
+- An HTTP proxy also works, but only carries TCP and DNS: the listed apps' UDP does not work, so in-game voice and real-time matches may fail.
+- `10.0.2.2` in the instance is `127.0.0.1` on this computer. The proxy program can listen on the local machine only; you do not need to turn on "allow LAN".
+- The instance must be started by the manager or the `modavd` CLI to get the proxy. An emulator that another program starts directly, without modavd, does not get it.
+
+## Setting it in the manager
+
+1. On the instance card, click "⋯" at the bottom right, then "按应用走代理…" (per-app proxy). When the card already shows the "代理" mark, clicking the mark opens it too.
+2. Turn on "名单里的应用走代理" (the listed apps use the proxy).
+3. Proxy address:
+   - Click "从系统代理读取" (read the system proxy) to take this computer's proxy setting (the environment variables `ALL_PROXY`, `HTTPS_PROXY`, `HTTP_PROXY`, or the proxy set by hand in Windows "Internet Options");
+   - or type an address such as `socks5://127.0.0.1:7890` (the protocol can be left out) and click "检测" (probe) to see which protocol it speaks and whether UDP works.
+   - `127.0.0.1` and `localhost` are stored as `10.0.2.2`, as the instance sees them; a mixed port written as `http://` is changed to `socks5://`. What was changed is shown under the probe result.
+4. App list:
+   - While the instance runs, the installed third-party apps and Google Play services are listed; just tick them. Games the manager knows are shown with their Chinese names.
+   - While the instance is off, type package names below (such as `com.example.game`) and press Enter to add them.
+   - Listed apps that are not installed in the instance yet are marked "没装" (not installed); they take effect once installed. The list holds at most 64 apps.
+5. Click "保存" (save). A running instance takes it at once; a stopped one at its next boot through the manager or `modavd`.
+
+The "现在" (now) line at the bottom of the dialog shows what the saved setting does now; it says the same as the mark on the card.
+
+::: tip Overseas games that sign in with Google
+Also list "Google Play 服务" (Google Play services, `com.google.android.gms`). When it is not in the list, the dialog says so; click "加进名单" (add to the list).
+:::
+
+To turn it off, untick "名单里的应用走代理" and save. The address and the list are kept, so you do not need to enter them again next time.
+
+## The "代理" mark on the card {#mark}
+
+While the setting is on and the list is not empty, the instance card shows a "代理" (proxy) mark next to its title, in both the card and the list view. Hover over it to see the details; click it to open the setting.
+
+While the instance runs and the manager window is open, the manager asks the instance for its state about every 30 seconds, and right away after a start, a stop or a change of the setting.
+
+| Color | Meaning |
+|---|---|
+| Gray | The instance is off (it shows how many apps go through which proxy from the next boot); it is starting or stopping; or the manager is asking the instance for its state |
+| Green | In effect: N apps (M not installed yet) → proxy address. When the proxy does not carry UDP, "UDP 不通" (no UDP) is added |
+| Yellow | Worth a look, but the listed apps most likely still work: some rules are missing and being put back; the last connection through the proxy failed, but this computer can reach the proxy; or the state could not be read this time |
+| Red | The listed apps have **no network or go direct** right now: the proxy cannot be reached; the proxy program in the instance is not running; the rules cannot be put in place; or the setting was saved but did not take effect |
+
+## The CLI
+
+```powershell
+tools\modavd.exe proxy 3                                          # show
+tools\modavd.exe proxy 3 on --server auto --add com.example.game  # turn on with this computer's proxy setting
+tools\modavd.exe proxy 3 --add com.google.android.gms             # add to the list
+tools\modavd.exe proxy 3 test                                     # probe the proxy from this computer
+tools\modavd.exe proxy 3 off                                      # turn off; the address and the list are kept
+```
+
+- Without other arguments it shows the switch, the address and the list; while the instance runs, it adds the state in the instance (whether the rules are in place, whether the proxy answers, which listed apps are not installed yet).
+- `on` turns it on, `off` turns it off; `--server` changes the address, `--add` / `--remove` edit the list, `--apps` replaces it. Each can be given several times or comma-separated; `--apps ""` empties the list. They can be combined with `on`.
+- `--server` takes the same addresses as the dialog; `auto` takes this computer's proxy setting. The first `on` without an address also means `auto`.
+- `test` probes the configured proxy from this computer: which protocol it speaks and whether UDP works through it. A proxy that cannot be reached is exit code 9 (`proxy_unavailable`).
+- The setting is stored in `mas-avd.json` under `instances.<i>.appProxy` and goes away with the instance.
+- In MCP, the tools are `get_app_proxy` and `set_app_proxy`.
+
+For every option and the `--json` output, see [the ModAVDManager README](https://github.com/ModAVD/ModAVDManager/blob/main/README.en.md#command-line).
+
+## The HTTP API
+
+The manager page uses a local HTTP API that listens only on `127.0.0.1`:
+
+| Endpoint | What it does |
+|---|---|
+| `GET` / `PUT /api/instances/{i}/proxy` | Read or change one instance's setting; reading also gives the state in the instance and the mark |
+| `GET /api/instances/{i}/packages` | List the third-party apps and Google Play services installed in the instance (it must be running) |
+| `GET /api/proxy/suggest` | This computer's proxy setting, as the instance sees the address |
+| `POST /api/proxy/probe` | Probe a proxy address from this computer |
+| Event `proxy` | Sent when an instance's mark changes |
+
+For the fields, error codes and how to log in, see [API.md](https://github.com/ModAVD/ModAVDManager/blob/main/internal/ui/API.md) (in Chinese).
+
+## Common problems {#faq}
+
+### The mark is red and says the proxy cannot be reached
+
+- Check that the proxy program is running and the port is right: click "检测" (probe) in the dialog, or run `tools\modavd.exe proxy <number> test`.
+- The listed apps have no network meanwhile; that is on purpose. Once the proxy program is back you do not need to restart the instance: the mark turns green after the next connection of a listed app succeeds, and may be yellow until then.
+
+### The mark is yellow and says the last connection through the proxy failed
+
+This computer can reach the proxy; only the listed app's last connection failed. Most likely the server it tried did not answer, or a rule in the proxy program blocked it. If the app works, nothing needs to be done; if it stays this way, look at the proxy program's log.
+
+### The mark is red and says the proxy program is not running or the rules cannot be put in place
+
+Shut the instance down and start it again with the manager or `modavd`. If it stays this way, [report a problem](../guide/feedback): collect the information while the instance runs, and the package includes the state and the log of the proxy program in the instance.
+
+### The game still cannot connect or sign in
+
+- Games that sign in with Google: also list Google Play services.
+- Games that use UDP (voice, real-time matches): use the proxy program's SOCKS5 or mixed port, not an HTTP proxy.
+- The listed apps get no IPv6; they use IPv4 only.
+- An app shown as "没装" (not installed): the package name may be wrong, or the game's package name differs from what you typed. Open the dialog while the instance runs and tick it in the listed apps.
+
+### Are apps outside the list affected?
+
+No, they go direct as before.