feishu-user-plugin 1.3.10 → 1.3.11

package/scripts/sync-team-skills.sh

@@ -1,28 +1,30 @@
 #!/usr/bin/env bash
 # scripts/sync-team-skills.sh — post-merge hook on main.
 #
-# What this does (zero manual steps, no degradation):
-#   1. Copy skills/ + .claude-plugin/plugin.json into team-skills repo
-#   2. Run team-skills' generate-catalog.py (forced manual-yaml path for byte
-#      parity with CI)
-#   3. Run our scripts/generate-release-artifacts.js to produce
-#      changelog + readme-row from CHANGELOG.md
-#   4. Inject the changelog block into team-skills child README before the
-#      previous version's heading
-#   5. Replace the team-skills root README catalog row matching feishu-user-plugin
-#   6. Commit + push branch + open PR
-#   7. Auto-merge: --admin --squash (we have admin on team-skills repo;
-#      org-level setting blocks repo PATCH for allow_auto_merge so we use
-#      --admin to bypass review wait. CI is non-blocking via "Check catalog"
-#      drift never happening since step 2 produced byte-identical output.)
+# Idempotent + conflict-resilient sync from feishu-user-plugin's main into
+# zhuzhen-team/team-skills. Designed so retries always converge:
 #
-# Failure modes are now narrow:
+# Flow:
+#   1. Generate release artifacts in feishu repo (changelog block + readme row).
+#   2. cd team-skills repo, fetch origin main.
+#   3. Close any stale OPEN sync PRs whose branch is for an older version
+#      (so v1.3.10 sync doesn't pile up behind a never-merged v1.3.9 sync).
+#   4. Delete any local stale sync/feishu-v$VERSION branch and recreate from
+#      origin/main — always starts fresh, never carries leftover commits.
+#   5. Copy plugin tree + inject changelog + replace catalog row + regen catalog.
+#   6. If nothing changed → exit 0 (already in sync for v$VERSION).
+#   7. Commit + push --force-with-lease (safe: only this script writes to sync/* branches).
+#   8. Open PR if not exists; merge --admin --squash.
+#
+# Failure modes:
 #   - team-skills repo not cloned at expected path → clean skip
-#   - branch already exists from previous attempt → clean skip
-#   - generate-release-artifacts.js fails → exit non-zero (visible to user
-#     via post-merge stderr; user fixes CHANGELOG and re-pushes)
+#   - generate-release-artifacts.js fails → exit non-zero (visible in stderr)
+#   - PR merge fails (rare; should be impossible after force-recreate from origin/main)
+#     → exit non-zero, post-merge wrapper labels as "non-fatal" but user sees stderr
 set -e
-TEAM_SKILLS="/Users/abble/team-skills/plugins/feishu-user-plugin"
+
+TEAM_SKILLS_REPO="/Users/abble/team-skills"
+TEAM_SKILLS="$TEAM_SKILLS_REPO/plugins/feishu-user-plugin"
 if [ ! -d "$TEAM_SKILLS" ]; then echo "[hook] team-skills not present, skip"; exit 0; fi
 
 ROOT="$(git rev-parse --show-toplevel)"
@@ -30,25 +32,43 @@ cd "$ROOT"
 
 VERSION=$(node -e "console.log(require('./package.json').version)")
 ARTIFACTS="/tmp/feishu-release/v${VERSION}"
+BRANCH="sync/feishu-v$VERSION"
 
-# Generate release artifacts FIRST so we can inject them into team-skills.
-# This reads CHANGELOG.md for the v$VERSION section and emits team-skills
-# changelog markdown + root readme row + announcement card JSON.
+# 1. Generate release artifacts FIRST so we can inject them into team-skills.
 node scripts/generate-release-artifacts.js "$VERSION" >/dev/null
 
-# Copy plugin tree.
-cp -r skills/. "$TEAM_SKILLS/skills/"
-cp .claude-plugin/plugin.json "$TEAM_SKILLS/.claude-plugin/"
+# 2. cd team-skills, fetch origin main.
+cd "$TEAM_SKILLS_REPO"
+git fetch origin main --quiet
+
+# 3. Close any stale OPEN sync PRs (different version branch). Idempotent —
+#    any matching PR for this same $VERSION is preserved (we'll force-update
+#    its branch in step 7 instead).
+STALE_PRS=$(gh pr list --state open --search "Sync feishu-user-plugin in:title" \
+  --json number,headRefName --jq ".[] | select(.headRefName != \"$BRANCH\") | .number")
+if [ -n "$STALE_PRS" ]; then
+  for stale_num in $STALE_PRS; do
+    gh pr close "$stale_num" \
+      --comment "Superseded by sync/feishu-v$VERSION (auto-closed by sync-team-skills.sh)" \
+      --delete-branch 2>&1 | tail -1 || true
+    echo "[hook] closed stale sync PR #$stale_num"
+  done
+fi
+
+# 4. Delete any local stale sync branch + recreate from origin/main.
+#    `git checkout -B` is "create or reset". We always start from latest main
+#    so there are no inherited commits from older sync attempts.
+git checkout -B "$BRANCH" origin/main
+
+# 5. Copy plugin tree from feishu repo, inject changelog, regen catalog.
+cp -r "$ROOT/skills/." "$TEAM_SKILLS/skills/"
+cp "$ROOT/.claude-plugin/plugin.json" "$TEAM_SKILLS/.claude-plugin/"
 
-# Inject changelog block into team-skills/plugins/feishu-user-plugin/README.md.
-# Insert just before the existing first "### vX.Y.Z" heading, OR after
-# "## 更新日志" if no prior version exists.
+# 5a. Inject changelog block into team-skills child README (idempotent).
 README="$TEAM_SKILLS/README.md"
 if grep -q "^### v${VERSION} " "$README"; then
   echo "[hook] team-skills child README already has v${VERSION} section, skipping inject"
 else
-  # awk: print everything; when we hit the FIRST `### vX.Y.Z (date)` heading,
-  # insert the new block before it.
   awk -v block_file="$ARTIFACTS/team-skills-changelog.md" '
     BEGIN { inserted = 0 }
     /^### v[0-9]+\.[0-9]+\.[0-9]+ \(/ && !inserted {
@@ -61,14 +81,12 @@ else
   echo "[hook] injected v${VERSION} changelog block into child README"
 fi
 
-# Replace the team-skills root README catalog row matching feishu-user-plugin.
-ROOT_README="$TEAM_SKILLS/../../README.md"
+# 5b. Replace root README catalog row matching feishu-user-plugin.
+ROOT_README="$TEAM_SKILLS_REPO/README.md"
 NEW_ROW=$(cat "$ARTIFACTS/team-skills-readme-row.md")
 if grep -q "^| \\*\\*feishu-user-plugin\\*\\* |" "$ROOT_README"; then
-  # Replace the line in-place. Use Python (sed regex with table chars + |
-  # quotes is brittle across BSD/GNU).
   python3 -c "
-import sys, re
+import re
 p = '$ROOT_README'
 new_row = '''$NEW_ROW'''.strip()
 text = open(p, 'r', encoding='utf-8').read()
@@ -78,47 +96,44 @@ open(p, 'w', encoding='utf-8').write(text)
   echo "[hook] updated root README catalog row to v${VERSION}"
 fi
 
-# Switch into team-skills repo root (two parents up from $TEAM_SKILLS).
-cd "$TEAM_SKILLS/../.."
-
-BRANCH="sync/feishu-v$VERSION"
-if git rev-parse --verify "$BRANCH" >/dev/null 2>&1; then
-  echo "[hook] branch $BRANCH already exists locally, skipping"; exit 0
-fi
-git checkout -b "$BRANCH"
-
-# team-skills CI runs generate-catalog.py without PyYAML; force the same path
-# locally for byte-identical output. Verified in PR #36.
+# 5c. Regenerate catalog.yaml (force PyYAML-less path for byte parity with CI).
 if [ -f "scripts/generate-catalog.py" ]; then
   python3 -c "import sys, runpy; sys.modules['yaml']=None; runpy.run_path('scripts/generate-catalog.py', run_name='__main__')" >/dev/null 2>&1
 fi
 
-# Stage every file the hook might have touched. Each `git add` is idempotent
-# on already-clean files, so unchanged ones stage as no-op. Files that don't
-# exist (e.g., catalog.yaml when team-skills repo doesn't have the generator)
-# would fail under `set -e`, so guard explicitly.
+# 6. Stage everything the hook touched.
 git add "plugins/feishu-user-plugin/"
 [ -f "README.md" ]    && git add README.md
 [ -f "catalog.yaml" ] && git add catalog.yaml
 
-# If nothing actually changed, exit 0 — the v$VERSION sync was already done.
 if git diff --cached --quiet; then
   echo "[hook] nothing to sync (working tree clean for v$VERSION)"; exit 0
 fi
 
 git commit -m "chore: sync feishu-user-plugin v$VERSION (skills + plugin.json + README changelog + catalog)"
-git push -u origin "$BRANCH"
 
-gh pr create --title "Sync feishu-user-plugin v$VERSION" --body "Auto-sync from feishu-user-plugin main. Includes:
+# 7. Push (force-with-lease since this branch is exclusively written by this
+#    script — safe even if a previous run pushed something we just rebuilt).
+git push --force-with-lease -u origin "$BRANCH"
+
+# 8. Open PR if not exists, then merge.
+PR_NUM=$(gh pr list --head "$BRANCH" --state open --json number --jq ".[0].number // empty")
+if [ -z "$PR_NUM" ]; then
+  gh pr create --title "Sync feishu-user-plugin v$VERSION" --body "Auto-sync from feishu-user-plugin main. Includes:
 - plugins/feishu-user-plugin/.claude-plugin/plugin.json bumped to v$VERSION
 - plugins/feishu-user-plugin/skills/ regenerated
 - plugins/feishu-user-plugin/README.md: v$VERSION changelog section auto-generated from feishu-user-plugin's CHANGELOG.md
 - README.md (root): catalog row updated
 - catalog.yaml regenerated"
+  PR_NUM=$(gh pr view "$BRANCH" --json number --jq .number)
+  echo "[hook] opened sync PR #$PR_NUM"
+else
+  echo "[hook] reusing existing sync PR #$PR_NUM (branch force-updated)"
+fi
 
-PR_NUM=$(gh pr view --json number --jq .number)
-# Use --admin --squash: we have admin permissions on team-skills (verified) and
-# the team-skills org has auto-merge disabled at org level. --admin merges
-# without waiting for required reviews. CI is informational only here.
+# Use --admin --squash: we have admin permissions on team-skills (verified).
+# After step 4's force-recreate from origin/main, this PR is always cleanly
+# mergeable (no carried conflicts). --admin bypasses required reviews; CI
+# is informational since step 5c produced byte-identical catalog output.
 gh pr merge "$PR_NUM" --admin --squash
 echo "[hook] team-skills sync PR #$PR_NUM merged"

package/skills/feishu-user-plugin/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: feishu-user-plugin
-version: "1.3.10"
+version: "1.3.11"
 description: "All-in-one Feishu plugin — send messages as yourself (incl. batch_send), read group/P2P chats (auto-expands merge_forward), manage docs/tables/wiki (full CRUD)/drive, OKR (with progress writes), calendar (read+write), Tasks v2, multi-profile auto-switch, real-time WS events. v1.3.8: multi-profile auto-switch on read errors (B), WebSocket realtime im.message events via get_new_events (C), credential pointer-only mode (E), CI gates (F), auth/uat.js + auth/cookie.js extracts (D)."
 allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, batch_send, send_card_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, list_profiles, switch_profile, manage_profile_hints, read_p2p_messages, list_user_chats, list_chats, read_messages, send_message_as_bot, reply_message, forward_message, delete_message, update_message, add_reaction, delete_reaction, pin_message, create_group, update_group, list_members, manage_members, search_docs, read_doc, get_doc_blocks, create_doc, manage_doc_block, read_doc_markdown, manage_bitable_app, manage_bitable_table, manage_bitable_field, manage_bitable_view, manage_bitable_record, upload_bitable_attachment, list_wiki_spaces, search_wiki, list_wiki_nodes, get_wiki_node, create_wiki_node, update_wiki_node, move_wiki_node, copy_wiki_node, delete_wiki_node, list_files, create_folder, upload_drive_file, manage_drive_file, upload_image, upload_file, download_message_resource, download_doc_image, list_user_okrs, get_okrs, list_okr_periods, create_okr_progress_record, list_okr_progress_records, delete_okr_progress_record, list_calendars, list_calendar_events, get_calendar_event, create_calendar_event, update_calendar_event, delete_calendar_event, respond_calendar_event, get_freebusy, list_tasks, get_task, create_task, update_task, complete_task, delete_task, manage_task_members, get_new_events, manage_ws_status
 user_invocable: true

package/skills/feishu-user-plugin/references/CLAUDE.md

@@ -197,6 +197,7 @@ For more profiles beyond the default, set `LARK_PROFILES_JSON` in the MCP env (o
 - `~/.feishu-user-plugin/ws-owner.lock`: lock file owned by the one MCP process driving the WS connection (O_CREAT|O_EXCL, 30 s stale).
 - `~/.feishu-user-plugin/events.jsonl`: append-only event log written by the WS owner; 10 MB soft / 20 MB hard cap then rotated to `events.jsonl.old`.
 - `~/.feishu-user-plugin/events.cursor.json`: global drain cursor shared across all MCP processes — advancing it marks events as consumed for all harnesses on the machine.
+- **Lark Desktop multi-account auto-switch (v1.3.11)**: when `credentials.json::profiles[*].larkHash` is bound, the owner heartbeat (15 s) watches `~/Library/.../sdk_storage/<hash>/cookie_store.db` mtime; switching the active Lark Desktop account auto-flips `credentials.json::active` to the bound profile. macOS-only. Bind via `setup --bind-hash <hash>` or auto-detect on `setup` (single account binds silently; multiple prompts in interactive mode / picks most-recent in non-interactive mode). Cookies stay per-profile in `LARK_COOKIE`; the encrypted `cookie_store.db` is never read.
 
 ### Credentials store (v1.3.7+)
 Single source of truth at `~/.feishu-user-plugin/credentials.json` (mode 0600). Schema documented at `docs/CREDENTIALS-FORMAT.md`. The MCP server reads from this file when present; cookie heartbeat and UAT refresh persist back to it atomically. Multiple harnesses (Claude Code, Codex) sharing the same file see token rotations consistently — no more "Codex still has the old UAT" drift after a refresh in Claude Code.

package/src/auth/credentials.js

@@ -360,6 +360,51 @@ function setProfileEvents(name, eventList) {
   return true;
 }
 
+// --- Lark Desktop hash bindings (v1.3.11 §A) ---
+//
+// Each profile may carry an optional `larkHash` 32-char-hex field binding it
+// to one of `~/Library/Containers/com.bytedance.macos.feishu/.../sdk_storage/<hash>/`.
+// The owner heartbeat reactor uses this binding to decide which profile to
+// switch to when the user changes account in Lark Desktop. See
+// src/auth/lark-desktop.js for the detection / switch logic; this module
+// just owns the persisted binding.
+
+const _LARK_HASH_RE = /^[a-f0-9]{32}$/;
+
+function getProfileLarkHash(name) {
+  const f = _readFile();
+  const target = name || (f ? f.active : 'default');
+  if (f && f.profiles[target] && typeof f.profiles[target].larkHash === 'string') {
+    return f.profiles[target].larkHash;
+  }
+  return null;
+}
+
+function setProfileLarkHash(name, hash) {
+  if (hash !== null && (typeof hash !== 'string' || !_LARK_HASH_RE.test(hash))) {
+    throw new Error('setProfileLarkHash: hash must be 32-char hex (a-f, 0-9) or null');
+  }
+  const f = _readFile();
+  if (!f) throw new Error('No credentials.json — cannot set profile larkHash. Run `npx feishu-user-plugin migrate --confirm` first.');
+  if (!f.profiles[name]) {
+    throw new Error(`setProfileLarkHash: profile "${name}" not found. Available: ${Object.keys(f.profiles).join(', ')}`);
+  }
+  if (hash === null) delete f.profiles[name].larkHash;
+  else f.profiles[name].larkHash = hash;
+  _atomicWriteJson(_credentialsPath(), f);
+  return true;
+}
+
+function findProfileByHash(hash) {
+  if (typeof hash !== 'string' || !_LARK_HASH_RE.test(hash)) return null;
+  const f = _readFile();
+  if (!f) return null;
+  for (const [name, profile] of Object.entries(f.profiles)) {
+    if (profile.larkHash === hash) return name;
+  }
+  return null;
+}
+
 // --- Profile hints (v1.3.8) ---
 //
 // profileHints maps resourceKey → profileName, persisted in credentials.json.
@@ -419,6 +464,10 @@ module.exports = {
   // per-profile events list (v1.3.9 A.4)
   getProfileEvents,
   setProfileEvents,
+  // Lark Desktop hash bindings (v1.3.11 §A)
+  getProfileLarkHash,
+  setProfileLarkHash,
+  findProfileByHash,
   // profile hints (v1.3.8)
   getProfileHints,
   setProfileHint,

package/src/auth/lark-desktop.js

@@ -0,0 +1,135 @@
+// src/auth/lark-desktop.js — Lark Desktop sdk_storage detection (v1.3.11 §A).
+//
+// macOS-only: Linux/Windows return null from getSdkStorageDir() and all
+// callers no-op gracefully. We never read the encrypted cookie_store.db —
+// only stat its mtime to detect account switches. Profile↔hash bindings
+// live in credentials.json::profiles[*].larkHash.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const HASH_RE = /^[a-f0-9]{32}$/;
+
+// Debounce + freshness windows for the heartbeat reactor.
+const SWITCH_DEBOUNCE_MS = 5_000;
+const UNBOUND_FRESH_WINDOW_MS = 60_000;
+
+function _macSdkStorageDir() {
+  return path.join(
+    os.homedir(),
+    'Library/Containers/com.bytedance.macos.feishu/Data/Library/Application Support/LarkShell/sdk_storage'
+  );
+}
+
+function getSdkStorageDir() {
+  if (process.platform !== 'darwin') return null;
+  const dir = _macSdkStorageDir();
+  try {
+    return fs.statSync(dir).isDirectory() ? dir : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// List Lark account hash directories under sdk_storage, sorted by
+// cookie_store.db mtime descending. Hash dirs without a cookie_store.db
+// are filtered (account never logged in / cleared).
+//
+// Returns: [{ hash, mtimeMs, dir }]
+function listAccountHashes({ dir } = {}) {
+  const root = dir || getSdkStorageDir();
+  if (!root) return [];
+  let entries;
+  try { entries = fs.readdirSync(root); } catch (_) { return []; }
+  const out = [];
+  for (const name of entries) {
+    if (!HASH_RE.test(name)) continue;
+    const accountDir = path.join(root, name);
+    const dbPath = path.join(accountDir, 'cookie_store.db');
+    let mtimeMs;
+    try { mtimeMs = fs.statSync(dbPath).mtimeMs; } catch (_) { continue; }
+    out.push({ hash: name, mtimeMs, dir: accountDir });
+  }
+  out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return out;
+}
+
+function mostRecentHash(opts = {}) {
+  const list = listAccountHashes(opts);
+  return list.length > 0 ? list[0] : null;
+}
+
+// Pure-ish reactor logic, dependency-injected for unit tests.
+//
+// Inputs:
+//   prevSnapshot: { [hash]: mtimeMs } from the previous heartbeat
+//   lastSwitchAt: ms timestamp of the last auto-switch (debounce key)
+//   seenUnboundHashes: Set<hash> — emit hint once per hash per session
+//   credsApi: { getActiveProfileName, getProfileLarkHash, findProfileByHash }
+//   listFn: () => [...] — defaults to listAccountHashes() with auto-detected dir
+//   now: ms — defaults to Date.now()
+//   log: (msg) => void — defaults to console.error (the unbound-hash hint goes here)
+//
+// Returns:
+//   { switchTo: { hash, profile } | null, isUnbound: boolean, hash?: string }
+//
+// Mutates seenUnboundHashes (adds the hash when it emits a hint).
+function detectSwitch({
+  prevSnapshot,
+  lastSwitchAt,
+  seenUnboundHashes,
+  credsApi,
+  listFn,
+  now,
+  log,
+} = {}) {
+  if (!credsApi) credsApi = require('./credentials');
+  if (!listFn) listFn = () => listAccountHashes();
+  if (typeof now !== 'number') now = Date.now();
+  if (typeof log !== 'function') log = console.error;
+
+  if (now - lastSwitchAt < SWITCH_DEBOUNCE_MS) {
+    return { switchTo: null, isUnbound: false };
+  }
+
+  const list = listFn();
+  if (list.length === 0) return { switchTo: null, isUnbound: false };
+
+  const top = list[0];
+  const activeProfile = credsApi.getActiveProfileName();
+  const activeHash = credsApi.getProfileLarkHash(activeProfile);
+  if (top.hash === activeHash) return { switchTo: null, isUnbound: false };
+
+  // Only act on a true mtime advance — this prevents repeatedly switching
+  // when the snapshot baseline shows a stable older delta.
+  const prev = prevSnapshot[top.hash] || 0;
+  if (top.mtimeMs <= prev) return { switchTo: null, isUnbound: false };
+
+  const targetProfile = credsApi.findProfileByHash(top.hash);
+  if (!targetProfile) {
+    const isFresh = (now - top.mtimeMs) < UNBOUND_FRESH_WINDOW_MS;
+    if (isFresh && seenUnboundHashes && !seenUnboundHashes.has(top.hash)) {
+      seenUnboundHashes.add(top.hash);
+      log(
+        `[feishu-user-plugin] Lark Desktop active account hash ${top.hash} is not bound to any MCP profile. ` +
+        `Run: npx feishu-user-plugin setup --profile <name> --bind-hash ${top.hash}`
+      );
+    }
+    return { switchTo: null, isUnbound: true, hash: top.hash };
+  }
+
+  return { switchTo: { hash: top.hash, profile: targetProfile }, isUnbound: false };
+}
+
+module.exports = {
+  HASH_RE,
+  SWITCH_DEBOUNCE_MS,
+  UNBOUND_FRESH_WINDOW_MS,
+  getSdkStorageDir,
+  listAccountHashes,
+  mostRecentHash,
+  detectSwitch,
+};

package/src/server.js

@@ -80,6 +80,11 @@ let ownerHeartbeatTimer = null;
 let nonOwnerPollTimer = null;
 let _ownerStartCallbacks = [];
 
+// Lark Desktop reactor state (v1.3.11 §A) — owned by the heartbeat callback.
+let _lastHashMtimes = {};
+let _lastSwitchAt = 0;
+const _seenUnboundHashes = new Set();
+
 function _onBecomeOwner(cb) { _ownerStartCallbacks.push(cb); }
 
 function _stopHeartbeat() {
@@ -203,6 +208,9 @@ async function _claimAndStart() {
 
   // Heartbeat + check active changes every 15s.
   let lastCredMtime = _credMtime();
+  // Bootstrap baseline so the very first heartbeat doesn't trigger a switch.
+  _lastHashMtimes = require('./auth/lark-desktop').listAccountHashes()
+    .reduce((acc, h) => { acc[h.hash] = h.mtimeMs; return acc; }, {});
   ownerHeartbeatTimer = setInterval(() => {
     if (ownerHandle) ownerHandle.heartbeat();
     const m = _credMtime();
@@ -210,6 +218,12 @@ async function _claimAndStart() {
       lastCredMtime = m;
       _maybeReconfigure().catch((e) => console.error(`[feishu-user-plugin] reconfigure failed: ${e.message}`));
     }
+    // Lark Desktop reactor (v1.3.11 §A)
+    try {
+      _runLarkDesktopReactor();
+    } catch (e) {
+      console.error(`[feishu-user-plugin] Lark reactor error: ${e.message}`);
+    }
     // Defer-rotate check
     try {
       const snap = events.cursor.readSnapshot(FEISHU_HOME);
@@ -242,6 +256,34 @@ function _credMtime() {
   } catch (_) { return null; }
 }
 
+// Lark Desktop reactor (v1.3.11 §A).
+// Called from the owner heartbeat. When the most-recently-active hash differs
+// from the active profile's bound hash AND its mtime advanced since the last
+// snapshot, flip credentials.json::active to the matching profile (the existing
+// _credMtime delta on the next tick triggers _maybeReconfigure which restarts
+// the WS client with the new profile's events list).
+function _runLarkDesktopReactor() {
+  const ld = require('./auth/lark-desktop');
+  const out = ld.detectSwitch({
+    prevSnapshot: _lastHashMtimes,
+    lastSwitchAt: _lastSwitchAt,
+    seenUnboundHashes: _seenUnboundHashes,
+  });
+  if (out.switchTo) {
+    _lastSwitchAt = Date.now();
+    console.error(
+      `[feishu-user-plugin] Lark Desktop account changed; switching profile to ` +
+      `"${out.switchTo.profile}" (hash ${out.switchTo.hash})`
+    );
+    try { credentials.setActiveProfile(out.switchTo.profile); }
+    catch (e) { console.error(`[feishu-user-plugin] setActiveProfile failed: ${e.message}`); }
+  }
+  // Refresh snapshot regardless of switch outcome — keeps debounce + advance
+  // detection consistent on subsequent ticks.
+  _lastHashMtimes = ld.listAccountHashes()
+    .reduce((acc, h) => { acc[h.hash] = h.mtimeMs; return acc; }, {});
+}
+
 // Cross-process active-profile sync (v1.3.9 A.2).
 // Each tool call: stat credentials.json; if mtime changed AND active differs
 // from in-memory currentProfile, do an in-process setActiveProfile().

package/src/setup.js

@@ -28,6 +28,8 @@ function parseArgs() {
     else if (argv[i] === '--force') args.force = true;
     else if (argv[i] === '--profile' && argv[i + 1]) args.profile = argv[++i];
     else if (argv[i] === '--activate') args.activate = true;
+    else if (argv[i] === '--bind-hash' && argv[i + 1]) args.bindHash = argv[++i];
+    else if (argv[i] === '--no-bind-hash') args.noBindHash = true;
   }
   return args;
 }
@@ -238,6 +240,48 @@ async function main() {
   }
   // mode === 'preserve': credentials.json is unchanged; we only update the harness pointer.
 
+  // --- Lark Desktop hash auto-bind (v1.3.11 §A) ---
+  // Triggers on fresh / update (i.e. whenever credentials.json was just modified).
+  // Skipped via --no-bind-hash. Explicit --bind-hash overrides auto-detect.
+  if ((mode === 'fresh' || mode === 'update') && !cliArgs.noBindHash) {
+    try {
+      const larkDesktop = require('./auth/lark-desktop');
+      const hashes = larkDesktop.listAccountHashes();
+      if (hashes.length > 0) {
+        let chosenHash = cliArgs.bindHash;
+        if (!chosenHash) {
+          if (hashes.length === 1) {
+            chosenHash = hashes[0].hash;
+            console.log(`\n[Lark Desktop] Detected single account hash: ${chosenHash}`);
+          } else if (nonInteractive) {
+            chosenHash = hashes[0].hash;
+            console.log(`\n[Lark Desktop] Detected ${hashes.length} accounts; auto-binding "${targetProfile}" to most-recent: ${chosenHash}`);
+            console.log(`  Other hashes (run setup --profile <name> --bind-hash <hash> to bind):`);
+            hashes.slice(1).forEach((h) => {
+              const ts = new Date(h.mtimeMs).toISOString();
+              console.log(`    - ${h.hash}  (last active ${ts})`);
+            });
+          } else {
+            console.log(`\n[Lark Desktop] Multiple accounts detected:`);
+            hashes.forEach((h, i) => {
+              const ts = new Date(h.mtimeMs).toISOString();
+              console.log(`  ${i + 1}. ${h.hash}  (last active ${ts})`);
+            });
+            const pick = (await ask(`Bind profile "${targetProfile}" to which? [1]: `)).trim() || '1';
+            const idx = parseInt(pick, 10) - 1;
+            chosenHash = (idx >= 0 && idx < hashes.length) ? hashes[idx].hash : hashes[0].hash;
+          }
+        }
+        credentials.setProfileLarkHash(targetProfile, chosenHash);
+        console.log(`Bound profile "${targetProfile}" to Lark account hash ${chosenHash}`);
+        console.log(`  → MCP will auto-switch to this profile when Lark Desktop activates this account.`);
+      }
+      // hashes.length === 0 → silent (Lark not installed, or non-darwin) — don't disrupt setup
+    } catch (e) {
+      console.error(`[Lark Desktop] auto-bind skipped: ${e.message}`);
+    }
+  }
+
   // --- Write harness config ---
   // Always write pointer-only env to harness configs (v1.3.9 SSOT).
   // The harness env block only needs FEISHU_PLUGIN_PROFILE; all real creds