feishu-user-plugin 1.3.6 → 1.3.8

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.6",
-  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself (incl. batch_send and real @-mentions), read chats (auto-expanded merge_forward), manage docs (image + file blocks) / bitable (with attachment upload) / wiki / drive (file upload + wiki attach) / OKR / calendar / multi-profile. 81 tools + 9 skills, 3 auth layers. v1.3.6: upload completeness, sheets:spreadsheet scope, batch_send, multi-profile, send_card_as_user (bot-default).",
+  "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,77 @@ 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
+- **Upload completeness**: `uploadDocMedia` → `uploadMedia` accepting 8 `parent_type`s (docx / sheet / bitable × image / file + legacy doc_*). New `create_doc_block` modes for files (`file_path` / `file_token`, block_type 23, auto view-wrap). `update_doc_block` accepts `file_token` to swap existing file blocks. New `upload_drive_file` (`drive/v1/files/upload_all`; optional `wiki_space_id` auto-attaches via `move_docs_to_wiki`). New `upload_bitable_attachment` (`parent_type=bitable_image|bitable_file`).
+- **`batch_send` tool**: fan-out the same or different content to multiple targets in one call. Each target dispatches sequentially with anti-rate-limit throttling and reports per-target `ok` / `error`. Identity is the cookie user unless `target.via=bot`.
+- **Multi-profile support**: `list_profiles` / `switch_profile` tools + `LARK_PROFILES_JSON` env. Hot-swap credentials without restarting the MCP server; cached client instances rebuild against the new profile.
+- **`send_card_as_user` (bot-routed default)**: send Feishu interactive cards. v1.3.6 routes through the bot identity; the `as_user` suffix is reserved for v1.3.7's reverse-engineered cookie path. `via="user"` returns an explicit not-yet-implemented error.
+
+### Changed
+- OAuth scopes added: `drive:file:upload` (narrower scope for `drive/v1/files/upload_all`), `sheets:spreadsheet` (sheet image / file uploads). Existing users must re-run `npx feishu-user-plugin oauth` to pick them up.
+
+## [1.3.5] - 2026-04-24
+
+### Fixed
+- **Cross-process UAT refresh lock**: file lock at `~/.claude/feishu-uat-refresh.lock` (`O_CREAT|O_EXCL`, 30s stale detection) serializes UAT refresh across concurrent MCP processes. Inside the critical section, the lock holder re-reads `~/.claude.json` to see whether a peer already rotated the token; if so it adopts the fresh one. Closes the "Codex spawned 6 MCP servers, all raced to refresh" failure mode that was burning refresh tokens on 2026-04-23.
+- **`get_login_status` UAT health check**: now actually exercises the UAT (calls `listChatsAsUser({pageSize:1})`) instead of just checking presence. Surfaces "configured but 401" cases that previously stayed silent until the next real tool call.
+
+### Added
+- **Bot-fallback ⚠️ warning**: every write tool that silently fell back from UAT to bot identity (`create_doc` / `create_bitable` / `create_folder` / `create_doc_block` / etc.) now appends a `fallbackWarning` to the response so users see the ownership change immediately. Before, callers only learned days later when a teammate could read their "private" resource.
+- **Auto-expand `merge_forward`**: `read_messages` / `read_p2p_messages` walk a `merge_forward` placeholder into its child messages by default (`expand_merge_forward=false` to opt out). Children carry `parentMessageId` (use that, NOT the child id, when downloading their media). Text children get `urls[]` + `feishuDocs[]` extracted so agents can feed them straight into `read_doc` / WebFetch.
+- **`download_file` tool**: download a file attachment (`msg_type=file`). Returns base64 + mimeType + byte count; optional `save_path` writes to disk. Same parent-id rule for `merge_forward` children as `download_image`.
+
 ## [1.3.4] - 2026-04-22
 
 ### 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-81-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 -- 81 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
@@ -337,7 +338,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 }
 ```
 
-## Tools (81 total)
+## Tools (80 total)
 
 ### User Identity -- Messaging (10 tools, cookie auth)
 
@@ -349,8 +350,6 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 | `send_image_as_user` | Send image (requires `image_key` from `upload_image`) |
 | `send_file_as_user` | Send file (requires `file_key` from `upload_file`) |
 | `send_post_as_user` | Send rich text with title + formatted paragraphs |
-| `send_sticker_as_user` | Send sticker/emoji |
-| `send_audio_as_user` | Send audio message |
 | `batch_send` | Fan-out send to multiple targets in one call (text / image / file / post). v1.3.6 |
 | `send_card_as_user` | Send a Feishu interactive card. v1.3.6 default routes through bot identity; user-identity is reserved for v1.3.7. |
 
@@ -392,8 +391,8 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 | `add_members` | Add users to a group |
 | `remove_members` | Remove users from a group |
 | `upload_image` / `upload_file` | Upload image/file, returns key for sending |
-| `download_image` | Download a chat-message image (message_id + image_key) OR a docx image (image_token + optional doc_token). Returned as MCP image content. For merge_forward children, use the child's `parentMessageId`, not the child id. |
-| `download_file` | Download a file attachment (msg_type=file). Returns base64 + mimeType + byte count; optional `save_path` writes to disk. Same parent-id rule for merge_forward children. (v1.3.5) |
+| `download_message_resource` | v1.3.7 (C2.4): download a message-attached image or file. Args: `message_id`, `key`, `kind=image|file`, `save_path?`. **Required save_path when bytes > 2 MiB** (Anthropic 5 MB inline cap). Replaces v1.3.6 download_image (message mode) + download_file. |
+| `download_doc_image` | v1.3.7 (C2.4): download an image embedded in a docx (image_token + optional doc_token). Same 2 MiB cap. Replaces v1.3.6 download_image (docx mode). |
 
 ### Wiki, OKR, and Calendar (v1.3.4)
 
@@ -409,7 +408,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 
 All docx / bitable tools' `document_id` / `app_token` parameter also accepts a Wiki node token or a full Feishu URL — the plugin resolves it transparently.
 
-### Official API -- Documents (7 tools)
+### Official API -- Documents (5 tools)
 
 | Tool | Description |
 |------|-------------|
@@ -417,67 +416,86 @@ All docx / bitable tools' `document_id` / `app_token` parameter also accepts a W
 | `read_doc` | Read raw text content |
 | `get_doc_blocks` | Get structured block tree |
 | `create_doc` | Create a new document |
-| `create_doc_block` | Insert content blocks: generic `children`, `image_path` / `image_token` (image block), `file_path` / `file_token` (file attachment block, v1.3.6) |
-| `update_doc_block` | Update a specific block: generic `update_body`, `image_token`, or `file_token` (v1.3.6) |
-| `delete_doc_blocks` | Delete a range of blocks |
+| `manage_doc_block` | Insert / update / delete blocks (`action=create|update|delete`). Supports generic `children`, image (`image_path`/`image_token`), and file (`file_path`/`file_token`) shortcuts. v1.3.7 consolidates the v1.3.6 trio create_doc_block / update_doc_block / delete_doc_blocks. |
 
-### Official API -- Bitable (18 tools)
+### Official API -- Bitable (6 tools, v1.3.7 consolidation)
 
-| Tool | Description |
-|------|-------------|
-| `create_bitable` | Create a new Bitable app |
-| `list_bitable_tables` / `create_bitable_table` / `delete_bitable_table` | Table management |
-| `list_bitable_fields` / `create_bitable_field` / `update_bitable_field` / `delete_bitable_field` | Field management |
-| `list_bitable_views` | List views |
-| `search_bitable_records` / `get_bitable_record` | Query records |
-| `create_bitable_record` / `update_bitable_record` / `delete_bitable_record` | Single record CRUD |
-| `batch_create_bitable_records` / `batch_update_bitable_records` / `batch_delete_bitable_records` | Batch operations (max 500/call) |
-| `upload_bitable_attachment` | Upload a file into a Bitable Attachment-type field. Returns `file_token` to write into the field as `[{file_token}]`. v1.3.6 |
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `manage_bitable_app` | create / copy / get_meta | App-level operations (v1.3.7 consolidates create_bitable / copy_bitable / get_bitable_meta) |
+| `manage_bitable_table` | list / create / update / delete | Table CRUD (rename via update) |
+| `manage_bitable_field` | list / create / update / delete | Field (column) management. `type` required for both create AND update. |
+| `manage_bitable_view` | list / create / delete | Views (grid, kanban, gallery, form, gantt, calendar) |
+| `manage_bitable_record` | search / get / create / update / delete | Record CRUD. create/update/delete accept arrays — single record or up to 500/call. |
+| `upload_bitable_attachment` | — | Upload a file into a Bitable Attachment-type field. Returns `file_token` to write into the field as `[{file_token}]`. v1.3.6 |
 
-### Official API -- Calendar (5 tools)
+### Official API -- Calendar (8 tools, write tools v1.3.7)
 
 | Tool | Description |
 |------|-------------|
 | `list_calendars` | List accessible calendars |
-| `create_calendar_event` | Create a calendar event |
 | `list_calendar_events` | List events in a calendar |
-| `delete_calendar_event` | Delete an event |
-| `get_freebusy` | Check user availability |
+| `get_calendar_event` | Full event details |
+| `create_calendar_event` | Create an event (v1.3.7). Requires `calendar:calendar.event:write`. |
+| `update_calendar_event` | Patch event fields (v1.3.7) |
+| `delete_calendar_event` | Delete an event, optionally dissolve its meeting chat (v1.3.7) |
+| `respond_calendar_event` | RSVP as accept / decline / tentative (v1.3.7) |
+| `get_freebusy` | Freebusy lookup for `user_ids` in a time range (v1.3.7) |
 
-### Official API -- Tasks (5 tools)
+### Official API -- Tasks v2 (7 tools, v1.3.7 new domain)
+
+Identifier is `task_guid` (not v1's numeric `task_id`). Requires `task:task` scope.
 
 | Tool | Description |
 |------|-------------|
-| `create_task` | Create a task |
-| `get_task` | Get task details |
-| `list_tasks` | List tasks |
-| `update_task` | Update a task |
-| `complete_task` | Mark task as complete |
+| `list_tasks` | List the current user's tasks (filter by completed / type) |
+| `get_task` | Full task detail |
+| `create_task` | Create a task (summary required; due/members optional) |
+| `update_task` | Patch fields. **`update_fields` is required** — Feishu only updates the listed keys. |
+| `complete_task` | Mark complete (or uncomplete with `completed=false`) |
+| `delete_task` | Permanent delete |
+| `manage_task_members` | `action=add|remove`, members `[{id, role:"assignee"|"follower"}]` |
 
-### Official API -- Drive (6 tools)
+### Official API -- Drive (4 tools)
 
 | Tool | Description |
 |------|-------------|
 | `list_files` | List files in a folder |
 | `create_folder` | Create a new folder |
-| `copy_file` | Copy a file |
-| `move_file` | Move a file |
-| `delete_file` | Delete a file/folder |
+| `manage_drive_file` | Copy / move / delete a Drive file (`action=copy|move|delete`, `type` required). v1.3.7 consolidates v1.3.6 copy_file / move_file / delete_file. |
 | `upload_drive_file` | Upload a local file into a Drive folder (`drive/v1/files/upload_all`). Optional `wiki_space_id` attaches the upload as a Wiki node atomically. v1.3.6 |
 
-### Official API -- Wiki & Contacts (4 tools)
+### Official API -- Wiki (8 tools)
 
 | Tool | Description |
 |------|-------------|
-| `list_wiki_spaces` / `search_wiki` / `list_wiki_nodes` | Wiki spaces, search, browse |
-| `find_user` | Find user by email or mobile number |
+| `list_wiki_spaces` / `search_wiki` / `list_wiki_nodes` / `get_wiki_node` | Wiki spaces, search, browse + resolve a wiki node to underlying obj_token |
+| `create_wiki_node` | Create a new wiki node (doc/sheet/bitable/mindnote/file/docx/slides) inside a space |
+| `update_wiki_node` | Rename a wiki node (title only — content edits via docx/bitable tools) |
+| `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)
 
@@ -537,7 +555,7 @@ feishu-user-plugin/
 │       ├── SKILL.md         # Main skill definition (trigger, tools, auth)
 │       └── references/      # 8 skill reference docs + CLAUDE.md
 ├── src/
-│   ├── index.js             # MCP server entry point (81 tools)
+│   ├── index.js             # MCP server entry point (78 tools)
 │   ├── client.js            # User identity client (Protobuf gateway)
 │   ├── official.js          # Official API client (REST, UAT)
 │   ├── utils.js             # ID generators, cookie parser
@@ -566,6 +584,19 @@ Issues and PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development s
 
 If Feishu updates their protocol and something breaks, please [open an issue](https://github.com/EthanQC/feishu-user-plugin/issues/new?template=bug_report.md) with the error details.
 
+### Automated sync hooks
+
+This repo uses husky to enforce several invariants on every commit:
+
+- **CLAUDE.md sync** — staging `CLAUDE.md` automatically regenerates `AGENTS.md` (identical body, different first line) and `skills/feishu-user-plugin/references/CLAUDE.md` (verbatim copy). Both are re-staged in the same commit.
+- **Version triangle** — if `package.json`, `.claude-plugin/plugin.json`, or `skills/feishu-user-plugin/SKILL.md` are staged, all three `version` fields must agree or the commit is rejected.
+- **Tool-count badge** — if `src/server.js` or any file under `src/tools/` is staged, the `N tools` badge in `README.md` must match the actual `TOOLS.length` exported by `src/server.js`.
+- **Smoke test** — any change under `src/` triggers `npm run smoke` to catch schema regressions before commit.
+
+CI (`.github/workflows/validate.yml`) runs the same checks on every PR to `main`, so bypassing the local hook still gets caught.
+
+On the maintainer's machine, a post-merge hook (`scripts/sync-team-skills.sh`) auto-opens a sync PR in the `~/team-skills` repo after every merge to main. The hook silently skips if `~/team-skills` is absent.
+
 ## License
 
 [MIT](LICENSE)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.6",
-  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging (with merge_forward expansion + batch_send), docs (image + file blocks read/write), bitable (with attachment upload), wiki, drive (file upload + wiki attach), OKR, calendar, multi-profile. 81 tools + 9 skills, 3 auth layers. v1.3.6: upload completeness, sheets:spreadsheet scope, batch_send, multi-profile, send_card_as_user (bot-default).",
+  "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"
@@ -11,7 +11,11 @@
     "test": "node src/test-all.js",
     "test:quick": "node src/test-send.js",
     "oauth": "node src/oauth.js",
-    "prepublishOnly": "node scripts/confirm-version.js"
+    "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/sync-server-json.js check && node scripts/check-docs-sync.js && node scripts/check-changelog.js && node scripts/confirm-version.js",
+    "prepare": "husky"
   },
   "keywords": [
     "feishu",
@@ -55,5 +59,8 @@
     "@modelcontextprotocol/sdk": "^1.12.1",
     "dotenv": "^16.4.7",
     "protobufjs": "^7.4.0"
+  },
+  "devDependencies": {
+    "husky": "^9.1.7"
   }
 }

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+'use strict';
+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');
+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 (README badge + SKILL.md allowed-tools both match)`);

package/scripts/check-version.js

@@ -0,0 +1,40 @@
+#!/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: .claude-plugin/plugin.json
+const plugin = JSON.parse(fs.readFileSync(path.join(ROOT, '.claude-plugin', 'plugin.json'), 'utf8'));
+const pluginVersion = plugin.version;
+
+// Source 3: skills/feishu-user-plugin/SKILL.md frontmatter version line
+const skillMd = fs.readFileSync(path.join(ROOT, 'skills', 'feishu-user-plugin', 'SKILL.md'), 'utf8');
+const skillMatch = skillMd.match(/^version:\s*["']?([^"'\s]+)["']?/m);
+if (!skillMatch) {
+  console.error('ERROR: Could not find version in skills/feishu-user-plugin/SKILL.md frontmatter');
+  process.exit(1);
+}
+const skillVersion = skillMatch[1];
+
+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' },
+];
+
+const versions = sources.map((s) => s.version);
+const allEqual = versions.every((v) => v === versions[0]);
+
+if (!allEqual) {
+  console.error('ERROR: Version triangle mismatch!');
+  sources.forEach((s) => console.error(`  ${s.path}: ${s.version}`));
+  process.exit(1);
+}
+
+console.log(`OK: version ${pkgVersion}`);