Merge pull request #2 from lixiaobaivv/agent/upstream-readme-copy

docs: 更新中英文 README

README.en.md

@@ -4,23 +4,23 @@
 
 ### iOS Location Spoofer · DingTalk · WeChat · Apple Watch Region Unlock · Fake GPS
 
-**No jailbreak — use App Mode's on-device Wi-Fi HTTP proxy or Third-party Proxy Mode (Wi-Fi/4G/5G) to rewrite Apple location responses.**<br>
+**No jailbreak — rewrite Apple location-service responses through App Mode's on-device Wi-Fi HTTP proxy or Third-party Proxy Mode (Wi-Fi/4G/5G).**<br>
-Works with DingTalk check-in, WeChat location sharing, and any app that uses system location. Map selection, real-time location, environment verification, certificate setup, and runtime logs in a single app.
+Designed for DingTalk, WeChat, Apple Maps, and other apps that read system location. Map selection, favorites, mode setup, environment checks, and diagnostics live in one app.
 
 [![iOS 15+](https://img.shields.io/badge/iOS-15%2B-111111?logo=apple)](project.yml)
 [![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138?logo=swift&logoColor=white)](project.yml)
 [![Go 1.23+](https://img.shields.io/badge/Go-1.23%2B-00ADD8?logo=go&logoColor=white)](Core/go.mod)
 [![Version](https://img.shields.io/badge/version-v1.0.1-2563EB)](docs/CHANGELOG.md)
-[![App Mode](https://img.shields.io/badge/App%20Mode-No%20VPN-16A34A)](#why-no-vpn)
+[![App Mode](https://img.shields.io/badge/App%20Mode-No%20VPN-16A34A)](#how-it-works)
 
-[Features](#key-features) · [Quick Start](#quick-start) · [中文](README.md) · [Changelog](docs/CHANGELOG.md)
+[Features](#key-features) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [中文](README.md) · [Changelog](docs/CHANGELOG.md)
 
 <img src="images/主界面.jpg" alt="Location Spoofer iOS Fake GPS main interface" width="380">
 
 </div>
 
 > [!IMPORTANT]
-> This project is intended for education, security research, and testing on your own devices. App Mode installs a locally generated CA and requires a manual HTTP proxy on the current Wi-Fi network. In Third-party Proxy Mode, the selected client owns certificate, MITM, and proxy/VPN setup. Please understand the risks and follow applicable laws and service terms.
+> This project is only for education, security research, and testing on devices you own. App Mode requires a locally generated CA and a manual HTTP proxy on the current Wi-Fi network. In Third-party Proxy Mode, the selected client owns certificate, MITM, and proxy/VPN setup. Results vary by iOS version, network, location cache, and target-app behavior. Follow applicable laws, network policies, and service terms.
 
 ## Credits
 
@@ -28,17 +28,18 @@ The core location-response rewriting approach and Go implementation are based on
 
 ## Why Location Spoofer?
 
-Unlike tools that require a computer to stay connected, a VPN tunnel, or a jailbroken device, Location Spoofer keeps the control flow on the iPhone itself.
+Unlike tools that require a computer to stay connected, developer debugging, or a jailbroken device, Location Spoofer keeps selection and control on the iPhone. It provides two mutually exclusive paths: run the Go proxy inside the app, or synchronize coordinates to an existing third-party proxy client.
 
 | Feature | Description |
 |---|---|
-| 🔀 **Two runtime modes** | Stable App Mode, plus a Third-party Proxy Mode under testing for Wi-Fi, 4G, and 5G. |
+| 🔀 **Two runtime modes** | App Mode needs no third-party client and works over Wi-Fi; Third-party Proxy Mode can follow its client across Wi-Fi, 4G, and 5G. |
 | 📱 **No jailbreak** | Can be installed through self-signing; minimum deployment target is iOS 15. |
 | 🗺️ **Native Maps experience** | The same blue dot and selection gestures as Apple Maps — search, tap, and drag. |
-| 📍 **System-level location spoofing** | Works with DingTalk, WeChat, Apple Maps, Amap, and other apps for real-time fake GPS. |
+| 📍 **Location-response rewriting** | Can affect DingTalk, WeChat, Apple Maps, Amap, and other apps that read system location; verify compatibility on-device. |
 | 🔍 **Visible map scale** | Left-side controls show the current visible range; place name adapts to zoom level. |
-| 🧪 **Environment verification** | Checks proxy, CA trust, Wi‑Fi interception, coordinate write, and response rewrite. |
+| 🧭 **Coordinate consistency** | Reconciles MapKit map coordinates with WGS-84 for favorites, restoration, and third-party sync. |
-| 🧾 **Diagnostics** | Per-entry copy for easy sharing and debugging. |
+| 🧪 **Mode-aware checks** | App Mode checks the local proxy, CA trust, and Wi-Fi path; Third-party Mode verifies real module interception. |
+| 🧾 **Diagnostics** | Search and copy logs, or generate a sanitized GitHub Issue report from inside the app. |
 
 ## Screenshots
 
@@ -48,15 +49,17 @@ Unlike tools that require a computer to stay connected, a VPN tunnel, or a jailb
 
 ## Key Features
 
-- **iOS Location Spoofer / Fake GPS**: Apply the selected coordinate to the local proxy that rewrites location responses, compatible with DingTalk check-in, WeChat location sharing, and more.
+- **iOS Location Spoofer / Fake GPS**: Apply the selected pin to App Mode's proxy or synchronize it to a third-party WLOC module.
-- **Native real-time location**: The map displays MapKit's own blue dot — no extra "fake real-time" overlay.
+- **Native map and real-time location**: Uses MapKit's blue dot with search, tap, map-center drag, zoom controls, and a shortcut to Apple Maps.
 - **Concurrency-safe selection**: Pan, tap, search, favorites, and async location respect the user's latest intent; stale results won't overwrite newer selections.
 - **Hierarchical place names**: POI, street, or road at close zoom; neighborhood, district, city, or province at wider zoom.
 - **Map scale display**: Zoom controls show the current visible range.
-- **Favorites with quick switch**: Save frequent coordinates and see which location is about to be applied.
+- **Favorites and state restoration**: Save, rename, and switch frequent locations while remembering the last pin and map range.
-- **Mode-specific setup**: Choose a mode first; App Mode guides local proxy and CA setup, while Third-party Proxy Mode guides client selection, configuration import, and API verification.
+- **Automatic coordinate handling**: Resolves the map's coordinate convention at startup and keeps paired WGS-84/map coordinates to reduce mainland-China map offsets.
-- **Built-in diagnostics**: Verification flow and structured runtime logs.
+- **Mode-specific onboarding**: App Mode guides local proxy and CA setup; Third-party Mode guides client selection, subscription import, and connection testing.
-- **Third-party Proxy Mode (testing)**: Send a favorite or current pin as WGS-84 to a supported proxy module; the proxy client persists it after this App exits.
+- **Local-proxy keep-alive**: App Mode uses silent audio while spoofing to remain active in the background and rechecks the environment after Wi-Fi changes.
+- **Structured diagnostics**: Logs rotate automatically, retain only three days, and can be filtered, copied, cleared, or attached to an Issue report.
+- **Third-party Proxy Mode (testing)**: Query, save, or clear WGS-84 coordinates through a WLOC module. The proxy client persists state, so spoofing may continue after this app closes.
 
 ## Quick Start
 
@@ -65,32 +68,15 @@ Unlike tools that require a computer to stay connected, a VPN tunnel, or a jailb
 - Download a build from [Releases](https://github.com/xweiba/location-spoofer/releases) and self-sign; or
 - Build from source on macOS with Xcode — see the [build guide](docs/BUILD.md).
 
-The release asset is an unsigned IPA. Sign it with [Impact](https://github.com/claration/Impactor) before installation. Keep the app Bundle ID `com.paopaolabs.location-spoofer`, the App Group `group.com.paopaolabs.location-spoofer`, and the declared entitlements unchanged. A free Apple ID signature normally expires after seven days and must then be renewed.
+The release asset is an unsigned IPA. Sign it with [Impact](https://github.com/claration/Impactor) before installation. Keep the app Bundle ID `com.paopaolabs.location-spoofer`, the App Group `group.com.paopaolabs.location-spoofer`, and the declared entitlements unchanged. A free Apple ID signature normally expires after seven days and must then be renewed; this is separate from the WLOC CA certificate.
 
 ### 2. Choose a Runtime Mode
 
-#### App Mode
+#### App Mode (On-device Wi-Fi)
 
-Choose App Mode during first launch, then configure `127.0.0.1:8888` and fully trust the locally generated CA. It has no third-party client dependency but supports Wi-Fi only. Free self-signed apps cannot use the VPN/Network Extension capability required for cellular interception, so this mode uses the current Wi-Fi's manual HTTP proxy.
+Choose App Mode during first launch, then follow the in-app guide to configure the proxy and CA. This mode starts `wloccore` on the device and has no third-party client dependency, but its traffic entry point covers only the current Wi-Fi.
 
-#### Third-party Proxy Mode
+On the current Wi-Fi network, set Configure Proxy to Manual:
-
-The App handles map selection, favorites, and WGS-84 coordinate delivery. A third-party proxy client handles WLOC interception, MITM, and persistence over Wi-Fi, 4G, or 5G. This mode skips the App's local proxy and CA checks.
-
-Shadowrocket is the only client currently available for device testing. Surge, Quantumult X, Loon, Stash, and Egern configurations are provided but unverified. The App lets the user copy the official subscription URL and open the selected client; the URL is then pasted into that client's module, rewrite, or override subscription UI. Configuration snapshots remain bundled for release provenance and offline inspection, but the setup UI does not export files. Egern uses the Surge module, and Stash imports `.stoverride` directly without Script Hub conversion. The third-party client—not this App—owns MITM, certificate, and proxy/VPN setup. Snapshot provenance is recorded in [the module snapshot document](docs/THIRD_PARTY_MODULES.md).
-
-### 3. Local-mode CA Setup
-
-Follow the first-setup wizard to download the profile, then:
-
-```text
-Settings → General → VPN & Device Management → install WLOC CA
-Settings → General → About → Certificate Trust Settings → enable full trust
-```
-
-Configure the current Wi-Fi proxy before installing the CA:
-
-On the current Wi‑Fi's proxy settings, choose "Manual":
 
 ```text
 Server: 127.0.0.1
@@ -98,18 +84,44 @@ Port: 8888
 Authentication: off
 ```
 
-### 4. Select a Location & Enable
+Return to the app and run the environment check. If the CA is not trusted, the app opens the complete certificate setup flow. Download the profile, then:
 
-1. Search, tap, or drag the map to pick a location; tap the real-time location button to jump to the MapKit blue dot.
+```text
+Settings → General → VPN & Device Management → install WLOC CA
+Settings → General → About → Certificate Trust Settings → enable full trust
+```
+
+#### Third-party Proxy Mode (Testing)
+
+The app handles map selection, favorites, and querying, saving, or clearing WGS-84 coordinates. A third-party proxy client handles WLOC interception, MITM, and persistence. This mode does not start the local Go proxy, use the app-generated CA, or require `127.0.0.1:8888`. Network coverage depends on the selected client and may include Wi-Fi, 4G, and 5G.
+
+Select a client during onboarding or from Settings → Runtime Mode. The app can copy the official subscription URL and open the selected client; paste that URL into its module, rewrite, or override subscription UI.
+
+| Client | Verification status | Configuration |
+|---|---|---|
+| Shadowrocket | **Currently available for testing** | [wloc.module](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.module) |
+| Surge | Provided, not verified | [wloc.sgmodule](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.sgmodule) |
+| Quantumult X | Provided, not verified | [wloc.conf](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.conf) |
+| Loon | Provided, not verified | [wloc.lpx](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.lpx) |
+| Stash | Provided, not verified | [wloc.stoverride](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.stoverride) |
+| Egern | Provided, not verified | Uses the Surge module |
+
+For Shadowrocket, also enable HTTPS decryption for `gs-loc.apple.com`. Import `.stoverride` directly into Stash without Script Hub conversion; Egern reuses the Surge module. The client—not this app—owns module enablement, MITM, certificates, and proxy/VPN state. A connection test passes only when the endpoint returns valid module JSON, not merely HTTP 200. Bundled snapshots and provenance are documented in [Third-party Module Snapshots](docs/THIRD_PARTY_MODULES.md).
+
+### 3. Select a Location & Enable
+
+1. Search, tap, or drag the map to pick a location; use the location button to return to the MapKit blue dot, or save the pin as a favorite.
 2. In App Mode, tap “Start Spoofing” and wait for verification. In Third-party Proxy Mode, tap “Sync to Third-party Proxy.”
 3. Follow the in‑app activation instructions to refresh airplane mode, Wi‑Fi, and location services.
 4. Open Apple Maps or your target app to verify.
 
-### 5. Restore Your Real Location
+### 4. Restore Your Real Location
 
-Stop spoofing, remove the manual proxy from the current Wi‑Fi, and follow the in‑app deactivation instructions to refresh the system location cache. If stale cache persists, restart your device.
+In App Mode, stop spoofing and disable the current Wi-Fi's manual proxy. In Third-party Mode, use “Clear Third-party Proxy Coordinates,” then disable the module or proxy connection if needed. Follow the in-app deactivation instructions to refresh the system location cache; restart the device if the old location remains.
 
-## Why No VPN?
+## How It Works
+
+### Why App Mode Needs No VPN
 
 ```text
 iPhone location request
@@ -124,7 +136,24 @@ Apple location service response
 The system and applications receive the modified result
 ```
 
-App Mode does not use Network Extension, so it does not occupy the VPN slot. **App Mode still requires the current Wi-Fi HTTP proxy and the locally generated CA.** Third-party Proxy Mode delegates proxy/VPN and MITM handling to the selected proxy client and may cover cellular networks. Do not enable both interception paths at once.
+App Mode does not create a Network Extension tunnel, so it does not display or occupy a VPN connection. **It still requires the current Wi-Fi's manual HTTP proxy and a fully trusted local CA.**
+
+### Third-party Proxy Mode
+
+```text
+Map pin (WGS-84) → WLOC settings endpoint → proxy module stores coordinate
+                                             │
+Location request → third-party proxy/VPN + MITM ┘→ rewritten response
+```
+
+The selected client owns proxy/VPN, certificates, and MITM and may cover cellular networks. Do not enable both interception paths at once.
+
+## Data & Security Notes
+
+- App Mode generates its CA and private key on-device. The private key is stored in the iOS Keychain; only the CA profile is installed into the system trust store.
+- Third-party modules and runtime scripts come from the upstream project. Review them before importing. Bundled snapshots provide release provenance and do not imply that every client has been verified.
+- Runtime logs live in the App Group container, rotate automatically, and retain only three days. They can be copied or cleared in-app. Exportable real-time-location diagnostics omit exact coordinates by default.
+- A self-signed CA or third-party MITM changes the device's HTTPS trust/proxy path. Disable the proxy or module when unused and remove certificates if appropriate.
 
 ## Compatibility
 
@@ -134,15 +163,18 @@ App Mode does not use Network Extension, so it does not occupy the VPN slot. **A
 | Build | macOS, Xcode, XcodeGen |
 | Swift | 5.9 |
 | Go | 1.23+ |
-| Network | Local mode: Wi-Fi with manual HTTP proxy support; third-party test mode: client-dependent Wi-Fi/4G/5G |
+| Network | App Mode: Wi-Fi with manual HTTP proxy support; Third-party Mode (testing): client-dependent Wi-Fi/4G/5G |
 | Installation | Self-sign or use release builds |
 
 Actual behavior may vary with iOS version, network conditions, system location cache, device model, and the target app's own location strategy. Compatibility with every iOS version or third-party app is not guaranteed.
 
 ## Build & Project Structure
 
+Building requires macOS, Xcode Command Line Tools, Go 1.23+, and XcodeGen:
+
 ```bash
-./build.sh
+./build.sh          # build the unsigned IPA
+./build.sh --test   # also run iOS Simulator unit tests
 ```
 
 The unsigned IPA is at:
@@ -156,14 +188,16 @@ App/        SwiftUI, MapKit, location and setup flow
 Core/       Go local proxy and location response rewriting
 Shared/     Favorites, settings, logs, and shared models
 Resources/  Info.plist, Entitlements, and icons
+Config/     Build configuration
 Scripts/    Build, signing, and verification scripts
 Tests/      XCTest and Bash contract tests
-docs/       Build, self-signing, and changelog documentation
+docs/       Build, third-party module, and release documentation
 ```
 
 ## Documentation & Feedback
 
 - [Build guide](docs/BUILD.md)
+- [Third-party module snapshots](docs/THIRD_PARTY_MODULES.md)
 - [Changelog](docs/CHANGELOG.md)
 - [中文文档](README.md)
 - [GitHub Issues](https://github.com/xweiba/location-spoofer/issues)

README.md

@@ -4,23 +4,23 @@
 
 ### iOS 虚拟定位 · 钉钉定位 · 微信定位 · Apple Watch 国区功能解锁 · Fake GPS
 
-**无需越狱；可使用 APP模式的本机 Wi‑Fi HTTP 代理，或第三方代理模式（支持 Wi‑Fi/4G/5G）改写 Apple 定位响应。**<br>
+**无需越狱；通过 APP 模式的本机 Wi‑Fi HTTP 代理，或第三方代理模式（Wi‑Fi/4G/5G）改写 Apple 定位服务响应。**<br>
-可修改钉钉、微信及任意依赖系统定位的 App 的位置。地图选点、实时位置、环境检测、证书配置与运行日志集中在一个 App 中。
+适用于钉钉、微信、Apple 地图等读取系统定位的 App。地图选点、收藏、模式配置、环境检测和问题诊断集中在一个 App 中。
 
 [![iOS 15+](https://img.shields.io/badge/iOS-15%2B-111111?logo=apple)](project.yml)
 [![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138?logo=swift&logoColor=white)](project.yml)
 [![Go 1.23+](https://img.shields.io/badge/Go-1.23%2B-00ADD8?logo=go&logoColor=white)](Core/go.mod)
 [![Version](https://img.shields.io/badge/version-v1.0.1-2563EB)](docs/CHANGELOG.md)
-[![App Mode](https://img.shields.io/badge/APP模式-无需VPN-16A34A)](#为什么不需要-vpn)
+[![App Mode](https://img.shields.io/badge/APP模式-无需VPN-16A34A)](#工作原理)
 
-[功能介绍](#核心功能) · [安装使用](#快速开始) · [English](README.en.md) · [更新日志](docs/CHANGELOG.md)
+[功能介绍](#核心功能) · [快速开始](#快速开始) · [工作原理](#工作原理) · [English](README.en.md) · [更新日志](docs/CHANGELOG.md)
 
 <img src="images/主界面.jpg" alt="Location Spoofer iOS 虚拟定位 Fake GPS 主界面" width="380">
 
 </div>
 
 > [!IMPORTANT]
-> 本项目用于学习、安全研究与自有设备测试。APP模式需要安装自签 CA，并在当前 Wi‑Fi 上配置本机 HTTP 代理；第三方代理模式的证书、MITM 和代理/VPN 连接由所选客户端处理。请先阅读工作原理和风险说明，并遵守当地法律、网络管理规则及相关服务条款。
+> 本项目仅用于学习、安全研究和自有设备测试。APP 模式需要安装本机生成的 CA，并为当前 Wi‑Fi 配置 HTTP 代理；第三方代理模式的证书、MITM 及代理/VPN 连接由所选客户端负责。实际效果受 iOS、网络、定位缓存和目标 App 策略影响，请遵守当地法律、网络管理规则及相关服务条款。
 
 ## 致谢
 
@@ -28,17 +28,18 @@
 
 ## 为什么选择 Location Spoofer？
 
-很多 iOS 虚拟定位工具依赖电脑常驻、开发者调试、VPN 或越狱。本项目采用不同路线：在 iPhone 本机运行 Go 代理，仅对 Apple 定位服务目标请求进行处理。
+很多 iOS 虚拟定位工具依赖电脑常驻、开发者调试或越狱。本项目把选点和控制流程放在 iPhone 上，并提供两条互斥的运行路径：由 App 在本机启动 Go 代理，或把坐标同步给已有的第三方代理客户端。
 
 | 特性 | 说明 |
 |---|---|
-| 🔀 **双运行模式** | APP模式无需第三方客户端、支持 Wi‑Fi；第三方代理模式可覆盖 Wi‑Fi、4G 和 5G |
+| 🔀 **双运行模式** | APP 模式无需第三方客户端、适用于 Wi‑Fi；第三方代理模式可随客户端覆盖 Wi‑Fi、4G 和 5G |
 | 📱 **无需越狱** | 支持自行签名安装，最低部署目标为 iOS 15 |
 | 🗺️ **原生地图体验** | 使用 Apple 地图同款蓝点，搜索、点击、拖动选点体验与 Apple 地图一致 |
-| 📍 **系统级虚拟定位** | 支持钉钉、微信、Apple 地图、高德等 App 的虚拟实时定位 |
+| 📍 **系统定位响应改写** | 可影响钉钉、微信、Apple 地图、高德等读取系统定位的 App，兼容性以真机结果为准 |
 | 🔍 **可见缩放范围** | 左侧缩放控件显示当前可视范围，地点名称随级别自动适配 |
-| 🧪 **环境检测** | 检查本地代理、CA 证书信任与 Wi‑Fi 代理链路 |
+| 🧭 **坐标一致性** | 自动处理 MapKit 地图坐标与 WGS-84，收藏、恢复和第三方同步使用明确的坐标来源 |
-| 🧾 **诊断日志** | 每条日志独立可复制，方便整理和反馈问题 |
+| 🧪 **按模式检测** | APP 模式检查本地代理、CA 信任和 Wi‑Fi 链路；第三方模式验证模块是否真正拦截请求 |
+| 🧾 **问题诊断** | 日志可搜索、逐条或整体复制，并可生成已脱敏的 GitHub Issue 报告 |
 
 ## 效果预览
 
@@ -67,15 +68,17 @@
 
 ## 核心功能
 
-- **iOS 虚拟定位 / Fake GPS**：将当前地图选点应用到本机定位响应改写代理，适配钉钉打卡、微信位置共享等场景。
+- **iOS 虚拟定位 / Fake GPS**：将当前选点写入 APP 模式代理，或同步给第三方 WLOC 模块。
-- **原生实时位置**：地图显示 MapKit 自带蓝点，不再由 App 额外绘制实时位置标记。
+- **原生地图与实时位置**：使用 MapKit 蓝点，支持搜索、点击、拖动地图中心、缩放以及快速打开 Apple 地图。
 - **并发安全选点**：拖动、点击、搜索、收藏和异步定位按用户最新意图处理，旧结果不会覆盖新选点。
 - **地点名称分级**：近距离显示 POI、门牌或道路；拉远后显示社区、区县、城市或省份。
 - **地图范围显示**：缩放控件中显示 `180 m`、`2.5 km`、`126 km` 等当前可视范围。
-- **收藏与快速切换**：保存常用坐标，并明确显示当前准备应用的位置。
+- **收藏与状态恢复**：保存、重命名和切换常用位置，记住最后图钉与地图范围。
-- **分流配置引导**：首次启动先选择模式；APP模式引导本机代理和 CA，第三方代理模式引导客户端、配置导入和接口检测。
+- **坐标系自动处理**：启动时确认地图坐标标准，内部保留 WGS-84 与地图坐标配对，减少中国大陆地图偏移。
-- **问题诊断**：内置验证流程和结构化运行日志。
+- **分模式首次引导**：APP 模式配置本机代理和 CA；第三方模式选择客户端、复制订阅地址并检测连接。
-- **第三方代理模式（测试）**：内置各客户端模块配置，把收藏或当前选点的 WGS-84 坐标发送到第三方代理模块；代理客户端持久化坐标，关闭本 App 后仍可继续生效。
+- **本机代理保活**：APP 模式启动虚拟定位后使用静音音频维持后台运行，并响应网络切换重新检测环境。
+- **结构化诊断**：运行日志自动轮转，仅保留近 3 天；支持过滤、复制、清空和生成 Issue 报告。
+- **第三方代理模式（测试）**：向模块查询、保存或清除 WGS-84 坐标；坐标由代理客户端持久化，关闭本 App 后仍可能继续生效。
 
 ## 快速开始
 
@@ -86,7 +89,7 @@
 
 #### 自签安装
 
-免费 Apple ID 即可侧载，无需付费开发者账号。本项目不使用 VPN、Network Extension 或 Packet Tunnel Provider，但签名工具仍需保留 App 的能力与标识。
+免费 Apple ID 可用于侧载，无需付费开发者账号。本项目自身不包含 VPN、Network Extension 或 Packet Tunnel Provider，但签名工具仍需保留 App 的标识和声明能力。
 
 需要自行构建时执行：
 
@@ -102,13 +105,13 @@
 |---|---|
 | 主 App Bundle ID | `com.paopaolabs.location-spoofer` |
 
-免费 Apple ID 签名通常只有 7 天有效期，到期后需要重新签名安装；这是 Apple 的侧载限制，不是 App 的证书失效。App 生成的 WLOC CA 私钥保存在 iOS 钥匙串中：使用相同 Bundle ID 和钥匙串访问范围重装时通常可继续复用，但卸载、系统清理或签名能力变化后不保证保留。
+免费 Apple ID 签名通常只有 7 天有效期，到期后需要重新签名安装；这是 Apple 的侧载限制，不是 WLOC CA 失效。CA 私钥保存在 iOS 钥匙串中：相同 Bundle ID 和钥匙串访问范围下重装通常可以复用，但卸载、系统清理或签名能力变化后不保证保留。
 
 ### 2. 选择运行模式
 
-#### APP模式
+#### APP 模式（本机 Wi‑Fi）
 
-首次打开后选择 APP模式，再按 App 内引导配置代理和 CA。APP模式没有第三方代理客户端依赖，但只支持 Wi‑Fi。免费自签应用无法使用此功能所需的 VPN/Network Extension 能力，因此使用当前 Wi‑Fi 的手动 HTTP 代理实现流量接入。
+首次打开后选择 APP 模式，再按 App 内引导配置代理和 CA。此模式会在设备内启动 `wloccore`，不依赖第三方代理客户端，但流量入口只覆盖当前 Wi‑Fi。
 
 ##### 配置当前 Wi‑Fi 代理
 
@@ -120,20 +123,20 @@
 鉴定：关闭
 ```
 
-返回 App 后运行环境检测；如果设备尚未信任 CA，App 会自动进入证书初始化。
+返回 App 后运行环境检测；若设备尚未信任 CA，App 会进入完整的证书初始化流程。
 
 ##### 安装并信任 CA
 
-按首次引导下载描述文件，然后完成：
+按首次引导下载描述文件，然后依次完成：
 
 ```text
 设置 → 通用 → VPN 与设备管理 → 安装 WLOC CA
 设置 → 通用 → 关于本机 → 证书信任设置 → 完全信任
 ```
 
-#### 第三方代理模式
+#### 第三方代理模式（测试）
 
-此模式由 App 负责地图选点、收藏和发送 WGS-84 坐标；WLOC 拦截、MITM 与坐标持久化由第三方代理客户端负责。它不会启动本机 Go 代理，不检查或使用 App 的 CA，也不要求配置 `127.0.0.1:8888`，可用于 Wi‑Fi、4G 和 5G。
+此模式由 App 负责地图选点、收藏以及查询、同步和清除 WGS-84 坐标；WLOC 拦截、MITM 与坐标持久化由第三方代理客户端负责。它不会启动本机 Go 代理，不使用 App 生成的 CA，也不要求配置 `127.0.0.1:8888`。网络覆盖范围取决于代理客户端，可包括 Wi‑Fi、4G 和 5G。
 
 首次引导或“设置 → 运行模式”切换后，选择客户端。App 提供官方订阅地址复制和客户端跳转按钮；在对应客户端的模块、重写或覆写订阅入口粘贴地址并导入。仓库和 App 包内仍保留以下模块配置快照，用于版本归档和离线核对：
 
@@ -146,22 +149,24 @@
 | Stash | 配置已提供，尚未验证 | [wloc.stoverride](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.stoverride) |
 | Egern | 配置已提供，尚未验证 | 直接使用 Surge 模块 |
 
-Stash 应直接订阅 `.stoverride`，无需通过 Script Hub 转换。Egern 复用 Surge 配置。导入后还需要按对应客户端自己的流程启用模块、MITM、证书和代理/VPN 连接；这些状态不由本 App 管理。App 只调用 WLOC 配置接口查询和同步坐标，“检测连接”仅在查询返回模块 JSON 时判定成功，不会把普通 HTTP 200 当作成功。
+Shadowrocket 还需为 `gs-loc.apple.com` 开启 HTTPS 解密。Stash 应直接订阅 `.stoverride`，无需通过 Script Hub 转换；Egern 复用 Surge 配置。导入后仍需按客户端自己的流程启用模块、MITM、证书和代理/VPN 连接，这些状态不由本 App 管理。“检测连接”只有在接口返回有效模块 JSON 时才会通过，普通 HTTP 200 不会被误判为成功。
 
 > 第三方代理模式目前是测试模式。内置模块快照来源及版本记录见 [第三方模块说明](docs/THIRD_PARTY_MODULES.md)；模块引用的运行脚本仍由第三方客户端按配置访问。上游更新可能改变行为；当前仅计划使用 Shadowrocket 做真机验证。
 
 ### 3. 选点并启用
 
-1. 搜索、点击或拖动地图选择位置；点击实时位置按钮可回到 MapKit 蓝点。
+1. 搜索、点击或拖动地图选择位置；点击定位按钮可回到当前 MapKit 蓝点，也可以保存为收藏。
 2. APP 模式点击“开始虚拟定位”并等待环境检测；第三方代理模式点击“同步到第三方代理”。
-3. 按 App 内"生效说明"刷新飞行模式、Wi‑Fi 和定位服务状态。
+3. 按 App 内“生效说明”刷新飞行模式、Wi‑Fi 和定位服务状态。
 4. 打开 Apple 地图或目标 App 验证结果。
 
 ### 4. 恢复真实位置
 
-停止虚拟定位，关闭当前 Wi‑Fi 的手动代理，并按 App 内"失效说明"刷新系统定位缓存。若系统仍保留旧缓存，请重启设备后再检查。
+APP 模式下先停止虚拟定位，再关闭当前 Wi‑Fi 的手动代理；第三方代理模式下使用“清除第三方代理坐标”，必要时再停用对应模块或代理连接。随后按 App 内“失效说明”刷新系统定位缓存；若仍保留旧位置，请重启设备后再检查。
 
-## 为什么不需要 VPN？
+## 工作原理
+
+### APP 模式为什么不需要 VPN？
 
 ```text
 iPhone 定位请求
@@ -176,7 +181,24 @@ iPhone 定位请求
 系统与应用读取定位结果
 ```
 
-APP 模式不使用 Network Extension 创建 VPN 隧道，因此不会显示 VPN 连接，也不会占用系统 VPN。**APP 模式仍需要为当前 Wi‑Fi 配置 HTTP 代理，并安装、信任本机生成的 CA。** 第三方代理模式则由所选代理客户端管理代理/VPN 和 MITM，可覆盖蜂窝网络；两种模式不得同时拦截 WLOC 请求。
+APP 模式不使用 Network Extension 创建 VPN 隧道，因此不会显示 VPN 连接，也不会占用系统 VPN。**它仍然需要当前 Wi‑Fi 的手动 HTTP 代理以及已完全信任的本机 CA。**
+
+### 第三方代理模式
+
+```text
+地图选点（WGS-84） → WLOC 配置接口 → 第三方代理模块保存坐标
+                                      │
+系统定位请求 → 第三方客户端代理/VPN + MITM ─┘→ 改写定位响应
+```
+
+第三方模式由所选客户端管理代理/VPN、证书和 MITM，可覆盖蜂窝网络。两种模式不要同时拦截 WLOC 请求。
+
+## 数据与安全说明
+
+- APP 模式的 CA 和私钥在设备本地生成，私钥存入 iOS 钥匙串；安装到系统的是 CA 描述文件。
+- 第三方代理模块及运行脚本来自上游项目，导入前请自行检查；仓库内快照用于版本留档，不代表已验证所有客户端。
+- 运行日志位于 App Group 容器，自动轮转并仅保留近 3 天；可在 App 内复制或清空。可导出的实时定位诊断默认不记录精确坐标。
+- 使用自签 CA 或第三方 MITM 都会改变设备的 HTTPS 信任/代理链路；不用时应关闭代理或模块，并按需移除证书。
 
 ## 兼容性
 
@@ -186,15 +208,18 @@ APP 模式不使用 Network Extension 创建 VPN 隧道，因此不会显示 VPN
 | 构建 | macOS、Xcode、XcodeGen |
 | Swift | 5.9 |
 | Go | 1.23+ |
-| 网络 | APP 模式：可手动配置 HTTP 代理的 Wi‑Fi；第三方代理模式（测试）：取决于代理客户端，可覆盖 Wi‑Fi/4G/5G |
+| 网络 | APP 模式：可手动配置 HTTP 代理的 Wi‑Fi；第三方代理模式（测试）：取决于客户端，可覆盖 Wi‑Fi/4G/5G |
 | 安装 | 自行签名或使用 Releases 构建产物 |
 
 效果会受到 iOS 版本、网络、系统定位缓存和目标 App 自身策略影响，不承诺兼容所有系统或第三方 App。
 
 ## 构建与项目结构
 
+构建要求为 macOS、Xcode Command Line Tools、Go 1.23+ 和 XcodeGen。执行：
+
 ```bash
-./build.sh
+./build.sh          # 构建未签名 IPA
+./build.sh --test   # 构建后额外运行 iOS Simulator 单元测试
 ```
 
 构建产物默认位于：
@@ -208,14 +233,16 @@ App/        SwiftUI、MapKit、定位和配置流程
 Core/       Go 本机代理与定位响应改写
 Shared/     收藏、设置、日志和共享模型
 Resources/  Info.plist、Entitlements 与图标
+Config/     构建配置
 Scripts/    构建、签名和检查脚本
 Tests/      XCTest 与 Bash 契约测试
-docs/       构建和版本发布归档
+docs/       构建、第三方模块和版本发布文档
 ```
 
 ## 文档与反馈
 
 - [构建说明](docs/BUILD.md)
+- [第三方模块说明](docs/THIRD_PARTY_MODULES.md)
 - [更新日志](docs/CHANGELOG.md)
 - [English README](README.en.md)
 - [GitHub Issues](https://github.com/xweiba/location-spoofer/issues)