# 使用指南

安装与升级见 [INSTALL.md](INSTALL.md)。开始任务时提供内容、用途、template 来源和 theme；沿用已确认选择。一次激活一个 template 和其中一个 theme，页面再选择 layout。没有模板来源时 Agent 会询问，不会猜一个全局默认模板。

可以直接这样请求：

```text
使用 ppt-template-workflow。模板 manifest：/path/to/template/manifest.json，
theme：THEME。根据附件制作可编辑 PPT，先设计并审阅第一页，通过后再继续。
```

```text
使用 ppt-template-workflow。沿用本工程的模板与主题，
把这份数据做成对比图表，保留真实数据、单位和来源，先给我审阅当前页。
```

```text
将这个 PPT 工程整理为可版本管理、可多人按页协作的源码项目，
保存数据、讲稿、素材、模板快照和构建入口，并验证移动后重建。
```

## 报告内容与制作的衔接

需要设计主线、调整章节顺序或分配逐页内容时，可先用独立 `report-structure` Skill，得到报告内容方案；用户实例和提炼规则由它维护。`ppt-template-workflow@0.9.0` 接收 `report-structure@0.4.0` 的逐页讲解 PDF、可编辑正文源和执行选择，也继续接收普通大纲或用户自己的逐页说明；两个 Skill 均可独立使用。将方案和已有页 ID 交给本 Skill，按[内容交接](references/content-handoff.md)制作，不重复重组已确认内容。

PDF 用于阅读讲解，制作从正文源取得屏幕文本、公式和必需图示；同一 PPT 页可跨数个 PDF 物理页，按稳定页 ID 对应。讲者分析和审阅说明不自动变成屏幕正文。内容改变时同步其版本、讲稿、必要分析及当前 PDF，避免以旧稿或旧确认覆盖新内容。

当前页交代最终信息、必要前提、页内推进、关键推理／推导步骤、证据与结论的对应，以及正文／讲稿／附录分配。按任务在已有说明中表达即可，无须增加统一必填表或逐页时间预算。制作方检查实际读序、信息负担和视觉对应；选图建议不扩充七类原生图表组件的技术能力。

仅调整一页的视觉或直接制作已有大纲时，可独立使用本 Skill。容量不足时反馈受影响页面和具体内容选项，由内容方案处理拆分与取舍；不改固定字号／间距，也不把关键限定藏入讲稿。逻辑审阅、页面制作及实际应用验收分别报告。

## 一次确认执行方式并沿用

接收已有执行表，沿用审阅分工与预算、修改后独立复核、逐页／按块制作、ImageGen 范围和替代方式。未确定的关键选择在开始相关工作前合并询问一次，后续授权页和约定范围内的必要修订不重复问。用户不愿并行不等于允许串行子 Agent；不用 ImageGen 也不等于已选择跳过草案或改为主 Agent 文字构图，具体替代须由用户决定。

启用 ImageGen 布局草案时，用真实所选模板／theme 的画面作参考，展示主要元素大致位置、分组、层级和读序；按反馈修改后实现获准页。模板固定 UI、几何与间距继续由共享实现决定。将已确认偏好、适用范围和参考画面记在现有工程说明／审阅材料中，仅复用于相应后续页。

修改后默认按一次确认的配置交未参与该部分修改的干净上下文 Agent 复核。提供当前稿、目标、受众、标准、原始依据和必要前文；排除作者自评、预期结论与引导说明，先独立判断再对照旧问题。用户明确改为主 Agent 自查或跳过时如实标明，后续实质修改按原配置复核受影响范围。详见[执行与复核](references/execution-and-review.md)。

例如，可在已有内容方案上补充：

```text
沿用已确认执行表：逐页制作；ImageGen 草案跳过，主 Agent 以文字构图沟通；
修改后由独立 Agent 复核。当前只授权 page-02。
请读取讲解 PDF 和正文源，以正文源中的 PPT 内容及必需图示制作当前页，
沿用本报告已确认的布局偏好，不重复询问已决定的工具方式。
```

页面构图遵守[HTML 边界](references/visual-design.md#page-composition-and-html-boundary)：禁止 HTML／DOM／CSS 页面排版及截图、打印、转换绕行，HTML 中仅可运行可视化本身及必要容器。周边标题、正文、分栏和页面 UI 使用允许的原生／SVG 方式。来源、范围、口径和引用可用小字，直接影响核心判断的条件在相关主体中说明；修正正文优先于叠加免责声明。

## 选择模板与制作页面

命令中的 `PPT_PYTHON` 指向准备好的 venv Python，`PPT_SKILL` 指向安装目录。两者是本机命令变量，不写入可移植工程源码。Windows 的 venv Python 在 `Scripts/python.exe`，其他平台在 `bin/python`。

```sh
PPT_PYTHON=/path/to/venv/bin/python
PPT_SKILL=/path/to/installed/ppt-template-workflow
"$PPT_PYTHON" "$PPT_SKILL/scripts/template_ref.py" list --catalog /path/to/catalog.json
"$PPT_PYTHON" "$PPT_SKILL/scripts/template_ref.py" inspect --manifest /path/to/template/manifest.json
"$PPT_PYTHON" "$PPT_SKILL/scripts/template_ref.py" export-style \
  --manifest /path/to/template/manifest.json --theme THEME --layout LAYOUT
"$PPT_PYTHON" "$PPT_SKILL/scripts/template_ref.py" resolve \
  --manifest /path/to/template/manifest.json --theme THEME --layout LAYOUT \
  --route native --workflow interactive-page --out /path/to/project/template-selection.json
```

Agent 读取导出的调色板、字体、网格、素材 paint 契约、结构和版式容量，按模板槽位制作当前页 SVG。页面库存在时先检查其设计思路、实现方法和预览，再适配；参考页不改变模板几何和审阅顺序。`resolve` 只绑定完整的正式模板，提案可以 `inspect`／`export-style`，不能绕过发行状态制作。

制作与重建均遵循[文字与容器硬约束](references/text-and-containers.md)。段落优先一个原生文本框；确需拆分时共用完整文本、整体边界、阅读顺序和排版实现，不逐行维护。关键解释、流程条件／时机、结论与影响解释的限定不得藏在小号灰字。容器中的不同文字角色需用字号、字重和／或颜色区分；同类容器由共享实现计算内部位置，作者只填内容、选择已声明变体并放置整体容器。

段落还须遵守标点避头尾；检查每一行，包括末行，禁止单字或被标点包围的单字独占一行。重新排整段文字来消除问题，保持完整内容、逻辑文本块和声明字号。纯文本可使用`paragraph_layout.py`配合实际字体测量；复杂文字与PowerPoint重新换行的结果仍按实际画面检查。

间距由template与共享recipe固定，调用者不传数字、阈值、偏移或临时变体。检查文字与边框、标题与正文、相邻内容和公式周围的固定关系，过窄与过宽均拒绝。多段文字用完整段落数组，段内行距与段间距分别控制；`text_block.py`读取固定padding与paragraph_gap并自动记录关系，`layout_spacing.py`按role精确核对。几何检查不能替代实际字形与画面审阅，见[固定间距](references/spacing.md)。

含数学内容时读取[数学制作](references/mathematics.md)，声明专用数学字体。`math_component.py`与原生导出包装器支持结构化表达式的Office Math输出；字体、字号角色和颜色由template或显式工程样式提供。它不是通用LaTeX解析器；源SVG的线性兼容文字也不等于复杂公式预览。目标应用的渲染和实际公式编辑分别验证。

```sh
"$PPT_PYTHON" "$PPT_SKILL/scripts/native_export.py" \
  --manifest /path/to/template/manifest.json --theme THEME \
  --source /path/to/project/pages/page.svg --source-root /path/to/project \
  --output /path/to/project/exports/review.pptx
```

输出文件保护既有内容，修订时使用新路径。原生页面保留 Master／Layout／占位符；图表保留数据缓存和内嵌工作簿，表格保留单元格。图标按 SVG＋paint 的 palette／fixed／structural 通道处理。图表和表格示例位于 `assets/components/`，用法见[图表](references/charts.md)和[基础组件](references/components.md)。

## 工程和协作

需要可重建工程时，按[工程接口](references/project-workspace.md)执行 `ppt_project.py init`，为已定稿 SVG 准备 `prepare_native_project.py`，添加页面、讲稿及显式数据绑定，再 `lock`／`check`／`build`／`pack`。初始化只是骨架，不能把空工程当作完成的 PPT。

协作时负责人固定页 ID、页序、风格和共用资源，参与者只修改分配的页面目录；负责人串行整合共享内容和锁。详见[页面分工](references/page-collaboration.md)。

## 交付标准

先核对当前页内容、布局、字体和实际预览，再报告原生对象、结构与应用证据。引用与哈希、原生结构、实际渲染、PowerPoint 编辑、投影和其他设备分别验证。无宿主能力时完成独立部分并说明具体缺口。逐页审阅、原生路线和用户已定选择优先；工程化或安装 Skill 不授予批量制作、提交、推送或发布权限。