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 内联生产任何产物 = 合同违规
• 即使 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 通信协议

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

多阶段 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-cheatsheet.md 建立对所有 CLI 接口的精确记忆。

3.1.0 模型与思考深度感知（Model & Thinking Effort Perception）

为了绝对保证内容质量不滑坡，主 agent 必须在开局时确认自己是谁，并在采访阶段确认 subagent 使用的模型及思考等级： 1. 强行识别当前主 agent 正在使用的大模型版本（例如 Claude-3.5、Gemini-1.5 等，如果无法确认直接问用户）。 2. 将其在心中显性固化为 MAIN_MODEL 全局变量，并在对话中输出 ## 模型感知结果。同时也需探测当前环境 API/工具是否支持给模型传递"思考深度/推理努力(reasoning effort)"这一级选项。 3. `SUBAGENT_MODEL` 与 `SUBAGENT_THINKING_EFFORT` 绑定：Step 0 采访阶段不仅会向用户确认 subagent 使用的模型，还会询问需要的思考深度等级（详见 6.2）。用户回答后，将其显性固化为 SUBAGENT_MODEL 和 SUBAGENT_THINKING_EFFORT 全局变量，并在 ## 模型感知结果 中同步输出。 4. 全局防降格红线：一旦确认这两个变量，在后续流程中创建任何 Subagent 时，必须强制将其带入构建参数中（绝对禁止走默认回退配置）。

3.1.1 Subagent 操作手册生成

环境中有多种执行工具，主 agent 必须为自己梳理规矩： 1. 自检环境中用于创建管理 agent/subagent 的技能或 API。 2. 检查这些工具是否支持模型重载参数（对应 3.1.0）。 3. 整理出支持情况并输出到对话，标题固定为 ## Subagent 操作手册，必须包含以下内容：

• 工具名称：当前环境可用的 subagent 创建工具
• 调用模板（必须含变量槽）：一个可参数化的命令模板，包含 {{SUBAGENT_NAME}}、{{PROMPT_PATH}}、{{MODEL}} 以及支持深度思考情况下的 {{THINKING_EFFORT}} 等四个槽位。
• 示例调用：用具体值填充槽位的实例

调用模板示例（主 agent 必须根据实际环境生成类似格式，{{MODEL}} = SUBAGENT_MODEL，{{THINKING_EFFORT}} = SUBAGENT_THINKING_EFFORT）：

   # 模板（槽位用 {{}} 标记，MODEL 取自 SUBAGENT_MODEL，THINKING_EFFORT 取自 SUBAGENT_THINKING_EFFORT）
   <tool> --model {{MODEL}} --reasoning-effort {{THINKING_EFFORT}} --message "Read {{PROMPT_PATH}} and execute all instructions" --name {{SUBAGENT_NAME}}

4. 此后每个业务节点调用 subagent 时，必须回查此模板、替换变量、显式输出组装后的完整命令到对话中，然后执行。禁止“依据操作手册”这种含糊引用。

3.1.2 采访 UI 能力探测

由于 Step 0 直接决定用户交互体验： 1. 主 agent 必须自检当前 CLI 是否提供原生结构化提问 UI。 2. 判断标准：是否存在可提交 question/header/id/options 一类结构化字段，并让用户直接点选/填写的能力；名称不限，可表现为 AskUserQuestion、request_user_input、ask_user_question、ui.form 等。 3. 将结论以 ## 采访 UI 能力 输出到对话中，至少包含：

• 是否支持结构化采访 UI
• 工具名称或能力形态
• 是否支持单选 / 多选 / 自由补充
• Step 0 实际执行策略：structured-ui / text-fallback

4. Step 0 发问前，必须先回查这一结论；支持则使用 tpl-interview-structured-ui.md，不支持则使用 tpl-interview-text-fallback.md。

3.1.3 Search 工具清单探测

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

3.1.4 兜底能力检查

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

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

3.2 路径变量

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

⚠️ 跨环境可移植性红线（防止运行时路径污染）：

在组装并向 prompt_harness.py 传入用于子代理指引的变量时，主 Agent 绝对禁止将其展开成宿主的死硬绝对路径（如 /home/xxxxxxxx/...），也尽量避免结构极度脆弱的外跳路径（如 ../../../.gemini/...）。

>

最聪敏的终极解决方案：

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

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

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

3.3 正式产物链

interview-qa.txt → requirements-interview.txt
  → search.txt + search-brief.txt（research）| source-brief.txt（非 research）
  → outline.txt → style.json
  → planning/planningN.json → slides/slide-N.html → png/slide-N.png
  → preview.html → presentation-{png,svg}.pptx → delivery-manifest.json

运行时 prompt 落 OUTPUT_DIR/runtime/prompt-*.md。

4. Canonical Plan

!强制使用CLI 原装plan list工具管理所有task

P0.01  采访问题组装
P0.02  [WAIT_USER] 获取回答
P0.03  写入 interview-qa.txt
P0.04  归一化 → requirements-interview.txt

P1.01  输入识别
P1.02  [WAIT_USER] 分支选择（research / 非research）

P2A.01 harness → phase1 + phase2 + orchestrator prompt
P2A.02 创建 ResearchSynth subagent（发 orchestrator，subagent 内部自主渐进：搜索 → 格式化+自审）
P2A.03 [WAIT_AGENT] FINALIZE
P2A.04 回收校验（search.txt + search-brief.txt）
P2A.05 [可选] 回退 P2A.01 扩搜重跑
P2A.06 关闭

P2B.01 [如 pptx][WAIT_USER] 模式确认
P2B.02 资料初读与方向提炼（梳理 3-5 个可能的陈述切入方向）
P2B.03 [WAIT_USER] 强制展示方向并获取用户选择
P2B.04 将用户选定方向写入 requirements-interview.txt
P2B.05 harness → phase1 + phase2 + orchestrator prompt
P2B.06 创建 SourceSynth subagent（发 orchestrator，subagent 内部自主渐进：提炼 → 自审）
P2B.07 [WAIT_AGENT] FINALIZE
P2B.08 回收校验（source-brief.txt）
P2B.09 关闭

P3.01  harness → phase1 + phase2 + orchestrator prompt
P3.02  创建 Outline subagent（发 orchestrator，subagent 内部自主渐进：编写 → 自审+修复）
P3.03  [WAIT_AGENT] FINALIZE
P3.04  回收校验 outline.txt
P3.05  关闭

P3.5.01 harness → phase1 + phase2 + orchestrator prompt
P3.5.02 创建 Style subagent（发 orchestrator，subagent 内部自主渐进：决策 → 自审）
P3.5.03 [WAIT_AGENT] FINALIZE
P3.5.04 回收校验 style.json
P3.5.05 关闭

P4.NN.01 生成 Step 4 planning 菜单快照 + runtime prompt
P4.NN.02 创建当前轮 subagent（首轮：PageAgent-NN；断点返工：阶段型 PageAgent 或 PagePatchAgent-NN）
P4.NN.03 [WAIT_AGENT] 回收当前轮 FINALIZE（拿到最新 planning/html/png）
P4.NN.04 [如 manual_audit_mode != off][WAIT_USER] 展示最新 slide-N.png，询问是否通过人工图审
P4.NN.05 [如未通过] 创建 `PagePatchAgent-NN`（默认 `START_STAGE=review, END_STAGE=review`）执行图审 + HTML 修复，然后回到 `P4.NN.03`
P4.NN.06 整页终检（产物校验 + visual_qa + 主 agent 看图）
P4.NN.07 关闭当前页 subagent
（所有页并行推进）

P5.01  生成 preview.html
P5.02  PNG 导出 → presentation-png.pptx
P5.03  SVG 导出 → presentation-svg.pptx
P5.04  写入 delivery-manifest.json

Plan 更新规则：仅状态变化时更新；并行页逐页追踪不合并；create/wait/close 拆开；generate/validate 拆开；回退显式标记 ROLLBACK→StepID。

5. 调度骨架与真源

5.1 统一 Subagent 调度骨架（P2A/P2B/P3/P3.5/P4 共用）

1. 查 cheatsheet 对应步骤 → harness 生成阶段 prompt 文件（phase1 + phase2 [+ phase3]） 2. harness 生成 orchestrator prompt（轻量调度，只含阶段路径 + 渐进式执行协议） 3. 按《Subagent 操作手册》创建 subagent（必须传 --model SUBAGENT_MODEL） 4. 发送 RUN（orchestrator prompt 路径）→ subagent 内部自主渐进式读取各阶段 → 收到 FINALIZE 5. 主 agent 执行 gate 复检；若是 Step 4 且 manual_audit_mode != off，则 FINALIZE 后必须先经过 review 后的 [WAIT_USER] 放行点，再进入整页终检 → 不再复用时立即 close

5.2 真源索引

CURRENT_BRIEF_PATH：research → search-brief.txt；非 research → source-brief.txt（Step 3/4 共用）。

5.3 单一真源与自动检查

• workflow / schema 版本真源：scripts/workflow_versions.py（当前 WORKFLOW_VERSION = 2026.04.09-v4.1）
• Step 4 schema 真源：scripts/planning_validator.py
• outline 密度合同真源：scripts/contract_validator.py
• Step 4 结构/像素双层校验真源：scripts/visual_qa.py
• prompt 变量真源：各 references/prompts/tpl-*.md 模板中的 {{VAR}}
• 资源 ID 真源：references/layouts/、references/blocks/、references/charts/、references/principles/ 的真实文件 stem，与 scripts/resource_loader.py 的归一化规则
• 多阶段完成信号真源：各 orchestrator 模板中的阶段协议
• 自动检查入口：修改 prompt/playbook/cheatsheet/Step 4 schema 示例后，运行 python3 SKILL_DIR/scripts/check_skill.py

6. 主流程状态机

6.1 Step 全景表

所有命令完整参数见 cli-cheatsheet.md。

6.2 Step 0 采访（核心起点，不可跳过）

即使第一句话用户提供了极多信息，严禁跳过采访阶段。

• 高效推进：采访直接收集所需字段信息，不生成解释性分析与背景描述。
• 默认执行方式：优先按环境能力生成使用结构化采访 UI（tpl-interview-structured-ui.md），若不支持则用格式清晰且附带选项的文本问答（tpl-interview-text-fallback.md）。
• 结构化输出约束：通过提示向用户提供明确的备选项。最终收集的字段组合必须高度结构化、数据详实，能直接输出至 requirements-interview.txt 并 100% 被下游验证器（Gate）与子系统（Subagent）解析消费，无需推测与加工。
• 必须覆盖但允许精简（如果已知）的维度：场景、受众、核心传达目标、期望页数与密度、风格倾向、品牌规范、配图策略、资料使用范围，以及是否参与中间人工审计。
• 密度归一化约定（Step 0 就要定死）：用户填写的 page_density 只表示整套 deck 的整体倾向，不等于每页固定密度。内部统一映射为 density_bias：
• 少而精 -> relaxed
• 适中 -> balanced
• 容量极大 -> ultra_dense
• 后续单页差异由 outline 产出的 density_curve 决定，不交给 html 临场发挥。
• subagent 模型与思考深度（必问）：直截了当让用户选「后续子系统使用什么模型，以及需要何种等级的思考深度？」（如低/中/高，或者普通/深度思考，视当前模型生态而定）。选出后分别固化在 SUBAGENT_MODEL 和 SUBAGENT_THINKING_EFFORT 全局变量。如果用户不关心，可以默认 SUBAGENT_MODEL = MAIN_MODEL 并使用中等思考等级。
• 人工审计参与方式（必问）：至少固化 manual_audit_mode、manual_audit_scope、manual_audit_assets 这 3 个字段；具体选项与提问形式放在采访模板里维护，不在 SKILL.md 展开。
• 只有所有重要选项收集齐并固化入 requirements-interview.txt（必须包含模型、思考深度和人工审计参数），才能进入 Step 1。

6.3 Step 1 分支确立

这是流程分水岭。 1. 识别并归类用户输入（大段文本、单文件、多文件、现成 pptx）。 2. 强制向用户确认分支：需要「联网重新检索扩写（Research 分支）」，还是「限定只用当前本地资料（非 Research 分支）」。 3. 得到回答后，将分支写入 requirements-interview.txt。

6.4 Step 2A Search-Lite（Research 分支专有）

此阶段极易发生两个极端：内容单薄 或 无限制搜索烧 Token。

搜索深度预估（主 agent 在生成 prompt 前必须完成）：

• 丰富度优先：搜索的首要目标是为每页提供足够丰富的素材（数据、案例、引用），宁可多搜一轮也不要内容单薄。
• 根据主题复杂度和目标页数，预估搜索轮次上限（MAX_SEARCH_ROUNDS）并写入 prompt 变量：
• 简单/熟知主题（公司介绍、产品宣讲等）：2 轮
• 中等复杂度（行业趋势、技术方案等）：3 轮
• 高复杂度（深度研究报告、多维竞品分析等）：4 轮
• 每轮搜索后 subagent 须自评覆盖率：若数据类型已覆盖目标页数需求且素材充裕，可提前终止；若某维度明显空缺，应继续搜索直到达到上限。
• MAX_SEARCH_ROUNDS 是硬上限而非目标——鼓励在上限内尽可能搜全，但到达上限后必须收敛出 brief，禁止无限追加。

强制检查项：产出的 search-brief.txt 必须包含专为 PPTX 设计的独立结构化数据包区块。必须至少含 3 种不同数据类型（Metrics指标、Comparisons对标、Timelines时间线等）。

• 若搜索质量偏低且未达 MAX_SEARCH_ROUNDS，主 agent 应回退到 `P2A.01` 重建一套新的 ResearchSynth prompt 与 subagent，扩大搜索预算/维度后整步重跑；不要在已 FINALIZE 的 session 上继续补搜。
• 若已达上限仍不满足，标记 SEARCH_QUALITY_LOW 并向用户说明缺口，由用户决定是否补充资料或降低预期。

6.5 Step 2B 本地资料压缩（非 Research 分支）

用户丢来的一堆资料必须先处理好再跑大纲。此步同样走 subagent 模式（SourceSynth subagent），但为了避免黑盒决定方向且保证方向贴合业务，必须在此阶段引入用户决策。禁止主 agent 内联执行正式内容生产，但允许浅度摸底。

1. [特例] pptx 模式确认：若用户直接传了 .pptx，主 agent 须最先强制询问期望的处理模式（仅美化排版 / 彻底重构大纲 / 美化排版并重构内容）。 2. [防黑盒] 资料初读与方向提炼：主 agent （或调用其他轻量解析工具）必须对用户现有的资料做一次快速摸底通读，提炼出 3-5 个可能的PPT 核心陈述方向/切入视角（例如：以技术机制为侧重点 vs 以商业价值为侧重点）。 3. 强制确认方向：通过 [WAIT_USER] 强制向用户提问："基于您提供的资料，我梳理了以下几个讲述方向，您倾向哪种或有其他补充？"。收到用户明确答复后，将此业务方向追加写入 requirements-interview.txt 中。 4. 主 agent 通过 harness 生成 SourceSynth prompt（命令见 cheatsheet Step 2B）。 5. 按《Subagent 操作手册》创建 SourceSynth subagent（必须传 --model SUBAGENT_MODEL）。 6. SourceSynth 负责：多文件降维（doc/excel/pdf/代码 → 纯文本）、前置理解（顺着文件 requirements-interview.txt 里的强制方向提取主题）、整合输出 source-brief.txt。 7. 主 agent 回收 FINALIZE 后执行 Gate 校验。

6.6 Step 3 大纲构建（内部闭环）

核心纪律：主 agent 不要自作聪明显式开启后续的审查验证轮回。Outline subagent 设计为自带闭环属性，它会在内部按照【打草稿 → 严格自查缺陷 → 覆盖修复】的死循环直到完美状态，只有这样它才会交出带有 FINALIZE 的最终 outline.txt。

这一步不只是在排页序，也要先把整套密度节奏定下来：

• outline 必须显式产出 deck 级 density_bias 和整套 density_curve
• 每页必须写完整的 密度下限 / 密度目标 / 密度上限 / 节奏动作 / 信息姿态 / 锚点类型
• 共同硬规则：cover / section / end 不允许 dashboard；禁止连续 3 页 high / dashboard；dashboard 前后必须至少有 1 页非 dashboard 过渡
• contract_validator outline 会直接检查这些字段，不允许把“页差”留到 Step 4 再临时决定

6.7 Step 3.5 风格锁定（全局卡口）

全盘风格定调。只有在明确了需求文本跑出的大纲后才定风格。风格判断不仅看需求，更依赖 runtime-style-rules.md。输出：一份精准的、没有含糊描述、能被页面规划和 HTML 代码直接执行的 style.json。

6.8 Step 4 单页并行生产（orchestrator 渐进式披露）

为防止大模型在一次 prompt 中同时兼顾排版、图文推演与 HTML 编码导致「注意力塌陷」，本阶段每个单页的任务被拆散成三级 prompt（4A Planning -> 4B HTML -> 4C Review）。

这里的密度合同是冻结点，不是建议项：

• planning 必须把 outline 给出的密度窗口冻结成 density_label、density_reason、density_contract
• density_contract 至少要包含 deck_bias、page_lower_bound、page_upper_bound、max_cards、max_charts、min_body_font_px、max_lines_per_card、image_policy、decoration_budget、overflow_strategy
• content_budget 是卡片级硬预算，缺失就算失败；它必须继续服从页级 density_contract
• 从这一步开始，html 只负责执行，不允许自己抬高或降低本页密度

执行模式

Step 4 只保留两种模式：

1. 自动直通：主 agent 生成标准 orchestrator prompt，PageAgent 一次跑完 Planning → HTML → Review。 2. 人工审计：若 manual_audit_mode != off，主 agent 可以在 planning、html 节点挂断点；而在 review 节点，用户放行是强制任务节点，不是可有可无的旁路。

review 后强制放行点

• 只要 manual_audit_mode != off，每次 PageAgent / PagePatchAgent 完成一轮 review、写出最新 slide-N.png 后，主 agent 都必须立刻 [WAIT_USER]。
• 此时提问目标固定为：是否通过人工图审。只有拿到用户明确“通过”，该页才允许进入整页终检。
• 若用户回答“不通过 / 继续改 / 再审一轮”，主 agent 必须默认创建 PagePatchAgent-N，以 START_STAGE=review、END_STAGE=review 重开，让 subagent 在保留现有 planning 与 HTML 上继续图审 + HTML 修复。
• 只有当用户明确要求重做结构或内容布局时，返工起点才允许从 html 或 planning 重开。

返工原则

• 用户在断点提出改单，或在 review 后强制放行点明确“不通过”时，主 agent 只能通过阶段型 PageAgent 或 PagePatchAgent-N 返工，不能自己改正式产物。
• 返工起点只允许是 planning / html / review 三选一；其中 review 后人工图审未通过时，默认从 review 重开；只有用户明确要求重做结构时，才回退到 html 或 planning。
• 断点材料、外挂 orchestrator 组装方式、以及 PagePatchAgent-N 的调用模板，都放在 cli-cheatsheet.md 的 Step 4 中维护。

共通规则

• 各页可以且应当并行推进。
• HTML 必须完全服从 planning：low / mid_low 可高自由度，medium 中自由度，high / dashboard 低自由度。高密页统一优先稳态 grid / flex、短语化文案、表格/矩阵/微图表；禁 hero image、禁重装饰、禁多个主锚点并列、禁靠复杂绝对定位硬塞内容。
• review 必须先核对 density_contract，再看 PNG 视觉质量。
• 如果同一个 P0 / P1 类别在连续 2 轮新截图里仍不收敛，说明问题已经回到预算或骨架层，必须停止继续修 HTML，强制回退 planning，重写 density_label / density_contract / layout_hint / cards 分配 中至少一项。
• 阶段放行条件：三件套（planningN.json + slide-N.html + slide-N.png）必须齐全，planning_validator 必须放行；整页 FINALIZE 回收后，主 agent 还必须补跑 visual_qa --html 并亲自看图；若开启人工审计，还必须拿到用户在 review 后的明确“通过”。这些条件同时满足才算该页放行。
• subagent 死亡 = 上下文全无。任何出错重试，旧 session 失去价值，必须整页打回重跑（详见 Section 7）。

6.9 Step 5 交付

双管线（PNG/SVG）并行；导出失败只回退导出，不回退内容生产。命令见 cheatsheet Step 5。

7. 重试与恢复

原则：只信文件与 Gate 校验，不信口头记忆或 session 状态。

7.1 Step 4 重试（两步走）

第一步：侦查 — 扫描所有页，收集触发条件（任一成立）的页号：

• planningN.json 不存在、为空或 planning_validator 不通过
• slide-N.html 不存在或为空
• slide-N.png 不存在或为空
• visual_qa.py 退出码为 1（致命缺陷）
• 主 agent 亲自看图发现明显视觉问题
• 用户在 review 后强制人工图审卡口明确表示未通过
• 同类 P0 / P1 问题连续 2 轮不收敛，需要回退 planning

第二步：并行重跑 — 收集完毕后，一次性并行启动所有失败页：清三件套及 review 图片残留 → 从 P4.NN.01 开始重跑（先生成 prompt，再创建 PageAgent，随后 RUN orchestrator）。

若失败来源只是 review 后人工图审未通过，主 agent 默认不要整页从头重跑，而是保留现有 planning/html，显式改用 PagePatchAgent-N 从 review 重开；只有用户明确要求改结构，或多轮 review 修复仍无效，才退回 html/planning 或整页重跑。若已经触发“同类 P0 / P1 连续 2 轮不收敛”，则不再允许继续打补丁，必须退回 planning 重新冻结预算与骨架。最终放行标准仍与完整 Step 4 完全一致。

单页连续 3 次失败 → 标记 BLOCKED_PAGE_N，先跳过推进其余页，最后集中处理。

BLOCKED 页终态处理：所有非 BLOCKED 页完成后，主 agent 必须： 1. 向用户汇报被 BLOCKED 的页号及每次失败的 Gate 错误摘要 2. 由用户裁决：手动修复（用户自行编辑 HTML）/ 简化重试（降低该页设计复杂度后重跑）/ 跳过该页（从 outline 和最终交付中移除） 3. 禁止静默吞掉 BLOCKED 页继续交付

7.2 跨对话断点恢复

触发：用户说「继续/恢复」并提供 RUN_ID（或默认取最新目录）。

1. update_plan 重建 canonical plan；绑定旧 RUN_ID 2. 里程碑探测（从高到低，第一个 exit=0 为最高自动通过点）：

contract_validator.py delivery-manifest ...                  # P5
planning_validator.py ...                                    # P4 自动下限（恢复后仍需补跑 visual_qa + 看图）
contract_validator.py style ...                              # P3.5
contract_validator.py outline ...                            # P3
contract_validator.py search-brief ... | source-brief ...   # P2
contract_validator.py requirements-interview ...             # P0/P1

3. 从下一未完成 step 继续；前序 Gate 失败则回退重做 4. Step 4：读 outline.txt 确认总页数 → 侦查所有页三件套 + planning_validator + visual_qa → 并行重跑失败页；自动项通过后，主 agent 仍需重新看图确认（旧 session 全部失效） 5. 若 requirements-interview.txt 中记录了人工审计开启，恢复到 Step 4 时还必须把最近可用的 runtime prompt、最终 PNG 和 review/roundX 存档一并纳入断点材料；如果最近一轮 review 后还没有用户明确“通过人工图审”的记录，必须先恢复到这个强制 [WAIT_USER] 卡口，再决定是放行还是走 PagePatchAgent-N

禁止：依赖旧 session、跳过侦查、串行逐页处理、恢复时新建 RUN_ID（除非用户要求全新开始）。

<div align="center"> <img src="assets/logo.png" alt="PPT Agent Logo" width="160" /> <h1>PPT Agent</h1> <p>Software-engineered, multi-agent pipeline for professional presentation generation</p> <p>English | <a href="README.md">中文</a></p>

<p> <a href="#quick-start"><img src="https://img.shields.io/badge/Quick_Start-blue?style=for-the-badge" alt="Quick Start" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/MIT-blue?style=for-the-badge" alt="License" /></a> </p>

<p> <img src="https://img.shields.io/badge/Pipeline-7_Stages-4f7df5?style=flat-square" /> <img src="https://img.shields.io/badge/Styles-8_Themes-ff6b35?style=flat-square" /> <img src="https://img.shields.io/badge/Layouts-10_Types-00d4ff?style=flat-square" /> <img src="https://img.shields.io/badge/Charts-13_Templates-8b5cf6?style=flat-square" /> <img src="https://img.shields.io/badge/Blocks-8_Components-22c55e?style=flat-square" /> <img src="https://img.shields.io/badge/Scripts-15_Tools-f59e0b?style=flat-square" /> </p> </div>

---

PPT Agent is a strict state-machine-driven multi-agent framework that converts a single prompt into a professional PPTX file—eliminating the hallucinations, visual overlaps, and layout instability common in direct LLM generation.

Latest Update

2026-04-09 · v4.1

• Added explicit density contracts across Step 3 density_bias and Step 4 density_label / density_contract, turning slide density into a validated budget instead of a loose prompt preference.
• Upgraded visual_qa.py with dual checks against both planning and html, so the gate now validates structure and decoration budget in addition to screenshot review.
• Added subagent_logger.py to persist PageAgent / PagePatchAgent stage commands and runtime logs, making replay and audit of repair loops much easier.

Highlights

Phase-isolated subagent orchestration: Research, Outline, Style, and Planning each run in fully independent subagent contexts. Cross-phase context contamination is architecturally impossible. Every subagent is created with an explicit SUBAGENT_MODEL parameter; default model fallback is prohibited.

Pixel-sensitive Visual QA loop: After each slide's HTML is built, a low-resolution screenshot is passed back to the model for visual audit. Layout collisions trigger DOM restructuring and CSS rewrites—not margin adjustments.

Stateless checkpoint recovery: No progress state files. After any interruption, the system infers its exact resume point by scanning committed artifact files (outline.txt, style.json, slide-N.png, etc.) on disk.

Data-render boundary isolation: Every slide produces a structured JSON contract, validated by planning_validator.py before entering the HTML render step. Generated static files are strictly guarded by html physical structure detectors to block non-standard skeletons.

Yin-Yang Demarcation Philosophy: A pioneering approach that enforces absolute physical firewalls and baseline grid alignment (the Yin), while granting AI models total supremacy over typography, overlap depth, and negative spaces (the Yang)—crushing the mediocre "Word document" look.

Zero-delay rasterization engine: The built-in Puppeteer engine fully eliminates hardcoded timeouts, hooking directly into event-driven signals (document.fonts.ready and global node listeners). This achieves lightning-fast snapshotting and native SVG parsing with zero dropped fonts or wasted waiting periods.

Dual-engine PPTX export: A PNG rasterization pipeline guarantees cross-platform visual fidelity; an SVG vector pipeline preserves text editability for post-delivery modifications.

Pipeline

P0 Interview  →  P1 Branch Routing
P2A Web Search / P2B Local Material Compression
P3 Narrative Outline  →  P3.5 Global Style Contract
P4 Per-slide Parallel Production (Planning → HTML → Visual QA)
P5 Preview Generation + Dual PPTX Export

Each stage commits its artifact to disk and passes a Gate validator before the next stage begins. Failures roll back only the current step.

Artifact Chain

interview-qa.txt → requirements-interview.txt
  → search.txt + search-brief.txt | source-brief.txt
  → outline.txt → style.json
  → planningN.json → slide-N.html → slide-N.png
  → preview.html → presentation-{png,svg}.pptx → delivery-manifest.json

Showcase

<details> <summary>Click to expand rendered output samples</summary> <div align="center"> <br/> <img src="assets/screenshots/slide1.png" width="48%" /> <img src="assets/screenshots/slide2.png" width="48%" /> <img src="assets/screenshots/slide3.png" width="48%" /> <img src="assets/screenshots/slide4.png" width="48%" /> </div> </details>

Quick Start

PPT Agent runs as a native Agent Skill—no separate deployment required. Trigger the full pipeline by describing your presentation in any Skill-enabled agent environment:

"Generate a 15-page pitch deck on embodied AI trends in 2026. Use a dark tech theme."

All outputs are written to ppt-output/runs/<RUN_ID>/, including a browser-previewable HTML gallery and both PPTX formats.

Repository Layout

ppt-agent-skill/
├── SKILL.md          # Control console: state machine, Gates, recovery rules
├── scripts/          # Runtime scripts (validator / harness / exporter)
├── references/       # On-demand markdown knowledge sources
│   ├── playbooks/    # Phase-specific subagent execution guides
│   ├── styles/       # Theme style specifications
│   ├── layouts/      # Layout resources
│   ├── charts/       # Chart templates
│   └── blocks/       # UI component library
└── assets/

Links

Recognized by and linked to the LINUX DO Community.

License

MIT

<div align="center"> <img src="assets/logo.png" alt="PPT Agent Logo" width="160" /> <h1>PPT Agent</h1> <p>基于软件工程理念的演示文稿全自动生成框架</p> <p><a href="README_EN.md">English</a> | 中文</p>

<p> <a href="#快速开始"><img src="https://img.shields.io/badge/快速开始-blue?style=for-the-badge" alt="Quick Start" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/MIT-blue?style=for-the-badge" alt="License" /></a> </p>

<p> <img src="https://img.shields.io/badge/流水线-7_阶段-4f7df5?style=flat-square" /> <img src="https://img.shields.io/badge/主题风格-8_套-ff6b35?style=flat-square" /> <img src="https://img.shields.io/badge/版式类型-10_种-00d4ff?style=flat-square" /> <img src="https://img.shields.io/badge/图表模板-13_种-8b5cf6?style=flat-square" /> <img src="https://img.shields.io/badge/组件库-8_类-22c55e?style=flat-square" /> <img src="https://img.shields.io/badge/脚本工具-15_个-f59e0b?style=flat-square" /> </p> </div>

---

PPT Agent 以严格的状态机驱动多 Agent 协作，将一句话需求输出为专业级 PPTX 文件，从根源解决传统大模型生成的幻觉、重叠与布局混乱问题。

最近更新

2026-04-09 · v4.1

• 补齐 Step 3 density_bias 与 Step 4 density_label / density_contract 合同，页面密度预算开始成为明确的可校验约束。
• visual_qa.py 新增 planning + html 双层断言，除了看图，也会核对结构与装饰预算。
• 新增 subagent_logger.py，把 PageAgent / PagePatchAgent 的阶段命令与运行日志补齐，断点返工更容易审计与回放。

安装

npx skills add sunbigfly/ppt-agent-skills

核心亮点

Subagent 阶段隔离：Research / Outline / Style / Planning 四大阶段各自运行独立的子代理，Context 不互染。每个子代理创建时强制携带 SUBAGENT_MODEL 参数，禁止走默认回退。

像素级 Visual QA 闭环：每页 HTML 构建后自动截图，由大模型进行视觉审计。检测到布局溢出后，子代理以 DOM + CSS 结构重写的方式消除冲突，而非依赖间距微调。

无状态断点恢复：全流程不依赖任何进度状态文件。中断后通过扫描磁盘上已存在的产物文件（outline.txt / style.json / slide-N.png 等）自动推断恢复点。

数据层与渲染层隔离：每页先生成并由 planning_validator.py 通过校验的 JSON 合同，再驱动 HTML 渲染。针对生成的静态文件拥有 html 级物理结构探测器拦截非标骨架。

《阴阳割线》设计哲学：首创在底层封死绝对的物理安全墙与基准坐标流（阴）的前提下，向 AI 模型全量释放针对 Typography、重叠深度与留白排版的特权（阳），告别传统的平庸公文感。

极速底层光栅化引擎：内置的 Puppeteer 引擎彻底摒弃硬延时，全面接入事件全息钩子 (document.fonts.ready 及全节点监听)，实现 0 丢字体、0 秒白等的极速快门截图与 SVG 源生解析。

双引擎 PPTX 导出：PNG 光栅流保证跨平台 100% 视觉还原；SVG 矢量流保留字体可独立编辑。

工作流

P0 采访   →  P1 分支确认
P2A 联网检索 / P2B 本地资料压缩
P3 叙事大纲  →  P3.5 全局风格锁定
P4 逐页并行生产（Planning → HTML → Visual QA）
P5 Preview + 双 PPTX 导出

每个阶段产物落盘后经 Gate 校验放行，失败只回退当前步，不影响其他页进度。

产物链

interview-qa.txt → requirements-interview.txt
  → search.txt + search-brief.txt | source-brief.txt
  → outline.txt → style.json
  → planningN.json → slide-N.html → slide-N.png
  → preview.html → presentation-{png,svg}.pptx → delivery-manifest.json

效果示例

<details> <summary>点击展开渲染参照</summary> <div align="center"> <br/> <img src="assets/screenshots/slide1.png" width="48%" /> <img src="assets/screenshots/slide2.png" width="48%" /> <img src="assets/screenshots/slide3.png" width="48%" /> <img src="assets/screenshots/slide4.png" width="48%" /> </div> </details>

快速开始

本项目以 Agent Skill 形式运行，无需独立部署。在支持 Skill 的代理环境中直接输入需求即可触发完整流程：

"帮我生成一份关于 2026 年具身智能发展趋势的 15 页路演 Deck，暗色科技风格。"

所有产物输出至 ppt-output/runs/<RUN_ID>/，包含网页预览和双格式 PPTX。

仓库结构

ppt-agent-skill/
├── SKILL.md          # 主控制台：状态机、Gate、恢复规则
├── scripts/          # 执行脚本（validator / harness / exporter）
├── references/       # 按需挂载的 Markdown 知识源
│   ├── playbooks/    # 各阶段子代理执行手册
│   ├── styles/       # 主题风格规范
│   ├── layouts/      # 版式资源
│   ├── charts/       # 图表模板
│   └── blocks/       # UI 组件
└── assets/

友情链接

已链接认可 LINUX DO 社区 的友情链接。

License

MIT

卡片视觉变体（card_style）-- PPTX 演讲设计语言

card_style 决策表：6种视觉存在感 -- filled(实体基底) / transparent(无界悬浮) / outline(虚境描边) / accent(灼焰核心) / glass(雾中幻影) / elevated(悬崖浮岩)。

规则：每页 >=2 种混用打破单调，accent 和 elevated 各最多1个/页。

card_type 与 card_style 的内在共鸣：data_highlight 用 transparent/accent、quote 用 transparent、timeline/diagram 用 transparent（自带骨架不需方块）、comparison 用 outline、data/text/list 用 filled/outline。

极致反差组合：accent+transparent+filled（燃烧vs虚空vs大地）、elevated+outline+transparent（浮岩vs气泡vs幽灵）。

设计哲学：每种变体是一种"空间存在感"

不要把 card_style 理解为"给 div 换个背景色"。在纯正的 PPTX 设计语言中，每种变体代表的是信息在画面中的存在方式和呼吸方式。它决定了这块内容是沉入底层、漂浮中层、还是跃出表面。

6 种变体的灵魂定义

filled -- 沉稳的大地

• 空间存在感：扎实的基底层，是画面中最可靠的信息承载面
• 本质：有可感知边界的实体区域，用主色调填充
• 设计思维：想象一块打磨光滑的大理石台面。它不需要装饰自身，它存在的目的是让上面放置的内容看起来稳定、可信
• 绝对禁止：所有卡片都用 filled --「全是大理石台面」等于「没有主角」

transparent -- 无界之灵

• 空间存在感：幽灵般的存在，内容直接裸露在虚空中呼吸
• 本质：无背景、无边框、无痕迹。内容靠自身的视觉重力独立悬浮
• 设计思维：一句极致的金句、一个 120px 的核心数据 -- 它们不需要被方块收容，它们本身就是画面的视觉锚点。让它们直接"生长"在页面空间中
• 黄金搭配：data_highlight / quote / timeline / diagram -- 这些自带视觉骨架的组件，用方块包裹反而是视觉灾难

outline -- 虚境描边

• 空间存在感：一层若有若无的气泡膜，暗示边界但不制造隔阂
• 本质：用极淡的描边（accent 色 20% 透明度）轻轻勾勒出存在面
• 设计思维：辅助信息、次要数据、补充说明 -- 它们需要有边界感但不能抢占视觉权重。像一个低声附和的旁白

accent -- 灼焰核心

• 空间存在感：画面中唯一燃烧的核心，从背景中灼然跃出
• 本质：用主题强调色渐变填充 + 反色文字，制造不可忽视的视觉爆裂
• 设计思维：这是你一页中最想让观众记住的那一块。它如同聚光灯下独自站立的主角。一页最多 1 个 -- 两个聚光灯等于没有聚光灯
• 视觉张力：与 transparent 卡片放在一起时形成最极致的反差 -- 一个在燃烧，一个在虚空中呼吸

glass -- 雾中幻影

• 空间存在感：半透明的浮冰层，在底图/渐变之上制造朦胧的景深感
• 本质：毛玻璃质感，让底层视觉信息若隐若现地渗透
• 设计思维：当页面有配图或浓烈的渐变背景时，glass 让信息卡片像漂浮在雾气中的告示牌 -- 既能读取信息，又不破坏底层画面的氛围感
• 注意：glass 在 PPTX 导出中 backdrop-filter 可能不被支持，但 HTML 预览时它是最惊艳的层次手段

elevated -- 悬崖浮岩

• 空间存在感：从画面中"顶"出来的浮岛，用阴影创造 Z 轴的物理凸起
• 本质：有实体背景 + 明显的投影 + 微妙的上移偏移，制造"这块内容在物理上更近"的错觉
• 设计思维：页面中最重要的那张卡片，它不仅内容重要，还要在空间上"更近"。一页最多 1 个
• 极致搭配：与 transparent 和 outline 同框时，elevated 像一座孤峰从平原中拔地而起

使用规则（灵动的本质在于反差和混合）

1. 每页至少 2 种 card_style -- 这是制造层次感和灵动呼吸的最低门槛 2. accent 和 elevated 各最多 1 个/页 -- 强调过多 = 没有强调 3. 没有默认值 -- 每张卡片的 card_style 都必须基于它在画面中的角色主动选择 4. 推荐的灵动组合（从张力最强到最柔和）：

• accent + transparent + filled -- 极致反差：燃烧 vs 虚空 vs 大地
• elevated + outline + transparent -- 层次纵深：浮岩 vs 气泡 vs 幽灵
• glass + transparent + accent -- 氛围沉浸：雾中 vs 裸露 vs 灼焰
• filled + outline -- 温和韵律：实体 vs 虚境（最低限度的层次）

与 card_type 的内在共鸣

comparison（对比块）-- 碰撞的擂台

适用数据类型：before_after / pros_cons / scenario_comparison / competitive_matrix。

结构：双面板正面对比，left+right各含label、points[]、accent色设定，底部可选verdict总结句。

设计要点：右侧推荐方案用更强accent色+更大字号+更丰满内容，左侧中性色+克制排版 -- 视觉上引导结论。

推荐 card_style：outline（轻轻分隔两面板）。推荐布局：symmetric。

JSON 结构

{
  "card_type": "comparison",
  "title": "传统方式 vs 新方案",
  "left": {"label": "方案A / 现状", "points": ["维度1", "维度2", "维度3"], "accent": "neutral"},
  "right": {"label": "方案B / 目标", "points": ["维度1", "维度2", "维度3"], "accent": "primary"},
  "verdict": "底部总结句（可选）"
}

设计灵魂

对比的戏剧性

• 左右两面板不应该看起来一模一样只是内容不同 -- 那是最死板的网页前端思维
• 有立场的对比：如果右侧是"推荐方案"，让右面板用更强的 accent 色、更大的字号、更丰满的内容，左面板用中性色 + 克制的排版。视觉上就已经在"引导结论"
• 无立场的对比：两面板用不同的 accent 色（accent-1 vs accent-2），但结构完全对称

灵动手法

• VS 分隔符可以是一个跨越中轴线的圆形 accent 色块 + "VS" 文字，打破左右的物理分割
• 对比维度上下对齐，让观众的视线可以水平扫视对比，制造"逐条PK"的紧张感
• verdict（总结句）跨两面板居中，是"裁判宣布结果"的画龙点睛

每面板 3-5 个对比维度

• 维度太少（< 3）对比不充分，维度太多（> 5）画面拥挤
• 推荐 outline card_style -- 描边轻轻分隔两个面板，不占视觉权重

diagram（图解块）-- 结构的星图

适用数据类型：hierarchies / architecture_diagram / cycle_flow / decision_tree / pyramid_layers / stakeholder_map。

结构：nodes[]节点 + edges[]连线，支持 layered/radial/tree/flowchart 四种布局模式。

实现方式不限：CSS Grid嵌套盒子、内联SVG节点连线、Flexbox+伪元素连接线。

推荐 card_style：transparent（自带视觉骨架，方块包裹会干扰）。推荐布局：single-focus / t-shape。

JSON 结构

{
  "card_type": "diagram",
  "diagram_type": "pyramid | flowchart | hub-spoke | layers | cycle",
  "nodes": [
    {"id": "1", "label": "节点名", "description": "描述（20字内）", "level": 1, "connects_to": ["2","3"]}
  ]
}

子类型的灵动设计思维

实现指引

• 节点间关系用内联 SVG 连线、CSS border、伪元素等均可，选择最佳视觉效果
• 文字标注可用 HTML 元素或 SVG <text>，按场景灵活选择
• 推荐 transparent card_style -- 图解自带节点连线的视觉骨架

image_hero（大图+叠加文字块）-- 画面的沉浸

适用数据类型：image_candidates。全幅图片+叠加文字，制造情感冲击。

结构：需指定 image.usage(hero-background/inline-illustration) + image.placement(full-bleed/left-half) + image.content_description。

推荐 card_style：transparent/glass（大图不需边框束缚，或毛玻璃让文字浮在图上）。

适用页面类型：cover / section 等氛围页。一页最多1个 image_hero。

JSON 结构

{
  "card_type": "image_hero",
  "title": "核心标题（28-44px）",
  "subtitle": "补充说明（80字内，可选）",
  "image_prompt": "配图描述（用于生成配图）",
  "data_highlights": [{"value": "87%", "label": "市场渗透率"}]
}

设计灵魂

图像是主角，文字是浮游

• 配图 object-fit:cover 铺满区域 -- 图片就是画面本身，不是被"放在"某个位置的装饰
• 遮罩层用真实 <div> 半透明渐变（禁止 mask-image）-- 遮罩的目的是让文字在图上可读，而非遮住图片
• 文字层悬浮在图像之上，标题用大号字体保证冲击力，副标题和数据亮点用小号字体保持克制

灵动手法

• 渐隐融合：图片从一侧（如右侧）向另一侧渐隐消失，文字在渐隐区域安身。图文不是分离的两层，而是融为一体的画面
• 底部涌现：图片铺满上方 70%，文字从底部 30% 的渐变暗区中涌现。像电影海报的标题排版
• 角落低语：图片铺满全域，文字极小地蜷缩在某个角落，让图像的叙事力量独占舞台

实现指引

• 图片可用 <img> 标签或 CSS background-image，按场景选择最佳方式
• 渐变遮罩方式不限：真实 div、::before/::after、mask-image 均可，选择最佳视觉效果
• 推荐 transparent card_style -- 大图不需要卡片边框束缚

matrix_chart（象限矩阵块）-- 象限的定位

适用数据类型：matrix_data / swot / competitive_matrix。2x2象限坐标定位。

结构：axes(x_label, y_label) + quadrants[4]({label, items[], color})。

设计要点：每象限独立色块，items用定位圆点标记，适合战略分析和多维评估。

推荐布局：single-focus / primary-secondary。

JSON 结构

{
  "card_type": "matrix_chart",
  "title": "市场定位分析",
  "x_label": "X轴含义（如：执行难度）",
  "y_label": "Y轴含义（如：业务价值）",
  "quadrants": [
    {"position": "top-right", "title": "优先执行", "items": ["项目A","项目B"], "highlight": true},
    {"position": "top-left", "title": "长期投资", "items": ["项目C"], "highlight": false},
    {"position": "bottom-right", "title": "快速见效", "items": ["项目D"], "highlight": false},
    {"position": "bottom-left", "title": "低优先级", "items": ["项目E"], "highlight": false}
  ]
}

设计灵魂

象限的视觉张力

• 十字轴是整个组件的脊柱 -- 不要只是两条灰线。可以用 accent 色极低透明度的粗线（2-3px），让轴线有"存在感"但不抢内容
• Highlight 象限应当从视觉上"跳出来" -- accent 色 15% 透明度背景 + 标题加粗加色 + 项目标签用 accent 胶囊
• 其他象限保持克制 -- 5% 透明度或完全透明，项目标签用 text-secondary

灵动手法

• 不要让四个象限看起来完全对称 -- highlight 象限可以面积微大/色调微浓，制造"视觉重力偏移"
• 轴标签在四端用 12px + letter-spacing:1px，像坐标系的刻度铭牌
• 项目标签用胶囊形圆角药丸，可以在象限内自由散落（非严格排列），暗示"定位"的概念

推荐 transparent card_style + 跨列跨行占据大区域

• 象限图需要足够的空间才能呈现清晰的四象限结构
• 推荐 占据全部可用空间

people（人物组块）-- 面孔的力量

适用数据类型：team_profiles / user_testimonials。

结构：persons[]({name, title, avatar_desc, quote?})，3-6人一组。

设计要点：圆形头像占位+姓名+职位，引述用斜体+小字号。无真实照片时用渐变色块+首字母。

推荐 card_style：filled/outline。推荐布局：symmetric / three-column。

JSON 结构

{
  "card_type": "people",
  "title": "核心团队",
  "members": [
    {"name": "姓名", "title": "职位", "bio": "简介（30字内）", "avatar": true}
  ]
}

设计灵魂

人物展示的灵动手法

• 不要做成通讯录：3-4 人一行等距排列 + 相同尺寸头像 + 相同格式的姓名职位 = 最无聊的人物展示
• 制造主次：如果有核心人物（如 CEO/创始人），让其头像明显大于其他成员（120px vs 80px），位置偏离中心或独占一侧
• 参差排列：人物可以交错排列（非严格等距），某些人物卡片稍高/稍大，制造自然的呼吸感
• 背景故事化：头像背后可以叠加极淡的渐变色块/光晕，暗示每个人物的"个人色彩"

头像处理

• 圆形裁切 (border-radius:50% + overflow:hidden)
• 有头像时：3px accent 色边框，制造"被选中"的感觉
• 无头像时：首字母占位圆（accent 背景 + 白色大号字母）

信息层级

• 姓名 16px 700 居中 -- 最重要
• 职位 13px accent 色 -- 身份标识
• 简介 12px secondary -- 最次要，可以在空间不足时省略

推荐 transparent card_style -- 人物组件靠面孔和排列本身构成视觉结构

quote（引用/金句块）-- 灵魂的锚点

适用数据类型：expert_quotes / user_testimonials。大引号+金句独立悬浮。

结构：quote_text + attribution(name, title, organization)。

设计要点：超大装饰引号(font-size:120px, opacity:0.1)、引文 font-size:28-36px、来源 font-size:14px。

推荐 card_style：transparent（文字靠自身重力撑住画面），1页最多1个 quote 卡。

JSON 结构

{
  "card_type": "quote",
  "content": "引用内容（50-150字）",
  "attribution": {"name": "人名", "title": "职位/机构"},
  "avatar": true
}

设计灵魂

金句的视觉重量

• 引用文字用 24-28px，font-weight:500，line-height:1.6 -- 让每个字都有份量
• 引号装饰用超大 div（80-120px 的 " 字符），accent 色极低透明度（10-15%），像一个巨大的水印衬托在文字背后
• 金句周围需要大量留白 -- 留白就是"请静听"的无声邀请

灵动表达的变奏

• 左侧竖线式：3px accent 竖线贯穿引用文字左侧，来源信息在下方。庄重、权威
• 居中悬浮式：引用文字居中排布，周围大面积留白，巨大引号在背后偏移。诗意、感性
• 偏心张力式：引用文字贴靠画面某一侧，另一侧大面积留白 + 来源人物信息。不对称的灵动

来源信息

• 头像（48px 圆形裁切） + 姓名（16px 700） + 职位（13px secondary）
• 来源信息要明显弱于引用文字 -- 观众先读金句，再看是谁说的

推荐 transparent card_style -- 金句裸露在虚空中，靠文字自身的重力撑住画面

区域展示组件库 -- PPTX 演讲设计语言

复合组件不是"网页 UI 组件"，而是信息叙事的视觉载体。每个组件是一种独特的信息组织方式，承载着特定的演讲节奏和观众情绪。

组件总表

选择指南

灵动组合原则

• 复合组件自带视觉骨架，推荐 transparent card_style -- 方块包裹是画蛇添足
• 一页中复合组件与基础卡片共存时，让复合组件用跨列成为画面的主角，基础卡片退为配角
• 同一页不宜超过 1 个跨列跨行的复合组件，否则两个"主角"会互相抢戏
• 当复合组件用 transparent 裸露在画面中时，它的视觉张力来自组件自身的结构（轴线、节点、面板），不需要额外的卡片边框去"框住"它

timeline（时间线块）-- 时间的河流

适用数据类型：timelines / journey_map / gantt_data。横向/纵向轴线+节点。

结构：orientation(horizontal/vertical) + nodes[]({time, title, description, highlight})。

设计要点：highlight 节点用 accent 实心+更大尺寸，普通节点描边+小尺寸。4-8节点为宜，超过8个拆页。

推荐 card_style：transparent（自带轴线骨架）。推荐布局：l-shape / waterfall。

JSON 结构不变（策划稿中的数据格式）

{
  "card_type": "timeline",
  "orientation": "horizontal | vertical",
  "nodes": [
    {"time": "2020", "title": "事件标题", "description": "简述（30字内）", "highlight": false}
  ]
}

设计灵魂（不是代码模板）

横向时间线的灵动表达

• 轴线不必是死板的直线 -- 可以是微微弯曲的弧线、可以在 highlight 节点处膨胀加粗、可以在末端渐隐消失暗示"未来仍在延伸"
• 节点交替上下排列，制造视觉的呼吸起伏 -- 打破所有节点都在同一水平线上的单调
• Highlight 节点用 accent 实心 + 更大的尺寸，普通节点用描边 + 更小的尺寸，形成明确的主次

纵向时间线的灵动表达

• 左侧时间标签可以用不同透明度/字号，越近的越清晰 -- 制造"时间的景深感"
• 右侧描述区域的内容密度可以不均匀 -- 重要事件给更多空间，次要事件精炼浓缩

实现指引

• 轴线和连线实现方式不限（真实 div、伪元素 ::before/::after、内联 SVG 均可）
• 箭头可用内联 SVG 或 CSS border 三角形
• 4-8 个节点为宜，超过 8 个拆页
• 推荐 transparent card_style -- 时间线自带轴线骨架，不需要方块包裹

对比柱（两项对比）

适用数据类型：before_after / scenario_comparison。两根柱子高度差=结论。

数据需求：2组数据，每组需有 label + value。柱宽 >=40px，间距16px，总宽度自适应容器。

PPTX 友好实现：纯 CSS div 高度百分比（不用 canvas/chart.js），柱体直接用 var(--accent-1) 和 var(--accent-2)。

chart_type: comparison_bar

适用数据：before_after / scenario_comparison。两根柱子高度差=结论，适合2项直接对比，数据需有数值和标签。

结构骨架

<!-- 容器：柱体 + 标签 纵向排列 -->
<div style="display:flex; flex-direction:column; gap:0;">
  <!-- 图表区：两根柱体从底部对齐 -->
  <div style="display:flex; gap:8px; align-items:flex-end; height:80px;">
    <div style="flex:1; border-radius:4px 4px 0 0; background:var(--card-bg-from);
                height:40%;"></div>
    <div style="flex:1; border-radius:4px 4px 0 0; background:var(--accent-1);
                height:80%;"></div>
  </div>
  <!-- 标签区 -->
  <div style="display:flex; gap:8px; margin-top:8px;">
    <span style="flex:1; text-align:center; font-size:12px;
                 color:var(--text-secondary);">标签A</span>
    <span style="flex:1; text-align:center; font-size:12px;
                 color:var(--text-secondary);">标签B</span>
  </div>
</div>

以上代码是结构参考，具体的 height 百分比、gap、容器高度都应根据实际数据和所在卡片空间灵活调整。

灵动指引

• "赢"的那根柱子用 accent 色，"输"的用 card-bg-from（低存在感），让结论一目了然
• 柱子高度差越大，视觉冲击力越强 -- 可以用数据的比例关系放大差异感
• 柱子顶部可以叠加数据数字（用 HTML 元素叠加，不用 SVG text）
• 容器高度根据卡片空间灵活调整，不要永远 80px

漏斗图 Funnel（转化流程）

适用数据类型：funnel_data。逐层收窄色块=转化流失。

数据需求：3-6层，每层需有 label + value + conversion_rate。宽度按比例递减。

PPTX 友好实现：梯形 div（clip-path或border），色彩从深到浅渐变，每层之间留 4px 间隙。

chart_type: funnel

适用数据：funnel_data。逐层收窄色块=转化流失，3-6层为宜，每层需有标签+数值+转化率。

结构原理

• 使用 CSS 宽度递减模拟漏斗（从 100% 逐层按转化率递减）
• 每层是一个矩形色块，内部包含标签 + 数值
• 层间 gap 极小（2-3px），让漏斗有"连续收窄"的视觉效果
• 底部可选的转化率标注行

关键规则

• 每层宽度 = 上一层宽度 * 本层转化率（保持数据诚实）
• 颜色用 accent-1 到 accent-4 逐层递进（章节色彩递进的微观版）
• 文字颜色要确保在对应 accent 色块上可读（深色 accent 用白字，浅色 accent 用背景色反色）
• 最窄层的宽度不要小于 20%（太窄放不下文字）
• 所有文字用 HTML 元素，不用 SVG text

灵动指引

• 层数不必固定为 4 层 -- 3 层漏斗比 6 层更有冲击力（少即是多）
• 如果某一层的流失特别剧烈，可以在该层和下一层之间加一条醒目的转化率标注（如红色高亮 "-58%"）
• 漏斗图最适合放在宽卡片或单一焦点版式中，让宽度递减有足够的视觉空间

KPI 指标卡（数字+趋势箭头+标签）

适用数据类型：metrics / number_highlights / milestone_results。

数据需求：单个核心数字 + 趋势方向(up/down/flat) + 变化百分比 + 标签。

结构：大数字 font-size:40-64px font-weight:800 + SVG三角箭头(16x16) + 变化值 + 标签。

PPTX 友好实现：纯 HTML+CSS，箭头用内联SVG polygon，tabular-nums 对齐数字。

chart_type: kpi

适用数据：metrics / number_highlights / milestone_results。大数字+趋势箭头+标签，单个核心指标的极致冲击力呈现。

结构骨架

<div style="display:flex; align-items:baseline; gap:8px;">
  <span style="font-size:40px; font-weight:800; color:var(--accent-1);
               font-variant-numeric:tabular-nums;">2.4M</span>
  <!-- 上升箭头 SVG -->
  <svg width="16" height="16" viewBox="0 0 16 16">
    <polygon points="8,2 14,10 2,10" fill="#16A34A"/>
  </svg>
  <span style="font-size:14px; color:#16A34A; font-weight:600;">+12.3%</span>
</div>
<div style="font-size:12px; color:var(--text-secondary); margin-top:4px;">月活跃用户数</div>

以上数据为占位示例。数字、箭头方向、百分比、标签都必须替换为实际数据。

关键规则

• 趋势箭头颜色语义：上升=绿色、下降=红色、持平=text-secondary
• 箭头用内联 SVG polygon 或 CSS border 三角形均可
• 数字用 font-variant-numeric: tabular-nums 让等宽数字对齐
• 多个 KPI 并排时，数字大小应一致

灵动指引

• 数字的字号不必永远 40px -- 在大卡片中可以用 56-64px 制造"数据爆炸"的视觉冲击
• 如果有同比/环比两个对比维度，可以把趋势箭头做成两行（同比/环比各一行）
• KPI 卡特别适合搭配 sparkline 折线图 -- 大数字下方加一条极细的趋势线，信息量翻倍

指标行（数字+标签+进度条 组合）

适用数据类型：metrics / kv_pairs。横向一行=一个指标故事。

数据需求：3-5个指标，每个需有 value + label + 可选 progress(0-100)。

结构：flex 横排，每项内部 value(大字号) + label(小字号) + progress-bar(可选)。

辅助组件，可与其他图表搭配使用。

适用数据：metrics / kv_pairs。横向一行=一个指标故事（数字+标签+进度条），适合3-5个并列指标。

结构骨架

<div style="display:flex; align-items:center; gap:12px; margin-bottom:10px;">
  <span style="font-size:24px; font-weight:800; color:var(--accent-1);
               font-variant-numeric:tabular-nums; min-width:60px;">87%</span>
  <div style="flex:1;">
    <div style="font-size:12px; color:var(--text-secondary); margin-bottom:4px;">用户满意度</div>
    <div class="progress-bar"><div class="fill" style="width:87%"></div></div>
  </div>
</div>

以上数据为占位示例。数字、标签、进度条宽度都必须替换为实际数据。

灵动指引

• 多行指标竖排时，可以给每行用不同的 accent 色 -- 或者统一 accent 色但用透明度梯度
• 最重要的指标行可以数字更大、进度条更粗，制造视觉锚点
• 指标行特别适合在 list 类或 data 类卡片中使用，3-5 行刚好

进度条（百分比/完成度）

适用数据类型：progress_tracker。填充长度=完成度。

数据需求：percentage(0-100) + label + 可选 milestone_markers[]。

PPTX 友好实现：外层 div(background:轨道色) + 内层 div(width:N%, background:渐变)，高度 8-12px 圆角。

chart_type: progress_bar

适用数据：progress_tracker。填充长度=完成度，需有百分比数值+标签，适合单指标进度展示。

结构骨架

.progress-bar {
  height: 8px; border-radius: 4px;
  background: var(--card-bg-from);
  overflow: hidden;
}
.progress-bar .fill {
  height: 100%; border-radius: 4px;
  background: linear-gradient(90deg, var(--accent-1), var(--accent-2));
  /* width 用内联 style 设置百分比 */
}

灵动指引

• 进度条的高度不必永远 8px -- 在大面积卡片中可以用 12-16px 制造更强的存在感
• 填充色可以根据数据语义变化：高值用 accent 色（积极），低值用红色（警示）
• 进度条左上方叠加百分比数字可以增强信息量
• 多个进度条竖排列时，可以给每条设置不同的 accent 色 + 递增延迟动画（HTML 预览增强）

雷达图 / 蜘蛛网图（多维度对比）

适用数据类型：score_card。多边形面积=综合实力。

数据需求：3-6个维度，每维度需有 dimension_name + value(0-100)。

PPTX 友好实现：内联 SVG polygon，网格线用 stroke-dasharray，数据多边形用 fill-opacity:0.3。不用 canvas。

chart_type: radar

适用数据：score_card。多边形面积=综合实力，3-6维度为宜，需有维度名+数值。

结构骨架

用 SVG polygon 绘制。适合展示 3-6 个维度的能力/指标对比。

<div style="position:relative; width:200px; height:200px;">
  <svg width="200" height="200" viewBox="0 0 200 200">
    <!-- 网格线（3层同心多边形） -->
    <polygon points="..." fill="none" stroke="var(--card-border)" stroke-width="1"/>
    <!-- 轴线（从中心到每个顶点） -->
    <line x1="100" y1="..." x2="100" y2="..." stroke="var(--card-border)" stroke-width="1"/>
    <!-- 数据区域（半透明填充的多边形） -->
    <polygon points="..."
             fill="var(--accent-1)" opacity="0.15"
             stroke="var(--accent-1)" stroke-width="2"/>
    <!-- 数据点（每个顶点上的圆点） -->
    <circle cx="..." cy="..." r="4" fill="var(--accent-1)"/>
  </svg>
  <!-- 维度标签用 HTML position:absolute 叠加在 SVG 外围（禁止 SVG text） -->
  <span style="position:absolute; top:2px; left:50%; transform:translateX(-50%);
      font-size:11px; color:var(--text-secondary);">维度名</span>
</div>

关键规则

• 维度数限制：3-6 维最佳，6 维以上标签太挤不推荐
• 文字标签可用 HTML 叠加（position:absolute）或 SVG text，按场景灵活选择
• 网格线用极细极淡的 card-border 色（视觉存在但不抢戏）
• 数据多边形用 accent 色 + 15% opacity 填充 + 实色描边

灵动指引

• 雷达图的多边形顶点坐标需要根据维度数和数据值计算（正 N 边形的几何坐标 + 数据比例缩放）
• 容器尺寸根据卡片空间灵活调整（不必永远 200x200），只需保持正方形比例
• 如果需要两组数据对比，可以画两个不同 accent 色的数据多边形叠加
• 标签位置需根据多边形顶点位置微调，确保不被 SVG 图形遮挡

评分指示器（5分制）

适用数据类型：score_card / ranked_list。实心vs空心=已达到vs未达到。

数据需求：score(1-5) + label。

PPTX 友好实现：5个内联SVG圆点(r=6)，实心用 accent 色 fill，空心用 stroke-only + fill:none。

chart_type: rating

适用数据：score_card / ranked_list。实心vs空心=已达到vs未达到，5分制评分直觉呈现。

结构原理

用一行圆点表示评分：实心圆 = 已得分，空心圆 = 未得分。

<div style="display:flex; gap:6px;">
  <!-- 实心圆（已得分） -->
  <div style="width:12px; height:12px; border-radius:50%; background:var(--accent-1);"></div>
  <!-- 空心圆（未得分） -->
  <div style="width:12px; height:12px; border-radius:50%; border:2px solid var(--accent-1); background:transparent;"></div>
</div>

以上为 结构参考。实心/空心数量根据实际评分调整。

灵动指引

• 圆点不一定要用圆形 -- 条状矩形（4px x 12px）也可以表达评分，且视觉更现代
• 圆点大小可以根据卡片空间调整（8-14px 范围内）
• 如果是半分制（如 4.5/5），可以用半实心圆（左半实心右半空心，用 clip-path 或 overlay div 实现）
• 评分指示器特别适合在 list 卡片中紧跟每条项目后面

数据可视化图表 -- PPTX 演讲中的视觉弹药

非默认资料。human-only chart workbook。

>

本文件不作为默认 runtime 主链图表注入资料，不进入默认 prompt 注入链或资源自动加载链。它保留骨架、demo 和讲解性内容，只供人工调试或定向参考时按需查阅。

数据是演讲中最有说服力的武器。但一个孤零零的大数字只是"需要记忆的信息"，而数字 + 可视化是"一秒钟就能理解的洞察"。

>

铁律：每个 data 卡片至少配一个可视化元素。不要只放一个大数字。

选择指南（数据特征 -> 视觉弹药）

灵动法则

图表不是孤岛

• 图表应该与其上方/旁边的文字解读形成紧密的叙事搭配。大数字是"什么"，图表是"怎么样"，解读是"意味着什么"
• 图表的颜色必须使用 CSS 变量（var(--accent-1) 等），不要硬编码色值（风格统一）

图表的视觉重量要服从全局

• 在 accent card_style 的卡片中，图表用白色/浅色调（因为背景深）
• 在 transparent card_style 的卡片中，图表可以用更浓烈的 accent 色（因为背景空旷）
• 图表容器必须有明确的 height（防溢出），但高度值应该根据所在卡片的空间灵活调整，而非永远 80px

图表文件提供什么

• 结构骨架型（ring/kpi/sparkline/comparison-bar/waffle/metric-row/rating/progress-bar）：提供 SVG/HTML 结构参考代码（因为 SVG 计算公式需要精确），但其中的尺寸、数据、颜色都是占位示例，必须根据实际数据重新适配
• 设计原理型（funnel/stacked-bar/timeline/treemap/radar）：只描述结构原理和灵动指引，不提供代码，LLM 基于原理自主构建
• 所有图表都附有视觉灵魂描述和灵动指引，引导 LLM 理解每种图表的叙事角色
• 绝对不要原样复制粘贴 demo 数据

环形百分比（推荐用内联 SVG）

适用数据类型：pie_data / cost_breakdown。圆弧饱满度=占比。

数据需求：value + total（或 percentage），可选 label。

PPTX 友好实现：内联 SVG circle + stroke-dasharray 计算弧长，圆心大数字叠加。不用 canvas。

chart_type: ring

适用数据：pie_data / cost_breakdown。圆弧饱满度=占比，适合单指标百分比，数据需有数值+总量。

结构骨架

<div style="position:relative; width:80px; height:80px;">
  <svg width="80" height="80" viewBox="0 0 80 80">
    <circle cx="40" cy="40" r="32" fill="none"
            stroke="var(--card-bg-from)" stroke-width="10"/>
    <circle cx="40" cy="40" r="32" fill="none"
            stroke="var(--accent-1)" stroke-width="10"
            stroke-dasharray="180.96 201.06" stroke-linecap="round"
            transform="rotate(-90 40 40)"/>
  </svg>
  <!-- 中心文字用 HTML 叠加，不用 SVG text -->
  <div style="position:absolute; top:50%; left:50%; transform:translate(-50%,-50%);
      font-size:16px; font-weight:700; color:var(--text-primary);">90%</div>
</div>

计算公式

dasharray 第一个值 = 2 PI r (百分比/100), 第二个值 = 2 PI * r

以上尺寸为结构参考。容器大小和圆弧半径应根据所在卡片空间灵活调整。

灵动指引

• 圆环的粗细（stroke-width）可以根据卡片大小变化 -- 小卡片用粗环线（8-12），大卡片用细环线（4-6）更优雅
• 未填充弧用 card-bg-from 色（低存在感），已填充弧用 accent 色（高存在感）
• 中心文字不一定只放百分比 -- 可以放核心数值 + 微小标签（如 "15 分钟"）
• 多个环形图并排时，尺寸可以有大小差异（最重要的指标最大），制造视觉层级

Runtime Chart Rules

本文件是主链 runtime 专用的图表规则文档。

>

它只定义图表选择矩阵、信息角色、最小内容合同和失败模式，不提供 HTML/SVG 骨架，不提供占位数据，不提供演示型成品结构。

---

1. 作用定位

• 给 planning 判断何时必须把数据变成可视化。
• 给 HTML 阶段判断图表在页面中的角色、重量和配套支撑信息。
• 保证图表承担阅读任务，而不是退化成页面角落里的装饰附件。

---

2. 图表选择矩阵

---

3. scene_mode 下的优先级

academic

• 优先准确表达变量关系、样本差异、趋势和来源说明。
• 图表必须可读、可解释、可被文本承接。
• 不以装饰感覆盖刻度、标签、条件说明。

report

• 优先让读者快速抓住指标、对比和结论动作。
• 图表和支撑文字需要形成“数据 + 判读 + 下一步”闭环。

pitch

• 优先让图表服务主论点和记忆点。
• 允许更强锚点，但不得把数据细节完全删空。

---

4. 图表最低内容合同

metric 页

• 必须同时表达指标值、指标含义、比较基线或趋势方向。
• 只有一个大数字且没有判读时，视为合同未完成。

comparison 页

• 必须同时表达比较对象、比较维度、差异方向。
• 若差异重要，还必须有一句管理判读或结论句。

trend 页

• 必须同时表达时间轴、变化方向、关键转折或阶段解释。

progress 页

• 必须同时表达当前状态、目标或总量、剩余空间。

---

5. 图表与卡片关系

chart 作为 anchor

• 适用于数据本身就是页面主结论的场景。
• 图表必须占据主要阅读视野，且旁边要有解释该图表的短文本。

chart 作为 support

• 适用于文本锚点已经明确，图表负责补足可信度和趋势感。
• 支撑图表不能小到失去阅读任务。

chart 必须配管理判读的情况

• 多指标并排。
• 存在异常值或反常变化。
• 图表本身不具备明确语义结论时。

---

6. 失败模式

小图角落化

• 触发条件：页面说自己是数据页，但图表只占很小角落。
• 失败征兆：读者先看到装饰，再看到数据。
• 修复顺序：先提高图表权重，再压装饰，再重写支撑说明。

单 KPI 孤岛

• 触发条件：只有一个大数字，没有比较基线、趋势或解释。
• 失败征兆：页面像海报，不像报告页。
• 修复顺序：先补趋势或对照，再补管理判读。

图表无结论承接

• 触发条件：图表存在，但页面没有说明它证明了什么。
• 失败征兆：读者能看到图形，不能得出判断。
• 修复顺序：补一句结论，再补上下文或来源说明。

support 退化成装饰

• 触发条件：support 图表不再承担信息，而只是平衡画面。
• 失败征兆：删掉图表对页面理解没有影响。
• 修复顺序：要么让图表承担明确语义，要么删掉并把空间还给内容。

数据可视化不承担主阅读任务

• 触发条件：数据页的阅读路径主要由背景材质和容器效果构成。
• 失败征兆：页面看起来复杂，但信息吞吐极低。
• 修复顺序：先恢复图表和正文的阅读路径，再处理材质与装饰。

迷你折线图 Sparkline（趋势方向）

适用数据类型：trend_series。一条折线=趋势方向。

数据需求：5-12个数据点序列，不需Y轴标签。适合嵌入卡片内的迷你趋势图。

PPTX 友好实现：内联 SVG polyline，stroke-width:2，无网格线，可选渐变 fill 下方区域。

chart_type: sparkline

适用数据：trend_series。一条折线=趋势方向，不需Y轴刻度，适合嵌入卡片内的迷你趋势图。

结构骨架

<svg width="120" height="40" viewBox="0 0 120 40">
  <!-- 面积填充（趋势线下方的柔和阴影） -->
  <path d="M0,35 L20,28 L40,30 L60,20 L80,15 L100,10 L120,5 L120,40 L0,40 Z"
        fill="var(--accent-1)" opacity="0.1"/>
  <!-- 趋势线 -->
  <polyline points="0,35 20,28 40,30 60,20 80,15 100,10 120,5"
            fill="none" stroke="var(--accent-1)" stroke-width="2" stroke-linecap="round"/>
  <!-- 终点圆点 -->
  <circle cx="120" cy="5" r="3" fill="var(--accent-1)"/>
</svg>

数据点坐标根据实际趋势调整 y 值（高=好 -> y 值小，低=差 -> y 值大）。

灵动指引

• sparkline 最佳用途是紧贴在大数字旁边 -- 数字是"现在"，折线是"怎么到这的"
• 面积填充（path）的 opacity 控制在 0.08-0.15，太浓会抢数字的视觉权重
• 终点圆点让观众知道"当前值在哪"
• 多个 sparkline 并排时（如多指标对比），可以统一 viewBox 尺寸但用不同 accent 色

堆叠条形图（多分类占比对比）

适用数据类型：distribution_data / cost_breakdown。一根柱子内的成分分析。

数据需求：2-5个分类，每分类需有 label + value + color。多根并排时可对比不同类别。

PPTX 友好实现：flex 横排 div，每段宽度按比例，用 var(--accent-N) 配色。

chart_type: stacked_bar

适用数据：distribution_data / cost_breakdown。一根柱子内的成分分析，不同色段=不同组成，适合多类别占比对比。

结构原理

用 CSS flex 横向堆叠色段，每根堆叠条 = 一个数据类别的占比分解。

• 每个色段的 width 百分比 = 该分类在总量中的实际占比
• 色段颜色用 accent-1 到 accent-4 区分分类
• 底部附图例行（色块 + 标签）

关键规则

• 色段宽度必须反映真实数据比例（不能为了好看而调整比例）
• 每根堆叠条上方标注类别名和总值
• 图例用 HTML flex 布局（禁止 SVG text）
• 图例色块尺寸保持一致（视觉整齐）
• 堆叠条高度统一（多根并排时整齐对比）

灵动指引

• 2-3 根堆叠条是最佳数量 -- 太多根观众来不及对比
• 最大的色段放在最左边（视觉锚点，人眼从左往右扫描）
• 如果某个分类的占比特别小（< 5%），考虑合并为"其他"
• 条形高度可以根据卡片空间调整（12-24px 范围内），粗条更有存在感

时间轴 Timeline（水平版）

适用数据类型：timelines。水平节点串联=时间河流。

数据需求：3-8个节点，每节点需有 time + title + 可选 description。

纯图表样式（比 blocks/timeline 更轻量），适合嵌入内容页的时间进度条。

chart_type: timeline

适用数据：timelines。水平节点串联=时间河流，纯图表样式（非 block 版），3-8节点。

结构原理

用 flex 水平排列，适合展示历史沿革、产品迭代、项目里程碑。

• 上层：水平轴线 + 节点圆点（圆点用 accent 色，轴线用极淡色）
• 下层：每个节点的标签（年份/阶段名 + 简要描述）
• 节点间用 flex:1 的线段连接，自动等距

关键规则

• 每个节点的圆点颜色用 accent-1 到 accent-4 递进（章节色彩的微观版）
• 最后一个节点（"当前/未来"）可以稍大，突出"终点"
• 节点圆点用真实 div 元素（border-radius:50%），外加背景色边框与底色区分
• 标签文字用 HTML 元素（禁止 SVG text）

灵动指引

• 节点数以 3-5 个为最佳 -- 太多节点观众记不住
• 轴线粗细极细（1-2px），存在但不抢戏
• "当前"节点可以用脉冲效果（外圈 + 内圈双圈，外圈低 opacity）制造视觉焦点
• 可以交替上下排列标签（奇数节点标签在上，偶数在下），让时间轴在纵向上有呼吸感
• 不必永远是水平的 -- 如果卡片纵向空间充裕，纵向时间轴同样有效

矩形树图 Treemap（层级结构占比）

适用数据类型：distribution_data / cost_breakdown。面积大小=重要性大小。

数据需求：4-12个项目，每项需有 label + value。

PPTX 友好实现：CSS Grid 计算面积占比，每格用不同 accent 色+白色标签。不用 D3。

chart_type: treemap

适用数据：distribution_data / cost_breakdown。面积大小=重要性大小，适合层级结构占比可视化，需有标签+数值。

结构原理

用 CSS Grid 模拟矩形树图，适合展示有层级关系的面积对比。

• 面积比例通过 grid-template-columns 和 grid-template-rows 的 fr 值控制
• 每个块内部放数据标签（百分比/数值 + 类别名）
• 块的颜色用不同 accent 色区分

关键规则

• fr 值必须反映真实数据比例（面积 = 占比，禁止为美观而扭曲比例）
• 最大块跨列或跨行（grid-row: 1 / -1），让它在视觉上明显最大
• 每个块的文字颜色要确保在对应 accent 色块上可读
• 块间 gap 极小（2-3px），让树图有"拼合"的视觉效果

灵动指引

• 3-4 个块是最佳数量 -- 太多块就变成"马赛克"失去了面积对比的冲击力
• 块的圆角和容器一致（统一 border-radius），整体更精致
• 数值标注的字号可以跟随块的大小变化 -- 最大块用最大字号，最小块用最小字号
• 容器高度根据卡片空间灵活调整

点阵图 Waffle Chart（百分比直觉化）

适用数据类型：distribution_data / progress_tracker。100格点阵亮灭=百分比。

数据需求：percentage(0-100)。适合单指标直觉呈现。

PPTX 友好实现：10x10 CSS Grid，每格 8x8px gap:2px，亮格用 accent 色，暗格用 opacity:0.15。

chart_type: waffle

适用数据：distribution_data / progress_tracker。100格点阵亮灭=百分比，最直觉的比例呈现，适合单指标。

结构骨架

<div style="display:grid; grid-template-columns:repeat(10,1fr); gap:3px; width:100px;">
  <!-- 填充点（accent 色） -->
  <div style="width:8px; height:8px; border-radius:2px; background:var(--accent-1);"></div>
  <!-- 重复填充点... -->
  <!-- 空点（card-bg-from 色） -->
  <div style="width:8px; height:8px; border-radius:2px; background:var(--card-bg-from);"></div>
  <!-- 重复空点... -->
</div>

10x10 = 100 格，填充数量 = 百分比值。

以上为结构参考。格点的尺寸和容器宽度应根据卡片空间灵活调整。

灵动指引

• 点阵图比进度条更直觉但占用空间更大 -- 适合在大面积卡片或单一焦点版式中使用
• 格点不一定要正方形 -- 圆形（border-radius:50%）更柔和，方形（border-radius:2px）更科技
• 如果百分比数据是多分类的（如 A=40% B=30% C=30%），可以用 3 种 accent 色的格点，制造"彩色拼图"效果
• 注意管线性能：100 个小元素接近 svg2pptx 的性能边界，考虑用 5x10=50 格（每格代表 2%）来减少元素数

CLI 速查表

按步骤组织的完整命令手册。执行时用实际路径替换 SKILL_DIR / OUTPUT_DIR 等变量。

主 agent 进入 Step 0 前必须读取此文件建立接口认知。禁止对任何脚本跑 --help。

---

Step 0 采访

Prompt 生成（按能力二选一）：

A. Structured UI 模式

python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-interview-structured-ui.md \
  --var TOPIC="用户主题" \
  --var USER_CONTEXT="用户已提供的背景信息" \
  --inject-file INTERVIEW_MODE_MODULE=SKILL_DIR/references/prompts/module-structured-interview-ui.md \
  --inject-file INTERVIEW_CORE=SKILL_DIR/references/prompts/tpl-interview.md \
  --output OUTPUT_DIR/runtime/prompt-interview.md

B. Text Fallback 模式

python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-interview-text-fallback.md \
  --var TOPIC="用户主题" \
  --var USER_CONTEXT="用户已提供的背景信息" \
  --inject-file INTERVIEW_MODE_MODULE=SKILL_DIR/references/prompts/module-text-interview-fallback.md \
  --inject-file INTERVIEW_CORE=SKILL_DIR/references/prompts/tpl-interview.md \
  --output OUTPUT_DIR/runtime/prompt-interview.md

执行规则：

1. 先根据 ## 采访 UI 能力 结论判断当前模式：structured-ui 或 text-fallback 2. Structured UI 模式使用 A 命令；Text Fallback 模式使用 B 命令 3. 两种模式都必须先生成 OUTPUT_DIR/runtime/prompt-interview.md 4. Text Fallback 模式也必须输出分组明确的 Markdown 采访单，不得退化成单行填空或散乱追问 5. 仅当 prompt_harness.py 在 Step 0 发生真实接口故障，并已判定 BLOCKED_SCRIPT_INTERFACE 时，才允许完全绕过 prompt-interview.md 直接发问；覆盖维度不得低于 tpl-interview.md

Gate 校验：

python3 SKILL_DIR/scripts/contract_validator.py interview OUTPUT_DIR/interview-qa.txt
python3 SKILL_DIR/scripts/contract_validator.py requirements-interview OUTPUT_DIR/requirements-interview.txt

---

Step 1 分支确认

主 agent 直接执行（无 subagent）：

1. 识别用户是否已提供现成资料（文件/文本/pptx） 2. 向用户确认分支选择：

• research 分支：联网搜索后制作（→ Step 2A）
• 非 research 分支：基于用户现有资料制作（→ Step 2B）

3. 回填 requirements-interview.txt 中的 分支 字段：

# 用实际分支值替换 BRANCH_VALUE（research 或 非research）
# 直接在文件中找到 "- 分支：" 这一行并更新它

Gate 校验：

python3 SKILL_DIR/scripts/contract_validator.py requirements-interview OUTPUT_DIR/requirements-interview.txt

---

Step 2A Research（渐进式上下文注入）

Subagent 强制：本步产物必须由 ResearchSynth subagent 生成，主 agent 禁止内联生产。

subagent 内部自主按阶段渐进：搜索 -> 数据格式化+整理+自审。

1. 生成阶段 prompt 文件（主 agent 执行）：

# Phase 1: 搜索与搜集
python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-research-synth-phase1.md \
  --var TOPIC="主题" \
  --var REQUIREMENTS_PATH=OUTPUT_DIR/requirements-interview.txt \
  --var SEARCH_OUTPUT=OUTPUT_DIR/search.txt \
  --var TOOLS_AVAILABLE="由主 agent 根据感知结果动态填入可用的检索工具及其功能简述" \
  --var MAX_SEARCH_ROUNDS="主 agent 根据主题复杂度预估：简单2/中等3/高复杂4" \
  --var TARGET_PAGES="目标页数（来自采访）" \
  --inject-file PLAYBOOK=SKILL_DIR/references/playbooks/research-phase1-playbook.md \
  --output OUTPUT_DIR/runtime/prompt-research-phase1.md

# Phase 2: 数据格式化、整理与自审
python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-research-synth-phase2.md \
  --var SEARCH_OUTPUT=OUTPUT_DIR/search.txt \
  --var BRIEF_OUTPUT=OUTPUT_DIR/search-brief.txt \
  --var TARGET_PAGES="目标页数（来自采访）" \
  --inject-file PLAYBOOK=SKILL_DIR/references/playbooks/research-phase2-playbook.md \
  --output OUTPUT_DIR/runtime/prompt-research-phase2.md

2. 生成 orchestrator 调度 prompt：

python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-research-synth-orchestrator.md \
  --var PHASE1_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-research-phase1.md \
  --var PHASE2_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-research-phase2.md \
  --var SEARCH_OUTPUT=OUTPUT_DIR/search.txt \
  --var BRIEF_OUTPUT=OUTPUT_DIR/search-brief.txt \
  --output OUTPUT_DIR/runtime/prompt-research-orchestrator.md

3. 创建 Subagent 并执行：

{{SUBAGENT_NAME}} = ResearchSynth
{{MODEL}}           = SUBAGENT_MODEL
{{THINKING_EFFORT}} = SUBAGENT_THINKING_EFFORT
{{PROMPT_PATH}}   = OUTPUT_DIR/runtime/prompt-research-orchestrator.md

subagent 内部会自主渐进：先读 phase1 完成搜索 -> 再读 phase2 完成格式化+自审 -> FINALIZE

4. Gate 校验（主 agent 复检）：

python3 SKILL_DIR/scripts/contract_validator.py search OUTPUT_DIR/search.txt
python3 SKILL_DIR/scripts/contract_validator.py search-brief OUTPUT_DIR/search-brief.txt

CURRENT_BRIEF_PATH（后续步骤用）= OUTPUT_DIR/search-brief.txt

若 Gate 已过但素材仍明显单薄，回退 Step 2A.01：重新生成 phase1/phase2/orchestrator prompt（扩大 TOOLS_AVAILABLE、查询维度或 MAX_SEARCH_ROUNDS），并新建 ResearchSynth。不要在已 FINALIZE 的旧 session 上继续补搜。

---

Step 2B 非 Search 分支（渐进式上下文注入）

Subagent 强制：本步产物必须由 SourceSynth subagent 生成，主 agent 禁止内联生产。

subagent 内部自主按阶段渐进：资料读取+提炼 -> 质量自审+边界校验。

1. 生成阶段 prompt 文件（主 agent 执行）：

# Phase 1: 资料读取与结构化提炼
python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-source-synth-phase1.md \
  --var REQUIREMENTS_PATH=OUTPUT_DIR/requirements-interview.txt \
  --var SOURCE_INPUT=用户资料路径（目录或文件） \
  --var BRIEF_OUTPUT=OUTPUT_DIR/source-brief.txt \
  --inject-file PLAYBOOK=SKILL_DIR/references/playbooks/source-phase1-playbook.md \
  --output OUTPUT_DIR/runtime/prompt-source-phase1.md

# Phase 2: 质量自审与边界校验
python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-source-synth-phase2.md \
  --var BRIEF_OUTPUT=OUTPUT_DIR/source-brief.txt \
  --var REQUIREMENTS_PATH=OUTPUT_DIR/requirements-interview.txt \
  --inject-file PLAYBOOK=SKILL_DIR/references/playbooks/source-phase2-playbook.md \
  --output OUTPUT_DIR/runtime/prompt-source-phase2.md

2. 生成 orchestrator 调度 prompt：

python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-source-synth-orchestrator.md \
  --var PHASE1_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-source-phase1.md \
  --var PHASE2_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-source-phase2.md \
  --var BRIEF_OUTPUT=OUTPUT_DIR/source-brief.txt \
  --output OUTPUT_DIR/runtime/prompt-source-orchestrator.md

3. 创建 Subagent 并执行：

{{SUBAGENT_NAME}} = SourceSynth
{{MODEL}}           = SUBAGENT_MODEL
{{THINKING_EFFORT}} = SUBAGENT_THINKING_EFFORT
{{PROMPT_PATH}}   = OUTPUT_DIR/runtime/prompt-source-orchestrator.md

subagent 内部会自主渐进：先读 phase1 完成资料提炼 -> 再读 phase2 完成自审 -> FINALIZE

4. Gate 校验（主 agent 复检）：

python3 SKILL_DIR/scripts/contract_validator.py source-brief OUTPUT_DIR/source-brief.txt

CURRENT_BRIEF_PATH（后续步骤用）= OUTPUT_DIR/source-brief.txt

Step 3 大纲（渐进式上下文注入）

Subagent 强制：本步产物必须由 Outline subagent 生成，主 agent 禁止内联生产。

subagent 内部自主按阶段渐进：大纲编写 -> 严格自审+修复。

1. 生成阶段 prompt 文件（主 agent 执行）：

# Phase 1: 大纲编写
python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-outline-phase1.md \
  --var REQUIREMENTS_PATH=OUTPUT_DIR/requirements-interview.txt \
  --var BRIEF_PATH=CURRENT_BRIEF_PATH \
  --var OUTLINE_OUTPUT=OUTPUT_DIR/outline.txt \
  --inject-file PLAYBOOK=SKILL_DIR/references/playbooks/outline-phase1-playbook.md \
  --output OUTPUT_DIR/runtime/prompt-outline-phase1.md

# Phase 2: 严格自审与修复
python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-outline-phase2.md \
  --var OUTLINE_OUTPUT=OUTPUT_DIR/outline.txt \
  --var REQUIREMENTS_PATH=OUTPUT_DIR/requirements-interview.txt \
  --var BRIEF_PATH=CURRENT_BRIEF_PATH \
  --inject-file PLAYBOOK=SKILL_DIR/references/playbooks/outline-phase2-playbook.md \
  --output OUTPUT_DIR/runtime/prompt-outline-phase2.md

2. 生成 orchestrator 调度 prompt：

python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-outline-orchestrator.md \
  --var PHASE1_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-outline-phase1.md \
  --var PHASE2_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-outline-phase2.md \
  --var OUTLINE_OUTPUT=OUTPUT_DIR/outline.txt \
  --output OUTPUT_DIR/runtime/prompt-outline-orchestrator.md

3. 创建 Subagent 并执行：

{{SUBAGENT_NAME}} = Outline
{{MODEL}}           = SUBAGENT_MODEL
{{THINKING_EFFORT}} = SUBAGENT_THINKING_EFFORT
{{PROMPT_PATH}}   = OUTPUT_DIR/runtime/prompt-outline-orchestrator.md

subagent 内部会自主渐进：先读 phase1 完成大纲编写 -> 再读 phase2 完成自审修复 -> FINALIZE

4. Gate 校验（主 agent 复检）：

python3 SKILL_DIR/scripts/contract_validator.py outline OUTPUT_DIR/outline.txt

若 validator 未通过，回退 Step 3.01 重新生成 prompt 并重建新的 Outline subagent；不要复用已 FINALIZE 的旧 session。

---

Step 3.5 风格（渐进式上下文注入）

Subagent 强制：本步产物必须由 Style subagent 生成，主 agent 禁止内联生产。

subagent 内部自主按阶段渐进：约束提炼+风格输出 -> 字段合同自审。

1. 生成阶段 prompt 文件（主 agent 执行）：

# Phase 1: 约束提炼与风格输出
python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-style-phase1.md \
  --var REQUIREMENTS_PATH=OUTPUT_DIR/requirements-interview.txt \
  --var OUTLINE_PATH=OUTPUT_DIR/outline.txt \
  --var SKILL_DIR='$SKILL_DIR' \
  --var STYLE_OUTPUT=OUTPUT_DIR/style.json \
  --inject-file STYLE_RUNTIME_RULES=SKILL_DIR/references/styles/runtime-style-rules.md \
  --inject-file STYLE_PRESET_INDEX=SKILL_DIR/references/styles/runtime-style-palette-index.md \
  --inject-file PLAYBOOK=SKILL_DIR/references/playbooks/style-phase1-playbook.md \
  --output OUTPUT_DIR/runtime/prompt-style-phase1.md

# Phase 2: 字段合同自审
python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-style-phase2.md \
  --var STYLE_OUTPUT=OUTPUT_DIR/style.json \
  --inject-file PLAYBOOK=SKILL_DIR/references/playbooks/style-phase2-playbook.md \
  --output OUTPUT_DIR/runtime/prompt-style-phase2.md

2. 生成 orchestrator 调度 prompt：

python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/tpl-style-orchestrator.md \
  --var PHASE1_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-style-phase1.md \
  --var PHASE2_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-style-phase2.md \
  --var STYLE_OUTPUT=OUTPUT_DIR/style.json \
  --output OUTPUT_DIR/runtime/prompt-style-orchestrator.md

3. 创建 Subagent 并执行：

{{SUBAGENT_NAME}} = Style
{{MODEL}}           = SUBAGENT_MODEL
{{THINKING_EFFORT}} = SUBAGENT_THINKING_EFFORT
{{PROMPT_PATH}}   = OUTPUT_DIR/runtime/prompt-style-orchestrator.md

subagent 内部会自主渐进：先读 phase1 完成风格决策 -> 再读 phase2 完成自审 -> FINALIZE

4. Gate 校验（主 agent 复检）：

python3 SKILL_DIR/scripts/contract_validator.py style OUTPUT_DIR/style.json

若 validator 未通过，回退 Step 3.5.01 重新生成 prompt 并重建新的 Style subagent；不要复用已 FINALIZE 的旧 session。

---

Step 4 单页生产（渐进式上下文注入）

统一执行后端：所有环境统一使用 orchestrator 渐进式披露。

subagent 内部自主按阶段读取 prompt，主 agent 只负责生成 prompt + 创建 subagent + 回收校验。

若用户开启人工审计断点，则主 agent 仍先生成同一套 runtime prompt，再按需要创建阶段型 PageAgent 或 PagePatchAgent-N。

---

4.1 生成 Planning 快照 + 三份阶段 prompt 文件

先生成 planning 阶段会直接用到的 runtime 快照，再依次执行三个 harness 命令（顺序不可调换）：

4A.0 Planning 图片清单快照：

python3 SKILL_DIR/scripts/resource_loader.py images \
  --images-dir OUTPUT_DIR/images \
  --output OUTPUT_DIR/runtime/page-images-N.md

4A.1 Planning 菜单快照：

python3 SKILL_DIR/scripts/resource_loader.py menu \
  --refs-dir SKILL_DIR/references \
  --output OUTPUT_DIR/runtime/page-planning-menu-N.md

4A. Planning prompt：

python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/step4/tpl-page-planning.md \
  --var PAGE_NUM=N \
  --var TOTAL_PAGES=TOTAL \
  --var REQUIREMENTS_PATH=OUTPUT_DIR/requirements-interview.txt \
  --var OUTLINE_PATH=OUTPUT_DIR/outline.txt \
  --var BRIEF_PATH=CURRENT_BRIEF_PATH \
  --var STYLE_PATH=OUTPUT_DIR/style.json \
  --var IMAGES_DIR=OUTPUT_DIR/images \
  --var IMAGE_INVENTORY_PATH=OUTPUT_DIR/runtime/page-images-N.md \
  --var RESOURCE_MENU_PATH=OUTPUT_DIR/runtime/page-planning-menu-N.md \
  --var PLANNING_RUNTIME_COPY_PATH=OUTPUT_DIR/runtime/page-planning-output-N.json \
  --var PLANNING_VALIDATOR_REPORT_PATH=OUTPUT_DIR/runtime/page-planning-validator-N.json \
  --var PLANNING_OUTPUT=OUTPUT_DIR/planning/planningN.json \
  --var SUBAGENT_LOG_PATH=OUTPUT_DIR/runtime/page-agent-N.log \
  --var SUBAGENT_NAME=PageAgent-N \
  --var SKILL_DIR='$SKILL_DIR' \
  --var REFS_DIR='$SKILL_DIR/references' \
  --inject-file PRINCIPLES_CHEATSHEET=SKILL_DIR/references/principles/design-principles-cheatsheet.md \
  --inject-file PLAYBOOK=SKILL_DIR/references/playbooks/step4/page-planning-playbook.md \
  --output OUTPUT_DIR/runtime/prompt-page-planning-N.md

4B. HTML prompt：

python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/step4/tpl-page-html.md \
  --var PAGE_NUM=N \
  --var TOTAL_PAGES=TOTAL \
  --var PLANNING_OUTPUT=OUTPUT_DIR/planning/planningN.json \
  --var SLIDE_OUTPUT=OUTPUT_DIR/slides/slide-N.html \
  --var IMAGES_DIR=OUTPUT_DIR/images \
  --var IMAGE_INVENTORY_PATH=OUTPUT_DIR/runtime/page-images-N.md \
  --var HTML_RESOLVE_PATH=OUTPUT_DIR/runtime/page-html-resolve-N.md \
  --var HTML_RUNTIME_COPY_PATH=OUTPUT_DIR/runtime/page-html-output-N.html \
  --var STYLE_PATH=OUTPUT_DIR/style.json \
  --var SUBAGENT_LOG_PATH=OUTPUT_DIR/runtime/page-agent-N.log \
  --var SUBAGENT_NAME=PageAgent-N \
  --var SKILL_DIR='$SKILL_DIR' \
  --var REFS_DIR='$SKILL_DIR/references' \
  --inject-file PLAYBOOK=SKILL_DIR/references/playbooks/step4/page-html-playbook.md \
  --output OUTPUT_DIR/runtime/prompt-page-html-N.md

4C. Review prompt：

python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/step4/tpl-page-review.md \
  --var PAGE_NUM=N \
  --var TOTAL_PAGES=TOTAL \
  --var PLANNING_OUTPUT=OUTPUT_DIR/planning/planningN.json \
  --var SLIDE_OUTPUT=OUTPUT_DIR/slides/slide-N.html \
  --var PNG_OUTPUT=OUTPUT_DIR/png/slide-N.png \
  --var REVIEW_DIR=OUTPUT_DIR/review \
  --var REVIEW_RUNTIME_PNG_PATH=OUTPUT_DIR/runtime/page-review-output-N.png \
  --var VISUAL_QA_REPORT_PATH=OUTPUT_DIR/runtime/page-review-qa-N.txt \
  --var STYLE_PATH=OUTPUT_DIR/style.json \
  --var SUBAGENT_LOG_PATH=OUTPUT_DIR/runtime/page-agent-N.log \
  --var SUBAGENT_NAME=PageAgent-N \
  --var SKILL_DIR='$SKILL_DIR' \
  --inject-file PRINCIPLES_CHEATSHEET=SKILL_DIR/references/principles/design-principles-cheatsheet.md \
  --inject-file PLAYBOOK=SKILL_DIR/references/playbooks/step4/page-review-playbook.md \
  --inject-file FAILURE_MODES=SKILL_DIR/references/principles/runtime-failure-modes.md \
  --output OUTPUT_DIR/runtime/prompt-page-review-N.md

---

4.2 生成 orchestrator 调度 prompt

python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/step4/tpl-page-orchestrator.md \
  --var PAGE_NUM=N \
  --var TOTAL_PAGES=TOTAL \
  --var PLANNING_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-page-planning-N.md \
  --var HTML_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-page-html-N.md \
  --var REVIEW_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-page-review-N.md \
  --var PLANNING_OUTPUT=OUTPUT_DIR/planning/planningN.json \
  --var SLIDE_OUTPUT=OUTPUT_DIR/slides/slide-N.html \
  --var PNG_OUTPUT=OUTPUT_DIR/png/slide-N.png \
  --var SUBAGENT_LOG_PATH=OUTPUT_DIR/runtime/page-agent-N.log \
  --var SUBAGENT_NAME=PageAgent-N \
  --var SKILL_DIR='$SKILL_DIR' \
  --output OUTPUT_DIR/runtime/prompt-page-orchestrator-N.md

---

4.3 创建 PageAgent-N 并执行

回查《Subagent 操作手册》取出调用模板，替换变量后显式输出到对话再执行：

{{SUBAGENT_NAME}} = PageAgent-N
{{MODEL}}           = SUBAGENT_MODEL
{{THINKING_EFFORT}} = SUBAGENT_THINKING_EFFORT
{{PROMPT_PATH}}   = OUTPUT_DIR/runtime/prompt-page-orchestrator-N.md

subagent 是完全隔离的：它只能看到 orchestrator prompt 的内容，内部按 orchestrator 指示自主渐进读取各阶段 prompt。

subagent 内部会按 orchestrator 的指示自主渐进：

1. 先读 planning prompt -> 完成策划 -> 产出 planningN.json

2. 自主读 html prompt -> 完成设计稿 -> 产出 slide-N.html

3. 自主读 review prompt -> 截图审查修复（保底 2 轮）-> 产出 slide-N.png

4. P0+P1 清零 + visual_qa 通过后 FINALIZE

---

4.3A 可选：人工审计断点 / Step 4 外挂返工

当 Step 0 已记录 manual_audit_mode != off，或用户在运行中明确要求“看某张图 / 用 runtime / 从某节点重开”时，主 agent 应切到这一支。

适用场景：

• 用户想先看 planningN.json 再决定是否继续
• 用户想看当前 slide-N.html 或最终 slide-N.png
• 用户点名某张 review/roundX/slide-N.png
• 用户给出追加 prompt，要求从 planning / html / review 某个节点重新执行

1. 生成外挂 orchestrator prompt：

# 1a. 先生成返工请求并校验
python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/step4/tpl-page-audit-request.md \
  --var PAGE_NUM=N \
  --var START_STAGE=html \
  --var END_STAGE=review \
  --var USER_AUDIT_REQUEST="用户追加的图审或改稿要求（压成一行）" \
  --var TARGET_ASSET_PATH=OUTPUT_DIR/review/round2/slide-N.png \
  --var RUNTIME_CONTEXT_PATHS="OUTPUT_DIR/runtime/prompt-page-html-N.md; OUTPUT_DIR/runtime/prompt-page-review-N.md; OUTPUT_DIR/runtime/page-html-resolve-N.md; OUTPUT_DIR/runtime/page-html-output-N.html" \
  --var PLANNING_OUTPUT=OUTPUT_DIR/planning/planningN.json \
  --var SLIDE_OUTPUT=OUTPUT_DIR/slides/slide-N.html \
  --var PNG_OUTPUT=OUTPUT_DIR/png/slide-N.png \
  --output OUTPUT_DIR/runtime/page-audit-request-N.txt

python3 SKILL_DIR/scripts/contract_validator.py page-audit-request OUTPUT_DIR/runtime/page-audit-request-N.txt --base-dir OUTPUT_DIR

# 1b. 再生成外挂 orchestrator prompt
python3 SKILL_DIR/scripts/prompt_harness.py \
  --template SKILL_DIR/references/prompts/step4/tpl-page-breakpoint-orchestrator.md \
  --var PAGE_NUM=N \
  --var TOTAL_PAGES=TOTAL \
  --var AUDIT_REQUEST_PATH=OUTPUT_DIR/runtime/page-audit-request-N.txt \
  --var START_STAGE=html \
  --var END_STAGE=review \
  --var PLANNING_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-page-planning-N.md \
  --var HTML_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-page-html-N.md \
  --var REVIEW_PROMPT_PATH=OUTPUT_DIR/runtime/prompt-page-review-N.md \
  --var PLANNING_OUTPUT=OUTPUT_DIR/planning/planningN.json \
  --var SLIDE_OUTPUT=OUTPUT_DIR/slides/slide-N.html \
  --var PNG_OUTPUT=OUTPUT_DIR/png/slide-N.png \
  --var SUBAGENT_LOG_PATH=OUTPUT_DIR/runtime/page-patch-agent-N.log \
  --var SUBAGENT_NAME=PagePatchAgent-N \
  --var SKILL_DIR='$SKILL_DIR' \
  --var TARGET_ASSET_PATH=OUTPUT_DIR/review/round2/slide-N.png \
  --var RUNTIME_CONTEXT_PATHS="OUTPUT_DIR/runtime/prompt-page-html-N.md; OUTPUT_DIR/runtime/prompt-page-review-N.md" \
  --var USER_AUDIT_REQUEST="用户追加的图审或改稿要求" \
  --output OUTPUT_DIR/runtime/prompt-page-breakpoint-N.md

若当前没有点名图片或额外 runtime 文件，将 TARGET_ASSET_PATH 或 RUNTIME_CONTEXT_PATHS 填成 none。

2. 创建 `PagePatchAgent-N` 并执行：

{{SUBAGENT_NAME}} = PagePatchAgent-N
{{MODEL}}           = SUBAGENT_MODEL
{{THINKING_EFFORT}} = SUBAGENT_THINKING_EFFORT
{{PROMPT_PATH}}   = OUTPUT_DIR/runtime/prompt-page-breakpoint-N.md

3. 起点规则：

• START_STAGE=planning：重做策划，并继续跑 html -> review
• START_STAGE=html：复用现有 planning，重做 html -> review
• START_STAGE=review：复用现有 planning + html，直接进图审修复并重新截图

4. 终点规则：

• END_STAGE=planning：只产出更新后的 planningN.json，用于中间断点确认
• END_STAGE=html：产出更新后的 slide-N.html，用于中间断点确认
• END_STAGE=review：产出更新后的 slide-N.png，随后仍要进入 4.4 的整页终检

---

4.4 回收 FINALIZE — 主 agent 整页终检

第 1 步：产物存在性 + 合同校验

test -s OUTPUT_DIR/planning/planningN.json
python3 SKILL_DIR/scripts/planning_validator.py OUTPUT_DIR/planning --refs SKILL_DIR/references --page N
test -s OUTPUT_DIR/slides/slide-N.html
test -s OUTPUT_DIR/png/slide-N.png

第 2 步：自动化视觉断言（第一道过滤器）

python3 SKILL_DIR/scripts/visual_qa.py OUTPUT_DIR/png/slide-N.png --planning OUTPUT_DIR/planning/planningN.json --html OUTPUT_DIR/slides/slide-N.html
# exit=1 -> 致命缺陷，直接重跑
# exit=2 -> 品质警告，第 3 步看图时重点关注 WARN 项

第 3 步（核心质量关卡）：主 agent 亲自看截图

这是整个质量体系的最终防线。visual_qa.py 只能抓硬伤，排版质量、内容完整性、视觉和谐度必须由主 agent 亲眼确认。

1. 用当前宿主可用的图像查看能力查看 OUTPUT_DIR/png/slide-N.png 2. 重点关注：

• 文字是否可读、排版是否正常（竖排单字列、文字溢出截断等）
• 卡片内容是否完整（对照 subagent FINALIZE 中的 planning 卡片列表）
• 整体视觉是否和谐（不像毛坯房、不像默认 HTML）
• visual_qa.py 输出的 WARN 项是否确实有问题

3. 如果看到明显问题 -> 标记该页失败，触发重跑

判定规则：若 visual_qa exit=1 或主 agent 看图发现明显问题，则本页视为失败，触发整页重跑。

---

触发条件（任一成立）：

• planningN.json 不存在、为空或 planning_validator.py 不通过
• slide-N.html 不存在或为空
• slide-N.png 不存在或为空
• visual_qa.py 退出码为 1（致命缺陷）
• 主 agent 亲自看图发现明显视觉问题

无论同对话还是跨对话，统一两步走：

第一步：侦查 -- 读 outline.txt 确认总页数，遍历所有页收集失败页列表：

# 对每页 1..N：
test -s OUTPUT_DIR/planning/planningN.json && \
test -s OUTPUT_DIR/slides/slide-N.html && \
test -s OUTPUT_DIR/png/slide-N.png && \
python3 SKILL_DIR/scripts/planning_validator.py OUTPUT_DIR/planning --refs SKILL_DIR/references --page N && \
python3 SKILL_DIR/scripts/visual_qa.py OUTPUT_DIR/png/slide-N.png --planning OUTPUT_DIR/planning/planningN.json --html OUTPUT_DIR/slides/slide-N.html
# 任一 exit!=0 -> 加入失败页列表

自动探测通过后，主 agent 仍需重新看图确认；visual_qa.py 不是人工审美检查的替代品。

第二步：并行重跑 -- 收集完毕，一次性并行启动所有失败页（不串行逐页）：

# 对失败页列表 [N1, N2, ...] 中每页，清理旧产物及可能的 review 图片残留：
python3 -c "import os, glob; [os.remove(p) for p in ['OUTPUT_DIR/planning/planningN.json','OUTPUT_DIR/slides/slide-N.html','OUTPUT_DIR/png/slide-N.png'] + glob.glob('OUTPUT_DIR/review/round*/slide-N.png') if os.path.exists(p)]"
# 从 Step 4 的 prompt 生成阶段开始重跑：先生成 prompt，再创建 PageAgent-N，随后 RUN orchestrator

session 一律视为不可续接（subagent 死亡=上下文全无），整页从 4.1 开始重跑。

跨对话恢复时旧 session 全部失效，逻辑相同。

---

Step 5 导出

执行管线：

# 1. 预览
python3 SKILL_DIR/scripts/html_packager.py OUTPUT_DIR/slides -o OUTPUT_DIR/preview.html

# 2. PNG 管线（与 SVG 并行）
# --scale 3 → 输出 3840x2160 高清 PNG 供 PPT 使用（图审用 0.75 是为省 token，两者目的不同）
python3 SKILL_DIR/scripts/html2png.py OUTPUT_DIR/slides -o OUTPUT_DIR/png --scale 3
python3 SKILL_DIR/scripts/png2pptx.py OUTPUT_DIR/png -o OUTPUT_DIR/presentation-png.pptx

# 3. SVG 管线（与 PNG 并行）
python3 SKILL_DIR/scripts/html2svg.py OUTPUT_DIR/slides -o OUTPUT_DIR/svg
python3 SKILL_DIR/scripts/svg2pptx.py OUTPUT_DIR/svg -o OUTPUT_DIR/presentation-svg.pptx --html-dir OUTPUT_DIR/slides

# 4. 交付清单
# 主 agent 按以下 schema 写入 delivery-manifest.json

delivery-manifest.json 必填 schema：

{
  "run_id": "RUN_ID（与 OUTPUT_DIR 对应）",
  "generated_at": "ISO 8601 时间戳（如 2026-04-01T14:30:00Z）",
  "summary": {
    "total_pages": 页数（正整数）
  },
  "artifacts": {
    "preview_html": "preview.html（相对于 OUTPUT_DIR 的路径）",
    "presentation_png_pptx": "presentation-png.pptx",
    "presentation_svg_pptx": "presentation-svg.pptx"
  },
  "pages": [
    { "page": 1, "planning": "planning/planning1.json", "html": "slides/slide-1.html", "png": "png/slide-1.png" }
  ]
}

run_id、generated_at、artifacts（含三个路径）为 validator 强制校验字段；summary 和 pages 建议填写。

Gate 校验：

python3 SKILL_DIR/scripts/contract_validator.py delivery-manifest OUTPUT_DIR/delivery-manifest.json --base-dir OUTPUT_DIR

---

资源路由

菜单（planning 阶段）：

python3 SKILL_DIR/scripts/resource_loader.py menu \
  --refs-dir SKILL_DIR/references \
  --output OUTPUT_DIR/runtime/page-planning-menu-N.md

解析（html 阶段）：

python3 SKILL_DIR/scripts/resource_loader.py resolve --refs-dir SKILL_DIR/references --planning OUTPUT_DIR/planning/planningN.json

图片清单（planning / html 阶段）：

python3 SKILL_DIR/scripts/resource_loader.py images --images-dir OUTPUT_DIR/images

---

里程碑总验收

python3 SKILL_DIR/scripts/milestone_check.py <stage> --output-dir OUTPUT_DIR

---

合同校验器 contract-type 列表

interview / requirements-interview / search / search-brief / source-brief / outline / style / images / page-review / page-audit-request / delivery-manifest

通用格式：

python3 SKILL_DIR/scripts/contract_validator.py <contract-type> <target-file> [--base-dir OUTPUT_DIR]

---

视觉质量断言

Step 4 回收后的第一道自动过滤器。抓明显硬伤（分辨率、空白、文件损坏等），真正的视觉质量判断由主 agent 亲自看图完成。

单页：

python3 SKILL_DIR/scripts/visual_qa.py OUTPUT_DIR/png/slide-N.png --planning OUTPUT_DIR/planning/planningN.json --html OUTPUT_DIR/slides/slide-N.html

批量：

python3 SKILL_DIR/scripts/visual_qa.py OUTPUT_DIR/png --planning-dir OUTPUT_DIR/planning --html-dir OUTPUT_DIR/slides

退出码：0 = 全通过、1 = FAIL（致命缺陷，必须重跑）、2 = WARN（品质警告，看图复查）

依赖：pip install Pillow

Director Command Runtime Rules

本文件是 Step 4 runtime 主链专用的 director_command 规则文档。

>

它只定义字段职责、写法边界、选择规则和失败模式，不提供示例库，不提供成品镜头脚本。

---

1. 作用定位

• 帮助 planning 把页面角色翻译成可执行的设计指令。
• 让 director_command 提供方向，而不是替 HTML 层写完页面。
• 保证字段之间分工稳定，避免 prose 吞掉空间策略。

---

2. 字段职责

mood

• 说明本页应建立的阅读状态和判断气氛。
• 只描述语义强度和氛围方向，不写营销口号，不写画面细节。

spatial_strategy

• 描述页面骨架、主次区域和重心分布。
• 必须回答锚点在哪里、支撑内容在哪里、留白如何参与结构。
• 不写 HTML、DOM、具体坐标、具体类名。

anchor_treatment

• 描述主锚如何被强调、约束和承托。
• 只写锚点处理原则，不写完整装饰戏法脚本。

techniques

• 只选择真正需要的技法编号。
• 数量应克制；需要说明这些技法如何服务本页任务，而不是堆满编号。

prose

• 负责补充上述字段没有表达完的设计意图。
• 只能解释“为什么这样组织”，不能直接把页面写成成品描述。

---

3. 写法规则

• mood 应短、准、稳定，能被后续 HTML 消费为设计方向。
• spatial_strategy 应围绕结构关系，不围绕表演性语言。
• anchor_treatment 应强调主锚与支撑的关系，不强调夸张表述。
• techniques 应优先少而有效，避免用技法数量替代设计判断。
• prose 必须服从页面合同，不得推翻 layout、card role、content budget。

---

4. 常见 failure modes

prose 写成长相脚本

• 触发条件：prose 直接描述具体成品样貌。
• 失败征兆：HTML 层只剩照抄，没有设计裁量空间。
• 修复顺序：把成品描述回收为结构目标、阅读路径和节奏意图。

spatial_strategy 写成 HTML

• 触发条件：字段中出现 DOM、类名、具体 CSS 或逐元素实现。
• 失败征兆：planning 越权替 design 写实现。
• 修复顺序：删实现细节，只保留结构和重心描述。

mood 变成营销口号

• 触发条件：mood 只剩煽动性语句，没有阅读状态信息。
• 失败征兆：页面调性被抬高，但设计选择没有依据。
• 修复顺序：改写成阅读状态、论证力度、情绪密度的描述。

techniques 堆满但无主次

• 触发条件：技法编号过多且没有对应结构目标。
• 失败征兆：装饰逻辑漂浮，页面执行发散。
• 修复顺序：只保留服务锚点、节奏或信息分组的技法。