## Before\n\n临时脚本直接写飞书 Base：先假设本机有旧路径 `config.bytedance.json`，再用 500 行批次调用。第一批 120 秒没有返回时，只能人工判断是接口太重、网络卡住还是输出缓冲；如果发现 `+record-upsert` 只能单条写，还要临时改脚本，最后再手工查询总记录数和抽样字段。\n\n## After\n\n```bash\npython /Users/bytedance/Documents/job-bu/data-analysis-workspace/tools/lark_base_bulk_sync.py \\\n --input-csv /Users/bytedance/Documents/job-bu/data-analysis-workspace/adhoc/query_recall_top3.csv \\\n --app-token base_xxx \\\n --table-id tbl_xxx \\\n --key-field '知识 ID' \\\n --mode upsert \\\n --batch-size auto \\\n --dry-run\n```\n\nDry run 输出：\n\n```text\n[preflight] active profile: bytedance-work, auth ok\n[preflight] table found, key field found: 知识 ID\n[input] rows=13102, unique_keys=6617\n[capability] batch_create=yes, batch_update=yes, single_upsert=yes\n[plan] existing=1912, to_create=4705, to_update=1912, initial_batch_size=200\n```\n\n正式执行：\n\n```bash\npython /Users/bytedance/Documents/job-bu/data-analysis-workspace/tools/lark_base_bulk_sync.py \\\n --input-csv /Users/bytedance/Documents/job-bu/data-analysis-workspace/adhoc/query_recall_top3.csv \\\n --app-token base_xxx \\\n --table-id tbl_xxx \\\n --key-field '知识 ID' \\\n --mode upsert \\\n --batch-size auto\n```\n\n成功信号：\n\n```text\n[batch 19/34] create=200 update=0 elapsed=8.4s\n[reconcile] source_unique_keys=6617 target_missing=0 field_mismatch=0\n[done] report=out/lark_base_sync_runs/2026-05-28T230102/reconcile.json\n```\n\n失败信号会直接给出下一步：比如 `profile mismatch` 要先切换 lark-cli profile，`field missing` 要先补字段，`batch timeout` 会自动把后续批次从 500 降到 200 或 100，并保留 checkpoint 供续跑。