Refly CLI 状态诊断实战用 refly status 排查配置、认证与 Skill 安装问题【免费下载链接】reflyThe first open-source agent skills builder. Define skills by vibe workflow, run on Claude Code, Cursor, Codex more. Build Clawdbot · APIs for Lovable · Bots for Slack Lark/Feishu · Skills are infrastructure, not prompts.项目地址: https://gitcode.com/GitHub_Trending/re/refly本文以 Refly CLI 的refly status命令及配套 Claude Code 斜杠命令 refly-status.md 为主体讲清楚这条诊断命令检查了哪些内容、输出 JSON 的每个字段从哪来、认证状态如何被后端二次校验以及如何根据输出中的错误码与退出码完成故障排查。读完本文你可以用一条命令判断 CLI 是否可用、登录是否有效、Skill 是否安装到位并能读懂其背后的配置、令牌刷新与符号链接机制。一、refly status 是什么refly status是 Refly CLI 的体检命令用于一次性检查四件事CLI 版本与配置目录、API 端点、认证状态含过期判断、Skill 安装状态。它的实现在 status.ts基于 commander 注册refly status仓库中还有一个同名文件 refly-status.md它不是给人直接读的文档而是一个Claude Code 斜杠命令定义。该文件带 frontmatter--- name: refly-status description: Check Refly CLI configuration and authentication status ---其正文要求 Agent 执行refly status解析 JSON 并汇总五个要点CLI 版本、当前用户、API 端点、认证状态与有效期、Skill 安装状态若未认证则建议执行refly login。这个.md文件会随refly init一起安装installer.ts 中的installSlashCommands()会把packages/cli/commands/目录下的所有.md文件复制到~/.claude/commands/于是 Claude Code 中就能直接调用/refly-status让 Agent 完成这套状态汇总。也就是说refly status既是人工排查工具也是 Agent 自动化诊断的入口。二、输出字段逐字段解读2.1 成功响应认证有效时命令通过ok(status, payload)输出成功响应。payload 的构造见 status.ts#L52-L65字段来源说明cli_versiongetCliVersion()读取 CLI 包自身package.json的 version读取失败时回退为0.1.0见 paths.ts#L12-L20config_dirgetReflyDir()固定为~/.refly目录不存在会自动创建api_endpointgetApiEndpoint()当前生效的 API 端点取值优先级见下文 3.2 节auth_status后端校验结果三态valid/expired/missingauth_method配置的认证方式oauth、apikey或nullauth_details按方式展开OAuth 时输出{ provider }google/githubAPI Key 时输出{ keyId, keyName }无则nulluserGET /v1/user/me当前用户{ uid, name?, email? }未认证时为nullskill.installedisSkillInstalled()~/.refly/skills/base/SKILL.md是否存在skill.versionSKILL.md frontmatterSkill 版本取不到时为nullskill.up_to_date本地比对结果本地 Skill 是否与当前 CLI 包内版本一致需要说明的是payload 本身不直接输出 token 过期时间戳。斜杠命令文档中提到的expiry对应两处事实——配置文件~/.refly/config.json中记录的auth.expiresAt登录时写入设备流登录固定为 1 小时见 login.ts#L218-L224以及 API 客户端在请求前比较该时间戳并自动刷新令牌的机制见 client.ts#L87-L99。refly status把本地凭证看似存在、但后端已不认的情况归为expired状态返回。2.2 输出格式自动检测输出并不是固定 JSON。formatter.ts#L47-L67 的resolveFormat()实现了三级优先级命令行显式指定的 format 参数环境变量REFLY_FORMAT取值pretty/json/compact/plain始终生效自动检测TTY 交互环境用pretty人类可读管道/重定向环境自动切到json供脚本和 Agent 解析。这正是斜杠命令能解析 JSON的前提在 Claude Code 中命令走管道输出天然就是 JSON。统一 JSON 结构定义在 output.ts#L21-L49{ ok: true, type: status, version: 1.0, payload: { ...: 上述字段 } }2.3 失败响应与退出码当auth_status不是valid时命令不会输出成功响应而是以错误码AUTH_REQUIRED失败退出status.ts#L68-L77消息区分两种情况本地有凭证但后端校验不通过 →Authentication expired本地根本没有凭证 →Not authenticated。两种情况都会带上完整 payload 作为details并给出hint: refly login。错误结构为{ ok: false, type: error, version: 1.0, error: { code: AUTH_REQUIRED, message: Not authenticated, details: { cli_version: ..., auth_status: missing, ...: ... }, hint: refly login } }若命令执行过程本身抛异常如读取配置失败则返回INTERNAL_ERROR并提示Try runningrefly initfirst。退出码映射规则在 output.ts#L232-L238AUTH_*类为 2校验/输入类为 3网络/超时段为 4NOT_FOUND类为 5其余为 1——脚本中可以用$?区分该重新登录还是该先 init。三、认证状态是如何判定的refly status的认证判断分两步本地检查 后端在线校验。3.1 本地检查isAuthenticated()config.ts#L170-L180 中本地检查只看凭证是否存在auth.method apikey时要求auth.apiKey非空其余情况即 OAuth要求auth.accessToken非空。注意这一步不判断 token 是否过期所以本地看起来已登录不代表真的可用。3.2 后端校验verifyConnection()本地通过后才调用 client.ts#L415-L452 的verifyConnection()按认证方式取出凭证API Key 或 access token取不到直接返回authenticated: false发起GET /v1/user/me请求status.ts 中verification.user即来自这里根据结果归类请求成功 →connected: true, authenticated: true并带回authMethod与用户信息抛出AuthErrorHTTP 401/403 等→connected: true, authenticated: false即网络通、登录失效对应expired抛出NetworkError连不上 API→connected: false, authenticated: false。status 命令最终把三者映射为authenticated→validconnected但未认证 →expired本地就没有凭证 →missing。3.3 令牌刷新机制为什么 OAuth 会话能长期保持 validAPI 客户端在每次带认证的请求前都会比较auth.expiresAt与当前时间client.ts#L87-L99若已过期先调用POST /v1/auth/cli/oauth/refresh用 refresh token 换新令牌成功后写回config.json新的 access/refresh token 与 1 小时后到期的expiresAt刷新失败才抛出 Session expired, please login again。API Key 方式则不需要刷新直接使用X-API-Key请求头。3.4 API 端点的取值优先级api_endpoint字段的来源在 config.ts#L140-L150优先级为环境变量REFLY_API_ENDPOINT~/.refly/config.json中的api.endpoint构建时注入的默认值源码默认https://refly.aiconfig.ts#L83。这意味着自部署或测试环境下只需设置REFLY_API_ENDPOINT即可让refly status指向自建后端。四、配置文件与凭证的安全存储所有状态都落在~/.refly/config.json。其结构由 zod schema 校验config.ts#L34-L72关键字段{ version: 1, auth: { method: oauth, accessToken: ..., refreshToken: ..., expiresAt: ISO-8601 时间戳, provider: google, user: { uid: ..., email: ..., name: ... } }, api: { endpoint: https://refly.ai }, skill: { installedVersion: 0.1.26, installedAt: ... } }auth.method只有oauth与apikey两个枚举值API Key 方式额外存apiKey/apiKeyId/apiKeyName写入采用临时文件 原子 rename文件权限强制0600仅属主可读写非 Windows 平台还会对已存在的文件补做chmodconfig.ts#L116-L135配置文件缺失或 JSON 解析失败时loadConfig()静默回退到默认配置而不是报错——这也是refly status能把从未登录识别为missing而不是崩溃的原因。两种登录方式的差异对应refly login即 status 失败时的修复动作设备流默认refly login先POST /v1/auth/cli/device/init拿deviceId/userCode打开浏览器授权页然后以 2 秒间隔轮询GET /v1/auth/cli/device/status最长 5 分钟授权成功后存储 OAuth 令牌。Ctrl-C 会先调device/cancel清理会话再退出login.ts#L109-L273API Keyrefly login -k rf_xxxkey 必须以rf_开头先经POST /v1/auth/cli/api-key/validate在线校验通过后连同用户信息写入配置login.ts#L39-L83。五、Skill 安装状态是怎么判定的skill字段由 installer.ts#L226-L250 的isSkillInstalled()提供它检查的是符号链接式 Skill 架构安装判定~/.refly/skills/base/SKILL.md存在即installed: true。refly init安装时会把包内 SKILL.md 和references/下规则文件workflow/node/file/skill 等拷贝到~/.refly/skills/base/再创建符号链接~/.claude/skills/refly - ~/.refly/skills/base/路径逻辑见 paths.ts#L118-L150版本判定从 SKILL.md frontmatter 中提取version: x.y.z取不到则回退到 CLI 包package.json的版本符号链接健康同时校验~/.claude/skills/refly指向是否有效isSkillSymlinkValid用于判断 Claude Code 端是否真的能加载到 Skill。如果skill.installed为false说明还没跑过refly init这也解释了 status 命令异常分支为何提示Try runningrefly initfirst。六、故障排查速查表现象输出特征原因源码依据处理未登录auth_status: missingcode: AUTH_REQUIRED退出码 2配置中无 accessToken/apiKeystatus.ts#L68-L77refly login默认设备流或refly login -k rf_key登录过期auth_status: expired消息 Authentication expired退出码 2本地有凭证但GET /v1/user/me被拒401/403重新refly login若 refresh 也失败说明 refresh token 已失效连不上 APIverifyConnection返回connected: false请求超时/网络错误NetworkErrorclient.ts#L446-L448检查网络/代理或设置REFLY_API_ENDPOINT指向正确端点命令内部异常code: INTERNAL_ERRORhint 指向refly init命令执行抛异常status.ts#L80-L86refly init重建配置与 Skill 目录Skill 缺失skill.installed: false~/.refly/skills/base/SKILL.md不存在refly init日常使用建议在脚本或 Agent 流程中refly status是最轻量的前置检查——管道调用时自动输出 JSON直接读ok/error.code即可分流处理交互终端里则会以 pretty 格式呈现便于人工快速扫一眼五个关键状态。七、相关文件索引斜杠命令定义本文主体文档packages/cli/commands/refly-status.md命令实现packages/cli/src/commands/status.ts连接与认证校验、令牌刷新packages/cli/src/api/client.ts配置 schema、端点优先级、凭证读写packages/cli/src/config/config.ts目录与路径约定~/.refly、~/.claude/skillspackages/cli/src/config/paths.tsSkill 安装与状态检测packages/cli/src/skill/installer.ts统一输出格式与退出码packages/cli/src/utils/output.ts、packages/cli/src/utils/formatter.ts命令总览与 JSON 输出规范packages/cli/README.md包元信息版本 0.1.26、Node 18、bin 名reflypackages/cli/package.json适用前提以上行为以当前仓库powerformer/refly-clipackage.json 中声明版本 0.1.26Node 18源码为准api_endpoint、构建环境production/test/staging 等会随构建参数注入默认值自部署场景请以REFLY_API_ENDPOINT实际指向为准。【免费下载链接】reflyThe first open-source agent skills builder. Define skills by vibe workflow, run on Claude Code, Cursor, Codex more. Build Clawdbot · APIs for Lovable · Bots for Slack Lark/Feishu · Skills are infrastructure, not prompts.项目地址: https://gitcode.com/GitHub_Trending/re/refly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
