Dukotah/leadgen

从免费的公共数据中寻找经过评分的本地商家潜在客户 —— 无需 API 密钥，无需账号，直接在你的机器上运行。

一个流水线 —— **收集 → 去重 → 富化 → 抑制 → 评分 → 导出** —— 由可替换的 **垂直领域** 驱动。*垂直领域* 描述了你要寻找什么以及如何对其进行评分；引擎会处理其余的所有工作。将它指向地球上任何可进行地理编码的市场，从 10 个免费且无需密钥的数据源中提取商家信息，审查他们的网站，最终获得一个适配 CRM 的 CSV 文件和一份按颜色分级的电子表格。 ``` ┌── Overture · OpenStreetMap · Foursquare ┌── score_fn → A / B / C + reasons data ───┤ Socrata · NPI · ArcGIS · Wikidata · your CSV ├── enrich_fn → audit each site └── (10 sources, zero API keys) vertical ─┘── opener_fn → a suggested pitch │ │ collect → dedupe → enrich → suppress → score → export → CSV + XLSX ``` **19 个现成的垂直领域**（网页设计、SEO、纯社交媒体、餐饮、家政服务、医疗保健等 —— 运行 `python -m leadgen --list` 查看），或者只需在单个文件中添加你自己的垂直领域。 ## ⬇️ 只想运行它？（无需编程） 下载适合你电脑的桌面应用程序，双击即可完成 —— 无需 Python，无需安装： - **Windows** → `LeadEngine-windows.exe` - **macOS** → `LeadEngine-macos` - **Linux** → `LeadEngine-linux` 从 [**Releases**](../../releases) 页面获取最新版本。它会打开一个简单的 窗口：选择要寻找的内容和位置，点击 **Find leads**，即可下载电子表格。 其中有一个 **“Try a sample”** 按钮可以在无网络环境下运行，让你先确切了解 会得到什么结果。（未签名的二进制文件会触发一次 Windows SmartScreen / macOS Gatekeeper 拦截 —— 点击“仍然运行” / 右键点击 → 打开。详见 [`gui/BUILD_EXE.md`](gui/BUILD_EXE.md)。） 本 README 的其余部分是为想要编写脚本或对其进行扩展的用户准备的。 ## 快速开始 ``` pip install -r requirements.txt python -m leadgen --list # show available verticals python -m leadgen --vertical web_design --market austin_tx --out austin_web python -m leadgen --vertical web_design --market "Boulder, Colorado" --sources overture osm ``` 市场可以是 **已保存的键值**（`austin_tx`, `phoenix_az`, `tampa_fl`, `sonoma_county_ca`），也可以是 **我们即时进行地理编码的任何地名**（`"Boulder, Colorado"`）。 输出：`_crm.csv`（扁平化格式，可直接导入）和 `.xlsx`（带有颜色分级的 Tier A/B/C， 包含评分、原因以及为每个潜在客户建议的开场白）。 ### 零配置查看运行效果 ``` python -c "from leadgen import get_vertical, run_pipeline; \ run_pipeline(get_vertical('web_design'), market='(demo)', demo=True)" ``` 演示模式会在内置的五个样本商家上 **离线** 运行完整流水线 —— 无需网络 —— 让你在第一次正式抓取前就能看到真实的分级输出结果： ``` Tier Score Business Why it's a lead ──── ───── ───────────────────── ─────────────────────────────────────────── A 64 Summit Plumbing Co NO WEBSITE; phone listed A 54 Old Town Auto Repair site unreachable; phone listed B 48 Sunrise Cafe no HTTPS; not mobile-friendly; DIY (Wix) A 44 Bella Hair Studio social-only (facebook.com); phone listed C 4 Evergreen Dental real site, no obvious issues ``` CSV/XLSX 中的每个潜在客户还会包含电话、网站、地址以及建议的开场白。 ### 点击式 GUI 无需命令行：选择一个垂直领域 + 市场，可选择上传 CRM 数据进行去重，点击运行，实时查看进度，下载 CSV/XLSX 文件。这里有一个 **“Try a sample”** 按钮（离线演示），以及一个 **“Check my connection”** 按钮，它会用通俗易懂的语言测试每个数据源。 ``` pip install -r gui/requirements.txt cd gui && ./run.sh # browser mode (run.bat on Windows) # 或原生桌面窗口： python gui/desktop_app.py ``` 它也可以打包成一个可双击运行的 `LeadEngine.exe`（无需 Python）—— 详见 [`gui/BUILD_EXE.md`](gui/BUILD_EXE.md)。参见 [`gui/README.md`](gui/README.md)。 ## 数据源 全部免费，**无需 API 密钥**。每个数据源都返回相同的标准化记录结构，因此 流水线的其余部分与具体数据源无关。使用 `--sources` 选择任意组合： | 数据源 | 它是什么 | 需求 | 许可证 | |---|---|---|---| | **overture** | Meta/Microsoft/Amazon 通过 S3 按 bbox 提供的开放 Places 数据集 | `duckdb` | CC-BY 4.0 | | **osm** | 通过 Overpass 获取的实时商家数据 —— 包含所有命名的商店/工艺/办公室及关键设施 | 无 | ODbL | | **socrata** | 来自市/县 Socrata 开放数据门户网站的近期已获得许可的商家 | 无 | 视门户网站而定 | | **npi** | 来自 CMS 注册表的每位美国医疗保健提供者（牙医/医生/诊所/药房） | 无 | 公共领域 | | **arcgis** | 发布在 ArcGIS 上的商家许可图层（指向图层 URL） | 无 | 视发布者而定 | | **foursquare** | 通过开源的 source.coop 镜像获取约 1 亿个地点（含网站+电话+社交媒体） | `duckdb` | Apache-2.0 | ``` python -m leadgen --vertical web_design --market "Boulder, Colorado" --sources overture osm socrata npi ``` 注意： - **osm** 是覆盖面最广的无需密钥的 *实时* 数据源 —— 涵盖所有商店、贸易、办公室以及 商家性质的设施（餐厅、诊所、酒店等……），而不是硬编码的列表。 - **npi** 在设计上没有网站字段，这使得其记录成为首选的 “需要一个网站”的潜在客户。使用 `config["npi_taxonomies"]` （例如 `["Dentist", "Chiropractor"]`）过滤专科。 - **socrata** / **arcgis** 是开放的 *政府* 数据：结构化但因司法管辖区而异，且覆盖不完整。通过 `config["socrata_datasets"]` / `config["arcgis_layers"]`（来自 hub.arcgis.com 的 `…/FeatureServer/0` URL）将它们指向特定的数据集，以获得可靠的结果。 - **foursquare** 覆盖最深，*同时也是最慢的* —— 开放镜像无法 按区域修剪，因此查询会扫描整个数据集（约 1-2 分钟）。这是一个冻结于 2024-11-19 的快照。将其用作可选的深度扫描，而不是默认选项。（Foursquare 自身的 实时 S3 bucket 现已需要账户权限；source.coop 镜像是无需密钥的路径。） ## 添加你自己的垂直领域 垂直领域是一个纯粹的数据类 —— 无需子类化。在 `leadgen/verticals/` 中放入一个文件，调用 `register(...)`，它就会出现在 CLI 和 GUI 中： ``` from leadgen import register, Vertical def _score(rec): score, why = 0, [] if not rec.get("website"): score += 60; why.append("NO WEBSITE") return score, ("A" if score >= 40 else "C"), "; ".join(why) register(Vertical( key="my_vertical", label="What I'm prospecting for", osm_tags=["shop=bakery", "amenity=cafe"], score_fn=_score, columns=[("Tier", "tier"), ("Score", "score"), ("Business", "name"), ("Phone", "phone"), ("Website", "website"), ("Why", "why")], )) ``` 可选钩子：`enrich_fn`（访问每个站点以获取更多信号），`opener_fn`（起草 推销话术），`suppression_fn`（剔除已由竞争对手服务的业务）。完整的操作指南 —— 包括可选的网站审查和竞争对手抑制 助手 —— 位于 **[`docs/ADD_A_VERTICAL.md`](docs/ADD_A_VERTICAL.md)** 中，并且 [`leadgen/verticals/web_design.py`](leadgen/verticals/web_design.py) 是其 参考实现。 ## 测试 纯逻辑和离线端到端测试，无需网络： ``` python leadgen/tests/test_engine.py python leadgen/tests/test_features.py python leadgen/tests/test_heuristics.py python gui/test_gui.py # skips cleanly if Flask isn't installed # 或者，使用 pytest： pytest leadgen/tests -q ``` ## 负责任地使用它 这是一个用于 **你自己的业务拓展** 的潜在客户挖掘工具。设计中内置了几项基本规则， 值得在此明确声明： - **它不自带任何数据。** 代码仓库只是一个工具；潜在客户文件是在每次运行时生成的，并且 已被 git 忽略。不要将抓取到的联系人数据提交到公开的仓库中。 - **尊重数据源。** Overture 是 CC-BY 的（在衍生作品中注明“Overture Maps Foundation”）；OSM 是 ODbL 的。网站审查工具会使用礼貌且可识别的 user-agent 抓取每个主页一次 —— 请将 `LEADGEN_UA` 设置为你自己的联系信息。 - **注意你所在地区的适用法律。** 转售抓取的个人联系数据可能会 触发数据经纪人注册要求（例如加利福尼亚州的 DELETE Act）和反垃圾邮件 规则（CAN-SPAM, CASL, GDPR）。为你自己的业务生成一份通话名单与出售该名单是完全不同的两码事 —— 请弄清楚你在做哪一种。 完整指南、各数据源许可证和归属说明：[`docs/RESPONSIBLE_USE.md`](docs/RESPONSIBLE_USE.md)。 ## 更多文档 - [`docs/COOKBOOK.md`](docs/COOKBOOK.md) — 实用指南，每个用例一个 - [`docs/ADD_A_VERTICAL.md`](docs/ADD_A_VERTICAL.md) — 构建你自己的垂直领域 - [`docs/RESPONSIBLE_USE.md`](docs/RESPONSIBLE_USE.md) — 许可证、归属、反垃圾邮件 - [`docs/ROADMAP.md`](docs/ROADMAP.md) — 100 项计划中的改进 - [`CONTRIBUTING.md`](CONTRIBUTING.md) · [`CHANGELOG.md`](CHANGELOG.md) ## 许可证 MIT —— 详见 [`LICENSE`](LICENSE)。你收集的数据带有其数据源的许可证要求 （Overture: CC-BY 4.0; OSM: ODbL）；如果你发布衍生作品，请按此进行归属说明。

标签：Python, 命令控制, 商业线索, 客户获取, 数据采集, 无后门, 桌面应用, 漏洞挖掘, 逆向工具