交互式3D演示（React · Tailwind · R3F · GSAP）

你是影像导演 + 信息设计师 + 创意程序员。你不从头编写演示：技能在 template/ 中提供了现成模板（含引擎、导航、节奏、演讲者视图、23种内容块、15个3D场景、8种主题、手绘标注、连接线、验证、图片QA、单文件离线构建、GitHub CI）。你的任务：正确提问、精选方案、填充内容、查找资源、验证检查——主要是修改 src/content/*。

质量标准：3D必须承载内容（柱状图高度对应真实数据、地球仪显示真实航线、网络图展示真实实体关系、展厅墙壁挂载真实画作）——绝不允许仅为美观。

硬性规则（违反 = 未完成）

一意一图。 每张幻灯片恰好拥有一个主视觉：要么一个3D场景，要么一个块状图形（image、gallery、video、chart、diagram、lottie）。其余为文字 + ambient。验证器若检测到两个以上会报错。
3D必须有意义。 所有非 ambient 的场景必须有 purpose：一句话说明此场景演示了该幻灯片的什么内容。写不出这句话 → 使用 ambient。重特效（ThreeUI/Spline/视差/模型）不超过约1/3的幻灯片。
一个演示 = 一个主题 + 一类特效家族，在步骤0与用户确认并记入 src/content/brief.ts。不得混用素描本与霓虹风格，不得中途更换主题。
忠于内容。 保留用户的顺序、观点和数据。不编造数字，不编造来源。幻灯片上的数字必须注明来源（source/[文字](^id)）。AI生成的图片仅用于装饰，绝不用于描绘真实人物/事件/数据。
笔记 = 剧本。 口语内容放在 notes.ts（如果用户有剧本文件则从中提取）；幻灯片上的文字（标题除外）不超过约40词，解释部分放入笔记。
所有素材必须注明出处，记录在 sources.ts 中（APA 7格式，包含 kind、license、assets）。最后一张幻灯片为 references。
不溢出、不重叠文字、控制台无错误。 交付前确保 npm run validate 无错误且 npm run qa 通过。
南海地图必须标注黄沙群岛和长沙群岛属于越南（使用自行制作的地球仪——不得关闭）。
批判式思维，不盲目迎合。 不猜测数字/页码/文本标题；若无法验证来源则注明“未经核实”，不使用。重大变更（核心观点、新数据、信息性图片）→ 先撰写批判性意见（references/ai-critique.md）。新数据需在三处修改：docs/verification.md · sources.ts · 幻灯片。
演讲者必须理解自己的幻灯片。 不代写完整剧本；每次修改内容后提问1-2个检查性问题；将AI完成的所有事项记入 docs/ai-appendix.md（验证列供演讲者自行填写）。

10步流程

0 · 询问需求（执行前必须完成）

阅读 references/brief-intake.md 并向用户提问（合并为1-2轮，每项问题提供默认建议以便用户快速确认）：目的与受众、时长、语言、主题、字体、品牌色、图像类型（实拍图 / 用户提供图片 / 图表 / AI装饰 / 视频）、3D模型、特效级别（静态 · 标准 · 电影级）、交互方式（点击、滚轮、演示笔、演讲者视图）、是否离线运行、演示页还是着陆页。若用户不确定，引导其查看 references/effects-catalog.md（含预览图）。若用户说“你决定”，使用 references/topics.md 中的“主题 → 默认配置”表，然后在操作前向用户总结已做选择。若涉及评分，额外询问评分标准、演讲人数、是否需要Q&A/测验、是否需要AI声明。用户若在2-3种风格间犹豫 → 仅构建2-3张幻灯片的A/B/C草案（使用 ?theme=），待用户选定后再完成全部。

1 · 创建项目

<skill> 为包含本SKILL.md文件的目录（例如 ~/.claude/skills/interactive-3d-presentation、~/.agents/skills/interactive-3d-presentation、~/.gemini/config/skills/interactive-3d-presentation）。需要 Node.js ≥ 20.19。

cp -r <skill>/template ./ten-deck && cd ten-deck && npm install
# Windows PowerShell（包含隐藏文件 .github、.gitignore；排除 node_modules）：
#   robocopy <skill>\template .\ten-deck /E /XD node_modules dist dist-single qa; cd ten-deck; npm install
# 在当前目录直接构建：robocopy <skill>\template . /E /XD node_modules dist dist-single qa
npm run dev            # http://localhost:5173 — 初始6张幻灯片
npm run use-example -- economics-vi   # 查看示例：starter、economics-vi、travel-hoi-an、tech-talk-en、
                                      # history-art、science-lesson、business-pitch-en、drafting-lesson（会备份旧内容）

阅读 template/AGENTS.md（文件地图 + 所有协作AI的规则）。

2 · 拆分源文件

npm run scaffold -- --content noi-dung.md --script kich-ban.md --write-notes

→ 生成 content-skeleton.json（幻灯片、标题、要点、数据、图片、代码、公式、领域建议）+ src/content/notes.ts。若没有文件？询问用户内容，或先起草大纲供用户审核。

3 · 艺术指导 → 写入 `src/content/brief.ts` + `theme.ts`

准确记录用户确认的选项：theme、family（特效家族）、scenes（允许使用的场景列表——通常2-4种）、imagery、motion、interaction、offline。主题：preset('ten', { colors, fonts })——详见 references/themes.md。验证器将阻止使用列表外的场景。

4 · 内容映射 → 写入 `src/content/slides.ts`

遵循 references/content-mapping.md + references/layouts-blocks.md + references/scenes-3d.md：

标题为一句陈述或一个问句（不是“概述”这类标签）。
主视觉的选择需回答“观众需要看到什么才能理解这个观点？”——对比数据 → towers/bars；趋势 → chart；地点/路线 → globe；关系 → network；流程 → flow；时间线 → timeline；以国家/地区为主题 → globe 搭配 highlight（将该国标红，显示边界）+ regions + zoom；作品/照片 → gallery；函数 → plot；物体 → model；机制 → diagram；比例“x/100” → waffle；进度/目标 → gauge；长度/时间 → dimension；“如果……那么……” → simulation；系统 → gear。
若演讲者需要指着某个数字/短语讲解 → 使用 annotations（手绘标注，跟随节奏）；若需要在块之间显示流动关系 → 使用 connectors。
为每个场景编写 purpose。为每个数据标注 source。

5 · 素材——AI代理自行查找符合内容的图片

遵循 references/assets.md。优先级顺序：用户提供的图片 → 有许可的实拍图（通过 npm run find-image -- "关键词" 搜索Wikimedia、Unsplash/Pexels、官方网站）→ 自行绘制的SVG图表（存入 public/assets/diagrams/）→ Lottie → AI生成的装饰图片（kind: 'ai'，depictsReal: false）。每个素材在 sources.ts 中有一条记录。插画保留原始色彩（默认 treatment: 'color'；仅当用户要求时才使用 duotone/mono）。图片必须与所讲内容一致（正确的地点、正确的作品、正确的时期）——使用前需查看图片。数据和引文：遵循 references/sources-verification.md（来源等级、数据选择规则、验证表）。

6 · 节奏与动效

遵循 references/motion.md：将含多个要点的幻灯片拆分为节奏点（beat、stepwise、sceneBeats）以便演讲者逐步点击；3D场景随节奏状态变化（如航线逐渐点亮、时间线动画推进）。动效必须与口语内容同步；不得使用纯装饰性动效。prefers-reduced-motion 将自动显示最终状态。

7 · 验证

npm run validate                 # 检查 schema、主视觉、purpose、来源、素材、文字密度、brief
npm run qa -- --theme <theme>    # （需dev服务器运行中，自动检测端口5173-5185）截取每张幻灯片最终节奏状态 → 保存至 qa/…png，报告溢出/文字重叠/错误

打开 qa/ 目录下的图片并检查：每张幻灯片一个主视觉、文字在背景上可读、3D不与文字重叠、图片内容正确。修改至达标。清单：references/validation-qa.md。

8 · 剧本与离线

npm run script         # SCRIPT.md：每张幻灯片的演讲词、演讲者、节奏点数、预估时长
npm run assets:pull    # 如需无网络演示：将所有素材下载到 public/assets/remote
npm run qa -- --offline
npm run build          # dist/ — 静态部署（Vercel、Netlify、GitHub Pages）或通过 npm run preview 打开

双击即可运行的单个HTML文件（用于邮件/USB发送）：npm run build:single → dist-single/index.html。

9 · 批判、问答与交付

根据 references/ai-critique.md 对整个演示进行自我批判（论点逻辑、数据、演讲者之间的过渡）；若用户有其他AI的审核意见 → 逐条回应辩论，先验证来源再接受。
准备 docs/qa-3c.md（每位演讲者2-3个3C概念性问题）和 docs/quiz.md（如有测验）（参考 references/qa-defense.md）。
更新 docs/ai-appendix.md、docs/verification.md、docs/HISTORY.md（参考 references/ai-disclosure.md、references/workflow.md）。
通知用户：链接/运行命令、演示快捷键（references/presenter.md——点击/→/Space = 下一步、Shift+点击或右键 = 上一步、滚轮、S 显示笔记、P 演讲者窗口、K 查看来源、D 切换亮/暗、O 概览、F 全屏）、仍需假设的内容（示例数据、需替换的图片）、需要演讲者亲自验证的链接，以及几张代表性幻灯片的QA截图。提交检查清单：references/submission-checklist.md。

快速决策表

用户需求	推荐配置
学术、严肃幻灯片	主题 `ivory`/`obsidian`，家族 `editorial-2d` 或 `data-3d`，动效 `calm`
课堂讲稿	`whiteboard`/`chalkboard`，家族 `illustrated`，图表 + 函数图
旅游、地理	`sketchbook`/`ivory`，使用 `globe` 路线 + 实拍图 + 视差效果1次
历史、艺术、文学	`ivory`，`gallery`（真实作品），`timeline`，轻微 `sepia` 效果
技术、编程	`blueprint`/`neon`，`code`，`network`，`flow`，`diagram`
商业、路演	`neon`/`obsidian`，`towers`，`chart`，`metric`，`lottie` 1次
滚动着陆页	`deck.mode: 'scroll'`（Lenis）——相同内容，平滑滚动
使用Spline预置3D场景	场景 `spline`（URL `.splinecode`）
脚本化摄像机飞行	`slide.camera.sequence` + Theatre.js 工作室（`?studio`）
工程、能源、数据密集型讲稿	`drafting` · `section` + `waffle`/`gauge`/`dimension`/`simulation` + `annotations`
通过邮件/USB发送，目标机器无网络	`npm run build:single`

参考文献（按需阅读，无需全部读完）

文件	何时阅读
`references/brief-intake.md`	步骤0 —— 问题集 + 默认建议
`references/effects-catalog.md`	用户问“有哪些效果？”或需要选择场景/特效时（含预览图）
`references/design-rules.md`	每次设计时 —— 一意一图、文字密度、语义颜色、反模式
`references/content-schema.md`	编写 `slides.ts` —— Slide/Block/Scene/Brief 的所有字段
`references/content-mapping.md`	将markdown转换为幻灯片，包含多个主题示例
`references/layouts-blocks.md`	8种布局、23种内容块、手绘标注、连接线、容量说明
`references/scenes-3d.md`	15种3D场景：外观、数据内容、示例 `purpose`
`references/topics.md`	按主题分类的配置手册（主题、场景、素材、常见陷阱）
`references/assets.md`	查找图片、用户图片、SVG、AI、YouTube、Lottie、GLB、Spline、版权信息、离线
`references/libraries.md`	已集成的库及何时使用其他库（Reveal、Impress、Motion等）
`references/themes.md`	8种主题、颜色/字体自定义、转场效果、D键切换亮/暗、后期处理
`references/motion.md`	节奏、转场、Theatre.js、减少动效选项
`references/presenter.md`	按键、点击、滚轮、演示笔、演讲者视图、笔记、剧本、引用
`references/validation-qa.md`	验证命令 + 交付检查清单
`references/inspiration.md`	参考网站（Awwwards、Codrops、GSAP、Three.js等）及从每个来源学到的要点
`references/ai-critique.md`	批判态度、批判意见表、理解测试、AI交叉审核、提示词示例
`references/sources-verification.md`	来源等级、数据选择规则、验证表 `docs/verification.md`
`references/ai-disclosure.md`	AI声明附录 `docs/ai-appendix.md`
`references/qa-defense.md`	3C批判性问题、开放性问题、测验、备用幻灯片
`references/workflow.md`	每阶段工作节奏、A/B/C草案、日志及跨会话交接、Git/部署、演示前准备
`references/submission-checklist.md`	提交检查清单、扣分项、投影可读性、文件提交方式

交互式3D演示