dsh-ppt 0.8.0 → 0.8.1

package/skills/dsh-ppt/references/syntax.md

@@ -1,44 +1,44 @@
-# dsh-ppt 输入语法参考（Markdown / 结构化 slides / 动效）
-
-只在需要查具体语法时读本文件；常规流程在 SKILL.md。
-
-## Markdown 解析规则
-
-`ppt_create` 与 `build-deck.mjs` 按以下规则解析 Markdown：
-
-- 第一个 `# 标题` 会成为封面标题；其后的段落/列表成为封面副标题来源。
-- 每个 `## 小节`（或更深标题）生成一页：
-  - 有 `- ` / `* ` / `1.` 列表 → `bullets` 页；
-  - 无列表且无正文 → `section` 过渡页；
-  - 有正文段落 → 正文拆句后作为 bullets。
-- 没有标题的纯文本：第一段第一句为封面副标题，后续段落按 5 句一组拆成要点页。
-- 只有一句话：自动生成「封面 → 核心观点 → 结束页」三页。
-- 需要更精细控制时使用结构化 `slides` JSON，不要和 Markdown 混用。
-
-## 进阶语法（自动识别）
-
-- **表格**：`| 列 | 列 |` 连续行（第二行 `| --- | --- |` 分隔线）→ 独立 `table` 页（主题色表头；每页 8 行数据，长表格自动续页并重复表头；最多 8 列、每格 60 字符，超限先报错）。数据对比优先用表格，别堆要点。
-- **金句**：`>` 引用块 → 独立 `quote` 页；最后一行写 `—— 出处` 会成为署名。
-- **演讲者备注**：`<!-- 备注: 这页要讲的内容 -->`（或 `<!-- note: ... -->`）附着到该页。备注不进正文：HTML 放映按 `S` 呼出备注面板，PPTX 写入原生备注（演示者视图可见）。为汇报/演讲类 deck 主动写备注（口径、数据出处、应答预案）。
-
-## 结构化 slides（高级用法）
-
-`ppt_create` 的 `slides` 与 CLI `--slides` 接受 JSON 数组：
-
-```json
-[
-  { "layout": "cover", "title": "标题", "subtitle": "副标题", "kicker": "开场", "notes": "开场先自我介绍 30 秒" },
-  { "layout": "section", "kicker": "01", "title": "背景" },
-  { "layout": "bullets", "title": "三个论点", "bullets": ["论点一", "论点二", "论点三"] },
-  { "layout": "table", "title": "业绩对比", "rows": [["大区", "营收"], ["华东", "1.2 亿"]], "notes": "强调华东增速" },
-  { "layout": "quote", "title": "慢就是快。", "subtitle": "创始人" },
-  { "layout": "statement", "title": "核心观点一句话", "subtitle": "支撑说明" },
-  { "layout": "closing", "title": "谢谢", "subtitle": "行动号召" }
-]
-```
-
-`layout` 支持 `cover | section | bullets | statement | quote | table | closing | image | image-left | image-right | chart`；每页可选 `notes`，表格用 `rows`（首行为表头）。结构化表格自动分页，备注只放第一页。分页后超过 maxSlides 会报错，最多120页。图文、图表、品牌及按页编辑见 `advanced.md`。
-
-## 动效（motion）
-
-默认 `motion: on`：HTML 放映有页间淡入与要点逐条入场；PPTX 每页原生淡入转场，`bullets` 页的要点按「点击一次出现一条」放映。交付严肃/打印场景或用户明确要静态时传 `motion: 'off'`（CLI `--motion off`），产物不含任何动画代码。
+# dsh-ppt 输入语法参考（Markdown / 结构化 slides / 动效）
+
+只在需要查具体语法时读本文件；常规流程在 SKILL.md。
+
+## Markdown 解析规则
+
+`ppt_create` 与 `build-deck.mjs` 按以下规则解析 Markdown：
+
+- 第一个 `# 标题` 会成为封面标题；其后的段落/列表成为封面副标题来源。
+- 每个 `## 小节`（或更深标题）生成一页：
+  - 有 `- ` / `* ` / `1.` 列表 → `bullets` 页；
+  - 无列表且无正文 → `section` 过渡页；
+  - 有正文段落 → 正文拆句后作为 bullets。
+- 没有标题的纯文本：第一段第一句为封面副标题，后续段落按 5 句一组拆成要点页。
+- 只有一句话：自动生成「封面 → 核心观点 → 结束页」三页。
+- 需要更精细控制时使用结构化 `slides` JSON，不要和 Markdown 混用。
+
+## 进阶语法（自动识别）
+
+- **表格**：`| 列 | 列 |` 连续行（第二行 `| --- | --- |` 分隔线）→ 独立 `table` 页（主题色表头；每页 8 行数据，长表格自动续页并重复表头；最多 8 列、每格 60 字符，超限先报错）。数据对比优先用表格，别堆要点。
+- **金句**：`>` 引用块 → 独立 `quote` 页；最后一行写 `—— 出处` 会成为署名。
+- **演讲者备注**：`<!-- 备注: 这页要讲的内容 -->`（或 `<!-- note: ... -->`）附着到该页。备注不进正文：HTML 放映按 `S` 呼出备注面板，PPTX 写入原生备注（演示者视图可见）。为汇报/演讲类 deck 主动写备注（口径、数据出处、应答预案）。
+
+## 结构化 slides（高级用法）
+
+`ppt_create` 的 `slides` 与 CLI `--slides` 接受 JSON 数组：
+
+```json
+[
+  { "layout": "cover", "title": "标题", "subtitle": "副标题", "kicker": "开场", "notes": "开场先自我介绍 30 秒" },
+  { "layout": "section", "kicker": "01", "title": "背景" },
+  { "layout": "bullets", "title": "三个论点", "bullets": ["论点一", "论点二", "论点三"] },
+  { "layout": "table", "title": "业绩对比", "rows": [["大区", "营收"], ["华东", "1.2 亿"]], "notes": "强调华东增速" },
+  { "layout": "quote", "title": "慢就是快。", "subtitle": "创始人" },
+  { "layout": "statement", "title": "核心观点一句话", "subtitle": "支撑说明" },
+  { "layout": "closing", "title": "谢谢", "subtitle": "行动号召" }
+]
+```
+
+`layout` 支持 `cover | section | bullets | statement | quote | table | closing | image | image-left | image-right | chart`；每页可选 `notes`，表格用 `rows`（首行为表头）。结构化表格自动分页，备注只放第一页。分页后超过 maxSlides 会报错，最多120页。图文、图表、品牌及按页编辑见 `advanced.md`。
+
+## 动效（motion）
+
+默认 `motion: on`：HTML 放映有页间淡入与要点逐条入场；PPTX 每页原生淡入转场，`bullets` 页的要点按「点击一次出现一条」放映。交付严肃/打印场景或用户明确要静态时传 `motion: 'off'`（CLI `--motion off`），产物不含任何动画代码。

package/skills/dsh-ppt/references/themes.md

@@ -1,61 +1,61 @@
-# dsh-ppt 内置主题参考
-
-主题系统移植自 hyperframes 技能的 `visual-styles.md` 视觉风格库。每套主题在 HTML 与 PPTX 中使用同一色板、同一字体族、同一情绪规则。
-
-> 想先看效果：运行 `ppt_themes { preview: true, outputDir: "dist" }`，会生成 `themes-preview.html` 与每套主题一张 `theme-<id>.svg`；README/npm 首屏可以直接引用 SVG。
-
-## 速查
-
-| ID | 中文名 | English | 明暗 | 底色 | 前景 | 主强调 | 次强调 | 情绪 | 适用 |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| `data` | 数据漂移 | Data Drift | 暗 | `#070B14` | `#E8F1FF` | `#7C3AED` | `#06B6D4` | 未来/沉浸 | AI、数据、研究、技术发布 |
-| `swiss` | 瑞士脉冲 | Swiss Pulse | 暗 | `#10151B` | `#F5F7FA` | `#2F6BFF` | `#FFB300` | 精准/理性 | SaaS、数据、开发者工具 |
-| `velvet` | 天鹅绒标准 | Velvet Standard | 暗 | `#111316` | `#F4EFE6` | `#C9A84C` | `#3D4A63` | 高级/克制 | 高管汇报、品牌、融资路演 |
-| `soft` | 柔和信号 | Soft Signal | 亮 | `#FFF8EC` | `#3B2F2A` | `#E58A2F` | `#8FAF8C` | 温暖/人本 | 品牌故事、培训、个人分享 |
-| `bold` | 极繁大字 | Maximalist Type | 暗 | `#0D0D0D` | `#FFFFFF` | `#E63946` | `#FFD60A` | 大声/动能 | 产品发布、活动、大事件 |
-
-## 逐主题说明
-
-### data — 数据漂移（默认）
-
-- 深黑底 + 电光紫 + 青色，细体未来感。
-- 适合 AI / ML / 数据 / 前沿技术；大标题少字，用对比数字。
-- 反模式：不要加多余暖色；不要堆长段落。
-
-### swiss — 瑞士脉冲
-
-- 黑白灰 + 一个电蓝（或琥珀），栅格感、大数字。
-- 适合 SaaS / 指标 / 开发者工具；标题短、要点像 spec。
-- 反模式：不要装饰性渐变文字；不要圆角卡片堆叠。
-
-### velvet — 天鹅绒标准
-
-- 黑、米白、香槟金，衬线标题 + 无衬线正文，宽字距，留白多。
-- 适合高管汇报 / 品牌 / 融资；节奏慢，页数少而精。
-- 反模式：不要动画感强烈的颜色；不要超过一个强调色。
-
-### soft — 柔和信号
-
-- 暖奶油底、深棕字、琥珀 + 鼠尾草绿，亮色唯一浅底主题。
-- 适合品牌故事 / 培训 / 个人分享；文字可以更口语。
-- 反模式：不要用纯黑正文；不要高饱和撞色。
-
-### bold — 极繁大字
-
-- 黑底、正红 + 明黄，超粗标题，字就是视觉主体。
-- 适合产品发布 / 活动 / 大事件；短标题、单页单一冲击。
-- 反模式：不要把页面塞满要点；不要让红黄之外再出现第三种强调色。
-
-## 选主题决策树
-
-1. 情绪是未来/科技 → `data`
-2. 情绪是理性/数据/精准 → `swiss`
-3. 情绪是高级/信任/正式 → `velvet`
-4. 情绪是温暖/人本/故事 → `soft`
-5. 情绪是大音量/发布会 → `bold`
-
-无法判断时用 `data`，不要自造主题 ID。
-
-## 视觉引擎复用（hyperframes）
-
-如果 `hyperframes` 技能已安装，生成前先读它的 `visual-styles.md` / `house-style.md` 作为视觉判断依据；本技能的 5 套主题就是把其中 Swiss Pulse / Velvet Standard / Data Drift / Soft Signal / Maximalist Type 五套风格落成确定性 HTML+PPTX 实现。需要高级动画视频版时，才转用 hyperframes；普通演示不要上视频引擎。
+# dsh-ppt 内置主题参考
+
+主题系统移植自 hyperframes 技能的 `visual-styles.md` 视觉风格库。每套主题在 HTML 与 PPTX 中使用同一色板、同一字体族、同一情绪规则。
+
+> 想先看效果：运行 `ppt_themes { preview: true, outputDir: "dist" }`，会生成 `themes-preview.html` 与每套主题一张 `theme-<id>.svg`；README/npm 首屏可以直接引用 SVG。
+
+## 速查
+
+| ID | 中文名 | English | 明暗 | 底色 | 前景 | 主强调 | 次强调 | 情绪 | 适用 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `data` | 数据漂移 | Data Drift | 暗 | `#070B14` | `#E8F1FF` | `#7C3AED` | `#06B6D4` | 未来/沉浸 | AI、数据、研究、技术发布 |
+| `swiss` | 瑞士脉冲 | Swiss Pulse | 暗 | `#10151B` | `#F5F7FA` | `#2F6BFF` | `#FFB300` | 精准/理性 | SaaS、数据、开发者工具 |
+| `velvet` | 天鹅绒标准 | Velvet Standard | 暗 | `#111316` | `#F4EFE6` | `#C9A84C` | `#3D4A63` | 高级/克制 | 高管汇报、品牌、融资路演 |
+| `soft` | 柔和信号 | Soft Signal | 亮 | `#FFF8EC` | `#3B2F2A` | `#E58A2F` | `#8FAF8C` | 温暖/人本 | 品牌故事、培训、个人分享 |
+| `bold` | 极繁大字 | Maximalist Type | 暗 | `#0D0D0D` | `#FFFFFF` | `#E63946` | `#FFD60A` | 大声/动能 | 产品发布、活动、大事件 |
+
+## 逐主题说明
+
+### data — 数据漂移（默认）
+
+- 深黑底 + 电光紫 + 青色，细体未来感。
+- 适合 AI / ML / 数据 / 前沿技术；大标题少字，用对比数字。
+- 反模式：不要加多余暖色；不要堆长段落。
+
+### swiss — 瑞士脉冲
+
+- 黑白灰 + 一个电蓝（或琥珀），栅格感、大数字。
+- 适合 SaaS / 指标 / 开发者工具；标题短、要点像 spec。
+- 反模式：不要装饰性渐变文字；不要圆角卡片堆叠。
+
+### velvet — 天鹅绒标准
+
+- 黑、米白、香槟金，衬线标题 + 无衬线正文，宽字距，留白多。
+- 适合高管汇报 / 品牌 / 融资；节奏慢，页数少而精。
+- 反模式：不要动画感强烈的颜色；不要超过一个强调色。
+
+### soft — 柔和信号
+
+- 暖奶油底、深棕字、琥珀 + 鼠尾草绿，亮色唯一浅底主题。
+- 适合品牌故事 / 培训 / 个人分享；文字可以更口语。
+- 反模式：不要用纯黑正文；不要高饱和撞色。
+
+### bold — 极繁大字
+
+- 黑底、正红 + 明黄，超粗标题，字就是视觉主体。
+- 适合产品发布 / 活动 / 大事件；短标题、单页单一冲击。
+- 反模式：不要把页面塞满要点；不要让红黄之外再出现第三种强调色。
+
+## 选主题决策树
+
+1. 情绪是未来/科技 → `data`
+2. 情绪是理性/数据/精准 → `swiss`
+3. 情绪是高级/信任/正式 → `velvet`
+4. 情绪是温暖/人本/故事 → `soft`
+5. 情绪是大音量/发布会 → `bold`
+
+无法判断时用 `data`，不要自造主题 ID。
+
+## 视觉引擎复用（hyperframes）
+
+如果 `hyperframes` 技能已安装，生成前先读它的 `visual-styles.md` / `house-style.md` 作为视觉判断依据；本技能的 5 套主题就是把其中 Swiss Pulse / Velvet Standard / Data Drift / Soft Signal / Maximalist Type 五套风格落成确定性 HTML+PPTX 实现。需要高级动画视频版时，才转用 hyperframes；普通演示不要上视频引擎。

package/skills/dsh-ppt/scripts/build-deck.mjs

@@ -1,184 +1,184 @@
-#! /usr/bin/env node
-/**
- * build-deck.mjs —— dsh-ppt 的跨 harness 裸 CLI。
- *
- * DSH 插件内请优先使用 ppt_create 工具；把 skills/dsh-ppt 目录复制到
- * Claude Code / Cursor / Gemini CLI / Codex 等 agent 时，用本脚本生成三件套。
- *
- * 示例：
- *   node build-deck.mjs --title "产品发布" --content "deck.md" --theme data --lang zh --out dist/deck
- *   node build-deck.mjs --title "Pitch" --content "一句话介绍我们的产品。" --theme velvet --lang bilingual
- *   node build-deck.mjs --list-themes
- */
-
-import { existsSync, readFileSync } from 'node:fs'
-import { resolve as resolvePath } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import { listThemes, THEME_IDS, DEFAULT_THEME } from './deck-core.mjs'
-import { buildDeckAsync, listTemplates, editDeck, undoDeck, checkDeckAsync, renderDeck } from './deck-advanced.mjs'
-
-const HELP = `dsh-ppt —— 一句话 / 一篇文档 → HTML 放映 + PPTX 导出
-
-用法：
-  node build-deck.mjs --title <标题> --content <Markdown 或文件路径> [选项]
-
-选项：
-  --title <text>      演示文稿标题（必填）
-  --content <text|@path>  Markdown 正文；或文件路径（自动读取）；或 @- 从 stdin 读
-  --slides <json>     结构化 slides JSON（可选，与 --content 二选一）
-  --template <id>    weekly / defense / project / pitch；仅模板会生成草稿
-  --brand <json|@path> 品牌颜色、字体、Logo、页脚
-  --edit <deck.json> 修改指定页，配合 --edits <json|@path>
-  --undo <deck.json> 撤销最近一次修改
-  --check <deck.json> 查看质量报告和页码 / ID
-  --render <deck.pptx> 用可选官方引擎生成逐页 PNG / PDF
-  --format <png|pdf|both> 渲染格式，默认 png
-  --width <n>        PNG 目标宽度，默认 1440
-  --timeout <ms>     渲染整体期限，默认 120000 毫秒
-  --render-receipt <path> 配合 --check 核验当前渲染收据
-  --revision <n>     编辑 / 撤销预期修订号，防止覆盖他人修改
-  --list-templates  列出场景结构参考
-  --theme <id>        视觉主题：${THEME_IDS.join(' / ')}（默认 ${DEFAULT_THEME}）
-  --lang <id>         界面语言：zh / en / bilingual（默认 zh）
-  --motion <on|off>   页间转场与要点入场动画（默认 on；off 产出纯静态）
-  --out <dir>         输出目录（默认当前目录）
-  --file <name>       文件名前缀（默认取标题）
-  --overwrite         显式覆盖同名三件套（默认自动追加 -1/-2…）
-  --list-themes       列出内置主题
-  --help              显示本帮助
-
-输出：
-  <file>.html   独立网页放映（无外链，可直接双击打开）
-  <file>.pptx   可编辑 PPTX（16:9）
-  <file>.json   deck manifest
-`
-
-export function parseArgv(argv) {
-  const args = { content: '', slides: null, lang: 'zh', theme: undefined, motion: undefined, out: '.', file: '', title: '', overwrite: false }
-  const positional = []
-  for (let i = 0; i < argv.length; i += 1) {
-    const raw = String(argv[i])
-    const eq = raw.indexOf('=')
-    const key = eq >= 0 ? raw.slice(0, eq) : raw
-    const inline = eq >= 0 ? raw.slice(eq + 1) : null
-    const nextValue = () => {
-      if (inline !== null) return inline
-      if (i + 1 >= argv.length) throw new Error('dsh-ppt CLI：' + key + ' 需要一个值')
-      i += 1
-      return String(argv[i])
-    }
-    if (key === '--help' || key === '-h') args.help = true
-    else if (key === '--list-themes') args.listThemes = true
-    else if (key === '--list-templates') args.listTemplates = true
-    else if (key === '--overwrite') args.overwrite = true
-    else if (key === '--title') args.title = nextValue()
-    else if (key === '--content') args.content = nextValue()
-    else if (key === '--slides') args.slides = readJson(nextValue())
-    else if (key === '--template') args.template = nextValue()
-    else if (key === '--brand') args.brand = readJson(nextValue())
-    else if (key === '--edit') args.edit = nextValue()
-    else if (key === '--edits') args.edits = readJson(nextValue())
-    else if (key === '--undo') args.undo = nextValue()
-    else if (key === '--check') args.check = nextValue()
-    else if (key === '--render') args.render = nextValue()
-    else if (key === '--format') args.format = nextValue()
-    else if (key === '--width') args.width = Number(nextValue())
-    else if (key === '--timeout') args.timeoutMs = Number(nextValue())
-    else if (key === '--render-receipt') args.renderReceipt = nextValue()
-    else if (key === '--revision') args.revision = Number(nextValue())
-    else if (key === '--theme') args.theme = nextValue()
-    else if (key === '--lang') args.lang = nextValue()
-    else if (key === '--motion') args.motion = nextValue()
-    else if (key === '--out') { args.out = nextValue(); args.explicitOut = true }
-    else if (key === '--file') args.file = nextValue()
-    else positional.push(raw)
-  }
-  args.positional = positional
-  return args
-}
-
-function readJson(value) { return JSON.parse(value.startsWith('@') ? readFileSync(resolvePath(value.slice(1)), 'utf8') : value) }
-
-async function readStdin(stream) {
-  let text = ''
-  stream.setEncoding('utf8')
-  for await (const chunk of stream) text += chunk
-  return text
-}
-
-export async function main(argv = process.argv.slice(2), io = {}) {
-  const log = io.log ?? ((message) => console.log(message))
-  const args = parseArgv(argv)
-
-  if (args.help) {
-    log(HELP.trim())
-    return 0
-  }
-  if (args.listThemes) {
-    for (const theme of listThemes('zh')) {
-      log('- ' + theme.id.padEnd(8) + theme.name + '｜' + theme.mood + '｜适合：' + theme.bestFor)
-    }
-    return 0
-  }
-  if (args.listTemplates) { log(JSON.stringify({ templates: listTemplates(args.lang) }, null, 2)); return 0 }
-  if ([args.edit, args.undo, args.check, args.render].filter(Boolean).length > 1) throw new Error('dsh-ppt CLI：--edit / --undo / --check / --render 只能选择一项')
-  if (args.renderReceipt !== undefined && !args.check) throw new Error('dsh-ppt CLI：--render-receipt 需配合 --check')
-  if (!args.render && [args.format, args.width, args.timeoutMs].some(v => v !== undefined)) throw new Error('dsh-ppt CLI：--format / --width / --timeout 需配合 --render')
-  if (args.check) {
-    const report = await checkDeckAsync({ deckPath: args.check, renderReceipt: args.renderReceipt })
-    log(JSON.stringify(report, null, 2)); return report.ok && (args.renderReceipt === undefined || report.render?.status === 'rendered') ? 0 : 1
-  }
-  if (args.render) {
-    const rendered = await (io.renderDeck ?? renderDeck)({ pptxPath: args.render, ...(args.explicitOut ? { outputDir: args.out } : {}), format: args.format, width: args.width, timeoutMs: args.timeoutMs })
-    log(JSON.stringify(rendered, null, 2)); return rendered.ok ? 0 : 1
-  }
-  if (args.edit || args.undo) {
-    const result = args.edit ? await editDeck({ deckPath: args.edit, edits: args.edits, brand: args.brand, expectedRevision: args.revision })
-      : await undoDeck({ deckPath: args.undo, expectedRevision: args.revision })
-    log(JSON.stringify(result, null, 2)); return 0
-  }
-
-  let content = String(args.content ?? '')
-  let slides = args.slides
-  if (content === '@-') {
-    content = await readStdin(io.stdin ?? process.stdin)
-  } else if (content.startsWith('@')) {
-    content = readFileSync(resolvePath(content.slice(1)), 'utf8')
-  } else if (content.trim() !== '' && existsSync(resolvePath(content.trim()))) {
-    // README / SKILL.md 的示例直接传文件路径（不带 @）时也按文件读取
-    content = readFileSync(resolvePath(content.trim()), 'utf8')
-  } else if (content.trim() === '' && slides === null && !args.template) {
-    throw new Error('dsh-ppt CLI：--content 不能为空（或用 --slides 传结构化幻灯片）')
-  }
-
-  const options = {
-    title: args.title,
-    content,
-    slides,
-    theme: args.theme,
-    lang: args.lang,
-    motion: args.motion,
-    outputDir: resolvePath(args.out || '.'),
-    fileName: args.file,
-    overwrite: args.overwrite,
-    template: args.template,
-    brand: args.brand,
-  }
-  const result = await buildDeckAsync(options)
-  log('dsh-ppt 已生成 ' + result.slideCount + ' 页演示文稿：')
-  log('  HTML 放映：' + result.htmlPath)
-  log('  PPTX 导出：' + result.pptxPath)
-  log('  Manifest ：' + result.jsonPath)
-  if (result.deliveryStatus === 'draft') log('  草稿：还有待填写内容，不可作为成品交付。')
-  log('  质量检查：' + result.quality.errorCount + ' 个错误 / ' + result.quality.warningCount + ' 个提醒；修订号 ' + result.revision)
-  return 0
-}
-
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
-  main().then((code) => {
-    process.exitCode = code ?? 0
-  }).catch((err) => {
-    console.error('[dsh-ppt] ' + (err instanceof Error ? err.message : String(err)))
-    process.exitCode = 1
-  })
-}
+#! /usr/bin/env node
+/**
+ * build-deck.mjs —— dsh-ppt 的跨 harness 裸 CLI。
+ *
+ * DSH 插件内请优先使用 ppt_create 工具；把 skills/dsh-ppt 目录复制到
+ * Claude Code / Cursor / Gemini CLI / Codex 等 agent 时，用本脚本生成三件套。
+ *
+ * 示例：
+ *   node build-deck.mjs --title "产品发布" --content "deck.md" --theme data --lang zh --out dist/deck
+ *   node build-deck.mjs --title "Pitch" --content "一句话介绍我们的产品。" --theme velvet --lang bilingual
+ *   node build-deck.mjs --list-themes
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve as resolvePath } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { listThemes, THEME_IDS, DEFAULT_THEME } from './deck-core.mjs'
+import { buildDeckAsync, listTemplates, editDeck, undoDeck, checkDeckAsync, renderDeck } from './deck-advanced.mjs'
+
+const HELP = `dsh-ppt —— 一句话 / 一篇文档 → HTML 放映 + PPTX 导出
+
+用法：
+  node build-deck.mjs --title <标题> --content <Markdown 或文件路径> [选项]
+
+选项：
+  --title <text>      演示文稿标题（必填）
+  --content <text|@path>  Markdown 正文；或文件路径（自动读取）；或 @- 从 stdin 读
+  --slides <json>     结构化 slides JSON（可选，与 --content 二选一）
+  --template <id>    weekly / defense / project / pitch；仅模板会生成草稿
+  --brand <json|@path> 品牌颜色、字体、Logo、页脚
+  --edit <deck.json> 修改指定页，配合 --edits <json|@path>
+  --undo <deck.json> 撤销最近一次修改
+  --check <deck.json> 查看质量报告和页码 / ID
+  --render <deck.pptx> 用可选官方引擎生成逐页 PNG / PDF
+  --format <png|pdf|both> 渲染格式，默认 png
+  --width <n>        PNG 目标宽度，默认 1440
+  --timeout <ms>     渲染整体期限，默认 120000 毫秒
+  --render-receipt <path> 配合 --check 核验当前渲染收据
+  --revision <n>     编辑 / 撤销预期修订号，防止覆盖他人修改
+  --list-templates  列出场景结构参考
+  --theme <id>        视觉主题：${THEME_IDS.join(' / ')}（默认 ${DEFAULT_THEME}）
+  --lang <id>         界面语言：zh / en / bilingual（默认 zh）
+  --motion <on|off>   页间转场与要点入场动画（默认 on；off 产出纯静态）
+  --out <dir>         输出目录（默认当前目录）
+  --file <name>       文件名前缀（默认取标题）
+  --overwrite         显式覆盖同名三件套（默认自动追加 -1/-2…）
+  --list-themes       列出内置主题
+  --help              显示本帮助
+
+输出：
+  <file>.html   独立网页放映（无外链，可直接双击打开）
+  <file>.pptx   可编辑 PPTX（16:9）
+  <file>.json   deck manifest
+`
+
+export function parseArgv(argv) {
+  const args = { content: '', slides: null, lang: 'zh', theme: undefined, motion: undefined, out: '.', file: '', title: '', overwrite: false }
+  const positional = []
+  for (let i = 0; i < argv.length; i += 1) {
+    const raw = String(argv[i])
+    const eq = raw.indexOf('=')
+    const key = eq >= 0 ? raw.slice(0, eq) : raw
+    const inline = eq >= 0 ? raw.slice(eq + 1) : null
+    const nextValue = () => {
+      if (inline !== null) return inline
+      if (i + 1 >= argv.length) throw new Error('dsh-ppt CLI：' + key + ' 需要一个值')
+      i += 1
+      return String(argv[i])
+    }
+    if (key === '--help' || key === '-h') args.help = true
+    else if (key === '--list-themes') args.listThemes = true
+    else if (key === '--list-templates') args.listTemplates = true
+    else if (key === '--overwrite') args.overwrite = true
+    else if (key === '--title') args.title = nextValue()
+    else if (key === '--content') args.content = nextValue()
+    else if (key === '--slides') args.slides = readJson(nextValue())
+    else if (key === '--template') args.template = nextValue()
+    else if (key === '--brand') args.brand = readJson(nextValue())
+    else if (key === '--edit') args.edit = nextValue()
+    else if (key === '--edits') args.edits = readJson(nextValue())
+    else if (key === '--undo') args.undo = nextValue()
+    else if (key === '--check') args.check = nextValue()
+    else if (key === '--render') args.render = nextValue()
+    else if (key === '--format') args.format = nextValue()
+    else if (key === '--width') args.width = Number(nextValue())
+    else if (key === '--timeout') args.timeoutMs = Number(nextValue())
+    else if (key === '--render-receipt') args.renderReceipt = nextValue()
+    else if (key === '--revision') args.revision = Number(nextValue())
+    else if (key === '--theme') args.theme = nextValue()
+    else if (key === '--lang') args.lang = nextValue()
+    else if (key === '--motion') args.motion = nextValue()
+    else if (key === '--out') { args.out = nextValue(); args.explicitOut = true }
+    else if (key === '--file') args.file = nextValue()
+    else positional.push(raw)
+  }
+  args.positional = positional
+  return args
+}
+
+function readJson(value) { return JSON.parse(value.startsWith('@') ? readFileSync(resolvePath(value.slice(1)), 'utf8') : value) }
+
+async function readStdin(stream) {
+  let text = ''
+  stream.setEncoding('utf8')
+  for await (const chunk of stream) text += chunk
+  return text
+}
+
+export async function main(argv = process.argv.slice(2), io = {}) {
+  const log = io.log ?? ((message) => console.log(message))
+  const args = parseArgv(argv)
+
+  if (args.help) {
+    log(HELP.trim())
+    return 0
+  }
+  if (args.listThemes) {
+    for (const theme of listThemes('zh')) {
+      log('- ' + theme.id.padEnd(8) + theme.name + '｜' + theme.mood + '｜适合：' + theme.bestFor)
+    }
+    return 0
+  }
+  if (args.listTemplates) { log(JSON.stringify({ templates: listTemplates(args.lang) }, null, 2)); return 0 }
+  if ([args.edit, args.undo, args.check, args.render].filter(Boolean).length > 1) throw new Error('dsh-ppt CLI：--edit / --undo / --check / --render 只能选择一项')
+  if (args.renderReceipt !== undefined && !args.check) throw new Error('dsh-ppt CLI：--render-receipt 需配合 --check')
+  if (!args.render && [args.format, args.width, args.timeoutMs].some(v => v !== undefined)) throw new Error('dsh-ppt CLI：--format / --width / --timeout 需配合 --render')
+  if (args.check) {
+    const report = await checkDeckAsync({ deckPath: args.check, renderReceipt: args.renderReceipt })
+    log(JSON.stringify(report, null, 2)); return report.ok && (args.renderReceipt === undefined || report.render?.status === 'rendered') ? 0 : 1
+  }
+  if (args.render) {
+    const rendered = await (io.renderDeck ?? renderDeck)({ pptxPath: args.render, ...(args.explicitOut ? { outputDir: args.out } : {}), format: args.format, width: args.width, timeoutMs: args.timeoutMs })
+    log(JSON.stringify(rendered, null, 2)); return rendered.ok ? 0 : 1
+  }
+  if (args.edit || args.undo) {
+    const result = args.edit ? await editDeck({ deckPath: args.edit, edits: args.edits, brand: args.brand, expectedRevision: args.revision })
+      : await undoDeck({ deckPath: args.undo, expectedRevision: args.revision })
+    log(JSON.stringify(result, null, 2)); return 0
+  }
+
+  let content = String(args.content ?? '')
+  let slides = args.slides
+  if (content === '@-') {
+    content = await readStdin(io.stdin ?? process.stdin)
+  } else if (content.startsWith('@')) {
+    content = readFileSync(resolvePath(content.slice(1)), 'utf8')
+  } else if (content.trim() !== '' && existsSync(resolvePath(content.trim()))) {
+    // README / SKILL.md 的示例直接传文件路径（不带 @）时也按文件读取
+    content = readFileSync(resolvePath(content.trim()), 'utf8')
+  } else if (content.trim() === '' && slides === null && !args.template) {
+    throw new Error('dsh-ppt CLI：--content 不能为空（或用 --slides 传结构化幻灯片）')
+  }
+
+  const options = {
+    title: args.title,
+    content,
+    slides,
+    theme: args.theme,
+    lang: args.lang,
+    motion: args.motion,
+    outputDir: resolvePath(args.out || '.'),
+    fileName: args.file,
+    overwrite: args.overwrite,
+    template: args.template,
+    brand: args.brand,
+  }
+  const result = await buildDeckAsync(options)
+  log('dsh-ppt 已生成 ' + result.slideCount + ' 页演示文稿：')
+  log('  HTML 放映：' + result.htmlPath)
+  log('  PPTX 导出：' + result.pptxPath)
+  log('  Manifest ：' + result.jsonPath)
+  if (result.deliveryStatus === 'draft') log('  草稿：还有待填写内容，不可作为成品交付。')
+  log('  质量检查：' + result.quality.errorCount + ' 个错误 / ' + result.quality.warningCount + ' 个提醒；修订号 ' + result.revision)
+  return 0
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  main().then((code) => {
+    process.exitCode = code ?? 0
+  }).catch((err) => {
+    console.error('[dsh-ppt] ' + (err instanceof Error ? err.message : String(err)))
+    process.exitCode = 1
+  })
+}