Lark Okr

okr (v2)

CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理

身份：OKR 操作默认使用 --as user（查看当前用户/上下级的 OKR 时）。也支持 --as bot 查看他人 OKR（需相应权限）。

Shortcuts（推荐优先使用）

Shortcut 是对常用操作的高级封装（lark-cli okr +<verb> [flags]）。有 Shortcut 的操作优先使用。

格式说明

• `OKR 业务实体` 获取 OKR 实体结构，定义和关系，帮助你更好的使用 OKR 功能
• `ContentBlock 富文本格式` — Objective/KeyResult/Progress 中 Content/Note 字段使用的富文本格式说明
• 强烈建议 在操作 OKR 前，阅读`OKR 业务实体`以了解基础概念

API Resources

alignments

• delete — 删除对齐关系
• get — 获取对齐关系

categories

• list — 批量获取分类

cycles

• list — 批量获取用户周期
• objectives_position — 更新用户周期下全部目标的位置
• 请求中必须携带对应周期下全部目标的 ID，否则会参数校验失败。以传入的目标ID顺序重新排列目标。
• objectives_weight — 更新用户周期下全部目标的权重
• 请求中必须同时修改对应周期下全部目标的权重，且所有权重值的和必须等于 1 ，否则会参数校验失败。例如周期下有 2 个目标时：
• 正确指令示例如下：

``` bash lark-cli okr cycles objectives_weight --params '{"cycle_id": "7000000000000000001"}' --data '{"objective_weights": [{"objective_id": "7000000000000000002", "weight": 0.7}, {"objective_id": "7000000000000000003", "weight": 0.3}]}' --as user

### cycle.objectives

- `create` — 创建目标
- `list` — 批量获取用户周期下的目标

### indicators

- `patch` — 更新量化指标

### key_results

- `delete` — 删除关键结果
- `get` — 获取关键结果
- `patch` — 更新关键结果

### key_result.indicators

- `list` — 获取关键结果的量化指标

### objectives

- `delete` — 删除目标
- `get` — 获取目标
- `key_results_position` — 更新全部关键结果的位置
    - 请求中必须携带对应周期下全部关键结果的 ID，否则会参数校验失败。以传入的关键结果ID顺序重新排列关键结果。
- `key_results_weight` — 更新全部关键结果的权重
    - 类似 `objectives_weight`, 请求中必须同时修改对应目标下全部关键结果的权重，且所有权重值的和必须等于 1 ，否则会参数校验失败。
- `patch` — 更新目标

### objective.alignments

- `create` — 创建对齐关系
    - 对齐不允许对齐自己的目标，且发起对齐的目标和被对齐的目标所在周期时间上必须有重叠，否则会参数校验失败。
- `list` — 批量获取目标下的对齐关系

### objective.indicators

- `list` — 获取目标的量化指标

### objective.key_results

- `create` — 创建关键结果
- `list` — 批量获取目标下的关键结果

## 不在本 skill 范围

- 待办任务管理 → 使用 [`lark-task`](../lark-task/SKILL.md)
- 日程安排 → 使用 [`lark-calendar`](../lark-calendar/SKILL.md)
- 绩效评估 → 使用 [`lark-openapi-explorer`](../lark-openapi-explorer/SKILL.md) 查找原生接口

OKR ContentBlock 富文本格式

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

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

根级别内容块。

ContentBlockElement

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

ContentParagraph

段落内容。

ContentParagraphElement

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

ContentTextRun

文本块。

ContentTextStyle

文本样式。

ContentColor

颜色。

ContentParagraphStyle

段落样式。

ContentList

列表样式。

ContentGallery

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

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

ContentImageItem

图片项。

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

ContentDocsLink

飞书文档链接。

ContentMention

提及。

ContentLink

链接。

使用示例

示例 1：简单文本段落

{
  "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
          }
        ]
      }
    }
  ]
}

okr +cycle-detail

前置条件： 先阅读 `lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

列出指定 OKR 周期下的所有目标及其关键结果。

推荐命令

# 列出指定周期的目标和关键结果
lark-cli okr +cycle-detail --cycle-id 1234567890123456789

# 预览 API 调用而不实际执行
lark-cli okr +cycle-detail --cycle-id 1234567890123456789 --dry-run

参数

工作流程

1. 使用 lark-cli okr +cycle-list 获取 OKR 周期 ID。 2. 执行 lark-cli okr +cycle-detail --cycle-id "123456"。 3. 报告结果：找到的目标数量、每个目标的 ID、分数、权重及其关键结果。

输出

返回 JSON：

{
  "cycle_id": "1234567890123456789",
  "objectives": [
    {
      "id": "2345678901234567890",
      "create_time": "2025-01-01 00:00:00",
      "update_time": "2025-01-15 12:00:00",
      "owner": {
        "owner_type": "user",
        "user_id": "ou_xxx"
      },
      "cycle_id": "1234567890123456789",
      "position": 0,
      "score": 0.75,
      "weight": 1.0,
      "deadline": "2025-06-30 23:59:59",
      "category_id": "cat_456",
      "content": "{...}",
      "notes": "{...}",
      "key_results": [
        {
          "id": "3456789012345678901",
          "create_time": "2025-01-01 00:00:00",
          "update_time": "2025-01-15 12:00:00",
          "owner": {
            "owner_type": "user",
            "user_id": "ou_xxx"
          },
          "objective_id": "2345678901234567890",
          "position": 0,
          "score": 0.8,
          "weight": 0.5,
          "deadline": "2025-06-30 23:59:59",
          "content": "{...}"
        }
      ]
    }
  ],
  "total": 1
}

其中，content 和 notes 字段是 JSON 字符串，为 OKR ContentBlock 富文本格式。请参考 lark-okr-contentblock.md 了解详细信息。

参考

• lark-okr -- 所有 OKR 命令(shortcut 和 API 接口)
• lark-shared -- 认证和全局参数

okr +cycle-list

前置条件： 先阅读 `lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

列出指定用户的 OKR 周期，支持可选的时间范围过滤。

推荐命令

# 列出用户的所有周期
lark-cli okr +cycle-list --user-id "ou_xxx"

# 使用特定的用户 ID 类型列出周期
lark-cli okr +cycle-list --user-id "xxx" --user-id-type user_id

# 列出时间范围内的周期（例如 2025-01 到 2025-06）
lark-cli okr +cycle-list --user-id "ou_xxx" --time-range "2025-01--2025-06"

# 预览 API 调用而不实际执行
lark-cli okr +cycle-list --user-id "ou_xxx" --dry-run

参数

工作流程

1. 获取目标用户的 open_id（或其他 ID 类型）。如果用户说"我的 OKR 周期"，先通过 lark-cli contact +get-user 获取当前用户的 ID。 2. 执行 lark-cli okr +cycle-list --user-id "ou_xxx"，可选择使用 --time-range。 3. 报告结果：找到的周期数量、每个周期的 ID、开始/结束时间和状态。

输出

返回 JSON：

{
  "cycles": [
    {
      "id": "1234567890123456789",
      "create_time": "2025-01-01 00:00:00",
      "update_time": "2025-01-01 00:00:00",
      "tenant_cycle_id": "789",
      "owner": {
        "owner_type": "user",
        "user_id": "ou_xxx"
      },
      "start_time": "2025-01-01 00:00:00",
      "end_time": "2025-06-30 00:00:00",
      "cycle_status": "normal",
      "score": 0
    }
  ],
  "total": 1
}

在这个周期信息中，这些字段值得关注：

• id 是这个周期的 ID，你通常需要用它在之后使用 okr +cycle-detail 获取 OKR 内容详情
• start_time end_time 是周期的起止时间，总是从某个月1日开始，直到此月或之后某月的最后一日结束。
• 在 OKR 系统中，我们只关注这个时间的年月部分，如 “2025-01-01开始，2025-06-30结束” 的周期被称作 “2025 年 1-6 月” 周期，而

“2025-01-01开始，2025-01-31结束” 的周期被称作 “2025 年 1 月”周期。

• 如果一个周期从某年1月1日开始，某年12月31日结束，则它是这一年的年度周期，如 “2025-01-01开始，2025-12-31结束” 的周期就是

“2025 年” 的年度周期

• cycle_status 为周期状态值，参见下文。

周期状态值

在 OKR 系统中，default/normal 状态下的周期当前正常生效，invalid 状态下的周期已失效但通常仍然可以填写，hidden 状态下的周期隐藏不可见。

参考

• lark-okr -- 所有 OKR 命令
• lark-shared -- 认证和全局参数

OKR 实体定义

本文档描述飞书 OKR API (/open-apis/okr/v2) 中涉及的核心实体及其字段定义。

实体关系概览

Cycle (用户周期)
  └── Objective (目标)
        ├── KeyResult (关键结果)
        │     └── Indicator (指标)
        │     └── list<Progress> (进展记录列表)
        └── Indicator (指标)
        └── list<Progress> (进展记录列表)

Alignment (对齐关系): Objective ↔ Objective
Category (分类): Objective 的分组标签

---

Owner (所有者)

所有者标识 OKR 实体的归属，目前仅支持用户类型。

---

Cycle (用户周期)

用户周期是 OKR 的顶层容器，代表一个时间段内的所有目标与关键结果。

常用术语

• 当前周期: 指周期的 start_time/end_time

指周期的 start_time / end_time 所在的时间段与当前时间重叠的周期（即： start_time <= 当前时间 且 end_time >= 当前时间）。 注意：时间重叠是判断当前周期的首要且必须的硬性条件，绝对不能仅仅根据 cycle_status == 1 去判断。 如果有多个符合时间重叠标准的周期，再在这些包含当前时间的周期中过滤，保留周期状态为 default (0) 或 normal (1) 的周期。如果仍然有多个，则选择其中较新的一个。当用户提及“上一个周期”，“下一个周期”一类的表述时，通常是以当前周期为准计算。

• 所有者: 绝大多数所有者都是用户，少部分租户启用了“团队OKR”功能，所有者可能是部门。用户身份下，只能编辑所有者为当前用户的

OKR。

周期状态 (cycle_status)

SHORTCUT： okr +cycle-list lark-okr-cycle-list.md 获取用户的周期列表，可按时间筛选

>

API： cycles.list

---

Objective (目标)

目标是 OKR 中的 "O"，属于某个用户周期，可包含多个关键结果。

SHORTCUT：

- okr +cycle-detail lark-okr-cycle-detail.md 获取某个用户周期下的全部目标和关键结果。时间相关的字段会以日期时间格式解析

>

API：

- cycle.objectives.list — 获取周期下的目标列表

- objectives.get — 获取单个目标

- cycle.objectives.create — 创建目标

- objectives.delete — 删除目标

- cycles.objectives_position — 更新周期下的目标排序

- cycles.objectives_weight — 更新周期下的目标权重

---

KeyResult (关键结果)

关键结果是 OKR 中的 "KR"，属于某个目标，描述目标的可衡量成果。

API：

- objective.key_results.list — 获取目标下的关键结果列表

- key_results.get — 获取单个关键结果

- key_results.patch — 更新关键结果

- key_results.delete — 删除关键结果

- objectives.key_results_position — 更新目标下的关键结果排序

- objectives.key_results_weight — 更新目标下的关键结果权重

---

Progress (进展记录)

进展记录挂载在目标（Objective）或关键结果（Key Result）上，用于记录阶段性进展内容与进度百分比。每条进展记录包含富文本内容和可选的进度率。

ProgressRate (进度率)

进度状态 (progress_rate.status)

创建进展记录时的参数

创建进展记录时，除了 content 外，还需要指定这条进展记录挂载的对应目标或关键结果：

SHORTCUT：

- okr +progress-get lark-okr-progress-get.md 获取单条进展记录

- okr +progress-create lark-okr-progress-create.md 为目标或关键结果创建进展记录

- okr +progress-update lark-okr-progress-update.md 更新进展记录内容

- okr +progress-delete lark-okr-progress-delete.md 删除进展记录

- okr +progress-list lark-okr-progress-list.md 获取目标/关键结果下的进展记录

---

Indicator (指标)

指标是目标和关键结果的量化度量，可独立挂载在 Objective 或 KeyResult 上。

修改指南

• 进度值: 一般指 current_value，单位未提及时通常用百分制计算。
• 当用户要求量化的更新 OKR 进度时，一般指的就是修改对应 OKR 的 Indicator。
• OKR 在未设置量化指标时，Indicator 的内容为空。如果用户未做特别说明，更新进度时可以默认将进度以百分制设置（初始值0，目标值100，unit

参见下文设置为 0/PERCENT）

指标状态 (indicator_status)

状态计算方式 (status_calculate_type)

当前值计算方式 (current_value_calculate_type)

IndicatorUnit (指标单位)

API：

- key_result.indicators.list — 获取关键结果的指标

- objective.indicators.list — 获取目标的指标

- indicators.patch — 更新指标

---

Alignment (对齐关系)

对齐关系描述两个目标之间的上下对齐。

API：

- alignments.get — 获取对齐关系

- alignments.delete — 删除对齐关系

- objective.alignments.list — 批量获取目标下的对齐关系

- objective.alignments.create — 创建对齐关系

---

Category (分类)

分类用于对目标进行分组标记（如"个人 OKR"、"团队 OKR"、"承诺 OKR"）等。具体的分类根据租户设置而定。

CategoryName (分类名称)

API： categories.list — 批量获取租户设置的分类列表

---

通用请求参数

以下参数在多数 OKR API 中通用：

---

权限 Scope 说明

所有 OKR API 均支持 user 和 tenant（应用）两种 access token 类型。

参考

• OKR ContentBlock 富文本格式 — content/notes 字段的富文本结构定义
• okr +cycle-list — 列出用户 OKR 周期
• okr +cycle-detail — 获取周期下的目标与关键结果
• okr +progress-get — 获取进展记录
• okr +progress-create — 创建进展记录
• okr +progress-update — 更新进展记录
• okr +progress-delete — 删除进展记录

okr +upload-image

前置条件： 先阅读 `lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

上传本地图片，用于 OKR 进展记录的富文本内容。

推荐命令

# 上传图片用于目标的进展记录
lark-cli okr +upload-image \
  --file ./progress_screenshot.png \
  --target-id 1234567890123456789 \
  --target-type objective

# 上传图片用于关键结果的进展记录
lark-cli okr +upload-image \
  --file ./chart.jpg \
  --target-id 9876543210987654321 \
  --target-type key_result

参数

工作流程

1. 使用 +cycle-list 和 +cycle-detail 获取目标或关键结果的 ID。 2. 准备本地图片文件，确保格式受支持。 3. 执行 lark-cli okr +upload-image --file ./image.png --target-id "..." --target-type objective。 4. 获取返回的 file_token，用于构建 ContentBlock 中的图片内容。

输出

返回 JSON：

{
  "file_token": "example-file-token",
  "url": "https://example.larksuite.com/download?file_token=example-file-token",
  "file_name": "screenshot.png",
  "size": 102400
}

其中：

• file_token — 用于在 ContentBlock 的 ContentGallery 中引用图片
• url — 图片的访问 URL
• file_name — 上传的文件名
• size — 文件大小（字节）

在进展记录中使用上传的图片

上传图片后，将返回的 file_token 用于构建 ContentBlock 的图库块：

{
  "blocks": [
    {
      "block_element_type": "paragraph",
      "paragraph": {
        "elements": [
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": "本周进展截图："
            }
          }
        ]
      }
    },
    {
      "block_element_type": "gallery",
      "gallery": {
        "images": [
          {
            "file_token": "example-file-token",
            "width": 800,
            "height": 600
          }
        ]
      }
    }
  ]
}

然后在创建或更新进展记录时使用此 ContentBlock：

lark-cli okr +progress-create \
  --content @content_with_image.json \
  --target-id 1234567890123456789 \
  --target-type objective

安全限制

• --file 参数必须使用相对路径（如 ./photo.png 或 images/photo.png），不支持绝对路径
• 图片文件必须存在于当前工作目录或其子目录中
• 不支持符号链接指向目录外的文件

参考

• lark-okr -- 所有 OKR 命令(shortcut 和 API 接口)
• ContentBlock 格式 -- 进展内容使用的富文本格式，包含图片块的使用说明
• lark-okr-progress-create -- 创建进展记录
• lark-okr-progress-update -- 更新进展记录
• lark-shared -- 认证和全局参数

okr +progress-create

前置条件： 先阅读 `lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

为目标（Objective）或关键结果（Key Result）创建一条 OKR 进展记录。

推荐命令

# 为目标创建进展记录
lark-cli okr +progress-create \
  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"本周完成了核心模块开发"}}]}}]}' \
  --target-id 1234567890123456789 \
  --target-type objective

# 为关键结果创建进展记录（带进度百分比和状态）
lark-cli okr +progress-create \
  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"指标已达到 80%"}}]}}]}' \
  --target-id 2345678901234567891 \
  --target-type key_result \
  --progress-percent 80 \
  --progress-status done

# 从文件读取 content（适用于较长的进展内容）
lark-cli okr +progress-create \
  --content @progress_content.json \
  --target-id 1234567890123456789 \
  --target-type objective

参数

工作流程

1. 使用 +cycle-list 和 +cycle-detail 获取目标或关键结果的 ID。 2. 构造 ContentBlock JSON 格式的进展内容。请参考 ContentBlock 格式。 3. 执行 lark-cli okr +progress-create --content "..." --target-id "..." --target-type objective。 4. 报告结果：新创建的进展记录 ID、修改时间等。

输出

返回 JSON：

{
  "progress": {
    "progress_id": "1234567890123456789",
    "modify_time": "2025-01-15 10:30:00",
    "content": "{...}",
    "progress_rate": {
      "percent": 80.0,
      "status": "done"
    }
  }
}

其中：

• content 字段是 JSON 字符串，为 OKR ContentBlock

富文本格式。请参考 lark-okr-contentblock.md 了解详细信息。

• progress_rate.status 返回可读字符串：normal（正常）、overdue（逾期）、done（已完成）。

参考

• lark-okr -- 所有 OKR 命令(shortcut 和 API 接口)
• ContentBlock 格式 -- 进展内容使用的富文本格式
• lark-shared -- 认证和全局参数

okr +progress-delete

前置条件： 先阅读 `lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

根据 ID 删除一条 OKR 进展记录。此操作为高风险操作，删除后不可恢复。

推荐命令

# 删除指定 ID 的进展记录
lark-cli okr +progress-delete --progress-id 1234567890123456789

# 预览 API 调用而不实际执行
lark-cli okr +progress-delete --progress-id 1234567890123456789 --dry-run

参数

工作流程

1. 使用 +progress-get 确认要删除的进展记录 ID 和内容。 2. 执行 lark-cli okr +progress-delete --progress-id "1234567890123456789"。 3. 报告结果：已删除的进展记录 ID。

注意：此操作不可恢复，建议在删除前先用 +progress-get 确认记录内容。

输出

返回 JSON：

{
  "deleted": true,
  "progress_id": "1234567890123456789"
}

参考

• lark-okr -- 所有 OKR 命令(shortcut 和 API 接口)
• lark-shared -- 认证和全局参数

okr +progress-get

前置条件： 先阅读 `lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

根据进展记录 ID 获取单条 OKR 进展记录。

推荐命令

# 获取指定 ID 的进展记录
lark-cli okr +progress-get --progress-id 1234567890123456789

# 使用特定的用户 ID 类型
lark-cli okr +progress-get --progress-id 1234567890123456789 --user-id-type open_id

# 预览 API 调用而不实际执行
lark-cli okr +progress-get --progress-id 1234567890123456789 --dry-run

参数

工作流程

1. 获取目标进展记录的 ID。可通过 +cycle-detail 获取目标和关键结果后，从中获取进展记录 ID。 2. 执行 lark-cli okr +progress-get --progress-id "1234567890123456789"。 3. 报告结果：进展记录的 ID、修改时间、进度百分比和内容。

输出

返回 JSON：

{
  "progress": {
    "progress_id": "1234567890123456789",
    "modify_time": "2025-01-15 10:30:00",
    "content": "{...}",
    "progress_rate": {
      "percent": 75.0,
      "status": "normal"
    }
  }
}

其中：

• content 字段是 JSON 字符串，为 OKR ContentBlock

富文本格式。请参考 lark-okr-contentblock.md 了解详细信息。

• progress_rate.status 返回可读字符串：normal（正常）、overdue（逾期）、done（已完成）。

参考

• lark-okr -- 所有 OKR 命令(shortcut 和 API 接口)
• lark-shared -- 认证和全局参数

okr +progress-list

前置条件： 先阅读 `lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

获取目标（Objective）或关键结果（Key Result）的所有进展记录列表。

推荐命令

# 获取目标的所有进展记录
lark-cli okr +progress-list \
  --target-id 1234567890123456789 \
  --target-type objective

# 获取关键结果的所有进展记录
lark-cli okr +progress-list \
  --target-id 9876543210987654321 \
  --target-type key_result

参数

工作流程

1. 使用 +cycle-list 和 +cycle-detail 获取目标或关键结果的 ID。 2. 执行 lark-cli okr +progress-list --target-id "..." --target-type objective。 3. 获取该目标或关键结果下的所有进展记录列表。

输出

返回 JSON：

{
  "progress": [
    {
      "progress_id": "1234567890123456789",
      "modify_time": "2025-01-15 10:30:00",
      "content": "{...}",
      "progress_rate": {
        "percent": 80.0,
        "status": "done"
      }
    }
  ],
  "total": 1
}

其中：

• progress — 进展记录数组
• content 字段是 JSON 字符串，为 OKR ContentBlock 富文本格式。请参考 lark-okr-contentblock.md 了解详细信息。
• progress_rate.status 返回可读字符串：normal（正常）、overdue（逾期）、done（已完成）。

与 +progress-get 的区别

+progress-list 返回的 progress_list 数组中每条记录的结构与 +progress-get 返回的 progress 结构相同。

参考

• lark-okr -- 所有 OKR 命令(shortcut 和 API 接口)
• ContentBlock 格式 -- 进展内容使用的富文本格式
• lark-okr-progress-get -- 根据 ID 获取单条进展记录
• lark-okr-progress-create -- 创建进展记录
• lark-shared -- 认证和全局参数

okr +progress-update

前置条件： 先阅读 `lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

更新指定 ID 的 OKR 进展记录内容。

推荐命令

# 更新进展记录内容
lark-cli okr +progress-update \
  --progress-id 1234567890123456789 \
  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"更新后的进展内容"}}]}}]}'

# 更新进展记录内容并同时更新进度
lark-cli okr +progress-update \
  --progress-id 1234567890123456789 \
  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"进度已更新至 90%"}}]}}]}' \
  --progress-percent 90 \
  --progress-status normal

# 从文件读取 content（适用于较长的进展内容）
lark-cli okr +progress-update \
  --progress-id 1234567890123456789 \
  --content @updated_progress.json

# 预览 API 调用而不实际执行
lark-cli okr +progress-update \
  --progress-id 1234567890123456789 \
  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"test"}}]}}]}' \
  --dry-run

参数

工作流程

1. 使用 +progress-get 获取要更新的进展记录的 ID 和当前内容。 2. 修改 ContentBlock JSON 格式的进展内容。请参考 ContentBlock 格式。 3. 执行 lark-cli okr +progress-update --progress-id "..." --content "..."。 4. 报告结果：更新后的进展记录 ID、修改时间、进度百分比等。

输出

返回 JSON：

{
  "progress": {
    "progress_id": "1234567890123456789",
    "modify_time": "2025-01-15 14:30:00",
    "content": "{...}",
    "progress_rate": {
      "percent": 90.0,
      "status": "normal"
    }
  }
}

其中：

• content 字段是 JSON 字符串，为 OKR ContentBlock

富文本格式。请参考 lark-okr-contentblock.md 了解详细信息。

• progress_rate.status 返回可读字符串：normal（正常）、overdue（逾期）、done（已完成）。

参考

• lark-okr -- 所有 OKR 命令(shortcut 和 API 接口)
• ContentBlock 格式 -- 进展内容使用的富文本格式
• lark-shared -- 认证和全局参数