@amaster.ai/pi-lark 0.1.3 → 0.1.5

package/skills/lark-okr/SKILL.md

@@ -0,0 +1,122 @@
+---
+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 的指标当前值（简单场景推荐）。更复杂的指标操作见 [量化指标管理](references/lark-okr-indicators.md) |
+| [`+patch`](references/lark-okr-patch.md)                       | 部分更新 Objective 或 KR（content、notes、score、deadline） |
+
+## 格式说明
+
+- [`OKR 业务实体`](references/lark-okr-entities.md) 获取 OKR 实体结构，定义和关系，帮助你更好的使用 OKR 功能
+- [`ContentBlock 富文本格式`](references/lark-okr-contentblock.md) — Objective/KeyResult/Progress 中 Content/Note 字段使用的富文本格式说明，以及简化的半纯文本（SemiPlainContent）格式的进一步说明。
+- **强烈建议** 在操作 OKR 前，阅读[`OKR 业务实体`](references/lark-okr-entities.md)以了解基础概念
+
+## API Resources
+
+### alignments
+
+- `delete` — 删除对齐关系
+- `get` — 获取对齐关系
+
+> **操作指南：** [OKR 对齐关系管理](references/lark-okr-alignments.md) 包含 list/create/delete 完整工作流
+
+### 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` — 更新量化指标
+
+> **操作指南：** [OKR 量化指标管理](references/lark-okr-indicators.md) 包含目标/KR 指标查询和 patch 更新完整工作流
+
+### key_results
+
+- `delete` — 删除关键结果
+- `get` — 获取关键结果
+- `patch` — 更新关键结果
+
+### key_result.indicators
+
+- `list` — 获取关键结果的量化指标
+
+> **操作指南：** [OKR 量化指标管理](references/lark-okr-indicators.md)
+
+### 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-alignments.md

@@ -0,0 +1,180 @@
+# OKR 对齐关系管理
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+管理 OKR 目标之间的对齐关系，包括查询、创建和删除对齐。
+
+## 对齐关系说明
+
+OKR 对齐关系表示两个目标之间的关联：
+- **对齐（aligning）**：目标 A 对齐到目标 B，表示 A 的完成有助于 B 的完成
+- **被对齐（aligned）**：目标 B 被目标 A 对齐
+
+每个对齐关系有唯一的 `alignment_id`，用于删除操作。
+
+---
+
+## 一、查询对齐关系
+
+### 命令
+
+```bash
+lark-cli okr objective.alignments list --objective-id "<目标ID>" [flags]
+```
+
+### 常用示例
+
+```bash
+# 获取目标的所有对齐关系（同时包含对齐和被对齐）
+lark-cli okr objective.alignments list \
+  --objective-id "7652569715131075772"
+
+# 只查询该目标主动对齐他人的关系
+lark-cli okr objective.alignments list \
+  --objective-id "7652569715131075772" \
+  --align-type "aligning"
+
+# 只查询他人对齐该目标的关系
+lark-cli okr objective.alignments list \
+  --objective-id "7652569715131075772" \
+  --align-type "aligned"
+
+# 自动分页获取全部数据
+lark-cli okr objective.alignments list \
+  --objective-id "7652569715131075772" \
+  --page-all
+```
+
+### 参数
+
+| 参数                   | 必填 | 默认值            | 说明                                                                 |
+|----------------------|----|----------------|--------------------------------------------------------------------|
+| `--objective-id`     | 是  | —              | 目标 ID                                                              |
+| `--align-type`       | 否  | —              | 对齐类型：`aligning`（该目标对齐他人）\| `aligned`（他人对齐该目标）。留空返回全部。 |
+| `--user-id-type`     | 否  | `open_id`      | 用户 ID 类型：`open_id` \| `union_id` \| `user_id`                    |
+| `--page-size`        | 否  | `10`           | 分页大小，最大 100                                                    |
+| `--page-all`         | 否  | —              | 自动分页获取全部数据                                                    |
+
+### 返回字段说明
+
+- `items[].id`：对齐关系 ID（删除时需要）
+- `items[].from_entity_id`：发起对齐的目标 ID
+- `items[].to_entity_id`：被对齐的目标 ID
+- `items[].from_owner` / `to_owner`：双方所有者信息
+
+---
+
+## 二、创建对齐关系
+
+### 命令
+
+```bash
+lark-cli okr objective.alignments create --objective-id "<发起对齐的目标ID>" --data '<JSON>'
+```
+
+### 常用示例
+
+```bash
+# 创建对齐关系：目标 7652569715131075772 对齐到目标 7652569715131075773
+lark-cli okr objective.alignments create \
+  --objective-id "7652569715131075772" \
+  --data '{"to_entity_id":"7652569715131075773","to_entity_type":2}'
+
+# 从文件读取请求体
+lark-cli okr objective.alignments create \
+  --objective-id "7652569715131075772" \
+  --data @alignment.json
+```
+
+### 参数
+
+| 参数               | 必填 | 说明                                                                 |
+|------------------|----|--------------------------------------------------------------------|
+| `--objective-id` | 是  | 发起对齐的目标 ID（"我"的目标）                                          |
+| `--data`         | 是  | JSON 请求体，格式见下方。支持 `@文件路径` 从文件读取。                           |
+
+### 请求体格式
+
+```json
+{
+  "to_entity_id": "7652569715131075773",  // 被对齐的目标 ID
+  "to_entity_type": 2                     // 固定值 2，表示目标类型
+}
+```
+
+### 对齐规则
+
+- **禁止自对齐**：不能自己对齐自己
+- **周期时间重叠**：两个目标所在周期的时间范围必须有重叠
+- **权限要求**：需要对发起对齐的目标有编辑权限
+
+### 返回
+
+成功后返回 `alignment_id`，保存好以便后续删除。
+
+---
+
+## 三、删除对齐关系
+
+### 命令
+
+```bash
+lark-cli okr alignments delete --alignment-id "<对齐关系ID>"
+```
+
+### 常用示例
+
+```bash
+# 删除指定的对齐关系
+lark-cli okr alignments delete \
+  --alignment-id "7652569715131075780"
+```
+
+### 参数
+
+| 参数               | 必填 | 说明                                   |
+|------------------|----|--------------------------------------|
+| `--alignment-id` | 是  | 对齐关系 ID（从 list 或 create 返回） |
+
+### 注意事项
+
+- 删除操作不可逆，请谨慎操作
+- 需要对关联的目标有编辑权限
+
+---
+
+## 完整工作流示例
+
+### 场景：将目标 A 对齐到目标 B
+
+1. **查询现有对齐关系**（确认是否已存在）
+   ```bash
+   lark-cli okr objective.alignments list \
+     --objective-id "目标A的ID" \
+     --align-type "aligning"
+   ```
+
+2. **创建对齐关系**
+   ```bash
+   lark-cli okr objective.alignments create \
+     --objective-id "目标A的ID" \
+     --data '{"to_entity_id":"目标B的ID","to_entity_type":2}'
+   ```
+
+3. **验证对齐结果**
+   ```bash
+   lark-cli okr objective.alignments list \
+     --objective-id "目标A的ID" \
+     --align-type "aligning"
+   ```
+
+4. **（如需）删除对齐关系**
+   ```bash
+   lark-cli okr alignments delete \
+     --alignment-id "从步骤1返回的alignment_id"
+   ```
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令
+- [lark-shared](../../lark-shared/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) -- 认证和全局参数