@yandy0725/pi-lark 0.1.0

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

@@ -0,0 +1,90 @@
+# okr +cycle-list
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+列出指定用户的 OKR 周期，支持可选的时间范围过滤。
+
+## 推荐命令
+
+```bash
+# 列出用户的所有周期
+lark-cli okr +cycle-list --user-id "ou_xxx"
+
+# 使用特定的用户 ID 类型列出周期
+lark-cli okr +cycle-list --user-id "xxx" --user-id-type user_id
+
+# 列出时间范围内的周期（例如 2025-01 到 2025-06）
+lark-cli okr +cycle-list --user-id "ou_xxx" --time-range "2025-01--2025-06"
+
+# 预览 API 调用而不实际执行
+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`）。留空获取所有周期。 |
+| `--dry-run`      | 否  | —         | 预览 API 调用而不实际执行。                                                 |
+| `--format`       | 否  | `json`    | 输出格式。                                                            |
+
+## 工作流程
+
+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、开始/结束时间和状态。
+
+## 输出
+
+返回 JSON：
+
+```json
+{
+  "cycles": [
+    {
+      "id": "1234567890123456789",
+      "create_time": "2025-01-01 00:00:00",
+      "update_time": "2025-01-01 00:00:00",
+      "tenant_cycle_id": "789",
+      "owner": {
+        "owner_type": "user",
+        "user_id": "ou_xxx"
+      },
+      "start_time": "2025-01-01 00:00:00",
+      "end_time": "2025-06-30 00:00:00",
+      "cycle_status": "normal",
+      "score": 0
+    }
+  ],
+  "total": 1
+}
+```
+
+在这个周期信息中，这些字段值得关注：
+
+- `id` 是这个周期的 ID，你通常需要用它在之后使用 `okr +cycle-detail` 获取 OKR 内容详情
+- `start_time` `end_time` 是周期的起止时间，总是从某个月1日开始，直到此月或之后某月的最后一日结束。
+    - 在 OKR 系统中，我们只关注这个时间的年月部分，如 “2025-01-01开始，2025-06-30结束” 的周期被称作 “2025 年 1-6 月” 周期，而
+      “2025-01-01开始，2025-01-31结束” 的周期被称作 “2025 年 1 月”周期。
+    - 如果一个周期从某年1月1日开始，某年12月31日结束，则它是这一年的年度周期，如 “2025-01-01开始，2025-12-31结束” 的周期就是
+      “2025 年” 的年度周期
+- `cycle_status` 为周期状态值，参见下文。
+
+### 周期状态值
+
+| 值         | 说明       |
+|-----------|----------|
+| `default` | 默认状态 (0) |
+| `normal`  | 生效 (1)   |
+| `invalid` | 失效 (2)   |
+| `hidden`  | 隐藏 (3)   |
+
+在 OKR 系统中，default/normal 状态下的周期当前正常生效，invalid 状态下的周期已失效但通常仍然可以填写，hidden 状态下的周期隐藏不可见。
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/skills/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/skills/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/skills/lark-okr/references/lark-okr-indicator-update.md

@@ -0,0 +1,80 @@
+# okr +indicator-update
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+直接更新目标（Objective）或关键结果（Key Result）的指标当前值，无需手动查询指标 ID。
+
+> **查询指标：** 如需查看指标详情，请使用原生 API：
+> - 目标指标：`lark-cli okr objective.indicators list --objective-id <id>`
+> - KR 指标：`lark-cli okr key_result.indicators list --key-result-id <id>`
+
+## 推荐命令
+
+```bash
+# 更新 Objective 的指标值
+lark-cli okr +indicator-update \
+  --level objective \
+  --id 7000000000000000001 \
+  --value 75.5 \
+  --as user
+
+# 更新 Key Result 的指标值
+lark-cli okr +indicator-update \
+  --level key-result \
+  --id 7000000000000000002 \
+  --value 100 \
+  --as user
+```
+
+## 参数
+
+| 参数         | 必填 | 默认值    | 说明                                                                 |
+|------------|----|--------|--------------------------------------------------------------------|
+| `--level`  | 是  | —      | 操作层级：`objective`（更新目标指标）\| `key-result`（更新 KR 指标） |
+| `--id`     | 是  | —      | 目标 ID 或 KR ID（int64 类型）                                       |
+| `--value`  | 是  | —      | 新的指标当前值（数字，范围：-99999999999 到 99999999999）              |
+| `--dry-run`| 否  | —      | 预览 API 调用而不实际执行                                            |
+| `--format` | 否  | `json` | 输出格式                                                             |
+
+## 工作流程
+
+1. 使用 `+cycle-list` 和 `+cycle-detail` 获取目标 ID 或 KR ID。
+2. 如需查看当前指标值，使用 `objective.indicators list` 或 `key_result.indicators list` 查询。
+3. 执行 `+indicator-update` 指定层级、ID 和新值。
+4. 命令自动查询指标 ID 并更新当前值。
+
+## 输出
+
+### JSON 格式
+
+```json
+{
+  "ok": true,
+  "data": {
+    "indicator_id": "7000000000000000003",
+    "current_value": 75.5,
+    "level": "objective",
+    "target_id": "7000000000000000001"
+  }
+}
+```
+
+### 字段说明
+
+| 字段             | 类型     | 说明                     |
+|----------------|--------|------------------------|
+| `indicator_id` | string | 被更新的指标 ID            |
+| `current_value`| number | 更新后的指标当前值           |
+| `level`        | string | 操作层级：`objective` / `key-result` |
+| `target_id`    | string | 目标或 KR 的 ID            |
+
+## 注意事项
+- 仅更新 `current_value` 字段，`unit`、`start_value`、`target_value` 等其他字段保持不变
+  - 若需要这些字段进行修改，使用原生接口 indicators.patch
+- 指标的 `current_value_calculate_type` 必须为「手动更新」才能通过此命令修改。
+
+## 参考
+
+- [OKR 指标更新 API](https://open.feishu.cn/api-explorer?from=op_doc_tab&apiName=patch&project=okr&resource=okr.indicator&version=v2)
+- [`lark-okr-progress-create.md`](./lark-okr-progress-create.md) — 创建进度记录
+- [`lark-okr-cycle-detail.md`](./lark-okr-cycle-detail.md) — 查询周期详情获取 ID