# How to Connect LoopX to External Collaboration Surfaces like Lark Kanban

> Connect LoopX to Lark Kanban easily. This guide shows how to project LoopX control-plane state (goals, todos, metrics) into Feishu/Lark Base boards using the CLI and Python adapters.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: how-to-guide
- Published: 2026-08-07

---

**LoopX ships a dedicated Lark Kanban extension that projects control-plane state (goals, todos, and metrics) into Feishu/Lark Base boards via the `loopx lark-kanban` CLI and Python adapters.**

The huangruiteng/loopx repository includes a first-party extension layer that bridges LoopX’s internal task management with external collaboration surfaces. This integration enables bidirectional sync between LoopX projections and Lark Kanban boards, eliminating manual data entry while preserving schema integrity through automated validation.

## Architecture Overview

The Lark Kanban integration follows a three-tier architecture that separates validation logic, presentation adapters, and user-facing commands:

- **Lark Provider** — Located in [`loopx/extensions/lark/provider.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/provider.py) (lines 9-34), this module validates that extension modules expose required callables including `lark_kanban_doctor` and `sync_loopx_projection_to_lark_kanban`. It serves as the entry point when the CLI runs with the `--doctor` flag.

- **Lark Kanban Presentation** — Implemented in [`loopx/extensions/lark/presentation/kanban.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/presentation/kanban.py) (lines 75-89), this adapter handles schema generation, board creation, record-level sync, and heartbeat logic. Core functions include `sync_loopx_projection_to_lark_kanban` and `sync_loopx_todos_to_lark_kanban`.

- **CLI Wrapper** — The file [`loopx/cli_commands/lark_kanban.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/lark_kanban.py) (lines 15-78) exposes sub-commands (`config`, `use`, `doctor`, `sync`) that orchestrate the underlying Python functions.

- **Schema Helpers** — Also within [`kanban.py`](https://github.com/huangruiteng/loopx/blob/main/kanban.py) (lines 217-236), these utilities generate the `lark_kanban_schema_payload` and perform pre-flight schema checks against Lark Base requirements.

## Step-by-Step Configuration

### Install Lark CLI and Authenticate

Before initiating the connection, install the Lark CLI tool and authenticate with your Feishu/Lark workspace:

```bash
pip install lark-cli
lark-cli login --access-token <YOUR_TOKEN>

```

The provider expects credentials matching any flag defined in `_LARK_CREDENTIAL_ARGUMENTS`, such as `--access-token` or `--app-id` with `--app-secret`.

### Initialize Board Configuration

Select or create a target board and store its identifiers locally:

```bash
loopx lark-kanban use https://open.feishu.cn/drive/...

```

This command persists the `table_id` and `view_id` to [`.loopx/lark_kanban_config.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/lark_kanban_config.json) in your project root. The configuration file is read by subsequent sync operations via `read_lark_kanban_local_config`.

## Validate Board Schema with the Doctor Command

Run the schema validator to ensure your Lark board structure matches LoopX expectations:

```bash
loopx lark-kanban doctor

```

Under the hood, this invokes `lark_kanban_doctor` from [`loopx/extensions/lark/presentation/kanban.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/presentation/kanban.py), which compares the live board schema against the expected `lark_kanban_schema_payload`. If field mismatches exist, the doctor reports specific discrepancies and suggests corrective actions before any data migration occurs.

## Syncing LoopX Data to Lark Kanban

### Projection-Level Sync

The `sync_loopx_projection_to_lark_kanban` function writes generic LoopX projection dictionaries to Lark board rows. It supports optional filters such as `include_done` and `limit`, and can execute generated Lark CLI commands when `execute=True`.

### Todo-Level Sync

For granular task management, `sync_loopx_todos_to_lark_kanban` synchronizes LoopX todos while preserving order, status, and claim fields. This function operates similarly to the projection sync but maps specifically to todo entities.

### Programmatic Integration Example

You can drive the Kanban connector directly from Python without invoking the CLI:

```python
from pathlib import Path
from loopx.extensions.lark.presentation.kanban import (
    LarkKanbanConfig,
    lark_kanban_doctor,
    sync_loopx_projection_to_lark_kanban,
    read_lark_kanban_local_config,
)

# Load existing configuration

config_path = Path(".loopx/lark_kanban_config.json")
local_cfg = read_lark_kanban_local_config(config_path)
config = LarkKanbanConfig(**local_cfg["config"])

# Validate schema before syncing

doctor_payload = lark_kanban_doctor(
    config=config, 
    config_path=config_path, 
    execute=False
)

# Prepare a LoopX projection

my_projection = {
    "source_id": "my-goal-123",
    "records": [
        {"task": "Write docs", "status": "Todo", "priority": "P1"},
        {"task": "Run tests", "status": "Todo", "priority": "P0"},
    ],
}

# Execute sync with explicit goal targeting

payload = sync_loopx_projection_to_lark_kanban(
    config,
    projection=my_projection,
    goal_id="my-goal-123",
    config_path=config_path,
    execute=True,
    sink_visibility="shared",
)

print("Sync receipt:", payload["sync_receipt"])

```

## Idempotency and Sync Receipts

All sync functions generate a **sync receipt** through `compact_lark_kanban_sync_receipt`. This compact JSON artifact is persisted alongside the board configuration, enabling safe retries and guaranteeing idempotency. If a sync operation interrupts, replaying the receipt prevents duplicate records on the Lark board.

## Heartbeat and Bi-Directional Reconciliation

The `lark_kanban_heartbeat` function (referenced in [`goal_boundary.py`](https://github.com/huangruiteng/loopx/blob/main/goal_boundary.py)) periodically reads the Lark board state, extracts urgency signals, and feeds them back into LoopX’s quota and goal system. This creates a closed loop where external updates on the Kanban surface influence LoopX’s internal prioritization logic.

## Summary

- **LoopX connects to Lark Kanban** through a dedicated extension layer located in `loopx/extensions/lark/`.
- **Configuration requires** the Lark CLI, valid credentials, and a local config file generated via `loopx lark-kanban use`.
- **Schema validation** is enforced by the `lark_kanban_doctor` callable before any sync operations execute.
- **Data synchronization** supports both projection-level and todo-level granularity via `sync_loopx_projection_to_lark_kanban` and `sync_loopx_todos_to_lark_kanban`.
- **Idempotency is guaranteed** through compact sync receipts stored in [`.loopx/lark_kanban_config.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/lark_kanban_config.json).
- **Bi-directional flow** is achieved via `lark_kanban_heartbeat`, which reconciles external board changes back into LoopX.

## Frequently Asked Questions

### What prerequisites are required to connect LoopX to Lark Kanban?

You must install the `lark-cli` Python package and authenticate against your Feishu/Lark workspace using valid credentials such as an access token or app credentials. The LoopX extension specifically checks for flags defined in `_LARK_CREDENTIAL_ARGUMENTS` during the provider validation phase in [`loopx/extensions/lark/provider.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/provider.py).

### How does the doctor command validate my Lark board configuration?

The `loopx lark-kanban doctor` command invokes `lark_kanban_doctor` from [`loopx/extensions/lark/presentation/kanban.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/presentation/kanban.py), which retrieves the live board schema and compares it against the expected `lark_kanban_schema_payload`. It reports mismatches in field names or types, ensuring the board structure can accommodate LoopX data before any records are written.

### Can I sync LoopX data programmatically without using the CLI?

Yes. Import the adapter functions directly from `loopx.extensions.lark.presentation.kanban`, instantiate a `LarkKanbanConfig` object, and call `sync_loopx_projection_to_lark_kanban` or `sync_loopx_todos_to_lark_kanban` with `execute=True`. This approach is useful for building automated pipelines or integrating Kanban sync into larger LoopX skills.

### How does LoopX handle synchronization failures or duplicate records?

LoopX implements idempotent sync via `compact_lark_kanban_sync_receipt`. Each sync operation generates a receipt that is persisted locally. When retrying, LoopX references this receipt to determine which records have already been propagated, preventing duplicates and ensuring that partial failures can be resumed safely without data corruption.