diff --git a/README.en.md b/README.en.md
index 5d3173f..b78a9c1 100644
--- a/README.en.md
+++ b/README.en.md
@@ -2,216 +2,393 @@
# 📍 Location Spoofer
-### iOS Location Spoofer · DingTalk · WeChat · Apple Watch Region Unlock · Fake GPS
+### iOS Location Service Research & Testing Framework
-**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).**
-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.
+An open-source project for **iOS location-service research, software development testing, and QA validation**.
+
+The project uses either an on-device proxy or a third-party proxy client to simulate selected Apple location-service
+responses in a controlled test environment.
[](project.yml)
-[](project.yml)
-[](Core/go.mod)
+[](project.yml)
+[](Core/go.mod)
[](docs/CHANGELOG.md)
-[](#how-it-works)
-[Features](#key-features) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [中文](README.md) · [Changelog](docs/CHANGELOG.md)
-
-
+[Features](#feature-overview) ·
+[How It Works](#how-it-works) ·
+[Quick Start](#quick-start) ·
+[Build](#building-the-project) ·
+[中文](README.md)
> [!IMPORTANT]
-> 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.
+> Use this project only for education, research, testing on devices you own, software development, and QA validation.
+>
+> Use it only on devices, networks, and software environments that you own or are authorized to test. Follow applicable
+> laws, network policies, and service terms.
+>
+> The project does not guarantee compatibility with every iOS version or third-party app, and it does not promise to
+> bypass third-party security controls, business restrictions, or service rules.
-## Credits
+## Project Scope
-The core location-response rewriting approach and Go implementation are based on [Yu9191/wloc](https://github.com/Yu9191/wloc). This project adds a SwiftUI interface, MapKit selection, certificate and proxy guidance, environment verification, favorites, and diagnostics.
+Location Spoofer is a tool for studying iOS location-service behavior and testing location-dependent software.
-## Why Location Spoofer?
+It provides:
-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.
+- Native map selection and location-scenario switching;
+- Controlled simulation of selected Apple location-service responses;
+- App Mode and Third-party Proxy Mode;
+- Map coordinate detection with paired WGS-84 and GCJ-02 values;
+- Environment checks, runtime logs, and diagnostics;
+- Favorite locations and restoration of the previous map state.
-| Feature | Description |
+The project does not modify the target app's source code and does not provide telemetry, remote control, or data
+collection services.
+
+## Feature Overview
+
+- **Native map interaction**
+ - Uses MapKit for the map and system blue dot;
+ - Supports search, map taps, center-point dragging, and zooming;
+ - Supports favorites and restoration of the latest selection;
+ - Shows both domestic and international coordinate representations with separate copy actions.
+
+- **Location-service response simulation**
+ - Processes only the Apple location-service requests defined by the project;
+ - Returns the selected coordinates in a controlled test environment;
+ - Does not require changes to the target app.
+
+- **Two runtime modes**
+ - App Mode: runs the Go proxy on-device and covers only the current Wi-Fi network;
+ - Third-party Proxy Mode: uses a supported proxy client and may cover Wi-Fi, 4G, or 5G depending on that client.
+
+- **Environment checks**
+ - App Mode checks the local proxy, CA trust, and request path;
+ - Third-party Proxy Mode checks the WLOC configuration API and module response;
+ - Failures route to the relevant setup or diagnostics screen.
+
+- **Development diagnostics**
+ - Runtime logs;
+ - Log copy and cleanup;
+ - Map coordinate-system change records;
+ - Sanitized issue-report generation.
+
+## How It Works
+
+### App Mode
+
+App Mode runs the local Go proxy inside the app. A manual HTTP proxy on the current Wi-Fi routes the selected requests
+through that on-device proxy.
+
+```text
+iOS location request
+ │
+ │ Manual HTTP proxy on the current Wi-Fi
+ ▼
+On-device wloccore Go proxy
+ │
+ │ Handle selected Apple location-service requests
+ ▼
+Apple location-service response
+ │
+ │ Test coordinate response
+ ▼
+The system and apps read the location result
+```
+
+App Mode:
+
+- Does not create a Network Extension;
+- Does not display or occupy the system VPN slot;
+- Covers only the current Wi-Fi network;
+- Requires a manual HTTP proxy on that Wi-Fi network;
+- Requires installation and trust of the CA generated by the app;
+- Handles only the Apple location-service and environment-verification traffic defined by the project. It is not a
+ general-purpose packet capture tool.
+
+### Third-party Proxy Mode
+
+Third-party Proxy Mode does not start the app's Go proxy and does not use the CA generated by the app.
+
+```text
+Map selection
+ │
+ │ WGS-84 coordinates
+ ▼
+WLOC configuration API
+ │
+ ▼
+Third-party proxy client stores the configuration
+ │
+ ▼
+Third-party client processes location-service requests
+```
+
+In this mode:
+
+- The app owns map selection, favorites, coordinate synchronization, and coordinate clearing;
+- The third-party client owns proxy/VPN, MITM, certificates, and rule execution;
+- The third-party client owns coordinate persistence;
+- Wi-Fi, 4G, and 5G support depends on the client;
+- The configuration may remain active after Location Spoofer closes.
+
+Do not enable App Mode interception and Third-party Proxy Mode interception at the same time.
+
+## Runtime Modes
+
+### App Mode
+
+Suitable for:
+
+- Wi-Fi-only device testing;
+- Local testing without a third-party proxy client;
+- Workflows that need in-app proxy, certificate, and environment guidance.
+
+Requirements:
+
+- An iOS device;
+- A Wi-Fi network that permits manual HTTP proxy configuration;
+- Installation and trust of the local CA;
+- Completion of the in-app proxy and environment checks.
+
+### Third-party Proxy Mode
+
+Suitable for:
+
+- Tests that need Wi-Fi, 4G, or 5G coverage;
+- Existing supported proxy-client workflows;
+- Cases where the third-party client should keep the proxy configuration active.
+
+Current client status:
+
+| Client | Status |
|---|---|
-| 🔀 **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. |
-| 📍 **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. |
-| 🧭 **Coordinate consistency** | Reconciles MapKit map coordinates with WGS-84 for favorites, restoration, and third-party sync. |
-| 🧪 **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. |
+| Shadowrocket | Currently used for on-device testing |
+| Surge | Configuration provided, not fully verified |
+| Quantumult X | Configuration provided, not fully verified |
+| Loon | Configuration provided, not fully verified |
+| Stash | Configuration provided, not fully verified |
+| Egern | Uses the Surge module, not fully verified |
-## Screenshots
+Module snapshots and provenance:
-| Main Interface | Apple Maps | Amap | Apple Watch |
-|---|---|---|---|
-|  |  |  |  |
+- [Third-party module documentation](docs/THIRD_PARTY_MODULES.md)
+- [Yu9191/wloc](https://github.com/Yu9191/wloc)
-## Key Features
-
-- **iOS Location Spoofer / Fake GPS**: Apply the selected pin to App Mode's proxy or synchronize it to a third-party WLOC module.
-- **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 and state restoration**: Save, rename, and switch frequent locations while remembering the last pin and map range.
-- **Automatic coordinate handling**: Resolves the map's coordinate convention at startup and keeps paired WGS-84/map coordinates to reduce mainland-China map offsets.
-- **Mode-specific onboarding**: App Mode guides local proxy and CA setup; Third-party Mode guides client selection, subscription import, and connection testing.
-- **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.
+The selected client owns its certificates, MITM configuration, and proxy switches. Review third-party modules and
+scripts before importing them.
## Quick Start
### 1. Install the App
-Release assets are unsigned IPA files and must be installed with a sideloading tool:
+You can use:
-1. **Enable sideloading support**: On iOS 16 or later, open Settings → Privacy & Security → Developer Mode, enable it, then restart and confirm when prompted. iOS 15 does not have this switch, so skip this step there.
-2. **Download the IPA**: Open this project's [Releases](https://github.com/xweiba/location-spoofer/releases) and download the latest `PaopaoLocationSpoofer-unsigned.ipa`.
-3. **Prepare a sideloading tool**: Download the appropriate Impact build from [Impact Releases](https://github.com/claration/Impactor/releases/latest). Aisi Assistant/i4Tools or another tool that supports signing and installing IPA files may also be used.
-4. **Connect and install**: Connect the iPhone to the computer with a USB cable, tap “Trust This Computer” on the phone, select the downloaded IPA in the sideloading tool, and follow that tool's prompts to sign and install it.
+- Your own Apple Developer signing environment;
+- A self-signing tool suitable for personal testing;
+- The unsigned IPA published in Releases;
+- A source build produced on macOS using the [build guide](docs/BUILD.md).
-> Impact supports Windows, macOS, and Linux. If Windows cannot detect the device, install iTunes to provide the Apple device drivers. Aisi Assistant/i4Tools is third-party software; download it only from its official source and assess its account, certificate, and privacy risks yourself.
+Free self-signing environments may not provide Network Extension capabilities. App Mode therefore uses an on-device
+proxy plus a manual Wi-Fi HTTP proxy and does not depend on a VPN component.
-If iOS blocks the installed app, trust its developer app under Settings → General → VPN & Device Management. A free Apple ID signature normally expires after seven days and must then be renewed; this is separate from the WLOC CA certificate. Keep the app Bundle ID `com.paopaolabs.location-spoofer`, the App Group `group.com.paopaolabs.location-spoofer`, and the declared entitlements unchanged.
+#### Self-Signing Instructions
-To build the unsigned IPA yourself on macOS with Xcode, follow the [build guide](docs/BUILD.md), then use the same sideloading steps above to sign and install it.
+Release assets are unsigned IPA files and must be installed on an iPhone with a self-signing tool:
-### 2. Choose a Runtime Mode
+1. **Enable sideloading support**: On iOS 16 or newer, open Settings → Privacy & Security → Developer Mode, enable it,
+ then restart and confirm when prompted. iOS 15 does not have this switch, so skip this step.
+2. **Download the IPA**: Open this project's [Releases](https://github.com/xweiba/location-spoofer/releases) and download
+ the latest `PaopaoLocationSpoofer-unsigned.ipa`.
+3. **Prepare signing software**: Download the appropriate Impactor build from
+ [Impactor Releases](https://github.com/claration/Impactor/releases). Other tools that support self-signing and installing
+ IPA files, such as Aisi Assistant, may also be used.
+4. **Connect and install**: Connect the iPhone to the computer with a USB cable, choose “Trust This Computer” on the
+ phone, select the downloaded IPA in the signing software, and follow that tool's instructions to sign and install it.
-#### App Mode (On-device Wi-Fi)
+Impactor supports Windows, macOS, and Linux. If Windows cannot detect the device, install the Apple device drivers supplied
+with iTunes first. Aisi Assistant is third-party software; obtain it from its official channel and evaluate its account,
+certificate, and privacy risks yourself.
-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.
+After installation, if iOS blocks the app from opening, go to Settings → General → VPN & Device Management and trust the
+corresponding developer app. A free Apple ID signature normally expires after seven days and must then be renewed.
-On the current Wi-Fi network, set Configure Proxy to Manual:
+### 2. First Launch
+
+1. Choose App Mode or Third-party Proxy Mode;
+2. Complete the corresponding in-app setup;
+3. Run the environment check;
+4. Search, tap, or drag on the map to select a test location;
+5. Enable the test location and verify the result in the authorized test environment.
+
+### 3. Restore the Real Location
+
+App Mode:
+
+1. Stop the test location;
+2. Disable the manual HTTP proxy on the current Wi-Fi network;
+3. Follow the in-app instructions to refresh the location environment.
+
+Third-party Proxy Mode:
+
+1. Clear the WLOC coordinates from the app;
+2. Disable the corresponding module or proxy in the third-party client;
+3. Restore HTTPS decryption and proxy settings according to the client documentation.
+
+Location caches may take time to refresh. Restart the device if the system or target app continues to show an old
+location.
+
+## Coordinate Handling
+
+The project stores two coordinate representations:
+
+- WGS-84: the international standard used for WLOC writes;
+- GCJ-02: the domestic map representation used where required.
+
+MapKit does not expose a public API that reports whether its current runtime output uses GCJ-02 or WGS-84. The project
+uses a fixed-anchor query to resolve the active representation and performs controlled refreshes after blue-dot changes
+and explicit user actions.
+
+Each write boundary stores a complete WGS-84/GCJ-02 pair. Rendering selects the field matching the confirmed map
+representation instead of repeatedly converting an already typed value.
+
+## Project Structure
```text
-Server: 127.0.0.1
-Port: 8888
-Authentication: off
+App/ SwiftUI interface, MapKit, location, and runtime flow
+Core/ Go proxy, certificate server, and location-response handling
+Shared/ Coordinates, favorites, logs, configuration, and shared models
+Resources/ Info.plist, Entitlements, and resources
+Config/ Build configuration
+Scripts/ Build, packaging, and validation scripts
+Tests/ XCTest and Shell contract tests
+docs/ Build, module, and release documentation
```
-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:
+## Building the Project
-```text
-Settings → General → VPN & Device Management → install WLOC CA
-Settings → General → About → Certificate Trust Settings → enable full trust
-```
+Source builds require:
-#### Third-party Proxy Mode (Testing)
+- macOS;
+- Xcode;
+- Xcode Command Line Tools;
+- XcodeGen;
+- Go 1.23 or newer.
-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.
-
-### 4. Restore Your Real Location
-
-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.
-
-## How It Works
-
-### Why App Mode Needs No VPN
-
-```text
-iPhone location request
- │ Wi‑Fi HTTP proxy: 127.0.0.1:8888
- ▼
-Local wloccore Go proxy
- │ Handles only the targeted Apple location-service traffic
- ▼
-Apple location service response
- │ The selected coordinate is written into the response
- ▼
-The system and applications receive the modified result
-```
-
-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
-
-| Item | Requirement |
-|---|---|
-| iOS | 15.0+ |
-| Build | macOS, Xcode, XcodeGen |
-| Swift | 5.9 |
-| Go | 1.23+ |
-| 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:
+Building the iOS app directly on Windows is not supported.
```bash
-./build.sh # build the unsigned IPA
-./build.sh --test # also run iOS Simulator unit tests
+git clone https://github.com/xweiba/location-spoofer.git
+cd location-spoofer
+
+./build.sh
```
-The unsigned IPA is at:
+Build and run Simulator tests:
+
+```bash
+./build.sh --test
+```
+
+The build script generates an unsigned IPA:
```text
dist/PaopaoLocationSpoofer-unsigned.ipa
```
-```text
-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, third-party module, and release documentation
-```
+Deploy it to a test device using your own signing and installation process.
-## Documentation & Feedback
+## Privacy and Security Boundaries
+
+- The project contains no telemetry or remote-control service;
+- The project does not automatically upload location data;
+- Runtime logs remain in the device App Group container and retain only the latest three days;
+- Issue reports are copied by the user before being submitted to GitHub;
+- App Mode accesses the local proxy and the environment-verification URL;
+- Third-party Proxy Mode may access the upstream module URL and the WLOC configuration endpoint;
+- The CA private key generated by the app is stored in the device Keychain;
+- Third-party MITM, certificates, and proxy behavior are owned by the selected client.
+
+Do not post real locations, authentication information, CA private keys, or complete sensitive logs in public issues.
+
+## Limitations
+
+- iOS updates may change location-service behavior;
+- MapKit coordinate output can vary with the system, region, and location environment;
+- System location caches may delay visible changes;
+- Each third-party proxy client requires separate compatibility testing;
+- Not every app uses the same location API;
+- Not every app or service accepts test coordinates;
+- Behavior is not guaranteed across every network, device model, or iOS version.
+
+## Contributing
+
+Contributions are welcome for:
+
+- Bug reports;
+- Feature requests;
+- Compatibility results;
+- Performance improvements;
+- Documentation improvements;
+- Additional tests.
+
+When filing an issue, include:
+
+- iOS version;
+- Device model;
+- Runtime mode;
+- Reproduction steps;
+- Sanitized runtime logs;
+- Whether a third-party proxy client was used.
+
+## Documentation
- [Build guide](docs/BUILD.md)
-- [Third-party module snapshots](docs/THIRD_PARTY_MODULES.md)
+- [Third-party module documentation](docs/THIRD_PARTY_MODULES.md)
- [Changelog](docs/CHANGELOG.md)
- [中文文档](README.md)
- [GitHub Issues](https://github.com/xweiba/location-spoofer/issues)
-When reporting issues, please include reproduction steps, iOS version, device model, and sanitized runtime logs.
+## Feature Preview
-## Links
+These screenshots show the main interface and selected on-device test scenarios. Actual results depend on the iOS
+version, network environment, system caches, and the target app's location strategy; they are not a compatibility
+guarantee for every app or release.
-**LinuxDo** — [https://linux.do](https://linux.do/)
+
+
+ | Main interface |
+ Apple Maps test |
+ Amap test |
+
+
+ |
+  |
+  |
+
+
+ | WeChat test |
+ DingTalk test |
+ Apple Watch scenario test |
+
+
+  |
+  |
+  |
+
+
+
+## Acknowledgements and Links
+
+The core location-response handling approach, Go implementation, and third-party modules are based on:
+
+- [Yu9191/wloc](https://github.com/Yu9191/wloc)
+
+Community link:
+
+- [LINUX DO](https://linux.do/)
+
+Thanks to the open-source contributors working on iOS location-service research, network proxies, and mobile testing
+tools.
diff --git a/README.md b/README.md
index 3c649f9..2ad9d7c 100644
--- a/README.md
+++ b/README.md
@@ -2,261 +2,384 @@
# 📍 Location Spoofer
-### iOS 虚拟定位 · 钉钉定位 · 微信定位 · Apple Watch 国区功能解锁 · Fake GPS
+### iOS Location Service Research & Testing Framework
-**无需越狱；通过 APP 模式的本机 Wi‑Fi HTTP 代理，或第三方代理模式（Wi‑Fi/4G/5G）改写 Apple 定位服务响应。**
-适用于钉钉、微信、Apple 地图等读取系统定位的 App。地图选点、收藏、模式配置、环境检测和问题诊断集中在一个 App 中。
+一个用于 **iOS 定位服务研究、软件开发测试和 QA 验证** 的开源项目。
+
+项目通过本机代理或第三方代理客户端，对 Apple 定位服务的指定响应进行测试环境模拟，帮助开发者验证应用在
+不同地理位置和定位场景下的行为。
[](project.yml)
-[](project.yml)
-[](Core/go.mod)
+[](project.yml)
+[](Core/go.mod)
[](docs/CHANGELOG.md)
-[](#工作原理)
-[功能介绍](#核心功能) · [快速开始](#快速开始) · [工作原理](#工作原理) · [English](README.en.md) · [更新日志](docs/CHANGELOG.md)
-
-
+[功能概览](#功能概览) ·
+[工作原理](#工作原理) ·
+[快速开始](#快速开始) ·
+[构建项目](#构建项目) ·
+[English](README.en.md)
> [!IMPORTANT]
-> 本项目仅用于学习、安全研究和自有设备测试。APP 模式需要安装本机生成的 CA，并为当前 Wi‑Fi 配置 HTTP 代理；第三方代理模式的证书、MITM 及代理/VPN 连接由所选客户端负责。实际效果受 iOS、网络、定位缓存和目标 App 策略影响，请遵守当地法律、网络管理规则及相关服务条款。
+> 本项目用于学习研究、自有设备测试、软件开发和 QA 验证。
+>
+> 请仅在你拥有或获得授权的设备、网络和软件环境中使用，并遵守当地法律法规、网络管理规定以及相关服务条
+> 款。
+>
+> 本项目不保证兼容所有 iOS 版本或第三方应用，也不承诺绕过第三方应用的安全策略、业务限制或服务规则。
-## 致谢
+## 项目定位
-核心定位响应改写思路与 Go 实现来源于 [Yu9191/wloc](https://github.com/Yu9191/wloc)。本项目在此基础上增加 SwiftUI 界面、MapKit 选点、证书与代理引导、环境验证、收藏和诊断能力。
+Location Spoofer 是一个面向 iOS 定位服务行为研究和开发测试的工具。
-## 为什么选择 Location Spoofer？
+它提供：
-很多 iOS 虚拟定位工具依赖电脑常驻、开发者调试或越狱。本项目把选点和控制流程放在 iPhone 上，并提供两条互斥的运行路径：由 App 在本机启动 Go 代理，或把坐标同步给已有的第三方代理客户端。
+- 原生地图选点和位置场景切换；
+- Apple 定位服务响应的测试环境模拟；
+- 本地代理和第三方代理两种运行模式；
+- 坐标标准识别与 WGS-84 / GCJ-02 双坐标管理；
+- 环境检测、运行日志和问题诊断；
+- 收藏位置和上次地图状态恢复。
-| 特性 | 说明 |
-|---|---|
-| 🔀 **双运行模式** | APP 模式无需第三方客户端、适用于 Wi‑Fi；第三方代理模式可随客户端覆盖 Wi‑Fi、4G 和 5G |
-| 📱 **无需越狱** | 支持自行签名安装，最低部署目标为 iOS 15 |
-| 🗺️ **原生地图体验** | 使用 Apple 地图同款蓝点，搜索、点击、拖动选点体验与 Apple 地图一致 |
-| 📍 **系统定位响应改写** | 可影响钉钉、微信、Apple 地图、高德等读取系统定位的 App，兼容性以真机结果为准 |
-| 🔍 **可见缩放范围** | 左侧缩放控件显示当前可视范围，地点名称随级别自动适配 |
-| 🧭 **坐标一致性** | 自动处理 MapKit 地图坐标与 WGS-84，收藏、恢复和第三方同步使用明确的坐标来源 |
-| 🧪 **按模式检测** | APP 模式检查本地代理、CA 信任和 Wi‑Fi 链路；第三方模式验证模块是否真正拦截请求 |
-| 🧾 **问题诊断** | 日志可搜索、逐条或整体复制，并可生成已脱敏的 GitHub Issue 报告 |
+项目不修改目标 App 的源代码，也不提供远程控制或数据采集服务。
-## 效果预览
+## 功能概览
-
-
- | 应用主界面 |
- 钉钉 |
- 微信 |
-
-
- |
- |
- |
-
-
- | Apple 地图 |
- 高德地图 |
- Apple Watch |
-
-
- |
- |
- |
-
-
+- **原生地图交互**
+ - 使用 MapKit 显示地图和系统蓝点；
+ - 支持搜索、点击选点、拖动地图中心和缩放；
+ - 支持收藏位置和恢复上次选点；
+ - 当前选点同时显示国内坐标和国际坐标，可分别复制。
-## 核心功能
+- **定位服务响应模拟**
+ - 通过代理层处理指定的 Apple 定位服务请求；
+ - 在测试环境中返回选定的坐标数据；
+ - 不需要修改目标 App 代码。
-- **iOS 虚拟定位 / Fake GPS**：将当前选点写入 APP 模式代理，或同步给第三方 WLOC 模块。
-- **原生地图与实时位置**：使用 MapKit 蓝点，支持搜索、点击、拖动地图中心、缩放以及快速打开 Apple 地图。
-- **并发安全选点**：拖动、点击、搜索、收藏和异步定位按用户最新意图处理，旧结果不会覆盖新选点。
-- **地点名称分级**：近距离显示 POI、门牌或道路；拉远后显示社区、区县、城市或省份。
-- **地图范围显示**：缩放控件中显示 `180 m`、`2.5 km`、`126 km` 等当前可视范围。
-- **收藏与状态恢复**：保存、重命名和切换常用位置，记住最后图钉与地图范围。
-- **坐标系自动处理**：启动时确认地图坐标标准，内部保留 WGS-84 与地图坐标配对，减少中国大陆地图偏移。
-- **分模式首次引导**：APP 模式配置本机代理和 CA；第三方模式选择客户端、复制订阅地址并检测连接。
-- **本机代理保活**：APP 模式启动虚拟定位后使用静音音频维持后台运行，并响应网络切换重新检测环境。
-- **结构化诊断**：运行日志自动轮转，仅保留近 3 天；支持过滤、复制、清空和生成 Issue 报告。
-- **第三方代理模式（测试）**：向模块查询、保存或清除 WGS-84 坐标；坐标由代理客户端持久化，关闭本 App 后仍可能继续生效。
+- **双运行模式**
+ - APP 模式：在设备内运行 Go 代理，仅支持当前 Wi-Fi 网络；
+ - 第三方代理模式：通过支持的代理客户端覆盖 Wi-Fi、4G 或 5G，具体能力取决于客户端。
-## 快速开始
+- **环境检测**
+ - APP 模式检测本地代理、证书信任和请求链路；
+ - 第三方代理模式检测 WLOC 配置接口和模块响应；
+ - 失败时提供对应的配置或诊断入口。
-### 1. 安装 App
-
-#### 自签安装
-
-Release 附件是未签名 IPA，需要使用自签工具安装到 iPhone：
-
-1. **开启自签支持**：iOS 16 及以上版本前往“设置 → 隐私与安全性 → 开发者模式”，开启后按系统提示重启并确认；iOS 15 没有此开关，可跳过本步。
-2. **下载 IPA**：前往本项目的 [Releases](https://github.com/xweiba/location-spoofer/releases)，下载最新的 `PaopaoLocationSpoofer-unsigned.ipa`。
-3. **准备自签软件**：前往 [Impact Releases](https://github.com/claration/Impactor/releases/latest) 下载对应系统版本的 Impact；也可以使用爱思助手等支持 IPA 自签安装的软件。
-4. **连接并安装**：使用 USB 数据线连接 iPhone 与电脑，在手机上选择“信任此电脑”，然后在自签软件中选择刚下载的 IPA，根据软件提示完成签名与安装。
-
-> Impact 支持 Windows、macOS 和 Linux；Windows 若无法识别设备，请先安装 iTunes 提供 Apple 设备驱动。爱思助手属于第三方软件，请从其官方渠道获取，并自行评估账号、证书和隐私风险。
-
-安装完成后，若 iOS 阻止打开 App，请前往“设置 → 通用 → VPN 与设备管理”信任对应的开发者 App。免费 Apple ID 自签通常只有 7 天有效期，到期后需要重新签名安装。
-
-本项目自身不包含 VPN、Network Extension 或 Packet Tunnel Provider，但签名工具仍需保留 App 的标识和声明能力。
-
-需要自行构建时执行：
-
-```bash
-./build.sh
-```
-
-输出文件为 `dist/PaopaoLocationSpoofer-unsigned.ipa`，随后按上面的自签步骤安装到设备。完整构建要求见[构建说明](docs/BUILD.md)。
-
-签名时不要修改以下标识，也不要移除 App Group 和 Wi-Fi 信息能力：
-
-| 组件 | 标识 |
-|---|---|
-| 主 App Bundle ID | `com.paopaolabs.location-spoofer` |
-
-签名有效期是 Apple 的侧载限制，不是 WLOC CA 失效。CA 私钥保存在 iOS 钥匙串中：相同 Bundle ID 和钥匙串访问范围下重装通常可以复用，但卸载、系统清理或签名能力变化后不保证保留。
-
-### 2. 选择运行模式
-
-#### APP 模式（本机 Wi‑Fi）
-
-首次打开后选择 APP 模式，再按 App 内引导配置代理和 CA。此模式会在设备内启动 `wloccore`，不依赖第三方代理客户端，但流量入口只覆盖当前 Wi‑Fi。
-
-##### 配置当前 Wi‑Fi 代理
-
-首次打开后，先在当前 Wi‑Fi 的“配置代理”中选择“手动”：
-
-```text
-服务器：127.0.0.1
-端口：8888
-鉴定：关闭
-```
-
-返回 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 提供官方订阅地址复制和客户端跳转按钮；在对应客户端的模块、重写或覆写订阅入口粘贴地址并导入。仓库和 App 包内仍保留以下模块配置快照，用于版本归档和离线核对：
-
-| 客户端 | 状态 | 模块 |
-|---|---|---|
-| Shadowrocket（小火箭） | **当前可测试** | [wloc.module](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.module) |
-| Surge | 配置已提供，尚未验证 | [wloc.sgmodule](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.sgmodule) |
-| Quantumult X | 配置已提供，尚未验证 | [wloc.conf](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.conf) |
-| Loon | 配置已提供，尚未验证 | [wloc.lpx](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.lpx) |
-| Stash | 配置已提供，尚未验证 | [wloc.stoverride](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.stoverride) |
-| Egern | 配置已提供，尚未验证 | 直接使用 Surge 模块 |
-
-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 蓝点，也可以保存为收藏。
-2. APP 模式点击“开始虚拟定位”并等待环境检测；第三方代理模式点击“同步到第三方代理”。
-3. 按 App 内“生效说明”刷新飞行模式、Wi‑Fi 和定位服务状态。
-4. 打开 Apple 地图或目标 App 验证结果。
-
-### 4. 恢复真实位置
-
-APP 模式下先停止虚拟定位，再关闭当前 Wi‑Fi 的手动代理；第三方代理模式下使用“清除第三方代理坐标”，必要时再停用对应模块或代理连接。随后按 App 内“失效说明”刷新系统定位缓存；若仍保留旧位置，请重启设备后再检查。
+- **开发调试**
+ - 运行日志；
+ - 日志复制和清理；
+ - 坐标标准变化记录；
+ - 脱敏问题报告生成。
## 工作原理
-### APP 模式为什么不需要 VPN？
+### APP 模式
+
+APP 模式在设备内运行本地 Go 代理，并通过当前 Wi-Fi 的手动 HTTP 代理让指定请求经过本地代理。
```text
-iPhone 定位请求
- │ 当前 Wi‑Fi HTTP 代理：127.0.0.1:8888
+iOS 定位请求
+ │
+ │ 当前 Wi-Fi 手动 HTTP 代理
▼
-本机 wloccore（Go）
- │ 仅处理目标 Apple 定位服务请求
- ├──────────────► Apple 定位服务
- ◄──────────────┘
- │ 改写目标响应中的坐标
+设备内 wloccore Go 代理
+ │
+ │ 处理指定 Apple 定位服务请求
▼
-系统与应用读取定位结果
+Apple 定位服务响应
+ │
+ │ 测试坐标响应
+ ▼
+系统和应用读取定位结果
```
-APP 模式不使用 Network Extension 创建 VPN 隧道，因此不会显示 VPN 连接，也不会占用系统 VPN。**它仍然需要当前 Wi‑Fi 的手动 HTTP 代理以及已完全信任的本机 CA。**
+APP 模式：
+
+- 不创建 Network Extension；
+- 不显示或占用系统 VPN；
+- 只覆盖当前 Wi-Fi 网络；
+- 需要配置当前 Wi-Fi 的手动 HTTP 代理；
+- 需要安装并信任 App 生成的本机 CA；
+- 代理只处理项目定义的 Apple 定位服务和环境验证请求，不是通用网络抓包工具。
### 第三方代理模式
+第三方代理模式不启动 App 内置 Go 代理，也不使用 App 生成的 CA。
+
```text
-地图选点（WGS-84） → WLOC 配置接口 → 第三方代理模块保存坐标
- │
-系统定位请求 → 第三方客户端代理/VPN + MITM ─┘→ 改写定位响应
+地图选点
+ │
+ │ WGS-84 坐标
+ ▼
+WLOC 配置接口
+ │
+ ▼
+第三方代理客户端保存配置
+ │
+ ▼
+第三方代理客户端处理定位服务请求
```
-第三方模式由所选客户端管理代理/VPN、证书和 MITM，可覆盖蜂窝网络。两种模式不要同时拦截 WLOC 请求。
+在该模式下：
-## 数据与安全说明
+- App 负责地图选点、收藏、坐标同步和清除；
+- 第三方客户端负责代理/VPN、MITM、证书和规则执行；
+- 坐标持久化由第三方客户端负责；
+- 是否支持 Wi-Fi、4G 或 5G 取决于客户端；
+- App 关闭后，第三方客户端中的配置可能继续生效。
-- APP 模式的 CA 和私钥在设备本地生成，私钥存入 iOS 钥匙串；安装到系统的是 CA 描述文件。
-- 第三方代理模块及运行脚本来自上游项目，导入前请自行检查；仓库内快照用于版本留档，不代表已验证所有客户端。
-- 运行日志位于 App Group 容器，自动轮转并仅保留近 3 天；可在 App 内复制或清空。可导出的实时定位诊断默认不记录精确坐标。
-- 使用自签 CA 或第三方 MITM 都会改变设备的 HTTPS 信任/代理链路；不用时应关闭代理或模块，并按需移除证书。
+不要同时启用 APP 模式代理和第三方代理模式，避免两个代理链路互相干扰。
-## 兼容性
+## 运行模式
-| 项目 | 要求 |
+### APP 模式
+
+适用于：
+
+- 只使用 Wi-Fi 的设备测试；
+- 不依赖第三方代理客户端的本地验证；
+- 需要在 App 内完成代理、证书和环境检测的场景。
+
+使用条件：
+
+- iOS 设备；
+- 当前 Wi-Fi 支持手动 HTTP 代理；
+- 安装并信任本机 CA；
+- 在 App 内完成代理配置和环境检测。
+
+### 第三方代理模式
+
+适用于：
+
+- 需要 Wi-Fi、4G 或 5G 网络覆盖的测试；
+- 已经使用支持模块或脚本的代理客户端；
+- 希望由第三方客户端继续保持代理配置的场景。
+
+当前客户端状态：
+
+| 客户端 | 状态 |
|---|---|
-| iOS | 15.0+ |
-| 构建 | macOS、Xcode、XcodeGen |
-| Swift | 5.9 |
-| Go | 1.23+ |
-| 网络 | APP 模式：可手动配置 HTTP 代理的 Wi‑Fi；第三方代理模式（测试）：取决于客户端，可覆盖 Wi‑Fi/4G/5G |
-| 安装 | 自行签名或使用 Releases 构建产物 |
+| Shadowrocket | 当前用于真机测试 |
+| Surge | 已提供配置，尚未完整验证 |
+| Quantumult X | 已提供配置，尚未完整验证 |
+| Loon | 已提供配置，尚未完整验证 |
+| Stash | 已提供配置，尚未完整验证 |
+| Egern | 使用 Surge 模块，尚未完整验证 |
-效果会受到 iOS 版本、网络、系统定位缓存和目标 App 自身策略影响，不承诺兼容所有系统或第三方 App。
+相关模块快照和来源记录：
-## 构建与项目结构
+- [第三方模块说明](docs/THIRD_PARTY_MODULES.md)
+- [Yu9191/wloc](https://github.com/Yu9191/wloc)
-构建要求为 macOS、Xcode Command Line Tools、Go 1.23+ 和 XcodeGen。执行：
+第三方客户端、证书、MITM 和代理开关由客户端自身负责。导入任何第三方模块前，请先审查其配置和脚本内容。
+
+## 快速开始
+
+### 1. 安装应用
+
+你可以使用：
+
+- 自己的 Apple Developer 签名环境；
+- 适合个人测试的自签工具；
+- 项目 Releases 中的未签名 IPA；
+- 在 macOS 上按[构建说明](docs/BUILD.md)自行构建。
+
+免费自签环境可能无法使用 Network Extension，因此 APP 模式采用设备内本地代理和 Wi-Fi 手动代理，不依赖
+VPN 组件。
+
+#### 自签安装说明
+
+Release 附件是未签名 IPA，需要使用自签工具安装到 iPhone：
+
+1. **开启自签支持**：iOS 16 及以上版本前往“设置 → 隐私与安全性 → 开发者模式”，开启后按系统提示重启并
+ 确认；iOS 15 没有此开关，可跳过本步。
+2. **下载 IPA**：前往本项目的 [Releases](https://github.com/xweiba/location-spoofer/releases)，下载最新的
+ `PaopaoLocationSpoofer-unsigned.ipa`。
+3. **准备自签软件**：前往 [Impactor Releases](https://github.com/claration/Impactor/releases) 下载对应系统
+ 版本的 Impactor；也可以使用爱思助手等支持 IPA 自签安装的软件。
+4. **连接并安装**：使用 USB 数据线连接 iPhone 与电脑，在手机上选择“信任此电脑”，然后在自签软件中选择
+ 刚下载的 IPA，根据软件提示完成签名与安装。
+
+Impactor 支持 Windows、macOS 和 Linux；Windows 若无法识别设备，请先安装 iTunes 提供的 Apple 设备驱动。
+爱思助手属于第三方软件，请从其官方渠道获取，并自行评估账号、证书和隐私风险。
+
+安装完成后，若 iOS 阻止打开 App，请前往“设置 → 通用 → VPN 与设备管理”信任对应的开发者 App。免费
+Apple ID 自签通常只有 7 天有效期，到期后需要重新签名安装。
+
+### 2. 首次启动
+
+首次启动时：
+
+1. 选择 APP 模式或第三方代理模式；
+2. 按照 App 内引导完成对应配置；
+3. 执行环境检测；
+4. 在地图中搜索、点击或拖动选择测试位置；
+5. 启用测试位置并在目标测试环境中验证结果。
+
+### 3. 恢复真实位置
+
+APP 模式：
+
+1. 停止测试位置；
+2. 关闭当前 Wi-Fi 的手动 HTTP 代理；
+3. 按 App 内提示刷新定位环境。
+
+第三方代理模式：
+
+1. 使用 App 清除 WLOC 坐标；
+2. 在第三方客户端中关闭对应模块或代理；
+3. 按客户端要求恢复 HTTPS 解密和代理设置。
+
+如果系统或目标应用仍显示旧位置，可能需要等待定位缓存刷新，必要时重启设备后再次验证。
+
+## 坐标处理
+
+项目内部保存两种坐标表示：
+
+- WGS-84：国际标准，WLOC 写入使用此坐标；
+- GCJ-02：国内地图标准，用于需要国内地图坐标的场景。
+
+MapKit 不提供公开 API 直接返回当前是否使用 GCJ-02 或 WGS-84。项目通过固定锚点查询判断 MapKit 当前返回
+标准，并在运行期间根据蓝点变化和用户操作进行受控刷新。
+
+坐标写入边界会保存完整的 WGS-84 / GCJ-02 坐标对，使用时根据当前地图标准选择对应字段，避免重复转换造成
+位置偏移。
+
+## 项目结构
+
+```text
+App/ SwiftUI 界面、MapKit、定位和运行流程
+Core/ Go 代理、证书服务和定位响应处理
+Shared/ 坐标、收藏、日志、配置和共享模型
+Resources/ Info.plist、Entitlements 和资源文件
+Config/ 构建配置
+Scripts/ 构建、打包和验证脚本
+Tests/ XCTest 和 Shell contract tests
+docs/ 构建、模块和版本文档
+```
+
+## 构建项目
+
+源码构建需要 macOS 环境：
+
+- macOS；
+- Xcode；
+- Xcode Command Line Tools；
+- XcodeGen；
+- Go 1.23 或更高版本。
+
+当前项目不支持在 Windows 上直接构建 iOS 应用。
```bash
-./build.sh # 构建未签名 IPA
-./build.sh --test # 构建后额外运行 iOS Simulator 单元测试
+git clone https://github.com/xweiba/location-spoofer.git
+cd location-spoofer
+
+./build.sh
```
-构建产物默认位于：
+运行构建并执行 Simulator 测试：
+
+```bash
+./build.sh --test
+```
+
+构建脚本会生成未签名 IPA：
```text
dist/PaopaoLocationSpoofer-unsigned.ipa
```
-```text
-App/ SwiftUI、MapKit、定位和配置流程
-Core/ Go 本机代理与定位响应改写
-Shared/ 收藏、设置、日志和共享模型
-Resources/ Info.plist、Entitlements 与图标
-Config/ 构建配置
-Scripts/ 构建、签名和检查脚本
-Tests/ XCTest 与 Bash 契约测试
-docs/ 构建、第三方模块和版本发布文档
-```
+之后需要使用你自己的签名和安装流程部署到测试设备。
-## 文档与反馈
+## 隐私与安全边界
+
+- 项目不包含遥测或远程控制服务；
+- 项目不会自动上传用户位置数据；
+- 运行日志保存在设备 App Group 容器中，并自动保留近三天；
+- 问题报告需要用户主动复制后提交到 GitHub；
+- APP 模式会访问本机代理和环境验证地址；
+- 第三方代理模式可能访问上游模块地址和 WLOC 配置接口；
+- App 生成的 CA 私钥保存在设备 Keychain 中；
+- 第三方客户端模块、MITM 和证书链路由用户选择的客户端负责。
+
+请不要把真实位置、认证信息、证书私钥或完整敏感日志提交到公开 Issue。
+
+## 限制
+
+- iOS 系统版本变化可能影响定位服务行为；
+- MapKit 的坐标返回标准可能随系统、地区和定位环境变化；
+- 系统定位存在缓存，切换位置后不一定立即生效；
+- 第三方代理客户端的兼容性和规则行为需要分别验证；
+- 不保证所有应用都使用同一种定位 API；
+- 不保证所有应用或服务都接受测试坐标；
+- 不保证在所有网络环境、设备型号和 iOS 版本上表现一致。
+
+## 贡献
+
+欢迎提交：
+
+- Bug Report；
+- Feature Request；
+- 兼容性测试结果；
+- 性能改进；
+- 文档改进；
+- 测试补充。
+
+提交 Issue 时建议包含：
+
+- iOS 版本；
+- 设备型号；
+- 使用的运行模式；
+- 复现步骤；
+- 脱敏后的运行日志；
+- 是否使用第三方代理客户端。
+
+## 文档
- [构建说明](docs/BUILD.md)
- [第三方模块说明](docs/THIRD_PARTY_MODULES.md)
- [更新日志](docs/CHANGELOG.md)
-- [English README](README.en.md)
+- [英文文档](README.en.md)
- [GitHub Issues](https://github.com/xweiba/location-spoofer/issues)
-反馈问题时，请附上复现步骤、iOS 版本、设备型号及已脱敏的运行日志。
+## 功能预览
-## 友链
+以下截图用于展示主界面和部分真机测试场景。实际结果会受到 iOS 版本、网络环境、系统缓存和目标应用定位策略
+影响，不代表对所有应用或版本作出兼容性保证。
-**LinuxDo** — [https://linux.do](https://linux.do/)
+
+
+ | 应用主界面 |
+ Apple 地图测试 |
+ 高德地图测试 |
+
+
+ |
+ |
+ |
+
+
+ | 微信测试 |
+ 钉钉测试 |
+ Apple Watch 场景测试 |
+
+
+ |
+ |
+ |
+
+
+
+## 致谢与友链
+
+核心定位响应处理思路、Go 实现和第三方模块参考自：
+
+- [Yu9191/wloc](https://github.com/Yu9191/wloc)
+
+友链：
+
+- [LINUX DO](https://linux.do/)
+
+感谢开源社区中参与 iOS 定位服务研究、网络代理和移动端测试工具建设的贡献者。
diff --git a/Scripts/generate-release-notes.sh b/Scripts/generate-release-notes.sh
index c030602..618cbe4 100755
--- a/Scripts/generate-release-notes.sh
+++ b/Scripts/generate-release-notes.sh
@@ -41,7 +41,7 @@ ${COMMITS}
## 自签安装
- Release 附件为未签名 IPA，安装前需要自行签名。
-- 可使用免费 Apple ID 和 Impact 完成签名安装，无需付费开发者账号。
+- 可使用免费 Apple ID 和 Impactor 完成签名安装，无需付费开发者账号。
- 签名时请保留 Bundle ID \`com.paopaolabs.location-spoofer\`、App Group \`group.com.paopaolabs.location-spoofer\` 及原有 entitlements。
- 免费 Apple ID 签名通常只有 7 天有效期，到期后需要重新签名安装。
diff --git a/Tests/readme_contract_test.sh b/Tests/readme_contract_test.sh
new file mode 100755
index 0000000..845d79f
--- /dev/null
+++ b/Tests/readme_contract_test.sh
@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ZH="$ROOT/README.md"
+EN="$ROOT/README.en.md"
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+grep -q 'iOS Location Service Research & Testing Framework' "$ZH" || fail "Chinese README positioning is missing"
+grep -q 'iOS Location Service Research & Testing Framework' "$EN" || fail "English README positioning is missing"
+
+grep -q '#### 自签安装说明' "$ZH" || fail "Chinese self-signing instructions are missing"
+grep -q '#### Self-Signing Instructions' "$EN" || fail "English self-signing instructions are missing"
+grep -q 'Impactor Releases' "$ZH" || fail "Chinese README must link the requested Impactor releases"
+grep -q 'Impactor Releases' "$EN" || fail "English README must link the requested Impactor releases"
+grep -q '开发者模式' "$ZH" || fail "Chinese README must explain iOS 16 Developer Mode"
+grep -q 'Developer Mode' "$EN" || fail "English README must explain iOS 16 Developer Mode"
+grep -q '7 天有效期' "$ZH" || fail "Chinese README must disclose free-signing expiry"
+grep -q 'seven days' "$EN" || fail "English README must disclose free-signing expiry"
+
+grep -q '^## 功能预览$' "$ZH" || fail "Chinese feature preview is missing"
+grep -q '^## Feature Preview$' "$EN" || fail "English feature preview is missing"
+
+images=(
+ '主界面.jpg'
+ 'Apple%20Map.jpg'
+ '高德地图.jpg'
+ '微信.jpg'
+ '钉钉.jpg'
+ '高血压.jpg'
+)
+for image in "${images[@]}"; do
+ grep -q "images/$image" "$ZH" || fail "Chinese README is missing image: $image"
+ grep -q "images/$image" "$EN" || fail "English README is missing image: $image"
+done
+
+image_files=(
+ '主界面.jpg'
+ 'Apple Map.jpg'
+ '高德地图.jpg'
+ '微信.jpg'
+ '钉钉.jpg'
+ '高血压.jpg'
+)
+for image in "${image_files[@]}"; do
+ test -f "$ROOT/images/$image" || fail "referenced preview image is missing: $image"
+done
+
+test "$(grep -c '^## ' "$ZH")" -eq "$(grep -c '^## ' "$EN")" \
+ || fail "Chinese and English README section counts must stay aligned"
+
+! grep -Eq '^## (许可证|License)$' "$ZH" "$EN" || fail "README must not claim a repository license"
+grep -q '当前项目不支持在 Windows 上直接构建 iOS 应用' "$ZH" || fail "Chinese README must reject Windows source builds"
+grep -q 'Building the iOS app directly on Windows is not supported' "$EN" || fail "English README must reject Windows source builds"
+
+if grep -Rnw --include='*.md' --include='*.sh' \
+ "$ROOT/build.sh" "$ROOT/README.md" "$ROOT/README.en.md" "$ROOT/docs" "$ROOT/Scripts" \
+ -e 'Impact'; then
+ fail "documentation and build output must use the correct Impactor name"
+fi
+
+echo "PASS: README contract"
diff --git a/build.sh b/build.sh
index 4d0897e..38ec743 100755
--- a/build.sh
+++ b/build.sh
@@ -73,4 +73,4 @@ if [ "$run_tests" -eq 1 ]; then
run_simulator_tests
fi
-echo "Next: sign with Impact (https://github.com/claration/Impactor) and install on device."
+echo "Next: sign with Impactor (https://github.com/claration/Impactor) and install on device."
diff --git a/docs/BUILD.md b/docs/BUILD.md
index 5bef662..e7e4052 100644
--- a/docs/BUILD.md
+++ b/docs/BUILD.md
@@ -32,12 +32,12 @@ Output:
dist/PaopaoLocationSpoofer-unsigned.ipa
```
-IPA 始终保持未签名。用 [Impact](https://github.com/claration/Impactor) 签名安装即可。
+IPA 始终保持未签名。用 [Impactor](https://github.com/claration/Impactor) 签名安装即可。
## 发布验收
1. `./build.sh` 通过并输出未签名 IPA
-2. 用 Impact 签名后安装到设备
+2. 用 Impactor 签名后安装到设备
3. 真机安装后，先配置 WiFi HTTP 代理 `127.0.0.1:8888`，再按检测结果完成 CA 下载、安装和信任
4. 环境检测通过后，选点开启虚拟定位
5. 打开 Apple 地图验证定位是否变为虚拟位置
diff --git a/docs/releases/v1.0.0.md b/docs/releases/v1.0.0.md
index bf344e0..725dd06 100644
--- a/docs/releases/v1.0.0.md
+++ b/docs/releases/v1.0.0.md
@@ -16,13 +16,13 @@
| 项目 | 要求 |
|---|---|
| iOS | 15.0+ |
-| 安装 | 自行签名（推荐 [Impact](https://github.com/claration/Impactor)） |
+| 安装 | 自行签名（推荐 [Impactor](https://github.com/claration/Impactor)） |
| 网络 | 可手动配置 HTTP 代理的 WiFi |
### 自签安装
1. 从 [Releases](https://github.com/xweiba/location-spoofer/releases) 下载 `PaopaoLocationSpoofer-unsigned.ipa`
-2. 使用 [Impact](https://github.com/claration/Impactor) 签名安装
+2. 使用 [Impactor](https://github.com/claration/Impactor) 签名安装
3. 签名时保留 Bundle ID `com.paopaolabs.location-spoofer`、App Group `group.com.paopaolabs.location-spoofer` 及原有 entitlements
### 致谢
diff --git a/docs/releases/v1.0.1.md b/docs/releases/v1.0.1.md
index bb7f927..719645d 100644
--- a/docs/releases/v1.0.1.md
+++ b/docs/releases/v1.0.1.md
@@ -13,7 +13,7 @@
## 自签安装
- Release 附件为未签名 IPA，安装前需要自行签名。
-- 可使用免费 Apple ID 和 Impact 完成签名安装，无需付费开发者账号。
+- 可使用免费 Apple ID 和 Impactor 完成签名安装，无需付费开发者账号。
- 签名时请保留 Bundle ID `com.paopaolabs.location-spoofer`、App Group `group.com.paopaolabs.location-spoofer` 及原有 entitlements。
- 免费 Apple ID 签名通常只有 7 天有效期，到期后需要重新签名安装。