@panda-agent/panda-cli 0.1.28 → 0.1.30

package/skills/pptx-generator/references/layout_guide.md

@@ -0,0 +1,290 @@
+# 布局指南
+
+本文档详细说明了 pptx-generator 支持的各种布局类型及其使用场景。
+
+## 目录
+1. [布局概述](#布局概述)
+2. [布局类型详解](#布局类型详解)
+3. [布局选择建议](#布局选择建议)
+4. [自定义布局](#自定义布局)
+
+---
+
+## 布局概述
+
+pptx-generator 支持多种预设布局类型，每种布局适用于不同的内容场景。
+
+| 布局类型 | 标题位置 | 内容位置 | 适用场景 |
+|----------|----------|----------|----------|
+| TitleSlide | 顶部中央 | 下方列表 | 封面、标题页 |
+| ContentSlide | 顶部 | 正文内容 | 标准内容页 |
+| TwoColumnSlide | 顶部 | 两栏内容 | 对比、并列内容 |
+| SectionHeaderSlide | 中央 | 无 | 章节页 |
+| ContentWithCaptionSlide | 顶部 | 内容 + 说明 | 图片 + 文字 |
+| SummarySlide | 顶部 | 总结内容 | 总结、结尾页 |
+
+---
+
+## 布局类型详解
+
+### 1. TitleSlide (标题页)
+
+**描述**：标题页布局，标题位于中央，内容作为副标题或要点展示。
+
+**适用场景**：
+- 演示文稿封面
+- 标题页
+- 章节标题页
+
+**JSON 示例**：
+```json
+{
+  "layout": "TitleSlide",
+  "title": "AI 智能助手",
+  "content": [
+    "新一代人工智能助手",
+    "提升工作效率",
+    "智能对话交互"
+  ],
+  "notes": "开场白"
+}
+```
+
+**布局特点**：
+- 标题：大字号、居中、加粗
+- 内容：中等字号、居中、项目符号
+- 适合：1-3 个要点
+
+---
+
+### 2. ContentSlide (内容页)
+
+**描述**：标准内容页布局，标题在顶部，内容在下方。
+
+**适用场景**：
+- 大部分幻灯片
+- 内容展示
+- 要点列表
+
+**JSON 示例**：
+```json
+{
+  "layout": "ContentSlide",
+  "title": "核心功能",
+  "content": [
+    "自然语言理解",
+    "智能内容生成",
+    "多模态交互",
+    "个性化定制"
+  ],
+  "notes": "详细介绍功能"
+}
+```
+
+**布局特点**：
+- 标题：大字号、左对齐、加粗
+- 内容：中等字号、左对齐、项目符号
+- 适合：3-7 个要点
+
+---
+
+### 3. TwoColumnSlide (两栏页)
+
+**描述**：两栏布局，标题在顶部，内容分为左右两栏。
+
+**适用场景**：
+- 对比展示
+- 并列内容
+- 分类展示
+
+**JSON 示例**：
+```json
+{
+  "layout": "TwoColumnSlide",
+  "title": "产品对比",
+  "content": [
+    "旧版本：功能单一",
+    "旧版本：界面陈旧",
+    "新版本：功能丰富",
+    "新版本：界面现代"
+  ],
+  "notes": "对比旧版本和新版本"
+}
+```
+
+**布局特点**：
+- 标题：大字号、左对齐、加粗
+- 内容：中等字号、两栏对齐
+- 适合：4-8 个要点（平均分配到两栏）
+
+---
+
+### 4. SectionHeaderSlide (章节页)
+
+**描述**：章节标题页布局，仅显示章节标题，无内容。
+
+**适用场景**：
+- 章节分隔
+- 主题切换
+- 过渡页
+
+**JSON 示例**：
+```json
+{
+  "layout": "SectionHeaderSlide",
+  "title": "第一部分：产品概述",
+  "content": [],
+  "notes": "章节分隔页"
+}
+```
+
+**布局特点**：
+- 标题：超大字号、居中、加粗
+- 内容：无
+- 适合：仅标题
+
+---
+
+### 5. ContentWithCaptionSlide (带说明的内容页)
+
+**描述**：内容页布局，标题在顶部，内容在下方，支持额外的说明文字。
+
+**适用场景**：
+- 图片展示
+- 图表说明
+- 数据展示
+
+**JSON 示例**：
+```json
+{
+  "layout": "ContentWithCaptionSlide",
+  "title": "用户增长数据",
+  "content": [
+    "2024年 Q1：100万用户",
+    "2024年 Q2：150万用户",
+    "2024年 Q3：200万用户"
+  ],
+  "notes": "图表说明：用户呈现稳定增长趋势"
+}
+```
+
+**布局特点**：
+- 标题：大字号、左对齐、加粗
+- 内容：中等字号、左对齐
+- 说明：小字号、左对齐、斜体
+- 适合：3-5 个要点 + 详细说明
+
+---
+
+### 6. SummarySlide (总结页)
+
+**描述**：总结页布局，标题在顶部，总结内容在下方。
+
+**适用场景**：
+- 演示文稿结尾
+- 章节总结
+- 要点回顾
+
+**JSON 示例**：
+```json
+{
+  "layout": "SummarySlide",
+  "title": "总结",
+  "content": [
+    "AI 智能助手",
+    "提升效率，创造价值",
+    "开启智能新时代"
+  ],
+  "notes": "总结发言"
+}
+```
+
+**布局特点**：
+- 标题：大字号、左对齐、加粗
+- 内容：中等字号、左对齐、项目符号
+- 适合：3-5 个要点
+
+---
+
+## 布局选择建议
+
+### 根据内容类型选择
+
+| 内容类型 | 推荐布局 | 原因 |
+|----------|----------|------|
+| 封面、标题 | TitleSlide | 标题突出，视觉冲击 |
+| 标准内容 | ContentSlide | 经典布局，易于阅读 |
+| 对比内容 | TwoColumnSlide | 两栏对比，清晰明了 |
+| 章节分隔 | SectionHeaderSlide | 简洁明了，区分章节 |
+| 图片/图表 | ContentWithCaptionSlide | 内容 + 说明，完整呈现 |
+| 总结、结尾 | SummarySlide | 重点突出，便于记忆 |
+
+### 根据内容数量选择
+
+| 内容数量 | 推荐布局 | 说明 |
+|----------|----------|------|
+| 1-3 个要点 | TitleSlide | 突出重点，简洁明了 |
+| 3-7 个要点 | ContentSlide | 标准布局，适合大多数场景 |
+| 4-8 个要点 | TwoColumnSlide | 两栏分布，避免拥挤 |
+| 无内容 | SectionHeaderSlide | 仅标题，章节分隔 |
+| 3-5 个要点 + 说明 | ContentWithCaptionSlide | 内容 + 说明，完整呈现 |
+| 3-5 个要点 | SummarySlide | 总结回顾，重点突出 |
+
+---
+
+## 自定义布局
+
+### 使用 notes 字段
+
+`notes` 字段可用于添加额外的说明文字，不会在幻灯片上显示，但在 PowerPoint 的备注窗格中可见。
+
+```json
+{
+  "title": "核心功能",
+  "content": ["功能1", "功能2"],
+  "notes": "演讲提示：详细解释每个功能的应用场景"
+}
+```
+
+### 省略 layout 字段
+
+如果 `layout` 字段省略，pptx-generator 将自动选择合适的布局：
+
+- 第一页：使用 TitleSlide
+- 最后一页：使用 SummarySlide
+- 其他页面：使用 ContentSlide
+
+### 内容数量自适应
+
+pptx-generator 会根据内容数量自动调整布局：
+
+- 1-3 个要点：使用 TitleSlide
+- 3-7 个要点：使用 ContentSlide
+- 4-8 个要点：使用 TwoColumnSlide
+
+---
+
+## 最佳实践
+
+### 1. 保持布局一致性
+
+在同一个演示文稿中，尽量使用相似的布局风格，避免过于频繁的布局切换。
+
+### 2. 合理使用章节页
+
+在较长的演示文稿中，使用 SectionHeaderSlide 进行章节分隔，帮助听众理解内容结构。
+
+### 3. 避免内容过载
+
+每页幻灯片的内容数量建议：
+- 最少：1 个要点
+- 最多：8 个要点
+- 推荐：3-5 个要点
+
+### 4. 使用备注
+
+使用 `notes` 字段添加演讲提示，帮助自己在演讲时更好地表达。
+
+### 5. 测试不同布局
+
+生成 PPTX 文件后，在 PowerPoint 中打开，查看实际效果，必要时调整布局类型。

package/skills/pptx-generator/scripts/json_validator.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""
+JSON Validator - Validate JSON format for PPT generation.
+
+This module validates JSON data to ensure it conforms to the
+expected format for PPT generation.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+
+# =============================================================================
+# JSON Validator
+# =============================================================================
+
+class JSONValidator:
+    """Validator for JSON format."""
+
+    def __init__(self):
+        """Initialize JSON validator."""
+        self.errors = []
+        self.warnings = []
+
+    def validate(self, json_path: str) -> bool:
+        """
+        Validate JSON file.
+
+        Args:
+            json_path: Path to JSON file.
+
+        Returns:
+            True if valid, False otherwise.
+        """
+        print(f"验证 JSON 文件: {json_path}\n")
+
+        try:
+            with open(json_path, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+        except FileNotFoundError:
+            self.errors.append(f"文件不存在: {json_path}")
+            return False
+        except json.JSONDecodeError as e:
+            self.errors.append(f"JSON 解析错误: {e}")
+            return False
+
+        # Validate structure
+        self._validate_structure(data)
+
+        # Print results
+        self._print_results()
+
+        return len(self.errors) == 0
+
+    def _validate_structure(self, data: Dict[str, Any]) -> None:
+        """
+        Validate JSON structure.
+
+        Args:
+            data: JSON data dictionary.
+        """
+        # Check metadata
+        if 'metadata' not in data:
+            self.warnings.append("缺少 'metadata' 字段（推荐）")
+        else:
+            self._validate_metadata(data['metadata'])
+
+        # Check slides
+        if 'slides' not in data:
+            self.errors.append("缺少 'slides' 字段（必需）")
+            return
+
+        if not isinstance(data['slides'], list):
+            self.errors.append("'slides' 必须是数组")
+            return
+
+        if len(data['slides']) == 0:
+            self.errors.append("'slides' 数组不能为空")
+            return
+
+        # Validate each slide
+        for i, slide in enumerate(data['slides'], 1):
+            self._validate_slide(slide, i)
+
+    def _validate_metadata(self, metadata: Dict[str, Any]) -> None:
+        """
+        Validate metadata.
+
+        Args:
+            metadata: Metadata dictionary.
+        """
+        if not isinstance(metadata, dict):
+            self.errors.append("'metadata' 必须是对象")
+            return
+
+        if 'title' not in metadata:
+            self.warnings.append("metadata 中缺少 'title' 字段（推荐）")
+
+        if 'author' not in metadata:
+            self.warnings.append("metadata 中缺少 'author' 字段（可选）")
+
+        if 'theme' not in metadata:
+            self.warnings.append("metadata 中缺少 'theme' 字段（可选）")
+
+    def _validate_slide(self, slide: Dict[str, Any], index: int) -> None:
+        """
+        Validate a slide.
+
+        Args:
+            slide: Slide data dictionary.
+            index: Slide index.
+        """
+        if not isinstance(slide, dict):
+            self.errors.append(f"幻灯片 {index} 必须是对象")
+            return
+
+        # Check title
+        if 'title' not in slide:
+            self.errors.append(f"幻灯片 {index} 缺少 'title' 字段（必需）")
+        elif not isinstance(slide['title'], str):
+            self.errors.append(f"幻灯片 {index} 的 'title' 必须是字符串")
+        elif not slide['title'].strip():
+            self.errors.append(f"幻灯片 {index} 的 'title' 不能为空")
+
+        # Check content
+        if 'content' not in slide:
+            self.errors.append(f"幻灯片 {index} 缺少 'content' 字段（必需）")
+        elif not isinstance(slide['content'], list):
+            self.errors.append(f"幻灯片 {index} 的 'content' 必须是数组")
+        elif len(slide['content']) == 0:
+            self.warnings.append(f"幻灯片 {index} 的 'content' 数组为空")
+        else:
+            # Validate content items
+            for j, item in enumerate(slide['content'], 1):
+                if not isinstance(item, str):
+                    self.errors.append(f"幻灯片 {index} 的 content[{j}] 必须是字符串")
+
+        # Check optional fields
+        if 'layout' in slide and not isinstance(slide['layout'], str):
+            self.warnings.append(f"幻灯片 {index} 的 'layout' 应该是字符串")
+
+        if 'notes' in slide and not isinstance(slide['notes'], str):
+            self.warnings.append(f"幻灯片 {index} 的 'notes' 应该是字符串")
+
+    def _print_results(self) -> None:
+        """Print validation results."""
+        if self.errors:
+            print(f"❌ 发现 {len(self.errors)} 个错误：\n")
+            for i, error in enumerate(self.errors, 1):
+                print(f"  {i}. {error}")
+            print()
+
+        if self.warnings:
+            print(f"⚠️  发现 {len(self.warnings)} 个警告：\n")
+            for i, warning in enumerate(self.warnings, 1):
+                print(f"  {i}. {warning}")
+            print()
+
+        if not self.errors and not self.warnings:
+            print("✓ JSON 格式验证通过！\n")
+
+
+# =============================================================================
+# Main Function
+# =============================================================================
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description='Validate JSON format for PPT generation'
+    )
+    parser.add_argument(
+        '--input', '-i',
+        required=True,
+        help='Input JSON file path'
+    )
+
+    args = parser.parse_args()
+
+    # Create validator
+    validator = JSONValidator()
+
+    # Validate
+    is_valid = validator.validate(args.input)
+
+    # Exit with appropriate code
+    sys.exit(0 if is_valid else 1)
+
+
+if __name__ == '__main__':
+    main()