@wagemule/daemon 0.1.2 → 0.1.4

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

@@ -0,0 +1,329 @@
+# OKR 实体定义
+
+本文档描述飞书 OKR API (`/open-apis/okr/v2`) 中涉及的核心实体及其字段定义。
+
+## 实体关系概览
+
+```
+Cycle (用户周期)
+  └── Objective (目标)
+        ├── KeyResult (关键结果)
+        │     └── Indicator (指标)
+        │     └── list<Progress> (进展记录列表)
+        └── Indicator (指标)
+        └── list<Progress> (进展记录列表)
+
+Alignment (对齐关系): Objective ↔ Objective
+Category (分类): Objective 的分组标签
+```
+
+---
+
+## Owner (所有者)
+
+所有者标识 OKR 实体的归属，目前仅支持用户类型。
+
+| 字段           | 类型       | 必填 | 说明                                            |
+|--------------|----------|----|-----------------------------------------------|
+| `owner_type` | `string` | 是  | 所有者类型，通常为 `"user"`。                           |
+| `user_id`    | `string` | 否  | 员工 ID，类型由请求参数 `user_id_type` 决定（默认 `open_id`） |
+
+---
+
+## Cycle (用户周期)
+
+用户周期是 OKR 的顶层容器，代表一个时间段内的所有目标与关键结果。
+
+| 字段                | 类型        | 必填 | 说明                                         |
+|-------------------|-----------|----|--------------------------------------------|
+| `id`              | `string`  | 是  | 用户周期 ID                                    |
+| `create_time`     | `string`  | 是  | 创建时间                                       |
+| `update_time`     | `string`  | 是  | 更新时间                                       |
+| `tenant_cycle_id` | `string`  | 是  | 租户周期 ID（同一周期在不同用户下有不同的用户周期 ID，但租户周期 ID 相同） |
+| `owner`           | `Owner`   | 是  | 所有者                                        |
+| `start_time`      | `string`  | 是  | 周期开始时间。总是从某月1日开始                           |
+| `end_time`        | `string`  | 是  | 周期结束时间。到某月最后一日结束                           |
+| `cycle_status`    | `integer` | 否  | 周期状态，见下表                                   |
+| `score`           | `number`  | 否  | 周期分数，范围 [0, 1]，支持一位小数                      |
+
+### 常用术语
+
+- **当前周期**: 指周期的 start_time/end_time
+  指周期的 start_time / end_time 所在的时间段与当前时间重叠的周期（即： start_time <= 当前时间 且 end_time >= 当前时间）。 注意：时间重叠是判断当前周期的首要且必须的硬性条件，绝对不能仅仅根据 cycle_status == 1 去判断。 如果有多个符合时间重叠标准的周期，再在这些包含当前时间的周期中过滤，保留周期状态为 default (0) 或 normal (1) 的周期。如果仍然有多个，则选择其中较新的一个。当用户提及“上一个周期”，“下一个周期”一类的表述时，通常是以当前周期为准计算。
+- **所有者**: 绝大多数所有者都是用户，少部分租户启用了“团队OKR”功能，所有者可能是部门。用户身份下，只能编辑所有者为当前用户的
+  OKR。
+
+### 周期状态 (cycle_status)
+
+| 值 | 常量名       | 说明          |
+|---|-----------|-------------|
+| 0 | `default` | 默认状态        |
+| 1 | `normal`  | 生效中         |
+| 2 | `invalid` | 已失效（通常仍可填写） |
+| 3 | `hidden`  | 已隐藏（不可见）    |
+
+> **SHORTCUT：** `okr +cycle-list` [lark-okr-cycle-list.md](lark-okr-cycle-list.md) 获取用户的周期列表，可按时间筛选
+>
+> **API：** `cycles.list`
+
+---
+
+## Objective (目标)
+
+目标是 OKR 中的 "O"，属于某个用户周期，可包含多个关键结果。
+
+| 字段            | 类型             | 必填 | 说明                                                      |
+|---------------|----------------|----|---------------------------------------------------------|
+| `id`          | `string`       | 是  | 目标 ID                                                   |
+| `create_time` | `string`       | 是  | 创建时间，毫秒时间戳，shortcut 会将其解析为日期时间                          |
+| `update_time` | `string`       | 是  | 更新时间，毫秒时间戳，shortcut 会将其解析为日期时间                          |
+| `owner`       | `Owner`        | 是  | 所有者                                                     |
+| `cycle_id`    | `string`       | 是  | 所属用户周期 ID                                               |
+| `position`    | `integer`      | 是  | 排序序号，从 1 开始，范围 [1, 100]                                 |
+| `content`     | `ContentBlock` | 否  | 目标内容（富文本），见 [ContentBlock 定义](lark-okr-contentblock.md) |
+| `score`       | `number`       | 否  | 目标分数，范围 [0, 1]，支持一位小数                                   |
+| `notes`       | `ContentBlock` | 否  | 目标备注（富文本），见 [ContentBlock 定义](lark-okr-contentblock.md) |
+| `weight`      | `number`       | 否  | 目标权重，范围 [0, 1]，支持三位小数                                   |
+| `deadline`    | `string`       | 否  | 截止时间，毫秒时间戳，shortcut 会将其解析为日期时间                          |
+| `category_id` | `string`       | 否  | 所属分类 ID                                                 |
+
+> **SHORTCUT：**
+> - `okr +cycle-detail` [lark-okr-cycle-detail.md](lark-okr-cycle-detail.md) 获取某个用户周期下的全部目标和关键结果。时间相关的字段会以日期时间格式解析
+>
+> **API：**
+> - `cycle.objectives.list` — 获取周期下的目标列表
+> - `objectives.get` — 获取单个目标
+> - `cycle.objectives.create` — 创建目标
+> - `objectives.delete` — 删除目标
+> - `cycles.objectives_position` — 更新周期下的目标排序
+> - `cycles.objectives_weight` — 更新周期下的目标权重
+
+---
+
+## KeyResult (关键结果)
+
+关键结果是 OKR 中的 "KR"，属于某个目标，描述目标的可衡量成果。
+
+| 字段             | 类型             | 必填 | 说明                                                        |
+|----------------|----------------|----|-----------------------------------------------------------|
+| `id`           | `string`       | 是  | 关键结果 ID                                                   |
+| `create_time`  | `string`       | 是  | 创建时间，毫秒时间戳                                                |
+| `update_time`  | `string`       | 是  | 修改时间，毫秒时间戳                                                |
+| `owner`        | `Owner`        | 是  | 所有者                                                       |
+| `objective_id` | `string`       | 是  | 所属目标 ID                                                   |
+| `position`     | `integer`      | 是  | 排序序号，从 1 开始，范围 [1, 100]                                   |
+| `content`      | `ContentBlock` | 否  | 关键结果内容（富文本），见 [ContentBlock 定义](lark-okr-contentblock.md) |
+| `score`        | `number`       | 否  | 关键结果分数，范围 [0, 1]，支持一位小数                                   |
+| `weight`       | `number`       | 否  | 权重，范围 [0, 1]，支持三位小数                                       |
+| `deadline`     | `string`       | 否  | 截止时间，毫秒时间戳                                                |
+
+> **API：**
+> - `objective.key_results.list` — 获取目标下的关键结果列表
+> - `key_results.get` — 获取单个关键结果
+> - `key_results.patch` — 更新关键结果
+> - `key_results.delete` — 删除关键结果
+> - `objectives.key_results_position` — 更新目标下的关键结果排序
+> - `objectives.key_results_weight` — 更新目标下的关键结果权重
+
+---
+
+## Progress (进展记录)
+
+进展记录挂载在目标（Objective）或关键结果（Key Result）上，用于记录阶段性进展内容与进度百分比。每条进展记录包含富文本内容和可选的进度率。
+
+| 字段              | 类型             | 必填 | 说明                                                      |
+|-----------------|----------------|----|---------------------------------------------------------|
+| `progress_id`   | `string`       | 是  | 进展记录 ID（int64，正整数）                                      |
+| `modify_time`   | `string`       | 是  | 最后修改时间，毫秒时间戳，shortcut 会将其解析为日期时间                        |
+| `content`       | `ContentBlock` | 否  | 进展内容（富文本），见 [ContentBlock 定义](lark-okr-contentblock.md) |
+| `progress_rate` | `ProgressRate` | 否  | 进度率，包含百分比和状态                                            |
+
+### ProgressRate (进度率)
+
+| 字段        | 类型       | 必填 | 说明                                                                                                                           |
+|-----------|----------|----|------------------------------------------------------------------------------------------------------------------------------|
+| `percent` | `number` | 否  | 进度百分比，范围 [-99999999999, 99999999999]。百分比的取值通常在 0-100，但允许超过此范围，以表示超额完成或负增长等情况。挂载的目标或关键结果的量化指标不使用百分比单位时，以这个字段更新当前值。系统内最多保留两位小数 |
+| `status`  | `string` | 否  | 进度状态，shortcut 返回可读字符串，见下表                                                                                                    |
+
+### 进度状态 (progress_rate.status)
+
+| 值         | 常量名 | 说明    |
+|-----------|-----|-------|
+| `normal`  | 正常  | 进展正常  |
+| `overdue` | 逾期  | 进展逾期  |
+| `done`    | 已完成 | 进展已完成 |
+
+### 创建进展记录时的参数
+
+创建进展记录时，除了 `content` 外，还需要指定这条进展记录挂载的对应目标或关键结果：
+
+| 字段              | 类型             | 必填 | 说明                                                      |
+|-----------------|----------------|----|---------------------------------------------------------|
+| `content`       | `ContentBlock` | 是  | 进展内容（富文本），见 [ContentBlock 定义](lark-okr-contentblock.md) |
+| `target_id`     | `string`       | 是  | 目标 ID 或关键结果 ID                                          |
+| `target_type`   | `integer`      | 是  | 目标类型：`2`=目标（Objective），`3`=关键结果（KeyResult）              |
+| `progress_rate` | `ProgressRate` | 否  | 进度率，可设置 `percent` 和 `status`                            |
+| `source_title`  | `string`       | 否  | 来源标题，用于在 OKR 界面中显示进展来源                                  |
+| `source_url`    | `string`       | 否  | 来源 URL，用于在 OKR 界面中显示进展来源链接                              |
+
+> **SHORTCUT：**
+> - `okr +progress-get` [lark-okr-progress-get.md](lark-okr-progress-get.md) 获取单条进展记录
+> - `okr +progress-create` [lark-okr-progress-create.md](lark-okr-progress-create.md) 为目标或关键结果创建进展记录
+> - `okr +progress-update` [lark-okr-progress-update.md](lark-okr-progress-update.md) 更新进展记录内容
+> - `okr +progress-delete` [lark-okr-progress-delete.md](lark-okr-progress-delete.md) 删除进展记录
+> - `okr +progress-list` [lark-okr-progress-list.md](lark-okr-progress-list.md) 获取目标/关键结果下的进展记录
+---
+
+## Indicator (指标)
+
+指标是目标和关键结果的量化度量，可独立挂载在 Objective 或 KeyResult 上。
+
+| 字段                             | 类型              | 必填 | 说明                                 |
+|--------------------------------|-----------------|----|------------------------------------|
+| `id`                           | `string`        | 是  | 指标 ID                              |
+| `create_time`                  | `string`        | 是  | 创建时间，毫秒时间戳                         |
+| `update_time`                  | `string`        | 是  | 更新时间，毫秒时间戳                         |
+| `owner`                        | `Owner`         | 是  | 所有者                                |
+| `entity_type`                  | `integer`       | 是  | 所属实体类型：`2`=目标，`3`=关键结果             |
+| `entity_id`                    | `string`        | 是  | 所属实体 ID                            |
+| `indicator_status`             | `integer`       | 是  | 指标状态，见下表                           |
+| `status_calculate_type`        | `integer`       | 是  | 状态计算方式，见下表                         |
+| `start_value`                  | `number`        | 否  | 起始值，范围 [-99999999999, 99999999999] |
+| `target_value`                 | `number`        | 否  | 目标值，范围 [-99999999999, 99999999999] |
+| `current_value`                | `number`        | 否  | 当前值，范围 [-99999999999, 99999999999] |
+| `current_value_calculate_type` | `integer`       | 否  | 当前值计算方式，见下表                        |
+| `unit`                         | `IndicatorUnit` | 否  | 指标单位                               |
+
+### 修改指南
+
+- **进度值**: 一般指 `current_value`，单位未提及时通常用百分制计算。
+- 当用户要求量化的更新 OKR 进度时，一般指的就是修改对应 OKR 的 Indicator。
+- OKR 在未设置量化指标时，Indicator 的内容为空。如果用户未做特别说明，更新进度时可以默认将进度以百分制设置（初始值0，目标值100，unit
+  参见下文设置为 0/PERCENT）
+
+### 指标状态 (indicator_status)
+
+| 值  | 说明  |
+|----|-----|
+| -1 | 未定义 |
+| 0  | 正常  |
+| 1  | 有风险 |
+| 2  | 已延期 |
+
+### 状态计算方式 (status_calculate_type)
+
+| 值 | 说明              | 适用范围    |
+|---|-----------------|---------|
+| 0 | 手动更新            | 目标、关键结果 |
+| 1 | 基于进度和当前时间自动更新   | 目标、关键结果 |
+| 2 | 基于风险最高的关键结果状态更新 | 仅目标     |
+
+### 当前值计算方式 (current_value_calculate_type)
+
+| 值 | 说明            | 适用范围    |
+|---|---------------|---------|
+| 0 | 手动更新          | 目标、关键结果 |
+| 1 | 基于关键结果进度自动更新  | 仅目标     |
+| 2 | 基于拆解的关键结果进度更新 | 仅关键结果   |
+
+### IndicatorUnit (指标单位)
+
+| 字段           | 类型        | 必填 | 说明                                                                          |
+|--------------|-----------|----|-----------------------------------------------------------------------------|
+| `unit_type`  | `integer` | 是  | 单位类型：`0`=公共，`1`=自定义                                                         |
+| `unit_value` | `string`  | 是  | 单位值。公共类型可选：`PERCENT`(百分比)、`NONE`(无单位)、`YUAN`(元)、`DOLLAR`(美元)；自定义类型字符长度不超过 5 |
+
+> **API：**
+> - `key_result.indicators.list` — 获取关键结果的指标
+> - `objective.indicators.list` — 获取目标的指标
+> - `indicators.patch` — 更新指标
+
+---
+
+## Alignment (对齐关系)
+
+对齐关系描述两个目标之间的上下对齐。
+
+| 字段                 | 类型        | 必填 | 说明                    |
+|--------------------|-----------|----|-----------------------|
+| `id`               | `string`  | 是  | 对齐 ID                 |
+| `create_time`      | `string`  | 是  | 创建时间，毫秒时间戳            |
+| `update_time`      | `string`  | 是  | 更新时间，毫秒时间戳            |
+| `from_owner`       | `Owner`   | 是  | 发起对齐的所有者              |
+| `to_owner`         | `Owner`   | 是  | 被对齐的所有者               |
+| `from_entity_type` | `integer` | 是  | 发起对齐的实体类型，固定为 `2`（目标） |
+| `from_entity_id`   | `string`  | 是  | 发起对齐的实体 ID            |
+| `to_entity_type`   | `integer` | 是  | 被对齐的实体类型，固定为 `2`（目标）  |
+| `to_entity_id`     | `string`  | 是  | 被对齐的实体 ID             |
+
+> **API：**
+> - `alignments.get` — 获取对齐关系
+> - `alignments.delete` — 删除对齐关系
+> - `objective.alignments.list` — 批量获取目标下的对齐关系
+> - `objective.alignments.create` — 创建对齐关系
+
+---
+
+## Category (分类)
+
+分类用于对目标进行分组标记（如"个人 OKR"、"团队 OKR"、"承诺 OKR"）等。具体的分类根据租户设置而定。
+
+| 字段              | 类型             | 必填 | 说明                                                          |
+|-----------------|----------------|----|-------------------------------------------------------------|
+| `id`            | `string`       | 是  | 分类 ID                                                       |
+| `create_time`   | `string`       | 是  | 创建时间，毫秒时间戳                                                  |
+| `update_time`   | `string`       | 是  | 更新时间，毫秒时间戳                                                  |
+| `category_type` | `string`       | 是  | 分类类型：`"person"`=个人，`"team"`=团队                              |
+| `enabled`       | `boolean`      | 是  | 是否启用                                                        |
+| `color`         | `string`       | 是  | 颜色标识：`blue`、`purple`、`wathet`、`turquoise`、`indigo`、`orange` |
+| `name`          | `CategoryName` | 是  | 多语言名称                                                       |
+
+### CategoryName (分类名称)
+
+| 字段   | 类型       | 必填 | 说明  |
+|------|----------|----|-----|
+| `zh` | `string` | 否  | 中文名 |
+| `en` | `string` | 否  | 英文名 |
+| `ja` | `string` | 否  | 日文名 |
+
+> **API：** `categories.list` — 批量获取租户设置的分类列表
+
+---
+
+## 通用请求参数
+
+以下参数在多数 OKR API 中通用：
+
+| 参数                   | 位置      | 必填 | 默认值                    | 说明                                               |
+|----------------------|---------|----|------------------------|--------------------------------------------------|
+| `user_id_type`       | `query` | 否  | `"open_id"`            | 用户 ID 类型：`open_id` \| `union_id` \| `user_id`    |
+| `department_id_type` | `query` | 否  | `"open_department_id"` | 部门 ID 类型：`open_department_id` \| `department_id` |
+| `page_size`          | `query` | 否  | `10`                   | 分页大小，最大 100                                      |
+| `page_token`         | `query` | 否  | `""`                   | 分页键，首页传空串                                        |
+
+---
+
+## 权限 Scope 说明
+
+| Scope                          | 权限类型 | 说明           |
+|--------------------------------|------|--------------|
+| `okr:okr.content:readonly`     | 读    | 读取 OKR 内容    |
+| `okr:okr.content:writeonly`    | 写    | 写入/删除 OKR 内容 |
+| `okr:okr.period:readonly`      | 读    | 读取 OKR 周期    |
+| `okr:okr.progress:readonly`    | 读    | 读取进展记录       |
+| `okr:okr.progress:writeonly`   | 写    | 创建/更新进展记录    |
+| `okr:okr.progress:delete`      | 写    | 删除进展记录       |
+| `okr:okr.progress.file:upload` | 写    | 上传进展记录图片附件   |
+| `okr:okr.setting:read`         | 读    | 读取 OKR 设置    |
+
+所有 OKR API 均支持 `user` 和 `tenant`（应用）两种 access token 类型。
+
+## 参考
+
+- [OKR ContentBlock 富文本格式](lark-okr-contentblock.md) — content/notes 字段的富文本结构定义
+- [okr +cycle-list](lark-okr-cycle-list.md) — 列出用户 OKR 周期
+- [okr +cycle-detail](lark-okr-cycle-detail.md) — 获取周期下的目标与关键结果
+- [okr +progress-get](lark-okr-progress-get.md) — 获取进展记录
+- [okr +progress-create](lark-okr-progress-create.md) — 创建进展记录
+- [okr +progress-update](lark-okr-progress-update.md) — 更新进展记录
+- [okr +progress-delete](lark-okr-progress-delete.md) — 删除进展记录

package/dist/skills/larksuite/lark-okr/references/lark-okr-image-upload.md

@@ -0,0 +1,116 @@
+# okr +upload-image
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+上传本地图片，用于 OKR 进展记录的富文本内容。
+
+## 推荐命令
+
+```bash
+# 上传图片用于目标的进展记录
+lark-cli okr +upload-image \
+  --file ./progress_screenshot.png \
+  --target-id 1234567890123456789 \
+  --target-type objective
+
+# 上传图片用于关键结果的进展记录
+lark-cli okr +upload-image \
+  --file ./chart.jpg \
+  --target-id 9876543210987654321 \
+  --target-type key_result
+```
+
+## 参数
+
+| 参数              | 必填 | 默认值 | 说明                                    |
+|-----------------|----|-----|---------------------------------------|
+| `--file`        | 是  | —   | 本地图片路径。**必须使用相对路径**（如 `./photo.png`）。 |
+| `--target-id`   | 是  | —   | 目标 ID 或关键结果 ID（int64 类型，正整数）          |
+| `--target-type` | 是  | —   | 目标类型：`objective` \| `key_result`      |
+| `--dry-run`     | 否  | —   | 预览 API 调用而不实际执行。                      |
+
+## 工作流程
+
+1. 使用 `+cycle-list` 和 `+cycle-detail` 获取目标或关键结果的 ID。
+2. 准备本地图片文件，确保格式受支持。
+3. 执行 `lark-cli okr +upload-image --file ./image.png --target-id "..." --target-type objective`。
+4. 获取返回的 `file_token`，用于构建 ContentBlock 中的图片内容。
+
+## 输出
+
+返回 JSON：
+
+```json
+{
+  "file_token": "example-file-token",
+  "url": "https://example.larksuite.com/download?file_token=example-file-token",
+  "file_name": "screenshot.png",
+  "size": 102400
+}
+```
+
+其中：
+
+- `file_token` — 用于在 ContentBlock 的 `ContentGallery` 中引用图片
+- `url` — 图片的访问 URL
+- `file_name` — 上传的文件名
+- `size` — 文件大小（字节）
+
+## 在进展记录中使用上传的图片
+
+上传图片后，将返回的 `file_token` 用于构建 ContentBlock 的图库块：
+
+```json
+{
+  "blocks": [
+    {
+      "block_element_type": "paragraph",
+      "paragraph": {
+        "elements": [
+          {
+            "paragraph_element_type": "textRun",
+            "text_run": {
+              "text": "本周进展截图："
+            }
+          }
+        ]
+      }
+    },
+    {
+      "block_element_type": "gallery",
+      "gallery": {
+        "images": [
+          {
+            "file_token": "example-file-token",
+            "width": 800,
+            "height": 600
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+然后在创建或更新进展记录时使用此 ContentBlock：
+
+```bash
+lark-cli okr +progress-create \
+  --content @content_with_image.json \
+  --target-id 1234567890123456789 \
+  --target-type objective
+```
+
+## 安全限制
+
+- `--file` 参数**必须使用相对路径**（如 `./photo.png` 或 `images/photo.png`），不支持绝对路径
+- 图片文件必须存在于当前工作目录或其子目录中
+- 不支持符号链接指向目录外的文件
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令(shortcut 和 API 接口)
+- [ContentBlock 格式](lark-okr-contentblock.md) -- 进展内容使用的富文本格式，包含图片块的使用说明
+- [lark-okr-progress-create](lark-okr-progress-create.md) -- 创建进展记录
+- [lark-okr-progress-update](lark-okr-progress-update.md) -- 更新进展记录
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,81 @@
+# okr +progress-create
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+为目标（Objective）或关键结果（Key Result）创建一条 OKR 进展记录。
+
+## 推荐命令
+
+```bash
+# 为目标创建进展记录
+lark-cli okr +progress-create \
+  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"本周完成了核心模块开发"}}]}}]}' \
+  --target-id 1234567890123456789 \
+  --target-type objective
+
+# 为关键结果创建进展记录（带进度百分比和状态）
+lark-cli okr +progress-create \
+  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"指标已达到 80%"}}]}}]}' \
+  --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`          | 是  | —                     | 进展内容，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. 构造 ContentBlock JSON 格式的进展内容。请参考 [ContentBlock 格式](lark-okr-contentblock.md)。
+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/dist/skills/larksuite/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/dist/skills/larksuite/lark-okr/references/lark-okr-progress-get.md

@@ -0,0 +1,62 @@
+# okr +progress-get
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+根据进展记录 ID 获取单条 OKR 进展记录。
+
+## 推荐命令
+
+```bash
+# 获取指定 ID 的进展记录
+lark-cli okr +progress-get --progress-id 1234567890123456789
+
+# 使用特定的用户 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 类型，正整数）                         |
+| `--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：
+
+```json
+{
+  "progress": {
+    "progress_id": "1234567890123456789",
+    "modify_time": "2025-01-15 10:30:00",
+    "content": "{...}",
+    "progress_rate": {
+      "percent": 75.0,
+      "status": "normal"
+    }
+  }
+}
+```
+
+其中：
+
+- `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 接口)
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数