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

AGENTS.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。

由此形成三级权威链：

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 纪律：

1. 解析绝对仓库根并保留绝对技能根——在发出第一条命令之前，必须从 AGENTS.md 被提供的路径解析出仓库绝对根目录，并保留skills/ppt-master的绝对路径。文件中出现的路径只是"仓库相对记法"，实际调用要通过绝对根展开。
2. 保留初始化返回的项目绝对路径——项目初始化后得到的绝对项目路径要贯穿后续所有命令。
3. 禁止cd skills/ppt-master或cd projects/...——切换工作目录会破坏路径锚定，命令必须从仓库根以完整路径调用。
4. 解析机器可读 stdout 时隔离 stderr——永远不要把2>&1放在 JSON 或 XML 解析器上游，否则错误输出会污染结构化解析。
5. 每个具体参数集只调用一次命令——不得把可执行文件或 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 路由内部有两个互斥的运行时，这是 AGENTS.md 反复强调的核心约束：

• Default 运行时：Strategist → Image_Generator → Executor三角色流水线，含规格（spec）、锁（lock）、SVG 与 PPTX 完整产物链；
• Quick 运行时：自包含短电路，无独立策略/确认环节——按需准备素材、由当前 Agent 自主决策、直接手写svg_output/、通过无锁最终检查器后导出。

AGENTS.md 明确了两个特殊画像（profile）与运行时的绑定关系：Image to PPTX（页面截图重建）恒走 Quick；Beautify（美化）是严格的 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 上。从源码结构看，正确生命周期是：

1. 运行 create-template 生成独立的已验证工作区；
2. 将该工作区根作为 Stage-1 模板候选传回 generate-pptx；
3. 从工作区手写新的结构化 SVG 页面（Master/Layout 契约从第一稿起就存在）；
4. 从这些页面导出新 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 Reference（AGENTS.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_path>

project_manager.py的完整子命令与导入边界规则详见专题文档 scripts/docs/project.md：import-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_path>

animation_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 Requirements（AGENTS.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.md；Default 与 Quick Generate 恒定加载 svg-effects.md；其他路由仅在文档声明的触发条件成立时才加载 native-data-interface.md 与 pptx-structure-interface.md。
• 画幅选择在 canvas-formats.md；图标细节在 templates/icons/README.md。

Required Conventions 一节（AGENTS.md）则把编辑仓库本身也纳入治理：

1. 仓库级风格规则——编辑 references/ 下的提示文件、scripts/ 下的 Python 或任何其他代码/文字时，遵循 docs/rules/ 中对应的风格规则；该目录实际包含 code-style.md、prompt-style.md、language.md 三份规则与一份 README。
2. 提示决策归属——遵循 prompt-style.md §4.1：Default 由 Strategist 准备项目级资源、Executor 实现之；Quick 由当前 Agent 在 SVG 创作前自行决策并准备。每个项目图标都是"已准备素材"；icons.inventory索引的是默认方案策划的捆绑池，而不是页面用量或执行白名单。
3. Markdown 语言一致性——遵循 language.md：每个文件一种语言、与同目录兄弟文件镜像；英文文件中允许出现非英文字符串仅限引用内容（用户触发词、示例值、渲染标签、专有名词），绝不作为规则措辞；不得硬编码模型回复语言。

兼容性边界：这不是一个应用脚手架

AGENTS.md 的 Compatibility Boundary（AGENTS.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）给出的目录职责划分是导航整个仓库的最短路径：

总结：把 AGENTS.md 当作 Agent 的"宪法"来读

AGENTS.md 的价值在于它把一条多角色、多路由的复杂 AI 工作流收敛为三条可执行的治理原则：

1. 单一权威链——AGENTS.md 只做索引，SKILL.md 只做纪律与路由入口，routing.md 只做路由裁决，具体步骤只归所选运行时文档；任何一级都不越级决策。
2. 互斥即纪律——Default 与 Quick 两个 Generate 运行时、四条顶层路由、Create Template 的四个子工作流，均以"恰好选一、永不混载"为硬约束，从机制上消除了 Agent 在模糊请求下"两条路都走一点"的失败模式。
3. 命令可复现——每条速查命令都能在当前仓库的 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