fstln-dev 飞书文档同步
管理本地文档与飞书知识库的双向同步。
前置条件
MCP 选择
飞书同步涉及两种 MCP：
| MCP | 用途 | 适用操作 |
|---|---|---|
feishu-official |
文档和 Wiki 操作 | create-doc, fetch-doc, search-doc, list-docs, get-comments, add-comments |
feishu |
多维表格及其他操作 | bitable, calendar, task, im 等 |
文档/Wiki 同步使用 *feishu-official*，多维表格操作使用 *feishu****。*
具体前置条件
- 文档/Wiki 操作 (
feishu-official):
.mcp.json中已配置feishu-official- 已获取 UAT Token（通过 Device Flow 授权）
- 多维表格操作 (
feishu):
.mcp.json中已配置feishu- 已通过
/mcp→ feishu → Authentication 完成授权
- 项目配置:
- Wiki Space ID 已配置（在
.claude/context/feishu-config.md中）
同步模式
模式 1: 推送到飞书 (Push)
当用户说"同步到飞书"时：
- 确定同步范围
📤 将同步以下文档到飞书:
docs/product/prd-order.md → 飞书 Wiki/产品文档/订单模块PRD
docs/tech/tech-order.md → 飞书 Wiki/技术文档/订单模块技术方案
是否继续？[确认] [选择] [取消]
检查同步状态
读取
.claude/context/feishu-map.md获取文档到飞书的映射：
- 新文档：创建新飞书文档
- 已同步文档：更新现有飞书文档
- 冲突文档：提示用户选择版本
执行同步
使用
feishu_create_doc或feishu_update_doc工具更新映射
同步完成后更新
feishu-map.md：
| 本地路径 | 飞书 Token | 最后同步 | 状态 |
|----------|-----------|----------|------|
| docs/product/prd-order.md | doxcnXXXX | 2026-03-09 14:00 | synced |
模式 2: 从飞书拉取 (Pull)
当用户说"从飞书拉取"时：
获取飞书变更
使用
feishu_list_wiki_nodes获取 Wiki 节点列表 对比feishu-map.md中的最后同步时间报告变更
📥 检测到飞书变更:
更新的文档:
- 订单模块PRD (更新于 2026-03-09 13:00)
新增的文档:
- 支付模块PRD (创建于 2026-03-09 12:00)
是否拉取？[全部] [选择] [取消]
执行拉取
使用
feishu_fetch_doc获取文档内容 保存到对应的本地路径更新映射
更新
feishu-map.md中的同步时间
模式 3: 检查同步状态
当用户说"检查同步状态"时：
📊 飞书同步状态:
已同步 (5):
✅ docs/product/prd-order.md → 订单模块PRD
✅ docs/tech/tech-order.md → 订单模块技术方案
待同步 (2):
⏳ docs/product/prd-payment.md (本地更新于 2026-03-09 14:00)
⏳ docs/test/test-order.md (新建，未同步)
冲突 (1):
⚠️ docs/product/prd-user.md (飞书有更新)
是否同步待同步文档？[是] [否]
文档路径映射规则
默认映射规则（可在 feishu-config.md 中自定义）：
| 本地目录 | 飞书 Wiki 节点 |
|---|---|
docs/product/ |
产品文档/ |
docs/tech/ |
技术文档/ |
docs/test/ |
测试文档/ |
docs/meetings/ |
会议纪要/ |
冲突处理
当检测到冲突时（本地和飞书都有更新）：
⚠️ 冲突检测: docs/product/prd-user.md
本地版本: 2026-03-09 14:00 (用户A)
飞书版本: 2026-03-09 13:30 (用户B)
请选择:
[1] 保留本地版本 (覆盖飞书)
[2] 使用飞书版本 (覆盖本地)
[3] 手动合并 (显示 diff)
[4] 跳过
选择手动合并时，显示两版本的差异：
--- 本地版本
+++ 飞书版本
@@ -10,7 +10,7 @@
-## 功能需求
+## 业务需求
feishu-map.md 格式
# 飞书文档映射
> 自动维护，请勿手动编辑
| 本地路径 | 飞书 Token | 飞书标题 | 最后同步 | 状态 | MD5 |
|----------|-----------|----------|----------|------|-----|
| docs/product/prd-order.md | doxcnXXXX | 订单模块PRD | 2026-03-09T14:00:00Z | synced | abc123 |
错误处理
| 错误 | 处理 |
|---|---|
| 飞书 Token 无效 / 过期 | 提示运行 "飞书授权" 或 "检查飞书状态"，引导使用 feishu-connect |
| feishu-official UAT 无效 | 提示运行 "飞书授权" 重新获取 UAT Token |
| feishu Token 无效 | 提示运行 /mcp → feishu → Authentication 重新授权 |
| Wiki 权限不足 | 提示检查应用权限配置 |
| 网络超时 | 重试 3 次，失败后提示 |
| 文档过大 | 提示拆分文档 |
授权问题处理
当遇到授权相关错误时：
⚠️ 飞书授权问题
检测到授权失效或未授权。
请运行以下命令解决:
- "飞书授权" - 引导完成授权流程
- "检查飞书状态" - 查看当前授权状态
或者直接说 "找 feishu-connect" 获取帮助
批量同步
支持批量操作：
用户: "同步所有待同步文档"
用户: "同步 docs/product/ 下的所有文档"
用户: "拉取飞书所有更新"
自动同步（可选）
在 feishu-config.md 中配置：
auto_sync:
on_commit: true # 提交时自动同步 status=approved 的文档
on_session_start: true # 会话启动时检查飞书变更
Git Commit Hook
初始化工作空间时会自动配置 post-commit hook：
# .git/hooks/post-commit
# 检测本次提交中 status=approved 的 .md 文件
# 如果有已批准的文档，提示用户可以同步到飞书
工作流程：
- 开发者提交包含
status: approved的 .md 文件 - Git hook 检测到已批准的文档
- 提示用户可以同步到飞书
- 用户在 Claude Code 中说 "同步到飞书" 执行同步
手动配置 Git Hook：
如果需要手动配置，复制 scripts/post-commit 到 .git/hooks/：
cp scripts/post-commit .git/hooks/
chmod +x .git/hooks/post-commit