ppt-master 的 AGENTS.md 详解：AI Agent 路由权威、命令速查与仓库执行纪律

ppt-master 的 AGENTS.md 详解AI Agent 路由权威、命令速查与仓库执行纪律【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-masterAGENTS.md 是 ppt-master 仓库为通用 AI Agent 准备的入口契约它规定了 Agent 进入仓库后必须先读什么、如何解析路径与命令输出、四条顶层产物路由如何划分、以及哪些目录与文件拥有何种权威。读完本文你将掌握 ppt-master 的AGENTS.md → SKILL.md → routing.md → 运行时权威文档三级权力结构能独立解读其命令速查表中每条脚本的用途与适用路由并理解该工作流包与通用工程脚手架之间的兼容性边界。AGENTS.md 的定位Agent 的仓库入口而非用户手册AGENTS.md 开篇第一句即声明其身份This file is the project entry point for general AI agents. 它不面向人类用户介绍产品卖点而是为将要在此仓库内执行任务的 AI Agent 建立执行纪律。文档的核心指令只有一条任何 PPT 生成任务或仓库修改之前必须阅读 skills/ppt-master/SKILL.md。由此形成三级权威链层级文件职责仓库入口AGENTS.md全局执行纪律的总纲、路由索引、命令速查、目录地图技能入口SKILL.md全局执行纪律Mandatory Load Order、8 条 Global Execution Discipline与路由选择的唯一入口运行时权威workflows/routing.md 选定的具体运行时文档拥有该路由下的步骤、门控gate与命令SKILL.md 自身的定位与之一致This entry owns global execution discipline and route selection only; each selected route owns its procedure.——入口文档只管纪律与路由具体步骤归所选路由所有。这种索引与执行分离是理解整个仓库治理结构的关键AGENTS.md 与 SKILL.md 都不会越级替某条路由做决策路由选定后后续一切由该路由的权威文档接管。仓库执行锚第一条命令之前的硬规则AGENTS.md 中最容易被忽略、却对执行稳定性影响最大的是Repository execution anchor一节AGENTS.md它规定了一组 Agent 调用命令前必须遵守的路径与 I/O 纪律解析绝对仓库根并保留绝对技能根——在发出第一条命令之前必须从 AGENTS.md 被提供的路径解析出仓库绝对根目录并保留skills/ppt-master的绝对路径。文件中出现的路径只是仓库相对记法实际调用要通过绝对根展开。保留初始化返回的项目绝对路径——项目初始化后得到的绝对项目路径要贯穿后续所有命令。禁止cd skills/ppt-master或cd projects/...——切换工作目录会破坏路径锚定命令必须从仓库根以完整路径调用。解析机器可读 stdout 时隔离 stderr——永远不要把21放在 JSON 或 XML 解析器上游否则错误输出会污染结构化解析。每个具体参数集只调用一次命令——不得把可执行文件或 flag 列表编码进标量 shell 字符串、不得用 shell 循环批量执行、也不得在命令本身已提供紧凑视图时再叠加下游解析器。这些规则针对的是 Agent 实践中最常见的失败模式相对路径漂移、循环批处理导致错误被吞掉、日志混流导致 JSON 解析崩溃。SKILL.md 的 Global Execution Discipline 第 8 条与之呼应Stable paths — Use absolute skill/project paths; never derive them from CWD.并规定若无法确定 Skill 根目录应直接询问用户而非猜测搜索。四条顶层路由与 Generate 的互斥双运行时AGENTS.md 的 Project Overview 部分AGENTS.md给出了全仓库的产物生命周期划分。路由选择的唯一权威是 workflows/routing.md它定义恰好四条顶层路由且声明若本文件与其他位置的路由摘要冲突本文件赢路由请求形态权威文档变更模型Generate PPTX从素材或主题创建、重建或视觉重生成演示/视频image-to-pptx恒 Quick、beautify-pptx、generate-pptx / quick-generate手写 SVG 页面并导出新 PPTXCreate Template从 PPTX/SVG、图片/PDF、文本、文档/网站、品牌资产或混合引用创建可复用模板create-template创建新的可移植工作区绝不就地修改引用文件Fill Native PPTX用原生 PPTX 的幻灯片壳替换/填充内容template-fill-pptx克隆并通过 OOXML 补丁修改 PPTX不经过 SVG 管线Enhance Native PPTX保持成品 PPTX 可见页稳定追加备注、音频、计时或转场native-enhance-pptx追加/更新限定范围的 OOXML 部件不重新生成页面Generate PPTX 路由内部有两个互斥的运行时这是 AGENTS.md 反复强调的核心约束Default 运行时Strategist → Image_Generator → Executor三角色流水线含规格spec、锁lock、SVG 与 PPTX 完整产物链Quick 运行时自包含短电路无独立策略/确认环节——按需准备素材、由当前 Agent 自主决策、直接手写svg_output/、通过无锁最终检查器后导出。AGENTS.md 明确了两个特殊画像profile与运行时的绑定关系Image to PPTX页面截图重建恒走 QuickBeautify美化是严格的 1:1 重生成画像——显式 Quick 意图走 Quick 运行时否则走 Default一旦发生拆分/合并/删页/重排Beautify 立即失效并回落到普通 Generate。routing.md 用两条 Hard rule 固化了这一点Image to PPTX and Beautify change different source/page invariants and are mutually exclusive且Neither defines a separate artifact lifecycle or loads both runtimes.此外 AGENTS.md 对若干高频场景给出了明确裁决纯主题输入或事实不足在所选 Generate 画像的 source intake 内运行 topic-research其事实 URL 不自动展开。常规图片搜索失败后最多抓取一个相关网页作为来源包且只有被评审选中的条目进入运行时图片池。Default 的模板候选Step 3 内部静默准备模板候选Stage 1 一次性确认沟通契约 自由设计/模板选择模板内容在该确认前保持未读选定根在模板感知的 Stage 2 之前安装。Quick 跳过这一交互。原始 PPTX 模板 新素材走 template-fill-pptx不进入 SVG 管线。video-design 条件加载录像、自运行或视频导向的 Generate 工作在页面规划前条件性加载 video-design它改变的是场景、脚本与动效设计而不是运行时或路由。模板与 Master/Layout 边界禁止直接结构嫁接AGENTS.md 与 routing.md 共同执行的一条硬规则值得单独强调永远不要把 Master/Layout 结构直接嫁接到现有 PPTX/SVG 上。从源码结构看正确生命周期是运行 create-template 生成独立的已验证工作区将该工作区根作为 Stage-1 模板候选传回 generate-pptx从工作区手写新的结构化 SVG 页面Master/Layout 契约从第一稿起就存在从这些页面导出新 PPTX。同时 routing.md 规定no automatic structure upgrade自由设计、仅品牌、仅样式的生成保持pptx_structure.mode: flat重复的 Slide-local 对象永远不会自动触发structured或 Master/Layout 提升。这解释了为什么 examples/ 中各项目都是svg_output → svg_final → exports的完整再生成链而不是对旧文件的就地升级。命令速查表逐条对照源码AGENTS.md 的 Command Quick ReferenceAGENTS.md自称仅便捷摘要——路由选择从 SKILL.md 开始。以下按功能分组逐条说明所有脚本均实际存在于 skills/ppt-master/scripts/ 目录中素材转换与项目管理# 素材内容转换文件/URL/目录均可 python3 skills/ppt-master/scripts/source_to_md.py file_or_URL_or_dir [file_or_URL_or_dir ...] # 项目初始化ppt169 为 16:9 画幅 python3 skills/ppt-master/scripts/project_manager.py init project_name --format ppt169 # 导入源文件projects/ 内默认移动、外部一律复制 python3 skills/ppt-master/scripts/project_manager.py import-sources project_path source_files_or_dirs_or_URLs... # 可选的手工脚手架辅助 python3 skills/ppt-master/scripts/project_manager.py scaffold-spec project_path python3 skills/ppt-master/scripts/project_manager.py scaffold-lock project_path # 项目校验 python3 skills/ppt-master/scripts/project_manager.py validate project_pathproject_manager.py的完整子命令与导入边界规则详见专题文档 scripts/docs/project.mdimport-sources还接受--move/--copy互斥init另有--quick-generate变体只建svg_output/与validation/workflow.log无 README。图标与声音资源# 图标选择——把选中的库图标复制进 project/icons/缺失名称会报告且退出码非零 需重新选择 python3 skills/ppt-master/scripts/icon_sync.py project_path lib/name [lib/name...] # 声音库 python3 skills/ppt-master/scripts/sound_sync.py list [--query term] python3 skills/ppt-master/scripts/sound_sync.py project_path namespace/id...图标库的五个子库chunk-filled、phosphor-duotone、simple-icons、tabler-filled、tabler-outline及其使用规范在 templates/icons/README.md 中定义。声音的选取规则遵循 references/animations.md §2.2。确认 UI 与 SVG 工具链# Stage-1 确认服务器守护模式启动 / 仅等待指定阶段 python3 skills/ppt-master/scripts/confirm_ui/server.py project_path --daemon python3 skills/ppt-master/scripts/confirm_ui/server.py project_path --wait-only --wait-stage stage1 # 图片分析与 SVG 质量检查 python3 skills/ppt-master/scripts/analyze_images.py project_path/images # 管线内 AI 图片生成——manifest 模式为必选哪怕只有 1 张图 python3 skills/ppt-master/scripts/image_gen.py --manifest project_path/images/image_prompts.json python3 skills/ppt-master/scripts/image_gen.py --render-md project_path/images/image_prompts.json # 管线外的一次性/调试/单图修复无 manifest、无 sidecar python3 skills/ppt-master/scripts/image_gen.py prompt --aspect_ratio 16:9 --image_size 1K -o project_path/images # 点状插画——把一张 AI 网格图切片成独立元素契约见 image-generator.md §4.3 python3 skills/ppt-master/scripts/slice_images.py project_path/images/sheet.png --grid RxC --names a,b,c --trim --alpha --bg KEY_HEX_FROM_PROMPT --strict-alpha # 浏览器实时编辑器live 模式 守护 python3 skills/ppt-master/scripts/svg_editor/server.py project_path --live --daemon # 最终 SVG 质量门 python3 skills/ppt-master/scripts/svg_quality_checker.py project_path从 image_gen.py 源码可以确认其文档字符串本身就给出了这两种用法manifest 模式与单 prompt 模式且内置后端的默认尺寸为1K部分后端默认2K——这与速查表中manifest 模式必选、单图仅限管线外的纪律一致。确认服务器的守护/等待语义在 confirm_ui/server.py 的用法注释中同样可见--daemon启动后保持页面打开--wait-only --wait-stage stage1则不另起子进程、只追踪已记录的 pid 并等待指定阶段。Create Template 专属工具# 模板校验前的坐标压缩共享步骤 python3 skills/ppt-master/scripts/compact_svg_coordinates.py template_workspace/templates --inplace --keep-native-frames # 显式模板归一化把选中的复杂 g 抽成单个 SVG 图片资产 / image python3 skills/ppt-master/scripts/extract_svg_pictures.py svg_file --select group_id --resource-root workspace --images-dir workspace/picture-assets --inplace # Type A 镜像已验证的 authoring IR - 确定性的结构化模板工作区 python3 skills/ppt-master/scripts/mirror_template_materialize.py import_workspace empty_template_workspace # 模板评审 deck工作区根可以是全局或项目级 python3 skills/ppt-master/scripts/template_preview_pptx.py template_workspace这四个脚本对应 Create Template 路由中authoring IR → 结构化工作区 → 评审 deck的物化链路是 routing.md §4先建工作区、再回 Generate生命周期的落地工具。动画与原生增强# 对象级自定义动画可选脚手架 重导出前校验 python3 skills/ppt-master/scripts/animation_config.py scaffold project_path python3 skills/ppt-master/scripts/animation_config.py validate project_path # 现有 PPTX 原生增强——直接 OOXML 补丁不做 SVG 转换 python3 skills/ppt-master/scripts/native_enhance_pptx.py init PPTX_file --name project_slug python3 skills/ppt-master/scripts/native_enhance_pptx.py validate project_path python3 skills/ppt-master/scripts/native_enhance_pptx.py apply project_pathanimation_config.py 源码中注册了scaffold、list_groups、validate三个子命令与速查表一致native_enhance_pptx.py 的 init/validate/apply 三段式对应 Enhance Native PPTX 路由锁定可见页 → 补丁 → 应用的不变式。AGENTS.md 最后提醒串行后处理与导出必须严格按 generate-pptx.md 的 Step 7 执行该步骤细分为 7.1 拆分演讲者备注、7.2 构建自包含 SVG 预览、7.3 导出原生 PPTX工具 flag 与行为详见 scripts/docs/svg-pipeline.md。执行要求与强制约定AGENTS.md 的 Execution RequirementsAGENTS.md规定了文档的常载与条件加载边界任何从 PPTX/SVG、图片/PDF、文档/网站、品牌资产、直接文本或混合引用创建brand/style/layout/deck工作区的请求统一进入 create-template.md——它保持固定的 Create Template 路由名并恰好分派 create-brand、create-style、create-layout、create-deck 四选一。Always-on 的 SVG 约束与共享视觉质量默认值位于 references/shared-standards-core.mdDefault 与 Quick Generate 恒定加载 svg-effects.md其他路由仅在文档声明的触发条件成立时才加载 native-data-interface.md 与 pptx-structure-interface.md。画幅选择在 canvas-formats.md图标细节在 templates/icons/README.md。Required Conventions 一节AGENTS.md则把编辑仓库本身也纳入治理仓库级风格规则——编辑 references/ 下的提示文件、scripts/ 下的 Python 或任何其他代码/文字时遵循 docs/rules/ 中对应的风格规则该目录实际包含 code-style.md、prompt-style.md、language.md 三份规则与一份 README。提示决策归属——遵循 prompt-style.md §4.1Default 由 Strategist 准备项目级资源、Executor 实现之Quick 由当前 Agent 在 SVG 创作前自行决策并准备。每个项目图标都是已准备素材icons.inventory索引的是默认方案策划的捆绑池而不是页面用量或执行白名单。Markdown 语言一致性——遵循 language.md每个文件一种语言、与同目录兄弟文件镜像英文文件中允许出现非英文字符串仅限引用内容用户触发词、示例值、渲染标签、专有名词绝不作为规则措辞不得硬编码模型回复语言。兼容性边界这不是一个应用脚手架AGENTS.md 的 Compatibility BoundaryAGENTS.md与 SKILL.md 的 Repository Compatibility 节共同划定了仓库形态的边界这一点在 Agent 协作中尤其重要本仓库是workflow/skill 包不是 app 或 service scaffold不要假设.worktrees/、tests/或强制分支设置等通用工程约定除非用户明确要求与通用编码技能冲突时本仓库内的 SKILL.md 优先。从目录结构可以印证仓库没有tests/目录树质量保障内嵌于工作流svg_quality_checker.py、project_manager.py validate、各 stage 的显式门控而非外部 CI 测试套件。同时 SKILL.md 还规定了一个前置完整性门加载顺序第 2 步要求从 Skill 目录运行python3 scripts/attribution_guard.py脚本确实存在于 scripts/attribution_guard.py任何非零结果立即停止技能且不得检查、修复或绕过该完整性门。核心目录地图AGENTS.md 末尾AGENTS.md给出的目录职责划分是导航整个仓库的最短路径路径职责skills/ppt-master/SKILL.md全局纪律与路由入口权威skills/ppt-master/workflows/generate-pptx.mdGenerate PPTX 的 Step 1–7 权威skills/ppt-master/references/角色核心 条件加载的角色与技术模块strategist/executor/image 系列、svg-effects、canvas-formats 等skills/ppt-master/scripts/可运行工具脚本约 60 个顶层脚本与多个子包confirm_ui、svg_editor、svg_to_pptx、pptx_to_svg 等skills/ppt-master/scripts/docs/面向主题的脚本文档project.md、svg-pipeline.md、troubleshooting.md 等 19 篇skills/ppt-master/templates/布局模板、图表模板、图标库、品牌预设skills/ppt-master/workflows/顶层路由权威 子工作流profiles/、阶段stages/与治理 runbookgovernance/docs/用户侧文档FAQ、安装、技术设计、模板指南、音频旁白docs/rules/仓库级风格规则examples/示例项目每个项目含 design_spec.md、spec_lock.md、svg_output/、svg_final/、exports/projects/用户项目工作区运行时生成通常不在版本库中总结把 AGENTS.md 当作 Agent 的宪法来读AGENTS.md 的价值在于它把一条多角色、多路由的复杂 AI 工作流收敛为三条可执行的治理原则单一权威链——AGENTS.md 只做索引SKILL.md 只做纪律与路由入口routing.md 只做路由裁决具体步骤只归所选运行时文档任何一级都不越级决策。互斥即纪律——Default 与 Quick 两个 Generate 运行时、四条顶层路由、Create Template 的四个子工作流均以恰好选一、永不混载为硬约束从机制上消除了 Agent 在模糊请求下两条路都走一点的失败模式。命令可复现——每条速查命令都能在当前仓库的 scripts/ 与 scripts/docs/ 中找到对应实现与专题文档路径锚定绝对根、禁cd、stderr 隔离保证这些命令在任意宿主 Agent 中行为一致。对新接入仓库的 Agent 而言正确的心智模型是先读 AGENTS.md 建立纪律与地图再读 SKILL.md 通过完整性门并加载 routing.md 完成路由选择最后才进入唯一一条运行时权威文档逐步执行——这正是文档开头那句先读 SKILL.md 再做任何事所守护的完整链条。【免费下载链接】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），仅供参考