enzostrano/huntova-public
GitHub: enzostrano/huntova-public
一款开源本地优先的 AI 驱动销售获客智能体集群，用命令行替代 Apollo/Clay/Hunter 等商业 SaaS，从线索搜索、评分、个性化邮件撰写到多轮跟进和回复检测一站式完成。
Stars: 1 | Forks: 0
# Huntova
**您的 AI 销售团队。本地优先。开源。**
Huntova 是一个用于主动出击的开源智能体集群。**Hunter** 在实时网络上寻找潜在客户。**Researcher** 爬取每个站点以获取切入点。**Composer** 起草个性化电子邮件。**Sequencer** 安排后续跟进。**Inbox-watcher** 对回复进行分类。**Pre-flight** 审计您的发送域名。**Coach** 展示哪些策略有效。每个智能体都在本地、您的机器上运行，并使用*您的* AI 密钥。
```
pipx install huntova
huntova onboard # 60-second TUI wizard, OS keychain
huntova hunt --max-leads 5 # short demo run; full hunts take longer
```
更喜欢 Web 向导？运行 `huntova onboard --browser` 跳过 TUI，直接在浏览器中配置提供商。
或者通过 curl：
```
# 一旦 huntova.com 部署完成：
curl -fsSL https://huntova.com/install.sh | sh
# 或者直接通过 GitHub raw URL（目前可用）：
curl -fsSL https://raw.githubusercontent.com/enzostrano/huntova-public/main/static/install.sh | sh
```
或者通过克隆公共代码库：
```
git clone https://github.com/enzostrano/huntova-public.git
cd huntova-public
# 明确使用 Python 3.11+（macOS 默认版本为 3.9，版本过旧）
python3.13 -m venv .venv # or python3.11 / python3.12
source .venv/bin/activate
# 升级 pip — 仅 pyproject.toml 安装需要 pip 21.3+
pip install --upgrade pip
pip install -e .
huntova onboard
```
## 它的功能
1. **Sweep** — 由 SearXNG 驱动的网络搜索，涵盖 Google、Bing、DuckDuckGo。每次寻找执行 60–80 个 AI 生成的查询，并进行噪音过滤。
2. **Score** — 每个潜在客户根据五个维度进行评级：匹配度、购买意向、可触达性、服务机会 和 时机。
3. **Qualify** — 高匹配度的线索将获得 Playwright 深度爬取：关于、团队、联系方式、近期帖子。智能体会像销售人员一样阅读页面。
4. **Draft** — 个性化的冷邮件 + LinkedIn 留言，其定制内容均基于智能体实际找到的证据。
5. **Learn** — 每一次“合适 / 不合适”的评分都会更新每个用户的指令摘要（每收集 3 个信号重建一次），智能体在下一次寻找时会读取该摘要。在获得足够的反馈后，智能体的评分指导将转向*您*所定义的“合适”。
您的线索、草稿和寻找历史记录存储在本地 SQLite 文件中，路径为
`~/.local/share/huntova/db.sqlite`。没有中央服务器。无需订阅。
## 60 秒冷邮件流水线
```
huntova examples install solo-coach # auto-seeds ICP + tone (10 playbooks)
huntova recipe run solo-coach # ~3 minutes, ~25 leads
huntova outreach send --top 5 --dry-run # preview AI-drafted emails
huntova outreach send --top 5 --max 5 # deliver via your SMTP
```
三条命令。真实的潜在客户。真实的个性化电子邮件。您的 AI 密钥，您的 SMTP，您的机器。除了访问您 SearXNG 的搜索查询和发往您提供商的外发邮件外，没有任何数据会离开您的笔记本电脑。
## 完整的本地优先冷邮件技术栈
以下命令涵盖了您原本需要跨多个商业 SaaS 订阅才能拼凑出的完整主动出击步骤——所有操作均使用*您*控制的凭证，并在您的机器上运行：
```
huntova playbook install solo-coach # 10 bundled ICP playbooks, auto-seed wizard
huntova hunt --max-leads 25 # find prospects (search → score → save)
huntova research --batch 5 --above 8 # deep-crawl 14 pages × 5 leads, rewrite openers
huntova outreach send --top 5 --research-above 8 # send research'd Step 1 (auto-enrols Step 2/3)
huntova sequence run --max 25 # Day +4 bump, Day +9 final, paused on reply
huntova inbox watch --interval 300 # IMAP poll + AI-classify replies (interested/OOO/etc)
huntova doctor --email # SPF / DKIM / DMARC / MX pre-flight
huntova pulse --since 7d # weekly self-coaching summary + next-action
huntova schedule print --target launchd # emit OS-native scheduled-job for daily auto-runs
```
| 主动出击功能 | 典型 SaaS 定价层级 | Huntova 命令 |
|---------------------|---------------------------|-----------------|
| 多页面个性化爬取 | 企业版 (~$300+/月) | `huntova research` |
| 回复检测 + AI 分流 | 中级基于席位 (~$80–200/席位/月) | `huntova inbox watch` |
| 多步骤后续跟进序列 | 中级基于席位 (~$99/席位/月) | `huntova sequence run` |
| 投递预检 | 专用 SaaS (~$30/月) | `huntova doctor --email` |
| 辅导 / KPI 摘要 | 中级 (~$99/月) | `huntova pulse` |
| 定时任务自动驾驶 | 中级 (~$97/月) | `huntova schedule print` |
### 自主每日模式
完成一次性设置后，将节奏配置为自动运行：
```
huntova schedule print --target launchd --at 09:00 \
> ~/Library/LaunchAgents/com.huntova.daily.plist
launchctl load ~/Library/LaunchAgents/com.huntova.daily.plist
```
(Linux: `--target systemd` 输出一个用户定时器 + 服务。) 现在
`huntova sequence run`、`huntova inbox check` 和 `huntova pulse`
将每日按计划触发。完全解放双手的冷 outreach，使用您自己的密钥，在您自己的机器上运行。
其他实用命令：
```
huntova playbook ls # 10 bundled playbooks (alias: examples)
huntova research # deep-research one lead, rewrite the opener
huntova research --batch 5 --above 8 # batch-research the top 5 unsent leads
huntova ls --status replied # quick filter shortcut
huntova ls --reply-class interested # only the IMAP-classified positive replies
huntova ls --min-fit 8 # only fit ≥ 8 leads
huntova share --top 10 --title "Q2" # mint a /h/ URL of top leads
huntova share status # how many people clicked it
huntova pulse --since 30d # 30-day self-coaching summary
huntova sequence status # how many leads at each follow-up step
huntova inbox setup # one-time IMAP cred capture for reply detection
huntova schedule print # emit cron / launchd / systemd snippet
huntova hunt --explain-scores # show fit/buy/timing/reach breakdown per lead
huntova doctor # diagnostic — verifies install, plugins, AI key
huntova doctor --email # deliverability pre-flight (dnspython bundled)
huntova plugins create my-crm-sink # scaffold a plugin in ~/.config/huntova/plugins/
```
## 配置
运行 `huntova init` 后，您将拥有：
| 路径 | 内容 |
|------|----------|
| `~/.config/huntova/config.toml` | `preferred_provider`，可选的非机密默认值 |
| `~/.config/huntova/secrets.enc` | Fernet 加密的 API 密钥（在没有 OS 密钥链时的备选方案） |
| `~/.local/share/huntova/db.sqlite` | 所有线索、寻找记录、设置和学习数据 |
API 密钥在可用时存储在您的 OS 密钥链中（macOS Keychain、
Windows Credential Manager、Linux Secret Service）。如果不可用，则回退到
`~/.config/huntova/secrets.enc` 处的加密文件。最后的备选方案是
位于 `~/.config/huntova/secrets.json` 的 0600 权限锁定明文文件，使用时会发出警告。
### 通过环境变量覆盖
| 变量 | 用途 |
|----------|---------|
| `HV_ANTHROPIC_KEY` | Anthropic Console 密钥（默认提供商 — Claude） |
| `HV_GEMINI_KEY` | Google AI Studio 密钥 |
| `HV_OPENAI_KEY` | OpenAI Platform 密钥 |
| `HV_AI_PROVIDER` | `anthropic`（默认）/ `gemini` / `openai` / 另有 10 个选项 — 参见 `huntova onboard` |
| `APP_MODE` | `local`（CLI 默认）/ `cloud` |
| `HUNTOVA_DB_PATH` | 覆盖 SQLite 路径 |
| `DATABASE_URL` | 如果设置，则使用 Postgres 而不是 SQLite |
| `SEARXNG_URL` | 用于网络搜索的 SearXNG 实例 |
### 自托管 SearXNG（推荐）
Huntova 通过 [SearXNG](https://searxng.github.io/searxng/) 搜索网络，
这是一个尊重隐私的元搜索引擎。公共实例通常
会禁用 JSON API 以防止滥用，因此最干净的设置是
您自己运行 SearXNG。
最快的途径是使用 Docker：
```
docker run -d --restart=always \
--name=searxng \
-p 8888:8080 \
-v "$HOME/.config/huntova/searxng:/etc/searxng" \
-e BASE_URL=http://localhost:8888 \
-e INSTANCE_NAME=huntova-search \
searxng/searxng:latest
```
然后通过编辑
`~/.config/huntova/searxng/settings.yml` 并将 `json` 添加到
`search.formats` 中来启用 JSON API。重启容器。
设置 `SEARXNG_URL=http://127.0.0.1:8888`（或运行 `huntova init` 并
在提示时粘贴 URL），Huntova 将会使用它。
## 命令
```
# 首次运行 + 设置
huntova onboard # rich TUI wizard — picks a provider, saves the key, opens the dashboard
huntova doctor # full diagnostic — providers, SearXNG, plugins, AI key probe
huntova status # one-screen operational dashboard (server, daemon, providers, last hunt)
huntova test-integrations # live probe of every configured provider + SearXNG
# 日常使用
huntova # alias for `huntova serve`
huntova serve # boot local dashboard (default port 5050)
huntova hunt # one-shot headless hunt — streams leads to terminal
huntova ls [--filter X] # list saved leads (table or json, substring/field-prefix filter)
huntova lead # full detail for one lead (use --by-org for partial match)
huntova rm # permanently delete one lead (use --yes to skip prompt)
huntova history # list recent hunt runs (id, status, leads, queries)
huntova export # CSV/JSON export to stdout
# Outreach
huntova outreach send # AI-draft personalised cold emails for top leads, send via SMTP
huntova research # deep-research one lead (14-page crawl), rewrite the opener
huntova sequence run # send Day +4 bump + Day +9 final to enrolled leads
huntova sequence status # how many leads at each step
huntova sequence pause --lead-id # pause / resume one lead's cadence
huntova inbox setup # capture IMAP creds for reply detection
huntova inbox check # one-shot poll, prints scanned + matched count
huntova inbox watch # daemon loop, auto-pauses cadences on reply
# 分享 + recipes
huntova share # mint a public /h/ link
huntova share status # view-count for a published share
huntova examples ls # 10 bundled playbooks (auto-seed ICP + tone + queries)
huntova examples install # adopt a playbook in one command
huntova recipe run # run a recipe end-to-end
# 配置
huntova config show # render the active config (secrets redacted)
huntova config edit # open config.toml in $EDITOR
huntova config get # read a single key
huntova config set # write a single key
# Plugins
huntova plugins # list discovered plugins
huntova plugins create # scaffold ~/.config/huntova/plugins/.py
huntova plugins install # one-command install from the registry
huntova plugins contribute # registry PR flow shortcut
# Daemon (可选 — 重启后依然生效)
huntova daemon install # install launchd (macOS) or systemd --user (Linux) unit
huntova daemon status # current daemon state
huntova daemon logs # tail the unit's logs
# Metadata
huntova metrics show # in-app analytics for the dashboard tab
huntova update # upgrade to latest via pipx
huntova version # print version
```
### 从终端浏览线索
```
huntova ls --filter "country:Germany" # field-prefixed filter
huntova ls --filter aurora # substring scan across common text fields
huntova lead L3 # full detail for one lead
huntova lead "aurora" --by-org # partial-org-name lookup
huntova export --format csv > leads.csv # pipe-friendly export
```
### 分享寻找结果（增长循环）
```
huntova share --top 10 --title "Q2 prospects" # mints a public /h/ URL
```
分享的页面会渲染出每个线索及其 **Proof Pack** — 引用
证据、来源 URL、最新时间戳。排在后面的线索
会被视觉模糊，并配有一键 `huntova hunt --from-share `
命令，让接收者可以安装 Huntova 并在本地复现
完全相同的寻找结果。每个分享页面的底部都有带
`pipx install huntova` 复制按钮的固定底栏。
```
huntova hunt --from-share HYgJouz4J1k # fetch the share, adopt its country set, run a fresh hunt
```
### 插件（护城河）
```
huntova plugins # list discovered plugins
huntova plugins create my-crm # scaffold ~/.config/huntova/plugins/my_crm.py
```
插件挂载到智能体生命周期中：`pre_search`、`post_search`、
`pre_score`、`post_score`、`post_qualify`、`post_save`、`pre_draft`、
`post_draft`。它们从 `~/.config/huntova/plugins/*.py` 加载，
或者作为声明了 `huntova.plugins` 入口点的已发布包加载。
**wheel 中附带了 9 个参考插件**（每次运行时加载；可通过 `HV_DISABLE_BUNDLED_PLUGINS=1` 选择退出）：
- **`csv-sink`** — 将每个保存的线索追加到本地 CSV 文件中。通过在 `config.toml` 中配置 `[csv_sink] path = "~/leads.csv"` 或 `HV_CSV_SINK_PATH` 环境变量来设置。如果两者都未设置，则不执行任何操作。
- **`dedup-by-domain`** — 丢弃过去 30 天内出现过的域名的搜索结果（可通过 `[dedup] window_days = 30` 配置）。消除了多查询寻找中的第一大噪音源。
- **`slack-ping`** — 每出现一个新线索时，向 Slack 入站 webhook 发送 POST 请求。通过 `[slack_ping] webhook_url = "..."` 或 `HV_SLACK_WEBHOOK_URL` 环境变量配置。
- **`discord-ping`** — 每出现一个新线索时，向 Discord 入站 webhook 发送简短的 embed POST 请求。通过 `discord_webhook_url`（Settings → Integrations）或 `HV_DISCORD_WEBHOOK_URL` 环境变量配置。
- **`telegram-ping`** — 每出现一个新线索时，通过 bot API 向 Telegram 聊天发送短消息。需要同时设置 `telegram_bot_token` 和 `telegram_chat_id`（Settings → Integrations）或环境变量 `HV_TELEGRAM_TOKEN` / `HV_TELEGRAM_CHAT_ID`。
- **`whatsapp-ping`** — 每出现一个新线索时，通过 Twilio 发送 WhatsApp 消息。需要 `twilio_account_sid`、`twilio_auth_token`、`twilio_whatsapp_from`、`whatsapp_to`（Settings → Integrations）或环境变量 `HV_TWILIO_SID` / `HV_TWILIO_TOKEN` / `HV_TWILIO_WHATSAPP_FROM` / `HV_WHATSAPP_TO`。
- **`generic-webhook`** — 每保存一个线索时，向用户配置的 webhook 发送 JSON 负载的 POST 请求。通过顶层的 `webhook_url`（Settings → Webhooks）或 `HV_WEBHOOK_URL` 环境变量配置。如果设置了 `HV_WEBHOOK_SECRET`（来自 keychain 或环境变量），则会使用 HMAC-SHA256 对正文进行签名；签名位于 `X-Huntova-Signature: sha256=` 标头中。
- **`recipe-adapter`** — 读取 `HV_RECIPE_ADAPTATION` 环境变量，在搜索前将 winning_terms / suppress_terms / added_queries 应用于查询列表。
- **`adaptation-rules`** — 应用从配方适配卡生成的 AI 评分规则。闭环了 结果→调整→寻找 循环。
在 [huntova.com/plugins](https://huntova.com/plugins) 浏览包含功能披露的社区插件完整注册表
（以便您在安装前审计每个插件的具体功能）。
示例：一个 Slack 通知插件 —
```
class SlackPing:
name = "slack-ping"
version = "0.1.0"
def post_save(self, ctx, lead):
import urllib.request, json
url = "https://hooks.slack.com/services/..."
body = json.dumps({"text": f"new lead: {lead.get('org_name')}"}).encode()
urllib.request.urlopen(url, data=body, timeout=5)
```
将其放入 `~/.config/huntova/plugins/slack_ping.py`，每保存一个
线索就会在您的 Slack 上发出提示。下次寻找时无需重启即可生效。
### 验证设置
```
huntova doctor
```
报告内容：
- Python + 配置路径
- 已配置的提供商 + 密钥后端（keyring / 加密文件 / 明文）
- SearXNG 可达性 + JSON API 状态
- **向您的 AI 密钥发起的实时 5 token 往返测试** — 确认其确实可用，而不仅仅是已设置
- 各环境变量状态
`--quick` 跳过网络调用。
### 无头寻找示例
```
huntova hunt --countries Germany,France --max-leads 10
```
输出随智能体的运行进行流式传输：
```
[huntova] hunting in 2 countries: Germany, France
[huntova] cap: 10 leads
[huntova] streaming to ~/.local/share/huntova/db.sqlite (Ctrl-C to stop)
· Loading hunt brain
· Generating search queries
✓ [9/10] Aurora Studios · Germany · aurora-studios.de
✓ [8/10] Tessera Marketing · France · tessera-mkt.com
✓ [9/10] Helio Production · Germany · helio-prod.de
...
[huntova] hunt completed: 10 leads
[huntova] top 3:
· [9/10] Aurora Studios — Mid-size production house, recently launched a brand campaign
· [9/10] Helio Production — Recurring event series, gap in their post-production pipeline
· [8/10] Tessera Marketing — Boutique agency hiring for content roles
[huntova] view in dashboard: `huntova serve`
```
`--verbose` 解锁完整的日志 + 思维流。Ctrl-C 可以干净地
停止智能体。`huntova hunt` 和 `huntova serve` 共享
同一个 SQLite 文件，因此通过任一途径找到的线索都会在两者中显示。
## 提供商
| 提供商 | 何时选择 | 获取密钥 |
|----------|--------------|-----------|
| **Claude (Anthropic)**（默认） | 最高质量的评分，最佳的邮件草稿。Huntova 端到端均使用 Claude 构建。 | |
| **Gemini** | 免费额度，快速评分，良好的默认设置 | |
| **OpenAI** | 广泛的模型选择，GPT-5 推理能力 | |
共有 13 个提供商 — 参见 `huntova onboard` 获取完整列表（云服务、
本地 AI 服务器、自定义 OpenAI 兼容端点）。
稍后切换提供商：重新运行 `huntova onboard --force` 或编辑
`~/.config/huntova/config.toml`。
## 状态
**Alpha 阶段。** 代码库正从托管的 SaaS 转型为这种
CLI 形态。核心智能体（搜索/评分/资格审查/起草）已稳定；当前
转型正在重建存储 + 身份验证 + 提供商边缘部分。请在[问题页面](https://github.com/enzostrano/huntova-public/issues)上跟踪进度。
## 冒烟测试
```
APP_MODE=local DATABASE_URL= HV_ANTHROPIC_KEY=fake \
python tools/smoke_test_local.py
```
25 项检查，涵盖运行时功能、策略、数据库驱动、schema、
FastAPI 路由、自动登录、功能解锁以及 /download 页面。
## 许可证
AGPL-3.0-or-later。参见 [LICENSE](./LICENSE)。
## 贡献者
**大脑：** [@enzostrano](https://github.com/enzostrano) —
方向、架构，以及您所看到界面背后的每一个决策。
**编码：** [Claude (Anthropic)](https://www.anthropic.com)，运行在
[Claude Code](https://claude.com/claude-code) 上。根据 Enzo 的规范，
Claude 逐行、逐个提示词地编写了代码库中的几乎每一行。
如果没有 Anthropic 的模型，Huntova 将不复存在。**感谢
Anthropic 团队构建了孕育 Huntova 的工具。** 这就是为什么
Claude 是默认提供商的原因 — 它是真正发布这个项目的模型。
标签：AI销售团队, B2B销售, pipx, Playwright, PyRIT, Python, Python 3.11+, SearXNG, SEO, TUI, 个性化邮件, 冷邮件, 外呼营销, 多智能体系统, 客户寻找, 开源, 搜索引擎聚合, 收件箱分类, 数据隐私, 无后门, 无订阅, 替代Apollo, 替代Clay, 替代Hunter, 本地优先, 测试用例, 源码安装, 潜在客户挖掘, 潜在客户评分, 特征检测, 网页向导, 自动化代理, 自带密钥(BYOK), 获客代理, 请求拦截, 逆向工具, 邮件跟进, 销售智能, 销售漏斗, 销售自动化