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

这是一个专为 AI 辅助开发 设计的飞书多维表格（Bitable）深度解析工具。

它能一键解析复杂的 .base 导出文件，生成三份核心业务文档：

1. 全量字段表：包含所有公式源码、字段配置及 ID 映射。
2. 自动化工作流：可视化的自动化路径、触发条件及执行步骤。
3. 字段关联关系：表与表之间的数据引用依赖清单。

🎯 解决了什么问题？

飞书多维表格功能强大，但在维护复杂系统时常遇到“逻辑黑盒”问题。本工具的核心价值在于将封闭的系统转化为 AI 可读 的文档：

• 赋能 AI 调试：将生成的文档发给 AI，它就能回答“如果我删这个字段会有什么后果？”、“这个自动化为什么没跑通？”等复杂问题。
• 逻辑可视化：不再需要逐个点开字段看公式，所有逻辑一览无余。
• 无痛交接：无需人工撰写文档，一键生成的用于存档或移交项目的完美说明书。

本工具通过解析 .base 源文件，自动生成以下核心文档：

1. 全量字段表.md：包含所有表、字段的详细定义（含公式源码翻译）。
2. 字段关联关系图.md：展示表与表之间的引用依赖关系。
3. 自动化地图.md（自动化工作流）：可视化的自动化流程逻辑说明。
4. 完整性校验报告.md：自动检查解析质量，发现潜在的数据完整性问题。

🚀 快速开始

1. 环境准备

本项目基于 Python 3 开发，仅使用标准库，无需安装任何第三方依赖。 确保你的电脑上安装了 Python 3.6+ 即可。

python3 --version

2. 导出数据

1. 在飞书多维表格右上角点击「...」菜单。
2. 选择「更多」->「导出」 -> 「导出为 .base 文件」。
3. 将导出的文件（例如 未命名表格.base）放入本项目根目录（或任意子目录）。

3. 运行脚本

为了方便使用，您可以直接运行各个脚本进行解析。推荐的执行顺序如下：

# 1. 生成全量字段表
python3 scripts/generate_全量字段表.py

# 2. 生成关联关系图
python3 scripts/generate_关联关系图.py

# 3. 生成自动化地图
python3 scripts/generate_自动化地图.py

# 4. 执行完整性校验
python3 scripts/completeness_checker.py

提示：脚本会自动寻找当前目录下最新修改的 .base 文件进行解析。

📂 输出文档说明

运行结束后，你将在当前目录下看到以下文档：

• 全量字段表.md: 数据字典，适合查阅具体的字段定义和计算逻辑。
• 字段关联关系图.md: 逻辑依赖清单，适合在删除字段/表之前确认依赖影响。
• 自动化地图.md: 自动化工作流说明书，适合理解什么时候会触发什么动作。
• 完整性校验报告.md: 诊断报告，用于确保解析结果的准确性。
• 文档使用指南.md: 配合 completeness_checker.py 自动复制生成，指导普通用户如何阅读上述文档。

🛠️ 目录结构

.
├── scripts/
│   ├── generate_全量字段表.py    # 解析数据库 Schema
│   ├── generate_关联关系图.py    # 解析引用依赖
│   ├── generate_自动化地图.py    # 解析 Automation
│   └── completeness_checker.py # 校验解析质量
├── references/
│   └── 文档使用指南.md           # 文档阅读手册模板
├── SKILL.md                    # AI Agent 专用技能描述
└── README.md                   # 项目说明文档

👤 作者 (Author)

@玉清selva

如果您觉得这个工具对您有帮助，欢迎给本项目点一个 Star ⭐️！ 如果您有任何建议或发现了 Bug，也欢迎提 Issue 与我交流。

📄 License

本项目的发布基于 CC BY-NC 4.0 协议 (知识共享署名-非商业性使用 4.0 国际许可协议)。

这意味着您可以：

• ✅ 共享 — 在任何媒介以任何形式复制、发行本作品。
• ✅ 演绎 — 修改、转换或以本作品为基础进行创作。

但必须遵守以下条件：

• ⚠️ 署名 — 您必须保留作者的署名（@玉清selva），并提供协议的链接。
• 🚫 非商业性使用 — 您不得将本作品用于商业目的。

如需商业使用，请单独联系作者获取授权。