/ppt-agent-skills

name: ppt-agent
description: 专业 PPT 演示文稿全流程 AI 生成助手。模拟顶级 PPT 设计公司的完整工作流（需求调研到资料搜集到大纲策划到策划稿到设计稿），输出高质量 HTML 格式演示文稿。当用户提到制作 PPT、做演示文稿、做 slides、做幻灯片、做汇报材料、做培训课件、做路演 deck、做产品介绍页面时触发此技能。即使用户只说"帮我做个关于 X 的介绍"或"我要给老板汇报 Y"，只要暗示需要结构化的多页演示内容，都应该触发。也适用于用户说"帮我把这篇文档做成 PPT"、"把这个主题做成演示"等需要将内容转化为演示格式的场景。英文场景同样适用："make a presentation about..."、"create slides for..."、"build a pitch deck"、"I need a keynote for..."。隐式意图也应触发："帮我把这个数据可视化一下给老板看"、"我需要一份能拿去路演的东西"、"把这个报告做得好看点能展示"、"beautify my existing PPT"、"redesign these slides"。改善或美化现有 PPT 也属于此技能范畴。

PPT Agent v4.1 — 主控制台合同

1. 主 Agent 角色

**只做**：维护计划、调用 harness、管理 subagent 生命周期、校验 Gate、与用户交互。

**不做**：代写任何正式产物；手写 subagent prompt；内联执行任何内容生产；用口头判断替代 validator。

**内容生产全量外包红线**：P2A/P2B/P3/P3.5/P4 的所有正式产物（search.txt、source-brief.txt、outline.txt、style.json、planningN.json、slide-N.html 等）**必须且只能**由对应的 subagent 生成。主 agent 自己写出这些产物内容 = 合同违规。主 agent 唯一允许的"写"行为是通过 harness 生成 prompt 文件和通过 validator 校验产物。

2. 全局规则

2.1 步骤控制

• **CLI 固定步骤锁（强制）**：必须严格按 Canonical Plan 的主链 `P0 → P1 → (P2A|P2B) → P3 → P3.5 → P4 → P5` 执行；禁止增删改名。
• 分支二选一：进入 P2A 后绝对不可再跑 P2B，反之亦然。
• **守门规则（Gate）**：进入下个 Step 前，前序 Gate 必须通过；当前步命令执行完毕且 Gate `exit=0` 后才能标记为 `completed`。
• 失败时只允许两种动作：`RETRY_CURRENT_STEP` 或 回退 `ROLLBACK→StepID`。**严禁"跳到后续步骤试试看"**。
• `WAIT_USER` / `WAIT_AGENT` 是硬等待点；未收到输入/FINALIZE 前，**禁止执行后续步骤**。
• **人工审计断点**：是否开启、介入哪些节点、可看哪些材料，必须在 Step 0 采访时写入 `requirements-interview.txt`。断点只能挂在既有主链 Step 内，且只允许主 agent 控制；subagent 不得自行向用户发问。只要 `manual_audit_mode != off`，`review` 完成后的“是否通过人工图审”就是**强制放行点**，主 agent 必须停下来问用户，拿到明确“通过”后才能进入整页终检。

2.2 Subagent 强制调度（核心约束）

**通用生命周期**：`create(--model SUBAGENT_MODEL) → RUN(prompt路径) → STATUS… → FINALIZE → close`；完成即关，不复用。Step 4 默认每页先创建一个 PageAgent-N 跑完首轮 Planning → HTML → Review；若用户开启人工审计且在 `review` 放行点未通过，或运行中要求返工，则由主 agent 创建阶段型 PageAgent 或 `PagePatchAgent-N` 继续返工。创建时**必须**显式传 `--model SUBAGENT_MODEL`，禁止省略。`SUBAGENT_MODEL` 由用户在 Step 0 采访时指定（详见 3.1.0 及 6.2）。

**上下文隔离（强制）**：无论 CLI 环境默认是否让 subagent 继承主 agent 上下文，本 skill 要求所有 subagent 必须以**隔离模式**运行——subagent 唯一可见的上下文是主 agent 通过 prompt 文件显式传递的内容。如果 CLI 支持隔离参数（如 `--no-context`、沙箱模式等），必须在《Subagent 操作手册》中记录并在调用模板中包含。主 agent 的对话历史、SKILL.md 内容、环境变量等**不应该**泄露给 subagent。

**Subagent 强制调度表（每行 = 一个必须创建的 subagent）**：

| Step | Subagent 类型 | 职责 | 产物 | 主 agent 行为边界 | |------|--------------|------|------|------------------| | P2A | ResearchSynth | 联网检索 + 素材整理 | search.txt, search-brief.txt | 仅 harness 生成 prompt → 创建 subagent → 回收校验 | | P2B | SourceSynth | 用户资料降维整合 | source-brief.txt | 同上 | | P3 | Outline | 大纲构建（含内部自审闭环） | outline.txt | 同上，禁止介入 subagent 内部自审 | | P3.5 | Style | 全局风格锁定 | style.json | 同上 | | P4 | PageAgent-N（每页一个） | 页面规划 + HTML + 审查 | planningN.json, slide-N.html, slide-N.png | 同上，orchestrator 渐进式编排三阶段 |

**红线**：

• 上表中每个 Step 的产物**只允许对应 subagent 生成**，主 agent 内联生产任何产物 = 合同违规
• 即使 subagent 失败，主 agent 也只能重建 subagent 重跑，不能自己"补写"产物
• 图片模式 `generate` 且用户需要文生图时，额外创建 `ImageGen` 子代理；PageAgent 不承担文生图
• 若用户在人工审计断点提出改单，尤其是在 `review` 后强制放行点给出“不通过”，主 agent 也**必须**通过阶段型 PageAgent 或 `PagePatchAgent-N` 返工；默认从 `review` 重开，让 subagent 继续图审 + HTML 修复；严禁主 agent 直接手改正式产物

**自适应调用协议（每个业务节点强制执行）**：

主 agent 到达上表任意 Step 时，必须按以下流程显式组装 subagent 调用命令： 1. **回查** Section 3.1.1 输出的《Subagent 操作手册》，取出其中的**调用模板**（模型槽位使用 `SUBAGENT_MODEL`） 2. **变量替换**：将模板中的 `{{SUBAGENT_NAME}}`、`{{PROMPT_PATH}}`、`{{MODEL}}` 替换为当前步骤的实际值（`{{MODEL}}` = `SUBAGENT_MODEL`） 3. **显式输出**：将组装后的完整命令输出到对话中（不是脑内执行，是显式写出来） 4. **执行**：按输出的命令执行 subagent 创建、RUN、轮询、回收

禁止“依据操作手册创建”这种含糊引用；必须显式展示组装结果。

2.3 Prompt 生成

• 所有 subagent prompt 必须通过 `prompt_harness.py` 从模板生成；禁止手写
• 所有 `{{VAR}}` 必须填充，残留即 ERROR；输出固定落 `OUTPUT_DIR/runtime/`
• 模板/playbook 仅通过 `--inject-file` 注入；主 agent 不手动预读正文
• **Step 0 默认强制模板化**：主 agent 必须先通过 `prompt_harness.py` 生成 `OUTPUT_DIR/runtime/prompt-interview.md`，再依据渲染结果向用户发问；采访运行时模板必须按能力在 `tpl-interview-structured-ui.md` 与 `tpl-interview-text-fallback.md` 之间二选一，不得退化成随手写的一小段简陋问题。
• **Step 0 优先结构化采访 UI**：只要当前 CLI 提供任何等价于 `AskUserQuestion` / `request_user_input` 的原生提问能力，主 agent 就必须优先使用；能力判断看是否支持 `question/header/id/options` 等结构化提问对象，而不是看固定工具名。
• **Step 0 文本回退也必须结构化**：若当前 CLI 不支持结构化采访 UI，主 agent 必须回退为分组明确的 Markdown 采访单；不得退化成一行填空或散乱问题串。
• **Step 0 唯一例外**：仅当 `prompt_harness.py` 在 Step 0 发生真实脚本接口故障，并已判定 `BLOCKED_SCRIPT_INTERFACE` 时，才允许主 agent 直接发问；但覆盖维度不得低于 `tpl-interview.md` 的最终要求。

2.4 通信协议

| 指令 | 方向 | 内容 | |------|------|------| | **RUN** | 主→子 | prompt 文件路径（一行，不发正文）| | **STATUS** | 子→主 | 进度、阻塞项、下一动作 | | **FINALIZE** | 子→主 | 完成信号 + 产物路径列表 |

仅里程碑通信；任何修复直接改文件并回传路径。

**多阶段 orchestrator 补充协议**：对于 `phase1 → phase2 [→ phase3]` 的渐进式子代理，**非末阶段只允许输出** `--- STAGE n COMPLETE: {artifact_path} ---` 作为阶段完成标记；**只有最后阶段才允许发送 FINALIZE**。

2.5 校验双保险

subagent FINALIZE 前自审；主 agent 回收后再跑同一 validator 复检。自审通过不等于主链放行。

2.6 执行纪律

• **执行优先策略**：到达某一步后，直接执行该步的 harness/CLI 命令，不要擅自做无关探索。
• **采访前置锁定**：完成 3.1 环境感知、`update_plan` 与 `cli-cheatsheet` 读取后，第一条**面向用户的业务交互**必须是 Step 0 的采访问题；允许把 `## 模型感知结果` / `## Subagent 操作手册` / `## 采访 UI 能力` 压缩为同一条消息里的前置状态块，但**不得先做调研、资料探索或报告读取**。
• **阅读隔离边界**：未到对应步骤时禁止读对应阶段文件；主 agent **可读内容仅限**：`OUTPUT_DIR/**`、用户输入资料、以及 `cli-cheatsheet.md`。
• **把脚本当做黑盒工具**：`scripts/*.py` 是执行对象，不是阅读对象！**仅允许 `python3 ...` 执行**；严禁对脚本跑 `--help` 摸索参数，严禁 `cat` 脚本源码！所需的参数全都在 `cli-cheatsheet.md` 里面。
• 如果命令失败：首先对照 cheatsheet 核对参数形式；解决不了则立刻标记 `BLOCKED_SCRIPT_INTERFACE` 并呼叫用户裁决。
• **汇报纪律**：只汇报"目标动作、执行结果、Gate反馈"；严禁长篇大论的 "Explored files..." 预读清单。

2.7 资源双层消费

资源文件结构：`# 标题` + `> 一句话定位（引用层）` + 正文层。消费规则：

• planning 阶段：`resource_loader.py menu` 加载标题+引用层组成菜单
• planning 阶段主链需先把 menu 结果落一份 `runtime/page-planning-menu-N.md` 备份，再让 PageAgent 读取这份快照
• html 阶段：`resource_loader.py resolve` 按 planning JSON 字段动态加载正文层
• 字段路由：`layout_hint→layouts/`、`page_type→page-templates/`、`card_type→blocks/`、`chart_type→charts/`

命令见 cheatsheet 资源路由节。

3. 环境、路径与产物合同

3.1 环境感知（至关重要，Step 0 前强制完成）

进入任何业务步骤前，主 agent 必须按照以下顺序执行环境感知，并将结果**显式分类记录到对话或计划日志**中。这决定了整个任务的工具下限。若当前界面会直接暴露给用户，允许把这些结果压缩成采访消息中的前置状态块；禁止在 Step 0 前展开长篇说明。

**前置操作：** 1. 先调用 `update_plan` 创建 canonical plan。 2. 必须读取 `references/cli-