PaperFrame PPT Agent

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

使用场景

情景	推荐做法
论文方法章节刚写完，想要一张能放进论文、且每个模块还能继续编辑的架构图	1) 把方法描述整理成 framework_spec.json（可参考 fixtures/transformer_pipeline.json，或让 AI 先帮你规划好结构）<br>2) python scripts\generate_framework.py --spec <spec.json> --task myfig --out-dir projects\myfig<br>3) 打开 projects\myfig\myfig.pptx，在 PowerPoint 里直接拖动、改字、改色
手头有手绘草图、PDF 截图或别的工具导出的静态图，想在 PowerPoint 里逐块编辑，而不是整张当图片	1) 先把图做成一张 sketch.pptx（哪怕是很糙的原生对象）<br>2) 反向导入成 spec: python -m paperframe.cli import --pptx sketch.pptx --out sketch.spec.json<br>3) 基于 spec 重新生成: python scripts\generate_framework.py --spec sketch.spec.json --task sketch --out-dir projects\sketch<br>4) 打开结果逐模块调整
图基本满意，只有一个模块的名字写错了或想换个颜色，只想改这一处	直接在 PowerPoint 里选中该模块改文字、改填充色即可——生成的就是原生对象，秒级完成
想调整两个模块的位置或顺序，希望箭头跟着模块走，不断开、不穿乱	直接在 PowerPoint 里拖动模块，粘附到形状连接点的连接线会自动重路由
在 PowerPoint 里手工挪过模块、改过标题，还想让 AI 继续加一个 Loss 模块，最怕手工调整被冲掉	1) 先感知当前状态: python scripts\inspect_framework.py --pptx <current.pptx> --spec <myfig.spec.json>，确认哪些是人工改动<br>2) 写只含「加 Loss 模块」的增量 edit_plan<br>3) edit 执行后再次 inspect 复查，未受指令影响的组件（含你的手工调整）保持原样
连续改了好几版，最新一版不满意，想退回某个修改前的状态	1) 列出快照: python -m paperframe.cli snapshots --task myfig-edit<br>2) 恢复: python scripts\edit_framework.py --rollback <snapshot_id> --task myfig-edit --out-dir projects\myfig-restored

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

快速开始

环境搭建

独立 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；阻断性问题不得交付
• 高风险操作（整页重建、删除节点、覆盖原文件等）必须向用户确认
• 增量编辑默认保留人工修改；连接线优先粘附到形状连接点，移动节点后跟随重路由