| name | sysu-ppt |
| description | 基于 officer 与中山大学官方模板制作组会、开题、中期、答辩或正式学术汇报 PPT。用户要求中大学术演示文件或新汇报文件夹时使用；页数与结构服从时长、内容和证据，组会禁止目录页及章节分隔页。实际文件操作配合 pptx。 |
SYSU PPT Skill
用 R officer + 官方模板，代码化生成可直接上台、精美完整的学术汇报 PPT。给定主题/内容/要求，按本文件流程即可产出合规 PPT。
总原则（奥卡姆剃刀）
精确实现每一条要求，不堆字、不过度设计。 “内容丰富”指主信息、证据或结构、必要解释已经闭环，不是元素更多。空荡页面必须处理：先从已有材料补充有来源的证据、解释或边界；没有更多有效内容就合并薄页或换构图；仍偏空时再增大字号、行距、段间距和主视觉，并调整内容区纵向位置。不得编造内容或用装饰图填空。
体裁与结构蓝图（先认体裁再开写）
先判断体裁，再从对应蓝本中选取适用模块。蓝本是论证结构参考，不是逐页清单：
| 体裁 | 参考规模（非硬限） | 章节分隔页 | 常见论证顺序 | 蓝本 |
|---|
| 组会汇报 / 文献分享 / 方法讲解 | 由内容与时长决定；示例骨架完全展开约 13 页 | 不用 | 背景 → 概念 → 方法 → 对比 → 决策 → 收束 | references/deck_skeleton.R |
| 开题 / 中期 / 答辩 / 正式研究汇报 | 由用户要求、研究设计与答辩时长决定 | 按需要使用 | 封面 → 立题依据 → 目的与内容 → 方法 → 技术路线 → 创新与可行性 → 计划 → 收束 | references/defense_blueprint.R |
先满足用户明确页数或时长；未指定时按论证链自然决定。删除无内容模块，合并证据不足的相邻页，只有一页无法清楚表达时才拆页。不得为了靠近参考规模补页，也不得假设骨架中的每张示例页都必须生成。
组会体裁要求（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 并建立逐页故事板，至少记录“结论式名词短语标题、主信息、证据或结构、解释或边界、主视觉、版式、口头内容”。
- 一页一条主信息：标题不能只是“背景 / 方法 / 结果”，应概括本页结论、关系或分析边界。每张实质内容页只保留一条主信息、最强支撑和一条必要解释；没有证据时不得为了完整感编造数字、图或文献。
- 主信息—证据—解释闭环：证据可以是真实统计图、文献事实、比较表、流程、机制、公式、代码或实际截图。定义、目的和边界页可以没有图片，但必须有清楚的信息层级。
- 有节制的版式变化：任意连续 4 张实质内容页至少使用 2 种主构图；除非同一母图或分析结果正在逐步展开，不得连续 3 张完全同构。全篇通常覆盖至少 4 类主构图，但左右换边不算新结构，也不为达成数量强行轮换。
- 一个视觉焦点：每页只让大图、表格、公式、代码或核心结论中的一个成为主角。主体过小而页面显空时先放大主视觉、删次要区域或拆页，不补卡片、图标和装饰。
- 页数服从内容：页数、章节和每页构图都由用户要求、时长、内容关系与证据量决定。骨架、在线经验和示例文件只帮助估算与选型，不构成固定配额。
- 设计基调（两类通用）：主色中大深绿
#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")
ppt <- sysu_add_cover(ppt, "主标题", "English Subtitle", "汇报人：姓名", "2026 组会")
ppt <- sysu_add_text(ppt, "1 背景", block_list( prose(bd("定义 "), tx("……")) ))
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 参数。
硬性规范（每次必须满足）
- 字体：中文宋体、英文 Times New Roman，同段自动分流（
.fp() 内置，无需手动切）。已在 slide XML 层校验 <a:ea>=宋体、<a:latin>=Times New Roman。
- 字号：标题默认 24pt；正文 16pt 只作为信息密集页的下限，不是所有页面的目标字号。内容允许时主动使用 18–20pt，短结论或关键数字可提高到 21–24pt，并同步调整行距、段间距和内容区位置；最终以 1280 × 720 导出图验收，不机械统一放大。
- 内容驱动版式：执行逐页设计合同，按内容拓扑选择纯文字、图文、表格、公式、比较、时间、流程或整图。不要整份纯文字，也不要把“每页有图”当目标。图像只用于真实对象、结构、机制、证据、时间或操作关系，能用表格、公式、编号短句或时间结构更清楚时就不生成插图。
- 充实靠信息闭环与构图，不靠堆字：按页面功能选择文字形态。结论、比较和决策页可用 2–4 条精炼大字；定义、方法解释、证据评述和边界说明页允许 1–3 个完整段落，每段围绕一个论点自然展开，不把连续论证强拆成短标签或卡片。段落页优先用 18–20pt、较宽行距和清楚段间距，长到影响口头讲述时再删减或拆页。少量文字只占正文区上半部时，依次检查“补真实内容 → 与相邻页合并 → 改段落/双栏/表格/主视觉/卡片 → 增大字号与行距 → 用
top 调整纵向位置”，不得原样交付。officer 文本框不自动缩字：左右图文 / 左文右表的左栏最多 5 块、约 12 行 / 230 中文字，纯文字全宽页最多 7 块 / 340 字；这是防溢出上限，不是填充目标。超出后删次要句或拆页，绝不缩小字号。生成后逐页检查最后一行是否压到页眉、页脚或页码。
- 编号体现真实层次（最多两级，编号只在内容页标题）：同主题确有多页时才使用
1.1 / 1.2 等二级编号；单页主题不为凑层级增设子页，正文不写 1.1.1。编号随实际论证结构生成，不得反过来驱动补页，也不得据此为组会生成目录或章节过渡页。
- 章节分隔页严格按体裁隔离：组会汇报不得调用
sysu_add_section()，不得添加目录、汇报提纲或任何过渡页，封面后直接进内容；开题、答辩和正式研究汇报只有在用户要求、既有模板或篇幅层级确实需要时才使用章节页、目录与致谢页（见 defense_blueprint.R）。
- 强调：关键术语/结论用
bd()（加粗+主色）。
7bis. 数字单源取数：汇报里的统计数字（估计值/CI/P/百分比/样本量）若项目有 07_paper/results.yaml，一律
val("07_paper/results.yaml", "key") 取已渲染串（toolkit 已内置 val()），禁止手敲；改数字回 results.yaml 改再重生成。
- 编号与圆点二选一：用了 ①②③/123 就别再加 ●（用
num_item，不要 bullet）。
- 学术书面、不口语（每页都查）：
- 标题用规范名词短语，不用反问/口语标题。✗"一个高 AUC 的模型就是好模型吗"/"判别和校准是两回事"/"概率准不准" ✓"仅凭 AUC 能否判定模型优劣"/"判别和校准的区别"/"校准（Calibration）"。
- 段落小标签用规范词：解决问题 / 指标计算 / 检验 / 局限性 / 定义 / 说明 / 注意事项 / 方法 / 重要性 等。禁用敷衍或口语标签：✗"一句话""坑""怎么读""怎么办""通俗讲""回答"。
- 英文缩写首次出现给全称：首次写
AUC（Area Under the Curve）、IDI（Integrated Discrimination Improvement）、NRI（Net Reclassification Improvement）、DCA（Decision Curve Analysis） 等，后文再用缩写。
- 删空话/敷衍句：没有信息量的
intro/note（如"这几乎覆盖了最常见的误用""核心：…"）直接删，不靠它凑版面。
- 不用网络口语：✗ 净赚、听得懂、一验就掉、学过头、乱筛、当万能、迷信、纹丝不动、虚高… → 改书面表达（净获益、可理解、外部验证性能下降、过度拟合、随意筛选、过度依赖、偏高…）。
- 当前版单一、旧版整组归档：当前汇报目录只保留稳定命名的
.pptx、当前生成脚本和必要素材，不生成“完善版 / 最终版 / v2 / final”等并列文件。每次重生成前，把被替代 PPT、对应旧脚本、渲染页图与旧素材按原相对目录移入 09_backup/YYYY-MM-DD_HHMM_<汇报主题>_<阶段>/，写 MANIFEST.md 并登记 09_backup/INDEX.md；sysu_save() 始终写当前稳定文件名。
API 速查
| 函数 | 版式 | 关键参数 |
|---|
sysu_init(tpl) | 初始化、清空演示页 | "default"/"模板1"=中大医学；"模板2"=原公卫模板；或路径 |
sysu_add_cover(ppt,title,subtitle,author,date) | 封面 | subtitle 用一行短副标题 |
sysu_add_text(ppt,title,blocks,top,height) | 纯文字（全宽） | 稀疏但必须独立的页面可调 top/height 与文字助手字号/行距 |
sysu_add_two_text(ppt,title,left,right,top,height) | 双栏文字 | 两个 block_list；top/height 同时控制两栏 |
sysu_add_text_image(ppt,title,blocks,img,img_w,img_h,side,caption) | 左右图文 | side="right"/"left" |
sysu_add_image_caption(ppt,title,img,img_w,img_h,blocks,img_pos,caption) | 上下图文 | img_pos="top"/"bottom"；caption="图N …" |
sysu_add_image(ppt,title,img,img_w,img_h,caption) | 整图居中 | |
sysu_add_table(ppt,title,ft,left,top,note) | 表格 | ft 用 sysu_flextable() |
sysu_add_text_table(ppt,title,blocks,ft) | 左文右表 | |
sysu_add_code(ppt,title,code_lines,intro) | 代码/示例（显式浅底代码框） | 短代码框按最长行收紧并居中，长代码保留全宽 |
sysu_add_cards(ppt,title,cards,cols,intro) | 卡片网格（近白绿灰） | cards=list(list(tag,head,body)…) |
sysu_add_section(ppt,title,subtitle) | 正式汇报章节页 | 组会禁止调用 |
sysu_save(ppt,path,genre) | 保存 + 体裁检查 + 顶端对齐修正 | 组会 meeting；正式汇报 formal |
文本助手：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) — 绿表头 + 斑马行 + 三线表。
卡片约束
- 统一近白绿灰底
#F7FAF8 + 低对比绿灰边框 + 品牌绿细左条；编号、标题、正文分三个色阶，禁止每张卡随机换色或使用高饱和彩色方块。只有来源材料本身存在明确类别、顺序或风险等级时才允许使用不同色阶，并必须同时保留文字标签。
- 卡片高度按最长正文的估计行数自动计算，整组在正文区平衡分布。单行 3 卡通常占正文区约 35%–50% 的高度和 85%–90% 的宽度；两行卡通常占 55%–75% 的高度。比例只是检查范围，内容多寡优先。
- 标题通常一行，正文通常 2–3 行；正文只占卡片很小一角时缩短卡高，文字溢出时先删减或拆页。不得用高卡内部空洞换取“铺满”。
- 全篇克制：最多 2-3 页卡片；用于真正并列的 3-4 项。其余并列点用
prose/num_item。
配图（imagegen 优先）
- 配图先问“这张图提供什么证据或关系”。只接受真实对象、组织关系、解释机制或证据四类功能；纯装饰图、剪贴画、无语义图标、伪造界面和低清拼贴不得进入实质内容页。外部图必须核验来源、许可和分辨率，不得放大超过原始尺寸；真实界面与分析产物使用实际截图。
- 开题、答辩、中期和正式研究汇报生成前阅读
../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*。用户明确要求矢量、工具不可用，或 Image 1、适用 Image 2 与允许的整图重生成均不能保证文字与关系准确时，才最终回退 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 适当压小。自检发现某图上下/左右有空条 → 调画布比例或换 coord 重渲染。
- 中文统计图使用
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 检查（每一项不合格都要改了重生成，不许将就）：
⓪ 组会体裁检查：无目录/汇报提纲/Agenda 页，无章节分隔/过渡页；封面下一页即实质内容；生成脚本无 sysu_add_section()，并以 genre = "meeting" 保存。
① 字体对（宋体/Times）；② 不空半屏、不溢出（表格列不被截断）；③ 逐页配图决策合理——不需要图的页面未强加装饰图，需要图的页面能明确回答对象、证据、机制、时间或路径问题；④ 图内文字够大且逐字准确——流程图/框架图框内字、坐标轴、注释在缩略图上仍清晰可读，偏小或错误立即回到 imagegen 完整图修正或重生成；⑤ 图无多余空边——图四周没有明显空白条，有则调 imagegen 构图、SVG 画布或统计图输出比例重渲染；⑥ 非统计图关系正确——节点、箭头、方向和层级与来源逐项一致，无伪文字、重复节点或无语义装饰；技术路线从数据源闭合到验证与输出；⑦ 来源与证据属性正确——外部图可追溯，无水印、低清截图、缺图占位符和混杂画风；⑧ 模板按内容适配——母版品牌元素保留，但结构、密度、图文比例、留白和视觉权重已按本页信息关系优化，无机械套版、卡片墙或硬塞；⑨ 表格上下居中——表格块在内容区垂直居中而非贴顶；⑩ 图居中不变形；⑪ 重点已加粗；⑫ 页眉锚点正确——默认模板的标题横线与左侧两块绿色矩形底边共线，公卫模板的标题横线与绿色竖条底边共线；⑬ 图内无重复标题、无解释性长句，内容图保留必要节点标签，讲道理的文字写到正文或题注；⑭ 题注使用正确——证据图、统计图、方法示意和技术路线有题注且编号连续，封面与纯背景图不强加编号；⑮ 图例简短；⑯ 学术书面（见硬性规范 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 路径耗尽后才最终回退 svg-diagrams。assets/template.pptx（默认中大医学）、assets/template-公卫学院.pptx（模板2）— 两套模板。
