# 使用指南

安装与升级见 [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 工程整理为可版本管理、可多人按页协作的源码项目，
保存数据、讲稿、素材、模板快照和构建入口，并验证移动后重建。
```

## 选择模板与制作页面

命令中的 `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 不授予批量制作、提交、推送或发布权限。