# X自動集客ツール システム設計書

最終更新: 2026-03-19（実行方式・運用フロー追記）

---

## 概要

Google スプレッドシートをユーザーインターフェース兼データベース（ダッシュボード）として活用し、  
X (旧Twitter) API v2 を通じてターゲットユーザーの**検索・自動いいね・自動フォロー**、  
および Gemini API を用いた**AIリプライ案の自動生成**を行う Python 製自動化システム。

---

## 実行方式と運用フロー

### 現状：手動実行のみ

現状、本ツールは **`x_main.py` を手動で実行した時だけ動作**します。  
ほっておいて自動で動くわけではなく、実行のたびに1バッチ分の処理（検索・いいね・フォロー）を行い終了します。

```
手動で python x_main.py を実行
  → 検索・いいね・フォロー実行（1バッチ）
  → スプレッドシートに結果書き込み
  → 終了
```

> 定期的に自動実行させるには **Windows タスクスケジューラ** への登録が必要（未設定）。

### リプライだけは「半自動」

意図しない内容を自動送信するリスクを避けるため、リプライは人間の目視確認を挟む半自動フローを採用しています。

```
[ツール] ツイートを検索 → AIがリプライ案を自動生成 → スプレッドシートに書き込み
  ↓
[人間] リプライ案を目視確認 → OKなら「対象FLG②」列を TRUE に変更
  ↓
[ツール] 次回 x_main.py 実行時、FLG②=TRUE の行のみリプライを送信
```

いいね・フォローは `like_mode` / `follow_mode` が「自動」なら起動時に即時実行されます。

---



```
発達障害自助会集客/
├── 00_設計_ドキュメント/
│   └── X自動化_システム設計書.md     # 本ファイル
├── 01_X運用/
│   ├── x_main.py                      # メイン実行スクリプト（定期実行対象）
│   ├── x_api_client.py                # X API クライアント（検索・いいね・フォロー・投稿）
│   ├── x_sheets_writer.py             # スプレッドシート操作マネージャー
│   ├── comment_generator.py           # AI リプライ生成（Gemini API）
│   ├── 20260311.env                   # 環境変数（GEMINI_API_KEY 等）
│   └── x_automation.log               # 実行ログ（自動append）
├── 02_ブログ運用/
│   ├── update_wordpress_page.py       # WordPress API 更新スクリプト
│   └── ... (各種WP関連ファイル)
└── 99_Archive/
    └── ...（廃止ファイル群）
```

---

## スプレッドシート構成

**スプレッドシートID:** `1icqi5ZjqjRUOcGnxtDyHw1-gXj-osmGjB8twUnKB6i0`  
**認証ファイル:** `C:\Windows\LOCALSTRAGE\GoogleAntiGravity\00_Common\gen-lang-client-0965294635-8bc2247ad0d2.json`

### シート一覧

| シート名 | 用途 |
|---|---|
| 👥 アカウント管理 | 設定項目 + フォロー済みアカウントDB |
| 📋 ツイート管理 | 設定項目 + 取得ツイートDB + AIコメント案 |

### 設定エリアの列フォーマット（両シート共通）

| C列 | D列 | E列 |
|---|---|---|
| ラベル（日本語） | 変数名（英語キー） | 値 |

設定エリアとデータエリアの境界は**列Cの空白行**を検出して動的に判定する（`_detect_settings_end_row`）。

---

## 👥 アカウント管理シート 設定項目

| ラベル | 変数名 | 備考 |
|---|---|---|
| 親アカウントID | `parent_account_id` | 参照用（プログラムでは未使用） |
| 子アカウントID | `child_account_id` | 参照用（プログラムでは未使用） |
| 認証ページ | `auth_url` | 参照用 |
| APIキー | `api_key` | X Developer Portal から取得 |
| APIシークレットキー | `api_key_secret` | 同上 |
| AccessToken | `access_token` | OAuth 1.0a ユーザー認証トークン |
| AccessTokenシークレット | `access_token_secret` | 同上 |
| 最大処理件数 | `search_limit` | 検索取得件数の上限（最大100） |
| 最大いいね数/起動 | `like_limit_per_run` | 1回の起動でいいねする最大件数 |
| 最大フォロー数/起動 | `follow_limit_per_run` | 1回の起動でフォローする最大件数 |
| API呼び出し間隔（秒） | `sleep_interval` | 各アクション間のスリープ秒数 |
| フォロー実行モード | `follow_mode` | `自動` or `手動` |
| 検索キーワード | `search_keywords` | カンマ区切り（例: 発達障害,生きづらい） |
| 検索NGワード | `ng_words` | カンマ区切り（例: 副業,アフィリ） |
| URL付きツイートを除外 | `exclude_urls` | `TRUE` / `FALSE` |
| 一時中断FLG（フォロー） | `pause_follow` | `TRUE` でフォロー処理をスキップ |

---

## 📋 ツイート管理シート 設定項目

| ラベル | 変数名 | 備考 |
|---|---|---|
| 親アカウントID | `parent_account_id` | アカウント管理シートを参照（VLOOKUP） |
| 子アカウントID | `child_account_id` | 同上 |
| 最大いいね数/起動 | `like_limit_per_run` | アカウント管理シートを参照（VLOOKUP） |
| いいね実行モード | `like_mode` | `自動` or `手動` |
| API呼び出し間隔（秒） | `sleep_interval` | アカウント管理シートを参照（VLOOKUP） |
| AIモデル名 | `ai_model` | 例: `gemini-2.5-flash` |
| AIリプライ生成プロンプト | `ai_prompt` | リプライ案生成時のシステムプロンプト |
| テストモード（いいね） | `test_like` | `TRUE` で実際にいいねを送信しない |
| テストモード（リプライ） | `test_reply` | `TRUE` で実際にリプライを送信しない |
| 一時中断FLG（いいね・リプライ） | `pause_tweet` | `TRUE` でいいね・リプライ処理をスキップ |

---

## 動作フロー

```
x_main.py 起動
  │
  ├─[初期化] スプレッドシート接続 → 全設定取得 (get_settings)
  │          pause_follow / pause_tweet フラグ判定
  │          XApiClient(settings) 初期化（Bearer Token 自動生成）
  │
  ├─[フェーズ1] 承認済みリプライの送信
  │   ツイート管理シートをスキャン → 対象FLG②=TRUE かつ未送信 → reply_tweet()
  │
  └─[フェーズ2] 新規ターゲット検索 + 即時アクション
      │
      ├─ search_tweets(settings) → X API v2 クエリ発行
      │      クエリ例: (発達障害 OR "仕事 限界") -is:retweet -is:reply -has:links -"副業"
      │
      ├─ 各ツイートに対して:
      │    ├─ NGワード / 既存NG判定
      │    ├─ like_tweet()     ← like_limit_per_run に達するまで
      │    ├─ follow_user()    ← follow_limit_per_run に達するまで
      │    └─ generate_reply() ← 429時は 20s → 40s バックオフで最大3回リトライ
      │
      └─ アカウント管理シートへ upsert / ツイート管理シートへ append
```

---

## クラス・モジュール構成

### `XSheetsManager` (x_sheets_writer.py)

| メソッド | 概要 |
|---|---|
| `get_settings()` | 両シートの設定エリアを読み込み、統合 dict を返す |
| `get_registered_accounts()` | アカウント管理シートのデータ行を読込み |
| `upsert_account()` | アカウントを新規追記 or 既存行更新 |
| `append_tweet()` | ツイートを管理シート末尾に追加 |
| `get_reply_targets()` | 対象FLG②=TRUE のリプライ候補を返す |
| `_detect_settings_end_row()` | 設定エリア末尾行を動的検出 |
| `_detect_data_start_row()` | データ開始行を動的検出（設定行数に依存しない実装） |

### `XApiClient` (x_api_client.py)

| メソッド | 概要 |
|---|---|
| `__init__(settings)` | `settings` dict から認証情報を読み込み Tweepy Client を初期化。`token.json` 不使用。 |
| `search_tweets(settings)` | キーワード・NGワードから API クエリを生成し、ツイート一覧を返す |
| `like_tweet(tweet_id)` | 指定ツイートにいいね |
| `follow_user(user_id)` | 指定ユーザーをフォロー |
| `reply_tweet(tweet_id, text)` | 指定ツイートにリプライ送信 |

### `GeminiCommentGenerator` (comment_generator.py)

| 項目 | 詳細 |
|---|---|
| 使用 API | Google Gemini API (`google-genai`) |
| モデル | スプレッドシート `ai_model` 設定で切替可（例: `gemini-2.5-flash`） |
| プロンプト | スプレッドシート `ai_prompt` 設定で実行時変更可 |
| リトライ | 429 エラー時: 20秒待機 → 再試行 → 40秒待機 → 再試行（最大3回） |

---

## 認証情報の管理方針

| 認証情報 | 管理場所 | 備考 |
|---|---|---|
| X API Key / Secret | スプレッドシート（アカウント管理シート） | `token.json` は廃止 |
| X Access Token / Secret | 同上 | |
| Bearer Token | 自動生成（api_key + api_key_secretから） | 設定不要 |
| GEMINI_API_KEY | `.env` ファイル（`20260311.env`） | |
| GCP サービスアカウント | `00_Common/` 配下の共通JSONファイル | プロジェクト間で共有 |

---

## 運用上の注意事項

- **Gemini 無料枠の上限**: 15リクエスト/分。短時間に複数起動するとリトライが多発する。本番は1時間以上の間隔を推奨。
- **X API の制限**: `search_limit` を 10〜20 程度に留めることを推奨。フリープランでは月総リクエスト数に上限あり。
- **`pause_follow` / `pause_tweet`**: いずれかを `TRUE` にするとそのフェーズ全体をスキップ。安全装置として活用。
- **テストモード**: `test_like = TRUE` / `test_reply = TRUE` にすると、実際の API 送信を行わずログのみ出力。動作確認に使用。

---

## 実行環境と依存パッケージ

### 現状の実行環境

| 項目 | 内容 |
|---|---|
| 実行OS | Windows 10/11（ローカルPC） |
| Python バージョン | Python 3.10 |
| 実行方法 | 手動（`python x_main.py`） |
| 定期実行 | **未設定**（将来的に検討） |

### 必要な pip パッケージ

```bash
pip install tweepy gspread google-genai requests python-dotenv
```

| パッケージ | バージョン | 用途 | 標準ライブラリ? |
|---|---|---|---|
| `tweepy` | 最新 | X API v2 クライアント | ❌ 要インストール |
| `gspread` | 最新 | Google スプレッドシート操作 | ❌ 要インストール |
| `google-genai` | 最新 | Gemini AI リプライ生成 | ❌ 要インストール |
| `requests` | 最新 | Bearer Token 動的取得 | ❌ 要インストール |
| `python-dotenv` | 最新 | `.env` ファイル読み込み | ❌ 要インストール |
| `json`, `os`, `time`, `logging`, `datetime`, `abc`, `typing` | ― | 各種ユーティリティ | ✅ 標準ライブラリ |

### ⚠️ Mixhost（共有ホスティング）での制約

2026-03-19 時点で確認済み：

| パッケージ | Mixhostでの状況 |
|---|---|
| `tweepy` | ❌ 導入不可 |
| `gspread` | ❌ 導入不可 |
| `google-genai` | ❌ 導入不可 |
| `python-dotenv` | ❌ 導入不可 |
| `requests` | 要確認 |

**結論：現時点でMixhostへの本番移行は困難。**  
代替案として以下を検討：

| 案 | 概要 | コスト |
|---|---|---|
| **① 現状維持（手動/Windows）** | 手元PCから定期的に手動実行 | 無料 |
| **② Windows タスクスケジューラ** | 手元PC上で自動定期実行（PCの電源ON時のみ） | 無料 |
| **③ VPS（さくら/ConoHa等）** | 専用仮想サーバーでcron実行。パッケージ自由 | 月500〜1,000円程度 |
| **④ Google Cloud Run / Functions** | サーバーレスでPython実行。GCPと相性◎ | 従量課金（小規模なら無料枠内） |