feishu-user-plugin 1.3.7 → 1.3.8

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.7",
-  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself, read chats (auto-expanded merge_forward), manage docs / bitable / wiki (full CRUD) / drive / OKR (with progress writes) / calendar (read+write) / Tasks v2 / multi-profile. 80 tools + 9 prompts, 3 auth layers.",
+  "version": "1.3.8",
+  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself, read chats (auto-expanded merge_forward), manage docs / bitable / wiki (full CRUD) / drive / OKR (with progress writes) / calendar (read+write) / Tasks v2 / multi-profile auto-switch / real-time WS events. 82 tools + 9 prompts, 3 auth layers.",
   "author": {
     "name": "EthanQC"
   },

package/CHANGELOG.md

@@ -4,6 +4,55 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.3.8] - 2026-05-05
+
+### Added
+- **Multi-profile auto-switch (B)**: when `~/.feishu-user-plugin/credentials.json` has ≥2 profiles, read-only tools (`read_*` / `list_*` / `get_*` / `search_*` / `download_*` plus `manage_bitable_*` read-action variants) auto-retry across profiles on permission-denied errors. Trigger codes `91403 / 1254301 / 1254000 / 99991672 / HTTP 403` plus message patterns. The winning profile is cached to `credentials.json::profileHints` so subsequent calls go straight to the right account. Writes never auto-switch — pass `via_profile: "auto"` per call to opt in. New tool: `manage_profile_hints(action=list|set|clear, resource_key?, profile?)`. Single-profile users see no behaviour change.
+- **Real-time WebSocket events (C)**: MCP server opens a `WSClient` connection at boot when `LARK_APP_ID/SECRET` are configured; events accumulate into an in-memory FIFO buffer (cap 1000) and surface via the new `get_new_events(event_type?, event_types?, chat_id?, since_seconds?, max_events=50, peek=false)` tool. Currently registers `im.message.receive_v1` (replies / group activity). feishu.cn only — Lark international not supported by Feishu's `WSClient`. Buffer is in-memory; events received before MCP boot aren't replayed.
+- **Cookie protobuf wire-format tooling (A.0)**: `scripts/decode-feishu-protobuf.js` decodes a captured payload against `proto/lark.proto` and reports unknown field tags + wire types so we know what to add. `scripts/capture-feishu-protobuf.js` documents the per-type session recipe and runs DECODE on `/tmp/feishu-captures`. Living write-up in `docs/COOKIE-PROTOBUF-CAPTURES.md`. Actual IMAGE / AUDIO / STICKER / CARD / search_messages captures move to v1.3.9 — tooling is in place; capture session is high-touch and preferably done by hand.
+- **`FEISHU_PLUGIN_PROFILE` env override (E.1)**: harness env can pin an active profile, validated at boot (fatal exit 2 on typo). Lets a single `credentials.json` serve different harnesses with different active profiles (Claude Code on "work", Codex on "personal").
+- **`setup --pointer-only` mode (E.2)**: writes only `FEISHU_PLUGIN_PROFILE=default` to harness env; real creds live solely in `credentials.json`. Eliminates env-vs-file divergence on UAT refresh. Opt-in (interactive prompt + flag).
+- **Migrate startup nudge (E.3)**: legacy env-only setups get a one-line TIP at MCP boot pointing at `npx feishu-user-plugin migrate --confirm`. Skipped when `credentials.json` already exists.
+- **CI / docs gates (F)**: `scripts/sync-server-json.js` regenerates `server.json` from `package.json + TOOLS` (was frozen at v1.2.0 / 33 tools — now matches reality). `scripts/check-tool-count.js` extended to verify `SKILL.md::allowed-tools` in addition to README badge. `scripts/check-changelog.js` blocks publish when CHANGELOG has no section for the tag version. `scripts/check-docs-sync.js` enforces CLAUDE.md / AGENTS.md / skill-ref triple-sync at prepublish + CI.
+
+### Changed
+- **`src/auth/uat.js` and `src/auth/cookie.js` extracted (D.1, D.2)** from `clients/official/base.js` and `clients/user.js` respectively. State (`this._uat` / `this._heartbeatTimer` / etc.) still lives on the client; only function bodies moved. base.js drops ~200 lines. Closes the v1.3.7 Phase B deferrals noted in `docs/REFACTOR-NOTES.md`.
+
+### Fixed
+- **G.1 wiki-attach fallback retest scaffold**: `scripts/test-wiki-attach-fallback.js` monkey-patches `attachToWiki` to throw 91403 and verifies `upload_drive_file` surfaces the failure rather than silently uploading to drive root. POSIX skip 77 when missing creds / `FEISHU_TEST_FOLDER_TOKEN`.
+
+### Deferred to v1.3.9
+- Cookie protobuf wire format reverse for IMAGE / AUDIO / STICKER / CARD / search_messages — tooling is in place (`scripts/decode-feishu-protobuf.js`, `scripts/capture-feishu-protobuf.js`, `docs/COOKIE-PROTOBUF-CAPTURES.md`), capture sessions are pending.
+- `switch_profile` multi-profile e2e — needs a real second profile in tests.
+- Test group `oc_daaa6a50f2a97dc668aaf79ae4dc6e4e` dissolution — needs owner-permission transfer.
+
+## [1.3.7] - 2026-05-04
+
+### Added
+- **Wiki write (5 tools)**: `create_wiki_node` / `update_wiki_node` / `move_wiki_node` / `copy_wiki_node` / `delete_wiki_node`. UAT-first. `create_wiki_node` builds doc/sheet/bitable/mindnote/file/docx/slides directly inside a wiki space, or `node_type=shortcut` for a pointer. `update_wiki_node` only patches `title` (Feishu wiki API doesn't accept content edits — those go through docx/bitable/sheet). `move`/`copy` accept `target_parent_token` + optional `target_space_id` for cross-space migration. `delete_wiki_node` calls `DELETE /wiki/v2/spaces/{id}/nodes/{token}` via raw REST (SDK doesn't type it) — only deletes the node pointer, not the underlying drive resource.
+- **OKR progress writes (3 tools)**: `create_okr_progress_record` / `list_okr_progress_records` / `delete_okr_progress_record`. UAT-first. Requires `okr:okr.content:write` scope. `create` accepts a simplified `content_text` (auto-wrapped into Feishu's block schema) plus optional `source_title` / `source_url` / `progress_percent`. `list` extracts `{progress_id, target_id, target_type}` triples from `get_okrs` since Feishu has no native list endpoint.
+- **Calendar write (5 tools)**: `create_calendar_event` / `update_calendar_event` / `delete_calendar_event` / `respond_calendar_event` / `get_freebusy`. UAT-first. Requires `calendar:calendar.event:write` scope. `start_time` / `end_time` are objects: `{timestamp:"<unix-seconds>", timezone?}` or `{date:"YYYY-MM-DD"}`. `delete` accepts `meeting_chat_id` to also dissolve the linked meeting chat. `respond` is the RSVP path.
+- **Tasks v2 (7 tools, new domain)**: `list_tasks` / `get_task` / `create_task` / `update_task` / `complete_task` / `delete_task` / `manage_task_members`. UAT-first. Requires `task:task` scope. v2 uses `task_guid` instead of v1 numeric `task_id`. `update_task` requires explicit `update_fields=["summary","due","completed_at",...]` — Feishu only patches the listed fields. `complete_task(completed=true|false)` is a convenience wrapper.
+- **MCP prompts (9)**: `/send` `/reply` `/digest` `/search` `/doc` `/table` `/wiki` `/drive` `/status`. Mirror the Claude Code skills via `prompts/list` + `prompts/get`, so Codex / Cursor / OpenClaw / Windsurf get the same guided UX. Reference bodies are read at server start from `skills/feishu-user-plugin/references/`.
+- **Single-source credentials store**: `~/.feishu-user-plugin/credentials.json` (mode 0600, schema `docs/CREDENTIALS-FORMAT.md`). Multiple MCP processes (Claude Code + Codex sharing the file) see token rotations consistently — closes the "Codex still has the old UAT after a refresh in Claude Code" drift. Cookie heartbeat + UAT refresh persist back atomically. Opt-in: `npx feishu-user-plugin migrate` (dry-run) / `migrate --confirm` (writes). Env vars remain as backward-compat fallback. Server's `Auth:` startup line on stderr shows source (`credentials.json profile=default` vs `env vars (legacy)`).
+- **Semi-automated regression**: `scripts/test-all-tools.js` walks every tool with representative payloads. `tests/baseline/` snapshots `tools-list.json` / `prompts-list.json` / `login-status-shape.json`; `npm run smoke` diffs against them, `npm run smoke:baseline` regenerates after intentional schema change. `docs/TESTING-METHODOLOGY.md` documents when to use unit / smoke / live MCP / `test-all-tools`.
+
+### Fixed
+- **C1.4 — `send_*_as_user` silently dropped messages with `oc_xxx` chat IDs**: cookie protobuf gateway's `PutMessageRequest.chatId` only recognizes numeric IDs; an `oc_xxx` was treated as unknown and the server returned an empty packet. Now auto-resolves `oc_xxx` via `getChatInfo(name) → cookie search(name) → numeric` and caches the mapping. Covers `send_as_user` / `send_image_as_user` / `send_file_as_user` / `send_post_as_user` / `send_card_as_user` / `batch_send`. Numeric IDs pass through unchanged. Resolution failure throws a clear error.
+- **`list_wiki_nodes` returned 131006 in spaces the bot wasn't invited to**: `list_wiki_spaces` was already UAT-first, but `list_wiki_nodes` was bot-only. Made `list_wiki_nodes` UAT-first to match.
+- **C1.15 — `get_user_info` showed current user as external tenant**: `getUserById` previously hit contact API first (requires `contact:user.base:readonly`); some OAuth configs returned no permission for same-tenant queries and the user was wrongly downgraded. Now UAT-first, contact API as fallback.
+- **`manage_drive_file(action=delete)` printed `task=undefined`**: `DELETE /drive/v1/files/{token}` is synchronous and returns no `task_id`. Switched to `File deleted ({type})` when no task_id, `File deletion queued: task=...` when one is returned.
+- **`send_image_as_user` failed silently**: cookie protobuf gateway rejects the simple `{imageKey}` content payload (HTTP 400) because Feishu Web actually encodes images with extra metadata (dimensions, MIME, thumbnails) that aren't in `proto/lark.proto`. Now throws a clear error pointing to `send_message_as_bot(msg_type="image", payload={image_key:"..."})` as the workaround. Wire format reverse-engineering deferred to v1.3.8 (needs Chrome DevTools traffic capture).
+- Documented common error codes in tool schemas: 9499 (`manage_members` missing `member_id_type`, default `open_id`), 1062501 / 1061002 (`manage_drive_file` missing `type`).
+
+### Changed
+- **Phase A refactor**: 7,500-line `src/index.js` split into `src/tools/<domain>.js` (handlers + schemas) and `src/clients/official/<domain>.js` (API methods). `src/server.js` orchestrates registration; `src/tools/_registry.js` provides shared `ctx` (factories, profile state, `resolveDocId`). See `docs/REFACTOR-NOTES.md` for the file-responsibility matrix.
+- **Tool consolidation (82 → 80)**: 21 bitable tools collapsed into 5 `manage_bitable_*` dispatchers (app / table / field / view / record, each with `action=list|create|update|delete|...`). 3 doc-block tools → `manage_doc_block(action=create|update|delete)`. 3 drive ops → `manage_drive_file(action=copy|move|delete)`. 2 download tools → `download_message_resource(kind=image|file)` + `download_doc_image`. Semantics unchanged; parameters collapsed onto an `action` field.
+- **Writes default to UAT**: every `create`/`edit` for docx / bitable / drive / wiki / OKR / calendar / tasks runs through `_asUserOrApp` — UAT first, bot only as fallback. Forced bot fallback appends a ⚠ warning to the response (and points to `npx feishu-user-plugin oauth`) so the ownership shift surfaces immediately.
+- **ID input normalization**: docx / bitable tools' `document_id` / `app_token` accept native token (`doccnXXX` / `docxXXX` / `bascnXXX`), wiki node token (`wikcnXXX` / `wikmXXX` / `wiknXXX`), and full Feishu URLs. Internally resolved via `getWikiNode` with a 10-minute cache.
+- **Upload scope inventory**: `uploadMedia` / `upload_drive_file` / `upload_bitable_attachment` / `manage_doc_block(image_path|file_path)` collectively need `drive:drive`, `drive:file:upload`, `docs:document.media:upload`, and `sheets:spreadsheet` (sheet uploads only). Documented in CLAUDE.md and the OAuth scope table.
+- **team-skills sync via PR**: post-merge hook in this repo now opens an auto-merging PR against team-skills instead of pushing to main. CI `validate.yml` enforces a version triangle across `plugin.json` / `SKILL.md` / `README.md` first `### vX.Y.Z` heading.
+
 ## [1.3.6] - 2026-05-03
 
 ### Added

package/README.md

@@ -3,10 +3,10 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
-[![Tools](https://img.shields.io/badge/Tools-80-orange.svg)](#tools)
+[![Tools](https://img.shields.io/badge/Tools-82-orange.svg)](#tools)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**All-in-one Feishu/Lark MCP Server -- 80 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, OKR, and more.**
+**All-in-one Feishu/Lark MCP Server -- 82 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, OKR, and more.**
 
 The only MCP server that lets you send messages as your **personal identity** (not a bot), while also integrating the full official Feishu API. Works with Claude Code, Cursor, Windsurf, OpenClaw, and any MCP-compatible client.
 
@@ -21,6 +21,7 @@ The only MCP server that lets you send messages as your **personal identity** (n
 - **Calendar & Tasks** -- Create events, check free/busy, manage tasks.
 - **9 slash commands** for Claude Code -- `/send`, `/reply`, `/search`, `/digest`, `/doc`, `/table`, `/wiki`, `/drive`, `/status`
 - **Auto session management** -- Cookie heartbeat every 4h, UAT auto-refresh with token rotation.
+- **Real-time events** (v1.3.8) -- `get_new_events` drains an in-memory queue of incoming Feishu messages — react to replies / group activity within seconds without polling. WS connection auto-starts on boot.
 - **Multi-platform** -- Claude Code, Cursor, Windsurf, VS Code, OpenClaw.
 
 ## Why This Exists
@@ -474,12 +475,27 @@ Identifier is `task_guid` (not v1's numeric `task_id`). Requires `task:task` sco
 | `move_wiki_node` | Move a wiki node to a different parent or different space |
 | `copy_wiki_node` | Deep-copy a wiki node to a different location (optionally to a different space) |
 
-### Plugin -- Profiles (2 tools, v1.3.6)
+### Plugin -- Profiles (3 tools, v1.3.6 + v1.3.8)
 
 | Tool | Description |
 |------|-------------|
 | `list_profiles` | List available identity profiles (default + extras from `LARK_PROFILES_JSON`) and the active one |
 | `switch_profile` | Hot-swap active profile; cached client instances rebuild against new credentials |
+| `manage_profile_hints` | Inspect/set/clear the resourceKey → profile cache used by the v1.3.8 auto-switch middleware |
+
+### Multi-profile auto-switch (v1.3.8)
+
+When `~/.feishu-user-plugin/credentials.json` has more than one profile, the plugin auto-switches between them on **read** paths when the active profile gets a permission-denied error. The winning profile is cached per resource so subsequent calls go straight to the right account.
+
+**Whitelist** -- only `read_*`, `list_*`, `get_*`, `search_*`, `download_*` (and the read-action variants of `manage_bitable_*`) get auto-retry. Writes never auto-switch -- they fail loud so you don't accidentally create resources under the wrong account.
+
+**Triggers** -- error codes 91403, 1254301, 1254000, 99991672, HTTP 403, plus message patterns `access_denied / permission_denied / docx_no_permission / no permission / forbidden`.
+
+**Per-call override** -- pass `via_profile: "<name>"` in any tool call to pin to that profile (no auto-switch). Pass `via_profile: "auto"` to opt **into** auto-switch on a write call (escape hatch -- be careful).
+
+**Cache management** -- `manage_profile_hints(action="list" | "set" | "clear", resource_key?, profile?)` lets you inspect or edit the cache.
+
+Single-profile users (the vast majority): zero behaviour change -- the router short-circuits and `manage_profile_hints` is a no-op.
 
 ## Claude Code Slash Commands (9 skills)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.7",
-  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging (with merge_forward expansion + batch_send), docs (image + file blocks read/write), bitable, wiki (full CRUD), drive, OKR (with progress writes), calendar (read+write), Tasks v2, multi-profile. 80 tools + 9 prompts, 3 auth layers.",
+  "version": "1.3.8",
+  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging (with merge_forward expansion + batch_send), docs (image + file blocks read/write), bitable, wiki (full CRUD), drive, OKR (with progress writes), calendar (read+write), Tasks v2, multi-profile auto-switch, real-time WS events. 82 tools + 9 prompts, 3 auth layers.",
   "main": "src/index.js",
   "bin": {
     "feishu-user-plugin": "src/cli.js"
@@ -14,7 +14,7 @@
     "smoke": "node scripts/smoke.js diff",
     "smoke:baseline": "node scripts/smoke.js write-baseline",
     "test:tools": "node scripts/test-all-tools.js",
-    "prepublishOnly": "node scripts/check-version.js && node scripts/check-tool-count.js && node scripts/confirm-version.js",
+    "prepublishOnly": "node scripts/check-version.js && node scripts/check-tool-count.js && node scripts/sync-server-json.js check && node scripts/check-docs-sync.js && node scripts/check-changelog.js && node scripts/confirm-version.js",
     "prepare": "husky"
   },
   "keywords": [

package/scripts/capture-feishu-protobuf.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+'use strict';
+// Companion script to docs/COOKIE-PROTOBUF-CAPTURES.md.
+//
+// Drives a single capture session: prints the recipe to follow, sets up
+// the output dir, and after capture, decodes everything dropped into it.
+//
+// Usage:
+//   node scripts/capture-feishu-protobuf.js IMAGE     # prints the IMAGE recipe
+//   node scripts/capture-feishu-protobuf.js DECODE    # decodes everything in /tmp/feishu-captures/
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const CAPTURE_DIR = '/tmp/feishu-captures';
+const TYPES = {
+  IMAGE: {
+    description: 'Image message via cookie protobuf — cmd=5 PutMessageRequest, content.type=5 (IMAGE)',
+    targetMessage: 'Content',
+  },
+  AUDIO: {
+    description: 'Audio message — cmd=5, content.type=7 (AUDIO)',
+    targetMessage: 'Content',
+  },
+  STICKER: {
+    description: 'Sticker — cmd=5, content.type=10 (STICKER)',
+    targetMessage: 'Content',
+  },
+  CARD: {
+    description: 'Interactive card — cmd=5, content.type=14 (CARD)',
+    targetMessage: 'Content',
+  },
+};
+
+const cmd = process.argv[2] || 'help';
+
+if (cmd === 'DECODE') {
+  if (!fs.existsSync(CAPTURE_DIR)) { console.error('No captures yet — run a TYPE first.'); process.exit(1); }
+  const files = fs.readdirSync(CAPTURE_DIR).filter(f => f.endsWith('.bin') || f.endsWith('.b64'));
+  if (!files.length) { console.error('No capture files in ' + CAPTURE_DIR); process.exit(1); }
+  for (const f of files) {
+    const type = path.basename(f).split('-')[0].toUpperCase();
+    const meta = TYPES[type] || { targetMessage: 'Packet' };
+    console.log(`\n=== ${f} (decoding as ${meta.targetMessage}) ===`);
+    const fullPath = path.join(CAPTURE_DIR, f);
+    const decodeScript = path.join(__dirname, 'decode-feishu-protobuf.js');
+    try {
+      if (f.endsWith('.b64')) {
+        const b64 = fs.readFileSync(fullPath, 'utf8').trim();
+        execSync(`node ${decodeScript} ${meta.targetMessage} --b64 ${JSON.stringify(b64)}`, { stdio: 'inherit' });
+      } else {
+        execSync(`node ${decodeScript} ${meta.targetMessage} < ${fullPath}`, { stdio: 'inherit' });
+      }
+    } catch (e) { console.error(`  decode failed: ${e.message}`); }
+  }
+  process.exit(0);
+}
+
+if (!TYPES[cmd]) {
+  console.log('Usage: node scripts/capture-feishu-protobuf.js [IMAGE|AUDIO|STICKER|CARD|DECODE]');
+  console.log('\nCapture types:');
+  for (const [k, v] of Object.entries(TYPES)) console.log(`  ${k}  — ${v.description}`);
+  console.log('\nRecipe (IMAGE example):');
+  console.log('  1. The agent uses Playwright MCP to:');
+  console.log('     a. Open https://www.feishu.cn/messenger/ with LARK_COOKIE');
+  console.log('     b. Click "我自己" / self-chat');
+  console.log('     c. Drag-drop a small test PNG OR click the image button + select file');
+  console.log('     d. Wait for the upload to complete');
+  console.log('     e. Click "send" and watch network for the POST to /im/gateway/');
+  console.log(`  2. Save the raw POST body to ${CAPTURE_DIR}/image-1.bin`);
+  console.log(`  3. Run: node scripts/capture-feishu-protobuf.js DECODE`);
+  process.exit(0);
+}
+
+fs.mkdirSync(CAPTURE_DIR, { recursive: true });
+console.log(`=== ${cmd} capture session ===`);
+console.log(TYPES[cmd].description);
+console.log(`\nCapture dir: ${CAPTURE_DIR}`);
+console.log('\nRecipe:');
+console.log('  1. Use Playwright MCP to open feishu.cn/messenger/ with cookie auth');
+console.log('  2. Send the message of type ' + cmd + ' to "我自己" via the web UI');
+console.log('  3. Capture POST /im/gateway/ request body via fetch monkey-patch');
+console.log(`  4. Drop the raw body to ${CAPTURE_DIR}/${cmd.toLowerCase()}-1.bin (or .b64)`);
+console.log(`  5. Run: node scripts/capture-feishu-protobuf.js DECODE`);
+console.log('\nSee docs/COOKIE-PROTOBUF-CAPTURES.md for full step-by-step.');

package/scripts/check-changelog.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+'use strict';
+// Verifies CHANGELOG.md has an "## [vX.Y.Z]" section matching package.json
+// version. Run from publish workflow + locally before tagging.
+//
+// Usage:
+//   node scripts/check-changelog.js               → checks current package.json version
+//   node scripts/check-changelog.js 1.3.8         → checks given version explicitly
+
+const fs = require('fs');
+const path = require('path');
+
+const explicit = process.argv[2];
+const pkgVersion = explicit || require(path.join(__dirname, '..', 'package.json')).version;
+
+const cl = fs.readFileSync(path.join(__dirname, '..', 'CHANGELOG.md'), 'utf8');
+
+// Common section headings used in this repo: "## [v1.3.7]" or "## v1.3.7" or "## 1.3.7" or "### v1.3.7".
+const patterns = [
+  new RegExp(`^##\\s*\\[?v?${pkgVersion.replace(/\./g, '\\.')}\\]?`, 'm'),
+  new RegExp(`^###\\s*v?${pkgVersion.replace(/\./g, '\\.')}`,        'm'),
+];
+const match = patterns.some(re => re.test(cl));
+
+if (!match) {
+  console.error(`ERROR: CHANGELOG.md has no section for v${pkgVersion}.`);
+  console.error(`Add "## [v${pkgVersion}]" or "### v${pkgVersion}" with the release notes before tagging.`);
+  process.exit(1);
+}
+
+console.log(`OK: CHANGELOG.md has v${pkgVersion} section`);

package/scripts/check-docs-sync.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+'use strict';
+// Verifies CLAUDE.md is in sync with AGENTS.md (Codex) and
+// skills/feishu-user-plugin/references/CLAUDE.md (skill reference copy).
+//
+// Pre-commit hook (scripts/sync-claude-md.sh) already auto-regenerates these
+// from CLAUDE.md, but this script gives prepublishOnly + CI a hard gate.
+//
+// Match logic mirrors validate.yml's diff steps:
+//   AGENTS.md = "# feishu-user-plugin — Codex Instructions\n" + tail -n +2 CLAUDE.md
+//   skills/.../CLAUDE.md = identical to CLAUDE.md
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const claude = fs.readFileSync(path.join(ROOT, 'CLAUDE.md'), 'utf8');
+
+// AGENTS.md: header replaced with "# feishu-user-plugin — Codex Instructions"
+const claudeBody = claude.split('\n').slice(1).join('\n'); // drop first line
+const expectedAgents = '# feishu-user-plugin — Codex Instructions\n' + claudeBody;
+const actualAgents = fs.readFileSync(path.join(ROOT, 'AGENTS.md'), 'utf8');
+
+const failures = [];
+if (actualAgents !== expectedAgents) {
+  failures.push('AGENTS.md is out of sync with CLAUDE.md');
+  failures.push('Fix: bash scripts/sync-claude-md.sh (or edit CLAUDE.md and re-stage)');
+}
+
+const skillRef = path.join(ROOT, 'skills', 'feishu-user-plugin', 'references', 'CLAUDE.md');
+const actualSkillRef = fs.readFileSync(skillRef, 'utf8');
+if (actualSkillRef !== claude) {
+  failures.push('skills/feishu-user-plugin/references/CLAUDE.md is out of sync with CLAUDE.md');
+  failures.push('Fix: bash scripts/sync-claude-md.sh (or edit CLAUDE.md and re-stage)');
+}
+
+if (failures.length) {
+  for (const f of failures) console.error(f);
+  process.exit(1);
+}
+console.log('OK: CLAUDE.md / AGENTS.md / skill reference all in sync');

package/scripts/check-tool-count.js

@@ -3,13 +3,38 @@
 const path = require('path');
 const fs = require('fs');
 const { TOOLS } = require(path.join(__dirname, '..', 'src', 'server'));
+
+const failures = [];
+
+// Source 1: README.md "N tools" badge
 const readme = fs.readFileSync(path.join(__dirname, '..', 'README.md'), 'utf8');
-// Find the canonical "N tools" reference. Pick the highest-confidence match.
-const m = readme.match(/(\d+)\s+tools/);
-if (!m) { console.error('No "N tools" badge in README.md'); process.exit(1); }
-const claimed = parseInt(m[1], 10);
-if (claimed !== TOOLS.length) {
-  console.error(`README claims ${claimed} tools, src/server.js has ${TOOLS.length}`);
+const readmeMatch = readme.match(/(\d+)\s+tools/);
+if (!readmeMatch) {
+  failures.push('No "N tools" badge in README.md');
+} else if (parseInt(readmeMatch[1], 10) !== TOOLS.length) {
+  failures.push(`README.md claims ${readmeMatch[1]} tools, src/server.js has ${TOOLS.length}`);
+}
+
+// Source 2: SKILL.md `allowed-tools` frontmatter — comma-separated list.
+const skillMd = fs.readFileSync(path.join(__dirname, '..', 'skills', 'feishu-user-plugin', 'SKILL.md'), 'utf8');
+const skillMatch = skillMd.match(/^allowed-tools:\s*(.+)$/m);
+if (!skillMatch) {
+  failures.push('No `allowed-tools:` line in skills/feishu-user-plugin/SKILL.md frontmatter');
+} else {
+  const skillTools = skillMatch[1].split(',').map(s => s.trim()).filter(Boolean);
+  const skillSet = new Set(skillTools);
+  const toolSet = new Set(TOOLS.map(t => t.name));
+  const missingFromSkill = [...toolSet].filter(t => !skillSet.has(t)).sort();
+  const extraInSkill = [...skillSet].filter(t => !toolSet.has(t)).sort();
+  if (missingFromSkill.length || extraInSkill.length) {
+    failures.push(`SKILL.md allowed-tools out of sync (server has ${TOOLS.length}, SKILL.md has ${skillTools.length}):`);
+    if (missingFromSkill.length) failures.push(`  missing from SKILL.md: ${missingFromSkill.join(', ')}`);
+    if (extraInSkill.length)     failures.push(`  extra in SKILL.md (not registered): ${extraInSkill.join(', ')}`);
+  }
+}
+
+if (failures.length) {
+  for (const f of failures) console.error(f);
   process.exit(1);
 }
-console.log(`OK: ${TOOLS.length} tools`);
+console.log(`OK: ${TOOLS.length} tools (README badge + SKILL.md allowed-tools both match)`);

package/scripts/decode-feishu-protobuf.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+'use strict';
+// Decode a captured Feishu protobuf payload against proto/lark.proto.
+//
+// Usage:
+//   node scripts/decode-feishu-protobuf.js Packet            < /path/to/payload.bin
+//   echo "0a..." | node scripts/decode-feishu-protobuf.js Packet --hex
+//   node scripts/decode-feishu-protobuf.js Packet --b64 'CgRwYWNr...'
+//
+// Output:
+//   - Decoded JSON of the named message
+//   - "Unknown fields detected" section listing tag numbers + wire types we
+//     don't have in the proto (these are what we need to add).
+
+const path = require('path');
+const protobuf = require('protobufjs');
+
+async function main() {
+  const args = process.argv.slice(2);
+  const messageName = args[0];
+  if (!messageName) {
+    console.error('Usage: node scripts/decode-feishu-protobuf.js <MessageName> [--hex | --b64 <data>]');
+    process.exit(2);
+  }
+  const flagIdx = args.indexOf('--hex');
+  const b64Idx = args.indexOf('--b64');
+
+  let buf;
+  if (b64Idx !== -1) {
+    buf = Buffer.from(args[b64Idx + 1], 'base64');
+  } else if (flagIdx !== -1) {
+    const hex = await readStdin();
+    buf = Buffer.from(hex.replace(/\s+/g, ''), 'hex');
+  } else {
+    buf = await readStdinBuffer();
+  }
+
+  const proto = await protobuf.load(path.join(__dirname, '..', 'proto', 'lark.proto'));
+  const T = proto.lookupType(messageName);
+  const decoded = T.decode(buf);
+  const obj = T.toObject(decoded, { defaults: false, bytes: String });
+  // Walk the buffer to find unknown field tags.
+  const unknown = scanUnknownFields(buf, T);
+  console.log(JSON.stringify(obj, _dumpBytes, 2));
+  if (unknown.length) {
+    console.log('\n--- Unknown fields detected ---');
+    for (const u of unknown) console.log(`  field ${u.tag} (wire type ${u.wireType}, ${u.length} bytes): ${u.preview}`);
+    console.log('\nFor each unknown tag, add the field to proto/lark.proto and re-run to see the decoded shape.');
+  } else {
+    console.log('\n--- All fields known ---');
+  }
+}
+
+function _dumpBytes(_, v) {
+  if (Buffer.isBuffer(v)) return `<${v.length} bytes 0x${v.slice(0, 16).toString('hex')}${v.length > 16 ? '…' : ''}>`;
+  return v;
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    const chunks = [];
+    process.stdin.on('data', (c) => chunks.push(c));
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+  });
+}
+
+function readStdinBuffer() {
+  return new Promise((resolve) => {
+    const chunks = [];
+    process.stdin.on('data', (c) => chunks.push(c));
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks)));
+  });
+}
+
+// Walks raw protobuf bytes, decoding tag headers, and reports tags whose
+// number+wireType is not present in the schema. Matches protobufjs's reader
+// state machine but operates entry-point-only (no recursion into subtrees).
+function scanUnknownFields(buf, type) {
+  const known = new Set(type.fieldsArray.map(f => f.id));
+  const reader = protobuf.Reader.create(buf);
+  const out = [];
+  while (reader.pos < reader.len) {
+    const tagInt = reader.uint32();
+    const tag = tagInt >>> 3;
+    const wireType = tagInt & 7;
+    const start = reader.pos;
+    let value;
+    try {
+      value = readValueByWireType(reader, wireType);
+    } catch (e) {
+      out.push({ tag, wireType, length: 0, preview: `decode error: ${e.message}` });
+      break;
+    }
+    if (!known.has(tag)) {
+      const len = reader.pos - start;
+      let preview;
+      if (Buffer.isBuffer(value)) preview = `0x${value.slice(0, 24).toString('hex')}${value.length > 24 ? '…' : ''}`;
+      else preview = String(value).slice(0, 80);
+      out.push({ tag, wireType, length: len, preview });
+    }
+  }
+  return out;
+}
+
+function readValueByWireType(reader, wireType) {
+  switch (wireType) {
+    case 0: return reader.uint64();        // varint
+    case 1: return reader.fixed64();       // 64-bit
+    case 2: return Buffer.from(reader.bytes()); // length-delimited
+    case 5: return reader.fixed32();       // 32-bit
+    default: reader.skipType(wireType); return null;
+  }
+}
+
+main().catch(e => { console.error('Error:', e.message); process.exit(1); });

package/scripts/sync-server-json.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+'use strict';
+// Regenerates server.json so it never drifts from package.json + src/server.js.
+// Reads:
+//   - package.json: version, description (truncated to ~220 chars for display)
+//   - src/server.js TOOLS: tool list (name + description from inputSchema.description)
+// Preserves:
+//   - display_name, icon, repository, license, categories, tags,
+//     installations, environment_variables (these don't drift, edited by hand)
+// CI gate (validate.yml) re-runs this and diffs — drift = build fail.
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const SERVER_JSON = path.join(ROOT, 'server.json');
+const PKG = require(path.join(ROOT, 'package.json'));
+const { TOOLS } = require(path.join(ROOT, 'src', 'server'));
+
+function deriveToolEntry(t) {
+  // Strip the "[Plugin]"/"[Cookie]"/etc category prefix from descriptions for compactness.
+  const desc = (t.description || '').replace(/^\[[^\]]+\]\s*/, '');
+  return { name: t.name, description: desc.split('\n')[0].slice(0, 200) };
+}
+
+const existing = JSON.parse(fs.readFileSync(SERVER_JSON, 'utf8'));
+
+// Truncate package.json description for the marketplace display field.
+// The package.json one is intentionally long for npm searches; server.json
+// trims it for cleaner cards.
+const shortDesc = PKG.description.replace(/\s+/g, ' ').slice(0, 220);
+
+const next = {
+  name: PKG.name,
+  display_name: existing.display_name || 'Feishu User Plugin for Claude Code',
+  description: shortDesc,
+  version: PKG.version,
+  icon: existing.icon || 'https://www.feishu.cn/favicon.ico',
+  repository: existing.repository || { type: 'git', url: PKG.repository?.url || '' },
+  license: existing.license || PKG.license || 'MIT',
+  categories: existing.categories || ['communication', 'messaging', 'productivity'],
+  tags: existing.tags || ['feishu', 'lark', 'im', 'messaging', 'docs', 'bitable', 'wiki', 'protobuf', 'plugin', 'claude-code'],
+  tools: TOOLS.map(deriveToolEntry),
+  installations: existing.installations || {
+    'claude-code': { type: 'stdio', command: 'npx', args: ['-y', 'feishu-user-plugin'] },
+  },
+  environment_variables: existing.environment_variables || [
+    { name: 'LARK_COOKIE',             description: 'Feishu web login cookie string (required for user identity messaging)', required: true },
+    { name: 'LARK_APP_ID',             description: 'Feishu Open Platform App ID (required for official API)',                required: true },
+    { name: 'LARK_APP_SECRET',         description: 'Feishu Open Platform App Secret (required for official API)',            required: true },
+    { name: 'LARK_USER_ACCESS_TOKEN',  description: 'OAuth user_access_token for P2P chat reading (run: npx feishu-user-plugin oauth)', required: true },
+    { name: 'LARK_USER_REFRESH_TOKEN', description: 'OAuth refresh_token for automatic UAT renewal (obtained via OAuth flow)', required: true },
+  ],
+};
+
+const cmd = process.argv[2] || 'write';
+const nextStr = JSON.stringify(next, null, 2) + '\n';
+
+if (cmd === 'check') {
+  const cur = fs.readFileSync(SERVER_JSON, 'utf8');
+  if (cur !== nextStr) {
+    console.error('ERROR: server.json is out of sync with package.json + src/server.js TOOLS.');
+    console.error('Fix: node scripts/sync-server-json.js');
+    process.exit(1);
+  }
+  console.log(`OK: server.json in sync (${TOOLS.length} tools, v${PKG.version})`);
+  process.exit(0);
+}
+
+fs.writeFileSync(SERVER_JSON, nextStr);
+console.log(`Regenerated server.json (${TOOLS.length} tools, v${PKG.version})`);

package/scripts/test-wiki-attach-fallback.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+'use strict';
+// Simulates wiki:wiki scope insufficient and verifies the upload fallback path
+// surfaces a clear error rather than burying the wiki failure under a generic
+// "uploaded to drive root, attach failed" silent miss.
+//
+// Approach: monkey-patch attachToWiki on the LarkOfficialClient prototype to
+// throw a 91403 (the production wiki "no permission" code), then call
+// upload_drive_file with wiki_space_id and check the response.
+
+const { readCredentials } = require('../src/auth/credentials');
+const creds = readCredentials();
+if (!creds.LARK_APP_ID || !creds.LARK_APP_SECRET || !creds.LARK_USER_ACCESS_TOKEN) {
+  console.error('Skipped: needs LARK_APP_ID / LARK_APP_SECRET / UAT (skip on CI).');
+  process.exit(77); // POSIX skip code
+}
+
+(async () => {
+  const { LarkOfficialClient } = require('../src/clients/official');
+  const client = new LarkOfficialClient(creds.LARK_APP_ID, creds.LARK_APP_SECRET);
+  client.loadUAT();
+
+  const original = client.attachToWiki?.bind(client);
+  if (!original) { console.error('attachToWiki not present — wiki domain may not be loaded.'); process.exit(2); }
+
+  client.attachToWiki = async function(...args) {
+    const err = new Error('attachToWiki failed (HTTP 403, code=91403): wiki scope not granted');
+    err.code = 91403;
+    throw err;
+  };
+
+  const tmpFile = '/tmp/feishu-test-attach-fallback.txt';
+  require('fs').writeFileSync(tmpFile, 'attach-fallback-test ' + Date.now());
+
+  // Need a real folder_token: this script is opportunistic — pass via env
+  // FEISHU_TEST_FOLDER_TOKEN. Skip cleanly otherwise.
+  const folderToken = process.env.FEISHU_TEST_FOLDER_TOKEN;
+  if (!folderToken) {
+    console.error('Skipped: set FEISHU_TEST_FOLDER_TOKEN env (a real Drive folder token you can write to) to exercise this fallback.');
+    require('fs').unlinkSync(tmpFile);
+    process.exit(77);
+  }
+
+  try {
+    const res = await client.uploadDriveFile({
+      file_path: tmpFile,
+      file_name: 'attach-fallback-test.txt',
+      folder_token: folderToken,
+      parent_type: 'explorer',
+      wiki_space_id: '0000000000000000', // bogus; attachToWiki monkey-patch throws 91403 either way
+    });
+    console.log('Result:', JSON.stringify(res, null, 2));
+    if (res?._wikiAttachWarning || res?.error || /91403|wiki/i.test(JSON.stringify(res))) {
+      console.log('PASS: upload surfaces the wiki attach failure');
+      process.exit(0);
+    }
+    console.log('FAIL: upload did not surface the wiki attach failure');
+    process.exit(1);
+  } catch (e) {
+    // The monkey-patched attachToWiki throws — uploadDriveFile may rethrow.
+    // That's also acceptable as long as the message preserves the wiki failure.
+    if (/91403|wiki/i.test(e.message)) {
+      console.log('PASS: upload surfaces the wiki attach failure via thrown error:', e.message);
+      process.exit(0);
+    }
+    console.error('FAIL: upload threw, but message does not mention wiki/91403:', e.message);
+    process.exit(1);
+  } finally {
+    try { require('fs').unlinkSync(tmpFile); } catch {}
+  }
+})().catch((e) => { console.error('Error:', e.message); process.exit(1); });