@wagemule/daemon 0.1.2 → 0.1.3

package/dist/skills/larksuite/lark-okr/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: lark-okr
+version: 1.0.0
+description: "飞书 OKR：管理目标与关键结果。查看和编辑 OKR 周期、目标（Objective）、关键结果（Key Result）、对齐关系、量化指标和进展记录。当用户需要查看或创建 OKR、管理目标和关键结果、查看对齐关系时使用。"
+metadata:
+  requires:
+    bins: [ "lark-cli" ]
+  cliHelp: "lark-cli okr --help"
+---
+
+# okr (v2)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+## 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 进展记录的富文本内容    |
+
+## 格式说明
+
+- [`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
+
+```bash
+lark-cli schema okr.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli okr <resource> <method> [flags] # 调用 API
+```
+
+> **重要**：使用原生 API 时，**必须**先运行 `schema` 查看 `--data` / `--params` 参数结构，**不要**猜测字段格式！
+
+### alignments
+
+- `delete` — 删除对齐关系
+- `get` — 获取对齐关系
+
+### categories
+
+- `list` — 批量获取分类
+
+### cycles
+
+- `list` — 批量获取用户周期
+- `objectives_position` — 更新用户周期下全部目标的位置
+    - 请求中必须同时修改对应周期下全部目标的位置，且不允许位置重叠，否则会参数校验失败。
+- `objectives_weight` — 更新用户周期下全部目标的权重
+    - 请求中必须同时修改对应周期下全部目标的权重，且所有权重值的和必须等于 1 ，否则会参数校验失败。
+
+### cycle.objectives
+
+- `create` — 创建目标
+- `list` — 批量获取用户周期下的目标
+
+### indicators
+
+- `patch` — 更新量化指标
+
+### key_results
+
+- `delete` — 删除关键结果
+- `get` — 获取关键结果
+- `patch` — 更新关键结果
+
+### key_result.indicators
+
+- `list` — 获取关键结果的量化指标
+
+### objectives
+
+- `delete` — 删除目标
+- `get` — 获取目标
+- `key_results_position` — 更新全部关键结果的位置
+    - 请求中必须同时修改对应目标下全部关键结果的位置，且不允许位置重叠，否则会参数校验失败。
+- `key_results_weight` — 更新全部关键结果的权重
+    - 请求中必须同时修改对应目标下全部关键结果的权重，且所有权重值的和必须等于 1 ，否则会参数校验失败。
+- `patch` — 更新目标
+
+### objective.alignments
+
+- `create` — 创建对齐关系
+    - 对齐不允许对齐自己的目标，且发起对齐的目标和被对齐的目标所在周期时间上必须有重叠，否则会参数校验失败。
+- `list` — 批量获取目标下的对齐关系
+
+### objective.indicators
+
+- `list` — 获取目标的量化指标
+
+### objective.key_results
+
+- `create` — 创建关键结果
+- `list` — 批量获取目标下的关键结果
+
+## 权限表
+
+| 方法                                | 所需 scope                    |
+|-----------------------------------|-----------------------------|
+| `alignments.delete`               | `okr:okr.content:writeonly` |
+| `alignments.get`                  | `okr:okr.content:readonly`  |
+| `categories.list`                 | `okr:okr.setting:read`      |
+| `cycles.list`                     | `okr:okr.period:readonly`   |
+| `cycles.objectives_position`      | `okr:okr.content:writeonly` |
+| `cycles.objectives_weight`        | `okr:okr.content:writeonly` |
+| `cycle.objectives.create`         | `okr:okr.content:writeonly` |
+| `cycle.objectives.list`           | `okr:okr.content:readonly`  |
+| `indicators.patch`                | `okr:okr.content:writeonly` |
+| `key_results.delete`              | `okr:okr.content:writeonly` |
+| `key_results.get`                 | `okr:okr.content:readonly`  |
+| `key_results.patch`               | `okr:okr.content:writeonly` |
+| `key_result.indicators.list`      | `okr:okr.content:readonly`  |
+| `objectives.delete`               | `okr:okr.content:writeonly` |
+| `objectives.get`                  | `okr:okr.content:readonly`  |
+| `objectives.key_results_position` | `okr:okr.content:writeonly` |
+| `objectives.key_results_weight`   | `okr:okr.content:writeonly` |
+| `objectives.patch`                | `okr:okr.content:writeonly` |
+| `objective.alignments.create`     | `okr:okr.content:writeonly` |
+| `objective.alignments.list`       | `okr:okr.content:readonly`  |
+| `objective.indicators.list`       | `okr:okr.content:readonly`  |
+| `objective.key_results.create`    | `okr:okr.content:writeonly` |
+| `objective.key_results.list`      | `okr:okr.content:readonly`  |
+

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