ppt-storyboard

name	ppt-storyboard
description	当需要把任务包、研究结果、风格规格和模板约束转换成固定 schema 的分页叙事结果，并供前端展示和后续页面生成直接消费时使用。

PPT 分页叙事

storyboard.json 是默认必产工件，也是前端契约。将上游所有工件收束为固定 schema 的分页叙事，供前端展示和 ppt-page-html 直接消费。

目标

同时满足三件事：

1. 前端可稳定展示阶段性结果。
2. 用户可基于页面级对象进行局部修改。
3. ppt-page-html 可以直接消费。

触发条件

• task-pack.json、info-pack.json 和 style-spec.json 已产出。
• 如果 research_required 为真，research-pack.json 也必须已产出。
• 由 ppt-superpower 在流水线中调度进入。

输入

• task-pack.json：任务边界、页数、deck_dir、content_density_profile。
• info-pack.json：分页前的唯一信息来源，包含所有可见信息的 InfoAtom。
• style-spec.json：设计控制面、density_rules、page_type_variants。
• research-pack.json（按需）：结构化内容池。
• template-pack.json（按需）：模板约束。

消费前必须先确认以上工件真实存在且可读。如果目标文件不存在、路径不一致或关键字段缺失，先返回缺失依赖并补齐上游工件，不要猜测。

输出

• 输出路径：${deck_dir}/storyboard.json。
• 不要手写、缩写、翻译或重拼 deck_dir。
• storyboard.json 为默认必产。

执行规则

页面编排

• 页数必须严格匹配 task-pack.json 要求。
• 页面自然语言内容默认与用户 query 保持一致。
• 页面顺序必须体现清晰叙事，而不是堆砌信息。

payload_budget 规则

• 必须先读取 task-pack.json.content_density_profile，结合 page_type、narrative_role 和 style-spec.json 中已声明的 density_rules，把 content_density_profile 转成可执行的 payload_budget。
• 每页必须声明页级 payload_budget，不要只停在 deck 级 profile 描述。
• payload_budget 至少要写出 claim_count、evidence_count、structure_block_count 和 require_comparison_or_summary，供后续 ppt-page-html 直接消费。
• analysis-heavy 下的分析类页应给更高预算：允许更多 claim / evidence，并且优先要求 2 块以上结构块，必要时要求对比或摘要。
• balanced 采用中位预算，让正文页既不空也不过载。
• showcase-light 下的展示类页预算可以更轻，但仍要明确最低承载，不要把内容责任完全让给主视觉。
• 分析类页与展示类页不能共用同一套预算；前者更强调论点、证据和结构块，后者更强调聚焦表达与节奏控制。

content_blocks 与 source ID 引用

• 不允许只拿 research 主题词重新写一遍；必须把 research 中可上页的 claim、evidence 和未解决缺口落到页面级对象。
• 每页必须能说明主 claim 和 evidence 从哪里来。
• 每个 content_blocks[n] 都必须显式填写 source_claim_ids 与 source_evidence_ids，引用 research-pack 中实际存在的条目，而不是写模糊主题词。
• 未触发 ppt-research-pack 时，source_claim_ids 与 source_evidence_ids 应保留为空列表；这是合法状态，不要伪造引用。
• 缺证据时要显式记录 unresolved_gaps，不要假装内容已经闭环。

info-pack 与可见信息回指

• info-pack.json 是分页前的唯一信息来源。
• 页面上所有可见信息都必须先在 storyboard.json 中显式出现，不要把页面上的次级文案、数值或图表数据留到 ppt-page-html 再现场补编。
• 页面标题必须显式记录 title_atom_ids，指向 info-pack.json 中实际存在的 InfoAtom。
• 每页还必须显式声明 display_items，覆盖标题之外的正文、数值、图表数据、标签、caption、脚注等可见信息。
• 每个 DisplayItem 都必须填写 atom_ids，引用 info-pack.json 中实际存在的条目；不要只写自然语言主题词。
• 图表页必须把图表标题、系列名、数值、图例、表格行等可见数据显式写进 display_items，并在 payload 中保留结构化字段。
• 不要只写一句摘要型 display_item，然后把真正的图表系列和值留给 ppt-page-html 去猜。
• layout_intent 和 data_requirements 不能替代显式图表数据；前者只描述布局意图，后者只描述仍需补齐或核验的数据缺口。
• display_items 只需要轻量记录用户可见信息与引用 ID，不要把整段来源全文复制进 storyboard。
• 如果 info-pack.json 中缺少某页所需的信息，应在 display_items 或 unresolved_gaps / unresolved_issues 中显式留下缺口，不要补编。

style_variant 映射

• style_variant 必须直接引用 style-spec.json 中已声明的 variant 映射，不要重新发明一套名字。
• style_variant 不要把它写成宽泛形容词；它必须是后续 ppt-page-html 可直接按 variant 落地的键。

asset_requirements 规则

• 不要只写模糊的槽位名；要用能指导后续分流的提示，例如 svg-illustration、svg-icon、real-photo、qr-placeholder。
• 资产类型判断必须先看页面语义，再看风格偏好。
• 如果页面要呈现人物、产品、空间、场景、活动现场、作品样张、环境氛围等真实对象，默认应规划为 real-photo，必要时可叠加 svg-illustration 或 svg-icon 做装饰。
• 如果页面布局需要多张独立真实图片，asset_requirements 必须拆成多个可追踪槽位，不要只写一个泛化的 real-photo。
• 人物卡、产品卡、双图对照、瀑布流图组、多列样张展示这类布局，都要把每个独立图片位单独写清。
• 不要让三张人物卡只共享一个宽泛的 real-photo 要求；否则后续 ppt-asset-plan 和 ppt-review 无法判断是否缺图。
• 插画感 只影响装饰语法、背景氛围和前景点缀，不等于把证据型图片全部改成 svg-illustration。
• 不要因为风格里有插画感、手作感、童趣感，就把整套 deck 的图片需求都改写成 svg-illustration。

问题与缺口记录

• unresolved_gaps 只承接块级内容 / 证据 / claim 缺口。
• unresolved_issues 只承接页级问题，例如布局、资产、待确认页级约束。
• 每页必须显式记录 asset_requirements 与 unresolved_issues，便于后续局部修复。

其他

• presenter_intent 只表达讲述意图，不承担完整讲稿。

数据结构

from typing import Any, Literal

Json = dict[str, Any]

Mode = Literal["fast", "guided", "surgical"]


class Storyboard:
    schema_version: str
    ppt_title: str
    language: str
    total_pages: int
    mode: Mode
    pages: list["StoryboardPage"]


class StoryboardPage:
    page_id: str
    page_number: int
    title: str
    title_atom_ids: list[str]
    page_type: str
    section: str
    narrative_role: str
    audience_takeaway: str
    layout_intent: str
    style_variant: str
    payload_budget: "PayloadBudget"
    content_blocks: list["ContentBlock"]
    display_items: list["DisplayItem"]
    visual_requirements: list[str]
    data_requirements: list[str]
    asset_requirements: list[str]
    unresolved_issues: list[str]
    presenter_intent: str


class PayloadBudget:
    claim_count: int
    evidence_count: int
    structure_block_count: int
    require_comparison_or_summary: bool


class ContentBlock:
    block_id: str
    heading: str
    summary: str
    source_claim_ids: list[str]
    source_evidence_ids: list[str]
    unresolved_gaps: list[str]


class DisplayItem:
    item_id: str
    kind: str
    text: str
    payload: Json | None
    atom_ids: list[str]
    block_id: str | None

用户回显

• 开始反馈：说明正在把任务包、info-pack、research 条目和风格规格转成分页叙事，并指出会产出 storyboard.json。
• 完成反馈：概括总页数、主要章节、页面分布、未解决项数量和 下一步。
• 如果当前处于 guided 模式，完成反馈必须明确提示用户现在可以先审阅 storyboard.json，不要只返回一段自由文本大纲。

关键原则

• storyboard 是 research 的消费层。
• info-pack.json 是 storyboard 的唯一信息来源。
• storyboard.json 为默认必产。
• 页数必须严格匹配任务包要求。
• 页面顺序必须体现清晰叙事，而不是堆砌信息。
• 每页必须声明页级 payload_budget。
• 每个 content_blocks[n] 都必须有可追溯的 source ID。
• 每页标题和其余可见信息都必须显式回指 info-pack.json 中的 atom_id。
• 图表页不能只靠摘要和 data_requirements 驱动；系列名、标签、数值、图例必须显式进入 display_items。
• style_variant 必须映射到 style-spec.json 中已声明的 variant。
• asset_requirements 必须拆到可追踪粒度。

禁止事项

• 不要退回旧 outline 的松散结构。
• 不要把完整讲稿直接塞进 storyboard.json。
• 不要让前端需要猜字段含义。
• 不要伪造 source_claim_ids / source_evidence_ids 引用。
• 不要让页面上的标题、正文、数值、图表数据、标签或 caption 只存在于 HTML，不存在于 storyboard.json。
• 不要把页面上的次级文案、数值或图表数据留到 ppt-page-html 再现场补编。
• 不要让图表页只留下摘要型 display_item，再让 ppt-page-html 根据 layout_intent 或 data_requirements 自行推断系列数据。
• 不要因为风格里有插画感，就把整套 deck 的图片需求都改写成 svg-illustration。
• 不要让多个独立图片位共享一个泛化的 real-photo 要求。