Feishu Common

核心用法

feishu-common 是 OpenClaw 飞书生态的基础依赖 Skill，本身不直接面向终端用户，而是作为其他飞书相关 Skill 的底层支撑。主要暴露三个核心能力：

1. 租户 Token 管理：getToken() 自动获取并缓存飞书 Tenant Token，避免重复调用开放平台接口
2. 请求重试机制：fetchWithRetry() 封装带指数退避的重试逻辑，处理网络抖动
3. 认证请求封装：fetchWithAuth() 组合 Token 获取与请求发送，内置 Token 过期自动刷新

依赖 Skill 通过 require("../feishu-common/index.js") 或兼容别名 feishu-client.js 引入使用。

显著优点

• 基础设施定位：统一封装飞书认证复杂性，避免各 Skill 重复实现
• 可靠性设计：内置重试、超时、Token 刷新机制，提升下游 Skill 稳定性
• 零配置使用：依赖 Skill 无需关心飞书凭证管理细节

潜在局限

• 非独立运行：必须配合其他飞书 Skill 使用，单独安装无实际功能
• 隐式耦合：下游 Skill 硬编码依赖路径，迁移或版本变更时存在兼容风险
• 文档缺失：未暴露接口参数说明、错误码定义及 Token 缓存策略细节
• 无监控观测：缺乏日志等级控制、指标上报等可观测能力

适合人群

• 开发飞书相关 Skill 的 OpenClaw 贡献者
• 需要集成飞书开放平台的内部自动化场景

常规风险

• 凭证泄漏风险：若 Token 缓存机制不当，可能存在内存泄漏或日志打印敏感信息
• 级联故障：作为基础设施，本 Skill 异常将导致所有依赖方失效
• 版本兼容性：飞书开放平台 API 升级时，需同步更新本 Skill，否则下游全面受影响
• 路径依赖风险：使用相对路径 ../ 引用，在 Skill 目录结构调整时可能断裂

核心用法

feishu-common 是飞书 API 的底层认证与请求封装工具，专为 OpenClaw 生态设计。主要功能包括：

1. 租户 Token 获取与缓存：通过 getToken() 自动获取飞书租户访问令牌，并实现本地缓存，避免重复请求
2. 认证请求封装：fetchWithAuth() 提供带自动 Token 刷新的 HTTP 请求封装
3. 重试机制：fetchWithRetry() 内置超时与重试逻辑，提升网络不稳定场景下的可靠性

使用方式为依赖 Skill 引入模块：

const { getToken, fetchWithAuth } = require("../feishu-common/index.js");

显著优点

• 安全设计规范：敏感凭证（APP_ID、APP_SECRET）严格从环境变量读取，无硬编码密钥风险；Token 缓存存储于用户目录，生命周期管理合理
• 依赖精简可信：仅依赖 axios (1.6.0) 和 dotenv (16.3.1) 两个知名库，无已知 CVE 漏洞
• 网络边界清晰：所有请求仅限于飞书官方 API (open.feishu.cn)，HTTPS 加密传输，无数据外泄风险
• 代码质量高：139 行可执行代码，结构清晰，职责单一，静态分析得分 92 分

潜在局限

• 无输入校验：当前未对传入 URL 和参数进行严格校验，存在防御性编程不足的问题
• 日志脱敏缺失：错误输出可能包含敏感信息，需使用者自行处理
• 测试覆盖空白：无内置单元测试，需依赖方自行验证集成效果
• 功能单一：仅为认证层封装，不包含飞书具体业务 API（如消息发送、文档操作等）

适合人群

• 需在 OpenClaw 平台开发飞书集成的开发者
• 需要稳定 Token 管理机制的飞书应用开发场景
• 对安全合规有要求的组织级飞书应用开发

常规风险

• 环境变量依赖：需确保 FEISHU_APP_ID 和 FEISHU_APP_SECRET 正确配置，否则运行时直接失败
• Token 缓存失效：极端情况下缓存文件损坏需手动清理
• API 限流：未内置飞书 API 限流处理逻辑，高频调用需使用者自行控制