thomasproject-stack/signal-prospector

# Signal Prospector **一个基于信号、在免费基础设施上运行的 B2B 潜在客户开发引擎。** 它能发现刚进入“采购模式”的公司——例如获得融资、新领导层上任、招聘扩张、以及参与竞品或特定话题的互动——根据你的理想客户画像对它们进行评分，通过免费的 MX 验证邮件猜测来丰富决策者信息，并起草个性化、具备信号感知能力的外联信息。对于收到的回复，系统会提供可直接发送的 AI 草稿。 整个系统通过三种方式提供服务：一个 CLI，一个自助式 Flask 仪表盘，**以及一个 MCP server**，让你可以在 Claude 中通过自然语言进行潜在客户开发。  *Flask 仪表盘。上面的每一个评分和漏斗均由该引擎计算——此处展示的公司、联系人和信号均为说明性的演示数据，而非真实记录。' 潜在客户表格让评分过程透明化：每一行都包含其触发信号、丰富的联系人和电子邮件、生命周期状态，以及一段用通俗英语解释的**“为什么”**，说明该线索为何获得此评分。  ## 为什么它很有趣 大多数“潜在客户开发工具”要么是一个静态的线索列表，要么是一个黑盒。这款工具恰恰相反：它是一个透明的 检测 → 评分 → 丰富 → 起草 → 回复 → 优化 的循环，其中每一个数字都是可解释的，而且默认情况下所有的外部调用都是免费的。 - **一个契约背后的八大信号族。** 融资、职位变动、领导层变动、招聘、扩张、竞品互动、话题互动和新闻，每一个都是一个小型检测器，返回一个类型化的 `Signal`，注册在 registry 中，并由*注入的*免费 `search_fn` / `fetch_fn` 函数提供支持——因此，添加一个检测器或更换搜索后端只需直接插入即可。 - **一个可解释的 ICP 评分器，而不是一个排名黑盒。** 0–100 的评分是对*对的买家 × 对的时机*的精确加权混合（公式如下），并且每个潜在客户都会附带一段通俗英语的“为什么选这个线索”的原因字符串。 - **一个免费的邮件丰富瀑布流。** 决策者发现机制会解析公开的搜索片段，剥离 RTL/零宽 Unicode，然后从姓名+域名模式中推断出最可能的企业邮箱，并通过 DNS 验证域名——无需付费的丰富数据供应商，并且它绝不会编造一个无法组成的地址。 - **结构上的免费优先。** 发现机制使用的是自托管的 SearXNG；抓取机制是一个 `httpx → headless-browser → PDF` 的级联流程，并使用 `trafilatura` 进行提取；生成机制使用的是 DeepSeek（任何兼容 OpenAI 的 endpoint）。除非你主动配置密钥，否则付费的备用方案将保持关闭。 - **561 个测试**，覆盖了检测器、评分器、邮件丰富瀑布流、回复分类器和 Web 层。未知数据始终保持为 `n/a`，而不会被捏造。 ## 精确的评分机制 不搞虚假宣传——这正是线索评分的计算方式（`prospector/icp.py`）： | 数量 | 定义 | 备注 | |---|---|---| | **最终评分 (0–100)** | `100 × (0.55 · signal_score + 0.45 · icp_match)` | “对的时机”的权重略高于“对的买家” | | **icp_match (0–1)** | `0.45 · company_fit + 0.55 · contact_fit` | *人*比企业基础数据更重要 | | **company_fit** | 配置的行业 / 地理位置 / 规模 / 关键词检查的平均值 | 缺失的证据是**中性的**（0.5 基准）；只有正向匹配会提升分数，而命中 `exclude_keyword` 则是硬性的 **0** | | **signal_score (0–1)** | `clamp(best + 0.35·second + 0.12·third, 0..1)`，其中每一项都是 `strength × recency` | 最强的近期信号占主导地位；额外强烈、新鲜的信号会叠加一个衰减的加成 | | **strength** | 按类型划分的基础权重（funding `0.95`，leadership `0.9`，…） | 检测器可以为每个信号覆盖此值 | | **recency** | 阶梯式衰减：`≤7d → 1.0`, `≤30d → 0.85`, `≤90d → 0.55`, `≤180d → 0.3`，更早或未来的时间 → `0.15` | 未来的日期界限被视为陈旧，绝不会被视为“最新” | 因为缺失的证据是中性的而非惩罚性的，所以一个强烈的购买信号仍然可以显现出一个企业基础数据仅部分已知的线索——这正是*基于信号的*潜在客户开发的核心意义所在。 ## 精确的邮件瀑布流 信息丰富过程绝不会编造地址（`prospector/enrich.py`）： 1. 从公司网站解析出一个支持邮件的域名，拒绝那些永远不是公司自有邮件域名的聚合器/社交主机和网站构建器域名（`*.wixsite.com`, `*.github.io`, …）。 2. 根据个人姓名生成候选，最可能排在最前：`{first}.{last}` · `{first}` · `{f}{last}` · `{first}{l}` · `{first}_{last}` · `{last}` —— 去除 `al-`/`el-` 前缀，并拒绝不符合 RFC 规范的本地部分（像 `bisrat.d.@` 这样的单独首字母缩写绝不会出现）。 3. 通过 DNS 对域名进行分类：**verified**（发布了 MX），**risky**（可解析但无 MX），**invalid**（NXDOMAIN 或 RFC 7505 null-MX）。我们刻意不进行 Outbound-25 SMTP 探测。 ## 工作原理 ``` ICP (a preset, or auto-drafted from a website URL) │ ▼ 1. DETECT eight signal detectors ──► Signal[] prospector/signals/* │ (SearXNG discovery + free httpx→browser→PDF scrape cascade, │ trafilatura extraction, optional LLM entity refinement) ▼ 2. SCORE fit × signal-strength × recency ──► 0..100 prospector/icp.py │ + explainable "why this lead" reason ▼ 3. ENRICH decision-maker + email waterfall (MX-validated) prospector/enrich.py │ ▼ 4. DRAFT DeepSeek signal-aware outreach (+ A/B variants) prospector/outreach.py │ multilingual (en/ar/fr), draft-first (never auto-sent) ▼ 5. REPLY classify inbound + draft a response prospector/reply.py │ ▼ 6. OPTIMIZE weekly "what converts" feeds back into step 4 prospector/campaign.py Surfaces: CLI (cli.py) · Flask dashboard (prospector/web) · MCP server (prospector/mcp_server.py) Storage: SQLite (prospector/db.py) · Export: CSV / XLSX / HubSpot / Pipedrive ``` - **`prospector/signals/`** — 共享 `Signal` dataclass + `persist_signals` 背后的每个信号族对应一个检测器；一个 `registry` 使用注入的免费搜索/获取函数运行它们，因此检测器可以完全离线进行单元测试。 - **`prospector/icp.py`** — ICP 模型和上述透明的复合评分器。 - **`prospector/enrich.py`** — 联系人发现 + 邮件模式瀑布流 + 免费的 MX 验证。 - **`prospector/outreach.py` / `reply.py` / `campaign.py`** — 具备信号感知的草稿生成、回复分类，以及每周的优化循环。 - **`prospector/web/`** — 自助式 Flask 仪表盘（引导配置、运行进度、草稿审查、回复、导出）。 - **`cli.py` / `prospector/mcp_server.py`** — 通过 CLI 和 MCP stdio server 运行相同的引擎。 ## 技术栈 Python · Flask + waitress · SQLite · httpx · BeautifulSoup / lxml / trafilatura · feedparser · rapidfuzz · dnspython · openpyxl · DeepSeek (任何兼容 OpenAI 的 endpoint) · 自托管 SearXNG · MCP · pytest ## 本地运行 ``` python3 -m venv .venv && source .venv/bin/activate pip install -r requirements.txt pip install -e . # exposes the `prospector` command (same as `python cli.py`) cp .env.example .env # fill in DEEPSEEK_API_KEY etc. (all optional; it degrades) prospector selfcheck # verify config + external deps -> READY # 最快路径：从预设中植入 ICP，运行 pipeline，展示 leads prospector quickstart # ...或在浏览器中完成所有操作 prospector serve # http://127.0.0.1:8101 # ...或从 Claude 中驱动 prospector mcp # stdio MCP server (find_leads / draft_outreach / query_analytics / ...) ``` 手动 pipeline： ``` prospector init-icp "KSA RE developers" \ --titles "CEO,Managing Director,Head of Development" \ --industries "real estate,proptech" --geos "Saudi Arabia,Riyadh,GCC" \ --keywords "off-plan,residential,giga-project" --competitors "ROSHN,Dar Al Arkan" prospector run --icp "KSA RE developers" --limit 30 # detect -> score -> enrich -> draft prospector leads --min-score 70 prospector export --xlsx data/leads.xlsx ``` 完整命令列表：`quickstart`, `presets`, `init-icp` / `list-icp`, `detect`, `score`, `enrich`, `draft`, `run`, `replies ingest|list`, `export`, `notify`, `report` / `leads`, `serve`, `mcp`, `selfcheck`。 ## 安全默认设置 - **草稿优先** —— 不会自动发送任何内容。只有在 `EMAIL_AUTOSEND=1` **并且**配置了 SMTP 时才会发送邮件；LinkedIn 永远不会自动发送。 - **免费优先** —— 付费的备用方案（Serper, Firecrawl, CRM）在配置密钥前将保持关闭。 - **绝不捏造** —— 未知数据保持为 `n/a`；如果检测器无法将结果追溯到真实公司，则会跳过这些结果。 ## 数据与隐私 此代码仓库**仅包含代码**——没有线索、没有数据库、没有抓取的输出。`data/` 目录（SQLite DB、搜索缓存、会话密钥）和 `.env` 已被 gitignore 且从未发布。示例 ICP 预设列出了公开的房地产开发商，所有测试夹具均使用带有保留的 example.com 域名的虚构人物。 ## 项目结构 ``` prospector/ the engine: signals/ · icp · enrich · outreach · reply · campaign · db · web/ · mcp_server cli.py the `prospector` command surface tests/ 561 tests (detectors, scorer, enrichment, replies, web) deploy/ systemd unit + Caddy reverse-proxy snippet scripts/ nightly cron pipeline ``` ## License MIT — 请参阅 [LICENSE](LICENSE)。

标签：AI外联, B2B销售, Flask, MCP服务器, Splunk, 安全规则引擎, 客户线索挖掘, 运行时操纵, 逆向工具, 邮件验证