addashboard-cli 0.6.0 → 0.6.2

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

@@ -2,8 +2,11 @@
 # ad-ops スキルの単一エントリポイント。
 #
 #   adops.sh preflight <platform> <accountId>   フェーズ0: ログイン + アカウント疎通確認
-#   adops.sh planner [--stop]                   フェーズ2: プランナーをHTTPで開く (file:// 禁止)
+#   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
@@ -57,13 +60,60 @@ 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() {
-  if [ "${1:-}" = "--stop" ]; then
-    pkill -f "http.server ${PORT}" && echo "✓ プランナーの配信を停止しました" \
-      || echo "（起動中のサーバーはありませんでした）"
-    return 0
+  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
@@ -91,16 +141,103 @@ 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 "$@" ;;
+  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 [--stop]                   フェーズ2: プランナーをHTTPで開く
+  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

@@ -111,24 +111,44 @@ def pick_plan(argv: list[str]) -> str:
 
 # ------------------------------------------------------- 共通: 値の取り出し
 def param_code_of(ad: dict, group: dict) -> str:
-    """広告グループの paramCode。export形式には無いので finalUrl の ?ad= から復元する。"""
+    """広告グループの 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)
-    return (q.get("ad") or [""])[0]
+    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:
-    """creative パラメータ '<code>-1047c-45L60-<code>' から画像番号を復元する。"""
+    """画像番号。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 []
 
@@ -159,9 +179,12 @@ def summarize(plan: dict) -> None:
 
 
 # --------------------------------------------------------------- 3. lint
-def lint(plan: dict) -> None:
+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 = {
@@ -189,6 +212,10 @@ def lint(plan: dict) -> None:
             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):
@@ -209,9 +236,42 @@ def lint(plan: dict) -> None:
                     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:
-                    err(f"CP「{name}」の paramCode が特定できません")
+                    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}）。新規なら未使用の番号に変えてください")
@@ -275,7 +335,7 @@ def main() -> int:
     print(f"📄 {path}")
 
     summarize(plan)
-    lint(plan)
+    lint(plan, path)
     diff_against_sample(plan)
 
     print("\n── lint（dry-run が検出しない項目）──")

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

@@ -0,0 +1,348 @@
+#!/usr/bin/env python3
+"""実アカウントから参照表（見出し・説明文・オーディエンス・配置面）を取り込む。
+
+`adops.sh refs-import <platform> <accountId> [--write]` から呼ばれる。単体でも動く:
+
+    python3 refs_import.py yda 1002811292 [--write] [--campaign-id 32430712]
+
+`webgram list` を campaigns / ads / resources の3系統で叩き、
+`アカウント/<platform>/<name>.json` にマージする。--write なしは差分表示のみ。
+
+━━ 採番アルゴリズム（最重要）━━
+既存の番号は **絶対に振り直さない**。既存番号は過去の入稿計画・広告名・
+`creative` パラメータに焼き込まれており、renumber は計測を壊す。
+
+  1. 比較用 norm(s): NFKC → trim → 連続空白畳み込み。**比較にのみ使い、保存は原文**
+  2. 既存 refs.titles を {norm(値): 番号} に反転
+  3. 取得した headline が既存に一致 → その番号を再利用
+  4. 未知は max(既存の整数キー)+1 から (adGroupId, adId) 昇順の初出順で採番（決定的）
+  5. 同一テキストが複数広告に出たら1番号に名寄せ
+  6. descriptions も同手順（独立した番号空間）
+  7. 消えた audiences / placements の ID は **削除せず "stale": true** を付ける
+"""
+import argparse
+import glob
+import json
+import os
+import re
+import subprocess
+import sys
+import unicodedata
+import urllib.parse
+
+SKILL_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+CLI = os.environ.get("ADOPS_CLI", "npx -y addashboard-cli@latest")
+
+
+# ---------------------------------------------------------------- 共通
+def norm(s: object) -> str:
+    """比較専用の正規化。保存するのは常に原文であることに注意。"""
+    t = unicodedata.normalize("NFKC", str(s or "")).strip()
+    return re.sub(r"\s+", " ", t)
+
+
+def int_keys(d: dict) -> list[int]:
+    out = []
+    for k in d or {}:
+        try:
+            out.append(int(k))
+        except (TypeError, ValueError):
+            pass
+    return out
+
+
+def run_list(resource: str, account_id: str, **opts) -> dict:
+    """webgram list を1回叩いて JSON を返す。失敗したら空dict + stderr に理由。"""
+    cmd = [*CLI.split(), "list", "--platform", opts.pop("platform", "yda"),
+           "--resource", resource, "--account-id", account_id]
+    for k, v in opts.items():
+        if v:
+            cmd += [f"--{k}", str(v)]
+    print(f"▸ {resource} を取得中...", file=sys.stderr)
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+    except Exception as e:  # noqa: BLE001
+        print(f"  ✗ {resource} の取得に失敗: {e}", file=sys.stderr)
+        return {}
+    if proc.returncode != 0:
+        print(f"  ✗ {resource} の取得に失敗 (exit {proc.returncode}): "
+              f"{proc.stderr.strip()[:400]}", file=sys.stderr)
+        return {}
+    try:
+        return json.loads(proc.stdout)
+    except Exception as e:  # noqa: BLE001
+        print(f"  ✗ {resource} の応答を解釈できません: {e}", file=sys.stderr)
+        return {}
+
+
+def find_account(platform: str, account_id: str) -> tuple[str | None, dict]:
+    """accountId からアカウントJSONのパスと内容を引く（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:  # noqa: BLE001
+            continue
+        if str(data.get("accountId", "")) == str(account_id):
+            return path, data
+    return None, {}
+
+
+# --------------------------------------------------- 採番（既存を絶対に守る）
+def assign_numbers(existing: dict, incoming: list[str]) -> tuple[dict, dict]:
+    """既存番号を保ったまま未知テキストへ採番する。
+
+    existing: {"1": "見出し", ...}（原文）
+    incoming: 出現順（(adGroupId, adId) 昇順）のテキスト列。重複を含んでよい。
+
+    returns (merged, stats)
+      merged: 既存 + 追加ぶん（既存の番号・原文は不変）
+      stats : {"reused": n, "added": n, "merged": n}
+    """
+    merged = dict(existing or {})
+    by_norm: dict[str, str] = {}
+    for k, v in merged.items():
+        by_norm.setdefault(norm(v), str(k))
+
+    nxt = (max(int_keys(merged)) + 1) if int_keys(merged) else 1
+    stats = {"reused": 0, "added": 0, "merged": 0}
+    seen_this_run: set[str] = set()
+
+    for text in incoming:
+        if not str(text or "").strip():
+            continue
+        n = norm(text)
+        if n in by_norm:
+            # 既存番号を再利用（振り直さない）。同一 run で2回目なら名寄せ扱い。
+            if n in seen_this_run:
+                stats["merged"] += 1
+            else:
+                stats["reused"] += 1
+            seen_this_run.add(n)
+            continue
+        merged[str(nxt)] = text          # 保存は原文
+        by_norm[n] = str(nxt)
+        seen_this_run.add(n)
+        nxt += 1
+        stats["added"] += 1
+    return merged, stats
+
+
+# ------------------------------------------------------------- 取り込み本体
+def import_yda(account_id: str, campaign_id: str | None) -> dict:
+    """YDA から取り込んだ生データを {ads, placements, audiences, campaigns} で返す。"""
+    out: dict = {"ads": [], "placements": {}, "audiences": [], "campaigns": {}}
+
+    camp = run_list("campaigns", account_id, platform="yda")
+    out["campaigns"] = camp or {}
+
+    ad_kwargs = {}
+    if campaign_id:
+        ad_kwargs["campaign-id"] = campaign_id
+    else:
+        # campaignId が無いと backend が 400 を返すので、campaigns から全CPを回す
+        ids = [str(c.get("campaignId") or c.get("id") or "")
+               for c in (camp.get("campaigns") or []) if (c.get("campaignId") or c.get("id"))]
+        ads: list = []
+        for cid in ids:
+            r = run_list("ads", account_id, platform="yda", **{"campaign-id": cid})
+            ads += r.get("ads") or []
+        out["ads"] = ads
+        res = run_list("resources", account_id, platform="yda")
+        out["placements"] = res.get("placements") or {}
+        out["audiences"] = res.get("audiences") or []
+        return out
+
+    out["ads"] = (run_list("ads", account_id, platform="yda", **ad_kwargs)).get("ads") or []
+    res = run_list("resources", account_id, platform="yda")
+    out["placements"] = res.get("placements") or {}
+    out["audiences"] = res.get("audiences") or []
+    return out
+
+
+def sort_key(ad: dict) -> tuple:
+    """(adGroupId, adId) 昇順。数値化できないものは末尾へ。"""
+    def num(v):
+        try:
+            return (0, int(v))
+        except (TypeError, ValueError):
+            return (1, 0)
+    return (num(ad.get("adGroupId")), num(ad.get("adId")))
+
+
+def merge(account: dict, fetched: dict) -> tuple[dict, list[str]]:
+    """アカウントJSON（v1/v2 どちらでも）へマージし、(新しいdict, レポート行) を返す。"""
+    acc = json.loads(json.dumps(account))  # deep copy
+    refs = acc.setdefault("refs", {})
+    report: list[str] = []
+
+    ads = sorted(fetched.get("ads") or [], key=sort_key)
+
+    # --- 見出し / 説明文（既存番号は不変）
+    # backend の /yda/ads は複数形の配列 (headlines / descriptions) で返す。
+    # レスポンシブ広告は実測で1件だが、媒体側が複数返す形に変わっても取りこぼさない
+    # よう配列を平坦化して全件を採番対象にする（単数キーは旧レスポンスの後方互換）。
+    def texts(key_plural: str, key_singular: str) -> list:
+        out = []
+        for a in ads:
+            v = a.get(key_plural)
+            if isinstance(v, list):
+                out.extend(v)
+            elif v:
+                out.append(v)
+            else:
+                out.append(a.get(key_singular))
+        return out
+
+    titles, t_stats = assign_numbers(refs.get("titles") or {},
+                                     texts("headlines", "headline"))
+    descs, d_stats = assign_numbers(refs.get("descriptions") or {},
+                                    texts("descriptions", "description"))
+    refs["titles"], refs["descriptions"] = titles, descs
+    report.append(f"見出し     追加 {t_stats['added']} / 既存一致 {t_stats['reused']}"
+                  f" / 名寄せ統合 {t_stats['merged']}（合計 {len(titles)}）")
+    report.append(f"説明文     追加 {d_stats['added']} / 既存一致 {d_stats['reused']}"
+                  f" / 名寄せ統合 {d_stats['merged']}（合計 {len(descs)}）")
+
+    # --- キャンペーン: ID → name（プランナーの「既存キャンペーン呼び出し」が引く）
+    cps = refs.setdefault("campaigns", {})
+    cp_added = 0
+    for c in (fetched.get("campaigns") or {}).get("campaigns") or []:
+        cid = str(c.get("campaignId") or c.get("id") or "")
+        if not cid:
+            continue
+        if cid not in cps:
+            cps[cid] = {}
+            cp_added += 1
+        if c.get("name"):
+            cps[cid]["name"] = str(c["name"])
+    report.append(f"キャンペーン 新規 {cp_added}（合計 {len(cps)}）")
+
+    # --- 広告グループ: campaignId / finalUrlSample / paramCode 補完
+    #     ⚠ campaignId を必ず入れる。無いとプランナーの「既存広告グループ呼び出し」が親CPを
+    #        特定できず、**プラン末尾の無関係なキャンペーン配下にぶら下がる**。
+    #     ⚠ AG名は /yda/ads が返さないので新規行は name 無しになる（一覧では ID 表示）。
+    #        件数をレポートに出して、名前が要るなら手で足せると分かるようにする。
+    ag = refs.setdefault("adGroups", {})
+    url_added = code_added = cid_added = 0
+    new_ags: list[str] = []
+    for a in ads:
+        gid = str(a.get("adGroupId") or "")
+        if not gid:
+            continue
+        if gid not in ag:
+            ag[gid] = {}
+            new_ags.append(gid)
+        row = ag[gid]
+        cid = str(a.get("campaignId") or "")
+        if cid and not row.get("campaignId"):
+            row["campaignId"] = cid
+            cid_added += 1
+        url = a.get("finalUrl") or ""
+        if not url:
+            continue
+        if not row.get("finalUrlSample"):
+            row["finalUrlSample"] = url
+            url_added += 1
+        if not row.get("paramCode"):
+            q = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)
+            code = (q.get("ad") or [""])[0]
+            if not code:
+                m = re.search(r"【([^】]+)】", str(row.get("name") or ""))
+                code = m.group(1) if m else ""
+            if code:
+                row["paramCode"] = code
+                code_added += 1
+    report.append(f"広告グループ 新規 {len(new_ags)} / campaignId 補完 {cid_added}"
+                  f" / finalUrlSample 補完 {url_added} / paramCode 補完 {code_added}"
+                  + ("　※新規行は AG名 が未設定です（/yda/ads は広告グループ名を返しません）。"
+                     "プランナーの一覧では ID 表示になるので、必要なら name を手で足してください"
+                     if new_ags else ""))
+
+    # --- baseArticleUrl 候補（提示のみ・自動上書きしない）
+    urls = [a.get("finalUrl") for a in ads if str(a.get("finalUrl") or "").startswith("http")]
+    if urls:
+        pre = os.path.commonprefix([u.split("?")[0] for u in urls])
+        pre = pre[: pre.rfind("/") + 1] if "/" in pre else pre
+        cur = acc.get("baseArticleUrl") or ""
+        if pre and pre != cur:
+            report.append(f"baseArticleUrl 候補: {pre}（現在: {cur or '未設定'}）"
+                          " ※自動では上書きしません")
+
+    # --- audiences / placements（消えたIDは削除せず stale マーク）
+    for key, incoming in (
+        ("audiences", [{"id": str(x.get("id")), "name": x.get("name"), "kind": "audienceList"}
+                       for x in (fetched.get("audiences") or []) if x.get("id")]),
+        ("placements", [
+            {"id": str(x.get("id")), "name": x.get("name"), "kind": kind}
+            for kind, arr in (("standard", (fetched.get("placements") or {}).get("standard") or []),
+                              ("exclusion", (fetched.get("placements") or {}).get("exclusions") or []))
+            for x in arr if x.get("id")
+        ]),
+    ):
+        table = refs.setdefault(key, {})
+        live_ids = {r["id"] for r in incoming}
+        added = 0
+        for r in incoming:
+            if r["id"] not in table:
+                added += 1
+            row = table.setdefault(r["id"], {})
+            row["name"], row["kind"] = r["name"], r["kind"]
+            row.pop("stale", None)
+        stale = 0
+        for i in table:
+            if i not in live_ids:
+                table[i]["stale"] = True
+                stale += 1
+        report.append(f"{key:<10} {len(live_ids)}件（新規 {added} / stale {stale}）"
+                      + (" ※stale は過去プランが参照している可能性があるため削除しません"
+                         if stale else ""))
+
+    acc["accountJsonVersion"] = 2
+    return acc, report
+
+
+# ---------------------------------------------------------------- main
+def main() -> int:
+    ap = argparse.ArgumentParser(description="実アカウントから参照表を取り込む")
+    ap.add_argument("platform")
+    ap.add_argument("account_id")
+    ap.add_argument("--write", action="store_true", help="アカウントJSONへ書き込む（既定は dry-run）")
+    ap.add_argument("--campaign-id", dest="campaign_id", default=None,
+                    help="対象キャンペーンを絞る（省略時は全CP）")
+    args = ap.parse_args()
+
+    if args.platform != "yda":
+        sys.exit(f"✗ refs-import は現状 yda のみ対応です（指定: {args.platform}）")
+
+    path, account = find_account(args.platform, args.account_id)
+    if not path:
+        sys.exit(f"✗ accountId {args.account_id} のアカウントJSONが "
+                 f"アカウント/{args.platform}/ にありません。先に作成してください")
+    print(f"📄 {path}")
+
+    fetched = import_yda(args.account_id, args.campaign_id)
+    if not fetched["ads"] and not fetched["audiences"] and not fetched["placements"]:
+        sys.exit("✗ 取得できたデータがありません（ログイン状態・accountId を確認してください）")
+
+    merged, report = merge(account, fetched)
+
+    print("\n── 取り込み結果 ──")
+    for line in report:
+        print(f"  {line}")
+
+    if not args.write:
+        print("\n（dry-run: 書き込んでいません。反映するには --write を付けてください）")
+        return 0
+
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(merged, f, indent=1, ensure_ascii=False)
+        f.write("\n")
+    print(f"\n✓ 書き込みました: {path}（accountJsonVersion=2）")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())