Add Lark document comment Connector provider

docs/reference/extensions.md

@@ -119,6 +119,28 @@ does not advance the cursor until an event-bound response receipt and provider
 readback succeed. Concrete provider adapters supply the page reader and response
 writer; LoopX does not own their credentials or raw payloads.
 
+The bundled Lark extension supplies the first concrete document-comment
+adapter through `lark-cli`. Its owner-local target binds a safe Connector source
+reference to a private document URL, profile, and bot or user identity. The
+adapter probes exact comment read/create scopes, paginates comment cards and
+nested replies with a restart-safe private cursor, and maps stable reply ids to
+hashed Connector event ids. A completed scan restarts from the first comment
+page so new replies on older cards remain discoverable; the generic inbox
+deduplicates already captured or acknowledged events. Because Lark does not
+expose provider idempotency for reply creation, the adapter requires an
+owner-local receipt store: it records intent before the write, recovers a reply
+by its opaque idempotency marker after a crash, records the returned reply id
+before readback, and reuses that receipt on retry. The comment-list shortcut
+requires `lark-cli` 1.0.69 or newer. Public status and provider receipts omit
+document URLs, profiles, raw ids, cursor values, bodies, and subprocess output.
+
+The Lark adapter intentionally rejects `addressed_only`. Correct mention
+filtering needs an explicit provider identity contract, and treating every
+comment on a configured document as an Agent mention would silently weaken the
+generic capture policy. Configured-source and incremental bindings remain
+supported. Source-thread response bindings also filter solved and whole-
+document comment cards, which the Lark reply API does not allow replying to.
+
 `Provider` is an implementation role. When it implements a LoopX capability,
 it is registered under that capability; a standalone extension provider may
 instead expose only its own bounded command. A provider may be built into LoopX

loopx/extensions/lark/README.md

@@ -57,6 +57,36 @@ private chat, app, group, Base, document, or Miaoda target remains in ignored
 local configuration. External writes still require the owning capability's
 exact authority, gate, revision, idempotency, and readback contract.
 
+## Document-comment Connector provider
+
+`document_comment_provider.py` adapts one owner-configured Lark document to the
+provider-neutral Agent external Connector runtime. It delegates authentication
+and API calls to `lark-cli`, probes the exact comment read/create scopes, and
+turns one bounded comment or nested-reply page into owner-local inbox events.
+The adapter requires `lark-cli` 1.0.69 or newer for `drive +list-comments`;
+older binaries fail closed and must be upgraded before the Connector is ready.
+The provider supports configured-source and incremental capture. It rejects
+`addressed_only` until a caller supplies an explicit mention-identity contract;
+it never guesses that every document comment addressed the Agent.
+
+Lark comment pagination has separate cursors for comment cards and replies.
+The adapter persists both phases in the private Connector cursor and restarts a
+completed scan from the first comment page, relying on stable hashed event ids
+and the generic inbox for deduplication. A response-capable binding must also
+configure an owner-local reply receipt store. Reply creation writes a pending
+receipt, reads the exact reply back, then marks the receipt verified; only that
+verified receipt lets the generic runtime ACK the event. Solved and
+whole-document comment cards are skipped for source-thread response bindings
+because the provider does not permit replies to them.
+
+Document URLs, `lark-cli` profiles, provider cursors, comment/reply ids, raw
+payloads, and reply receipts remain owner-local. Public status reports only
+permission readiness, operation counts, inbox health, and content-free failure
+codes. The required provider scopes are
+`docs:document.comment:read` for history/readback and
+`docs:document.comment:create` for replies; enabling the extension does not
+grant either scope or publish an app.
+
 ## Ownership boundary
 
 - The extension owns Lark authentication checks, provider dispatch, bounded