feishu-user-auth

Original：🇨🇳 Chinese
Translated
14 scripts

Use this skill when users mention scenarios such as "Feishu authorization", "OAuth", "Device Flow", "open_id", "repeated authorization pop-ups", "token reuse", "supplement authorization scopes", or "where Feishu tokens are stored"—scenarios that require reusing existing local user tokens, only supplementing missing scopes, or troubleshooting the actual storage location of tokens.

9installs
Sourceshuliuzhenhua-sys/shuliu-skills
Added on

NPX Install

npx skill4agent add shuliuzhenhua-sys/shuliu-skills feishu-user-auth

Tags

Translated version includes tags in frontmatter
feishu-authtoken-reuseoauth-authorizationtoken-storagetroubleshooting

SKILL.md Content (Chinese)

View Translation Comparison →

Feishu User Auth

This skill only handles two things:
  1. Initiate Feishu user authorization
  2. Reuse existing tokens as much as possible to avoid repeated authorization pop-ups

When to Use

Use this skill directly when users have the following needs:
  • Implement user authorization for Feishu applications
  • Troubleshoot why authorization pop-ups keep appearing repeatedly
  • Check if a user has already authorized locally
  • Want to add new scopes without losing old authorizations
  • Want to delete a user's local token and re-authorize

Storage Location

By default, this skill stores tokens in the user directory:
  • ~/.feishu-auth/tokens/<appId>.json
If you explicitly configure 
storeDir
in 
config.json
, the path will be changed to:
  • <storeDir>/tokens/<appId>.json
storeDir
supports absolute paths or user directory paths like 
~/.feishu-auth
.
For older versions where tokens are stored in the legacy directory, the script will attempt to migrate from these two locations:
  • <legacyStoreDir>/tokens/<appId>.json
  • <legacyStoreDir>/<appId>__<openId>.json
The script will use this old directory as the default migration source and automatically attempt migration when the new directory is empty.

Pre-configuration

First, find the installed skill directory, then maintain the 
config.json
file within it.
Common installation locations:
  • Project-local installation: 
    ./.agents/skills/feishu-user-auth/config.json
  • Global installation (
    npx skills add ... -g
    ): 
    ~/.agents/skills/feishu-user-auth/config.json
If you don't want to modify the skill directory, you can prepare your own configuration file and pass it in via 
--config
later.
Format as follows:
json
{
  "appId": "cli_xxx",
  "appSecret": "replace-with-app-secret",
  "brand": "feishu"
}
Notes:
  • appId
    and 
    appSecret
    are required
  • brand
    is optional, default is 
    feishu
  • storeDir
    is optional; if not specified, the default is 
    ~/.feishu-auth
  • If 
    storeDir
    is explicitly filled in, it can be an absolute path or 
    ~/.feishu-auth
  • legacyStoreDir
    is optional, default points to the skill's own 
    state/
    directory
This set of scripts no longer depends on environment variables like 
FEISHU_APP_ID
, 
FEISHU_APP_SECRET
, 
FEISHU_BRAND
, and 
FEISHU_AUTH_*
in the system.

Execution Methods

After installation, 
feishu-auth
is not automatically added to the PATH by default.
The most reliable way to call it is to directly execute the bin file in the installation directory:
bash
./.agents/skills/feishu-user-auth/bin/feishu-auth.js auth
If installed globally, you can execute it from any directory:
bash
~/.agents/skills/feishu-user-auth/bin/feishu-auth.js auth
If you want to use the 
feishu-auth
command name directly, you can create a link yourself:
bash
mkdir -p ~/.local/bin
ln -sf ~/.agents/skills/feishu-user-auth/bin/feishu-auth.js ~/.local/bin/feishu-auth
Then ensure 
~/.local/bin
is in your PATH, and you can execute directly:
bash
feishu-auth auth
Available commands:
bash
<skill-dir>/bin/feishu-auth.js auth [--batch-size 60] [--open-id ou_xxx]
<skill-dir>/bin/feishu-auth.js user-auth [--batch-size 60] [--open-id ou_xxx]
<skill-dir>/bin/feishu-auth.js auth --scope "scope1 scope2"
<skill-dir>/bin/feishu-auth.js refresh-token [--open-id ou_xxx]
<skill-dir>/bin/feishu-auth.js refresh-token [--open-id ou_xxx] --force
<skill-dir>/bin/feishu-auth.js show-token
<skill-dir>/bin/feishu-auth.js show-token --open-id ou_xxx
<skill-dir>/bin/feishu-auth.js remove-token --open-id ou_xxx
<skill-dir>/bin/feishu-auth.js system-token
<skill-dir>/bin/feishu-auth.js system-auth
<skill-dir>/bin/feishu-auth.js --config /path/to/config.json auth
<skill-dir>/bin/feishu-auth.js --help
If you are developing locally in a repository, you can execute the source code entry in the repository root directory:
bash
node skills/feishu-user-auth/scripts/run-auth.js auth

Working Rules

Follow this sequence:
  1. Prioritize reusing saved tokens
  2. If 
    --open-id
    is not specified, automatically select the most suitable user record to reuse
  3. If the application's scopes are more than the locally authorized scopes, only supplement the missing parts
  4. After batch authorization, save the union of scopes and do not overwrite old batches

Troubleshooting Key Points

If users say "It still pops up even though I've authorized before", check these items first:
  1. Whether the script of this skill is used, instead of other scripts
  2. Whether the 
    appId
    in 
    config.json
    corresponds to the same app as the old token
  3. Whether there is indeed a record for the app in the current 
    storeDir/tokens/
  4. Whether the scopes required this time exceed the historically authorized scope
  5. Whether the token has 
    expired
    or is in 
    needs_refresh
    status

Output Requirements

Inform users of these key pieces of information:
  1. Which 
    open_id
    was reused
  2. Whether re-authorization is actually needed this time
  3. If needed, which scopes are missing
  4. The final location of the token in the 
    storeDir/tokens/<appId>.json
    file