npm - pi-feishu-cli - Versions diffs - 0.1.0 - Mend

pi-feishu-cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (407) hide show

package/skills/lark-slides/assets/templates/product--product_promotion_2.xml ADDED Viewed

@@ -0,0 +1,198 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <link rel="icon" href="favicon.ico" />
+  <title></title>
+  <style>
+      * {
+          box-sizing: border-box;
+          padding: 0;
+          margin: 0;
+      }
+      .open-platform-wrapper {
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          justify-content: center;
+          height: 100vh;
+          background-color: #ffffff;
+      }
+      .open-platform-icon {
+          width: 120px;
+          height: 120px;
+          display: block;
+      }
+      .open-platform-desc {
+          margin-top: 16px;
+          line-height: 22px;
+          font-size: 14px;
+          color: #646a73;
+          text-align: center
+      }
+      .open-platform-back {
+          border-radius: 6px;
+          font-size: 14px;
+          height: 32px;
+          line-height: 22px;
+          min-width: 80px;
+          padding: 4px 11px;
+          text-align: center;
+          text-decoration: none;
+          touch-action: manipulation;
+          transition: color .1s ease-in, background-color .1s ease-in, border-color .1s ease-in, width .2s ease-in;
+          user-select: none;
+          white-space: nowrap;
+          background: #1456f0;
+          border: 1px solid #1456f0;
+          color: #ffffff;
+          margin-top: 16px;
+      }
+  </style>
+</head>
+<body>
+<div class="open-platform-wrapper">
+  <img class="open-platform-icon"
+       src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTIwIiBoZWlnaHQ9IjEyMCIgdmlld0JveD0iMCAwIDEyMCAxMjAiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZD0iTTEyLjkxMyA1NS4yNDRjLTUuNjMyIDIuOTUtOC4yNDYgNi4yODQtOC4yNDYgOS40NHY5LjcyYzAtMy4xNTYgMi42MTQtNi40OSA4LjI0Ni05LjQ0di05LjcyWm05NC4xNjMtMTIuMDg0di05LjcyNmM1LjkzNC0zLjE5IDguOTgxLTYuODkxIDguOTgxLTEwLjcyNXY5LjcyYzAgMy44NC0zLjA0NyA3LjU0My04Ljk4MSAxMC43MzJaIiBmaWxsPSIjMEMyOTZFIi8+PHBhdGggZD0iTTYwLjIyOSAxOS4wNTkgNDguNzMgNDkuOTIyIDYwLjM2NSA3Mi45MmwtOC40NzQgMjMuODczSDE2LjkyM2E0IDQgMCAwIDEtNC00VjIzLjA2YTQgNCAwIDAgMSA0LTRINjAuMjNaIiBmaWxsPSIjQkJCRkM0IiBmaWxsLW9wYWNpdHk9Ii40NSIvPjxwYXRoIGQ9Ik03MS40MDggMTkuMDU5IDYwLjAxMyA0OS45MjIgNzEuNDYgNzIuOTJsLTguMzI1IDIzLjg3M2gzOS45NDNhNCA0IDAgMCAwIDQtNFYyMy4wNmE0IDQgMCAwIDAtNC00aC0zMS42N1oiIGZpbGw9IiNCQkJGQzQiIGZpbGwtb3BhY2l0eT0iLjQ1Ii8+PHBhdGggZD0iTTIxLjkyMyAyNi4xYTIgMiAwIDEgMSAwIDQgMiAyIDAgMCAxIDAtNFptMyAyYTMgMyAwIDEgMC02IDAgMyAzIDAgMCAwIDYgMFptNi45MTUtMmEyIDIgMCAxIDEgMCA0IDIgMiAwIDAgMSAwLTRabTMgMmEzIDMgMCAxIDAtNiAwIDMgMyAwIDAgMCA2IDBabS0xNS43NjMgNy4zOTRhLjUuNSAwIDAgMSAuNS0uNWgzMS41ODFhLjUuNSAwIDAgMSAwIDFIMTkuNTc1YS41LjUgMCAwIDEtLjUtLjVabTQ4LjQ3NyAwYS41LjUgMCAwIDEgLjUtLjVoMzIuNDY1YS41LjUgMCAwIDEgMCAxSDY4LjA1MmEuNS41IDAgMCAxLS41LS41WiIgZmlsbD0iIzhGOTU5RSIvPjxwYXRoIGQ9Ik05OCAxMTFjOS45NDEgMCAxOC04LjA1OSAxOC0xOHMtOC4wNTktMTgtMTgtMThjLTkuOTQyIDAtMTggOC4wNTktMTggMThzOC4wNTggMTggMTggMThaIiBmaWxsPSIjRjgwIi8+PHBhdGggZD0iTTk3LjE4MSA4NC44MThhLjgxOC44MTggMCAwIDAtLjgxOC44MTl2OS44MThjMCAuNDUyLjM2Ni44MTguODE4LjgxOGgxLjYzN2EuODE4LjgxOCAwIDAgMCAuODE4LS44MTh2LTkuODE5YS44MTguODE4IDAgMCAwLS44MTgtLjgxOEg5Ny4xOFptMCAxMy4wOTJhLjgxOC44MTggMCAwIDAtLjgxOC44MTh2MS42MzZjMCAuNDUyLjM2Ni44MTguODE4LjgxOGgxLjYzN2EuODE4LjgxOCAwIDAgMCAuODE4LS44MTh2LTEuNjM2YS44MTguODE4IDAgMCAwLS44MTgtLjgxOUg5Ny4xOFoiIGZpbGw9IiNmZmYiLz48cGF0aCBkPSJNNC4wMjcgODUuMzFjMi40OSA1LjUxIDE0Ljc3IDkuOTQgNDEuNDUgOS45M3Y5LjcyMWMtMjYuNjguMDEtMzguOTYtNC40Mi00MS40NS05Ljkzdi05LjcyWm04NC44MS0yNy4yN2MxNy41Mi0yLjY5IDI1LjgwNy03LjAyNiAyNy4yLTExLjcxdjkuNzJjLS4zMyA0LjY3LTkuNjggOS4wMi0yNy4yIDExLjcxdi05LjcyWiIgZmlsbD0iIzMzNzBGRiIvPjxwYXRoIGQ9Ik04OS4yMzcgMTMuMDFjMTguMDU4IDAgMjYuOCAzLjI1IDI2LjggOS43MnY5LjcyYzAtNi40Ny04Ljc0Mi05LjcyLTI2LjgtOS43MnYtOS43MlptLTg0LjU3IDUxLjdjMCA2LjYgMTEuMzcgMTIuNDUgMzAuNDcgMTIuNDR2OS43MmMtMTkuMSAwLTMwLjQ3LTUuODQtMzAuNDctMTIuNDR2LTkuNzJaIiBmaWxsPSIjMDBENkI5Ii8+PC9zdmc+"
+       alt="">
+  <div class="open-platform-desc">The page does not exist.</div>
+  <a class="open-platform-back" href="/">Go to homepage</a>
+</div>
+<script>window.gfdatav1={"env":"prod","ver":"1.0.0.13","canary":0,"garrModules":null,"envName":"prod","region":"CN","idc":"hl","webServerCodeType":"DeployServerlessWebServer","runtime":"node","extra":{"canaryType":null}}</script><script>
+  function parseQueryString(queryString) {
+    // 移除开头的 "?"
+    if (queryString.charAt(0) === '?') {
+      queryString = queryString.substring(1);
+    }
+    var params = {};
+    if (!queryString) return params;
+    // 分割参数对
+    var paramPairs = queryString.split('&');
+    for (var i = 0; i < paramPairs.length; i++) {
+      var paramPair = paramPairs[i].split('=');
+      var key = decodeURIComponent(paramPair[0]);
+      var value = paramPair.length > 1 ? decodeURIComponent(paramPair[1]) : '';
+      // 处理重复参数（转为数组）
+      if (params[key] === undefined) {
+        params[key] = value;
+      } else if (!Array.isArray(params[key])) {
+        params[key] = [params[key], value];
+      } else {
+        params[key].push(value);
+      }
+    }
+    return params;
+  }
+  function getLocale() {
+    var zhLang = 'zh-CN';
+    var enLang = 'en-US';
+    var queryLang = parseQueryString(window.location.search).lang;
+    var cookieLang = getCookieLocale();
+    var lang = enLang;
+    <!--从cookie中取值-->
+    function getCookieLocale() {
+      var locale = '';
+      var cookies = document.cookie.split('; ');
+      var loclaeKey = 'open_locale';
+      for (var i = 0; i < cookies.length; i++) {
+        var cookie = cookies[i].trim();
+        var cookieArr = cookie.split('=');
+        if (cookieArr[0] === loclaeKey) {
+          locale = cookieArr[1];
+          break;
+        }
+      }
+      return locale;
+    }
+    function setLocaleCookie(lang) {
+      var date = new Date();
+      // 300天到期
+      date.setTime(date.getTime() + (300 * 24 * 60 * 60 * 1000));
+      var expires = 'expires=' + date.toUTCString();
+      document.cookie = 'open_locale=' + lang + '; ' + expires + '; path=/;';
+    }
+    // 获取浏览器默认语言
+    if (navigator.language.indexOf('en') !== -1) {
+      lang = enLang;
+    } else if (navigator.language.indexOf('zh') !== -1) {
+      lang = zhLang;
+    }
+    if (cookieLang === enLang) {
+      lang = enLang;
+    } else if (cookieLang === zhLang) {
+      lang = zhLang;
+    }
+    if (queryLang === enLang) {
+      lang = enLang;
+    } else if (queryLang === zhLang) {
+      lang = zhLang;
+    }
+    // 设置cookie
+    setLocaleCookie(lang);
+    return lang;
+  }
+  // 根据域名获取当前brand
+  function isLarkDomain() {
+    var defaultBrandMap = {
+      lark: ['larksuite'],
+      feishu: ['feishu', 'larkoffice', 'larkenterprise'],
+    };
+    const { hostname } = window.location;
+    if (defaultBrandMap.feishu.some((item) => hostname.includes(item))) {
+      return false;
+    }
+    if (defaultBrandMap.lark.some((item) => hostname.includes(item))) {
+      return true;
+    }
+    if (window.domainBrand) {
+      return window.domainBrand === 'lark';
+    }
+    return false;
+  }
+  var isLarkBrand = isLarkDomain();
+  var config = {
+    'zh-CN': {
+      'desc': '抱歉，您访问的页面不存在',
+      'back': '返回首页',
+      'title': (isLarkBrand ? 'Lark' : '飞书') + '开放平台',
+    },
+    'en-US': {
+      'desc': 'The page does not exist.',
+      'back': 'Go to homepage',
+      'title': (isLarkBrand ? 'Lark': 'Feishu') + ' Open Platform',
+    },
+  };
+  var locale = getLocale();
+  var descObj = document.querySelector('.open-platform-desc');
+  var backObj = document.querySelector('.open-platform-back');
+  descObj.innerHTML = config[locale].desc;
+  backObj.innerHTML = config[locale].back;
+  document.title = config[locale].title;
+</script>
+</body>
+</html>

package/skills/lark-slides/references/asset-planning.md ADDED Viewed

@@ -0,0 +1,124 @@
+# Asset Planning
+新建演示文稿或大幅改写页面时，在写入 `slide_plan.json` 前后都可以参考本文件。目标是让 agent 主动识别有价值的图、图标、图表、截图或示意图需求，同时保持 deck 在没有真实素材时也能完整执行。
+本文件只定义轻量资产规划。不要把它理解成素材采集流程。
+## Core Rules
+- `asset_need` is metadata only. It can guide page design, but it must not require web search, local download, media upload, or external tools.
+- Every planned asset must include a fallback visual plan so the slide can be generated with XML shapes, text, arrows, tables, simple charts, or placeholder regions.
+- Asset needs must serve the page's `key_message` and `visual_focus`. Do not add decorative assets that do not clarify the page.
+- Prefer a few high-value asset plans over one asset on every page. For a 6-page technical or business deck, plan assets on at least 3 pages when the content allows.
+- If a real local asset already exists or the user provides one, it can be used through the normal media-upload workflow. Still keep `fallback_if_missing` in the plan.
+- Do not leave blank image boxes in final XML. If the asset is missing, render the fallback visual.
+## JSON Shape
+Use an object for one planned asset, or an array when a page genuinely needs multiple assets. Keep each item compact.
+```json
+{
+  "asset_type": "architecture_diagram",
+  "purpose": "Show how API gateway, planner, XML generator, and Slides API interact.",
+  "suggested_query": "agent native slides runtime architecture diagram",
+  "fallback_if_missing": "Draw grouped boxes and arrows with XML shapes; use labels instead of an image."
+}
+```
+For a page without a meaningful asset need, use:
+```json
+{
+  "asset_type": "none",
+  "purpose": "No external or simulated asset needed; the page is text-led.",
+  "suggested_query": "",
+  "fallback_if_missing": "Use typography, spacing, and simple accent shapes only."
+}
+```
+## Supported Asset Types
+- `paper_figure`: figure from a paper or technical article.
+- `architecture_diagram`: system components, data flow, dependency map, or model structure.
+- `icon`: small semantic symbol for a concept, step, role, or status.
+- `logo`: brand, product, team, or customer mark.
+- `chart`: line, bar, pie, funnel, scatter, or chart-like data visual.
+- `infographic`: composed visual explanation, usually combining labels, numbers, and simple shapes.
+- `screenshot`: product UI, terminal output, workflow state, or page capture.
+- `flow_diagram`: process, sequence, decision tree, or mechanism diagram.
+- `none`: explicitly no asset needed.
+Do not invent new asset types unless the user asks for a special visual format. If a need is close to these types, choose the closest one and explain the detail in `purpose`.
+## Planning Guidance
+Match asset type to slide role:
+- `architecture-diagram` layout usually pairs with `architecture_diagram` or `flow_diagram`.
+- `process-flow` layout usually pairs with `flow_diagram`, `icon`, or `infographic`.
+- `comparison` layout often works with `icon`, `chart`, or `infographic`.
+- `timeline` layout often works with `icon`, `chart`, or shape-based milestone markers.
+- `big-number` layout often works with `chart` or `infographic`, but only if it supports the metric.
+- `image-left-text-right` and `image-right-text-left` can use `screenshot`, `paper_figure`, `logo`, or `infographic`; if missing, use a large placeholder diagram or stylized panel.
+`suggested_query` is only a future lookup hint. Write it as a short phrase a human or later workflow could search, but do not execute the search unless the user separately requests real assets.
+`fallback_if_missing` must be concrete enough to turn into XML, for example:
+- "Draw a simplified attention matrix with 5 token labels, semi-transparent cells, and arrows to output token."
+- "Use three grouped boxes with arrows from client to gateway to service; add small protocol labels."
+- "Render a mini bar chart with 4 bars using shapes and value labels."
+- "Use a bordered placeholder panel with product area labels, not an empty image."
+Weak fallbacks to avoid:
+- "Use a placeholder."
+- "Find another image."
+- "Leave blank if unavailable."
+- "Use generic decoration."
+## Examples
+Transformer Self-Attention page:
+```json
+{
+  "asset_type": "paper_figure",
+  "purpose": "Explain token-to-token attention and why each output token mixes context.",
+  "suggested_query": "Transformer self attention attention matrix diagram",
+  "fallback_if_missing": "Draw a simplified attention matrix with token labels, colored weights, and arrows from input tokens to one highlighted output token."
+}
+```
+System architecture page:
+```json
+{
+  "asset_type": "architecture_diagram",
+  "purpose": "Show the runtime path from user prompt to plan, XML generation, Slides API creation, and fetch verification.",
+  "suggested_query": "slides generation runtime architecture planner XML API verification",
+  "fallback_if_missing": "Draw four grouped boxes connected left-to-right with arrows; put verification as a return arrow from Slides API to agent."
+}
+```
+Business comparison page:
+```json
+{
+  "asset_type": "infographic",
+  "purpose": "Make before/after differences scannable without dense bullet lists.",
+  "suggested_query": "before after product workflow comparison infographic",
+  "fallback_if_missing": "Use two side-by-side panels with matching icon circles and three parallel rows of concise labels."
+}
+```
+## Plan To XML Contract
+When generating XML:
+1. If an asset exists and the workflow supports it, place it in the planned visual region.
+2. If no asset exists, immediately render `fallback_if_missing` with XML-native shapes, text, lines, arrows, tables, or chart-like elements.
+3. Size the fallback to satisfy `visual_focus`; it should be a real page element, not a tiny decoration.
+4. Keep text-density limits. Do not compensate for missing assets by adding long bullet text.
+5. After creation, fetch the presentation and verify asset pages are not blank and that each planned fallback is visible when no real asset was used.

package/skills/lark-slides/references/examples.md ADDED Viewed

@@ -0,0 +1,261 @@
+# 完整操作示例
+本文档提供与 CLI schema 一致的调用示例，XML 内容均遵循 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。
+> **重要**：创建 PPT 请优先使用 `slides +create`；实际页面内容请使用 `xml_presentation.slide.create` 逐页添加。
+## 目录
+- [示例 1: 使用 Shortcut 创建空白演示文稿](#示例-1-使用-shortcut-创建空白演示文稿)
+- [示例 2: 创建后添加第一页](#示例-2-创建后添加第一页)
+- [示例 3: 读取 XML 内容](#示例-3-读取-xml-内容)
+- [示例 4: 在指定页面前插入新幻灯片](#示例-4-在指定页面前插入新幻灯片)
+- [示例 5: 删除幻灯片](#示例-5-删除幻灯片)
+- [示例 6: 从文件读取 XML 后添加页面](#示例-6-从文件读取-xml-后添加页面)
+- [示例 7: +replace-slide + block_insert 给已有页加图](#示例-7-replace-slide--block_insert-给已有页加图)
+- [示例 8: +replace-slide + block_replace 替换一个块](#示例-8-replace-slide--block_replace-替换一个块)
+## 示例 1: 使用 Shortcut 创建空白演示文稿
+```bash
+lark-cli slides +create --title "项目汇报"
+```
+预期返回结构：
+```json
+{
+  "data": {
+    "xml_presentation_id": "slides_example_presentation_id",
+    "title": "项目汇报",
+    "revision_id": 1
+  }
+}
+```
+## 示例 2: 创建后添加第一页
+```bash
+PRESENTATION_ID=$(lark-cli slides +create --title "季度复盘" | jq -r '.data.xml_presentation_id')
+lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data '{
+  "slide": {
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><style><fill><fillColor color=\"rgb(245, 245, 245)\"/></fill></style><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"72\" width=\"760\" height=\"90\"><content textType=\"title\"><p>2024 Q3 季度复盘</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"190\" width=\"520\" height=\"220\"><content textType=\"body\"><p>关键结论</p><ul><li><p>收入增长 30%</p></li><li><p>重点项目全部上线</p></li><li><p>用户满意度持续提升</p></li></ul></content></shape><shape type=\"rect\" topLeftX=\"660\" topLeftY=\"180\" width=\"180\" height=\"140\"><fill><fillColor color=\"rgba(100, 149, 237, 0.25)\"/></fill><border color=\"rgb(100, 149, 237)\" width=\"2\"/></shape></data><note><content textType=\"body\"><p>讲述时先给结论，再补充数据。</p></content></note></slide>"
+  }
+}'
+```
+## 示例 3: 读取 XML 内容
+```bash
+lark-cli slides xml_presentations get --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}'
+```
+提取 XML 内容：
+```bash
+lark-cli slides xml_presentations get --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' | jq -r '.data.xml_presentation.content'
+```
+预期返回结构：
+```json
+{
+  "code": 0,
+  "data": {
+    "xml_presentation": {
+      "presentation_id": "slides_example_presentation_id",
+      "revision_id": 3,
+      "content": "<presentation xmlns=\"http://www.larkoffice.com/sml/2.0\" height=\"540\" width=\"960\">...</presentation>"
+    }
+  },
+  "msg": "success"
+}
+```
+## 示例 4: 在指定页面前插入新幻灯片
+```bash
+lark-cli slides xml_presentation.slide create --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' --data '{
+  "slide": {
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新增页面</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"200\" width=\"800\" height=\"180\"><content textType=\"body\"><p>这是新增页面的正文。</p></content></shape></data></slide>"
+  },
+  "before_slide_id": "sld_before_target"
+}'
+```
+预期返回结构：
+```json
+{
+  "code": 0,
+  "data": {
+    "slide_id": "slide_example_id",
+    "revision_id": 100
+  },
+  "msg": "success"
+}
+```
+## 示例 5: 删除幻灯片
+```bash
+lark-cli slides xml_presentation.slide delete --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id",
+  "slide_id": "slide_example_id"
+}'
+```
+预期返回结构：
+```json
+{
+  "code": 0,
+  "data": {
+    "revision_id": 101
+  },
+  "msg": "success"
+}
+```
+## 示例 6: 从文件读取 XML 后添加页面
+先准备 `slide.xml`：
+```xml
+<slide xmlns="http://www.larkoffice.com/sml/2.0">
+  <data>
+    <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+      <content textType="title">
+        <p>从文件加载</p>
+      </content>
+    </shape>
+  </data>
+</slide>
+```
+先创建演示文稿：
+```bash
+PRESENTATION_ID=$(lark-cli slides +create --title "从文件添加页面" | jq -r '.data.xml_presentation_id')
+```
+再用 `jq` 组装请求体，从文件添加页面：
+```bash
+lark-cli slides xml_presentation.slide create --as user \
+  --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" \
+  --data "$(jq -n --arg content "$(cat slide.xml)" '{slide:{content:$content}}')"
+```
+## 示例 7: +replace-slide + block_insert 给已有页加图
+只想在已有页上加一张图、不动其他元素——走 shortcut `+replace-slide`，`block_insert` 追加到页末（或用 `insert_before_block_id` 指定位置）。
+```bash
+PID="slides_example_presentation_id"
+SID="slide_example_id"
+# 1. 上传图片拿 file_token
+TOKEN=$(lark-cli slides +media-upload --file ./pic.png --presentation "$PID" --as user \
+  | jq -r '.data.file_token')
+# 2. block_insert 到页面末尾（省略 insert_before_block_id）
+# 注：<img .../> 是自闭合标签，CLI 不会展开（只有 <shape/> 会被补 <content/>）
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" \
+  --parts "$(jq -n --arg token "$TOKEN" \
+    '[{action:"block_insert",insertion:("<img src=\""+$token+"\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>")}]')"
+```
+预期返回：
+```json
+{
+  "ok": true,
+  "data": {
+    "xml_presentation_id": "slides_example_presentation_id",
+    "slide_id": "slide_example_id",
+    "parts_count": 1,
+    "revision_id": 102
+  }
+}
+```
+## 示例 8: +replace-slide + block_replace 替换一个块
+已知某块的 3 位 short element ID（从 `slide.get` 返回 XML 里读），整块换掉。`replacement` 根元素的 `id` 会由 CLI 自动注入为 `block_id`，无需手写；若写了 `<shape/>` 自闭合形式，CLI 也会自动补 `<content/>`。
+```bash
+lark-cli slides +replace-slide --as user \
+  --presentation slides_example_presentation_id \
+  --slide-id slide_example_id \
+  --parts '[
+    {
+      "action": "block_replace",
+      "block_id": "bab",
+      "replacement": "<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"
+    }
+  ]'
+# CLI 实际发送的 replacement 根元素会带 id="bab"，即使手写时省略了
+```
+失败时（3350001 错误，CLI 在 error 字段中给出 hint）：
+```json
+{
+  "ok": false,
+  "error": {
+    "type": "api_error",
+    "code": 3350001,
+    "message": "API error: [3350001] invalid param",
+    "hint": "common causes: (1) block_id not found in current slide ..."
+  }
+}
+```
+整批作为原子事务，任一 part 失败则整批不生效；按 `failed_part_index` 定位修正后重发。
+## 常见处理技巧
+### 获取最新 revision_id
+```bash
+lark-cli slides xml_presentations get --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' | jq '.data.xml_presentation.revision_id'
+```
+### 批量插入多页
+```bash
+#!/bin/bash
+PRESENTATION_ID="slides_example_presentation_id"
+slides=(
+  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 1</p></content></shape></data></slide>'
+  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 2</p></content></shape></data></slide>'
+)
+for slide_xml in "${slides[@]}"; do
+  payload=$(jq -n --arg content "$slide_xml" '{slide:{content:$content}}')
+  lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data "$payload"
+done
+```
+### 本地校验 XML 基本语法
+```bash
+xmllint --noout presentation.xml
+```
+### 真实示例
+- [slides_demo.xml](slides_demo.xml) 提供了更完整的页面示例，包含 `theme`、渐变填充、图片、图标和备注内容。