coding-parrot/pothole-reporter · 上手攻略
- 仓库：coding-parrot/pothole-reporter
- 链接：https://github.com/coding-parrot/pothole-reporter
- 分类：AI 应用 · 政务/民生
- 作者：Tom
- 更新：2026-08-21
这是什么
pothole-reporter 是一个纯客户端 Android 应用，用 AI 视觉检测班加罗尔（Bengaluru）道路坑洞，自动关联公共采购记录找到负责官员和承包商，生成一份可编辑的投诉邮件草稿，由你审核后手动发送。
核心特点：没有服务端、不需要账号、不自动发邮件——一切都在本地完成，你掌控每一步。App 扫描约 2,900 份政府合同记录用于关联，检测结果生成时间约 4 秒（含照片、地理位置、标段编号、负责官员）。
⚠️ 注意：当前覆盖范围仅限卡纳塔克邦（Karnataka）城市地方机构，国道和农村道路不在范围内。
解决什么问题
印度政府数据显示，2024 年全国因坑洞相关事故死亡人数达 2,385 人。坑洞投诉长期面临两大痛点：
- 定位难：普通人知道哪里有坑，但不知道怎么准确描述位置、该向哪个机构投诉。
- 追责难：即使投诉了，道路可能有保修期内的承包商负责，政府可以直接把责任转给承包商——但普通人无从得知这些信息。
pothole-reporter 同时解决了这两个问题：拍照 → AI 识别坑洞类型 → 自动查 Karnataka GIS 边界 + 公共采购合同数据库 → 找到对应官员和合同 → 生成投诉草稿。
快速安装
下载 APK（推荐）
直接从 GitHub Releases 下载最新 APK：
https://github.com/coding-parrot/pothole-reporter/releases/latest
在手机设置中开启「安装未知来源应用」权限后，侧载（sideload） 安装。
从源码构建
# 克隆仓库
git clone https://github.com/coding-parrot/pothole-reporter.git
cd pothole-reporter
# 构建 APK（需要 Node.js、Android/JDK、Python、Gradle、Playwright）
./tools/build-apk.sh
# 运行测试套件
./tests/run-all.sh
⚠️ 注意：测试套件需要 OPENAI_API_KEY 写入 .env 文件，部分测试会调用真实的 OpenAI API 和 Karnataka GIS 服务。
首次配置
- 打开 App
- 允许相机和位置权限
- 输入你的 OpenAI API Key（API key 存储在本地，只发给 OpenAI）
- 开始使用
核心用法
模式一：停车拍照报告（最常用）
- 在安全停车状态下，打开 App
- 点击 Report road damage
- 拍摄一张照片（单张模式）
- AI 在约 4 秒内返回结果，包含：
- 坑洞类型：pothole cavity / failed patch / surface breakup / rut or depression
- 置信度：0~1 分值（如 0.72）
- 地址：通过 OpenStreetMap Nominatim 逆地理编码
- 对应机构：Commissioner（班加罗尔南方城市公司 BBMP South 等）
- Probable 合同编号：如
BBMP/2025-26/OW/WORK_INDENT7739+ 中标承包商 - 审核草稿内容，确认无误后打开邮件应用发送（不会自动发送）
⚠️ 草稿是 Probable 匹配，不是责任证明。合同信息来自公共采购记录，匹配是概率性的，不代表官方确认的责任归属。
模式二：行车记录模式（Drive Mode）
适合通勤路上自动采集沿途坑洞：
- 固定手机：使用车载支架，确保道路在橙色引导框内
- 开启 Drive Mode（默认关闭，需手动开启）
- 启动行车，App 在前台持续录制（不需要操作手机）
- App 根据 GPS + 视觉采样，每隔一段距离分析一次路况
- 行程结束后，所有识别结果分组显示为一个事件
存储消耗：Drive Mode 每分钟约 18 MB 存储。分析完成后（除非开启 Debug 模式）， footage 自动删除以释放空间。
⚠️ 注意事项： - Drive Mode 需要 App 始终在前台（不允许切到后台） - 需要网络连接（用于实时地理编码和道路分类） - 检测不完美：可能漏检或误检，每次结果都需要人工审核后再发送投诉 - 检测默认使用 gpt-4o-mini + 高图像-detail；App 也提供 gpt-4o / original-detail 实验选项，但均无完整人工标注 v3 field benchmark（见 eval/README.md）
数据说明
| 数据发送至 | 用途 |
|---|---|
| OpenAI API | 视觉识别坑洞类型 |
| OpenStreetMap Nominatim | 地理坐标 → 地址 |
| Karnataka GIS | 行政边界 + 道路分类 |
- 面孔和车牌不会自动模糊（如需隐私保护请手动处理）
- API Key 存储在本地
- 报告、标签、footage 均仅存在本地，不上传到任何项目服务器
典型使用场景
| 场景 | 操作方式 | 说明 |
|---|---|---|
| 上班路上发现坑洞 | Drive Mode 通勤录制 | 一次 drive 检出 12 个坑洞并生成投诉记录 |
| 安全停车时拍单张 | 拍照 Report 模式 | 适合偶发性发现 |
| 发现坑洞想投诉 | 审核草稿后发送 | 草稿含合同编号 + 官员邮箱 |
坑与注意
-
检测非 100% 准确：README 明确声明"Detection is not perfect. It can miss damage or produce false positives"——所有结果都需要人工审核，不能直接照发。
-
覆盖边界严格：以下情况 App 会拒绝生成投诉： - 国道（National highways）→ 由 NHAI 或 PWD 维护，不猜测 - 农村道路 → 指定 gram panchayat - 卡纳塔克邦以外 → 拒绝 - 道路归属不明或该机构无公开邮箱 → 拒绝
-
API 费用注意：Drive Mode 会产生大量图片请求，一次长途行驶可能调用数十次 OpenAI Vision，费用需要自己承担。
-
隐私：拍摄的照片会发送给 OpenAI；面孔和车牌未做自动模糊处理，介意的话需要自己裁剪。
-
无 Zotero/学术支持：这是民生政务工具，不是研究类插件，没有 PDF 阅读或引用管理功能。
-
Zim 牌检测：App 会把形状像减速带的物体也识别为 pothole，需要人工判断。
与同类对比
| 方案 | 平台 | 公共记录关联 | 邮件草稿 | 开源 |
|---|---|---|---|---|
| pothole-reporter（本案） | Android | ✅ 2900 份 Karnataka 合同 | ✅ 含合同编号 + 官员 | ✅ MIT |
| 政府 1919 投诉热线 | 电话/网页 | ❌ | ❌ | ❌ |
| FixMyStreet（全球） | Web/App | ❌ 纯投诉通道 | ❌ | 部分开源 |
| OpenStreetMap 志愿者采集 | Web | ❌ | ❌ | ✅ |
本工具的差异化在于把坑洞检测 + 政府公共记录 + 投诉草稿生成三步合一，且完全本地化——不依赖任何政府 IT 系统。
一句话推荐结论
在 Bengaluru 生活或通勤、需要投诉坑洞的人，这个 App 把「拍照→AI 分析→找到负责人→写好投诉邮件」压缩成 4 秒一条龙，适合作为公民上报工具的加速器；但记得审核每一条结果再发送，别让 AI 的误检浪费公共资源。