geo-sleuth 照片定位工作流程

geo-sleuth 是由 Agent 操作 Python 腳本的照片定位技能。它以候選地點與證據紀錄組織調查，適用於分析本人拍攝或已獲授權的照片。

這是一個技能資料夾，需由可讀取 SKILL.md 並執行 shell 的 Agent 使用。它不提供獨立的照片定位網站。

透過 skills CLI 安裝時，由互動介面選擇使用的 Agent：

這條安裝路徑需要可用的 Node.js／npm 工具鏈；Python 腳本本身依 uv 管理依賴。若要從原始碼查閱及執行，使用以下路徑：

需要檢查服務連線時，再執行：

doctor.py --network 不上傳照片，也不載入 OCR 或 ML 模型。首次透過 uv run 執行時，依賴安裝仍可能使用網路。

反向搜尋的瀏覽器未安裝時，可依官方方式安裝 Chromium：

以下卡片列出腳本或子命令名稱。從 clone 根目錄執行時，在名稱前加上 uv run skills/geo-sleuth/scripts/；已安裝的技能則使用實際路徑。

線索依狀態記錄，避免把推測寫成測量：

observed 與 inferred 可改變候選權重，但不能直接作為排除依據。排除需要符合證據條件，且檔案存在不代表其內容已被正確解讀。

候選板的 share 是目前紀錄候選間的相對分數，不能當成已校準的照片定位命中率。最終報告的信心分級與候選排序分開處理。

match.py 與 sat_scan.py 首次使用會安裝 ML 依賴並下載權重。裝置預設嘗試順序如下，可透過 GEO_DEVICE 選擇支援的裝置：

• CUDA。

• MPS。

• CPU。

模型權重下載與影像處理需預留時間及磁碟空間。Agent 使用費依宿主工具與模型方案而定，不因技能程式碼採 MIT 就保證整次調查沒有成本。

範例使用本人拍攝、可合法分析的公共步道照片 public-landscape.jpg。目標先設定為片區層級，且不執行對未同意者的定位。

以下命令是操作規格，本次未分析照片。從 clone 根目錄建立新的案例資料：

先檢查以下產出；初始 board 尚未包含定位證據：

可將以下工作規格交給已載入技能的 Agent：

Agent 應依實際線索選路徑。地圖與幾何資料確認後，才建立 case-landscape/spec.json：

先檢查地圖 sidecar 的 failed_tiles 與實際影像，再組合證據圖：

接著檢查候選板：

若印出 FAIL，先停止並修正。內容檢查通過後，再將候選紀錄合併至結果檔：

report --merge 整理候選紀錄，不會替照片計算真實座標。若證據不足，交付已支持的層級與待補資訊，不要為了填滿欄位產生一個位置。

技能要求誤差半徑不大於 100 m 時，需有兩項獨立限制的交會，或至少三項不變特徵的地面影像吻合。這是證據門檻，不能取代來源品質與相機幾何的檢查。

各層級分開評分，報告到最細且達到中信心以上的層級。單一山稜線吻合只限制視線；不能直接寫成公尺級相機位置。

候選板的 --level 與報告的信心表不同。建立候選時使用該 CLI 支援的層級，不要把報告名稱直接當成參數：

證據圖使用 WGS84 對齊的底圖。從其他地圖讀到座標時，先確認 datum：

程式碼授權與資料授權分開確認：

案例目錄與 .geo-cache/ 可能保留來源資訊。對外分享前檢查檔案內容，勿公開未授權的照片或私密位置。

README 列出以下新 Agent 重跑紀錄；數字屬作者報告，本次未重現：

這兩張照片先前都已解出，相關經驗也已寫入技能，因此 README 將它們定位為回歸檢查。它們不是未見照片的整體準確率；公開的未見照片盲測集仍列在 roadmap。

個別算子的檢索排名不能代表端到端定位成功。評估自己的用途時，保留未解出的案例與實際調查成本。

維護中的工具訊息與說明以英文為主；OCR 與來源文字保留原文，由 Agent 用讀者語言解釋。凍結的 zh-final tag 不能替代目前主線文件。

本手冊查核修訂為 1a9ecee153b02e2db2e62352002fa5b17bbd819d，技能文件標示 v2。本次未執行：

• 照片定位或案例重跑。

• 照片上傳與地圖服務查詢。

• 技能安裝或模型下載。