From 3100db93ed92f9f8ef19aceae49a699768e20ca9 Mon Sep 17 00:00:00 2001
From: Draculabo <a1842298680@gmail.com>
Date: Sat, 11 Apr 2026 17:31:13 +0800
Subject: [PATCH] docs(proxyman): add setup and debugging guides and link them
 from readmes

---
 README.md                  |  10 ++
 README.zh-CN.md            |  10 ++
 docs/proxyman-debugging.md | 244 +++++++++++++++++++++++++++++++++++++
 docs/proxyman-install.md   | 140 +++++++++++++++++++++
 4 files changed, 404 insertions(+)
 create mode 100644 docs/proxyman-debugging.md
 create mode 100644 docs/proxyman-install.md

diff --git a/README.md b/README.md
index bd15ffc..a5c50a9 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,7 @@
 - [Quick Start](#-quick-start)
 - [Tech Stack](#️-tech-stack)
 - [Development](#-development)
+- [Debugging Docs](#-debugging-docs)
 - [FAQ](#-faq)
 - [Contributing](#-contributing)
 - [License](#-license)
@@ -311,6 +312,15 @@ AntigravityManager/
 
 ---
 
+## 🔍 Debugging Docs
+
+If you want to inspect Antigravity or Antigravity Manager traffic with Proxyman, start here:
+
+- [Proxyman Installation and Basic Setup on Windows](docs/proxyman-install.md)
+- [Proxyman Debugging Guide for Antigravity and Antigravity Manager](docs/proxyman-debugging.md)
+
+---
+
 ## ❓ FAQ
 
 <details>
diff --git a/README.zh-CN.md b/README.zh-CN.md
index dcc4593..77789fe 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -50,6 +50,7 @@
 - [快速开始](#-快速开始)
 - [技术栈](#️-技术栈)
 - [开发指南](#-开发指南)
+- [调试文档](#-调试文档)
 - [常见问题](#-常见问题)
 - [贡献指南](#-贡献指南)
 - [许可证](#-许可证)
@@ -310,6 +311,15 @@ AntigravityManager/
 
 ---
 
+## 🔍 调试文档
+
+如果你希望用 Proxyman 抓取和排查 Antigravity 或 Antigravity Manager 的流量，请先阅读：
+
+- [Proxyman Installation and Basic Setup on Windows](docs/proxyman-install.md)
+- [Proxyman Debugging Guide for Antigravity and Antigravity Manager](docs/proxyman-debugging.md)
+
+---
+
 ## ❓ 常见问题
 
 <details>
diff --git a/docs/proxyman-debugging.md b/docs/proxyman-debugging.md
new file mode 100644
index 0000000..5644dcf
--- /dev/null
+++ b/docs/proxyman-debugging.md
@@ -0,0 +1,244 @@
+# Proxyman Debugging Guide for Antigravity and Antigravity Manager
+
+This guide explains how to use Proxyman for two debugging targets:
+
+1. The installed official `Antigravity` desktop client
+2. The `Antigravity Manager` development build from this repository
+
+Before you start, complete [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md).
+
+## Scope
+
+Use this guide when you want to:
+
+- inspect login, quota, project context, or model-list requests from `Antigravity`
+- inspect OAuth, quota refresh, or proxy traffic from `Antigravity Manager`
+- compare requests from the official client with requests produced by this project
+
+## Understand the Two Traffic Paths
+
+### Official `Antigravity` Client
+
+`Antigravity` is an Electron application. Its traffic may come from:
+
+- Chromium or renderer-side requests
+- Electron or Node-side requests
+
+### `Antigravity Manager` in This Repository
+
+This project is also an Electron app, but it additionally includes Node, Undici, and internal proxy flows. You may need to inspect:
+
+- Electron main-process outbound requests
+- renderer-side requests
+- upstream requests emitted by `src/server/`
+
+## Debug the Installed Official Antigravity Client
+
+### Recommended Path: Use the Repository Script
+
+Use the provided script:
+
+- [scripts/start-antigravity-with-proxyman.ps1](../scripts/start-antigravity-with-proxyman.ps1)
+
+This should be the default path for the installed official client because it already does the following:
+
+- sets `HTTP_PROXY`, `HTTPS_PROXY`, and `ALL_PROXY`
+- sets `NODE_EXTRA_CA_CERTS`
+- passes `--proxy-server` and `--proxy-bypass-list`
+- stops existing `Antigravity` processes so the new environment takes effect
+
+Typical usage:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1
+```
+
+If Proxyman is using a different port:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1 -Port 9091
+```
+
+If you are temporarily debugging TLS failures:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1 -AllowInsecureTls
+```
+
+Notes:
+
+- This script targets the installed official `Antigravity` client.
+- It does not launch this repository's `Antigravity Manager` development build.
+- Override `-AppPath`, `-CaPath`, `-ProxyHost`, or `-NoProxy` if your local environment differs.
+
+### Suggested Flow
+
+1. Open Proxyman.
+2. Confirm that installation and certificate setup are already complete.
+3. Confirm the local proxy port, for example `9090`.
+4. Launch `Antigravity` with the script.
+5. Trigger a request that is easy to identify, such as:
+   - Google sign-in
+   - model list loading
+   - quota refresh
+   - a generated request or prompt action
+
+### Why Manual Parameters Are Still Documented
+
+The script is the recommended default, but the raw parameters are still useful because:
+
+- contributors may want to understand exactly what the script configures
+- some people launch from VS Code, another shell, or a custom wrapper
+- some debugging sessions need a partial override rather than the full script
+
+### If Windows System Proxy Is Not Enough
+
+In some environments you may still need to point the system proxy to Proxyman manually. At minimum, verify:
+
+- HTTP proxy: `127.0.0.1:9090`
+- HTTPS proxy: `127.0.0.1:9090`
+- the bypass list is not excluding the domains you want to inspect
+
+### If You Need Direct Chromium Proxy Arguments
+
+If system proxy behavior is unreliable, you can launch the installed client with explicit Chromium proxy arguments:
+
+```powershell
+& "C:\Users\<YourUser>\AppData\Local\Programs\Antigravity\Antigravity.exe" `
+  --proxy-server="http://127.0.0.1:9090" `
+  --proxy-bypass-list="<local>;localhost;127.0.0.1;::1"
+```
+
+Use this as a fallback, not the default path.
+
+## Debug Antigravity Manager From This Repository
+
+This project has more layers than the official client. The script above is not the general launcher for this repository's development app.
+
+### Capture Main-Process, Node, and Internal Proxy Traffic
+
+Set proxy-related environment variables before starting the app:
+
+```powershell
+$env:HTTP_PROXY = "http://127.0.0.1:9090"
+$env:HTTPS_PROXY = "http://127.0.0.1:9090"
+$env:ALL_PROXY = "http://127.0.0.1:9090"
+$env:NO_PROXY = "localhost,127.0.0.1,::1"
+$env:NODE_EXTRA_CA_CERTS = "$env:APPDATA\\Proxyman\\certificate\\certs\\ca.pem"
+
+# Enable only for temporary TLS debugging
+$env:NODE_TLS_REJECT_UNAUTHORIZED = "0"
+
+npm start
+```
+
+This primarily affects:
+
+- Node HTTP and HTTPS requests
+- `undici`, `fetch`, and some dependency-driven upstream requests
+- internal proxy requests forwarded to upstream services
+
+### Also Capture Electron and Chromium Traffic
+
+If you want both Node-side and renderer-side traffic, add Chromium proxy arguments:
+
+```powershell
+$env:HTTP_PROXY = "http://127.0.0.1:9090"
+$env:HTTPS_PROXY = "http://127.0.0.1:9090"
+$env:ALL_PROXY = "http://127.0.0.1:9090"
+$env:NO_PROXY = "localhost,127.0.0.1,::1"
+$env:NODE_EXTRA_CA_CERTS = "$env:APPDATA\\Proxyman\\certificate\\certs\\ca.pem"
+$env:NODE_TLS_REJECT_UNAUTHORIZED = "0"
+
+npm start -- --proxy-server="http://127.0.0.1:9090" --proxy-bypass-list="<local>;localhost;127.0.0.1;::1"
+```
+
+If your local `npm start` flow does not forward arguments to Electron Forge, use one of these fallback approaches:
+
+- capture only Node and main-process traffic
+- wrap the Electron launch in your own PowerShell or VS Code task
+
+## Troubleshooting
+
+### I Can See Requests but HTTPS Bodies Are Empty
+
+Check:
+
+- the Proxyman root certificate is really trusted
+- `NODE_EXTRA_CA_CERTS` is set when Node-side traffic needs it
+- `NODE_TLS_REJECT_UNAUTHORIZED=0` is only being used as a temporary debugging override
+- the target app is not using SSL pinning
+
+Background setup guide:
+
+- [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md)
+
+### I Can See Browser Traffic but Not Node or Main-Process Traffic
+
+Common causes:
+
+- Node is not using system proxy settings
+- the HTTP client does not read `HTTP_PROXY`
+- only the system proxy was configured, but runtime environment variables were not
+
+### I Cannot See `localhost` Traffic
+
+Common cause:
+
+- loopback traffic is bypassing the proxy
+
+Keep this bypass list in mind when launching Electron:
+
+```plaintext
+--proxy-bypass-list="<local>;localhost;127.0.0.1;::1"
+```
+
+Adjust it only if your current debugging target requires a different loopback behavior.
+
+### TLS Still Fails After the Certificate Was Installed
+
+Common causes:
+
+- the process started before the certificate was installed and needs a full restart
+- `ca.cer` was imported but `ca.pem` was not passed to Node when required
+- a corporate proxy, VPN, or security product is changing network behavior
+- the target app uses SSL pinning
+
+## Security Notes
+
+Keep local debugging settings out of the repository and out of public issue threads.
+
+- Do not commit your local proxy address, certificate paths, cookies, or OAuth codes.
+- Do not leave `NODE_TLS_REJECT_UNAUTHORIZED=0` enabled beyond temporary local debugging.
+- Do not post raw tokens, sessions, or authorization headers in public issues.
+- Redact logs before sharing them.
+
+## Minimal Workflows
+
+### Official Antigravity Client
+
+1. Complete [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md).
+2. Open Proxyman.
+3. Run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1
+```
+
+4. Trigger login, quota, or model-list traffic.
+
+### Antigravity Manager in This Repository
+
+1. Complete [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md).
+2. Open PowerShell.
+3. Set `HTTP_PROXY`, `HTTPS_PROXY`, and `NODE_EXTRA_CA_CERTS`.
+4. Run `npm start`.
+5. Filter Proxyman traffic by domains such as:
+   - `googleapis.com`
+   - `googleusercontent.com`
+   - the upstream domain you are debugging
+
+## Related Files
+
+- Setup guide: [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md)
+- Official-client launcher: [scripts/start-antigravity-with-proxyman.ps1](../scripts/start-antigravity-with-proxyman.ps1)
diff --git a/docs/proxyman-install.md b/docs/proxyman-install.md
new file mode 100644
index 0000000..4b4c5f0
--- /dev/null
+++ b/docs/proxyman-install.md
@@ -0,0 +1,140 @@
+# Proxyman Installation and Basic Setup on Windows
+
+This guide covers the Proxyman prerequisites for contributors:
+
+1. Install Proxyman for Windows
+2. Trust the Proxyman certificate so HTTPS traffic can be decrypted
+3. Verify that Proxyman is working before you start debugging Antigravity traffic
+
+If your goal is to debug the installed Antigravity client or this repository's development build, continue with [Proxyman Debugging Guide](./proxyman-debugging.md).
+
+## Scope
+
+This document is intentionally limited to the setup layer. It does not cover Antigravity-specific debugging flows.
+
+Use it when you need to answer:
+
+- How do I install Proxyman on Windows?
+- How do I trust the certificate?
+- Why can I only see CONNECT requests but not HTTPS bodies?
+- How do I verify that Proxyman itself is working?
+
+## Install Proxyman
+
+Official resources:
+
+- Download: [https://proxyman.com/download](https://proxyman.com/download)
+- Windows product page: [https://proxyman.com/windows](https://proxyman.com/windows)
+
+Recommended steps:
+
+1. Install the Windows build from the official download page.
+2. Launch Proxyman.
+3. Confirm that Proxyman is listening on a local proxy port.
+4. This guide uses `9090` as the example port. Replace it with your local port if it differs.
+
+## Install and Trust the Certificate
+
+Without the Proxyman root certificate, you will usually only see CONNECT tunnels or TLS handshakes instead of decrypted HTTPS requests.
+
+Official references:
+
+- Windows certificate installation: [https://docs.proxyman.com/proxyman-windows/install-certificate](https://docs.proxyman.com/proxyman-windows/install-certificate)
+- SSL troubleshooting: [https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response](https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response)
+
+### Recommended Path: Install Automatically
+
+In Proxyman, run:
+
+```plaintext
+Certificate -> Install Certificate on this Windows...
+```
+
+Then:
+
+1. Choose `Install & Trust`
+2. Approve the administrator prompt
+
+According to the official documentation, Proxyman uses Windows `certutil` to import the root certificate into the trusted store.
+
+### Prepare a PEM File for Node and Electron
+
+Some Node.js and Electron traffic needs more than system trust. You may also need to point the runtime at the PEM file:
+
+```plaintext
+%APPDATA%\Proxyman\certificate\certs\ca.pem
+```
+
+If you only see `ca.cer` and not `ca.pem`, confirm that Proxyman has generated the PEM variant before moving on.
+
+## Verify That Proxyman Works
+
+Do this before trying to debug any application-specific flow.
+
+### Verify Browser Traffic
+
+1. Open Proxyman.
+2. Visit any HTTPS page in a browser, for example:
+
+```plaintext
+https://httpbin.org/get
+```
+
+3. Confirm that the request and response appear in Proxyman.
+
+### If You Cannot See Any Traffic
+
+Check these first:
+
+- Proxyman is actually listening on the expected port
+- Windows proxy settings are pointing to Proxyman
+- A VPN, endpoint security agent, or antivirus is not taking over proxy behavior
+- The certificate is trusted
+
+If localhost traffic is missing, see:
+
+- [https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server](https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server)
+
+The official page includes macOS-specific examples, but the localhost bypass concept is still relevant on Windows.
+
+## Basic Troubleshooting
+
+### HTTPS Bodies Are Missing
+
+Common causes:
+
+- The Proxyman root certificate is not actually trusted
+- The target process was already running before the certificate was installed
+- The application uses SSL pinning
+
+### Certificate Is Installed but TLS Still Fails
+
+Common causes:
+
+- You imported `ca.cer` but did not provide `ca.pem` to the runtime when needed
+- A corporate proxy, VPN, or security product is overriding the network path
+- The target application uses SSL pinning
+
+### Localhost Traffic Is Missing
+
+Common cause:
+
+- Local loopback traffic is bypassing the proxy
+
+Official reference:
+
+- [https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server](https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server)
+
+## Next Step
+
+Once Proxyman is installed, trusted, and verified, continue with:
+
+- [Proxyman Debugging Guide](./proxyman-debugging.md)
+
+## References
+
+- Proxyman download page: [https://proxyman.com/download](https://proxyman.com/download)
+- Proxyman Windows page: [https://proxyman.com/windows](https://proxyman.com/windows)
+- Proxyman Windows certificate guide: [https://docs.proxyman.com/proxyman-windows/install-certificate](https://docs.proxyman.com/proxyman-windows/install-certificate)
+- Proxyman localhost troubleshooting: [https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server](https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server)
+- Proxyman SSL troubleshooting: [https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response](https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response)