magic-slide

Magic Slide

生成精美的 HTML 演示文稿，并实现流畅的 Magic Move 转场——在多张幻灯片上出现的元素会在不同位置之间流畅移动。将 Magic Move 视为故事规划的约束，而非事后才考虑的效果：安排大纲时，应让有意义的标题、卡片标题、数字、图片或图表节点能够在相邻幻灯片之间延续。

技能命令参数

用户通过以下参数调用了此技能：$ARGUMENTS

可见 TODO 要求

每次调用此技能时，都必须在执行第一个实质性操作之前创建可见的 TODO/计划，并在本轮结束前持续更新。

• 如果有可用的宿主规划工具，请使用它：Codex 的 update_plan、Claude Code 的 TodoWrite，或环境中等效的可见清单。每次 $magic-slide 运行都必须遵守此要求，包括仅预览命令、需求收集／提问轮次、新建演示文稿、后续编辑演示文稿，以及修复 visual-issues.json 的轮次。
• 清单应简短具体，包含 3-7 项，并与当前模式相符。示例：“确定演示文稿路径”“启动预览服务”“阅读 QA 备注”“修复幻灯片 02 源文件”“合并并注入运行时”“将 QA 备注标记为待确认”“保持 QA Overview 打开以供审核”。
• 随着工作推进更新各项状态。不要等到最后才把所有项目标记为已完成；用户应能看到技能运行过程。
• 如果必须在某个检查点停止本轮，例如需求收集、是否联网搜索的选择、大纲确认或用户 QA 确认，应保留显示等待／检查点事项的 TODO。
• 如果没有可见的 TODO 工具，请在继续之前于聊天中写出简短的 TODO 清单，并在后续进度消息中手动更新。

在 Claude Code 中以 /magic-slide preview [topic] 调用，或在 Codex 中以 $magic-slide preview [topic] 调用时，运行预览快速流程：

在 CelHive 托管的 Skill 运行中，将 $CELHIVE_SKILL_WORKSPACE/deck 用作演示文稿目录，并在生成后调用宿主通用的 Preview 工具。包级的 preview.json 负责管理命令、端口、健康检查路由和 Artifact 根目录；不要手动启动第二个预览进程。在托管宿主之外，使用下方的本地 serve.py 工作流。

1. 首先创建可见的 TODO 清单，包含适用于预览的步骤，例如确定演示文稿路径、启动 serve.py 和报告 URL。
2. 将 preview 后的参数视为主题／演示文稿目录。如果省略，则使用 .。预览该目录中的 index.html。如果用户传入明确的 .html 文件，则直接预览该文件。
3. 如有需要，定位此技能目录： SKILL_DIR=$(find ~ -type d -name "magic-slide-skill" 2>/dev/null | head -1)
4. 按照下方的脚本运行时要求，确定 Python 3 解释器。
5. 使用现有脚本启动预览服务： $PYTHON_BIN "$SKILL_DIR/scripts/serve.py" "$DECK_PATH"
6. 保持服务进程运行，并向用户提供显示的 URL。
7. 除非用户也明确要求生成演示文稿、创建大纲、合并幻灯片或注入运行时，否则不要询问生成演示文稿的问题，也不要执行这些操作。

对于任何其他 magic-slide 调用参数，将这些参数视为用户的演示文稿需求，并遵循常规生成工作流。

非预览请求的需求收集关卡

对于任何非预览演示文稿请求，在运行命令、搜索、创建文件夹、编写大纲或生成幻灯片之前，请先完成 references/workflows/step-01-requirements.md 中的步骤 1。

严格关卡：

• 可见的 TODO 要求仍须在此关卡之前执行。如果本轮因需求收集而暂停，请让 TODO 显示正在收集需求，且生成工作正等待用户回答。
• 如果主题／受众视角、审美风格、演示语言或图片政策缺失、是推断得出的，或仅有暗示，请提出步骤 1 中的需求问题并停止。
• 不要将用户的聊天语言视为演示语言。
• 不要将 URL、公司／产品名称或“介绍一下 X”视为完整主题，除非受众／视角也已明确提供或确认。
• 如果结构化提问工具不可用，请在本轮中仅使用步骤 1 的纯文本备用模板作为完整回复，然后等待。

关键：脚本运行时要求

Magic Slide 附带的脚本需要 Python 3 运行时。核心合并、注入、修复说明和预览脚本使用 Python 标准库及现代浏览器；不需要外部 Python 包。只有在使用网页搜索或图片生成时，PipeLLM 脚本才需要环境中的 PIPELLM_API_KEY。仅 Agent 执行截图 QA 时才需要 Playwright，包括运行 scripts/check-magic-text-wrap.py。

PipeLLM 网页搜索是可选功能，须经用户同意，并会返回经过净化的不可信证据记录。PipeLLM 图片生成是可选功能，须经用户同意。脚本需要 --allow-external，以确保未经明确的工作流关卡批准不会发出外部请求；提示词注入边界的详细规定由步骤 2 负责。

在本轮首次执行脚本之前，请确定 Python 3 解释器：

PYTHON_BIN=$(command -v python3 || command -v python || true)
if [ -z "$PYTHON_BIN" ]; then
  echo "Magic Slide requires Python 3 to run its bundled scripts." >&2
  echo "Install Python 3, then rerun the Magic Slide command." >&2
  exit 1
fi
if ! "$PYTHON_BIN" -c 'import sys; raise SystemExit(0 if sys.version_info[0] == 3 else 1)'; then
  echo "Magic Slide requires Python 3, but the resolved python command is not Python 3." >&2
  exit 1
fi

确定解释器后，执行脚本时请使用 $PYTHON_BIN。如果没有 Python 3，请停止并告知用户 Magic Slide 需要 Python 3，而不是改写或绕过脚本。

关键：脚本执行规则

此技能中的所有脚本都位于相对于技能根目录的 scripts/ 目录中。

执行脚本时：

1. 如果脚本执行失败并提示 "No such file or directory"：

   • 不要放弃，也不要告诉用户“脚本不可用”
   • 使用以下命令查找技能目录：find ~ -name "magic-slide-skill" -type d 2>/dev/null | head -1
   • 或搜索 SKILL.md：find ~ -name "SKILL.md" -path "*/magic-slide-skill/*" 2>/dev/null | head -1 | xargs dirname
   • 将技能目录路径存入变量
   • 使用绝对路径重新执行脚本：$PYTHON_BIN $SKILL_DIR/scripts/websearch.py

2. 执行脚本时始终使用绝对路径，以避免路径问题

正确执行示例：

# Find skill directory (do this once at the start)
SKILL_DIR=$(find ~ -type d -name "magic-slide-skill" 2>/dev/null | head -1)

# Execute scripts with absolute paths
$PYTHON_BIN "$SKILL_DIR/scripts/websearch.py" "query" --allow-external
$PYTHON_BIN "$SKILL_DIR/scripts/generate-image.py" "prompt text" --output ./assets/image.png --allow-external
$PYTHON_BIN "$SKILL_DIR/scripts/merge-slides.py" ./sources/ --lang en

重要：注入的运行时输出边界

将 scripts/inject-runtime.py 及其注入到最终演示文稿中的行为和结果视为 Magic Slide 运行时输出。在生成、更新和 QA 演示文稿时，按原样运行现有注入器，并默认保留其注入行为。除非用户明确要求更改特定运行时行为，否则不要编辑注入器、修补 {topic}/index.html 中注入的运行时代码块，也不要添加旨在禁用、隐藏、中和或覆盖注入功能的源 CSS/HTML/JS。

未经用户明确要求，禁止进行以下“清理”：隐藏动画/自定义光标、使用 cursor: auto 或 cursor: default 恢复系统光标、移除或隐藏导航/进度/编辑控件、关闭 Magic Move、抑制注入的交错效果，或绕过运行时适配。

如果演示文稿存在视觉或布局问题，应围绕运行时行为修复模块化源文件（sources/style.css 和 sources/slide-XX.html），然后重新运行合并和注入。如果问题似乎由注入的运行时行为本身导致，应报告疑似运行时问题或先询问用户；只有用户要求更改时才修改运行时行为。

快速工作流

默认采用平衡路径。 保留大纲确认节点，撰写简短设计简报，然后一次性生成完整演示文稿。除非用户明确要求采用较慢的工作流，否则不要单独制作原型。可见 TODO 要求适用于步骤 1 之前；当工作流从信息收集进入大纲、生成、QA 或修复阶段时，应更新 TODO。

用户交互规则： 所有用户确认都必须使用 AskUserQuestion 工具。只有在该工具不可用或调用失败时，才可改用文本提问。务必先尝试使用 AskUserQuestion。如果必须改用纯文本，对结构化问题应以可复制的回复模板结尾；大纲确认和网络搜索的是/否问题除外，详见 references/workflows/text-question-templates.md。

1. 步骤 1：收集需求 — 询问全部 4 组问题：主题/受众视角、审美风格、语言（必需——绝不根据用户消息的语言推断）、图片
2. 步骤 2：网络搜索 — 询问用户是否需要在线搜索（可选）。如果用户同意，先运行 scripts/websearch.py；只有该脚本失败或未返回可用结果时，才使用内置 Agent 搜索作为后备方案。
3. 步骤 3：生成大纲 — 创建 {topic}/sources/outline.md，其中必须包含：论点主线、受众/视角、章节脉络、结尾构想、Magic Move 内容接力主线、演讲者备注模式，以及每张幻灯片的演讲者提示词。须获得用户确认（必经节点）
4. 步骤 4：撰写精简设计简报 — 在编写 CSS/HTML 之前，输出一份精简设计简报，内容包括：视觉世界、排除的套路、封面承诺、语气模式、由风格控制的字体/颜色/材质逻辑、幻灯片系列，以及 Magic Move 内容接力的动态规则
5. 步骤 5：生成生产用源文件 — 根据已确认的大纲和精简设计简报，直接创建 style.css 和所有 slide-XX.html 文件；此前应为相邻幻灯片对制作主要/辅助连续性映射，并将大纲中的演讲者提示词映射到隐藏的演示者备注中
6. 步骤 6：合并幻灯片 — 将模块化源文件合并为单个 HTML
7. 步骤 7：注入运行时 — 按原样运行现有注入器；除非用户明确另有要求，否则保留注入的行为/结果
8. 步骤 8：预览、自主概览 QA 修复、强制用户修订暂停、根据修订备注修复、用户确认并交付 — 务必使用 scripts/serve.py 启动技能预览服务，打开运行时 QA 截图 URL，使用 Playwright 拍摄一张 QA 概览长截图以进行首轮修复，然后暂停，让用户标记幻灯片修订。根据已保存的修订备注完成修复后，将其标记为已修复并等待用户确认，不要再进行截图验证。 **不可妥协的交付规则：**生成或更新幻灯片后，必须等到 $PYTHON_BIN "$SKILL_DIR/scripts/serve.py" {topic}/index.html 正在运行，并向用户提供预览 URL，才能结束。直接打开 HTML 文件并不足够：编辑模式、保存、替换图像以及关闭／关停控件都需要 Magic Slide 预览服务。切勿用 python3 -m http.server、npx serve 或文件 URL 代替技能服务。

**不可妥协的 QA 门槛：**为新生成的幻灯片启动 serve.py 后，打开 ?ms_qa=overview&ms_qa_capture=1，等待 QA 墙报告 iframe 已加载就绪，然后使用 Playwright 捕获一张全页／滚动式 QA 概览长截图，并优先按幻灯片编号修复最明显的渲染问题。在这一轮自主修复中，概览修复后不要捕获单张幻灯片的全尺寸截图。请遵循 references/workflows/step-10-preview.md 中的详细问题排查顺序和仅使用 Playwright 截图的规则。随后重新打开 QA 概览或保持其运行，然后停止：告诉用户在 QA 卡片上用 Revise slide 标记幻灯片修改，并在准备好后回来。用户修改暂停是最终 QA 或交付前的强制步骤。继续修复时，首先读取 {topic}/sources/qa/visual-issues.json 中未处理的 JSON 备注。

**不可妥协的更新规则：**幻灯片生成后，用户在聊天中继续提出修改要求时，先读取 {topic}/sources/qa/visual-issues.json，并在存在未处理的修改请求时优先处理。如果存在未处理的备注，应根据保存的 JSON 以及相应的 {topic}/sources/slide-XX.html 和 {topic}/sources/style.css 进行修复；只有在无法根据 JSON／源文件上下文理解备注时，才使用截图，并且必须通过 Playwright 捕获。首先编辑模块化源文件，然后重新运行 merge-slides.py，不做任何更改地重新运行现有的 inject-runtime.py，将已修复的 JSON 记录标记为 status: "fixed_pending_confirmation"，并设为 resolved: false，刷新或重启 Magic Slide 预览服务，然后打开或保持 QA 概览运行，供用户确认或继续提出修改。除非用户明确要求进行视觉验证，否则修复保存的 JSON 备注后不要运行截图验证。除非用户明确要求修补合并后的 HTML，或修改来自浏览器编辑模式的 Save 流程，否则不要直接编辑 {topic}/index.html 来跟进 Agent 处理的修改。

**Brief Lite 并非可选项。**它是防止生成泛泛无奇或令人不安的模板内容的质量保障。请保持简洁。只有当用户要求深入的设计探索、高风险的视觉方向，或在生成整套幻灯片前先制作少量样例时，才使用较慢的原型门槛。

详细工作流步骤

每个步骤都有详细说明，位于 references/workflows/ 目录中。到达相应步骤时，请阅读对应文件：

• 步骤 1：收集需求 - 必须询问全部 4 组问题：主题／受众视角、风格、语言（必问）、图片。绝不能跳过语言问题。
• 步骤 2：网络搜索 - 可选：在线搜索最新信息
• 步骤 3：生成大纲 - 创建并确认演示文稿结构
• 步骤 4：编写精简设计简报 - 编码前必须编写精简设计简报
• 步骤 5：生成制作源文件 - 直接根据已确认的大纲和精简设计简报创建 style.css 和所有幻灯片
• 步骤 6：合并幻灯片 - 将模块化源文件合并为单个 HTML 文件
• 步骤 7：注入运行时 - 运行现有注入器，并保留注入后的行为和结果，除非用户明确要求更改
• 步骤 8：预览和最终质量检查 - 启动预览并检查质量

旧版可选工作流文件：

• 可选：构建视觉原型 - 仅在用户要求先提供样例时使用
• 可选：通过视觉检查 - 仅用于可选的原型工作流

生成后编辑

用户可以通过两种方式编辑演示文稿，但由 Agent 执行的后续工作必须保留作为事实来源的文件。

编辑需要预览服务器。 提及编辑模式之前，请确保演示文稿正通过 scripts/serve.py 提供服务，并告知用户服务器 URL。如果服务器未运行，请先启动。

键盘快捷键适用范围。 通过本地 serve.py 预览路由（http://localhost:.../deck/...）打开演示文稿时，所有运行时快捷键均可用。在此本地预览环境之外打开同一 HTML 时，只有适用于演示的快捷键仍有效：O 用于总览，C 用于显示或隐藏光标，Space／方向键用于切换幻灯片。

演示者页面指示器。 演示者窗口必须在其底部控制台中显示高对比度的当前页码／总页数指示器，并在每次导航后更新。此指示器只能创建在演示者外壳中；不得将其重复放到面向观众的幻灯片画布或导出的幻灯片视觉内容上。

1. 编辑模块化源文件（所有 Agent 更改的默认方式）：

• 编辑 {topic}/sources/slide-XX.html 或 style.css
• 重新运行合并和注入脚本
• 刷新浏览器

2. 编辑合并后的 HTML（仅用于明确要求的快速修复或浏览器编辑模式）：

• 在浏览器中按 e 进入编辑模式
• 点击任意文本即可进行行内编辑
• 点击“Save”将更改写入 index.html
• 预览服务器会尝试将浏览器保存的更改同步回 sources/
• 如果直接在浏览器之外编辑 index.html，请提醒用户模块化源文件可能会过时，并优先使用 sources/

文件结构

{topic}/
├── index.html          # Final merged presentation (deliverable)
├── assets/             # Final presentation assets (if generated)
│   ├── image-1.png
│   └── ...
└── sources/            # Process files and modular source files
    ├── outline.md      # Confirmed outline
    ├── create_sources.mjs  # Optional generation helper, if used
    ├── qa/             # QA screenshots/reports, if generated
    ├── style.css
    ├── slide-01.html
    ├── slide-02.html
    └── ...

保持主题根目录整洁。除 index.html、assets/ 和 sources/ 外，所有流程产物都必须放在 {topic}/sources/ 中。

关键参考文件

生成过程中按需阅读这些文件。将它们视为各自主题的唯一权威来源；不要在本文或工作流步骤中重新整理并复述其中的完整规则。

• design-system.md — 美学方向与反模板准则
• generation-guide.md — 制作规划与生成策略
• layout-guide.md — 布局基础元素、舞台适配、溢出、垂直平衡与来源说明的位置
• html-contract.md — 必需的幻灯片结构、演示文稿语气模式、根背景、SVG 规范、文件命名与验证清单
• flip-engine.md — Magic Move / data-magic-id 规划与可靠性规则
• images.md — 生成图像的使用、可上传的封装方式与封面图规范

设计理念

1. 大纲必须提出论点，而不是罗列主题 — 每张幻灯片都应推进一个论点，而不只是说“还有这个”
2. 先写 Brief Lite — 编写 CSS 前，先确定贴合主题的视觉世界，以及主要的浅色／深色基调。内容保持简洁，但要输出，让设计承诺清晰可见。
3. 尽早规划 Magic Move — 在编写 HTML 前，大纲就应创造内容衔接机会：概览／详情、指标／主视觉数据、地图／缩放、对比／案例，以及其他主要锚点。不要等到后期依靠装饰性重复元素来制造动效。
4. 生成一次、检查，然后暂停 — 完成大纲和 Brief Lite 后，生成完整演示文稿，修复明显的 Playwright QA 概览缩略图问题，然后暂停，等待用户执行必需的 Revise slide 标注，再交付最终版本。
5. QA 概览用于视觉检查，而非诊断 — 将概览用作渲染后的幻灯片墙，以及供人工／Agent 进行视觉审查并记录修改意见的界面。单独进行的检查仅限于语法、预览启动、运行时控件，以及 Playwright 渲染的截图检查。
6. 封面是特别时刻 — 第 1 张幻灯片必须采用独特的开场构图，并配以简洁的封面文案；对于产品／AI／基础设施类演示文稿，应以标题为主，而不是放置可读的流程图。详细的封面规则请参阅 design-system.md、images.md 和 html-contract.md。
7. 快速迭代 — 如有问题，快速修改 CSS 和受影响的源幻灯片，然后重新合并／注入。
8. 合并后的 HTML 是生成产物 — 将 {topic}/index.html 视为生成的输出。仅在明确要求的一次性补丁或浏览器编辑模式的 Save 流程中，才直接编辑 HTML。
9. 布局可靠性是硬性要求 — 遵循 layout-guide.md 中关于基础元素、舞台适配、溢出、垂直平衡与来源说明位置的规范。
10. 不要添加人为的幻灯片装饰或仅用于 Magic 的标签 — 遵循 html-contract.md 和 flip-engine.md：不要生成类似浏览器栏的顶部条、全宽品牌胶囊，或主要为了实现 Magic Move 连贯性而放置的正文 token 行。

质量标准： 每份演示文稿都应独特且经过用心设计，而不是想到什么就直接采用。如果同一设计可以原封不动地用于其他主题，那么它就太泛化了。

可读性标准： 将无法阅读的文本视为演示文稿缺陷，而非审美问题。详细的文本对比度与文本适配规则请参阅 html-contract.md、layout-guide.md 和 design-system.md。

输出质量

每份演示文稿都应具备以下特点：

• 自包含 — 单个 HTML 文件，无外部依赖
• 流畅 — Magic Move 带来流畅的过渡
• 便携 — 可离线使用，便于分享
• 可编辑 — 源文件模块化，便于迭代
• 独特 — 视觉风格鲜明，不落入泛化的 AI 美学

目标是在速度与审美之间取得平衡：确定视觉世界，尽早预览，然后快速生成，并根据渲染后的演示文稿进行迭代。