Gorden PPT Skill:21 套中文模板与不破坏排版的 .pptx 生成契约

Gorden PPT Skill(仓库 GordenSun/GordenPPTSkill,v1.0.20,3,748 星)是一个面向 AI agent 的 PowerPoint 生成与编辑技能:21 套内置中文模板加一套「只换文字、不碰排版」的非破坏编辑契约,把「帮我做一份 PPT」从一次自由发挥变成一条可复核的流水线。代码部分 MIT 许可,模板部分另有非商业限制(见文末)。它的设计重心不在「写文案」,而在把版式、容量、字号层级这些过去靠审美把关的东西,写成 agent 必须遵守的结构化条款。

三种模式:模板优先、自带模板、原创兜底

SKILL.md 把任务分成三条路径。模式 A 是默认:从 21 套内置模板里选,先读 templates/INDEX.md 按「主色 + 风格 + 场景」缩候选,再读候选模板的 intro.md 与 detail.json 做匹配。模板选择有一条硬协议:用户没指定、或 agent 没有高度确信时,必须给用户正好 3 个候选,每个附一句话理由和对应的 preview.png 预览图,并永远多带一个「都不满意,换一批」选项;候选用尽仍不满意才追问偏好或转模式 C。禁止不看预览图就凭模糊匹配自作主张定模板。

模式 B 处理用户自带的 .pptx:先用 render_slides.py 把每页渲成 PNG 目测,再用 python-pptx 现场探查 shape / paragraph / run 结构,按启发式给每页打角色标签(封面 / 目录 / 章节扉页 / 内容 / 结束 / 模板宣传),跳过「稻壳儿 / WPS / 感谢下载」一类宣传页,然后用显式 address 写 edits.json;原文件永远不改,产出写到新路径。模式 C 是完全原创的兜底:每页元素不超过 4 个、1 个主色加灰阶白底、字号走 48-54 / 32-40 / 18-22 / 12-14pt 的梯度,并且明确要求「模式 C 是兜底,不是首选」——用户要丰富视觉时 agent 应主动回头推荐模板。

两份 JSON 契约:detail.json 与 edits.json

整个技能的中枢是两份结构化数据。detail.json(schema 为 ppt-template-detail/v1)由模板维护者写:每页一个 entry,带 role、layout 描述、use_for 与 cautions;每个文本位是一个 slot,含全局稳定的 slot_id、物理寻址 address(shape_id / paragraph / run 三级)、current_text 做 sanity check、max_chars / chars_per_line / max_lines 容量字段、editable 开关与给上层 AI 的 guidance。顶层还有 page_roles 索引(cover / agenda / section_divider / content / ending)、skip_pages、shape_caution_pages、data_charts 与 type_scale 字号层级表。

edits.json(schema 为 ppt-edit-spec/v1)由编辑端 AI 写:selected_slides 按演示顺序列原模板页号,未选的页直接删除;edits 数组每条是一处替换,推荐用 slot_id(配 --detail),也可用显式 address 加 expected_text 做校验。约束有三:顺序无关、同 slot 以最后一条为准;每个 editable=true 的 slot 必须出现,否则留下占位文字;editable=false 的装饰序号默认不碰。原生图表则在 edits 里挂 chart_data,由 build_pptx.py 调 python-pptx 的 replace_data 换数据。

编辑铁律:把品味写成可判定条款

SKILL.md 列了九条所有模式通用的铁律,其中几条直接对着 agent 的常见毛病去:

• 不改排版:形状的位置、大小、颜色、字体、字号、行距一律不动,只替换 run 文本。
• 所有占位文字必须替换:成品里不允许出现 Question 1、Vivamus、Key Words Here 这类模板占位词。
• max_chars 是软性参考而非硬上限,严禁用省略号截断:容量已留约 20% 余量,略微超框没关系;太长就重写措辞、减要点或换版式,「被省略号截断的半句话比轻微超框难看得多」。
• 同级标题字号必须一致:detail.json 的 type_scale 标了 level,同 level 保持模板原字号,不许逐处改小字号来控制长度。
• 封面与致谢页按模板能力来:page_roles 里 cover 为空就直接从第一张内容页开始,ending 为空就以最后内容页收尾,不许拿内容页冒充封面或硬造「感谢聆听」。
• 章节名前后呼应:改了目录章节名,分章扉页与内容页面包屑必须同步。

与之配套,build_pptx.py 的出框检测默认只打印提示、不阻断保存;--strict 会因超框拒绝保存,文档明确「日常不要加」,因为它会反过来诱导截断。检测与规则的方向是一致的:宁可轻微超框,不要半句话。

图表的三种形态:能改与不能改

形态	识别方式	能否改数据
原生 PPT 图表	shape.has_chart 为 True,读得到 series / categories	可以,edits 里挂 chart_data 调 replace_data
装饰形状组	圆环 / 旗帜 / 进度条 / 流程箭头等形状拼成,无 chart 对象	不能改弧长与占比,只能改伴随文字;偏差大就换版式
图片图表	shape_type 为 PICTURE 的截图或嵌入 png	不能改,保留或整张替换

原生图表也有边界:类别数建议不超过 detail.json 的 max_categories,series 数量与图表类型由模板决定、不能动态换类型,坐标轴范围、网格线、单点颜色都不支持改;需要这些就让用户在 PowerPoint 里手动调或换一页版式。装饰形状页会在 detail.json 的 shape_caution_pages 里点名并写 cautions,数据偏差小于等于 5% 可容忍,偏差大就换版式或向用户说明。

工程外壳:五个脚本与像软件一样的自更新

脚本	职责
build_pptx.py	按 edits.json 选页加换字输出 pptx,带出框检测,--strict 时出框拒存
render_slides.py	LibreOffice 转 PDF 再 pdftoppm 出每页 PNG,用于预览与自检
compute_capacity.py	从 template.pptx 计算每个 slot 的容量字段,加新模板时才跑
check_update.py / apply_update.py	对比远端 updates.json 列出变更 / 按 delta 增量下载应用
build_manifest.py	重建 manifest.json(每文件 sha256 与版本归属)

自更新是这个技能少见的一处工程坚持:SKILL.md 要求任何 AI 在会话内第一次使用本技能时,第一个 tool call 必须是 python3 scripts/apply_update.py,从 update_source(git+ 仓库地址)拉 updates.json、比对 VERSION、只下载真正变动的文件;manifest.json 存每个文件的 sha256 与版本归属,使增量更新可校验。文档同时写明技能不会自动 push 更新,跳过检查就可能用过期的规则与模板。字体侧也给了确定方案:模板大量使用微软雅黑,缺字体时用 fontconfig alias 落到 WenQuanYi Micro Hei、DengXian、Noto Sans SC、PingFang SC 的链;最终 .pptx 在 PowerPoint / WPS / Keynote 里由宿主机字体渲染,不担心丢字体。

21 套模板的矩阵

INDEX.md 把 21 套模板按主色、场景、规模三个维度做了筛选表:深蓝商务系(minimal-business-summary、operations-deck、report-savior、competition-speech 等)、党政红系(red-patriot-youth、red-patriot-general)、高密度教学红系(red-teaching-framework、red-teaching-models)、学术开题系(thesis-novice、thesis-formula、top-thesis)、咨询酱红系(mckinsey-style、premium-corp)、数据可视化系(data-viz-deck、report-massive-charts)等;页数从 16 页到 59 页不等。文档还坦白标出同作者系列的重叠:data-viz-deck、report-savior、operations-deck、competition-speech 与 report-massive-models / charts / reports 出自同一个深蓝商务合辑(原 118 页拆分),配色统一、可跨套混用;需求模糊时优先从 report-massive 三套里挑。场景覆盖工作汇报、述职竞聘、开题答辩、教学课件、党政教育、商务提案、架构图与数据可视化,README 称 DeepSeek、小米 MiMo、Claude、GPT 均实测可用。

许可边界:MIT 的代码与非商业的模板

仓库的许可是双层的:LICENSE 的 MIT 只覆盖源码(scripts/、references/ 与顶层技能元数据),templates/ 下的 template.pptx 与 preview.png 另受 NOTICE.md 约束——素材来自稻壳儿、WPS 在线模板、党政机关公开模板等公开渠道,视觉设计版权仍归原作者,只允许个人学习与研究、非商业教学讨论,禁止任何商业使用(含商业演示、销售与路演、付费培训分发、营利组织内部使用、作为付费 SaaS 或插件的一部分再分发);商用必须联系原模板作者取得书面授权,仓库维护者明确自己不持有模板的商业授权。打算把它接进商业产品或公司日常汇报链路的人,需要先解决模板这一层的授权;脚本与元数据结构则可以自由复用。这条边界写进了 SKILL.md 顶部、README 与 INDEX,三处一致。