lead-gen-crm

面向 OpenClaw 代理的端到端销售线索生成和 CRM 管道自动化。从网络搜索和目录中发现潜在客户，丰富联系数据，对潜在客户进行评分和资格鉴定，推送到 CRM（HubSpot、Pipedrive、Zoho），并运行自动电子邮件外展序列和后续跟进。在以下情况下使用：(1) 寻找新的潜在客户或潜在客户，(2) 通过电子邮件和公司信息丰富潜在客户数据，(3) 将潜在客户推送到 CRM，(4) 设置电子邮件外展活动，(5) 对潜在客户进行评分或筛选，(6) 管理销售渠道，或 (7) 自动执行后续序列。

## 概述（中文）

面向 OpenClaw 代理的端到端销售线索生成和 CRM 管道自动化。从网络搜索和目录中发现潜在客户，丰富联系数据，对潜在客户进行评分和资格鉴定，推送到 CRM（HubSpot、Pipedrive、Zoho），并运行自动电子邮件外展序列和后续跟进。在以下情况下使用：(1) 寻找新的潜在客户或潜在客户，(2) 通过电子邮件和公司信息丰富潜在客户数据，(3) 将潜在客户推送到 CRM，(4) 设置电子邮件外展活动，(5) 对潜在客户进行评分或筛选，(6) 管理销售渠道，或 (7) 自动执行后续序列。

## 原文

# Lead Gen + CRM Pipeline

Full lead generation pipeline — from discovery to CRM to outreach. Find prospects, enrich their data, qualify them, push to your CRM, and automate follow-up sequences.

## Setup

### Dependencies

```bash
pip3 install requests
```

### API Keys (configure in `config.json`)

- **Brave Search API** — lead discovery (already configured if web_search works)
- **Hunter.io** — email finding/verification (`HUNTER_API_KEY`, free 25 searches/mo)
- **HubSpot** — CRM integration (`HUBSPOT_API_KEY`)
- **Pipedrive** — CRM integration (`PIPEDRIVE_API_KEY` + `PIPEDRIVE_DOMAIN`)
- **Zoho** — CRM integration (`ZOHO_ACCESS_TOKEN`)
- **SendGrid or SMTP** — outreach emails (`SENDGRID_API_KEY` or SMTP config)

Not all are required — use what fits your stack.

### Workspace

```
lead-gen/
├── config.json           # API keys, CRM selection, scoring rules
├── leads/                # Lead database (JSON files)
│   ├── raw/              # Newly discovered leads
│   ├── enriched/         # Leads with contact data
│   ├── qualified/        # Scored and qualified
│   └── archived/         # Closed/rejected
├── campaigns/            # Outreach campaign configs
├── templates/            # Email templates
└── reports/              # Pipeline reports
```

Run `scripts/init-workspace.sh` to create this structure.

## Core Workflows

### 1. Lead Discovery

Find leads matching your ideal customer profile:

```bash
scripts/discover-leads.sh --query "ai agency owner" --count 20
scripts/discover-leads.sh --query "shopify store owner" --industry ecommerce --location "United States"
scripts/discover-leads.sh --directory yelp --category "marketing agencies" --location "Los Angeles"
```

Discovery sources:
- **Brave Search** — find companies/people matching criteria
- **Web scraping** — extract contact info from search results
- **Directory parsing** — structured business directories

Output: raw lead JSON files in `leads/raw/`.

### 2. Lead Enrichment

Add contact data and company info to raw leads:

```bash
scripts/enrich-lead.sh <lead-id>
scripts/enrich-leads.sh --batch raw    # Enrich all raw leads
```

Enrichment adds:
- **Email addresses** — via Hunter.io or pattern matching
- **Company info** — website, size, industry, tech stack
- **Social profiles** — LinkedIn, Twitter handles
- **Domain authority** — basic SEO metrics

### 3. Lead Scoring

Score leads based on configurable criteria:

```bash
scripts/score-leads.sh                  # Score all enriched leads
scripts/score-leads.sh --threshold 70   # Only qualify leads scoring 70+
```

Default scoring rubric (customizable in `config.json`):
- **Company size fit** (0-25) — matches your target
- **Industry match** (0-25) — in your target verticals
- **Email available** (0-20) — can reach them
- **Web presence** (0-15) — active website, social profiles
- **Tech signals** (0-15) — uses relevant technology

Leads scoring above threshold move to `leads/qualified/`.

### 4. CRM Integration

Push qualified leads to your CRM:

```bash
scripts/push-to-crm.sh <lead-id>
scripts/push-to-crm.sh --batch qualified   # Push all qualified leads
scripts/push-to-crm.sh --crm hubspot       # Override default CRM
```

Supported CRMs:
- **HubSpot** — creates contact + deal, sets pipeline stage
- **Pipedrive** — creates person + deal
- **Zoho** — creates lead record
- **CSV export** — fallback for any CRM via import

See `references/crm-setup.md` for per-CRM configuration.

### 5. Email Outreach

Run automated outreach campaigns with follow-ups:

```bash
scripts/create-campaign.sh --name "q1-outreach" --template cold-intro --leads qualified
scripts/send-campaign.sh --campaign "q1-outreach" --dry-run    # Preview first
scripts/send-campaign.sh --campaign "q1-outreach"              # Send for real
```

Campaign features:
- **Templates with variables** — personalized per lead
- **Multi-step sequences** — initial + 2-3 follow-ups
- **Delay between steps** — configurable (default 3 days)
- **Tracking** — opens, replies, bounces (via SendGrid)
- **Auto-pause** — stops sequence when lead replies
- **Human approval** — requires explicit approval before sending

**Critical: Never send without user approval.** `--dry-run` always first.

### 6. Pipeline Reports

```bash
scripts/pipeline-report.sh                 # Current pipeline summary
scripts/pipeline-report.sh --weekly        # Weekly activity report
scripts/pipeline-report.sh --conversion    # Conversion funnel metrics
```

## Email Templates

Store in `templates/` as JSON:

```json
{
  "name": "cold-intro",
  "subject": "Quick question about {company_name}",
  "body": "Hi {first_name},\n\nI noticed {company_name} is {personalization_hook}.\n\nWe help companies like yours {value_prop}.\n\nWould you be open to a quick chat this week?\n\nBest,\n{sender_name}",
  "follow_ups": [
    {
      "delay_days": 3,
      "subject": "Re: Quick question about {company_name}",
      "body": "Hi {first_name},\n\nJust following up on my previous note. {follow_up_hook}\n\nHappy to share more details if helpful.\n\nBest,\n{sender_name}"
    },
    {
      "delay_days": 7,
      "subject": "Last note from me",
      "body": "Hi {first_name},\n\nDon't want to be a pest — just one last check. If {value_prop_short} isn't a priority right now, no worries at all.\n\nIf timing changes, I'm here.\n\nBest,\n{sender_name}"
    }
  ]
}
```

## Safety & Compliance

- **CAN-SPAM / GDPR** — always include unsubscribe option
- **Rate limiting** — max 50 emails/day by default (configurable)
- **Bounce handling** — auto-remove bounced addresses
- **Never scrape emails from personal pages** — only business contacts
- **Always dry-run first** — no outreach without human review

## Cron Integration

- **Daily discovery** — run lead searches on schedule
- **Batch enrichment** — enrich new raw leads nightly
- **Follow-up sends** — check and send due follow-ups
- **Weekly pipeline report** — summarize funnel health

## References

- `references/crm-setup.md` — Setup guides for HubSpot, Pipedrive, Zoho
- `references/email-best-practices.md` — Deliverability, compliance, templates
- `references/scoring-customization.md` — How to tune the scoring model

---

## 中文说明

# 销售线索生成 + CRM 管道

完整的销售线索生成管道——从发现到 CRM 再到外展。发现潜在客户、丰富其数据、对其进行资格鉴定、推送到你的 CRM，并自动执行后续跟进序列。

## 设置

### 依赖

```bash
pip3 install requests
```

### API 密钥（在 `config.json` 中配置）

- **Brave Search API** — 线索发现（如果 web_search 可用则已配置）
- **Hunter.io** — 邮箱查找/验证（`HUNTER_API_KEY`，每月免费 25 次搜索）
- **HubSpot** — CRM 集成（`HUBSPOT_API_KEY`）
- **Pipedrive** — CRM 集成（`PIPEDRIVE_API_KEY` + `PIPEDRIVE_DOMAIN`）
- **Zoho** — CRM 集成（`ZOHO_ACCESS_TOKEN`）
- **SendGrid 或 SMTP** — 外展邮件（`SENDGRID_API_KEY` 或 SMTP 配置）

并非全部都是必需的——使用适合你技术栈的即可。

### 工作区

```
lead-gen/
├── config.json           # API keys, CRM selection, scoring rules
├── leads/                # Lead database (JSON files)
│   ├── raw/              # Newly discovered leads
│   ├── enriched/         # Leads with contact data
│   ├── qualified/        # Scored and qualified
│   └── archived/         # Closed/rejected
├── campaigns/            # Outreach campaign configs
├── templates/            # Email templates
└── reports/              # Pipeline reports
```

运行 `scripts/init-workspace.sh` 来创建此结构。

## 核心工作流程

### 1. 线索发现

查找符合你理想客户画像的线索：

```bash
scripts/discover-leads.sh --query "ai agency owner" --count 20
scripts/discover-leads.sh --query "shopify store owner" --industry ecommerce --location "United States"
scripts/discover-leads.sh --directory yelp --category "marketing agencies" --location "Los Angeles"
```

发现来源：
- **Brave Search** — 查找符合条件的公司/人员
- **网页抓取** — 从搜索结果中提取联系信息
- **目录解析** — 结构化的商业目录

输出：`leads/raw/` 中的原始线索 JSON 文件。

### 2. 线索丰富

为原始线索添加联系数据和公司信息：

`