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

package/skills/lark-event/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-event
 version: 1.0.0
-description: "Lark/Feishu real-time event listening / subscribing / consuming: stream events as NDJSON via `lark-cli event consume <EventKey>` (covers IM messages/reactions/chat changes, Task updates, VC meeting started/joined/ended, Minutes generated, Whiteboard updated, etc.). Use for Lark bots, real-time message processing, long-running subscribers, streaming webhook/push handlers. Supports `--max-events` / `--timeout` bounded runs and a stderr ready-marker contract — designed for AI agents running as subprocesses."
+description: "Lark/Feishu real-time event listening / subscribing / consuming: stream events as NDJSON via `lark-cli event consume <EventKey>` (covers IM messages/reactions/chat changes, Approval status changes, Task updates, VC meeting started/joined/ended, Minutes generated, Whiteboard updated, etc.). Use for Lark bots, real-time message processing, long-running subscribers, streaming webhook/push handlers. Supports `--max-events` / `--timeout` bounded runs and a stderr ready-marker contract — designed for AI agents running as subprocesses."
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -147,6 +147,8 @@ 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 |
 | VC         | [`references/lark-event-vc.md`](references/lark-event-vc.md)                 | Catalog of 4 VC EventKeys (`vc.meeting.participant_meeting_started_v1`, `vc.meeting.participant_meeting_joined_v1`, `vc.meeting.participant_meeting_ended_v1`, `vc.note.generated_v1`) + field reference + source type semantics (meeting only) |

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-event/references/lark-event-approval.md

@@ -0,0 +1,170 @@
+# Approval Events
+
+> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
+
+## Key catalog (2)
+
+| EventKey | Purpose |
+|---|---|
+| `approval.instance.status_changed_v4` | An approval instance status changed |
+| `approval.task.status_changed_v4` | An approval task status changed |
+
+Both keys use a **Custom schema**. The raw Lark schema 2.0 envelope is flattened: event metadata is exposed as `type`, `event_id`, and `timestamp`, while approval business fields are exposed at the top level.
+
+Both keys carry a **PreConsume hook** that subscribes the current authorized user through the Approval subscription APIs before listening. The consumer intentionally does **not** unsubscribe on exit; the server-side Approval subscription relation remains until it is canceled outside `event consume`. These keys require `--as user`.
+
+## Listener and subscription selection
+
+At the raw CLI level, each `event consume` process accepts exactly one EventKey. `approval.instance.status_changed_v4` and `approval.task.status_changed_v4` have different output shapes, so listening to both still means two processes.
+
+For Approval only, `subscription_type` is an optional setup param used by PreConsume to register server-side Approval subscription relations before the local listener starts. It is **not** an output field, a local event filter, or a local subscription identity. The pushed event does not say which subscription relation caused delivery, and one business event can match both relations; deduplicate with `event_id` when needed.
+
+`subscription_type` may be omitted, a single value, a comma-separated list, or a JSON string array:
+
+```bash
+# Omitted: register both INVOLVED_APPROVAL and MANAGED_APPROVAL for this EventKey
+lark-cli event consume approval.instance.status_changed_v4 --as user
+
+# Single relation
+lark-cli event consume approval.instance.status_changed_v4 \
+  -p subscription_type=INVOLVED_APPROVAL \
+  --as user
+
+# Explicit multi-relation registration for one local consumer
+lark-cli event consume approval.task.status_changed_v4 \
+  -p subscription_type=INVOLVED_APPROVAL,MANAGED_APPROVAL \
+  --as user
+
+# JSON array form; quote it for the shell
+lark-cli event consume approval.task.status_changed_v4 \
+  -p 'subscription_type=["INVOLVED_APPROVAL","MANAGED_APPROVAL"]' \
+  --as user
+```
+
+| Value | Meaning |
+|---|---|
+| `INVOLVED_APPROVAL` | Receive events where the current user is the approval requester or approver |
+| `MANAGED_APPROVAL` | Receive events under approval definitions managed by the current user |
+
+User-intent inference:
+
+| User intent | EventKey(s) | `subscription_type` |
+|---|---|---|
+| Mentions approval instances, approval forms, approval order/status, or "instance status" | `approval.instance.status_changed_v4` | infer from relation words below |
+| Mentions approval tasks, approval todo items, approver operations, or "task status" | `approval.task.status_changed_v4` | infer from relation words below |
+| Says "approval status changes/events" without saying task vs instance | both EventKeys | infer from relation words below |
+| Says "my approvals", "approvals involving me", "I requested/approved", "待我审批", "我发起/我参与" | requested EventKey(s) | `INVOLVED_APPROVAL` |
+| Says "approvals I manage", "managed definitions", "definitions managed by me", "我管理的审批定义" | requested EventKey(s) | `MANAGED_APPROVAL` |
+| Explicitly asks for both involved and managed, or says "all approval subscriptions" | requested EventKey(s), or both if EventKey is also ambiguous | omit `subscription_type`, or pass both values in one `-p` |
+| Relation is ambiguous and the user wants broad coverage | requested EventKey(s), or both if EventKey is also ambiguous | omit `subscription_type` so PreConsume registers both |
+
+If the user's wording omits the relation and broad listening is acceptable, omit `subscription_type`. Ask only when registering both relations would be materially harmful.
+
+## Scopes & auth
+
+| EventKey | Scope | Auth |
+|---|---|---|
+| `approval.instance.status_changed_v4` | `approval:instance:read` | user |
+| `approval.task.status_changed_v4` | `approval:task:read` | user |
+
+## Subscription behavior
+
+Startup calls the endpoint for the selected EventKey:
+
+```text
+POST /open-apis/approval/v4/instances/subscription
+POST /open-apis/approval/v4/tasks/subscription
+```
+
+For each resolved `subscription_type`, PreConsume sends one request body:
+
+```json
+{"subscription_type":"INVOLVED_APPROVAL"}
+```
+
+If `subscription_type` is omitted, PreConsume sends two registration requests for that EventKey: one with `INVOLVED_APPROVAL`, then one with `MANAGED_APPROVAL`. If listening to both instance and task events, run two consumers; each consumer may omit `subscription_type` to register both relations for its own EventKey.
+
+Do not start two consumers for the same Approval EventKey merely to split `INVOLVED_APPROVAL` and `MANAGED_APPROVAL`. The server push and flattened output are keyed by EventKey and cannot be distinguished by subscription relation.
+
+Shutdown behavior:
+
+`event consume` does not call the Approval unsubscribe APIs when it exits. This applies to graceful exit, Ctrl+C / SIGTERM, stdin EOF, `--timeout`, and `--max-events`.
+
+To stop future delivery for a user, cancel the Approval subscription relation outside this consumer. The unsubscribe APIs are separate operations and are not called by `event consume`.
+
+## Output fields
+
+Common fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | string | Event type |
+| `event_id` | string | Globally unique event ID; use for deduplication |
+| `timestamp` | string (timestamp_ms) | Event delivery time in milliseconds, taken from `header.create_time` |
+
+Instance event fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `approval_code` | string | Approval definition code; not a subscription dimension |
+| `instance_code` | string | Approval instance code |
+| `external_id` | string | Third-party approval instance id, when present |
+| `status` | string enum | `PENDING`, `APPROVED`, `REJECTED`, `CANCELED`, `DELETED`, `REVERTED`, `OVERTIME_CLOSE`, `OVERTIME_RECOVER` |
+| `operate_time` | string (timestamp_ms) | Status change time |
+| `start_user` | object | Instance starter user IDs, omitted when unavailable |
+| `start_user.open_id` | string (open_id) | Instance starter open_id, when present |
+| `start_user.union_id` | string (union_id) | Instance starter union_id, when present |
+| `start_user.user_id` | string (user_id) | Instance starter tenant user_id, when present |
+
+Task event fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `approval_code` | string | Approval definition code; not a subscription dimension |
+| `instance_code` | string | Approval instance code |
+| `task_id` | string | Approval task id |
+| `external_id` | string | Third-party approval external id, when present |
+| `task_external_id` | string | Third-party task external id, when emitted |
+| `assigned_user` | object | Task assignee or operator user IDs, omitted for automatic flows without an operator |
+| `assigned_user.open_id` | string (open_id) | Task assignee or operator open_id, when present |
+| `assigned_user.union_id` | string (union_id) | Task assignee or operator union_id, when present |
+| `assigned_user.user_id` | string (user_id) | Task assignee or operator tenant user_id, when present |
+| `status` | string enum | `REVERTED`, `PENDING`, `APPROVED`, `REJECTED`, `TRANSFERRED`, `ROLLBACK`, `DONE`, `OVERTIME_CLOSE`, `OVERTIME_RECOVER` |
+| `operate_time` | string (timestamp_ms) | Status change time |
+
+## Examples
+
+```bash
+# Stream approval instance updates broadly; registers both involved and managed relations
+lark-cli event consume approval.instance.status_changed_v4 \
+  --as user
+
+# Stream approval instance updates only for approvals involving the current user
+lark-cli event consume approval.instance.status_changed_v4 \
+  -p subscription_type=INVOLVED_APPROVAL \
+  --as user
+
+# Stream approval task updates for definitions managed by the current user
+lark-cli event consume approval.task.status_changed_v4 \
+  -p subscription_type=MANAGED_APPROVAL \
+  --as user
+
+# Broad approval status listening:
+# run both EventKeys as separate processes; omit subscription_type so each registers both relations.
+lark-cli event consume approval.instance.status_changed_v4 \
+  --as user > approval-instance.ndjson &
+lark-cli event consume approval.task.status_changed_v4 \
+  --as user > approval-task.ndjson &
+wait
+
+# Listen to both involved and managed task subscriptions with one local consumer.
+lark-cli event consume approval.task.status_changed_v4 \
+  -p subscription_type=INVOLVED_APPROVAL,MANAGED_APPROVAL \
+  --as user > approval-task.ndjson
+
+# Project a compact approval-task record
+lark-cli event consume approval.task.status_changed_v4 \
+  -p subscription_type=INVOLVED_APPROVAL \
+  --as user \
+  --jq '{event_id, task_id, status, at: .operate_time}'
+```

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