How to Connect LoopX to External Collaboration Surfaces like Lark Kanban

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 (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 (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 (lines 15-78) exposes sub-commands (config, use, doctor, sync) that orchestrate the underlying Python functions.

• Schema Helpers — Also within 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:

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:

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

This command persists the table_id and view_id to .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:

loopx lark-kanban doctor

Under the hood, this invokes lark_kanban_doctor from 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:

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) 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.
• 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.

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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}