@amaster.ai/pi-lark 0.1.2-beta.44 → 0.1.2-beta.45

package/skills/lark-event/SKILL.md

@@ -147,6 +147,7 @@ Lark-defined semantic tags (**not** JSON Schema's standard `format`). Common val
 
 | Topic      | Reference                                                                    | Coverage |
 |------------|------------------------------------------------------------------------------|---|
+| Application | [`references/lark-event-application.md`](references/lark-event-application.md) | Catalog of Application EventKeys, including `application.bot.menu_v6` for custom bot menu push events + flattened `event_key` / operator fields + jq recipe |
 | Approval   | [`references/lark-event-approval.md`](references/lark-event-approval.md)     | Catalog of 2 Approval EventKeys (`approval.instance.status_changed_v4`, `approval.task.status_changed_v4`) + optional/multi `subscription_type` pre-registration + user-auth subscription lifecycle + flat output field reference |
 | IM         | [`references/lark-event-im.md`](references/lark-event-im.md)                 | Catalog of 12 IM EventKeys + shape notes (flat vs V2 envelope) + `im.message.receive_v1` field gotchas (`sender_id` is open_id only; `.content` is plain text except for `interactive` cards) + common jq recipes (filter by chat_type / message_type / sender); for `card.action.trigger` see also [`../lark-im/references/lark-im-card-action-reply.md`](../lark-im/references/lark-im-card-action-reply.md) |
 | Task       | [`references/lark-event-task.md`](references/lark-event-task.md)             | Catalog of 1 Task EventKey (`task.task.update_user_access_v2`) + Native V2 envelope shape + task commit types + user/bot subscription notes |

package/skills/lark-event/references/lark-event-application.md

@@ -0,0 +1,38 @@
+# Lark Application Events
+
+This page covers Application-domain EventKeys supported by `lark-cli event`.
+
+## `application.bot.menu_v6`
+
+Triggered when a user clicks a custom bot menu item whose response action is configured as a push event.
+
+Listen as the bot identity:
+
+```bash
+lark-cli event consume application.bot.menu_v6 --as bot
+```
+
+Filter a specific menu event key:
+
+```bash
+lark-cli event consume application.bot.menu_v6 --as bot --jq 'select(.event_key == "start_eval")'
+```
+
+Output is flattened at the top level:
+
+| Field | Meaning |
+|---|---|
+| `type` | Event type, always `application.bot.menu_v6` |
+| `event_id` | Globally unique event ID from the event header |
+| `timestamp` | Event delivery time, preferring `header.create_time` |
+| `app_id` | App ID from the event header |
+| `tenant_key` | Tenant key from the event header |
+| `event_key` | Developer-defined menu event key, for example `start_eval` |
+| `menu_timestamp` | Menu click timestamp from the event body |
+| `operator_id` | Operator open_id alias |
+| `operator_open_id` | Operator open_id |
+| `operator_union_id` | Operator union_id |
+| `operator_user_id` | Operator user_id |
+| `operator_name` | Operator display name |
+
+This EventKey has no `--param`; use `--jq` to filter by `event_key` or operator fields.

package/skills/lark-im/SKILL.md

@@ -117,7 +117,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。
 | [`+threads-messages-list`](references/lark-im-threads-messages-list.md) | List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports sort/pagination |
 | [`+flag-create`](references/lark-im-flag-create.md) | Create a bookmark on a message; user-only; defaults to message-layer flag; use --flag-type feed for feed-layer flag (item_type auto-detected from chat mode) |
 | [`+flag-cancel`](references/lark-im-flag-cancel.md) | Cancel (remove) a bookmark. When no --flag-type is given, best-effort double-cancel: removes message layer and (when chat_type is determinable) feed layer |
-| [`+flag-list`](references/lark-im-flag-list.md) | List bookmarks; user-only; auto-enriches feed-type thread entries with message content; supports `--page-all` auto-pagination |
+| [`+flag-list`](references/lark-im-flag-list.md) | List bookmarks; user-only; auto-enriches feed-type thread entries with message content; `--page-all` is capped by `--page-limit` (default 20, max 1000), and `has_more=true` means the result is incomplete |
 | [`+feed-shortcut-create`](references/lark-im-feed-shortcut-create.md) | Add chats to the user's feed shortcuts; user-only; oc_xxx chat IDs only; batch up to 10 per call; `--head`/`--tail` controls insertion order; partial failures return an `ok:false` ledger |
 | [`+feed-shortcut-remove`](references/lark-im-feed-shortcut-remove.md) | Remove chats from the user's feed shortcuts; user-only; batch up to 10 per call; removing an absent shortcut is idempotent success; real per-item failures return an `ok:false` ledger |
 | [`+feed-shortcut-list`](references/lark-im-feed-shortcut-list.md) | List one page of the user's feed shortcuts; user-only; omit `--page-token` for the first page; default output enriches CHAT entries under `detail`; pass `--no-detail` to skip the extra lookup and `im:chat:read` scope |

package/skills/lark-im/references/lark-im-flag-list.md

@@ -6,9 +6,9 @@ This skill maps to shortcut: `lark-cli im +flag-list`. Underlying API: `GET /ope
 
 ## Sorting Rules (Important)
 
-The API returns data sorted by `update_time` in **ascending order**, meaning **oldest first, newest last**. When `has_more=true`, you cannot simply take the first page's items as the latest flags — you must paginate through all pages and take the last item on the last page as the newest.
+The API returns data sorted by `update_time` in **ascending order**, meaning **oldest first, newest last**. When `has_more=true`, continue pagination until `has_more=false`; only then is the last item in the merged result authoritative as the newest flag. If pagination stops while `has_more=true`, the last item is only the newest observed flag.
 
-Recommended: use `--page-all` for auto-pagination to get the complete list, then use `-q '.data.flag_items[-1]'` to get the latest item.
+`--page-all` enables automatic pagination but is still capped by `--page-limit`. The default cap is 20 pages; **20 is not the hard maximum**. Set `--page-limit` between 1 and 1000 when a larger scan is required. A response with `has_more=true` is incomplete, even when `flag_items` is empty; increase the limit or resume from the returned `page_token` before reporting an authoritative latest item or count.
 
 ## Commands
 
@@ -19,7 +19,7 @@ lark-cli im +flag-list --as user
 # Manual pagination with custom page size
 lark-cli im +flag-list --as user --page-size 30 --page-token <page_token>
 
-# Auto-paginate to get all flags (recommended)
+# Auto-paginate, capped at the default 20 pages
 lark-cli im +flag-list --as user --page-all
 
 # Auto-paginate + get the latest flag
@@ -31,8 +31,8 @@ lark-cli im +flag-list --as user --page-all -q '.data.flag_items[].item_id'
 # Disable auto-enrichment of message content (enabled by default)
 lark-cli im +flag-list --as user --page-all --enrich-feed-thread=false
 
-# Limit max pages (default 20, max 1000)
-lark-cli im +flag-list --as user --page-all --page-limit 10
+# Use the largest supported page limit for a broader scan
+lark-cli im +flag-list --as user --page-all --page-limit 1000
 ```
 
 ## Parameters
@@ -41,8 +41,8 @@ lark-cli im +flag-list --as user --page-all --page-limit 10
 |------|------|------|
 | `--page-size <n>` | 50 | Range 1-50 (server max is 50) |
 | `--page-token <token>` | empty | Pagination token from previous page; empty string must still be provided |
-| `--page-all` | false | Auto-paginate to fetch all pages and merge results |
-| `--page-limit <n>` | 20 | Max pages in `--page-all` mode (max 1000) |
+| `--page-all` | false | Auto-paginate and merge results, capped by `--page-limit` |
+| `--page-limit <n>` | 20 | Max pages in `--page-all` mode; configurable range 1-1000 (20 is only the default) |
 | `--enrich-feed-thread` | true | Auto-enrich feed-layer thread entries with message content (calls `im.messages.mget`) |
 | `--as user` | Required | Currently only supports user identity |
 
@@ -62,6 +62,7 @@ Note: `(thread, feed)` / `(msg_thread, feed)` entries are automatically enriched
 
 ## Limitations
 
+- **Auto-pagination is bounded**: `--page-all` fetches at most 20 pages by default. If the response still has `has_more=true`, the result is incomplete; increase `--page-limit` up to 1000 or resume with `page_token`. Never interpret `flag_items: []` as an authoritative zero while more pages remain. Historical `delete_flag_items` may occupy early pages and push active flags to later pages.
 - **delete_flag_items are not enriched**: Message content is only fetched for active flags (`flag_items`), not canceled flags (`delete_flag_items`). If you need message content for a canceled flag, query the message separately using `+messages-mget --message-ids <item_id>`.
 
 ## Response Example (Sanitized)

package/skills/lark-okr/SKILL.md

@@ -14,30 +14,85 @@ metadata:
 
 **身份**：OKR 操作默认使用 `--as user`（查看当前用户/上下级的 OKR 时）。也支持 `--as bot` 查看他人 OKR（需相应权限）。
 
+## 快速决策
+
+| 用户需求           | 操作路径                                                                             | 参考文档                                                                                                                                                                                                                 |
+|----------------|----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 查看自己/他人的 OKR   | 获取用户 ID -> `+cycle-list` -> `+cycle-detail` -> 按需查指标/进展记录                        | [`cycle-list`](references/lark-okr-cycle-list.md), [`cycle-detail`](references/lark-okr-cycle-detail.md), [`indicators`](references/lark-okr-indicators.md), [`progress-list`](references/lark-okr-progress-list.md) |
+| 为自己写一组 OKR     | 优先用 `+batch-create` 创建 Objective/KR 骨架                                           | [`batch-create`](references/lark-okr-batch-create.md), [`contentblock`](references/lark-okr-contentblock.md)                                                                                                         |
+| 只新增一条 O 或单条 KR | 用 `+create`                                                                      | [`create`](references/lark-okr-create.md)                                                                                                                                                                            |
+| 编辑内容/备注/截止时间   | 用 `+patch`                                                                       | [`patch`](references/lark-okr-patch.md)                                                                                                                                                                              |
+| 修改 OKR 分数      | 只有用户明确说“分数”“评分”“打分”“score”时才用 `+patch --score`；分数不是进度/完成度                        | [`patch`](references/lark-okr-patch.md)                                                                                                                                                                              |
+| 调整顺序或权重        | 用 `+reorder` / `+weight`                                                         | [`reorder`](references/lark-okr-reorder.md), [`weight`](references/lark-okr-weight.md)                                                                                                                               |
+| 更新数字进度/完成度     | 百分比或不带单位数字用 `+indicator-update`；需要改单位/目标值时查指标后用 `indicators patch`               | [`indicator-update`](references/lark-okr-indicator-update.md), [`indicators`](references/lark-okr-indicators.md)                                                                                                     |
+| 写文字进展          | 用 `+progress-create`；如果文本和数字都有，百分比或默认单位可使用 `--progress-percent` 统一改，非百分比单位更新量化指标 | [`progress-create`](references/lark-okr-progress-create.md), [`progress-list`](references/lark-okr-progress-list.md), [`progress-update`](references/lark-okr-progress-update.md)                                    |
+| 对齐目标           | 直接按对齐关系工作流处理                                                                     | [`alignments`](references/lark-okr-alignments.md)                                                                                                                                                                    |
+
+分类只在用户明确要求分类，或创建 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。
+
+```bash
+lark-cli contact +search-user --query "张三" --has-chatted --as user
+```
+
+最常用 OKR 命令示例：
+
+```bash
+# 查用户周期，再用周期 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`](references/lark-okr-patch.md)；`score` 取值是 0-1，最多一位小数。
+
+进度判断规则：用户说“进度”“完成度”时，先判断是否是量化数字。数字进度通常对应量化指标；不可量化文本对应进展记录。需要修改指标单位时看 [`lark-okr-indicators.md`](references/lark-okr-indicators.md)
+
 ## Shortcuts（推荐优先使用）
 
 Shortcut 是对常用操作的高级封装（`lark-cli okr +<verb> [flags]`）。有 Shortcut 的操作优先使用。
 
-| Shortcut                                                       | 说明                       |
-|----------------------------------------------------------------|--------------------------|
-| [`+cycle-list`](references/lark-okr-cycle-list.md)             | 获取特定用户的 OKR 周期列表，可以按时间筛选 |
-| [`+cycle-detail`](references/lark-okr-cycle-detail.md)         | 获取特定 OKR 中所有目标和关键结果的内容   |
-| [`+progress-list`](references/lark-okr-progress-list.md)       | 获取目标或关键结果的所有进展记录列表       |
-| [`+progress-get`](references/lark-okr-progress-get.md)         | 根据 ID 获取单条 OKR 进展记录      |
-| [`+progress-create`](references/lark-okr-progress-create.md)   | 为目标或关键结果创建进展记录           |
-| [`+progress-update`](references/lark-okr-progress-update.md)   | 更新指定 ID 的进展记录内容          |
-| [`+progress-delete`](references/lark-okr-progress-delete.md)   | 删除指定 ID 的进展记录（不可恢复）      |
-| [`+upload-image`](references/lark-okr-image-upload.md)         | 上传图片用于 OKR 进展记录的富文本内容    |
-| [`+batch-create`](references/lark-okr-batch-create.md)         | 批量创建 Objective 和 KR      |
-| [`+reorder`](references/lark-okr-reorder.md)                   | 调整 Objective 或 KR 的顺位    |
-| [`+weight`](references/lark-okr-weight.md)                     | 调整 Objective 或 KR 的权重    |
-| [`+indicator-update`](references/lark-okr-indicator-update.md) | 更新 Objective 或 KR 的指标当前值（简单场景推荐）。更复杂的指标操作见 [量化指标管理](references/lark-okr-indicators.md) |
-| [`+patch`](references/lark-okr-patch.md)                       | 部分更新 Objective 或 KR（content、notes、score、deadline） |
+| Shortcut                                                       | 说明                                                                                |
+|----------------------------------------------------------------|-----------------------------------------------------------------------------------|
+| [`+cycle-list`](references/lark-okr-cycle-list.md)             | 分页获取特定用户的 OKR 周期列表，可以用 `--time-range` 对当前页后置筛选                                    |
+| [`+cycle-detail`](references/lark-okr-cycle-detail.md)         | 获取特定 OKR 中所有目标和关键结果的内容                                                            |
+| [`+create`](references/lark-okr-create.md)                     | 创建单个 Objective（可带备注），或向已有 Objective 新增 KR                                      |
+| [`+progress-list`](references/lark-okr-progress-list.md)       | 分页获取目标或关键结果的进展记录列表                                                                |
+| [`+progress-get`](references/lark-okr-progress-get.md)         | 根据 ID 获取单条 OKR 进展记录                                                               |
+| [`+progress-create`](references/lark-okr-progress-create.md)   | 为目标或关键结果创建进展记录                                                                    |
+| [`+progress-update`](references/lark-okr-progress-update.md)   | 更新指定 ID 的进展记录内容                                                                   |
+| [`+progress-delete`](references/lark-okr-progress-delete.md)   | 删除指定 ID 的进展记录（不可恢复）                                                               |
+| [`+upload-image`](references/lark-okr-image-upload.md)         | 上传图片用于 OKR 进展记录的富文本内容                                                             |
+| [`+batch-create`](references/lark-okr-batch-create.md)         | 批量创建 Objective（可带备注）和 KR                                                        |
+| [`+reorder`](references/lark-okr-reorder.md)                   | 调整 Objective 或 KR 的顺位                                                             |
+| [`+weight`](references/lark-okr-weight.md)                     | 调整 Objective 或 KR 的权重                                                             |
+| [`+indicator-update`](references/lark-okr-indicator-update.md) | 更新 Objective 或 KR 的当前进度指标。更复杂的量化指标操作见 [量化指标管理](references/lark-okr-indicators.md) |
+| [`+patch`](references/lark-okr-patch.md)                       | 部分更新 Objective 或 KR（content、notes、score、deadline）                                 |
+
+### 创建场景选择
+
+- **单条创建优先用 [`+create`](references/lark-okr-create.md)**：适合创建一个 Objective，或给已有 Objective 增加一个 KR。
+- **批量创建用 [`+batch-create`](references/lark-okr-batch-create.md)**：适合一次创建多个 Objective，并可同时附带多个 KR。
+- 如果你只需要修改已有 Objective / KR 的内容、备注、分数或截止时间，使用 [`+patch`](references/lark-okr-patch.md)。
 
 ## 格式说明
 
 - [`OKR 业务实体`](references/lark-okr-entities.md) 获取 OKR 实体结构，定义和关系，帮助你更好的使用 OKR 功能
-- [`ContentBlock 富文本格式`](references/lark-okr-contentblock.md) — Objective/KeyResult/Progress 中 Content/Note 字段使用的富文本格式说明，以及简化的半纯文本（SemiPlainContent）格式的进一步说明。
+- [`ContentBlock 富文本格式`](references/lark-okr-contentblock.md) — Objective/KeyResult/Progress 中 Content/Note
+  字段使用的富文本格式说明，以及简化的半纯文本（SemiPlainContent）格式的进一步说明。
 - **强烈建议** 在操作 OKR 前，阅读[`OKR 业务实体`](references/lark-okr-entities.md)以了解基础概念
 
 ## API Resources
@@ -56,18 +111,9 @@ Shortcut 是对常用操作的高级封装（`lark-cli okr +<verb> [flags]`）
 ### cycles
 
 - `list` — 批量获取用户周期
-- `objectives_position` — 更新用户周期下全部目标的位置
-    - 请求中必须携带对应周期下全部目标的 ID，否则会参数校验失败。以传入的目标ID顺序重新排列目标。
-- `objectives_weight` — 更新用户周期下全部目标的权重
-    - 请求中必须同时修改对应周期下全部目标的权重，且所有权重值的和必须等于 1 ，否则会参数校验失败。例如周期下有 2 个目标时：
-    - 正确指令示例如下：
-      ``` bash
-      lark-cli okr cycles objectives_weight --params '{"cycle_id": "7000000000000000001"}' --data '{"objective_weights": [{"objective_id": "7000000000000000002", "weight": 0.7}, {"objective_id": "7000000000000000003", "weight": 0.3}]}' --as user
-      ```
 
 ### cycle.objectives
 
-- `create` — 创建目标
 - `list` — 批量获取用户周期下的目标
 
 ### indicators
@@ -110,7 +156,6 @@ Shortcut 是对常用操作的高级封装（`lark-cli okr +<verb> [flags]`）
 
 ### objective.key_results
 
-- `create` — 创建关键结果
 - `list` — 批量获取目标下的关键结果
 
 ## 不在本 skill 范围

package/skills/lark-okr/references/lark-okr-batch-create.md

@@ -10,23 +10,7 @@
 # 批量创建 2 个 Objective，各带 2 个 KR。
 lark-cli okr +batch-create \
   --cycle-id 7000000000000000001 \
-  --input '[
-    {
-      "text": "提升产品用户体验",
-      "mention": ["ou_xxxxxxxx"],
-      "krs": [
-        {"text": "页面加载速度提升 50%", "mention": ["ou_yyyyyyyy"]},
-        {"text": "用户满意度达到 4.8 分"}
-      ]
-    },
-    {
-      "text": "拓展新市场份额",
-      "krs": [
-        {"text": "新增 10 个城市覆盖"},
-        {"text": "市场份额提升至 25%"}
-      ]
-    }
-  ]' \
+  --input '[{"text":"提升产品用户体验","mention":["ou_xxxxxxxx"],"notes":"重点关注核心路径体验","krs":[{"text":"页面加载速度提升 50%","mention":["ou_yyyyyyyy"]},{"text":"用户满意度达到 4.8 分"}]},{"text":"拓展新市场份额","krs":[{"text":"新增 10 个城市覆盖"},{"text":"市场份额提升至 25%"}]}]' \
   --as user
 
 # 从文件读取输入
@@ -44,17 +28,22 @@ lark-cli okr +batch-create \
 ```
 - mention 是可选参数，不需要使用“@”提及其他用户时不传入。
   - 传入的 mention 参数会以 @对应用户的形式，添加在文本后。
+- Objective 的 notes / notes_mention 是可选参数，用于创建目标备注；KR 不支持备注。
+- Objective 的 category_id 是可选参数；也可以通过 `--category-id` 给所有未显式设置分类的 Objective 指定默认分类。
 
 ## 参数
 
 | 参数               | 必填 | 默认值       | 说明                                                         |
 |------------------|----|-----------|------------------------------------------------------------|
 | `--cycle-id`     | 是  | —         | OKR 周期 ID（int64 类型）                                        |
-| `--input`        | 是  | —         | JSON 数组格式的 Objective 列表。支持 `@文件路径` 从文件读取或 `@-` 从 stdin 读取。 |
+| `--input`        | 是  | —         | JSON 数组格式的 Objective 列表。支持 `@文件路径` 从文件读取或 `-` 从 stdin 读取。 |
+| `--category-id`  | 否  | —         | 默认 Objective 分类 ID。仅用于 input 中未设置 `category_id` 的 Objective。通常不需要传入，见下方“分类提示”。 |
 | `--user-id-type` | 否  | `open_id` | mention 中使用的用户 ID 类型：`open_id` \| `union_id` \| `user_id`  |
 | `--dry-run`      | 否  | —         | 预览 API 调用而不实际执行                                            |
 | `--format`       | 否  | `json`    | 输出格式                                                       |
 
+> **分类提示**：当用户明确要求设置 Objective 分类，或创建 Objective 返回 `invalid parameters` 且怀疑租户强制开启分类时，可以配置 category-id 字段进行创建。先运行 `lark-cli okr categories list --as user` 查看可用分类，然后选择一个语义合适且 `enabled=true` 的分类 ID 作为 `category-id`。分类创建后可以再调整；不必因为分类选择停下等待用户确认。
+
 ## 输入格式
 
 ```json
@@ -62,6 +51,9 @@ lark-cli okr +batch-create \
   {
     "text": "Objective 内容",
     "mention": ["ou_xxxxxxxx", "ou_yyyyyyyy"],
+    "notes": "Objective 备注",
+    "notes_mention": ["ou_xxxxxxxx"],
+    "category_id": "7249339036661170180",
     "krs": [
       {
         "text": "KR 内容",
@@ -72,6 +64,15 @@ lark-cli okr +batch-create \
 ]
 ```
 
+字段说明：
+
+- `text`：Objective 或 KR 内容，必填。
+- `mention`：追加到内容后的用户 mention，可选。
+- `notes`：Objective 备注文本，可选，仅 Objective 支持。
+- `notes_mention`：追加到 Objective 备注后的用户 mention，可选，仅在 `notes` 存在时有意义。
+- `category_id`：Objective 分类 ID，可选；会覆盖命令级 `--category-id`。
+- `krs`：当前 Objective 下要创建的 KR 列表，可选。
+
 ## 工作流程
 
 1. 使用 `+cycle-list` 获取可用的 OKR 周期 ID

package/skills/lark-okr/references/lark-okr-create.md

@@ -0,0 +1,173 @@
+# okr +create
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+创建单个 OKR 目标（Objective）或关键结果（Key Result）。这是单条写入场景的首选 shortcut；如果需要一次创建多个 Objective 及其 KR，可使用 [`+batch-create`](lark-okr-batch-create.md)。
+
+## 推荐命令
+
+```bash
+# 在指定周期下创建一个 Objective（默认 simple 风格）
+lark-cli okr +create \
+  --level objective \
+  --cycle-id 7000000000000000001 \
+  --content '{"text":"提升北极星指标","mention":["ou_xxxxxxxx"]}' \
+  --notes '{"text":"重点关注活跃用户和转化漏斗"}' \
+  --as user
+
+# 在已有 Objective 下创建一个 KR
+lark-cli okr +create \
+  --level key-result \
+  --objective-id 7000000000000000002 \
+  --content '{"text":"季度留存率提升到 45%"}' \
+  --as user
+
+# 使用 richtext 风格创建 Objective（完整 ContentBlock JSON）
+lark-cli okr +create \
+  --level objective \
+  --cycle-id 7000000000000000001 \
+  --style richtext \
+  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"建立跨部门协作机制"}}]}}]}' \
+  --as user
+
+# 预览 API 调用而不实际执行
+lark-cli okr +create \
+  --level key-result \
+  --objective-id 7000000000000000002 \
+  --content '{"text":"完成 3 次核心流程优化"}' \
+  --dry-run \
+  --as user
+```
+
+## 参数
+
+| 参数               | 必填 | 默认值       | 说明                                                                                                                 |
+|------------------|----|-----------|--------------------------------------------------------------------------------------------------------------------|
+| `--level`        | 是  | —         | 创建层级：`objective`（创建目标）\| `key-result`（在已有目标下创建 KR）                                                                 |
+| `--cycle-id`     | 条件 | —         | OKR 周期 ID（int64 类型）。当 `--level=objective` 时**必填**。                                                                 |
+| `--objective-id` | 条件 | —         | Objective ID（int64 类型）。当 `--level=key-result` 时**必填**。                                                             |
+| `--style`        | 否  | `simple`  | 内容输入风格：`simple`（半纯文本 JSON，推荐） \| `richtext`（完整 ContentBlock JSON）。请参考 [ContentBlock 格式](lark-okr-contentblock.md)。 |
+| `--content`      | 是  | —         | 内容。根据 `--style` 指定格式。支持 `@文件路径` 从文件读取或 `-` 从 stdin 读取。                                                             |
+| `--notes`        | 否  | —         | Objective 备注，仅 `--level=objective` 支持。根据 `--style` 指定格式，支持 `@文件路径` 或 `-` 从 stdin 读取。                               |
+| `--category-id`  | 否  | —         | Objective 分类 ID，仅 `--level=objective` 支持。通常不需要传入，见下方“分类提示”。                                                        |
+| `--user-id-type` | 否  | `open_id` | 用户 ID 类型：`open_id` \| `union_id` \| `user_id`。影响 mention 中用户 ID 的解释方式。                                             |
+| `--dry-run`      | 否  | —         | 预览 API 调用而不实际执行。                                                                                                   |
+| `--format`       | 否  | `json`    | 输出格式。                                                                                                              |
+
+> **分类提示**：当用户明确要求设置 Objective 分类，或创建 Objective 返回 `invalid parameters` 且怀疑租户强制开启分类时，可以配置 --category-id 参数进行创建。先运行 `lark-cli okr categories list --as user` 查看可用分类，然后选择一个语义合适且 `enabled=true` 的分类 ID 作为 `--category-id`。分类创建后可以再调整；不必因为分类选择停下等待用户确认。
+
+## 输入格式
+
+### `--style simple`（默认）
+
+推荐大多数创建场景使用 `simple` 风格。`--content` 和 `--notes` 都使用 `SemiPlainContent` JSON：
+
+```json
+{
+  "text": "提升北极星指标",
+  "mention": ["ou_xxxxxxxx"]
+}
+```
+
+规则：
+
+- `text` 必填，且不能为空白字符串
+- `mention` 可选；如果传入，数组中的每个用户 ID 都不能为空字符串
+- `--notes` 仅适用于 Objective；创建 KR 时传 `--notes` 会报错
+- 同一条命令只有一个 flag 可以使用 `-` 读取 stdin；如果 `--content -`，`--notes` 请使用内联 JSON 或 `@文件路径`
+
+### `--style richtext`
+
+当你需要精确控制段落结构、插入文档链接，或使用完整富文本块结构时，使用 `richtext` 风格：
+
+```json
+{
+  "blocks": [
+    {
+      "block_element_type": "paragraph",
+      "paragraph": {
+        "elements": [
+          {
+            "paragraph_element_type": "textRun",
+            "text_run": {
+              "text": "建立跨部门协作机制"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+规则：
+
+- `blocks` 至少需要有一个非空段落或图片块
+- 不能传空 `blocks`，也不能传只有空段落元素的内容
+- 更多结构说明见 [ContentBlock 富文本格式](lark-okr-contentblock.md)
+
+## 工作流程
+
+1. 如果要创建 Objective，先使用 `+cycle-list` 获取目标周期的 `cycle_id`。
+2. 如果要给已有 Objective 新增 KR，先通过 `+cycle-detail` 或其他 OKR 查询命令拿到 `objective_id`。
+3. 选择输入风格：
+   - **推荐**：`simple`，适合普通文本和 mention。
+   - 需要复杂富文本时：`richtext`。
+4. 执行 `lark-cli okr +create ...`。
+5. 报告结果：
+   - 创建 Objective 时返回新的 `objective_id`
+   - 创建 KR 时返回新的 `key_result_id`，并附带父 `objective_id`
+
+## Dry-run 对应接口
+
+- `--level=objective`：
+  - `POST /open-apis/okr/v2/cycles/:cycle_id/objectives`
+- `--level=key-result`：
+  - `POST /open-apis/okr/v2/objectives/:objective_id/key_results`
+
+## 输出
+
+### 创建 Objective 成功
+
+```json
+{
+  "level": "objective",
+  "objective_id": "7000000000000000002"
+}
+```
+
+### 创建 KR 成功
+
+```json
+{
+  "level": "key-result",
+  "objective_id": "7000000000000000002",
+  "key_result_id": "7000000000000000003"
+}
+```
+
+## 常见错误与处理
+
+- `--level=objective` 但未传 `--cycle-id`
+  - 补充有效的周期 ID
+- `--level=key-result` 但未传 `--objective-id`
+  - 补充已有 Objective 的 ID
+- `--content` 为空、不是合法 JSON，或内容结构为空
+  - 按 `--style` 对应格式修正输入
+- 在 `simple` 风格中传了 `docs` 或 `images`
+  - 改用 `--style richtext`，或移除这些字段
+
+## 何时用 +create，何时用 +batch-create
+
+| 命令 | 适用场景 |
+|------|----------|
+| `+create` | 创建单个 Objective，或向已有 Objective 新增单个 KR |
+| `+batch-create` | 一次创建多个 Objective，并可同时为每个 Objective 创建多个 KR |
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令
+- [OKR 业务实体](lark-okr-entities.md) -- Objective、KR、周期等基础概念
+- [ContentBlock 格式](lark-okr-contentblock.md) -- content/notes 字段的另一种输入风格，支持完整富文本格式
+- [okr +batch-create](lark-okr-batch-create.md) -- 批量创建多个 Objective / KR
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/skills/lark-okr/references/lark-okr-cycle-list.md

@@ -2,18 +2,21 @@
 
 > **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-列出指定用户的 OKR 周期，支持可选的时间范围过滤。
+列出指定用户的一页 OKR 周期，支持外部控制翻页和可选的时间范围后置过滤。
 
 ## 推荐命令
 
 ```bash
-# 列出用户的所有周期
+# 获取用户周期第一页 (默认页大小为 100 按时间倒序排列，一般不用翻页)
 lark-cli okr +cycle-list --user-id "ou_xxx"
 
+# 获取下一页
+lark-cli okr +cycle-list --user-id "ou_xxx" --page-size 100 --page-token "7000000000000000002"
+
 # 使用特定的用户 ID 类型列出周期
 lark-cli okr +cycle-list --user-id "xxx" --user-id-type user_id
 
-# 列出时间范围内的周期（例如 2025-01 到 2025-06）
+# 列出当前返回页中与时间范围重叠的周期（例如 2025-01 到 2025-06）
 lark-cli okr +cycle-list --user-id "ou_xxx" --time-range "2025-01--2025-06"
 
 # 预览 API 调用而不实际执行
@@ -26,7 +29,9 @@ lark-cli okr +cycle-list --user-id "ou_xxx" --dry-run
 |------------------|----|-----------|------------------------------------------------------------------|
 | `--user-id`      | 是  | —         | OKR 所有者的用户 ID                                                    |
 | `--user-id-type` | 否  | `open_id` | 用户 ID 类型：`open_id` \| `union_id` \| `user_id`                    |
-| `--time-range`   | 否  | —         | 按时间范围过滤周期。格式：`YYYY-MM--YYYY-MM`（例如 `2025-01--2025-06`）。留空获取所有周期。 |
+| `--time-range`   | 否  | —         | 后置筛选条件：先按 `--page-size`/`--page-token` 请求一页，再在本地保留与该时间范围重叠的周期。格式：`YYYY-MM--YYYY-MM`（例如 `2025-01--2025-06`）。 |
+| `--page-size`    | 否  | `100`     | 每页数量，范围 `1-100`。                                               |
+| `--page-token`   | 否  | `""`      | 上一次响应中的 `page_token`，留空表示第一页。                            |
 | `--dry-run`      | 否  | —         | 预览 API 调用而不实际执行。                                                 |
 | `--format`       | 否  | `json`    | 输出格式。                                                            |
 
@@ -34,8 +39,11 @@ lark-cli okr +cycle-list --user-id "ou_xxx" --dry-run
 
 1. 获取目标用户的 `open_id`（或其他 ID 类型）。如果用户说"我的 OKR 周期"，先通过 `lark-cli contact +get-user` 获取当前用户的
    ID。
-2. 执行 `lark-cli okr +cycle-list --user-id "ou_xxx"`，可选择使用 `--time-range`。
-3. 报告结果：找到的周期数量、每个周期的 ID、开始/结束时间和状态。
+2. 执行 `lark-cli okr +cycle-list --user-id "ou_xxx" --page-size 100`，可选择使用 `--time-range`。
+3. 如果响应中 `has_more=true`，继续用返回的 `page_token` 调用下一页。
+4. 报告结果：每个周期的 ID、开始/结束时间和状态。
+
+`--time-range` 是后置筛选条件，不会改变服务端分页窗口。也就是说，命令会先获取指定页，再过滤该页中的周期；如果需要完整时间范围结果，需要按 `has_more`/`page_token` 逐页拉取并合并。
 
 ## 输出
 
@@ -51,7 +59,8 @@ lark-cli okr +cycle-list --user-id "ou_xxx" --dry-run
       "cycle_status": "normal"
     }
   ],
-  "total": 1,
+  "has_more": true,
+  "page_token": "7000000000000000002",
   "current_active_cycles": [
     {
       "id": "1234567890123456789",
@@ -66,6 +75,7 @@ lark-cli okr +cycle-list --user-id "ou_xxx" --dry-run
 在这个周期信息中，这些字段值得关注：
 
 - `id` 是这个周期的 ID，你通常需要用它在之后使用 `okr +cycle-detail` 获取 OKR 内容详情
+- `has_more` 和 `page_token` 用于外部控制翻页；`has_more=true` 时，用 `--page-token` 原样传入本次返回的 `page_token` 获取下一页。
 - `start_time` `end_time` 是周期的起止时间，总是从某个月1日开始，直到此月或之后某月的最后一日结束。
     - 在 OKR 系统中，我们只关注这个时间的年月部分，如 "2025-01-01开始，2025-06-30结束" 的周期被称作 "2025 年 1-6 月" 周期，而
       "2025-01-01开始，2025-01-31结束" 的周期被称作 "2025 年 1 月"周期。

package/skills/lark-okr/references/lark-okr-entities.md

@@ -50,6 +50,7 @@ Category (分类): Objective 的分组标签
 
 - **当前周期**: 指周期的 start_time/end_time
   指周期的 start_time / end_time 所在的时间段与当前时间重叠的周期（即： start_time <= 当前时间 且 end_time >= 当前时间）。 注意：时间重叠是判断当前周期的首要且必须的硬性条件，绝对不能仅仅根据 cycle_status == 1 去判断。 如果有多个符合时间重叠标准的周期，再在这些包含当前时间的周期中过滤，保留周期状态为 default (0) 或 normal (1) 的周期。如果仍然有多个，则选择其中较新的一个。当用户提及“上一个周期”，“下一个周期”一类的表述时，通常是以当前周期为准计算。
+  - 如果用户没有提及，那么当前周期一般不考虑年度周期（起止时间从 01-01 至 12-31 的周期）
 - **所有者**: 绝大多数所有者都是用户，少部分租户启用了“团队OKR”功能，所有者可能是部门。用户身份下，只能编辑所有者为当前用户的
   OKR。
 

package/skills/lark-okr/references/lark-okr-indicator-update.md

@@ -40,7 +40,9 @@ lark-cli okr +indicator-update \
 
 1. 使用 `+cycle-list` 和 `+cycle-detail` 获取目标 ID 或 KR ID。
 2. 如需查看当前指标值，使用 `objective.indicators list` 或 `key_result.indicators list` 查询。
-3. 执行 `+indicator-update` 指定层级、ID 和新值。
+  若当前量化指标没有 start_value/current_value/target_value/unit 这些字段，代表当前量化指标为未设置的默认初始进度。
+3. 执行 `+indicator-update` 指定层级、ID 和新值。 
+  使用 +indicator-update 为默认初始进度设置当前值会将该量化指标配置为默认的百分比模式。若用户不希望将指标设置为百分比，请使用原生 API 详细设置，参考 [lark-okr-indicators.md](lark-okr-indicators.md)
 4. 命令自动查询指标 ID 并更新当前值。
 
 ## 输出