@amaster.ai/pi-lark 0.1.3 → 0.1.5

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

@@ -0,0 +1,427 @@
+# OKR ContentBlock 富文本格式
+
+OKR 的 Objective、KeyResult 中的 content/notes 字段使用 `ContentBlock` 富文本格式。本文档描述其结构和使用方式。
+
+## 两种输入输出风格
+
+OKR shortcuts 支持 `--style` 标志控制 content/notes 字段的输入输出格式：
+
+| `--style` 值  | 说明                                                                 | 适用场景                     |
+|--------------|--------------------------------------------------------------------|--------------------------|
+| `simple`（默认） | 半纯文本格式 `SemiPlainContent`，简化的 JSON 结构，仅包含 text、mention、docs、images | 大多数场景，简单易用               |
+| `richtext`   | 原始 `ContentBlock` 富文本格式，完整的块结构和样式信息                                | 需要精确控制@提及用户位置、包含图片/文档链接时 |
+
+**重要**：输入时严格根据 `--style` 值验证格式，不会自动检测。输出时读操作（如 `+cycle-detail`、`+progress-get`）根据 `--style` 返回对应格式。
+
+## 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 |
+
+## SemiPlainContent 半纯文本格式
+
+`SemiPlainContent` 是 `ContentBlock` 的简化、有损表示形式，适用于大多数不需要复杂格式的场景。
+
+### 结构
+
+```json
+{
+  "text": "任务一 @{ou_zhangsan} ，任务二 @{ou_lisi} ",
+  "mention": ["ou_zhangsan", "ou_lisi"],
+  "docs": [
+    {
+      "title": "产品需求文档",
+      "url": "https://larkoffice.com/docx/xxx"
+    }
+  ],
+  "images": [
+    "https://example.com/image.png"
+  ]
+}
+```
+
+### 类型定义
+
+| 字段        | 类型               | 说明                                                                                                        |
+|-----------|------------------|-----------------------------------------------------------------------------------------------------------|
+| `text`    | `string`         | 纯文本内容（必填，不能为空）。**输出时**包含 ` @{userID} ` 占位符以保留提及的位置上下文；**输入时** `@{...}` 占位符会被自动 strip 掉，只识别 `mention` 字段内容 |
+| `mention` | `string[]`       | 用户 ID 列表（可选），与 text 中的 `@{userID}` 占位符一一对应，输入时按顺序转换为 mention 元素**置于文本末尾**                                 |
+| `docs`    | `SemiPlainDoc[]` | 文档列表（仅输出时包含，输入时 simple 风格不支持）                                                                             |
+| `images`  | `string[]`       | 图片 URL 列表（仅输出时包含，输入时 simple 风格不支持）                                                                        |
+
+### SemiPlainDoc
+
+| 字段      | 类型       | 说明     |
+|---------|----------|--------|
+| `title` | `string` | 文档标题   |
+| `url`   | `string` | 文档 URL |
+
+### 双向转换说明
+
+- **ContentBlock → SemiPlainContent**（输出时）：提取纯文本、提及用户、文档链接和图片 URL，丢弃格式信息（粗体、列表、颜色等）。**提及的位置信息通过 ` @{userID} ` 占位符保留在 text 中**，同时 userID 也会被收集到 mention 数组中
+- **SemiPlainContent → ContentBlock**（输入时）：自动 strip 掉 text 中的 `@{...}` 占位符，然后将 text 和 mention 合并为单个段落，mention 按顺序附加在文本末尾。docs 和 images 在输入时被忽略（simple 风格不支持）
+
+## 使用示例
+
+### 示例 0：--style simple 半纯文本格式
+
+```json
+{
+  "text": "提升用户满意度",
+  "mention": ["ou_123"]
+}
+```
+
+使用方式：
+```bash
+lark-cli okr +patch --level objective --style simple --target-id 123 --content '{"text":"提升用户满意度","mention":["ou_123"]}'
+```
+
+### 示例 1：简单文本段落（richtext 风格）
+
+```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,91 @@
+# okr +cycle-detail
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+列出指定 OKR 周期下的所有目标及其关键结果。
+
+## 推荐命令
+
+```bash
+# 列出指定周期的目标和关键结果（默认 simple 风格，半纯文本格式，推荐使用，更简洁）
+lark-cli okr +cycle-detail --cycle-id 1234567890123456789
+
+# 列出指定周期的目标和关键结果（richtext 风格，原始 ContentBlock JSON）
+lark-cli okr +cycle-detail --cycle-id 1234567890123456789 --style richtext
+
+# 预览 API 调用而不实际执行
+lark-cli okr +cycle-detail --cycle-id 1234567890123456789 --dry-run
+```
+
+## 参数
+
+| 参数           | 必填 | 默认值      | 说明                                                                                                                          |
+|--------------|----|----------|-----------------------------------------------------------------------------------------------------------------------------|
+| `--cycle-id` | 是  | —        | OKR 周期 ID（int64 类型）。从 `+cycle-list` 获取。                                                                                     |
+| `--style`    | 否  | `simple` | 输出风格：`simple`（半纯文本格式，不涉及字体/颜色等信息时推荐使用） \| `richtext`（原始 ContentBlock JSON）。请参考 [ContentBlock 格式](lark-okr-contentblock.md)。 |
+| `--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 字段格式由 `--style` 控制：
+- `--style simple`（默认）：`SemiPlainContent` 对象，包含 `text`、`mention`、`docs` 字段
+- `--style richtext`：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,93 @@
+# 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",
+      "start_time": "2025-01-01 00:00:00",
+      "end_time": "2025-06-30 00:00:00",
+      "cycle_status": "normal"
+    }
+  ],
+  "total": 1,
+  "current_active_cycles": [
+    {
+      "id": "1234567890123456789",
+      "start_time": "2025-01-01 00:00:00",
+      "end_time": "2025-06-30 00:00:00",
+      "cycle_status": "normal"
+    }
+  ]
+}
+```
+
+在这个周期信息中，这些字段值得关注：
+
+- `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` 为周期状态值，参见下文。
+- `current_active_cycles` 是当前生效的周期列表，不过根据用户的周期设置，可能会出现为空的场景。
+
+如果需要获取周期的创建时间/总分等信息，可以通过原生 API `okr cycles list` 获取。
+
+### 周期状态值
+
+| 值         | 说明       |
+|-----------|----------|
+| `default` | 默认状态 (0) |
+| `normal`  | 生效 (1)   |
+| `invalid` | 失效 (2)   |
+| `hidden`  | 隐藏 (3)   |
+
+在 OKR 系统中，default/normal 状态下的周期当前正常生效，invalid 状态下的周期已失效但通常仍然可以填写，hidden 状态下的周期隐藏不可见。
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数