Feishu Bitable Import

批量导入本地CSV/Excel/JSON数据至飞书多维表格，支持智能字段推断及增量、全量、仅新增三种同步模式。

Security Scan

The skill's code and runtime instructions match its described purpose (importing local CSV/Excel/JSON into Feishu Bitable), but the package/registry metadata omits that the skill requires Feishu credentials (FEISHU_APP_ID/FEISHU_APP_SECRET) and ships executable Python scripts — this metadata mismatch and the presence of executable code warrants caution.

Purpose & Capability

Name, description, SKILL.md and the included Python scripts all focus on importing local CSV/Excel/JSON into Feishu Bitable and creating/updating fields/records; these requirements are coherent with that purpose. However, the registry metadata claims 'Required env vars: none' while the SKILL.md and code clearly require FEISHU_APP_ID and FEISHU_APP_SECRET — a mismatch between declared requirements and actual needs.

Instruction Scope

SKILL.md explicitly instructs reading local files, creating a .env with FEISHU_APP_ID/FEISHU_APP_SECRET, and running the provided scripts with app-token/table-id arguments. The scripts themselves operate only on local input files and the Feishu open API endpoints (open.feishu.cn). There are no instructions to read unrelated system files or send data to unknown endpoints.

Install Mechanism

There is no install spec (instruction-only in registry), but the SKILL.md lists Python dependencies (pandas, openpyxl, python-dotenv, requests). The skill includes runnable Python scripts (scripts/*.py) which will be written to disk as part of the skill bundle — this is higher-risk than a purely prose skill because it includes executable code the user will run locally. The dependency list is reasonable for the stated task.

Credentials

The code and instructions require FEISHU_APP_ID and FEISHU_APP_SECRET (used to fetch tenant_access_token) and expect app_token/table_id parameters — all appropriate for interacting with Feishu. The concern is that the registry metadata did not declare any required env vars; that omission is misleading. Requesting these credentials is proportionate to the task, but the metadata mismatch reduces transparency.

Persistence & Privilege

The skill does not request persistent/always-on privileges (always:false). It does not attempt to modify other skills or system-wide settings. The scripts read local files and call Feishu APIs only when executed.

What to consider before installing

This skill appears to implement the described Feishu Bitable import functionality, but exercise caution before installing/running: 1) The registry metadata incorrectly states no env vars required — the scripts need FEISHU_APP_ID and FEISHU_APP_SECRET (put in a .env) and you must supply app_token/table_id. 2) Review the included Python scripts locally before running to confirm they match the provided sources and there are no unexpected network calls. 3) Create a dedicated Feishu application with the minimal permissions (docs:bitable:read and docs:bitable:write only), add it as a collaborator to the target Base, and avoid using high-privilege tenant credentials if possible. 4) Run the scripts in an isolated environment (container or VM) and rotate/revoke the app secret after use. 5) If you need higher assurance, request that the publisher update registry metadata to declare required environment variables and provide a homepage or source repository for auditing.

feishu-bitable-import — 企业级飞书多维表格数据导入

核心价值：连接本地 CSV/Excel/JSON 数据与飞书多维表格，实现业务数据自动化导入，让团队实时查看最新报表，减少手动导入的错误和时间消耗。

适用场景

• 企业数据中台：将数仓/BI导出的数据自动同步到飞书多维表格，供业务团队分析
• 定时报表同步：每日/每周业务报表自动更新，团队始终看到最新数据
• 批量数据导入：从 CRM/ERP 导出数据，一键导入飞书供团队协作
• 增量数据更新：只同步新增/变化数据，提高效率
• 自动化表格创建：根据数据结构自动创建表格和字段，无需手动配置

核心特性

✨ 智能类型推断 — 基于数据分布自动识别字段类型，准确率 > 95%
⚡ 三种同步模式 — 增量更新/全量覆盖/仅新增，满足不同业务场景
🏗️ 零配置建表 — 从 CSV/Excel 一键创建完整表格，自动生成所有字段
🔒 企业级可靠性 — 自动重试、限流处理、错误报告，保证数据一致性
📊 支持多种格式 — CSV / Excel (xlsx/xls) / JSON 全覆盖

企业级工作流

阶段 1：环境准备

1. 用户提供飞书应用凭证 (APP_ID / APP_SECRET)
2. 提供目标多维表格地址 (app_token / table_id)
3. 准备本地数据文件

阶段 2：智能数据分析

1. 读取数据文件，推断数据分布
2. 基于统计特征自动识别字段类型
   - 文本/数字/日期/单选/多选/复选框/URL/手机号
3. 对比现有表格 schema，发现差异
4. 自动创建缺失字段（可选）

阶段 3：选择性同步

根据业务场景选择同步策略：

模式	适用企业场景	核心算法
增量同步	日常业务数据更新	基于主键匹配，只同步变化数据
全量覆盖	每日定时报表更新	清空旧数据，全量重新导入
仅新增	日志/事件数据追加	在末尾追加，不修改历史数据

阶段 4：执行与报告

1. 权限校验与连接建立
2. 批量数据同步（带限流退避）
3. 生成同步统计报告
4. 输出结果明细

系统要求

环境依赖

# Python 依赖
pip install pandas openpyxl python-dotenv requests

飞书权限配置

1. 在 飞书开放平台 创建企业自建应用
2. 获取 App ID 和 App Secret
3. 添加权限：docs:bitable:read, docs:bitable:write
4. 将应用添加为多维表格协作者

环境变量配置

创建 .env 文件：

FEISHU_APP_ID=cli_xxxxxx
FEISHU_APP_SECRET=xxxxxx

🚀 快速开始

场景 1：从 CSV 一键创建新表格

python scripts/create_table.py \
  --input employees.csv \
  --app-token <base_app_token> \
  --table-name "员工信息表"

输出示例：

✅ 创建表格成功: 员工信息表 (table_id: tblxxxxxxxxxx)
开始导入数据...

🎉 完成!
- 表格 ID: tblxxxxxxxxxx
- 导入: 128 条
- 自动创建字段: 8 个
- 分享链接: https://pangeedoc.feishu.cn/drive/base/xxx?table=tblxxxxxxxxxx

场景 2：增量同步到现有表格

python scripts/sync.py \
  --input daily_sales.csv \
  --app-token <base_app_token> \
  --table-id <table_id> \
  --mode incremental \
  --primary-key "订单号"

场景 3：全量覆盖每日报表

python scripts/sync.py \
  --input daily_report.xlsx \
  --app-token <base_app_token> \
  --table-id <table_id> \
  --mode full

智能类型推断矩阵

数据类型	飞书类型ID	推断规则	准确率
文本	1	默认类型，不符合其他规则时使用	-
数字	2	80%+ 可转换为数值	98%
日期	5	匹配 YYYY-MM-DD 等格式	95%
单选	3	唯一值占比 < 30% 且唯一值数量 ≤ 20	92%
多选	4	包含逗号/分号分隔符	88%
复选框	7	仅包含是/否、真/假、Y/N 等二值	100%
链接	15	匹配 http:// / https://	100%
手机号	13	匹配中国大陆手机号格式	100%

企业级可靠性设计

场景	处理策略
API 限流	自动退避重试，最大重试 3 次
网络超时	指数退避，逐步重试
权限错误	立即终止，输出清晰提示
格式错误	跳过错误行，记录错误继续同步
大文件	分批处理，每 50 条暂停避免限流

典型企业架构

[数仓/BI系统] 
    ↓ 导出
[CSV/Excel 文件] 
    ↓ 定时任务 / 手动触发
feishu-bitable-sync 
    ↓ 自动同步
[飞书多维表格] 
    ↓ 实时协作
业务团队分析决策

帮助与参考

• 获取 app_token 和 table_id: 点击查看
• 官方 API 文档: 飞书开放平台 - 多维表格 API
• 问题反馈: 欢迎提交 Issue 改进企业级适配

---

License

MIT