pi-feishu-cli 0.1.0

package/skills/lark-slides/scripts/template_tool_test.py

@@ -0,0 +1,177 @@
+# Copyright (c) 2026 Lark Technologies Pte. Ltd.
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+import template_tool
+
+
+class TemplateToolTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.index_data = template_tool.build_index_data()
+
+    def test_build_index_data_exposes_light_general_metadata(self) -> None:
+        template = next(
+            entry for entry in self.index_data["templates"] if entry["template_id"] == "office--light_general"
+        )
+        expected_keys = {
+            "template_id",
+            "category",
+            "category_label",
+            "scene",
+            "tone",
+            "formality",
+            "is_general_template",
+            "slide_count",
+            "presentation_title",
+            "palette",
+            "structure",
+            "page_types",
+            "layout_tags",
+            "use_cases",
+            "ranges",
+        }
+        self.assertEqual(set(template.keys()), expected_keys)
+        self.assertEqual(template["tone"], "light")
+        self.assertEqual(template["formality"], "formal")
+        self.assertEqual(template["slide_count"], 54)
+        self.assertEqual(template["presentation_title"], "白底通用模板")
+        self.assertIsInstance(template["layout_tags"], list)
+        self.assertNotIn("theme_summary", template)
+        self.assertNotIn("editable_regions", template)
+        self.assertNotIn("bbox_summary", template)
+
+    def test_search_templates_keeps_work_report_templates_in_top_results(self) -> None:
+        results = template_tool.search_templates(self.index_data, {"query": "工作汇报", "limit": 3})
+        self.assertTrue(results)
+        self.assertTrue(any(entry["template_id"] == "office--work_report" for entry in results))
+
+    def test_search_templates_extracts_scene_from_long_chinese_prompt(self) -> None:
+        results = template_tool.search_templates(
+            self.index_data,
+            {"query": "帮我做一个季度工作汇报PPT，偏正式", "limit": 3},
+        )
+        self.assertTrue(results)
+        self.assertTrue(any(entry["template_id"] == "office--work_report" for entry in results))
+
+    def test_search_templates_maps_chinese_tone_words(self) -> None:
+        results = template_tool.search_templates(
+            self.index_data,
+            {"query": "深色科技感产品发布", "limit": 5},
+        )
+        self.assertTrue(results)
+        self.assertTrue(any(entry["tone"] == "dark" for entry in results))
+
+    def test_search_templates_finds_product_launch_and_promotion_defense(self) -> None:
+        product_results = template_tool.search_templates(
+            self.index_data,
+            {"query": "产品发布会新品介绍", "limit": 5},
+        )
+        self.assertTrue(product_results)
+        self.assertTrue(
+            any(
+                entry["template_id"]
+                in {"office--project_kickoff", "product--product_intro", "product--product_promotion"}
+                for entry in product_results
+            )
+        )
+
+        defense_results = template_tool.search_templates(
+            self.index_data,
+            {"query": "晋升答辩 个人述职", "limit": 5},
+        )
+        self.assertTrue(defense_results)
+        self.assertTrue(any(entry["template_id"] == "personal--promotion_defense" for entry in defense_results))
+
+    def test_extract_selection_xml_keeps_only_requested_slides_and_theme(self) -> None:
+        xml = template_tool.extract_selection_xml(self.index_data, "office--light_general", {"label": "封面"})
+        self.assertEqual(len(template_tool.re.findall(r"<slide\b", xml)), 2)
+        self.assertIn("<theme>", xml)
+        self.assertIn("<title>白底通用模板</title>", xml)
+
+    def test_summarize_selection_aggregates_slide_titles_and_counts(self) -> None:
+        summary = template_tool.summarize_selection(self.index_data, "office--light_general", {"label": "封面"})
+        self.assertEqual(summary["selection"]["range"], "1-2")
+        self.assertEqual(summary["summary"]["slide_count"], 2)
+        self.assertTrue(summary["theme_summary"]["has_theme_node"])
+        self.assertIn("通用模板", summary["summary"]["title_hints"])
+        self.assertGreater(summary["summary"]["element_totals"]["shape"], 0)
+        self.assertIsInstance(summary["slides"][0]["layout_tags"], list)
+        self.assertIn("bbox_summary", summary["slides"][0])
+        self.assertIn("editable_regions", summary["slides"][0])
+
+    def test_template_selector_accepts_catalog_visible_filename(self) -> None:
+        entry = template_tool.resolve_template_entry(self.index_data, "work_report.xml")
+        self.assertEqual(entry["template_id"], "office--work_report")
+
+    def test_template_path_uses_user_supplied_file(self) -> None:
+        source_path = template_tool.TEMPLATES_DIR / "office--work_report.xml"
+        with tempfile.TemporaryDirectory() as temp_dir:
+            copied_path = Path(temp_dir) / "work_report.xml"
+            copied_path.write_text(
+                source_path.read_text(encoding="utf-8").replace(
+                    "<title>工作汇报</title>",
+                    "<title>Copied Path Template</title>",
+                    1,
+                ),
+                encoding="utf-8",
+            )
+
+            xml = template_tool.extract_selection_xml(
+                self.index_data,
+                str(copied_path),
+                {"range": "1"},
+            )
+
+        self.assertIn("<title>Copied Path Template</title>", xml)
+
+    def test_template_path_accepts_unindexed_xml_with_range(self) -> None:
+        xml = (
+            '<presentation xmlns="http://www.larkoffice.com/sml/2.0">'
+            "<title>Generated Template</title>"
+            "<slide><data></data></slide>"
+            "</presentation>"
+        )
+        with tempfile.TemporaryDirectory() as temp_dir:
+            template_path = Path(temp_dir) / "generated.xml"
+            template_path.write_text(xml, encoding="utf-8")
+
+            extracted = template_tool.extract_selection_xml(
+                self.index_data,
+                str(template_path),
+                {"range": "1"},
+            )
+
+        self.assertIn("<title>Generated Template</title>", extracted)
+
+    def test_search_templates_supports_layout_tag_filtering(self) -> None:
+        results = template_tool.search_templates(
+            self.index_data,
+            {"query": "", "layout-tag": "full-bleed-image-caption", "limit": 10},
+        )
+        self.assertTrue(results)
+        self.assertTrue(
+            any("full-bleed-image-caption" in entry["layout_tags"] for entry in results)
+        )
+
+    def test_all_template_files_are_cataloged_and_indexed(self) -> None:
+        template_files = sorted(path.stem for path in template_tool.TEMPLATES_DIR.glob("*.xml"))
+        indexed_templates = sorted(entry["template_id"] for entry in self.index_data["templates"])
+        self.assertEqual(indexed_templates, template_files)
+        self.assertEqual(self.index_data["template_count"], len(template_files))
+        self.assertTrue(template_files)
+
+    def test_catalog_range_parser_keeps_comma_separated_ranges(self) -> None:
+        template = next(
+            entry for entry in self.index_data["templates"] if entry["template_id"] == "operations--product_promotion"
+        )
+        content_range = next(item for item in template["ranges"] if item["label"] == "内容")
+        self.assertEqual(content_range["range"], "3-8, 10-12")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/lark-slides/scripts/xml_text_overlap_lint.py

@@ -0,0 +1,367 @@
+#!/usr/bin/env python3
+# Copyright (c) 2026 Lark Technologies Pte. Ltd.
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import xml.etree.ElementTree as ET
+from difflib import SequenceMatcher
+from pathlib import Path
+from typing import Any
+
+
+class XmlTextOverlapLintError(Exception):
+    pass
+
+
+def fail(message: str) -> None:
+    raise XmlTextOverlapLintError(message)
+
+
+def read_file(file_path: str | Path) -> str:
+    return Path(file_path).read_text(encoding="utf-8")
+
+
+def parse_args(argv: list[str]) -> dict[str, Any]:
+    options: dict[str, Any] = {}
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if not token.startswith("--"):
+            fail(f"unexpected argument: {token}")
+        key = token[2:]
+        next_token = argv[index + 1] if index + 1 < len(argv) else None
+        if next_token is None or next_token.startswith("--"):
+            options[key] = True
+            index += 1
+            continue
+        options[key] = next_token
+        index += 2
+    return options
+
+
+def extract_attribute(tag_source: str, name: str) -> str | None:
+    match = re.search(fr'{re.escape(name)}="([^"]+)"', tag_source)
+    return match.group(1) if match else None
+
+
+def extract_numeric_attribute(tag_source: str, name: str) -> int | float | None:
+    raw = extract_attribute(tag_source, name)
+    if raw is None:
+        return None
+    try:
+        value = float(raw)
+    except ValueError:
+        return None
+    return int(value) if value.is_integer() else value
+
+
+def strip_xml(value: str) -> str:
+    stripped = re.sub(r"<!\[CDATA\[([\s\S]*?)\]\]>", r"\1", value)
+    stripped = re.sub(r"<[^>]+>", " ", stripped)
+    stripped = stripped.replace("&nbsp;", " ")
+    stripped = stripped.replace("&amp;", "&")
+    stripped = stripped.replace("&lt;", "<")
+    stripped = stripped.replace("&gt;", ">")
+    stripped = stripped.replace("&quot;", '"')
+    stripped = stripped.replace("&#39;", "'")
+    return re.sub(r"\s+", " ", stripped).strip()
+
+
+def xml_local_name(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1] if tag.startswith("{") else tag
+
+
+def extract_error_context(xml: str, line: int | None, column: int | None, radius: int = 40) -> str | None:
+    if line is None or column is None:
+        return None
+    lines = xml.splitlines()
+    if line < 1 or line > len(lines):
+        return None
+    source_line = lines[line - 1]
+    start = max(column - radius, 0)
+    end = min(column + radius, len(source_line))
+    return source_line[start:end].strip()
+
+
+def build_xml_error_issue(error: ET.ParseError, xml: str) -> dict[str, Any]:
+    line, column = getattr(error, "position", (None, None))
+    return {
+        "level": "error",
+        "code": "xml_not_well_formed",
+        "message": f"XML is not well-formed: {error}",
+        "line": line,
+        "column": column,
+        "context": extract_error_context(xml, line, column),
+        "hint": (
+            "Escape raw user text before placing it in XML. In text nodes and attribute values, bare & must be "
+            "written as &amp;. In text nodes, write < as &lt; and > as &gt;. For attribute URLs, use a=1&amp;b=2."
+        ),
+    }
+
+
+def validate_xml_well_formed(xml: str) -> dict[str, Any] | None:
+    try:
+        root = ET.fromstring(xml)
+    except ET.ParseError as error:
+        return build_xml_error_issue(error, xml)
+
+    root_name = xml_local_name(root.tag)
+    if root_name not in {"presentation", "slide"}:
+        fail("input must contain a <presentation> or <slide> root")
+    return None
+
+
+def parse_presentation(xml: str) -> dict[str, Any]:
+    presentation_match = re.search(r"<presentation\b([^>]*)>", xml)
+    if presentation_match:
+        return {
+            "width": int(float(extract_attribute(presentation_match.group(1), "width") or 960)),
+            "height": int(float(extract_attribute(presentation_match.group(1), "height") or 540)),
+            "slides": re.findall(r"<slide\b[\s\S]*?</slide>", xml),
+        }
+    slide_match = re.findall(r"<slide\b[\s\S]*?</slide>", xml)
+    if slide_match:
+        return {"width": 960, "height": 540, "slides": slide_match}
+    fail("input must contain a <presentation> or <slide> root")
+
+
+def extract_elements(slide_xml: str) -> list[dict[str, Any]]:
+    elements: list[dict[str, Any]] = []
+    for match in re.finditer(r"<shape\b([^>]*)>([\s\S]*?)</shape>", slide_xml):
+        attrs, content = match.group(1), match.group(2)
+        x = extract_numeric_attribute(attrs, "topLeftX")
+        y = extract_numeric_attribute(attrs, "topLeftY")
+        width = extract_numeric_attribute(attrs, "width")
+        height = extract_numeric_attribute(attrs, "height")
+        if all(value is not None for value in [x, y, width, height]):
+            font_size = float(extract_attribute(content, "fontSize") or extract_attribute(attrs, "fontSize") or 16)
+            elements.append(
+                {
+                    "id": f"shape-{len(elements) + 1}",
+                    "kind": "shape",
+                    "type": extract_attribute(attrs, "type") or "shape",
+                    "textType": extract_attribute(content, "textType"),
+                    "x": x,
+                    "y": y,
+                    "width": width,
+                    "height": height,
+                    "fontSize": font_size,
+                    "text": strip_xml(content),
+                }
+            )
+
+    for match in re.finditer(r"<(img|table|chart)\b([^>]*)/?>", slide_xml):
+        attrs = match.group(2)
+        x = extract_numeric_attribute(attrs, "topLeftX")
+        y = extract_numeric_attribute(attrs, "topLeftY")
+        width = extract_numeric_attribute(attrs, "width")
+        height = extract_numeric_attribute(attrs, "height")
+        if all(value is not None for value in [x, y, width, height]):
+            elements.append(
+                {
+                    "id": f"{match.group(1)}-{len(elements) + 1}",
+                    "kind": match.group(1),
+                    "type": match.group(1),
+                    "x": x,
+                    "y": y,
+                    "width": width,
+                    "height": height,
+                }
+            )
+    return elements
+
+
+def intersects(left: dict[str, Any], right: dict[str, Any]) -> bool:
+    return (
+        left["x"] < right["x"] + right["width"]
+        and left["x"] + left["width"] > right["x"]
+        and left["y"] < right["y"] + right["height"]
+        and left["y"] + left["height"] > right["y"]
+    )
+
+
+def is_text_element(element: dict[str, Any]) -> bool:
+    return element["kind"] == "shape" and element["type"] == "text"
+
+
+def has_text_content(element: dict[str, Any]) -> bool:
+    return bool(element.get("text"))
+
+
+def is_decorative_text(element: dict[str, Any]) -> bool:
+    text = element.get("text") or ""
+    return bool(text) and re.search(r"[A-Za-z0-9\u4e00-\u9fff]", text) is None
+
+
+def normalize_text_for_overlap(text: str) -> str:
+    return re.sub(r"\s+", "", text)
+
+
+def is_similar_text_overlay(left: dict[str, Any], right: dict[str, Any]) -> bool:
+    left_text = normalize_text_for_overlap(left.get("text") or "")
+    right_text = normalize_text_for_overlap(right.get("text") or "")
+    if not left_text or not right_text:
+        return False
+    if left_text == right_text or left_text in right_text or right_text in left_text:
+        return True
+    return SequenceMatcher(None, left_text, right_text).ratio() >= 0.75
+
+
+def estimate_text_line_count(element: dict[str, Any]) -> int:
+    font_size = element["fontSize"] if isinstance(element["fontSize"], (int, float)) else 16
+    chars_per_line = max(1, int(element["width"] // max(font_size * 0.55, 1)))
+    paragraphs = [paragraph for paragraph in re.split(r"\n+", element["text"]) if paragraph]
+    line_count = 0
+    for paragraph in paragraphs:
+        logical_length = max(len(paragraph), 1)
+        line_count += max(1, -(-logical_length // chars_per_line))
+    return max(line_count, 1)
+
+
+def estimate_text_visual_bbox(element: dict[str, Any]) -> dict[str, int | float] | None:
+    if not is_text_element(element) or not has_text_content(element) or is_decorative_text(element):
+        return None
+
+    font_size = element["fontSize"] if isinstance(element["fontSize"], (int, float)) else 16
+    char_width = max(font_size * 0.55, 1)
+    line_count = estimate_text_line_count(element)
+    visual_width = min(element["width"], max(1, len(element["text"]) * char_width))
+    visual_height = min(element["height"], max(1, line_count * font_size * 1.2))
+    return {
+        "x": element["x"],
+        "y": element["y"],
+        "width": visual_width,
+        "height": visual_height,
+    }
+
+
+def intersection_area(left: dict[str, Any], right: dict[str, Any]) -> int | float:
+    width = min(left["x"] + left["width"], right["x"] + right["width"]) - max(left["x"], right["x"])
+    height = min(left["y"] + left["height"], right["y"] + right["height"]) - max(left["y"], right["y"])
+    if width <= 0 or height <= 0:
+        return 0
+    return width * height
+
+
+def is_template_text_stack(left: dict[str, Any], right: dict[str, Any]) -> bool:
+    if not (is_text_element(left) and is_text_element(right)):
+        return False
+    if not (has_text_content(left) and has_text_content(right)):
+        return True
+    top, bottom = sorted([left, right], key=lambda element: element["y"])
+    top_type = top.get("textType")
+    bottom_type = bottom.get("textType")
+    allowed_pairs = {
+        ("title", "sub-headline"),
+        ("title", None),
+        ("headline", "headline"),
+        ("headline", None),
+    }
+    if (top_type, bottom_type) not in allowed_pairs:
+        return False
+    same_column = abs(top["x"] - bottom["x"]) <= 4
+    vertical_offset = bottom["y"] - top["y"]
+    top_font_size = float(top.get("fontSize", 16))
+    return same_column and vertical_offset >= top_font_size * 0.75
+
+
+def should_flag_overlap(left: dict[str, Any], right: dict[str, Any]) -> bool:
+    if is_text_element(left) and not has_text_content(left):
+        return False
+    if is_text_element(right) and not has_text_content(right):
+        return False
+    if is_template_text_stack(left, right):
+        return False
+    if is_text_element(left) and is_text_element(right):
+        if is_similar_text_overlay(left, right):
+            return False
+        left_visual = estimate_text_visual_bbox(left)
+        right_visual = estimate_text_visual_bbox(right)
+        if left_visual is None or right_visual is None:
+            return False
+        overlap_area = intersection_area(left_visual, right_visual)
+        if overlap_area <= 0:
+            return False
+        smaller_area = min(
+            left_visual["width"] * left_visual["height"],
+            right_visual["width"] * right_visual["height"],
+        )
+        return smaller_area > 0 and overlap_area / smaller_area >= 0.30
+    return False
+
+
+def lint_slide(slide_xml: str, slide_number: int) -> dict[str, Any]:
+    elements = extract_elements(slide_xml)
+    issues: list[dict[str, Any]] = []
+
+    for index, left in enumerate(elements):
+        for right in elements[index + 1 :]:
+            if not intersects(left, right) or not should_flag_overlap(left, right):
+                continue
+            issues.append(
+                {
+                    "level": "error",
+                    "code": "bbox_overlap",
+                    "elements": [left["id"], right["id"]],
+                    "message": f'{left["id"]} overlaps {right["id"]}',
+                }
+            )
+
+    return {"slide_number": slide_number, "element_count": len(elements), "issues": issues}
+
+
+def lint_xml(xml: str, source_path: str | None = None) -> dict[str, Any]:
+    xml_error = validate_xml_well_formed(xml)
+    if xml_error:
+        return {
+            "file": source_path,
+            "slide_size": {"width": 960, "height": 540},
+            "summary": {"slide_count": 0, "error_count": 1, "warning_count": 0},
+            "issues": [xml_error],
+            "slides": [],
+        }
+
+    presentation = parse_presentation(xml)
+    slides = [
+        lint_slide(slide_xml, index + 1)
+        for index, slide_xml in enumerate(presentation["slides"])
+    ]
+    error_count = sum(1 for slide in slides for issue in slide["issues"] if issue["level"] == "error")
+    warning_count = sum(1 for slide in slides for issue in slide["issues"] if issue["level"] == "warning")
+    return {
+        "file": source_path,
+        "slide_size": {"width": presentation["width"], "height": presentation["height"]},
+        "summary": {"slide_count": len(slides), "error_count": error_count, "warning_count": warning_count},
+        "slides": slides,
+    }
+
+
+def print_usage() -> None:
+    print("Usage:\n  python3 xml_text_overlap_lint.py --input <presentation.xml>", file=sys.stderr)
+
+
+def run_cli(argv: list[str] | None = None) -> None:
+    options = parse_args(argv or sys.argv[1:])
+    if options.get("help") or options.get("--help"):
+        print_usage()
+        raise SystemExit(0)
+    if not options.get("input"):
+        print_usage()
+        fail("--input is required")
+    input_path = Path(options["input"]).resolve()
+    result = lint_xml(read_file(input_path), str(input_path))
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    if result["summary"]["error_count"] > 0:
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    try:
+        run_cli()
+    except XmlTextOverlapLintError as error:
+        print(f"xml-text-overlap-lint error: {error}", file=sys.stderr)
+        raise SystemExit(1) from error