signal-scanner

シグナルスキャナー

TAM 対象企業とウォッチリストのペルソナを定期的にスキャンして購買シグナルを検出し、signals テーブルに書き込み、後続のアクティベーションを設定します。

使用するタイミング

• TAM Builder で企業とペルソナを登録した後
• タイミングに基づくアプローチのきっかけを検出するため、定期スキャン（日次／週次）を実行するとき
• 静的なリストから、インテントに基づくアプローチへ移行するとき

前提条件

• .env に SUPABASE_URL と SUPABASE_SERVICE_ROLE_KEY が設定されていること
• .env に APIFY_TOKEN が設定されていること（Phase 2 のシグナル用）
• .env に ANTHROPIC_API_KEY が設定されていること（任意。LLM によるコンテンツ分析用）
• tam-builder を使って TAM の企業が登録されていること
• Tier 1～2 の企業にウォッチリストのペルソナが作成されていること

シグナルの種類

優先度	シグナル	レベル	ソース	コスト
P0	従業員数の増加（90 日間で 10% 超）	企業	データ差分	無料
P0	テクノロジースタックの変更	企業	データ差分	無料
P0	資金調達ラウンド	企業	データ差分	無料
P0	関連職種の求人掲載	企業	Apify linkedin-job-search	約 $0.001／件
P1	リーダー層の転職	人物	Apify linkedin-profile-scraper	約 $3／1,000 件
P1	LinkedIn コンテンツ分析	人物	Apify linkedin-profile-posts + LLM	約 $2／1,000 件 + LLM
P1	LinkedIn プロフィールの更新	人物	Apify linkedin-profile-scraper	約 $3／1,000 件
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. 承認を得てから、データベースに書き込む実際のスキャンを実行します

これが重要な理由：

• シグナルはアプローチのタイミングを左右するため、誤ったシグナルは早すぎるアプローチにつながります
• monitoring から signal_detected への lead_status の変更は、多数のレコードにわたると元に戻すのが困難です
• スナップショットの更新は今後のシグナル差分に影響するため、不正確なスナップショットは後続のスキャンにも影響します
• エンリッチメントログのエントリーには、Apify のクレジット消費が記録されます

エージェントは初回実行時に --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	シグナルを検出しますが、DB には書き込みません。必ず最初に実行してください。
--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 を更新
• tool='apify'、action='search' または 'enrich'、および credits_used を含む enrichment_log エントリー

コンソール出力

• サマリー統計が 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