geo-sleuth

给 AI 装上地理侦探技能，一张照片顺藤摸瓜找到拍摄地

开源 🏷️完全免费 🔧 仅开源项目，无在线服务，需自行部署智能体 🍴 复刻 796 🐛 待处理 26 👀 关注 15

GitHub ↗

GitHub 星标 ★ 6490

维护状态活跃

是否开源开源

定价模式 🏷️完全免费开源免费，需自行部署

项目预览

项目数据

分类智能体

开发团队Oldcircle

GitHubhttps://github.com/Oldcircle/geo-sleuth

定价模式🏷️完全免费

价格说明开源免费，需自行部署

访问状态🔧 仅开源项目，无在线服务，需自行部署

是否开源是

开源协议MIT

主要语言Python

技术栈/模型agent-skills,ai-agents,claude-code,codex,computer-vision,cursor,gemini-cli,geoguessr,geoint,geolocation,github-copilot,image-geolocation,opencode,openstreetmap,osint,photo-geolocation,reverse-image-search,satellite-imagery

GitHub 星标★ 6490

上线时间2026-09-18 00:00:00

代码更新2026-11-05

仓库体积17.9 MB

本站数据更新2026-11-08

维护状态活跃

收录时间2026-09-25

浏览次数102

项目介绍

geo-sleuth 是一个面向 AI 智能体的照片地理位置推断技能包，目标是回答「这张照片拍在哪里」。它把多种开源地理数据源组合成一条可解释的推理链：先用 OpenStreetMap 的几何与道路信息匹配画面中的建筑、路牌、地形特征，再用高程数据生成天际线轮廓与照片中的山脊线比对，接着调用卫星影像和街景视角做视觉验证，最终给出候选坐标并展示每一步依据。项目以 Python 编写，作为 agent skill 可接入 Claude Code、Codex、Cursor、Gemini CLI、OpenCode 和 GitHub Copilot 等编码智能体，让模型在对话中直接调用地理定位能力。它解决的是传统单模型「看图猜地点」缺乏证据、难以复核的问题，把定位过程拆成可追溯的多个环节，适合做地理情报分析、OSINT 调查、GeoGuessr 辅助训练等场景。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

数据来源：GitHub API 逐日快照 · 收录于 2026-09-25 · 当前星标 ★ 6490

技术标签

agent-skills ai-agents claude-code codex computer-vision

使用教程

难度：入门约 10 分钟部署方式：命令行工具 7 步

环境要求

Python 3.10+
uv（用于 uv run / uvx 运行脚本与安装依赖）
curl
一个能执行 shell 命令的编码智能体（Claude Code、Codex、Cursor、Gemini CLI、OpenCode、GitHub Copilot
反查图搜需本机装有 Google Chrome 或 Playwright Chromium

安装与启动步骤

1一键安装技能包

在终端用 skills CLI 安装，提示时选择要接入的智能体，安装完成后即可把照片交给它。
```
npx skills add Oldcircle/geo-sleuth
```
2六个智能体全局安装

一条命令把技能装到全部六个智能体的用户级目录，-y 跳过确认，省去逐个选择。
```
npx skills add Oldcircle/geo-sleuth -g -a claude-code -a codex -a cursor -a gemini-cli -a opencode -a github-copilot -y
```

3手动克隆安装

不想用 CLI 时，克隆仓库后把技能文件夹复制到 ~/.agents/skills/，并为 Claude Code 建软链。

git clone https://github.com/Oldcircle/geo-sleuth
mkdir -p ~/.agents/skills ~/.claude/skills
cp -r geo-sleuth/skills/geo-sleuth ~/.agents/skills/
ln -s ~/.agents/skills/geo-sleuth ~/.claude/skills/geo-sleuth

4装浏览器依赖

反查图搜需要 Chrome 或 Chromium，脚本会先试 Chrome 再退回 Chromium；两者都没有才需执行。
```
uvx playwright install chromium
```
5运行环境自检

首次使用先跑 doctor.py，它会测 Python、uv、curl、查找表、可写工作目录和浏览器启动；--network 额外探测服务。
```
uv run skills/geo-sleuth/scripts/doctor.py
uv run skills/geo-sleuth/scripts/doctor.py --network
```
6本地管道自测

用自己的照片验证元数据、图像预处理与 OCR，加 --no-rev 跳过联网反查图搜；去掉该参数即为完整流程。
```
uv run skills/geo-sleuth/scripts/intake.py photo.jpg --out-dir intake --no-rev
```
7让智能体定位

把照片交给已接入的智能体，直接说“find where this photo was taken”，它会读 SKILL.md 并调用脚本。

关键配置

配置项	必填	说明	示例
`skills 安装目录（用户级）`	否	Codex、Cursor、Gemini CLI、OpenCode、GitHub Copilot 共用的技能目录	`~/.agents/skills/`
`Claude Code 技能目录`	否	Claude Code 读取的技能目录，可用软链指向共用目录	`~/.claude/skills/geo-sleuth`
`技能目录（项目级）`	否	仅对当前项目生效的技能放置位置	`.agents/skills/`

如何确认成功

doctor.py 没有失败检查（退出码不为 1）即环境就绪；之后智能体能返回相机位置、朝向和卫星证据图。

常见问题

Q：反查图搜报缺少浏览器怎么办？

A：脚本优先用 Google Chrome，找不到会自动退回 Chromium。装好任一浏览器即可，或缺依赖时执行 uvx playwright install chromium 安装。

Q：Linux 上浏览器启动失败？

A：可能缺系统库，改用 uvx playwright install --with-deps chromium 一并安装；Playwright 升级后若提示缺可执行文件，重跑一次安装器。

Q：第一次运行很慢、磁盘占用大？

A：match.py 和 sat_scan.py 首次运行会安装 ML 包并下载模型权重，需要额外时间和空间，属正常现象。

Q：自检通过是否代表一定能用？

A：不一定。端点探测通过不代表能上传图片、下载模型、覆盖到目标影像或不被 CAPTCHA 拦截。

Q：只想本地处理，不想联网搜索？

A：用 intake.py 加 --no-rev 只做元数据、图像准备与 OCR 检查；去掉 --no-rev 才是包含反查图搜的完整流程。

注意事项

必须保留完整技能文件夹，包括 data/ 和 scripts/ 里的辅助模块，缺文件会导致脚本失败。
uv 与模型权重的下载仍需要网络访问，即使当前处理步骤本身是本地完成的。
手动安装时常见路径写错，注意仓库内是 skills/geo-sleuth 子目录，而不是仓库根目录。

核心亮点

多源证据链设计：OSM 几何、高程天际线、卫星影像、街景交叉验证，而非单模型黑箱猜测
每一步推理过程可视化展示，定位结论可复核、可追溯，适合调查类场景
作为 agent skill 即插即用，兼容 Claude Code、Codex、Cursor、Gemini CLI 等多个主流编码智能体

不足之处

依赖外部地理数据源和街景/卫星接口，网络与配额受限时效果会明显下降
项目处于早期，313 星规模下文档完整度和边界案例覆盖仍待观察

适用场景

OSINT 调查人员根据社交媒体照片推断拍摄地点
GeoGuessr 玩家用 AI 辅助分析画面线索并学习推理方法
记者或研究者核实图片拍摄位置与地理背景

替代项目

GeoSpy、PIGEON

上一篇：accessibility-agents

下一篇：langgraph-cua-py