larksuite-cli/skills/lark-okr/references/lark-okr-patch.md

okr +patch

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

部分更新 OKR 目标（Objective）或关键结果（Key Result）的 content、notes、score、deadline 字段。支持增量更新，只需提供要修改的字段。

推荐命令

# 更新目标的 content（默认 simple 风格，半纯文本格式）
lark-cli okr +patch \
  --level objective \
  --target-id 1234567890123456789 \
  --content '{"text":"更新后的目标内容","mention":["ou_123"]}'

# 更新关键结果的分数（0.0-1.0 的一位小数）
lark-cli okr +patch \
  --level key-result \
  --target-id 2345678901234567890 \
  --score 0.7

# 同时更新目标的多个字段（richtext 风格，完整 ContentBlock 格式）
lark-cli okr +patch \
  --level objective \
  --target-id 1234567890123456789 \
  --style richtext \
  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"更新后的目标内容"}}]}}]}' \
  --notes '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"更新后的备注"}}]}}]}' \
  --score 0.5 \
  --deadline 1735776000000

# 预览 API 调用而不实际执行
lark-cli okr +patch \
  --level objective \
  --target-id 1234567890123456789 \
  --content '{"text":"测试更新"}' \
  --dry-run

参数

参数	必填	默认值	说明
--level	是	—	更新级别：objective（目标） | key-result（关键结果）
--target-id	是	—	目标 ID 或关键结果 ID（int64 类型，正整数）
--style	否	simple	输入风格：simple（半纯文本 JSON，推荐） | richtext（完整 ContentBlock JSON）。请参考 ContentBlock 格式 了解两种格式。
--content	否¹	—	内容。根据 --style 指定格式。支持 @文件路径 从文件读取。
--notes	否¹	—	备注（仅 --level=objective 时支持）。根据 --style 指定格式。支持 @文件路径 从文件读取。
--score	否¹	—	分数值，0-1 之间，最多一位小数（如 0.5、1.0）。
--deadline	否¹	—	截止时间，毫秒级时间戳（如 1735776000000）。
--user-id-type	否	open_id	用户 ID 类型：open_id | union_id | user_id
--dry-run	否	—	预览 API 调用而不实际执行。
--format	否	json	输出格式。

¹ 至少需要提供 --content、--notes、--score、--deadline 中的一个字段。

工作流程

1. 使用 +cycle-list 和 +cycle-detail 获取目标或关键结果的 ID。
2. 确定要更新的字段：
   • content/notes：构造内容
     • 推荐：使用 simple 风格（默认），构造 SemiPlainContent JSON：{"text":"内容","mention":["ou_xxx"]}
     • 如需复杂格式：使用 richtext 风格，构造 ContentBlock JSON。请参考 ContentBlock 格式。
   • score：0-1 之间的数字，最多一位小数（如 0.3、0.7、1.0）
   • deadline：毫秒级时间戳
3. 执行 lark-cli okr +patch --level objective --target-id "..." --content "..."。
4. 报告结果：更新的级别、目标 ID、以及哪些字段被更新。

输出

返回 JSON：

{
  "level": "objective",
  "target_id": "1234567890123456789",
  "patched": {
    "content": true,
    "notes": true,
    "score": true,
    "deadline": true
  }
}

其中 patched 对象中的每个字段表示该字段是否被更新。

注意事项

• --notes 仅适用于目标：关键结果（key-result）不支持 notes 字段，使用时会报错。
• score 格式：必须在 0-1 之间，且最多一位小数（如 0.5 正确，0.51 错误）。
• 严格验证：输入格式严格根据 --style 值验证，不会自动检测。使用 ContentBlock JSON 时必须指定 --style richtext。
• simple 风格输入限制：simple 风格的输入不支持 docs 和 images 字段，如需包含文档或图片请使用 richtext 风格。

关于 1001001 错误

有时，当你涉及修改目标或关键结果的分数时，即使输入的参数完全正确， +patch 也会返回 1001001 错误(invalid parameters)。 这可能是因为在用户的租户设置中停用了目标/关键结果的分数功能，或禁用了目标分数的手动计算。此时可以先去掉 --score 参数再修改，并向用户确认是否启用了对应的功能。

参考

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