feishu-cli-okr

Feishu OKR の照会と進捗報告スキル

feishu-cli を使用して OKR 周期を照会し、進捗記録を一覧表示／作成します。OKR で最もよく使われる 3 つの操作をカバーしています。

feishu-cli：まだインストールしていない場合は、riba2534/feishu-cli でインストール方法をご確認ください。

基本概念

OKR データモデル

Feishu OKR は 4 層のオブジェクトで構成されており、このスキルでは最初の 3 層を扱います。

層	オブジェクト	説明	このスキルのコマンド
1	Period（周期）	テナントレベルの全体設定です（例：2026-Q1）。すべてのメンバーに同じ周期が表示されます	cycle list
2	Objective（目標 O）	1 つの周期に属する目標で、ユーザーに紐付けられます	参照のみ（--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 はどちらか一方を指定します（両方ではありません）。各進捗記録は、1 つの目標 または 1 つの主要な結果にのみ紐付けられます。
• 進捗記録は周期と独立して作成できます。API に period_id を渡す必要はありませんが、通常、O/KR はいずれかの period に属します。

ID：アプリトークン／テナントトークン

OKR モジュールでは現在、アプリトークン／テナントトークンの使用が必須です。実際に確認したところ、OKR サーバーはユーザートークンを拒否します（99991668 user access token not support）。そのため、コマンドは --user-access-token を読み込まず、auth login も必要ありません。

• Feishu オープンプラットフォームで、アプリに 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 はプレーンテキストを Feishu 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 で修正済み：Feishu の公式列挙型に 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"

進捗カードには Feishu 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	ソースタイトル（フラグ登録時のデフォルト値は空文字列で、実行時に client 層がデフォルト値 created by feishu-cli を設定します）	created by feishu-cli
--source-url	ソース URL（⚠️ API では必須です。フラグ登録時のデフォルト値は空文字列で、実行時に 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 で必須

Feishu OKR の progress_record/create API では、source フィールドの url が必須です。渡さないとエラーになります。CLI はデフォルトでプレースホルダー値 https://www.feishu.cn/okr/progress を設定しますが、意味のある URL（週報ドキュメントのアドレスなど）で明示的に上書きすることをおすすめします。そうすれば、OKR ページの進捗カードから実際にリンク先へ移動できます。

2. cycle のパスは v1/periods であり、v2/cycles ではありません

過去に混同されたことがありますが、Feishu 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 类型分两条路径）： • OKRTargetObjective: /open-apis/okr/v2/objectives/{id}/progresses • 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 — 综合工具箱（任务、日历等其他周报相关工具）