product-storyboard

name	product-storyboard
description	使用 playwright-cli 或本地文本输入，生成面向开发者的视频分镜脚本，并输出为结构化 Markdown 文件。Triggers on "创建分镜", "生成分镜脚本", "产品分镜", "视频分镜", "storyboard", or provides a product documentation URL.
metadata	{"version":"1.3.0"}

产品分镜技能 (Product Storyboard Skill)

路径约定：{SKILL_DIR} 表示 Skill 安装目录，{WORKSPACE_DIR} 表示当前工作目录（执行目录）

前置检查

在 URL 抓取场景，先检查 playwright-cli 可用性：

if ! command -v playwright-cli &> /dev/null; then
  echo "需要安装 playwright-cli"
  echo "运行: npm install -g playwright-cli"
  echo "或使用 npx: npx playwright-cli"
fi

如果不可用，按以下顺序降级：

1. 提示安装：npm install -g playwright-cli --registry=https://registry.npmmirror.com
2. 提示使用 npx：npx playwright-cli open [url]
3. 提示用户改用本地文件或直接粘贴文本

输入参数

参数	类型	必需	说明	示例
source	string	是	内容来源：URL、文件路径或直接文本	https://docs.example.com/intro
type	enum	否	内容类型；可自动识别	product/tutorial/concept/story/interview
duration	number	否	目标总时长（分钟）	3
focus	string	否	重点功能或主题	"API 集成"
output_dir	string	否	输出根目录，默认 public/storyboard	"public/storyboard"
overwrite	boolean	否	目标目录存在时是否覆盖，默认 false	true

输出契约

输出目录必须遵循：

public/storyboard/
├── index.md              ← 分镜大纲、导航、元信息
├── visual-spec.md        ← 全局视觉规范（独立文件）
├── scenes/               ← 分镜内容
│   ├── 01.md
│   ├── 02.md
│   └── ...
└── assets/               ← excalidraw 配图输出
    └── {scene}.excalidraw

• 字段与结构约束：{SKILL_DIR}/references/storyboard-schema.md
• 文件模板：{SKILL_DIR}/references/storyboard-template.md
• 步骤验收标准：{SKILL_DIR}/references/acceptance-criteria.md

执行流程（单点确认）

仅在 Step 3 需要用户确认。Step 1-2 自动执行，Step 3 确认后连续执行 Step 4-5。

Step 1: 获取内容

支持来源：

• URL（使用 playwright-cli 抓取）
• 本地文件（Markdown/HTML/TXT）
• 用户粘贴文本

最小抓取路径见：{SKILL_DIR}/references/playwright-usage.md#mvp-最小抓取路径

输出：

• 原始正文（可截断）
• 内容摘要（建议前 300-500 字）
• 章节结构（标题层级）

Step 2: 分析内容

分析并产出：

• 核心主题
• 建议内容类型（或采用用户指定）
• 关键功能点/概念点
• 建议总时长和分镜数量区间
• 可视化素材建议（UI、代码、图表）
• 全局视觉规范建议（仅在此步骤中以文字形式输出给用户参考，不写入文件；最终文件写入统一在 Step 5 执行）：
  • 推荐画布尺寸
  • 风格基调（根据内容调性建议）
  • 配色方案和字号设定
  • 图表类型偏好

Step 3: 生成分镜大纲（唯一确认点）

先生成大纲表并向用户展示，至少包含：

• 序号、类型、标题、时长、核心内容

用户可在此阶段：

• 确认继续（进入 Step 4）
• 要求调整（增删分镜、改时长、改重点）
• 重新规划（重做大纲）

Step 4: 生成分镜内容

根据已确认大纲，生成每个分镜的完整内容草案。字段必须符合： {SKILL_DIR}/references/storyboard-schema.md

Step 5: 写入文件并校验

按输出契约写入 index.md、visual-spec.md 与 scenes/NN.md。

重要：必须严格使用 YAML frontmatter 格式

• index.md 和 visual-spec.md 必须以 --- 开头的 YAML frontmatter 包含元信息
• 禁止使用表格或 blockquote 代替 frontmatter
• 模板参考：{SKILL_DIR}/references/storyboard-template.md

visual-spec.md 必须包含全局视觉规范，字段定义见： {SKILL_DIR}/references/storyboard-schema.md#visual-spec.md-全局视觉规范契约

写入后执行最小校验：

• 文件数与大纲分镜数一致
• duration 与总时长统计一致
• 必填字段完整
• visual-spec.md 存在且 frontmatter 包含三个必填字段（canvas_size、style_tone、diagram_types），可选字段不影响校验通过

防循环机制：

• 校验失败最多重试 1 次
• 若重试后仍有问题，输出当前结果并列出未通过的检查项，不再继续修改
• 用户可根据问题清单手动调整或要求重新生成

异常处理与回退

场景	处理方式
URL 抓取失败	提示用户改用本地文件或粘贴文本
内容类型不明确	使用默认 product，并显式告知
内容过短	建议缩短为 1-3 个分镜，或补充资料
Step 3 被要求修改	回到 Step 3 重新确认，不直接覆盖生成
输出目录已存在且 overwrite=false	生成新 slug 或请求用户确认覆盖

约束原则

• 单一真源：字段约束只在 storyboard-schema.md 定义一次
• SKILL.md 只负责流程编排，不重复粘贴模板正文
• 每一步必须有可验证输出，避免“看似完成但不可复现”

端到端示例（最小可执行）

输入示例：

source: "https://docs.example.com/getting-started"
type: product
duration: 3
focus: "API 集成"
output_dir: "public/storyboard"
overwrite: false

期望执行过程：

1. Step 1 抓取内容并输出摘要与章节结构
2. Step 2 输出主题、关键要点、建议分镜数量
3. Step 3 展示大纲并等待一次确认
4. Step 4 生成全部分镜内容
5. Step 5 写入文件并通过最小校验

期望输出目录：

public/storyboard/
├── index.md
├── visual-spec.md
├── scenes/
│   ├── 01.md
│   ├── 02.md
│   └── 03.md
└── assets/
    └── 01.excalidraw

回归检查建议：

• 使用 acceptance-criteria.md 做步骤级检查
• 使用 minimal-regression-sample.md 做固定样例回归

References

文件	用途
{SKILL_DIR}/references/playwright-usage.md	文档抓取操作（MVP + 进阶）
{SKILL_DIR}/references/storyboard-schema.md	输出字段与结构约束
{SKILL_DIR}/references/storyboard-template.md	可直接套用的模板示例
{SKILL_DIR}/references/acceptance-criteria.md	Step 级验收标准
{SKILL_DIR}/references/minimal-regression-sample.md	最小回归样例与检查清单