+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published
+ by the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program. If not, see .
+
+Also add information on how to contact you by electronic and paper mail.
+
+ If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source. For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code. There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+ You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+.
diff --git a/README.en.md b/README.en.md
deleted file mode 100644
index ce700d8..0000000
--- a/README.en.md
+++ /dev/null
@@ -1,463 +0,0 @@
-
-
-# 📍 Location Spoofer
-
-### iOS Location Service Research & Testing Framework
-
-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.
-
-> ⚠️ **Starting with iOS 27 beta 6, the system blocks MITM interception of `gs-loc.apple.com`.** This project is
-> temporarily unusable on that version and later betas until a workaround is found.
-
-[](project.yml)
-[](project.yml)
-[](Core/go.mod)
-[](docs/CHANGELOG.md)
-
-[Features](#feature-overview) ·
-[How It Works](#how-it-works) ·
-[Quick Start](#quick-start) ·
-[Build](#building-the-project) ·
-[中文](README.md)
-
-
-
-> [!IMPORTANT]
-> 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.
-
-## Project Scope
-
-Location Spoofer is a tool for studying iOS location-service behavior and testing location-dependent software.
-
-It provides:
-
-- 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.
-
-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.
-
-#### Configuration API and Client Integration
-
-The app does not upload coordinates to a project server. It sends the following GET request, which the third-party
-client must intercept locally on the device:
-
-```text
-https://gs-loc.apple.com/wloc-settings/save
-```
-
-| Action | Query parameters | Purpose |
-|---|---|---|
-| Query | `action=query` | Verify module connectivity and read the stored coordinate |
-| Save | `lon=&lat=&acc=` | Store the selected coordinate |
-| Clear | `action=clear` | Remove the stored test coordinate |
-
-The interception script must return HTTP 200 with JSON:
-
-```json
-{
- "success": true,
- "longitude": 113.0,
- "latitude": 22.0,
- "accuracy": 25
-}
-```
-
-Failures use:
-
-```json
-{
- "success": false,
- "error": "Error description"
-}
-```
-
-When no coordinate is stored, a query may return `{"success":false,"error":"无已保存的坐标"}`. The app interprets
-that response as “module connected, virtual location inactive.” A successful save response must echo the requested
-WGS-84 longitude and latitude.
-
-To integrate another third-party client:
-
-1. Add an HTTP request script for `gs-loc.apple.com/wloc-settings/save` that parses the parameters and returns the
- specified JSON;
-2. Store coordinates, accuracy, and optional state in the client's persistent storage;
-3. Enable HTTPS decryption for `gs-loc.apple.com` and `gs-loc-cn.apple.com`;
-4. Intercept `gs-loc(-cn).apple.com/clls/wloc` responses, read the same persistent data, and modify the WLOC response;
-5. Publish an importable module and verify query, save, clear, and location restoration on a real device.
-
-The app validates only the configuration endpoint's HTTP status, JSON shape, and coordinate round trip. It does not
-manage the third-party client's certificate, MITM, VPN, or proxy state.
-
-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 | Community configuration |
-|---|---|---|
-| Shadowrocket | Currently used for on-device testing | Built-in App guide |
-| Surge | Configuration provided, not fully verified | Contributions wanted |
-| Quantumult X | Configuration provided, not fully verified | Contributions wanted |
-| Loon | Configuration provided, not fully verified | Contributions wanted |
-| Stash | Configuration provided, not fully verified | Contributions wanted |
-| Egern | Uses the Surge module, not fully verified | Contributions wanted |
-
-Community configurations are reviewed by client. Accepted submissions are linked in this table with attribution unless
-the contributor requests anonymous inclusion.
-
-Modules and scripts are now hosted by this repository. The original
-`Yu9191/wloc` repository was deleted and remains attribution only, not a runtime dependency:
-
-- [Third-party module documentation](docs/THIRD_PARTY_MODULES.md)
-
-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
-
-You can use:
-
-- 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).
-
-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.
-
-#### Self-Signing Instructions
-
-Release assets are unsigned IPA files and must be installed on an iPhone with a self-signing tool:
-
-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.
-
-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.
-
-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.
-
-### 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
-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
-```
-
-## Building the Project
-
-Source builds require:
-
-- macOS;
-- Xcode;
-- Xcode Command Line Tools;
-- XcodeGen;
-- Go 1.23 or newer.
-
-Building the iOS app directly on Windows is not supported.
-
-```bash
-git clone https://github.com/xweiba/location-spoofer.git
-cd location-spoofer
-
-./build.sh
-```
-
-Build and run Simulator tests:
-
-```bash
-./build.sh --test
-```
-
-The build script generates an unsigned IPA:
-
-```text
-dist/PaopaoLocationSpoofer-unsigned.ipa
-```
-
-Deploy it to a test device using your own signing and installation process.
-
-## 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 module URLs hosted by this repository 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](https://github.com/xweiba/location-spoofer/issues/new?template=bug-report.yml);
-- [Feature requests](https://github.com/xweiba/location-spoofer/discussions/categories/%E5%8A%9F%E8%83%BD%E5%BB%BA%E8%AE%AE);
-- [Usage help and compatibility results](https://github.com/xweiba/location-spoofer/discussions/categories/%E4%BD%BF%E7%94%A8%E5%B8%AE%E5%8A%A9);
-- [Third-party client configurations and sanitized screenshots](https://github.com/xweiba/location-spoofer/discussions/categories/%E7%AC%AC%E4%B8%89%E6%96%B9%E9%85%8D%E7%BD%AE%E5%88%86%E4%BA%AB);
-- Performance improvements;
-- Documentation improvements;
-- Additional tests.
-
-For bugs, generate a report from **Settings → Support → Report Bug** in the App whenever possible. The report includes:
-
-- iOS version;
-- App version;
-- Runtime mode;
-- Selected third-party client;
-- Whether the issue is reproducible;
-- Problem description;
-- Sanitized runtime logs;
-
-Paste it into the **App-generated diagnostic report** field in the GitHub Issue Form.
-
-## Documentation
-
-- [Build guide](docs/BUILD.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)
-
-## Feature Preview
-
-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.
-
-
-
- | 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
-the following projects (`Yu9191/wloc` has since been deleted):
-
-- [Yu9191/wloc](https://github.com/Yu9191/wloc)
-- [ios-location-spoofer](https://github.com/mekos2772/ios-location-spoofer)
-
-Thanks to the following LINUX DO users for their contributions:
-
-- Bug fixes: [Chen Ze](https://linux.do/u/lixiaobaivv)
-- Ideas and suggestions: [Alex](https://linux.do/u/_alex), [ye4241](https://linux.do/u/ye4241)
-
-Links:
-
-- [LINUX DO](https://linux.do/)
-- [iOS-Location-Spoofer-Web](https://github.com/akudamatata/iOS-Location-Spoofer-Web)
-
-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 ad649a9..51c084a 100644
--- a/README.md
+++ b/README.md
@@ -4,149 +4,155 @@
### iOS Location Service Research & Testing Framework
-一个用于 **iOS 定位服务研究、软件开发测试和 QA 验证** 的开源项目。
+An open-source project for **iOS location-service research, software development testing, and QA validation**.
-项目通过本机代理或第三方代理客户端，对 Apple 定位服务的指定响应进行测试环境模拟，帮助开发者验证应用在
-不同地理位置和定位场景下的行为。
+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.
-> ⚠️ **iOS 27 beta 6 起，系统已禁止对 `gs-loc.apple.com` 进行 MITM 拦截。** 目前该版本及之后的 beta 版本暂时无法使用本项目，等待后续适配方案。
+> ⚠️ **Starting with iOS 27 beta 6, the system blocks MITM interception of `gs-loc.apple.com`.** This project is
+> temporarily unusable on that version and later betas until a workaround is found.
[](project.yml)
[](project.yml)
[](Core/go.mod)
[](docs/CHANGELOG.md)
-[功能概览](#功能概览) ·
-[工作原理](#工作原理) ·
-[快速开始](#快速开始) ·
-[构建项目](#构建项目) ·
-[English](README.en.md)
+[Features](#feature-overview) ·
+[How It Works](#how-it-works) ·
+[Quick Start](#quick-start) ·
+[Build](#building-the-project) ·
+[中文](README.zh-CN.md)
> [!IMPORTANT]
-> 本项目用于学习研究、自有设备测试、软件开发和 QA 验证。
+> 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.
>
-> 本项目不保证兼容所有 iOS 版本或第三方应用，也不承诺绕过第三方应用的安全策略、业务限制或服务规则。
+> 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.
-## 项目定位
+## Project Scope
-Location Spoofer 是一个面向 iOS 定位服务行为研究和开发测试的工具。
+Location Spoofer is a tool for studying iOS location-service behavior and testing location-dependent software.
-它提供：
+It provides:
-- 原生地图选点和位置场景切换；
-- Apple 定位服务响应的测试环境模拟；
-- 本地代理和第三方代理两种运行模式；
-- 坐标标准识别与 WGS-84 / GCJ-02 双坐标管理；
-- 环境检测、运行日志和问题诊断；
-- 收藏位置和上次地图状态恢复。
+- 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.
-项目不修改目标 App 的源代码，也不提供远程控制或数据采集服务。
+The project does not modify the target app's source code and does not provide telemetry, remote control, or data
+collection services.
-## 功能概览
+## Feature Overview
-- **原生地图交互**
- - 使用 MapKit 显示地图和系统蓝点；
- - 支持搜索、点击选点、拖动地图中心和缩放；
- - 支持收藏位置和恢复上次选点；
- - 当前选点同时显示国内坐标和国际坐标，可分别复制。
+- **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.
-- **定位服务响应模拟**
- - 通过代理层处理指定的 Apple 定位服务请求；
- - 在测试环境中返回选定的坐标数据；
- - 不需要修改目标 App 代码。
+- **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.
-- **双运行模式**
- - APP 模式：在设备内运行 Go 代理，仅支持当前 Wi-Fi 网络；
- - 第三方代理模式：通过支持的代理客户端覆盖 Wi-Fi、4G 或 5G，具体能力取决于客户端。
+- **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.
-- **环境检测**
- - APP 模式检测本地代理、证书信任和请求链路；
- - 第三方代理模式检测 WLOC 配置接口和模块响应；
- - 失败时提供对应的配置或诊断入口。
+- **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 模式
+### App Mode
-APP 模式在设备内运行本地 Go 代理，并通过当前 Wi-Fi 的手动 HTTP 代理让指定请求经过本地代理。
+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 定位请求
+iOS location request
│
- │ 当前 Wi-Fi 手动 HTTP 代理
+ │ Manual HTTP proxy on the current Wi-Fi
▼
-设备内 wloccore Go 代理
+On-device wloccore Go proxy
│
- │ 处理指定 Apple 定位服务请求
+ │ Handle selected Apple location-service requests
▼
-Apple 定位服务响应
+Apple location-service response
│
- │ 测试坐标响应
+ │ Test coordinate response
▼
-系统和应用读取定位结果
+The system and apps read the location result
```
-APP 模式：
+App Mode:
-- 不创建 Network Extension；
-- 不显示或占用系统 VPN；
-- 只覆盖当前 Wi-Fi 网络；
-- 需要配置当前 Wi-Fi 的手动 HTTP 代理；
-- 需要安装并信任 App 生成的本机 CA；
-- 代理只处理项目定义的 Apple 定位服务和环境验证请求，不是通用网络抓包工具。
+- 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
-第三方代理模式不启动 App 内置 Go 代理，也不使用 App 生成的 CA。
+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 坐标
+ │ WGS-84 coordinates
▼
-WLOC 配置接口
+WLOC configuration API
│
▼
-第三方代理客户端保存配置
+Third-party proxy client stores the configuration
│
▼
-第三方代理客户端处理定位服务请求
+Third-party client processes location-service requests
```
-在该模式下：
+In this mode:
-- App 负责地图选点、收藏、坐标同步和清除；
-- 第三方客户端负责代理/VPN、MITM、证书和规则执行；
-- 坐标持久化由第三方客户端负责；
-- 是否支持 Wi-Fi、4G 或 5G 取决于客户端；
-- App 关闭后，第三方客户端中的配置可能继续生效。
+- 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.
-#### 配置接口与客户端适配
+#### Configuration API and Client Integration
-App 不会把坐标上传到项目服务器。它会发起以下 GET 请求，第三方客户端必须在设备本地拦截：
+The app does not upload coordinates to a project server. It sends the following GET request, which the third-party
+client must intercept locally on the device:
```text
https://gs-loc.apple.com/wloc-settings/save
```
-| 操作 | 查询参数 | 用途 |
+| Action | Query parameters | Purpose |
|---|---|---|
-| 查询 | `action=query` | 检查模块是否连接，并读取当前保存的坐标 |
-| 保存 | `lon=&lat=&acc=<精度>` | 保存当前选点 |
-| 清除 | `action=clear` | 删除已保存的测试坐标 |
+| Query | `action=query` | Verify module connectivity and read the stored coordinate |
+| Save | `lon=&lat=&acc=` | Store the selected coordinate |
+| Clear | `action=clear` | Remove the stored test coordinate |
-拦截脚本必须返回 HTTP 200 和 JSON：
+The interception script must return HTTP 200 with JSON:
```json
{
@@ -157,170 +163,178 @@ https://gs-loc.apple.com/wloc-settings/save
}
```
-失败时返回：
+Failures use:
```json
{
"success": false,
- "error": "错误说明"
+ "error": "Error description"
}
```
-查询时没有已保存坐标，可以返回 `{"success":false,"error":"无已保存的坐标"}`。App 会把它识别为
-“模块已连接，但虚拟定位未开启”。保存成功时，响应中的经纬度必须与请求中的 WGS-84 坐标一致。
+When no coordinate is stored, a query may return `{"success":false,"error":"无已保存的坐标"}`. The app interprets
+that response as “module connected, virtual location inactive.” A successful save response must echo the requested
+WGS-84 longitude and latitude.
-要适配新的第三方客户端，需要：
+To integrate another third-party client:
-1. 为 `gs-loc.apple.com/wloc-settings/save` 添加 HTTP 请求脚本，解析上述参数并返回约定 JSON；
-2. 使用客户端的持久化存储保存坐标、精度和可选状态；
-3. 为 `gs-loc.apple.com` 和 `gs-loc-cn.apple.com` 配置 HTTPS 解密；
-4. 拦截 `gs-loc(-cn).apple.com/clls/wloc` 响应，读取同一份持久化数据并修改 WLOC 响应；
-5. 提供可订阅的模块文件，并确认查询、保存、清除和定位恢复都能在真机完成。
+1. Add an HTTP request script for `gs-loc.apple.com/wloc-settings/save` that parses the parameters and returns the
+ specified JSON;
+2. Store coordinates, accuracy, and optional state in the client's persistent storage;
+3. Enable HTTPS decryption for `gs-loc.apple.com` and `gs-loc-cn.apple.com`;
+4. Intercept `gs-loc(-cn).apple.com/clls/wloc` responses, read the same persistent data, and modify the WLOC response;
+5. Publish an importable module and verify query, save, clear, and location restoration on a real device.
-App 只验证配置接口的 HTTP 状态、JSON 格式和坐标回读，不管理第三方客户端的证书、MITM、VPN 或代理状态。
+The app validates only the configuration endpoint's HTTP status, JSON shape, and coordinate round trip. It does not
+manage the third-party client's certificate, MITM, VPN, or proxy state.
-不要同时启用 APP 模式代理和第三方代理模式，避免两个代理链路互相干扰。
+Do not enable App Mode interception and Third-party Proxy Mode interception at the same time.
-## 运行模式
+## Runtime Modes
-### APP 模式
+### App Mode
-适用于：
+Suitable for:
-- 只使用 Wi-Fi 的设备测试；
-- 不依赖第三方代理客户端的本地验证；
-- 需要在 App 内完成代理、证书和环境检测的场景。
+- Wi-Fi-only device testing;
+- Local testing without a third-party proxy client;
+- Workflows that need in-app proxy, certificate, and environment guidance.
-使用条件：
+Requirements:
-- iOS 设备；
-- 当前 Wi-Fi 支持手动 HTTP 代理；
-- 安装并信任本机 CA；
-- 在 App 内完成代理配置和环境检测。
+- 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:
-- 需要 Wi-Fi、4G 或 5G 网络覆盖的测试；
-- 已经使用支持模块或脚本的代理客户端；
-- 希望由第三方客户端继续保持代理配置的场景。
+- 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 | Community configuration |
|---|---|---|
-| Shadowrocket | 当前用于真机测试 | App 内置教程 |
-| Surge | 已提供配置，尚未完整验证 | 待征集 |
-| Quantumult X | 已提供配置，尚未完整验证 | 待征集 |
-| Loon | 已提供配置，尚未完整验证 | 待征集 |
-| Stash | 已提供配置，尚未完整验证 | 待征集 |
-| Egern | 使用 Surge 模块，尚未完整验证 | 待征集 |
+| Shadowrocket | Currently used for on-device testing | Built-in App guide |
+| Surge | Configuration provided, not fully verified | Contributions wanted |
+| Quantumult X | Configuration provided, not fully verified | Contributions wanted |
+| Loon | Configuration provided, not fully verified | Contributions wanted |
+| Stash | Configuration provided, not fully verified | Contributions wanted |
+| Egern | Uses the Surge module, not fully verified | Contributions wanted |
-社区配置按客户端分区审核；采纳后会在上表链接教程和投稿者，投稿者也可以选择匿名收录。
+Community configurations are reviewed by client. Accepted submissions are linked in this table with attribution unless
+the contributor requests anonymous inclusion.
-模块与脚本现由本仓库托管，原 `Yu9191/wloc` 仓库已删除，仅保留来源致谢，不再作为运行时依赖：
+Modules and scripts are now hosted by this repository. The original
+`Yu9191/wloc` repository was deleted and remains attribution only, not a runtime dependency:
-- [第三方模块说明](docs/THIRD_PARTY_MODULES.md)
+- [Third-party module documentation](docs/THIRD_PARTY_MODULES.md)
-第三方客户端、证书、MITM 和代理开关由客户端自身负责。导入任何第三方模块前，请先审查其配置和脚本内容。
+The selected client owns its certificates, MITM configuration, and proxy switches. Review third-party modules and
+scripts before importing them.
-## 快速开始
+## Quick Start
-### 1. 安装应用
+### 1. Install the App
-你可以使用：
+You can use:
-- 自己的 Apple Developer 签名环境；
-- 适合个人测试的自签工具；
-- 项目 Releases 中的未签名 IPA；
-- 在 macOS 上按[构建说明](docs/BUILD.md)自行构建。
+- 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).
-免费自签环境可能无法使用 Network Extension，因此 APP 模式采用设备内本地代理和 Wi-Fi 手动代理，不依赖
-VPN 组件。
+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.
-#### 自签安装说明
+#### Self-Signing Instructions
-Release 附件是未签名 IPA，需要使用自签工具安装到 iPhone：
+Release assets are unsigned IPA files and must be installed on an iPhone with a self-signing tool:
-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，根据软件提示完成签名与安装。
+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.
-Impactor 支持 Windows、macOS 和 Linux；Windows 若无法识别设备，请先安装 iTunes 提供的 Apple 设备驱动。
-爱思助手属于第三方软件，请从其官方渠道获取，并自行评估账号、证书和隐私风险。
+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.
-安装完成后，若 iOS 阻止打开 App，请前往“设置 → 通用 → VPN 与设备管理”信任对应的开发者 App。免费
-Apple ID 自签通常只有 7 天有效期，到期后需要重新签名安装。
+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.
-### 2. 首次启动
+### 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.
-1. 选择 APP 模式或第三方代理模式；
-2. 按照 App 内引导完成对应配置；
-3. 执行环境检测；
-4. 在地图中搜索、点击或拖动选择测试位置；
-5. 启用测试位置并在目标测试环境中验证结果。
+### 3. Restore the Real Location
-### 3. 恢复真实位置
+App Mode:
-APP 模式：
+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.
-1. 停止测试位置；
-2. 关闭当前 Wi-Fi 的手动 HTTP 代理；
-3. 按 App 内提示刷新定位环境。
+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.
-1. 使用 App 清除 WLOC 坐标；
-2. 在第三方客户端中关闭对应模块或代理；
-3. 按客户端要求恢复 HTTPS 解密和代理设置。
+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.
-- WGS-84：国际标准，WLOC 写入使用此坐标；
-- GCJ-02：国内地图标准，用于需要国内地图坐标的场景。
+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.
-MapKit 不提供公开 API 直接返回当前是否使用 GCJ-02 或 WGS-84。项目通过固定锚点查询判断 MapKit 当前返回
-标准，并在运行期间根据蓝点变化和用户操作进行受控刷新。
+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.
-坐标写入边界会保存完整的 WGS-84 / GCJ-02 坐标对，使用时根据当前地图标准选择对应字段，避免重复转换造成
-位置偏移。
-
-## 项目结构
+## Project Structure
```text
-App/ SwiftUI 界面、MapKit、定位和运行流程
-Core/ Go 代理、证书服务和定位响应处理
-Shared/ 坐标、收藏、日志、配置和共享模型
-Resources/ Info.plist、Entitlements 和资源文件
-Config/ 构建配置
-Scripts/ 构建、打包和验证脚本
-Tests/ XCTest 和 Shell contract tests
-docs/ 构建、模块和版本文档
+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
```
-## 构建项目
+## Building the Project
-源码构建需要 macOS 环境：
+Source builds require:
-- macOS；
-- Xcode；
-- Xcode Command Line Tools；
-- XcodeGen；
-- Go 1.23 或更高版本。
+- macOS;
+- Xcode;
+- Xcode Command Line Tools;
+- XcodeGen;
+- Go 1.23 or newer.
-当前项目不支持在 Windows 上直接构建 iOS 应用。
+Building the iOS app directly on Windows is not supported.
```bash
git clone https://github.com/xweiba/location-spoofer.git
@@ -329,119 +343,128 @@ cd location-spoofer
./build.sh
```
-运行构建并执行 Simulator 测试：
+Build and run Simulator tests:
```bash
./build.sh --test
```
-构建脚本会生成未签名 IPA：
+The build script generates an unsigned IPA:
```text
dist/PaopaoLocationSpoofer-unsigned.ipa
```
-之后需要使用你自己的签名和安装流程部署到测试设备。
+Deploy it to a test device using your own signing and installation process.
-## 隐私与安全边界
+## Privacy and Security Boundaries
-- 项目不包含遥测或远程控制服务；
-- 项目不会自动上传用户位置数据；
-- 运行日志保存在设备 App Group 容器中，并自动保留近三天；
-- 问题报告需要用户主动复制后提交到 GitHub；
-- APP 模式会访问本机代理和环境验证地址；
-- 第三方代理模式可能访问本仓库托管的模块地址和 WLOC 配置接口；
-- App 生成的 CA 私钥保存在设备 Keychain 中；
-- 第三方客户端模块、MITM 和证书链路由用户选择的客户端负责。
+- 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 module URLs hosted by this repository 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.
-请不要把真实位置、认证信息、证书私钥或完整敏感日志提交到公开 Issue。
+Do not post real locations, authentication information, CA private keys, or complete sensitive logs in public issues.
-## 限制
+## Limitations
-- iOS 系统版本变化可能影响定位服务行为；
-- MapKit 的坐标返回标准可能随系统、地区和定位环境变化；
-- 系统定位存在缓存，切换位置后不一定立即生效；
-- 第三方代理客户端的兼容性和规则行为需要分别验证；
-- 不保证所有应用都使用同一种定位 API；
-- 不保证所有应用或服务都接受测试坐标；
-- 不保证在所有网络环境、设备型号和 iOS 版本上表现一致。
+- 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.
-## 贡献
+## License
-欢迎提交：
+The project code is distributed under the [GNU Affero General Public License v3.0](LICENSE).
+Third-party WLOC scripts retain their original copyright notices and AGPL-3.0 license in
+[`ThirdParty/WlocScripts/`](ThirdParty/WlocScripts/THIRD_PARTY_NOTICES.md).
+Other third-party dependencies remain subject to their respective licenses.
-- [Bug Report](https://github.com/xweiba/location-spoofer/issues/new?template=bug-report.yml)；
-- [功能建议](https://github.com/xweiba/location-spoofer/discussions/categories/%E5%8A%9F%E8%83%BD%E5%BB%BA%E8%AE%AE)；
-- [使用帮助与兼容性测试](https://github.com/xweiba/location-spoofer/discussions/categories/%E4%BD%BF%E7%94%A8%E5%B8%AE%E5%8A%A9)；
-- [第三方客户端配置和脱敏原始截图](https://github.com/xweiba/location-spoofer/discussions/categories/%E7%AC%AC%E4%B8%89%E6%96%B9%E9%85%8D%E7%BD%AE%E5%88%86%E4%BA%AB)；
-- 性能改进；
-- 文档改进；
-- 测试补充。
+## Contributing
-提交 Bug 时建议优先通过 App 的“设置 → 支持 → 报告 Bug”生成报告。报告包含：
+Contributions are welcome for:
-- iOS 版本；
-- App 版本；
-- 使用的运行模式；
-- 当前第三方客户端；
-- 是否可以稳定复现；
-- 问题描述；
-- 脱敏后的运行日志；
+- [Bug reports](https://github.com/xweiba/location-spoofer/issues/new?template=bug-report.yml);
+- [Feature requests](https://github.com/xweiba/location-spoofer/discussions/categories/%E5%8A%9F%E8%83%BD%E5%BB%BA%E8%AE%AE);
+- [Usage help and compatibility results](https://github.com/xweiba/location-spoofer/discussions/categories/%E4%BD%BF%E7%94%A8%E5%B8%AE%E5%8A%A9);
+- [Third-party client configurations and sanitized screenshots](https://github.com/xweiba/location-spoofer/discussions/categories/%E7%AC%AC%E4%B8%89%E6%96%B9%E9%85%8D%E7%BD%AE%E5%88%86%E4%BA%AB);
+- Performance improvements;
+- Documentation improvements;
+- Additional tests.
-GitHub Issue Form 中的“App 生成的诊断报告”字段与 App 复制内容一一对应。
+For bugs, generate a report from **Settings → Support → Report Bug** in the App whenever possible. The report includes:
-## 文档
+- iOS version;
+- App version;
+- Runtime mode;
+- Selected third-party client;
+- Whether the issue is reproducible;
+- Problem description;
+- Sanitized runtime logs;
-- [构建说明](docs/BUILD.md)
-- [第三方模块说明](docs/THIRD_PARTY_MODULES.md)
-- [社区客户端教程与截图提交](docs/COMMUNITY_TUTORIALS.md)
-- [更新日志](docs/CHANGELOG.md)
-- [英文文档](README.en.md)
+Paste it into the **App-generated diagnostic report** field in the GitHub Issue Form.
+
+## Documentation
+
+- [Build guide](docs/BUILD.md)
+- [Third-party module documentation](docs/THIRD_PARTY_MODULES.md)
+- [Changelog](docs/CHANGELOG.md)
+- [中文文档](README.zh-CN.md)
- [GitHub Issues](https://github.com/xweiba/location-spoofer/issues)
-## 功能预览
+## Feature Preview
-以下截图用于展示主界面和部分真机测试场景。实际结果会受到 iOS 版本、网络环境、系统缓存和目标应用定位策略
-影响，不代表对所有应用或版本作出兼容性保证。
+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.
- | 应用主界面 |
- Apple 地图测试 |
- 高德地图测试 |
+ Main interface |
+ Apple Maps test |
+ Amap test |
- |
- |
- |
+ |
+ |
+ |
- | 微信测试 |
- 钉钉测试 |
- Apple Watch 场景测试 |
+ WeChat test |
+ DingTalk test |
+ Apple Watch scenario test |
- |
- |
- |
+ |
+ |
+ |
-## 致谢与友链
+## Acknowledgements and Links
-核心定位响应处理思路、Go 实现和第三方模块参考自（`Yu9191/wloc` 原仓库已删除）：
+The core location-response handling approach, Go implementation, and third-party modules are based on
+the following projects (`Yu9191/wloc` has since been deleted):
- [Yu9191/wloc](https://github.com/Yu9191/wloc)
- [ios-location-spoofer](https://github.com/mekos2772/ios-location-spoofer)
-感谢以下 LINUX DO 用户对项目的贡献：
+Thanks to the following LINUX DO users for their contributions:
-- 功能修复：[陈泽](https://linux.do/u/lixiaobaivv)
-- 思路及建议：[Alex](https://linux.do/u/_alex)、[ye4241](https://linux.do/u/ye4241)
+- Bug fixes: [Chen Ze](https://linux.do/u/lixiaobaivv)
+- Ideas and suggestions: [Alex](https://linux.do/u/_alex), [ye4241](https://linux.do/u/ye4241)
-友链：
+Links:
- [LINUX DO](https://linux.do/)
- [iOS-Location-Spoofer-Web](https://github.com/akudamatata/iOS-Location-Spoofer-Web)
-感谢开源社区中参与 iOS 定位服务研究、网络代理和移动端测试工具建设的贡献者。
+Thanks to the open-source contributors working on iOS location-service research, network proxies, and mobile testing
+tools.
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..ba1d0e0
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,454 @@
+
+
+# 📍 Location Spoofer
+
+### iOS Location Service Research & Testing Framework
+
+一个用于 **iOS 定位服务研究、软件开发测试和 QA 验证** 的开源项目。
+
+项目通过本机代理或第三方代理客户端，对 Apple 定位服务的指定响应进行测试环境模拟，帮助开发者验证应用在
+不同地理位置和定位场景下的行为。
+
+> ⚠️ **iOS 27 beta 6 起，系统已禁止对 `gs-loc.apple.com` 进行 MITM 拦截。** 目前该版本及之后的 beta 版本暂时无法使用本项目，等待后续适配方案。
+
+[](project.yml)
+[](project.yml)
+[](Core/go.mod)
+[](docs/CHANGELOG.md)
+
+[功能概览](#功能概览) ·
+[工作原理](#工作原理) ·
+[快速开始](#快速开始) ·
+[构建项目](#构建项目) ·
+[English](README.md)
+
+
+
+> [!IMPORTANT]
+> 本项目用于学习研究、自有设备测试、软件开发和 QA 验证。
+>
+> 请仅在你拥有或获得授权的设备、网络和软件环境中使用，并遵守当地法律法规、网络管理规定以及相关服务条
+> 款。
+>
+> 本项目不保证兼容所有 iOS 版本或第三方应用，也不承诺绕过第三方应用的安全策略、业务限制或服务规则。
+
+## 项目定位
+
+Location Spoofer 是一个面向 iOS 定位服务行为研究和开发测试的工具。
+
+它提供：
+
+- 原生地图选点和位置场景切换；
+- Apple 定位服务响应的测试环境模拟；
+- 本地代理和第三方代理两种运行模式；
+- 坐标标准识别与 WGS-84 / GCJ-02 双坐标管理；
+- 环境检测、运行日志和问题诊断；
+- 收藏位置和上次地图状态恢复。
+
+项目不修改目标 App 的源代码，也不提供远程控制或数据采集服务。
+
+## 功能概览
+
+- **原生地图交互**
+ - 使用 MapKit 显示地图和系统蓝点；
+ - 支持搜索、点击选点、拖动地图中心和缩放；
+ - 支持收藏位置和恢复上次选点；
+ - 当前选点同时显示国内坐标和国际坐标，可分别复制。
+
+- **定位服务响应模拟**
+ - 通过代理层处理指定的 Apple 定位服务请求；
+ - 在测试环境中返回选定的坐标数据；
+ - 不需要修改目标 App 代码。
+
+- **双运行模式**
+ - APP 模式：在设备内运行 Go 代理，仅支持当前 Wi-Fi 网络；
+ - 第三方代理模式：通过支持的代理客户端覆盖 Wi-Fi、4G 或 5G，具体能力取决于客户端。
+
+- **环境检测**
+ - APP 模式检测本地代理、证书信任和请求链路；
+ - 第三方代理模式检测 WLOC 配置接口和模块响应；
+ - 失败时提供对应的配置或诊断入口。
+
+- **开发调试**
+ - 运行日志；
+ - 日志复制和清理；
+ - 坐标标准变化记录；
+ - 脱敏问题报告生成。
+
+## 工作原理
+
+### APP 模式
+
+APP 模式在设备内运行本地 Go 代理，并通过当前 Wi-Fi 的手动 HTTP 代理让指定请求经过本地代理。
+
+```text
+iOS 定位请求
+ │
+ │ 当前 Wi-Fi 手动 HTTP 代理
+ ▼
+设备内 wloccore Go 代理
+ │
+ │ 处理指定 Apple 定位服务请求
+ ▼
+Apple 定位服务响应
+ │
+ │ 测试坐标响应
+ ▼
+系统和应用读取定位结果
+```
+
+APP 模式：
+
+- 不创建 Network Extension；
+- 不显示或占用系统 VPN；
+- 只覆盖当前 Wi-Fi 网络；
+- 需要配置当前 Wi-Fi 的手动 HTTP 代理；
+- 需要安装并信任 App 生成的本机 CA；
+- 代理只处理项目定义的 Apple 定位服务和环境验证请求，不是通用网络抓包工具。
+
+### 第三方代理模式
+
+第三方代理模式不启动 App 内置 Go 代理，也不使用 App 生成的 CA。
+
+```text
+地图选点
+ │
+ │ WGS-84 坐标
+ ▼
+WLOC 配置接口
+ │
+ ▼
+第三方代理客户端保存配置
+ │
+ ▼
+第三方代理客户端处理定位服务请求
+```
+
+在该模式下：
+
+- App 负责地图选点、收藏、坐标同步和清除；
+- 第三方客户端负责代理/VPN、MITM、证书和规则执行；
+- 坐标持久化由第三方客户端负责；
+- 是否支持 Wi-Fi、4G 或 5G 取决于客户端；
+- App 关闭后，第三方客户端中的配置可能继续生效。
+
+#### 配置接口与客户端适配
+
+App 不会把坐标上传到项目服务器。它会发起以下 GET 请求，第三方客户端必须在设备本地拦截：
+
+```text
+https://gs-loc.apple.com/wloc-settings/save
+```
+
+| 操作 | 查询参数 | 用途 |
+|---|---|---|
+| 查询 | `action=query` | 检查模块是否连接，并读取当前保存的坐标 |
+| 保存 | `lon=&lat=&acc=<精度>` | 保存当前选点 |
+| 清除 | `action=clear` | 删除已保存的测试坐标 |
+
+拦截脚本必须返回 HTTP 200 和 JSON：
+
+```json
+{
+ "success": true,
+ "longitude": 113.0,
+ "latitude": 22.0,
+ "accuracy": 25
+}
+```
+
+失败时返回：
+
+```json
+{
+ "success": false,
+ "error": "错误说明"
+}
+```
+
+查询时没有已保存坐标，可以返回 `{"success":false,"error":"无已保存的坐标"}`。App 会把它识别为
+“模块已连接，但虚拟定位未开启”。保存成功时，响应中的经纬度必须与请求中的 WGS-84 坐标一致。
+
+要适配新的第三方客户端，需要：
+
+1. 为 `gs-loc.apple.com/wloc-settings/save` 添加 HTTP 请求脚本，解析上述参数并返回约定 JSON；
+2. 使用客户端的持久化存储保存坐标、精度和可选状态；
+3. 为 `gs-loc.apple.com` 和 `gs-loc-cn.apple.com` 配置 HTTPS 解密；
+4. 拦截 `gs-loc(-cn).apple.com/clls/wloc` 响应，读取同一份持久化数据并修改 WLOC 响应；
+5. 提供可订阅的模块文件，并确认查询、保存、清除和定位恢复都能在真机完成。
+
+App 只验证配置接口的 HTTP 状态、JSON 格式和坐标回读，不管理第三方客户端的证书、MITM、VPN 或代理状态。
+
+不要同时启用 APP 模式代理和第三方代理模式，避免两个代理链路互相干扰。
+
+## 运行模式
+
+### APP 模式
+
+适用于：
+
+- 只使用 Wi-Fi 的设备测试；
+- 不依赖第三方代理客户端的本地验证；
+- 需要在 App 内完成代理、证书和环境检测的场景。
+
+使用条件：
+
+- iOS 设备；
+- 当前 Wi-Fi 支持手动 HTTP 代理；
+- 安装并信任本机 CA；
+- 在 App 内完成代理配置和环境检测。
+
+### 第三方代理模式
+
+适用于：
+
+- 需要 Wi-Fi、4G 或 5G 网络覆盖的测试；
+- 已经使用支持模块或脚本的代理客户端；
+- 希望由第三方客户端继续保持代理配置的场景。
+
+当前客户端状态：
+
+| 客户端 | 状态 | 社区配置 |
+|---|---|---|
+| Shadowrocket | 当前用于真机测试 | App 内置教程 |
+| Surge | 已提供配置，尚未完整验证 | 待征集 |
+| Quantumult X | 已提供配置，尚未完整验证 | 待征集 |
+| Loon | 已提供配置，尚未完整验证 | 待征集 |
+| Stash | 已提供配置，尚未完整验证 | 待征集 |
+| Egern | 使用 Surge 模块，尚未完整验证 | 待征集 |
+
+社区配置按客户端分区审核；采纳后会在上表链接教程和投稿者，投稿者也可以选择匿名收录。
+
+模块与脚本现由本仓库托管，原 `Yu9191/wloc` 仓库已删除，仅保留来源致谢，不再作为运行时依赖：
+
+- [第三方模块说明](docs/THIRD_PARTY_MODULES.md)
+
+第三方客户端、证书、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
+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
+```
+
+之后需要使用你自己的签名和安装流程部署到测试设备。
+
+## 隐私与安全边界
+
+- 项目不包含遥测或远程控制服务；
+- 项目不会自动上传用户位置数据；
+- 运行日志保存在设备 App Group 容器中，并自动保留近三天；
+- 问题报告需要用户主动复制后提交到 GitHub；
+- APP 模式会访问本机代理和环境验证地址；
+- 第三方代理模式可能访问本仓库托管的模块地址和 WLOC 配置接口；
+- App 生成的 CA 私钥保存在设备 Keychain 中；
+- 第三方客户端模块、MITM 和证书链路由用户选择的客户端负责。
+
+请不要把真实位置、认证信息、证书私钥或完整敏感日志提交到公开 Issue。
+
+## 限制
+
+- iOS 系统版本变化可能影响定位服务行为；
+- MapKit 的坐标返回标准可能随系统、地区和定位环境变化；
+- 系统定位存在缓存，切换位置后不一定立即生效；
+- 第三方代理客户端的兼容性和规则行为需要分别验证；
+- 不保证所有应用都使用同一种定位 API；
+- 不保证所有应用或服务都接受测试坐标；
+- 不保证在所有网络环境、设备型号和 iOS 版本上表现一致。
+
+## 许可证
+
+项目代码采用 [GNU Affero General Public License v3.0](LICENSE) 授权。
+第三方 WLOC 脚本保留原作者版权声明及其 AGPL-3.0 许可，详情见
+[`ThirdParty/WlocScripts/`](ThirdParty/WlocScripts/THIRD_PARTY_NOTICES.md)。
+其他第三方依赖仍遵循各自的许可证。
+
+## 贡献
+
+欢迎提交：
+
+- [Bug Report](https://github.com/xweiba/location-spoofer/issues/new?template=bug-report.yml)；
+- [功能建议](https://github.com/xweiba/location-spoofer/discussions/categories/%E5%8A%9F%E8%83%BD%E5%BB%BA%E8%AE%AE)；
+- [使用帮助与兼容性测试](https://github.com/xweiba/location-spoofer/discussions/categories/%E4%BD%BF%E7%94%A8%E5%B8%AE%E5%8A%A9)；
+- [第三方客户端配置和脱敏原始截图](https://github.com/xweiba/location-spoofer/discussions/categories/%E7%AC%AC%E4%B8%89%E6%96%B9%E9%85%8D%E7%BD%AE%E5%88%86%E4%BA%AB)；
+- 性能改进；
+- 文档改进；
+- 测试补充。
+
+提交 Bug 时建议优先通过 App 的“设置 → 支持 → 报告 Bug”生成报告。报告包含：
+
+- iOS 版本；
+- App 版本；
+- 使用的运行模式；
+- 当前第三方客户端；
+- 是否可以稳定复现；
+- 问题描述；
+- 脱敏后的运行日志；
+
+GitHub Issue Form 中的“App 生成的诊断报告”字段与 App 复制内容一一对应。
+
+## 文档
+
+- [构建说明](docs/BUILD.md)
+- [第三方模块说明](docs/THIRD_PARTY_MODULES.md)
+- [社区客户端教程与截图提交](docs/COMMUNITY_TUTORIALS.md)
+- [更新日志](docs/CHANGELOG.md)
+- [英文文档](README.md)
+- [GitHub Issues](https://github.com/xweiba/location-spoofer/issues)
+
+## 功能预览
+
+以下截图用于展示主界面和部分真机测试场景。实际结果会受到 iOS 版本、网络环境、系统缓存和目标应用定位策略
+影响，不代表对所有应用或版本作出兼容性保证。
+
+
+
+ | 应用主界面 |
+ Apple 地图测试 |
+ 高德地图测试 |
+
+
+ |
+ |
+ |
+
+
+ | 微信测试 |
+ 钉钉测试 |
+ Apple Watch 场景测试 |
+
+
+ |
+ |
+ |
+
+
+
+## 致谢与友链
+
+核心定位响应处理思路、Go 实现和第三方模块参考自（`Yu9191/wloc` 原仓库已删除）：
+
+- [Yu9191/wloc](https://github.com/Yu9191/wloc)
+- [ios-location-spoofer](https://github.com/mekos2772/ios-location-spoofer)
+
+感谢以下 LINUX DO 用户对项目的贡献：
+
+- 功能修复：[陈泽](https://linux.do/u/lixiaobaivv)
+- 思路及建议：[Alex](https://linux.do/u/_alex)、[ye4241](https://linux.do/u/ye4241)
+
+友链：
+
+- [LINUX DO](https://linux.do/)
+- [iOS-Location-Spoofer-Web](https://github.com/akudamatata/iOS-Location-Spoofer-Web)
+
+感谢开源社区中参与 iOS 定位服务研究、网络代理和移动端测试工具建设的贡献者。
diff --git a/Tests/readme_contract_test.sh b/Tests/readme_contract_test.sh
index 0987e2a..fede18d 100755
--- a/Tests/readme_contract_test.sh
+++ b/Tests/readme_contract_test.sh
@@ -2,8 +2,8 @@
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-ZH="$ROOT/README.md"
-EN="$ROOT/README.en.md"
+ZH="$ROOT/README.zh-CN.md"
+EN="$ROOT/README.md"
fail() { echo "FAIL: $*" >&2; exit 1; }
grep -q 'iOS Location Service Research & Testing Framework' "$ZH" || fail "Chinese README positioning is missing"
@@ -49,7 +49,14 @@ 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"
+test -s "$ROOT/LICENSE" || fail "root AGPL-3.0 license is missing"
+grep -q "GNU AFFERO GENERAL PUBLIC LICENSE" "$ROOT/LICENSE" || fail "root license must be AGPL-3.0"
+grep -q '^## 许可证$' "$ZH" || fail "Chinese README license section is missing"
+grep -q '^## License$' "$EN" || fail "English README license section is missing"
+grep -q 'ThirdParty/WlocScripts/THIRD_PARTY_NOTICES.md' "$ZH" || fail "Chinese README must retain third-party provenance"
+grep -q 'ThirdParty/WlocScripts/THIRD_PARTY_NOTICES.md' "$EN" || fail "English README must retain third-party provenance"
+grep -q 'README.zh-CN.md' "$EN" || fail "English README must link Chinese translation"
+grep -q 'README.md' "$ZH" || fail "Chinese README must link English default"
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"
grep -q 'docs/COMMUNITY_TUTORIALS.md' "$ZH" || fail "Chinese README must link the community tutorial submission guide"
@@ -70,7 +77,7 @@ grep -q '不得覆盖上述原图' "$ROOT/docs/COMMUNITY_TUTORIALS.md" \
|| fail "annotated app assets must not replace categorized source screenshots"
if grep -Rnw --include='*.md' --include='*.sh' \
- "$ROOT/build.sh" "$ROOT/README.md" "$ROOT/README.en.md" "$ROOT/docs" "$ROOT/Scripts" \
+ "$ROOT/build.sh" "$ROOT/README.md" "$ROOT/README.zh-CN.md" "$ROOT/docs" "$ROOT/Scripts" \
-e 'Impact'; then
fail "documentation and build output must use the correct Impactor name"
fi
diff --git a/Tests/update_and_contribution_contract_test.sh b/Tests/update_and_contribution_contract_test.sh
index e821c19..afd0054 100644
--- a/Tests/update_and_contribution_contract_test.sh
+++ b/Tests/update_and_contribution_contract_test.sh
@@ -39,8 +39,8 @@ grep -Fq "latestVersion: \"$LATEST_VERSION\"" "$CONFIG" \
|| fail "Shared/AppRemoteConfiguration.swift fallback latestVersion must match version.txt ($LATEST_VERSION)"
grep -Fq "version-v$LATEST_VERSION" "$ROOT/README.md" \
|| fail "README.md version badge must match version.txt ($LATEST_VERSION)"
-grep -Fq "version-v$LATEST_VERSION" "$ROOT/README.en.md" \
- || fail "README.en.md version badge must match version.txt ($LATEST_VERSION)"
+grep -Fq "version-v$LATEST_VERSION" "$ROOT/README.zh-CN.md" \
+ || fail "README.zh-CN.md version badge must match version.txt ($LATEST_VERSION)"
grep -q 'static let fallback = AppRemoteConfiguration' "$CONFIG" \
|| fail "the app must ship a built-in remote-configuration fallback"