"""
提议者(Proposer)与审核者(Reviewer)两个 Agent,以及一个带 token 计量的 LLM 客户端。
设计要点(对应书中“提议者-审核者”机制):
- Proposer 只处理**文本**:论文正文 + 累积的结构化文字反馈;从不接收渲染图片。
- Reviewer 每一轮**只看最新一版的渲染截图**,且每轮都是一次全新的、无历史的调用。
- 单 Agent 自审对照组则相反:同一段对话里不断累积历次渲染的图片,上下文迅速膨胀。
所有对 OpenAI 的调用都经过 TokenMeter 统计 prompt / completion token,
用于最后的“单 Agent vs 双 Agent 上下文消耗”对比。
"""
import base64
import io
import json
import os
import re
from openai import OpenAI
from PIL import Image
# 文本生成用的模型(Proposer / 单 Agent 的文本部分)
TEXT_MODEL = os.environ.get("TEXT_MODEL", "gpt-5.6-luna")
# 视觉审查用的模型(Reviewer / 单 Agent 的看图部分),必须支持图像
VISION_MODEL = os.environ.get("VISION_MODEL", "gpt-5.6-luna")
OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
def map_model_to_openrouter(model: str) -> str:
"""把直连模型名映射为 OpenRouter 上的 id(非可映射 id 统一兜底到当前廉价旗舰)。"""
if not model or "/" in model:
return model or "openai/gpt-5.6-luna"
m = model.lower()
if m.startswith(("gpt-", "o1", "o3", "o4")):
return "openai/" + model
if m.startswith("claude"):
if "haiku" in m:
return "anthropic/claude-haiku-4.5"
if "sonnet" in m:
return "anthropic/claude-sonnet-4.6"
return "anthropic/claude-opus-4.8"
if m.startswith("gemini"):
return "google/" + model
return "openai/gpt-5.6-luna"
# 发送给 Vision 前把截图缩放到该宽度,兼顾“看得清文字溢出”与“控制 token 成本”
VISION_IMAGE_WIDTH = 1280
class TokenMeter:
"""累计一个“角色/模式”消耗的 token,并记录每次调用的 prompt token(用于看上下文峰值)。"""
def __init__(self, name: str):
self.name = name
self.prompt_tokens = 0
self.completion_tokens = 0
self.calls = 0
self.peak_prompt_tokens = 0 # 单次调用最大的 prompt token —— 决定是否“撑爆上下文”
self.per_call_prompt = []
def add(self, usage):
self.calls += 1
pt = usage.prompt_tokens
self.prompt_tokens += pt
self.completion_tokens += usage.completion_tokens
self.peak_prompt_tokens = max(self.peak_prompt_tokens, pt)
self.per_call_prompt.append(pt)
@property
def total_tokens(self):
return self.prompt_tokens + self.completion_tokens
def _client() -> OpenAI:
# 通用 OpenRouter 兜底:无直连 key,或默认 gpt-5.x(直连需组织实名认证)时改走 OpenRouter。
global TEXT_MODEL, VISION_MODEL
api_key = os.environ.get("OPENAI_API_KEY")
base_url = os.environ.get("OPENAI_BASE_URL")
orkey = os.environ.get("OPENROUTER_API_KEY")
prefer_or = bool(orkey) and (
(TEXT_MODEL or "").lower().startswith("gpt-5") or (VISION_MODEL or "").lower().startswith("gpt-5")
)
if prefer_or or (not api_key and orkey):
api_key, base_url = orkey, OPENROUTER_BASE_URL
# 走 OpenRouter 时把模型名映射为其 id(幂等:已带前缀的 id 原样返回)。
TEXT_MODEL = map_model_to_openrouter(TEXT_MODEL)
VISION_MODEL = map_model_to_openrouter(VISION_MODEL)
if not api_key:
raise SystemExit(
"❌ 未检测到 OPENAI_API_KEY(或 OPENROUTER_API_KEY 兜底)。请先 `cp env.example .env` 并填入有效的 "
"OpenAI API Key(或 `export OPENAI_API_KEY=sk-...` / `export OPENROUTER_API_KEY=...`)后再运行。"
)
# timeout + max_retries:单次网络抖动/SSL 中断会自动重试,而不是让整条流水线崩溃。
return OpenAI(
api_key=api_key,
base_url=base_url,
timeout=60.0,
max_retries=4,
)
def encode_image(path: str) -> str:
"""读取 PNG,缩放到统一宽度,编码为 data URL(base64)。"""
img = Image.open(path).convert("RGB")
if img.width > VISION_IMAGE_WIDTH:
h = int(img.height * VISION_IMAGE_WIDTH / img.width)
img = img.resize((VISION_IMAGE_WIDTH, h), Image.LANCZOS)
buf = io.BytesIO()
img.save(buf, format="PNG")
b64 = base64.b64encode(buf.getvalue()).decode()
return f"data:image/png;base64,{b64}"
def _extract_json(text: str):
"""从模型回复里稳健地抽取 JSON(容忍 ```json 代码块或前后多余文字)。"""
text = text.strip()
m = re.search(r"```(?:json)?\s*(.*?)```", text, re.DOTALL)
if m:
text = m.group(1).strip()
# 找到第一个 { 到最后一个 }
start = text.find("{")
end = text.rfind("}")
if start != -1 and end != -1:
text = text[start:end + 1]
return json.loads(text)
def _extract_slides_md(text: str) -> str:
"""从模型回复里抽取 slides.md 内容(容忍 ```markdown 包裹)。"""
m = re.search(r"```(?:markdown|md)?\s*(.*?)```", text, re.DOTALL)
if m:
return m.group(1).strip()
return text.strip()
# --------------------------------------------------------------------------- #
# Reviewer 的审查评分标准(Proposer / 单 Agent / 独立评委共用同一套 rubric)
# --------------------------------------------------------------------------- #
REVIEW_RUBRIC = """你是一名严格的演示文稿质量审核员(Reviewer)。你会看到一份由 Slidev 渲染出的 PPT,
每张图对应一页幻灯片(按顺序编号,从第 1 页开始)。请逐页检查以下问题:
- text_overflow(文字溢出/被裁切超出页面边界)
- overcrowded(内容过多/过于拥挤/留白不足)
- image_size(图片过大顶出布局,或过小看不清)
- readability(字号过小、对比度差、代码块难读)
- layout(对齐混乱、标题与正文比例失衡、空页)
请以**目标用户是听众**的严格标准审查——一页幻灯片若要点超过约 5 条、或正文文字块偏长、
或图片挤压了文字空间,都应视为 overcrowded/image_size 问题。报告真实存在的问题,
但不要放过"塞得太满"。对每个问题给出:page(页码,整数)、
issue_type(上面之一)、severity(high/medium/low)、suggestion(具体、可执行的修改建议,中文)。
同时给出:
- overall_score:0-100 的整体质量分(越高越好)
- pass:布尔值,仅当整份 PPT **既无 high 也无 medium 级问题**、排版干净可读时才为 true
严格输出如下 JSON(不要输出任何多余文字):
{
"overall_score": <int>,
"pass": <bool>,
"issues": [
{"page": <int>, "issue_type": "<type>", "severity": "<high|medium|low>", "suggestion": "<中文建议>"}
]
}"""
class Reviewer:
"""审核者 Agent:看最新一版渲染截图,输出结构化 JSON 建议。每轮独立调用、无历史。"""
def __init__(self, meter: TokenMeter):
self.client = _client()
self.meter = meter
def review(self, png_paths: list[str]) -> dict:
content = [{"type": "text",
"text": f"这份 PPT 共 {len(png_paths)} 页,下面按页码顺序给出每一页的渲染截图。请审查。"}]
for i, p in enumerate(png_paths, 1):
content.append({"type": "text", "text": f"第 {i} 页:"})
content.append({"type": "image_url",
"image_url": {"url": encode_image(p), "detail": "high"}})
resp = self.client.chat.completions.create(
model=VISION_MODEL,
messages=[
{"role": "system", "content": REVIEW_RUBRIC},
{"role": "user", "content": content},
],
temperature=0.2,
)
self.meter.add(resp.usage)
return _extract_json(resp.choices[0].message.content)
PROPOSER_SYSTEM = """你是一名擅长把学术论文转化为演示文稿的 Proposer Agent。
你用 Slidev 框架(Markdown + HTML)编写 PPT 源码 slides.md。
Slidev 语法要点:
- 文件开头是 YAML frontmatter(--- 包裹),设置 theme: default。
- 用单独一行的 `---`(前后空行)分隔每一页幻灯片。
- 首页通常放标题、作者、会议。
- 引用图片用 markdown:,可用 HTML 控制尺寸,
例如 <img src="/speedup_bar.png" class="h-60 mx-auto" />。
- 可用 Windi/Uno CSS 工具类控制排版(如 text-sm、grid grid-cols-2 gap-4)。
要求:
- 生成约 8-12 页,覆盖论文的标题、背景/动机、方法、实验结果、结论。
- 至少在 3 页中使用提供的图表/表格,且图文匹配。
- 每页信息量适中、不要塞太多字,宁可拆页也不要溢出。
- 只输出 slides.md 的完整内容,用 ```markdown 代码块包裹,不要额外解释。"""
class Proposer:
"""提议者 Agent:只吃文本(论文 + 累积文字反馈),产出 slides.md。"""
def __init__(self, meter: TokenMeter, paper_md: str, figures: dict):
self.client = _client()
self.meter = meter
fig_desc = "\n".join(f"- {name}:{desc}" for name, desc in figures.items())
first_user = (
f"以下是论文全文(Markdown):\n\n{paper_md}\n\n"
f"可直接引用的图表文件(放在 Slidev public 目录,用 /文件名 引用):\n{fig_desc}\n\n"
f"请先做一版**快速初稿**:为了尽快出稿,把整篇论文压缩到 **4 页以内**——"
f"直接把每个章节对应的**完整段落原文**成段贴到幻灯片上(保留整段文字,先不要精简成要点),"
f"并把两张图表也放进去。(后续会有审核者看真实渲染效果再帮你调整。)生成完整的 slides.md。"
)
# Proposer 的对话历史——只累积文本,永不加入图片
self.messages = [
{"role": "system", "content": PROPOSER_SYSTEM},
{"role": "user", "content": first_user},
]
def _generate(self) -> str:
resp = self.client.chat.completions.create(
model=TEXT_MODEL, messages=self.messages, temperature=0.3,
)
self.meter.add(resp.usage)
reply = resp.choices[0].message.content
self.messages.append({"role": "assistant", "content": reply})
return _extract_slides_md(reply)
def propose(self) -> str:
"""首轮生成。"""
return self._generate()
def revise(self, review: dict) -> str:
"""根据 Reviewer 的结构化文字反馈修订(只把 JSON 文本加入上下文)。"""
feedback = json.dumps(review, ensure_ascii=False, indent=2)
self.messages.append({
"role": "user",
"content": (
"审核者(Reviewer)渲染了你上一版 slides.md 的每一页截图,"
"给出如下结构化改进建议(JSON):\n\n"
f"{feedback}\n\n"
"请理解这些问题并修订 slides.md(可拆页、精简文字、调整图片尺寸等),"
"重新输出完整的 slides.md。"
),
})
return self._generate()
# --------------------------------------------------------------------------- #
# 单 Agent 自审对照组:同一段对话里既生成、又看自己的渲染图、又修订。
# 关键区别:历次渲染的图片会**留在**同一上下文里,导致上下文随迭代快速膨胀。
# --------------------------------------------------------------------------- #
SELF_REVIEW_SYSTEM = PROPOSER_SYSTEM + """
此外,你还要**自我审查**:当收到自己 PPT 的渲染截图时,先在心里按下列标准找出问题
(文字溢出、内容拥挤、图片尺寸、可读性、布局),再据此输出修订后的完整 slides.md。"""
class SelfReviewAgent:
"""单 Agent 自审:一条不断增长的对话,图片累积在上下文中。"""
def __init__(self, meter: TokenMeter, paper_md: str, figures: dict):
self.client = _client()
self.meter = meter
fig_desc = "\n".join(f"- {name}:{desc}" for name, desc in figures.items())
first_user = (
f"以下是论文全文(Markdown):\n\n{paper_md}\n\n"
f"可直接引用的图表文件:\n{fig_desc}\n\n"
f"请先做一版**快速初稿**:为了尽快出稿,把整篇论文压缩到 **4 页以内**——"
f"直接把每个章节对应的**完整段落原文**成段贴到幻灯片上(保留整段文字,先不要精简成要点),"
f"并把两张图表也放进去。(之后你会看到真实渲染截图再据此调整。)生成完整的 slides.md。"
)
self.messages = [
{"role": "system", "content": SELF_REVIEW_SYSTEM},
{"role": "user", "content": first_user},
]
def propose(self) -> str:
resp = self.client.chat.completions.create(
model=VISION_MODEL, messages=self.messages, temperature=0.3,
)
self.meter.add(resp.usage)
reply = resp.choices[0].message.content
self.messages.append({"role": "assistant", "content": reply})
return _extract_slides_md(reply)
def self_review_and_revise(self, png_paths: list[str]) -> str:
"""把最新渲染截图加入**同一**上下文,让模型自审并修订。图片会一直留在历史里。"""
content = [{"type": "text",
"text": (f"这是你上一版 slides.md 渲染出的 {len(png_paths)} 页截图。"
"请自我审查(文字溢出/拥挤/图片尺寸/可读性/布局),"
"然后输出修订后的完整 slides.md。")}]
for i, p in enumerate(png_paths, 1):
content.append({"type": "text", "text": f"第 {i} 页:"})
content.append({"type": "image_url",
"image_url": {"url": encode_image(p), "detail": "high"}})
self.messages.append({"role": "user", "content": content})
resp = self.client.chat.completions.create(
model=VISION_MODEL, messages=self.messages, temperature=0.3,
)
self.meter.add(resp.usage)
reply = resp.choices[0].message.content
self.messages.append({"role": "assistant", "content": reply})
return _extract_slides_md(reply)
def independent_judge(png_paths: list[str], meter: TokenMeter) -> dict:
"""用同一套 rubric、独立地给某一版最终 PPT 打分,用于公平比较两种方案的质量。"""
reviewer = Reviewer(meter)
return reviewer.review(png_paths)