PPTAgent V2

PPTAgent V2 的核心流程是：

1. 先规划：Markdown -> plan draft
2. 再匹配：draft -> scored candidates
3. 人工评审：review bundle -> confirmed plan
4. 最后生成：confirmed plan -> PPTX + QC

另外，当前支持两种生成模式：

• standard：适合自动化联调，允许在 operations 缺失时做模板结构自动构建或文本回填。
• studio：适合 Claude V1 精品链路，要求每页都有完整 operations，否则直接拒绝生成。

环境

• Python 3.11+
• 建议使用项目内虚拟环境

依赖（requirements）

项目依赖写在 requirements.txt，当前核心依赖是 python-pptx。

source .venv/bin/activate
pip install -r requirements.txt

如果你在编辑器里看到 import pptx 提示不可解析，通常是 VS Code 解释器没有切到 .venv，切换到项目虚拟环境即可。

分步命令

1) 生成草案与候选

python scripts/build_plan.py input/基础篇.md
python scripts/match_templates.py input/基础篇_plan_draft.json
python scripts/export_review_bundle.py input/基础篇_plan_draft_scored.json

输出示例：

• input/基础篇_plan_draft.json
• input/基础篇_plan_draft_scored.json
• input/基础篇_review_bundle.json

2) 人工评审并导出 confirmed

• 打开 review/index.html
• 加载 input/基础篇_review_bundle.json
• 逐页调整后导出 基础篇_plan_confirmed.json
• 将导出的文件放到 input/ 目录

3) 从 confirmed 生成并执行 QC

python scripts/generate_from_confirmed_plan.py input/基础篇_plan_confirmed.json
python scripts/run_qc.py input/基础篇_plan_confirmed.json --pptx output/基础篇_模板匹配生成.pptx

说明：--pptx 参数建议与 confirmed plan 里的 output_file 保持一致。

输出示例：

• output/基础篇_模板匹配生成.pptx
• output/基础篇_qc_report.json

流水脚本（推荐）

新增了统一入口：scripts/full_pipeline.py

仅准备评审数据

python scripts/full_pipeline.py input/基础篇.md --prepare-only

仅完成生成与 QC（需要 confirmed）

python scripts/full_pipeline.py --finalize-only --confirmed input/基础篇_plan_confirmed.json

精品模式生成（严格要求完整 operations）

python scripts/generate_from_confirmed_plan.py input/基础篇_plan_confirmed.json --mode studio

联调模式（自动批准，不经过人工）

python scripts/full_pipeline.py input/基础篇.md --auto-approve

说明：--auto-approve 只用于流水线联调，不建议用于正式产出。

Qwen Authoring（可选增强）

如果你希望在人工评审前，先让 Qwen 根据“已选模板 + 模板真实 shape 槽位”生成一版更贴模板的文案和 operations 草案，可以使用：

python scripts/enrich_review_bundle.py input/基础篇_review_bundle.json --dry-run

这会先输出带模板上下文和 prompt 预览的 review bundle，不调用 API，适合联调。

配置好环境变量后：

export SILICONFLOW_API_KEY=<你的硅基流动 API Key>
export SILICONFLOW_API_URL=https://api.siliconflow.cn/v1/chat/completions
export SILICONFLOW_MODEL=Qwen/Qwen3.5-27B
python scripts/enrich_review_bundle.py input/基础篇_review_bundle.json

项目内也兼容以下变量名：

export QWEN_API_KEY=<你的硅基流动 API Key>
export QWEN_API_URL=https://api.siliconflow.cn/v1/chat/completions
export QWEN_MODEL=Qwen/Qwen3.5-27B

也可以直接走流水线：

python scripts/full_pipeline.py input/基础篇.md --prepare-only --enrich-qwen
python scripts/full_pipeline.py --finalize-only --confirmed input/基础篇_plan_confirmed.json --generation-mode studio

说明：

• 当前默认 provider 已切到硅基流动；未显式设置 URL 时，会默认使用 https://api.siliconflow.cn/v1/chat/completions。
• 当前默认模型已设为 Qwen/Qwen3.5-27B；未显式设置模型时会直接使用它。
• --qwen-dry-run 可在不联网时先验证 prompt 和模板槽位分析。

门禁说明

• scripts/generate_from_confirmed_plan.py 会强制要求 confirmed plan。
• 若输入文件缺少 review_summary 或 slides[].review_status，会拒绝生成。
• 若存在未批准页面，也会拒绝生成。

质量报告说明

QC 报告按页输出：

• pass: 通过
• warn: 有风险（可人工判断）
• fail: 阻塞问题（建议修复后再生成）

端到端生成流程（数据流）

下面是当前 V2 的真实执行链路：

1. Markdown 解析与叙事规划（Phase 1）

• 输入：input/<topic>.md
• 处理：scripts/build_plan.py -> src/pptagent/planner.py
• 输出：input/<topic>_plan_draft.json
• 内容：deck_strategy、每页 outline、content_type、布局偏好。

1. 模板检索与混合评分（Phase 2）

• 输入：*_plan_draft.json
• 处理：scripts/match_templates.py -> src/pptagent/retrieval.py + src/pptagent/scoring.py + src/pptagent/model_judge.py
• 输出：input/<topic>_plan_draft_scored.json
• 内容：每页 top-k candidates、selected_match、评分拆解与主题锚点。

1. 评审包导出（Phase 3）

• 输入：*_plan_draft_scored.json
• 处理：scripts/export_review_bundle.py
• 输出：input/<topic>_review_bundle.json
• 内容：评审 UI 所需字段（截图路径、文案、候选、当前选择、评审状态）。

1. 人工评审与冻结确认计划（Phase 3 gate）

• 工具：review/index.html + review/app.js
• 动作：逐页 approve / swap / edit / lock-style，并可查看模型给出的布局填充建议。
• 输出：input/<topic>_plan_confirmed.json
• 关键：生成前必须是 confirmed 计划。

1. 严格门禁生成（Phase 4）

• 输入：*_plan_confirmed.json
• 处理：scripts/generate_from_confirmed_plan.py -> src/pptagent/executor.py
• 门禁：
  • 缺 review_summary 或 slides[].review_status 会拒绝。
  • 任一页非 approved 会拒绝。
  • studio 模式下，任一页缺少 operations 会拒绝。
  • 当前执行器默认只支持单模板 confirmed plan。
• 输出：output/<topic>.pptx（或 confirmed 中指定的 output_file）。

1. 质量检查与报告（Phase 5）

• 输入：confirmed plan + 生成后的 PPTX（可选）
• 处理：scripts/run_qc.py -> src/pptagent/qc.py
• 输出：output/<topic>_qc_report.json
• 检查：标题/要点长度风险、缺失字段、审批状态、相邻页风格跳变、页数一致性。