bit-ppt-generator 0.3.0

package/bin/bit-ppt.mjs

@@ -0,0 +1,480 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  ROOT,
+  checkDeckFile,
+  defaultFont,
+  generateDeckFile,
+  listLayouts,
+} from "../src/generate.mjs";
+import {
+  getAllGuides,
+  getGuideOverview,
+  getGuideWorkflow,
+  getImagePlaceholderGuide,
+  getLayoutExample,
+  getLayoutGuide,
+  getLayoutSchema,
+  getSpeakerNotesGuide,
+  getWritingRules,
+  listGuideLayouts,
+} from "../src/layout-guides.mjs";
+
+function printHelp() {
+  console.log(`bit-ppt
+
+Usage:
+  bit-ppt generate <input.yaml> <output.pptx> [--json] [--strict] [font options]
+  bit-ppt check <input.yaml> [--json] [--strict]
+  bit-ppt list-layouts [--json]
+  bit-ppt guide [topic] [name] [--json]
+  bit-ppt doctor [--json]
+
+Progressive guide:
+  bit-ppt guide
+  bit-ppt guide all --json
+  bit-ppt guide workflow --json
+  bit-ppt guide layouts
+  bit-ppt guide layout imageText
+  bit-ppt guide schema imageText --json
+  bit-ppt guide example imageText
+  bit-ppt guide speaker-notes
+  bit-ppt guide image-placeholder
+  bit-ppt guide writing-rules
+
+Quality options:
+  --json                  Print machine-readable JSON where supported
+  --strict                Treat validation warnings as failures
+
+Font options:
+  --font-cn <name>        Chinese/CJK font, default: ${defaultFont.cn}
+  --font-cn-light <name>  Light Chinese/CJK font, default: ${defaultFont.cnLight}
+  --font-en <name>        Latin font, default: ${defaultFont.en}
+  --font-serif <name>     Serif font, default: ${defaultFont.serif}
+  --font-code <name>      Code font, default: ${defaultFont.code}
+`);
+}
+
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+function printGuideOverview(overview) {
+  console.log(`${overview.name}
+
+${overview.purpose}
+
+Workflow:
+${overview.workflow.map((item, idx) => `  ${idx + 1}. ${item}`).join("\n")}
+
+Guide commands:
+${overview.commands.map((item) => `  ${item}`).join("\n")}
+
+Guided layouts:
+  ${overview.guidedLayouts.join(", ")}
+`);
+}
+
+function printLayoutGuide(guide) {
+  console.log(`${guide.layout}
+
+Purpose:
+  ${guide.purpose}
+
+Use when:
+  ${guide.whenToUse}
+
+Fields:
+${Object.entries(guide.fields).map(([name, spec]) => {
+    const required = spec.required ? "required" : "optional";
+    const value = spec.value ? ` = ${spec.value}` : "";
+    return `  ${name}: ${spec.type}${value} (${required})`;
+  }).join("\n")}
+
+Limits:
+${Object.entries(guide.limits || {}).map(([name, spec]) => `  ${name}: ${Object.entries(spec).map(([key, value]) => `${key}=${value}`).join(", ")}`).join("\n") || "  none"}
+
+Notes:
+${guide.notes.map((item) => `  - ${item}`).join("\n")}
+`);
+}
+
+function printExample(example) {
+  console.log(JSON.stringify(example, null, 2));
+}
+
+function printWritingRules(rules) {
+  console.log(`Writing rules:
+${rules.map((item) => `  - ${item}`).join("\n")}
+`);
+}
+
+function printSpeakerNotesGuide(guide) {
+  console.log(`Speaker notes
+
+Purpose:
+  ${guide.purpose}
+
+Fields:
+${Object.entries(guide.fields).map(([name, spec]) => {
+    const required = spec.required ? "required" : "optional";
+    return `  ${name}: ${spec.type} (${required})`;
+  }).join("\n")}
+
+Aliases:
+  ${guide.aliases.join(", ")}
+
+Limits:
+${Object.entries(guide.limits || {}).map(([name, spec]) => `  ${name}: ${Object.entries(spec).map(([key, value]) => `${key}=${value}`).join(", ")}`).join("\n")}
+
+Notes:
+${guide.notes.map((item) => `  - ${item}`).join("\n")}
+
+Example:
+${JSON.stringify(guide.example, null, 2)}
+`);
+}
+
+function printImagePlaceholderGuide(guide) {
+  console.log(`Image placeholder
+
+Purpose:
+  ${guide.purpose}
+
+Use when:
+  ${guide.whenToUse}
+
+Fields:
+${Object.entries(guide.fields).map(([name, spec]) => {
+    const required = spec.required ? "required" : "optional";
+    return `  ${name}: ${spec.type} (${required})`;
+  }).join("\n")}
+
+Limits:
+${Object.entries(guide.limits || {}).map(([name, spec]) => `  ${name}: ${Object.entries(spec).map(([key, value]) => `${key}=${value}`).join(", ")}`).join("\n")}
+
+Notes:
+${guide.notes.map((item) => `  - ${item}`).join("\n")}
+
+Example:
+${JSON.stringify(guide.example, null, 2)}
+`);
+}
+
+function printAvailableGuideLayouts() {
+  console.log(listGuideLayouts().join("\n"));
+}
+
+function printWorkflow(workflow) {
+  console.log(`Workflow:
+${workflow.map((item, idx) => `  ${idx + 1}. ${item}`).join("\n")}
+`);
+}
+
+function printGuideHelp() {
+  console.log(`bit-ppt guide
+
+Usage:
+  bit-ppt guide
+  bit-ppt guide all --json
+  bit-ppt guide workflow [--json]
+  bit-ppt guide layouts
+  bit-ppt guide layout <name> [--json]
+  bit-ppt guide schema <name> --json
+  bit-ppt guide example <name> [--json]
+  bit-ppt guide speaker-notes [--json]
+  bit-ppt guide image-placeholder [--json]
+  bit-ppt guide writing-rules [--json]
+`);
+}
+
+function doctorCheck(name, ok, message, details = {}) {
+  return { name, ok, message, ...details };
+}
+
+function canImportPackage(packageName) {
+  try {
+    import.meta.resolve(packageName);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runDoctor() {
+  const checks = [];
+  const version = process.versions.node;
+  const major = Number(version.split(".")[0]);
+  checks.push(doctorCheck("node", major >= 18, `Node.js ${version}`, { version }));
+
+  ["pptxgenjs", "yaml", "jszip", "latex-to-omml", "@modelcontextprotocol/sdk", "zod"].forEach((packageName) => {
+    const available = canImportPackage(packageName);
+    checks.push(doctorCheck(`dependency:${packageName}`, available, available ? `${packageName} is available` : `${packageName} is missing`));
+  });
+
+  ["assets/bit-campus-photo.png", "assets/bit-campus-line.png", "content/example.yaml", "content/body-layout-test.yaml", "content/chart-flow-test.yaml"].forEach((relativePath) => {
+    const fileName = path.join(ROOT, relativePath);
+    checks.push(doctorCheck(`file:${relativePath}`, fs.existsSync(fileName), fs.existsSync(fileName) ? "found" : "missing", { path: fileName }));
+  });
+
+  [
+    ["fixture:example", "content/example.yaml"],
+    ["fixture:body-layouts", "content/body-layout-test.yaml"],
+    ["fixture:charts", "content/chart-flow-test.yaml"],
+  ].forEach(([name, relativePath]) => {
+    try {
+      const result = checkDeckFile(path.join(ROOT, relativePath));
+      checks.push(doctorCheck(name, result.validation.errors.length === 0, result.validation.errors.length ? "validation errors found" : "check passed", {
+        warnings: result.validation.warnings.length,
+        errors: result.validation.errors.length,
+      }));
+    } catch (error) {
+      checks.push(doctorCheck(name, false, error.message || String(error)));
+    }
+  });
+
+  try {
+    const outputDir = path.join(ROOT, "output");
+    fs.mkdirSync(outputDir, { recursive: true });
+    const probe = path.join(outputDir, `.bit-ppt-doctor-${process.pid}.tmp`);
+    fs.writeFileSync(probe, "ok");
+    fs.unlinkSync(probe);
+    checks.push(doctorCheck("output:writable", true, "output directory is writable", { path: outputDir }));
+  } catch (error) {
+    checks.push(doctorCheck("output:writable", false, error.message || String(error)));
+  }
+
+  const ok = checks.every((item) => item.ok);
+  return {
+    ok,
+    platform: process.platform,
+    arch: process.arch,
+    cwd: process.cwd(),
+    root: ROOT,
+    checks,
+  };
+}
+
+function printDoctor(result) {
+  console.log(`BIT PPT doctor: ${result.ok ? "ok" : "failed"}
+
+Root:
+  ${result.root}
+
+Checks:
+${result.checks.map((item) => `  ${item.ok ? "OK" : "FAIL"} ${item.name}: ${item.message}`).join("\n")}
+`);
+}
+
+function parseOptions(args) {
+  const options = {};
+  const positional = [];
+  for (let idx = 0; idx < args.length; idx += 1) {
+    const arg = args[idx];
+    if (arg === "--json") options.json = true;
+    else if (arg === "--strict") options.strict = true;
+    else if (arg === "--font-cn" || arg === "--font-cjk") options.fontCn = args[++idx];
+    else if (arg === "--font-cn-light") options.fontCnLight = args[++idx];
+    else if (arg === "--font-en" || arg === "--font-latin") options.fontEn = args[++idx];
+    else if (arg === "--font-serif") options.fontSerif = args[++idx];
+    else if (arg === "--font-code") options.fontCode = args[++idx];
+    else if (arg === "-h" || arg === "--help") options.help = true;
+    else positional.push(arg);
+  }
+  return { options, positional };
+}
+
+function printCheck(result, asJson) {
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const errors = result.validation.errors.length;
+  const warnings = result.validation.warnings.length;
+  console.log(`slides: ${result.inputSlides} -> ${result.outputSlides}`);
+  console.log(`errors: ${errors}`);
+  console.log(`warnings: ${warnings}`);
+  if (result.actions.length) {
+    console.log(`actions: ${result.actions.map((item) => `${item.title}->${item.parts}`).join(", ")}`);
+  }
+  if (result.repairPrompt) {
+    console.log("\nrepair prompt:");
+    console.log(result.repairPrompt);
+  }
+}
+
+function hasStrictFailure(result, options) {
+  return Boolean(options.strict && result.validation.warnings.length);
+}
+
+function applyCheckExitCode(result, options) {
+  if (result.validation.errors.length || hasStrictFailure(result, options)) {
+    process.exitCode = 1;
+  }
+}
+
+function makeStrictWarningError(result) {
+  const error = new Error("Deck validation warning(s) failed strict mode.");
+  error.validation = result.validation;
+  error.repairPrompt = result.repairPrompt;
+  return error;
+}
+
+function printGuide(command, name, asJson) {
+  if (!command) {
+    const overview = getGuideOverview();
+    if (asJson) printJson(overview);
+    else printGuideOverview(overview);
+    return;
+  }
+
+  if (command === "help" || command === "-h" || command === "--help") {
+    printGuideHelp();
+    return;
+  }
+
+  if (command === "all") {
+    const guides = getAllGuides();
+    if (asJson) printJson(guides);
+    else printGuideOverview(guides.overview);
+    return;
+  }
+
+  if (command === "workflow") {
+    const workflow = getGuideWorkflow();
+    if (asJson) printJson(workflow);
+    else printWorkflow(workflow);
+    return;
+  }
+
+  if (command === "speaker-notes") {
+    const guide = getSpeakerNotesGuide();
+    if (asJson) printJson(guide);
+    else printSpeakerNotesGuide(guide);
+    return;
+  }
+
+  if (command === "image-placeholder") {
+    const guide = getImagePlaceholderGuide();
+    if (asJson) printJson(guide);
+    else printImagePlaceholderGuide(guide);
+    return;
+  }
+
+  if (command === "layouts") {
+    const layouts = listGuideLayouts();
+    if (asJson) printJson(layouts);
+    else printAvailableGuideLayouts();
+    return;
+  }
+
+  if (command === "layout") {
+    if (!name) throw new Error("Usage: bit-ppt guide layout <name>");
+    const guide = getLayoutGuide(name);
+    if (!guide) throw new Error(`No guide available for layout: ${name}`);
+    if (asJson) printJson(guide);
+    else printLayoutGuide(guide);
+    return;
+  }
+
+  if (command === "schema") {
+    if (!name) throw new Error("Usage: bit-ppt guide schema <name>");
+    const schema = getLayoutSchema(name);
+    if (!schema) throw new Error(`No schema available for layout: ${name}`);
+    printJson(schema);
+    return;
+  }
+
+  if (command === "example") {
+    if (!name) throw new Error("Usage: bit-ppt guide example <name>");
+    const example = getLayoutExample(name);
+    if (!example) throw new Error(`No example available for layout: ${name}`);
+    if (asJson) printJson(example);
+    else printExample(example);
+    return;
+  }
+
+  if (command === "writing-rules") {
+    const rules = getWritingRules();
+    if (asJson) printJson(rules);
+    else printWritingRules(rules);
+    return;
+  }
+
+  throw new Error(`Unknown guide topic: ${command}`);
+}
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const { options, positional } = parseOptions(rest);
+  if (!command || command === "help" || command === "-h" || command === "--help" || options.help) {
+    printHelp();
+    return;
+  }
+
+  if (command === "list-layouts") {
+    const layouts = listLayouts();
+    if (options.json) console.log(JSON.stringify(layouts, null, 2));
+    else console.log(layouts.join("\n"));
+    return;
+  }
+
+  if (command === "guide") {
+    printGuide(positional[0], positional[1], options.json);
+    return;
+  }
+
+  if (command === "doctor") {
+    const result = runDoctor();
+    if (options.json) printJson(result);
+    else printDoctor(result);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
+  if (command === "check") {
+    const input = positional[0];
+    if (!input) throw new Error("Missing input YAML path.");
+    const result = checkDeckFile(path.resolve(input));
+    printCheck(result, options.json);
+    applyCheckExitCode(result, options);
+    return;
+  }
+
+  if (command === "generate") {
+    const [input, output] = positional;
+    if (!input || !output) throw new Error("Usage: bit-ppt generate <input.yaml> <output.pptx>");
+    if (options.strict) {
+      const strictCheck = checkDeckFile(path.resolve(input));
+      if (hasStrictFailure(strictCheck, options)) throw makeStrictWarningError(strictCheck);
+    }
+    const result = await generateDeckFile(path.resolve(input), path.resolve(output), options);
+    if (options.json) {
+      printJson(result);
+      return;
+    }
+    if (result.validation.warnings.length) {
+      console.warn(`Validation warning(s): ${result.validation.warnings.length}`);
+      console.warn(result.repairPrompt);
+    }
+    if (result.preflight.length) {
+      console.log(`Preflight adjusted ${result.preflight.length} slide(s): ${result.preflight.map((item) => `${item.title}->${item.parts}`).join(", ")}`);
+    }
+    console.log(`Generated ${result.output}`);
+    console.log(`Fonts: cn=${result.fonts.cn}, en=${result.fonts.en}, serif=${result.fonts.serif}, code=${result.fonts.code}`);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main().catch((error) => {
+  if (error.validation) {
+    console.error(JSON.stringify({ error: error.message, validation: error.validation, repairPrompt: error.repairPrompt }, null, 2));
+  } else {
+    console.error(error.message || error);
+  }
+  process.exitCode = 1;
+});

package/content/body-layout-test.yaml

@@ -0,0 +1,112 @@
+meta:
+  title: 北理工正文页型扩展示例
+  subtitle: Architecture / ablation / case / image / code / appendix
+  author: BIT PPT Template Generator
+  advisor: 北京理工大学
+  date: 2026.05
+
+slides:
+  - layout: title
+
+  - layout: architecture
+    title: 模型驱动的 PPT 生成架构
+    layers:
+      - title: 输入层
+        components: [论文草稿, 实验结果, 图片素材, 用户约束]
+        note: 将非结构化材料整理为可验证的内容块。
+      - title: 规划层
+        components: [章节规划, 页型选择, 字段填充, 修复提示]
+        note: AI 只选择 layout 并填写 YAML，不直接操作 PowerPoint。
+      - title: 生成层
+        components: [溢出检测, 公式 OMML, 表格拆页, PPTX 写入]
+        note: 模板侧保证字号、位置、颜色和 $p_{\theta}(x_i)$ 等公式写入。
+      - title: 验证层
+        components: [结构检查, 版面预检, 人工复核]
+        note: 发现异常后回传给模型压缩或改写内容。
+
+  - layout: ablation
+    title: 消融实验页
+    baseline: 基线模型使用完整模块组合，目标函数为 $L(\theta)$。
+    items:
+      - factor: 检索增强
+        setting: 移除检索上下文
+        delta: "-6.2%"
+        conclusion: 长文档问题下降明显
+      - factor: 结构化规划
+        setting: 直接生成正文页
+        delta: "+3.8 overflow"
+        conclusion: 页面溢出风险上升
+      - factor: 公式写入
+        setting: OMML 替换为图片
+        delta: 可编辑性下降
+        conclusion: 小公式不适合图片
+      - factor: 表格拆页
+        setting: 关闭 preflight
+        delta: 2 页重叠
+        conclusion: 长表格必须预检
+
+  - layout: caseStudy
+    title: 案例分析页
+    image: assets/bit-campus-photo.png
+    caption: 示例图片区域，可替换为实验样本、系统截图或结果图。
+    context:
+      - 输入是一段包含公式、表格和图片引用的论文草稿。
+      - 目标是生成北理工答辩风格的可编辑 PPTX。
+    method:
+      - 先让模型选择正文类型，再填充短字段。
+      - 生成器负责固定版式、OMML 公式和溢出检测。
+    result:
+      - 输出可在 WPS / PowerPoint 中继续编辑。
+      - 版式一致性优于直接让模型写 PPT 代码。
+
+  - layout: imageGrid
+    title: 多图结果展示
+    images:
+      - path: assets/bit-campus-photo.png
+        caption: 输入样本
+      - path: assets/bit-campus-photo.png
+        caption: 中间特征
+      - path: assets/bit-campus-photo.png
+        caption: 预测结果
+      - path: assets/bit-campus-photo.png
+        caption: 误差区域
+      - path: assets/bit-campus-photo.png
+        caption: 对照方法
+      - path: assets/bit-campus-photo.png
+        caption: 本文方法
+
+  - layout: code
+    title: 算法伪代码页
+    language: Algorithm
+    code: |
+      Input: draft D, template layouts T
+      1. parse D into claims, evidence and assets
+      2. select layout t in T for each content block
+      3. generate YAML fields with concise text
+      4. run preflight and formula conversion
+      5. repair overflow until deck is valid
+    noteTitle: 关键约束
+    notes:
+      - 模型只产出结构化 YAML。
+      - 公式使用 OMML 写入，避免图片变形。
+      - 长列表、长表格和参考文献优先自动拆页。
+
+  - layout: appendix
+    title: 附录索引页
+    items:
+      - key: A1
+        title: 数据集细节
+        text: 样本来源、筛选规则和统计分布。
+      - key: A2
+        title: 超参数设置
+        text: 学习率、batch size 和训练轮数。
+      - key: A3
+        title: 更多公式
+        text: 包括 $p_{\theta}(x_i)$、$L(\theta)$ 与推导步骤。
+      - key: A4
+        title: 额外可视化
+        text: 多组实验结果图和失败案例。
+
+  - layout: closing
+    title: 谢谢
+    subtitle: 新增正文页型测试完成

package/content/chart-flow-test.yaml

@@ -0,0 +1,82 @@
+meta:
+  title: 图表与流程图能力测试
+  subtitle: Native PowerPoint flowchart and chart layouts
+  author: BIT PPT Template Generator
+  advisor: 北京理工大学
+  date: 2026.05
+
+slides:
+  - layout: title
+
+  - layout: flowchart
+    title: 方法流程图
+    nodes:
+      - id: input
+        text: 输入数据
+        note: 文本 / 图像 / 表格
+      - id: parse
+        text: 结构解析
+        note: 提取 claim 与 evidence
+      - id: plan
+        text: 页型规划
+        note: 选择 layout
+      - id: render
+        text: PPTX 生成
+        note: 形状 / 表格 / OMML
+      - id: check
+        text: 预检修复
+        note: 检查溢出
+        emphasis: true
+      - id: output
+        text: 可编辑输出
+        note: WPS / PowerPoint
+        emphasis: true
+    edges:
+      - from: input
+        to: parse
+      - from: parse
+        to: plan
+      - from: plan
+        to: render
+      - from: render
+        to: check
+      - from: check
+        to: output
+    note: 流程图使用 PowerPoint 原生形状和箭头，可继续编辑。
+
+  - layout: chart
+    title: 柱状图：不同方案指标对比
+    type: bar
+    categories: [Dataset A, Dataset B, Dataset C, Dataset D]
+    valueAxisTitle: Accuracy
+    series:
+      - name: Baseline
+        values: [81.2, 83.5, 84.1, 82.4]
+      - name: Ours
+        values: [85.6, 87.2, 88.0, 86.5]
+    caption: 原生 PowerPoint 柱状图，可在 WPS / PowerPoint 中编辑数据。
+
+  - layout: chart
+    title: 折线图：训练过程变化
+    type: line
+    categories: [Epoch 1, Epoch 2, Epoch 3, Epoch 4, Epoch 5]
+    valueAxisTitle: Loss
+    series:
+      - name: Train
+        values: [0.92, 0.71, 0.55, 0.44, 0.39]
+      - name: Valid
+        values: [0.98, 0.78, 0.63, 0.57, 0.52]
+    caption: 折线图适合展示训练损失、指标趋势或时间序列。
+
+  - layout: chart
+    title: 饼图：错误类型分布
+    type: pie
+    categories: [识别错误, 定位错误, 格式错误, 其他]
+    series:
+      - name: Error Types
+        values: [42, 27, 18, 13]
+    caption: 饼图适合少量类别占比，不建议用于精细数值比较。
+
+  - layout: closing
+    title: 谢谢
+    subtitle: 图表与流程图测试完成