fix(auth): prefer App Token over User Token for optional commands

resolveOptionalUserToken no longer auto-loads from token.json, ensuring
APIs that work with App Token use it by default. Only explicitly provided
tokens (--user-access-token flag or FEISHU_USER_ACCESS_TOKEN env var)
override to user identity. Search commands (resolveRequiredUserToken)
are unaffected and still use the full priority chain.

Update skill docs and CLAUDE.md to reflect the new token strategy.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: riba2534

CLAUDE.md

@@ -109,11 +109,14 @@ app_secret: "xxx"
 
 **流程**：`auth login` → 浏览器授权 → 回调获取 code → 换取 Token → 保存到 `~/.feishu-cli/token.json`
 
-**Token 优先级链**（`ResolveUserAccessToken`）：
-1. `--user-access-token` 命令行参数
-2. `FEISHU_USER_ACCESS_TOKEN` 环境变量
-3. `~/.feishu-cli/token.json`（access_token 有效直接返回；过期则用 refresh_token 自动刷新）
-4. `config.yaml` 中的 `user_access_token` 静态配置
+**Token 使用策略**：
+- **默认使用 App Token**（租户身份）：wiki、msg、calendar、task 等 55+ 个命令默认通过 `resolveOptionalUserToken` 使用 App Token，不会自动从 token.json 加载 User Token
+- **显式使用 User Token**：通过 `--user-access-token` 参数或 `FEISHU_USER_ACCESS_TOKEN` 环境变量可覆盖为用户身份
+- **必须 User Token**：搜索命令（`search docs/messages/apps`）通过 `resolveRequiredUserToken` 走完整优先级链：
+  1. `--user-access-token` 命令行参数
+  2. `FEISHU_USER_ACCESS_TOKEN` 环境变量
+  3. `~/.feishu-cli/token.json`（access_token 有效直接返回；过期则用 refresh_token 自动刷新）
+  4. `config.yaml` 中的 `user_access_token` 静态配置
 
 **前置条件**：在飞书开放平台 → 应用详情 → 安全设置 → 重定向 URL 中添加 `http://127.0.0.1:9768/callback`
 

cmd/utils.go

@@ -13,16 +13,17 @@ import (
 	"github.com/spf13/cobra"
 )
 
-// resolveOptionalUserToken 尝试解析 user_access_token（可选）
-// 有 token 时使用用户身份，无 token 时回退到应用身份（tenant token）
+// resolveOptionalUserToken 解析显式指定的 user_access_token（可选）
+// 仅检查 --user-access-token 参数和 FEISHU_USER_ACCESS_TOKEN 环境变量，
+// 不自动从 token.json 加载，确保能用 App Token 的 API 默认使用 App Token（租户身份）
 func resolveOptionalUserToken(cmd *cobra.Command) string {
-	flagToken, _ := cmd.Flags().GetString("user-access-token")
-	cfg := config.Get()
-	token, err := auth.ResolveUserAccessToken(flagToken, cfg.UserAccessToken, cfg.AppID, cfg.AppSecret, cfg.BaseURL)
-	if err != nil && cfg.Debug {
-		fmt.Fprintf(os.Stderr, "[提示] 未找到 User Access Token，将使用应用身份访问。可通过 feishu-cli auth login 获取用户授权\n")
+	if flagToken, _ := cmd.Flags().GetString("user-access-token"); flagToken != "" {
+		return flagToken
+	}
+	if envToken := os.Getenv("FEISHU_USER_ACCESS_TOKEN"); envToken != "" {
+		return envToken
 	}
-	return token
+	return ""
 }
 
 // resolveRequiredUserToken 解析 user_access_token（必需）

skills/feishu-cli-auth/SKILL.md

@@ -106,9 +106,13 @@ scope 决定了 Token 能访问哪些 API。登录时通过 `--scopes` 指定（
 offline_access search:docs:read search:message search:app 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 contact:user.base:readonly drive:drive.metadata:readonly
 ```
 
-### 为什么用最大 scope
+### Token 使用策略
 
-feishu-cli 的 wiki、calendar、task、msg 等命令通过 `resolveOptionalUserToken` 支持可选的用户身份。当 token.json 存在时，这些命令会**自动使用 User Access Token**。如果 Token 的 scope 不包含对应权限，API 会返回 99991679 错误（不会回退到应用身份）。一次性授权所有 scope 可以彻底避免此问题。
+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 完整说明
 
@@ -191,7 +195,7 @@ scope 中无目标权限         → 需要重新登录并补充 scope
 
 ## Token 自动刷新机制
 
-每次执行需要 User Access Token 的命令时，`ResolveUserAccessToken()` 按以下优先级链查找：
+搜索等**必须** User Access Token 的命令（`resolveRequiredUserToken`）通过 `ResolveUserAccessToken()` 按以下优先级链查找。其他可选命令（`resolveOptionalUserToken`）仅检查第 1、2 项，默认使用 App Token：
 
 1. `--user-access-token` 命令行参数
 2. `FEISHU_USER_ACCESS_TOKEN` 环境变量
@@ -218,7 +222,7 @@ scope 中无目标权限         → 需要重新登录并补充 scope
 
 ### 可选 User Access Token 的命令
 
-以下命令通过 `resolveOptionalUserToken` 支持可选的用户身份——有 Token 时用用户身份获取更多结果，无 Token 时回退到应用身份。**但如果 Token 存在而 scope 不足，API 会直接报错而不会回退**：
+以下命令通过 `resolveOptionalUserToken` 支持可选的用户身份——**默认使用 App Token（租户身份）**，仅在通过 `--user-access-token` 参数或 `FEISHU_USER_ACCESS_TOKEN` 环境变量显式指定时才使用 User Token：
 
 | 命令类别 | 需要的 scope |
 |---------|-------------|
@@ -240,8 +244,9 @@ feishu-cli auth login --print-url --scopes "offline_access search:docs:read sear
 # ... 用户授权 ...
 feishu-cli auth callback "<回调URL>" --state "<state>"
 
-# 3. 登录后所有命令自动从 token.json 读取 Token
+# 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 "待办事项"
 ```

skills/feishu-cli-toolkit/references/search-commands.md

@@ -11,7 +11,7 @@
 3. **命令行参数**：`--user-access-token <token>`
 4. **环境变量**：`FEISHU_USER_ACCESS_TOKEN=<token>`
 
-Token 有效期约 2 小时，Refresh Token 有效期 30 天。**始终使用最大 scope 范围登录**，一次性覆盖搜索 + wiki + 日历 + 任务等全部功能。详见 `feishu-cli-auth` 技能。
+Token 有效期约 2 小时，Refresh Token 有效期 30 天（需 `offline_access` scope）。搜索命令通过 `resolveRequiredUserToken` 自动从 `token.json` 加载 Token；wiki、日历、任务等命令默认使用 App Token，仅在显式传 `--user-access-token` 时使用用户身份。详见 `feishu-cli-auth` 技能。
 
 ## 搜索消息