bit-ppt-generator 0.3.0

package/src/layout-guides.mjs

@@ -0,0 +1,315 @@
+const writingRules = [
+  "Keep slide text short and concrete; use validation warnings as rewrite hints.",
+  "Prefer editable PPTX objects: text boxes, shapes, tables, charts, OMML formulas, and native images.",
+  "Use `speakerNotes` for presenter scripts; these notes are written to the PPTX notes pane, not the slide canvas.",
+  "When an image is unavailable, use `image.mode: placeholder` with a concrete prompt instead of inventing a local file path.",
+  "Use local image paths relative to the project root unless an integration provides assets separately.",
+  "Run `bit-ppt check <deck.yaml> --json` before generation and use `repairPrompt` to revise content.",
+];
+
+const speakerNotesGuide = {
+  topic: "speaker-notes",
+  purpose: "Add PowerPoint/WPS speaker notes to any slide without rendering them on the slide canvas.",
+  fields: {
+    speakerNotes: { type: "string | string[]", required: false },
+  },
+  aliases: ["speaker_notes", "speakerScript", "speaker_script"],
+  limits: {
+    speakerNotes: { recommendedChars: 1200, recommendedLines: 30 },
+  },
+  notes: [
+    "Use a YAML block scalar for paragraph-style presenter scripts.",
+    "Use a string list when the script is naturally segmented into short beats.",
+    "Formula text in speaker notes is kept as plain text for now, for example `$L(\\theta)$`.",
+    "`notes` remains layout-specific slide content in some layouts; use `speakerNotes` for the actual notes pane.",
+  ],
+  example: {
+    layout: "bullets",
+    title: "核心观点",
+    bullets: ["输出是可编辑 PPTX。"],
+    speakerNotes: "这一页先解释为什么选择 YAML 到 PPTX 的路线。\n公式暂时按普通文本保留，例如 $L(\\theta)$。",
+  },
+};
+
+const imagePlaceholderGuide = {
+  topic: "image-placeholder",
+  purpose: "Describe missing images with editable placeholders that users can replace later.",
+  whenToUse: "Use when the user has no image yet, cannot upload images, or wants AI to draft an image prompt inside the deck.",
+  fields: {
+    image: { type: "{ mode: placeholder, prompt, aspectRatio?, placement?, variants? }", required: true },
+    prompt: { type: "string", required: true },
+    aspectRatio: { type: "16:9 | 4:3 | 3:2 | 1:1 | 3:4 | 9:16 | auto", required: false },
+    placement: { type: "top | side | auto", required: false },
+    variants: { type: "boolean", required: false },
+  },
+  limits: {
+    prompt: { recommendedChars: 160 },
+  },
+  notes: [
+    "This is a common image object mode, not a standalone slide layout.",
+    "Supported by imageText, caseStudy, and imageGrid.",
+    "Use `aspectRatio` when the likely image shape is known.",
+    "For imageText with unknown aspect ratio, leave it as auto so preflight emits top and side variants.",
+    "The generated placeholder is editable PowerPoint text and shapes, not a raster image.",
+  ],
+  example: {
+    layout: "imageText",
+    title: "系统架构示意",
+    image: {
+      mode: "placeholder",
+      aspectRatio: "auto",
+      prompt: "A clean architecture diagram showing YAML input, validation, PPTX generation, and OMML post-processing.",
+    },
+    text: ["用户后续可替换占位图。"],
+  },
+};
+
+const layoutGuides = {
+  imageText: {
+    layout: "imageText",
+    purpose: "Show one image with a short explanatory bullet list.",
+    whenToUse: "Use for visual evidence, screenshots, diagrams, and result images that need concise interpretation.",
+    fields: {
+      layout: { type: "literal", required: true, value: "imageText" },
+      title: { type: "string", required: true },
+      image: { type: "string | { path, placement, fit } | { mode: placeholder, prompt, aspectRatio?, placement? }", required: true },
+      caption: { type: "string", required: false },
+      text: { type: "string[]", required: true },
+    },
+    limits: {
+      text: { maxItems: 5, recommendedChars: 38 },
+      imagePrompt: { recommendedChars: 160 },
+    },
+    notes: [
+      "Very wide images are automatically placed above the text.",
+      "Ordinary landscape, portrait, and square images stay side-by-side so text space remains usable.",
+      "`placement: top` or `placement: side` overrides automatic placement.",
+      "`fit: contain` avoids cropping; `fit: cover` fills the image box.",
+      "If no image is available, set `image.mode: placeholder` and provide a prompt for the future image.",
+      "When placeholder aspectRatio is omitted or `auto`, imageText preflight creates top and side layout variants for user selection.",
+    ],
+    example: {
+      layout: "imageText",
+      title: "视觉结果说明",
+      image: {
+        path: "assets/bit-campus-photo.png",
+        placement: "auto",
+        fit: "contain",
+      },
+      caption: "图片说明控制在一行内。",
+      text: ["图像展示关键现象。", "右侧或下方保留少量解释。"],
+    },
+  },
+  chart: {
+    layout: "chart",
+    purpose: "Create an editable native PowerPoint chart.",
+    whenToUse: "Use for quantitative comparisons, trends, composition, and metric summaries.",
+    fields: {
+      layout: { type: "literal", required: true, value: "chart" },
+      title: { type: "string", required: true },
+      type: { type: "bar | line | pie | doughnut | scatter | area", required: false },
+      categories: { type: "string[]", required: true },
+      series: { type: "{ name, values }[]", required: false },
+      values: { type: "number[]", required: false },
+      caption: { type: "string", required: false },
+    },
+    limits: {
+      categories: { maxItems: 8, pieMaxItems: 6, recommendedChars: 18 },
+      seriesName: { recommendedChars: 16 },
+      caption: { recommendedChars: 58 },
+    },
+    notes: [
+      "Every series values list must match the categories length.",
+      "Use `values` as a shortcut for a single unnamed series.",
+      "Pie and doughnut charts work best with six or fewer categories.",
+    ],
+    example: {
+      layout: "chart",
+      title: "指标对比",
+      type: "bar",
+      categories: ["Baseline", "Ours"],
+      series: [{ name: "Accuracy", values: [82.1, 87.4] }],
+      caption: "Ours improves accuracy under the same setting.",
+    },
+  },
+  flowchart: {
+    layout: "flowchart",
+    purpose: "Draw an editable flowchart with PowerPoint shapes and arrow lines.",
+    whenToUse: "Use for pipelines, decision paths, model stages, and process diagrams.",
+    fields: {
+      layout: { type: "literal", required: true, value: "flowchart" },
+      title: { type: "string", required: true },
+      nodes: { type: "{ id, text, note?, x?, y?, w?, h? }[]", required: true },
+      edges: { type: "{ from, to }[]", required: false },
+      note: { type: "string", required: false },
+    },
+    limits: {
+      nodes: { maxItems: 10, recommendedTextChars: 12, recommendedNoteChars: 22 },
+      note: { recommendedChars: 56 },
+    },
+    notes: [
+      "Node ids must be unique.",
+      "Edges must reference existing node ids.",
+      "If edges are omitted, nodes are connected in order.",
+      "Optional x/y coordinates are relative to the flowchart area.",
+    ],
+    example: {
+      layout: "flowchart",
+      title: "生成流程",
+      nodes: [
+        { id: "yaml", text: "YAML" },
+        { id: "check", text: "校验" },
+        { id: "pptx", text: "PPTX" },
+      ],
+      edges: [
+        { from: "yaml", to: "check" },
+        { from: "check", to: "pptx" },
+      ],
+    },
+  },
+  table: {
+    layout: "table",
+    purpose: "Create an editable comparison or data table.",
+    whenToUse: "Use for compact structured comparisons with a small number of columns.",
+    fields: {
+      layout: { type: "literal", required: true, value: "table" },
+      title: { type: "string", required: true },
+      columns: { type: "string[]", required: true },
+      rows: { type: "array[]", required: true },
+    },
+    limits: {
+      columns: { maxItems: 5 },
+      cell: { recommendedChars: 42 },
+    },
+    notes: [
+      "Rows may be split across multiple slides during preflight if the table is too tall.",
+      "Keep wide tables under five columns, or split the content by topic.",
+      "Inline formulas in table cells are converted to native OMML.",
+    ],
+    example: {
+      layout: "table",
+      title: "方法对比",
+      columns: ["方法", "输入", "输出"],
+      rows: [
+        ["Baseline", "文本", "普通 PPTX"],
+        ["Ours", "YAML", "可编辑 BIT 风格 PPTX"],
+      ],
+    },
+  },
+  formula: {
+    layout: "formula",
+    purpose: "Show a display formula with short explanatory notes.",
+    whenToUse: "Use for core equations, objective functions, and derivations that need native Office Math.",
+    fields: {
+      layout: { type: "literal", required: true, value: "formula" },
+      title: { type: "string", required: true },
+      formula: { type: "string | { latex, caption? }", required: true },
+      caption: { type: "string", required: false },
+      explanation: { type: "string[]", required: false },
+    },
+    limits: {
+      explanation: { maxItems: 4, recommendedChars: 48 },
+    },
+    notes: [
+      "LaTeX is converted to native OMML during PPTX post-processing.",
+      "Inline `$...$` and `\\(...\\)` formulas are supported in text-heavy layouts.",
+      "Avoid image formulas unless explicitly using a fallback outside this generator.",
+    ],
+    example: {
+      layout: "formula",
+      title: "优化目标",
+      formula: {
+        latex: "\\mathcal{L}=\\sum_i (y_i-\\hat{y}_i)^2",
+      },
+      explanation: ["目标函数衡量预测误差。"],
+    },
+  },
+};
+
+function listGuideLayouts() {
+  return Object.keys(layoutGuides);
+}
+
+function getLayoutGuide(layout) {
+  return layoutGuides[layout] || null;
+}
+
+function getLayoutSchema(layout) {
+  const guide = getLayoutGuide(layout);
+  if (!guide) return null;
+  return {
+    layout: guide.layout,
+    commonFields: speakerNotesGuide.fields,
+    fields: guide.fields,
+    limits: guide.limits,
+  };
+}
+
+function getLayoutExample(layout) {
+  const guide = getLayoutGuide(layout);
+  return guide?.example || null;
+}
+
+function getGuideOverview() {
+  return {
+    name: "BIT PPT Generator",
+    purpose: "Generate editable Beijing Institute of Technology style PPTX files from YAML.",
+    workflow: [
+      "Choose layouts with `bit-ppt list-layouts`.",
+      "Inspect one layout with `bit-ppt guide layout <name>`.",
+      "Draft YAML and run `bit-ppt check <deck.yaml> --json`.",
+      "Fix validation errors using `repairPrompt`.",
+      "Generate with `bit-ppt generate <deck.yaml> <output.pptx>`.",
+    ],
+    commands: [
+      "bit-ppt guide",
+      "bit-ppt guide layouts",
+      "bit-ppt guide layout <name>",
+      "bit-ppt guide schema <name> --json",
+      "bit-ppt guide example <name>",
+      "bit-ppt guide speaker-notes",
+      "bit-ppt guide image-placeholder",
+      "bit-ppt guide writing-rules",
+    ],
+    guidedLayouts: listGuideLayouts(),
+  };
+}
+
+function getSpeakerNotesGuide() {
+  return { ...speakerNotesGuide };
+}
+
+function getImagePlaceholderGuide() {
+  return { ...imagePlaceholderGuide };
+}
+
+function getWritingRules() {
+  return [...writingRules];
+}
+
+function getGuideWorkflow() {
+  return getGuideOverview().workflow;
+}
+
+function getAllGuides() {
+  return {
+    overview: getGuideOverview(),
+    speakerNotes: getSpeakerNotesGuide(),
+    imagePlaceholder: getImagePlaceholderGuide(),
+    writingRules: getWritingRules(),
+    layouts: Object.fromEntries(listGuideLayouts().map((layout) => [layout, getLayoutGuide(layout)])),
+  };
+}
+
+export {
+  getAllGuides,
+  getGuideOverview,
+  getGuideWorkflow,
+  getImagePlaceholderGuide,
+  getLayoutExample,
+  getLayoutGuide,
+  getLayoutSchema,
+  getSpeakerNotesGuide,
+  getWritingRules,
+  listGuideLayouts,
+};

package/src/mcp-server.mjs

@@ -0,0 +1,197 @@
+import fs from "node:fs";
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as z from "zod/v4";
+import { parseDeckYaml } from "./core/yaml-parse.mjs";
+import {
+  ROOT,
+  checkDeck,
+  checkDeckFile,
+  generateDeckFile,
+  listLayouts,
+  validateDeck,
+} from "./generate.mjs";
+import {
+  getAllGuides,
+  getGuideOverview,
+  getGuideWorkflow,
+  getImagePlaceholderGuide,
+  getLayoutExample,
+  getLayoutGuide,
+  getLayoutSchema,
+  getSpeakerNotesGuide,
+  getWritingRules,
+  listGuideLayouts,
+} from "./layout-guides.mjs";
+
+function packageVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
+    return pkg.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function resolveLocalPath(value) {
+  const source = String(value || "");
+  return path.isAbsolute(source) ? source : path.resolve(ROOT, source);
+}
+
+function loadDeckArgs(args) {
+  if (args.deckYaml) return parseDeckYaml(args.deckYaml, "deckYaml");
+  if (args.inputPath) return parseDeckYaml(fs.readFileSync(resolveLocalPath(args.inputPath), "utf8"), args.inputPath);
+  throw new Error("Provide either inputPath or deckYaml.");
+}
+
+function textResult(data) {
+  return {
+    structuredContent: data,
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+function guideResult(topic = "overview", name) {
+  switch (topic) {
+    case "overview":
+      return getGuideOverview();
+    case "all":
+      return getAllGuides();
+    case "workflow":
+      return getGuideWorkflow();
+    case "layouts":
+      return listGuideLayouts();
+    case "layout": {
+      if (!name) throw new Error("get_guide topic=layout requires name.");
+      const guide = getLayoutGuide(name);
+      if (!guide) throw new Error(`No guide available for layout: ${name}`);
+      return guide;
+    }
+    case "schema": {
+      if (!name) throw new Error("get_guide topic=schema requires name.");
+      const schema = getLayoutSchema(name);
+      if (!schema) throw new Error(`No schema available for layout: ${name}`);
+      return schema;
+    }
+    case "example": {
+      if (!name) throw new Error("get_guide topic=example requires name.");
+      const example = getLayoutExample(name);
+      if (!example) throw new Error(`No example available for layout: ${name}`);
+      return example;
+    }
+    case "speaker-notes":
+      return getSpeakerNotesGuide();
+    case "image-placeholder":
+      return getImagePlaceholderGuide();
+    case "writing-rules":
+      return getWritingRules();
+    default:
+      throw new Error(`Unknown guide topic: ${topic}`);
+  }
+}
+
+const deckInputSchema = {
+  inputPath: z.string().optional().describe("Path to a YAML deck file. Relative paths resolve from the project root."),
+  deckYaml: z.string().optional().describe("Raw YAML deck content. Use this instead of inputPath for generated drafts."),
+};
+
+const fontOptionsSchema = {
+  fontCn: z.string().optional().describe("Chinese/CJK font override."),
+  fontCnLight: z.string().optional().describe("Light Chinese/CJK font override."),
+  fontEn: z.string().optional().describe("Latin font override."),
+  fontSerif: z.string().optional().describe("Serif font override."),
+  fontCode: z.string().optional().describe("Code font override."),
+};
+
+export function createBitPptMcpServer() {
+  const server = new McpServer({
+    name: "bit-ppt-template",
+    version: packageVersion(),
+  });
+
+  server.registerTool("list_layouts", {
+    title: "List Layouts",
+    description: "List supported BIT PPT slide layouts.",
+    inputSchema: {},
+  }, async () => textResult({ layouts: listLayouts() }));
+
+  server.registerTool("get_guide", {
+    title: "Get Progressive Guide",
+    description: "Return focused guide content for layouts, schemas, examples, speaker notes, image placeholders, or writing rules.",
+    inputSchema: {
+      topic: z.enum(["overview", "all", "workflow", "layouts", "layout", "schema", "example", "speaker-notes", "image-placeholder", "writing-rules"]).optional().default("overview"),
+      name: z.string().optional().describe("Layout name for topic layout, schema, or example."),
+    },
+  }, async ({ topic, name }) => textResult(guideResult(topic, name)));
+
+  server.registerTool("validate_deck", {
+    title: "Validate Deck",
+    description: "Validate a YAML deck and return validation errors, warnings, and repairPrompt.",
+    inputSchema: deckInputSchema,
+  }, async (args) => {
+    const deck = loadDeckArgs(args);
+    const validation = validateDeck(deck);
+    return textResult({
+      validation: {
+        errors: validation.errors,
+        warnings: validation.warnings,
+      },
+      repairPrompt: validation.repairPrompt,
+    });
+  });
+
+  server.registerTool("preflight_deck", {
+    title: "Preflight Deck",
+    description: "Run validation plus preflight planning such as automatic splits and placeholder layout variants.",
+    inputSchema: deckInputSchema,
+  }, async (args) => textResult(checkDeck(loadDeckArgs(args))));
+
+  server.registerTool("get_repair_prompt", {
+    title: "Get Repair Prompt",
+    description: "Return only the repairPrompt for a YAML deck, plus validation counts.",
+    inputSchema: deckInputSchema,
+  }, async (args) => {
+    const result = checkDeck(loadDeckArgs(args));
+    return textResult({
+      repairPrompt: result.repairPrompt,
+      errors: result.validation.errors.length,
+      warnings: result.validation.warnings.length,
+    });
+  });
+
+  server.registerTool("generate_pptx", {
+    title: "Generate PPTX",
+    description: "Generate an editable PPTX from a YAML file. Generation stops on validation errors; strict mode also stops on warnings.",
+    inputSchema: {
+      inputPath: z.string().describe("Path to the input YAML deck file. Relative paths resolve from the project root."),
+      outputPath: z.string().describe("Path to the output PPTX file. Relative paths resolve from the project root."),
+      strict: z.boolean().optional().describe("Treat validation warnings as failures before generation."),
+      ...fontOptionsSchema,
+    },
+  }, async (args) => {
+    const input = resolveLocalPath(args.inputPath);
+    const output = resolveLocalPath(args.outputPath);
+    if (args.strict) {
+      const check = checkDeckFile(input);
+      if (check.validation.errors.length || check.validation.warnings.length) {
+        return textResult({
+          generated: false,
+          error: "Deck validation failed strict mode.",
+          validation: check.validation,
+          repairPrompt: check.repairPrompt,
+        });
+      }
+    }
+    const result = await generateDeckFile(input, output, args);
+    return textResult({ generated: true, ...result });
+  });
+
+  return server;
+}
+
+export async function startStdioMcpServer() {
+  const server = createBitPptMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}