dsh-plugin-lark

English | 简体中文

Feishu/Lark long-connection bridge for DeepSeek Harness. Incoming text becomes an agent follow-up; each turn, tool lifecycle, approval, and structured question is rendered back into the originating chat with Card 2.0.

Features

• No inbound public endpoint: receives Feishu/Lark events through the official SDK WebSocket long connection.
• Isolated, resumable conversations: direct chats, group reply trees, and native threads keep separate durable Harness sessions; an explicit global session remains available when desired.
• Bounded session navigation: lists eligible history in the exact conversation scope with stored titles, timestamps, project labels, and opaque references, then atomically resumes one selected transcript without accepting raw Session IDs or paths.
• Project registration and selection: project managers can register the active Session directory or remove a registration from a direct chat; every authorized conversation can list and select registered Workspaces without accepting arbitrary paths from chat.
• Conversation model selection: lists live providers and their advertised models, accepts exact adapter-resolved provider/model routes, and preserves each conversation's choice across fresh generations and recovery.
• Image-aware routing safety: detects images on the exact compacted model surface and prevents model switches, Session resumes, or ordinary prompts from sending that history to a text-only or capability-unknown route.
• Opt-in direct-chat images: validates one bounded static PNG or JPEG, stores it through the Harness attachment service, and submits only its content-addressed reference to an explicitly image-capable model.
• Structured human input: renders the official ask_user_question tool as a bounded native single-choice, multiple-choice, or free-text Card and returns the authorized answer to the same running turn.
• Opt-in direct-chat text attachments: admits one bounded UTF-8 .txt, .log, .patch, or .diff message through strict authorization, filename, MIME, byte, and content gates, without URLs or temporary files.
• Approved outbound Workspace artifacts: exposes an opt-in Agent-scoped tool that can send one bounded text file or static PNG/JPEG only after the originating Lark user approves the exact live turn.
• Reliable proactive delivery: admits one completion or attention Card to the conversation already registered for this turn, with a durable outbox so restarts neither drop nor duplicate an admitted send.
• Live execution cards: streams reasoning, todos, retries, compaction, hooks, workflows, tool calls, results, token usage, and the final answer into one bounded Card 2.0 message, then makes a bounded attempt to remove live controls if service shutdown interrupts it.
• Safe tool approval and cancellation: approval and stop actions are bound to the originating session, chat, and user, with stale or cross-chat actions failing closed.
• Reliable reply delivery: keeps cards and fallbacks attached to the triggering message or native thread, continues long answers in full, and durably suppresses normal WebSocket redelivery duplicates.
• Bounded process residency: releases durably checkpointed least-recently-used idle Agents and cold-resumes their exact session without deleting transcripts.
• Localized and observable: includes zh-CN and en-US UI copy plus an optional, sanitized WebSocket readiness endpoint.
• Operator status and diagnostics: /status and /diag give operators a Card 2.0 snapshot of version, uptime, connection, conversation scope, project, model, and work — plus sanitized remediation — without platform IDs or secrets.
• Conversation-scoped policy: operators can narrow one chat or group to extra authorized users, required mentions, visible Workspaces, selectable models, and allowed approval or outbound tool classes. Local rules only intersect the global fail-closed configuration.
• Document handoff (optional): reads only a document link the user supplied in the conversation, bounded and attributed as untrusted data, and publishes a long report as a document on explicit request while the ordinary chat answer is still delivered. It needs its own Lark scopes and stays off unless enabled.
• Explicit parallel tasks (optional): /task run starts one bounded task with its own session, opaque reference, reply target, and lifecycle Card. Ordinary consecutive messages stay serialized and are never reinterpreted as parallel work, and two live tasks cannot claim one project unless sharing is configured.
• Supervised runtime (optional): claims cross-process ownership of the bot before connecting, publishes a status document an external probe can read without loading the Harness profile, and ships reviewable systemd and readiness templates.
• Fail-closed boundaries: authorization defaults to deny, Lark app credentials stay launch-environment-only, media ingestion is opt-in and bounded, and approval failures never grant access.

Stability

1.0 freezes two contracts. The public configuration surface is the 31 options above: a later 1.x release may add an optional option, and removing or renaming one is a breaking change that requires a major version. The durable storage domains are lark_conversations, lark_inbound, lark_notify, lark_policy, and lark_tasks, each at domain version 0; a version bump requires a migration path and an [UPGRADING.md](./UPGRADING.md) entry before it can ship. Both sets are enforced by a release gate, so drifting from them fails the build rather than reaching a deployment.

Freezing these contracts is not a claim that every deployment path is verified. Two remain outside the evidence this project has:

• Credential-backed Web-profile startup. The release gates install and upgrade the packed candidate into isolated stock profiles and verify composition, but they do not boot the app with real Feishu or Lark credentials. Startup with credentials, WebSocket readiness against the live platform, and persisted-state migration during a credential-backed upgrade are exercised only by the manual runbook in [SMOKE_TESTS.md](./SMOKE_TESTS.md).
• Long-running resource behaviour. There is no soak test. Memory, handle, and durable-store growth over days of continuous operation are unmeasured. The bounded-residency, outbox, and task limits are enforced and unit-tested, but their behaviour over a long uptime is not evidence-backed.

Treat both as unverified rather than as known-good. If you deploy 1.0 into a long-lived production channel, run the credential-backed smoke checklist first and watch resource use yourself.

Requirements

• Node.js 22.x, or Node.js 24.x with plugin v0.8.5 or newer
• One coherent DeepSeek Harness 0.1.0-rc.7 package cohort
• The Harness agents and sessions services; the stock Web profile mounts both
• The Harness tools service, Session persistence, and the compatible rc.6 ask_user_question definition for structured Lark input; the stock Web profile mounts them
• A durable storageDomain service; the stock Web profile supplies its JSON-backed storage stack
• Session navigation additionally requires sessionPersistence, sessionQuery, and workspaceRegistry; the stock rc.6 Web profile supplies them
• Inbound images additionally require the Harness attachments service; the stock rc.6 Web profile supplies its local content-addressed store
• Outbound artifacts additionally require sessionPersistence, workspaceRegistry, approval, attachments for images, and the stock local filesystem-backed Workspace runtime
• A self-built Feishu or Lark app with a bot

Supported Harness matrix

Each supported row is an exact release-tested baseline. A version accepted by a broad semver range is not automatically a supported combination.

The required tests assemble the real rc.6 Cordis, Agent, Agent Loop, LLM, Session, semantic checkpoint policy, Session Title, SQLite Session Query exact-read path, JSONL persistence, JSON storage-domain, local Attachment Store, Tools, User Questions, Approval, and Workspace services. Platform connection, model provider, and browser behavior use controlled doubles; project mutation and approved artifact delivery also have real Registry/persistence lifecycle tests. CI pins the official Lark SDK to 1.73.0, packs the canonical candidate on Node 22, clean-installs it into an isolated stock rc.6 Web profile, and upgrades a second isolated profile from the strictly verified v0.9.12 Release package while preserving its user patch. Both paths require the installed package version, a single bundle registration, and exactly one composed Lark configuration layer.

The profile gate also pins npm resolution to the registry snapshot immediately after the rc.7 cohort was published. Harness prerelease packages use caret ranges internally, so an exact top-level dsh@0.1.0-rc.6 alone can otherwise drift to a later prerelease in a clean npm-exec environment; every resolved DSH package is still checked as exactly rc.6.

Starting with v0.8.5, that same Linux release gate then switches to Node 24, recreates node_modules with engine-strict enabled, repeats the complete source/Harness and independent packed-consumer gates, and consumes the already packed canonical candidate in an isolated stock profile. The v0.8.5 gate used a clean install because its v0.8.4 baseline supported only Node 22; starting with v0.8.6, Node 24 also verifies the adjacent upgrade from the now-compatible v0.8.5 baseline.

Starting with v0.8.6, a separate required gate runs engine-strict Node 22 on GitHub-hosted macOS 26 arm64. Starting with v0.8.7, it runs the same isolated flow for Node 22 and 24. Each runtime repeats the complete source/Harness tests, audit, and an independent packed-consumer installation, then downloads and consumes the exact Ubuntu-built canonical archive after Actions artifact-digest verification. Neither runtime runs dsh plugin, composes a stock Web profile, or validates app startup and stateful operations on macOS.

That Web-profile gate is deliberately boot-free: it validates package installation, upgrade, bundle resolution, and configuration composition, but does not start the Web app or exercise credentials, the SDK WebSocket connection, /api/lark/health, the Feishu/Lark network path, or persisted-state migration. Those remain deployment and credential-backed smoke checks.

Direct host peers are pinned to this baseline, and every DSH package in the resolved graph must stay in the same rc.6 cohort. Mixed DSH releases, Node.js 23.x or 25 and newer, Node.js 24 with plugin v0.8.4 or older, later Cordis or Schemastery releases, other Harness cohorts, Ubuntu architectures outside x64, and a host with the optional Approval service completely absent are unverified. Starting with v0.8.7, the macOS evidence is limited to macOS 26 arm64 with Node 22 or 24 package/runtime consumption; Intel Macs, other macOS releases, stock Web-profile operation, and state migration on macOS remain unverified. Alternative persistence stacks are also unverified. Custom profiles are supported only when they provide the services documented in [Config](#config); missing agents, sessions, tools, or durable storageDomain support is unsupported.

Install

Install the published package into a Harness profile:

dsh plugin --profile web add dsh-plugin-lark

Or build from a checkout, which is what the release gates exercise:

git clone https://github.com/LPX-E5BD8/dsh-plugin-lark.git
cd dsh-plugin-lark
npm ci --ignore-scripts
npm run build
dsh plugin --profile web add .

The dsh plugin installation and operational procedures in this README remain verified on the Ubuntu/Linux gate. The macOS gate verifies the packaged module only; it does not establish stock Web-profile deployment support.

The registry package and the GitHub Release archive for a given version are the same artifact: the release gates pack it once, verify it as an independent consumer, and publish that exact archive. [Release provenance](#release-provenance) covers verifying it before use. When installing from a checkout instead, keep that checkout in place while the profile uses it.

Before replacing that checkout or rolling back a state-bearing release, follow the cold-snapshot and schema boundaries in [UPGRADING.md](./UPGRADING.md). A plugin downgrade is not automatically a durable-state downgrade.

In the Feishu/Lark developer console:

1. Select long connection for event delivery. 2. Subscribe to im.message.receive_v1. 3. Register the card.action.trigger callback. 4. Grant the bot im:message send/receive access. 5. Grant im:resource when inboundTextFiles, inboundImages, or outboundArtifacts is enabled. Without those features, the scope remains optional and only enables the bundled animated loading indicator; the card otherwise uses a static icon.

Release provenance

Starting with v0.8.3, each GitHub Release includes the exact npm-format .tgz that passed the packed-consumer smoke test, plus a GitHub-hosted SLSA build-provenance attestation for that file. This workflow does not publish to the npm registry, and the automatically generated Source code archives are not the attested package.

Download and verify a release package with GitHub CLI:

set -eu

version='1.1.1'
repository='LPX-E5BD8/dsh-plugin-lark'
archive="dsh-plugin-lark-${version}.tgz"
tag="v${version}"

tag_object="$(gh api "repos/${repository}/git/ref/tags/${tag}" --jq '.object.type + ":" + .object.sha')"
object_type="${tag_object%%:*}"
object_sha="${tag_object#*:}"
if [ "$object_type" != 'tag' ]; then
  printf 'remote %s is not an annotated tag\n' "$tag" >&2
  exit 1
fi

peel_depth=0
while [ "$object_type" = 'tag' ]; do
  peel_depth=$((peel_depth + 1))
  if [ "$peel_depth" -gt 8 ]; then
    printf 'remote %s exceeds the tag peel limit\n' "$tag" >&2
    exit 1
  fi
  tag_object="$(gh api "repos/${repository}/git/tags/${object_sha}" --jq '.object.type + ":" + .object.sha')"
  object_type="${tag_object%%:*}"
  object_sha="${tag_object#*:}"
done
if [ "$object_type" != 'commit' ]; then
  printf 'remote %s resolves to %s, not a commit\n' "$tag" "$object_type" >&2
  exit 1
fi
tag_commit="$object_sha"

release_target="$(gh release view "$tag" --repo "$repository" --json targetCommitish --jq .targetCommitish)"
if [ "$release_target" != "$tag_commit" ]; then
  printf 'release target %s does not match tag commit %s\n' "$release_target" "$tag_commit" >&2
  exit 1
fi

gh release download "$tag" --repo "$repository" --pattern "$archive"
gh attestation verify "$archive" \
  --repo "$repository" \
  --signer-workflow "$repository/.github/workflows/ci.yml" \
  --source-ref refs/heads/main \
  --source-digest "$tag_commit" \
  --deny-self-hosted-runners

The attestation binds the archive digest to this repository, workflow, ref, and release commit. It establishes origin and integrity, not that the code or its dependencies are vulnerability-free.

Run

Start DSH from the project that the Lark Agent should work on:

cd /path/to/target-project
export DSH_LARK_APP_ID='<app-id>'
export DSH_LARK_APP_SECRET='<app-secret>'
dsh --profile web --host 127.0.0.1 --port 3080

The invocation directory becomes the workspace for each fresh Lark session. A persisted session resumes its stored workspace instead. /project register <title> can register that active Session directory, and /project can move one conversation to any registered Workspace. Binding the Web UI beyond loopback is deployment-specific; Feishu/Lark event delivery itself uses the outbound long connection and needs no inbound public listener.

Credentials

The plugin reads app credentials only from environment variables. It does not accept them in plugin config.

export DSH_LARK_APP_ID='<app-id>'
export DSH_LARK_APP_SECRET='<app-secret>'

These DSH_* values must be inherited by the DSH launch process. DSH 0.1.0-rc.7 rejects DSH_* entries in both t

…