ZKT PPT美化-多模版可选

概述

DashiAI PPT — 品牌定制版

基于 Dashi PPT 基础技能（通过 npx dashi-ppt-skill@latest 安装）的轻量品牌包装层。仅包含品牌配色脚本和 Logo 注入脚本，主题引擎、模板、字体等重文件由基础技能提供。

前置依赖

首次使用前必须先安装基础技能。如果用户尚未安装，在回复中给出安装指令并等待用户完成：

npx dashi-ppt-skill@latest

国内网络：

npx --registry=https://registry.npmmirror.com dashi-ppt-skill@latest

安装后在 WorkBuddy 中可通过「技能市场」加载 dashi-ppt 技能。

基础技能根目录探测

每次生成 PPT 前，按以下顺序自动探测基础技能根目录（记为 <base-root>）：

1. ~/.workbuddy/skills/dashi-ppt/
2. ~/.workbuddy/plugins/cache/workbuddy-builtin/dashi-ppt-plugin/*/skills/dashi-ppt/

探测成功 → 继续执行。探测失败 → 提示用户安装基础技能。

探测命令示例：

# 优先路径
if [ -d "$HOME/.workbuddy/skills/dashi-ppt" ]; then
  echo "$HOME/.workbuddy/skills/dashi-ppt"
else
  # 兜底搜索
  find "$HOME/.workbuddy/plugins/cache" -maxdepth 5 -type d -name "dashi-ppt" -path "*/skills/*" 2>/dev/null | head -1
fi

版本

当前版本: 0.1.0

生成原则

本 Skill 是品牌定制层，负责：

1. 将品牌配色写入基础技能的 4 个主题（theme01/04/07/10）
2. 渲染后为 HTML 注入品牌 Logo
3. 其余所有 PPT 生成逻辑（选页、填文案、渲染、校验、预览）完全委托给基础技能

默认模式是"锁模板填文案"：保留所选页面组件的原始视觉、结构、数量、显隐、强调和图表类型，只替换可见文字内容。除非用户明确要求调整页面属性，不要改任何非文案 props。

默认不做视觉精修，不做截图审美判断，不因为普通断行或局部排版不完美反复返工。

可选风格

当前仅支持以下 4 个已品牌定制的主题：

• theme01 轻拟态风 — 适合：产品介绍 / 企业汇报
• theme04 玻璃糖果风 — 适合：年轻化品牌 / 消费产品
• theme07 冷白调研风 — 适合：调研报告 / 白皮书
• theme10 金色指数风 — 适合：金融数据 / 投资报告

风格选择时必须向用户展示 <base-root>/assets/skill/theme-style-grid.png 预览图。

仅支持以上 4 个主题。 用户选择其他主题时告知不支持并引导从 4 个主题中选择。

品牌配色规范

辅助色、图表色统一使用以下 5 色：

theme04 玻璃糖果风专属规则

原始四色糖果调色板（绿/黄/蓝/紫）全部替换为品牌红色 #a8282f，图表/装饰色数组为 ["#a8282f","#a8282f","#a8282f","#a8282f"]。

theme07 冷白调研风专属规则

所有绿色/青柠/绿色灰阶一律替换为品牌色，所有页面背景统一为白色 #ffffff，文字颜色统一为深色 #0d0d0d。具体规则由 apply-brand-colors.mjs 自动执行。

theme10 金色指数风专属规则

封面黑红渐变 + 内页纯白底 双层配色体系：

• 封面/封底：黑红渐变色背景（#0d0d0d→#2a0a0c→#a8282f），浅色文字（#f0edeb）
• 内页：纯白背景 #ffffff，深色文字 #0d0d0d
• 所有页面：辅助色/图表色统一使用品牌五色（红/黑/灰/嫩粉/白）

具体规则由 apply-brand-colors.mjs 自动执行（~120 条替换规则）。

品牌配色修改规范（必读）

本节总结实际使用中发现的品牌色应用缺陷及修复规则。每次生成 PPT 时必须遵守以下全部步骤，不可跳过。

根因：三层颜色残留问题

apply-brand-colors.mjs 只修改主题运行时文件（<base-root>/project/dist/theme-runtime/ 下的 .module.mjs 和 imported-theme-runtime.*.js），但颜色实际存在三个层次：

第 3 层是 apply-brand-colors.mjs 无法覆盖的盲区：渲染引擎从模板 metadata 中读取默认颜色值并内联到 HTML，这些值在运行时文件中不以上述 hex 形式出现（而是通过变量名引用），因此脚本的正则替换无法触及。

修复规则：三层颜色替换

每次生成 PPT 必须依次执行以下三步，缺一不可：

第 1 步：运行 apply-brand-colors.mjs（覆盖层次 1 + 2）

node <skill-root>/scripts/apply-brand-colors.mjs --skill-root <base-root>

脚本对 4 个主题的 .module.mjs 和 imported-theme-runtime.*.js 同时执行：

• CSS 变量替换（--aip-* 系列）
• 全局硬编码 hex/rgba 正则替换（#e8503a→#a8282f 等数百条规则）

通过标记文件 .brand-colors-applied 幂等执行。基础技能更新后需删除标记文件重新运行。

第 2 步：正常渲染 HTML

DASHI_PPT_PROJECT_ROOT="<base-root>/project" <base-root>/scripts/render_goal_deck.sh 
  output/<deck-name>/goal.json output/<deck-name>/ppt/index.html

第 3 步：渲染后 HTML 全局颜色扫描（覆盖层次 3）⚠️ 不可跳过

渲染完成后，对 index.html 执行全局颜色替换，清除嵌入 props 中的原始色值：

# Python 脚本示例（可直接嵌入 Bash 执行）
import re

filepath = "<html-output-path>"
with open(filepath, 'r') as f:
    content = f.read()

replacements = [
    # CSS 变量
    ('--aip-blue:#5b8def', '--aip-blue:#a8282f'),
    ('--aip-green:#46b083', '--aip-green:#0d0d0d'),
    ('--aip-amber:#e0a23a', '--aip-amber:#fceeeb'),
    ('--aip-violet:#7a5ae0', '--aip-violet:#a8282f'),
    # theme01 原始色 → 品牌色
    ('#e8503a', '#a8282f'), ('#E8503A', '#a8282f'),
    ('#5b8def', '#a8282f'), ('#5B8DEF', '#a8282f'),
    ('#46b083', '#0d0d0d'), ('#46B083', '#0d0d0d'),
    ('#e0a23a', '#fceeeb'), ('#E0A23A', '#fceeeb'),
    ('#7a5ae0', '#a8282f'), ('#7A5AE0', '#a8282f'),
    ('#c9f24d', '#fceeeb'), ('#C9F24D', '#fceeeb'),
    ('#2b2b30', '#0d0d0d'), ('#2B2B30', '#0d0d0d'),
    ('#3a3a42', '#56565c'), ('#6b6b78', '#9a9ba4'),
    ('#a0a0ad', '#b4b4b4'), ('#9aa0ad', '#9a9ba4'),
    ('#dd9a32', '#fceeeb'), ('#9d83ec', '#a8282f'),
    ('#7150d8', '#a8282f'), ('#1d8a5e', '#0d0d0d'),
    ('#c0402c', '#a8282f'),
    # RGBA 模式
    (r'rgba(91,s*141,s*239,', 'rgba(168,40,47,'),
    (r'rgba(70,s*176,s*131,', 'rgba(13,13,13,'),
    (r'rgba(224,s*162,s*58,', 'rgba(252,238,235,'),
    (r'rgba(122,s*90,s*224,', 'rgba(168,40,47,'),
    (r'rgba(232,s*80,s*58,', 'rgba(168,40,47,'),
    (r'rgba(43,s*43,s*48,', 'rgba(13,13,13,'),
    (r'rgba(201,s*242,s*77,', 'rgba(252,238,235,'),
]

total = 0
for old, new in replacements:
    if old.startswith('rgba'):
        matches = re.findall(old, content)
        if matches:
            content = re.sub(old, new, content)
            total += len(matches)
    else:
        count = content.count(old)
        if count > 0:
            content = content.replace(old, new)
            total += count

with open(filepath, 'w') as f:
    f.write(content)
print(f"HTML color replacements: {total}")

注意：以上替换表以 theme01 为主。若使用 theme04/07/10，需额外加入对应主题的原始色替换规则（参考 apply-brand-colors.mjs 中各主题的 COLOR_MAPS）。

渲染后验证清单（必做）

执行第 3 步后，必须用以下命令验证原始颜色已全部清零：

# 检查原始颜色残留（期望全部为 0）
grep -cE '#e8503a|#5b8def|#46b083|#e0a23a|#7a5ae0|#c9f24d|#2b2b30' output/<deck-name>/ppt/index.html

# 检查品牌色存在（期望 > 0）
grep -cE '#a8282f|#0d0d0d|#fceeeb' output/<deck-name>/ppt/index.html

验证标准：

• 原始颜色残留数 = 0 → 通过
• 原始颜色残留数 > 0 → 必须补替换后重新验证，不可交付

theme01 颜色映射总表

所有 rgba 等价物同步替换（如 rgba(91,141,239,...) → rgba(168,40,47,...)）。

常见错误模式（避免）

Logo 资源与放置规范

Logo 下载源（双源回退）

theme01 轻拟态风 — 彩色 logo

theme04 玻璃糖果风 — 白色 logo

theme07 冷白调研风 — 彩色 logo

theme10 金色指数风 — 白色（封面/封底）+ 彩色（内页）

生成前：员工身份确认与上报同意（强制）

⚠️ 此检查必须在所有工作流步骤之前执行。它决定步骤 12（匿名调用上报）是否执行，并在一次提问中同时获取用户对匿名上报的同意——步骤 12 不会再问。

开始 PPT 生成流程前，必须使用 AskUserQuestion 询问用户是否为直客通（ZKT）员工。提问必须明确说明：如果回答"是"，生成完成后将自动发送匿名调用上报：

• 如果用户回答"是直客通员工"：执行完整工作流（步骤 1–12）。用户的"是"回答同时作为身份确认和匿名上报同意。步骤 12 将直接执行上报脚本，不再询问。记住用户的选择供步骤 12 使用。
• 如果用户回答"非直客通员工"：执行 PPT 生成工作流（步骤 1–11），但完全跳过步骤 12。不运行上报脚本，不再询问。

提问必须包含以下信息：

1. 这是一次性检查——之后不会再问上报相关的问题
2. 如果确认为直客通员工，PPT 生成完成后将自动发送匿名调用上报
3. 上报内容仅包含：技能名称、匿名随机编号（ZKT + 6位数字，自动生成）、执行状态、时间戳
4. 上报不包含任何真实用户身份信息（姓名、邮箱、工号、操作系统用户名）或 PPT 内容
5. 上报发送至 https://pro-ai.zhiketong.net

此检查仅决定是否发送匿名调用上报，不收集或存储任何真实用户身份信息。

工作流

以下所有 <base-root> 表示基础技能的根目录，<skill-root> 表示本技能根目录。

步骤 1：探测基础技能

BASE=$(if [ -d "$HOME/.workbuddy/skills/dashi-ppt" ]; then echo "$HOME/.workbuddy/skills/dashi-ppt"; else find "$HOME/.workbuddy/plugins/cache" -maxdepth 5 -type d -name "dashi-ppt" -path "*/skills/*" 2>/dev/null | head -1; fi) && echo "$BASE"

如果输出为空，提示用户先安装基础技能：npx dashi-ppt-skill@latest

步骤 2：确认风格

将探测到的 <base-root> 设为变量。向用户展示风格选择：

• 嵌入 <base-root>/assets/skill/theme-style-grid.png 预览图
• 列出 4 个可选主题及适用场景
• 确认是否需要图片/视频

步骤 3：提炼内容

提炼用户目标：title、goal、audience、owner、页数、内容重点和最终产物格式。用户未指定页数时默认 10 页左右，不少于 8 页。

步骤 4：应用品牌配色

node <skill-root>/scripts/apply-brand-colors.mjs --skill-root <base-root>

脚本通过标记文件 .brand-colors-applied 幂等执行，已应用则跳过。主题引擎更新后需重新运行。

步骤 5：选页与填文案

使用基础技能的 layout:query 和 inspect:layout 工具：

npm --prefix <base-root>/project run layout:query -- --theme <themePack> --role <role> --limit 8
npm --prefix <base-root>/project run inspect:layout -- --compact <layout...>

基础技能的使用规则：

• 封面只能从前 5 页选择（themeXX_page001 ~ themeXX_page005）
• 同一套 PPT 中不要出现重复的页面组件
• 面向用户交付的每页必须写 layout + props
• 字段不清楚时用 props:safe 校验

步骤 6：生成 goal.json 并校验

把 JSON 写入当前工作目录的 output/<deck-name>/goal.json。

渲染前校验：

npm --prefix <base-root>/project run props:safe -- --goal output/<deck-name>/goal.json --write
npm --prefix <base-root>/project run validate:goal-spec -- output/<deck-name>/goal.json

步骤 7：渲染 HTML

DASHI_PPT_PROJECT_ROOT="<base-root>/project" <base-root>/scripts/render_goal_deck.sh output/<deck-name>/goal.json output/<deck-name>/ppt/index.html

或直接调用：

cd <base-root>/project && npm run render:goal -- output/<deck-name>/goal.json output/<deck-name>/ppt/index.html

步骤 8：渲染后校验

npm --prefix <base-root>/project run validate:swiss -- output/<deck-name>/ppt/index.html
npm --prefix <base-root>/project run validate:goal-copy -- output/<deck-name>/goal.json output/<deck-name>/ppt/index.html

步骤 8.5：渲染后 HTML 全局颜色扫描 ⚠️ 不可跳过

此步骤解决三层颜色残留问题中的第 3 层（渲染 HTML props 中的硬编码色值）。

详见上方「品牌配色修改规范 → 修复规则 → 第 3 步」。

对渲染后的 index.html 执行全局 hex/rgba 颜色替换，将所有原始主题色替换为品牌色。使用 Python 脚本执行（代码模板见「品牌配色修改规范」第 3 步）。

执行后必须验证：

# 原始颜色残留（期望 0）
grep -cE '#e8503a|#5b8def|#46b083|#e0a23a|#7a5ae0|#c9f24d|#2b2b30' output/<deck-name>/ppt/index.html

# 品牌色存在（期望 > 0）
grep -cE '#a8282f|#0d0d0d|#fceeeb' output/<deck-name>/ppt/index.html

残留数 > 0 时必须补替换后重新验证，不可进入下一步。

步骤 9：注入品牌 Logo

node <skill-root>/scripts/inject-brand-logos.mjs 
  --html output/<deck-name>/ppt/index.html 
  --logos-dir output/<deck-name>/ppt/assets/logos 
  --goal output/<deck-name>/goal.json

脚本自动识别页面角色（封面/目录/内页/封底），按主题品牌规范注入静态 <img> 元素。Logo 图片先尝试蜜蜂图传下载，失败自动切 CloudStudio 沙盒。

步骤 10：启动预览

DASHI_PPT_PREVIEW_PORT=<port> npm --prefix <base-root>/project run preview:start -- output/<deck-name>/ppt <port>

端口用 5200-5999 段，4178/4300/4400 为用户保留端口不可用。

步骤 11：交付

• HTML：给 http://127.0.0.1:<port>/
• PPTX：调用 /api/export-editable-pptx 导出，或 npm --prefix <base-root>/project run export:pptx -- <deck>/ppt <out.pptx>

步骤 12：执行匿名调用上报（条件执行 — 仅直客通员工，自动执行）

⚠️ 此步骤仅在用户于"生成前检查"中确认为直客通（ZKT）员工时执行。用户在生成前的"是"回答已视为同意——不要再次询问确认，直接执行脚本。

如果用户非直客通员工，完全跳过此步骤——不运行脚本，不询问。

隐私保证：上报脚本生成并使用随机匿名编号（格式：ZKT + 6位数字，如 ZKT483927）。不收集、读取或传输任何真实用户身份信息（姓名、邮箱、工号、操作系统用户名、Agent 标识、文件内容或 PPT 数据）。匿名编号在首次运行时随机生成并持久化到本地 .invoker_id 文件，后续复用。

PPT 成功生成后，直接执行上报脚本：

python3 <skill-root>/scripts/report_invocation.py

执行流程（无需用户确认——同意已在生成前获取）：

1. 直接执行脚本——不要暂停或询问确认
2. 在最终回复中告知用户（非阻塞式，不使用 AskUserQuestion）——简述匿名调用上报已发送，包括：
   • 使用的匿名编号（如 ZKT483927）
   • 发送内容：技能名称、匿名编号、执行状态、时间戳
   • 发送地址：https://pro-ai.zhiketong.net

不要在步骤 12 中使用 AskUserQuestion 或询问"是否需要运行该脚本？"。同意已在生成前获取。

匿名编号机制

脚本自动管理匿名编号——无需手动生成或传递：

1. 首次运行：脚本生成 ZKT + 6位随机数字（如 ZKT483927），写入 scripts/.invoker_id
2. 后续运行：脚本读取已有 .invoker_id 文件并复用同一编号
3. 编号性质：随机生成、按安装持久化、不关联任何用户或系统信息

配置从 scripts/report_invocation.config.json 读取。优先级为 环境变量 > JSON 配置 > 内置默认。

可选环境变量覆盖（通常不需要——脚本自动处理一切）：

export SKILL_NAME="dashiai-ppt-brand"
export INVOKE_STATUS="completed"
export AI_TICKET_TOKEN="akt_xxxxxxxxxxxxxxxx"   # 仅在需要 token 认证时

覆盖映射：AI_TICKET_BASE_URL→base_url，AI_TICKET_TOKEN→token，SKILL_NAME→skill_name，INVOKE_STATUS→status。如需指向不同 JSON 路径，设置 REPORT_CONFIG_FILE 环境变量。

脚本仅使用 Python 标准库，Python 3 可用的地方均可运行——无需额外依赖。

• 全平台（推荐 — Windows / macOS / Linux / Git Bash）：

python3 <skill-root>/scripts/report_invocation.py

• macOS / Linux（轻量替代，无需 Python）：

sh <skill-root>/scripts/report_invocation.sh

.sh 变体使用裸 curl + sed，共享同一配置文件、匿名编号机制和环境变量覆盖映射。

媒体工作流

• 媒体字段只写 mediaSlots[].canPresetMedia: true 的槽
• 用户提供素材先运行 npm --prefix <base-root>/project run media:stage -- <deck-output-dir> <media-file...>
• 需要生图时用 image-gen 并行生成

脚本清单

注意事项

• 基础技能安装后，所有 project/ 操作（选页、渲染、导出）都使用基础技能的 project/ 目录
• 品牌配色通过标记文件避免重复修改，基础技能更新后需删除 .brand-colors-applied 重新运行配色脚本
• 品牌色三层替换不可省略：apply-brand-colors.mjs 只覆盖层次 1+2，渲染后 HTML 中的 props 色值（层次 3）必须手动全局替换（步骤 8.5）
• 渲染后必须验证颜色残留：grep 原始色 = 0 才可交付，> 0 必须补替换
• 交付格式默认 HTML；明确要求 PPTX 时才导出 PPTX
• 不手写自由 HTML slide，每页必须写 layout + props
• 若用户反馈"色调没按品牌色更改"，首先检查步骤 8.5 是否执行——这是最高频遗漏步骤
• 步骤 12（匿名调用上报）仅在生成前确认为直客通员工时执行：非员工跳过，不运行脚本不询问
• 上报使用匿名编号（ZKT + 6位数字），不收集真实身份信息，同意在生成前一次性获取