@amaster.ai/pi-lark 0.1.2-beta.51 → 0.1.2-beta.53

package/skills/lark-slides/references/xml-schema-quick-ref.md

@@ -4,7 +4,7 @@
 
 ## 最重要的规则
 
-1. 协议标准写法应使用 `<presentation xmlns="http://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
+1. 协议标准写法应使用 `<presentation xmlns="https://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
 2. `<presentation>` 直接子元素只有 `<title>`、`<theme>`、`<slide>`
 3. `<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`
 4. 页面中的文本通常通过 `<content>` 表达，而不是把 `<title>`、`<body>` 直接挂在 `<slide>` 下
@@ -13,7 +13,7 @@
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+<presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540">
   <slide>
     <data>
       <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
@@ -81,7 +81,7 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 **子元素：**
 
 - `<style>?` - 页面样式，目前可放 `<fill>`
-- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`undefined`
+- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`embed`、`chart`、`undefined`
 - `<note>?` - 演讲者备注，内部可放 `<content>`
 
 这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。
@@ -227,17 +227,17 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 ### img
 
 ```xml
-<img src="file_token_or_url" topLeftX="80" topLeftY="120" width="320" height="180"/>
+<img src="file_token_或_@本地路径" topLeftX="80" topLeftY="120" width="320" height="180"/>
 ```
 
 `img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。
 
-`src` 只支持：`slides +media-upload` 返回的 `file_token`，或 `@<本地路径>` 占位符（仅 `+create --slides` 自动上传并替换）。**禁止使用 http(s) 外链 URL**——飞书 slides 渲染端不会代理外链图，外链 src 在 PPT 里通常不显示。本地图片详见 [lark-slides-create.md](lark-slides-create.md#本地图片path-占位符) / [lark-slides-media-upload.md](lark-slides-media-upload.md)。
+`src` 只支持：`slides +media-upload` 返回的 `file_token`，或 `@<本地路径>` 占位符（`+create --slides` 和 `+add-slide` 会自动上传并替换）。**禁止使用 http(s) 外链 URL**——飞书 slides 渲染端不会代理外链图，外链 src 在 PPT 里通常不显示。本地图片详见 [lark-slides-create.md](lark-slides-create.md#本地图片path-占位符) / [lark-slides-media-upload.md](lark-slides-media-upload.md)。
 
 本地图片的两种姿势：
 
 - 新建带图 PPT：`+create --slides` 里直接写 `src="@./pic.png"`，CLI 在创空白 PPT 后、加 slides 前自动上传并替换 token
-- 给已有 PPT 加带图新页：先 `slides +media-upload --file ./pic.png --presentation $PID` 拿 token，再用 token 写进 `xml_presentation.slide create` 的 XML
+- 给已有 PPT 加带图新页：`+add-slide --slide` 的 XML 里直接写 `src="@./pic.png"`，CLI 上传后替换 token 再提交页面
 
 > **注意**：`width`/`height` 是**裁剪后**的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 `width:height` 对齐原图比例。
 
@@ -355,6 +355,20 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 详细用法见 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。
 
+### embed
+
+嵌入内容容器：外层 `<embed>` 承载 Slides 的摆放和效果属性（`topLeftX`/`topLeftY`/`width`/`height` 必填，`rotation`/`flipX`/`flipY`/`alpha` 可选），内层承载外部标准内容。当前内层内容为标准 SVG，`<svg>` 必须使用 `http://www.w3.org/2000/svg` 命名空间，且仅描述嵌入内容本身，不承载 Slides 布局属性。
+
+```xml
+<embed topLeftX="80" topLeftY="120" width="200" height="120">
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 120">
+    <circle cx="100" cy="60" r="40" fill="rgba(37, 99, 235, 1)"/>
+  </svg>
+</embed>
+```
+
+`<embed>` 直接子元素为一个 `<svg>`（必需），以及可选的 `<reflection>`（倒影）与 `<shadow>`（阴影）。
+
 ## 颜色与样式
 
 ### fill
@@ -418,7 +432,7 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+<presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540">
   <title>季度报告</title>
   <theme>
     <textStyles>
@@ -466,7 +480,7 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 ## 最佳实践
 
-1. 始终带上命名空间 `xmlns="http://www.larkoffice.com/sml/2.0"`
+1. 始终带上命名空间 `xmlns="https://www.larkoffice.com/sml/2.0"`
 2. 用 `shape type="text"` + `content` 表达页面文本
 3. 用 `topLeftX` / `topLeftY`、`startX` / `startY` 等 schema 中定义的属性名
 4. 优先使用 `rgb` / `rgba` 颜色格式；渐变必须使用 `rgba()` 且带百分比停靠点
@@ -481,5 +495,5 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 ## Schema 版本信息
 
 - **版本**: 2.0.0
-- **命名空间**: http://www.larkoffice.com/sml/2.0
+- **命名空间**: https://www.larkoffice.com/sml/2.0
 - **发布日期**: 2025-11-03

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

@@ -16,11 +16,11 @@ from typing import Any
 
 
 XS_NS = "{http://www.w3.org/2001/XMLSchema}"
-SML_NAMESPACE = "http://www.larkoffice.com/sml/2.0"
+SML_NAMESPACE = "https://www.larkoffice.com/sml/2.0"
+SML_LEGACY_HTTP_NAMESPACE = "http://www.larkoffice.com/sml/2.0"
 SML_READBACK_NAMESPACE = "/sml/2.0"
-SML_HTTPS_READBACK_NAMESPACE = "https://www.larkoffice.com/sml/2.0"
 ACCEPTED_SML_NAMESPACES = frozenset(
-    (SML_NAMESPACE, SML_READBACK_NAMESPACE, SML_HTTPS_READBACK_NAMESPACE)
+    (SML_NAMESPACE, SML_LEGACY_HTTP_NAMESPACE, SML_READBACK_NAMESPACE)
 )
 
 
@@ -79,6 +79,15 @@ class ChildRule:
     order: int | None
 
 
+@dataclass(frozen=True)
+class WildcardRule:
+    namespace: str
+    process_contents: str
+    min_occurs: int
+    max_occurs: int | None
+    order: int | None
+
+
 @dataclass(frozen=True)
 class ChoiceRequirement:
     names: tuple[str, ...]
@@ -307,12 +316,13 @@ def multiplied_max(left: int | None, right: int | None) -> int | None:
 
 def child_rules_for_complex_type(
     complex_type: ET.Element,
-) -> tuple[list[ChildRule], list[ChoiceRequirement]]:
+) -> tuple[list[ChildRule], list[WildcardRule], list[ChoiceRequirement]]:
     particle = particle_for_complex_type(complex_type)
     if particle is None:
-        return [], []
+        return [], [], []
 
     rules: list[ChildRule] = []
+    wildcard_rules: list[WildcardRule] = []
     requirements: list[ChoiceRequirement] = []
     next_order = 0
 
@@ -337,6 +347,25 @@ def child_rules_for_complex_type(
             )
         )
 
+    def add_wildcard(
+        wildcard: ET.Element,
+        *,
+        order: int | None,
+        optional_by_choice: bool,
+        max_multiplier: int | None,
+    ) -> None:
+        minimum = occurs_value(wildcard.attrib.get("minOccurs"), 1) or 0
+        maximum = occurs_value(wildcard.attrib.get("maxOccurs"), 1)
+        wildcard_rules.append(
+            WildcardRule(
+                namespace=wildcard.attrib.get("namespace", "##any"),
+                process_contents=wildcard.attrib.get("processContents", "strict"),
+                min_occurs=0 if optional_by_choice else minimum,
+                max_occurs=multiplied_max(maximum, max_multiplier),
+                order=order,
+            )
+        )
+
     def walk_group(
         group: ET.Element,
         *,
@@ -369,6 +398,13 @@ def child_rules_for_complex_type(
                         optional_by_choice=True,
                         max_multiplier=effective_max,
                     )
+                elif child_kind == "any":
+                    add_wildcard(
+                        child,
+                        order=choice_order,
+                        optional_by_choice=True,
+                        max_multiplier=effective_max,
+                    )
                 elif child_kind in {"sequence", "all", "choice"}:
                     walk_group(
                         child,
@@ -395,6 +431,17 @@ def child_rules_for_complex_type(
                     optional_by_choice=optional_by_choice or group_min == 0,
                     max_multiplier=effective_max,
                 )
+            elif child_kind == "any":
+                child_order = fixed_order
+                if child_order is None and ordered and group_ordered:
+                    child_order = next_order
+                    next_order += 1
+                add_wildcard(
+                    child,
+                    order=child_order,
+                    optional_by_choice=optional_by_choice or group_min == 0,
+                    max_multiplier=effective_max,
+                )
             elif child_kind in {"sequence", "all", "choice"}:
                 walk_group(
                     child,
@@ -405,7 +452,7 @@ def child_rules_for_complex_type(
                 )
 
     walk_group(particle, ordered=local_name(particle.tag) == "sequence")
-    return rules, requirements
+    return rules, wildcard_rules, requirements
 
 
 def issue(
@@ -688,6 +735,31 @@ def element_namespace(tag: str) -> str | None:
     return tag[1:].split("}", 1)[0]
 
 
+def wildcard_matches_namespace(namespace_rule: str, namespace: str | None) -> bool:
+    tokens = namespace_rule.split()
+    if "##any" in tokens:
+        return True
+    if "##local" in tokens and namespace is None:
+        return True
+    if "##targetNamespace" in tokens and namespace == SML_NAMESPACE:
+        return True
+    if "##other" in tokens and namespace not in {None, SML_NAMESPACE}:
+        return True
+    return namespace in tokens
+
+
+def wildcard_namespace_description(namespace_rule: str) -> str:
+    if namespace_rule == "##any":
+        return "any namespace"
+    if namespace_rule == "##local":
+        return "the local namespace"
+    if namespace_rule == "##targetNamespace":
+        return f"the target namespace {SML_NAMESPACE}"
+    if namespace_rule == "##other":
+        return "a namespace other than the SXSD target namespace"
+    return f"namespace {namespace_rule}"
+
+
 def validate_element_children(
     element: ET.Element,
     path: str,
@@ -696,8 +768,10 @@ def validate_element_children(
 ) -> tuple[list[dict[str, Any]], dict[int, ElementRule]]:
     tag = local_name(element.tag)
     complex_type = complex_type_for_element(element_rule, model)
-    child_rules, choice_requirements = (
-        child_rules_for_complex_type(complex_type) if complex_type is not None else ([], [])
+    child_rules, wildcard_rules, choice_requirements = (
+        child_rules_for_complex_type(complex_type)
+        if complex_type is not None
+        else ([], [], [])
     )
     rules_by_name: dict[str, list[ChildRule]] = {}
     for child_rule in child_rules:
@@ -706,19 +780,37 @@ def validate_element_children(
     issues: list[dict[str, Any]] = []
     matched: dict[int, ElementRule] = {}
     counts: dict[str, int] = {}
+    wildcard_counts: dict[int, int] = {}
     latest_order = -1
     for child in element:
         child_name = local_name(child.tag)
         child_path = f"{path}/{child_name}"
         candidates = rules_by_name.get(child_name, [])
-        if not candidates:
+        wildcard_match = next(
+            (
+                (index, wildcard_rule)
+                for index, wildcard_rule in enumerate(wildcard_rules)
+                if wildcard_matches_namespace(
+                    wildcard_rule.namespace,
+                    element_namespace(child.tag),
+                )
+            ),
+            None,
+        )
+        if not candidates and wildcard_match is None:
+            expected_children = sorted(rules_by_name)
+            expected_children.extend(
+                wildcard_namespace_description(rule.namespace) for rule in wildcard_rules
+            )
             issues.append(
                 issue(
                     "sxsd_unexpected_child",
                     child_path,
                     child_name,
                     attr=None,
-                    expected="one of: " + ", ".join(sorted(rules_by_name)) if rules_by_name else "no child elements",
+                    expected="one of: " + ", ".join(expected_children)
+                    if expected_children
+                    else "no child elements",
                     actual=child_name,
                     message=f"unexpected SXSD child <{child_name}> under <{tag}> at {child_path}",
                     hint=f"Move or remove <{child_name}> so <{tag}> follows the SXSD child structure.",
@@ -726,6 +818,40 @@ def validate_element_children(
             )
             continue
 
+        if not candidates and wildcard_match is not None:
+            wildcard_index, wildcard_rule = wildcard_match
+            if wildcard_rule.order is not None:
+                if wildcard_rule.order < latest_order:
+                    issues.append(
+                        issue(
+                            "sxsd_invalid_child_order",
+                            child_path,
+                            child_name,
+                            attr=None,
+                            expected="children in xs:sequence order",
+                            actual=child_name,
+                            message=f"SXSD child <{child_name}> is out of order under <{tag}> at {child_path}",
+                            hint=f"Reorder <{child_name}> according to the SXSD sequence for <{tag}>.",
+                        )
+                    )
+                latest_order = max(latest_order, wildcard_rule.order)
+            wildcard_counts[wildcard_index] = wildcard_counts.get(wildcard_index, 0) + 1
+            actual_count = wildcard_counts[wildcard_index]
+            if wildcard_rule.max_occurs is not None and actual_count > wildcard_rule.max_occurs:
+                issues.append(
+                    issue(
+                        "sxsd_too_many_children",
+                        child_path,
+                        child_name,
+                        attr=None,
+                        expected=f"at most {wildcard_rule.max_occurs} child from {wildcard_namespace_description(wildcard_rule.namespace)}",
+                        actual=actual_count,
+                        message=f"too many wildcard SXSD children under <{tag}> at {path}",
+                        hint=f"Keep at most {wildcard_rule.max_occurs} child from {wildcard_namespace_description(wildcard_rule.namespace)} under <{tag}>.",
+                    )
+                )
+            continue
+
         child_rule = candidates[0]
         if child_rule.order is not None:
             if child_rule.order < latest_order:
@@ -777,6 +903,24 @@ def validate_element_children(
             )
         )
 
+    for wildcard_index, wildcard_rule in enumerate(wildcard_rules):
+        actual_count = wildcard_counts.get(wildcard_index, 0)
+        if wildcard_rule.min_occurs <= actual_count:
+            continue
+        namespace_description = wildcard_namespace_description(wildcard_rule.namespace)
+        issues.append(
+            issue(
+                "sxsd_missing_required_child",
+                path,
+                tag,
+                attr=None,
+                expected=f"at least {wildcard_rule.min_occurs} child from {namespace_description}",
+                actual=actual_count,
+                message=f"missing required wildcard SXSD child under <{tag}> at {path}",
+                hint=f"Add at least {wildcard_rule.min_occurs} child from {namespace_description} under <{tag}>.",
+            )
+        )
+
     for requirement in choice_requirements:
         actual_count = sum(counts.get(name, 0) for name in requirement.names)
         expected_names = ", ".join(requirement.names)