Feishu Sheet Sync

Use this reference whenever a workflow updates the local customer outreach workbook and the WorkBuddy/Lark Sheets plugin is available.

Trigger Rule

Feishu sync is a mandatory post-write step when all conditions are true:

A local workbook write has completed successfully, such as --write-excel, --write-summary, --write-workbook, email status write-back, or social outreach status write-back.
The run is not preview-only, dry-run, review-only, or schedule-only.
The project root contains feishu_sync_config.json with enabled: true.
The agent has access to the lark-sheets plugin in WorkBuddy.

If the config is missing, report once: 本地建联表已更新；未发现 feishu_sync_config.json，飞书同步未执行。 Do not silently skip. If the plugin is unavailable or unauthenticated, report: 本地建联表已更新；飞书同步待授权/待插件可用。 Do not roll back the local workbook.

Config

Real Feishu URLs or tokens must live in the project root config file, not inside the skill package.

Recommended project config file: feishu_sync_config.json.

{
  "enabled": true,
  "spreadsheet_url": "https://example.feishu.cn/sheets/xxxxxx",
  "spreadsheet_token": "",
  "sync_scope": "summary_first",
  "summary_sheet_name": "客户信息汇总表",
  "channel_sheets": [
    "Facebook",
    "LinkedIn",
    "Google Maps",
    "汽车网站精选线索",
    "协会商会"
  ]
}

Rules:

Use either spreadsheet_url or spreadsheet_token; prefer spreadsheet_url when available.
Keep enabled=false to disable automatic sync without deleting config.
Do not store cookies, user tokens, app secrets, passwords, SMTP authorization codes, or exported Feishu access tokens in this config.
The skill package may only contain assets/feishu_sync_config.example.json, never a real project config.

Default Sync Scope

Default sync_scope is summary_first.

Sync 客户信息汇总表 by default after it is rebuilt successfully.
If a channel sheet was written but the summary sheet was not rebuilt in the same run, report that the local channel sheet was updated and recommend refreshing the summary before Feishu sync.
Sync all configured channel sheets only when the user explicitly asks for full workbook sync or sync_scope is set to all_configured_sheets.
Never sync previews, JSON candidates, HTML previews, sent logs, backups, temporary files, or SMTP data to Feishu.

Lark Plugin Routing

When sync is required, the agent must use the WorkBuddy lark-sheets plugin. If it needs to locate a spreadsheet by name or folder first, use lark-drive search only for discovery, then return to lark-sheets for table operations.

Before writing with lark-sheets, follow that skill's required setup, including reading lark-shared for authentication and permissions. Do not use lark-doc for customer table sync unless the user explicitly asks for a narrative document.

Sync Flow

Confirm the local Excel write has succeeded.
Read the local workbook target sheet, normally 客户信息汇总表, preserving header order and all effective rows.
Call lark-sheets +workbook-info to confirm the remote spreadsheet exists and list sheet names.
If the target sheet is absent, create a sheet with the same name.
Clear or overwrite the remote target sheet range so repeated syncs do not append duplicates.
Write the local sheet data to the remote sheet with +table-put when typed data matters, otherwise +csv-put is acceptable for plain text customer tables.
Read back with +csv-get and verify remote header, effective row count, first data row, and last data row.
Save a sync report under runs/YYYYMMDD/<run_id>/feishu-sync-report.json when a run directory exists; otherwise print the report in chat.

Failure Handling

Local Excel is the source of truth. Never roll back local writes because Feishu sync failed.
Report the failure reason clearly: missing config, disabled config, plugin unavailable, unauthenticated account, permission denied, remote spreadsheet missing, sheet creation failed, write failed, or read-back mismatch.
If only Feishu sync fails, final response must separate local workbook success from Feishu sync failure.
If the remote table contains manual edits, default behavior is still to overwrite the target sheet from the local source of truth. Ask only if the user explicitly says remote edits must be preserved.

Acceptance Criteria

A completed write-enabled workflow should end with one of these statuses:

本地建联表已更新，飞书客户信息汇总表已同步并回读校验通过。
本地建联表已更新；feishu_sync_config.json 未配置，飞书同步未执行。
本地建联表已更新；飞书同步失败：<原因>。本地数据已保留。

feishu-sync.md 4.8 KB Historia Czysty