Feishu Base Excel Sync

Problem Background: Synchronization Challenges Between Excel and Feishu Base

In collaborative environments, data often needs to be synced between local Excel files and online Feishu Base (multidimensional tables). Manual synchronization is time-consuming, error-prone, and can lead to inconsistencies, especially with large datasets. Additionally, Feishu Base supports field types that don’t fully align with Excel, such as select, user, attachment, and formula fields, which cannot be handled via simple copy-paste. This necessitates a tool that not only migrates data but also intelligently handles field mapping and conflicts.

Core Capabilities: How the Script Enables Safe Synchronization

The excel-sync-bitable skill provides a Python script solution centered on business key-driven incremental sync. It compares a business key column in the source Excel and target Feishu table to update only matching records, thereby avoiding accidental deletion of remote data. Key capabilities include:

• Preview and Apply Separation: The --preview flag shows the impact of sync (e.g., number of records to update or create), allowing users to confirm before executing writes with --apply. This two-step mechanism ensures operational control.
• Missing Field Handling: When Excel columns don’t exist in the target table, the script defaults to a no-write prompt with inferred types. Users can explicitly control behavior via --missing-fields skip or --missing-fields create --apply.
• Table Creation and Export: It supports creating new Feishu tables from Excel workbooks and exporting Feishu tables to Excel, enabling bidirectional sync.

The key steps follow this workflow:
1. Precondition Checks: Confirm the input file, Base URL, target table, and business key column; use lark-cli auth status to verify identity.
2. Run Preview: Execute a command like python scripts/excel_sync_bitable.py --preview --source data.xlsx --base-url <URL> --table <TABLE> --key <COLUMN> to view sync preview.
3. Apply Sync: After reviewing the preview, add the --apply flag to perform the write.
4. Handle Feedback: Adjust missing field strategies or check errors based on script output.

The script automatically resolves the Base URL to avoid permission issues from guessed tokens. During sync, it adheres to safety rules: only updates records with exact business key matches, stops on blank or duplicate keys, and ensures data integrity.

Applicable Boundaries and Best Practices

While this skill simplifies synchronization, it has clear boundaries:

• Supported Field Types: Currently, it natively supports text, number, date/time, and checkbox fields. For select, user, attachment, link, formula, and lookup fields, use field-specific workflows (e.g., Feishu API configurations) instead of guessing values.
• Data Safety: Sync does not delete remote records; it only performs updates. Users must rely on preview counts as approval material—applying without confirmation may lead to unintended overwrites.
• Business Key Requirements: The business key column must be unique and non-empty in both source and target; duplicate or blank keys terminate the script, requiring data cleansing beforehand.
• Field Mapping: Missing fields are not written by default. It’s recommended to check field alignment during preview and manually adjust Feishu table structures if necessary.

Best practices include testing on small datasets first, using clear business keys (e.g., order IDs), and verifying field compatibility before production use. For complex field types, consider supplementing sync with Feishu Base automations (e.g., webhooks).