claude-mem 插件技能 wowerpoint 实战：把单篇文档一键生成 kawaii 风格 NotebookLM 幻灯片 PDF

导读

本文讲解 claude-mem 插件内置技能 wowerpoint 的完整原理与实操：以"一篇文档进、一份 PDF 出"为铁律，调用 NotebookLM 官方 notebooklm CLI，用 kawaii 风格 prompt 加 --format detailed 默认参数，把长文档渲染为可分享的叙事型幻灯片，并通过 WOWerpoint Server 额外产出适配手机竖屏的 9:16 分享链接。读完本文，你将掌握一次性环境安装、五步端到端工作流、子代理（subagent）模板参数化、失败模式处置与"先写足源文档再生成"的单源原则，能够在 claude-mem 会话里用一句 "Wowerpoint <文件>" 交付一份可直接分享的幻灯片。技能定义文件位于 plugin/skills/wowerpoint/SKILL.md。

技能定位：单源文档驱动的幻灯片生成器

wowerpoint 是 claude-mem 插件技能体系中的一员。从仓库的 plugin/skills 目录可以看到，插件打包了 babysit、how-it-works、mem-search、smart-explore、standup、timeline-report、version-bump、mode-creator、cloud-sync 等十几个面向不同场景的技能，而 wowerpoint 承担的是"输出物加工"这一类任务：把一个文档变成一份可分享的叙事型幻灯片 PDF。仓库 CHANGELOG.md 在 v13.2.0（2026-05-12）release note 中记录了这一技能的引入，注明它"包装 notebooklm CLI 并施加 kawaii-prompt 与 --format detailed 默认值，再叠加 spawn-subagent 模式，使约 10 分钟的生成过程不会阻塞主对话"，设计评审见 PR #2430。

技能 frontmatter 里的 description 定义了 Agent 的触发语义：它面向"把单个文档渲染为可分享的叙事型幻灯片"这类请求，例如 "wowerpoint this"、"make a deck about "、"turn this report into slides"。典型触发语如下：

• "Wowerpoint "
• "Make a slide deck about "
• "Turn this report into slides"
• "Kawaii-deck this"

值得注意的是，技能刻意把边界画得很窄：只做幻灯片，不做视频和播客。SKILL.md 明确写"同一引擎出品的视频和播客质量明显更差、不在范围内"，若用户确有此类需求，应直接把用户引导到 notebooklm CLI 而不是用本技能硬做。这与 CHANGELOG.md 中"Slide-deck only"的定位描述完全一致，属于设计上主动收敛范围，避免劣质输出反噬交付质量。

环境前提与一次性安装

wowerpoint 的能力建立在两个外部工具之上：NotebookLM 官方 CLI notebooklm（Python 生态，含 Playwright 渲染依赖）与 JSON 解析器 jq。安装只在每台机器上做一次，完成后可通过下述命令跳过安装直接使用。

uv tool install --with playwright --force notebooklm-py
$(uv tool dir)/notebooklm-py/bin/playwright install chromium

• 使用 uv tool install 而非 pip：SKILL.md 的失败模式清单明确指出，现代 macOS 不再把 pip 放到 PATH 上，遇到 pip: command not found 时应改用 uv tool install。
• --with playwright 是必选项：notebooklm-py 只有在带上 Playwright 依赖时才能完成 PDF/幻灯片的浏览器渲染环节，漏装会在运行时报 Playwright not installed；补救方式就是重装带 --with playwright 的版本并执行 playwright install chromium。
• jq 用于整个工作流中的 JSON 解析：macOS 上 brew install jq，其他发行版用各自的包管理器安装。

安装完成后，认证必须由用户交互式完成、绝不可脚本化：SKILL.md 要求让用户在自己终端输入 ! notebooklm login，使 OAuth 的 ENTER 授权流程落在真实终端里（OAuth 要求浏览器/交互确认，Agent 无法代替）。这是全流程中唯一必须人工介入的环节。

从环境设计的细节也能看出该技能与 claude-mem 的深度绑定：技能运行于 claude-mem 的 Agent 会话内，其"记忆—检索—生成"链路（mem-search、sequential thinking 等）正是 wowerpoint 准备源文档时的上游工具，二者通过"先写足源文档"衔接，这一点在下一节展开。

端到端工作流：五步走

SKILL.md 把一次完整交付拆成五个阶段，其中前三步在主对话中快速完成，第四步把耗时约 10 分钟的生成交给子代理，第五步结束回合并把可观察的进度链接交给用户。

第 1 步：准备源文档——单源铁律

wowerpoint 的输入严格只有一份源文档。如果文件不存在、或内容太薄撑不起一份 deck，那么正确做法是先把它写好：结合 mem-search 与顺序推理（sequential thinking）写出长篇、叙事化、通常数千词的完整文档，而不是靠叠加多个源来掩盖源文档的单薄。这一"单源 + 先写足"原则同时出现在 SKILL.md 与 CHANGELOG.md 的 v13.2.0 说明中："Don't paper over a weak source by stacking more sources——先写一份内容全面的文档。"

对 claude-mem 用户来说，这一步天然契合：会话历史与记忆被压缩进 mem-search 之后，可以基于记忆把一份小笔记扩写成数千词的完整叙事，再交给 wowerpoint 出 deck。

第 2 步：认证预检（auth pre-flight）

正式干活前先探测认证是否有效：

notebooklm auth check 2>&1 | tail -5

若返回退出码 1 且提示 Run 'notebooklm login' to authenticate.，则按 SKILL.md 的要求立即停下并向用户说明：OAuth 只能由用户本人完成，Agent 不该尝试绕过或假装通过。

第 3 步：创建 notebook 并注入源文档

NOTEBOOK_ID=$(notebooklm create "<title>" --json | jq -r .notebook.id)
SOURCE_ID=$(notebooklm source add "<doc-path>" --notebook "$NOTEBOOK_ID" --json | jq -r .source.id)

• 命名规则：标题取源文档 H1，或取文件名主干（filename stem）；若为有日期属性的工作产物则附加日期。
• JSON 信封键名各不相同，这是 SKILL.md 特别强调的坑：create 返回对象要取 .notebook.id，source add 要取 .source.id，而稍后的 generate 要取顶层 .task_id。键名取错会拿到空字符串，而空字符串会被下游静默当成失败延续下去（详见"失败模式"一节的 task_id 空串问题），因此每一步都应从对应层级解析。

第 4 步：派生子代理，绝不阻塞主对话

生成大约需要 10 分钟，主对话永远不要同步阻塞。SKILL.md 给出的做法是用下文的子代理模板、以 run_in_background: true 在后台启动；子代理内部用 CLI 自带的 wait 系列命令完成轮询（自带退避策略），生成完毕、PDF 落盘后由完成通知回调主对话。

第 5 步：结束回合，交出可观察链接

把 notebook 的实时 URL 打印给用户，让其可围观生成进度：

https://notebooklm.google.com/notebook/<NOTEBOOK_ID>

子代理的完成通知会在文件真正落盘后触发，主对话无需也不该去猜何时完成。

输出路径规则

PDF 默认输出到源文档同目录、采用平行文件名：

<source-dir>/<source-stem>-slides.pdf

例如 reports/q3-review.md 会得到 reports/q3-review-slides.pdf。若源文档所在目录不适合作为产物目录（比如临时文件、系统路径），则回退到仓库约定的 reports/<stem>-slides.pdf。这条约定让"源文档在哪、产物就在哪"的行为可预期，也方便子代理与分享环节直接引用同一个 <OUTPUT_PATH>。

WOWerpoint Server：把 16:9 deck 变成 9:16 移动端分享链接

PDF 落盘后并非终点：子代理还会把它 POST 给 WOWerpoint Server，后者会把 16:9 的横屏 deck 转成 9:16 的移动端孪生版本并返回分享链接。按 SKILL.md 的优先级，分享 URL 才是交付给用户的主产物，磁盘上的 PDF 是备份。

这一环节依赖三个环境变量，它们是"在用户 shell 中导出、子代理继承父进程环境"的（由于继承机制，普通 export 即可生效，不需要 dotenv 加载器）：

WOWERPOINT_API_BASE=https://wowerpoint-api.<subdomain>.workers.dev
WOWERPOINT_VIEWER_BASE=https://wowerpoint-viewer.<subdomain>.workers.dev
WOWERPOINT_UPLOAD_TOKEN=<token>

任一变量缺失则静默跳过分享环节，直接把手里的 PDF 交付给用户——分享是增强项，不是阻断项。

上传必须在子代理确认 PDF 已存在于磁盘之后执行，且要完整捕获响应体以处理空 id 与 error 载荷。这里有一个 jq 的语义陷阱：当键缺失时 jq -r '.id' 会输出字面量字符串 null（而非空），所以必须始终用 .id // empty 兜底。SKILL.md 给出的健壮上传写法如下：

if [ -n "$WOWERPOINT_API_BASE" ] && [ -n "$WOWERPOINT_UPLOAD_TOKEN" ] && [ -n "$WOWERPOINT_VIEWER_BASE" ]; then
  UPLOAD_JSON=$(curl -sS --connect-timeout 10 --max-time 30 -X POST "$WOWERPOINT_API_BASE/api/decks" \
    -H "Authorization: Bearer $WOWERPOINT_UPLOAD_TOKEN" \
    -F "file=@<OUTPUT_PATH>" \
    -F "title=<TITLE>")
  DECK_ID=$(printf '%s' "$UPLOAD_JSON" | jq -r '.id // empty')
  API_ERROR=$(printf '%s' "$UPLOAD_JSON" | jq -r '.error // empty')
  if [ -n "$API_ERROR" ] || [ -z "$DECK_ID" ]; then
    echo "WOWerpoint upload warning: ${API_ERROR:-missing id}"
  else
    echo "Share URL: $WOWERPOINT_VIEWER_BASE/$DECK_ID"
  fi
fi

其中 curl 参数含义：--connect-timeout 10 限制建连超时 10 秒、--max-time 30 限制总请求 30 秒，避免上传把子代理吊死；-H "Authorization: Bearer $WOWERPOINT_UPLOAD_TOKEN" 用 Bearer token 鉴权；-F 两个字段分别携带 PDF 文件与 deck 标题。

上传接口返回的 id 是一个由标题派生的 kebab-case slug，且带随机生物后缀：例如标题为 TokenRouter Quest 会得到类似 tokenrouter-quest-hawk 的 id；若标题为空或非 ASCII，则会退化为类似 velvet-comet-tiger 的纯随机 id。最终分享链接格式为：

$WOWERPOINT_VIEWER_BASE/<id>

链接立即可用：打开时会先显示"still converting…"页面，就绪后自动刷新。转换耗时大约每页 1～2 分钟（deck 页数越多越久）。主对话的最终回复里必须打印该分享 URL。

需要留意的是，这一 URL 格式是经修复后的版本：仓库 CHANGELOG.md 在 v13.15.3 的 Fixes 中记录"wowerpoint skill: corrected the share URL format（去掉了 /d/ 路径段）"，即早期实现曾在 viewer base 与 id 之间错误插入 /d/，现已移除。若你引用旧版本文档/旧输出中的链接，应比对是否含多余路径段。

生成 prompt：默认一句话，用户原话直通

默认 prompt 只有一句话，走"温暖清晰"的 kawaii 路线：

Use kawaii characters to tell the story of <subject>. Keep it warm and clear.

其中 <subject> 用源文档 H1 或用户表述中的短语替换。若用户自己给出了 prompt，则原样透传、不做任何扩写——不添加、不润色、不"增强"。这也呼应了失败模式中的一条硬性约束：CLI 不存在 --style 参数，kawaii 风格只存在于 prompt 文本里，别指望用参数开关控制画风。

子代理模板逐段拆解

SKILL.md 提供了一段可 copy-paste、只需参数化的子代理模板，它把生成阶段压缩为"六步命令序列 + 一份简报"，是整份技能最核心的自动化骨架。下面按参数位与执行语义逐段解读。

上下文与输入参数。模板声明子代理工作目录为 <repo-absolute-path>（仓库绝对路径），并传入五个占位符：<NOTEBOOK_ID>、<SOURCE_ID>、<PROMPT>、<OUTPUT_PATH>、<TITLE>。注意父代理只负责"认证已通过 + notebook/source 已就绪"这两个前置，真正的生成全在子代理里跑。

Step 1 — 等待源就绪：notebooklm source wait <SOURCE_ID> -n <NOTEBOOK_ID> --timeout 600。退出码语义：0 = 就绪、1 = 出错、2 = 超时。若超时（600 秒），则改用 notebooklm source list -n <NOTEBOOK_ID> --json 查询状态并向主对话报告。

Step 2 — 触发生成：notebooklm generate slide-deck "<PROMPT>" --format detailed --length default --notebook <NOTEBOOK_ID> --json --retry 2。从 JSON 顶层解析 task_id（键位于顶层，不是嵌套对象）。这里 --format detailed 是 wowerpoint 对"详细叙事版 deck"的固定默认值；--retry 2 负责瞬时错误的自动重试。若最终落为 GENERATION_FAILED 或 "No result found for RPC ID"，则 sleep 300 秒后重试一次，仍失败即放弃。

Step 3 — 等待产物：notebooklm artifact wait <task_id> -n <NOTEBOOK_ID> --timeout 1800。1800 秒上限对应"最长约 30 分钟"的渲染预算，期间退避由 wait 命令自行处理。

Step 4 — 下载：notebooklm download slide-deck <OUTPUT_PATH> -a <task_id> -n <NOTEBOOK_ID>，把渲染结果写进主对话指定的输出路径。

Step 5 — 校验：ls -la <OUTPUT_PATH> 确认文件真实存在于磁盘——这一步是"再上传分享"的硬前提。

Step 6 — 上传分享：按上文"WOWerpoint Server"一节的同一套 curl + jq 模式执行；三个环境变量任一未设置就静默跳过；上传若返回 warning，不要重试——磁盘上的 PDF 已经是有效交付物。

强制约束：禁止手动轮询状态——wait 命令自带退避逻辑，手动轮询既多余又容易打爆接口；报告需简洁（200 词以内），内容包括：最终产物 ID、各阶段耗时（source wait / generation / render wait / download）、输出文件路径与大小、分享 URL（若生成）、重试或告警记录、任一步失败时的精确错误消息。

失败模式速查

SKILL.md 列出了一份精炼的排障清单，多数坑来自"CLI 行为与直觉不符"或"环境差异"，逐条对照可快速定位：

• pip: command not found —— 现代 macOS 的 PATH 上不再有 pip，改用 uv tool install。
• Playwright not installed —— 安装 notebooklm-py 时未带 --with playwright；补装后再执行 playwright install chromium。
• Run 'notebooklm login' to authenticate —— OAuth 只能由用户本人完成，Agent 必须停下交还控制权。
• task_id 被解析成空串 —— 解析错了 JSON 信封键：generate 在顶层返回 {"task_id": "..."}，别从 .notebook 或 .source 层级取。
• 限流（GENERATION_FAILED 或 "No result found for RPC ID"） —— --retry 2 覆盖瞬时抖动；若持续失败，等 5～10 分钟再试，或退回 Web UI 手动触发。
• 敏感文档被拒 —— NotebookLM 是 Google 服务，向其中注入含凭据、客户数据或未发布产品信息的源文档前，必须先向用户确认。
• --length long 不存在 —— --length 只接受 default|short 二值；用户要求"长幻灯片"时应退回 default 并向用户解释。
• 没有 --style 开关 —— kawaii 画风只存在于 prompt 文本中，不要寻找样式参数。

运营技巧：低成本重跑与 Web UI 兜底

两条运营建议直接决定这个技能的日常使用手感：

• 低成本重跑：notebook + source 一旦建好，更换 prompt 重新生成只涉及 generation + download 两段，因此复用 NOTEBOOK_ID 与 SOURCE_ID，不要每次从建 notebook 重来，能省掉重复的建库与源上传时间。
• Web UI 兜底：若生成被限流超过约 30 分钟，打开 notebook URL，在 NotebookLM 网页界面手动触发一次生成，随后用 notebooklm artifact list -n <NOTEBOOK_ID> 找到产物并 download 收尾。CLI 被限流不代表网页端不可用，两条通道互为备份。

在 claude-mem 中的定位小结

wowerpoint 是 claude-mem 插件技能体系中少有的"对外交付型"技能：它不负责记忆的写入与检索，而是把 claude-mem 长期积累的会话上下文、mem-search 检索结果与顺序推理扩写出来的长文档，最终物化为一份可分享的叙事幻灯片。纵向看，它与 CHANGELOG.md 的演进记录一一对应——v13.2.0 随插件扩展至 12 个技能时引入（含 babysit、how-it-works、knowledge-agent、learn-codebase、make-plan、mem-search、pathfinder、smart-explore、standup、timeline-report、version-bump、wowerpoint），v13.15.3 又修复了其分享 URL 格式；技能本体则始终以 plugin/skills/wowerpoint/SKILL.md 这一份自包含的 Markdown 为唯一实现载体，运行期不依赖仓库其他代码，体现了 claude-mem"技能即文档"的轻量可插拔设计。对想要在会话中快速产出高质量叙事 deck 的用户而言，这套"单源长文档 + kawaii prompt + 后台子代理 + 移动端分享"的组合是直接可用的完整方案。