feishu-base-parser

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

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

🎯 核心能力

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

🚀 触发时机

当用户有以下需求时触发：

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

🛠️ 执行流程

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

第一步：生成基础文档

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

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

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

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

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

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

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

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 文件很大，脚本运行可能需要几秒钟，请耐心等待。