# 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](SETUP.md)。

### 手动使用

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

```powershell
# 首稿生成: 示例 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`）

```powershell
# 增量编辑: 移动/改字（需先生成 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`: 高风险操作（删除节点/整页重建/覆盖原文件）需加上此参数确认

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

其中

- `--rollback`: snapshot_id（可用 `--task` 对应的快照列表查看，见下）
- `--task`: 快照所属任务
- `--out-dir`: 恢复目标目录

查看任务快照:

```powershell
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 做确定性执行

```powershell
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](skill/paperframe-ppt/SKILL.md)

## 约定

- 对象命名: `node_<semantic_id>` / `edge_<from>_<to>` / `group_<semantic_id>` / `label_<semantic_id>`
- 所有写操作前创建快照（`snapshots/`），失败可回滚
- 交付前必须真实 PowerPoint 渲染 + 视觉 QA；阻断性问题不得交付
- 高风险操作（整页重建、删除节点、覆盖原文件等）必须向用户确认
- 增量编辑默认保留人工修改；连接线优先粘附到形状连接点，移动节点后跟随重路由