version: "1.0.6" name: feishu-cli-auth description: >- 飞书 OAuth 认证和 User Access Token 管理（Device Flow，RFC 8628）。 支持一键创建飞书应用、按域申请推荐权限、auth check 预检 scope、auth login 登录、Token 自动刷新。 覆盖 AI Agent 两步授权（--no-wait 拿链接 → --device-code 续轮询）、JSON 事件流解析、部分 scope 未授予（missing_scopes）的判读与补授。 当用户请求登录飞书、获取 Token、OAuth 授权、用户身份授权、device flow、权限缺失、Token 过期、create-app、99991672、99991679， 或其他飞书技能遇到 User Access Token 问题时使用。 本技能同时承载两个相关子命令：doctor 做配置/网络/代理体检（错误信息不指向 scope/token 时用）， profile 管理多 App / 多账号独立配置（多租户切换）。 注意：profile 指 CLI 配置切换，与邮箱 mailbox profile（feishu-cli-mail）无关。 argument-hint: login | status | check | logout | doctor | profile <subcmd> | config create-app user-invocable: true allowed-tools: Bash(feishu-cli auth:), Bash(feishu-cli config:), Bash(feishu-cli doctor:), Bash(feishu-cli profile:), Read

飞书认证

本项目默认使用 App Token。只有搜索、消息历史/互动、审批任务、会议/妙记、邮箱等用户身份场景需要 User Access Token。

推荐流程（人工 / 交互终端）

# 1. 预检：缺什么 scope 一目了然（auth check 返回 missing 时先到开放平台开通）
feishu-cli auth check --scope "search:docs:read search:message"
 
# 2a. 按业务域登录，自动带该域推荐 scope
feishu-cli auth login --domain search --recommend
 
# 2b. 一次授全：对全部业务域申请推荐 scope（单独用 --recommend，不带 --domain）
feishu-cli auth login --recommend
 
# 2c. 精确控制：显式指定 scope（与 --domain/--recommend 互斥）
feishu-cli auth login --scope "search:docs:read search:message"

--recommend 三种用法：单独用 = 全部 20 个业务域的推荐 scope；配 --domain X = 仅该域推荐 scope；都不传且在交互终端下 = 弹出选择提示。非交互环境（无 tty）必须显式指定范围，否则报错。

💡 auth login 是增量授权：多次登录申请的 scope 在飞书服务端累积，补授新 scope 不会丢掉之前已授的。（本地 token.json 虽被新 token 覆盖，但其 scope 是服务端返回的累积值。）

AI Agent 授权（两步模式 ⭐）

AI Agent 的 harness 通常只把最终回复发给用户、且单轮有 timeout，不适合在同一轮里阻塞等授权。用两步模式：第一步拿链接发给用户并结束本轮，用户授权后下一轮再续轮询。

# 第一步：只取 device_code + 授权链接，立即返回不轮询
feishu-cli auth login --recommend --no-wait --json
# → 输出一行 device_authorization 事件，把 verification_uri_complete 发给用户后结束本轮
 
# 第二步（用户回复已授权后）：用 device_code 续上轮询
feishu-cli auth login --device-code <device_code> --json

要点：

• scope 自动恢复：第二步从 device_code 缓存读回第一步申请的 scope，不用也不能再传 --scope/--domain/--recommend（重传会报错）。
• device_code 有效期约 10 分钟，超时需从第一步重来；每次重新跑第一步都会作废上一个链接。
• 不要用短 timeout 反复重试第一步——每次重启都会让上一个授权链接失效。

若 harness 支持后台任务，也可一步阻塞 + 后台运行：

# run_in_background 跑：阻塞轮询最长约 10 分钟，stdout 逐行出 JSON 事件
feishu-cli auth login --recommend --json

阻塞模式务必 run_in_background，或把单命令 timeout 设到 ≥ 600s。

JSON 事件 schema

--json 模式按 JSONL 逐行输出事件，Agent 解析这两个即可：

`device_authorization`（第一步 / 阻塞模式开头）：

{"event":"device_authorization","verification_uri_complete":"https://accounts.feishu.cn/oauth/v1/device/verify?flow_id=...&user_code=XXXX-XXXX","user_code":"XXXX-XXXX","device_code":"...","expires_in":600,"interval":5,"requested_scopes":["..."]}

→ 把 verification_uri_complete（已含 user_code，可直接点开）原样发给用户，不要做任何 URL 编码/改写。

`authorization_complete`（授权成功，token 已落盘）：

{"event":"authorization_complete","expires_at":"...","scope":"...","refresh_token_present":true,"granted_scopes":["..."],"missing_scopes":["..."],"requested_scopes":["..."]}

→ 上述 6 个字段常驻（scope 即落盘 token.json 的累积 scope 值）；refresh_expires_at（拿到 refresh token 时）、warnings/hints（refresh 缺失或 scope 未授予时）为条件字段，无对应情况时 key 不出现——解析勿假设必存。

授权结果判读

收到 authorization_complete 即代表登录成功、token 已写入 `token.json`——但还要看这几个字段：

补授权（增量）：missing_scopes 非空时，先到飞书开放平台开通这些 scope，再照 CLI 的 hint 执行 auth login --scope "<缺失的>" 即可。多次 login 的 scope 在服务端累积，补授只需带缺失的那几个，不会丢掉之前已授的，无需重跑全量。

常用命令

feishu-cli auth status
feishu-cli auth status -o json --verify
feishu-cli auth check --scope "REQ_SCOPES"
feishu-cli auth login --domain <domain> --recommend
feishu-cli auth logout
feishu-cli auth token --as user|bot|auto    # v1.29+ 导出 token 给 curl/Python 用
feishu-cli config create-app --save
feishu-cli doctor --json
feishu-cli profile current

auth token 导出 Token 给外部工具用（v1.29+）

让 curl / Python requests / 任何 HTTP 工具复用本 CLI 的 Token 全生命周期管理 （Device Flow 登录、2 小时自动刷新、多 profile），不再各自实现 OAuth 流程。

# 给 curl 用
TOKEN=$(feishu-cli auth token --as user)
curl -H "Authorization: Bearer $TOKEN" \
  https://open.feishu.cn/open-apis/authen/v1/user_info
 
# 给 Python 用
TOKEN=$(feishu-cli auth token --as bot)
python3 -c "import requests; print(requests.get('https://open.feishu.cn/open-apis/im/v1/chats', headers={'Authorization': f'Bearer $TOKEN'}).json())"

想直接调任意 OpenAPI 而不写 curl？用 feishu-cli api <method> <path>（详见 feishu-cli-schema skill）。

Agent 判读：auth check / auth status 的 JSON 契约

`auth check --scope "..."` —— 执行业务前预检某组 scope 够不够。退出码 0=满足、非 0=缺失或未登录；stdout 出 JSON：

# 满足才往下执行业务命令
feishu-cli auth check --scope "search:docs:read" && feishu-cli search docs --query "..."

`auth status -o json` —— 看本地 token 现状（默认不连服务端，加 --verify 才在线核验）。已登录时关键字段：

未登录时返回 {"logged_in": false, "identity": "bot", "note": "..."}。

判断"任务能不能干"优先用 auth check（按 scope 精确判定）；auth status 看整体健康度和当前身份。下面「排错」表的状态值即来自这两个命令（auth check 的 error / auth status 的 health）。

Token 解析策略

CLI 把命令分成三类，对应 cmd/utils.go 里三个 helper：

1. 读类 · User 优先 + Tenant 兜底（resolveOptionalUserTokenWithFallback）

登录后自动用 token.json 里的 User Token；未登录则回落 App Token（要求 Bot 在群/有相应权限）。

优先级链：--user-access-token → FEISHU_USER_ACCESS_TOKEN → ~/.feishu-cli/token.json（access 过期会自动刷新）→ config.yaml 的 user_access_token → App Token 兜底。

涉及命令：

• 消息读：msg history（container 路径）、msg list、msg get、msg mget、msg thread-messages、msg resource-download
• 任务读：task get、task list、task subtask list、task comment list、tasklist get/list/tasks
• 日历读：calendar get/list/primary/agenda/freebusy/suggestion/room-find、calendar event get/list/search、calendar attendee list
• 文件/文档读：file meta/stats/list/version list/version get、file download、doc blocks（读）、board image/nodes/export-code/lint
• sheet 全家桶（项目历史就是这种行为）：sheet read/export/get/meta/list-sheets/find/replace/write/append/insert/delete/clear/import-md/dropdown/filter/filter-view/protect/style/merge/...，所有 sheet 子命令都走 fallback，登录后默认 User、未登录 Tenant 兜底
• wiki 读：wiki get/nodes/spaces/space-get/export/export-tree、wiki member list
• drive：drive pull/push/status
• 其他：user read

2. 写类 / 默认 Bot 身份（resolveOptionalUserToken）

默认 App Token（Bot 身份），仅当显式传 --user-access-token 或 FEISHU_USER_ACCESS_TOKEN 时才切到 User Token，不会自动加载 token.json。

涉及命令：所有 add/create/update/delete/move/copy/import/upload/send/reply/forward/merge-forward 类、comment reply、doc content-update / table 写、msg delete（Bot 自撤回，传显式 User Token 给管理员撤回）等。

3. 必须 User Token（resolveRequiredUserToken / requireUserToken）

强制 User Token，没登录直接报错。

chat create 和 chat link 不在此表：默认走 App Token，仅显式 --user-access-token 时切到 User 身份创建群/获取链接。

登录时 CLI 会自动注入 offline_access 和 auth:user.id:read。如果 refresh_token_present=false，通常是应用未开通 offline_access，需要开通后重新登录。

业务域登录

--domain 可重复或逗号分隔。可选域：approval attendance bitable calendar chat contact doc_access docs drive event im mail minutes search sheets slides task vc whiteboard wiki，或 all。

feishu-cli auth login --domain search --recommend                # 单域
feishu-cli auth login --domain vc --domain minutes --recommend   # 多域
feishu-cli auth login --recommend                                # 全部域（等价 --domain all --recommend）

--scope 与 --domain/--recommend 互斥；最终以 auth check --scope 结果为准。

排错

环境诊断（doctor）

用户报“feishu-cli 不工作”“突然连不上”“配置有问题”时，先用 doctor 缩小问题面：

feishu-cli doctor
feishu-cli doctor --json
feishu-cli doctor --offline
feishu-cli doctor --only user_token
feishu-cli doctor --only proxy

doctor 共 6 项检查；--only 仅接受其中之一（typo 会被服务端拒收）：

每项状态为 pass / warn / fail / skip。整体退出码：全部 pass/skip 或仅 warn → 0；任一 fail → 1。

--json 输出 schema：

{
  "ok": true,
  "checks": [
    {"name": "user_token", "status": "pass", "message": "...", "hint": "..."}
  ]
}

CI 用法：feishu-cli doctor --offline --json | jq -e '.ok == true'。

常见命中：proxy 检查发现 HTTPS_PROXY 拦截 → 把 .feishu.cn,.larkoffice.com,.larksuite.com 加入 NO_PROXY；HTTPS_PROXY 中的 userinfo（user:pass@host）会被 redact 后再上报，无需担心日志泄漏。

已经明确是 scope 缺失时，不需要 doctor，直接 auth check --scope "..."。

v1.27.1 新增：使用 --config <path> 显式覆盖配置时，CLI 会在 stderr 打印 warning，提示 profile 系统被绕过（token.json 自动加载等行为失效）。AI Agent 调试时若看到该 warning，意味着当前命令未走 profile 体系，token 解析仅依赖该 --config 文件中的字段。

多 App Profile（profile）

用户需要在多个飞书租户、多个 App ID 或工作/个人账号之间切换时，用 profile 管理独立的 config.yaml 和 token.json：

feishu-cli profile add work --app-id cli_xxx --app-secret secret_xxx --use
feishu-cli profile list --json
feishu-cli profile current
feishu-cli profile use work
feishu-cli profile use -                    # toggle 到上一个 profile（previous-profile 指针）
feishu-cli profile rename old-name new-name
feishu-cli profile remove old-name
feishu-cli profile migrate --name work

解析优先级：

1. FEISHU_PROFILE=<name> 环境变量强制覆盖。
2. ~/.feishu-cli/active-profile 指针。
3. 指针缺失或失效时，回退到 profiles/ 下字典序第一个（可能不是预期的那个）。
4. 未启用 profile 系统时，继续使用旧布局 ~/.feishu-cli/config.yaml 和 ~/.feishu-cli/token.json。

踩坑（违反直觉、可能丢数据，逐条留意）：

1. `profile add` 不会自动迁移旧配置；已有配置接入 profile 系统必须显式运行 profile migrate，避免静默改变当前环境。
2. `profile migrate` 不可逆且不删旧文件：~/.feishu-cli/config.yaml / token.json 仍留在原位，需要时手动清理；不要把 migrate 当成"备份+迁移"用。
3. `profile use <name>` 不会自动登录：切到一个新建的 profile 后，必须再 auth login 才有 User Token。
4. 进程内锁仅 `sync.Mutex`，不跨进程：并发 profile use / profile rename 在不同 shell 里同时跑会有 race。
5. `profile use -` 在没有上一个 profile 时直接报错：CLI 不会自动回退到字典序首位；先 profile list 确认目标，再 profile use <name> 显式切换。

profile 名校验规则 [A-Za-z0-9_-]{1,64}（禁止 . / .. / profiles / cache 等保留名），违反时 CLI 自身会报错。profile rename 会自动同步 active 与 previous 指针，不需要手动改文件。

auth logout 会清理当前 profile 的 token 和用户 profile 缓存。

Agent 约定

1. 执行业务前先 auth check --scope，缺什么报什么。
2. 登录优先用两步模式（--no-wait --json 拿链接 → 用户授权后 --device-code --json 续轮询）；能开后台任务时也可 --json 阻塞 + run_in_background。把 verification_uri_complete 原样发给用户，不改写 URL。
3. 授权成功后读 authorization_complete 的 missing_scopes：非空只是 warning，开通后按需补授（增量授权，补缺失的几个即可，不会丢已授 scope）。
4. 不把 user_access_token / device_code 写入文档、代码或日志。
5. 错误信息明确指向 scope/token 时直接 auth check；只有错误不明确（"突然不工作"/网络异常）才用 doctor 缩小问题面，不要混用。