feishu-user-plugin 1.3.9 → 1.3.11

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.9",
-  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging (incl. user-identity image send v1.3.9 + batch_send), docs (markdown read v1.3.9, image/file blocks), bitable, wiki, drive, OKR, calendar, Tasks v2, multi-profile (cross-process sync v1.3.9), machine-level shared WS events (v1.3.9). 84 tools + 9 prompts, 3 auth layers.",
+  "mcpName": "io.github.EthanQC/feishu-user-plugin",
+  "version": "1.3.11",
+  "description": "All-in-one Feishu MCP server for Claude Code & Codex — 84 tools across 3 auth layers (cookie / app / OAuth). Send as you, read groups, manage docs / bitable / wiki / drive / calendar / tasks / OKR.",
   "main": "src/index.js",
   "bin": {
     "feishu-user-plugin": "src/cli.js"
@@ -44,11 +45,15 @@
     "proto/",
     "scripts/",
     ".claude-plugin/",
+    ".cursor-plugin/",
+    ".mcpb/",
     "skills/",
     ".mcp.json.example",
     ".env.example",
     "CHANGELOG.md",
     "README.md",
+    "README.en.md",
+    "PRIVACY.md",
     "LICENSE"
   ],
   "engines": {

package/scripts/build-mcpb.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/build-mcpb.js
+//
+// Packages the runtime files + .mcpb/manifest.json into
+// dist/feishu-user-plugin-<version>.mcpb (a ZIP with manifest.json at the root).
+//
+// The .mcpb format is a plain ZIP archive consumed by Claude Desktop / Anthropic
+// Connectors Directory. Required layout:
+//   manifest.json            (at root, copied from .mcpb/manifest.json)
+//   src/...                  (server runtime)
+//   proto/...                (protobuf descriptors)
+//   skills/...               (MCP prompts source)
+//   .claude-plugin/...       (plugin metadata)
+//   package.json             (so `node src/index.js` resolves deps after `npm ci`)
+//   package-lock.json
+//   PRIVACY.md, README.md, LICENSE
+//
+// node_modules/ is NOT bundled; the connector host runs `npm ci --omit=dev`
+// against the bundled package.json once installed (Anthropic convention).
+//
+// Re-runnable: overwrites dist/feishu-user-plugin-<version>.mcpb on each run.
+//
+// Usage:
+//   node scripts/build-mcpb.js
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const ROOT = path.join(__dirname, '..');
+const DIST = path.join(ROOT, 'dist');
+const MANIFEST_SRC = path.join(ROOT, '.mcpb', 'manifest.json');
+
+function fail(msg) {
+  console.error(`build-mcpb: ${msg}`);
+  process.exit(1);
+}
+
+if (!fs.existsSync(MANIFEST_SRC)) fail('.mcpb/manifest.json not found');
+
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const manifest = JSON.parse(fs.readFileSync(MANIFEST_SRC, 'utf8'));
+
+if (!manifest.version) fail('.mcpb/manifest.json missing `version`');
+if (manifest.version !== pkg.version) {
+  fail(
+    `version mismatch — package.json=${pkg.version} but .mcpb/manifest.json=${manifest.version}. ` +
+      `Run: node scripts/check-mcpb-version.js`
+  );
+}
+
+const VERSION = pkg.version;
+const OUT = path.join(DIST, `feishu-user-plugin-${VERSION}.mcpb`);
+
+if (!fs.existsSync(DIST)) fs.mkdirSync(DIST, { recursive: true });
+if (fs.existsSync(OUT)) fs.unlinkSync(OUT);
+
+// Files & dirs to bundle. Order matters only for predictable zip output.
+// Mirrors package.json::files plus PRIVACY.md and the bundled manifest.json.
+const ENTRIES = [
+  'manifest.json', // synthesized at staging root from .mcpb/manifest.json
+  'src',
+  'proto',
+  'scripts',
+  '.claude-plugin',
+  'skills',
+  'package.json',
+  'package-lock.json',
+  'PRIVACY.md',
+  'README.md',
+  'LICENSE',
+];
+
+// Stage in a tmp dir so the zip has manifest.json at the archive root rather
+// than .mcpb/manifest.json. Using a tmp dir keeps the source tree clean.
+const STAGE = fs.mkdtempSync(path.join(require('os').tmpdir(), 'mcpb-build-'));
+try {
+  // Copy manifest.json to staging root
+  fs.copyFileSync(MANIFEST_SRC, path.join(STAGE, 'manifest.json'));
+
+  // Copy each remaining entry from repo root → staging root
+  for (const entry of ENTRIES.slice(1)) {
+    const src = path.join(ROOT, entry);
+    if (!fs.existsSync(src)) {
+      console.warn(`build-mcpb: skipping missing entry: ${entry}`);
+      continue;
+    }
+    const dest = path.join(STAGE, entry);
+    copyRecursive(src, dest);
+  }
+
+  // Create the ZIP via system `zip` (present on macOS + ubuntu-latest CI).
+  // -r recursive, -X strip extra OS attrs for reproducibility, -q quiet.
+  // We pass `.` so paths inside the zip are relative to the staging root.
+  execFileSync('zip', ['-rqX', OUT, '.'], { cwd: STAGE, stdio: 'inherit' });
+} finally {
+  fs.rmSync(STAGE, { recursive: true, force: true });
+}
+
+const stats = fs.statSync(OUT);
+console.log(`OK: built ${path.relative(ROOT, OUT)} (${(stats.size / 1024).toFixed(1)} KB)`);
+
+// --- helpers ------------------------------------------------------------
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const child of fs.readdirSync(src)) {
+      // Skip OS noise + already-built artifacts inside copied dirs
+      if (child === '.DS_Store' || child === 'node_modules' || child === 'dist') continue;
+      copyRecursive(path.join(src, child), path.join(dest, child));
+    }
+  } else if (stat.isFile()) {
+    fs.copyFileSync(src, dest);
+  }
+}

package/scripts/check-mcp-registry-version.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+// Verifies mcp-registry.json::version + packages[0].version == package.json::version.
+// Wired into:
+//   - .github/workflows/publish.yml — pre-publish gate so CI never publishes to the
+//     official MCP Registry with a stale version string.
+//   - .github/workflows/validate.yml — PR-time gate so any version bump on
+//     package.json without a matching bump on mcp-registry.json fails before merge.
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const pkgVersion = pkg.version;
+
+const registryPath = path.join(ROOT, 'mcp-registry.json');
+const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+const registryVersion = registry.version;
+
+if (!Array.isArray(registry.packages) || registry.packages.length === 0) {
+  console.error('ERROR: mcp-registry.json has no packages[] entries');
+  process.exit(1);
+}
+const pkgEntryVersion = registry.packages[0].version;
+
+const sources = [
+  { label: 'package.json', version: pkgVersion, path: 'package.json' },
+  { label: 'mcp-registry.json::version', version: registryVersion, path: 'mcp-registry.json' },
+  { label: 'mcp-registry.json::packages[0].version', version: pkgEntryVersion, path: 'mcp-registry.json' },
+];
+
+const allEqual = sources.every((s) => s.version === sources[0].version);
+
+if (!allEqual) {
+  console.error('ERROR: mcp-registry.json version mismatch with package.json!');
+  sources.forEach((s) => console.error(`  ${s.label}: ${s.version}`));
+  console.error('Fix: bump mcp-registry.json::version AND mcp-registry.json::packages[0].version');
+  console.error(`     to match package.json (${pkgVersion}).`);
+  process.exit(1);
+}
+
+console.log(`OK: mcp-registry.json version ${pkgVersion}`);

package/scripts/check-mcpb-version.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+// Source 1: package.json
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const pkgVersion = pkg.version;
+
+// Source 2: .mcpb/manifest.json
+const manifestPath = path.join(ROOT, '.mcpb', 'manifest.json');
+if (!fs.existsSync(manifestPath)) {
+  console.error('ERROR: .mcpb/manifest.json not found');
+  process.exit(1);
+}
+const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+const manifestVersion = manifest.version;
+
+if (!manifestVersion) {
+  console.error('ERROR: .mcpb/manifest.json is missing the `version` field');
+  process.exit(1);
+}
+
+if (pkgVersion !== manifestVersion) {
+  console.error('ERROR: .mcpb manifest version mismatch!');
+  console.error(`  package.json:        ${pkgVersion}`);
+  console.error(`  .mcpb/manifest.json: ${manifestVersion}`);
+  process.exit(1);
+}
+
+console.log(`OK: .mcpb manifest version ${pkgVersion}`);

package/scripts/check-version.js

@@ -22,10 +22,15 @@ if (!skillMatch) {
 }
 const skillVersion = skillMatch[1];
 
+// Source 4: .cursor-plugin/plugin.json
+const cursorPlugin = JSON.parse(fs.readFileSync(path.join(ROOT, '.cursor-plugin', 'plugin.json'), 'utf8'));
+const cursorVersion = cursorPlugin.version;
+
 const sources = [
   { label: 'package.json', version: pkgVersion, path: 'package.json' },
   { label: '.claude-plugin/plugin.json', version: pluginVersion, path: '.claude-plugin/plugin.json' },
   { label: 'skills/feishu-user-plugin/SKILL.md', version: skillVersion, path: 'skills/feishu-user-plugin/SKILL.md' },
+  { label: '.cursor-plugin/plugin.json', version: cursorVersion, path: '.cursor-plugin/plugin.json' },
 ];
 
 const versions = sources.map((s) => s.version);

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.9"
+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,
+};