105 lines
6.1 KiB
Markdown
105 lines
6.1 KiB
Markdown
# okr +patch
|
||
|
||
> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||
|
||
部分更新 OKR 目标（Objective）或关键结果（Key Result）的 content、notes、score、deadline 字段。支持增量更新，只需提供要修改的字段。
|
||
|
||
## 推荐命令
|
||
|
||
```bash
|
||
# 更新目标的 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 格式](lark-okr-contentblock.md) 了解两种格式。 |
|
||
| `--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 格式](lark-okr-contentblock.md)。
|
||
- **score**：0-1 之间的数字，最多一位小数（如 0.3、0.7、1.0）
|
||
- **deadline**：毫秒级时间戳
|
||
3. 执行 `lark-cli okr +patch --level objective --target-id "..." --content "..."`。
|
||
4. 报告结果：更新的级别、目标 ID、以及哪些字段被更新。
|
||
|
||
## 输出
|
||
|
||
返回 JSON：
|
||
|
||
```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](../SKILL.md) -- 所有 OKR 命令(shortcut 和 API 接口)
|
||
- [ContentBlock 格式](lark-okr-contentblock.md) -- content/notes 使用的富文本格式
|
||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|