统一 CLI 操作飞书全量 API
6 个模块、50+ 命令覆盖文档、任务、Wiki、多维表格、成员目录。OAuth2 全自动管理，Token 过期自动刷新，Markdown 双向转换。仅依赖 Python 3 标准库，无需 pip install。
FEATURES
创建、读取、追加、删除云文档。Markdown 到 Block 结构双向转换，Agent 直接操作文档内容。
完整的任务生命周期：创建、更新、评论、完成。支持批量创建和关键词过滤。
Bitable 全量 CRUD，支持 500 条自动分批。JSON / CSV 导出，字段定义查询。
空间浏览、递归目录树、节点读取。从 Markdown 文件直接创建 Wiki 页面。
组织成员扫描与本地缓存，模糊匹配查找。解析 @mention 为用户 ID。
Token 过期自动刷新，Scope 不足自动增量授权。User Identity Only，不降级到应用身份。
REFERENCE
读写飞书云文档，Markdown 双向转换
| 命令 | 说明 | 示例 |
|---|---|---|
list | 列出云空间文件 | ./feishu doc list |
tree | 递归目录树 | ./feishu doc tree --token "xxx" |
read-raw | 按名称搜索并读取 | ./feishu doc read-raw --name "需求文档" |
create | 创建新文档 | ./feishu doc create --title "设计方案" |
append-markdown | 追加 Markdown | ./feishu doc append-markdown --token "xxx" --file spec.md |
trash | 移入回收站 | ./feishu doc trash --token "xxx" |
完整的任务 v2 生命周期管理
| 命令 | 说明 | 示例 |
|---|---|---|
create | 创建任务 | ./feishu task create --summary "审计" --due "2026-03-01" |
list | 列出任务 | ./feishu task list --keyword "重构" |
update | 更新任务 | ./feishu task update --id "xxx" --summary "新标题" |
complete | 标记完成 | ./feishu task complete --id "xxx" |
comment | 添加评论 | ./feishu task comment --id "xxx" --content "已完成" |
batch-create | 批量创建 | ./feishu task batch-create --file tasks.json |
Bitable 全量 CRUD，批量操作与导出
| 命令 | 说明 | 示例 |
|---|---|---|
list-tables | 列出数据表 | ./feishu bitable list-tables --app-token "basXXX" |
list-fields | 列出字段 | ./feishu bitable list-fields --app-token "xxx" --table-id "yyy" |
list-records | 列出记录 | ./feishu bitable list-records --app-token "xxx" --table-id "yyy" |
create-record | 创建记录 | ./feishu bitable create-record --fields '{"Name":"test"}' |
batch-create | 批量创建 | ./feishu bitable batch-create --file records.json |
export | 导出 CSV/JSON | ./feishu bitable export --format csv --output data.csv |
Wiki 空间、节点、目录树管理
| 命令 | 说明 | 示例 |
|---|---|---|
space-list | 列出空间 | ./feishu wiki space-list |
tree | 递归目录树 | ./feishu wiki tree --space-id "xxx" --depth 3 |
node-read | 读取节点 | ./feishu wiki node-read --token "xxx" |
create-from-markdown | 从 MD 创建 | ./feishu wiki create-from-markdown --space-id "xxx" --file spec.md |
组织成员扫描、缓存与模糊匹配
| 命令 | 说明 | 示例 |
|---|---|---|
scan | 扫描并缓存 | ./feishu member scan |
find | 模糊匹配 | ./feishu member find --name "张三" |
whoami | 当前用户 | ./feishu member whoami |
对 Agent 说"帮我创建 Sprint-1 的任务列表"，Agent 自动创建 tasklist 并批量导入任务：
> "把这些需求拆成任务放到 Sprint-1 里"
Agent 执行:
1. ./feishu task tasklist-create --name "Sprint-1"
2. ./feishu task batch-create --file tasks.json --tasklist-id "$TASKLIST"也可以单独创建："建个任务：实现支付回调，截止到下周五"
./feishu task create --summary "实现支付回调" --due "2026-03-07T18:00:00+08:00"写好方案后说"把这个发到工程文档的知识库里"：
> "把 plan.md 发布到 Engineering Docs 知识库"
Agent 执行:
./feishu wiki create-from-markdown --space-id "$SPACE" --title "支付方案 v2" --file plan.md也可以追加内容到已有文档：
./feishu doc append-markdown --document-id "xxx" --file changelog.md说"把 Bug Tracker 的数据导出成 CSV"：
> "导出 Bug Tracker 表格的全部数据"
Agent 执行:
./feishu bitable export --app-token "basXXX" --table-id "tblXXX" --format csv --output report.csv也支持写入："往 Bug Tracker 里加一条记录，标题是 xxx"
说"看看我还有什么没完成的任务"：
./feishu task list --completed false认证由 Agent 自动处理。首次使用时 Agent 会调用 ./feishu auth login 打开浏览器完成 OAuth2 授权，token 保存在 ~/.feishu/credentials.json。
member 模块时自动增量授权 contact:user.base:readonly scopefeishu (Bash CLI 入口)
│
├── doc → docx.py 文档 & 云空间（CRUD + Markdown↔Block 双向转换）
├── task → task.py 任务 v2（CRUD + tasklist + batch + comment）
├── wiki → wiki.py 知识库（空间/节点/递归 tree + create-from-markdown）
├── bitable → bitable.py 多维表格（CRUD + 500条自动分批 + JSON/CSV 导出）
├── member → members.py 成员目录（扫描 + 7天缓存 + 模糊匹配）
└── auth → auth.py OAuth2（login / refresh / relogin + 增量授权）
↓
feishu_api.py 核心引擎 (HTTP + 429/5xx 自动重试 + 分页 + token 解析)
↓
~/.feishu/credentials.jsonINSTALL