文字只是简单的部分：为 AI 生成文章配图的完整流水线

┌─ 1. WRITE ────────────────────────────────────────────────────┐
   topic ──▶ LLM ──▶ draft.md  (h2 sections, front-matter)
└───────────────────────────────┬───────────────────────────────┘
┌─ 2. BRIEF ────────────────────┴───────────────────────────────┐
   draft.md ──▶ LLM ──▶ { hero: {...}, sections: [ {...} ] }
                     one JSON object: per slot, a kind +
                     either a camera brief or a data/diagram spec
└──────────┬──────────────────────────────────┬─────────────────┘
           │ kind = "photo"                │ kind = "chart" | "diagram"
           ▼                               ▼
┌─ 3. SEARCH ───────────────┐   ┌─ 4. DRAW (optional) ─────────┐
   GET /search/photos          LLM ──▶ mermaid | plotting code
   ← credited photo +           ──▶ sandbox ──▶ .svg / .png
     w/h, blur_hash, alt,       (deterministic render, no
     licence, source URL         invented numbers)
└──────────┬────────────────┘   └──────────────┬───────────────┘
           └───────────────┬──────────────────┘
┌─ 5. ASSEMBLE ─────────────┴───────────────────────────────────┐
   <img> with width/height + fetchpriority | loading
   alt written for a human · visible credit · ImageObject JSON-LD
   photo_id stored so no two pages share a hero
└───────────────────────────────────────────────────────────────┘

# system prompt — run once per finished draft
You are the art director of a technical publication. Read the article and
return the visual plan: one entry for the hero, one per H2 section.

For each entry choose exactly one kind:
  "photo"    a real scene: someone doing something somewhere, a place,
              an object, a gesture. The default for heroes.
  "chart"    the section states numbers that are IN the article. Never
              invent values: copy them into data, verbatim.
  "diagram"  the section describes a structure, a flow or a sequence.
  "none"     the section is short, or already carries a code block.

Rules for "photo" entries — the field is query:
撰写一段镶头简介：描述一个相机可以拍摄到的场景，用英文写成，字数在12到25词之间，
   并与该章节的氛围相符。要写出画面中出现的实际事物，而不是主题本身。禁止出现文字、
   徽标、品牌或名人；也不要使用看不见的隐喻。（完整规则，含示例与失败案例：
   pexafy.com/blog/illustrate-blog-articles-at-scale/)

Do NOT write the alt text of a photo entry: the picture you get back is the
closest match to the brief, not the scene you described, so its alt has to be
written from the chosen photo. Chart and diagram entries DO carry an alt —
there you control exactly what is rendered.

Return JSON only:
{
  "hero": { "kind": "photo", "query": "…", "orientation": "landscape" },
  "sections": [
    { "h2": "…", "kind": "photo",   "query": "…" },
    { "h2": "…", "kind": "chart",   "title": "…", "unit": "ms",
      "data": [ {"label": "…", "value": 0} ], "alt": "…" },
    { "h2": "…", "kind": "diagram", "spec": "flowchart LR; …", "alt": "…" }
  ]
}

{
  "photo_id":  "019e1c7f-0063-759e-b498-33ce1714e6c9",   // 保存它：不重复使用
  "urls": { "small": "…?w=400", "regular": "…?w=1080",
             "large": "…?w=1920" },
  "width": 3000, "height": 1688,          // → 无布局偏移
  "blur_hash": "LJ8gjv9rVq-6OFxanNNFI7xco$Na",   // → 真实占位图
  "alt_description": "Person types on keyboard in front of dual monitors…",
  "photographer_full_name": "Jakub Żerdzicki",   // → ImageObject.creator
  "source": "Unsplash", "license_type": "free",
  "source_image_url": "https://unsplash.com/photos/…",
  "attribution": { "html": "<span…>Photo by …</span>",
                    "plain": "Photo by Jakub Żerdzicki on Unsplash (…)" }
}

# the "spec" field of a diagram entry, written to build/graph.mmd
cat build/graph.mmd
flowchart LR
  install["install deps · 480s"] --> compile["compile · 1080s"]
  compile --> test["test suite · 720s"]
  compile --> upload["upload artifacts · 120s"]

npx -y @mermaid-js/mermaid-cli -i build/graph.mmd -o static/img/graph.svg
# → 一个可以在 PR 中审查的 SVG，而不是必须盲目信任的图片

import re, matplotlib
matplotlib.use("Agg")                # 无头模式：CI 中没有显示器
import matplotlib.pyplot as plt

def assert_in_draft(value, draft: str) -> None:
    """绘制的数字必须以数字形式出现在文章中。"""
    # 这里的陷阱是子串匹配："120" 存在于 "1200" 之中，
    # 也存在于 "?w=1200" 之中——朴素的 `str(v) in draft` 会对任何情况都放行。
    # 要基于单词边界匹配，并接受 1 234 / 1,234 / 1234 这几种写法。
    body = re.sub(r"(?<=\d)[  ,](?=\d{3}\b)", "", draft)   # 去掉分隔符
    if not re.search(rf"(?<![\d.]){re.escape(str(value))}(?![\d.])", body):
        raise ValueError(f"{value} is not stated in the article — refusing to plot")

def render_chart(entry: dict, draft: str, out: str) -> str:
    labels = [d["label"] for d in entry["data"]]
    values = [d["value"] for d in entry["data"]]
    for v in values:
        assert_in_draft(v, draft)       # 幻觉出的数值 → 不绘制图表

    fig, ax = plt.subplots(figsize=(8, 4.5), dpi=160)
    ax.barh(labels, values)
    ax.set_xlabel(entry["unit"])
    ax.set_title(entry["title"])
    fig.tight_layout()
    fig.savefig(out)                    # 确定性、可审查的产物
    return out

<!-- 这些字节来自另一个源站：提前完成握手 -->
<link rel="preconnect" href="https://images.unsplash.com" crossorigin>

<!-- LCP 元素：绝不懒加载，始终高优先级 -->
<figure>
  <img src="{urls.regular}"
       width="{width}" height="{height}"        <!-- 杜绝布局偏移 -->
       alt="{alt}"                                <!-- 在选定照片之后再撰写 -->
       fetchpriority="high" decoding="async"
       style="background:{color_hex}">   <!-- 主色调，1 个字段 -->
  <figcaption>{attribution.html}</figcaption>
</figure>

<!-- 首屏以下的段落配图：设置相反 -->
<img src="{urls.regular}" width="{width}" height="{height}"
     alt="{alt}" loading="lazy" decoding="async">

<script type="application/ld+json">
{
  "@context": "https://schema.org/",
  "@type": "ImageObject",
  "contentUrl": "{urls.large}",                 // 必填
  "creator": { "@type": "Person",
                "name": "{photographer_full_name}" },
  "creditText": "{photographer_full_name} on {source}",
  "license": "{LICENSE_URL[source]}",           // 该图库自己的许可页面
  "acquireLicensePage": "{source_image_url}"     // 该照片的页面
}
</script>

# LICENSE_URL 将 `source` 字段映射到真正约束
# 该照片的许可——unsplash.com/license, pexels.com/license, pixabay.com/…

on: { pull_request: { paths: ["content/**.md"] } }

jobs:
  illustrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r requirements.txt
      - run: python plan_to_pr.py $(git diff --name-only origin/main -- 'content/*.md')
        env:
          PEXAFY_API_KEY: ${{ secrets.PEXAFY_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - uses: peter-evans/create-pull-request@v6   # 图片随 PR 一起落地
        with: { commit-message: "chore(content): illustrate" }

import frontmatter
from photo_search import search   # 一次 GET /search/photos；跳过 `used` 中已有的 id

def find_photo(entry: dict, used: set) -> dict | None:
    """搜索；如果简报过于具体，放宽一次，再不行就放弃。"""
    orientation = entry.get("orientation", "landscape")
    for query in (entry["query"], widen(entry["query"])):
        photo = search(query, orientation, used)
        if photo:
            used.add(photo["photo_id"])   # 占用它：全站不重复
            return photo
    return None                        # 由调用者决定：跳过该位置，还是直接失败

def widen(query: str) -> str:
    """去掉最后一个从句——通常就是过于具体的那一部分。"""
    return query.rsplit(" in ", 1)[0] if " in " in query else query

def illustrate(path: str, plan: dict, used: set) -> None:
    post = frontmatter.load(path)
    hero = find_photo(plan["hero"], used)
    if hero is None:                    # 没有首图，好过配一张糟糕的首图
        raise SystemExit(f"{path}: no photo above threshold — rewrite the brief")

    post["hero"] = {                    # 模板需要的一切
        "src": hero["urls"]["regular"], "w": hero["width"], "h": hero["height"],
        # alt 描述的是我们实际拿到的照片，而不是我们最初要求的场景。
        "alt": alt_for(hero, section=post.get("title", "")),
        "bg": hero["color_hex"], "credit": hero["attribution"]["html"],
        "creator": hero["photographer_full_name"], "id": hero["photo_id"],
        "source": hero["source"],
        "source_url": hero["source_image_url"],   # → acquireLicensePage
    }
    open(path, "w").write(frontmatter.dumps(post))

def alt_for(photo: dict, section: str) -> str:
    """以 alt_description 为基础，裁剪到约 125 字符以适配屏幕阅读器。
    若想效果更好，可结合段落再把它发回模型润色。"""
    base = photo.get("alt_description") or photo.get("description", "")
    return base[:125].rstrip(" ,;")

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page(viewport={"width": 1440, "height": 900},
                            device_scale_factor=2)   # 视网膜屏级清晰
    page.goto("http://localhost:3000/dashboard")
    page.get_by_role("button", name="New API key").click()
    page.screenshot(path="static/img/docs/new-api-key.png")
    browser.close()
# 与文档构建运行在同一个 CI 任务中 → 截图永远不可能
# 描述一个已不复存在的界面版本。