システム構成

Sales Clawアーキテクチャ

AI CLIで企業分析とメッセージ生成を行い、MCP Playwrightがブラウザ上でフォーム操作を実行。 最後に人の承認を挟むことで、自動化の速さと営業品質の安全性を両立します。

AI CLIが企業分析と文面作成を担当

Claude / Codex / Geminiを選び、営業リストや企業情報から送信候補ごとの提案文を組み立てます。

MCP Playwrightがフォーム操作を実行

フォーム構造を読み取り、入力・確認・スクリーンショット取得までブラウザ上で確実に進めます。

人の承認とローカル保存を中核に配置

送信前の確認、除外ルール、履歴保存を挟むことで、自動化しながら安全性を保ちます。

全体アーキテクチャ

Sales Claw は Electron デスクトップアプリとして動作します。ブラウザ UI（Next.js）と Node.js バックエンドが同一プロセス内で動き、外部の AI CLI と MCP Playwright を通じてタスクを実行します。

┌─────────────────────────────────────────────────────┐
│                 Sales Claw (Electron)                │
│                                                     │
│  ┌──────────────────┐    ┌──────────────────────┐  │
│  │  Dashboard UI    │    │  AI CLI Launcher     │  │
│  │  (Next.js SSR)   │◄──►│  (managed PTY)       │  │
│  │  Port 3765       │    │  claude / codex /    │  │
│  └──────────────────┘    │  gemini              │  │
│           │              └──────────┬───────────┘  │
│           │                         │               │
│  ┌────────▼─────────────────────────▼──────────┐  │
│  │           Dashboard Server (Express)         │  │
│  │  - REST API    /api/*                        │  │
│  │  - Settings    /api/settings                 │  │
│  │  - Logs        /api/log-action               │  │
│  │  - List Builder /api/list-builder/*          │  │
│  └──────────────────────────────────────────────┘  │
│           │                         │               │
│  ┌────────▼────────┐   ┌────────────▼───────────┐  │
│  │  Local Storage  │   │  MCP Playwright        │  │
│  │  settings.json  │   │  (Claude Code 経由で   │  │
│  │  action-log.json│   │   ブラウザ自動操作)    │  │
│  │  targets.xlsx   │   └────────────────────────┘  │
│  └─────────────────┘                               │
└─────────────────────────────────────────────────────┘

主要コンポーネント

1. Dashboard Server (`src/dashboard-server.cjs`)

Express.js ベースの HTTP サーバー。ポート 3765 でリッスンし、ダッシュボード UI と AI CLI の橋渡しをします。

• REST API エンドポイント（設定管理・ログ記録・承認フロー）
• AI CLI の PTY 起動・管理
• WebSocket による進行状況のリアルタイム配信
• セッショントークン認証（48 文字以上の hex）

2. Settings Manager (`src/settings-manager.cjs`)

data/settings.json を Single Source of Truth として管理します。 ファイルロック（排他制御）付きで書き込みを保護し、キャッシュによって頻繁な I/O を防ぎます。

3. Action Logger (`src/action-logger.cjs`)

全操作ログを data/action-log.json に記録。ログには会社名・アクション・詳細・タイムスタンプが含まれます。sentMessage フィールドは送信内容の証跡として保存されます（30 文字未満は 422 で拒否）。

4. Message Builder (`src/message-builder.cjs`)

AI CLI のプロンプトを組み立てるモジュール。buildMessagePrompt(analysis) が企業ごとの分析結果を受け取り、 Claude/Codex/Gemini が自然な日本語文面を生成するためのプロンプト構造を返します。

5. Parallel Analysis (`src/parallel-analysis.cjs`)

フェーズ A の企業分析を並列実行するサブプロセスエントリポイント。 AI CLI のサブエージェントから呼び出され、直接 HTTP フェッチで企業サイトを解析します。

6. List Builder (`src/list-builder/`)

8 ステージのパイプラインで企業リストを生成します。URL モード・自然言語モード・カテゴリモードの 3 種類の発見方法に対応。

データフロー

1社の処理フロー（Phase A + Phase B）

[Phase A: 並列・MCP なし]
  ↓ parallel-analysis.cjs を haiku サブエージェントで起動
  ↓ 企業サイト HTTP フェッチ → テキスト抽出
  ↓ company-analyzer.cjs で事業ドメイン・ギャップ分析
  ↓ message-builder.cjs でプロンプト構築
  ↓ templateDraft（フォールバック文面）生成
  ↓ POST /api/log-action → action: "site_analysis"

[Phase A.5: CLI メッセージ生成]
  ↓ CLI が messagePrompt を受け取り最終文面を生成
  ↓ POST /api/log-action → action: "message_draft"

[Phase B: 順次・MCP Playwright 使用]
  ↓ browser_navigate → 企業サイト / 問い合わせページ
  ↓ browser_snapshot → フォーム構造解析
  ↓ [NG判定] → POST /api/log-action → action: "skipped"
  ↓ browser_fill_form → 全フィールド入力
  ↓ POST /api/log-action → action: "form_fill"
  ↓ browser_take_screenshot → ss-{No}-input.png
  ↓ POST /api/log-action → action: "confirm_reached"
  ↓ POST /api/log-action → action: "awaiting_approval"
     ★ details.sentMessage 必須（30文字以上）

[承認フロー]
  ↓ ユーザーがダッシュボードでスクリーンショット確認
  ↓ 「送信」→ POST /api/log-action → action: "submitted"
     または「却下」→ action: "rejected"

ファイル構成

セキュリティ設計

• セッショントークン: 起動時に 48 文字以上の hex でランダム生成。x-sales-claw-session ヘッダーで認証。
• ローカル実行: 全データは手元 PC に保存。AI API には必要最小限のプロンプトのみ送信。
• 入力サニタイズ: 会社名・フォーム URL 等は HTML エスケープ・パストラバーサル防止処理済み。
• sentMessage ガード: 30 文字未満・placeholder 文言・screenshot 欠如のリクエストは 422 で拒否。
• ファイルロック: settings.json の書き込みは排他ロックで保護。