@amaster.ai/pi-lark 0.1.2-beta.41 → 0.1.2-beta.42

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

@@ -117,6 +117,58 @@ class XmlTextOverlapLintTest(unittest.TestCase):
         self.assertIn("attribute", issue["hint"])
         self.assertIn("a=1&b=2", issue["hint"])
 
+    def test_lint_xml_reports_mismatched_xml_tag(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <shape type="text" topLeftX="80" topLeftY="80" width="300" height="60">
+                  <content textType="body"><p>Broken XML</content>
+                </shape>
+              </data>
+            </slide>
+            """
+        )
+        issue = result["issues"][0]
+        self.assertEqual(result["summary"]["slide_count"], 0)
+        self.assertEqual(result["summary"]["error_count"], 1)
+        self.assertEqual(issue["code"], "xml_not_well_formed")
+        self.assertIsInstance(issue["line"], int)
+        self.assertIsInstance(issue["column"], int)
+        self.assertIn("Broken XML", issue["context"])
+
+    def test_lint_xml_rejects_prefixed_sml_tags(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <ns0:slide xmlns:ns0="http://www.larkoffice.com/sml/2.0">
+              <ns0:data>
+                <sml:shape xmlns:sml="http://www.larkoffice.com/sml/2.0" type="text" topLeftX="80" topLeftY="80" width="300" height="60">
+                  <sml:content textType="body"><sml:p>Prefixed SML</sml:p></sml:content>
+                </sml:shape>
+              </ns0:data>
+            </ns0:slide>
+            """
+        )
+        issues = result["issues"]
+        self.assertEqual(result["summary"]["error_count"], 5)
+        self.assertEqual([issue["code"] for issue in issues], ["sml_prefixed_tag"] * 5)
+        self.assertEqual(issues[0]["tag"], "ns0:slide")
+        self.assertIn("default namespace", issues[0]["hint"])
+
+    def test_lint_xml_allows_unprefixed_tags_without_namespace(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide>
+              <data>
+                <shape type="text" topLeftX="80" topLeftY="80" width="300" height="60">
+                  <content textType="body"><p>Unprefixed SML</p></content>
+                </shape>
+              </data>
+            </slide>
+            """
+        )
+        self.assertEqual(result["summary"]["error_count"], 0)
+
     def test_lint_xml_accepts_escaped_entities_without_suspicious_entity_warning(self) -> None:
         result = xml_text_overlap_lint.lint_xml(
             """
@@ -162,6 +214,291 @@ class XmlTextOverlapLintTest(unittest.TestCase):
         self.assertEqual(result["summary"]["slide_count"], 1)
         self.assertEqual(result["summary"]["error_count"], 0)
 
+    def test_lint_xml_preserves_presentation_canvas_and_slide_order(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <presentation xmlns="http://www.larkoffice.com/sml/2.0" width="1280" height="720">
+              <slide xmlns="http://www.larkoffice.com/sml/2.0">
+                <data>
+                  <shape id="first" type="text" topLeftX="80" topLeftY="80" width="300" height="60">
+                    <content textType="body"><p>First slide</p></content>
+                  </shape>
+                </data>
+              </slide>
+              <slide xmlns="http://www.larkoffice.com/sml/2.0">
+                <data>
+                  <img id="second" src="tok" topLeftX="100" topLeftY="120" width="240" height="160"/>
+                  <shape id="skipped" type="text" topLeftX="80" topLeftY="80" width="300">
+                    <content textType="body"><p>Missing height</p></content>
+                  </shape>
+                </data>
+              </slide>
+            </presentation>
+            """
+        )
+        self.assertEqual(result["slide_size"], {"width": 1280, "height": 720})
+        self.assertEqual(result["summary"]["slide_count"], 2)
+        self.assertEqual([slide["slide_number"] for slide in result["slides"]], [1, 2])
+        self.assertEqual([slide["element_count"] for slide in result["slides"]], [1, 1])
+        self.assertEqual(result["summary"]["error_count"], 0)
+        self.assertEqual(result["summary"]["warning_count"], 0)
+
+    def test_lint_xml_reports_sxsd_unsupported_tag_with_alias_hint(self) -> None:
+        cases = [
+            ("textbox", '<textbox topLeftX="80" topLeftY="80" width="300" height="60">Text</textbox>', '<shape type="text">'),
+            ("image", '<image src="tok" topLeftX="80" topLeftY="80" width="300" height="180"/>', "<img>"),
+        ]
+        for tag_name, element_xml, expected_hint in cases:
+            with self.subTest(tag=tag_name):
+                result = xml_text_overlap_lint.lint_xml(
+                    f"""
+                    <slide xmlns="http://www.larkoffice.com/sml/2.0">
+                      <data>{element_xml}</data>
+                    </slide>
+                    """
+                )
+                issue = result["issues"][0]
+                self.assertEqual(result["summary"]["error_count"], 1)
+                self.assertEqual(issue["code"], "sxsd_unsupported_tag")
+                self.assertEqual(issue["tag"], tag_name)
+                self.assertIn(expected_hint, issue["hint"])
+
+    def test_lint_xml_reports_sxsd_unsupported_attr_with_alias_hint(self) -> None:
+        cases = [
+            ("shape", "x", "topLeftX", '<shape type="text" x="80" topLeftY="80" width="300" height="60"><content><p>Text</p></content></shape>'),
+            ("content", "fontColor", "color", '<shape type="text" topLeftX="80" topLeftY="80" width="300" height="60"><content fontColor="rgba(0, 0, 0, 1)"><p>Text</p></content></shape>'),
+        ]
+        for tag_name, attr_name, expected_attr, element_xml in cases:
+            with self.subTest(attr=attr_name):
+                result = xml_text_overlap_lint.lint_xml(
+                    f"""
+                    <slide xmlns="http://www.larkoffice.com/sml/2.0">
+                      <data>{element_xml}</data>
+                    </slide>
+                    """
+                )
+                issue = result["issues"][0]
+                self.assertEqual(result["summary"]["error_count"], 1)
+                self.assertEqual(issue["code"], "sxsd_unsupported_attr")
+                self.assertEqual(issue["tag"], tag_name)
+                self.assertEqual(issue["attr"], attr_name)
+                self.assertIn(expected_attr, issue["hint"])
+
+    def test_lint_xml_ignores_server_filled_id_attrs(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide id="server-slide-id" xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <shape id="server-shape-id" type="rect" topLeftX="80" topLeftY="80" width="300" height="160">
+                  <fill id="server-fill-id" unexpected="value">
+                    <fillColor color="rgba(255, 255, 255, 1)"/>
+                  </fill>
+                </shape>
+              </data>
+            </slide>
+            """
+        )
+
+        self.assertEqual(result["summary"]["error_count"], 1)
+        issue = result["issues"][0]
+        self.assertEqual(issue["code"], "sxsd_unsupported_attr")
+        self.assertEqual(issue["tag"], "fill")
+        self.assertEqual(issue["attr"], "unexpected")
+
+    def test_lint_xml_reports_gradient_shorthand_attrs_on_fill_color(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <shape type="rect" topLeftX="80" topLeftY="80" width="300" height="160">
+                  <fill>
+                    <fillColor
+                      type="gradient"
+                      color1="rgba(255, 0, 0, 1)"
+                      color2="rgba(0, 0, 255, 1)"
+                      angle="45"
+                      stop1="0%"
+                      stop2="100%"/>
+                  </fill>
+                </shape>
+              </data>
+            </slide>
+            """
+        )
+        unsupported_attrs = {issue["attr"] for issue in result["issues"]}
+        self.assertEqual(result["summary"]["error_count"], 6)
+        self.assertEqual(
+            unsupported_attrs,
+            {"type", "color1", "color2", "angle", "stop1", "stop2"},
+        )
+        self.assertTrue(all(issue["code"] == "sxsd_unsupported_attr" for issue in result["issues"]))
+        self.assertTrue(all(issue["tag"] == "fillColor" for issue in result["issues"]))
+
+    def test_lint_xml_accepts_chart_field_simple_content_attrs(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <chart topLeftX="80" topLeftY="80" width="520" height="320">
+                  <chartPlotArea>
+                    <chartPlot type="line"/>
+                  </chartPlotArea>
+                  <chartData>
+                    <dim1>
+                      <chartField name="month" valueType="string">Jan, Feb</chartField>
+                    </dim1>
+                    <dim2>
+                      <chartField name="value" valueType="number">1, 2</chartField>
+                    </dim2>
+                  </chartData>
+                </chart>
+              </data>
+            </slide>
+            """
+        )
+        self.assertEqual(result["summary"]["error_count"], 0)
+        self.assertNotIn("issues", result)
+
+    def test_lint_xml_does_not_load_iconpark_index_without_icons(self) -> None:
+        original_loader = xml_text_overlap_lint.load_iconpark_icon_types
+
+        def fail_if_loaded() -> set[str]:
+            raise AssertionError("iconpark index should not be loaded without <icon iconType>")
+
+        xml_text_overlap_lint.load_iconpark_icon_types = fail_if_loaded
+        try:
+            result = xml_text_overlap_lint.lint_xml(
+                """
+                <slide xmlns="http://www.larkoffice.com/sml/2.0">
+                  <data>
+                    <shape type="text" topLeftX="80" topLeftY="80" width="300" height="60">
+                      <content><p>No icons here</p></content>
+                    </shape>
+                  </data>
+                </slide>
+                """
+            )
+        finally:
+            xml_text_overlap_lint.load_iconpark_icon_types = original_loader
+
+        self.assertEqual(result["summary"]["error_count"], 0)
+        self.assertNotIn("issues", result)
+
+    def test_lint_xml_accepts_iconpark_icon_type_from_index(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <icon iconType="iconpark/Base/setting.svg" topLeftX="80" topLeftY="80" width="48" height="48">
+                  <fill><fillColor color="rgba(37, 99, 235, 1)"/></fill>
+                </icon>
+              </data>
+            </slide>
+            """
+        )
+        self.assertEqual(result["summary"]["error_count"], 0)
+        self.assertNotIn("issues", result)
+
+    def test_lint_xml_reports_icon_missing_fill_color(self) -> None:
+        cases = [
+            '<icon iconType="iconpark/Base/setting.svg" topLeftX="80" topLeftY="80" width="48" height="48"/>',
+            '<icon iconType="iconpark/Base/setting.svg" topLeftX="80" topLeftY="80" width="48" height="48"><fill/></icon>',
+            (
+                '<icon iconType="iconpark/Base/setting.svg" topLeftX="80" topLeftY="80" width="48" height="48">'
+                "<fill><fillColor/></fill></icon>"
+            ),
+        ]
+        for icon_xml in cases:
+            with self.subTest(icon=icon_xml):
+                result = xml_text_overlap_lint.lint_xml(
+                    f"""
+                    <slide xmlns="http://www.larkoffice.com/sml/2.0">
+                      <data>{icon_xml}</data>
+                    </slide>
+                    """
+                )
+
+                issue = result["issues"][0]
+                self.assertEqual(result["summary"]["error_count"], 1)
+                self.assertEqual(issue["code"], "icon_missing_fill_color")
+                self.assertEqual(issue["tag"], "icon")
+
+    def test_lint_xml_reports_icon_transparent_fill_color(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <icon iconType="iconpark/Base/setting.svg" topLeftX="80" topLeftY="80" width="48" height="48">
+                  <fill><fillColor color="rgba(37, 99, 235, 0)"/></fill>
+                </icon>
+              </data>
+            </slide>
+            """
+        )
+        issue = result["issues"][0]
+        self.assertEqual(result["summary"]["error_count"], 1)
+        self.assertEqual(issue["code"], "icon_transparent_fill_color")
+        self.assertEqual(issue["tag"], "icon")
+        self.assertEqual(issue["attr"], "fillColor")
+
+    def test_lint_xml_reports_iconpark_icon_type_outside_index(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <icon iconType="iconpark/Base/settng.svg" topLeftX="80" topLeftY="80" width="48" height="48">
+                  <fill><fillColor color="rgba(37, 99, 235, 1)"/></fill>
+                </icon>
+              </data>
+            </slide>
+            """
+        )
+        issue = result["issues"][0]
+        self.assertEqual(result["summary"]["error_count"], 1)
+        self.assertEqual(issue["code"], "iconpark_unsupported_icon_type")
+        self.assertEqual(issue["tag"], "icon")
+        self.assertEqual(issue["attr"], "iconType")
+        self.assertEqual(issue["iconType"], "iconpark/Base/settng.svg")
+        self.assertIn("iconpark-index.json", issue["hint"])
+        self.assertIn("iconpark/Base/setting.svg", issue["hint"])
+
+    def test_lint_xml_allows_namespaced_svg_inside_whiteboard(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <whiteboard id="wb" topLeftX="80" topLeftY="80" width="300" height="180">
+                  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 300 180">
+                    <rect x="10" y="10" width="120" height="60"/>
+                  </svg>
+                </whiteboard>
+              </data>
+            </slide>
+            """
+        )
+        self.assertEqual(result["summary"]["error_count"], 0)
+        self.assertNotIn("issues", result)
+
+    def test_lint_xml_reports_unqualified_svg_inside_whiteboard_with_namespace_hint(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <whiteboard id="wb" topLeftX="80" topLeftY="80" width="300" height="180">
+                  <svg viewBox="0 0 300 180">
+                    <rect x="10" y="10" width="120" height="60"/>
+                  </svg>
+                </whiteboard>
+              </data>
+            </slide>
+            """
+        )
+        issue = result["issues"][0]
+        self.assertEqual(result["summary"]["error_count"], 1)
+        self.assertEqual(issue["code"], "sxsd_unsupported_tag")
+        self.assertEqual(issue["tag"], "svg")
+        self.assertIn('xmlns="http://www.w3.org/2000/svg"', issue["hint"])
+
     def test_lint_xml_detects_overlapping_text_boxes(self) -> None:
         result = xml_text_overlap_lint.lint_xml(
             """
@@ -182,6 +519,83 @@ class XmlTextOverlapLintTest(unittest.TestCase):
         self.assertEqual(result["summary"]["error_count"], 1)
         self.assertEqual(result["slides"][0]["issues"][0]["code"], "bbox_overlap")
 
+    def test_lint_xml_detects_current_itinerary_cjk_caption_occlusion(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide id="pQO" xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <shape width="190" height="80" topLeftX="580" topLeftY="170" presetHandlers="0" type="rect" id="blI">
+                  <fill><fillColor color="rgba(255, 255, 255, 0.9)"/></fill>
+                  <border color="rgba(220, 205, 185, 1)" width="1"/>
+                  <content fontSize="16" fontFamily="思源黑体" color="rgba(31, 35, 41, 1)"/>
+                </shape>
+                <shape width="160" height="25" topLeftX="595" topLeftY="180" type="text" id="blX">
+                  <content fontSize="14" fontFamily="思源黑体" color="rgba(120, 80, 40, 1)" bold="true"><p>日照金山</p></content>
+                </shape>
+                <shape width="160" height="40" topLeftX="595" topLeftY="205" type="text" id="blY">
+                  <content textType="caption" fontSize="11" fontFamily="思源黑体" color="rgba(130, 100, 70, 1)"><p>清晨躺在床上看玉龙雪山日照金山奇观</p></content>
+                </shape>
+                <shape width="180" height="80" topLeftX="730" topLeftY="170" presetHandlers="0" type="rect" id="blH">
+                  <fill><fillColor color="rgba(255, 255, 255, 0.9)"/></fill>
+                  <border color="rgba(220, 205, 185, 1)" width="1"/>
+                  <content fontSize="16" fontFamily="思源黑体" color="rgba(31, 35, 41, 1)"/>
+                </shape>
+                <shape width="150" height="25" topLeftX="745" topLeftY="180" type="text" id="blp">
+                  <content fontSize="14" fontFamily="思源黑体" color="rgba(120, 80, 40, 1)" bold="true"><p>午餐返程</p></content>
+                </shape>
+                <shape width="150" height="40" topLeftX="745" topLeftY="205" type="text" id="blV">
+                  <content textType="caption" fontSize="11" fontFamily="思源黑体" color="rgba(130, 100, 70, 1)"><p>享用特色午餐，带着美好回忆返程</p></content>
+                </shape>
+                <shape width="190" height="80" topLeftX="580" topLeftY="310" presetHandlers="0" type="rect" id="blP">
+                  <fill><fillColor color="rgba(255, 255, 255, 0.9)"/></fill>
+                  <border color="rgba(220, 205, 185, 1)" width="1"/>
+                  <content fontSize="16" fontFamily="思源黑体" color="rgba(31, 35, 41, 1)"/>
+                </shape>
+                <shape width="160" height="25" topLeftX="595" topLeftY="320" type="text" id="blG">
+                  <content fontSize="14" fontFamily="思源黑体" color="rgba(120, 80, 40, 1)" bold="true"><p>高路徒步</p></content>
+                </shape>
+                <shape width="160" height="40" topLeftX="595" topLeftY="345" type="text" id="blQ">
+                  <content textType="caption" fontSize="11" fontFamily="思源黑体" color="rgba(130, 100, 70, 1)"><p>经典高路徒步，28道拐，龙洞瀑布，中虎跳峡</p></content>
+                </shape>
+                <shape width="180" height="80" topLeftX="730" topLeftY="310" presetHandlers="0" type="rect" id="blw">
+                  <fill><fillColor color="rgba(255, 255, 255, 0.9)"/></fill>
+                  <border color="rgba(220, 205, 185, 1)" width="1"/>
+                  <content fontSize="16" fontFamily="思源黑体" color="rgba(31, 35, 41, 1)"/>
+                </shape>
+                <shape width="150" height="25" topLeftX="745" topLeftY="320" type="text" id="blZ">
+                  <content fontSize="14" fontFamily="思源黑体" color="rgba(120, 80, 40, 1)" bold="true"><p>伴手礼</p></content>
+                </shape>
+                <shape width="150" height="40" topLeftX="745" topLeftY="345" type="text" id="blS">
+                  <content textType="caption" fontSize="11" fontFamily="思源黑体" color="rgba(130, 100, 70, 1)"><p>酒店精心准备的归途伴手礼，留下难忘纪念</p></content>
+                </shape>
+              </data>
+            </slide>
+            """
+        )
+        overlap_pairs = {tuple(issue["elements"]) for issue in result["slides"][0]["issues"]}
+        self.assertEqual(result["summary"]["error_count"], 2)
+        self.assertIn(("blY", "blV"), overlap_pairs)
+        self.assertIn(("blQ", "blS"), overlap_pairs)
+
+    def test_lint_xml_detects_horizontal_text_overflow_across_declared_box_gap(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <shape id="source" type="text" topLeftX="80" topLeftY="100" width="160" height="40">
+                  <content fontSize="18"><p>这是一个足够长的中文文本用于检测跨越间隙的横向溢出</p></content>
+                </shape>
+                <shape id="target" type="text" topLeftX="260" topLeftY="100" width="160" height="40">
+                  <content fontSize="18"><p>目标</p></content>
+                </shape>
+              </data>
+            </slide>
+            """
+        )
+        self.assertEqual(result["summary"]["error_count"], 1)
+        self.assertEqual(result["slides"][0]["issues"][0]["code"], "bbox_overlap")
+        self.assertEqual(result["slides"][0]["issues"][0]["elements"], ["source", "target"])
+
     def test_lint_xml_does_not_check_bounds_or_text_height(self) -> None:
         result = xml_text_overlap_lint.lint_xml(
             """
@@ -223,6 +637,38 @@ class XmlTextOverlapLintTest(unittest.TestCase):
         self.assertEqual(result["summary"]["error_count"], 0)
         self.assertEqual(result["summary"]["warning_count"], 0)
 
+    def test_extract_elements_preserves_supported_element_geometry_order_and_text_metadata(self) -> None:
+        elements = xml_text_overlap_lint.extract_elements(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <img id="photo" src="tok" topLeftX="10" topLeftY="20" width="100" height="80"/>
+                <shape id="headline" type="text" topLeftX="40" topLeftY="60" width="320" height="90">
+                  <content textType="headline" textAlign="center" autoFit="normal-auto-fit" fontSize="28">
+                    <p><![CDATA[Growth & scale]]></p>
+                    <p>Focused execution</p>
+                  </content>
+                </shape>
+                <table id="table" topLeftX="400" topLeftY="60" width="220" height="120"></table>
+                <chart id="chart" topLeftX="640" topLeftY="60" width="220" height="120"/>
+                <whiteboard id="wb" topLeftX="80" topLeftY="220" width="760" height="240"/>
+                <shape id="missing-height" type="text" topLeftX="80" topLeftY="480" width="320">
+                  <content><p>Skipped</p></content>
+                </shape>
+              </data>
+            </slide>
+            """
+        )
+        self.assertEqual([element["id"] for element in elements], ["photo", "headline", "table", "chart", "wb"])
+        self.assertEqual([element["kind"] for element in elements], ["img", "shape", "table", "chart", "whiteboard"])
+        self.assertEqual([element["order"] for element in elements], [0, 1, 2, 3, 4])
+        self.assertEqual(elements[1]["type"], "text")
+        self.assertEqual(elements[1]["textType"], "headline")
+        self.assertEqual(elements[1]["textAlign"], "center")
+        self.assertEqual(elements[1]["autoFit"], "normal-auto-fit")
+        self.assertEqual(elements[1]["fontSize"], 28)
+        self.assertEqual(elements[1]["text"], "Growth & scale\nFocused execution")
+
     def test_lint_xml_does_not_check_small_out_of_bounds_elements(self) -> None:
         result = xml_text_overlap_lint.lint_xml(
             """
@@ -266,6 +712,89 @@ class XmlTextOverlapLintTest(unittest.TestCase):
         )
         self.assertEqual(result["summary"]["error_count"], 0)
 
+    def test_lint_xml_warns_for_whiteboard_external_boundary_overlap(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+              <slide xmlns="http://www.larkoffice.com/sml/2.0">
+                <data>
+                  <whiteboard id="wb" topLeftX="50" topLeftY="140" width="860" height="360"/>
+                  <shape id="card" type="rect" topLeftX="50" topLeftY="450" width="200" height="60">
+                    <fill><fillColor color="rgba(232, 186, 176, 0.2)"/></fill>
+                    <content/>
+                  </shape>
+                  <shape id="label" type="text" topLeftX="65" topLeftY="460" width="170" height="20">
+                    <content fontSize="12"><p>基础保障</p></content>
+                  </shape>
+                </data>
+              </slide>
+            </presentation>
+            """
+        )
+        issues = result["slides"][0]["issues"]
+        self.assertEqual(result["summary"]["error_count"], 0)
+        self.assertEqual(result["summary"]["warning_count"], 1)
+        self.assertEqual(issues[0]["code"], "whiteboard_external_overlap")
+        self.assertIn("static whiteboard container-bbox risk", issues[0]["hint"])
+        self.assertIn("screenshot QA", issues[0]["hint"])
+        self.assertEqual(issues[0]["elements"], ["wb", "card"])
+        self.assertEqual(issues[0]["overlaps"][0]["overlap_height"], 50)
+
+    def test_lint_xml_allows_whiteboard_internal_labels(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+              <slide xmlns="http://www.larkoffice.com/sml/2.0">
+                <data>
+                  <whiteboard id="wb" topLeftX="100" topLeftY="120" width="420" height="260"/>
+                  <shape id="label" type="text" topLeftX="150" topLeftY="180" width="180" height="40">
+                    <content fontSize="14"><p>内部标注</p></content>
+                  </shape>
+                </data>
+              </slide>
+            </presentation>
+            """
+        )
+        self.assertEqual(result["summary"]["error_count"], 0)
+        self.assertEqual(result["summary"]["warning_count"], 0)
+
+    def test_lint_xml_allows_bottom_layer_full_slide_whiteboard_background(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+              <slide xmlns="http://www.larkoffice.com/sml/2.0">
+                <data>
+                  <whiteboard id="background" topLeftX="0" topLeftY="0" width="960" height="540"/>
+                  <shape id="title" type="text" topLeftX="80" topLeftY="80" width="420" height="80">
+                    <content textType="title" fontSize="36"><p>Title</p></content>
+                  </shape>
+                </data>
+              </slide>
+            </presentation>
+            """
+        )
+        self.assertEqual(result["summary"]["error_count"], 0)
+        self.assertEqual(result["summary"]["warning_count"], 0)
+
+    def test_lint_xml_allows_whiteboard_inside_background_panel(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+              <slide xmlns="http://www.larkoffice.com/sml/2.0">
+                <data>
+                  <shape id="panel" type="rect" topLeftX="40" topLeftY="100" width="880" height="340">
+                    <fill><fillColor color="rgba(232, 186, 176, 0.2)"/></fill>
+                    <content/>
+                  </shape>
+                  <whiteboard id="wb" topLeftX="60" topLeftY="120" width="840" height="300"/>
+                </data>
+              </slide>
+            </presentation>
+            """
+        )
+        self.assertEqual(result["summary"]["error_count"], 0)
+        self.assertEqual(result["summary"]["warning_count"], 0)
+
     def test_lint_xml_detects_invalid_template_text_stack_overlap(self) -> None:
         cases = [
             (

package/skills/lark-task/SKILL.md

@@ -13,6 +13,7 @@ metadata:
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
 
 > **任务搜索技巧**：先区分用户是否**特地指定使用搜索 skill**，以及是否真的提供了**查询关键字**（例如任务名称、关键词、片段描述）。如果用户特地指定使用搜索 skill，或明确给出了任务查询关键字，则目标是**任务**时优先使用 `+search`。如果用户没有特地指定使用搜索 skill，且意图里没有查询关键字，只有范围条件（例如“今年以来”“已完成”“由我创建”“我关注的”），并且使用 `+search` 与 `+get-related-tasks` / `+get-my-tasks` 都能达到目的时，应优先使用列表型能力，而不是搜索型能力。其中，“与我相关 / 我关注的 / 由我创建”等优先考虑 `+get-related-tasks`；“我负责的 / 分配给我”的列表优先考虑 `+get-my-tasks`。不要把时间范围词（例如“今年以来”）本身误当成 `query` 去走搜索。
+> **任务搜索相关性提示**：`+search` 当前不会自动判断搜索结果与搜索发起人的相关性。如果用户明确要求搜索“与我相关”的任务，必须先识别具体关系，获取当前用户的 `open_id`，并显式传入对应的 `--assignee`（负责人）、`--creator`（创建人）或 `--follower`（关注人）过滤条件；不能只依赖 `query` 期待自动返回与当前用户相关的任务。
 > **任务清单搜索技巧**：任务清单也遵循同样的判断逻辑。先区分用户是否**特地指定使用搜索 skill**，以及是否真的提供了**清单查询关键字**（例如清单名称、关键词、片段描述）。如果用户特地指定使用搜索 skill，或明确给出了清单查询关键字，则优先使用 `+tasklist-search`。如果用户没有特地指定使用搜索 skill，且意图里没有查询关键字，只有范围条件（例如“由我创建的任务清单”“今年以来创建的清单”），并且使用搜索或原生列取清单都能达到目的时，应优先使用原生 `tasklists.list` 接口列取清单（先 `schema task.tasklists.list`，再 `lark-cli task tasklists list --as user ...`），再按 `creator`、`created_at` 等字段做本地筛选和分页控制。
 > **意图区分补充**：像“搜索飞书中今年以来我关注的任务”这类表达，虽然字面带有“搜索”，但如果没有真正的查询关键字，且本质是在限定“与我相关 + 时间范围”，则应优先走 `+get-related-tasks`；像“搜索飞书中由我创建的任务清单”这类表达，如果没有清单关键字，且本质是在限定“清单范围 + 创建者”，则应优先走原生 `tasklists.list` 后筛选，而不是直接走搜索型 shortcut。
 > **用户身份识别**：在用户身份（user identity）场景下，如果用户提到了“我”（例如“分配给我”、“由我创建”），请默认获取当前登录用户的 `open_id` 作为对应的参数值。

package/skills/lark-vc-agent/SKILL.md

@@ -18,9 +18,16 @@ metadata:
 ## 内测提示
 
 - 当前功能正在内测中，仅少数用户可用。忽略 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 中的权限申请流程，以下方的指引为准。
-- 如果 `lark-cli` 提示 `missing required scope(s)` / `permission_violations`，不要走普通权限申请流程；先提示用户加入早鸟群确认内测权限已开通，再按“应用身份权限配置检查”处理应用权限、安装和数据范围。
+- 如果 `lark-cli` 提示 `missing required scope(s)` / `missing_scopes`，不要走普通权限申请流程；先提示用户加入早鸟群确认内测权限已开通，再按“应用身份权限配置检查”处理应用权限、安装和数据范围。
 - 如果 `lark-cli` 返回 `error.code=20017` / `ErrNotInGray`，提示用户加入早鸟群：`https://go.larkoffice.com/join-chat/2f4nb0e1-fe00-4f67-bed7-25beaf533fbd`。
 
+## 会议查询权限
+
+`+meeting-list-active` 和 `+meeting-events` 缺少权限时，先按上面的内测提示确认功能已开通，再读取 CLI 错误中的 `hint`，并根据当前调用身份处理：
+
+- 用户身份 `--as user`：按 CLI 提示为当前用户授权 `vc:meeting.meetingevent:read`。
+- 应用身份 `--as bot`：请应用开发者开通 `vc:meeting.bot.join:write`，不要执行 `auth login`；随后按“应用身份权限配置检查”确认应用发布、安装和数据范围。
+
 ## 定位
 
 本 skill 与 [`lark-vc`](../lark-vc/SKILL.md) 并列：
@@ -170,9 +177,9 @@ Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。
 
 ## 应用身份权限配置检查
 
-应用身份 `--as bot` 报 `no permission`、`missing required scope(s)`、`permission_violations`、`ErrNotInGray` 或 `20017` 时，不要引导用户执行 `auth login`。按顺序检查：
+应用身份 `--as bot` 报 `no permission`、`missing required scope(s)`、`missing_scopes`、`ErrNotInGray` 或 `20017` 时，不要引导用户执行 `auth login`。按顺序检查：
 
-1. 以 CLI 返回的 metadata / error envelope 为准，确认提示的 VC Agent 相关权限已开通。常见读取 active meeting / events 需要会中事件读取权限；应用机器人入会 / 离会需要 bot 入会写权限。
+1. 确认内测权限后，按 CLI 错误中的 `hint` 处理；返回 `console_url` 时将其原样提供给用户。
 2. 应用已发布并安装到当前租户。
 3. 开放平台“权限可访问的数据范围”已开通并保存。
 4. 数据范围选择“按条件筛选”，条件配置为：**会议的归属者 包含 与应用的可用范围一致**。
@@ -180,7 +187,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。
 
 ## 用户身份被拒绝时
 
-用户身份 `--as user` 报权限或身份不支持类错误时，不要反复引导用户执行 `auth login`。先以 CLI 返回的 metadata / error envelope 为准判断：如果错误表明当前接口不支持用户身份访问，再按用户意图切换处理：
+用户身份 `--as user` 调用 `+meeting-list-active` 或 `+meeting-events` 报普通 scope 缺失时，按“会议查询权限”处理；其他 shortcut 的 scope 缺失按各自 CLI `hint` 处理。普通 scope 缺失不表示接口不支持用户身份，只有 CLI 明确表明当前接口不支持用户身份访问时，才按用户意图切换处理：
 
 1. 如果用户只是查询当前登录用户所在的进行中会议，说明当前接口链路不支持用户身份访问，改用应用身份流程；需要目标用户 open_id，并要求应用机器人已在会中或先按用户确认执行入会。
 2. 如果用户明确要求应用机器人入会、旁听、代参会或读取应用机器人可见事件，直接切到 `--as bot`，并按上面的应用身份权限配置检查处理。

package/skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md

@@ -290,7 +290,7 @@ lark-cli vc +meeting-events \
 | 用户身份无权限 / 不可见 | 当前用户不是该会议的可见参与者，或 `meeting_id` 不是从用户身份路径获得 | 不要反复执行 `auth login`。先确认 `meeting_id` 是否来自 `+meeting-list-active --as user`；如果用户明确要切到应用身份，再通过 `+meeting-list-active --as bot --user-id <user_open_id>` 获取应用身份可读的 `meeting_id`，或在用户明确同意后让应用机器人入会，再用 `+meeting-events --as bot` 读取 |
 | `20001 meeting_status_MEETING_END` | 会议已结束且已超出后端允许的 5 分钟宽限窗口 | 本接口不再适合继续拉取事件。先用 `lark-cli vc +detail --meeting-ids <meeting.id>` 获取会议产物信息，再根据 `note_display_type` / `note_id` / `minute_token` 和用户意图选择纪要正文、逐字稿或妙记；参会人请用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>"}' --with-participants` |
 | `20002 meeting not exist` | `meeting_id` 错误，或会议实例当前已不可获取（常见于把 9 位会议号当 meeting_id 传） | 确认传入的是长数字 `meeting_id`，不是 9 位会议号 |
-| 应用身份权限不足 | 应用权限、租户安装、权限可访问的数据范围或 VC Agent privilege 未配置完整 | 不要执行 `auth login`。以 CLI 返回的 metadata / error envelope 为准确认缺失权限；检查应用发布/安装，以及开放平台“权限可访问的数据范围”：选择“按条件筛选”，条件为“会议的归属者 包含 与应用的可用范围一致”；仍失败再排查内测 privilege / 灰度 |
+| 应用身份权限不足 | 应用权限、租户安装、权限可访问的数据范围或 VC Agent privilege 未配置完整 | 不要执行 `auth login`。请应用开发者开通 `vc:meeting.bot.join:write`；再检查应用发布/安装和权限可访问的数据范围，均正确仍失败时再排查内测灰度权限 |
 | `HTTP 404` / `HTTP 500` | 服务端当前无法找到或处理该会议实例 | 换一个正在进行且 bot 可见的 meeting_id，或排查后端问题 |
 
 ## 提示

package/skills/lark-vc-agent/references/lark-vc-agent-meeting-leave.md

@@ -46,7 +46,7 @@ lark-cli vc +meeting-leave --as bot --meeting-id 69xxxxxxxxxxxxx28 --dry-run
 ## 输出结果
 
 接口成功返回时，默认输出：`Left meeting <meeting-id> successfully.`。
-`--format json` 返回 API 原始响应体。
+`--format json` 返回标准 `{ok, identity, data}` 信封，例如 `{"ok":true,"identity":"bot","data":{}}`，不是带 `code` / `msg` 的 API 原始响应体。
 
 ## 如何获取输入参数