codewave-openclaw-installer 1.0.2 → 2.1.1

package/skills/ppt-master/scripts/docs/troubleshooting.md

@@ -0,0 +1,62 @@
+# Troubleshooting
+
+## Validation Failed
+
+1. Run:
+
+```bash
+python3 scripts/project_manager.py validate <project_path>
+```
+
+2. Fix missing files or invalid directories reported by the validator.
+3. Re-run validation before post-processing or export.
+
+## SVG Preview Looks Wrong
+
+1. Check the file path and filename.
+2. Confirm naming conventions are consistent.
+3. Preview via a local server if browser file loading is inconsistent:
+
+```bash
+python3 -m http.server --directory <svg_output_path> 8000
+```
+
+## Speaker Notes Do Not Split
+
+Check `total.md`:
+- headings must start with `# `
+- heading text must match SVG filenames
+- sections must be separated by `---`
+
+Then rerun:
+
+```bash
+python3 scripts/total_md_split.py <project_path>
+```
+
+## PPT Export Quality Issues
+
+Preferred sequence:
+
+```bash
+python3 scripts/total_md_split.py <project_path>
+python3 scripts/finalize_svg.py <project_path>
+python3 scripts/svg_to_pptx.py <project_path> -s final
+```
+
+Do not export directly from `svg_output/` when `svg_final/` exists.
+
+## Dependency Checklist
+
+Most tools use the standard library. Install extra dependencies only when needed:
+
+```bash
+pip install -r requirements.txt
+```
+
+Important optional packages:
+- `python-pptx` for PPTX export
+- `Pillow` for image utilities
+- `numpy` for watermark removal
+- `PyMuPDF` for PDF conversion
+- `google-genai` / `openai` for image generation backends

package/skills/ppt-master/scripts/error_helper.py

@@ -0,0 +1,438 @@
+#!/usr/bin/env python3
+"""
+PPT Master - Error Message Helper
+
+Provides user-friendly error messages and specific fix suggestions.
+"""
+
+from typing import Dict, List, Optional
+
+
+class ErrorHelper:
+    """Error message helper."""
+
+    # Error types and their corresponding fix suggestions
+    ERROR_SOLUTIONS = {
+        'missing_readme': {
+            'message': 'Missing README.md file',
+            'solutions': [
+                'Create a README.md file with project description, usage instructions, etc.',
+                'Reference template: examples/google_annual_report_ppt169_20251116/README.md',
+                'Or use command: cp examples/google_annual_report_ppt169_20251116/README.md <your_project>/'
+            ],
+            'severity': 'error'
+        },
+        'missing_spec': {
+            'message': 'Missing design specification file',
+            'solutions': [
+                'Create a design_specification.md file',
+                'Include: canvas specs, color scheme, font specs, layout specs, content outline',
+                'Refer to the design specification generated by the Strategist role'
+            ],
+            'severity': 'warning'
+        },
+        'missing_svg_output': {
+            'message': 'Missing svg_output directory',
+            'solutions': [
+                'Create the svg_output directory: mkdir svg_output',
+                'Place generated SVG files in this directory',
+                'Ensure SVG files follow naming convention: slide_XX_name.svg'
+            ],
+            'severity': 'error'
+        },
+        'empty_svg_output': {
+            'message': 'svg_output directory is empty',
+            'solutions': [
+                'Use the AI role (Executor) to generate SVG files',
+                'Save SVG files to the svg_output directory',
+                'Ensure file naming format: slide_01_cover.svg, slide_02_content.svg, etc.'
+            ],
+            'severity': 'warning'
+        },
+        'invalid_svg_naming': {
+            'message': 'Non-standard SVG file naming',
+            'solutions': [
+                'Rename SVG files using format: slide_XX_name.svg',
+                'XX should be a two-digit number (01, 02, ...)',
+                'name should use English or pinyin, separated by underscores',
+                'Example: slide_01_cover.svg, slide_02_overview.svg'
+            ],
+            'severity': 'warning'
+        },
+        'missing_project_date': {
+            'message': 'Project directory missing date suffix',
+            'solutions': [
+                'Rename the project directory to add a date suffix: _YYYYMMDD',
+                'Format: {project_name}_{format}_{YYYYMMDD}',
+                'Example: my_project_ppt169_20251116',
+                'Command: mv old_name new_name_ppt169_20251116'
+            ],
+            'severity': 'warning'
+        },
+        'viewbox_mismatch': {
+            'message': 'SVG viewBox does not match canvas format',
+            'solutions': [
+                'Check the viewBox attribute of SVG files',
+                'Ensure it matches the project canvas format',
+                'PPT 16:9 should be: viewBox="0 0 1280 720"',
+                'PPT 4:3 should be: viewBox="0 0 1024 768"',
+                'Reference: references/canvas-formats.md'
+            ],
+            'severity': 'warning'
+        },
+        'multiple_viewboxes': {
+            'message': 'Multiple different viewBox settings detected',
+            'solutions': [
+                'Unify the viewBox across all SVG files',
+                'All pages in the same project should use the same canvas size',
+                'Use find-and-replace tools for batch correction',
+                'Reference the viewBox setting of the first page'
+            ],
+            'severity': 'warning'
+        },
+        'no_viewbox': {
+            'message': 'SVG file missing viewBox attribute',
+            'solutions': [
+                'Add the viewBox attribute to the SVG root element',
+                'Format: <svg viewBox="0 0 1280 720" ...>',
+                'Ensure width, height are consistent with viewBox',
+                'This is a mandatory requirement for SVG generation'
+            ],
+            'severity': 'error'
+        },
+        'foreignobject_detected': {
+            'message': 'Forbidden <foreignObject> element detected',
+            'solutions': [
+                'Remove <foreignObject> elements',
+                'Use <text> + <tspan> for manual line wrapping',
+                'This is a project technical specification requirement',
+                'Reference: references/shared-standards.md'
+            ],
+            'severity': 'error'
+        },
+        'clippath_detected': {
+            'message': 'Forbidden <clipPath> element detected',
+            'solutions': [
+                'Remove <clipPath> elements',
+                'PPT does not support SVG clipping paths',
+                'Use basic shape combinations as an alternative to clipping'
+            ],
+            'severity': 'error'
+        },
+        'mask_detected': {
+            'message': 'Forbidden <mask> element detected',
+            'solutions': [
+                'Remove <mask> elements',
+                'PPT does not support SVG masks',
+                'Use opacity (opacity/fill-opacity) as an alternative'
+            ],
+            'severity': 'error'
+        },
+        'style_element_detected': {
+            'message': 'Forbidden <style> element detected',
+            'solutions': [
+                'Remove <style> elements',
+                'Convert CSS styles to inline attributes',
+                'Example: fill="#000" instead of class="text-black"'
+            ],
+            'severity': 'error'
+        },
+        'class_attribute_detected': {
+            'message': 'Forbidden class attribute detected',
+            'solutions': [
+                'Remove all class attributes',
+                'Use inline styles instead',
+                'Example: fill="#000" stroke="#333" directly on the element'
+            ],
+            'severity': 'error'
+        },
+        'id_attribute_detected': {
+            'message': 'Forbidden id attribute detected',
+            'solutions': [
+                'Remove all id attributes',
+                'Use inline styles instead',
+                'Avoid relying on selectors for positioning or style reuse'
+            ],
+            'severity': 'error'
+        },
+        'external_css_detected': {
+            'message': 'Forbidden external CSS reference detected',
+            'solutions': [
+                'Remove <?xml-stylesheet?> declarations',
+                'Remove <link rel="stylesheet"> references',
+                'Remove @import external styles',
+                'Convert styles to inline attributes'
+            ],
+            'severity': 'error'
+        },
+        'symbol_use_detected': {
+            'message': 'Forbidden <symbol> + <use> complex usage detected',
+            'solutions': [
+                'Expand <symbol> into actual SVG code',
+                'Avoid <symbol> + <use> reuse structures',
+                'Embed SVG paths directly when icons are needed'
+            ],
+            'severity': 'error'
+        },
+        'marker_detected': {
+            'message': 'Forbidden <marker> element detected',
+            'solutions': [
+                'Remove <marker> definitions',
+                'Use line + polygon to draw arrows',
+                'Reference the arrow drawing approach in AGENTS.md'
+            ],
+            'severity': 'error'
+        },
+        'marker_end_detected': {
+            'message': 'Forbidden marker-end attribute detected',
+            'solutions': [
+                'Remove marker-end attributes',
+                'Use line + polygon to draw arrows',
+                'Ensure arrow direction matches the line'
+            ],
+            'severity': 'error'
+        },
+        'rgba_detected': {
+            'message': 'Forbidden rgba() color detected',
+            'solutions': [
+                'Replace rgba() with hex + opacity notation',
+                'Example: fill="#FFFFFF" fill-opacity="0.1"',
+                'Use stroke-opacity for strokes'
+            ],
+            'severity': 'error'
+        },
+        'group_opacity_detected': {
+            'message': 'Forbidden <g opacity> detected',
+            'solutions': [
+                'Remove group-level opacity',
+                'Set opacity individually on each child element',
+                'Use fill-opacity / stroke-opacity for control'
+            ],
+            'severity': 'error'
+        },
+        'image_opacity_detected': {
+            'message': 'Forbidden <image opacity> detected',
+            'solutions': [
+                'Remove image opacity attribute',
+                'Add a <rect> overlay to control transparency',
+                'Ensure overlay color matches the background'
+            ],
+            'severity': 'error'
+        },
+        'event_attribute_detected': {
+            'message': 'Forbidden event attribute detected',
+            'solutions': [
+                'Remove onclick/onload and other event attributes',
+                'Scripts and event handling are forbidden in SVG',
+                'Implement interactivity in PPT instead'
+            ],
+            'severity': 'error'
+        },
+        'set_detected': {
+            'message': 'Forbidden <set> element detected',
+            'solutions': [
+                'Remove <set> elements',
+                'SVG animations will not be exported to PPT',
+                'Use PPT native animations for animation effects'
+            ],
+            'severity': 'error'
+        },
+        'iframe_detected': {
+            'message': 'Forbidden <iframe> element detected',
+            'solutions': [
+                'Remove <iframe> elements',
+                'External pages should not be embedded in SVG'
+            ],
+            'severity': 'error'
+        },
+        'textpath_detected': {
+            'message': 'Forbidden <textPath> element detected',
+            'solutions': [
+                'Remove <textPath> elements',
+                'Text on path is not compatible with PPT',
+                'Use regular <text> elements and adjust position manually'
+            ],
+            'severity': 'error'
+        },
+        'webfont_detected': {
+            'message': 'Forbidden web font (@font-face) detected',
+            'solutions': [
+                'Remove @font-face declarations',
+                'Use the system font stack',
+                'font-family: system-ui, -apple-system, sans-serif'
+            ],
+            'severity': 'error'
+        },
+        'animation_detected': {
+            'message': 'Forbidden SMIL animation element detected',
+            'solutions': [
+                'Remove all <animate>, <animateMotion>, <animateTransform> and similar elements',
+                'SVG animations will not be exported to PPT',
+                'Use PPT native animations for animation effects'
+            ],
+            'severity': 'error'
+        },
+        'script_detected': {
+            'message': 'Forbidden <script> element detected',
+            'solutions': [
+                'Remove <script> elements',
+                'Scripts and event handling are forbidden',
+                'JavaScript in SVG will not execute in PPT'
+            ],
+            'severity': 'error'
+        },
+        'invalid_font': {
+            'message': 'Non-standard font used',
+            'solutions': [
+                'Use the system UI font stack',
+                'font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+                'Avoid using specific font names (e.g. Arial, Helvetica)',
+                'Ensure cross-platform compatibility'
+            ],
+            'severity': 'warning'
+        }
+    }
+
+    @classmethod
+    def get_solution(cls, error_type: str, context: Optional[Dict] = None) -> Dict:
+        """
+        Get the solution for an error.
+
+        Args:
+            error_type: Error type
+            context: Context information (optional)
+
+        Returns:
+            Dictionary containing message, solutions, severity
+        """
+        if error_type in cls.ERROR_SOLUTIONS:
+            solution = cls.ERROR_SOLUTIONS[error_type].copy()
+
+            # Customize message based on context
+            if context:
+                solution = cls._customize_solution(solution, context)
+
+            return solution
+
+        # Unknown error type
+        return {
+            'message': 'Unknown error',
+            'solutions': ['Please check the documentation or contact the maintainer'],
+            'severity': 'error'
+        }
+
+    @classmethod
+    def _customize_solution(cls, solution: Dict, context: Dict) -> Dict:
+        """
+        Customize solution based on context.
+
+        Args:
+            solution: Original solution
+            context: Context information
+
+        Returns:
+            Customized solution
+        """
+        customized = solution.copy()
+
+        # Customize based on project path
+        if 'project_path' in context:
+            project_path = context['project_path']
+            customized['solutions'] = [
+                s.replace('<project_path>', project_path).replace(
+                    '<your_project>', project_path)
+                for s in customized['solutions']
+            ]
+
+        # Customize based on filename
+        if 'file_name' in context:
+            file_name = context['file_name']
+            customized['message'] = f"{customized['message']}: {file_name}"
+
+        # Customize based on expected/actual values
+        if 'expected' in context and 'actual' in context:
+            customized['message'] += f" (expected: {context['expected']}, actual: {context['actual']})"
+
+        return customized
+
+    @classmethod
+    def format_error_message(cls, error_type: str, context: Optional[Dict] = None) -> str:
+        """
+        Format error message (for terminal output).
+
+        Args:
+            error_type: Error type
+            context: Context information
+
+        Returns:
+            Formatted error message string
+        """
+        solution = cls.get_solution(error_type, context)
+
+        lines = []
+
+        # Error message
+        severity_icon = "[ERROR]" if solution['severity'] == 'error' else "[WARN]"
+        lines.append(f"{severity_icon} {solution['message']}")
+
+        # Solutions
+        if solution['solutions']:
+            lines.append("\nSuggested fixes:")
+            for i, sol in enumerate(solution['solutions'], 1):
+                lines.append(f"   {i}. {sol}")
+
+        return "\n".join(lines)
+
+    @classmethod
+    def print_error(cls, error_type: str, context: Optional[Dict] = None):
+        """
+        Print formatted error message.
+
+        Args:
+            error_type: Error type
+            context: Context information
+        """
+        print(cls.format_error_message(error_type, context))
+
+    @classmethod
+    def get_all_error_types(cls) -> List[str]:
+        """Get all supported error types."""
+        return list(cls.ERROR_SOLUTIONS.keys())
+
+    @classmethod
+    def print_help(cls):
+        """Print all error types and solutions."""
+        print("PPT Master - Error Types and Solutions\n")
+        print("=" * 80)
+
+        for error_type, info in cls.ERROR_SOLUTIONS.items():
+            print(f"\n[{error_type}]")
+            print(f"Message: {info['message']}")
+            print(f"Severity: {info['severity']}")
+            print("Solutions:")
+            for i, sol in enumerate(info['solutions'], 1):
+                print(f"  {i}. {sol}")
+            print("-" * 80)
+
+
+def main() -> None:
+    """Run the CLI entry point for error lookup."""
+    import sys
+
+    if len(sys.argv) > 1:
+        error_type = sys.argv[1]
+        context = {}
+
+        # Parse context parameters
+        for arg in sys.argv[2:]:
+            if '=' in arg:
+                key, value = arg.split('=', 1)
+                context[key] = value
+
+        print(ErrorHelper.format_error_message(error_type, context))
+    else:
+        ErrorHelper.print_help()
+
+
+if __name__ == '__main__':
+    main()