scripts/check-social.py

GitHub
#!/usr/bin/env python3
"""
OG Tags + Twitter Card 社交标签验证脚本。

从 HTML 中提取 Open Graph 和 Twitter Card meta 标签,
验证关键字段的存在性、长度、一致性。

Usage:
    python scripts/check-social.py https://example.com
    python scripts/check-social.py --file page.html

Output: JSON — og / twitter_card 两组检查结果 + 整体 status。

Dependencies:
    pip install requests
"""

import argparse
import ipaddress
import json
import socket
import sys
from html.parser import HTMLParser
from typing import Optional
from urllib.parse import urlparse

try:
    import requests
except ImportError:
    print(
        "Error: requests library required. Install with: pip install requests",
        file=sys.stderr,
    )
    sys.exit(1)


_DEFAULT_HEADERS = {
    "User-Agent": (
        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 "
        "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 ClaudeSEO/1.2"
    ),
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "Accept-Language": "en-US,en;q=0.5",
    "Connection": "keep-alive",
}

# OG 字段长度阈值
_OG_TITLE_MAX = 95
_OG_DESC_MAX = 200

# Twitter 字段长度阈值
_TW_TITLE_MAX = 70
_TW_DESC_MAX = 200

# 合法的 twitter:card 类型
_VALID_CARD_TYPES = frozenset({
    "summary", "summary_large_image", "app", "player",
})


# ── HTTP fetch ────────────────────────────────────────────────────────────────


def _safe_fetch(
    url: str, timeout: int
) -> tuple[Optional[int], Optional[str], Optional[str]]:
    """带 SSRF 防护的 HTTP 请求,返回 (status, content, error)。"""
    parsed = urlparse(url)
    try:
        hostname = parsed.hostname or ""
        resolved_ip = socket.gethostbyname(hostname)
        ip = ipaddress.ip_address(resolved_ip)
        if ip.is_private or ip.is_loopback or ip.is_reserved:
            return None, None, f"Blocked: resolves to private IP ({resolved_ip})"
    except (socket.gaierror, ValueError):
        pass

    try:
        resp = requests.get(
            url, headers=_DEFAULT_HEADERS, timeout=timeout, allow_redirects=True
        )
        return resp.status_code, resp.text, None
    except requests.exceptions.RequestException as exc:
        return None, None, str(exc)


# ── HTML parser ───────────────────────────────────────────────────────────────


class _MetaExtractor(HTMLParser):
    """单次遍历提取 <meta> 标签中的 OG / Twitter / canonical 信息。"""

    def __init__(self) -> None:
        super().__init__()
        self.og: dict[str, str] = {}
        self.twitter: dict[str, str] = {}
        self.canonical: Optional[str] = None

    def handle_starttag(self, tag: str, attrs: list[tuple[str, Optional[str]]]) -> None:
        if tag == "meta":
            attrs_dict = {k.lower(): (v or "") for k, v in attrs}
            prop = attrs_dict.get("property", "").lower()
            name = attrs_dict.get("name", "").lower()
            content = attrs_dict.get("content", "")

            # OG 标签: <meta property="og:xxx" content="...">
            if prop.startswith("og:"):
                key = prop[3:]  # 去掉 "og:" 前缀
                if key and content:
                    self.og[key] = content

            # Twitter 标签: <meta name="twitter:xxx" content="...">
            if name.startswith("twitter:"):
                key = name[8:]  # 去掉 "twitter:" 前缀
                if key and content:
                    self.twitter[key] = content

        # Canonical: <link rel="canonical" href="...">
        if tag == "link":
            attrs_dict = {k.lower(): (v or "") for k, v in attrs}
            if attrs_dict.get("rel", "").lower() == "canonical":
                href = attrs_dict.get("href", "").strip()
                if href:
                    self.canonical = href


# ── OG 验证 ───────────────────────────────────────────────────────────────────


def _check_og(og: dict[str, str], canonical: Optional[str]) -> dict:
    """验证 Open Graph 标签完整性和质量。"""
    issues: list[str] = []
    warnings: list[str] = []
    fields: dict[str, dict] = {}

    # og:title — 必须存在
    title = og.get("title", "")
    if not title:
        issues.append("og:title missing.")
        fields["title"] = {"present": False, "status": "fail"}
    else:
        f: dict = {"present": True, "value": title, "length": len(title), "status": "pass"}
        if len(title) > _OG_TITLE_MAX:
            f["status"] = "warn"
            warnings.append(f"og:title is {len(title)} chars (max {_OG_TITLE_MAX}).")
        fields["title"] = f

    # og:description — 推荐存在
    desc = og.get("description", "")
    if not desc:
        warnings.append("og:description missing.")
        fields["description"] = {"present": False, "status": "warn"}
    else:
        f = {"present": True, "value": desc, "length": len(desc), "status": "pass"}
        if len(desc) > _OG_DESC_MAX:
            f["status"] = "warn"
            warnings.append(f"og:description is {len(desc)} chars (max {_OG_DESC_MAX}).")
        fields["description"] = f

    # og:image — 必须存在且为有效 URL
    image = og.get("image", "")
    if not image:
        issues.append("og:image missing — social shares will lack a preview image.")
        fields["image"] = {"present": False, "status": "fail"}
    else:
        f = {"present": True, "value": image, "status": "pass"}
        if not image.startswith(("http://", "https://")):
            f["status"] = "warn"
            warnings.append("og:image is not an absolute URL.")
        fields["image"] = f

    # og:type — 推荐存在
    og_type = og.get("type", "")
    if not og_type:
        warnings.append("og:type missing (defaults to 'website').")
        fields["type"] = {"present": False, "status": "warn"}
    else:
        fields["type"] = {"present": True, "value": og_type, "status": "pass"}

    # og:url — 推荐存在,且应与 canonical 一致
    og_url = og.get("url", "")
    if not og_url:
        warnings.append("og:url missing.")
        fields["url"] = {"present": False, "status": "warn"}
    else:
        f = {"present": True, "value": og_url, "status": "pass"}
        if canonical and og_url.rstrip("/") != canonical.rstrip("/"):
            f["status"] = "warn"
            f["canonical_mismatch"] = True
            warnings.append(
                f"og:url ({og_url}) differs from canonical ({canonical})."
            )
        fields["url"] = f

    # 综合状态
    if issues:
        status = "fail"
    elif warnings:
        status = "warn"
    else:
        status = "pass"

    detail_parts = []
    if issues:
        detail_parts.extend(issues)
    if warnings:
        detail_parts.extend(warnings)
    if not detail_parts:
        detail_parts.append("All OG tags present and valid.")

    return {
        "status": status,
        "fields": fields,
        "issues": issues,
        "warnings": warnings,
        "detail": " ".join(detail_parts),
    }


# ── Twitter Card 验证 ─────────────────────────────────────────────────────────


def _check_twitter(
    twitter: dict[str, str], og: dict[str, str]
) -> dict:
    """验证 Twitter Card 标签,考虑 OG fallback 机制。"""
    issues: list[str] = []
    warnings: list[str] = []
    fields: dict[str, dict] = {}

    # twitter:card — 必须存在
    card = twitter.get("card", "")
    if not card:
        issues.append("twitter:card missing — no Twitter Card will render.")
        fields["card"] = {"present": False, "status": "fail"}
    else:
        f: dict = {"present": True, "value": card, "status": "pass"}
        if card not in _VALID_CARD_TYPES:
            f["status"] = "warn"
            warnings.append(f"twitter:card value '{card}' is non-standard.")
        fields["card"] = f

    # twitter:title — 可 fallback 到 og:title
    tw_title = twitter.get("title", "")
    og_title = og.get("title", "")
    if tw_title:
        f = {"present": True, "value": tw_title, "length": len(tw_title), "status": "pass"}
        if len(tw_title) > _TW_TITLE_MAX:
            f["status"] = "warn"
            warnings.append(f"twitter:title is {len(tw_title)} chars (max {_TW_TITLE_MAX}).")
        fields["title"] = f
    elif og_title:
        fields["title"] = {
            "present": False, "fallback": "og:title",
            "fallback_value": og_title, "status": "pass",
        }
    else:
        warnings.append("twitter:title missing and no og:title fallback.")
        fields["title"] = {"present": False, "status": "warn"}

    # twitter:description — 可 fallback 到 og:description
    tw_desc = twitter.get("description", "")
    og_desc = og.get("description", "")
    if tw_desc:
        f = {"present": True, "value": tw_desc, "length": len(tw_desc), "status": "pass"}
        if len(tw_desc) > _TW_DESC_MAX:
            f["status"] = "warn"
            warnings.append(
                f"twitter:description is {len(tw_desc)} chars (max {_TW_DESC_MAX})."
            )
        fields["description"] = f
    elif og_desc:
        fields["description"] = {
            "present": False, "fallback": "og:description",
            "fallback_value": og_desc, "status": "pass",
        }
    else:
        warnings.append("twitter:description missing and no og:description fallback.")
        fields["description"] = {"present": False, "status": "warn"}

    # twitter:image — 可 fallback 到 og:image
    tw_image = twitter.get("image", "")
    og_image = og.get("image", "")
    if tw_image:
        fields["image"] = {"present": True, "value": tw_image, "status": "pass"}
    elif og_image:
        fields["image"] = {
            "present": False, "fallback": "og:image",
            "fallback_value": og_image, "status": "pass",
        }
    else:
        warnings.append("twitter:image missing and no og:image fallback.")
        fields["image"] = {"present": False, "status": "warn"}

    # 综合状态
    if issues:
        status = "fail"
    elif warnings:
        status = "warn"
    else:
        status = "pass"

    detail_parts = []
    if issues:
        detail_parts.extend(issues)
    if warnings:
        detail_parts.extend(warnings)
    if not detail_parts:
        detail_parts.append("Twitter Card valid with all fields present or fallback available.")

    return {
        "status": status,
        "fields": fields,
        "issues": issues,
        "warnings": warnings,
        "detail": " ".join(detail_parts),
    }


# ── Main check ────────────────────────────────────────────────────────────────


def check_social(html: str, url: str = "") -> dict:
    """提取并验证 OG + Twitter Card 社交标签。"""
    extractor = _MetaExtractor()
    try:
        extractor.feed(html)
    except Exception:
        return {
            "url": url,
            "status": "error",
            "og": {},
            "twitter_card": {},
            "detail": "Failed to parse HTML for meta tag extraction.",
        }

    og_result = _check_og(extractor.og, extractor.canonical)
    tw_result = _check_twitter(extractor.twitter, extractor.og)

    # 综合两组检查的最终状态
    statuses = [og_result["status"], tw_result["status"]]
    if "fail" in statuses:
        overall = "fail"
    elif "warn" in statuses:
        overall = "warn"
    else:
        overall = "pass"

    return {
        "url": url,
        "status": overall,
        "og": og_result,
        "twitter_card": tw_result,
        "detail": f"OG: {og_result['status']}. Twitter Card: {tw_result['status']}.",
    }


# ── CLI entry point ──────────────────────────────────────────────────────────


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Validate OG Tags + Twitter Card on a page and output JSON."
    )
    parser.add_argument("url", nargs="?", help="Target page URL")
    parser.add_argument(
        "--file", "-f", help="Local HTML file path (skip HTTP fetch)"
    )
    parser.add_argument(
        "--timeout", "-t", type=int, default=20, help="Request timeout in seconds"
    )
    args = parser.parse_args()

    if not args.url and not args.file:
        parser.error("Provide a URL or --file <path>")

    if args.file:
        try:
            with open(args.file, "r", encoding="utf-8") as f:
                html = f.read()
        except OSError as exc:
            print(json.dumps({"error": str(exc)}, indent=2))
            sys.exit(1)
        url = args.url or args.file
    else:
        url = args.url or ""
        if not url.startswith(("http://", "https://")):
            url = f"https://{url}"
        status_code, html, error = _safe_fetch(url, args.timeout)
        if error or not html:
            err_msg = error or f"HTTP {status_code}"
            print(json.dumps({"url": url, "status": "error", "error": err_msg}, indent=2))
            sys.exit(1)

    result = check_social(html, url=url)
    print(json.dumps(result, indent=2, ensure_ascii=False))
    sys.exit(1 if result["status"] == "fail" else 0)


if __name__ == "__main__":
    main()