pi-feishu-cli 0.1.0

package/skills/lark-minutes/references/lark-minutes-download.md

@@ -0,0 +1,137 @@
+
+# minutes +download
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+下载妙记的音视频媒体文件到本地，或获取有效期 1 天的下载链接。只读操作。
+
+本 skill 对应 shortcut：`lark-cli minutes +download`。
+
+## 命令
+
+```bash
+# 下载妙记（默认布局，落到 ./minutes/{minute_token}/<server-filename>）
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx
+
+# 指定输出文件（单 token，文件路径）
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --output ./meeting.mp4
+
+# 指定输出目录（单/批量均可，目录路径）
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --output-dir ./downloads
+
+# 仅获取下载链接（有效期 1 天），不下载文件
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --url-only
+
+# 批量下载多个妙记（默认布局，逐个落到 ./minutes/{minute_token}/）
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx,obcnyyyyyyyyyyyyyyyyyyyy
+
+# 批量下载到同一指定目录
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx,obcnyyyyyyyyyyyyyyyyyyyy --output-dir ./downloads
+
+# 预览 API 调用
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--minute-tokens <tokens>` | 是 | 妙记 Token，逗号分隔支持批量（最多 50 个） |
+| `--output <path>` | 否 | 输出文件路径（单 token）。若传入的是已存在目录，等价于 `--output-dir`。与 `--output-dir` 互斥 |
+| `--output-dir <dir>` | 否 | 输出目录（单/批量均可）。与 `--output` 互斥 |
+| `--overwrite` | 否 | 覆盖已存在的输出文件 |
+| `--url-only` | 否 | 仅返回下载链接，不下载文件 |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+> **默认落点**：未指定 `--output` / `--output-dir` 时，文件落到 `./minutes/{minute_token}/<server-filename>`。文件名沿用服务端 Content-Disposition / Content-Type 推断，Agent 可从 `saved_path` 字段读取实际路径。同一 minute_token 的录像和 `vc +notes` 的逐字稿默认会落在**同一目录**下，方便聚合。
+
+## 核心约束
+
+### 1. 妙记必须已完成转写
+
+音视频文件仅在妙记转写完成后可下载。如果妙记尚未准备好，API 会返回 `2091003` 错误。
+
+### 2. 下载链接有效期 1 天
+
+`--url-only` 返回的链接有效期为 1 天，过期后需重新获取。
+
+### 3. 频率限制
+
+API 限流 5 次/秒，批量下载时需注意控制频率。
+
+### 4. 所需权限
+
+| 身份 | 所需权限 |
+|------|---------|
+| user / bot | `minutes:minutes.media:export` |
+
+## 输出结果
+
+### 下载模式（默认）
+
+单 token：
+
+```json
+{
+  "minute_token": "obcnxxxxxxxxxxxxxxxxxxxx",
+  "artifact_type": "recording",
+  "saved_path": "/path/to/minutes/obcnxxxxxxxxxxxxxxxxxxxx/访谈一则.m4a",
+  "size_bytes": 52428800
+}
+```
+
+批量：`downloads` 数组，每条与上面结构一致，失败项带 `error` 字段。
+
+| 字段 | 说明 |
+|------|------|
+| `minute_token` | 妙记 Token（用于 Agent 索引） |
+| `artifact_type` | 固定为 `"recording"`（与 `vc +notes` 的 `"transcript"` 区分） |
+| `saved_path` | 文件保存的本地路径（绝对路径） |
+| `size_bytes` | 文件大小（字节） |
+
+### URL 模式（--url-only）
+
+```json
+{
+  "minute_token": "obcnxxxxxxxxxxxxxxxxxxxx",
+  "download_url": "https://..."
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `minute_token` | 妙记 Token |
+| `download_url` | 媒体文件下载链接（有效期 1 天） |
+
+## 如何获取 minute_token
+
+| 来源 | 获取方式 |
+|------|---------|
+| 妙记 URL | 从 URL 末尾提取，如 `https://sample.feishu.cn/minutes/obcnxxxxxxxxxxxxxxxxxxxx` → `obcnxxxxxxxxxxxxxxxxxxxx` |
+| 妙记元信息查询 | `lark-cli minutes minutes get --params '{"minute_token": "obcn..."}'` |
+| 会议录制查询 | `lark-cli vc +recording --meeting-ids <id>` 或 `lark-cli vc +recording --calendar-event-ids <event_id>` |
+
+## 常见错误与排查
+
+| 错误现象 | 错误码 | 根本原因 | 解决方案 |
+|---------|--------|---------|---------|
+| 参数无效 | 2091001 | minute_token 格式不正确 | 检查 token 是否完整（24 位） |
+| 资源不存在 | 2091002 | token 不存在 | 确认 minute_token 正确 |
+| 妙记尚未准备好 | 2091003 | 转写未完成 | 等待转写完成后重试 |
+| 资源已删除 | 2091004 | 妙记已被删除 | 确认妙记文件仍然存在 |
+| 权限不足 | 2091005 | 无阅读权限 | 检查是否有该妙记的访问权限 |
+| `missing required scope(s)` | — | 应用缺少权限 | 运行 `auth login --scope "minutes:minutes.media:export"` |
+
+## 提示
+
+- 音视频文件可能较大，下载无固定超时限制（由用户 Ctrl+C 控制取消）。
+- 默认落点 `./minutes/{minute_token}/` 与 `vc +notes` 的逐字稿共享同一目录，方便 Agent 聚合同一会议的所有产物。
+- 单 token 模式下 `--output` 若传入已存在目录（如 `--output ./existing-dir`），等价于 `--output-dir`，文件落入该目录（cp 语义）。
+- 批量模式下 `--output` 不接受已存在的文件路径（会报错），应改用 `--output-dir`。
+- 如需获取妙记的纪要内容（逐字稿、AI 总结等），请使用 [vc +notes](../../lark-vc/references/lark-vc-notes.md)。
+
+## 参考
+
+- [lark-minutes](../SKILL.md) — 妙记全部命令
+- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) — 会议纪要查询
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/skills/lark-minutes/references/lark-minutes-search.md

@@ -0,0 +1,206 @@
+# minutes +search
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+搜索妙记列表，支持关键词、所有者、参与者以及时间范围等多条件过滤。所有者与参与者都支持传入多个 open\_id，也支持传入 `me` 表示当前用户。只读操作，不修改任何妙记数据。
+
+本 skill 对应 shortcut：`lark-cli minutes +search`（调用 `POST /open-apis/minutes/v1/minutes/search`）。
+
+## 典型触发表达
+
+以下说法通常应优先使用 `minutes +search`：
+
+- 我的妙记
+- 我拥有的妙记
+- 我参与的妙记
+- 最近的妙记
+- 某个关键词的妙记
+- 某段时间内的妙记
+
+## 命令
+
+```bash
+# 关键词搜索
+lark-cli minutes +search --query "预算复盘"
+
+# 查询某一天内的妙记（单日查询时，建议将 start 和 end 都填写为同一天）
+lark-cli minutes +search --start 2026-03-10 --end 2026-03-10
+
+# 按时间范围搜索
+lark-cli minutes +search --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"
+lark-cli minutes +search --start 2026-03-10 --end 2026-03-17
+
+# 关键词 + 时间范围
+lark-cli minutes +search --query "预算复盘" --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"
+lark-cli minutes +search --query "预算复盘" --start "2026-03-10T00:00+08:00"
+lark-cli minutes +search --query "预算复盘" --end "2026-03-17T00:00+08:00"
+
+# 按参与者过滤（open_id，逗号分隔）
+lark-cli minutes +search --participant-ids "ou_x,ou_y"
+
+# 按所有者过滤（open_id，逗号分隔）
+lark-cli minutes +search --owner-ids "ou_owner,ou_owner_2"
+
+# 严格只查我作为参与者的妙记（不含我拥有）
+lark-cli minutes +search --participant-ids "me"
+
+# 查询我拥有的妙记
+lark-cli minutes +search --owner-ids "me"
+
+# 广义查询我参与的妙记（自然语言默认：我拥有 ∪ 我参与）
+lark-cli minutes +search --owner-ids "me" --start 2026-03-10 --end 2026-03-10
+lark-cli minutes +search --participant-ids "me" --start 2026-03-10 --end 2026-03-10
+# 然后按 token 去重合并两次结果
+
+# 多条件组合查询
+lark-cli minutes +search --owner-ids "ou_owner" --participant-ids "ou_x" --start "2026-03-10T00:00+08:00"
+
+# 分页查询
+lark-cli minutes +search --query "预算复盘" --page-size 20
+lark-cli minutes +search --query "预算复盘" --page-size 20 --page-token '<PAGE_TOKEN>'
+
+# 输出为结构化 JSON
+lark-cli minutes +search --query "预算复盘" --format json
+```
+
+## 参数
+
+| 参数                        | 必填 | 说明                                   |
+| ------------------------- | -- | ------------------------------------ |
+| `--query <text>`          | 否  | 搜索关键词                                |
+| `--owner-ids <ids>`       | 否  | 所有者 open\_id 列表，逗号分隔；支持传 `me` 表示当前用户 |
+| `--participant-ids <ids>` | 否  | 参与者 open\_id 列表，逗号分隔；支持传 `me` 表示当前用户 |
+| `--start <time>`          | 否  | 开始时间（ISO 8601 或仅日期）                  |
+| `--end <time>`            | 否  | 结束时间（ISO 8601 或仅日期）                  |
+| `--page-size <n>`         | 否  | 每页数量，默认 `15`，最大 `30`                 |
+| `--page-token <token>`    | 否  | 下一页分页 token                          |
+| `--dry-run`               | 否  | 预览 API 调用，不执行                        |
+
+## 核心约束
+
+### 1. 至少提供一个过滤条件
+
+所有参数均可选，但必须至少提供一个过滤条件：`--query`、`--owner-ids`、`--participant-ids`、`--start` 或 `--end`。
+
+### 2. 仅支持 user 身份
+
+该接口仅支持 `user` 身份，使用前需完成 `lark-cli auth login` 并具备 `minutes:minutes.search:read` 权限。
+
+### 3. `me` 表示当前用户
+
+在 `--owner-ids` 和 `--participant-ids` 中可使用 `me`，表示当前登录用户。该值会在本地解析为当前用户的 `open_id`，无需手动先查询自己的用户 ID。
+若当前环境尚未完成用户登录，或 CLI 无法解析出当前用户的 `open_id`，则应先执行 `lark-cli auth login`，再重新执行搜索。
+
+### 4. 自然语言中的“参与的妙记”默认按并集理解
+
+当用户说"我参与的妙记""我参加过的妙记""参与过的妙记"时，默认理解为"我涉及的全部妙记"：
+
+- 我拥有的妙记：`--owner-ids me`
+- 我作为参与者的妙记：`--participant-ids me`
+
+不要只跑一次 `--participant-ids me` 就直接下结论，也不要把 `--owner-ids me` 和 `--participant-ids me` 同时塞进一次查询里赌接口语义。应分别查询后，按 `token` 做并集去重。
+
+只有在用户明确说"仅我参与但不是我拥有""别人拥有但我参与""只看参与者身份"时，才只使用 `--participant-ids`。
+
+### 5. 支持分页
+
+当返回 `has_more=true` 时，使用响应中的 `page_token` 配合 `--page-token` 获取下一页结果。
+
+### 6. 日期型 `--end` 包含当天整天
+
+当 `--end` 传入的是仅日期格式（如 `2026-03-10`）时，CLI 会将它解释为当天 `23:59:59`，而不是当天 `00:00:00`。
+CLI 会先按输入的本地日历日语义解析，再标准化为 RFC3339 时间戳发给 API；在 dry-run 或排查请求体时，看到的 `Z` 结尾时间表示同一个绝对时间点的 UTC 表示，不改变“按当天整天查询”的语义。
+
+这意味着：
+
+- `--start 2026-03-10 --end 2026-03-10` 表示只查 `2026-03-10` 当天
+- `--start 2026-03-10 --end 2026-03-11` 表示查询 `2026-03-10` 和 `2026-03-11` 两天
+
+如果用户说“昨天的妙记”“今天的妙记”“某一天内的妙记”，应把 `--start` 和 `--end` 都设置为同一天，而不是把 `--end` 设成下一天。
+
+### 7. 会议的妙记先定位会议
+
+如果用户明确要找某场会议的妙记，或同时提到“会议 / 开会 / 会”和“妙记”，应优先使用 `vc +search` 先定位会议，再按需通过 `vc +recording` 获取 `minute_token`，不要直接按妙记时间范围或关键词搜索。
+只有在无法通过会议搜索定位目标会议，或用户明确要求按妙记维度检索时，才回退到 `minutes +search`。
+
+如果用户要的是"某场会议的妙记信息""某个日程对应的妙记详情""minute\_token""妙记链接""标题""时长""owner"，正确链路是：
+
+1. `vc +search` 或 `calendar +agenda` 先定位会议 / 日程
+2. `vc +recording` 获取 `minute_token`
+3. `minutes minutes get` 查询妙记基础信息
+
+不要为了查"妙记信息"直接走 `vc +notes --meeting-ids`。`vc +notes` 只适用于逐字稿、总结、待办、章节等纪要内容。
+
+<br />
+
+## 时间格式
+
+`--start` 和 `--end` 支持以下时间格式：
+
+| 格式             | 示例                          | 说明                                 |
+| -------------- | --------------------------- | ---------------------------------- |
+| ISO 8601（带时区）  | `2026-03-10T14:00:00+08:00` | 推荐                                 |
+| ISO 8601（不带时区） | `2026-03-10T14:00:00`       | 按本地时区解析                            |
+| 仅日期            | `2026-03-10`                | 按天粒度解析；若用于 `--end`，表示当天 `23:59:59` |
+
+## 输出结果
+
+- 默认输出包含 `items`、`total`、`has_more` 和 `page_token`。
+
+## Pagination (`has_more` / `page_token`)
+
+- 当结果中返回 `has_more=true` 时，说明还有更多页可继续获取。
+- 继续翻页时，使用响应中的 `page_token` 搭配 `--page-token` 发起下一次查询。
+- 不要假设调大 `--page-size` 就能拿全结果；分页遍历时应以 `has_more` 和 `page_token` 为准。
+- `total` 数量小于 50 时，自动分页获取所有结果；`total` 数量大于 50 时，向用户确认是否获取全部结果。
+
+```bash
+# First page
+lark-cli minutes +search --query "预算复盘" --page-size 20
+
+# Next page
+lark-cli minutes +search --query "预算复盘" --page-size 20 --page-token '<PAGE_TOKEN>'
+```
+
+## 搜索结果中的下一步
+
+搜索结果中的 `token` 可直接作为 `minute_token` 用于继续查询妙记产物：
+通常先用搜索结果中的 `token` 获取妙记基础信息，确认描述、链接等元数据是否命中目标；只有需要进一步查看逐字稿、总结、待办、章节时，再继续查询关联的纪要产物。
+
+如果你已经确定目标妙记，优先直接复用搜索结果中的 `token`，避免重复搜索。
+
+```bash
+# 首先查询妙记元信息（标题、时长、封面） → 用本 skill
+lark-cli minutes minutes get --params '{"minute_token": "obcn***************"}'
+
+# 查妙记关联的纪要产物：逐字稿、总结、待办、章节等 → 用 lark-cli vc +notes
+lark-cli vc +notes --minute-tokens obcn_EXAMPLE_TOKEN
+```
+
+## 常见错误与排查
+
+| 错误现象                   | 根本原因                                                  | 解决方案                                         |
+| ---------------------- | ----------------------------------------------------- | -------------------------------------------- |
+| 命令直接报错，要求提供过滤条件        | 没有传入 `--query`、时间范围或任何过滤 ID                           | 至少补充一个过滤条件后重试                                |
+| 时间参数校验失败               | `--start` 或 `--end` 格式不合法                             | 改用 ISO 8601 或 `YYYY-MM-DD`                   |
+| `owner-ids` 校验失败       | 传入的不是 open\_id，且也不是 `me`；或传了 `me` 但当前用户 open\_id 不可解析 | 改为 `ou_` 开头的用户 ID，或先完成 `auth login` 后再传 `me` |
+| `participant-ids` 校验失败 | 传入的不是 open\_id，且也不是 `me`；或传了 `me` 但当前用户 open\_id 不可解析 | 改为 `ou_` 开头的用户 ID，或先完成 `auth login` 后再传 `me` |
+| 权限不足                   | 未授权 `minutes:minutes.search:read`                     | 使用 `auth login` 完成授权                         |
+
+## 提示
+
+- 当用户说“我的妙记”时，优先理解为 `--owner-ids me`。
+- 当用户说“我参与的妙记”“我参加过的妙记”时，默认理解为 `--owner-ids me` 与 `--participant-ids me` 两次查询后的并集。
+- 当用户明确说“仅我参与但不是我拥有”时，才优先理解为 `--participant-ids me`。
+- 当用户同时提到“会议 / 会 / 开会 / 某场会”和“妙记”时，优先先定位会议；如果要的是妙记信息，走 `vc +recording` → `minutes minutes get`，只有要纪要内容时才走 `vc +notes --minute-tokens`。
+- 必须使用 `--format json` 输出，你更加擅长解析 JSON 数据。
+- 排查参数与请求结构时优先使用 `--dry-run`。
+- 搜索的时间范围最大为 1 个月，如果需要搜索更长时间范围的妙记，需要拆分为多次时间范围为一个月查询。
+
+## 参考
+
+- [lark-minutes](../SKILL.md) -- 妙记相关命令
+- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) -- 基于 `minute_token` 获取逐字稿、总结、待办、章节等产物
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [lark-vc](../../lark-vc/SKILL.md) -- 视频会议全部命令
+

package/skills/lark-minutes/references/lark-minutes-upload.md

@@ -0,0 +1,104 @@
+# minutes +upload
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+上传音视频文件到飞书妙记并生成妙记（Minute）。
+
+本 skill 对应 shortcut：`lark-cli minutes +upload`。
+
+## 典型触发表达
+
+- "把这个音视频文件转成妙记"
+- "把这个音视频文件转成纪要"
+- "把这个音视频文件转成逐字稿、文字稿或撰写文字"
+- "把这个音视频文件转成总结、待办或章节"
+
+## 完整工作流
+
+当用户要求将音视频文件转换为妙记，或进一步要纪要/逐字稿/文字稿/撰写文字时，必须按照以下步骤执行：
+
+1. **上传文件至云空间获取 file_token**
+   - 使用 `lark-cli drive +upload` 命令上传本地文件到云空间（Drive）：
+     ```bash
+     lark-cli drive +upload --file <path/to/media/file>
+     ```
+   - 从命令的返回结果中提取生成的 `file_token`。
+
+2. **将 file_token 转换为妙记链接（minute_url）**
+   - 调用本 shortcut，将获取到的 `file_token` 转换为妙记：
+     ```bash
+     lark-cli minutes +upload --file-token <file_token>
+     ```
+   - 命令执行成功后，将返回生成的妙记链接 `minute_url`。
+
+3. **如需纪要 / 逐字稿 / 文字稿 / 撰写文字，继续提取 `minute_token` 调用 `vc +notes`**
+   - 从返回的 `minute_url` 中提取路径最后一段，得到 `minute_token`。
+   - 如果用户要的是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，继续调用：
+     ```bash
+     lark-cli vc +notes --minute-tokens <minute_token>
+     ```
+   - `vc +notes --minute-tokens` 会返回纪要文档、逐字稿文档，以及 AI 内置产物（总结、待办、章节）；必要时还会把逐字稿落地到本地文件。
+
+> **异步生成提示**：API 会立即返回 `minute_url`，但妙记可能仍在异步生成中，您可以直接通过该妙记链接查看当前的处理状态和转写结果。
+
+## 命令示例
+
+```bash
+# 通过已上传到云空间的 file_token 生成妙记
+lark-cli minutes +upload --file-token boxcnxxxxxxxxxxxxxxxx
+
+# 通过 minute_token 继续获取纪要 / 逐字稿 / 文字稿 / AI 产物
+lark-cli vc +notes --minute-tokens obcnxxxxxxxxxxxxxxxx
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token <token>` | 是 | 已经上传到飞书云空间的音视频文件的 file_token |
+
+## 支持的格式与限制
+
+待上传到妙记的原始音视频文件必须满足以下要求：
+
+- 支持音频格式：`wav`、`mp3`、`m4a`、`aac`、`ogg`、`wma`、`amr`
+- 支持视频格式：`avi`、`wmv`、`mov`、`mp4`、`m4v`、`mpeg`、`ogg`、`flv`
+- 音视频时长不能超过 `6` 小时
+- 文件大小不能超过 `6 GB`
+
+> 说明：本 shortcut 只接收 `file_token`，不会直接读取本地文件内容，因此这些格式、时长和大小限制对应的是**原始上传文件**本身。若妙记生成失败，请先回查源文件是否满足上述要求。
+
+## 核心约束
+
+### 1. 必须提供 file_token
+
+本接口不直接处理本地文件的上传，必须先使用 `drive +upload` 将文件上传到云空间获取 `file_token`，然后再调用本接口。
+
+### 2. 先上传，再生成妙记
+
+推荐流程如下：
+
+1. 使用 `lark-cli drive +upload --file <path>` 上传本地音视频文件到云空间
+2. 从返回结果中取出 `file_token`
+3. 调用 `lark-cli minutes +upload --file-token <file_token>` 生成妙记
+4. 如果目标是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，再从 `minute_url` 提取 `minute_token`，继续调用 `lark-cli vc +notes --minute-tokens <minute_token>`
+
+> **边界说明**：`minutes +upload` 本身只负责把文件转成妙记并返回 `minute_url`。纪要内容、逐字稿、文字稿、撰写文字、总结、待办、章节属于后续产物获取，应由 [vc +notes](../../lark-vc/references/lark-vc-notes.md) 承接。
+
+## 输出结果示例
+
+```json
+{
+  "minute_url": "http(s)://<host>/minutes/<minute-token>"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `minute_url` | 生成的妙记访问链接 |
+
+## 参考
+
+- [lark-minutes](../SKILL.md) -- 妙记相关功能说明
+- [drive +upload](../../lark-drive/references/lark-drive-upload.md) -- 上传文件到云空间
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/skills/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`  |
+