ooodc a7883dbed9 refactor(todo): 重构待办事项管理逻辑及更新状态规则

- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段
- 强制每个任务都必须有唯一 id，且由用户负责生成
- 修改合并模式逻辑，merge=true 下保留未提及的旧任务
- 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress）
- 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled
- 优化状态转换校验，允许特定状态间合法切换
- 简化任务变更消息，移除详细的新增/更新/移除统计
- 更新文档和示例，明确 id 必须由用户生成和使用
- 修复和补充测试，增强状态转换和合并模式验证
- 调整任务时间戳生成逻辑，统一使用当前时间及索引
- 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性

2026-06-13 09:22:33 +08:00

8.9 KiB

Raw Blame History

XML 格式指南

本文档基于 slides_xml_schema_definition.xml 整理，说明飞书 Slides XML Schema（SML 2.0）的核心结构和常用写法。

基本结构

<?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>

示例：

<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"。

<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
  <content textType="title">
    <p>主标题</p>
  </content>
</shape>

<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>`

<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>`

<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>`

<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>`

<fill>
  <fillColor color="rgb(100, 149, 237)"/>
</fill>

`<border>`

<border color="rgb(0, 0, 0)" width="2" dashArray="solid"/>

颜色格式

<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>`

<note>
  <content textType="body">
    <p>这是演讲者备注内容。</p>
  </content>
</note>

完整示例

<?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>

最佳实践

始终带上命名空间 xmlns="http://www.larkoffice.com/sml/2.0"
用 shape type="text" + content 表达页面文本
用 topLeftX / topLeftY、startX / startY 等 schema 中定义的属性名
优先使用 rgb / rgba 颜色格式
特殊字符按 XML 规则转义
标准 16:9 页面建议使用 width="960" 和 height="540"

8.9 KiB Raw Blame History Unescape Escape

XML 格式指南

基本结构

根元素

<presentation>

主题

<theme>

幻灯片元素

<slide>

文本内容模型

<content>

<p>

常用页面元素

<shape>

<line>

<img>

<icon>

<table>

<chart>

样式元素

<fill>

<border>

颜色格式

演讲者备注

<note>

完整示例

最佳实践

参考文档

8.9 KiB

Raw Blame History

`<presentation>`

`<theme>`

`<slide>`

`<content>`

`<p>`

`<shape>`

`<line>`

`<img>`

`<icon>`

`<table>`

`<chart>`

`<fill>`

`<border>`

`<note>`