Feishu Bot — 飞书知识库与云文档工具集

基于 Node.js 的飞书（Feishu / Lark）知识库（Wiki）与云文档（Docx）操作工具集。通过 npm scripts 驱动，覆盖读取、导出（dump）、搜索、写入、编辑、OAuth 登录授权全流程，专为 AI Agent 与自动化脚本设计。

✨ 功能特性

• 📖 知识库（Wiki）
  • 列出空间与节点树（wiki:tree）
  • 创建知识库空间（wiki:create）
  • 添加 Bot / 成员到空间（wiki:add）
• 📄 云文档（Docx）
  • 读取文档正文与元素（article:read / docx:elements）
  • 写入 / 编辑文章（article:write）
  • Markdown 导入成飞书文档（article:import-markdown）
  • 更新标题结构（article:update-headings）
• 🗂 导出（Dump）
  • 整个空间导出为 Markdown（wiki:export）
  • 树形导出 + 媒体下载（wiki:export-tree）
• 🔐 登录与授权
  • 应用身份（tenant_access_token）
  • 管理员 OAuth 用户身份（user_access_token，oauth:user-token）
  • 权限自检（check:permissions / write:check）
• ✈️ 其他实用脚本：旅行规划生成、面试资料整理、采访稿整合等

🚀 快速开始

环境要求

• Node.js 18+（内置 fetch，无第三方依赖）
• 一个飞书开放平台应用：https://open.feishu.cn/app

1. 安装与配置

git clone https://github.com/VitaElegy/feishu_bot.git
cd feishu_bot
cp .env.example .env

编辑 .env，填入应用凭据：

FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_WIKI_SPACE_ID=            # 可选：默认空间 ID
FEISHU_WIKI_ROOT_NODE_TOKEN=     # 可选：默认根节点 token

⚠️ .env 与 .user-token.json 已被 .gitignore 忽略，绝不会进入版本库。

2. 验证权限

npm run check:permissions   # 检查应用 scopes 是否齐全
npm run wiki:tree           # 列出可见的知识库节点树

3. 管理员 OAuth 授权（写操作用）

npm run oauth:user-token    # 浏览器授权，生成 .user-token.json

关键约定：读取/导出用应用身份即可；添加成员、创建空间、真实写入用管理员 OAuth 身份。

📋 命令速查

命令	作用
npm run wiki:tree	列出知识库节点树
npm run wiki:create	创建知识库空间
npm run wiki:add	添加 Bot/成员到空间
npm run wiki:export	导出整个空间为 Markdown
npm run wiki:export-tree	树形导出 + 下载媒体
npm run article:read	读取文档正文
npm run article:write	写入文档
npm run article:import-markdown	Markdown 导入飞书文档
npm run article:update-headings	更新文档标题结构
npm run docx:elements	读取文档元素
npm run oauth:user-token	OAuth 登录获取用户 token
npm run check:permissions	权限自检
npm run write:check	写入能力自检
npm run requestions:collect	采集需求/问题
npm run travel:tokyo-map	东京路线图生成
npm run travel:japan-planner	日本行程规划

完整脚本清单见 scripts/ 目录（31 个脚本）。

🛡 健壮性设计

所有脚本共用 lib/feishu.mjs 作为统一飞书客户端，避免每个脚本各自复制一份 HTTP / 鉴权逻辑：

• 强制 .env：缺失或缺少必填 key 立即报错退出，绝不回退到 .env.example 占位凭据
• token 缓存：tenant_access_token 进程内缓存，过期前自动刷新
• 过期校验：读取 user_access_token 时校验过期时间，过期立即提示重新 npm run oauth:user-token，而不是带着坏 token 打到飞书 API
• 超时与重试：所有请求默认 30s 超时；429 / 5xx / 频控错误自动指数退避重试（最多 3 次）
• 统一错误出口：fail() 打印完整错误对象并退出；{ exit: false } 可在清理逻辑之后抛异常
• 写入保护：写脚本支持 --dry-run，先看计划再落笔，写完必须 article:read 回读校验
• 媒体下载：downloadFile() 统一处理超时、错误与 content-type 映射

📁 目录结构

feishu_bot/
├── scripts/            # 全部操作脚本（mjs / py）
├── lib/
│   └── feishu.mjs      # 共享飞书客户端：env、token、HTTP、下载
├── docs/
│   ├── FEISHU_KNOWLEDGE_BASE_ACCESS.md   # AI 接手访问手册（必读）
│   └── proposals/                        # 方案提案
├── package.json        # npm scripts 入口
├── .env.example        # 环境变量模板
└── .gitignore          # 敏感文件保护

📚 文档

• 飞书知识库访问手册 — 权限模型、常见问题、AI 接手指南

📄 License

保留所有权利（All rights reserved）。仅限个人使用与学习，请勿用于商业用途。