feat：移除了弹窗，服务器添加sls

.claude/skills/lark-okr/references/lark-okr-entities.md

@@ -0,0 +1,330 @@
+# 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) 的周期。如果仍然有多个，则选择其中较新的一个。当用户提及“上一个周期”，“下一个周期”一类的表述时，通常是以当前周期为准计算。
+  - 如果用户没有提及，那么当前周期一般不考虑年度周期（起止时间从 01-01 至 12-31 的周期）
+- **所有者**: 绝大多数所有者都是用户，少部分租户启用了“团队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) — 删除进展记录