PPT Master 贡献指南环境搭建、PR 准入标准与 AI 辅助贡献的边界规则【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-masterPPT Master 是一个单人维护solo-maintained、AI 驱动的开源技能仓库其贡献规则本身就是一套为AI 生成代码时代设计的准入机制。本文基于 CONTRIBUTING.md 全文展开并结合仓库中的 PR 模板、依赖清单、图像后端实现与 SVG 校验脚本讲清楚三类信息作为贡献者如何搭建环境并提交合格的 PR哪些改动会被直接接受、哪些会被直接关闭以及当 AI 参与代码起草时维护者划定了怎样的审查红线。读完后你将掌握一套可复制的贡献流程issue 优先还是 PR 优先、如何本地验证、如何跑 SVG 质量检查以及该项目刻意保留的能力边界。一、项目背景与贡献形式PPT Master 以 MIT 协议开源由单人维护者管理评审带宽review bandwidth有限——这一前提直接决定了 CONTRIBUTING.md 中所有规则的取向规则不是设卡而是保护贡献者自己的时间。文档开宗明义A 500-line PR that doesnt match the project direction is worse for you than a 10-line issue comment that clarifies it upfront.文档列出的贡献形式共七类Templates— 新版式模板或视觉风格对应 skills/ppt-master/templates/ 下的模板资产Charts— 新增图表类型或 SVG 图表模板Icons— 图标库的矢量图标Scripts— 转换或后处理脚本的改进对应 skills/ppt-master/scripts/ 下 240 余个 Python 脚本Docs— 实质性提升项目使用体验的指南或勘误Bug reports— 可复现、描述清晰的 issueIdeas— 功能请求与设计建议值得注意的是Docs一类的限定词是substantive实质性不是所有文档润色都值得一个 PR措辞级修改应走 issue见后文准入标准。二、环境准备唯一的硬依赖是 Python 3.10CONTRIBUTING.md 的 Prerequisites 一节把依赖分成了必需与边缘兜底两层Python 3.10— 唯一必需依赖Node.js 18 与 Pandoc— 边缘场景兜底edge-case fallbacks99% of contributors never need只有在处理特定代码路径时才需要安装。其中 Pandoc 的适用边界在 README.md 的 Prerequisites 部分有精确说明Pandoc 仅用于旧式文档格式.doc、.odt、.rtf、.tex、.rst、.org、.typ而.docx、.html、.epub、.ipynb由纯 Python 原生路径处理无需 Pandoc。从 skills/ppt-master/requirements.txt 的注释可以看到对应实现.docx走mammoth、.html走markdownify、.epub走ebooklib、.ipynb走nbconvert这些才是Native (pure-Python) paths。安装步骤CONTRIBUTING.md 给出的 Setup 为git clone https://gitcode.com/GitHub_Trending/ppt/ppt-master cd ppt-master pip install -r requirements.txt根目录的 requirements.txt 本身只有一行有效内容-r skills/ppt-master/requirements.txt。这样设计的意图在文件头部注释里写明Full list lives inside the skill so installing the skill alone gives full capability——完整依赖清单内置于 skill 内部单独安装 skill 即可获得完整能力根目录文件只是转发。文件头还提到update_repo.py会对该文件及其递归-r/--requirement引用树计算指纹用于判断升级时是否需要同步依赖。真正的依赖清单在 skills/ppt-master/requirements.txt按用途分段组织几个关键分组与最低版本用途依赖说明模板注册PyYAML6.0供register_template.py使用SVG 转 PPTXpython-pptx0.6.21、XlsxWriter3.0.0、skia-pathops0.9.2、uharfbuzz0.50.0将受支持的 SVG 元素转换为可编辑的原生 DrawingML 形状后两者分别负责合并形状物化与文字轮廓排版逐页旁白音频edge-tts7.2.8notes_to_audio.py在 macOS/Linux/Windows 上生成旁白PDF/文档转 MarkdownPyMuPDF1.23.0、mammoth、markdownify、ebooklib、nbconvert、openpyxl覆盖source_to_md/下的各转换脚本贡献者在本地跑通受影响的脚本见第五节工作流第 4 步时这份清单就是验证环境的基准。三、提交 PR 前的判据issue 优先还是 PR 优先这是 CONTRIBUTING.md Before You Open a PR 一节的核心按改动类型给出六条判据直接决定了贡献的入口选择Tiny fixes错别字、一行用法/文档修正、明显的小不一致——开 issue不要开 PR。清晰的 issue 报告通常比 PR 更快被维护者直接修复。翻译与措辞级修改——同样开 issue。未被请求的翻译文件会引入没有明确 owner 的持续同步负担治理类文档CONTRIBUTING、Code of Conduct有意不维护独立的_CN副本。Focused bug fixes——PR 欢迎前提是修复自包含self-contained、有清晰复现步骤、并包含本地验证。纯代码改动code-only——对脚本或脚本行为的自包含修复只要不触碰 prompt/指令文本且满足上一条标准可直接提 PR。Prompt/指令类改动必须先有 issue 讨论——凡是编辑 skills/ppt-master/SKILL.md、references/*.md、workflows/*.md或其他面向 agent 的指令文本必须在开 PR 之前于 issue 中讨论并达成一致。文档给出的理由很具体这些文件全局性地引导 AI 行为紧贴固定的 prompt token 预算而且重复陈述文档已有的规则很少能修正不合规的 agent——修复通常应该发生在 agent 侧而不是堆更多 prompt 文本。没有先前 issue 的 prompt 类 PR 可能不经过详细评审直接关闭。大特性、新后端、新抽象——先开 issue 讨论契合度与方向未经事先讨论的 PR 可能直接关闭。重构、结构性改动、大范围清理或工作流变更同理——项目刻意保持接近当前形态。仓库中 .github/MAINTAINER_PLAYBOOK.md 是维护者内部的分诊参考文档自述 not an outward promise从源码结构看它对 CONTRIBUTING 的上述规则给出了成体系的五道闸门foundational → capability boundary → already-solved → root cause layer → evidence process且第一个未通过的闸门即为关闭原因。贡献者阅读该文件有助于理解每条规则背后的先例编号如 pip 唯一安装路径、无 CI、无固定数值配额等但外部承诺仍以 CONTRIBUTING.md 与 PR 模板为准。四、AI 辅助 PR 的三条红线PPT Master 本身就是 AI 驱动的项目因此 CONTRIBUTING.md 对 AI 辅助持开放但严格的态度AI assistance is welcome... But an AI-drafted PR you havent personally reviewed is not a contribution; its an unreviewed code dump. 具体红线有三未经人工审查的纯 AI 生成 PR 会被直接关闭closed unmerged。开 PR 前必须自己读完整 diff、跑过受影响的脚本、确认所述问题在本仓库中真实存在——而不是听起来合理。PR 描述中的每一条事实声明都是你提交者的责任不是 AI 的。如果描述中声称了本仓库并不存在的代码路径中的失败AI 虚构的问题叙事无论 diff 质量如何都会被关闭。PR 模板的三个确认框必须全部勾选漏勾任意一个即closed without review。第 3 条在 .github/PULL_REQUEST_TEMPLATE.md 中有逐字落地L16–L21All three of the following must be checked. If any one is left unchecked, the PR is closed without review.三个确认项分别是已完整阅读 CONTRIBUTING.md已亲自审查完整 diff 并逐条核对描述中的声明包括问题在本仓库真实存在、该能力不是已有路径已提供或main上已修复该 PR 是纯代码改动或者触碰了 prompt/指令文本且已在 issue 中先行讨论需链接 issue。模板正文还固定了 What why 与 Verification 两节分别要求说明改动原因bug 修复需附复现步骤与本地运行观察——与第五节工作流的第 3、4 步一一对应。五、接受与拒绝清单与仓库能力边界逐条对应CONTRIBUTING.md 的 What We Accept / What We Dont 一节把边界写得很实。接受侧Welcome有清晰复现的 bug 修复新版式模板、图表模板、图标实质性改善现有工作流、安装路径或排障路径的文档更新遵循现有image_backends/模式的图像后端保持在已声明约束之内的 SVG 质量改进拒绝侧Not a fit每一条都能在仓库里找到对应证据值得逐条展开不接受uv/poetry等作为必需依赖。pip requirements.txt是唯一官方安装路径。仓库证据根 requirements.txt 只有-r转发一行skills/ppt-master/requirements.txt 的安装注释也只给出pip install -r requirements.txt一种方式。不接受引入 CI、测试框架、pre-commit、lint 基础设施。单人维护项目刻意不承接这部分负担docs/rules/code-style.md 第 11 节明确禁止tests/目录与test_*.py文件与 MAINTAINER_PLAYBOOK.md 中引用的先例一致。不接受把 skill 重新打包成 CLI、SaaS、桌面应用或安装器。PPT Master 在设计上就是跑在 AI IDE 里的 chat-driven skill——这也解释了为什么 examples/ 下每个示例项目的入口都是SKILL.md驱动的工作流而不是可执行程序。不接受架构重构或大规模重命名只接受渐进式清理。不接受顺手为改的drive-by格式化、未事先讨论的纯翻译与措辞修改。不接受改动出厂设置MIT 协议以及用 DrawingML 组件复用/模板填充替代 AI 生成形状的路线。文档将其定性为 deliberate founding choices and wont change midway。不接受用固定数值配额约束生成max_cards/max_bullets/max_table_rows之类。页面密度由叙事节奏与每页一个主焦点治理而不是硬上限。不接受质量润色型后处理。项目只修复不做就会坏/不可用的东西如 AI 图片的尺寸/格式/alpha 问题做了更好的打磨响度归一化、字距调整不入项目。文档给出的立场是如果某个模型或服务不达标正确的做法是换掉它而不是让项目去适配它。不接受与仓库已有能力重复的新后端/路径/选项。典型例子OpenAI 兼容服务商已经可以通过IMAGE_BACKENDopenai运行。仓库证据在 skills/ppt-master/scripts/image_backends/ 目录backend_openai.py、backend_fal.py、backend_gemini.py、backend_qwen.py等 16 个后端文件并存而网关类需求走两条通用路径即可——IMAGE_BACKENDopenai配合OPENAI_BASE_URL见 backend_openai.py 中base_url os.environ.get(OPENAI_BASE_URL)或IMAGE_BACKENDopenrouter配合OPENROUTER_BASE_URL/OPENROUTER_MODEL见 backend_openrouter.py 中的同名环境变量读取。因此为某个 API 网关/路由/聚合服务单独新建后端文件会被拒绝网关专属文件只增加一条需要维护的代码路径而不增加任何能力image_backends/的新条目保留给运行自有图像模型的服务商。文档最后留了一个安全阀If youre unsure, open an issue to ask — thats always welcome.六、贡献工作流与评审流程CONTRIBUTING.md 给出的五步工作流Fork仓库并从main建分支一个 PR 只做一件事——发现无关的改进请另开 PR写有用的 PR 描述——解释what改了什么和why为什么而不仅是 diff 摘要bug 修复必须附复现步骤提交前本地测试——跑受影响的脚本并验证输出不夸大——如果 PR 描述声称了测试或行为变化diff 里必须真的包含它们这一条与 AI 辅助 PR 红线第 2 条呼应。评审流程Review Process三条评审为尽力而为best-effort通常几天内完成PR 挂一周无响应可以 ping反馈会具体说明要改什么以及是否阻塞项blocker。如果一个 PR 需要超过约 2 轮才能收敛可能被附注关闭——方向更清晰后重新打开即可聚焦型修复可能直接合并较大的贡献通常会 squash-merge 以保持历史可读。七、SVG 贡献规范单一权威 一条校验命令SVG 相关的贡献不需要另记规则——CONTRIBUTING.md 明确把书写规范与 PPTX 兼容性契约的权威指向shared-standards.mdThis guide does not duplicate its required, forbidden, or conditional entries。而这份权威文件本身是一个兼容路由器compatibility router它不是运行时权威文档而是把规则拆分路由到四个模块——作用域权威文件触发条件XML/SVG 基础、共享视觉质量默认值、页面收尾、分组shared-standards-core.mdSVG 书写时始终生效高级效果与几何svg-effects.mdDefault / Quick Generate 始终加载其余情况用到对应效果/几何时加载预置模式与原生图表/表格元数据native-data-interface.md使用对应 native-data 接口时Master/Layout/占位符结构pptx-structure-interface.mdpptx_structure.mode: structured时其Hard rule提醒按所选路由加载必需模块不要默认加载全部条件模块——这与 CONTRIBUTING 中prompt 预算有限、不重复已有规则的精神一致。提交前必须运行质量校验python3 skills/ppt-master/scripts/svg_quality_checker.py file_or_directorysvg_quality_checker.py 的模块 docstring 说明了它的定位Stable CLI entry point实现位于svg_quality/包并给出扩展用法支持--all examples全量检查、--stage final --json等参数可作用于单个 SVG 文件或整个目录。贡献模板/图表类 PR 时这条命令的输出就是本地验证的直接证据。八、Bug 报告issue 是最快的修复通道CONTRIBUTING.md 要求 bug 报告包含四要素清晰的问题描述、复现步骤、期望行为与实际行为的对照、环境细节操作系统、Python 版本、所用 AI 编辑器。仓库为此配置了结构化模板.github/ISSUE_TEMPLATE/ 下有bug_report.yml、feature_request.yml与config.yml开 issue 时会按类型引导填写——这与 Tiny fixes issue 比 PR 更快的判据闭环维护者拿到结构化报告后可直接应用修复。九、行为准则与许可贡献前需阅读并遵守 CODE_OF_CONDUCT.md按 CONTRIBUTING.md 与 LICENSE 的约定提交即表示你的贡献将以 MIT 协议发布——这一条款同时是不接受改动基础设置清单中的第一条MIT 协议是刻意的初始选择中途不会改变。附贡献者速查表场景正确入口错别字 / 一行文档修正 / 措辞issue翻译 / 纯措辞编辑issue自包含、可复现、已本地验证的 bug 修复PR纯脚本行为修复不碰 prompt/指令文本PR修改SKILL.md/references/*.md/workflows/*.md先 issue 达成一致再 PR大特性 / 新后端 / 重构 / 工作流变更先 issueSVG 模板或图表PR且先过svg_quality_checker.py网关/聚合服务商后端不新建文件走IMAGE_BACKENDopenaiOPENAI_BASE_URL或openrouter路径拿不准开 issue 问总是受欢迎【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考