AxTps/Starlight_Lancher

Fork 1

Files

Ap_Tx 6a295f9a7a feat：移除了弹窗，服务器添加sls

2026-09-08 22:39:45 +08:00

13 KiB

Raw Blame History

OKR ContentBlock 富文本格式

OKR 的 Objective、KeyResult 中的 content/notes 字段使用 ContentBlock 富文本格式。本文档描述其结构和使用方式。

两种输入输出风格

OKR shortcuts 支持 --style 标志控制 content/notes 字段的输入输出格式：

`--style` 值	说明	适用场景
`simple`（默认）	半纯文本格式 `SemiPlainContent`，简化的 JSON 结构，仅包含 text、mention、docs、images	大多数场景，简单易用
`richtext`	原始 `ContentBlock` 富文本格式，完整的块结构和样式信息	需要精确控制@提及用户位置、包含图片/文档链接时

重要：输入时严格根据 --style 值验证格式，不会自动检测。输出时读操作（如 +cycle-detail、+progress-get）根据 --style 返回对应格式。

ContentBlock 结构概览

{
  "blocks": [
    {
      "block_element_type": "paragraph",
      "paragraph": {
        "style": {
          "list": {
            "list_type": "bullet",
            "indent_level": 0,
            "number": 1
          }
        },
        "elements": [
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": "Hello World",
              "style": {
                "bold": true,
                "strike_through": false,
                "back_color": {
                  "red": 255,
                  "green": 0,
                  "blue": 0,
                  "alpha": 1
                },
                "text_color": {
                  "red": 0,
                  "green": 255,
                  "blue": 0,
                  "alpha": 1
                },
                "link": {
                  "url": "https://example.com"
                }
              }
            }
          },
          {
            "paragraph_element_type": "docsLink",
            "docs_link": {
              "url": "https://larkoffice.com/docx/xxx",
              "title": "Lark Document"
            }
          },
          {
            "paragraph_element_type": "mention",
            "mention": {
              "user_id": "ou_xxx"
            }
          }
        ]
      }
    },
    {
      "block_element_type": "gallery",
      "gallery": {
        "images": [
          {
            "file_token": "file_xxx",
            "src": "https://...",
            "width": 800,
            "height": 600
          }
        ]
      }
    }
  ]
}

类型定义

ContentBlock

根级别内容块。

字段	类型	说明
`blocks`	`ContentBlockElement[]`	内容块元素数组

ContentBlockElement

内容块元素，支持段落或图库。

字段	类型	说明
`block_element_type`	`BlockElementType`	块类型：`paragraph` \| `gallery`
`paragraph`	`ContentParagraph`	段落内容（当 `block_element_type="paragraph"` 时）
`gallery`	`ContentGallery`	图库内容（当 `block_element_type="gallery"` 时）

ContentParagraph

段落内容。

字段	类型	说明
`style`	`ContentParagraphStyle`	段落样式（列表类型等）
`elements`	`ContentParagraphElement[]`	段落内元素数组

ContentParagraphElement

段落内元素，支持文本、文档链接、提及。

字段	类型	说明
`paragraph_element_type`	`ParagraphElementType`	元素类型：`textRun` \| `docsLink` \| `mention`
`text_run`	`ContentTextRun`	文本内容
`docs_link`	`ContentDocsLink`	飞书文档链接
`mention`	`ContentMention`	用户提及

ContentTextRun

文本块。

字段	类型	说明
`text`	`string`	文本内容
`style`	`ContentTextStyle`	文本样式

ContentTextStyle

文本样式。

字段	类型	说明
`bold`	`boolean`	是否粗体
`strike_through`	`boolean`	是否删除线
`back_color`	`ContentColor`	背景颜色
`text_color`	`ContentColor`	文字颜色
`link`	`ContentLink`	链接

ContentColor

颜色。

字段	类型	说明
`red`	`int32`	红色通道 (0-255)
`green`	`int32`	绿色通道 (0-255)
`blue`	`int32`	蓝色通道 (0-255)
`alpha`	`float64`	透明度 (0-1)

ContentParagraphStyle

段落样式。

字段	类型	说明
`list`	`ContentList`	列表样式

ContentList

列表样式。

字段	类型	说明
`list_type`	`ListType`	列表类型：`bullet` \| `number` \| `checkBox` \| `checkedBox` \| `indent`
`indent_level`	`int32`	缩进层级
`number`	`int32`	序号（当 `list_type="number"` 时）

ContentGallery

图片块。目前仅有进展记录中的富文本支持展示图片。

由于 OKR 应用中进展页面的布局排版限制，一个 ContentGallery 元素中仅可放置一个图片元素，需要插入多张图片时需使用多个 ContentGallery 元素 (同一个 ContentGallery 中添加多个 image 会导致这些图片在狭窄的横向排版空间中互相挤占，效果很差)

字段	类型	说明
`images`	`ContentImageItem[]`	图片项数组

ContentImageItem

图片项。

字段	类型	说明
`file_token`	`string`	文件 token
`src`	`string`	图片 URL
`width`	`float64`	宽度
`height`	`float64`	高度

如何获取 file_token？ 使用 +upload-image 命令上传本地图片，返回的 file_token 可用于构建 ContentGallery 图片块。

ContentDocsLink

飞书文档链接。

字段	类型	说明
`url`	`string`	链接 URL
`title`	`string`	链接标题

ContentMention

提及。

字段	类型	说明
`user_id`	`string`	用户 ID

ContentLink

链接。

字段	类型	说明
`url`	`string`	链接 URL

SemiPlainContent 半纯文本格式

SemiPlainContent 是 ContentBlock 的简化、有损表示形式，适用于大多数不需要复杂格式的场景。

结构

{
  "text": "任务一 @{ou_zhangsan} ，任务二 @{ou_lisi} ",
  "mention": ["ou_zhangsan", "ou_lisi"],
  "docs": [
    {
      "title": "产品需求文档",
      "url": "https://larkoffice.com/docx/xxx"
    }
  ],
  "images": [
    "https://example.com/image.png"
  ]
}

类型定义

字段	类型	说明
`text`	`string`	纯文本内容（必填，不能为空）。输出时包含 `@{userID}` 占位符以保留提及的位置上下文；输入时 `@{...}` 占位符会被自动 strip 掉，只识别 `mention` 字段内容
`mention`	`string[]`	用户 ID 列表（可选），与 text 中的 `@{userID}` 占位符一一对应，输入时按顺序转换为 mention 元素置于文本末尾
`docs`	`SemiPlainDoc[]`	文档列表（仅输出时包含，输入时 simple 风格不支持）
`images`	`string[]`	图片 URL 列表（仅输出时包含，输入时 simple 风格不支持）

SemiPlainDoc

字段	类型	说明
`title`	`string`	文档标题
`url`	`string`	文档 URL

双向转换说明

ContentBlock → SemiPlainContent（输出时）：提取纯文本、提及用户、文档链接和图片 URL，丢弃格式信息（粗体、列表、颜色等）。提及的位置信息通过 @{userID} 占位符保留在 text 中，同时 userID 也会被收集到 mention 数组中
SemiPlainContent → ContentBlock（输入时）：自动 strip 掉 text 中的 @{...} 占位符，然后将 text 和 mention 合并为单个段落，mention 按顺序附加在文本末尾。docs 和 images 在输入时被忽略（simple 风格不支持）

使用示例

示例 0：--style simple 半纯文本格式

{
  "text": "提升用户满意度",
  "mention": ["ou_123"]
}

使用方式：

lark-cli okr +patch --level objective --style simple --target-id 123 --content '{"text":"提升用户满意度","mention":["ou_123"]}'

示例 1：简单文本段落（richtext 风格）

{
  "blocks": [
    {
      "block_element_type": "paragraph",
      "paragraph": {
        "elements": [
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": "提升用户满意度"
            }
          }
        ]
      }
    }
  ]
}

示例 2：带格式的文本段落

{
  "blocks": [
    {
      "block_element_type": "paragraph",
      "paragraph": {
        "elements": [
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": "Q2 目标",
              "style": {
                "bold": true
              }
            }
          },
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": " - 提升产品质量"
            }
          }
        ]
      }
    }
  ]
}

示例 3：带列表的段落

{
  "blocks": [
    {
      "block_element_type": "paragraph",
      "paragraph": {
        "style": {
          "list": {
            "list_type": "bullet",
            "indent_level": 0
          }
        },
        "elements": [
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": "完成功能开发"
            }
          }
        ]
      }
    },
    {
      "block_element_type": "paragraph",
      "paragraph": {
        "style": {
          "list": {
            "list_type": "bullet",
            "indent_level": 0
          }
        },
        "elements": [
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": "进行用户测试"
            }
          }
        ]
      }
    }
  ]
}

示例 4：带用户提及和图片（仅进展记录支持）的段落

{
  "blocks": [
    {
      "block_element_type": "paragraph",
      "paragraph": {
        "elements": [
          {
            "paragraph_element_type": "mention",
            "mention": {
              "user_id": "ou_example_user"
            }
          },
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": " 请关注此进度并查看以下图片"
            }
          }
        ]
      }
    },
    {
      "block_element_type": "gallery",
      "gallery": {
        "images": [
          {
            "file_token": "img_example_token",
            "src": "https://example.com/image.png",
            "width": 800,
            "height": 600
          }
        ]
      }
    }
  ]
}

13 KiB Raw Blame History Unescape Escape

OKR ContentBlock 富文本格式

两种输入输出风格

ContentBlock 结构概览

类型定义

ContentBlock

ContentBlockElement

ContentParagraph

ContentParagraphElement

ContentTextRun

ContentTextStyle

ContentColor

ContentParagraphStyle

ContentList

ContentGallery

ContentImageItem

ContentDocsLink

ContentMention

ContentLink

SemiPlainContent 半纯文本格式

结构

类型定义

SemiPlainDoc

双向转换说明

使用示例

示例 0：--style simple 半纯文本格式

示例 1：简单文本段落（richtext 风格）

示例 2：带格式的文本段落

示例 3：带列表的段落

示例 4：带用户提及和图片（仅进展记录支持）的段落

13 KiB

Raw Blame History