@amaster.ai/pi-lark 0.1.2-beta.44 → 0.1.2-beta.45

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

@@ -34,6 +34,24 @@ class XmlTextOverlapLintTest(unittest.TestCase):
             f"{sample_name} has XML text overlap lint warnings:\n" + "\n".join(issue_summaries),
         )
 
+    def test_cli_suggests_input_flag_for_positional_argument(self) -> None:
+        script_path = Path(xml_text_overlap_lint.__file__).resolve()
+        input_path = "/sandboxdata/workspace/file/full_presentation.xml"
+
+        completed = subprocess.run(
+            [sys.executable, str(script_path), input_path],
+            capture_output=True,
+            check=False,
+            text=True,
+        )
+
+        self.assertEqual(completed.returncode, 1)
+        self.assertEqual(completed.stdout, "")
+        self.assertEqual(
+            completed.stderr,
+            f"xml-text-overlap-lint error: unexpected argument: {input_path}，need --input\n",
+        )
+
     def test_xml_text_overlap_lint_accepts_inline_fixture_xml_samples(self) -> None:
         samples = {
             "image-led-cover": """
@@ -311,6 +329,42 @@ class XmlTextOverlapLintTest(unittest.TestCase):
         self.assertEqual(issue["tag"], "fill")
         self.assertEqual(issue["attr"], "unexpected")
 
+    def test_lint_xml_ignores_chart_roundtrip_attrs(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <chart updated="true" topLeftX="80" topLeftY="80" width="300" height="160">
+                  <chartData isStaticData="true"/>
+                </chart>
+              </data>
+            </slide>
+            """
+        )
+
+        self.assertEqual(result["summary"]["error_count"], 0)
+        self.assertNotIn("issues", result)
+
+    def test_lint_xml_limits_chart_roundtrip_attrs_to_matching_tags(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <chart isStaticData="true" topLeftX="80" topLeftY="80" width="300" height="160">
+                  <chartData updated="true"/>
+                </chart>
+              </data>
+            </slide>
+            """
+        )
+
+        self.assertEqual(result["summary"]["error_count"], 2)
+        self.assertEqual(
+            {(issue["tag"], issue["attr"]) for issue in result["issues"]},
+            {("chart", "isStaticData"), ("chartData", "updated")},
+        )
+        self.assertTrue(all(issue["code"] == "sxsd_unsupported_attr" for issue in result["issues"]))
+
     def test_lint_xml_reports_gradient_shorthand_attrs_on_fill_color(self) -> None:
         result = xml_text_overlap_lint.lint_xml(
             """
@@ -468,43 +522,6 @@ class XmlTextOverlapLintTest(unittest.TestCase):
         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(
             """
@@ -523,6 +540,7 @@ class XmlTextOverlapLintTest(unittest.TestCase):
             """
         )
         self.assertEqual(result["summary"]["error_count"], 1)
+        self.assertEqual(result["summary"]["warning_count"], 0)
         self.assertEqual(result["slides"][0]["issues"][0]["code"], "bbox_overlap")
 
     def test_lint_xml_detects_current_itinerary_cjk_caption_occlusion(self) -> None:
@@ -589,7 +607,7 @@ class XmlTextOverlapLintTest(unittest.TestCase):
             <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>
+                  <content fontSize="18" wrap="false"><p>这是一个足够长的中文文本用于检测跨越间隙的横向溢出</p></content>
                 </shape>
                 <shape id="target" type="text" topLeftX="260" topLeftY="100" width="160" height="40">
                   <content fontSize="18"><p>目标</p></content>
@@ -599,10 +617,31 @@ class XmlTextOverlapLintTest(unittest.TestCase):
             """
         )
         self.assertEqual(result["summary"]["error_count"], 1)
+        self.assertEqual(result["summary"]["warning_count"], 0)
         self.assertEqual(result["slides"][0]["issues"][0]["code"], "bbox_overlap")
         self.assertEqual(result["slides"][0]["issues"][0]["elements"], ["source", "target"])
 
-    def test_lint_xml_reports_text_out_of_canvas_but_not_text_height(self) -> None:
+    def test_lint_xml_allows_horizontal_text_with_default_wrap(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"], 0)
+        self.assertEqual(result["summary"]["warning_count"], 1)
+        self.assertEqual(result["slides"][0]["issues"][0]["code"], "text_may_overflow_shape")
+        self.assertEqual(result["slides"][0]["issues"][0]["elements"], ["source"])
+
+    def test_lint_xml_reports_text_out_of_canvas_and_warns_for_text_height(self) -> None:
         result = xml_text_overlap_lint.lint_xml(
             """
             <presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
@@ -621,10 +660,98 @@ class XmlTextOverlapLintTest(unittest.TestCase):
         )
         issue = result["slides"][0]["issues"][0]
         self.assertEqual(result["summary"]["error_count"], 1)
-        self.assertEqual(result["summary"]["warning_count"], 0)
+        self.assertEqual(result["summary"]["warning_count"], 1)
         self.assertEqual(issue["code"], "shape_out_of_canvas")
         self.assertEqual(issue["overflow"], {"left": 0, "top": 0, "right": 160, "bottom": 40})
 
+    def test_lint_xml_warns_when_text_may_overflow_its_own_shape(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <shape id="overflowing" type="text" topLeftX="80" topLeftY="80" width="360" height="80">
+                  <content fontSize="20" lineSpacing="multiple:1.5">
+                    <p>第一段</p><p>第二段</p><p>第三段</p><p>第四段</p>
+                  </content>
+                </shape>
+                <shape id="fitting" type="text" topLeftX="480" topLeftY="80" width="360" height="120">
+                  <content fontSize="20" lineSpacing="multiple:1.5">
+                    <p>第一段</p><p>第二段</p><p>第三段</p><p>第四段</p>
+                  </content>
+                </shape>
+                <shape id="auto-fit" type="text" topLeftX="80" topLeftY="240" width="360" height="80">
+                  <content fontSize="20" lineSpacing="multiple:1.5" autoFit="normal-auto-fit">
+                    <p>第一段</p><p>第二段</p><p>第三段</p><p>第四段</p>
+                  </content>
+                </shape>
+              </data>
+            </slide>
+            """
+        )
+        issues = result["slides"][0]["issues"]
+        self.assertEqual(result["summary"]["error_count"], 0)
+        self.assertEqual(result["summary"]["warning_count"], 1)
+        self.assertEqual(issues[0]["code"], "text_may_overflow_shape")
+        self.assertEqual(issues[0]["elements"], ["overflowing"])
+        self.assertEqual(issues[0]["line_count"], 4)
+        self.assertEqual(issues[0]["estimated_height"], 110)
+        self.assertEqual(issues[0]["available_height"], 80)
+        self.assertEqual(issues[0]["overflow"], 30)
+        self.assertIn('wrap="true" autoFit="normal-auto-fit"', issues[0]["message"])
+
+    def test_lint_xml_uses_fixed_line_spacing_for_text_height_warning(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <shape id="fixed-overflow" type="text" topLeftX="80" topLeftY="80" width="360" height="50">
+                  <content fontSize="20" lineSpacing="fixed:20">
+                    <p>第一段</p><p>第二段</p><p>第三段</p>
+                  </content>
+                </shape>
+              </data>
+            </slide>
+            """
+        )
+        issue = result["slides"][0]["issues"][0]
+        self.assertEqual(result["summary"]["warning_count"], 1)
+        self.assertEqual(issue["line_height"], 20)
+        self.assertEqual(issue["estimated_height"], 60)
+        self.assertEqual(issue["overflow"], 10)
+
+    def test_lint_xml_uses_paragraph_spacing_overrides_for_text_height_warning(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0">
+              <data>
+                <shape id="paragraph-overflow" type="text" topLeftX="80" topLeftY="80" width="360" height="35">
+                  <content fontSize="20" lineSpacing="multiple:1.5">
+                    <p lineSpacing="fixed:10" beforeLineSpacing="fixed:5" afterLineSpacing="fixed:5">第一行<br/>第二行</p>
+                  </content>
+                </shape>
+                <shape id="paragraph-fitting" type="text" topLeftX="480" topLeftY="80" width="360" height="40">
+                  <content fontSize="20" lineSpacing="multiple:1.5">
+                    <p lineSpacing="fixed:10">第一行<br/>第二行<br/>第三行</p>
+                  </content>
+                </shape>
+              </data>
+            </slide>
+            """
+        )
+        issues = result["slides"][0]["issues"]
+        self.assertEqual(result["summary"]["warning_count"], 1)
+        self.assertEqual(issues[0]["elements"], ["paragraph-overflow"])
+        self.assertEqual(issues[0]["line_count"], 2)
+        self.assertEqual(issues[0]["line_height"], 10)
+        self.assertEqual(issues[0]["estimated_height"], 40)
+        self.assertEqual(issues[0]["overflow"], 5)
+
+    def test_strip_xml_paragraphs_preserves_br_as_hard_line_break(self) -> None:
+        self.assertEqual(
+            xml_text_overlap_lint.strip_xml_paragraphs("<p>第一行<br/>第二行<br />第三行</p>"),
+            "第一行\n第二行\n第三行",
+        )
+
     def test_lint_xml_allows_template_style_bleed_and_text_over_images(self) -> None:
         result = xml_text_overlap_lint.lint_xml(
             """
@@ -730,7 +857,6 @@ class XmlTextOverlapLintTest(unittest.TestCase):
                   <shape id="outside-shape" type="text" topLeftX="-10" topLeftY="40" width="50" height="50"/>
                   <img id="outside-img" src="token" topLeftX="120" topLeftY="-20" width="50" height="50"/>
                   <chart id="outside-chart" topLeftX="900" topLeftY="100" width="100" height="100"/>
-                  <whiteboard id="outside-whiteboard" topLeftX="100" topLeftY="500" width="100" height="100"/>
                 </data>
               </slide>
             </presentation>
@@ -1054,89 +1180,6 @@ class XmlTextOverlapLintTest(unittest.TestCase):
                         result["slides"][0]["issues"],
                     )
 
-    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 = [
             (
@@ -1166,5 +1209,21 @@ class XmlTextOverlapLintTest(unittest.TestCase):
                 self.assertEqual(result["slides"][0]["issues"][0]["code"], "bbox_overlap")
 
 
+    def test_lint_xml_reports_vertical_text_image_overlap_as_info(self) -> None:
+        result = xml_text_overlap_lint.lint_xml(
+            """
+            <slide xmlns="http://www.larkoffice.com/sml/2.0"><data>
+              <shape id="text" type="text" vert="vert" topLeftX="100" topLeftY="100" width="100" height="100">
+                <content><p>Vertical</p></content>
+              </shape>
+              <img id="image" src="token" topLeftX="120" topLeftY="120" width="20" height="20"/>
+            </data></slide>
+            """
+        )
+        issue = next(issue for issue in result["slides"][0]["issues"] if issue["code"] == "image_may_cover_vertical_text")
+        self.assertEqual(issue["level"], "info")
+        self.assertEqual(result["summary"]["error_count"], 0)
+
+
 if __name__ == "__main__":
     unittest.main()

package/skills/lark-whiteboard/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 
 > [!IMPORTANT]
 > - 运行 `lark-cli --version`，确认可用，无需询问用户。
-> - 运行 `npx -y @larksuite/whiteboard-cli@^0.2.12 -v`，确认可用，无需询问用户。
+> - 运行 `npx -y @larksuite/whiteboard-cli@^0.2.13 -v`，确认可用，无需询问用户。
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
 
@@ -22,21 +22,22 @@ metadata:
 
 **身份**：画板操作默认使用 `--as user`。仅当需要以应用身份上传时使用 `--as bot`。
 
-| 用户需求                                    | 行动                                                                                            |
-|-----------------------------------------|-----------------------------------------------------------------------------------------------|
-| 查看画板内容 / 导出图片 / 导出 SVG 矢量图 | [`+query --output_as image/svg`](references/lark-whiteboard-query.md)                             |
-| 获取画板的 Mermaid/PlantUML 代码               | [`+query --output_as code`](references/lark-whiteboard-query.md)                              |
-| 检查画板是否由代码绘制                             | [`+query --output_as code`](references/lark-whiteboard-query.md)                              |
-| 仅微调节点文字/颜色                         | `+query --output_as raw` → 手动改 JSON → `+update --input_format raw`                            |
+| 用户需求                                    | 行动                                                                                                |
+|-----------------------------------------|---------------------------------------------------------------------------------------------------|
+| 查看画板内容 / 导出图片 | [`+export --output-type preview`](references/lark-whiteboard-export.md)                       |
+| 导出 SVG 矢量图 | [`+export --output-type svg`](references/lark-whiteboard-export.md)                       |
+| 获取画板的 Mermaid/PlantUML 代码               | [`+export --output-type source`](references/lark-whiteboard-export.md)                             |
+| 检查画板是否由代码绘制                             | [`+export --output-type source`](references/lark-whiteboard-export.md)                             |
+| 仅微调节点文字/颜色                         | `+export --output-type raw` → 手动改 JSON → `+update --input_format raw`                             |
 | 用户**已提供** Mermaid/PlantUML/SVG 代码，或明确指定用该格式 | 自己生成/使用代码 → [`+update --input_format mermaid/plantuml/svg`](references/lark-whiteboard-update.md) |
-| 新建/创作复杂图表（架构/流程/组织等）                    | → **[§ 创作 Workflow](references/lark-whiteboard-workflow.md#创作-workflow)**                     |
-| 修改/重绘已有画板                               | → **[§ 修改 Workflow](references/lark-whiteboard-workflow.md#修改-workflow)**                     |
+| 新建/创作复杂图表（架构/流程/组织等）                    | → **[§ 创作 Workflow](references/lark-whiteboard-workflow.md#创作-workflow)**                         |
+| 修改/重绘已有画板                               | → **[§ 修改 Workflow](references/lark-whiteboard-workflow.md#修改-workflow)**                         |
 
 ## Shortcuts
 
-| Shortcut | 说明 |
-|---|---|
-| [`+query`](references/lark-whiteboard-query.md) | 查询画板，导出为预览图片、SVG 矢量图、代码或原始节点结构。 |
+| Shortcut                                          | 说明 |
+|---------------------------------------------------|---|
+| [`+export`](references/lark-whiteboard-export.md) | 导出画板为预览图片、SVG 矢量图、代码或原始节点结构。 |
 | [`+update`](references/lark-whiteboard-update.md) | 更新画板，支持 PlantUML、Mermaid、SVG 或 OpenAPI 原生格式 |
 
 ---

package/skills/lark-whiteboard/elements/layout.md

@@ -336,7 +336,7 @@ DSL 的语法是严格白名单，不能写原生 CSS 属性（不支持 `alignS
 先出骨架图导出坐标，再基于坐标补充连线和注解：
 
 ```bash
-npx -y @larksuite/whiteboard-cli@^0.2.12 -i skeleton.json -o step1.png -l coords.json
+npx -y @larksuite/whiteboard-cli@^0.2.13 -i skeleton.json -o step1.png -l coords.json
 ```
 
 `coords.json` 包含每个带 id 节点的精确坐标（absX, absY, width, height）。

package/skills/lark-whiteboard/elements/schema.md

@@ -272,14 +272,14 @@ SVG 通过 `image/svg+xml` Blob 加载到画布，**不在 HTML DOM 中**，因
   x?: number; y?: number;
   width?: WBSizeValue;          // 默认 48
   height?: WBSizeValue;         // 默认 48，保持正方形
-  name: string;                 // 图标名称，从 npx -y @larksuite/whiteboard-cli@^0.2.12 --icons 输出中选取
+  name: string;                 // 图标名称，从 npx -y @larksuite/whiteboard-cli@^0.2.13 --icons 输出中选取
   color?: string;               // 可选颜色覆盖，hex 格式如 '#FF6600'
 }
 ```
 
 **获取可用图标**：规划好内容和布局后，运行以下命令查看所有可用图标名，从中选取：
 ```bash
-npx -y @larksuite/whiteboard-cli@^0.2.12 --icons
+npx -y @larksuite/whiteboard-cli@^0.2.13 --icons
 ```
 
 用法：

package/skills/lark-whiteboard/references/{lark-whiteboard-query.md → lark-whiteboard-export.md}

@@ -1,23 +1,23 @@
-# whiteboard +query（查询画板）
+# whiteboard +export（导出画板）
 
 > **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-查询画板内容，支持导出为预览图片、SVG 矢量图、提取 PlantUML/Mermaid 代码，或获取飞书 OpenAPI 原生画板节点格式。
+导出画板内容，支持导出为预览图片、SVG 矢量图、提取 PlantUML/Mermaid 代码，或获取飞书 OpenAPI 原生画板节点格式。
 
 ## 参数
 
 | 参数                   | 必填 | 说明                                                                     |
 |----------------------|----|------------------------------------------------------------------------|
 | `--whiteboard-token` | 是  | 画板 token，需要拥有画板的读权限                                                    |
-| `--output_as`        | 是  | 输出格式：`image`（预览图片）、`svg`（SVG 矢量图）、`code`（PlantUML/Mermaid 代码）、`raw`（OpenAPI 原生画板节点格式） |
-| `--output`           | 否  | 输出路径。当 `--output_as image` 时必填；当 `--output_as svg/code/raw` 时可选，不填则直接输出到终端 |
+| `--output-type`      | 是  | 输出格式：`preview`（预览图片）、`svg`（SVG 矢量图）、`source`（PlantUML/Mermaid 代码）、`raw`（OpenAPI 原生画板节点格式） |
+| `--output`           | 否  | 输出路径。当 `--output-type preview` 时必填，推荐传入无后缀文件路径（如 `./preview`）；当 `--output-type svg/source/raw` 时可选，不填则直接输出到终端 |
 | `--overwrite`        | 否  | 覆盖已存在的文件，默认为 false                                                     |
 
 ## 输出格式
 
-- `image`：预览图片
+- `preview`：预览图片。推荐 `--output ./preview` 这类无后缀文件路径，CLI 会按实际图片类型保存为 `./preview.png` 或 `./preview.jpg`。如果 `--output` 是目录，会保存为该目录下的 `whiteboard_<whiteboard-token>.png/.jpg`；如果显式写了后缀，需要和实际图片类型匹配。`--overwrite` 检查的是补齐后缀后的最终路径，例如返回 PNG 时 `--output ./preview` 对应覆盖 `./preview.png`。
 - `svg`：导出画板为标准 SVG 矢量图。可用于 SVG 编辑后回写画板（见 [`routes/svg-edit.md`](../routes/svg-edit.md)）。注意：导出为纯视觉快照，思维导图层级、表格结构、连接器绑定等语义信息会丢失。
-- `code`：PlantUML/Mermaid 代码。仅限画板内有且仅有一个 PlantUML/Mermaid 图时，才可导出代码，否则会在返回值中告知不存在/有多个节点。
+- `source`：PlantUML/Mermaid 代码。仅限画板内有且仅有一个 PlantUML/Mermaid 图时，才可导出代码，否则会在返回值中告知不存在/有多个节点。
 - `raw`：飞书 OpenAPI 原生画板节点格式。这一 json 格式不适合直接编辑复杂布局或内容，建议仅限于需要修改简单的文本内容/颜色等细节时使用。需要进行更复杂的设计/修改时，建议参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)。
 
 ## 示例
@@ -25,26 +25,26 @@
 ### 示例 1：导出画板为预览图片
 
 ```bash
-lark-cli whiteboard +query \
+lark-cli whiteboard +export \
   --whiteboard-token "wbcnxxxxxxxx" \
-  --output_as image \
-  --output ./preview.png
+  --output-type preview \
+  --output ./preview
 ```
 
 ### 示例 2：提取画板中的代码并直接输出
 
 ```bash
-lark-cli whiteboard +query \
+lark-cli whiteboard +export \
   --whiteboard-token "wbcnxxxxxxxx" \
-  --output_as code
+  --output-type source
 ```
 
 ### 示例 3：导出画板为 SVG 矢量图
 
 ```bash
-lark-cli whiteboard +query \
+lark-cli whiteboard +export \
   --whiteboard-token "wbcnxxxxxxxx" \
-  --output_as svg \
+  --output-type svg \
   --output ./whiteboard.svg \
   --as user
 ```
@@ -52,9 +52,9 @@ lark-cli whiteboard +query \
 ### 示例 4：导出画板原始节点结构到文件
 
 ```bash
-lark-cli whiteboard +query \
+lark-cli whiteboard +export \
   --whiteboard-token "wbcnxxxxxxxx" \
-  --output_as raw \
+  --output-type raw \
   --output ./nodes.json \
   --overwrite
 ```

package/skills/lark-whiteboard/references/lark-whiteboard-update.md

@@ -16,7 +16,7 @@
 | 参数                   | 必填 | 说明                                         |
 |----------------------|----|--------------------------------------------|
 | `--whiteboard-token` | 是  | 画板 token，需要拥有画板的编辑权限                       |
-| `--idempotent-token` | 否  | 幂等 token，确保更新操作幂等，最小长度 10 个字符              |
+| `--idempotent-token` | 否  | 幂等 token，确保更新操作幂等；最少 10 个字符，建议使用时间戳 + 场景标识拼接（如 `1744800000-board-1`）。同一次逻辑更新只生成一次该 token，重试时须原样复用；切勿在每次重试时重新生成时间戳或幂等 key，否则会重复写入 |
 | `--overwrite`        | 否  | 覆盖更新，在更新前删除所有现有内容，默认为 false                |
 | `--source`           | 是  | 输入画板内容，支持使用 `@path` 从文件读取，或 `-` 从 stdin 读取 |
 | `--input_format`     | 否  | 输入格式：`raw`、`plantuml`、`mermaid`、`svg`，默认为 `raw`  |
@@ -75,7 +75,7 @@ whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKIL
 
 ```bash
 # 使用 whiteboard-cli 生成 OpenAPI 格式并通过管道传递
-npx -y @larksuite/whiteboard-cli@^0.2.12 -i <产物文件> --to openapi --format json \
+npx -y @larksuite/whiteboard-cli@^0.2.13 -i <产物文件> --to openapi --format json \
   | lark-cli whiteboard +update \
     --whiteboard-token <画板Token> \
     --source - --input_format raw \
@@ -89,7 +89,7 @@ whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKIL
 
 ```bash
 # 生成 OpenAPI 格式到文件
-npx -y @larksuite/whiteboard-cli@^0.2.12 -i <DSL 文件> --to openapi --format json -o ./temp.json
+npx -y @larksuite/whiteboard-cli@^0.2.13 -i <DSL 文件> --to openapi --format json -o ./temp.json
 
 # 从文件读取并更新
 lark-cli whiteboard +update \

package/skills/lark-whiteboard/references/lark-whiteboard-workflow.md

@@ -26,12 +26,12 @@
 **Step 2：判断修改策略**
 
 ```
-+query --output_as code
++export --output-type source
   ├─ 返回 Mermaid/PlantUML 代码
   │   → 在原代码上修改 → +update --input_format mermaid/plantuml
   ├─ 无代码（SVG/DSL 或其他方式绘制的画板）
   │   ├─ 需纯新增（思维导图、流程图、时序图、类图、饼图、甘特图）图表节点
-  │   │    → +query --output_as image → 看图 → +query --output_as raw → 确定新节点坐标和层级  → [§ 渲染 & 写入画板]
+  │   │    → +export --output-type preview → 看图 → +export --output-type raw → 确定新节点坐标和层级  → [§ 渲染 & 写入画板]
   │   └─ 其他改动（几何变动/增删元素/结构调整/混合编辑等）
   │       → [`../routes/svg-edit.md`](../routes/svg-edit.md)（视觉高保真还原，大部分场景适用）
   └─ 用户有明确要求 → 以用户要求优先
@@ -79,19 +79,9 @@ diagram.png           ← 渲染结果
 
 ### 写入画板
 
-> 关于 --overwrite
-> 画板更新命令中，若不携带 --overwrite flag，则是增量更新画板内容，若画板内已有内容的话，新增内容可能会和已有内容重叠，导致问题。
-> 因此，若需要整体更新画板内容，需携带 --overwrite flag 覆盖式更新。
-
-```bash
-npx -y @larksuite/whiteboard-cli@^0.2.12 -i <产物文件> --to openapi --format json \
-  | lark-cli whiteboard +update \
-    --whiteboard-token <Token> \
-    --source - --input_format raw \
-    --idempotent-token <10+字符唯一串> \
-    --as user \
-    --overwrite
-```
+写入画板时按最终产物类型选择 `+update --input_format`：
+
+- Mermaid / PlantUML / SVG 产物直接用对应的 `mermaid` / `plantuml` / `svg` 写入。
+- 只有 DSL 产物或已明确需要 OpenAPI 原生节点格式时，才先用 `npx -y @larksuite/whiteboard-cli@^0.2.13 --to openapi --format json` 转换，再用 `raw` 写入。
 
-> `--idempotent-token` 最少 10 字符，建议用时间戳+标识拼接（如 `1744800000-board-1`），避免重试导致重复写入。
-> 如需应用身份上传，将 `--as user` 替换为 `--as bot`。
+具体命令示例、`--overwrite`、`--idempotent-token` 和 `--as user/bot` 的使用方式，统一参考 [`whiteboard +update`](./lark-whiteboard-update.md)。

package/skills/lark-whiteboard/routes/dsl.md

@@ -13,7 +13,7 @@ Step 1: 路由 & 读取知识
 Step 2: 生成完整 DSL（含颜色）
   - 按 content.md 规划信息量和分组
   - 按 layout.md 选择布局模式和间距
-  - 推荐使用图标让图表更直观，运行 `npx -y @larksuite/whiteboard-cli@^0.2.12 --icons` 查看可用图标
+  - 推荐使用图标让图表更直观，运行 `npx -y @larksuite/whiteboard-cli@^0.2.13 --icons` 查看可用图标
   - 按 style.md 上色（用户没指定时用默认经典色板）
   - 按 schema.md 语法输出完整 JSON
   - 连线参考 connectors.md，排版参考 typography.md
@@ -25,12 +25,12 @@ Step 2: 生成完整 DSL（含颜色）
 
 Step 3: 渲染 & 审查 → 交付
   - 渲染前自查（见下方检查清单）
-  - 渲染 PNG（仅用于预览验证，不是最终产物）：npx -y @larksuite/whiteboard-cli@^0.2.12 -i diagram.json -o diagram.png
+  - 渲染 PNG（仅用于预览验证，不是最终产物）：npx -y @larksuite/whiteboard-cli@^0.2.13 -i diagram.json -o diagram.png
   - 检查：信息完整？布局合理？配色协调？文字无截断？连线无交叉？
   - 有问题 → 按症状表修复 → 重新渲染（最多 2 轮）
   - 2 轮后仍有严重问题 → 考虑走 Mermaid 路径兜底
   - 写入画板：用 whiteboard-cli 将 diagram.json 转换为 OpenAPI 格式并 pipe 给 +update：
-      npx -y @larksuite/whiteboard-cli@^0.2.12 -i diagram.json --to openapi --format json \
+      npx -y @larksuite/whiteboard-cli@^0.2.13 -i diagram.json --to openapi --format json \
         | lark-cli whiteboard +update --whiteboard-token <board_token> \
             --source - --input_format raw --idempotent-token <时间戳+标识> --as user
       → 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板)

package/skills/lark-whiteboard/routes/mermaid.md

@@ -16,10 +16,10 @@ Step 3: 渲染验证 & 写入画板 & 交付
   1. 创建产物目录 ./diagrams/YYYY-MM-DDTHHMMSS/
   2. 保存为 diagram.mmd
   3. 渲染（仅用于预览验证，PNG 不是最终产物）：
-       npx -y @larksuite/whiteboard-cli@^0.2.12 -i diagram.mmd -o diagram.png
+       npx -y @larksuite/whiteboard-cli@^0.2.13 -i diagram.mmd -o diagram.png
   4. 审查 PNG，有问题修改后重新渲染（最多 2 轮）
   5. 写入画板：用 whiteboard-cli 将 diagram.mmd 转换为 OpenAPI 格式并 pipe 给 +update：
-       npx -y @larksuite/whiteboard-cli@^0.2.12 -i diagram.mmd --to openapi --format json \
+       npx -y @larksuite/whiteboard-cli@^0.2.13 -i diagram.mmd --to openapi --format json \
          | lark-cli whiteboard +update --whiteboard-token <board_token> \
              --source - --input_format raw --idempotent-token <时间戳+标识> --as user
        → 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板)