riba2534/feishu-cli-okr

飞书 OKR 查询与进度上报技能

通过 feishu-cli 查询 OKR 周期、列出/创建进度记录。覆盖 OKR 最高频的 3 个操作。

feishu-cli：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式。

核心概念

OKR 数据模型

飞书 OKR 由 4 层对象组成，本技能涉及前 3 层：

| 层级 | 对象 | 说明 | 本技能命令 | |------|------|------|-----------| | 1 | Period（周期） | 租户级全局，如 2026-Q1。所有成员看到的周期一致 | cycle list | | 2 | Objective（目标 O） | 一个周期内的目标，归属用户 | 仅做引用（--objective-id） | | 3 | Key Result（关键结果 KR） | O 下的可量化结果 | 仅做引用（--key-result-id） | | 4 | Progress Record（进展记录） | O 或 KR 下的一条进展更新 | progress list/create |

关键约束：

• 周期是租户级的，cycle list 没有 user_id 参数——所有人看到的周期相同。你不能"查某人的 OKR 周期"，只能"查租户当前都有哪些周期"。
• Objective ID 和 Key Result ID 二选一（不是同时）：每条进展记录只能挂在一个目标 或 一个关键结果上。
• 进展记录可以独立于周期：API 不需要传 period_id，但通常一个 O/KR 都属于一个 period。

身份：应用 Token / Tenant Token

OKR 模块当前强制使用 应用 Token / Tenant Token。实测 OKR 服务端拒绝 User Token（99991668 user access token not support），因此命令不读取 --user-access-token，也不需要 auth login。

• 需要在飞书开放平台为应用开通 OKR tenant scopes
• 本地只需配置 FEISHU_APP_ID / FEISHU_APP_SECRET 或 config.yaml
• 如服务端返回 99991672，按错误里的开放平台链接申请对应应用权限

命令速查

| 子命令 | 说明 | 必填参数 | |--------|------|---------| | okr cycle list | 列出当前租户所有 OKR 周期 | — | | okr progress list | 列出某 O/KR 下的所有进展 | --objective-id 或 --key-result-id | | okr progress create | 创建一条新进展 | 目标 ID（二选一）+ 内容（二选一） |

cycle list — 查租户 OKR 周期

# 默认文本输出（带名称 + 时间 + 状态）
feishu-cli okr cycle list

# JSON 输出（脚本消费）
feishu-cli okr cycle list --output json

输出字段：

• id — 周期 ID（后续创建 O/KR 时会用，本技能不涉及）
• zh_name / en_name — 周期名称（如 "2026-Q1"）
• start_time / end_time — 周期起止时间
• cycle_status — 周期状态（如 normal / archived）

实现细节：底层走 HTTP 直调 /open-apis/okr/v1/periods，自动分页。

progress list — 查进展记录列表

# 查目标下的所有进展
feishu-cli okr progress list --objective-id 7123456789012345678

# 查关键结果下的所有进展
feishu-cli okr progress list --key-result-id 7123456789012345678

# JSON 输出
feishu-cli okr progress list --objective-id 7xxx --output json

参数：

| 参数 | 说明 | 默认值 | |------|------|--------| | --objective-id | 目标 ID（与 --key-result-id 二选一） | — | | --key-result-id | 关键结果 ID（与 --objective-id 二选一） | — | | --user-id-type | 用户 ID 类型：open_id / union_id / user_id | open_id | | -o, --output | 输出格式：json | 文本 |

输出字段：

• progress_id — 进展 ID
• create_time / modify_time — 创建/修改时间（已转本地时区 YYYY-MM-DD HH:MM:SS）
• progress_rate.percent / progress_rate.status — 进度百分比和状态（如果有）

progress create — 创建进展记录

最常用：周报/日报中手动同步进度。

最简形式（纯文本）

feishu-cli okr progress create \
  --objective-id 7123456789012345678 \
  --content "本周完成核心模块联调，下周开始联调测试"

CLI 会自动把纯文本包装成飞书 ContentBlock 富文本 JSON（paragraph + textRun）。

带进度百分比

feishu-cli okr progress create \
  --key-result-id 7123456789012345678 \
  --content "完成 8/10 任务" \
  --progress-percent 80 \
  --progress-status normal

• --progress-percent 数字（0-100）
• --progress-status 取值：normal（正常）/ risky（有风险）/ overdue（已延期）— v1 PR 修正：飞书官方枚举不含 done，旧文档说的 done 实际就是 overdue
• ⚠️ --progress-status 必须配合 --progress-percent 使用，单独传 status 会报错

富文本（ContentBlock JSON）

需要 @某人、嵌入链接、加粗等富文本场景：

feishu-cli okr progress create \
  --objective-id 7xxx \
  --content-json '{"blocks":[{"type":"paragraph","paragraph":{"elements":[{"type":"textRun","textRun":{"text":"加粗内容","style":{"bold":true}}}]}}]}'

--content 和 --content-json 互斥，只能填一个。

自定义 source（来源标题 + URL）

feishu-cli okr progress create \
  --objective-id 7xxx \
  --content "本周完成 X" \
  --source-title "周报：W18" \
  --source-url "https://xxx.feishu.cn/docx/abc123"

进展卡片在飞书 OKR 页面会展示来源标题，点击跳转 URL。

完整参数表

| 参数 | 说明 | 默认值 | |------|------|--------| | --objective-id | 目标 ID（与 --key-result-id 二选一） | — | | --key-result-id | 关键结果 ID（与 --objective-id 二选一） | — | | --content | 纯文本内容（与 --content-json 二选一） | — | | --content-json | 原始 ContentBlock JSON（与 --content 二选一） | — | | --progress-percent | 进度百分比（数字） | — | | --progress-status | 进度状态：normal / risky / overdue | — | | --source-title | 来源标题（flag 注册默认空字符串，运行时 client 层注入默认值 created by feishu-cli） | created by feishu-cli | | --source-url | 来源 URL（⚠️ API 必填；flag 注册默认空字符串，运行时 client 层注入默认值 https://www.feishu.cn/okr/progress） | https://www.feishu.cn/okr/progress | | --user-id-type | 用户 ID 类型 | open_id | | -o, --output | 输出格式：json | 文本 |

⚠️ 关键踩坑

1. source_url 字段 API 强制必填

飞书 OKR progress_record/create API 在 source 字段下强制要求 url，不传会直接报错。CLI 已经默认填了占位值 https://www.feishu.cn/okr/progress，但建议显式覆盖为有意义的 URL（如周报文档地址），这样进展卡片在 OKR 页面才有真正的跳转价值。

2. cycle 路径是 v1/periods 不是 v2/cycles

历史上有过混淆——飞书 OKR 周期 OpenAPI 的正确路径是：

GET /open-apis/okr/v1/periods   ✅ 真实存在
GET /open-apis/okr/v2/cycles    ❌ 不存在，404

cycle list 命令的 cycle 是 CLI 子命令名（更符合用户直觉），实际调用走 v1/periods。如果手动拼 HTTP 请求时不要写错。

3. progress create 走 SDK，cycle list / progress list 走 HTTP 直调

实现层面有分工：

| 命令 | 实现方式 | |------|---------| | progress create | 飞书 Open SDK v3.5.3 的 Okr.ProgressRecord.Create | | cycle list | 通用 HTTP client 直调 /open-apis/okr/v1/periods | | progress list | 通用 HTTP client 直调（按 target 类型分两条路径）：<br>• OKRTargetObjective: /open-apis/okr/v2/objectives/{id}/progresses<br>• OKRTargetKeyResult: /open-apis/okr/v2/key_results/{id}/progresses |

原因：SDK 在 v3.5.3 版本只暴露了 progress record 的 Create 方法（没有 List/Get/Update/Delete），其他能力都得自己拼 HTTP。

4. cycle 是租户级，没有 user_id 参数

不要试图传 --user-id 给 cycle list——周期是全租户共享的，所有成员看到的都是同一份列表。这点容易被"OKR 是个人目标"的直觉误导。

权限要求（应用 Token / Tenant scope）

| 命令 | 所需 scope（任一即可） | |------|----------------------| | cycle list | okr:okr:readonly 或 okr:okr.period:readonly | | progress list | okr:okr:readonly 或 okr:okr.progress:readonly | | progress create | okr:okr 或 okr:okr.progress:writeonly |

这些是应用权限，不是 OAuth 用户授权；用开放平台应用权限管理页面开通。

典型工作流

周报同步进展

# 1. 查当前有哪些周期（可选，确认正在哪个 Q）
feishu-cli okr cycle list

# 2. 看某个目标历史进展（可选，回顾上次说了啥）
feishu-cli okr progress list --objective-id 7xxx

# 3. 同步本周进展
feishu-cli okr progress create \
  --objective-id 7xxx \
  --content "W18: 完成 X 和 Y，下周冲刺 Z" \
  --progress-percent 60 \
  --progress-status normal \
  --source-title "周报 W18" \
  --source-url "https://xxx.feishu.cn/docx/<your-weekly-doc-id>"

脚本化批量同步多个 KR 进展

for kr_id in 7xxx 7yyy 7zzz; do
  feishu-cli okr progress create \
    --key-result-id "$kr_id" \
    --content "自动同步: 当前推进中" \
    --output json
  sleep 1
done

未实现的能力（按需后续补 CLI）

以下 OKR API 飞书都支持，但本 PR 的 MVP 范围只覆盖 3 个最高频动词。internal/client 层已经部分实现，CLI 子命令暂未暴露：

| 能力 | 状态 | |------|------| | okr progress get <progress-id> | ❌ 未实现 | | okr progress update <progress-id> | ❌ 未实现 | | okr progress delete <progress-id> | ❌ 未实现 | | okr progress image upload | ❌ 未实现（图片素材上传） | | okr objective list/get | ❌ 未实现 | | okr key-result list/get | ❌ 未实现 | | okr review list/query（评审/复盘） | ❌ 未实现 |

如有需要，提 issue 或 PR 时参考 cmd/okr_progress_create.go 的模式扩展。

错误处理

| 错误 | 原因 | 解决 | |------|------|------| | 必须指定 --objective-id 或 --key-result-id 之一 | 没传目标 ID | 二选一传入 | | --objective-id 和 --key-result-id 只能填一个 | 同时传了两个 | 只保留一个 | | 必须指定 --content 或 --content-json 之一 | 没传内容 | 二选一传入 | | --content 和 --content-json 只能填一个 | 同时传了两个 | 只保留一个 | | --progress-status 必须配合 --progress-percent 一起使用 | 单独传 status | 加上 --progress-percent | | --content-json 不是合法 JSON | JSON 语法错误 | 用 jq . 校验后再传 | | source_url is required 或类似 | 飞书 API 强制必填 | CLI 已默认填占位，理论上不会触发；如出现请显式传 --source-url | | 99991672 / scope not authorized | 应用缺少 OKR tenant scope | 到开放平台应用权限管理开通 okr:okr* 相关权限 | | 99991668 user access token not support | 使用了 User Token | 不传用户 token，使用应用身份运行 |

相关技能

• feishu-cli-auth — 通用认证诊断；OKR scopes 需要在开放平台应用权限管理开通
• feishu-cli-msg — 发飞书消息（进展同步后通知 leader/小组）
• feishu-cli-toolkit — 综合工具箱（任务、日历等其他周报相关工具）