Sysu Ppt

SYSU PPT Skill

用 R officer + 官方模板，代码化生成内容清楚、版式克制、可直接上台的学术汇报 PPT。给定主题/内容/要求，按本文件流程即可产出合规 PPT。

模板选择前置条件（CRITICAL）

• 只在用户已经明确中山大学场景，或经 pptx 的模板来源分流选择中大官方模板后执行本流程。用户只说“做 PPT / 开题汇报 / 答辩”但未说明模板来源时，先按 pptx 询问，不得默认中大。
• 每个新建的中大汇报必须读取 assets/template.pptx 或用户明确选择的 assets/template-公卫学院.pptx，并通过 source(.../sysu_toolkit.R)、sysu_init(...) 和 sysu_save(...) 生成。绕过 sysu_init() 从空白画布仿制配色、校徽或水印，视为未使用模板、任务未完成。
• 用户提供其他学校、机构、会议或自定义模板时转 pptx 的模板编辑流程，不得把该文件改套成中大模板，也不得自行伪造对方官方品牌。
• 写逐页故事板前在内部记录已选模板及依据；交付前从生成脚本和渲染页同时核验模板来源。模板资产缺失或无法读取时停止生成，报告具体路径，不静默改成无模板设计。

总原则（奥卡姆剃刀）

精确实现每一条要求，不堆字、不过度设计。 “内容丰富”指主信息、证据或结构与必要解释已经完整对应，不是元素更多。若已有材料能够提供对象、依据、做法、条件、影响或限制，却只写几个标签和单行概述，页面仍属未完成；先从材料补足本页所需内容，再判断是否需要拆页。完整的段落页可以保留有意留白；材料不足以支撑独立页面时与相邻页合并，不用大号数字、装饰图或额外分区填空，也不编造信息。

体裁与结构蓝图（先认体裁再开写）

先判断体裁，再从对应蓝本中选取适用模块。蓝本是论证结构参考，不是逐页清单：

先满足用户明确页数或时长；未指定时根据内容之间的关系自然决定。删除没有实际内容的部分，合并证据不足的相邻页，只有一页无法清楚表达时才拆页。不得为了靠近参考规模补页，也不得假设示例中的每一页都必须生成。

组会体裁要求（CRITICAL，违反 = 未完成）

• 组会 PPT 禁止目录页：不得出现“目录 / 汇报提纲 / 内容提要 / Agenda / Contents”等单独页面。
• 组会 PPT 禁止任何章节分隔页或过渡页：封面后直接进入第一张实质内容页，主题切换直接用内容页标题编号表达，不插入只有章节名、序号或短副标题的空转页面。
• 组会生成脚本禁止调用 sysu_add_section()。该函数只属于开题、答辩、中期和正式研究汇报。
• 组会必须用 sysu_save(ppt, path, genre = "meeting")；meeting 也是默认值，保存前会检测目录页与章节分隔页，命中即停止写出。正式体裁必须显式使用 genre = "formal"。

开题/答辩体裁的常见模块、规范用词库（章节名 / 段落标签 / 方法对比表头 / 封面署名 / 结尾语）和设计基调在 references/defense_blueprint.R 顶部。写作前先读，但只选与用户要求和研究设计有关的模块；保留必要的论证先后关系，不机械填满全部示例页。

逐页设计说明

写内容前先读 references/slide-design-practice.md 并建立逐页故事板，至少记录“结论式名词短语标题、主信息、证据或结构、解释或边界、主视觉、版式、口头内容”。

• 一页一条主信息：标题不能只是“背景 / 方法 / 结果”，应概括本页结论、关系或分析边界。每张实质内容页只保留一条主信息、最强支撑和一条必要解释；没有证据时不得为了完整感编造数字、图或文献。
• 主信息—证据—解释完整对应：证据可以是真实统计图、文献事实、比较表、流程、机制、公式、代码或实际截图。定义、目的和边界页可以没有图片，但必须有清楚的信息层级。
• 版式服从内容而非配额：同一论证允许连续使用相同的自然段版式；只要每页承担清楚的语义单位且排版可读，不要求在固定页数内更换构图，也不把连续文字页判为失败。
• 一个视觉焦点：页面确有图、表、公式或代码时只保留一个焦点，并按阅读所需尺寸放置。普通公式、样本量、轮次数和组合数不因页面留白而放大成海报主视觉。
• 页数服从内容：页数、章节和每页构图都由用户要求、时长、内容关系与证据量决定。参考结构、在线经验和示例文件只帮助估算和选择版式，不规定固定页数。
• 内容优先的审美基线：普通科研内容页默认使用一个明确标题和 1–3 个自然段或简单表格；美观来自字体层级、左对齐、稳定间距、适中行长和留白。不要用可编辑的装饰性左栏、眉题、徽章、KPI 面板、孤立的大号关键词或数字、四宫格、渐变、厚重阴影、装饰性横线或无语义图标把科研汇报做成展报。
• 版式按信息关系选择：纯文字页、图文页、比较表、时间结构、流程图和整图页都可以成立。若多个等大文字框只是为了“排满”，必须改成段落、双栏、表格或拆页；若连续自然段最清楚，就保持稳定版式，不为变化而制作解释图。
• 设计基调（两类通用）：主色中大深绿 #014924；强调红 #C00000 全篇仅用于 1–2 处关键结论。统一标题、字体、题注、图号和页码，变化来自内容关系、图文比例、视觉权重和留白。
• 模板适配（两类通用）：官方模板只规定画布、母版、校徽或水印、字体、主色、标题与页码。按顺序、比较、层级、时间、证据或场景关系选择版式；模板导致文字过小、关系隐藏、比较失衡或出现大量重复卡片时，必须重排或拆页，不得为套用模板牺牲科学表达与可读性。

工作流（复制即用）

Sys.setlocale("LC_ALL", "Chinese (Simplified)_China.utf8")
skill_roots <- path.expand(c(
  Sys.getenv("EPIAGENTKIT_SKILLS"), Sys.getenv("EPICLAUDE_SKILLS"),
  "~/.claude/skills", "~/.agents/skills", "~/.codex/skills"
))
skill_dirs <- file.path(skill_roots[nzchar(skill_roots)], "sysu-ppt")
SKILL <- skill_dirs[dir.exists(skill_dirs)][1]
if (!length(SKILL) || is.na(SKILL)) stop("找不到 sysu-ppt；请设置 EPIAGENTKIT_SKILLS")
source(file.path(SKILL, "scripts", "sysu_toolkit.R"))

ppt <- sysu_init("default")          # 默认=原“模板2”中大医学版；旧公卫模板可用 sysu_init("模板2")
ppt <- sysu_add_cover(ppt, "主标题", "English Subtitle", "汇报人：姓名", "2026 组会")
ppt <- sysu_add_text(ppt, "1 背景", block_list( prose(bd("定义　"), tx("……")) ))
# ……更多内容页（见 API）……
sysu_save(ppt, "输出.pptx", genre = "meeting")  # 组会：强制禁目录/章节过渡页

完整示例见 references/deck_skeleton.R；逐页设计与版式选择见 references/slide-design-practice.md；配图函数见 references/figure_snippets.R。

模板选择

• 未指明 / 模板1 / medical → sysu_init("default") = assets/template.pptx（原模板2：中大医学棕榈实景封面 + 校徽 + 城市水印）。
• 用户说"模板2/模板二/公卫" → sysu_init("模板2") = assets/template-公卫学院.pptx（原模板1：公卫学院绿色封面 + 标题绿竖条）。
• 也可传 .pptx 完整路径。两套模板内容页 API 完全一致，只改 sysu_init 参数。

硬性规范（每次必须满足）

1. 字体：中文宋体、英文 Times New Roman，同段自动分流（.fp() 内置，无需手动切）。已在 slide XML 层校验 <a:ea>=宋体、<a:latin>=Times New Roman。
2. 字号：标题默认 24pt；正文 16pt 只作为信息密集页的下限，不是所有页面的目标字号。内容允许时使用 18–20pt；只有效应估计等主要结果需要单独强调时才适度提高字号，并同时保留定义和不确定性。样本量、轮次数、组合数和普通关键词不做成孤立的大号数字。最终以 1280 × 720 导出图验收，不机械放大以填补留白。
3. 内容驱动版式：执行逐页设计说明，根据信息关系选择纯文字、图文、表格、公式、比较、时间、流程或整图。组会可以连续多页使用自然段；也不把“每页有图”当目标。图像只用于真实对象、统计证据，或文字和表格难以同样清楚表达的结构、机制、时间和操作关系。
4. 充实靠信息完整性，不靠展示形式：研究依据、定义、方法解释、证据评述和边界说明默认使用 1–3 个完整段落，每段围绕一个论点自然展开，并从已有材料补足本页实际需要的对象、依据、过程、条件、含义或限制。有材料却只写“研究背景：很重要”“影响：影响下一步”之类标签式短句不得交付。同一解释可按语义延续到下一页，不把连续论证强拆成卡片、编号列或箭头链。公式页使用“可读公式 + 邻近解释段落”，不设置大面积顶栏、海报分区或口号页脚。少量数字用完整句子或简单表格，卡片只用于真正并列的短对象。officer 文本框不自动缩字：左右图文 / 左文右表的左栏最多 5 块、约 12 行 / 230 中文字，纯文字全宽页最多 7 块 / 340 字；这是防溢出上限，不是填充目标。超出后删次要句或拆页，绝不缩小字号。生成后逐页检查最后一行是否压到页眉、页脚或页码。
5. 编号体现真实层次（最多两级，编号只在内容页标题）：同主题确有多页时才使用 1.1 / 1.2 等二级编号；单页主题不为凑层级增设子页，正文不写 1.1.1。编号随实际论证结构生成，不得反过来驱动补页，也不得据此为组会生成目录或章节过渡页。
6. 章节分隔页严格按体裁隔离：组会汇报不得调用 sysu_add_section()，不得添加目录、汇报提纲或任何过渡页，封面后直接进内容；开题、答辩和正式研究汇报只有在用户要求、既有模板或篇幅层级确实需要时才使用章节页、目录与致谢页（见 defense_blueprint.R）。
7. 强调：关键术语/结论用 bd()（加粗+主色）。 7bis. 统一从项目结果文件取数：汇报中的估计值、置信区间、P 值、百分比和样本量，如果项目有 results/results.yaml，一律按每项结果的固定名称读取；旧项目可读取旧版结果文件。禁止手工输入关键数字；数字需要变更时，回到实际生成结果的脚本，并重新生成所有使用该结果的文件。
8. 编号与圆点二选一：用了 ①②③/123 就别再加 ●（用 num_item，不要 bullet）。
9. 学术书面、不口语（每页都查）：
   • 段落小标签用规范词：解决问题 / 指标计算 / 检验 / 局限性 / 定义 / 说明 / 注意事项 / 方法 / 重要性 等。禁用敷衍或口语标签：✗"一句话""坑""怎么读""怎么办""通俗讲""回答"。
   • 删空话/敷衍句：没有信息量的 intro/note（如"这几乎覆盖了最常见的误用""核心：…"）直接删，不靠它凑版面。
   • 不用网络口语：✗ 净赚、听得懂、一验就掉、学过头、乱筛、当万能、迷信、纹丝不动、虚高… → 改书面表达（净获益、可理解、外部验证性能下降、过度拟合、随意筛选、过度依赖、偏高…）。
10. 当前版单一、旧版整组归档：当前汇报目录只保留稳定命名的 .pptx、当前生成脚本和必要素材，不生成“完善版 / 最终版 / v2 / final”等并列文件。每次重生成前，把被替代 PPT、对应旧脚本、渲染页图与旧素材按原相对目录移入 09_backup/archive/YYYY-MM-DD_HHMM_<汇报主题>_<阶段>/，写 MANIFEST.md 并登记 09_backup/INDEX.md；sysu_save() 始终写当前稳定文件名。

API 速查

文本助手：tx(text,size) 正文 / bd(text,size) 加粗主色 / cd() 等宽 / prose(...,line_spacing,space_after,space_before) 成段 / num_item(...,size,line_spacing,space_after) 编号条目 / bullet(...,size,line_spacing,space_after) 圆点列表 / sp(h) 间距。解释页优先用 prose() 保留完整论证；字号与间距在可读范围内按文字量调整，不用来填满页面或掩盖内容缺口。 表格：sysu_flextable(df, widths, fsize, align) — 绿表头 + 斑马行 + 三线表。

卡片约束（默认不用）

• 卡片不是科研 PPT 的默认版式。先用 prose()、num_item()、sysu_add_two_text() 或 sysu_add_table() 表达内容；只有用户明确要求卡片，或页面确实需要比较 3–4 个同层级短对象时才调用。
• sysu_add_cards() 只接受短对象：每项应是短名称、关键差异和适用边界；解释性长句、因果链、下一步、创新点、可行性和结论不得直接装进卡片。两项可作为双栏短并列例外；四项不再自动生成 2×2，未明确指定布局时会停止并提示改用段落、双栏、表格或拆页。
• 卡片页不应连续出现，也不应成为全篇主要构图。单页仍统一使用近白底、细边框和单一品牌强调色；禁止随机换色、高饱和彩色方块、厚重阴影、装饰图标和为填满页面而拉高卡片。
• 卡片正文超过约 2–3 个显示行，或两行卡片需要放入完整段落时，必须删减为短语、改用非卡片版式或拆页；不能依赖缩小字号或扩大空洞卡高。

配图（确认必要后使用 research-visuals）

• 配图先问“这张图是否比自然段或简单表格更清楚地提供证据或关系”。只接受真实对象、组织关系、解释机制或证据四类功能；若几段文字已能直接说明研究依据或方法，就保留段落页。纯装饰图、剪贴画、无语义图标、伪造界面和低清拼贴不得进入实质内容页。外部图必须核验来源、许可和分辨率，不得放大超过原始尺寸；真实界面与分析产物使用实际截图。
• 开题、答辩、中期和正式研究汇报生成前阅读 ../research-visuals/references/research-figure-patterns.md，逐页标记主要表达方式和是否确实需要图。背景页默认使用论点、自然段和引文，存在真实统计证据时可用统计图；方法页只为难以用段落或表格说明的时间、空间、变换、模型分支和验证关系配图；创新、可行性和研究计划优先结构化文字、真实前期结果和简单计划表。
• 只有逐页设计已经确认需要表达流程、结构、技术路线、包含关系、概念框架、机制或研究场景时，才调用 research-visuals。封面沿用官方模板主视觉，不为显得丰富自动增加生成图；研究背景也不默认生成图片。确需图时，先读取实际模板、图片区、标题位置和配色，并按 ../research-visuals/references/carrier-specs.md 与 ../research-visuals/references/scenario-playbook.md 区分正文内容图和氛围图。Codex 有工具时直接使用内置 imagegen/image_gen，以高质量 PNG 嵌入 sysu_add_image*。只有 imagegen 实际不可用、用户明确要求 SVG/矢量源、编辑现有 SVG 或目标格式强制矢量时才使用 svg-diagrams；不得因生成结果不准确或不好看而切换。统计图仍走 publication-figures。
• 图位于侧栏时通常占 30%–45%；机制图占 45%–60%；分步方法采用文字 30%–35% 加图 55%–65%；总体技术路线占标题以下正文区 70%–90%，页内不再并列长段正文。多图必须等高对齐并逐图题注。
• 技术路线至少按项目实际覆盖“研究对象/数据源 → 采集与整合 → 纳排/清洗/QC → 变量或特征构建 → 研究问题及对应方法 → 验证/分层/敏感性 → 输出与解释”。研究问题与方法成对表达，不得只罗列模型名。复杂方法可复用同一总体图，并逐页突出当前讲解的部分。
• imagegen 图先按 research-visuals 在原始分辨率与实际幻灯片中双重核验。流程、框架和路线图逐字检查标签、数字、节点和箭头；有误时最多用 imagegen 定向修改两轮，不得用 Python、PPT 文本框或 SVG 覆盖层补字。第二次修改后保留当前图，披露内容硬伤、审美问题和实际页面影响，由用户决定是否继续。PPT 主视觉和章节配图默认不烧录标题或正文，由幻灯片原生文本承担。
• 图内不写标题、不写解释性句子（最常被打回）：删掉 labs(title=...)、删掉像"偏离对角线 = 概率不准""模型净获益最高的阈值区间"这类讲道理的 annotate("text")。图里只保留坐标轴、图例、必要的数据标签（如曲线旁的"病例/非病例"、参考线旁的阈值数值）。解释一律写到 PPT 正文或题注。
• 证据图、统计图、方法示意和技术路线必须有题注：黑色、小字号(13pt)、居中、置于图下方。外部图同时在邻近位置或页脚写来源。用各 sysu_add_image* 的 caption= 参数；需要编号的图按出现顺序连续使用 图1/图2…。封面主视觉、纯背景图和章节氛围图不编号，也不强加题注。
• 图例要短：不要把整句解释当图例标签（如"过度极端 slope<1（概率太极端）"）；缩成"slope<1 概率太极端"这类短词，解释移正文。图例条目过长且使用 coord_equal 时，图例与绘图区之间常出现大块空白，可使用 coord_cartesian(expand=FALSE) 并缩短标签。
• 图内字要够大（最常被打回的问题）：统计图按接近嵌入尺寸渲染并放大字号；imagegen 流程/框架图按实际占位比例生成，节点标题与组标题在缩略图上仍须清晰，分支标题不得缩成注脚。发现字小一律回到 imagegen 完整图定向修正或重生成，不在 PPT 中补字或拉伸补救。
• 图不能有多余留白或空边：ggsave 的画布长宽比要贴合内容，否则四周会出现不必要的空白。ROC、校准图等可用 coord_cartesian(expand=FALSE) 让绘图区充分利用画布；谨慎使用 coord_equal，因为它会把绘图区固定为正方形，常在另一方向留下大块空白。注释和图例应适当收紧，plot.margin 可按需减小。检查发现图的上下或左右有空条时，调整画布比例或坐标设置后重新生成。
• 中文统计图使用 showtext，从当前系统已有字体中按候选路径检测并注册；找不到兼容字体时报告缺口，不硬编码单一 Windows 路径，也不安装字体。
• 嵌入 img_w/img_h 只是最大边界框，.fit() 自动按 PNG 真实比例等比缩放，不会变形；给的比例不必精确。

自检（生成后必跑）

$pp = New-Object -ComObject PowerPoint.Application
$pres = $pp.Presentations.Open("绝对路径.pptx", $true, $false, $false)
$pres.Export("png输出目录", "PNG", 1280, 720)
$pres.Close(); try { $pp.Quit() } catch {}

逐页读 PNG 检查（每一项不合格都要改了重生成，不许将就）： ⓪ 模板来源检查：生成脚本已 source(.../sysu_toolkit.R) 并调用一次 sysu_init(已选模板)，输出封面与内容页可见所选模板的母版品牌元素；未从空白画布仿制模板。 ⓪bis 组会体裁检查：无目录/汇报提纲/Agenda 页，无章节分隔/过渡页；封面下一页即实质内容；生成脚本无 sysu_add_section()，并以 genre = "meeting" 保存。 ① 字体对（宋体/Times）；② 面积与位置合理——正文、公式、图表和留白与信息量匹配，无无意义左栏、大面积顶栏或上下展报分区，也不溢出或截断；②bis 段落内容完整——已经从现有材料写清本页实际需要的对象、依据、做法、条件、影响或限制，不是几个标签配单行空泛说明；无材料时已合并薄页而非编造或装饰；③ 逐页配图决策合理——不需要图的页面保留自然段或简单表格，需要图的页面能明确回答对象、证据、机制、时间或路径问题；④ 图内文字够大且逐字准确——流程图/框架图框内字、坐标轴、注释在缩略图上仍清晰可读，偏小或错误在两轮上限内回到 imagegen 修正，达到上限后明确披露；⑤ 图无多余空边——图四周没有明显空白条，有则调 imagegen 构图、SVG 画布或统计图输出比例重渲染；⑥ 非统计图关系正确——节点、箭头、方向和层级与来源逐项一致，无伪文字、重复节点或无语义装饰；技术路线从数据源开始，完整呈现到验证与输出；⑦ 来源与证据属性正确——外部图可追溯，无水印、低清截图、缺图占位符和混杂画风；⑧ 模板按内容适配——母版品牌元素保留，但结构、密度、图文比例、留白和视觉权重已按本页信息关系优化，无机械套版、卡片墙或硬塞；⑧bis 科研汇报而非展报——页面没有额外的装饰性左栏、眉题、徽章、KPI 面板、孤立大号关键词/数字、口号页脚、四宫格、重复信息框、渐变、厚重阴影、无语义图标或装饰性横线；连续自然段页不因版式相同而判为问题；⑨ 表格上下居中——表格块在内容区垂直居中而非贴顶；⑩ 图居中不变形；⑪ 重点已加粗；⑫ 页眉对齐正确——默认模板的标题横线与左侧两块绿色矩形底边共线，公卫模板的标题横线与绿色竖条底边共线；⑬ 图内无重复标题、无解释性长句，内容图保留必要节点标签，讲道理的文字写到正文或题注；⑭ 题注使用正确——证据图、统计图、方法示意和技术路线有题注且编号连续，封面与纯背景图不强加编号；⑮ 图例简短；⑯ 学术书面（见硬性规范 9）。 归档检查：当前目录仅保留一份稳定命名 PPT 与当前源；无“完善版 / 最终版 / v2 / final”等旧版；旧版批次可由 09_backup/INDEX.md 定位且含 MANIFEST.md。

图件大于 ~2000px 时图像读取工具可能报错，可先缩放到 ≤1280px 再读；或直接读 1280×720 的逐页导出 PNG。 只关闭本次自动化创建的 presentation 与 PowerPoint application 实例。不得用 Stop-Process 结束用户其他 PowerPoint 进程；若文件仍被占用，报告具体路径并停下等待用户关闭占用者。

已处理的常见问题

• 默认模板设计在 layout 而不在 master：当前默认的中大医学模板封面、校徽和水印位于带设计的版式中，即 cover="1_空白"、content="3_空白"。误用普通的“标题和内容”或“空白”版式时，页面只会显示白色背景。
• 默认模板页眉：3_空白 左侧自带两块绿色矩形；标题和 flextable 横线共同对齐到矩形底边，禁止复用公卫模板的纵向坐标。
• 公卫模板页眉：Title and Content 自带单个绿色竖条；标题和独立 flextable 横线共同对齐到竖条底边。不得依赖标题段落边框，PowerPoint 对该边框的渲染不稳定。
• 几何参数唯一来源：两套模板的页眉坐标只在 scripts/sysu_toolkit.R 的 .TPL_REG[[...]]$header 中维护；G、.add_title() 和调用脚本不得另写标题或横线坐标。修改模板后先重新测量版式中的对齐位置，再更新注册表并生成两套代表页验证，不能让两套模板共享同一纵向坐标。
• 正文偏下：部分版式文本框默认垂直居中；sysu_save() 按字节把空 <a:bodyPr/> 设 anchor="t"，故用 sysu_save 而非 print。
• 表格垂直居中：sysu_add_table / sysu_add_text_table 的 top 默认 NULL = 按表实际高度在内容区(1.58~7.0)自动垂直居中（行数少的表不再贴顶）。需固定位置时显式传 top= 数值。单元格内文字已由 sysu_flextable 设 valign="center"。

参考文件

• scripts/sysu_toolkit.R — 核心工具库。
• scripts/example_ppt.R — 覆盖全部 API 的运行与渲染测试，不作为生产内容或版式节奏蓝本。
• references/slide-design-practice.md — 基于 Harvard、MIT 与 UC San Diego 公开指南整理的逐页设计说明、版式映射、视觉节奏、文字密度与配图准确性规范。
• references/deck_skeleton.R — 组会汇报可选页面与版式示例；完全展开约 13 页，实际按内容选、删、合并或拆分，无章节页。
• references/defense_blueprint.R — 开题/答辩/正式研究汇报的参考模块、示例顺序、规范用词库与设计基调；目录、章节页、技术路线、进度表和致谢均按任务要求选用。
• ../research-visuals/references/research-figure-patterns.md — 通用科研流程图、框架图、机制图、研究设计、技术路线和图形摘要的内容与视觉规范。
• references/figure_snippets.R — 数据散点、时间变化等统计图示例；非统计流程、结构与场景配图使用 research-visuals。最多用 imagegen 定向修改两轮并按该技能披露遗留问题；只有 imagegen 实际不可用或存在明确矢量要求时才使用 svg-diagrams。
• assets/template.pptx（默认中大医学）、assets/template-公卫学院.pptx（模板2）— 两套模板。