一键在 Manus 中运行任何 Skill

themed-cn-pptx

星标5

分支1

更新时间2026年6月21日 15:09

Build, modify, and QA-verify Chinese + IP/character-themed + QR-embeddable EDITABLE PPTX decks using PptxGenJS, with StepFun or MiniMax AI image generation, locked aesthetic recipes, and a deterministic render-QA gate (CJK overflow, text overlap, editable-text, color contrast). Triggers: 可编辑 PPTX, 中文 PPT, PPT 验收, render QA, PptxGenJS, presentation, slide, deck, PowerPoint, 演示文稿, 幻灯片.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

在 Manus 中运行

来源

CacinieP

CacinieP/ppt-skills

打开 GitHub 仓库查看创作者相关仓库

下载

在 Manus 中运行

0. 两条使用路径

本 skill 按用户意图分为两条路径，先判断再执行：

路径 A：改 PPT

用户已有一份 .pptx（或 .js 构建脚本），需要做局部修改——换主题色、加配图、调排版、插页、替换内容。

流程：

读取现有 .pptx（用 python-pptx 解析）或 .js 脚本
确定修改范围——主题色？哪些页加图？哪些文字要改？
修改 build_<theme>.js → 重新生成 .pptx
QA 循环（§8）

典型说法：

"把这份 PPT 换成初音主题"
"给第 3 页和第 6 页各加一张 AI 配图"
"封面加个背景图，文字加半透明遮罩"
"粉色再浅一点"

路径 B：从文稿到 PPT

用户给一份文稿/大纲/README/Notion 页，从零生成完整 PPTX。

流程：

抓取内容源（粘贴文本 / GitHub README / URL）
任务拆解（§1）
构建色板（§2）+ 确定生图需求（§2.5）
选择 Slide 布局（§5）→ 编写 build_<theme>.js
生成配图（§2.5）→ 嵌入 PPTX
QA 循环（§8）

典型说法：

"帮我把这个 README 做成 PPT，10 页，初音主题"
"按这份大纲生成一份演讲稿 PPT"
"从这篇文档出一份产品介绍 PPT，带配图"

1. 任务拆解（先做这一步）

在写代码前，从用户需求中先抽出：

IP / 主题 → 映射到 4 色身份（主色 + 副色 + 深底 + 浅底）
输出格式 → 确认 .pptx（可编辑）/ PDF Slides / Notion Slides / Presentation App，不要假设
语言 → 中文需要 CJK 字体 + 更紧的字号阶（全角字符在同 pt 下比 Latin 宽）
硬约束 → 页数上限、二维码目标 URL、需隐去的话题、品牌标识
内容源 → 用户粘贴的文本？GitHub README？现有 Notion 页？先抓取再写 slide
图像需求 → 哪些页需要 AI 配图？封面背景？卡片插图？项目展示？→ 参考 §2.5 确定用途和尺寸
视觉系统 → 对复杂/公开发布 deck，先读 references/aesthetic-rules.md，声明 style_id、布局族、密度和负面风格
生图约束 → 生成封面/hero/showcase 前先读 references/image-constraints.md，写出 image manifest 再调用 API

2. 构建角色 IP 调色板（模板）

角色 / IP 主题 deck 需要既像 IP 又不刺眼的配色。固定 6 个色槽：

色槽	作用	Miku 示例
Dominant 主色	承载 deck 身份的招牌色	`#39C5BB` 初音青（官方）
Secondary 副色	一种反差强调色（仅用于 header/kicker/callout）	`#FF77AA` 双马尾粉
Dark BG 深底	封面 / 分隔 / 收尾	`#0B1B2B` 深夜空蓝
Light BG 浅底	内容页	`#F1FBFA` 青调米白
Soft accent 柔和点缀	chips / 浅卡背景	`#E6F8F6`
Muted text 弱化文字	浅底正文	`#59707B`

权重规则：

主色 60-70% 视觉权重，副色 ~20%，强调 ~10%
副色绝不用于正文，只用 header / kicker / callout
IP 有官方色就用官方色，不要猜（先查）

可复用的 JS 常量块：

const C = { miku:"39C5BB", mikuDeep:"1C9990", pink:"FF77AA", pinkSoft:"FFC2DB",
  navy:"0B1B2B", navyDeep:"06121E", ink:"0F2233",
  paper:"F1FBFA", paperAlt:"E6F8F6", white:"FFFFFF",
  textOnDark:"E8FFFD", textOnLight:"0F2233", muted:"59707B", line:"BFE7E2" };

换 IP 时只替换具名颜色，色槽结构保持不变。

预置色板库

非 IP 场景直接从下面挑一套，无需自己配色。每套都经过对比度验证（WCAG AA）。

🏔️ Nord 商务蓝

来源：Nord · 冷调专业，适合技术/SaaS/企业演示。

const C = {
  // Dominant 系列：Frost 蓝
  dominant: "88C0D0", dominantDeep: "5E81AC",
  // Secondary：Aurora 暖橙（互补强调）
  secondary: "D08770", secondarySoft: "EBCB8B",
  // 背景
  darkBg: "2E3440", darkBgDeep: "242933",
  lightBg: "ECEFF4", lightBgAlt: "E5E9F0",
  // 中性
  white: "FFFFFF", ink: "3B4252",
  textOnDark: "D8DEE9", textOnLight: "3B4252",
  muted: "4C566A", line: "D8DEE9"
};

验证：白字 on #2E3440 = 12.5:1 ✅ | #4C566A on #ECEFF4 = 6.4:1 ✅ | 深字 on #88C0D0 = 5.0:1 ✅（浅主色用深字）

🐱 Catppuccin 柔和

来源：Catppuccin Latte · 温暖柔和，适合教育/培训/内部分享。

const C = {
  // Dominant：Latte Blue
  dominant: "1E66F5", dominantDeep: "1A5BD6",
  // Secondary：Mauve 紫（邻近色策略）
  secondary: "8839EF", secondarySoft: "7287FD",
  // 背景
  darkBg: "4C4F69", darkBgDeep: "3B3E56",
  lightBg: "EFF1F5", lightBgAlt: "E6E9EF",
  // 中性
  white: "FFFFFF", ink: "4C4F69",
  textOnDark: "EFF1F5", textOnLight: "4C4F69",
  muted: "646777", line: "BCC0CC"
};

验证：白字 on #4C4F69 = 8.0:1 ✅ | #646777 on #EFF1F5 = 5.0:1 ✅

💎 Radix 科技蓝

来源：Radix Colors Blue · 无障碍优先，适合产品/技术架构演示。

const C = {
  // Dominant：Radix Blue 9
  dominant: "0090FF", dominantDeep: "006ADC",
  // Secondary：Indigo（邻近色策略）
  secondary: "6E56CF", secondarySoft: "8B7CE8",
  // 背景
  darkBg: "0B1120", darkBgDeep: "060A14",
  lightBg: "FBFCFF", lightBgAlt: "F0F4FF",
  // 中性
  white: "FFFFFF", ink: "0C1A2B",
  textOnDark: "E1E8F5", textOnLight: "0C1A2B",
  muted: "5C6B7F", line: "C6D2E0"
};

验证：白字 on #0B1120 = 16.8:1 ✅ | #5C6B7F on #FBFCFF = 6.2:1 ✅

🌿 暖色教育

适合培训课件、K-12 教育、教学分享。色温偏暖，视觉友好。

const C = {
  // Dominant：Catppuccin Teal
  dominant: "179299", dominantDeep: "12787E",
  // Secondary：Peach 暖橙（互补策略）
  secondary: "FE640B", secondarySoft: "F5A97F",
  // 背景
  darkBg: "1A2332", darkBgDeep: "111825",
  lightBg: "F7F9F4", lightBgAlt: "EEF2E6",
  // 中性
  white: "FFFFFF", ink: "2C3E2D",
  textOnDark: "D4E8D5", textOnLight: "2C3E2D",
  muted: "587259", line: "C0D4C0"
};

验证：白字 on #1A2332 = 15.8:1 ✅ | #587259 on #F7F9F4 = 5.0:1 ✅

🎓 学术靛

适合论文答辩、学术报告、研究分享。深沉内敛。

const C = {
  // Dominant：靛蓝
  dominant: "3F51B5", dominantDeep: "303F9F",
  // Secondary：Catppuccin Mauve（邻近色策略）
  secondary: "7C4DFF", secondarySoft: "B388FF",
  // 背景
  darkBg: "1A1A2E", darkBgDeep: "12121F",
  lightBg: "F5F5FA", lightBgAlt: "EBEBF5",
  // 中性
  white: "FFFFFF", ink: "1A1A2E",
  textOnDark: "D0D0E8", textOnLight: "1A1A2E",
  muted: "5C5C7A", line: "C0C0DA"
};

验证：白字 on #1A1A2E = 14.2:1 ✅ | #5C5C7A on #F5F5FA = 5.5:1 ✅

🌙 暗色创意

适合创意提案、设计评审、夜间/暗室演示。高对比暗色系。

const C = {
  // Dominant：Catppuccin Mocha Blue
  dominant: "89B4FA", dominantDeep: "74C7EC",
  // Secondary：Pink（互补策略）
  secondary: "F5C2E7", secondarySoft: "CBA6F7",
  // 背景
  darkBg: "1E1E2E", darkBgDeep: "11111B",
  lightBg: "2A2A3C", lightBgAlt: "252536",
  // 中性
  white: "FFFFFF", ink: "11111B",
  textOnDark: "CDD6F4", textOnLight: "CDD6F4",
  muted: "8C92AE", line: "45475A"
};

验证：#CDD6F4 on #1E1E2E = 11.3:1 ✅ | #8C92AE on #2A2A3C = 4.6:1 ✅ | 深字 on #89B4FA = 8.9:1 ✅（浅主色用深字）

色板选择决策树

有 IP 官方色？ ── 是 ── 用 IP 色 + §2 6 色槽规则
       │
       否
       │
  场景是什么？
       ├── 科技/企业/SaaS ──→ Nord 商务蓝 或 Radix 科技蓝
       ├── 教育/培训 ──→ 暖色教育 或 Catppuccin 柔和
       ├── 学术/研究 ──→ 学术靛
       ├── 产品/设计 ──→ 暗色创意（暗室）或 Catppuccin 柔和（亮室）
       └── 不知道 ──→ Nord 商务蓝（最安全）

更多设计理论参考 design-principles.md。

2.1 色彩方案与 QA 规则

中文 PPT 的色彩 QA 不看“感觉”，先按 sRGB / RGB 色号计算。RGB 通道不是线性亮度；先把 #RRGGBB 的 R/G/B 从 0-255 归一化并做 sRGB gamma 线性化，再算相对亮度：

L = 0.2126 * R_linear + 0.7152 * G_linear + 0.0722 * B_linear
contrast = (L_lighter + 0.05) / (L_darker + 0.05)

绿色通道对亮度贡献最大，蓝色最小，所以不要用 RGB 数值差或“看起来颜色不一样”判断可读性。正文对比度至少 4.5:1；大标题、粗体大字、UI 边框、图形对象至少 3:1。用 scripts/color-qa.mjs 快速检查：

node scripts/color-qa.mjs --fg 0F2233 --bg F1FBFA --role body
node scripts/color-qa.mjs --palette 0F2233,F1FBFA,39C5BB,FF77AA --role body

色彩方案选择

方案	适用	规则
Neutral + Accent	中文说明型、产品介绍、交付物	最稳。正文只用深墨色/近白，品牌色只做条纹、编号、图标、强调块
Monochrome 单色系	严肃、科技、统一感强的 deck	必须拉开明度阶，不要只改饱和度；正文仍用深/浅中性色
Analogous 邻近色	柔和、情绪统一的角色主题	需要一个深底和一个浅底承载文字，否则容易“一片糊”
Complementary 互补色	封面、章节页、强冲突观点	一方做主色，另一方只做 5-10% 强调；不要互相做正文/背景
Split-complementary 分裂互补	IP 主题、活泼但可控	比纯互补更安全，适合“主色 + 两个小强调色”
Triadic / Tetradic	流程图、矩阵、分类图	只用于图形编码；同页高饱和主色不超过 3 个
Dark mode 深底	封面、收尾、章节分隔	用 `textOnDark` 近白，不用纯高饱和色写长正文；图片上文字必须加遮罩

颜色组合负面清单

这些组合默认判为风险，除非能证明对比度和场景都安全：

正文对比度 < 4.5:1：任何小字号中文、脚注、URL、表格正文都禁止。
标题 / 图形 / UI 对比度 < 3:1：大标题、标签、边框、图标、数据图例都禁止。
副色当正文：例如高饱和粉、青、黄直接写在浅底上，通常会失败；副色只做 kicker、短线、编号、callout。
红 + 绿表达状态：不要只靠红绿区分成功/失败；必须加文字、图标或形状。
蓝字压红/橙底，或红/橙字压蓝底：CJK 小字边缘容易震动，除非是大号短标题且对比度足够。
两个高饱和色互为文字/背景：如亮青压亮粉、亮黄压亮蓝；用中性色隔开。
同色相低明度差：同一 hue 只改一点点亮度/饱和度，容易看成一片；相邻层级必须拉开亮度。
浅灰压浅底 / 深灰压深底：灰度很容易“过关感知不过关”，用脚本先算。
AI 图上裸放文字：不允许直接在复杂图片上放正文；加 40-55% 深色遮罩或独立文字底板。
一页超过 3 个高饱和主视觉色：分类图例可以多色，普通内容页不行。
全 deck 只有一个 hue 家族且没有中性深浅阶：会变成单色糊；至少保留深底、浅底、正文色、弱化文字色。
PptxGenJS 色号带 #：代码里始终写 "39C5BB"，不要写 "#39C5BB"。

QA 时列出实际使用的 fg/bg 对，至少检查：正文 on 浅底、正文 on 深底、标题 on 封面图遮罩、表格文字 on header、QR URL、footer、图例文字。

2.5 AI 生图 — 尺寸适配（StepFun / MiniMax）

通过 lib/ai-image.js 生成配图，自动适配 PPT 排版。StepFun 是默认和重点推荐 provider；MiniMax 作为可选补充。两者都支持国内版 / 国际版。不硬编码 API Key，从环境变量或 .env 读取。新脚本优先导入 ai-image.js；旧脚本继续导入 stepfun-image.js 也能运行（兼容 re-export）。

引入方式

import { generateSlideImage, addImageToSlide, addImageOverlay, SIZE_MAP } from "./lib/ai-image.js";

// 用法：按用途自动选比例/尺寸
const img = await generateSlideImage({
  provider: "stepfun-cn", // 推荐；也支持 stepfun-global / minimax-cn / minimax-global
  prompt: "赛博朋克城市夜景，中文发布会封面背景，留出标题区域",
  usage: "cover",
});

if (img) {
  slide.addImage({ path: img.localPath, x: 0, y: 0, w: img.pptxLayout.w, h: img.pptxLayout.h });
}

Provider 选择

优先级：

generateSlideImage({ provider: "stepfun" | "minimax" })
环境变量 PPT_IMAGE_PROVIDER 或 AI_IMAGE_PROVIDER
如果只有 MINIMAX_API_KEY，自动选择 minimax
默认 stepfun-cn，保证旧脚本行为不变，并优先走 StepFun 国内开放平台

可直接使用 region alias：

await generateSlideImage({ provider: "stepfun-cn", prompt, usage: "cover" });
await generateSlideImage({ provider: "stepfun-global", prompt, usage: "cover" });
await generateSlideImage({ provider: "minimax-cn", prompt, usage: "card" });
await generateSlideImage({ provider: "minimax-global", prompt, usage: "card" });

用途 → 尺寸映射

用途	PPT 场景	StepFun 尺寸	MiniMax 比例	PPTX (英寸)
`cover`	封面全幅背景	1360×768	16:9	`{ w:10, h:5.625 }`
`coverOverlay`	带文字遮罩的封面背景	1360×768	16:9	`{ w:10, h:5.625 }`
`hero`	上半区横幅	1360×768	16:9	`{ w:10, h:3 }`
`bannerWide`	超宽横幅	1360×768 + 裁切	21:9	`{ w:10, h:2.45 }`
`ultraWideHero`	超宽首页/章节视觉	1360×768 + 裁切	21:9	`{ w:10, h:2.8 }`
`sideStrip`	右侧竖版装饰条	768×1360	9:16	`{ w:2.5, h:4.44 }`
`card`	方形卡片配图	1024×1024	1:1	`{ w:2.5, h:2.5 }`
`cardTall`	竖版卡片配图	896×1184	3:4	`{ w:2.3, h:3.04 }`
`cardWide`	横版卡片配图	1184×896	4:3	`{ w:3.5, h:2.65 }`
`showcase`	产品/项目展示	1184×896	4:3	`{ w:3.9, h:2.95 }`
`phoneMockup`	手机竖屏 mockup	768×1360	9:16	`{ w:1.8, h:3.2 }`
`icon`	小图标/占位图	512×512	1:1	`{ w:1.5, h:1.5 }`

适配规则：

StepFun step-image-edit-2 使用官方 size 字符串：1024x1024、768x1360、896x1184、1360x768、1184x896。文档标注该字符串是 height x width，但在本 skill 中按视觉用途映射到 PPT：cover/hero 固定用 1360x768，showcase/cardWide 固定用 1184x896，phoneMockup/sideStrip 固定用 768x1360。
StepFun 当前单次文生图按 1 张处理；如需要多张候选图，循环调用，不依赖 n > 1。
MiniMax 优先使用 aspect_ratio 而不是 width/height：16:9、4:3、1:1、3:4、9:16。只有确实需要自定义像素时才传 width/height，并保证 512-2048 且能被 8 整除。
cover、hero、bannerWide、ultraWideHero、showcase、phoneMockup 不手写尺寸，统一从 SIZE_MAP 或 getImageUsageConfig() 取，避免把 MiniMax ratio 和 StepFun size 混用。
bannerWide / ultraWideHero：MiniMax 原生 21:9；StepFun 用 1360x768 生成，再按 cropPolicy 和 safeZone 放入 PPT。
返回 URL 一律立即下载到 assets/<provider>/，PPTX 只引用本地文件，避免 StepFun/MiniMax 临时链接过期。

环境变量配置

# 可选：默认生图供应商
export PPT_IMAGE_PROVIDER=stepfun   # stepfun | minimax
export PPT_IMAGE_REGION=cn          # cn | global

# StepFun（国内 https://platform.stepfun.com；国际 https://platform.stepfun.ai）
export STEPFUN_API_KEY=sk-xxx
export STEPFUN_REGION=cn            # cn -> api.stepfun.com；global -> api.stepfun.ai
export STEPFUN_API_MODE=platform    # platform | step_plan
# export STEPFUN_BASE_URL=https://api.stepfun.com/v1  # 可选强制覆盖

# MiniMax（国内 https://platform.minimaxi.com；国际 https://platform.minimax.io）
export MINIMAX_API_KEY=sk-xxx
export MINIMAX_REGION=global        # cn -> api.minimaxi.com；global -> api.minimax.io
# export MINIMAX_BASE_URL=https://api.minimax.io/v1   # 可选强制覆盖

ai-image.js 会自动加载项目根目录 .env，但 shell / MCP / CI 中已有的 process.env 优先。

Provider 参数

StepFun：使用 /images/generations，按具体 size 生成，适合精确 PPT 预设。
MiniMax：使用 /image_generation，按 aspect_ratio 生成；返回 URL 时工具会立即下载到本地，避免 URL 过期影响 PPT。
StepFun 国内开放平台默认 Base URL：https://api.stepfun.com/v1
StepFun 国际开放平台默认 Base URL：https://api.stepfun.ai/v1
StepFun Step Plan 国内 / 国际专属路径：https://api.stepfun.com/step_plan/v1 / https://api.stepfun.ai/step_plan/v1
MiniMax 国内 / 国际默认 Base URL：https://api.minimaxi.com/v1 / https://api.minimax.io/v1
MiniMax 可传 promptOptimizer、seed、n、subjectReference：

const img = await generateSlideImage({
  provider: "minimax",
  prompt,
  usage: "showcase",
  promptOptimizer: true,
  seed: 42,
});

StepFun 可传 steps、cfgScale、negativePrompt、textMode、seed、apiMode：

const img = await generateSlideImage({
  provider: "stepfun-cn",
  prompt,
  usage: "cover",
  steps: 8,
  cfgScale: 1.0,
  textMode: true,
});

开放平台申请与使用指南（StepFun 推荐）

选择版本：国内账号用 https://platform.stepfun.com，国际账号用 https://platform.stepfun.ai。
注册 / 登录后进入用户中心或 API Key 页面。
创建 API Key。只放在本地 .env、系统环境变量或 CI Secret，不写进源码。
普通开放平台调用用 STEPFUN_API_MODE=platform；如已订阅 Step Plan 且要走专属路径，用 STEPFUN_API_MODE=step_plan。
在构建目录创建 .env：

PPT_IMAGE_PROVIDER=stepfun
PPT_IMAGE_REGION=cn
STEPFUN_API_KEY=sk-xxx
STEPFUN_REGION=cn
STEPFUN_API_MODE=platform

先跑 npm test 验证导入、provider/region 解析、无 key 降级。
构建 PPT 时优先使用 provider: "stepfun-cn"；国际版账号改为 provider: "stepfun-global" 或设置 STEPFUN_REGION=global。

图片排版规范

深底图片上放文字 → 必须加半透明遮罩（addImageOverlay），透明度 40-50%
注意：addImageOverlay(slide, pres, { opacity: 45 }) 中的 opacity 是用户接口参数，传 40–50 的整数；内部映射到 PptxGenJS 的 transparency。不要传 0.18 这种比例值。
卡片内图片 → 上下留 0.15″ padding，用 rounding: true 圆角
封面背景图 → 叠加深色半透明矩形 + 文字层，确保文字可读
图片不贴文字 → 左右至少 0.2″ 间距
无 API Key 时 → 自动跳过生图，console.warn 提示，不阻断 PPT 生成

模型尺寸对照

Provider	模型	支持尺寸 / 比例
StepFun	`step-image-edit-2`（默认）	1024×1024, 768×1360, 896×1184, 1360×768, 1184×896
StepFun	`step-2x-large`	256×256, 512×512, 768×768, 1024×1024, 1280×800, 800×1280
StepFun	`step-1x-medium`	256×256, 512×512, 768×768, 1024×1024, 1280×800, 800×1280
MiniMax	`image-01`	1:1, 16:9, 4:3, 3:2, 2:3, 3:4, 9:16, 21:9

3. 中文字体默认

标题 & 正文字体：Microsoft YaHei（LibreOffice 和 PowerPoint 渲染都 OK，CJK + Latin 都支持）
等宽：Consolas（URL / 代码 / 框架名）
CJK 安全字号（16:9，10×5.625″）：

用途	字号	说明
封面主标题（CJK + 括号）	44pt	56pt 会溢出——「」是全角，占位多
章节标题	28pt	9″ 宽下一行中文够用
卡片 / 引擎标题	16pt bold
正文	11–12pt	中文 11pt 仍很清晰
大数字 stat	60–80pt	Latin / 数字，放心放大
Kicker（英文大写）	11–12pt + `charSpacing: 4–6`	竖线序号下的拉丁字母 letter-spacing

CJK 坑：

大量「」括号的标题，比纯 CJK 标题字号要再小 ~25%
估算：CJK 字符宽度 ≈ fontSize × 0.95pt
charSpacing 对中文很丑，只在英文 kicker 上加

4. 重复装饰 = 品牌一致性

把三个 helper 函数提出来，每页都调用：

// 1. 顶部 + 底部条纹 —— deck 的心跳
function mikuStripe(slide) {
  slide.addShape(pres.shapes.RECTANGLE, { x:0, y:0, w:SW, h:0.08, fill:{color:C.miku}, line:{color:C.miku} });
  slide.addShape(pres.shapes.RECTANGLE, { x:0, y:0.08, w:SW, h:0.025, fill:{color:C.pink}, line:{color:C.pink} });
  slide.addShape(pres.shapes.RECTANGLE, { x:0, y:SH-0.04, w:SW, h:0.04, fill:{color:C.miku}, line:{color:C.miku} });
}

// 2. 章节标题 —— 副色 kicker 方块 + 主/副色双段下划线
function sectionTitle(slide, kicker, title) {
  slide.addShape(pres.shapes.RECTANGLE, { x:0.5, y:0.45, w:0.18, h:0.18, fill:{color:C.pink}, line:{color:C.pink} });
  slide.addText(kicker, { x:0.75, y:0.38, w:6, h:0.3, fontSize:12, bold:true, color:C.miku, charSpacing:4, margin:0 });
  slide.addText(title, { x:0.5, y:0.68, w:9, h:0.7, fontSize:28, bold:true, color:C.ink, margin:0 });
  slide.addShape(pres.shapes.RECTANGLE, { x:0.5, y:1.42, w:0.9, h:0.05, fill:{color:C.miku}, line:{color:C.miku} });
  slide.addShape(pres.shapes.RECTANGLE, { x:1.42, y:1.42, w:0.3, h:0.05, fill:{color:C.pink}, line:{color:C.pink} });
}

// 3. 页脚：品牌行 + N/total
function footer(slide, n, total) {
  slide.addText("Brand · Subtitle", { x:0.5, y:SH-0.35, w:6, h:0.25, fontSize:9, color:C.muted, margin:0 });
  slide.addText(`${n} / ${total}`, { x:SW-1.2, y:SH-0.35, w:0.7, h:0.25, fontSize:9, color:C.muted, align:"right", margin:0 });
}

这三件套，能把 10 页临时排版瞬间变成一套有设计的 deck。

💡

"长主色 + 短副色" 双段下划线是性价比最高的品牌符号。不需要任何图片素材，立刻有「设计过」的观感。

5. Slide 类型菜单

不要每页重新发明 layout。从这些里挑。每个布局的必需槽位（stripe / title / footer / pageBadge / image）和允许的生图 usage 已登记在 references/layout-slots.md —— 那是一份可被 scripts/render-qa.mjs --contract 校验的契约，相当于 HTML deck 的 data-layout 注册表。交付前用 render-qa 跑一遍，缺槽位会报 P2。

基础布局（无图）

#	类型	何时用	核心元素
1	封面（深底）	第 1 页	角落半透明大椭圆 + kicker 胶囊 + 多行堆叠主标题 + 强调 bar + 作者块
2	引言 + 三支柱	定位 / 定义	带副色左 bar 的大引用卡 + 下方 3 个图标圆 mini-card
3	双卡 + verdict	两股对比力量	上 2 张白卡 + 下方一个深底 callout 写「所以呢」
4	条纹表格	3–5 行对比	主色 header bar + 交替白 / paperAlt 行 + 副色编号圆圈
5	矩阵	映射 / 同构	N 列 × 主/副/白横向色带网格
6	项目展示	突出某个项目	左侧深色卡 + 巨型数字 stat + 右侧 2×3 特性网格
7	双栏映射	A ↔ B 等价	两侧 header bar + 交替行 + 中间箭头线
8	问题堆叠	讨论提问	Q1/Q2/Q3 卡堆叠 + 彩色字母圆 + 左侧色 bar
9	收尾 + QR（深底）	最终 CTA	双色大标题 + 左侧联系列表 + 右侧 QR 卡（带框）

带图布局（AI 生图增强）

#	类型	何时用	核心元素 + 生图
1a	封面（深底+背景图）	需要视觉冲击	`cover` 1360×768 全幅背景 + 深色遮罩 + 文字层
3a	双卡 + 配图 + verdict	对比 + 视觉辅助	每张白卡嵌 `card` 1024×1024 方形图
3b	双卡 + 竖版配图 + verdict	对比 + 竖版展示	白卡嵌 `cardTall` 896×1184 竖版图
6a	项目展示 + 配图	产品/界面展示	左侧 `cardWide`/`showcase` 1184×896 图 + 右侧特性网格
6b	项目展示 + 竖版 mockup	手机 App 展示	左侧 `phoneMockup` 768×1360 + 右侧特性
7a	双栏映射 + 侧栏图	映射 + 装饰	右侧 `sideStrip` 768×1360 竖版装饰条

用 8–10 张。一个 deck 不要超过 5 种 layout，否则视觉碎片化。

带图布局示例代码

1a. 封面（深底+背景图）

const coverImg = await generateSlideImage({
  prompt: "抽象科技流动线条，深蓝色调，初音未来风格",
  usage: "cover",
});

const slide = pres.addSlide();
if (coverImg) {
  slide.addImage({ path: coverImg.localPath, x: 0, y: 0, w: 10, h: 5.625 });
  addImageOverlay(slide, pres, { color: C.navy, opacity: 45 });
} else {
  slide.background = { fill: C.navy };
}

// 文字层（不受背景图影响）
slide.addText(kicker, { ... });
slide.addText(mainTitle, { ... });
mikuStripe(slide);

3a. 双卡 + 配图 + verdict

const cardImg1 = await generateSlideImage({ prompt: "自然语言文本界面", usage: "card" });
const cardImg2 = await generateSlideImage({ prompt: "编程代码界面", usage: "card" });

const slide = pres.addSlide();
sectionTitle(slide, "CONTRAST", "语言 vs 编程");

// 左卡片
slide.addShape(pres.shapes.RECTANGLE, { x:0.5, y:1.7, w:4.4, h:2.0, fill:{color:C.white}, shadow:... });
if (cardImg1) {
  slide.addImage({ path: cardImg1.localPath, x: 0.7, y: 2.2, w: 1.5, h: 1.5, rounding: true });
}
slide.addText("标题", { x:2.3, y:2.25, w:2.4, h:0.45, fontSize:16, bold:true, color:C.ink });

6a. 项目展示 + 配图

const showcaseImg = await generateSlideImage({ prompt: "现代化仪表盘界面", usage: "showcase" });

const slide = pres.addSlide();
sectionTitle(slide, "SHOWCASE", "核心产品");

if (showcaseImg) {
  slide.addImage({ path: showcaseImg.localPath, x: 0.5, y: 1.75, w: 3.9, h: 2.95, rounding: true });
} else {
  slide.addShape(pres.shapes.RECTANGLE, { x:0.5, y:1.75, w:3.9, h:2.95, fill:{color:C.navy} });
}
// 右侧特性网格 ...

6. 无网络生成二维码

沙箱默认无网络——pip install qrcode 会失败。用 reportlab 内藏的 QR 编码器（预装）+ PIL 自己栅格化：

from reportlab.graphics.barcode.qrencoder import QRCode, QRErrorCorrectLevel, QR8bitByte
from PIL import Image

data = "https://github.com/CacinieP"
for v in range(1, 20):
    try:
        qr = QRCode(v, QRErrorCorrectLevel.H)
        qr.addData(QR8bitByte(data))
        qr.make()
        modules = qr.modules
        break
    except Exception:
        continue

n, scale, border = len(modules), 16, 4
size = (n + border*2) * scale
img = Image.new("RGB", (size, size), (255,255,255))
px = img.load()
for r in range(n):
    for c in range(n):
        if modules[r][c]:
            for dy in range(scale):
                for dx in range(scale):
                    px[(c+border)*scale+dx, (r+border)*scale+dy] = (0,0,0)
img.save("/data/qr.png")

然后在 PptxGenJS 中嵌入：

slide.addImage({ path: "/data/qr.png", x: 6.95, y: 2.15, w: 2.4, h: 2.4 });

给 QR 加框：白色圆角卡 + 主色边 + 主色顶 strip 写 SCAN · 扫码访问，URL 用等宽字体放在码下方。深底上裸放 QR 像故障。

7. 踩过的坑

CJK 主标题溢出 — 封面 56pt + 全角「」导致「训练场」换到第三行撞副标题。修：44pt 一行，或拆成有意识的多行 + 间距
超窄文本框被裁 — 0.1″ 宽的竖向标签会渲染成断行碎片。别用低于 0.4″ 的文本容器；要竖排就用 rotate，不用窄盒
reportlab.renderPM 在沙箱里坏的（缺 rlPyCairo）。不要用 renderPM.drawToFile，手动 PIL 栅格化
pip install 没用。先看预装列表，不要为没装的库设计架构
LibreOffice CJK 字体 fallback：找不到 Microsoft YaHei 会落到 Noto Sans CJK SC，也 OK。别用渲染管线没有的冷门中文字体
shadow 对象复用会污染第二个形状。一定写成 () => ({...}) 工厂函数，每次形状调用
颜色不要带 #：永远 "39C5BB" 不是 "#39C5BB"。透明度也不要编进 8 位 hex，用 opacity: 0.18
PptxGenJS 没有 TRIANGLE 形状 → 用 LINE 替代箭头指示
封面背景图比例 — 必须用 1360×768（16:9）精确匹配幻灯片，其他比例会裁切或留白

8. 强制 QA 循环

先跑自动化门禁，再看图。 三条命令构成 P0 gate，任一不过都不要交付：

# 1. PPTX 渲染 + 启发式 QA —— 溢出 / 遮挡 / 越界 / 图文比例 / 缺页码 badge / 版式契约
#    P0 findings 退出码 1。本机没装 soffice 时静态检查仍会跑。
npm run qa:render -- output/deck.pptx --fix-hints \
  --contract references/layout-slots.md

# 2. 可编辑性 / CJK 字体 / 宏 / 主题完整性
python3 ../../scripts/pptx-editable-check.py output/deck.pptx

# 3. 色板对比度门禁（WCAG AA）
node ../../scripts/color-qa.mjs --palette <你的色板> --role body

生成前用免渲染估算器预防 CJK 溢出（比渲染一轮再发现快得多）：

node ../../scripts/cjk-overflow-check.mjs --text "你的标题" --font-size 44 --box-width 9

自动化门禁全绿后，再做视觉核对（渲染成图逐页挑刺）：

soffice --headless --convert-to pdf deck.pptx
pdftoppm -jpeg -r 100 deck.pdf slide

8.1 对比度自检（WCAG AA）

在视觉 QA 前，先用 JS 脚本量化检查所有文字/背景对比度：

// 对比度计算工具 — 在 QA 前运行一次
function hexToRgb(hex) {
  const h = hex.replace("#","");
  return { r: parseInt(h.slice(0,2),16), g: parseInt(h.slice(2,4),16), b: parseInt(h.slice(4,6),16) };
}
function relativeLuminance({r,g,b}) {
  const [rs,gs,bs] = [r,g,b].map(c => {
    const s = c / 255;
    return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
}
function contrastRatio(hex1, hex2) {
  const l1 = relativeLuminance(hexToRgb(hex1));
  const l2 = relativeLuminance(hexToRgb(hex2));
  const lighter = Math.max(l1, l2), darker = Math.min(l1, l2);
  return (lighter + 0.05) / (darker + 0.05);
}

// 检查当前色板的关键对比度对
const checks = [
  { label: "深底+白字", fg: "#FFFFFF", bg: "#"+C.darkBg, min: 4.5 },
  { label: "浅底+正文", fg: "#"+C.muted, bg: "#"+C.lightBg, min: 4.5 },
  { label: "主色块+文字", fg: "#"+C.ink, bg: "#"+C.dominant, min: 3.0 },
  { label: "浅底+深字", fg: "#"+C.textOnLight, bg: "#"+C.lightBg, min: 4.5 },
  { label: "深底+浅字", fg: "#"+C.textOnDark, bg: "#"+C.darkBg, min: 4.5 },
];
checks.forEach(c => {
  const ratio = contrastRatio(c.fg, c.bg);
  const pass = ratio >= c.min ? "✅" : "❌";
  console.log(`${pass} ${c.label}: ${ratio.toFixed(1)}:1 (需要 ≥${c.min})`);
});

标准：WCAG AA（正常文字 ≥ 4.5:1，大文字 ≥ 3.0:1）。任何 ❌ 都要调整色值。

8.2 视觉 QA 清单

然后把每张 slide 图加载到 transcript，用挑刺的眼光看：

只重渲染问题页：

pdftoppm -jpeg -r 100 -f N -l N deck.pdf slide-fix

**至少完成一轮「修复 → 复查 → 无新问题」**才算完工。

9. 默认文件布局

skills/themed-cn-pptx/
  skill.md                     # 本文档
  references/
    aesthetic-rules.md         # 视觉系统与美学负面清单
    image-constraints.md       # 生图 manifest、尺寸、负面 prompt
    layout-slots.md            # 可校验的布局槽位契约（render-qa --contract 消费）
  recipes/                     # 锁定审美 recipe：可直接跑的 theme + marks + 布局
    recipe-editorial-grid.mjs  #   中文编辑设计风（克制、发丝线、低饱和）
    recipe-dark-launch.mjs     #   深底发布风（大对比、hero 配图、CTA/QR）
    design-contract.md         #   editorial-grid 锁定项说明
    design-contract-darklaunch.md
  lib/
    ai-image.js                # StepFun / MiniMax 通用生图工具库
    stepfun-image.js           # 旧脚本兼容入口，re-export ai-image.js
    cjk-text.js                # CJK 宽度估算（QA 工具共享）
    pptx-shapes.js             # OOXML slide 解析器（render-qa 用）
    zip-reader.js              # 零依赖 .pptx zip 读取器（render-qa 用）
  examples/
    build_<theme>.js           # 可选：示例构建脚本

项目构建目录：

/data/
  build_<theme>.js             # PptxGenJS 脚本
  lib/
    ai-image.js                # 生图工具库副本
    stepfun-image.js           # 兼容旧脚本时才需要
  assets/
    stepfun/                   # StepFun 生成的图片
      YYYY-MM-DD-xxxx.png
    minimax/                   # MiniMax 生成的图片
      YYYY-MM-DD-xxxx.png
  qr.png                       # 收尾页二维码
  <output>.pptx                # 最终交付
  <output>.pdf                 # QA 渲染
  slide-*.jpg                  # QA 视觉

把 .js 和 .pptx 一起留着，用户后续要微调时可以局部改，不用从零重来。

10. 完工前清单

通用

调色板只有一个主色，不互相竞争
每页都有 stripe + sectionTitle + footer（封面/收尾除外）
封面主标题不溢出
二维码能扫（带边框 + 高纠错 + 框在白底里）
页数上限遵守
用户要求隐去的话题确实隐去
完整 PDF → JPG QA 至少一轮且问题已修
.pptx 可编辑（无奇怪嵌入、无图片化的文字）

对比度与无障碍

深底 + 白字对比度 ≥ 4.5:1（WCAG AA）
浅底 + 正文（muted）对比度 ≥ 4.5:1
主色块 + 白字对比度 ≥ 3.0:1
副色未用于正文大段文字
背景图上有文字时，叠加半透明遮罩（opacity 40-50%）
高饱和度颜色未用于大面积背景区域

AI 生图

背景图用 1360×768（16:9）匹配幻灯片，不裁切不留白
MiniMax 背景图用 16:9，StepFun 背景图用 1360×768，均匹配幻灯片
卡片配图比例与 PPT 布局一致（1:1 → card, 4:3 → cardWide/showcase, 3:4 → cardTall）
背景图上有文字时，叠加半透明遮罩确保可读
卡片内图片与文字间距 ≥ 0.15″，不贴死
所选 provider 的 API key 未设置时不报错，优雅降级为纯色/占位

改 PPT 路径额外检查

原有未修改页的内容和排版保持不变
修改后的色板在所有页（含未改页）上一致
新增配图与已有视觉风格协调

从文稿到 PPT 路径额外检查

文稿核心信息全部覆盖，无遗漏
页面逻辑顺序（定位→背景→理论→展示→讨论→收尾）合理
每页信息密度适中，不堆砌