pi-feishu-cli 0.1.0

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

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