gabrielmoreira okr (v2)
CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md，其中包含认证、权限处理
身份：OKR 操作默认使用 --as user（查看当前用户/上下级的 OKR 时）。也支持 --as bot 查看他人 OKR（需相应权限）。
快速决策
| 用户需求 | 操作路径 | 参考文档 |
|---|---|---|
| 查看自己/他人的 OKR | 获取用户 ID -> +cycle-list -> +cycle-detail -> 按需查指标/进展记录 |
cycle-list, cycle-detail, indicators, progress-list |
| 为自己写一组 OKR | 优先用 +batch-create 创建 Objective/KR 骨架 |
batch-create, contentblock |
| 只新增一条 O 或单条 KR | 用 +create |
create |
| 编辑内容/备注/截止时间 | 用 +patch |
patch |
| 修改 OKR 分数 | 只有用户明确说“分数”“评分”“打分”“score”时才用 +patch --score；分数不是进度/完成度 |
patch |
| 调整顺序或权重 | 用 +reorder / +weight |
reorder, weight |
| 更新数字进度/完成度 | 百分比或不带单位数字用 +indicator-update；需要改单位/目标值时查指标后用 indicators patch |
indicator-update, indicators |
| 写文字进展 | 用 +progress-create；如果文本和数字都有，百分比或默认单位可使用 --progress-percent 统一改，非百分比单位更新量化指标 |
progress-create, progress-list, progress-update |
| 对齐目标 | 直接按对齐关系工作流处理 | alignments |
| 查询/创建/修改/解决 OKR 评论 | 获取周期下全部评论聚合用 +comment-detail，查询单个 O/KR/进展或仅查询周期全局评论用 +comment-list； |
comment, comment-create, comment-solve-reopen |
分类只在用户明确要求分类，或创建 Objective 返回 invalid parameters 且怀疑租户强制开启分类时处理：用 lark-cli okr categories list --params '{"owner_type":"user","page_size":100}' --as user 查可用分类，选择语义合适且enabled=true 的分类 ID；分类可后续调整，不必停下等待用户确认。
获取当前用户用 contact +get-user；按姓名/邮箱查他人用 contact +search-user，拿到 open_id 后再查 OKR。
lark-cli contact +search-user --query "张三" --has-chatted --as user
最常用 OKR 命令示例：
# 查用户周期，再用周期 ID 查详情
lark-cli okr +cycle-list --user-id "ou_xxx" --as user
lark-cli okr +cycle-detail --cycle-id 7000000000000000001 --as user
# 批量创建 Objective/KR
lark-cli okr +batch-create \
--cycle-id 7000000000000000001 \
--input '[{"text":"提升产品用户体验","notes":"关注核心流程和用户反馈","krs":[{"text":"核心流程满意度达到 4.8 分"}]}]' \
--as user
# 更新数字进度/完成度
lark-cli okr +indicator-update \
--level key-result \
--id 7000000000000000003 \
--value 75 \
--as user
分数和进度不要混用：用户说“进度”“完成度”“当前做到 75%”时，通常是在改量化指标或写进展记录，不是在改 score。只有明确要求修改 OKR 分数/评分/打分时，才使用 +patch --score；score 取值是 0-1，最多一位小数。
进度判断规则：用户说“进度”“完成度”时，先判断是否是量化数字。数字进度通常对应量化指标；不可量化文本对应进展记录。需要修改指标单位时看 lark-okr-indicators.md
Shortcuts（推荐优先使用）
Shortcut 是对常用操作的高级封装（lark-cli okr +<verb> [flags]）。有 Shortcut 的操作优先使用。
| Shortcut | 说明 |
|---|---|
+cycle-list |
分页获取特定用户的 OKR 周期列表，可以用 --time-range 对当前页后置筛选 |
+cycle-detail |
获取特定 OKR 中所有目标和关键结果的内容 |
+create |
创建单个 Objective（可带备注），或向已有 Objective 新增 KR |
+progress-list |
分页获取目标或关键结果的进展记录列表 |
+progress-get |
根据 ID 获取单条 OKR 进展记录 |
+progress-create |
为目标或关键结果创建进展记录 |
+progress-update |
更新指定 ID 的进展记录内容 |
+progress-delete |
删除指定 ID 的进展记录（不可恢复） |
+upload-image |
上传图片用于 OKR 进展记录的富文本内容 |
+batch-create |
批量创建 Objective（可带备注）和 KR |
+reorder |
调整 Objective 或 KR 的顺位 |
+weight |
调整 Objective 或 KR 的权重 |
+indicator-update |
更新 Objective 或 KR 的当前进度指标。更复杂的量化指标操作见 量化指标管理 |
+patch |
部分更新 Objective 或 KR（content、notes、score、deadline） |
+comment-detail |
获取周期下 Cycle/Objective/KeyResult/Progress 的全部评论 |
+comment-list |
分页获取单个 OKR 实体下的评论 |
+comment-get |
获取单条评论详情 |
+comment-create |
创建新评论或回复已有评论(仅支持 --as user) |
+comment-patch |
修改评论内容(仅支持 --as user) |
+comment-delete |
永久删除单条评论(仅支持 --as user) |
+comment-solve |
解决评论或划词评论串(仅支持 --as user) |
+comment-reopen |
重新打开评论或划词评论串(仅支持 --as user) |
创建场景选择
- 单条创建优先用
+create：适合创建一个 Objective，或给已有 Objective 增加一个 KR。 - 批量创建用
+batch-create：适合一次创建多个 Objective，并可同时附带多个 KR。 - 如果你只需要修改已有 Objective / KR 的内容、备注、分数或截止时间，使用
+patch。
格式说明
OKR 业务实体获取 OKR 实体结构，定义和关系，帮助你更好的使用 OKR 功能ContentBlock 富文本格式— Objective/KeyResult/Progress 中 Content/Note 字段使用的富文本格式说明，以及简化的半纯文本（SemiPlainContent）格式的进一步说明。- 强烈建议 在操作 OKR 前，阅读
OKR 业务实体以了解基础概念
API Resources
alignments
delete— 删除对齐关系get— 获取对齐关系
操作指南： OKR 对齐关系管理 包含 list/create/delete 完整工作流
categories
list— 批量获取分类
cycles
list— 批量获取用户周期
cycle.objectives
list— 批量获取用户周期下的目标
indicators
patch— 更新量化指标
操作指南： OKR 量化指标管理 包含目标/KR 指标查询和 patch 更新完整工作流
key_results
delete— 删除关键结果get— 获取关键结果patch— 更新关键结果
key_result.indicators
list— 获取关键结果的量化指标
操作指南： OKR 量化指标管理
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
list— 批量获取目标下的关键结果
不在本 skill 范围
- 待办任务管理 → 使用
lark-task - 日程安排 → 使用
lark-calendar - 绩效评估 → 使用
lark-openapi-explorer查找原生接口
Usage Notes
This supplement is maintained by the repository sync pipeline. It keeps the imported upstream skill usable inside this curated collection when the upstream source is intentionally concise.
Common Patterns
1. Confirm that the user's task matches the skill trigger.
2. Read the relevant project files or user-provided context before acting.
3. Choose the smallest reversible action that advances the task.
4. Run the verification command or manual check that proves the result.
5. Report the outcome, evidence, and any remaining risk.
Boundaries
- Prefer the upstream workflow for Lark Okr; this section only adds local quality guardrails.
- Do not invent project facts when required files, vaults, services, or tools are unavailable.
- Stop and ask for clarification when the next action could overwrite user work, expose private data, or change production state.
- Treat skill selection as routing, not ceremony: invoke only the narrowest applicable workflow and keep user or repository instructions authoritative.