PPT Master 项目工作区实战指南从project_manager.py到标准化的 PPT 交付物流水线【免费下载链接】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 仓库中的projects/目录User Project Workspace为核心讲解如何用官方命令行工具创建、填充、校验和交付一个规范的 PPT 制作项目。读完本文你将掌握project_manager.py的完整命令面init / import-sources / scaffold-spec / scaffold-lock / validate / info / page-context、画布格式canvas format的选用与记录机制以及sources → svg_output → svg_final → exports这条贯穿「素材归档 → 页面编排 → 视觉终稿 → 原生 PPTX」的项目生命周期并能在你自己的机器上复现完整流程。一、projects/是什么一个进行中项目的托管目录在 PPT Master 的仓库布局中projects/目录projects/README.md专门用于存放尚未完成的制作中项目in-progress projects。它与仓库内的skills/ppt-master/技能实现、docs/文档、templates/模板是平级的承担的是用户工作空间的角色。理解这个目录的关键在于三点约定生命周期阶段性一个项目可以停留在任意阶段不需要一次性具备全部产物。文档明确列出了三种典型中间状态——只有sources/归档与设计规范design_spec就绪svg_output/已生成但尚未执行后处理svg_final/已是自包含的视觉预览且exports/*.pptx完成。不进入版本库该目录下的内容被.gitignore排除属于本地工作数据而不是仓库的可分发资产。交付出口完成的项目可通过 PPT Master 的 examples 仓库对外发布文档中给出的是hugohe3/ppt-master-examples这一发布通道具体以仓库 README 为准。从实现上看路径常量在 skills/ppt-master/scripts/project_management/paths.py 中被统一定义PROJECTS_ROOT REPO_ROOT / projects即项目工作区永远锚定在仓库根目录下的projects/。所有项目管理逻辑都围绕这个根目录展开。二、创建新项目init命令与画布格式决策2.1 两种初始化方式创建新项目使用project_manager.py的init子命令入口脚本位于 skills/ppt-master/scripts/project_manager.py核心实现在 skills/ppt-master/scripts/project_management/cli.py。官方文档给出了两种调用形态# 方式一推迟画布决策交给创作阶段Default 流程 python3 skills/ppt-master/scripts/project_manager.py init my_project # 方式二记录一个精确的已注册画布格式 python3 skills/ppt-master/scripts/project_manager.py init my_widescreen --format ppt169命令实际生成的目录名遵循project_name[_registered_format]_YYYYMMDD模式不带--format生成my_project_20260909日期取自datetime.now().strftime(%Y%m%d)带--format生成my_widescreen_ppt169_20260909格式 token 只在收到--format时出现。注意init对项目名的合法性有严格校验见 cli.py 中init_project项目名必须是单个、非绝对路径的路径分量禁止为.、..禁止包含/或\同时项目目录必须落在基础目录内is_within_path校验且目录已存在时会直接抛FileExistsError避免误覆盖。如果你把带_YYYYMMDD或_format_YYYYMMDD后缀的完整目录名贴回init实现会识别并原样使用不会重复追加日期导致name_20260101_20260102这样的脏目录名。2.2--format的语义只认已注册格式文档特别强调只有当画布精确匹配一个已注册格式时才传--format。省略时画布在创作阶段确定并通过两条路径被记录Default Generate流程记录在spec_lock.md中Quick Generate流程由第一张 SVG 决定。init对格式参数的处理在 cli.py 中可见传入的格式键先经normalize_canvas_format归一化支持别名例如xhs → xiaohongshu、朋友圈 → moments然后必须命中CANVAS_FORMATS注册表否则报错Unsupported canvas format并列出全部可用键。已注册的画布格式定义在 skills/ppt-master/scripts/config.py 的CANVAS_FORMATS字典中project_utils.py 中另有一份兜底副本每个格式包含name、dimensions、viewbox、width、height、aspect_ratio和use_case。下表整理了仓库中可查证的完整注册表格式键名称尺寸pxviewBox宽高比适用场景ppt169PPT 16:91280×7200 0 1280 72016:9现代投影、线上演示ppt43PPT 4:31024×7680 0 1024 7684:3传统投影wechat微信公众号文章头图900×3830 0 900 3832.35:1公众号封面图xiaohongshu小红书1242×16600 0 1242 16603:4知识分享、种草评测moments朋友圈/Instagram1080×10800 0 1080 10801:1社交平台方形图story竖屏 Story1080×19200 0 1080 19209:16短视频封面、Storybanner横版 Banner1920×10800 0 1920 108016:9横幅广告a4A4 打印1240×17540 0 1240 1754√2:1打印输出这也解释了 PPT Master 的定位它不只产出传统幻灯片还能为公众号头图、小红书笔记、朋友圈、短视频封面等场景直接产出对应画布的演示。2.3 两种初始化档位默认档与--quick-generateinit还接受两个进阶参数--dir path指定项目的基础目录默认是projects/--quick-generate创建精简骨架只生成svg_output/外加校验工作流审计日志并且不生成 README.md。从源码看默认档会一次性创建 11 个目录svg_output、svg_final、images、icons、notes、templates、live_preview、sources、analysis、validation、exports并写入一份带目录说明的README.md而 Quick 档只创建svg_output一个目录。两种档位在init完成时都会通过append_noteworkflow_log.py写入工作流审计日志记录profiledefault|quick与 canvas 信息。三、标准项目目录结构详解文档给出了一个典型项目的完整目录树svg_final/下省略具体 SVGproject_name[_registered_format]_YYYYMMDD/ ├── README.md ├── design_spec.md ├── sources/ │ ├── Raw files / URL archives / Converted Markdown │ └── *_files/ # Markdown 伴生资源目录如图片 ├── images/ # 项目使用的图片资产 ├── analysis/ # 抽取的源事实PPTX intake bundle、image_analysis.csv ├── notes/ │ ├── 01_xxx.md │ ├── 02_xxx.md │ └── total.md ├── svg_output/ │ ├── 01_xxx.svg │ └── ... ├── svg_final/ │ ├── 01_xxx.svg │ └── ... ├── templates/ # 项目级模板如有 └── exports/ └── *.pptx # 原生 DrawingML 交付物结合init写入的 README 模板cli.pyinit_project各目录的职责可以进一步明确README.md项目级说明init自动生成记录项目名、画布格式/推迟声明、创建日期和目录导览design_spec.md设计规范与内容大纲是创作的蓝图validate会检查其 §IX Content Outline 的完整性sources/源材料与归一化后的 Markdown包括原始文件、URL 归档、转换产物及*_files/伴生资源目录images/运行时图片池。导入的图片资产尽量保留原有短文件名源 Markdown 常用短名引用仅在真正冲突时追加数字后缀同名图片的归属与去重信息记录在image_manifest.json含source_namespace字段analysis/机器抽取的中间分析如 PPTX intake 的 identity/slide_library JSON、image_analysis.csv是管线的权威事实源notes/演讲者备注逐页01_xxx.md、02_xxx.md以及合成后的total.mdsvg_output/SVG 原始输出创作阶段生成svg_final/自包含的视觉终稿预览后处理产物templates/项目级模板如有validation/冷启动工作流审计日志、SVG 质量报告、PPTX 交付后审计报告exports/仅存放最终的原生 DrawingML PPTX 交付物带时间戳启用--native-charts-and-tables时使用_native_charts_tables.pptx命名嵌入旁白音频时使用_narrated.pptx命名。目录名中的_YYYYMMDD日期后缀不仅用于标识还承担了解析语义project_utils.parse_project_nameskills/ppt-master/scripts/project_utils.py会从目录名中还原项目名、画布格式与创建日期输出2026-09-09这样的格式化日期validate_project_structure也会检查目录名是否缺少日期后缀并给出警告。四、填充项目import-sources与源材料治理4.1 命令形态python3 skills/ppt-master/scripts/project_manager.py import-sources project_path source1 [source2 ...] [--move | --copy]import-sources接受文件、目录或 URL三类输入目录会被展开为其下的全部文件。--move与--copy互斥argparse互斥组源码中同时传两者直接抛ValueError。4.2 按类型分流的导入策略导入核心逻辑在 cli.py 的import_sources中按扩展名路由到不同处理输入类型处理方式HTTP(S) URL调用web_to_md转换经source_to_md/_dispatcher.py的build_conversion_command路由若产出不可用 Markdown如内容含[Failed URLs]:或为空则改为写入.url.txt归档记录.md/.markdown归入sources/内容做规范化CRLF→LF、剥离Crawled:/Imported:时间戳行、将*_files/路径归一化后做等价查重重复内容跳过.png.jpg.gif等位图归档到sources/并复制一份到images/运行时图片池文件名冲突自动加_2、_3后缀.pdf归档 自动转 Markdown同 stem 已存在 Markdown 则跳过.pptx等演示文件归档 调用pptx_intake.py做 intake 分析identity / slide_library JSON多 deck 汇总进analysis/source_profile.json 自动转 Markdown.xlsx/.csv/.tsvExcel 转 MarkdownCSV/TSV 作为纯文本表格源归档不转换旧式.xls仅归档并提示另存为.xlsx.doc等文档归档 自动转 Markdown.txt归一化为 Markdown_normalize_text_source其他仅归档不做自动转换Markdown 的伴生资源目录stem_files/会被整体导入到sources/Markdown 内的资源引用路径会被重写为新的目录名随后_propagate_image_assets会把其中的图片复制进项目images/并将image_manifest.json与项目级 manifest 做按文件名合并同名文件以新来源覆盖并记录source_namespace。4.3 移动还是复制projects/内外的边界规则文档的 Notes 明确指出工作区外的文件默认复制工作区内的文件直接移入项目的sources/。源码把这一规则落实得非常细致源文件位于projects/内且属于另一个项目时即使不带--move也默认复制避免历史上出现过拿走已完成项目images/的问题并打印提示要取出需显式--move源文件位于projects/内但属于目标项目自己默认移动可用--copy保留源文件位于projects/外--move会被降级为复制只有projects/下的源允许移动并打印说明。导入结束后会输出分门别类的汇总Archived originals / Normalized markdown / Runtime image copies / Analysis artifacts / Notes / Skipped且只有至少产出一个可用源时命令才返回成功_has_usable_import检查archived、markdown、assets、images、analysis任一非空。另外image_manifest.json的读写采用同目录临时文件 原子重命名_write_json_atomic损坏的既有 manifest 会 fail-closed 报错而非静默覆盖。五、规划产物scaffold-spec与scaffold-lock在动手创作之前可以用两个脚手架命令生成标准的规划文档python3 skills/ppt-master/scripts/project_manager.py scaffold-spec project_path python3 skills/ppt-master/scripts/project_manager.py scaffold-lock project_pathscaffold-spec生成design_spec.md设计规范与内容大纲scaffold-lock生成spec_lock.md执行锁。两者的模板位于 skills/ppt-master/templates/scaffolds/渲染逻辑在 skills/ppt-master/scripts/project_management/project_specs.pyscaffold_project_artifact对应的 JSON Schema 在 skills/ppt-master/templates/schemas/design_spec.schema.json、spec_lock.schema.json。spec_lock.md模板带ppt-master-schema: spec-lock/v1标记的结构揭示了执行锁的职责## canvasviewBox 与格式名、## communicationprimary_language / audience / objective / core_message / consumption_mode、## mode、## visual_style、## colors、## typography、## icons、## page_rhythm、## pptx_structuremode: flat以及## forbidden禁用style、class、外部 CSS、foreignObject、textPath、font-face、动画标签、script、iframe等文本需用原始 Unicode 书写并转义 XML 保留字符。正是这份spec_lock.md承担了推迟画布决策时的记录职责——Default Generate 流程会把创作阶段确定的画布写进它的## canvas段。project_utils.validate_communication_trace还会校验spec_lock.md必须包含## communication段且含 audience / objective / core_message 三行键值以及design_spec.md的 §IX 每个 Slide 块必须含Audience move与Relationships行——这是沟通痕迹communication trace校验的一部分确保每一页都带着明确的受众转化目标。六、校验与诊断validate、info与page-context6.1 项目结构校验python3 skills/ppt-master/scripts/project_manager.py validate project_pathvalidate聚合了多层检查validate_project→ project_utils.py 的validate_project_structurevalidate_svg_viewbox以及 project_specs.py 的validate_project_artifacts目录必须存在且为目录错误级缺少svg_output/目录SVG 文件命名需匹配^(slide_\d_\w|P?\d_.)\.svg$、沟通痕迹校验失败spec_lock 缺## communication或关键键、design_spec §IX 缺 Slide 块或缺 Audience move/Relationships 行警告级缺少README.md提示nothing reads it、缺少design_spec.md、svg_output/为空、SVG 命名不规范、目录名缺少_YYYYMMDD日期后缀viewBox 一致性所有 SVG 根 viewBox 必须一致若项目目录名编码了格式如ppt169还会逐一比对每个 SVG 的 viewBox 是否与0 0 1280 720匹配不匹配即告警。退出码 0 表示通过1 表示存在错误级问题——因此它可以直接用于 CI 或脚本化的批量检查仓库还提供 batch_validate.py 用于批量校验。6.2 元信息速览python3 skills/ppt-master/scripts/project_manager.py info project_path打印项目名、路径、是否存在、SVG 文件数、是否有 design_spec、源材料数量、画布格式目录名未编码格式时显示 Not encoded in the project directory name和创建日期。6.3 逐页执行上下文python3 skills/ppt-master/scripts/project_manager.py page-context project_path P07 [--record-usage] python3 skills/ppt-master/scripts/project_manager.py page-context-report project_pathpage-context为某一页如P07输出确定性的单页执行视图JSON--pretty可美化输出--record-usage会把紧凑输出的 token 遥测写入analysis/page-context/page-context-report汇总这些遥测。实现位于 skills/ppt-master/scripts/project_management/page_context.py。这是为分页创作/续跑设计的能力每次只给模型一页所需的全部上下文控制单次调用成本。七、项目全生命周期与交付要点7.1 一条完整流水线把上面的命令串起来一个标准项目会经历如下阶段# 1. 初始化推迟画布或直接锁定 ppt169 python3 skills/ppt-master/scripts/project_manager.py init my_project python3 skills/ppt-master/scripts/project_manager.py init my_widescreen --format ppt169 # 2. 导入源材料文件/目录/URL python3 skills/ppt-master/scripts/project_manager.py import-sources projects/my_project_20260909 source.md assets/ https://example.com/article # 3. 生成规划产物 python3 skills/ppt-master/scripts/project_manager.py scaffold-spec projects/my_project_20260909 python3 skills/ppt-master/scripts/project_manager.py scaffold-lock projects/my_project_20260909 # 4. 创作产出 SVG 到 svg_output/ # 5. 校验并查看项目状态 python3 skills/ppt-master/scripts/project_manager.py validate projects/my_project_20260909 python3 skills/ppt-master/scripts/project_manager.py info projects/my_project_20260909 # 6. 后处理 svg_output → svg_final → exports/*.pptx各阶段对应文档所述的三种中间状态可以只完成源归档 design_spec可以svg_output 已生成但未后处理也可以推进到svg_final 自包含预览 exports 完成。7.2 交付物的三条硬约束svg_final/的可视化预览可以直接用浏览器打开或作为 SVG 图片手动插入到 PowerPoint 中但PowerPoint 的手动 Convert to Shape转换为形状行为不受支持文档 Notes 明确声明init生成的 README 中也重复了这一约束。若要获得可编辑的原生形状应走exports/*.pptx的 SVG→DrawingML 转换管线skills/ppt-master/scripts/svg_to_pptx/。exports/只放最终交付物文件名带时间戳且根据特性带_native_charts_tables.pptx原生图表/表格或_narrated.pptx嵌入旁白音频后缀避免与中间产物混淆。canvas 一致性项目所有页面的根 viewBox 必须统一且当目录名编码格式时必须匹配注册格式的 viewBox否则validate告警、导出可能异常。7.3 工程化特性小结原子写入manifest JSON 等关键文件通过临时文件 os.replace原子落盘崩溃不产生半成品失败可审计init/import-sources都会写工作流审计日志append_notevalidation/目录留存冷启动审计与质量报告安全边界项目名 sanitizesanitize_name限制为字母数字与-_ .、长度 ≤120、默认名source、路径必须落在基础目录内、manifest 文件名禁止路径穿越字符可脚本化validate有明确退出码info、page-context输出结构化信息便于接入 CI 或自动化流水线。八、结语projects/是 PPT Master 工作流的工位init负责搭骨架、import-sources负责喂素材、scaffold-spec/scaffold-lock负责立规划、validate/info/page-context负责保质量最终由svg_output → svg_final → exports收敛为原生 DrawingML 的.pptx。理解画布格式的注册表语义config.py、目录名的解析规则project_utils.py与projects/内外的移动/复制边界是驾驭这套流水线的关键。所有命令的完整用法可直接查看 project_manager.py 与 cli.py 的 docstring或在仓库中运行python3 skills/ppt-master/scripts/project_manager.py -h获取帮助。【免费下载链接】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），仅供参考