lark-okr

okr (v2)

CRITICAL — Before starting, you MUST first use the Read tool to read ../lark-shared/SKILL.md, which contains authentication and permission handling

Identity: OKR operations use --as userby default (when viewing the current user's/superior's/subordinate's OKRs). Also supports --as bot to view others' OKRs (requires corresponding permissions).

Quick Decision

User Need	Operation Path	Reference Document
View own/others' OKRs	Get user ID -> `+cycle-list` -> `+cycle-detail` -> query metrics/progress records as needed	`cycle-list`, `cycle-detail`, `indicators`, `progress-list`
Write a set of OKRs for yourself	Prefer using `+batch-create` to create the Objective/KR skeleton	`batch-create`, `contentblock`
Add only one O or a single KR	Use `+create`	`create`
Edit content/notes/deadline	Use `+patch`	`patch`
Modify OKR score	Use `+patch --score`only when the user explicitly says "score", "rating", "scoring", or "score"; score is not progress/completion	`patch`
Adjust order or weight	Use `+reorder` / `+weight`	`reorder`, `weight`
Update numeric progress/completion	For percentages or numbers without units, use `+indicator-update`; to change units/target values, query the metric first, then use `indicators patch`	`indicator-update`, `indicators`
Write text progress	Use `+progress-create`; if there is both text and numbers, percentages or default units can use `--progress-percent` to update uniformly, and non-percentage units update the quantitative metric	`progress-create`, `progress-list`, `progress-update`
Align objectives	Handle directly according to the alignment relationship workflow	`alignments`
Query/create/modify/resolve OKR comments	To aggregate all comments under a cycle, use `+comment-detail`, to query a single O/KR/progress or to query only cycle-wide comments, use `+comment-list`；	`comment`, `comment-create`, `comment-solve-reopen`

Categories are handled only when the user explicitly requests categorization, or when creating an Objective returns invalid parameters and it is suspected that the tenant has mandatory categorization enabled: use lark-cli okr categories list --params '{"owner_type":"user","page_size":100}' --as user to check available categories, and select one with suitable semantics andenabled=true the category ID; categories can be adjusted later, so there is no need to stop and wait for user confirmation.

To get the current user, use contact +get-user; to look up others by name/email, use contact +search-user, and after getting open_id , then query the OKRs.

lark-cli contact +search-user --query "张三" --has-chatted --as user

Most commonly used OKR command examples:

# 查用户周期，再用周期 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

Do not mix up score and progress: when the user says "progress", "completion", or "currently at 75%", they are usually changing a quantitative metric or writing a progress record, not changing score. Only when explicitly asked to modify the OKR score/rating/scoring should you use +patch --score；score value is 0-1, with at most one decimal place.

Progress determination rules: when the user says "progress" or "completion", first determine whether it is a quantitative number. Numeric progress usually corresponds to a quantitative metric; non-quantifiable text corresponds to a progress record. If the metric unit needs to be changed, see lark-okr-indicators.md

Shortcuts (recommended to use first)

A Shortcut is a high-level wrapper for common operations (lark-cli okr +<verb> [flags]). Prefer to use operations that have a Shortcut.

Shortcut	Description
`+cycle-list`	Paginate through the OKR cycle list of a specific user; you can use `--time-range` to post-filter the current page
`+cycle-detail`	Get the contents of all objectives and key results in a specific OKR
`+create`	Create a single Objective (optionally with notes), or add a new KR to an existing Objective
`+progress-list`	Paginate through the progress record list of an objective or key result
`+progress-get`	Get a single OKR progress record by ID
`+progress-create`	Create a progress record for an objective or key result
`+progress-update`	Update the content of the progress record with the specified ID
`+progress-delete`	Delete the progress record with the specified ID (irrecoverable)
`+upload-image`	Upload images for use in rich-text content of OKR progress records
`+batch-create`	Batch create Objectives (optionally with notes) and KRs
`+reorder`	Adjust the order of an Objective or KR
`+weight`	Adjust the weight of an Objective or KR
`+indicator-update`	Update the current progress indicator of an Objective or KR. For more complex quantitative metric operations, see Quantitative Metric Management
`+patch`	Partially update an Objective or KR (content, notes, score, deadline)
`+comment-detail`	Get all comments of Cycle/Objective/KeyResult/Progress under a cycle
`+comment-list`	Paginate through the comments under a single OKR entity
`+comment-get`	Get the details of a single comment
`+comment-create`	Create a new comment or reply to an existing comment (only supports --as user)
`+comment-patch`	Modify comment content (only supports --as user)
`+comment-delete`	Permanently delete a single comment (only supports --as user)
`+comment-solve`	Resolve a comment or highlighted-text comment thread (only supports --as user)
`+comment-reopen`	Reopen a comment or highlighted-text comment thread (only supports --as user)

Create scenario selection

For single creation, prefer +create: suitable for creating one Objective, or adding one KR to an existing Objective.
For batch creation, use +batch-create: suitable for creating multiple Objectives at once, optionally with multiple KRs attached.
If you only need to modify the content, notes, score, or deadline of an existing Objective / KR, use +patch。

Format description

OKR 业务实体 Get the OKR entity structure, definitions, and relationships to help you better use the OKR features
ContentBlock 富文本格式 — Description of the rich-text format used by the Content/Note fields in Objective/KeyResult/Progress, and further description of the simplified semi-plain-text (SemiPlainContent) format.
Strongly recommended Before operating OKR, readOKR 业务实体to understand the basic concepts

API Resources

alignments

delete — Delete alignment relationship
get — Get alignment relationship

Operation guide: OKR Alignment Relationship Management includes the complete list/create/delete workflow

cycles

list — Batch get user cycles

cycle.objectives

list — Batch get objectives under a user cycle

indicators

patch — Update quantitative metrics

Operation guide: OKR Quantitative Metric Management includes the complete workflow for querying and patch-updating objective/KR metrics

key_results

delete — Delete key result
get — Get key result
patch — Update key result

key_result.indicators

list — Get the quantitative metrics of a key result

Operation guide: OKR Quantitative Metric Management

objectives

delete — Delete objective
get — Get objective
key_results_position — Update the positions of all key results
- The request must carry the IDs of all key results under the corresponding cycle; otherwise, parameter validation will fail. The key results will be rearranged according to the order of the passed-in key result IDs.
key_results_weight — Update the weights of all key results
- Similar to objectives_weight, the request must simultaneously modify the weights of all key results under the corresponding objective, and the sum of all weight values must equal 1; otherwise, parameter validation will fail.
patch — Update objective

objective.alignments

create — Create alignment relationship
- Alignment does not allow aligning an objective with itself, and the cycles of the initiating objective and the aligned objective must overlap in time; otherwise, parameter validation will fail.
list — Batch retrieve alignment relationships under objectives

objective.indicators

list — Retrieve quantitative metrics of an objective

objective.key_results

list — Batch retrieve key results under objectives

Not within the scope of this skill

To-do task management → Use lark-task
Scheduling → Use lark-calendar
Performance evaluation → Use lark-openapi-explorer to find the native interface