feishu-cli-auth

name	feishu-cli-auth
description	飞书 OAuth 认证和 User Access Token 管理。两步式非交互登录（AI Agent 专用）、 Token 状态检查、scope 配置、自动刷新机制、搜索功能的 Token 依赖关系。 当用户请求"登录飞书"、"获取 Token"、"OAuth 授权"、"auth login"、"认证"、 "搜索需要什么权限"、"Token 过期了"、"刷新 Token"时使用。 当遇到权限错误（如 99991679 Unauthorized）、Token 过期、state 不匹配等问题时也应使用此技能。 也适用于：搜索命令报权限错误、Token 相关的排错、需要判断当前授权状态的场景。 当其他飞书技能（toolkit/msg/read 等）遇到 User Access Token 相关问题时，也应参考此技能。
user-invocable	true
allowed-tools	Bash, Read

飞书 OAuth 认证与 Token 管理

feishu-cli 通过 OAuth 2.0 Authorization Code Flow 获取 User Access Token，用于搜索等需要用户身份的 API。

核心概念

Token 存储位置：所有 OAuth Token 保存在 ~/.feishu-cli/token.json，包括 Access Token、Refresh Token、过期时间和授权 scope。登录、刷新、退出等操作都围绕此文件进行。

两种身份：

• App Access Token（应用身份）：通过 app_id/app_secret 自动获取，大多数文档操作使用此身份
• User Access Token（用户身份）：需 OAuth 授权，搜索 API 必须使用此身份

Token 生命周期：

• Access Token：2 小时有效
• Refresh Token：30 天有效（需 offline_access scope）
• 过期后自动用 Refresh Token 刷新，用户无感

---

两步式非交互登录（AI Agent 推荐）

AI Agent 的 Bash tool 无法进行交互式 stdin 输入，因此 --manual 模式不可用。使用 --print-url + auth callback 两步式流程：

步骤 1：生成授权 URL

始终使用最大 scope 范围授权，一次性覆盖 feishu-cli 所有用户身份功能，避免后续因 scope 不足导致 99991679 错误：

feishu-cli auth login --print-url --scopes "offline_access search:docs:read search:message drive:drive.search:readonly wiki:wiki:readonly calendar:calendar:read calendar:calendar.event:read calendar:calendar.event:create calendar:calendar.event:update calendar:calendar.event:reply calendar:calendar.free_busy:read task:task:read task:task:write task:tasklist:read task:tasklist:write im:message:readonly im:message.group_msg:get_as_user im:chat:read contact:user.base:readonly drive:drive.metadata:readonly"

输出 JSON（stdout）：

{
  "auth_url": "https://accounts.feishu.cn/open-apis/authen/v1/authorize?...",
  "state": "随机64字符十六进制字符串",
  "redirect_uri": "http://127.0.0.1:9768/callback"
}

立即返回，不阻塞，不启动 HTTP 服务器。

将 auth_url 展示给用户，请用户在浏览器中打开并完成授权。授权后浏览器会跳转到一个无法访问的页面（127.0.0.1:9768/callback?code=xxx&state=yyy），这是正常的——让用户复制地址栏中的完整 URL。

步骤 2：用回调 URL 换 Token

feishu-cli auth callback "<回调URL>" --state "<步骤1输出的state>"

输出 JSON（stdout）+ 人类可读信息（stderr）：

{
  "status": "success",
  "expires_at": "2026-03-09T04:31:11+08:00",
  "scope": "auth:user.id:read search:docs:read search:message offline_access"
}

Token 自动保存到 ~/.feishu-cli/token.json。

auth callback 常见错误

错误	原因	解决
code has expired	授权 code 有效期约 5 分钟，用户复制回调 URL 太慢	重新执行步骤 1 获取新的授权 URL，提醒用户尽快完成
state 不匹配	--state 参数与回调 URL 中的 state 不一致，或混用了不同次 --print-url 的结果	确保 --state 使用的是同一次 --print-url 输出的 state 值
网络超时 / 连接失败	无法访问飞书 OAuth 服务器（网络不通或代理问题）	检查网络连通性，确认能访问 open.feishu.cn；如有代理需配置 HTTPS_PROXY

完整示例

# 步骤 1（使用最大 scope 范围）
feishu-cli auth login --print-url --scopes "offline_access search:docs:read search:message drive:drive.search:readonly wiki:wiki:readonly calendar:calendar:read calendar:calendar.event:read calendar:calendar.event:create calendar:calendar.event:update calendar:calendar.event:reply calendar:calendar.free_busy:read task:task:read task:task:write task:tasklist:read task:tasklist:write im:message:readonly im:message.group_msg:get_as_user im:chat:read contact:user.base:readonly drive:drive.metadata:readonly"
# → 展示 auth_url 给用户，用户浏览器授权后复制回调 URL

# 步骤 2（用步骤 1 的 state 和用户提供的回调 URL）
feishu-cli auth callback "http://127.0.0.1:9768/callback?code=xxx&state=yyy" --state "yyy"

---

Scope 配置

scope 决定了 Token 能访问哪些 API。登录时通过 --scopes 指定（空格分隔）。scope 名称 = 飞书开放平台开发者后台的权限名称，最多 50 个，多次授权累加生效。

默认策略：始终使用最大 scope

每次登录都使用以下完整 scope 列表，一次性覆盖 feishu-cli 全部用户身份功能。避免因 scope 不足导致部分命令报 99991679 错误：

offline_access search:docs:read search:message drive:drive.search:readonly wiki:wiki:readonly calendar:calendar:read calendar:calendar.event:read calendar:calendar.event:create calendar:calendar.event:update calendar:calendar.event:reply calendar:calendar.free_busy:read task:task:read task:task:write task:tasklist:read task:tasklist:write im:message:readonly im:message.group_msg:get_as_user im:chat:read contact:user.base:readonly drive:drive.metadata:readonly

Token 使用策略

feishu-cli 的 wiki、calendar、task、msg 等命令通过 resolveOptionalUserToken 支持可选的用户身份。这些命令默认使用 App Token（租户身份），不会自动从 token.json 加载 User Token。只有在以下情况才使用 User Token：

• 通过 --user-access-token 参数显式传入
• 通过 FEISHU_USER_ACCESS_TOKEN 环境变量显式设置

搜索命令（search docs/messages/apps）通过 resolveRequiredUserToken 必须使用 User Token，会从 token.json 自动加载。

Scope 完整说明

scope	作用	对应命令
offline_access	获取 Refresh Token（30 天有效）	必须包含，否则 2 小时后需重新登录
search:docs:read	搜索云文档	search docs
search:message	搜索消息	search messages
drive:drive.search:readonly	搜索云空间文件	search docs（补充权限）
wiki:wiki:readonly	知识库读取（用户身份）	wiki get/export/nodes
calendar:calendar:read	日历读取	calendar list/get/primary
calendar:calendar.event:read	日历事件读取	calendar event-search
calendar:calendar.event:create	创建日历事件	calendar create-event
calendar:calendar.event:update	更新日历事件	calendar event-reply
calendar:calendar.event:reply	回复日历事件	calendar event-reply
calendar:calendar.free_busy:read	忙闲查询	calendar freebusy
task:task:read	任务读取	task list/get
task:task:write	任务写入	task create/complete
task:tasklist:read	任务列表读取	tasklist list/get
task:tasklist:write	任务列表写入	tasklist create/delete
im:message:readonly	消息历史读取	msg history/get
im:message.group_msg:get_as_user	用户身份读取群消息	msg list/history（User Token 读群消息必需）
im:chat:read	群聊信息读取	chat get/search-chats
contact:user.base:readonly	用户信息读取	user info/search
drive:drive.metadata:readonly	文件元数据读取	file list/meta
auth:user.id:read	用户身份信息	通常自动包含

前提条件

scope 中的权限必须先在飞书开放平台 → 应用详情 → 权限管理中启用。未启用的权限在授权时会被忽略或报错 20027。

常见错误

错误	原因	解决
error=99991679, Unauthorized	Token 的 scope 不包含目标 API 权限	重新登录，使用最大 scope
Refresh Token 为空	缺少 offline_access scope	重新登录，使用最大 scope
error=20027	开发者后台未启用该权限	在飞书开放平台启用对应权限后重新授权

---

Token 状态检查

# 人类可读格式
feishu-cli auth status

# JSON 格式（AI Agent 推荐）
feishu-cli auth status -o json

当已登录且 Token 有效时：

{
  "logged_in": true,
  "access_token_valid": true,
  "access_token_expires_at": "2026-03-09T04:32:19+08:00",
  "refresh_token_valid": true,
  "refresh_token_expires_at": "2026-03-16T02:32:19+08:00",
  "scope": "auth:user.id:read search:docs:read search:message offline_access"
}

当未登录时：

{"logged_in": false}

状态判断逻辑

logged_in=false           → 从未登录，需要 auth login
access_token_valid=true   → 正常可用
access_token_valid=false + refresh_token_valid=true → 下次调用时自动刷新，无需操作
access_token_valid=false + refresh_token_valid=false → 需要重新 auth login
scope 中无目标权限         → 需要重新登录并补充 scope

---

Token 自动刷新机制

搜索等必须 User Access Token 的命令（resolveRequiredUserToken）通过 ResolveUserAccessToken() 按以下优先级链查找。其他可选命令（resolveOptionalUserToken）仅检查第 1、2 项，默认使用 App Token：

1. --user-access-token 命令行参数
2. FEISHU_USER_ACCESS_TOKEN 环境变量
3. ~/.feishu-cli/token.json：
   • access_token 有效 → 直接使用
   • access_token 过期 + refresh_token 有效 → 自动刷新并保存新 Token
   • 都过期 → 报错"已过期，请重新登录"
4. config.yaml 中的 user_access_token 静态配置
5. 全部为空 → 报错"缺少 User Access Token"，列出 4 种获取方式

刷新过程对用户透明：stderr 输出 [自动刷新] 刷新成功...，命令正常执行。

---

User Access Token 的使用场景

必需 User Access Token 的命令

命令	需要的 scope
search docs "关键词"	search:docs:read
search messages "关键词"	search:message
search apps "关键词"	（需确认应用是否已开通搜索应用权限）

可选 User Access Token 的命令

以下命令通过 resolveOptionalUserToken 支持可选的用户身份——默认使用 App Token（租户身份），仅在通过 --user-access-token 参数或 FEISHU_USER_ACCESS_TOKEN 环境变量显式指定时才使用 User Token：

命令类别	需要的 scope
wiki get/export/nodes	wiki:wiki:readonly
calendar list/get/event-search/freebusy	calendar:calendar:read 等
task create/complete/list	task:task:read task:task:write
tasklist create/list/delete	task:tasklist:read task:tasklist:write
msg history/get	im:message:readonly
user info/search	contact:user.base:readonly

登录前的检查流程

# 1. 检查是否已登录且 Token 有效
feishu-cli auth status -o json

# 2. 如果未登录或已过期，执行两步式登录（使用最大 scope）
feishu-cli auth login --print-url --scopes "offline_access search:docs:read search:message drive:drive.search:readonly wiki:wiki:readonly calendar:calendar:read calendar:calendar.event:read calendar:calendar.event:create calendar:calendar.event:update calendar:calendar.event:reply calendar:calendar.free_busy:read task:task:read task:task:write task:tasklist:read task:tasklist:write im:message:readonly im:message.group_msg:get_as_user im:chat:read contact:user.base:readonly drive:drive.metadata:readonly"
# ... 用户授权 ...
feishu-cli auth callback "<回调URL>" --state "<state>"

# 3. 登录后搜索命令自动从 token.json 读取 Token
feishu-cli search docs "产品需求"
# 其他命令默认使用 App Token，需要时可显式传 --user-access-token
feishu-cli wiki export <node_token> -o doc.md
feishu-cli task create --summary "待办事项"

---

其他登录模式

除 AI Agent 的两步式外，还有两种人类用户直接使用的模式（同样使用最大 scope）：

# 本地桌面环境（默认）：自动打开浏览器 + 本地 HTTP 回调
feishu-cli auth login --scopes "offline_access search:docs:read search:message drive:drive.search:readonly wiki:wiki:readonly calendar:calendar:read calendar:calendar.event:read calendar:calendar.event:create calendar:calendar.event:update calendar:calendar.event:reply calendar:calendar.free_busy:read task:task:read task:task:write task:tasklist:read task:tasklist:write im:message:readonly im:message.group_msg:get_as_user im:chat:read contact:user.base:readonly drive:drive.metadata:readonly"

# 远程 SSH 环境：打印 URL，用户手动粘贴回调 URL（交互式 stdin）
feishu-cli auth login --manual --scopes "offline_access search:docs:read search:message drive:drive.search:readonly wiki:wiki:readonly calendar:calendar:read calendar:calendar.event:read calendar:calendar.event:create calendar:calendar.event:update calendar:calendar.event:reply calendar:calendar.free_busy:read task:task:read task:task:write task:tasklist:read task:tasklist:write im:message:readonly im:message.group_msg:get_as_user im:chat:read contact:user.base:readonly drive:drive.metadata:readonly"

前置条件

在飞书开放平台 → 应用详情 → 安全设置 → 重定向 URL 中添加：

http://127.0.0.1:9768/callback

如果使用自定义端口（--port 8080），需添加对应的重定向 URL。

---

退出登录

feishu-cli auth logout

删除 ~/.feishu-cli/token.json，不影响 App Access Token（app_id/app_secret）。

---

排错指南

问题	诊断	解决
"缺少 User Access Token"	从未登录	执行 auth login
"User Access Token 已过期"	token.json 中 access + refresh 都过期	重新 auth login
搜索报 99991679 权限错误	scope 不足	重新登录，加上缺失的 scope
Refresh Token 为空	未包含 offline_access scope	重新登录，加上 offline_access
"state 不匹配"	auth callback 的 --state 与 URL 中的 state 不一致	确保使用同一次 --print-url 的 state
"端口被占用"	9768 端口已被其他进程使用	使用 --port 其他端口，并在飞书平台添加对应回调 URL
auth login --manual 在 AI Agent 中卡住	stdin 阻塞	改用 --print-url + auth callback 两步式