@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/lark-tools/cli-skills/lark-slides/references/xml-format-guide.md

@@ -0,0 +1,369 @@
+# XML 格式指南
+
+本文档基于 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 整理，说明飞书 Slides XML Schema（SML 2.0）的核心结构和常用写法。
+
+## 基本结构
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+  <title>演示文稿标题</title>
+  <slide>
+    <style>
+      <fill>
+        <fillColor color="rgb(245, 245, 245)"/>
+      </fill>
+    </style>
+    <data>
+      <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+        <content textType="title">
+          <p>主标题</p>
+        </content>
+      </shape>
+    </data>
+    <note>
+      <content textType="body">
+        <p>这是演讲者备注。</p>
+      </content>
+    </note>
+  </slide>
+</presentation>
+```
+
+## 根元素
+
+### `<presentation>`
+
+协议标准写法应带命名空间 `http://www.larkoffice.com/sml/2.0`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证。
+
+**属性：**
+
+| 属性 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `width` | positiveInteger | 是 | 演示文稿宽度，如 `960` |
+| `height` | positiveInteger | 是 | 演示文稿高度，如 `540` |
+| `id` | string | 否 | 演示文稿标识 |
+
+**子元素：**
+
+| 元素 | 必需 | 说明 |
+|------|------|------|
+| `<title>` | 否 | 演示文稿标题 |
+| `<theme>` | 否 | 全局主题 |
+| `<slide>` | 是 | 幻灯片页面，至少 1 页，最多 100 页 |
+
+## 主题
+
+### `<theme>`
+
+`<theme>` 当前包含两部分：
+
+- `<background>`：演示文稿级背景填充
+- `<textStyles>`：主题文本样式集合
+
+`<textStyles>` 下可选子元素：
+
+- `<title>`
+- `<headline>`
+- `<sub-headline>`
+- `<body>`
+- `<caption>`
+
+这些元素定义的是主题默认样式，不是页面结构。常用属性：
+
+| 属性 | 说明 |
+|------|------|
+| `fontFamily` | 字体 |
+| `fontSize` | 字号 |
+| `fontColor` | 字体颜色 |
+
+## 幻灯片元素
+
+### `<slide>`
+
+单张幻灯片的结构比较严格。
+
+**属性：**
+
+| 属性 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `id` | string | 否 | 幻灯片标识 |
+
+**直接子元素只有：**
+
+| 元素 | 必需 | 说明 |
+|------|------|------|
+| `<style>` | 否 | 页面样式 |
+| `<data>` | 否 | 页面元素容器 |
+| `<note>` | 否 | 演讲者备注 |
+
+这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。
+
+## 文本内容模型
+
+### `<content>`
+
+实际页面文本通常通过 `<content>` 表达，常见位置有：
+
+- `shape` 内部
+- `table/td` 内部
+- `note` 内部
+
+**常用属性：**
+
+| 属性 | 说明 |
+|------|------|
+| `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` |
+| `verticalAlign` | 垂直对齐 |
+| `textAlign` | 水平对齐 |
+| `lineSpacing` | 行间距 |
+| `fontSize` | 字号 |
+| `fontFamily` | 字体 |
+| `color` | 字体颜色 |
+| `bold` / `italic` / `underline` / `strikethrough` | 内容级样式 |
+| `wrap` | 是否自动换行 |
+
+**可包含的子元素：**
+
+- `<p>`
+- `<ul>`
+- `<ol>`
+
+### `<p>`
+
+`<p>` 是段落元素，可混排纯文本和内联标签：
+
+- `<br/>`
+- `<strong>`
+- `<em>`
+- `<u>`
+- `<span>`
+- `<del>`
+- `<a>`
+- `<shadow>`
+- `<outline>`
+
+示例：
+
+```xml
+<content textType="body" textAlign="left">
+  <p>普通文本 <strong>加粗</strong> <em>斜体</em> <a href="https://example.com">链接</a></p>
+  <ul>
+    <li><p>列表项 1</p></li>
+    <li><p>列表项 2</p></li>
+  </ul>
+</content>
+```
+
+## 常用页面元素
+
+所有页面元素都放在 `<data>` 中。
+
+### `<shape>`
+
+`shape` 可表示普通形状，也可表示文本框。文本框推荐使用 `type="text"`。
+
+```xml
+<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+  <content textType="title">
+    <p>主标题</p>
+  </content>
+</shape>
+```
+
+```xml
+<shape type="rect" topLeftX="700" topLeftY="120" width="180" height="120">
+  <fill>
+    <fillColor color="rgba(100, 149, 237, 0.25)"/>
+  </fill>
+  <border color="rgb(100, 149, 237)" width="2"/>
+</shape>
+```
+
+**属性：**
+
+| 属性 | 必需 | 说明 |
+|------|------|------|
+| `type` | 是 | 形状类型，`text` 表示文本框 |
+| `topLeftX` | 是 | 左上角 X 坐标 |
+| `topLeftY` | 是 | 左上角 Y 坐标 |
+| `width` | 是 | 宽度 |
+| `height` | 是 | 高度 |
+| `rotation` | 否 | 旋转角度 |
+| `flipX` / `flipY` | 否 | 翻转 |
+| `alpha` | 否 | 透明度 |
+
+**可选子元素：**
+
+- `<fill>`
+- `<border>`
+- `<reflection>`
+- `<shadow>`
+- `<content>`
+
+### `<line>`
+
+```xml
+<line startX="100" startY="200" endX="420" endY="200">
+  <border color="rgb(43, 47, 54)" width="2"/>
+</line>
+```
+
+`line` 使用的是 `startX` / `startY` / `endX` / `endY`，不是 `x1` / `y1` / `x2` / `y2`。
+
+### `<img>`
+
+```xml
+<img src="file_token_or_url" topLeftX="100" topLeftY="220" width="320" height="180"/>
+```
+
+`img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。
+
+`src` 只接受两种值：
+
+| `src` 形式 | 说明 |
+|---|---|
+| `file_token`（如 `boxcnXXXXXXXXXXXXXXXXXXXXXX`） | 通过 `slides +media-upload` 上传后返回的 token |
+| `@<本地路径>`（如 `@./assets/chart.png`） | **仅在 `slides +create --slides` 中可用**：CLI 会自动上传该文件并替换为 file_token |
+
+> **禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，`src="https://..."` 在 PPT 里通常显示破图。要用网图必须先 `curl`/下载到 CWD 内，再走上传流程拿 `file_token`。
+
+本地图片的两种姿势：
+
+- **新建带图 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
+
+### `<icon>`
+
+```xml
+<icon iconType="iconpark/Base/setting.svg" topLeftX="440" topLeftY="220" width="32" height="32"/>
+```
+
+### `<table>`
+
+表格结构为：
+
+- `<table>`
+- `<colgroup>` / `<tr>`
+- `<tr>` 内为 `<td>`
+- `<td>` 内可放 `<content>`
+
+### `<chart>`
+
+图表元素必须至少包含：
+
+- `<chartPlotArea>`
+- `<chartData>`
+
+同时还可以包含：
+
+- `<chartTitle>`
+- `<chartSubTitle>`
+- `<chartStyle>`
+- `<chartLegend>`
+- `<chartTooltip>`
+
+如果要写图表 XML，建议直接以 XSD 为准，不要自行发明更简化的 chart DSL。
+
+## 样式元素
+
+### `<fill>`
+
+```xml
+<fill>
+  <fillColor color="rgb(100, 149, 237)"/>
+</fill>
+```
+
+### `<border>`
+
+```xml
+<border color="rgb(0, 0, 0)" width="2" dashArray="solid"/>
+```
+
+### 颜色格式
+
+```xml
+<fillColor color="rgb(255, 0, 0)"/>
+<fillColor color="rgba(255, 0, 0, 0.5)"/>
+<fillColor color="linear-gradient(90deg, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/>
+<fillColor color="radial-gradient(circle at 50% 50%, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/>
+```
+
+## 演讲者备注
+
+### `<note>`
+
+```xml
+<note>
+  <content textType="body">
+    <p>这是演讲者备注内容。</p>
+  </content>
+</note>
+```
+
+## 完整示例
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+  <title>季度报告</title>
+  <theme>
+    <textStyles>
+      <title fontFamily="思源黑体" fontSize="54" fontColor="rgba(0, 0, 0, 1)"/>
+      <body fontFamily="思源黑体" fontSize="18" fontColor="rgba(43, 47, 54, 1)"/>
+    </textStyles>
+  </theme>
+  <slide>
+    <style>
+      <fill>
+        <fillColor color="rgb(245, 245, 245)"/>
+      </fill>
+    </style>
+    <data>
+      <shape type="text" topLeftX="80" topLeftY="72" width="760" height="100">
+        <content textType="title">
+          <p>2024 年第一季度报告</p>
+        </content>
+      </shape>
+      <shape type="text" topLeftX="80" topLeftY="200" width="520" height="180">
+        <content textType="body">
+          <p>核心指标</p>
+          <ul>
+            <li><p>用户增长：+25%</p></li>
+            <li><p>收入增长：+30%</p></li>
+            <li><p>市场份额：15%</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>
+</presentation>
+```
+
+## 最佳实践
+
+1. 始终带上命名空间 `xmlns="http://www.larkoffice.com/sml/2.0"`
+2. 用 `shape type="text"` + `content` 表达页面文本
+3. 用 `topLeftX` / `topLeftY`、`startX` / `startY` 等 schema 中定义的属性名
+4. 优先使用 `rgb` / `rgba` 颜色格式
+5. 特殊字符按 XML 规则转义
+6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"`
+
+## 参考文档
+
+- [xml-schema-quick-ref.md](xml-schema-quick-ref.md)
+- [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)
+- [examples.md](examples.md)
+- [slides_demo.xml](slides_demo.xml)

package/server/assets/skills/lark-tools/cli-skills/lark-slides/references/xml-schema-quick-ref.md

@@ -0,0 +1,215 @@
+# XML Schema 快速参考
+
+本文档是 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 的精简版摘要；如果两者不一致，以 XSD 原文为准。
+
+## 最重要的规则
+
+1. 协议标准写法应使用 `<presentation xmlns="http://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
+2. `<presentation>` 直接子元素只有 `<title>`、`<theme>`、`<slide>`
+3. `<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`
+4. 页面中的文本通常通过 `<content>` 表达，而不是把 `<title>`、`<body>` 直接挂在 `<slide>` 下
+
+## 最小可用示例
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+  <slide>
+    <data>
+      <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+        <content textType="title">
+          <p>标题</p>
+        </content>
+      </shape>
+    </data>
+  </slide>
+</presentation>
+```
+
+## presentation 根元素
+
+| 属性 | 必需 | 说明 |
+|------|------|------|
+| `width` | 是 | 演示文稿宽度，正整数 |
+| `height` | 是 | 演示文稿高度，正整数 |
+| `id` | 否 | 演示文稿标识 |
+
+**子元素：** `<title>?`, `<theme>?`, `<slide>+`
+
+## slide 元素
+
+| 属性 | 必需 | 说明 |
+|------|------|------|
+| `id` | 否 | 幻灯片标识 |
+
+**子元素：**
+- `<style>?` - 页面样式，目前可放 `<fill>`
+- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`undefined`
+- `<note>?` - 演讲者备注，内部可放 `<content>`
+
+## theme 与文本类型
+
+XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出现在：
+
+- `<theme><textStyles>...</textStyles></theme>` 中，作为主题文本样式
+- `<content textType="...">` 中，作为内容的文本类型
+
+`textStyles` 的 schema 默认值如下：
+
+| textType | 默认字号 |
+|----------|----------|
+| `title` | 54 |
+| `headline` | 38 |
+| `sub-headline` | 32 |
+| `body` | 16 |
+| `caption` | 12 |
+
+## content 内容模型
+
+`<content>` 可出现在 `shape`、`table/td`、`note` 中，常用属性包括：
+
+| 属性 | 说明 |
+|------|------|
+| `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` |
+| `textAlign` | 文本对齐方式 |
+| `lineSpacing` | 行间距，schema 默认 `multiple:1.5` |
+| `fontSize` | 字号 |
+| `fontFamily` | 字体 |
+| `color` | 字体颜色 |
+| `bold` / `italic` / `underline` / `strikethrough` | 文本样式 |
+
+`<content>` 的子元素只能是：
+
+- `<p>`
+- `<ul>`
+- `<ol>`
+
+### content 示例
+
+```xml
+<content textType="body" textAlign="left">
+  <p>正文内容 <strong>加粗</strong> <em>斜体</em> <a href="https://example.com">链接</a></p>
+  <ul>
+    <li><p>列表项 1</p></li>
+    <li><p>列表项 2</p></li>
+  </ul>
+</content>
+```
+
+## data 常用元素
+
+### shape
+
+```xml
+<shape type="rect" topLeftX="120" topLeftY="120" width="240" height="120">
+  <fill>
+    <fillColor color="rgb(100, 149, 237)"/>
+  </fill>
+  <border color="rgb(0, 0, 0)" width="2"/>
+</shape>
+```
+
+| 属性 | 必需 | 说明 |
+|------|------|------|
+| `type` | 是 | 形状类型，`text` 表示文本框 |
+| `topLeftX` | 是 | 左上角 X 坐标 |
+| `topLeftY` | 是 | 左上角 Y 坐标 |
+| `width` | 是 | 宽度 |
+| `height` | 是 | 高度 |
+| `rotation` | 否 | 旋转角度 |
+
+### line
+
+```xml
+<line startX="120" startY="120" endX="420" endY="120">
+  <border color="rgb(43, 47, 54)" width="2"/>
+</line>
+```
+
+### img
+
+```xml
+<img src="file_token_or_url" topLeftX="80" topLeftY="120" width="320" height="180"/>
+```
+
+`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)。
+
+> **注意**：`width`/`height` 是**裁剪后**的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 `width:height` 对齐原图比例。
+
+### icon
+
+```xml
+<icon iconType="iconpark/Base/setting.svg" topLeftX="80" topLeftY="120" width="32" height="32"/>
+```
+
+## 颜色与样式
+
+### fill
+
+```xml
+<fill>
+  <fillColor color="rgb(255, 0, 0)"/>
+</fill>
+```
+
+### border
+
+```xml
+<border color="rgb(43, 47, 54)" width="2" dashArray="solid"/>
+```
+
+### 颜色格式
+
+```xml
+<fillColor color="rgb(255, 0, 0)"/>
+<fillColor color="rgba(255, 0, 0, 0.5)"/>
+<fillColor color="linear-gradient(90deg, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/>
+<fillColor color="radial-gradient(circle at 50% 50%, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/>
+```
+
+> **注意**：渐变色必须使用 `rgba()` 格式并带百分比停靠点，例如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)`。使用 `rgb()` 或省略停靠点会导致服务端将其回退为白色。此规则对页面背景和 shape fill 均适用。
+
+### 页面背景
+
+```xml
+<!-- 纯色背景 -->
+<slide>
+  <style>
+    <fill>
+      <fillColor color="rgb(245, 245, 245)"/>
+    </fill>
+  </style>
+</slide>
+
+<!-- 渐变背景（必须用 rgba + 百分比停靠点） -->
+<slide>
+  <style>
+    <fill>
+      <fillColor color="linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)"/>
+    </fill>
+  </style>
+</slide>
+```
+
+## 备注示例
+
+```xml
+<note>
+  <content textType="body">
+    <p>这是演讲者备注。</p>
+  </content>
+</note>
+```
+
+## 详细参考
+
+- [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)
+- [xml-format-guide.md](xml-format-guide.md)
+- [examples.md](examples.md)
+- [slides_demo.xml](slides_demo.xml)
+
+## Schema 版本信息
+
+- **版本**: 2.0.0
+- **命名空间**: http://www.larkoffice.com/sml/2.0
+- **发布日期**: 2025-11-03