14790897 GitHub Issue → 飞书多维表格同步
将任意 GitHub 仓库的所有 Issue 一次性/增量同步到飞书多维表格。
脚本
核心脚本: scripts/sync_github_issues.py
前置条件
1. 飞书应用
- 在 飞书开放平台 创建企业自建应用
- 开通权限:
bitable:app（多维表格完整读写） - 发布版本并审批通过
- 获取 App ID 和 App Secret
2. 文档级授权（91403 错误的根因）
飞书权限是两层架构：
- 第一层: 开放平台 API 权限（上一步）
- 第二层: 在具体文档/表格中添加应用为协作者
操作: 打开目标多维表格 → 右上角 ... → ...更多 → 添加文档应用 → 搜索应用名 → 赋予「可编辑」权限
3. 环境变量
export FEISHU_APP_ID="cli_xxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxx"
# 可选，提高 GitHub API 速率限制
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxx"
用法
参数
| 参数 | 说明 |
|---|---|
--dry-run |
预览模式，只显示不写入 |
--limit N |
只处理前 N 条 Issue |
--force |
跳过重复检查，强制全量写入 |
--include-pr |
包含 Pull Request |
--fields JSON |
手动指定表字段（类型: 1=文本, 2=数字, 5=日期, 15=超链接） |
示例
# 预览（推荐首次使用）
python scripts/sync_github_issues.py --dry-run --limit 3
# 正式同步
python scripts/sync_github_issues.py
# 强制覆盖（不去重）
python scripts/sync_github_issues.py --force
配置修改
脚本中需要修改的配置常量（在文件顶部）:
GITHUB_REPO = "owner/repo" # GitHub 仓库
FEISHU_DOC_TOKEN = "xyz123..." # 飞书文档 token（从 URL 提取）
FEISHU_TABLE_ID = "tblxxxxxxxx" # 飞书表 ID（从 URL 提取）
表结构约定
默认创建/映射以下字段:
| 飞书列 | 类型 | GitHub 来源 |
|---|---|---|
| Issue编号 | 文本 (1) | issue.number |
| 标题 | 文本 (1) | issue.title |
| 状态 | 文本 (1) | issue.state |
| 链接 | 超链接 (15) | issue.html_url |
| 创建人 | 文本 (1) | issue.user.login |
| 标签 | 文本 (1) | issue.labels[].name |
| 创建时间 | 日期 (5) | issue.created_at |
| 更新时间 | 日期 (5) | issue.updated_at |
| 正文 | 文本 (1) | issue.body |
工作流程
- 拉取 GitHub 所有 Issue（分页，默认过滤 PR）
- 连接飞书获取表字段结构
- 自动映射字段名（支持中英文模糊匹配）
- 读取已有记录按 Issue 编号去重
- 批量写入新记录（500 条/批）
- 输出同步结果
踩坑记录
- 91403 Forbidden: 缺少第二层文档授权，需要在表格页面「添加文档应用」
- DatetimeFieldConvFail: 日期字段必须用毫秒时间戳，不能用 ISO 字符串
- 中文字段名乱码: curl 在 Windows bash 下传中文会编码错误，用 Python requests 代替
- 主列不可删除: 飞书多维表格的主列是硬性设计，只能改名或隐藏