【免费下载链接】geo-sleuth

An agent skill that finds where a photo was taken — OpenStreetMap geometry, elevation skylines, satellite imagery and street view — and shows its work. Works with Claude Code, Codex, Cursor, Gemini CLI, OpenCode and GitHub Copilot.

项目地址： https://gitcode.com/gh_mirrors/ge/geo-sleuth

点击查看 免费下载

geo-sleuth 是一个开源的照片地理定位 Agent Skill：把一张照片交给 AI 智能体，它就能找出照片的拍摄地点，并输出机位坐标、镜头朝向和卫星证据图。本教程带你用 5 分钟完成 geo-sleuth 安装，一次覆盖 Claude Code、Codex、Cursor、Gemini CLI、OpenCode 和 GitHub Copilot 这 6 大 AI 智能体，并教你用自检脚本验证部署是否成功。

30 秒了解：geo-sleuth 能做什么

很多人以为"照片定位"必须依赖 GPS 或 EXIF 信息，但 geo-sleuth 恰恰擅长没有这些线索的场景：画面里没有文字、没有车牌、没有地标，它照样能靠 OpenStreetMap 几何数据、高程数据、卫星图和街景把搜索一步步推进下去。

它的工作方式是"脚本排序、模型判断"：二十多个各司其职的脚本负责搜索、打分和排序，模型只在排名靠前的少数候选里做判断，最终结论必须指向真实运行过的命令和产出的文件。一次定位完成后，你会拿到：

• 机位坐标 + 误差半径（案例中最好成绩 ±2 m）
• 镜头朝向（朝向角）
• 一张卫星证据图
• 分档的置信度（高 / 中 / 低）

安装完成后，它的核心入口就是 skills/geo-sleuth/SKILL.md，AI 智能体读取它即可知道整个定位流程。

安装前环境检查：Python、uv 与浏览器要求

部署 geo-sleuth 前，请确认本机满足以下 3 项要求：

要求	说明
Python 3.10+	每个脚本通过 uv run 自动安装自己的依赖，无需手动装包
uv 和 curl	脚本运行与网络探测的基础工具
Google Chrome 或 Playwright Chromium	仅"以图搜图"环节需要，脚本会先尝试 Chrome，失败自动回退 Chromium

另外，如果你使用 npx 方式安装，系统里还需要 Node.js。安装完成后，skill 文件夹应保持完整，包含 SKILL.md、scripts/、references/ 和 data/（其中查表数据的来源见 skills/geo-sleuth/data/README.md）。

方法一：一键安装，一条命令覆盖 6 大 AI 智能体

最省事的部署方式是 skills CLI。交互式安装（按提示勾选你要用的 agent）：

npx skills add Oldcircle/geo-sleuth

如果想一次性把 geo-sleuth 装到全部 6 个 agent 的用户级目录，可以一条命令完成：

npx skills add Oldcircle/geo-sleuth -g -a claude-code -a codex -a cursor -a gemini-cli -a opencode -a github-copilot -y

参数含义：-g 表示安装到用户级（全局可用），-a 指定目标 agent，-y 自动确认。装完即可跳到 安装后自检。

方法二：手动安装，clone 仓库 + 复制 skill 文件夹

如果你想完全掌控文件位置，也可以手动复制，只需 4 条命令：

git clone https://gitcode.com/gh_mirrors/ge/geo-sleuth
mkdir -p ~/.agents/skills ~/.claude/skills
cp -r geo-sleuth/skills/geo-sleuth ~/.agents/skills/   # Codex、Cursor、Gemini CLI、OpenCode、GitHub Copilot
ln -s ~/.agents/skills/geo-sleuth ~/.claude/skills/geo-sleuth   # Claude Code

关键在于：Codex、Cursor、Gemini CLI、OpenCode 和 GitHub Copilot 都会读取 ~/.agents/skills/，所以在这份目录放一个 skill 就能同时覆盖 5 个 agent；Claude Code 则有自己独立的 ~/.claude/skills/ 目录。

六大 AI 智能体的 skill 目录速查表

Agent	用户级目录	项目级目录
Claude Code	~/.claude/skills/	.claude/skills/
Codex	~/.agents/skills/	.agents/skills/
Cursor	~/.cursor/skills/ 或 ~/.agents/skills/	.cursor/skills/ 或 .agents/skills/
Gemini CLI	~/.gemini/skills/ 或 ~/.agents/skills/	.gemini/skills/ 或 .agents/skills/
OpenCode	~/.config/opencode/skills/ 或 ~/.agents/skills/	.opencode/skills/ 或 .agents/skills/
GitHub Copilot	~/.copilot/skills/ 或 ~/.agents/skills/	.github/skills/ 或 .agents/skills/

其他任何能读取 SKILL.md 并运行 shell 命令的 agent 用法相同：把文件夹放到它查找 skill 的位置即可。

安装后自检：doctor.py 一条命令验证环境

部署完成后，第一件事是运行环境自检脚本 skills/geo-sleuth/scripts/doctor.py。在仓库目录内直接运行：

uv run skills/geo-sleuth/scripts/doctor.py
uv run skills/geo-sleuth/scripts/doctor.py --network

如果 skill 已安装，换成实际路径（也可以直接让 agent 帮你运行）：

uv run ~/.agents/skills/geo-sleuth/scripts/doctor.py --network

自检会检查：Python / uv / curl 是否可用、查表数据是否完整、当前目录是否可写、浏览器能否真实启动；加上 --network 后还会探测各在线服务的连通性（不上传你的照片）。结果判读：

• 退出码为 1：存在失败项，按输出的英文提示修复后重跑
• 出现 warning：仅表示部分可选功能（如以图搜图）可能不可用
• 自检不加载 OCR 或 ML 模型，跑一次很快

如果浏览器启动失败，安装 Playwright Chromium 即可：

uvx playwright install chromium

Linux 系统若缺少系统库，可改用 uvx playwright install --with-deps chromium。

首次使用：把照片交给 agent 开始定位

部署成功后的使用方式简单到只需一句话。把一张照片发给你的 agent，然后说：

找出这张照片是在哪拍的

agent 会读取 SKILL.md、运行脚本，最终返回机位、朝向和证据图。整个流程大致是：

1. intake.py 一条命令完成元数据读取、边缘裁图、OCR 和以图搜图，生成 intake.md
2. 线索和候选进入"候选盘"（board.py）打分、排名
3. 按线索类型走不同分支：高程天际线、卫星图扫描、街景比对等
4. evidence.py 输出卫星证据图和分档置信度

如果不想完全交给 agent，也可以先手动跑一遍本地处理流水线来验证部署：

uv run ~/.agents/skills/geo-sleuth/scripts/intake.py photo.jpg --out-dir intake --no-rev

--no-rev 表示跳过在线以图搜图，只检查元数据、裁图和 OCR；首次运行会安装依赖，建议给命令 10 分钟以上超时。运行完成后打开 intake/intake.md，再查看定位结果生成的卫星证据图：

各脚本的具体功能与数据来源，可参考 skills/geo-sleuth/references/data-sources.md。

常见问题速查：浏览器、超时与模型下载

症状	解决办法
uv 或 curl not found	安装缺失的工具，重开终端后重跑 doctor.py
浏览器启动失败	安装 Chrome 或运行 uvx playwright install chromium；期间可用 intake.py --no-rev 先走本地流程
HTTP 403 / 429 或验证码	查看脚本保存的截图，稍后重试
服务连接超时	先跑 doctor.py --network 排查服务与网络
首次运行明显变慢	match.py、sat_scan.py 首次会下载 ML 模型权重，预留时间和磁盘空间
intake.md 出现 failed / skipped 步骤	阅读报告；搜索失败不等于"没有相似图片"

另外注意：skill 的指令、CLI 帮助和报错信息为英文，但 agent 会用你的语言撰写最终定位报告；OCR 识别到的地名等原文会作为证据保留。

总结：从安装到首次照片地理定位只需 5 分钟

回顾 geo-sleuth 部署教程的完整路径：确认 Python 3.10+ / uv / curl 环境 → 用 npx skills add 一键装到 6 大 AI 智能体（或手动 clone 复制）→ 用 doctor.py 自检 → 把照片交给 agent 说出"找出这张照片是在哪拍的"。更多细节可阅读 README.zh-CN.md 中的完整案例与基准测试。

最后提醒一句：请只在自己拍摄的照片或已获授权分析的照片上运行 geo-sleuth，不要用它去定位没有同意被找到的人。

【免费下载链接】geo-sleuth

An agent skill that finds where a photo was taken — OpenStreetMap geometry, elevation skylines, satellite imagery and street view — and shows its work. Works with Claude Code, Codex, Cursor, Gemini CLI, OpenCode and GitHub Copilot.

项目地址： https://gitcode.com/gh_mirrors/ge/geo-sleuth

点击查看 免费下载