企业官网建设流程全解析

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-master

PPT 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 doesn't 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— 可复现、描述清晰的 issue
• Ideas— 功能请求与设计建议

值得注意的是"Docs"一类的限定词是substantive（实质性）：不是所有文档润色都值得一个 PR，措辞级修改应走 issue（见后文准入标准）。

二、环境准备：唯一的硬依赖是 Python 3.10+

CONTRIBUTING.md 的 Prerequisites 一节把依赖分成了"必需"与"边缘兜底"两层：

• Python 3.10+— 唯一必需依赖；
• Node.js 18+ 与 Pandoc— 边缘场景兜底（edge-case fallbacks），"99% 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，按用途分段组织，几个关键分组与最低版本：

贡献者在本地跑通受影响的脚本（见第五节工作流第 4 步）时，这份清单就是验证环境的基准。

三、提交 PR 前的判据：issue 优先，还是 PR 优先

这是 CONTRIBUTING.md "Before You Open a PR" 一节的核心，按改动类型给出六条判据，直接决定了贡献的入口选择：

1. Tiny fixes（错别字、一行用法/文档修正、明显的小不一致）——开 issue，不要开 PR。清晰的 issue 报告通常比 PR 更快被维护者直接修复。
2. 翻译与措辞级修改——同样开 issue。未被请求的翻译文件会引入没有明确 owner 的持续同步负担；治理类文档（CONTRIBUTING、Code of Conduct）有意不维护独立的_CN副本。
3. Focused bug fixes——PR 欢迎，前提是修复自包含（self-contained）、有清晰复现步骤、并包含本地验证。
4. 纯代码改动（code-only）——对脚本或脚本行为的自包含修复，只要不触碰 prompt/指令文本，且满足上一条标准，可直接提 PR。
5. Prompt/指令类改动必须先有 issue 讨论——凡是编辑 skills/ppt-master/SKILL.md、references/*.md、workflows/*.md或其他面向 agent 的指令文本，必须在开 PR 之前于 issue 中讨论并达成一致。文档给出的理由很具体：这些文件全局性地引导 AI 行为，紧贴固定的 prompt token 预算，而且"重复陈述文档已有的规则很少能修正不合规的 agent——修复通常应该发生在 agent 侧，而不是堆更多 prompt 文本"。没有先前 issue 的 prompt 类 PR 可能不经过详细评审直接关闭。
6. 大特性、新后端、新抽象——先开 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 haven't personally reviewed is not a contribution; it's an unreviewed code dump." 具体红线有三：

1. 未经人工审查的纯 AI 生成 PR 会被直接关闭（closed unmerged）。开 PR 前必须自己读完整 diff、跑过受影响的脚本、确认所述问题在本仓库中真实存在——而不是"听起来合理"。
2. PR 描述中的每一条事实声明都是你（提交者）的责任，不是 AI 的。如果描述中声称了本仓库并不存在的代码路径中的失败（AI 虚构的问题叙事），无论 diff 质量如何都会被关闭。
3. PR 模板的三个确认框必须全部勾选，漏勾任意一个即"closed without review"。

第 3 条在 .github/PULL_REQUEST_TEMPLATE.md 中有逐字落地（L16–L21）：

All 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 Don't" 一节把边界写得很实。接受侧（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 won't change midway"。
• 不接受用固定数值配额约束生成（max_cards/max_bullets/max_table_rows之类）。页面密度由叙事节奏与"每页一个主焦点"治理，而不是硬上限。
• 不接受"质量润色"型后处理。项目只修复"不做就会坏/不可用"的东西（如 AI 图片的尺寸/格式/alpha 问题）；"做了更好"的打磨（响度归一化、字距调整）不入项目。文档给出的立场是：如果某个模型或服务不达标，正确的做法是换掉它，而不是让项目去适配它。
• 不接受与仓库已有能力重复的新后端/路径/选项。典型例子：OpenAI 兼容服务商已经可以通过IMAGE_BACKEND=openai运行。仓库证据在 skills/ppt-master/scripts/image_backends/ 目录：backend_openai.py、backend_fal.py、backend_gemini.py、backend_qwen.py等 16 个后端文件并存，而网关类需求走两条通用路径即可——IMAGE_BACKEND=openai配合OPENAI_BASE_URL（见 backend_openai.py 中base_url = os.environ.get("OPENAI_BASE_URL")），或IMAGE_BACKEND=openrouter配合OPENROUTER_BASE_URL/OPENROUTER_MODEL（见 backend_openrouter.py 中的同名环境变量读取）。因此为某个 API 网关/路由/聚合服务单独新建后端文件会被拒绝：网关专属文件只增加一条需要维护的代码路径而不增加任何能力，image_backends/的新条目保留给"运行自有图像模型"的服务商。

文档最后留了一个安全阀："If you're unsure, open an issue to ask — that's always welcome."

六、贡献工作流与评审流程

CONTRIBUTING.md 给出的五步工作流：

1. Fork仓库并从main建分支；
2. 一个 PR 只做一件事——发现无关的改进请另开 PR；
3. 写有用的 PR 描述——解释what（改了什么）和why（为什么），而不仅是 diff 摘要；bug 修复必须附复现步骤；
4. 提交前本地测试——跑受影响的脚本并验证输出；
5. 不夸大——如果 PR 描述声称了测试或行为变化，diff 里必须真的包含它们（这一条与 AI 辅助 PR 红线第 2 条呼应）。

评审流程（Review Process）三条：

• 评审为尽力而为（best-effort），通常几天内完成；PR 挂一周无响应可以 ping；
• 反馈会具体说明"要改什么"以及"是否阻塞项（blocker）"。如果一个 PR 需要超过约 2 轮才能收敛，可能被附注关闭——方向更清晰后重新打开即可；
• 聚焦型修复可能直接合并；较大的贡献通常会 squash-merge 以保持历史可读。

七、SVG 贡献规范：单一权威 + 一条校验命令

SVG 相关的贡献不需要另记规则——CONTRIBUTING.md 明确把书写规范与 PPTX 兼容性契约的权威指向shared-standards.md，"This guide does not duplicate its required, forbidden, or conditional entries"。而这份权威文件本身是一个兼容路由器（compatibility router）：它不是运行时权威文档，而是把规则拆分路由到四个模块——

其"Hard rule"提醒：按所选路由加载必需模块，不要默认加载全部条件模块——这与 CONTRIBUTING 中"prompt 预算有限、不重复已有规则"的精神一致。

提交前必须运行质量校验：

python3 skills/ppt-master/scripts/svg_quality_checker.py <file_or_directory>

svg_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 协议是刻意的初始选择，中途不会改变。

附：贡献者速查表

【免费下载链接】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