bit-ppt-generator 0.3.0 → 0.3.2

package/README.md

@@ -6,6 +6,25 @@
 项目目标不是把幻灯片截图塞进 PPT，而是尽量生成原生 Office 对象：
 文本框、形状、表格、图表、图片和 Office Math 公式都应保持可编辑。
 
+在线测试地址：[http://47.109.207.16:8080/](http://47.109.207.16:8080/)
+
+欢迎试用并在 [GitHub Issues](https://github.com/yang-kun-long/bit-ppt-template/issues)
+反馈问题、语法建议、版式需求或生成失败案例。
+
+## 项目来源与相关路线
+
+本项目的视觉风格和最初需求来自 TeXPage 上的北京理工大学 LaTeX 幻灯片模板：
+[BIThesis Beamer Slide Template](https://www.texpage.com/zh/template/18f4a5d2-2167-47b8-b193-85e2475e7a06)。
+原模板适合熟悉 LaTeX / Beamer 的用户，但 LaTeX 工具链较重，输出也通常是 PDF。
+PDF 用 WPS 播放比较方便；如果没有 WPS，常见的 PDF 转 PPT 流程又容易造成格式错乱。
+
+因此这里提供另一条路线：用 YAML 描述内容，直接生成可编辑 PPTX，尽量保留文本、
+表格、图表、形状和 Office Math 公式的可编辑性。
+
+如果你的需求是“已有 PDF 幻灯片，只想在线展示或播放”，可以使用另一个项目
+[pptView](https://github.com/yang-kun-long/pptView)。在线演示：
+[https://ppt.yangkunlong.top](https://ppt.yangkunlong.top)。
+
 代码使用 MIT License。北京理工大学名称、标识和视觉参考归其各自权利人所有。
 
 ## 特性
@@ -19,9 +38,14 @@
 - 支持 `--json` 和 `--strict`，便于脚本、CI 和 AI agent 自动调用
 - 支持图片尺寸读取和 `imageText` 自动排版
 
-## 安装
+## 三种使用方式
+
+同一个 npm 包同时提供 Web UI、CLI 和 MCP 三个入口。普通用户优先使用 Web UI；
+脚本和 CI 使用 CLI；Codex、Claude Code 等本地 agent 使用 MCP。
+
+### 1. 普通用户：打开本地网页
 
-发布到 npm 后，普通用户可直接启动本地网页：
+无需安装，直接启动：
 
 ```powershell
 npx bit-ppt-generator
@@ -35,88 +59,107 @@ http://127.0.0.1:3000/
 
 本地网页默认不需要登录；只有部署者配置了鉴权环境变量时才会显示登录区。
 
-全局安装：
+也可以全局安装后启动：
 
 ```powershell
 npm install -g bit-ppt-generator
 bit-ppt-generator
 ```
 
-仓库开发：
+### 2. 命令行用户：检查和生成 PPTX
 
 ```powershell
-npm install
+npm install -g bit-ppt-generator
+bit-ppt check content/example.yaml --json
+bit-ppt generate content/example.yaml output/example.pptx
 ```
 
-本地开发可以直接使用 Node 入口：
+常用 CLI：
 
-```powershell
-node bin/bit-ppt.mjs --help
+```text
+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]
 ```
 
-也可以链接为全局命令：
+### 3. Agent 用户：配置 MCP
+
+全局安装后，MCP 客户端可以直接启动 npm 包提供的 `bit-ppt-mcp` 命令：
 
 ```powershell
-npm link
-bit-ppt --help
+npm install -g bit-ppt-generator
+bit-ppt-mcp --help
 ```
 
-## 快速开始
-
-启动本地网页：
+MCP 客户端配置示例：
 
-```powershell
-npm run serve
+```json
+{
+  "mcpServers": {
+    "bit-ppt": {
+      "command": "bit-ppt-mcp",
+      "args": []
+    }
+  }
+}
 ```
 
-生成示例 PPT：
+如果 MCP 客户端不继承系统 PATH，改用 `npx` 启动：
 
-```powershell
-npm run build:ppt
-npm run build:body-layouts
-npm run build:charts
+```json
+{
+  "mcpServers": {
+    "bit-ppt": {
+      "command": "npx",
+      "args": ["-y", "--package", "bit-ppt-generator", "bit-ppt-mcp"]
+    }
+  }
+}
 ```
 
-输出文件位于：
 
-```text
-output/example.pptx
-output/body-layout-test.pptx
-output/chart-flow-test.pptx
-```
+## 仓库开发
 
-手动指定输入和输出：
+克隆仓库后安装依赖：
 
 ```powershell
-node bin/bit-ppt.mjs generate content/example.yaml output/example.pptx
+npm install
 ```
 
-先检查再生成：
+启动本地网页：
 
 ```powershell
-node bin/bit-ppt.mjs check content/example.yaml --json
-node bin/bit-ppt.mjs generate content/example.yaml output/example.pptx --json
+npm run serve
 ```
 
-严格模式会把 warning 也视为失败：
+生成示例 PPT：
 
 ```powershell
-node bin/bit-ppt.mjs check content/formula-test.yaml --json --strict
-node bin/bit-ppt.mjs generate content/example.yaml output/example.pptx --json --strict
+npm run build:ppt
+npm run build:body-layouts
+npm run build:charts
 ```
 
-## Release Targets
+源码入口：
 
-本仓库采用单主干、多入口策略。CLI、MCP 和 Node HTTP 服务都复用同一套核心生成逻辑。
+```powershell
+node bin/bit-ppt.mjs --help
+node bin/bit-ppt-http.mjs --help
+node bin/bit-ppt-mcp.mjs --help
+```
 
-当前状态：
+本仓库采用单主干、多入口策略。Web UI、CLI、MCP 和 Node HTTP API 都复用同一套核心生成逻辑。
+
+## npm 包入口
 
 - Web UI：默认入口为 `bit-ppt-generator`，适合 npm 用户本地打开网页
 - CLI：已支持，入口为 `bit-ppt` 或 `node bin/bit-ppt.mjs`
 - MCP：已支持，入口为 `bit-ppt-mcp` 或 `node bin/bit-ppt-mcp.mjs`
 - Node HTTP API：已支持，入口为 `bit-ppt-http` 或 `node bin/bit-ppt-http.mjs`
 
-当前 npm 包名预定为 `bit-ppt-generator`。一个 npm release 同时包含 Web UI、CLI 和 MCP 三个入口，不拆成三个包。
+一个 npm release 同时包含 Web UI、CLI 和 MCP 三个入口，不拆成三个包。
 
 ## CLI 命令
 
@@ -134,10 +177,10 @@ bit-ppt-http
 常用命令：
 
 ```powershell
-node bin/bit-ppt.mjs list-layouts
-node bin/bit-ppt.mjs list-layouts --json
-node bin/bit-ppt.mjs doctor
-node bin/bit-ppt.mjs doctor --json
+bit-ppt list-layouts
+bit-ppt list-layouts --json
+bit-ppt doctor
+bit-ppt doctor --json
 ```
 
 `doctor` 会检查 Node 版本、依赖、关键素材、示例 deck、输出目录可写性。
@@ -150,24 +193,23 @@ MCP 只是 adapter，仍复用 CLI 背后的同一套生成和校验函数。
 本地运行：
 
 ```powershell
-node bin/bit-ppt-mcp.mjs
+bit-ppt-mcp
 ```
 
-全局链接后：
+从源码运行：
 
 ```powershell
-bit-ppt-mcp
+node bin/bit-ppt-mcp.mjs
 ```
 
-MCP 客户端配置示例：
+MCP 客户端配置示例，优先使用 npm 包命令：
 
 ```json
 {
   "mcpServers": {
     "bit-ppt": {
-      "command": "node",
-      "args": ["D:/atuodl/presentation-slide/bit-ppt-template/bin/bit-ppt-mcp.mjs"],
-      "cwd": "D:/atuodl/presentation-slide/bit-ppt-template"
+      "command": "bit-ppt-mcp",
+      "args": []
     }
   }
 }
@@ -593,6 +635,32 @@ npm run check:charts
 npm pack --dry-run
 ```
 
+## 发布
+
+npm 包名为 `bit-ppt-generator`。后续版本通过 GitHub Release 触发
+`.github/workflows/publish.yml`，并使用 npm Trusted Publisher 发布，不需要在
+GitHub Secrets 保存 npm token。
+
+Trusted Publisher 配置：
+
+```text
+Publisher: GitHub Actions
+Organization or user: yang-kun-long
+Repository: bit-ppt-template
+Workflow filename: publish.yml
+Environment name: 留空
+```
+
+发布新版本：
+
+```powershell
+npm version patch
+git push
+git push --tags
+```
+
+随后在 GitHub 创建并发布对应 tag 的 Release。
+
 ## 项目结构
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bit-ppt-generator",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "LaTeX-free Beijing Institute of Technology style PPTX generator with Web UI, CLI, and MCP entrypoints.",
   "license": "MIT",
   "type": "module",
@@ -38,5 +38,13 @@
     "pptxgenjs": "^4.0.1",
     "yaml": "^2.8.4",
     "zod": "^4.4.3"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yang-kun-long/bit-ppt-template.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yang-kun-long/bit-ppt-template/issues"
+  },
+  "homepage": "https://github.com/yang-kun-long/bit-ppt-template#readme"
 }

package/src/http-server.mjs

@@ -40,11 +40,25 @@ const WEB_APP_HTML = String.raw`<!doctype html>
     button { border: 1px solid var(--red); background: var(--red); color: #fff; border-radius: 6px; padding: 9px 12px; font: inherit; cursor: pointer; }
     button.secondary { background: #fff; color: var(--red); }
     button:disabled { opacity: .55; cursor: not-allowed; }
+    a { color: var(--red); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .intro { margin: 0 0 14px; color: var(--muted); font-size: 13px; line-height: 1.6; }
+    .repo-link { display: inline-flex; align-items: center; gap: 6px; margin-bottom: 12px; font-size: 13px; font-weight: 650; }
+    .repo-icon { width: 16px; height: 16px; fill: currentColor; flex: 0 0 auto; }
+    .guide { display: grid; gap: 10px; margin: 10px 0 14px; }
+    .guide-step { border-left: 3px solid #d9b6b8; padding: 2px 0 2px 10px; }
+    .guide-step strong { display: block; margin-bottom: 4px; font-size: 13px; }
+    .guide-step p { margin: 0; color: var(--muted); font-size: 12px; line-height: 1.55; }
+    .yaml-section { min-width: 0; }
+    .yaml-workspace { display: grid; gap: 16px; grid-template-columns: minmax(0, 1fr) 290px; align-items: start; }
+    .yaml-workspace textarea { min-height: 640px; }
+    .side-guide { border-left: 1px solid var(--line); padding-left: 16px; }
     .status { min-height: 42px; white-space: pre-wrap; font-family: Consolas, "Cascadia Mono", monospace; font-size: 12px; color: var(--muted); }
     .ok { color: #137333; }
     .err { color: #b3261e; }
     .hidden { display: none; }
-    @media (max-width: 860px) { main { grid-template-columns: 1fr; padding: 14px; } textarea { min-height: 420px; } }
+    @media (max-width: 1060px) { .yaml-workspace { grid-template-columns: 1fr; } .side-guide { border-left: 0; border-top: 1px solid var(--line); padding: 14px 0 0; } }
+    @media (max-width: 860px) { main { grid-template-columns: 1fr; padding: 14px; } textarea, .yaml-workspace textarea { min-height: 420px; } }
   </style>
 </head>
 <body>
@@ -63,6 +77,13 @@ const WEB_APP_HTML = String.raw`<!doctype html>
         </div>
         <div id="authStatus" class="status"></div>
       </div>
+      <a class="repo-link" href="https://github.com/yang-kun-long/bit-ppt-template" target="_blank" rel="noreferrer">
+        <svg class="repo-icon" viewBox="0 0 16 16" aria-hidden="true">
+          <path d="M8 0C3.58 0 0 3.64 0 8.13c0 3.59 2.29 6.63 5.47 7.7.4.07.55-.18.55-.39 0-.19-.01-.83-.01-1.51-2.01.38-2.53-.5-2.69-.96-.09-.23-.48-.96-.82-1.15-.28-.15-.68-.52-.01-.53.63-.01 1.08.59 1.23.83.72 1.23 1.87.88 2.33.67.07-.53.28-.88.51-1.09-1.78-.2-3.64-.9-3.64-4.01 0-.89.31-1.61.82-2.18-.08-.2-.36-1.03.08-2.15 0 0 .67-.22 2.2.83A7.5 7.5 0 0 1 8 3.92c.68 0 1.36.09 2 .27 1.53-1.05 2.2-.83 2.2-.83.44 1.12.16 1.95.08 2.15.51.57.82 1.29.82 2.18 0 3.12-1.87 3.81-3.65 4.01.29.25.54.74.54 1.5 0 1.09-.01 1.97-.01 2.24 0 .21.15.46.55.39A8.03 8.03 0 0 0 16 8.13C16 3.64 12.42 0 8 0Z"/>
+        </svg>
+        GitHub 仓库
+      </a>
+      <p class="intro">这是一个把 YAML 生成可编辑 PPTX 的网页入口。推荐先让 AI 产出 YAML，再在这里检查和生成；报错时把检查结果交给 AI 修改。</p>
       <h2>输出</h2>
       <label for="outputName">文件名</label>
       <input id="outputName" value="bit-ppt" />
@@ -75,6 +96,8 @@ const WEB_APP_HTML = String.raw`<!doctype html>
       <div class="row">
         <button id="copyPromptBtn" class="secondary">复制提示词</button>
         <button id="copyRulesBtn" class="secondary">复制语法规则</button>
+        <button id="copyWorkflowBtn" class="secondary">复制使用教程</button>
+        <button id="copyErrorHelpBtn" class="secondary">复制报错求助</button>
         <button id="insertExampleBtn" class="secondary">插入最小示例</button>
         <button id="insertFullExampleBtn" class="secondary">插入完整示例</button>
       </div>
@@ -343,6 +366,42 @@ YAML 与公式注意事项：
 - 表格中有公式时，建议用单引号包住单元格。
 - 图片没有真实路径时使用 placeholder，不要写不存在的 assets 路径。
 - 每页文字保持短；如果 check 返回 warnings，按 repairPrompt 压缩或拆页。</textarea>
+      <textarea id="workflowGuide" hidden>请按这个流程和 AI 协作生成 PPT：
+
+1. 先发“提示词”
+- 告诉 AI：只输出 YAML，不要 Markdown 代码块，不要解释。
+- 补充你的任务：主题、页数、受众、用途、是否需要演讲稿。
+
+2. 再发“语法规则”
+- 让 AI 使用支持的 layout 和字段。
+- 告诉 AI：没有真实图片路径时必须用 image.mode: placeholder。
+- 告诉 AI：公式用 LaTeX，生成后要能通过 check。
+
+3. 最后发材料
+- 可以贴论文摘要、章节结构、实验结果、表格数据、图片说明、参考文献。
+- 要求 AI 生成完整 YAML。
+
+4. 在网页里检查
+- 把 YAML 粘到网页的 YAML 输入框，先点“检查”。
+- 没有 errors 再点“生成 PPTX”。
+
+5. 如果检查有问题
+- 把 check 返回的 errors、warnings、repairPrompt 和当前 YAML 一起发给 AI。
+- 要求 AI 只修改 YAML，不要解释，不要改变核心内容。</textarea>
+      <textarea id="errorHelpPrompt" hidden>下面是 BIT PPT Generator 的检查/生成报错。请你只输出修复后的完整 YAML，不要 Markdown 代码块，不要解释。
+
+修复要求：
+1. 保留原始内容意图和页面顺序。
+2. 修复未知 layout、字段结构错误、YAML 语法错误。
+3. 如果 warnings 说明文字过长，请压缩文字或拆成多页。
+4. 如果图片路径不存在，请改成 image.mode: placeholder，并补充具体 prompt。
+5. 如果公式导致 YAML 转义问题，请避免双引号，优先使用 plain scalar 或单引号。
+6. 输出必须能重新通过 check。
+
+网页报错 / check 结果：
+
+当前 YAML：
+</textarea>
       <textarea id="exampleYaml" hidden>meta:
   title: 北理工风格汇报
   author: BIT PPT Generator
@@ -617,8 +676,9 @@ slides:
       收尾时提示听众：生成结果是可编辑 PPTX。
       后续可以在 PowerPoint 或 WPS 中继续调整。</textarea>
     </section>
-    <section>
+    <section class="yaml-section">
       <h2>YAML</h2>
+      <div class="yaml-workspace">
       <textarea id="yaml" spellcheck="false">meta:
   title: 北理工风格 PPT
   author: BIT PPT Generator
@@ -633,6 +693,28 @@ slides:
       - 输出为可编辑 PPTX
       - 支持公式、图表和多种版式
 </textarea>
+      <aside class="side-guide">
+        <h3>使用教程</h3>
+        <div class="guide">
+          <div class="guide-step">
+            <strong>1. 先复制提示词</strong>
+            <p>发给 AI，说明它的角色、输出格式和页面限制。再补一句你的主题，例如“请做一份 10 页组会汇报”。</p>
+          </div>
+          <div class="guide-step">
+            <strong>2. 再复制语法规则</strong>
+            <p>继续发给 AI，让它按支持的 layout 和字段写 YAML。最后把论文摘要、实验结果、表格数据、图片说明等材料贴给 AI。</p>
+          </div>
+          <div class="guide-step">
+            <strong>3. 粘贴 YAML 后先检查</strong>
+            <p>把 AI 输出粘到左侧输入框，点“检查”。如果有 errors / warnings，把检查结果和当前 YAML 一起发回 AI，让它只修 YAML。</p>
+          </div>
+          <div class="guide-step">
+            <strong>4. 生成失败时这样沟通</strong>
+            <p>复制“报错求助”模板，把网页显示的错误、check 结果、当前 YAML 一起发给 AI；要求它保留内容意图，只修字段、长度、图片路径或公式写法。</p>
+          </div>
+        </div>
+      </aside>
+      </div>
     </section>
   </main>
   <script>
@@ -795,6 +877,8 @@ slides:
     $("generateBtn").addEventListener("click", generateDeck);
     $("copyPromptBtn").addEventListener("click", () => copyTextFrom("aiPrompt", "提示词"));
     $("copyRulesBtn").addEventListener("click", () => copyTextFrom("syntaxRules", "语法规则"));
+    $("copyWorkflowBtn").addEventListener("click", () => copyTextFrom("workflowGuide", "使用教程"));
+    $("copyErrorHelpBtn").addEventListener("click", () => copyTextFrom("errorHelpPrompt", "报错求助模板"));
     $("insertExampleBtn").addEventListener("click", insertExample);
     $("insertFullExampleBtn").addEventListener("click", insertFullExample);
     loadServerConfig();

package/src/layout-guides.mjs

@@ -1,3 +1,5 @@
+import { listLayouts as listSupportedLayouts } from "./core/layouts.mjs";
+
 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.",
@@ -226,8 +228,414 @@ const layoutGuides = {
   },
 };
 
+const additionalLayoutGuides = {
+  title: {
+    layout: "title",
+    purpose: "Create the deck cover slide from top-level metadata.",
+    whenToUse: "Use as the first slide; title content usually comes from the deck-level `meta` object.",
+    fields: {
+      layout: { type: "literal", required: true, value: "title" },
+      "meta.title": { type: "string", required: false },
+      "meta.subtitle": { type: "string", required: false },
+      "meta.author": { type: "string", required: false },
+      "meta.advisor": { type: "string", required: false },
+      "meta.date": { type: "string", required: false },
+    },
+    limits: {
+      "meta.title": { recommendedChars: 28 },
+      "meta.subtitle": { recommendedChars: 42 },
+    },
+    notes: [
+      "The slide object normally only needs `layout: title`.",
+      "Cover text is read from deck metadata.",
+    ],
+    example: { layout: "title" },
+  },
+  agenda: {
+    layout: "agenda",
+    purpose: "Show the main agenda or chapter list.",
+    whenToUse: "Use near the beginning of a deck to preview sections.",
+    fields: {
+      layout: { type: "literal", required: true, value: "agenda" },
+      title: { type: "string", required: true },
+      items: { type: "string[]", required: true },
+    },
+    limits: { items: { maxItems: 7, recommendedChars: 24 } },
+    notes: ["Keep agenda labels short and parallel.", "Use `section` slides for major chapter breaks."],
+    example: { layout: "agenda", title: "目录", items: ["研究背景", "方法设计", "实验结果", "总结展望"] },
+  },
+  section: {
+    layout: "section",
+    purpose: "Create a visual chapter divider.",
+    whenToUse: "Use before a major topic shift or report section.",
+    fields: {
+      layout: { type: "literal", required: true, value: "section" },
+      sectionNo: { type: "string", required: false },
+      title: { type: "string", required: true },
+      subtitle: { type: "string", required: false },
+    },
+    limits: { title: { recommendedChars: 24 }, subtitle: { recommendedChars: 42 } },
+    notes: ["`sectionNo` can be supplied explicitly, for example `01`.", "Keep the subtitle as context, not body content."],
+    example: { layout: "section", sectionNo: "01", title: "研究背景", subtitle: "从问题定义与现有瓶颈切入" },
+  },
+  bullets: {
+    layout: "bullets",
+    purpose: "Show a lead sentence and a concise bullet list.",
+    whenToUse: "Use for findings, observations, requirements, and short argument chains.",
+    fields: {
+      layout: { type: "literal", required: true, value: "bullets" },
+      title: { type: "string", required: true },
+      lead: { type: "string", required: false },
+      bullets: { type: "string[]", required: true },
+      fontSize: { type: "number", required: false },
+    },
+    limits: { lead: { recommendedChars: 58 }, bullets: { maxItems: 8, recommendedChars: 38 } },
+    notes: ["Inline `$...$` and `\\(...\\)` formulas are supported.", "Long bullet lists may be split during preflight."],
+    example: { layout: "bullets", title: "核心发现", lead: "结构化输入能降低排版漂移。", bullets: ["模型只填写短字段。", "模板负责视觉规范。", "预检负责溢出修复。"] },
+  },
+  claim: {
+    layout: "claim",
+    purpose: "Emphasize one central claim with supporting evidence.",
+    whenToUse: "Use when a slide needs one clear takeaway rather than several equal points.",
+    fields: {
+      layout: { type: "literal", required: true, value: "claim" },
+      title: { type: "string", required: true },
+      claim: { type: "string", required: true },
+      evidence: { type: "string[]", required: false },
+    },
+    limits: { claim: { recommendedChars: 54 }, evidence: { maxItems: 5, recommendedChars: 38 } },
+    notes: ["Make `claim` a complete sentence.", "Use evidence bullets for proof, not extra claims."],
+    example: { layout: "claim", title: "核心结论", claim: "AI 生成 PPT 的关键是稳定内容结构。", evidence: ["YAML 限定字段。", "PPTX 对象保持可编辑。"] },
+  },
+  twoColumn: {
+    layout: "twoColumn",
+    purpose: "Compare or separate two parallel content blocks.",
+    whenToUse: "Use for before/after, baseline/ours, or two-topic explanation.",
+    fields: {
+      layout: { type: "literal", required: true, value: "twoColumn" },
+      title: { type: "string", required: true },
+      left: { type: "{ title, text? | bullets? }", required: true },
+      right: { type: "{ title, text? | bullets? }", required: true },
+    },
+    limits: { columnTitle: { recommendedChars: 16 }, columnText: { recommendedChars: 105 }, columnBullets: { maxItems: 5, recommendedChars: 34 } },
+    notes: ["Each column can use either `text` or `bullets`.", "Use `comparison` when the point is explicitly adversarial or directional."],
+    example: { layout: "twoColumn", title: "两种路线", left: { title: "传统做法", bullets: ["手工排版", "一致性依赖人工"] }, right: { title: "模板化做法", bullets: ["结构化输入", "生成器固定样式"] } },
+  },
+  cards: {
+    layout: "cards",
+    purpose: "Show several peer points as compact cards.",
+    whenToUse: "Use for features, modules, contributions, or categories with equal weight.",
+    fields: {
+      layout: { type: "literal", required: true, value: "cards" },
+      title: { type: "string", required: true },
+      cards: { type: "{ title, text }[]", required: true },
+    },
+    limits: { cards: { maxItems: 6 }, cardTitle: { recommendedChars: 14 }, cardText: { recommendedChars: 52 } },
+    notes: ["Cards work best when each item has similar importance.", "Use no more than six cards on one slide."],
+    example: { layout: "cards", title: "能力模块", cards: [{ title: "校验", text: "检查字段与长度风险。" }, { title: "生成", text: "写入可编辑 PPTX 对象。" }] },
+  },
+  comparison: {
+    layout: "comparison",
+    purpose: "Show a direct comparison between two options.",
+    whenToUse: "Use when one side is preferred, rejected, or contrasted against another.",
+    fields: {
+      layout: { type: "literal", required: true, value: "comparison" },
+      title: { type: "string", required: true },
+      left: { type: "{ label?, title, bullets }", required: true },
+      right: { type: "{ label?, title, bullets }", required: true },
+    },
+    limits: { comparisonTitle: { recommendedChars: 18 }, bullets: { maxItems: 5, recommendedChars: 32 } },
+    notes: ["`left.label` and `right.label` are short tags.", "Keep the two sides structurally parallel."],
+    example: { layout: "comparison", title: "技术路线取舍", left: { label: "不优先", title: "端到端 Agent", bullets: ["流程封闭", "复核成本高"] }, right: { label: "优先", title: "MCP 工具链", bullets: ["跨客户端", "人类可介入"] } },
+  },
+  timeline: {
+    layout: "timeline",
+    purpose: "Show milestones along a horizontal timeline.",
+    whenToUse: "Use for roadmaps, phases, history, or scheduled work.",
+    fields: {
+      layout: { type: "literal", required: true, value: "timeline" },
+      title: { type: "string", required: true },
+      items: { type: "{ date? | phase?, title, text }[]", required: true },
+    },
+    limits: { items: { maxItems: 6 }, itemTitle: { recommendedChars: 10 }, itemText: { recommendedChars: 24 } },
+    notes: ["Use `date` for calendar time and `phase` for abstract stages.", "Avoid paragraph text in timeline nodes."],
+    example: { layout: "timeline", title: "路线图", items: [{ date: "阶段 1", title: "模板", text: "固化视觉规范。" }, { date: "阶段 2", title: "校验", text: "加入预检修复。" }] },
+  },
+  process: {
+    layout: "process",
+    purpose: "Show a linear process as connected steps.",
+    whenToUse: "Use for workflows, generation pipelines, or execution procedures.",
+    fields: {
+      layout: { type: "literal", required: true, value: "process" },
+      title: { type: "string", required: true },
+      steps: { type: "{ title, text }[]", required: true },
+    },
+    limits: { steps: { maxItems: 5 }, stepTitle: { recommendedChars: 8 }, stepText: { recommendedChars: 24 } },
+    notes: ["Steps are rendered left-to-right.", "Use `flowchart` for branching or non-linear processes."],
+    example: { layout: "process", title: "生成流程", steps: [{ title: "解析", text: "读取 YAML。" }, { title: "校验", text: "检查字段。" }, { title: "导出", text: "生成 PPTX。" }] },
+  },
+  problemSolution: {
+    layout: "problemSolution",
+    purpose: "Present problem, solution, and impact in three panels.",
+    whenToUse: "Use for proposal framing or product/research motivation.",
+    fields: {
+      layout: { type: "literal", required: true, value: "problemSolution" },
+      title: { type: "string", required: true },
+      problem: { type: "{ label?, title, bullets }", required: true },
+      solution: { type: "{ label?, title, bullets }", required: true },
+      impact: { type: "{ label?, title, bullets }", required: true },
+    },
+    limits: { panelTitle: { recommendedChars: 12 }, bullets: { maxItems: 4, recommendedChars: 26 } },
+    notes: ["Use this when the three blocks form one argument.", "Each panel supports a custom short `label`."],
+    example: { layout: "problemSolution", title: "问题与方案", problem: { title: "排版不稳", bullets: ["模型自由发挥导致溢出。"] }, solution: { title: "结构约束", bullets: ["YAML 固定字段。"] }, impact: { title: "可复核", bullets: ["输出可编辑 PPTX。"] } },
+  },
+  painOpportunity: {
+    layout: "painOpportunity",
+    purpose: "Frame current status, pain points, and opportunity.",
+    whenToUse: "Use for background analysis before introducing a solution.",
+    fields: {
+      layout: { type: "literal", required: true, value: "painOpportunity" },
+      title: { type: "string", required: true },
+      status: { type: "{ title, text? | bullets? }", required: true },
+      pain: { type: "{ title, text? | bullets? }", required: true },
+      opportunity: { type: "{ title, text? | bullets? }", required: true },
+    },
+    limits: { panelTitle: { recommendedChars: 12 }, bullets: { maxItems: 4, recommendedChars: 30 } },
+    notes: ["Panels use the same structure as `twoColumn` column blocks.", "Best for moving from observation to opportunity."],
+    example: { layout: "painOpportunity", title: "现状痛点与机会", status: { title: "现状", bullets: ["PPT 生成需求高。"] }, pain: { title: "痛点", bullets: ["直接生成不稳定。"] }, opportunity: { title: "机会", bullets: ["模板化生成可控。"] } },
+  },
+  experimentDesign: {
+    layout: "experimentDesign",
+    purpose: "Summarize an experiment setup.",
+    whenToUse: "Use before result slides to define data, variables, metrics, and baselines.",
+    fields: {
+      layout: { type: "literal", required: true, value: "experimentDesign" },
+      title: { type: "string", required: true },
+      dataset: { type: "string | string[]", required: false },
+      variables: { type: "string | string[]", required: false },
+      metrics: { type: "string | string[]", required: false },
+      baselines: { type: "string | string[]", required: false },
+      procedure: { type: "string[]", required: false },
+    },
+    limits: { eachBlock: { maxItems: 4, recommendedChars: 26 }, procedure: { maxItems: 5 } },
+    notes: ["Scalar strings are accepted and rendered as one bullet.", "Keep procedure items short because they render on one line."],
+    example: { layout: "experimentDesign", title: "实验设计", dataset: ["公开数据集 A"], variables: ["是否启用预检"], metrics: ["溢出页数"], baselines: ["直接生成 PPT"], procedure: ["准备输入", "生成", "人工复核"] },
+  },
+  resultAnalysis: {
+    layout: "resultAnalysis",
+    purpose: "State one finding, key metrics, and analysis bullets.",
+    whenToUse: "Use after experiments to connect numbers to interpretation.",
+    fields: {
+      layout: { type: "literal", required: true, value: "resultAnalysis" },
+      title: { type: "string", required: true },
+      finding: { type: "string", required: true },
+      metrics: { type: "{ value, label, note? }[]", required: false },
+      analysis: { type: "string[]", required: false },
+    },
+    limits: { finding: { recommendedChars: 52 }, metrics: { maxItems: 3 }, analysis: { maxItems: 4, recommendedChars: 38 } },
+    notes: ["Put the strongest result in `finding`.", "Metrics are compact; use `chart` for richer data."],
+    example: { layout: "resultAnalysis", title: "结果分析", finding: "预检显著减少长列表造成的页面溢出。", metrics: [{ value: "-80%", label: "溢出页", note: "相对基线" }], analysis: ["主要收益来自 bullets 和 references 拆页。"] },
+  },
+  riskMitigation: {
+    layout: "riskMitigation",
+    purpose: "Show risks, impacts, and mitigations in a table.",
+    whenToUse: "Use for project planning, deployment risk, or limitation handling.",
+    fields: {
+      layout: { type: "literal", required: true, value: "riskMitigation" },
+      title: { type: "string", required: true },
+      items: { type: "{ risk, impact, mitigation }[]", required: true },
+    },
+    limits: { items: { maxItems: 5 }, cell: { recommendedChars: 28 } },
+    notes: ["Keep mitigation actionable.", "Use this for risks; use `table` for arbitrary structured data."],
+    example: { layout: "riskMitigation", title: "风险与对策", items: [{ risk: "图片缺失", impact: "生成失败", mitigation: "使用 placeholder 并补 prompt" }] },
+  },
+  contribution: {
+    layout: "contribution",
+    purpose: "List the main contributions with numbered emphasis.",
+    whenToUse: "Use near the end of a research or project deck.",
+    fields: {
+      layout: { type: "literal", required: true, value: "contribution" },
+      title: { type: "string", required: true },
+      items: { type: "{ title, text }[]", required: true },
+    },
+    limits: { items: { maxItems: 4 }, itemTitle: { recommendedChars: 14 }, itemText: { recommendedChars: 44 } },
+    notes: ["Use one contribution per item.", "Avoid turning this into a general summary slide."],
+    example: { layout: "contribution", title: "主要贡献", items: [{ title: "可编辑输出", text: "文本、表格、图表均保留为 PPTX 对象。" }, { title: "公式支持", text: "LaTeX 公式转换为原生 OMML。" }] },
+  },
+  summary: {
+    layout: "summary",
+    purpose: "Close a section with one takeaway and supporting points.",
+    whenToUse: "Use at section endings or before the closing slide.",
+    fields: {
+      layout: { type: "literal", required: true, value: "summary" },
+      title: { type: "string", required: true },
+      takeaway: { type: "string", required: true },
+      points: { type: "string[]", required: false },
+    },
+    limits: { takeaway: { recommendedChars: 52 }, points: { maxItems: 5, recommendedChars: 36 } },
+    notes: ["`takeaway` should be a sentence, not a heading.", "Use `closing` only for the final thank-you page."],
+    example: { layout: "summary", title: "章节小结", takeaway: "结构化内容让 PPT 生成更稳定也更容易修复。", points: ["页面类型明确。", "校验信息可回传模型。"] },
+  },
+  architecture: {
+    layout: "architecture",
+    purpose: "Show a layered architecture with components and notes.",
+    whenToUse: "Use for systems, model stacks, or pipeline architecture.",
+    fields: {
+      layout: { type: "literal", required: true, value: "architecture" },
+      title: { type: "string", required: true },
+      layers: { type: "{ title, components, note? }[]", required: true },
+    },
+    limits: { layers: { maxItems: 4 }, layerTitle: { recommendedChars: 8 }, components: { maxItems: 5, recommendedChars: 10 }, note: { recommendedChars: 44 } },
+    notes: ["Layer order is top-to-bottom.", "Use short component labels so chips stay readable."],
+    example: { layout: "architecture", title: "系统架构", layers: [{ title: "输入层", components: ["YAML", "图片"], note: "收集结构化材料。" }, { title: "生成层", components: ["校验", "PPTX", "OMML"], note: "写入可编辑对象。" }] },
+  },
+  ablation: {
+    layout: "ablation",
+    purpose: "Summarize ablation factors, settings, deltas, and conclusions.",
+    whenToUse: "Use for research experiments that remove or vary components.",
+    fields: {
+      layout: { type: "literal", required: true, value: "ablation" },
+      title: { type: "string", required: true },
+      baseline: { type: "string", required: false },
+      items: { type: "{ factor, setting, delta, conclusion }[]", required: true },
+    },
+    limits: { baseline: { recommendedChars: 58 }, items: { maxItems: 6 }, factor: { recommendedChars: 18 }, setting: { recommendedChars: 18 }, delta: { recommendedChars: 18 }, conclusion: { recommendedChars: 28 } },
+    notes: ["Use `delta` for numeric or qualitative change.", "Keep conclusions short enough for table-like rendering."],
+    example: { layout: "ablation", title: "消融实验", baseline: "基线启用所有模块。", items: [{ factor: "预检", setting: "关闭", delta: "+3 overflow", conclusion: "长列表风险上升" }] },
+  },
+  caseStudy: {
+    layout: "caseStudy",
+    purpose: "Show one visual case with context, method, and result.",
+    whenToUse: "Use for qualitative examples, screenshots, or representative samples.",
+    fields: {
+      layout: { type: "literal", required: true, value: "caseStudy" },
+      title: { type: "string", required: true },
+      image: { type: "string | { path, fit? } | { mode: placeholder, prompt, aspectRatio? }", required: true },
+      caption: { type: "string", required: false },
+      context: { type: "string[]", required: false },
+      method: { type: "string[]", required: false },
+      result: { type: "string[]", required: false },
+    },
+    limits: { caption: { recommendedChars: 40 }, context: { maxItems: 2, recommendedChars: 34 }, method: { maxItems: 2, recommendedChars: 34 }, result: { maxItems: 2, recommendedChars: 34 } },
+    notes: ["Image placeholders are supported.", "Use `imageGrid` when comparing multiple images."],
+    example: { layout: "caseStudy", title: "案例分析", image: "assets/bit-campus-photo.png", caption: "示例图片，可替换为实验结果图。", context: ["输入是一段论文草稿。"], method: ["生成器按 layout 写入 PPTX。"], result: ["输出可继续编辑。"] },
+  },
+  imageGrid: {
+    layout: "imageGrid",
+    purpose: "Show multiple images in a regular grid.",
+    whenToUse: "Use for visual result sets, comparisons, or qualitative examples.",
+    fields: {
+      layout: { type: "literal", required: true, value: "imageGrid" },
+      title: { type: "string", required: true },
+      images: { type: "(string | { path, caption? } | { mode: placeholder, prompt, caption?, aspectRatio? })[]", required: true },
+    },
+    limits: { images: { maxItems: 6 }, caption: { recommendedChars: 16 } },
+    notes: ["Each image can be a local path or an image object.", "Use short captions to avoid crowding the grid."],
+    example: { layout: "imageGrid", title: "多图结果", images: [{ path: "assets/bit-campus-photo.png", caption: "输入" }, { path: "assets/bit-campus-photo.png", caption: "输出" }] },
+  },
+  code: {
+    layout: "code",
+    purpose: "Show pseudocode or a compact code block with notes.",
+    whenToUse: "Use for algorithms, command snippets, or implementation sketches.",
+    fields: {
+      layout: { type: "literal", required: true, value: "code" },
+      title: { type: "string", required: true },
+      language: { type: "string", required: false },
+      code: { type: "string", required: false },
+      algorithm: { type: "string", required: false },
+      noteTitle: { type: "string", required: false },
+      notes: { type: "string[]", required: false },
+    },
+    limits: { code: { recommendedLines: 12, recommendedCharsPerLine: 72 }, notes: { maxItems: 5, recommendedChars: 32 } },
+    notes: ["Use either `code` or `algorithm`; `code` takes precedence.", "A YAML block scalar is recommended for multi-line code."],
+    example: { layout: "code", title: "算法伪代码", language: "Algorithm", code: "Input: deck D\n1. validate D\n2. generate PPTX", noteTitle: "关键约束", notes: ["代码块保持短行。"] },
+  },
+  appendix: {
+    layout: "appendix",
+    purpose: "Create an appendix index or supplemental topic list.",
+    whenToUse: "Use for backup slides, extra details, or appendix navigation.",
+    fields: {
+      layout: { type: "literal", required: true, value: "appendix" },
+      title: { type: "string", required: true },
+      items: { type: "{ key?, title, text }[]", required: true },
+    },
+    limits: { items: { maxItems: 8 }, itemTitle: { recommendedChars: 14 }, itemText: { recommendedChars: 42 } },
+    notes: ["`key` is optional and defaults to a numbered label.", "Use this as an index, not as dense body text."],
+    example: { layout: "appendix", title: "附录索引", items: [{ key: "A1", title: "数据细节", text: "样本来源与筛选规则。" }] },
+  },
+  metrics: {
+    layout: "metrics",
+    purpose: "Highlight up to four key metrics.",
+    whenToUse: "Use when numeric or compact KPI-style facts should dominate the slide.",
+    fields: {
+      layout: { type: "literal", required: true, value: "metrics" },
+      title: { type: "string", required: true },
+      metrics: { type: "{ value, label, note? }[]", required: true },
+    },
+    limits: { metrics: { maxItems: 4 }, value: { recommendedChars: 8 }, label: { recommendedChars: 12 }, note: { recommendedChars: 30 } },
+    notes: ["Use compact values such as `12+`, `-8%`, or `0`.", "Use `chart` when the reader needs to inspect a trend or distribution."],
+    example: { layout: "metrics", title: "关键指标", metrics: [{ value: "12+", label: "正文页型", note: "覆盖常见汇报页面" }, { value: "100%", label: "可编辑", note: "原生 PPTX 对象" }] },
+  },
+  matrix: {
+    layout: "matrix",
+    purpose: "Show four quadrants or a compact 2x2 decision matrix.",
+    whenToUse: "Use for strategy tradeoffs, option classification, or two-axis judgment.",
+    fields: {
+      layout: { type: "literal", required: true, value: "matrix" },
+      title: { type: "string", required: true },
+      cells: { type: "{ title, text }[]", required: true },
+    },
+    limits: { cells: { maxItems: 4 }, cellTitle: { recommendedChars: 18 }, cellText: { recommendedChars: 52 } },
+    notes: ["Cells render row-major in a 2x2 grid.", "Provide exactly four cells for a complete matrix."],
+    example: { layout: "matrix", title: "方案判断矩阵", cells: [{ title: "低成本 / 高控制", text: "YAML 内容加模板生成。" }, { title: "高成本 / 高控制", text: "完整设计系统与截图校验。" }] },
+  },
+  quote: {
+    layout: "quote",
+    purpose: "Show a short quote or memorable statement.",
+    whenToUse: "Use for thesis statements, external quotes, or section openers.",
+    fields: {
+      layout: { type: "literal", required: true, value: "quote" },
+      title: { type: "string", required: false },
+      quote: { type: "string", required: true },
+      source: { type: "string", required: false },
+    },
+    limits: { quote: { recommendedChars: 70 } },
+    notes: ["Keep the quote short enough to remain visually dominant.", "`source` is optional and rendered below the quote."],
+    example: { layout: "quote", title: "引用页", quote: "让模型生成结构化内容，让模板承担视觉和排版责任。", source: "BIT PPT Template Generator" },
+  },
+  references: {
+    layout: "references",
+    purpose: "List references or citations.",
+    whenToUse: "Use near the end of academic or research decks.",
+    fields: {
+      layout: { type: "literal", required: true, value: "references" },
+      title: { type: "string", required: false },
+      items: { type: "string[]", required: true },
+      fontSize: { type: "number", required: false },
+    },
+    limits: { items: { recommendedChars: 140 } },
+    notes: ["Long reference lists may be split during preflight.", "Keep each reference as one string item."],
+    example: { layout: "references", title: "参考文献", items: ["PptxGenJS project documentation. Generate editable PowerPoint presentations with JavaScript."] },
+  },
+  closing: {
+    layout: "closing",
+    purpose: "Create the final thank-you slide.",
+    whenToUse: "Use as the final slide of a deck.",
+    fields: {
+      layout: { type: "literal", required: true, value: "closing" },
+      title: { type: "string", required: false },
+      subtitle: { type: "string", required: false },
+    },
+    limits: { title: { recommendedChars: 12 }, subtitle: { recommendedChars: 28 } },
+    notes: ["Defaults to a BIT green closing slide.", "Use `subtitle` for defense/Q&A wording."],
+    example: { layout: "closing", title: "谢谢", subtitle: "敬请各位老师批评指正" },
+  },
+};
+
+Object.assign(layoutGuides, additionalLayoutGuides);
+
 function listGuideLayouts() {
-  return Object.keys(layoutGuides);
+  return listSupportedLayouts();
 }
 
 function getLayoutGuide(layout) {