Ppt Agent

# 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 就必须优先使用；能力判断看是否支