@amaster.ai/pi-lark 0.1.5 → 0.1.7

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 并更新当前值。
 
 ## 输出

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

@@ -40,11 +40,11 @@ lark-cli okr objective.indicators list --objective-id "<目标ID>" [flags]
 ```bash
 # 获取目标的量化指标
 lark-cli okr objective.indicators list \
-  --objective-id 7652569715131075772
+  --objective-id 7000000000000000001
 
 # 指定用户 ID 类型
 lark-cli okr objective.indicators list \
-  --objective-id 7652569715131075772 \
+  --objective-id 7000000000000000001 \
   --user-id-type "user_id"
 ```
 
@@ -60,6 +60,63 @@ lark-cli okr objective.indicators list \
 
 返回 `indicator` 字段，包含该目标的量化指标详情。
 
+示例返回值:
+有进度时:
+```json 
+{
+   "ok": true,
+   "identity": "user",
+   "data": {
+      "indicator": {
+         "create_time": "1782835200000",    // 创建时间
+         "current_value": 60,               // 当前值
+         "current_value_calculate_type": 0, // 当前值计算方式 0(手动更新)|2(按KR计算)|3(按拆解计算)。 仅当此处为 0 时，允许使用 patch API 更新当前值
+         "entity_id": "7000000000000000001",// 指标挂载的 Objective/KR id
+         "entity_type": 2,                  // 指标挂载在 Objective还是KR 上 2(Objective)|3(KR)
+         "id": "7000000000000000002",       // 指标本身的 ID
+         "indicator_status": 0,             // 指标状态 -1(未定义)|0(正常)|1(有风险)|2(延期)
+         "owner": {                         // 指标归属的用户
+            "owner_type": "user",
+            "user_id": "ou_xxx"
+         },
+         "start_value": 0,                  // 起始值, 默认0
+         "status_calculate_type": 0,        // 状态计算方式
+         "target_value": 100,               // 目标值, 默认 100
+         "unit": {                          // 指标单位，默认是公共的百分比
+            "unit_type": 0,                 // 单位类型 0(公共)|1(自定义)
+            "unit_value": "PERCENT"         // 单位名
+         },
+         "update_time": "1782835200000"     // 更新时间
+      }
+   }
+}
+```
+默认初始进度:
+```json 
+{
+   "ok": true,
+   "identity": "user",
+   "data": {
+      "indicator": {
+         "create_time": "1782835200000",
+         "entity_id": "7000000000000000001",
+         "entity_type": 2,
+         "id": "7000000000000000002",
+         "indicator_status": -1,
+         "owner": {
+            "owner_type": "user",
+            "user_id": "ou_xxx"
+         },
+         "status_calculate_type": 0,
+         "update_time": "1782835200000"
+      }
+   }
+}
+```
+
+默认初始进度不携带 start_value/current_value/target_value/unit 等信息，若直接设置当前值，则使用百分比作为默认单位。
+由于默认单位为百分比，当一定要计算数值时，可以视作 0%，但是向用户汇报默认初始进度时，应当明确对应的 O/KR 未设置进度这一点，以和真正的 0% 区别开。
+
 ---
 
 ## 二、查询关键结果的量化指标
@@ -187,12 +244,7 @@ lark-cli okr indicators patch \
    ```bash
    lark-cli okr indicators patch \
      --indicator-id "ind-123" \
-     --data '{
-       "current_value": 65.0,
-       "current_value_calculate_type": 0,
-       "indicator_status": 1,
-       "status_calculate_type": 0
-     }'
+     --data '{"current_value":65.0,"current_value_calculate_type":0,"indicator_status":1,"status_calculate_type":0}'
    ```
 
 4. **验证更新结果**
@@ -210,10 +262,7 @@ lark-cli okr key_result.indicators list --key-result-id 7652569715131075780
 # 2. 更新目标值和单位
 lark-cli okr indicators patch \
   --indicator-id 7652569715131075781 \
-  --data '{
-    "target_value": 500,
-    "unit": {"unit_type": 0, "unit_value": "YUAN"}
-  }'
+  --data '{"target_value":500,"unit":{"unit_type":0,"unit_value":"YUAN"}}'
 ```
 
 ## 参考

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

@@ -2,17 +2,24 @@
 
 > **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-获取目标（Objective）或关键结果（Key Result）的所有进展记录列表。
+获取目标（Objective）或关键结果（Key Result）的一页进展记录列表，支持外部控制翻页。
 
 ## 推荐命令
 
 ```bash
-# 获取目标的所有进展记录
+# 获取目标进展记录第一页 (默认页大小为 100，一般不用翻页)
 lark-cli okr +progress-list \
   --target-id 1234567890123456789 \
   --target-type objective
 
-# 获取关键结果的所有进展记录
+# 获取下一页进展记录 
+lark-cli okr +progress-list \
+  --target-id 1234567890123456789 \
+  --target-type objective \
+  --page-size 100 \
+  --page-token "7000000000000000002"
+
+# 获取关键结果进展记录第一页
 lark-cli okr +progress-list \
   --target-id 9876543210987654321 \
   --target-type key_result
@@ -26,14 +33,17 @@ lark-cli okr +progress-list \
 | `--target-type`         | 是  | —                  | 目标类型：`objective` \| `key_result`            |
 | `--user-id-type`        | 否  | `open_id`          | 用户 ID 类型：`open_id` \| `union_id` \| `user_id` |
 | `--department-id-type`  | 否  | `open_department_id` | 部门 ID 类型：`department_id` \| `open_department_id` |
+| `--page-size`           | 否  | `100`              | 每页数量，范围 `1-100`。                           |
+| `--page-token`          | 否  | `""`               | 上一次响应中的 `page_token`，留空表示第一页。        |
 | `--dry-run`             | 否  | —                  | 预览 API 调用而不实际执行。                       |
 | `--format`              | 否  | `json`             | 输出格式。                                        |
 
 ## 工作流程
 
 1. 使用 `+cycle-list` 和 `+cycle-detail` 获取目标或关键结果的 ID。
-2. 执行 `lark-cli okr +progress-list --target-id "..." --target-type objective`。
-3. 获取该目标或关键结果下的所有进展记录列表。
+2. 执行 `lark-cli okr +progress-list --target-id "..." --target-type objective --page-size 100`。
+3. 如果响应中 `has_more=true`，继续用返回的 `page_token` 调用下一页。
+4. 获取该目标或关键结果下的进展记录列表。
 
 ## 输出
 
@@ -41,7 +51,7 @@ lark-cli okr +progress-list \
 
 ```json
 {
-  "progress": [
+  "progress_list": [
     {
       "progress_id": "1234567890123456789",
       "modify_time": "2025-01-15 10:30:00",
@@ -52,13 +62,15 @@ lark-cli okr +progress-list \
       }
     }
   ],
-  "total": 1
+  "has_more": true,
+  "page_token": "7000000000000000002"
 }
 ```
 
 其中：
 
-- `progress` — 进展记录数组
+- `progress_list` — 进展记录数组
+- `has_more` 和 `page_token` 用于外部控制翻页；`has_more=true` 时，用 `--page-token` 原样传入本次返回的 `page_token` 获取下一页。
 - `content` 字段是 JSON 字符串，为 OKR ContentBlock 富文本格式。请参考 [lark-okr-contentblock.md](lark-okr-contentblock.md) 了解详细信息。
 - `progress_rate.status` 返回可读字符串：`normal`（正常）、`overdue`（逾期）、`done`（已完成）。
 
@@ -66,7 +78,7 @@ lark-cli okr +progress-list \
 
 | 命令             | 用途                               | API 版本 |
 |------------------|------------------------------------|----------|
-| `+progress-list` | 获取某个目标/关键结果的所有进展记录 | v2       |
+| `+progress-list` | 分页获取某个目标/关键结果的进展记录 | v2       |
 | `+progress-get`  | 根据进展记录 ID 获取单条记录        | v1       |
 
 `+progress-list` 返回的 `progress_list` 数组中每条记录的结构与 `+progress-get` 返回的 `progress` 结构相同。

package/skills/lark-shared/SKILL.md

@@ -69,7 +69,7 @@ LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 lark-cli a
 遇到权限相关错误时，**根据当前身份类型采取不同解决方案**。
 
 错误响应中包含关键信息：
-- `permission_violations`：列出缺失的 scope (N选1)
+- `missing_scopes`：列出缺失的 scope (N选1)
 - `console_url`：飞书开发者后台的权限配置链接
 - `hint`：建议的修复命令
 
@@ -146,6 +146,24 @@ lark-cli update
 
 **重要**：始终使用 `lark-cli update` 更新，它会同时更新 CLI 和 AI Skills。
 
+## JSON 输出契约
+
+`--format json`（默认）下，成功与错误的信封结构不同：
+
+成功信封写入 **stdout**（退出码 0）：
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+错误信封写入 **stderr**（退出码非 0）：
+
+```json
+{ "ok": false, "identity": "user", "error": { "type": "authorization", "subtype": "missing_scope", "code": 99991679, "message": "...", "hint": "...", "missing_scopes": ["..."] } }
+```
+
+**判断成功必须用 `ok == true`（或进程退出码 0），不要用 `code == 0`**：成功信封没有顶层 `code` / `msg` 字段，`code` 只出现在错误信封的 `error` 内，含义是上游 OpenAPI 的 numeric code。按 OpenAPI 老格式 `{"code": 0, "msg": "ok"}` 判断会把所有成功调用误判为失败；封装写入类命令（如 `task +create`）时尤其危险，误判会绕过幂等逻辑导致重复创建。
+
 ## 安全规则
 
 - **禁止输出密钥**（appSecret、accessToken）到终端明文。
@@ -160,22 +178,22 @@ lark-cli 对高风险写操作（`risk: "high-risk-write"`）有强制确认门
 ```json
 {
   "ok": false,
+  "identity": "bot",
   "error": {
-    "type": "confirmation_required",
+    "type": "confirmation",
+    "subtype": "confirmation_required",
     "message": "drive +delete requires confirmation",
     "hint": "add --yes to confirm",
-    "risk": {
-      "level": "high-risk-write",
-      "action": "drive +delete"
-    }
+    "risk": "high-risk-write",
+    "action": "drive +delete"
   }
 }
 ```
 
 **遇到这种情况，不要当普通错误放弃。** 按以下流程处理：
 
-1. **识别**：看到子进程 exit code = `10` 且 stderr JSON 里 `error.type == "confirmation_required"`
-2. **向用户确认**：把 `error.risk.action` 和关键参数展示给用户，明确告知"这是高风险操作"，等待用户显式同意
+1. **识别**：看到子进程 exit code = `10` 且 stderr JSON 里 `error.type == "confirmation"`、`error.subtype == "confirmation_required"`
+2. **向用户确认**：把 `error.action`、`error.risk` 和关键参数展示给用户，明确告知"这是高风险操作"，等待用户显式同意
 3. **用户同意** → 在你**原始 argv 的末尾追加 `--yes`** 后重试
 4. **用户拒绝** → 终止流程，不要擅自改写参数或跳过门禁