PPT Agent v4 — 主控制台合同

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 前，禁止执行后续步骤。

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

通用生命周期：create(--model SUBAGENT_MODEL) → RUN(prompt路径) → STATUS… → FINALIZE → close；完成即关，不复用。Step 4 每页一个 PageAgent-N，通过 orchestrator prompt 内部自主渐进完成 Planning → HTML → Review，整页 FINALIZE 后立刻关闭。创建时必须显式传 --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 不承担文生图

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

主 agent 到达上表任意 Step 时，必须按以下流程显式组装 subagent 调用命令：

回查 Section 3.1.1 输出的《Subagent 操作手册》，取出其中的调用模板（模型槽位使用 SUBAGENT_MODEL）
变量替换：将模板中的 {{SUBAGENT_NAME}}、{{PROMPT_PATH}}、{{MODEL}} 替换为当前步骤的实际值（{{MODEL}} = SUBAGENT_MODEL）
显式输出：将组装后的完整命令输出到对话中（不是脑内执行，是显式写出来）
执行：按输出的命令执行 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 命令，不要擅自做无关探索。
采访前置锁定：进入流程后的第一条对外消息必须是 Step 0 的采访问题；不得先做调研、资料探索或报告读取。
阅读隔离边界：未到对应步骤时禁止读对应阶段文件；主 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 加载标题+引用层组成菜单
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 必须按照以下顺序执行环境感知，并将结果显式分类输出到对话中。这决定了整个任务的工具下限。

前置操作：

先调用 update_plan 创建 canonical plan。
必须读取 references/cli-cheatsheet.md 建立对所有 CLI 接口的精确记忆。

3.1.0 模型感知与 Subagent 模型绑定（Model Perception）

为了绝对保证内容质量不滑坡，主 agent 必须在开局时确认自己是谁，并在采访阶段确认 subagent 使用的模型：

强行识别当前主 agent 正在使用的大模型版本（例如 Claude-3.5、Gemini-1.5 等，如果无法确认直接问用户）。
将其在心中显性固化为 MAIN_MODEL 全局变量，并在对话中输出 ## 模型感知结果。
SUBAGENT_MODEL 绑定：Step 0 采访阶段会向用户确认 subagent 使用的模型（详见 6.2）。用户回答后，将其显性固化为 SUBAGENT_MODEL 全局变量，并在 ## 模型感知结果 中同步输出。若用户未明确指定，则 SUBAGENT_MODEL 默认等于 MAIN_MODEL。
全局防降格红线：一旦确认 SUBAGENT_MODEL，在后续流程中创建任何 Subagent 时，必须强制携带该模型参数发起子系统（绝对禁止走默认回退配置）。

3.1.1 Subagent 操作手册生成

环境中有多种执行工具，主 agent 必须为自己梳理规矩：

自检环境中用于创建管理 agent/subagent 的技能或 API。
检查这些工具是否支持模型重载参数（对应 3.1.0）。
整理出支持情况并输出到对话，标题固定为 ## Subagent 操作手册，必须包含以下内容：
- 工具名称：当前环境可用的 subagent 创建工具
- 调用模板（必须含变量槽）：一个可参数化的命令模板，包含 {{SUBAGENT_NAME}}、{{PROMPT_PATH}}、{{MODEL}} 三个槽位（{{MODEL}} 填 SUBAGENT_MODEL 的值）
- 示例调用：用具体值填充槽位的实例
调用模板示例（主 agent 必须根据实际环境生成类似格式，{{MODEL}} = SUBAGENT_MODEL）：
```
# 模板（槽位用 {{}} 标记，MODEL 取自用户在采访阶段指定的 SUBAGENT_MODEL）
<tool> --model {{MODEL}} --message "Read {{PROMPT_PATH}} and execute all instructions" --name {{SUBAGENT_NAME}}
```
此后每个业务节点调用 subagent 时，必须回查此模板、替换变量、显式输出组装后的完整命令到对话中，然后执行。禁止“依据操作手册”这种含糊引用。

3.1.2 采访 UI 能力探测

由于 Step 0 直接决定用户交互体验：

主 agent 必须自检当前 CLI 是否提供原生结构化提问 UI。
判断标准：是否存在可提交 question/header/id/options 一类结构化字段，并让用户直接点选/填写的能力；名称不限，可表现为 AskUserQuestion、request_user_input、ask_user_question、ui.form 等。
将结论以 ## 采访 UI 能力 输出到对话中，至少包含：
- 是否支持结构化采访 UI
- 工具名称或能力形态
- 是否支持单选 / 多选 / 自由补充
- Step 0 实际执行策略：structured-ui / text-fallback
Step 0 发问前，必须先回查这一结论；支持则使用 tpl-interview-structured-ui.md，不支持则使用 tpl-interview-text-fallback.md。

3.1.3 Search 工具清单探测

由于 Research 分支极度依赖网络检索能力：

主 agent 自检所有带有 web search 或直接读取 URL 功能的系统工具及自定义 skill。
梳理支持项，输出名为 ## Search 工具清单 的表格到对话中。
此步生成的清单，将在 Step 2A 通过 TOOLS_AVAILABLE 变量直接喂给检索子代理，务必清晰详实。

3.1.4 兜底能力检查

如果缺失基础能力，必须主动停止并报错：

文件读写、Python、规划：必须具备，无则直接停止流程。
信息检索：尽量具备，若无可主动建议用户仅走 Step 2B 修改本地资料。
图像生成：若无实际工具支持，强制后续图片策略降级为 manual_slot 或 decorate。

3.2 路径变量

变量	值
`SKILL_DIR`	当前 skill 根目录（例如：`../skills/ppt-agent-workflow-san`，必须是相对路径）
`ROOT_OUTPUT_DIR`	`ppt-output/`（必须相对 CWD，禁止跳出）
`RUN_ID`	`YYYYMMDD-HHMMSS-topic`（带时间戳用于区分同目录下不同任务的产出）
`OUTPUT_DIR`	`ROOT_OUTPUT_DIR/runs/{RUN_ID}`

RUN_ID 唯一性约束：同一个 PPT 任务全程只允许一个 RUN_ID，Step 0 创建后锁定复用，重试/回退/断点恢复均复用同一个，禁止为同一任务重复创建。不同的 PPT 任务（不同主题）各自独立 RUN_ID。恢复旧任务时绑定旧 RUN_ID。

⚠️ 跨环境可移植性红线（防止运行时路径污染）：在组装并向 prompt_harness.py 传入用于子代理指引的变量时，主 Agent 绝对禁止将其展开成宿主的死硬绝对路径（如 /home/xxxxxxxx/...），也尽量避免结构极度脆弱的外跳路径（如 ../../../.gemini/...）。

最聪敏的终极解决方案：

对于引擎代码路径（如 --var SKILL_DIR= 或 --var REFS_DIR=），主 agent 请直接传递带有环境变量字面量的字符串本身（如 --var SKILL_DIR='$SKILL_DIR'、--var REFS_DIR='$SKILL_DIR/references'）。

这样最终生成的 OUTPUT_DIR/runtime/prompt-*.md 模板内容里，就会直接保留 python3 $SKILL_DIR/scripts/... 这种占位符。子代模型也会乖乖地用这样的环境变量向终端请求执行，任何终端只要配置了 $SKILL_DIR 都可以瞬间通跑我们的产物！

对于业务流水线位置（OUTPUT_DIR 相关），必须退化成基于 CWD 的干净相对路径。

3.3 正式产物链

interview-qa.txt → requirements-interview.txt
  → search.txt + search-brief.txt（research）| source-brief.txt（非 research）
  → outline

ppt-agent