# 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:

1. 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.
2. The run is not preview-only, dry-run, review-only, or schedule-only.
3. The project root contains `feishu_sync_config.json` with `enabled: true`.
4. 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`.

```json
{
  "enabled": true,
  "spreadsheet_url": "https://example.feishu.cn/sheets/xxxxxx",
  "spreadsheet_token": "",
  "sync_scope": "summary_first",
  "summary_sheet_name": "客户信息汇总表",
  "conversation_sheet_name": "Facebook对话记录",
  "sync_conversation_sheet": true,
  "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.
- A Facebook conversation write-back is a special event-log workflow: when `sync_conversation_sheet=true`, sync both `Facebook对话记录` and the rebuilt `客户信息汇总表`.
- Overwrite the remote conversation Sheet from the local Sheet so repeated syncs do not append duplicate message IDs.
- 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

1. Confirm the local Excel write has succeeded.
2. Read the local workbook target sheet, normally `客户信息汇总表`, preserving header order and all effective rows.
3. Call `lark-sheets +workbook-info` to confirm the remote spreadsheet exists and list sheet names.
4. If the target sheet is absent, create a sheet with the same name.
5. Clear or overwrite the remote target sheet range so repeated syncs do not append duplicates.
6. 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.
7. Read back with `+csv-get` and verify remote header, effective row count, first data row, and last data row.
8. 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 未配置，飞书同步未执行。`
- `本地建联表已更新；飞书同步失败：<原因>。本地数据已保留。`