| name | ppt:refine |
| description | 对 ppt:create 已生成的 PPT 做自然语言追加调整 (必须有 .ppt-workdir/slide-plan.yaml). 当用户提到"调整 PPT""修改 PPT""ppt:refine""PPT 微调"时触发. |
| argument-hint | <pptx 路径> <调整指令> |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion |
| version | 3.9.3 |
PPT:Refine — 自然语言追加调整
v3.4.0 简化说明 + 适用范围明示
仅支持有 <pptx目录>/.ppt-workdir/slide-plan.yaml 的 deck (即 ppt:create 生成的). 外部 PPTX (没有 slide-plan.yaml 的) 不支持 — v3.3.x 文档承诺"用 python-pptx 逆向分析推断 visual_type"实际从未实现, LLM 现场写逆向解析逻辑也不可靠. 外部 PPTX 请用 /ppt:create 重新生成.
v3.4.0 同时删除 Agent-V 和 Agent-R LLM 自审 (无 ground truth, 增加 token 成本不增加质量), 改为 deterministic 校验 (validate_plan.py) + 可选 /ppt:taste 评审.
路径约定
<plugin-root> = skills/refine/ 的两级父目录. 执行 bash 前替换实际路径.
参数解析
从 $ARGUMENTS 中解析:
- PPTX 文件路径 (必需): 要调整的 .pptx 文件
- 调整指令 (必需): 自然语言描述的修改需求
示例: /ppt:refine output/report.pptx 第3页换成左图右文布局, 标题改为行动标题
执行流程
Step 0: 前置检查
test -f <pptx目录>/.ppt-workdir/slide-plan.yaml || { echo "未找到 slide-plan.yaml. ppt:refine 仅支持 ppt:create 生成的 deck. 外部 PPTX 请用 /ppt:create 重新生成"; exit 1; }
未通过此检查时, 立即 AskUserQuestion 给用户:
- 选项 1: "用 /ppt:create 重新生成" (推荐)
- 选项 2: "我手动改 PPTX 即可"
Step 1: 解析指令 + 用户确认
- Read .pptx 关联的 slide-plan.yaml 和 .theme-prompt.md (若存在)
- Read
<plugin-root>/design-guide.md + <plugin-root>/anchors.yaml (审美锚点 metadata)
- 理解自然语言指令, 映射为 slide-plan.yaml 的具体修改:
- 识别目标 slide (页码 / 标题 / 内容匹配)
- 识别修改类型 (布局变更 / 内容修改 / 样式调整)
- 生成修改方案
- AskUserQuestion 确认理解:
- 选项 1: "确认修改方案"
- 选项 2: "需要调整" (用户补充说明)
Step 2: 修改 slide-plan.yaml
如修改涉及 visual_type 变更或新加 slide, 先重装载主题决策框架:
uv run --script <plugin-root>/engine/prompt_assembler.py --theme <theme-from-plan-meta> --output <workdir>/.theme-prompt.md
Read .theme-prompt.md 确保 visual_type 选择遵循当前主题的硬约束 + 软引导, 避免破坏 huawei 应用率门禁.
仅文字 / 数据 / 字号微调 (不改 visual_type, 不加 slide) 时可跳过.
修改 slide-plan.yaml 中受影响的 slides, 写回原路径.
Step 3: 全量重渲染 + deterministic 校验
uv run python <plugin-root>/engine/render.py <workdir>/slide-plan.yaml \
--theme <theme> --output <output-path>
注意: refine 一律全量重渲染整份 PPT(render.py 输出确定性, 同输入同输出), 不做局部页替换. 早期 --base-pptx/--only-slides 局部替换路径因页号失真 + 追加到末尾不原位替换, 已于 2026-06-23 弃用移除, 全量重渲染是唯一可靠路径.
渲染后跑 deterministic 校验 (带 --theme 让应用率门禁不退化):
uv run --script <plugin-root>/engine/validate_plan.py <workdir>/slide-plan.yaml --theme <theme> --json
检查受影响 slides 的 FAIL / WARN (含反模式 / 连续相同 visual_type) 和 theme_application.status 不退化为 FAIL (exit 2). 退化时 → 回到 Step 2 按 .theme-prompt.md 软引导改回 huawei 专属版式.
Step 4: 完成
输出:
PPT 已更新: <output-path>
修改了 N 页 (页码: x, y, z)
评审 (可选): /ppt:taste <output-path>
继续调整: /ppt:refine <output-path> <新指令>
