97 lines
4.0 KiB
Markdown
97 lines
4.0 KiB
Markdown
# okr +weight
|
||
|
||
> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||
|
||
调整 OKR 周期下目标（Objective）或目标下关键结果（Key Result）的权重。支持部分指定权重，未指定的按原权重比例自动分配。
|
||
|
||
## 推荐命令
|
||
|
||
```bash
|
||
# 调整 Objective 权重（部分指定，剩余自动分配）
|
||
lark-cli okr +weight \
|
||
--cycle-id 7000000000000000001 \
|
||
--level objective \
|
||
--weights '[
|
||
{"id": "7000000000000000002", "weight": 0.6},
|
||
{"id": "7000000000000000003", "weight": 0.3}
|
||
]' \
|
||
--as user
|
||
|
||
# 调整 KR 权重（全部指定，和为 1）
|
||
lark-cli okr +weight \
|
||
--cycle-id 7000000000000000001 \
|
||
--level key-result \
|
||
--objective-id 7000000000000000002 \
|
||
--weights '[
|
||
{"id": "7000000000000000004", "weight": 0.6},
|
||
{"id": "7000000000000000005", "weight": 0.4}
|
||
]' \
|
||
--as user
|
||
|
||
# 从文件读取 weights
|
||
lark-cli okr +weight \
|
||
--cycle-id 7000000000000000001 \
|
||
--level objective \
|
||
--weights @weights.json \
|
||
--as user
|
||
```
|
||
|
||
参数限制: 请求中的权重保留三位小数，分配的所有权重和不能大于 1 (小于等于 1 是允许的)。
|
||
|
||
### 权重归一化
|
||
|
||
- 在 OKR 中，一个周期下所有 Objective 和 一个 Objective 下所有 Key Result 的权重和固定为 1.
|
||
- 在使用 +weight shortcut 分配 OKR 权重时，已分配的总权重不得超过 1。
|
||
- 若已分配的权重 < 1，剩余的权重会按照原始权重的比例均分到未指定的 Objective/Key Result 下。
|
||
- 若所有 Objective/Key Result 均分配了权重但和 < 1，剩余的权重会计算在最后一个 Objective/Key Result 下。
|
||
|
||
|
||
|
||
## 参数
|
||
|
||
| 参数 | 必填 | 默认值 | 说明 |
|
||
|------------------|----|--------|---------------------------------------------------------------------|
|
||
| `--level` | 是 | — | 调整层级：`objective`（调整周期下目标权重）\| `key-result`（调整目标下 KR 权重） |
|
||
| `--cycle-id` | 是 | — | OKR 周期 ID（int64 类型） |
|
||
| `--objective-id` | 条件 | — | 目标 ID。当 `--level=key-result` 时**必填**，用于定位父目标。 |
|
||
| `--weights` | 是 | — | JSON 数组格式的权重分配。支持 `@文件路径` 或 `@-` 从 stdin 读取。权重保留三位小数，分配的所有权重和不能大于 1 |
|
||
| `--dry-run` | 否 | — | 预览 API 调用而不实际执行 |
|
||
| `--format` | 否 | `json` | 输出格式 |
|
||
|
||
## 工作流程
|
||
|
||
1. 使用 `+cycle-list` 和 `+cycle-detail` 获取周期 ID、目标 ID、KR ID 和当前权重。
|
||
2. 构造 `--weights` JSON 数组，指定要调整的 ID 和权重，执行命令。
|
||
3. 返回调整后的完整权重列表。
|
||
|
||
## 输出
|
||
|
||
成功返回 JSON：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"level": "objective",
|
||
"cycle_id": "7000000000000000001",
|
||
"total": 3,
|
||
"weights": [
|
||
{"id": "7000000000000000002", "weight": 0.6},
|
||
{"id": "7000000000000000003", "weight": 0.3},
|
||
{"id": "7000000000000000004", "weight": 0.1}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## 关于 1001001 错误
|
||
|
||
有时，即使输入的参数完全正确， +weight 也会返回 1001001 错误。这是因为你的租户设置中，不一定开启了目标或关键结果的设置权重功能。
|
||
若你确认输入的参数无误（cycle-id/objective-id 正确，weights 中的 id 均是同一个周期下的目标或同一个目标下的关键结果，weights 中的权重和 <1）,
|
||
不必进一步尝试，你需要向用户确认 OKR 应用目前是否开启了目标或关键结果的设置权重功能。
|
||
|
||
## 参考
|
||
|
||
- [OKR 业务实体](lark-okr-entities.md) -- OKR 实体结构定义
|
||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|