核心用法
feishu-doc 是飞书（Lark）官方API封装的文档读写工具，支持四大内容形态：
| 能力 | 操作 | 典型场景 |
|------|------|---------|
| **Docs** | 读取、创建、覆写、追加、块级编辑 | 长文档生成、报告自动化 |
| **Wiki** | 读取Wiki节点，自动解析URL为实体 | 知识库同步、文档迁移 |
| **Sheets** | 读取单元格、批量查询 | 数据报表导出、表格备份 |
| **Bitable** | 读取记录、表元数据 | 轻量数据库导出、记录同步 |
关键设计：长文档分块追加。由于LLM输出限制（~2000-4000 tokens），超长文档需采用"创建→分块→循环追加"模式，而非单次写入。
快速示例
# 创建并追加长文档
node index.js --action create --title "年度报告"
# 获取 doc_token 后
node index.js --action append --token $TOKEN --content "## 第一章..."
node index.js --action append --token $TOKEN --content "## 第二章..."
---
显著优点
1. 官方API背书：唯一依赖 @larksuiteoapi/node-sdk（飞书官方SDK），无第三方中间层，API行为与官方文档完全一致。
2. 安全认证S级：静态分析95分，无危险函数（eval/exec）、无硬编码密钥、输入验证完善；动态分析90分，仅连接 open.feishu.cn 官方端点，HTTPS/TLS 1.2+ 加密。
3. 跨文档形态统一：Wiki URL自动解析、Docs块级操作、Sheets范围读取、Bitable记录查询——同一套CLI风格接口覆盖飞书全文档生态。
4. Token智能缓存：访问令牌自动持久化，避免重复鉴权，提升批量操作效率。
---
潜在缺点与局限性
| 问题 | 说明 | 影响 |
|------|------|------|
| **Token缓存路径隐患** | 使用相对路径 `../../../memory/` 存储缓存文件，若Skill安装位置变动可能导致写入非预期目录 | 低危，建议改用 `os.homedir()` 绝对路径 |
| **Markdown解析器简化** | 自研解析器仅覆盖基础语法，复杂嵌套结构（如多层代码块、表格嵌套）可能解析异常 | 中危，生产环境建议集成 `marked` 或 `remark` |
| **无内置速率限制** | 批量Block插入可能触发飞书API限流，需调用方自行控制并发 | 中危，高频率场景需自行实现退避重试 |
| **依赖预装feishu-common** | 需先安装配套Skill完成认证初始化，无法独立运行 | 使用门槛 |
| **仅支持读取与写入** | 无权限管理、无协作成员操作、无版本历史接口 | 功能边界 |
---
适合人群
- 企业自动化工程师：需将LLM生成内容自动同步至飞书知识库
- 数据分析师：定期导出Sheets/Bitable数据至本地或下游系统
- DevOps/运维团队：构建文档流水线，实现Wiki→Git文档双向同步
- 飞书深度用户：已具备
app_id/app_secret 组织级应用权限
不适合：无飞书企业应用权限的个人用户；需要复杂权限管控或版本管理的场景。
---
常规风险
1. 凭证管理：FEISHU_APP_ID/FEISHU_APP_SECRET 需通过环境变量或 config.json 配置，避免提交至代码仓库。
2. 数据残留：Token缓存文件包含短期访问令牌，多用户共享环境需确保 memory/ 目录权限隔离。
3. API配额消耗：飞书开放平台有租户级QPS限制，高频批量操作前建议评估配额余量。
4. 内容覆盖风险：write 操作为全量覆盖，误执行将导致文档内容丢失；生产环境建议先用 append 模式验证。