PaperFrame PPT Agent

面向科研人员的 PowerPoint 原生框架图生成与编辑 Agent。输入论文/方法描述，输出可在 PowerPoint 中继续手工编辑的原生框架图（模块、文字、箭头、分组均为原生对象），支持自然语言增量修改、人工修改保护、快照回滚和真实渲染验收。

使用场景

小修小改（改字、改色、拖动）在 PowerPoint 里直接做最快；从论文出图、转静态图为原生对象、多步连续编辑则用上面的命令或 MCP（见下文「交付给消费 Agent」）让 AI 连续完成。每次写操作前系统会自动创建快照（snapshots/），所以总能回到任意修改前版本。

Related MCP server: pptx-mcp-server

快速开始

环境搭建

独立 conda 环境，安装步骤见 SETUP.md。

手动使用

# 激活环境
conda activate paperframe
# 烟雾测试（COM 最小闭环）
python scripts\smoke_test.py

# 首稿生成: 示例 Transformer 架构图
python scripts\generate_framework.py --spec fixtures\transformer_pipeline.json --task transformer --out-dir projects\transformer

其中

• --spec: framework_spec JSON 文件路径（结构规格，见 fixtures/ 示例）

• --task: 任务 id，作为输出文件名前缀（默认取 spec.project_id）

• --out-dir: 输出目录（生成 <task>.pptx / <task>_preview.png / <task>.spec.json / <task>.run.json）

# 增量编辑: 移动/改字（需先生成 edit_plan，见 fixtures\edit_move_decoder.json）
python scripts\edit_framework.py --pptx projects\transformer\transformer.pptx --plan fixtures\edit_move_decoder.json `
    --task transformer-edit --out-dir projects\transformer-edit --spec projects\transformer\transformer.spec.json

其中

• --pptx: 目标 .pptx 绝对路径

• --plan: edit_plan JSON 文件路径（操作计划，见 fixtures/ 示例）

• --task: 任务 id，用于快照与输出命名

• --out-dir: 新版本输出目录（保存为 vNNN，不覆盖原文件）

• --spec: 生成时的 spec 文件（可选，供结构 QA 对比）

• --confirm: 高风险操作（删除节点/整页重建/覆盖原文件）需加上此参数确认

# 回滚
python scripts\edit_framework.py --rollback <snapshot_id> --task transformer-edit --out-dir projects\transformer-edit\restored

其中

• --rollback: snapshot_id（可用 --task 对应的快照列表查看，见下）

• --task: 快照所属任务

• --out-dir: 恢复目标目录

查看任务快照:

python -m paperframe.cli snapshots --task transformer-edit

无 PowerPoint 的环境用 --no-export 跳过预览导出与视觉 QA。

Agent自动化(MCP + Skill)

本项目可交付给agent 直接使用: LLM 做语义规划（产出 framework_spec.json / edit_plan.json），MCP server 做确定性执行

conda activate paperframe
python -m pip install -e .           # 安装包 + paperframe / paperframe-mcp 命令
python -m paperframe.mcp_server      # 启动 MCP server（stdio，默认）
# 远端: python -m paperframe.mcp_server --transport streamable-http --host 127.0.0.1 --port 8765

• 工具（9 个）:

  • generate: 从 spec 生成原生 PPTX + QA

  • edit: 增量编辑（快照→原子操作→新版本 vNNN）

  • inspect: 感知人工改动 / 同步当前状态回 spec

  • validate: 结构 QA（校验 PPTX 与 spec 一致性）

  • import_pptx: 反向导入任意 PPTX 为 spec

  • validate_spec: 校验 framework_spec JSON（语义规划后自检）

  • validate_plan: 校验 edit_plan JSON（编辑计划自检）

  • rollback: 从快照恢复文件

  • list_snapshots: 列出任务的全部快照

• 资源（8 个）:

  • paperframe://schema/framework_spec: framework_spec JSON Schema

  • paperframe://schema/edit_plan: edit_plan JSON Schema

  • paperframe://design_tokens: 默认样式令牌（字体/配色/线型）

  • paperframe://prompt/planner: 语义规划 prompt（论文→spec）

  • paperframe://prompt/edit_plan: 增量编辑 prompt（自然语言→edit_plan）

  • paperframe://skill: PaperFrame 使用总览（触发/路由/门槛/交付物）

  • paperframe://templates/components: framework_spec 组件模板库（节点/边/分组写法）

  • paperframe://templates/edit_ops: edit_plan 操作模板库（22 个 op 写法）

• 消费 agent 的触发/路由/门槛说明见 skill/paperframe-ppt/SKILL.md

约定

• 对象命名: node_<semantic_id> / edge_<from>_<to> / group_<semantic_id> / label_<semantic_id>

• 所有写操作前创建快照（snapshots/），失败可回滚

• 交付前必须真实 PowerPoint 渲染 + 视觉 QA；阻断性问题不得交付

• 高风险操作（整页重建、删除节点、覆盖原文件等）必须向用户确认

• 增量编辑默认保留人工修改；连接线优先粘附到形状连接点，移动节点后跟随重路由