| 模式 | 說明 | | --- | --- | | 瞬移 | 直接跳到指定座標 | | 導航 | 從目前位置沿實際道路以走路、腳踏車或開車的速度前往目的地 | | 多點路徑 | 依序經過多個路徑點,每站可停留(預設隨機 5 到 20 秒)。圈數設 0 為跑一趟,設 N 為繞 N 圈,留空為無限循環 | | 花農專用 | 在每個路徑點周圍繞圈。繞圈距離、每圈段數(3 到 20)、每點圈數(0.5 為半圈)、總輪數、每點前後等待都可以自訂並保存,點與點之間可走過去或瞬移。面板會即時顯示整趟預估時間,斷線會自動重連續跑 | | 隨機漫步 | 在指定半徑內隨機漫遊,每段停頓時間可調 | | 搖桿 | 以方向和力度即時操控,支援 WASD 與方向鍵 |

多點路徑可以勾選「點對點跳躍」,改成逐點瞬移而不走道路,適合只需要 GPS 依序停在每個點上的情況。跳躍前延遲(預設 2 秒)與跳躍後延遲(預設 4 秒)都可以調整,暫停時兩段延遲都會凍結。

• 三檔預設:走路 10.8、腳踏車 19.8、開車 60 km/h。
• 可輸入任意固定速度,或輸入最小到最大的隨機範圍(例如 40 到 80 km/h),每段路重新抽一次,模擬真實路況。
• 移動進行中可以修改速度後按「套用新速度」,會從目前位置以新速度接續,不用停下重來。
• 選過的速度會記住,下次開啟沿用。到點暫停時地圖上方會顯示倒數。

導航與多點路徑使用的道路路線,可以在四個免費、免註冊的路徑引擎之間切換:

| 引擎 | 說明 | | --- | --- | | OSRM 公用 demo(預設) | 全球涵蓋,偶爾整個服務會中斷 | | OSRM FOSSGIS | 同樣是 OSRM 引擎,由 FOSSGIS 代管的鏡像 | | Valhalla | 完全不同的引擎,兩個 OSRM 節點都中斷時最有用 | | BRouter | 獨立營運的第四個引擎,單車、健行、開車 profile 齊全 |

任何引擎失敗時,該段路自動改走直線,下一段再重試,不會卡住。也可以直接勾選「使用直線路徑」完全不查詢引擎。多點路徑另有「最佳順序」功能,一鍵算出最短的走訪順序。

• USB:插上自動連線,iPhone 鎖定螢幕不受影響。拔除約 4 秒內偵測到,重新插上自動恢復,不用重新整理。
• WiFi Tunnel(iOS 17+,需先用 USB 配對過一次):

可同時連接最多三台裝置。瞬移、導航、各種移動模式、暫停、繼續、停止、套用速度、還原,都會同步送到所有裝置,桌面與手機網頁操控都適用。

• 啟動任何動作前,會先把所有裝置瞬移到同一個座標,確保路徑一致。
• 隨機漫步使用相同的亂數種子,所有裝置走的路線完全相同。
• 後來才接上的裝置,會自動同步到目前位置並接續正在執行的任務。
• 每台裝置可以個別還原、中斷或開啟開發者模式選項。

• 圖層切換(右上角):OSM、Google 圖磚(測試)、ESRI 街道、ESRI 衛星、OpenFreeMap Liberty / Bright / Positron(向量圖)、VersaTiles Colorful、NLSC 台灣電子地圖、GSI 日本地理院地圖。全部免 API key。
• 路徑點以 S / 1 / 2 / 3 標示,路徑線有流動箭頭可以看出方向。
• 左上角按鈕可一鍵置中目前的模擬位置。選「只顯示路徑」時地圖會自動縮放到整條路線。
• 地圖上的使用者圖示可以換成內建的 6 組角色,或上傳自己的 PNG(自動去除透明邊界)。
• 座標格式(設定頁):座標系統可選 WGS84 / CGCS2000(預設)、GCJ02(高德、騰訊)、BD09(百度),經緯度順序可選緯度在前或經度在前。設定套用於座標的顯示、複製與輸入,手機網頁操控同步套用;地圖、已儲存的座標與路線、GPX 與備份檔一律維持 WGS84。GCJ02 只在中國大陸與港澳有偏移,BD09 另外包含台灣,其他地區等同 WGS84。

上方導覽列的「收藏」會開啟一個可拖曳的浮動視窗,分成「座標」與「路線」兩個分頁,操作方式相同:

• 搜尋框固定在最上方。單擊座標即移動 GPS,單擊路線即載入。
• 在項目上按右鍵,或按每列右側的「⋯」,會出現同一份選單:重新命名、編輯、複製、匯出、移動到分類、刪除。分類標題同樣可以按右鍵改名、換顏色、匯出或刪除。
• 按住 Ctrl 或 Shift 點擊可以一次選取多個,再一起移動或刪除。
• 直接拖曳項目即可調整順序,拖到另一個分類上就是移過去;分類本身也能拖曳排序。
• 排序可選手動、名稱、新增時間、最後使用(路線為更新時間)。

• 「新增」可以儲存目前位置、輸入座標新增、批次貼上多筆座標,或從檔案匯入。新增時自動帶入國旗。
• 刪除座標後視窗下方會出現「復原」。
• 匯入與匯出:JSON(全部資料,匯入為合併不覆蓋)、GPX(單筆、整個分類,或多個分類一次匯出成 ZIP)。
• 可把所有座標顯示在地圖上,數萬筆也不會卡頓,密集的點會自動聚合。
• 「點擊座標時移動 GPS」關閉後,單擊座標只會把地圖畫面移過去,不會移動 GPS。

• 「新增」可以把地圖上目前的路線存起來;同名時可選擇覆蓋或另存。
• 支援 GPX 與 JSON 的匯入匯出。
• 可以把路徑點依目前順序複製成一行一筆的座標文字。

在地圖上顯示 pipimushroom.com 的蘑菇、花與煙霧點位(目前涵蓋台灣、香港、馬來西亞)。按地圖左側工具列的蘑菇按鈕就會開啟面板;面板可以拖曳標題移動,也可以收起只留標題。

• 蘑菇、花、煙霧三種點位可以分別開關。
• 蘑菇篩選(點開展開):依大小、種類與最少剩餘時間篩選,選項取自已載入的資料,每組都有全選與全不選。
• 花可以「只顯示彩帶」或隱藏普花。彩帶花會有彩虹外框,並顯示彩帶期剩餘時間。
• 點位標記有小、中、大三種大小。點開標記可以看到剩餘時間,並直接瞬移或導航過去。
• 地圖要放大到 Zoom 15 以上才會載入,太遠時地圖上方會提示放大。同一個畫面 60 秒內不會重複抓取,對該網站的請求間隔至少 1 秒。

1. Chrome 擴充功能(建議):按教學裡的「開啟資料夾」找到隨程式附上的擴充功能,到 Chrome 的 chrome://extensions 開啟開發人員模式並「載入未封裝項目」,再於同一個 Chrome 登入 pipimushroom.com。登入狀態會自動同步。這個網站的登入約 15 分鐘沒使用就會過期,LocWarp 執行期間與擴充功能都會定時續期;若仍然過期(例如電腦休眠後),面板會顯示「登入已過期」,在 Chrome 重新登入網站後約一分鐘內會自動恢復。
2. 手動貼上 Cookie:不用 Chrome 時,依教學裡的說明從瀏覽器複製 Cookie 貼上。

資料來源為 pipimushroom.com。位置、種類與剩餘時間的準確度無法保證,僅供參考;該網站改版時這個圖層可能暫時無法使用。

• 免費版:預設來源,使用 OpenStreetMap 開放資料,不用 API key。設定裡另有 Photon 選項,模糊搜尋與錯字容錯較強。
• Google Geocoding:輸入自己的 API key(只存在本機),中文地名與店家結果最精準,每月有免費額度。
• 座標輸入框可以直接貼上座標文字,會自動辨識出有效的經緯度。
• 手機網頁操控會沿用電腦端的設定。

人不在電腦旁時,可以用手機瀏覽器操控。按狀態列的「手機操控」會顯示區域網路網址與 6 位數 PIN,手機輸入後就能使用行動版地圖:瞬移、導航到指定點(走路 / 腳踏車 / 開車或自訂速度)、搜尋地址、輸入座標、停止與還原,並即時顯示桌面上同一條路徑。移動中會顯示進度、剩餘距離與時間,可以暫停、繼續或變更速度。電腦上儲存的座標與最近紀錄(保留 50 筆)可以直接取用。頁面可以加到手機主畫面,像 app 一樣全螢幕開啟,配色與座標格式跟隨電腦端的設定。

• 路線清單:選一條電腦上儲存的路線,地圖會先畫出路線預覽,再選擇起點(瞬移到起點或從目前位置走過去)與走法:走一趟、循環,或以花農專用模式在每個路徑點繞圈。
• 隨機漫步:以目前位置為中心,設定範圍半徑與速度後開始。
• 地圖圖層:地圖右下角的圖層按鈕可以切換底圖,選項與電腦端相同。預設跟隨電腦目前的圖層,在手機上另外選擇後以手機為準。

手機必須跟電腦連在同一個 WiFi,電腦防火牆需放行 8777 port。按「重新產生」可立刻更換 PIN,讓之前配對過的手機失效。PIN 連續輸入錯誤 5 次會暫時鎖定 60 秒。

• 目前模擬位置的國旗、地名、當地天氣與溫度。
• 跨時區時顯示時差,點開可看完整時區資訊。
• 一鍵還原:清除虛擬定位。注意「停止」只會結束移動,虛擬定位仍然保留,要恢復真實 GPS 請按還原。
• 版本號:有新版本時旁邊出現 NEW 標示。點擊後可以按「下載更新」在程式內下載(顯示進度),完成後按「重新啟動」即為新版;也可以改從 GitHub 或 Google 雲端自行下載安裝檔。程式不會自動下載,按了才會開始。
• 「Log 資料夾」按鈕:一鍵開啟 ~/.locwarp/logs/,方便把 backend.log 附到 Issue。

• Cooldown:依瞬移距離自動計算冷卻時間,降低被偵測為異常移動的風險。
• 介面語言可在繁體中文與 English 之間即時切換。
• 外觀(設定頁):六種主題色、三段玻璃效果(液態 / 霧面 / 關閉)、動畫開關。畫面卡頓時可把玻璃效果改為霧面或關閉。
• 設定頁的外觀、座標格式與提示音變更,需按「儲存設定」才會保留。
• 路線完成提示音、硬體加速開關(部分顯示卡驅動下關閉可解決殘影或黑畫面,見 Issue #24)。
• 所有資料(座標收藏、路線、設定)都存在 ~/.locwarp/,重新安裝不會遺失。

架構

┌─────────────────┐      IPC / HTTP + WS       ┌──────────────────┐
│ Electron + React│ ─────────────────────────► │ FastAPI backend  │
│  (port 5173 dev)│ ◄───────────────────────── │  (port 8777)     │
└─────────────────┘                            └────────┬─────────┘
                                                        │ pymobiledevice3
                                                        ▼
                                              ┌──────────────────┐
                                              │ iPhone (USB/WiFi)│
                                              └──────────────────┘

技術組成

| 層 | 技術 | 用途 | | --- | --- | --- | | Frontend | Electron 45 | 桌面外殼,負責視窗、啟動 backend、改寫圖磚請求的 User-Agent | | Frontend | electron-updater | 程式內更新,從 GitHub Releases 下載 | | Frontend | React 19 + TypeScript 7 + Vite 8 | UI 與打包(base: './' 供 file:// 載入) | | Frontend | Leaflet 1.9 | 互動地圖、自訂標記、動畫路徑線 | | Frontend | MapLibre GL 6 | 向量圖層渲染,經 maplibre-gl-leaflet 掛進 Leaflet | | Backend | Python 3.13 + FastAPI + uvicorn | REST API 與 WebSocket(:8777) | | Backend | pymobiledevice3 11.50+ | iOS 裝置協議(DVT / RemoteServices / lockdown / LegacyLocationService)與 WiFi tunnel | | Backend | httpx、pydantic、gpxpy | 外部服務呼叫、資料驗證、GPX 解析 | | 打包 | PyInstaller、electron-builder(NSIS) | backend exe 與 Windows 安裝檔 |

介面圖示全部是 inline SVG,樣式是手寫的 CSS(styles.css 為版面,appearance.css 為主題、玻璃與動畫,library.css 為收藏視窗),沒有使用第三方 icon 或 UI 套件。

外部服務

全部免費。除了 Google Geocoding 需要使用者自備 key,其餘都不需要註冊。

| 服務 | 呼叫端 | 用途 | | --- | --- | --- | | OSRM demo、OSRM FOSSGIS、Valhalla、BRouter | backend | 路線規劃與多點順序最佳化 | | Photon (komoot) | backend | 地址搜尋與反向地理編碼(國旗、地名) | | Google Geocoding API | backend | 地址搜尋(選用,使用者自備 key) | | Open-Meteo | frontend | 模擬位置的天氣 | | TimezoneDB | backend | 座標轉時區(內建 key) | | flagcdn.com | frontend | 國旗圖片 | | OpenStreetMap、Google、ESRI、OpenFreeMap、VersaTiles、NLSC、GSI | frontend | 地圖圖磚 | | pipimushroom.com | backend | 蘑菇地圖圖層的點位資料(選用,需使用者自己登入) | | GitHub Releases | frontend | 啟動時檢查新版本(無遙測);使用者按下「下載更新」後才下載新版 |

反向地理編碼不使用 Nominatim 公共伺服器,因為它的使用政策以應用程式為單位計算流量上限,不適合散佈型的桌面程式。地址搜尋的預設選項若被 Nominatim 拒絕,會自動改用 Photon。

核心模組(backend/core/)

| 模組 | 職責 | | --- | --- | | simulation_engine.py | 中央控制器:狀態轉換、任務生命週期、_move_along_route() 移動迴圈、ETA 計算 | | device_manager.py | 裝置探索、USB 與 WiFi Tunnel 連線管理 | | navigator.py | 單一目的地導航 | | route_loop.py / multi_stop.py | 多點路徑的循環與停留 | | flower.py | 花農專用的繞圈邏輯 | | random_walk.py / joystick.py | 隨機漫步、搖桿 | | teleport.py / restore.py | 瞬移、還原 |

設計重點

• 位置推播:backend 每個 tick 透過 WebSocket 送出 position_update,前端即時更新地圖與 ETA。
• 速度解析:config.resolve_speed_profile() 統一處理模式預設、固定速度、隨機範圍,優先序為範圍 > 固定 > 預設。
• In-process WiFi tunnel:backend 直接在主 event loop 內執行 start_tcp_tunnel(),沒有獨立的 helper 程式。
• 狀態目錄:所有執行期資料寫入 ~/.locwarp/,避開 PyInstaller 的臨時目錄。
• 節制的地理查詢:國旗、地名、時區、天氣只在靜止或瞬移後、且位置變動超過 100 公尺時查詢,移動中不查,避免干擾與裝置的通訊。四項查詢並行,其中一項慢不會拖住其他項。
• 反向地理編碼快取:結果以約 100 公尺的格子為單位存在磁碟(reverse_geocode_cache.json,保留 30 天),回到查過的地方不再連網,同時發出的相同查詢會合併成一次。新增座標與「這裡是哪裡」會略過快取以取得精確名稱。
• 天氣由前端直連:每個使用者用自己的 IP 計算 Open-Meteo 配額,不經 backend 轉送。
• 圖層預先連線:滑鼠移到圖層選單時,預先對所有圖層的主機建立連線並抓取向量圖層的 style,縮短第一次切換的等待。
• 多裝置群組:primary 裝置不會被後插的裝置取代,後插的裝置會同步到 primary 的位置並接續任務。

開發環境

需求:Windows 10 / 11、Python 3.13、Node.js 18+,以及一台已配對並開啟開發者模式的 iPhone。

# 後端依賴(含 WiFi tunnel)
py -3.13 -m pip install -r backend/requirements.txt
前端依賴
cd frontend
npm install

雙擊 LocWarp.bat 會自動提權並啟動 backend(:8777)與 Vite dev server(:5173),並用預設瀏覽器開啟。也可以手動啟動:

# 終端 1:backend
cd backend && py -3.13 main.py
終端 2a:前端走瀏覽器
cd frontend && npx vite --host --port 5173
終端 2b:前端走 Electron 視窗(跟安裝檔相同的執行方式)
cd frontend && npm run start

開發模式走 http://,安裝檔走 file://,兩者行為不完全相同(例如 MapLibre 的 worker)。升級前端相依套件後,請務必用打包後的安裝檔驗證。

打包

# 一次性安裝
py -3.13 -m pip install pyinstaller
cd frontend && npm install -D electron-builder
一鍵建置
build-installer.bat

build-installer.bat 依序執行:

1. PyInstaller 編譯 backend 到 dist-py/locwarp-backend/
2. Vite 建置前端到 frontend/dist/
3. electron-builder 產出 frontend/release/LocWarp-Setup-X.Y.Z.exe(約 150 MB)

發布新版時,frontend/release/ 裡的三個檔都要上傳到 GitHub release:LocWarp-Setup-X.Y.Z.exe、LocWarp-Setup-X.Y.Z.exe.blockmap、latest.yml。程式內更新靠 latest.yml 得知最新版本,.blockmap 讓它只下載有變動的部分;缺少 latest.yml 時使用者只能手動下載。

專案結構

locwarp/
├── backend/                 # FastAPI + pymobiledevice3
│   ├── api/                 # HTTP endpoints
│   ├── core/                # Simulation engine + 各移動模式
│   ├── services/            # 定位服務、地理編碼、座標收藏、路線
│   ├── models/schemas.py    # Pydantic models
│   ├── static/phone.html    # 手機網頁操控頁面
│   ├── config.py            # 速度 profile、cooldown 表、路徑設定
│   ├── main.py              # Entrypoint
│   └── locwarp-backend.spec # PyInstaller spec
│
├── frontend/                # Electron + React
│   ├── electron/main.js     # Electron 進入點,打包模式下啟動 backend
│   ├── src/
│   │   ├── App.tsx
│   │   ├── components/      # MapView, ControlPanel, LibraryPanel, StatusBar...
│   │   ├── hooks/           # useSimulation, useDevice, useBookmarks
│   │   ├── i18n/            # 中英文字串
│   │   └── services/api.ts
│   ├── build/               # 圖示與安裝程式圖片
│   └── package.json         # electron-builder 設定
│
├── LocWarp.bat / start.py   # 開發用啟動器(自動提權)
├── stop.py
├── extensions/              # 蘑菇地圖用的 Chrome 擴充功能,pack.py 產生商店上傳用的 zip
└── build-installer.bat      # 一鍵建置安裝檔