{ "sha": "9521e35962e12e6237599a285d6d96689f343d88", "message": "feat: require source-backed descriptions for article images (#166)\n\nCo-authored-by: avwire-bot ", "author": { "login": "nnneeeooo-nnneeeooo", "name": "", "email": "" }, "committer": { "login": "web-flow", "name": "", "email": "" }, "created_at": "2026-09-06T10:15:27Z", "files": [ { "filename": ".github/workflows/hourly.yml", "previous_filename": "", "status": "modified", "additions": 2, "deletions": 0, "changes": 2 }, { "filename": ".github/workflows/manual-article-deploy.yml", "previous_filename": "", "status": "modified", "additions": 2, "deletions": 0, "changes": 2 }, { "filename": "data/image-captions.json", "previous_filename": "", "status": "added", "additions": 2005, "deletions": 0, "changes": 2005 }, { "filename": "pipeline/build.py", "previous_filename": "", "status": "modified", "additions": 28, "deletions": 13, "changes": 41 }, { "filename": "pipeline/image_captions.py", "previous_filename": "", "status": "added", "additions": 189, "deletions": 0, "changes": 189 }, { "filename": "pipeline/image_fallbacks.py", "previous_filename": "", "status": "modified", "additions": 1, "deletions": 0, "changes": 1 }, { "filename": "pipeline/images.py", "previous_filename": "", "status": "modified", "additions": 1, "deletions": 0, "changes": 1 }, { "filename": "static/manual.js", "previous_filename": "", "status": "modified", "additions": 18, "deletions": 3, "changes": 21 }, { "filename": "templates/article.html", "previous_filename": "", "status": "modified", "additions": 1, "deletions": 1, "changes": 2 }, { "filename": "templates/home.html", "previous_filename": "", "status": "modified", "additions": 1, "deletions": 1, "changes": 2 }, { "filename": "templates/manual.html", "previous_filename": "", "status": "modified", "additions": 4, "deletions": 0, "changes": 4 }, { "filename": "tests/test_image_captions.py", "previous_filename": "", "status": "added", "additions": 127, "deletions": 0, "changes": 127 }, { "filename": "tests/test_images.py", "previous_filename": "", "status": "modified", "additions": 5, "deletions": 3, "changes": 8 } ], "diff": "@@ -85,6 +85,8 @@ jobs:\\n python pipeline/airport_codes.py\\n python pipeline/images.py\\n python pipeline/image_fallbacks.py\\n+ python pipeline/image_captions.py\\n+ python tests/test_image_captions.py\\n python pipeline/image_qa.py\\n # The saved Taipei date makes this one LLM-assisted refresh per day.\\n # Missing/invalid model output falls back to published article titles.\\n@@ -58,6 +58,8 @@ jobs:\\n run: |\\n python pipeline/summary_guard.py\\n python pipeline/airport_codes.py\\n+ python pipeline/image_captions.py\\n+ python tests/test_image_captions.py\\n python pipeline/build.py\\n \\n - name: Scan publishable output\\n\\n@@ -55,6 +55,13 @@\\n MODEL_DISPLAY_NAMES,\\n MODEL_ORDER,\\n )\\n+from image_captions import clean_description\\n+\\n+_caption_cache = load_json(DATA_DIR / \"image-captions.json\", {})\\n+IMAGE_CAPTIONS = (_caption_cache.get(\"images\", {})\\n+ if isinstance(_caption_cache, dict) else {})\\n+if not isinstance(IMAGE_CAPTIONS, dict):\\n+ IMAGE_CAPTIONS = {}\\n \\n PUBLIC_DIR = Path(__file__).resolve().parent.parent / \"public\"\\n \\n@@ -975,37 +982,43 @@ def _public_direct_url(url: str) -> bool:\\n return bool(value) and _safe_web_url(value) and not is_google_news_url(value)\\n \\n \\n-def normalize_image(raw_img):\\n+def normalize_image(raw_img, titles=()):\\n \"\"\"Article image -> {url, link, credit, license, provider, kind} or None.\\n \\n- Accepts the images.py match dict or a plain URL string (legacy).\\n+ Accepts the images.py match dict or a plain URL string (legacy) with an\\n+ exact-URL cached description. Uncaptioned photos use the brand fallback.\\n Only http(s) URLs survive; a credited external embed keeps its\\n attribution and backlink so CC/photographer terms are honored.\\n \"\"\"\\n+ if isinstance(raw_img, str):\\n+ raw_img = {\"url\": raw_img}\\n if isinstance(raw_img, dict):\\n url = str(raw_img.get(\"url\") or \"\")\\n if not url or not _safe_web_url(url):\\n return None\\n- link = str(raw_img.get(\"link\") or \"\")\\n+ cached = IMAGE_CAPTIONS.get(url) or {}\\n+ if not isinstance(cached, dict):\\n+ cached = {}\\n+ subject = (clean_description(raw_img.get(\"description\"))\\n+ or clean_description(raw_img.get(\"subject\"))\\n+ or clean_description(cached.get(\"subject\")))\\n+ if not subject or subject.casefold() in {\\n+ str(title).strip().casefold() for title in titles if title}:\\n+ return None\\n+ link = str(raw_img.get(\"link\") or cached.get(\"link\") or \"\")\\n return {\\n \"url\": url,\\n \"link\": link if link and _safe_web_url(link) else None,\\n \"credit\": str(raw_img.get(\"credit\") or \"\") or None,\\n \"license\": str(raw_img.get(\"license\") or \"\") or None,\\n- \"provider\": str(raw_img.get(\"provider\") or \"\") or None,\\n- \"subject\": str(raw_img.get(\"subject\") or \"\") or None,\\n+ \"provider\": str(raw_img.get(\"provider\") or cached.get(\"provider\") or \"\") or None,\\n+ \"subject\": subject,\\n \"kind\": (raw_img.get(\"kind\")\\n if raw_img.get(\"kind\") in (\"airframe_photo\",\\n \"file_photo\",\\n \"event_photo\")\\n else \"file_photo\"),\\n }\\n- if raw_img:\\n- url = str(raw_img)\\n- if not _safe_web_url(url):\\n- return None\\n- return {\"url\": url, \"link\": None, \"credit\": None, \"license\": None,\\n- \"provider\": None, \"subject\": None, \"kind\": \"file_photo\"}\\n return None\\n \\n \\n@@ -1153,7 +1166,8 @@ def side(own, other):\\n ]\\n if not available_languages:\\n available_languages = [\"zh\", \"en\"]\\n- image = normalize_image(raw.get(\"image\"))\\n+ image = normalize_image(raw.get(\"image\"), titles=[\\n+ (raw.get(lang) or {}).get(\"title\") for lang in (\"zh\", \"en\")])\\n # Display the SOURCE's newest publication time when the write stage\\n # recorded one; the generation time (dt) is used for ordering only, so\\n # a days-old official release is never presented as breaking news.\\n@@ -1399,7 +1413,8 @@ def _hero_image_caption(image, lang: str) -> str:\\n )\\n parts = []\\n if image.get(\"subject\"):\\n- parts.append(str(image[\"subject\"]))\\n+ parts.append((\"圖中主體：\" if lang == \"zh\" else \"Pictured: \")\\n+ + str(image[\"subject\"]))\\n kind = str(image.get(\"kind\") or \"\")\\n kind_label = L[lang][\"photoKind\"].get(kind)\\n if kind_label:\\n@@ -0,0 +1,189 @@\\n+\"\"\"Recover descriptions of the exact source image, never from story titles.\\n+\\n+The URL-keyed cache also serves legacy URL-only images at build time. Missing\\n+metadata is retried after six hours; the renderer uses the named brand fallback\\n+until a description exists. No model, filename guess, or network call in build.\\n+\"\"\"\\n+from __future__ import annotations\\n+\\n+import argparse\\n+from concurrent.futures import ThreadPoolExecutor\\n+from datetime import timedelta\\n+from html import unescape\\n+import re\\n+import sys\\n+from pathlib import Path\\n+from urllib.parse import unquote, urljoin, urlsplit\\n+\\n+import requests\\n+from bs4 import BeautifulSoup\\n+\\n+sys.path.insert(0, str(Path(__file__).resolve().parent))\\n+from common import ARTICLES_DIR, DATA_DIR, USER_AGENT, load_json, now_utc, parse_iso, save_json\\n+\\n+CACHE_PATH = DATA_DIR / \"image-captions.json\"\\n+MAX_LOOKUPS = 80\\n+_GENERIC = re.compile(\\n+ r\"^(?:image|photo|picture|thumbnail|featured image|file photo|stock photo|\"\\n+ r\"untitled|圖片|照片|資料照片|示意圖|示意照片)(?:\\s*\\d+)?$\", re.I)\\n+\\n+\\n+def clean_description(value) -> str:\\n+ if not isinstance(value, str):\\n+ return \"\"\\n+ text = \" \".join(BeautifulSoup(unescape(value), \"html.parser\").stripped_strings)\\n+ text = re.sub(r\"\\s+\", \" \", text).strip()\\n+ if (len(text) < 4 or len(text) > 300 or _GENERIC.fullmatch(text)\\n+ or re.search(r\"\\b(?:untitled design|screenshot|gallery[-_ ]*\\d|adobestock[_-]?\\d)\", text, re.I)\\n+ or re.match(r\"^(?:credit|photo credit|copyright|©)\\s*[:：]?\", text, re.I)\\n+ or re.fullmatch(r\"[\\W\\d_]+\", text)\\n+ or re.search(r\"\\.(?:jpe?g|png|webp|gif)$\", text, re.I)):\\n+ return \"\"\\n+ return text\\n+\\n+\\n+def image_identity(url: str, base: str = \"\") -> tuple[str, str]:\\n+ \"\"\"Ignore CDN resize parameters, but never match by basename alone.\"\"\"\\n+ try:\\n+ parts = urlsplit(urljoin(base, unescape(url)))\\n+ if parts.scheme not in (\"http\", \"https\") or not parts.hostname:\\n+ return \"\", \"\"\\n+ path = unquote(parts.path)\\n+ path = re.sub(r\"-(?:\\d{2,4}x\\d{2,4}|scaled)(?=\\.[^.]+$)\", \"\", path)\\n+ return parts.hostname.lower(), path\\n+ except ValueError:\\n+ return \"\", \"\"\\n+\\n+\\n+def source_description(html: str, image_url: str, source_url: str,\\n+ titles=()) -> dict | None:\\n+ \"\"\"Only alt/figcaption tied to this image can describe the photograph.\"\"\"\\n+ target = image_identity(image_url)\\n+ if not target[0]:\\n+ return None\\n+ soup = BeautifulSoup(html, \"html.parser\")\\n+ blocked = {str(t).strip().casefold() for t in titles if t}\\n+ blocked.update(node.get_text(\" \", strip=True).casefold()\\n+ for node in soup.select(\"h1, title\"))\\n+\\n+ def usable(value):\\n+ text = clean_description(value)\\n+ return text if text.casefold() not in blocked else \"\"\\n+\\n+ for img in soup.find_all(\"img\"):\\n+ urls = [img.get(k, \"\") for k in\\n+ (\"src\", \"data-src\", \"data-lazy-src\", \"data-img-url\")]\\n+ for key in (\"srcset\", \"data-srcset\"):\\n+ urls.extend(part.strip().split()[0] for part in\\n+ str(img.get(key, \"\")).split(\",\") if part.strip())\\n+ if not any(image_identity(u, source_url) == target for u in urls):\\n+ continue\\n+ subject = usable(img.get(\"alt\", \"\"))\\n+ figure = img.find_parent(\"figure\")\\n+ caption = figure.find(\"figcaption\") if figure else None\\n+ if not subject and caption:\\n+ # Credit alone is attribution, not a description of the subject.\\n+ text = caption.get_text(\" \", strip=True)\\n+ subject = usable(re.split(r\"\\b(?:Photo )?Credit\\s*:\", text,\\n+ flags=re.I)[0])\\n+ if subject:\\n+ return {\"subject\": subject, \"link\": source_url,\\n+ \"captionSource\": \"source-image-metadata\"}\\n+ og_images = soup.find_all(\"meta\", property=\"og:image\")\\n+ if any(image_identity(m.get(\"content\", \"\"), source_url) == target\\n+ for m in og_images):\\n+ alt = soup.find(\"meta\", property=\"og:image:alt\")\\n+ subject = usable(alt.get(\"content\", \"\")) if alt else \"\"\\n+ if subject:\\n+ return {\"subject\": subject, \"link\": source_url,\\n+ \"captionSource\": \"og:image:alt\"}\\n+ return None\\n+\\n+\\n+def resolve_description(image_url: str, sources: list, titles: list) -> dict | None:\\n+ for source in sources[:3]:\\n+ url = str(source.get(\"url\") or \"\")\\n+ if not image_identity(url)[0]:\\n+ continue\\n+ try:\\n+ response = requests.get(url, timeout=(5, 15),\\n+ headers={\"User-Agent\": USER_AGENT})\\n+ if response.status_code != 200:\\n+ continue\\n+ result = source_description(response.text, image_url, url, titles)\\n+ if result:\\n+ result[\"provider\"] = str(source.get(\"name\") or\\n+ urlsplit(url).hostname).split(\" — \")[0]\\n+ return result\\n+ except requests.RequestException:\\n+ continue\\n+ return None\\n+\\n+\\n+def main(*, all_articles=False, max_lookups=MAX_LOOKUPS) -> int:\\n+ now = now_utc()\\n+ cache = load_json(CACHE_PATH, {})\\n+ entries = cache.get(\"images\", {}) if isinstance(cache, dict) else {}\\n+ if not isinstance(entries, dict):\\n+ entries = {}\\n+ candidates = {}\\n+ for path in sorted(ARTICLES_DIR.glob(\"*.json\"), reverse=True):\\n+ for article in (load_json(path, {}) or {}).get(\"articles\", []):\\n+ if not isinstance(article, dict):\\n+ continue\\n+ if not all_articles:\\n+ try:\\n+ if parse_iso(article.get(\"publishedUtc\", \"\")) < now - timedelta(days=7):\\n+ continue\\n+ except (TypeError, ValueError):\\n+ continue\\n+ raw = article.get(\"image\")\\n+ if isinstance(raw, dict) and clean_description(raw.get(\"subject\")):\\n+ continue\\n+ url = raw.get(\"url\") if isinstance(raw, dict) else raw\\n+ if not isinstance(url, str) or not image_identity(url)[0]:\\n+ continue\\n+ old = entries.get(url) or {}\\n+ if clean_description(old.get(\"subject\")):\\n+ continue\\n+ try:\\n+ if old.get(\"retryUtc\") and parse_iso(old[\"retryUtc\"]) > now:\\n+ continue\\n+ except (TypeError, ValueError):\\n+ pass\\n+ candidate = candidates.setdefault(url, {\"sources\": [], \"titles\": []})\\n+ for source in article.get(\"sources\") or []:\\n+ if isinstance(source, dict) and source not in candidate[\"sources\"]:\\n+ candidate[\"sources\"].append(source)\\n+ candidate[\"titles\"].extend((article.get(lang) or {}).get(\"title\")\\n+ for lang in (\"zh\", \"en\"))\\n+ jobs = list(candidates.items())[:max_lookups]\\n+\\n+ def lookup(job):\\n+ url, context = job\\n+ return url, resolve_description(url, context[\"sources\"], context[\"titles\"])\\n+\\n+ found = 0\\n+ with ThreadPoolExecutor(max_workers=6) as pool:\\n+ for url, result in pool.map(lookup, jobs):\\n+ entry = {\"checkedUtc\": now.isoformat()}\\n+ if result:\\n+ entry.update(result)\\n+ found += 1\\n+ else:\\n+ entry[\"retryUtc\"] = (now + timedelta(hours=6)).isoformat()\\n+ entries[url] = entry\\n+ payload = {\"images\": entries}\\n+ if payload != cache:\\n+ save_json(CACHE_PATH, payload)\\n+ print(f\"image captions: {len(jobs)} lookup(s), {found} descriptions, \"\\n+ f\"{len(jobs) - found} awaiting source metadata\", flush=True)\\n+ return 0\\n+\\n+\\n+if __name__ == \"__main__\":\\n+ parser = argparse.ArgumentParser()\\n+ parser.add_argument(\"--all\", action=\"store_true\")\\n+ parser.add_argument(\"--limit\", type=int, default=MAX_LOOKUPS)\\n+ args = parser.parse_args()\\n+ raise SystemExit(main(all_articles=args.all, max_lookups=args.limit))\\n@@ -217,6 +217,7 @@ def lookup_commons_airport(airport: str) -> dict | None:\\n \"kind\": \"file_photo\",\\n \"matched\": f\"airport:{airport}\",\\n \"subject\": f\"{airport} 資料照片\",\\n+ \"description\": title.removeprefix(\"File:\").rsplit(\".\", 1)[0].replace(\"_\", \" \"),\\n }\\n return None\\n \\n@@ -716,6 +716,7 @@ def lookup_commons(query: str, require_tokens: list[str],\\n \"kind\": \"file_photo\",\\n \"matched\": query,\\n \"subject\": subject or None,\\n+ \"description\": title.removeprefix(\"File:\").rsplit(\".\", 1)[0].replace(\"_\", \" \"),\\n \"photoYear\": photo_year,\\n }\\n if not prefer_recent:\\n@@ -20,7 +20,7 @@\\n \"publication-period\", \"manual-order-panel\", \"sort-follow-publication\",\\n \"sort-time-fields\", \"sort-date\", \"sort-hour\", \"sort-minute\",\\n \"sort-period\",\\n- \"image-input\", \"image-list\", \"upload-zone\", \"article-type\", \"language\",\\n+ \"image-input\", \"image-list\", \"image-description\", \"upload-zone\", \"article-type\", \"language\",\\n \"model\", \"reasoning-tier\", \"chat-history\", \"instruction\", \"clear-chat\",\\n \"generate\", \"form-error\", \"security-state\", \"job-state\", \"metric-model\",\\n \"metric-reasoning\", \"metric-fallback\", \"metric-duration\",\\n@@ -659,6 +659,17 @@\\n els.attempts.innerHTML = '

尚無資料

';\\n }\\n \\n+ function manualImageSubject() {\\n+ const subject = els[\"image-description\"].value.trim();\\n+ if (subject.length < 4 || subject.length > 240\\n+ || /^(圖片|照片|資料照片|示意圖|image|photo|file photo)$/i.test(subject)\\n+ || subject === els[\"manual-title-primary\"].value.trim()\\n+ || subject === els[\"manual-title-secondary\"].value.trim()) {\\n+ throw new Error(\"請填寫首張配圖的具體主體，不能只寫資料照片或直接使用新聞標題。\");\\n+ }\\n+ return subject;\\n+ }\\n+\\n function validateForm() {\\n if (!validToken) return \"私人網址權杖無效\";\\n if (!validPat(els[\"github-token\"].value.trim())) {\\n@@ -670,6 +681,9 @@\\n return \"來源網址只能使用 http:// 或 https://\";\\n }\\n if (workbenchMode === \"manual\") {\\n+ if (images.length) {\\n+ try { manualImageSubject(); } catch (error) { return error.message; }\\n+ }\\n if (!els[\"manual-title-primary\"].value.trim()) {\\n return \"請輸入文章標題\";\\n }\\n@@ -770,7 +784,7 @@\\n image: imageUrls[0] ? {\\n url: imageUrls[0],\\n provider: \"AVWIRE manual upload\",\\n- subject: zh.title || en.title,\\n+ subject: manualImageSubject(),\\n kind: \"file_photo\",\\n } : null,\\n zh,\\n@@ -1475,12 +1489,13 @@\\n try {\\n let latestCommit = \"\";\\n if (lastResult.operatorAuthored && images.length) {\\n+ const imageSubject = manualImageSubject();\\n const imageUrls = imageUrlsForArticle(article.id);\\n latestCommit = await uploadManualImages(article.id);\\n article.image = {\\n url: imageUrls[0],\\n provider: \"AVWIRE manual upload\",\\n- subject: article.zh.title || article.en.title,\\n+ subject: imageSubject,\\n kind: \"file_photo\",\\n };\\n article.attachments = imageUrls.map((url, index) => ({\\n@@ -29,7 +29,7 @@

{{ a.title }}

\\n
\\n \"{{\\n
\\n- {% if a.image.subject %}{{ a.image.subject }}{% endif %}\\n+ {% if html_lang.startswith('zh') %}圖中主體：{% else %}Pictured: {% endif %}{{ a.image.subject }}\\n {{ t.photoKind[a.image.kind] }}\\n {% if a.image.credit %}© {{ a.image.credit }}{% endif %}\\n {% if a.image.license %}{{ a.image.license }}{% endif %}\\n@@ -47,7 +47,7 @@
{{ t.sourceStatus }}
\\n \"{{\\n-
{% if hero.image.subject %}{{ hero.image.subject }} · {% endif %}{{ t.photoKind[hero.image.kind] }}{% if hero.image.credit %} · © {{ hero.image.credit }}{% endif %}{% if hero.image.license %} · {{ hero.image.license }}{% endif %}{% if hero.image.provider %} · {{ hero.image.provider }}{% endif %}
\\n+
{% if html_lang.startswith('zh') %}圖中主體：{% else %}Pictured: {% endif %}{{ hero.image.subject }} · {{ t.photoKind[hero.image.kind] }}{% if hero.image.credit %} · © {{ hero.image.credit }}{% endif %}{% if hero.image.license %} · {{ hero.image.license }}{% endif %}{% if hero.image.provider %} · {{ hero.image.provider }}{% endif %}
\\n {% else %}\\n 補稿輸入\\n 點選、拖入，或直接 Ctrl+V 貼上；最多 4 張。\\n
\\n \\n+ \\n