addashboard-cli 0.5.1 → 0.6.2

package/skills/ad-ops/scripts/adops.sh

@@ -0,0 +1,243 @@
+#!/usr/bin/env bash
+# ad-ops スキルの単一エントリポイント。
+#
+#   adops.sh preflight <platform> <accountId>   フェーズ0: ログイン + アカウント疎通確認
+#   adops.sh planner [--platform <媒体> --account <案件名>] [--stop]
+#                                               フェーズ2: プランナーをHTTPで開く (file:// 禁止)
+#   adops.sh plan [<入稿計画.json>]              フェーズ3: DL回収 + 要約 + lint + 合意との差分
+#   adops.sh open <platform> <accountId> [resource]  管理画面を開く (URLを手で組み立てない)
+#   adops.sh refs-import <platform> <accountId> [--write]  実アカウントから参照表を取り込む
+#
+# 覚えるコマンドを1本に畳むためのラッパー。個別の python3 -c / curl / ls -t を書かない。
+set -uo pipefail
+
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PORT=8799                      # cli/playwright.config.ts の webServer と同じポートを共用する
+URL="http://127.0.0.1:${PORT}/ad-planner.html"
+CLI="npx -y addashboard-cli@latest"
+
+die() { echo "✗ $*" >&2; exit 1; }
+
+# ---------------------------------------------------------------- preflight
+# フェーズ4の本実行で初めて 401 Account not found に気づく事故を防ぐ。
+# 戦略壁打ちを始める前にこれを通し、落ちたら戦略を練らずに止める。
+cmd_preflight() {
+  local platform="${1:-}" account="${2:-}"
+  [ -n "$platform" ] && [ -n "$account" ] \
+    || die "usage: adops.sh preflight <platform> <accountId>"
+
+  echo "▸ ログイン確認..."
+  local who
+  who="$($CLI auth whoami 2>&1)" || {
+    echo "$who" >&2
+    die "未ログイン、または認証が期限切れです。ターミナルで '$CLI auth login' を実行してください（Google SSO は本人が操作）"
+  }
+  python3 -c 'import json,sys; d=json.load(sys.stdin); print("  ✓", d.get("email"), "/ role:", d.get("role"))' <<<"$who" \
+    || die "whoami の応答を解釈できません: $who"
+
+  echo "▸ アカウント疎通確認 (${platform} / ${account})..."
+  local accounts
+  accounts="$($CLI list --platform "$platform" --resource accounts 2>&1)" \
+    || { echo "$accounts" >&2; die "アカウント一覧の取得に失敗しました"; }
+
+  ACCOUNT_ID="$account" python3 - <<'PY' <<<"$accounts"
+import json, os, sys
+want = os.environ["ACCOUNT_ID"]
+try:
+    accounts = json.load(sys.stdin).get("accounts", [])
+except Exception as e:
+    sys.exit(f"✗ アカウント一覧を解釈できません: {e}")
+hit = next((a for a in accounts if str(a.get("id")) == want), None)
+if hit:
+    print(f"  ✓ {want} — {hit.get('name')} （アクセス可能: 全{len(accounts)}件中）")
+    sys.exit(0)
+print(f"  ✗ accountId {want} は接続中の認証情報のスコープ外です（このまま入稿すると 401 Account not found）")
+print(f"  アクセス可能な {len(accounts)} 件:")
+for a in accounts:
+    print(f"    {a.get('id')}  {a.get('name')}")
+sys.exit(1)
+PY
+}
+
+# ------------------------------------------------------------------ planner
+# アクティブプラン.json = 「いま作業中の案件×媒体」を指す各自のローカル状態。
+# プランナーは起動時にこれを読んで案件と媒体を自動選択する (ad-planner.html の bootstrapBundled)。
+#
+# 書き出す実装がどこにも無かったため、リポジトリに commit された値が全環境へ配られ、
+# 「別案件で作ったアカウントが既定になり、毎回切り替えが要る」状態になっていた。
+# ここが唯一の書き出し口。ファイル自体は .gitignore 済みで追跡しない。
+write_active_plan() {
+  local platform="$1" account="$2" sample
+  case "$platform" in
+    yda)  sample='サンプルプラン.json' ;;
+    meta) sample='サンプルプラン_meta.json' ;;
+    *)    die "未知の媒体: ${platform}（yda / meta）" ;;
+  esac
+
+  # 参照データが無いまま指定するとプランナーが同梱デフォルトへ黙って落ちるので、先に止める
+  local acc_json="${SKILL_DIR}/アカウント/${platform}/${account}.json"
+  [ -f "$acc_json" ] \
+    || die "アカウント参照データがありません: アカウント/${platform}/${account}.json（先に adops.sh refs-import で取り込む）"
+
+  SKILL_DIR="$SKILL_DIR" PF="$platform" ACC="$account" SAMPLE="$sample" python3 - <<'PY'
+import json, os
+body = {
+    "_comment": "ad-ops スキルが書き出す『いま作業中のプラン』の指定。プランナーは起動時にこれを読み、媒体と案件（アカウント）を自動選択してサンプルプランを適用する。各自のローカル状態なので git では追跡しない。",
+    "platform": os.environ["PF"],
+    "accountName": os.environ["ACC"],
+    "samplePlanFile": os.environ["SAMPLE"],
+}
+with open(os.path.join(os.environ["SKILL_DIR"], "アクティブプラン.json"), "w", encoding="utf-8") as f:
+    json.dump(body, f, ensure_ascii=False, indent=1)
+    f.write("\n")
+print(f"✓ 作業中プランを設定: {os.environ['ACC']} / {os.environ['PF']}")
+PY
+}
+
+# file:// で開くと fetch('サンプルプラン.json') がブロックされ、
+# エラーも出ないまま空のプランナーが表示される。必ずHTTPで開く。
+cmd_planner() {
+  local platform='' account=''
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --stop)
+        pkill -f "http.server ${PORT}" && echo "✓ プランナーの配信を停止しました" \
+          || echo "（起動中のサーバーはありませんでした）"
+        return 0 ;;
+      --platform) platform="${2:-}"; shift 2 ;;
+      --account)  account="${2:-}";  shift 2 ;;
+      *) die "unknown option: $1（usage: adops.sh planner [--platform <媒体> --account <案件名>] [--stop]）" ;;
+    esac
+  done
+
+  if [ -n "$platform" ] || [ -n "$account" ]; then
+    [ -n "$platform" ] && [ -n "$account" ] \
+      || die "--platform と --account は両方指定してください"
+    write_active_plan "$platform" "$account"
+  fi
+
+  if curl -sf -o /dev/null "$URL"; then
+    echo "✓ 配信は起動済み（再利用）"
+  else
+    echo "▸ http.server を起動中 (port ${PORT})..."
+    # nohup でデタッチしないと、呼び出し元シェルの終了に巻き込まれて死ぬ
+    nohup python3 -m http.server "$PORT" --directory "$SKILL_DIR" \
+      >/tmp/adops-planner.log 2>&1 &
+    for _ in $(seq 1 20); do
+      curl -sf -o /dev/null "$URL" && break
+      sleep 0.3
+    done
+    curl -sf -o /dev/null "$URL" || die "配信を起動できませんでした（/tmp/adops-planner.log を確認）"
+    echo "✓ 起動しました"
+  fi
+
+  open "$URL"
+  echo "  $URL"
+  echo "  停止: adops.sh planner --stop"
+}
+
+# --------------------------------------------------------------------- plan
+cmd_plan() {
+  python3 "${SKILL_DIR}/scripts/plan_lint.py" "$@"
+}
+
+# --------------------------------------------------------------------- open
+# 管理画面URLの唯一の供給元。SKILL.md 本文や会話にURLをベタ書きしない
+# （ホスト名の記憶違いで存在しないURL(ads-display.yahoo.co.jp)を開く事故の根治）。
+#
+#   YDA : https://ads.yahoo.co.jp/manager/#/{mccId}/{accountId}/list/{resource}
+#   Meta: https://adsmanager.facebook.com/adsmanager/manage/{resource}?act={accountIdNum}
+#
+# resource は campaigns | adgroups | ads で受け、媒体別の語へ変換する
+# （中間層は YDA=adgroups / Meta=adsets。adsets 表記でも受ける）。
+#
+# ⚠ YDA はキャンペーン詳細への直リンクを表現できない（list/ 配下しかルートが無い）。
+#    一覧を開いて CP 名で探す。
+cmd_open() {
+  local platform="${1:-}" account="${2:-}" resource="${3:-campaigns}" dry="${ADOPS_OPEN_DRY:-}"
+  [ "${4:-}" = "--dry" ] && dry=1
+  [ "${3:-}" = "--dry" ] && { resource="campaigns"; dry=1; }
+  [ -n "$platform" ] && [ -n "$account" ] \
+    || die "usage: adops.sh open <platform> <accountId> [campaigns|adgroups|ads] [--dry]"
+
+  # 中間層のURL語彙は媒体で違う (YDA=adgroups / Meta=adsets)。
+  # プランナー側 (PLATFORMS[].consoleResourceMap) と同じ吸収をここでも行う。
+  # 素通しにすると `open meta ... adgroups` が存在しないビューを開く。
+  local key
+  case "$(printf '%s' "$resource" | tr 'A-Z' 'a-z')" in
+    campaigns|campaign) key=campaigns ;;
+    adgroups|adgroup|adsets|adset)   key=adgroups ;;
+    ads|ad)             key=ads ;;
+    *) die "resource は campaigns | adgroups (Meta では adsets) | ads のいずれかです: ${resource}" ;;
+  esac
+
+  local url mcc
+  case "$platform" in
+    yda)
+      # mccId はアカウントJSON（v2）が唯一の供給元。未設定なら accountId で代替する。
+      mcc="$(ACCOUNT_ID="$account" SKILL_DIR="$SKILL_DIR" python3 - <<'PY'
+import glob, json, os
+want, skill = os.environ["ACCOUNT_ID"], os.environ["SKILL_DIR"]
+paths = [p for p in glob.glob(os.path.join(skill, "アカウント", "yda", "*.json"))
+         if os.path.basename(p) != "index.json"]
+paths.sort(key=lambda p: os.path.basename(p) == "sample_account.json")
+for p in paths:
+    try:
+        d = json.load(open(p, encoding="utf-8"))
+    except Exception:
+        continue
+    if str(d.get("accountId", "")) == want:
+        print(str(d.get("mccId") or ""))
+        break
+PY
+)"
+      if [ -z "$mcc" ]; then
+        mcc="$account"
+        echo "⚠ アカウントJSONに mccId がありません。accountId (${account}) で代替します。" >&2
+        echo "  404 / 白画面になったら、管理画面URLの '#/{ここ}/' の値を控えて" >&2
+        echo "  アカウント/yda/<名前>.json に \"mccId\": \"...\" を追記してください。" >&2
+      fi
+      url="https://ads.yahoo.co.jp/manager/#/${mcc}/${account}/list/${key}"
+      ;;
+    meta)
+      # Meta の中間層は adsets (adgroups というルートは無い)
+      local mres="$key"; [ "$key" = "adgroups" ] && mres="adsets"
+      url="https://adsmanager.facebook.com/adsmanager/manage/${mres}?act=${account#act_}"
+      ;;
+    *) die "open が未対応の媒体です: ${platform}（yda / meta）" ;;
+  esac
+
+  echo "$url"
+  [ -n "$dry" ] || open "$url"
+}
+
+# --------------------------------------------------------------- refs-import
+# 実アカウントから見出し/説明文/オーディエンス/配置面を取り込み、アカウントJSONへマージする。
+# --write なしは差分表示のみ（dry-run 既定）。
+cmd_refs_import() {
+  python3 "${SKILL_DIR}/scripts/refs_import.py" "$@"
+}
+
+case "${1:-}" in
+  preflight)   shift; cmd_preflight "$@" ;;
+  planner)     shift; cmd_planner "$@" ;;
+  plan)        shift; cmd_plan "$@" ;;
+  open)        shift; cmd_open "$@" ;;
+  refs-import) shift; cmd_refs_import "$@" ;;
+  *)
+    cat >&2 <<EOF
+usage:
+  adops.sh preflight <platform> <accountId>   フェーズ0: ログイン + アカウント疎通確認
+  adops.sh planner [--platform <媒体> --account <案件名>] [--stop]
+                                              フェーズ2: プランナーをHTTPで開く
+                                              --platform/--account を渡すと「作業中プラン」を
+                                              設定してから開く（省略時は前回の設定を引き継ぐ）
+  adops.sh plan [<入稿計画.json>]              フェーズ3: DL回収 + 要約 + lint + 合意との差分
+  adops.sh open <platform> <accountId> [campaigns|adgroups|ads] [--dry]
+                                              管理画面を開く（URLを手で組み立てない）
+                                              中間層は YDA=adgroups / Meta=adsets に自動変換
+  adops.sh refs-import <platform> <accountId> [--write] [--campaign-id <id>]
+                                              実アカウントから参照表を取り込む（既定 dry-run）
+EOF
+    exit 2 ;;
+esac

package/skills/ad-ops/scripts/plan_lint.py

@@ -0,0 +1,357 @@
+#!/usr/bin/env python3
+"""入稿計画JSONの回収・要約・lint・合意差分を1コマンドで行う。
+
+`adops.sh plan` から呼ばれる。単体でも動く:
+
+    python3 plan_lint.py [<入稿計画.json>]
+
+引数を省略すると ~/Downloads と 入稿計画/ の中で最も新しい入稿計画を拾う。
+Downloads にあったものは 入稿計画/ へリネームして移動する。
+
+やること:
+  1. 回収 — DLに落ちた計画を 入稿計画/<案件名>_<CP名>_入稿計画_<timestamp>.json へ移動
+  2. 要約 — CP > 広告グループ > 広告 を1画面の表で出す
+  3. lint — dry-run が検出しない不備（相対finalUrl・paramCode衝突など）を拾う
+  4. 差分 — サンプルプラン.json（＝合意した内容の正）と突き合わせ、違う項目だけ出す
+"""
+import glob
+import json
+import os
+import re
+import shutil
+import sys
+import urllib.parse
+
+SKILL_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+PLAN_DIR = os.path.join(SKILL_DIR, "入稿計画")
+DOWNLOADS = os.path.expanduser("~/Downloads")
+
+# 新規モードの既定 12,000円 / 既存ASC の 5〜10万円 を包含するレンジ。
+# 外れたら桁間違いを疑う（エラーではなく確認を促す）。
+BUDGET_MIN, BUDGET_MAX = 3_000, 200_000
+SUSPICIOUS_NAME = re.compile(r"テスト|test|サンプル|sample|dummy|仮", re.I)
+
+errors: list[str] = []
+warns: list[str] = []
+
+
+def err(msg: str) -> None:
+    errors.append(msg)
+
+
+def warn(msg: str) -> None:
+    warns.append(msg)
+
+
+# --------------------------------------------------------------- 1. 回収
+def newest(pattern: str) -> str | None:
+    hits = glob.glob(pattern)
+    return max(hits, key=os.path.getmtime) if hits else None
+
+
+def load_account(platform: str, account_id: str) -> dict:
+    """accountId からアカウントJSONを引く。見つからなければ空dict。
+
+    sample_account.json は雛形として実アカウントと同じ accountId を持つため、
+    実データを優先して最後に回す（先に拾うと案件名が 'sample_account' になる）。
+    """
+    paths = [
+        p for p in glob.glob(os.path.join(SKILL_DIR, "アカウント", platform, "*.json"))
+        if os.path.basename(p) != "index.json"
+    ]
+    paths.sort(key=lambda p: os.path.basename(p) == "sample_account.json")
+    for path in paths:
+        try:
+            data = json.load(open(path, encoding="utf-8"))
+        except Exception:
+            continue
+        if str(data.get("accountId", "")) == str(account_id):
+            return data
+    return {}
+
+
+def collect(path: str, plan: dict) -> str:
+    """Downloads にある計画を 入稿計画/ へリネーム移動する。移動後のパスを返す。"""
+    if os.path.dirname(os.path.abspath(path)) != os.path.abspath(DOWNLOADS):
+        return path
+
+    platform = plan.get("platform", "yda")
+    account = load_account(platform, plan.get("accountId", ""))
+    project = account.get("name") or plan.get("accountId", "plan")
+    campaigns = plan.get("campaigns") or []
+    cp = (campaigns[0].get("name") if campaigns else "") or "no-campaign"
+    stamp = re.search(r"(\d{8}-\d{6})", os.path.basename(path))
+    stamp = stamp.group(1) if stamp else "unknown"
+
+    safe = lambda s: re.sub(r"[/\\:\s]+", "_", str(s)).strip("_")
+    dest = os.path.join(PLAN_DIR, f"{safe(project)}_{safe(cp)}_入稿計画_{stamp}.json")
+    os.makedirs(PLAN_DIR, exist_ok=True)
+    shutil.move(path, dest)
+    print(f"📥 回収: ~/Downloads → 入稿計画/{os.path.basename(dest)}")
+    return dest
+
+
+def pick_plan(argv: list[str]) -> str:
+    if argv:
+        if not os.path.exists(argv[0]):
+            sys.exit(f"✗ ファイルが見つかりません: {argv[0]}")
+        return argv[0]
+    candidates = [
+        p
+        for p in (
+            newest(os.path.join(DOWNLOADS, "*入稿計画*.json")),
+            newest(os.path.join(PLAN_DIR, "*.json")),
+        )
+        if p
+    ]
+    if not candidates:
+        sys.exit("✗ 入稿計画JSONが見つかりません（~/Downloads にも 入稿計画/ にも）")
+    return max(candidates, key=os.path.getmtime)
+
+
+# ------------------------------------------------------- 共通: 値の取り出し
+def param_code_of(ad: dict, group: dict) -> str:
+    """広告グループの paramCode。
+
+    優先順: group.paramCode → finalUrl の ?ad= → 広告グループ名の【…】。
+    URLパラメータ無し運用（urlParamsEnabled: false）でも AG 名から復元できるようにする。
+    """
+    if group.get("paramCode"):
+        return str(group["paramCode"])
+    url = ad.get("finalUrl") or ""
+    q = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)
+    code = (q.get("ad") or [""])[0]
+    if code:
+        return code
+    m = re.search(r"【([^】]+)】", str(group.get("name") or ""))
+    return m.group(1) if m else ""
+
+
+def image_no_of(ad: dict) -> str:
+    """画像番号。ad.imageNo → creative パラメータ → 広告名 '1047c-...' の順で復元する。"""
+    if ad.get("imageNo"):
+        return str(ad["imageNo"])
+    url = ad.get("finalUrl") or ""
+    q = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)
+    m = re.search(r"-(\d+)[a-z]-", (q.get("creative") or [""])[0])
+    if m:
+        return m.group(1)
+    m = re.match(r"^(\d+)[cs]-", str(ad.get("adName") or ""))
+    return m.group(1) if m else ""
+
+
+def resolve_media_path(raw: str, base_dir: str) -> str:
+    """CLI の resolveLocalMediaPath と同じ規則でローカル画像パスを解決する。
+
+    `~` 展開 → 絶対はそのまま → 相対は計画JSONのあるディレクトリ基準。
+    """
+    p = os.path.expanduser(str(raw or ""))
+    return p if os.path.isabs(p) else os.path.normpath(os.path.join(base_dir, p))
+
+
+def ad_groups(campaign: dict) -> list:
+    return campaign.get("adGroups") or campaign.get("adSets") or []
+
+
+# --------------------------------------------------------------- 2. 要約
+def summarize(plan: dict) -> None:
+    print(f"\n── 入稿計画 ── platform={plan.get('platform', 'yda')} "
+          f"accountId={plan.get('accountId')} planVersion={plan.get('planVersion')}")
+    for ci, c in enumerate(plan.get("campaigns") or []):
+        bid = c.get("biddingStrategy", "")
+        if c.get("targetCpa"):
+            bid += f" (tCPA {c['targetCpa']:,})"
+        print(f"\n  CP[{ci}] {c.get('name')}")
+        print(f"        予算 {c.get('budget', 0):,}/日 | {bid} | status {c.get('status')} "
+              f"| 開始 {c.get('startDate', '-')}")
+        for g in ad_groups(c):
+            tg = "/".join(filter(None, [
+                ",".join(g.get("devices") or g.get("devicePlatforms") or []) or "全デバイス",
+                ",".join(g.get("ages") or []) or "全年齢",
+                ",".join(g.get("genders") or []) or "全性別",
+            ]))
+            print(f"    AG  {g.get('name')} | {tg} | status {g.get('status')}")
+            for a in g.get("ads") or []:
+                media = ",".join(a.get("mediaIds") or []) or a.get("videoId") or a.get("imageHash") or "-"
+                head = (a.get("headlines") or ["（空）"])[0]
+                print(f"      AD  media {media} | 画像No {image_no_of(a) or '-'} | {head}")
+                print(f"          {a.get('finalUrl')}")
+
+
+# --------------------------------------------------------------- 3. lint
+def lint(plan: dict, plan_path: str = "") -> None:
+    platform = plan.get("platform", "yda")
+    account = load_account(platform, plan.get("accountId", ""))
+    # キー無し = true（従来挙動）。アカウントJSON v2 の追加キーなので .get() で読む。
+    url_params = account.get("urlParamsEnabled", True) is not False
+    base_dir = os.path.dirname(os.path.abspath(plan_path)) if plan_path else os.getcwd()
+    base = account.get("baseArticleUrl") or ""
+    base_host = urllib.parse.urlparse(base).netloc if base else ""
+    known_codes = {
+        str(v.get("paramCode"))
+        for v in (account.get("refs", {}).get("adGroups") or {}).values()
+        if v.get("paramCode")
+    }
+
+    if not base:
+        warn(f"アカウントJSONに baseArticleUrl がありません（{platform}/{plan.get('accountId')}）。"
+             " finalUrl が相対パスになる原因になります")
+
+    seen_media: dict[str, str] = {}
+    for c in plan.get("campaigns") or []:
+        name = c.get("name", "")
+        budget = c.get("budget") or 0
+        if not (BUDGET_MIN <= budget <= BUDGET_MAX):
+            warn(f"CP「{name}」の日予算 {budget:,} が想定レンジ外（{BUDGET_MIN:,}〜{BUDGET_MAX:,}）。桁を確認してください")
+        if c.get("status") == "ACTIVE":
+            warn(f"CP「{name}」が ACTIVE です。初回・PoC は PAUSED（配信オフ）を推奨します")
+        if SUSPICIOUS_NAME.search(name):
+            warn(f"CP名「{name}」に検証用らしき語が残っています。本番入稿の命名か確認してください")
+
+        for g in ad_groups(c):
+            gname = g.get("name", "")
+            if SUSPICIOUS_NAME.search(gname):
+                warn(f"広告グループ名「{gname}」に検証用らしき語が残っています")
+            # 方針: スマートターゲティングは常時 ON。明示 false は事故を疑う
+            if g.get("smartTargeting") is False:
+                warn(f"広告グループ「{gname}」の smartTargeting が false です"
+                     f"（方針は常時ON）。意図的でなければ外してください")
+            for a in g.get("ads") or []:
+                url = a.get("finalUrl") or ""
+                if not re.match(r"https?://", url):
+                    err(f"CP「{name}」の finalUrl が相対パスです: {url}\n"
+                        f"        → アカウントJSONの baseArticleUrl 未設定。"
+                        f"**dry-run はこれを検出しません**")
+                elif base_host and urllib.parse.urlparse(url).netloc != base_host:
+                    warn(f"CP「{name}」の finalUrl のホストがアカウントの baseArticleUrl "
+                         f"({base_host}) と違います: {urllib.parse.urlparse(url).netloc}")
+
+                media = a.get("mediaIds") or []
+                if not media and not a.get("videoId") and not a.get("imageHash"):
+                    err(f"CP「{name}」の広告にクリエイティブがありません（mediaIds が空）")
+                for m in media:
+                    if m in seen_media:
+                        warn(f"mediaId {m} が複数の広告で使われています"
+                             f"（{seen_media[m]} / {name}）。画像検証なら重複は想定外です")
+                    else:
+                        seen_media[m] = name
+
+                # mediaIds（解決済み）と imagePaths の同時指定は **サイレントな取り違え**。
+                # CLI はアップロードした mediaId を末尾に追記するだけで、backend は
+                # mediaIds[0] しか使わない → 新画像は登録されるのに広告は旧画像のまま。
+                if media and (a.get("imagePaths") or []):
+                    err(f"CP「{name}」の広告に mediaIds と imagePaths が両方あります"
+                        f"（{a.get('adName') or ''}）\n"
+                        f"        → アップロードされた画像は広告に使われません"
+                        f"（backend は mediaIds[0] のみ使用）。差し替えたいなら mediaIds を空にし、"
+                        f"既存画像のままでよいなら imagePaths を消してください")
+
+                # ローカル画像パスの存在チェック（dry-run は検出しない）
+                for raw in a.get("imagePaths") or []:
+                    resolved = resolve_media_path(raw, base_dir)
+                    if not os.path.isfile(resolved):
+                        err(f"CP「{name}」の imagePaths のファイルが見つかりません: {raw}\n"
+                            f"        → 解決先 {resolved}（相対パスの基準は計画JSONのディレクトリ "
+                            f"{base_dir}）")
+
+                query = urllib.parse.urlparse(url).query
+                if not url_params and query:
+                    warn(f"CP「{name}」は urlParamsEnabled: false ですが finalUrl に"
+                         f" クエリが付いています: ?{query}")
+                # 相対/空 URL は上で ERROR 済みなので二重に鳴らさない
+                if url_params and not query and re.match(r"https?://", url):
+                    err(f"CP「{name}」の finalUrl に URLパラメータがありません: {url}\n"
+                        f"        → パラメータ無し運用ならアカウントJSONに"
+                        f" \"urlParamsEnabled\": false を入れてください")
+
+                code = param_code_of(a, g)
+                if not code:
+                    if url_params:
+                        err(f"CP「{name}」の paramCode が特定できません")
+                    else:
+                        warn(f"CP「{name}」の paramCode が特定できません"
+                             f"（urlParamsEnabled: false のため WARN 止まり）。"
+                             f"広告グループ名に【コード】を入れると復元できます")
+                elif code in known_codes:
+                    err(f"paramCode {code} はアカウントの既存広告グループと重複しています"
+                        f"（{name}）。新規なら未使用の番号に変えてください")
+
+
+# --------------------------------------------------------------- 4. 差分
+def flatten(plan: dict, is_sample: bool) -> dict:
+    """サンプルプラン(schemaVersion 3)と入稿計画(planVersion 1)を同じ形に潰して比較可能にする。"""
+    out: dict[str, object] = {"CP数": len(plan.get("campaigns") or [])}
+    for ci, c in enumerate(plan.get("campaigns") or []):
+        p = f"CP[{ci}]"
+        out[f"{p}.name"] = c.get("name")
+        out[f"{p}.budget"] = c.get("budget")
+        out[f"{p}.tCPA"] = c.get("tcpa") if is_sample else c.get("targetCpa")
+        groups = ad_groups(c)
+        out[f"{p}.広告グループ数"] = len(groups)
+        for gi, g in enumerate(groups):
+            gp = f"{p}.AG[{gi}]"
+            out[f"{gp}.name"] = g.get("name")
+            ads = g.get("ads") or []
+            out[f"{gp}.広告数"] = len(ads)
+            for ai, a in enumerate(ads):
+                out[f"{gp}.AD[{ai}].paramCode"] = param_code_of(a, g)
+                out[f"{gp}.AD[{ai}].画像No"] = image_no_of(a)
+    return out
+
+
+def diff_against_sample(plan: dict) -> None:
+    platform = plan.get("platform", "yda")
+    sample_path = os.path.join(
+        SKILL_DIR, "サンプルプラン_meta.json" if platform == "meta" else "サンプルプラン.json"
+    )
+    if not os.path.exists(sample_path):
+        print("\n（サンプルプランが無いため差分比較をスキップしました）")
+        return
+    sample = json.load(open(sample_path, encoding="utf-8"))
+    if str(sample.get("accountId")) != str(plan.get("accountId")):
+        print(f"\n⚠ サンプルプランのaccountId({sample.get('accountId')})と入稿計画"
+              f"({plan.get('accountId')})が違うため差分比較をスキップしました")
+        return
+
+    a, b = flatten(sample, True), flatten(plan, False)
+    rows = [(k, a.get(k, "—"), b.get(k, "—")) for k in dict.fromkeys([*a, *b])
+            if str(a.get(k, "—")) != str(b.get(k, "—"))]
+
+    print("\n── 合意（サンプルプラン）との差分 ──")
+    if not rows:
+        print("  ✓ 差分なし（合意どおり）")
+        return
+    width = max(len(k) for k, _, _ in rows)
+    for k, want, got in rows:
+        print(f"  {k.ljust(width)}  {want} → {got}")
+    print("  ↑ この差分だけをユーザーに確認すること（全項目の読み上げはしない）")
+
+
+# ---------------------------------------------------------------- main
+def main() -> int:
+    path = pick_plan(sys.argv[1:])
+    plan = json.load(open(path, encoding="utf-8"))
+    path = collect(path, plan)
+    print(f"📄 {path}")
+
+    summarize(plan)
+    lint(plan, path)
+    diff_against_sample(plan)
+
+    print("\n── lint（dry-run が検出しない項目）──")
+    for m in errors:
+        print(f"  ERROR  {m}")
+    for m in warns:
+        print(f"  WARN   {m}")
+    if not errors and not warns:
+        print("  ✓ 問題なし")
+
+    if errors:
+        print(f"\n✗ ERROR {len(errors)}件。修正するまで本実行しないこと")
+        return 1
+    print(f"\n✓ ERROR なし{f'（WARN {len(warns)}件は要確認）' if warns else ''}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())