@yandy0725/pi-lark 0.1.0

package/skills/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/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,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) -- 认证和全局参数

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) -- 认证和全局参数

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

@@ -0,0 +1,81 @@
+# okr +progress-update
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+更新指定 ID 的 OKR 进展记录内容。
+
+## 推荐命令
+
+```bash
+# 更新进展记录内容
+lark-cli okr +progress-update \
+  --progress-id 1234567890123456789 \
+  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"更新后的进展内容"}}]}}]}'
+
+# 更新进展记录内容并同时更新进度
+lark-cli okr +progress-update \
+  --progress-id 1234567890123456789 \
+  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"进度已更新至 90%"}}]}}]}' \
+  --progress-percent 90 \
+  --progress-status normal
+
+# 从文件读取 content（适用于较长的进展内容）
+lark-cli okr +progress-update \
+  --progress-id 1234567890123456789 \
+  --content @updated_progress.json
+
+# 预览 API 调用而不实际执行
+lark-cli okr +progress-update \
+  --progress-id 1234567890123456789 \
+  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"test"}}]}}]}' \
+  --dry-run
+```
+
+## 参数
+
+| 参数                   | 必填 | 默认值       | 说明                                                                                                             |
+|----------------------|----|-----------|----------------------------------------------------------------------------------------------------------------|
+| `--progress-id`      | 是  | —         | 进展记录 ID（int64 类型，正整数）                                                                                          |
+| `--content`          | 是  | —         | 进展内容，ContentBlock JSON 格式。支持 `@文件路径` 从文件读取。请参考 [ContentBlock 格式](lark-okr-contentblock.md)。                    |
+| `--progress-percent` | 否  | —         | 进度百分比(-99999999999 - 99999999999)。百分比的取值通常在 0-100，但允许超过此范围，以表示超额完成或负增长等情况。挂载的目标或关键结果的量化指标不使用百分比单位时，以这个字段更新当前值。系统内最多保留两位小数 |
+| `--progress-status`  | 否  | —         | 进度状态：`normal`（正常） \| `overdue`（逾期） \| `done`（已完成）。仅在指定 `--progress-percent` 时生效。                               |
+| `--user-id-type`     | 否  | `open_id` | 用户 ID 类型：`open_id` \| `union_id` \| `user_id`                                                                  |
+| `--dry-run`          | 否  | —         | 预览 API 调用而不实际执行。                                                                                               |
+| `--format`           | 否  | `json`    | 输出格式。                                                                                                          |
+
+## 工作流程
+
+1. 使用 `+progress-get` 获取要更新的进展记录的 ID 和当前内容。
+2. 修改 ContentBlock JSON 格式的进展内容。请参考 [ContentBlock 格式](lark-okr-contentblock.md)。
+3. 执行 `lark-cli okr +progress-update --progress-id "..." --content "..."`。
+4. 报告结果：更新后的进展记录 ID、修改时间、进度百分比等。
+
+## 输出
+
+返回 JSON：
+
+```json
+{
+  "progress": {
+    "progress_id": "1234567890123456789",
+    "modify_time": "2025-01-15 14:30:00",
+    "content": "{...}",
+    "progress_rate": {
+      "percent": 90.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 接口)
+- [ContentBlock 格式](lark-okr-contentblock.md) -- 进展内容使用的富文本格式
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,81 @@
+# okr +reorder
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+调整 OKR 周期下目标（Objective）或目标下关键结果（Key Result）的顺序。
+
+## 推荐命令
+
+```bash
+# 调整 Objective 顺位
+lark-cli okr +reorder \
+  --cycle-id 7000000000000000001 \
+  --level objective \
+  --ops '[
+    {"id": "7000000000000000002", "position": 2},
+    {"id": "7000000000000000003", "position": 1}
+  ]' \
+  --as user
+
+# 调整 KR 顺位（需指定 --objective-id）
+lark-cli okr +reorder \
+  --cycle-id 7000000000000000001 \
+  --level key-result \
+  --objective-id 7000000000000000002 \
+  --ops '[
+    {"id": "7000000000000000004", "position": 1},
+    {"id": "7000000000000000005", "position": 2}
+  ]' \
+  --as user
+
+# 从文件读取 ops
+lark-cli okr +reorder \
+  --cycle-id 7000000000000000001 \
+  --level objective \
+  --ops @reorder_ops.json \
+  --as user
+```
+
+- 不允许将多个 objective/key-result 放在同一个位置下
+
+## 参数
+
+| 参数               | 必填 | 默认值    | 说明                                                      |
+|------------------|----|--------|---------------------------------------------------------|
+| `--level`        | 是  | —      | 调整层级：`objective`（调整周期下目标顺序）\| `key-result`（调整目标下 KR 顺序） |
+| `--cycle-id`     | 是  | —      | OKR 周期 ID（int64 类型）。                                    |
+| `--objective-id` | 条件 | —      | 目标 ID。当 `--level=key-result` 时**必填**，用于定位父目标。           |
+| `--ops`          | 是  | —      | JSON 数组格式的顺位调整操作。支持 `@文件路径` 或 `@-` 从 stdin 读取。          |
+| `--dry-run`      | 否  | —      | 预览 API 调用而不实际执行                                         |
+| `--format`       | 否  | `json` | 输出格式                                                    |
+
+## 工作流程
+
+1. 使用 `+cycle-list` 和 `+cycle-detail` 获取周期 ID、目标 ID 和 KR ID。
+2. 构造 `--ops` JSON 数组，指定要调整的 ID 和新 position，执行命令。
+3. 返回调整后的完整顺序。
+
+## 输出
+
+成功返回 JSON（以调整 Objective 位置为例）：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "level": "objective",
+    "cycle_id": "7000000000000000001",
+    "total": 3,
+    "ordered": [
+      "7000000000000000003",
+      "7000000000000000002",
+      "7000000000000000004"
+    ]
+  }
+}
+```
+
+## 参考
+
+- [OKR 业务实体](lark-okr-entities.md) -- OKR 实体结构定义
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,96 @@
+# okr +weight
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+调整 OKR 周期下目标（Objective）或目标下关键结果（Key Result）的权重。支持部分指定权重，未指定的按原权重比例自动分配。
+
+## 推荐命令
+
+```bash
+# 调整 Objective 权重（部分指定，剩余自动分配）
+lark-cli okr +weight \
+  --cycle-id 7000000000000000001 \
+  --level objective \
+  --weights '[
+    {"id": "7000000000000000002", "weight": 0.6},
+    {"id": "7000000000000000003", "weight": 0.3}
+  ]' \
+  --as user
+
+# 调整 KR 权重（全部指定，和为 1）
+lark-cli okr +weight \
+  --cycle-id 7000000000000000001 \
+  --level key-result \
+  --objective-id 7000000000000000002 \
+  --weights '[
+    {"id": "7000000000000000004", "weight": 0.6},
+    {"id": "7000000000000000005", "weight": 0.4}
+  ]' \
+  --as user
+
+# 从文件读取 weights
+lark-cli okr +weight \
+  --cycle-id 7000000000000000001 \
+  --level objective \
+  --weights @weights.json \
+  --as user
+```
+
+参数限制: 请求中的权重保留三位小数，分配的所有权重和不能大于 1 (小于等于 1 是允许的)。
+
+### 权重归一化
+
+- 在 OKR 中，一个周期下所有 Objective 和 一个 Objective 下所有 Key Result 的权重和固定为 1.
+- 在使用 +weight shortcut 分配 OKR 权重时，已分配的总权重不得超过 1。
+- 若已分配的权重 < 1，剩余的权重会按照原始权重的比例均分到未指定的 Objective/Key Result 下。
+  - 若所有 Objective/Key Result 均分配了权重但和 < 1，剩余的权重会计算在最后一个 Objective/Key Result 下。
+
+
+
+## 参数
+
+| 参数               | 必填 | 默认值    | 说明                                                                  |
+|------------------|----|--------|---------------------------------------------------------------------|
+| `--level`        | 是  | —      | 调整层级：`objective`（调整周期下目标权重）\| `key-result`（调整目标下 KR 权重）             |
+| `--cycle-id`     | 是  | —      | OKR 周期 ID（int64 类型）                                                 |
+| `--objective-id` | 条件 | —      | 目标 ID。当 `--level=key-result` 时**必填**，用于定位父目标。                       |
+| `--weights`      | 是  | —      | JSON 数组格式的权重分配。支持 `@文件路径` 或 `@-` 从 stdin 读取。权重保留三位小数，分配的所有权重和不能大于 1 |
+| `--dry-run`      | 否  | —      | 预览 API 调用而不实际执行                                                     |
+| `--format`       | 否  | `json` | 输出格式                                                                |
+
+## 工作流程
+
+1. 使用 `+cycle-list` 和 `+cycle-detail` 获取周期 ID、目标 ID、KR ID 和当前权重。
+2. 构造 `--weights` JSON 数组，指定要调整的 ID 和权重，执行命令。
+3. 返回调整后的完整权重列表。
+
+## 输出
+
+成功返回 JSON：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "level": "objective",
+    "cycle_id": "7000000000000000001",
+    "total": 3,
+    "weights": [
+      {"id": "7000000000000000002", "weight": 0.6},
+      {"id": "7000000000000000003", "weight": 0.3},
+      {"id": "7000000000000000004", "weight": 0.1}
+    ]
+  }
+}
+```
+
+## 关于 1001001 错误
+
+有时，即使输入的参数完全正确， +weight 也会返回 1001001 错误。这是因为你的租户设置中，不一定开启了目标或关键结果的设置权重功能。
+若你确认输入的参数无误（cycle-id/objective-id 正确，weights 中的 id 均是同一个周期下的目标或同一个目标下的关键结果，weights 中的权重和 <1）,
+不必进一步尝试，你需要向用户确认 OKR 应用目前是否开启了目标或关键结果的设置权重功能。
+
+## 参考
+
+- [OKR 业务实体](lark-okr-entities.md) -- OKR 实体结构定义
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数