signal-scanner

Signal Scanner

定期扫描器，可检测 TAM 公司和观察名单中的 personas 的购买信号，将其写入 signals 表，并为后续激活做好准备。

适用场景

• TAM Builder 已填充公司和 personas 后
• 定期扫描（每日／每周），检测基于时机的外联触发因素
• 需要从静态名单转向由意向驱动的外联时

前提条件

• .env 中配置了 SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY
• .env 中配置了 APIFY_TOKEN（用于 Phase 2 信号）
• .env 中配置了 ANTHROPIC_API_KEY（可选，用于大模型内容分析）
• 已通过 tam-builder 填充 TAM 公司
• 已为 Tier 1-2 公司创建观察名单 personas

信号类型

优先级	信号	层级	来源	成本
P0	员工人数增长（90 天内超过 10%）	公司	数据差异	免费
P0	技术栈变化	公司	数据差异	免费
P0	融资轮次	公司	数据差异	免费
P0	发布相关职位的招聘信息	公司	Apify linkedin-job-search	约 $0.001/职位
P1	领导层职位变动	人员	Apify linkedin-profile-scraper	约 $3/1k
P1	LinkedIn 内容分析	人员	Apify linkedin-profile-posts + 大模型	约 $2/1k + 大模型
P1	LinkedIn 个人资料更新	人员	Apify linkedin-profile-scraper	约 $3/1k
P2	新任 C-suite 高管	公司	根据人员扫描得出	免费

配置格式

完整架构请参阅 configs/example.json。主要部分：

• client_name — 要扫描哪位客户的 TAM
• signals.* — 根据阈值启用／禁用各类信号
• scan_scope — 按 tier、status、lead_status 筛选

数据库写入策略

重要：未经用户明确批准，绝不要写入信号或更新潜在客户状态。

信号扫描器会写入多个表：signals（插入）、enrichment_log（插入）、companies（更新快照）和 people（更新 lead_status）。这些写入会影响后续外联决策——错误的信号会导致错误的外联时机。

必须遵循的流程：

1. 始终先运行 --dry-run，检测信号但不写入数据库
2. 向用户展示试运行结果：信号数量、类型、最重要的信号，以及受影响的公司／人员
3. 运行不带 --dry-run 的命令前，先获得用户明确批准
4. 只有获得批准后，才能运行会写入数据库的实际扫描

原因：

• 信号会影响外联时机——错误的信号会触发过早外联
• 将 lead_status 从 monitoring 更改为 signal_detected 后，很难跨大量记录撤销
• 快照更新会影响未来的信号差异——错误的快照会连带影响后续扫描
• enrichment log 条目会记录 Apify 积分消耗

Agent 首次运行时绝不能传入 --yes。 --yes 标志仅用于已获预先批准的定时扫描，且用户已验证信号检测逻辑。

用法

# Dry run first (ALWAYS DO THIS) — detect signals without writing to DB
python skills/capabilities/signal-scanner/scripts/signal_scanner.py \
  --config skills/capabilities/signal-scanner/configs/my-client.json --dry-run

# Full scan (only after user reviews dry-run results and approves)
python skills/capabilities/signal-scanner/scripts/signal_scanner.py \
  --config skills/capabilities/signal-scanner/configs/my-client.json

# Test mode (5 companies max)
python skills/capabilities/signal-scanner/scripts/signal_scanner.py \
  --config configs/example.json --test --dry-run

# Free signals only (skip Apify)
# Set all Apify signals to enabled: false in config

标志

标志	效果
--config PATH	配置 JSON 的路径（必需）
--test	限制为 5 家公司、3 名人员
--yes	自动确认 Apify 成本提示。仅用于已获预先批准的定时扫描。
--dry-run	检测信号但不写入数据库。始终先运行此命令。
--max-runs N	覆盖 Apify 运行次数上限（默认值为 50）

输出

写入 Signals 表

每个信号包含：client_name、company_id、person_id、signal_level（company 或 person）、signal_type、signal_source、strength、signal_data（JSON）、activation_score、detected_at、acted_on、run_id。

其他数据库写入

• 当 activation_score >= 阈值时，将人员的 lead_status 更新为 signal_detected
• 更新公司 metadata._signal_snapshot，供下一轮差异比较使用
• 更新人员 raw_data._signal_snapshot，供下一轮差异比较使用
• enrichment_log 条目包含 tool='apify'、action='search' 或 'enrich'，以及 credits_used

控制台输出

• 将摘要统计信息打印到 stdout

激活评分

activation_score = strength * recency_multiplier * account_fit

Recency:   <24h = 1.5, 1-3d = 1.2, 3-7d = 1.0, 1-2w = 0.8, 2-4w = 0.5
Account:   Tier 1 = 1.3, Tier 2 = 1.0, Tier 3 = 0.7

Connects To

• Upstream: tam-builder (provides companies + people)
• Downstream: cold-email-outreach (acts on signals)

File Structure

signal-scanner/
├── SKILL.md
├── configs/
│   └── example.json
└── scripts/
    └── signal_scanner.py