AI Skills
lark-shared

lark-shared

熱門

首次設定 lark-cli、執行 auth login、切換使用者/機器人身分（--as）、處理權限不足或範圍錯誤、需要更新 lark-cli，或在 JSON 輸出中看到 _notice 時使用。

1.4萬星標
1039分支
更新於 2026/6/15
獲取技能源代碼

相關技能

msstore-cli3.7萬site-architecture3.4萬vercel-optimize2.8萬
SKILL.md
readonlyread-only
name
lark-shared
description

Use when first setting up lark-cli, running auth login, switching user/bot identity (--as), handling permission denied or scope errors, needing to update lark-cli, or seeing _notice in JSON output.

version
1.0.0

lark-cli 共享規則

本技能指導你如何透過 lark-cli 操作飛書資源，以及有哪些注意事項。

配置初始化

首次使用需執行 lark-cli config init 完成應用配置。

當你幫用戶初始化配置時，使用 background 方式使用下面的命令發起配置應用流程，啟動後讀取輸出，從中提取授權連結並發給用戶。

URL 轉發規則：當命令輸出 verification_url、verification_uri_complete、console_url 等 URL 欄位時：必須產生 QR Code：你必須呼叫 lark-cli auth qrcode 將 URL 轉為 QR Code 並展示給用戶，這是必須步驟，不要跳過。優先生成 PNG QR Code（--output）；僅當用戶明確要求時才使用 ASCII（--ascii）。URL 輸出規則：將 URL 視為不可修改的 opaque string，不要做任何修改（包括 URL 編碼/解碼、添加空格或標點、重新拼接 query），QR Code 和連結請一起展示給用戶。

# 發起配置（該命令會阻塞直到用戶打開連結並完成操作或過期）
lark-cli config init --new

認證

身分類型

兩種身分類型，透過 --as 切換：

身份 標識 取得方式 適用場景
user 使用者身分 --as user lark-cli auth login 等 存取使用者自己的資源（日曆、雲空間/雲端硬碟/雲端儲存等）
bot 應用身分 --as bot 自動，只需 appId + appSecret 應用級操作，存取 bot 自己的資源

身分選擇原則

輸出的 [identity: bot/user] 代表目前身分。bot 與 user 表現差異很大，需確認身分符合目標需求：

  • Bot 看不到使用者資源：無法存取使用者的日曆、雲空間（雲端硬碟/雲端儲存）文件、信箱等個人資源。例如 --as bot 查行程回傳 bot 自己的（空）日曆
  • Bot 無法代表使用者操作：發訊息以應用名義發送，建立文件歸屬 bot
  • Bot 權限：只需在飛書開發者後台開通 scope，無需 auth login
  • User 權限：後台開通 scope + 使用者透過 auth login 授權，兩層都要滿足

權限不足處理

遇到權限相關錯誤時，根據目前身分類型採取不同解決方案。

錯誤回應中包含關鍵資訊：

  • permission_violations：列出缺少的 scope（N 選 1）
  • console_url：飛書開發者後台的權限設定連結
  • hint：建議的修復命令
Bot 身分（--as bot）

將錯誤中的 console_url 原樣提供給用戶，引導去後台開通 scope。禁止對 bot 執行 auth login。

User 身分（--as user）
lark-cli auth login --domain <domain>           # 按業務域授權
lark-cli auth login --scope "<missing_scope>"   # 按具體 scope 授權（推薦，符合最小權限原則）

規則：auth login 必須指定範圍（--domain 或 --scope）。多次 login 的 scope 會累積（增量授權）。

Agent 代理發起認證（推薦）

當你作為 AI agent 需要幫用戶完成認證時，優先使用 split-flow，避免在同一輪對話中阻塞等待用戶授權：

# 發起授權（立即回傳 device_code 和 verification_url）
lark-cli auth login --scope "calendar:calendar:readonly" --no-wait --json

拿到 verification_url 後，將它原樣作為本輪最終訊息發給用戶，並結束本輪/交還控制權。不要在同一輪中展示 URL 後立刻執行 --device-code 阻塞輪詢；在不透傳中間輸出的 agent harness 裡，這會導致用戶永遠看不到 URL。

用戶回覆已完成授權後，再在後續步驟執行：

lark-cli auth login --device-code <device_code>

Split-Flow 完整步驟：

第一步：發起授權（當前輪）

  1. 執行 lark-cli auth login --scope "xxx" --no-wait --json（必須加 --no-wait --json）
  2. 從 JSON 輸出中提取 verification_url 和 device_code
  3. 產生 QR Code：lark-cli auth qrcode <verification_url> --output "xxx"
  4. 將 URL 和 QR Code 展示給用戶（先 URL，後 QR Code）
  5. 結束本輪對話前，必須明確告知用戶：「請完成授權後，回來告訴我已授權完成，我會幫你完成後續步驟」

第二步：完成授權（後續輪）

  1. 等待用戶回覆「已完成授權」
  2. 由你（AI agent）親自執行：lark-cli auth login --device-code <device_code>
  3. 此命令會輪詢授權狀態並完成登入
  4. 如果回傳授權成功，流程結束

關鍵規則：

  • 你必須親自執行 --device-code 命令，不要指示用戶自行執行
  • 不要在同一輪中展示 URL 後立刻執行 --device-code，這會導致用戶看不到 URL
  • 禁止快取 verification_url 或 device_code：每次需要授權時，必須重新執行 lark-cli auth login --no-wait --json 產生新的連結。不要將授權連結和 device code 存入上下文供後續重複使用

更新檢查

lark-cli 命令執行後，如果偵測到新版本，JSON 輸出中會包含 _notice.update 欄位（含 message、command 等）。

當你在輸出中看到 _notice.update 時，完成用戶當前請求後，主動提議幫用戶更新：

  1. 告知用戶目前版本和最新版本號
  2. 提議執行更新（同時更新 CLI 和 Skills）：
    lark-cli update
  3. 更新完成後提醒用戶：退出並重新打開 AI Agent 以載入最新 Skills

重要：始終使用 lark-cli update 更新，它會同時更新 CLI 和 AI Skills。

規則：不要靜默忽略更新提示。即使當前任務與更新無關，也應在完成用戶請求後補充告知。

安全規則

  • 禁止輸出金鑰（appSecret、accessToken）到終端明文。
  • 寫入/刪除操作前必須確認用戶意圖。
  • 用 --dry-run 預覽危險請求。
  • 檔案路徑只接受相對路徑：--file、--output、--output-dir、@file 等路徑參數只接受 cwd 下的相對路徑，傳絕對路徑會報 unsafe file path。資料輸入（@file、大 JSON）優先使用 stdin 傳入，避免路徑和跳脫問題。

高風險操作的審批協議（exit 10）

lark-cli 對高風險寫操作（risk: "high-risk-write"）有強制確認門禁。當你不帶 --yes 呼叫這類命令時，CLI 會退出碼 10、並在 stderr 回傳如下結構化 envelope：

{
  "ok": false,
  "error": {
    "type": "confirmation_required",
    "message": "drive +delete requires confirmation",
    "hint": "add --yes to confirm",
    "risk": {
      "level": "high-risk-write",
      "action": "drive +delete"
    }
  }
}

遇到這種情況，不要當普通錯誤放棄。 按以下流程處理：

  1. 識別：看到子程序 exit code = 10 且 stderr JSON 裡 error.type == "confirmation_required"
  2. 向用戶確認：把 error.risk.action 和關鍵參數展示給用戶，明確告知「這是高風險操作」，等待用戶明確同意
  3. 用戶同意 → 在你原始 argv 的末尾追加 --yes 後重試
  4. 用戶拒絕 → 終止流程，不要擅自改寫參數或跳過門禁

絕對不允許：

  • 看到 exit 10 就預設加 --yes 靜默重試（這等於停用門禁）
  • 把 confirmation_required 當網路錯誤/權限錯誤處理
  • 在用戶沒明確同意的前提下追加 --yes 重試
  • 用 sh -c 等 shell 方式拼接命令重試——用 exec.Command(argv...) 參數陣列形式，避免 shell 解析把用戶參數當作語法

提前預判：想先讓用戶 review 危險操作的具體請求，呼叫時加 --dry-run——它不會觸發門禁，會印出完整請求詳情（URL / body / params），你可以把這個預覽給用戶看過再去真正執行。

如何識別一條命令是高風險

  • shortcut：lark-cli <service> +<cmd> --help 頂部會顯示 Risk: high-risk-write
  • service 命令：lark-cli schema <service>.<resource>.<method> --format json 的回傳值裡 "risk": "high-risk-write"