feishu-cli-bridge · 快速上手（中文简版）

本地运行的飞书 MCP Server，让 Cursor / Claude Code 等 AI 工具直接访问飞书文档、表格、多维表格、画板、搜索与知识库能力，而不是先落地本地文件再手工同步。

这份是面向「5 分钟跑通」的简版。完整文档（外部接入总览、分层设计、Skill 套件、LLM Wiki 同步子系统、源码结构）在 README.md。

快速开始

1. 选择安装方式

方式 A：全局安装（推荐）

优点：启动更快，安装一次永久使用
缺点：占用磁盘空间（约 19 KB）

npm install -g feishu-cli-bridge

方式 B：使用 npx（无需安装）

优点：无需安装，始终使用最新版本
缺点：首次启动较慢（按需下载）

无需安装 - 直接配置 MCP 即可（见步骤 4）。

2. 配置 lark-cli

# 方式 A：使用现有应用
npx @larksuite/cli config init --app-id cli_xxx --app-secret-stdin
# (粘贴你的 app secret，然后按回车)

# 方式 B：自动创建新应用
npx @larksuite/cli config init --new

3. 授权

npx @larksuite/cli auth login --recommend

4. 添加到 AI 客户端

如果选择了全局安装：

Cursor - 添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "feishu-doc-publisher": {
      "command": "feishu-cli-bridge"
    }
  }
}

Claude Code - 添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "feishu-doc-publisher": {
      "command": "feishu-cli-bridge"
    }
  }
}

如果选择了 npx：

Cursor - 添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "feishu-doc-publisher": {
      "command": "npx",
      "args": ["feishu-cli-bridge"]
    }
  }
}

Claude Code - 添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "feishu-doc-publisher": {
      "command": "npx",
      "args": ["feishu-cli-bridge"]
    }
  }
}

5. 重启 AI 客户端

完成！现在可以使用了。

可用工具

| 工具 | 描述 | |---|---| | publish_to_feishu_doc | 从 Markdown 创建飞书文档 | | feishu_login | 重新授权（通常不需要） | | feishu_parse_url | 解析飞书 URL 提取 token | | feishu_search_docs | 搜索云文档 | | feishu_doc_get_raw_content | 读取文档原文 | | feishu_doc_set_link_permission | 设置文档分享权限 | | feishu_sheet_get_values / feishu_sheet_update_values | 读写电子表格 | | feishu_bitable_list_records / feishu_bitable_batch_create_records | 多维表格记录 | | feishu_board_list_nodes / feishu_board_create_nodes | 画板节点 | | feishu_wiki_resolve_or_create / feishu_wiki_load_context / feishu_wiki_sync_change_log | LLM Wiki 同步：任务前读模块 Wiki 摘要、任务后回写设计决策（详见主 README「LLM Wiki 同步子系统」章节） | | feishu_drive_delete_file | 删除云空间文件（高风险，需 FEISHU_ENABLE_DRIVE_DELETE=1 且 confirm=DELETE） |

Skill 套件（可选）

仓库根目录 skills/ 提供随仓库一起维护的 Skill 套件，让 AI 宿主按照固定流程调用上面的 MCP 工具。目前可用：

• llm-wiki-sync：任务前读模块 Wiki 摘要 + 任务后回写决策的闭环工作流，带版本预检与冲突降级。

规划中：feishu-preflight（认证/scope 预检）、feishu-artifact-mode（local / cloud / both 三模式文件路由）。激活方式见 skills/README.md 的「如何在 AI 宿主里激活」。

使用示例

在 AI 客户端中：

创建一个标题为"会议纪要"的飞书文档，内容如下：
# 今日讨论
- 确定了架构方案
- 下一步：开始实现

AI 会自动调用 publish_to_feishu_doc 并返回文档 URL。

核心特性

✅ Markdown → 飞书 Blocks：自动转换标题、列表、代码块、引用
✅ URL 解析：自动从飞书 URL 提取 token
✅ 多步骤工作流：一次工具调用完成创建 + 追加 + 设置权限
✅ LLM Wiki 同步：为模块建立结构化知识页，前读上下文 / 后写决策
✅ Skill 套件：把常见工作流沉淀成可复用的 AI 编排说明
✅ AI 友好的错误提示：出错时给出清晰的修复建议
✅ 基于官方 CLI：使用 @larksuite/cli 进行认证和 API 调用

前置要求

1. Node.js 16+
2. 飞书开放平台应用：
   • 在 https://open.feishu.cn/app 创建企业内部应用
   • 获取 App ID 和 App Secret
   • 发布应用（或获得管理员审批）
3. AI 客户端：Cursor 或 Claude Code

故障排除

"应用待审批"

你的应用需要发布。前往飞书开放平台 → 你的应用 → 创建版本 → 发布。

"权限被拒绝"

1. 在飞书开放平台 → 权限中检查应用权限
2. 重新授权：npx @larksuite/cli auth logout && npx @larksuite/cli auth login --recommend

工具没有显示

在添加 MCP 配置后重启 AI 客户端。

feishu_wiki_* 工具报「Wiki 不存在」或骨架创建失败

1. 如果希望自动建页，在调用 feishu_wiki_resolve_or_create 时显式传 createIfMissing=true；
2. 建议在 .env 里设置 FEISHU_WIKI_DEFAULT_SPACE_ID 指向测试知识空间，避免 fallback 到云空间根目录；
3. 权限需要 wiki:node:create + docs:document（user 身份更稳）。

vs 官方 lark-cli

| | lark-cli | feishu-cli-bridge | |---|---|---| | 面向用户 | 开发者（手动） | AI 工具（自动） | | Markdown → Blocks | ❌ | ✅ | | URL 解析 | ❌ 手动 | ✅ 自动 | | 多步骤流程 | 需要脚本 | 单个工具调用 | | 任务级 Wiki 同步 | ❌ | ✅ feishu_wiki_* 三件套 | | Skill 编排 | ❌ | ✅ 仓库内维护 skills/ 套件 | | 典型场景 | CI/CD、脚本 | AI 辅助写作 / 编码助手 |

feishu-cli-bridge 在 lark-cli 之上补一层「任务级能力 + Skill 编排」，把飞书能力通过 MCP 协议暴露给 AI 工具。

文档

• 完整版（含 LLM Wiki 同步、Skill 套件、源码结构）：README.md
• 协作与分层约束：AGENTS.md
• Skill 套件说明：skills/README.md
• 长期设计文档：docs/superpowers/

许可证

MIT

链接

• GitHub: https://github.com/wen/feishu-cli-bridge
• npm: https://www.npmjs.com/package/feishu-cli-bridge
• 飞书开放平台: https://open.feishu.cn/document
• lark-cli: https://github.com/larksuite/cli