@yandy0725/pi-lark 0.1.0

package/skills/lark-okr/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: lark-okr
+version: 1.0.0
+description: "飞书 OKR：管理目标与关键结果。查看和编辑 OKR 周期、目标、关键结果、对齐关系、量化指标和进展记录。当用户需要查看或创建 OKR、管理目标和关键结果、查看对齐关系时使用。不负责：待办任务管理（lark-task）、日程/会议安排（lark-calendar）、绩效评估"
+metadata:
+  requires:
+    bins: [ "lark-cli" ]
+  cliHelp: "lark-cli okr --help"
+---
+
+# okr (v2)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+**身份**：OKR 操作默认使用 `--as user`（查看当前用户/上下级的 OKR 时）。也支持 `--as bot` 查看他人 OKR（需相应权限）。
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli okr +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut                                                       | 说明                       |
+|----------------------------------------------------------------|--------------------------|
+| [`+cycle-list`](references/lark-okr-cycle-list.md)             | 获取特定用户的 OKR 周期列表，可以按时间筛选 |
+| [`+cycle-detail`](references/lark-okr-cycle-detail.md)         | 获取特定 OKR 中所有目标和关键结果的内容   |
+| [`+progress-list`](references/lark-okr-progress-list.md)       | 获取目标或关键结果的所有进展记录列表       |
+| [`+progress-get`](references/lark-okr-progress-get.md)         | 根据 ID 获取单条 OKR 进展记录      |
+| [`+progress-create`](references/lark-okr-progress-create.md)   | 为目标或关键结果创建进展记录           |
+| [`+progress-update`](references/lark-okr-progress-update.md)   | 更新指定 ID 的进展记录内容          |
+| [`+progress-delete`](references/lark-okr-progress-delete.md)   | 删除指定 ID 的进展记录（不可恢复）      |
+| [`+upload-image`](references/lark-okr-image-upload.md)         | 上传图片用于 OKR 进展记录的富文本内容    |
+| [`+batch-create`](references/lark-okr-batch-create.md)         | 批量创建 Objective 和 KR      |
+| [`+reorder`](references/lark-okr-reorder.md)                   | 调整 Objective 或 KR 的顺位    |
+| [`+weight`](references/lark-okr-weight.md)                     | 调整 Objective 或 KR 的权重    |
+| [`+indicator-update`](references/lark-okr-indicator-update.md) | 更新 Objective 或 KR 的指标当前值 |
+
+## 格式说明
+
+- [`OKR 业务实体`](references/lark-okr-entities.md) 获取 OKR 实体结构，定义和关系，帮助你更好的使用 OKR 功能
+- [`ContentBlock 富文本格式`](references/lark-okr-contentblock.md) — Objective/KeyResult/Progress 中 Content/Note 字段使用的富文本格式说明
+- **强烈建议** 在操作 OKR 前，阅读[`OKR 业务实体`](references/lark-okr-entities.md)以了解基础概念
+
+## API Resources
+
+### alignments
+
+- `delete` — 删除对齐关系
+- `get` — 获取对齐关系
+
+### categories
+
+- `list` — 批量获取分类
+
+### cycles
+
+- `list` — 批量获取用户周期
+- `objectives_position` — 更新用户周期下全部目标的位置
+    - 请求中必须携带对应周期下全部目标的 ID，否则会参数校验失败。以传入的目标ID顺序重新排列目标。
+- `objectives_weight` — 更新用户周期下全部目标的权重
+    - 请求中必须同时修改对应周期下全部目标的权重，且所有权重值的和必须等于 1 ，否则会参数校验失败。例如周期下有 2 个目标时：
+    - 正确指令示例如下：
+      ``` bash
+      lark-cli okr cycles objectives_weight --params '{"cycle_id": "7000000000000000001"}' --data '{"objective_weights": [{"objective_id": "7000000000000000002", "weight": 0.7}, {"objective_id": "7000000000000000003", "weight": 0.3}]}' --as user
+      ```
+
+### cycle.objectives
+
+- `create` — 创建目标
+- `list` — 批量获取用户周期下的目标
+
+### indicators
+
+- `patch` — 更新量化指标
+
+### key_results
+
+- `delete` — 删除关键结果
+- `get` — 获取关键结果
+- `patch` — 更新关键结果
+
+### key_result.indicators
+
+- `list` — 获取关键结果的量化指标
+
+### objectives
+
+- `delete` — 删除目标
+- `get` — 获取目标
+- `key_results_position` — 更新全部关键结果的位置
+    - 请求中必须携带对应周期下全部关键结果的 ID，否则会参数校验失败。以传入的关键结果ID顺序重新排列关键结果。
+- `key_results_weight` — 更新全部关键结果的权重
+    - 类似 `objectives_weight`, 请求中必须同时修改对应目标下全部关键结果的权重，且所有权重值的和必须等于 1 ，否则会参数校验失败。
+- `patch` — 更新目标
+
+### objective.alignments
+
+- `create` — 创建对齐关系
+    - 对齐不允许对齐自己的目标，且发起对齐的目标和被对齐的目标所在周期时间上必须有重叠，否则会参数校验失败。
+- `list` — 批量获取目标下的对齐关系
+
+### objective.indicators
+
+- `list` — 获取目标的量化指标
+
+### objective.key_results
+
+- `create` — 创建关键结果
+- `list` — 批量获取目标下的关键结果
+
+## 不在本 skill 范围
+
+- 待办任务管理 → 使用 [`lark-task`](../lark-task/SKILL.md)
+- 日程安排 → 使用 [`lark-calendar`](../lark-calendar/SKILL.md)
+- 绩效评估 → 使用 [`lark-openapi-explorer`](../lark-openapi-explorer/SKILL.md) 查找原生接口
+
+

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

@@ -0,0 +1,106 @@
+# okr +batch-create
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+批量创建 OKR 目标（Objective）和关键结果（Key Result）。
+
+## 推荐命令
+
+```bash
+# 批量创建 2 个 Objective，各带 2 个 KR。
+lark-cli okr +batch-create \
+  --cycle-id 7000000000000000001 \
+  --input '[
+    {
+      "text": "提升产品用户体验",
+      "mention": ["ou_xxxxxxxx"],
+      "krs": [
+        {"text": "页面加载速度提升 50%", "mention": ["ou_yyyyyyyy"]},
+        {"text": "用户满意度达到 4.8 分"}
+      ]
+    },
+    {
+      "text": "拓展新市场份额",
+      "krs": [
+        {"text": "新增 10 个城市覆盖"},
+        {"text": "市场份额提升至 25%"}
+      ]
+    }
+  ]' \
+  --as user
+
+# 从文件读取输入
+lark-cli okr +batch-create \
+  --cycle-id 7000000000000000001 \
+  --input @okr_batch.json \
+  --as user
+
+# 预览 API 调用（Dry-run）
+lark-cli okr +batch-create \
+  --cycle-id 7000000000000000001 \
+  --input @okr_batch.json \
+  --dry-run \
+  --as user
+```
+- mention 是可选参数，不需要使用“@”提及其他用户时不传入。
+  - 传入的 mention 参数会以 @对应用户的形式，添加在文本后。
+
+## 参数
+
+| 参数               | 必填 | 默认值       | 说明                                                         |
+|------------------|----|-----------|------------------------------------------------------------|
+| `--cycle-id`     | 是  | —         | OKR 周期 ID（int64 类型）                                        |
+| `--input`        | 是  | —         | JSON 数组格式的 Objective 列表。支持 `@文件路径` 从文件读取或 `@-` 从 stdin 读取。 |
+| `--user-id-type` | 否  | `open_id` | mention 中使用的用户 ID 类型：`open_id` \| `union_id` \| `user_id`  |
+| `--dry-run`      | 否  | —         | 预览 API 调用而不实际执行                                            |
+| `--format`       | 否  | `json`    | 输出格式                                                       |
+
+## 输入格式
+
+```json
+[
+  {
+    "text": "Objective 内容",
+    "mention": ["ou_xxxxxxxx", "ou_yyyyyyyy"],
+    "krs": [
+      {
+        "text": "KR 内容",
+        "mention": ["ou_zzzzzzzz"]
+      }
+    ]
+  }
+]
+```
+
+## 工作流程
+
+1. 使用 `+cycle-list` 获取可用的 OKR 周期 ID
+2. 构造 `--input` JSON 数组，包含要创建的 Objective 和 KR
+3. 执行 `lark-cli okr +batch-create --cycle-id <id> --input '...'`
+
+## 输出
+
+成功返回 JSON：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "created": [
+      {
+        "objective_id": "7000000000000000002",
+        "krs": ["7000000000000000003", "7000000000000000004"]
+      },
+      {
+        "objective_id": "7000000000000000005",
+        "krs": ["7000000000000000006"]
+      }
+    ]
+  }
+}
+```
+
+## 参考
+
+- [OKR 业务实体](lark-okr-entities.md) -- OKR 实体结构定义
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,359 @@
+# OKR ContentBlock 富文本格式
+
+OKR 的 Objective、KeyResult 中的 content/notes 字段使用 `ContentBlock` 富文本格式。本文档描述其结构和使用方式。
+
+## ContentBlock 结构概览
+
+```json
+{
+  "blocks": [
+    {
+      "block_element_type": "paragraph",
+      "paragraph": {
+        "style": {
+          "list": {
+            "list_type": "bullet",
+            "indent_level": 0,
+            "number": 1
+          }
+        },
+        "elements": [
+          {
+            "paragraph_element_type": "textRun",
+            "text_run": {
+              "text": "Hello World",
+              "style": {
+                "bold": true,
+                "strike_through": false,
+                "back_color": {
+                  "red": 255,
+                  "green": 0,
+                  "blue": 0,
+                  "alpha": 1
+                },
+                "text_color": {
+                  "red": 0,
+                  "green": 255,
+                  "blue": 0,
+                  "alpha": 1
+                },
+                "link": {
+                  "url": "https://example.com"
+                }
+              }
+            }
+          },
+          {
+            "paragraph_element_type": "docsLink",
+            "docs_link": {
+              "url": "https://larkoffice.com/docx/xxx",
+              "title": "Lark Document"
+            }
+          },
+          {
+            "paragraph_element_type": "mention",
+            "mention": {
+              "user_id": "ou_xxx"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "block_element_type": "gallery",
+      "gallery": {
+        "images": [
+          {
+            "file_token": "file_xxx",
+            "src": "https://...",
+            "width": 800,
+            "height": 600
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+## 类型定义
+
+### ContentBlock
+
+根级别内容块。
+
+| 字段       | 类型                      | 说明      |
+|----------|-------------------------|---------|
+| `blocks` | `ContentBlockElement[]` | 内容块元素数组 |
+
+### ContentBlockElement
+
+内容块元素，支持段落或图库。
+
+| 字段                   | 类型                 | 说明                                         |
+|----------------------|--------------------|--------------------------------------------|
+| `block_element_type` | `BlockElementType` | 块类型：`paragraph` \| `gallery`               |
+| `paragraph`          | `ContentParagraph` | 段落内容（当 `block_element_type="paragraph"` 时） |
+| `gallery`            | `ContentGallery`   | 图库内容（当 `block_element_type="gallery"` 时）   |
+
+### ContentParagraph
+
+段落内容。
+
+| 字段         | 类型                          | 说明          |
+|------------|-----------------------------|-------------|
+| `style`    | `ContentParagraphStyle`     | 段落样式（列表类型等） |
+| `elements` | `ContentParagraphElement[]` | 段落内元素数组     |
+
+### ContentParagraphElement
+
+段落内元素，支持文本、文档链接、提及。
+
+| 字段                       | 类型                     | 说明                                        |
+|--------------------------|------------------------|-------------------------------------------|
+| `paragraph_element_type` | `ParagraphElementType` | 元素类型：`textRun` \| `docsLink` \| `mention` |
+| `text_run`               | `ContentTextRun`       | 文本内容                                      |
+| `docs_link`              | `ContentDocsLink`      | 飞书文档链接                                    |
+| `mention`                | `ContentMention`       | 用户提及                                      |
+
+### ContentTextRun
+
+文本块。
+
+| 字段      | 类型                 | 说明   |
+|---------|--------------------|------|
+| `text`  | `string`           | 文本内容 |
+| `style` | `ContentTextStyle` | 文本样式 |
+
+### ContentTextStyle
+
+文本样式。
+
+| 字段               | 类型             | 说明    |
+|------------------|----------------|-------|
+| `bold`           | `boolean`      | 是否粗体  |
+| `strike_through` | `boolean`      | 是否删除线 |
+| `back_color`     | `ContentColor` | 背景颜色  |
+| `text_color`     | `ContentColor` | 文字颜色  |
+| `link`           | `ContentLink`  | 链接    |
+
+### ContentColor
+
+颜色。
+
+| 字段      | 类型        | 说明           |
+|---------|-----------|--------------|
+| `red`   | `int32`   | 红色通道 (0-255) |
+| `green` | `int32`   | 绿色通道 (0-255) |
+| `blue`  | `int32`   | 蓝色通道 (0-255) |
+| `alpha` | `float64` | 透明度 (0-1)    |
+
+### ContentParagraphStyle
+
+段落样式。
+
+| 字段     | 类型            | 说明   |
+|--------|---------------|------|
+| `list` | `ContentList` | 列表样式 |
+
+### ContentList
+
+列表样式。
+
+| 字段             | 类型         | 说明                                                                  |
+|----------------|------------|---------------------------------------------------------------------|
+| `list_type`    | `ListType` | 列表类型：`bullet` \| `number` \| `checkBox` \| `checkedBox` \| `indent` |
+| `indent_level` | `int32`    | 缩进层级                                                                |
+| `number`       | `int32`    | 序号（当 `list_type="number"` 时）                                        |
+
+### ContentGallery
+
+图片块。目前仅有进展记录中的富文本支持展示图片。
+
+由于 OKR 应用中进展页面的布局排版限制，一个 ContentGallery 元素中**仅可放置一个图片元素**，需要插入多张图片时需使用多个 ContentGallery 元素
+(同一个 ContentGallery 中添加多个 image 会导致这些图片在狭窄的横向排版空间中互相挤占，效果很差)
+
+| 字段       | 类型                   | 说明    |
+|----------|----------------------|-------|
+| `images` | `ContentImageItem[]` | 图片项数组 |
+
+### ContentImageItem
+
+图片项。
+
+| 字段           | 类型        | 说明       |
+|--------------|-----------|----------|
+| `file_token` | `string`  | 文件 token |
+| `src`        | `string`  | 图片 URL   |
+| `width`      | `float64` | 宽度       |
+| `height`     | `float64` | 高度       |
+
+> **如何获取 `file_token`？** 使用 [`+upload-image`](lark-okr-image-upload.md) 命令上传本地图片，返回的 `file_token` 可用于构建 `ContentGallery` 图片块。
+
+### ContentDocsLink
+
+飞书文档链接。
+
+| 字段      | 类型       | 说明     |
+|---------|----------|--------|
+| `url`   | `string` | 链接 URL |
+| `title` | `string` | 链接标题   |
+
+### ContentMention
+
+提及。
+
+| 字段        | 类型       | 说明    |
+|-----------|----------|-------|
+| `user_id` | `string` | 用户 ID |
+
+### ContentLink
+
+链接。
+
+| 字段    | 类型       | 说明     |
+|-------|----------|--------|
+| `url` | `string` | 链接 URL |
+
+## 使用示例
+
+### 示例 1：简单文本段落
+
+```json
+{
+  "blocks": [
+    {
+      "block_element_type": "paragraph",
+      "paragraph": {
+        "elements": [
+          {
+            "paragraph_element_type": "textRun",
+            "text_run": {
+              "text": "提升用户满意度"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### 示例 2：带格式的文本段落
+
+```json
+{
+  "blocks": [
+    {
+      "block_element_type": "paragraph",
+      "paragraph": {
+        "elements": [
+          {
+            "paragraph_element_type": "textRun",
+            "text_run": {
+              "text": "Q2 目标",
+              "style": {
+                "bold": true
+              }
+            }
+          },
+          {
+            "paragraph_element_type": "textRun",
+            "text_run": {
+              "text": " - 提升产品质量"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### 示例 3：带列表的段落
+
+```json
+{
+  "blocks": [
+    {
+      "block_element_type": "paragraph",
+      "paragraph": {
+        "style": {
+          "list": {
+            "list_type": "bullet",
+            "indent_level": 0
+          }
+        },
+        "elements": [
+          {
+            "paragraph_element_type": "textRun",
+            "text_run": {
+              "text": "完成功能开发"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "block_element_type": "paragraph",
+      "paragraph": {
+        "style": {
+          "list": {
+            "list_type": "bullet",
+            "indent_level": 0
+          }
+        },
+        "elements": [
+          {
+            "paragraph_element_type": "textRun",
+            "text_run": {
+              "text": "进行用户测试"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### 示例 4：带用户提及和图片（仅进展记录支持）的段落
+
+```json
+{
+  "blocks": [
+    {
+      "block_element_type": "paragraph",
+      "paragraph": {
+        "elements": [
+          {
+            "paragraph_element_type": "mention",
+            "mention": {
+              "user_id": "ou_example_user"
+            }
+          },
+          {
+            "paragraph_element_type": "textRun",
+            "text_run": {
+              "text": " 请关注此进度并查看以下图片"
+            }
+          }
+        ]
+      }
+    },
+    {
+      "block_element_type": "gallery",
+      "gallery": {
+        "images": [
+          {
+            "file_token": "img_example_token",
+            "src": "https://example.com/image.png",
+            "width": 800,
+            "height": 600
+          }
+        ]
+      }
+    }
+  ]
+}
+```

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

@@ -0,0 +1,84 @@
+# okr +cycle-detail
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+列出指定 OKR 周期下的所有目标及其关键结果。
+
+## 推荐命令
+
+```bash
+# 列出指定周期的目标和关键结果
+lark-cli okr +cycle-detail --cycle-id 1234567890123456789
+
+# 预览 API 调用而不实际执行
+lark-cli okr +cycle-detail --cycle-id 1234567890123456789 --dry-run
+```
+
+## 参数
+
+| 参数           | 必填 | 默认值    | 说明                                      |
+|--------------|----|--------|-----------------------------------------|
+| `--cycle-id` | 是  | —      | OKR 周期 ID（int64 类型）。从 `+cycle-list` 获取。 |
+| `--dry-run`  | 否  | —      | 预览 API 调用而不实际执行。                        |
+| `--format`   | 否  | `json` | 输出格式。                                   |
+
+## 工作流程
+
+1. 使用 `lark-cli okr +cycle-list` 获取 OKR 周期 ID。
+2. 执行 `lark-cli okr +cycle-detail --cycle-id "123456"`。
+3. 报告结果：找到的目标数量、每个目标的 ID、分数、权重及其关键结果。
+
+## 输出
+
+返回 JSON：
+
+```json
+{
+  "cycle_id": "1234567890123456789",
+  "objectives": [
+    {
+      "id": "2345678901234567890",
+      "create_time": "2025-01-01 00:00:00",
+      "update_time": "2025-01-15 12:00:00",
+      "owner": {
+        "owner_type": "user",
+        "user_id": "ou_xxx"
+      },
+      "cycle_id": "1234567890123456789",
+      "position": 0,
+      "score": 0.75,
+      "weight": 1.0,
+      "deadline": "2025-06-30 23:59:59",
+      "category_id": "cat_456",
+      "content": "{...}",
+      "notes": "{...}",
+      "key_results": [
+        {
+          "id": "3456789012345678901",
+          "create_time": "2025-01-01 00:00:00",
+          "update_time": "2025-01-15 12:00:00",
+          "owner": {
+            "owner_type": "user",
+            "user_id": "ou_xxx"
+          },
+          "objective_id": "2345678901234567890",
+          "position": 0,
+          "score": 0.8,
+          "weight": 0.5,
+          "deadline": "2025-06-30 23:59:59",
+          "content": "{...}"
+        }
+      ]
+    }
+  ],
+  "total": 1
+}
+```
+
+其中，content 和 notes 字段是 JSON 字符串，为 OKR ContentBlock
+富文本格式。请参考 [lark-okr-contentblock.md](lark-okr-contentblock.md) 了解详细信息。
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令(shortcut 和 API 接口)
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数