# feishu-base-parser

> 深度解析飞书多维表格（Bitable）的 .base 导出文件，生成人类可读的业务逻辑文档。

- Author: selvaluo
- Repository: selvaluo/feishu-base-parser
- Version: 20260129172510
- Stars: 14
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/selvaluo/feishu-base-parser
- Web: https://mule.run/skillshub/@@selvaluo/feishu-base-parser~feishu-base-parser:20260129172510

---

---
name: feishu-base-parser
description: 深度解析飞书多维表格（Bitable）的 .base 导出文件，生成人类可读的业务逻辑文档。
---

# 飞书多维表格解析器 (Feishu Base Parser)

## 🎯 核心能力

将飞书多维表格的 `.base` 导出文件转换为清晰的 Markdown 文档，帮助用户理解复杂的业务逻辑、字段依赖和自动化流程。

## 🚀 触发时机

当用户有以下需求时触发：
- "解析这个飞书多维表格"
- "梳理这个表格的业务逻辑"
- "帮我看下这个自动化流程是怎么跑的"
- "分析这个 base 文件的结构"
- 用户上传了 `.base` 文件并请求分析

## 🛠️ 执行流程

> **注意**: 请严格按照以下顺序执行，不要跳过任何步骤。

### 第一步：生成基础文档

依次运行以下 3 个脚本生成核心文档：

```bash
# 1. 解析数据表结构 (输出: 全量字段表.md)
python3 scripts/generate_全量字段表.py

# 2. 解析表关联关系 (输出: 字段关联关系图.md)
python3 scripts/generate_关联关系图.py

# 3. 解析自动化工作流 (输出: 自动化工作流.md)
python3 scripts/generate_自动化地图.py

# 4. 复制使用指南 (输出: 文档使用指南.md)
cp references/文档使用指南.md .
```

### 第二步：完整性校验与自愈

运行校验脚本，检查是否有未解析的 ID 或结构：

```bash
python3 scripts/completeness_checker.py
```

**根据校验结果执行分支策略**：

**情况 A: output 包含 "✅ 解析完成"**
- 直接向用户交付生成的 4 份文档。

**情况 B: output 包含 "⚠️ 发现 ... 个未翻译ID" (解析器缺陷)**
- 这通常意味着代码中缺少某些 ID 的映射。
- **Action**: 尝试读取代码，修复映射逻辑，然后**重新回到第一步**。
- **Loop**: 最多重试 2 次。

**情况 C: output 包含 "⚠️ 发现 ... 个需要人工介入的问题" (数据缺失)**
- 这意味着 ID 在源数据中根本不存在（可能是字段被删除）。
- **Action**: 不要尝试修复代码。直接向用户交付文档，并重点展示 `完整性校验报告.md` 中的诊断建议。

## 📄 交付物说明

1.  **📖 文档使用指南** (必读): "这是说明书，教您如何高效阅读后续文档（含检索技巧）。"
2.  **📋 完整性校验报告** (体检): "这是解析质量报告。如果有未解析的内容或数据缺失，会在这里第一时间警示。"
3.  **核心业务文档三件套** (按顺序阅读):
    - **📕 全量字段表** (字典): "所有数据表的字段定义字典，包含公式源码和选项定义。"
    - **📗 字段关联关系图** (架构): "表与表之间的引用关系图，用于理解数据流转方向。"
    - **📘 自动化工作流** (逻辑): "所有的自动化流程逻辑，包含触发条件、判断分支和详细步骤。"

## ⚠️ 常见问题处理

- **Unknown ID**: 如果报告中显示 `[未知字段:fldXXX]`，请告知用户："这通常是因为该字段在飞书中已被删除，请参考校验报告中的定位去核实。"
- **大文件**: 如果 `.base` 文件很大，脚本运行可能需要几秒钟，请耐心等待。