@amaster.ai/pi-lark 0.1.3 → 0.1.5

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

@@ -0,0 +1,223 @@
+# OKR 量化指标管理
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+管理 OKR 目标（Objective）和关键结果（Key Result）的量化指标，包括查询和更新指标。
+
+> **快速更新当前值：** 如果只需要更新指标的当前值，推荐使用 shortcut [`okr +indicator-update`](lark-okr-indicator-update.md)，无需手动查询指标 ID。
+>
+> 本指南中的原生 API 适用于需要修改指标其他字段（如 `unit`、`target_value`、`status_calculate_type` 等）的场景。
+
+---
+
+## 指标字段说明
+
+| 字段                          | 类型   | 说明                                                                 |
+|-----------------------------|------|--------------------------------------------------------------------|
+| `id`                        | string | 指标 ID（更新时需要）                                                     |
+| `entity_id` / `entity_type` | string/int | 所属实体 ID 和类型（2=目标，3=关键结果）                                   |
+| `current_value`             | number | 当前值                                                                 |
+| `target_value`              | number | 目标值                                                                 |
+| `start_value`               | number | 起始值                                                                 |
+| `indicator_status`          | int    | 状态：-1=未定义，0=正常，1=有风险，2=已延期                                   |
+| `status_calculate_type`     | int    | 状态计算方式：0=手动更新，1=基于进度和当前时间自动更新，2=基于风险最高的 KR 状态更新       |
+| `current_value_calculate_type` | int | 当前值计算方式：0=手动更新，1=基于 KR 进度自动更新（目标），2=基于拆解 KR 进度更新（KR） |
+| `unit`                      | object | 单位，包含 `unit_type`（0=公共，1=自定义）和 `unit_value`（如 PERCENT、YUAN 等）       |
+| `owner`                     | object | 所有者                                                                 |
+
+---
+
+## 一、查询目标的量化指标
+
+### 命令
+
+```bash
+lark-cli okr objective.indicators list --objective-id "<目标ID>" [flags]
+```
+
+### 常用示例
+
+```bash
+# 获取目标的量化指标
+lark-cli okr objective.indicators list \
+  --objective-id 7652569715131075772
+
+# 指定用户 ID 类型
+lark-cli okr objective.indicators list \
+  --objective-id 7652569715131075772 \
+  --user-id-type "user_id"
+```
+
+### 参数
+
+| 参数                   | 必填 | 默认值            | 说明                                                  |
+|----------------------|----|----------------|-----------------------------------------------------|
+| `--objective-id`     | 是  | —              | 目标 ID                                               |
+| `--user-id-type`     | 否  | `open_id`      | 用户 ID 类型：`open_id` \| `union_id` \| `user_id`     |
+| `--department-id-type` | 否 | `open_department_id` | 部门 ID 类型：`open_department_id` \| `department_id` |
+
+### 返回
+
+返回 `indicator` 字段，包含该目标的量化指标详情。
+
+---
+
+## 二、查询关键结果的量化指标
+
+### 命令
+
+```bash
+lark-cli okr key_result.indicators list --key-result-id "<关键结果ID>" [flags]
+```
+
+### 常用示例
+
+```bash
+# 获取关键结果的量化指标
+lark-cli okr key_result.indicators list \
+  --key-result-id "7652569715131075780"
+```
+
+### 参数
+
+| 参数                   | 必填 | 默认值            | 说明                                                  |
+|----------------------|----|----------------|-----------------------------------------------------|
+| `--key-result-id`    | 是  | —              | 关键结果 ID                                            |
+| `--user-id-type`     | 否  | `open_id`      | 用户 ID 类型：`open_id` \| `union_id` \| `user_id`     |
+| `--department-id-type` | 否 | `open_department_id` | 部门 ID 类型：`open_department_id` \| `department_id` |
+
+### 返回
+
+返回 `indicator` 字段，包含该关键结果的量化指标详情。
+
+---
+
+## 三、更新量化指标
+
+### 命令
+
+```bash
+lark-cli okr indicators patch --indicator-id "<指标ID>" --data '<JSON>'
+```
+
+### 常用示例
+
+```bash
+# 更新指标的当前值（手动更新方式）
+lark-cli okr indicators patch \
+  --indicator-id "ind-123" \
+  --data '{"current_value": 75.5, "current_value_calculate_type": 0}'
+
+# 更新指标状态为"有风险"（需 status_calculate_type=0）
+lark-cli okr indicators patch \
+  --indicator-id "ind-123" \
+  --data '{"indicator_status": 1, "status_calculate_type": 0}'
+
+# 更新关键结果指标的目标值和单位
+lark-cli okr indicators patch \
+  --indicator-id "ind-456" \
+  --data '{
+    "target_value": 100,
+    "unit": {"unit_type": 0, "unit_value": "PERCENT"}
+  }'
+
+# 从文件读取请求体
+lark-cli okr indicators patch \
+  --indicator-id "ind-123" \
+  --data @indicator_update.json
+```
+
+### 参数
+
+| 参数               | 必填 | 说明                                                                 |
+|------------------|----|--------------------------------------------------------------------|
+| `--indicator-id` | 是  | 指标 ID（从 list 接口获取）                                             |
+| `--data`         | 是  | JSON 请求体，包含要更新的字段。支持 `@文件路径` 从文件读取。                        |
+| `--user-id-type` | 否  | 用户 ID 类型                                                           |
+
+### 请求体字段
+
+根据需要更新的字段选择传入，支持增量更新：
+
+| 字段                          | 类型   | 适用实体 | 说明                                                                 |
+|-----------------------------|------|------|--------------------------------------------------------------------|
+| `current_value`             | number | 全部   | 当前值，范围 -99999999999 到 99999999999                                  |
+| `current_value_calculate_type` | int  | 全部   | 当前值计算方式：0=手动，1=基于 KR 进度（目标），2=基于拆解 KR 进度（KR）              |
+| `indicator_status`          | int    | 全部   | 状态：-1=未定义，0=正常，1=有风险，2=已延期。仅 `status_calculate_type=0` 时可修改      |
+| `status_calculate_type`     | int    | 全部   | 状态计算方式：0=手动，1=自动（进度+时间），2=自动（最高风险 KR）。目标支持 0/1/2，KR 支持 0/1 |
+| `start_value`               | number | KR    | 起始值。目标不支持修改                                                   |
+| `target_value`              | number | KR    | 目标值。目标不支持修改；有承接记录的 KR 不支持修改                                  |
+| `unit`                      | object | KR    | 单位。目标不支持修改；有承接记录的 KR 不支持修改                                  |
+
+### 单位 (`unit`) 格式
+
+```json
+{
+  "unit": {
+    "unit_type": 0,              // 0=公共单位，1=自定义单位
+    "unit_value": "PERCENT"      // 公共单位枚举：PERCENT、NONE、YUAN、DOLLAR；自定义单位：最长5字符
+  }
+}
+```
+
+### 限制说明
+
+- **目标指标**：不支持修改 `start_value`、`target_value`、`unit`
+- **关键结果指标**：有承接记录的 KR 不支持修改 `target_value`、`unit`
+- **自动计算的指标**：`current_value_calculate_type != 0` 时，不能手动修改 `current_value`
+- **自动状态的指标**：`status_calculate_type != 0` 时，不能手动修改 `indicator_status`
+
+---
+
+## 完整工作流示例
+
+### 场景：更新关键结果的指标当前值和状态
+
+1. **查询关键结果的指标**（获取 `indicator_id` 和当前配置）
+   ```bash
+   lark-cli okr key_result.indicators list \
+     --key-result-id 7652569715131075780
+   ```
+
+2. **检查指标配置**，确认：
+   - `current_value_calculate_type` 为 0（手动更新）才能修改 `current_value`
+   - `status_calculate_type` 为 0（手动更新）才能修改 `indicator_status`
+
+3. **更新指标**
+   ```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
+     }'
+   ```
+
+4. **验证更新结果**
+   ```bash
+   lark-cli okr key_result.indicators list \
+     --key-result-id 7652569715131075780
+   ```
+
+### 场景：修改关键结果指标的目标值和单位
+
+```bash
+# 1. 查询获取 indicator_id
+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"}
+  }'
+```
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [okr +indicator-update](lark-okr-indicator-update.md) -- 快捷更新指标当前值（推荐）

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

@@ -0,0 +1,104 @@
+# okr +patch
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+部分更新 OKR 目标（Objective）或关键结果（Key Result）的 content、notes、score、deadline 字段。支持增量更新，只需提供要修改的字段。
+
+## 推荐命令
+
+```bash
+# 更新目标的 content（默认 simple 风格，半纯文本格式）
+lark-cli okr +patch \
+  --level objective \
+  --target-id 1234567890123456789 \
+  --content '{"text":"更新后的目标内容","mention":["ou_123"]}'
+
+# 更新关键结果的分数（0.0-1.0 的一位小数）
+lark-cli okr +patch \
+  --level key-result \
+  --target-id 2345678901234567890 \
+  --score 0.7
+
+# 同时更新目标的多个字段（richtext 风格，完整 ContentBlock 格式）
+lark-cli okr +patch \
+  --level objective \
+  --target-id 1234567890123456789 \
+  --style richtext \
+  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"更新后的目标内容"}}]}}]}' \
+  --notes '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"更新后的备注"}}]}}]}' \
+  --score 0.5 \
+  --deadline 1735776000000
+
+# 预览 API 调用而不实际执行
+lark-cli okr +patch \
+  --level objective \
+  --target-id 1234567890123456789 \
+  --content '{"text":"测试更新"}' \
+  --dry-run
+```
+
+## 参数
+
+| 参数             | 必填 | 默认值       | 说明                                                                                                                                   |
+|----------------|----|-----------|--------------------------------------------------------------------------------------------------------------------------------------|
+| `--level`      | 是  | —         | 更新级别：`objective`（目标） \| `key-result`（关键结果）                                                                                    |
+| `--target-id`  | 是  | —         | 目标 ID 或关键结果 ID（int64 类型，正整数）                                                                                                         |
+| `--style`      | 否  | `simple`  | 输入风格：`simple`（半纯文本 JSON，推荐） \| `richtext`（完整 ContentBlock JSON）。请参考 [ContentBlock 格式](lark-okr-contentblock.md) 了解两种格式。          |
+| `--content`    | 否¹ | —         | 内容。根据 `--style` 指定格式。支持 `@文件路径` 从文件读取。                                                                                                |
+| `--notes`      | 否¹ | —         | 备注（仅 `--level=objective` 时支持）。根据 `--style` 指定格式。支持 `@文件路径` 从文件读取。                                                                           |
+| `--score`      | 否¹ | —         | 分数值，0-1 之间，最多一位小数（如 0.5、1.0）。                                                                                                            |
+| `--deadline`   | 否¹ | —         | 截止时间，毫秒级时间戳（如 1735776000000）。                                                                                                      |
+| `--user-id-type` | 否  | `open_id` | 用户 ID 类型：`open_id` \| `union_id` \| `user_id`                                                                                        |
+| `--dry-run`    | 否  | —         | 预览 API 调用而不实际执行。                                                                                                                     |
+| `--format`     | 否  | `json`    | 输出格式。                                                                                                                                |
+
+> ¹ 至少需要提供 `--content`、`--notes`、`--score`、`--deadline` 中的一个字段。
+
+## 工作流程
+
+1. 使用 `+cycle-list` 和 `+cycle-detail` 获取目标或关键结果的 ID。
+2. 确定要更新的字段：
+   - **content/notes**：构造内容
+     - **推荐**：使用 `simple` 风格（默认），构造 SemiPlainContent JSON：`{"text":"内容","mention":["ou_xxx"]}`
+     - 如需复杂格式：使用 `richtext` 风格，构造 ContentBlock JSON。请参考 [ContentBlock 格式](lark-okr-contentblock.md)。
+   - **score**：0-1 之间的数字，最多一位小数（如 0.3、0.7、1.0）
+   - **deadline**：毫秒级时间戳
+3. 执行 `lark-cli okr +patch --level objective --target-id "..." --content "..."`。
+4. 报告结果：更新的级别、目标 ID、以及哪些字段被更新。
+
+## 输出
+
+返回 JSON：
+
+```json
+{
+  "level": "objective",
+  "target_id": "1234567890123456789",
+  "patched": {
+    "content": true,
+    "notes": true,
+    "score": true,
+    "deadline": true
+  }
+}
+```
+
+其中 `patched` 对象中的每个字段表示该字段是否被更新。
+
+## 注意事项
+
+- **`--notes` 仅适用于目标**：关键结果（key-result）不支持 notes 字段，使用时会报错。
+- **score 格式**：必须在 0-1 之间，且最多一位小数（如 0.5 正确，0.51 错误）。
+- **严格验证**：输入格式严格根据 `--style` 值验证，不会自动检测。使用 ContentBlock JSON 时必须指定 `--style richtext`。
+- **simple 风格输入限制**：simple 风格的输入不支持 `docs` 和 `images` 字段，如需包含文档或图片请使用 `richtext` 风格。
+
+## 关于 1001001 错误
+
+有时，当你涉及修改目标或关键结果的分数时，即使输入的参数完全正确， +patch 也会返回 1001001 错误(invalid parameters)。
+这可能是因为在用户的租户设置中停用了目标/关键结果的分数功能，或禁用了目标分数的手动计算。此时可以先去掉 --score 参数再修改，并向用户确认是否启用了对应的功能。
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令(shortcut 和 API 接口)
+- [ContentBlock 格式](lark-okr-contentblock.md) -- content/notes 使用的富文本格式
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,85 @@
+# okr +progress-create
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+为目标（Objective）或关键结果（Key Result）创建一条 OKR 进展记录。
+
+## 推荐命令
+
+```bash
+# 为目标创建进展记录（默认 simple 风格，半纯文本格式）
+lark-cli okr +progress-create \
+  --content '{"text":"本周完成了核心模块开发","mention":["ou_123"]}' \
+  --target-id 1234567890123456789 \
+  --target-type objective
+
+# 为关键结果创建进展记录（richtext 风格，完整 ContentBlock 格式）
+lark-cli okr +progress-create \
+  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"指标已达到 80%"}}]}}]}' \
+  --style richtext \
+  --target-id 2345678901234567891 \
+  --target-type key_result \
+  --progress-percent 80 \
+  --progress-status done
+
+# 从文件读取 content（适用于较长的进展内容）
+lark-cli okr +progress-create \
+  --content @progress_content.json \
+  --target-id 1234567890123456789 \
+  --target-type objective
+```
+
+## 参数
+
+| 参数                   | 必填 | 默认值                   | 说明                                                                                                                                   |
+|----------------------|----|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------|
+| `--content`          | 是  | —                     | 进展内容。根据 `--style` 指定格式：`simple` 风格为 SemiPlainContent JSON，`richtext` 风格为 ContentBlock JSON。支持 `@文件路径` 从文件读取。请参考 [ContentBlock 格式](lark-okr-contentblock.md)。 |
+| `--style`            | 否  | `simple`              | 输入风格：`simple`（半纯文本 JSON，推荐） \| `richtext`（完整 ContentBlock JSON）。请参考 [ContentBlock 格式](lark-okr-contentblock.md) 了解两种格式。          |
+| `--target-id`        | 是  | —                     | 目标 ID 或关键结果 ID（int64 类型，正整数）                                                                                                         |
+| `--target-type`      | 是  | —                     | 目标类型：`objective` \| `key_result`                                                                                                     |
+| `--progress-percent` | 否  | —                     | 进度百分比(-99999999999 - 99999999999)。百分比的取值通常在 0-100，但允许超过此范围，以表示超额完成或负增长等情况。挂载的目标或关键结果的量化指标不使用百分比单位时，以这个字段更新当前值。系统内最多保留两位小数            |
+| `--progress-status`  | 否  | —                     | 进度状态：`normal`（正常） \| `overdue`（逾期） \| `done`（已完成）。仅在指定 `--progress-percent` 时生效。                                                     |
+| `--source-title`     | 否  | `created by lark-cli` | 来源标题，用于在 OKR 界面中显示进展来源                                                                                                               |
+| `--source-url`       | 否  | 根据品牌自动生成              | 来源 URL，用于在 OKR 界面中显示进展来源链接，通常可以填写 OKR 编写信息来源的文档链接等。飞书品牌默认为 `https://open.feishu.cn/app`, Lark 品牌默认为 `https://open.larksuite.com/app` |
+| `--user-id-type`     | 否  | `open_id`             | 用户 ID 类型：`open_id` \| `union_id` \| `user_id`                                                                                        |
+| `--dry-run`          | 否  | —                     | 预览 API 调用而不实际执行。                                                                                                                     |
+| `--format`           | 否  | `json`                | 输出格式。                                                                                                                                |
+
+## 工作流程
+
+1. 使用 `+cycle-list` 和 `+cycle-detail` 获取目标或关键结果的 ID。
+2. 构造进展内容：
+   - **推荐**：使用 `simple` 风格（默认），构造 SemiPlainContent JSON：`{"text":"内容","mention":["ou_xxx"]}`，mention 中提及的用户会统一连接在文本末尾。
+   - 如需复杂格式：使用 `richtext` 风格，构造 ContentBlock JSON。请参考 [ContentBlock 格式](lark-okr-contentblock.md)。若需要插入图片/飞书文档或复杂文本格式，则必须使用 richtext 风格
+3. 执行 `lark-cli okr +progress-create --content "..." --target-id "..." --target-type objective`。
+4. 报告结果：新创建的进展记录 ID、修改时间等。
+
+## 输出
+
+返回 JSON：
+
+```json
+{
+  "progress": {
+    "progress_id": "1234567890123456789",
+    "modify_time": "2025-01-15 10:30:00",
+    "content": "{...}",
+    "progress_rate": {
+      "percent": 80.0,
+      "status": "done"
+    }
+  }
+}
+```
+
+其中：
+
+- `content` 字段是 JSON 字符串，为 OKR ContentBlock
+  富文本格式。请参考 [lark-okr-contentblock.md](lark-okr-contentblock.md) 了解详细信息。
+- `progress_rate.status` 返回可读字符串：`normal`（正常）、`overdue`（逾期）、`done`（已完成）。
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令(shortcut 和 API 接口)
+- [ContentBlock 格式](lark-okr-contentblock.md) -- 进展内容使用的富文本格式
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,47 @@
+# okr +progress-delete
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+根据 ID 删除一条 OKR 进展记录。此操作为高风险操作，删除后不可恢复。
+
+## 推荐命令
+
+```bash
+# 删除指定 ID 的进展记录
+lark-cli okr +progress-delete --progress-id 1234567890123456789
+
+# 预览 API 调用而不实际执行
+lark-cli okr +progress-delete --progress-id 1234567890123456789 --dry-run
+```
+
+## 参数
+
+| 参数              | 必填 | 默认值    | 说明                    |
+|-----------------|----|--------|-----------------------|
+| `--progress-id` | 是  | —      | 进展记录 ID（int64 类型，正整数） |
+| `--dry-run`     | 否  | —      | 预览 API 调用而不实际执行。      |
+| `--format`      | 否  | `json` | 输出格式。                 |
+
+## 工作流程
+
+1. 使用 `+progress-get` 确认要删除的进展记录 ID 和内容。
+2. 执行 `lark-cli okr +progress-delete --progress-id "1234567890123456789"`。
+3. 报告结果：已删除的进展记录 ID。
+
+> **注意**：此操作不可恢复，建议在删除前先用 `+progress-get` 确认记录内容。
+
+## 输出
+
+返回 JSON：
+
+```json
+{
+  "deleted": true,
+  "progress_id": "1234567890123456789"
+}
+```
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令(shortcut 和 API 接口)
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,93 @@
+# okr +progress-get
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+根据进展记录 ID 获取单条 OKR 进展记录。
+
+## 推荐命令
+
+```bash
+# 获取指定 ID 的进展记录（默认 simple 风格，半纯文本格式）
+lark-cli okr +progress-get --progress-id 1234567890123456789
+
+# 获取指定 ID 的进展记录（richtext 风格，原始 ContentBlock JSON）
+lark-cli okr +progress-get --progress-id 1234567890123456789 --style richtext
+
+# 使用特定的用户 ID 类型
+lark-cli okr +progress-get --progress-id 1234567890123456789 --user-id-type open_id
+
+# 预览 API 调用而不实际执行
+lark-cli okr +progress-get --progress-id 1234567890123456789 --dry-run
+```
+
+## 参数
+
+| 参数               | 必填 | 默认值         | 说明                                                                 |
+|------------------|----|-------------|--------------------------------------------------------------------|
+| `--progress-id`  | 是  | —           | 进展记录 ID（int64 类型，正整数）                                               |
+| `--style`        | 否  | `simple`    | 输出风格：`simple`（半纯文本 SemiPlainContent，推荐） \| `richtext`（原始 ContentBlock JSON）。请参考 [ContentBlock 格式](lark-okr-contentblock.md)。 |
+| `--user-id-type` | 否  | `open_id`   | 用户 ID 类型：`open_id` \| `union_id` \| `user_id`                           |
+| `--dry-run`      | 否  | —           | 预览 API 调用而不实际执行。                                                        |
+| `--format`       | 否  | `json`      | 输出格式。                                                                     |
+
+## 工作流程
+
+1. 获取目标进展记录的 ID。可通过 `+cycle-detail` 获取目标和关键结果后，从中获取进展记录 ID。
+2. 执行 `lark-cli okr +progress-get --progress-id "1234567890123456789"`。
+3. 报告结果：进展记录的 ID、修改时间、进度百分比和内容。
+
+## 输出
+
+返回 JSON，`content` 字段格式由 `--style` 控制：
+
+### `--style simple`（默认）输出示例：
+
+```json
+{
+  "progress": {
+    "progress_id": "1234567890123456789",
+    "modify_time": "2025-01-15 10:30:00",
+    "content": {
+      "text": "已完成 80% 的开发工作 @{ou_zhangsan} ",
+      "mention": ["ou_zhangsan"],
+      "docs": [],
+      "images": []
+    },
+    "progress_rate": {
+      "percent": 75.0,
+      "status": "normal"
+    }
+  },
+  "style": "simple"
+}
+```
+
+### `--style richtext` 输出示例：
+
+```json
+{
+  "progress": {
+    "progress_id": "1234567890123456789",
+    "modify_time": "2025-01-15 10:30:00",
+    "content": "{\"blocks\":[{\"block_element_type\":\"paragraph\",\"paragraph\":{\"elements\":[{\"paragraph_element_type\":\"textRun\",\"text_run\":{\"text\":\"已完成 80% 的开发工作 \"}},{\"paragraph_element_type\":\"mention\",\"mention\":{\"user_id\":\"ou_zhangsan\"}}]}}]}",
+    "progress_rate": {
+      "percent": 75.0,
+      "status": "normal"
+    }
+  },
+  "style": "richtext"
+}
+```
+
+其中：
+
+- `content` 字段格式由 `--style` 控制：
+  - `--style simple`（默认）：`SemiPlainContent` 对象，包含 `text`、`mention`、`docs`、`images` 字段。`text` 中包含 `@{userID}` 占位符用于标识 mention 位置。
+  - `--style richtext`：JSON 字符串，为 OKR ContentBlock 富文本格式
+- 请参考 [lark-okr-contentblock.md](lark-okr-contentblock.md) 了解两种格式的详细信息。
+- `progress_rate.status` 返回可读字符串：`normal`（正常）、`overdue`（逾期）、`done`（已完成）。
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令(shortcut 和 API 接口)
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,80 @@
+# okr +progress-list
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+获取目标（Objective）或关键结果（Key Result）的所有进展记录列表。
+
+## 推荐命令
+
+```bash
+# 获取目标的所有进展记录
+lark-cli okr +progress-list \
+  --target-id 1234567890123456789 \
+  --target-type objective
+
+# 获取关键结果的所有进展记录
+lark-cli okr +progress-list \
+  --target-id 9876543210987654321 \
+  --target-type key_result
+```
+
+## 参数
+
+| 参数                    | 必填 | 默认值             | 说明                                             |
+|-------------------------|----|--------------------|--------------------------------------------------|
+| `--target-id`           | 是  | —                  | 目标 ID 或关键结果 ID（int64 类型，正整数）       |
+| `--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` |
+| `--dry-run`             | 否  | —                  | 预览 API 调用而不实际执行。                       |
+| `--format`              | 否  | `json`             | 输出格式。                                        |
+
+## 工作流程
+
+1. 使用 `+cycle-list` 和 `+cycle-detail` 获取目标或关键结果的 ID。
+2. 执行 `lark-cli okr +progress-list --target-id "..." --target-type objective`。
+3. 获取该目标或关键结果下的所有进展记录列表。
+
+## 输出
+
+返回 JSON：
+
+```json
+{
+  "progress": [
+    {
+      "progress_id": "1234567890123456789",
+      "modify_time": "2025-01-15 10:30:00",
+      "content": "{...}",
+      "progress_rate": {
+        "percent": 80.0,
+        "status": "done"
+      }
+    }
+  ],
+  "total": 1
+}
+```
+
+其中：
+
+- `progress` — 进展记录数组
+- `content` 字段是 JSON 字符串，为 OKR ContentBlock 富文本格式。请参考 [lark-okr-contentblock.md](lark-okr-contentblock.md) 了解详细信息。
+- `progress_rate.status` 返回可读字符串：`normal`（正常）、`overdue`（逾期）、`done`（已完成）。
+
+## 与 +progress-get 的区别
+
+| 命令             | 用途                               | API 版本 |
+|------------------|------------------------------------|----------|
+| `+progress-list` | 获取某个目标/关键结果的所有进展记录 | v2       |
+| `+progress-get`  | 根据进展记录 ID 获取单条记录        | v1       |
+
+`+progress-list` 返回的 `progress_list` 数组中每条记录的结构与 `+progress-get` 返回的 `progress` 结构相同。
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令(shortcut 和 API 接口)
+- [ContentBlock 格式](lark-okr-contentblock.md) -- 进展内容使用的富文本格式
+- [lark-okr-progress-get](lark-okr-progress-get.md) -- 根据 ID 获取单条进展记录
+- [lark-okr-progress-create](lark-okr-progress-create.md) -- 创建进展记录
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数