feishu-user-plugin 1.3.8 → 1.3.9

package/.claude-plugin/plugin.json

@@ -1,9 +1,19 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.8",
+  "version": "1.3.9",
   "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"
   },
-  "keywords": ["feishu", "lark", "claude-code", "plugin", "messaging", "im", "document", "bitable", "protobuf"]
+  "keywords": [
+    "feishu",
+    "lark",
+    "claude-code",
+    "plugin",
+    "messaging",
+    "im",
+    "document",
+    "bitable",
+    "protobuf"
+  ]
 }

package/CHANGELOG.md

@@ -4,27 +4,65 @@ 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.9] - 2026-05-08
+
+D 系列首项 ship：新增 `read_doc_markdown` 工具，用 `feishu-docx` 把 docx blocks 转换为 markdown 字符串输出，替代 `get_doc_blocks` 的结构化 JSON，给 RAG / digest / 摘要类调用省 ~60% token（实测 216 KB JSON vs 90 KB markdown）。A 系列主线 ship：WS 机器级 SSOT + active profile 跨进程同步 + setup CLI 4 行决策矩阵 + per-profile events 字段。工具数 83 → 84。
+
+### Added
+- **`manage_ws_status(action=info|reconnect|claim|rotate|reconfig)` (A.1)**：5-action 工具，`info` 给 owner / WS / log / cursor / config 状态 dump；`reconnect` / `rotate` / `reconfig` 是 owner-only；`claim` 接管 stale lock，`force=true` 强夺活跃 owner。`rotate` 触发 `events.jsonl` → `events.jsonl.old` 轮转。`reconfig` 重读 `credentials.json::profiles[active].events` 并重新注册事件类型，无需重启。
+- **WS 机器级 SSOT (A.1)**：单 owner 进程持 `~/.feishu-user-plugin/ws-owner.lock`（O_CREAT|O_EXCL，30 s stale），事件写 `events.jsonl`（append-only，10 MB soft / 20 MB hard cap，超限 rotate 成 `.old`），全局共享 `events.cursor.json` 保护以 cursor-specific lock 避免并发 drain 重读。多 harness 同事件不再重复；owner 死亡 / 锁过期后下一个 MCP 进程自动接管，event log 不丢。
+- **Active profile 跨进程同步 (A.2)**：dispatcher 入口 stat `credentials.json` mtime；变化时重新读 `active`，与 in-memory `currentProfile` 不同即触发 `setActiveProfile`（invalidate `userClient` / `officialClient` 缓存）。成本 ~10μs/call（macOS stat）。`FEISHU_PLUGIN_PROFILE` env 退化为 bootstrap-only；`credentials.json::active` 为唯一跨进程权威来源。
+- **setup CLI 4 行决策矩阵 (A.3)**：非交互模式自动判断 `fresh` / `auto-migrate` / `preserve` / `update` 四种路径；新增 `--force` flag 强制重写 + `--profile <name>` 指定目标 profile。`credentials.json` 已存在时默认 `--pointer-only`；首次安装自动 migrate，harness env 只写 `FEISHU_PLUGIN_PROFILE=default`，消除多 harness token diverge。
+- **per-profile events 字段 (A.4)**：`credentials.json::profiles[*].events` 可选数组，缺省 `["im.message.receive_v1"]`；支持 `approval.instance.created_v4` / `calendar.calendar.event.changed_v4` 等。编辑后调 `manage_ws_status(action=reconfig)` 立即生效，不需重启。`FEISHU_PLUGIN_EXTRA_EVENTS` env 仅在首次 bootstrap 时写入，不覆盖已有字段。
+- **`read_doc_markdown(document_id)` (D)**：返回 markdown 字符串而非结构化 JSON，省 ~60% token；依赖 `feishu-docx@^0.7.0`，后处理器 `_normaliseEmbeds` 位于 `src/tools/docs.js`。嵌入图片 / 文件以 `feishu://image_token/<TOKEN>` / `feishu://file_token/<TOKEN>` 占位符形式保留，配合 `download_doc_image` 取二进制内容。`document_id` 同样接受原生 token / wiki node token / 飞书 URL，分辨率逻辑与其它 doc 工具相同。
+
+### Fixed
+- **`send_image_as_user` 不再报 HTTP 400 (B.1)**：v1.3.9 通过暴力探测 cookie protobuf gateway 拿到 IMAGE 最小有效字段集 — `Content.imageKey` (字段 2) + `Content.thumbnailKey` (字段 10) 即可发送成功；宽 / 高 / mime / size 全部可选。`proto/lark.proto` 加了 `imageWidth=4 / imageHeight=5 / mimeType=8 / fileSize=9 / thumbnailKey=10` 五个字段；`sendImage()` 默认 thumbnailKey = imageKey（飞书在缩略图未单独上传时接受同 key）。`scripts/explore-image-minimize.js` 留作未来字段验证起点。
+
+### Removed
+- **`send_card_as_user(via="user")` 路径删除 (B.4)** — v1.3.9 通过 brute-force 确认 cookie protobuf gateway 的 `cmd=5 type=14 (CARD)` 路径在服务端 auth 层就被拒绝（任何字段组合都返回同一句 `richText and card type need for card message`，验证发生在 Content 解析之前）。结论是用户身份发卡片在 Feishu cookie auth tier 被服务端禁用，brute-force 不可解。`send_card_as_user` 工具保留，但 `via` 参数和 `via="user"` 代码分支彻底移除，工具固定走 bot (Official API)。`as_user` 后缀作历史命名保留，避免破坏调用方。`scripts/explore-card-protobuf.js` 留作参考，下次会话不需要重复 brute-force。
+
+### Test
+- **`switch_profile` 多 profile e2e (F.1)**：验证原子 credentials.json 更新 + 进程内 cache 失效。位于 `src/test-switch-profile.js`，CI-friendly（dummy 凭证不联网）。
+
+### Test scenarios
+- 调用 `read_doc_markdown(<docx_token>)`，确认返回 markdown 字符串而非 JSON；HTML 标签如 `<b>` `<em>` 已被转成 `**` `*` 等价物
+- 包含 mention 链接 `[doc](wikcnXXX)` 的文档应保留原样，不被错判为 file token 占位符
+- 启动 MCP 看 stderr 是否出现 `WS connected (profile=default)`；`~/.feishu-user-plugin/ws-owner.lock` 应存在
+- 多 MCP 进程同时跑 → 仅一个看 `WS connected`，其它静默 → `manage_ws_status(action=info)` 看 `is_owner` 字段
+
 ## [1.3.8] - 2026-05-05
 
+本次更新主线是多 profile 自动切换和 WebSocket 实时事件两块新能力，同时把 v1.3.7 推迟的 auth 模块拆分和凭证 pointer-only 模式补齐，并加固 CI 闸门（server.json 自动重生、SKILL.md allowed-tools 与 TOOLS 1:1 校验、CHANGELOG section 校验、文档三方同步校验）。工具数 80 → 82。
+
 ### 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.
+- **多 profile 自动切换 (B)**：当 `~/.feishu-user-plugin/credentials.json` 配了 ≥2 profile，读取类工具（`read_*` / `list_*` / `get_*` / `search_*` / `download_*` 加 `manage_bitable_*` 的 read-action 变体）遇到 91403 / 1254301 / 1254000 / 99991672 / HTTP 403 时自动尝试其它 profile 重试。命中后 resourceKey → profile 写入 `profileHints`，下次直接走对的账号。写操作绝不自动切；显式 `via_profile="alt"` 单次锁定，`via_profile="auto"` 在写操作上手动允许。
+- **新工具 manage_profile_hints**：`action=list|set|clear, resource_key?, profile?`，检查或编辑 profile 命中缓存。
+- **WebSocket 实时事件 (C)**：MCP server 启动时后台连飞书 WSClient（仅 feishu.cn，Lark 国际版不支持），事件入 1000 容量 FIFO buffer。新工具 `get_new_events(event_type?, event_types?, chat_id?, since_seconds?, max_events=50, peek=false)` 拉取，默认 drain 语义；当前注册 `im.message.receive_v1`。
+- **Cookie protobuf 工具链 (A.0)**：`scripts/decode-feishu-protobuf.js` 解码 + 报告未知字段；`scripts/capture-feishu-protobuf.js` 抓包 recipe；`docs/COOKIE-PROTOBUF-CAPTURES.md` 流程文档。下版本用这套真做 send_image / audio / sticker / card / search_messages 反向。
+- **`FEISHU_PLUGIN_PROFILE` 启动 env (E.1)**：让 harness 各自指向不同 profile，启动时校验存在（拼错直接 exit 2，不静默 fall through）。
+- **`setup --pointer-only` 模式 (E.2)**：harness env 只写 `FEISHU_PLUGIN_PROFILE=default`，真凭证全部留 `credentials.json`，消除 UAT 刷新后两端 diverge。
 
 ### 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`.
+- **`src/auth/uat.js` + `src/auth/cookie.js` 拆分 (D.1, D.2)**：从 `clients/official/base.js` 和 `clients/user.js` 拆出来，client 实例上变 1-line delegate；状态字段保留在客户端实例。base.js 减约 200 行，关掉 v1.3.7 Phase B 的拆分欠账。
+- **启动诊断更主动 (E.3)**：credentials.json + 旧 LARK_* env 双存在打 NOTE 提示 env 已被忽略；env-only 用户打 TIP 建议运行 `npx feishu-user-plugin migrate --confirm`。
 
 ### 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`.
+- **server.json 长期 drift**：长期停在 v1.2.0 / 33 tools 且包含已删工具。新增 `scripts/sync-server-json.js` 从 package.json + TOOLS 自动重生，prepublishOnly 与 CI 验证 drift；本版同步到 v1.3.8 / 82 tools。
+- **`check-tool-count.js` 扩展**：除 README badge 之外同时校验 `SKILL.md::allowed-tools` 与 TOOLS 一致，避免 SKILL.md 单独 drift 漏掉。
+- **G.1 wiki-attach 兜底回归脚本**：`scripts/test-wiki-attach-fallback.js` 把 `attachToWiki` monkey-patch 成抛 91403，验证 `upload_drive_file` 把失败透出来而不是默默上传到 drive root。POSIX skip 77 缺凭证时跳过。
 
 ### 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.
+- Cookie protobuf 实际抓包：`send_image_as_user` / `send_audio_as_user` / `send_sticker_as_user` / `send_card_as_user` 真用户身份 / `search_messages`。工具链已 ship（`scripts/decode-feishu-protobuf.js` 等），抓包 session 留下版本一并做。
+- 机器级 SSOT 完整化：WebSocket 单 owner + 共享 events.jsonl + 单一 drain 游标；active profile 跨进程 stat 同步；setup 非交互模式自动 pointer-only。
+- 本地 md → 飞书 wiki 同步、`read_doc_markdown` 工具、`src/config/` 目录化拆分。
+- `switch_profile` 多 profile e2e（mock 第二 profile 测 setActiveProfile cache 失效路径）。
+- 测试群 `oc_daaa6a50f2a97dc668aaf79ae4dc6e4e` 解散（卡 group owner 权限转让）。
+
+### Test scenarios
+- 调用 `read_doc` 命中外部租户文档时观察 stderr 出现 `profile-router: default → alt on read_doc (code=91403)`，结果回到 alt profile 的内容
+- 用 `send_to_user` 给自己发条文本后调 `get_new_events`，看到对应的 `im.message.receive_v1` 事件
+- 跑 `npx feishu-user-plugin migrate --confirm` 后重启 MCP，启动 stderr 显示 `Auth: ... source: credentials.json profile=default`，所有工具调用照常
 
 ## [1.3.7] - 2026-05-04
 

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-82-orange.svg)](#tools)
+[![Tools](https://img.shields.io/badge/Tools-84-orange.svg)](#tools)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**All-in-one Feishu/Lark MCP Server -- 82 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, OKR, and more.**
+**All-in-one Feishu/Lark MCP Server -- 84 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,7 +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.
+- **Real-time events** (v1.3.9) -- Machine-level WS: one owner process writes to `~/.feishu-user-plugin/events.jsonl`, all harnesses drain from a shared cursor — every event delivered exactly once across all MCP processes. `manage_ws_status` to diagnose/control. WS auto-starts on boot.
 - **Multi-platform** -- Claude Code, Cursor, Windsurf, VS Code, OpenClaw.
 
 ## Why This Exists
@@ -351,7 +351,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 | `send_file_as_user` | Send file (requires `file_key` from `upload_file`) |
 | `send_post_as_user` | Send rich text with title + formatted paragraphs |
 | `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. |
+| `send_card_as_user` | Send a Feishu interactive card via bot identity (Official API). User-identity card sending is server-side disabled at the Feishu cookie auth tier — confirmed in v1.3.9. |
 
 ### User Identity -- Contacts & Info (5 tools, cookie auth)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "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.",
+  "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.",
   "main": "src/index.js",
   "bin": {
     "feishu-user-plugin": "src/cli.js"
@@ -55,12 +55,16 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@larksuiteoapi/node-sdk": "^1.59.0",
-    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@larksuiteoapi/node-sdk": "^1.63.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^16.4.7",
-    "protobufjs": "^7.4.0"
+    "feishu-docx": "^0.7.0",
+    "protobufjs": "^7.5.6"
   },
   "devDependencies": {
     "husky": "^9.1.7"
+  },
+  "overrides": {
+    "axios": "^1.16.0"
   }
 }

package/proto/lark.proto

@@ -123,8 +123,18 @@ message Content {
   optional string text = 1;
   optional string imageKey = 2;
   optional string title = 3;
+  // Image metadata fields (v1.3.9 — reverse-engineered via brute-force probe;
+  // see scripts/explore-image-minimize.js). Required for IMAGE messages on the
+  // cookie-protobuf path: imageKey + thumbnailKey(10) is the minimum the
+  // gateway accepts. width(4) / height(5) / mimeType(8) / fileSize(9) are
+  // optional but commonly present in the real wire format.
+  optional int32 imageWidth = 4;
+  optional int32 imageHeight = 5;
   optional string fileKey = 6;
   optional string audioKey = 7;
+  optional string mimeType = 8;
+  optional int64 fileSize = 9;
+  optional string thumbnailKey = 10;
   optional string fileName = 11;
   optional RichText richText = 14;
   optional string stickerSetId = 24;

package/scripts/explore-card-protobuf.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+'use strict';
+// CARD (type=14) protobuf field exploration. Probe field numbers + types.
+
+const fs = require('fs');
+const path = require('path');
+const protobuf = require('protobufjs');
+
+const claudeCfg = JSON.parse(fs.readFileSync(path.join(require('os').homedir(), '.claude.json'), 'utf8'));
+const env = claudeCfg.mcpServers?.['feishu-user-plugin']?.env || {};
+process.env.LARK_COOKIE = env.LARK_COOKIE;
+process.env.LARK_APP_ID = env.LARK_APP_ID;
+process.env.LARK_APP_SECRET = env.LARK_APP_SECRET;
+
+const PLUGIN_ROOT = path.join(__dirname, '..');
+const { LarkUserClient } = require(path.join(PLUGIN_ROOT, 'src/clients/user'));
+const { generateCid, generateRequestId } = require(path.join(PLUGIN_ROOT, 'src/utils'));
+
+const TEST_GROUP_NAME = '飞书plugin测试群';
+
+const errProto = protobuf.parse(`
+  syntax = "proto3";
+  message ErrorResponse {
+    optional string message = 1;
+    optional int32 code = 2;
+    optional int32 subCode = 3;
+    optional string detail = 4;
+    optional string trace = 5;
+    optional string requestId = 6;
+  }
+`).root;
+const ErrorResponse = errProto.lookupType('ErrorResponse');
+
+async function fetchProto(url, opts) {
+  const u = new URL(url);
+  return new Promise((resolve, reject) => {
+    const req = require('node:https').request({
+      hostname: u.hostname,
+      port: u.port || 443,
+      path: u.pathname + u.search,
+      method: opts.method || 'GET',
+      headers: opts.headers || {},
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => resolve({ status: res.statusCode, body: Buffer.concat(chunks) }));
+    });
+    req.on('error', reject);
+    if (opts.body) req.write(opts.body);
+    req.end();
+  });
+}
+
+function encodeVarint(n) {
+  const bytes = [];
+  while (n >= 0x80) { bytes.push((n & 0x7f) | 0x80); n = Math.floor(n / 128); }
+  bytes.push(n & 0x7f);
+  return Buffer.from(bytes);
+}
+
+function encodeWireField(num, type, val) {
+  if (type === 'varint') return Buffer.concat([Buffer.from([(num << 3) | 0]), encodeVarint(val)]);
+  if (type === 'string' || type === 'bytes') {
+    const v = type === 'string' ? Buffer.from(val, 'utf8') : val;
+    const tag = (num << 3) | 2;
+    if (num < 16) return Buffer.concat([Buffer.from([tag]), encodeVarint(v.length), v]);
+    // For field numbers > 15, tag is multi-byte varint
+    return Buffer.concat([encodeVarint(tag), encodeVarint(v.length), v]);
+  }
+  throw new Error('unknown type');
+}
+
+async function trySendRaw(userClient, chatId, msgType, contentBytes, label) {
+  const proto = userClient.proto;
+  const PutMessageRequest = proto.lookupType('PutMessageRequest');
+  const Packet = proto.lookupType('Packet');
+
+  const restReq = PutMessageRequest.encode(PutMessageRequest.create({
+    type: msgType, chatId, cid: generateCid(), isNotified: true, version: 1,
+  })).finish();
+  const contentField = Buffer.concat([
+    Buffer.from([(2 << 3) | 2]),
+    encodeVarint(contentBytes.length),
+    contentBytes,
+  ]);
+  const reqBuf = Buffer.concat([contentField, restReq]);
+
+  const packetBuf = Packet.encode(Packet.create({
+    payloadType: 1,
+    cmd: 5,
+    cid: generateRequestId(),
+    payload: reqBuf,
+  })).finish();
+
+  const res = await fetchProto('https://internal-api-lark-api.feishu.cn/im/gateway/', {
+    method: 'POST',
+    headers: userClient._protoHeaders(5, '5.7.0'),
+    body: packetBuf,
+  });
+
+  let parsedErr = null;
+  try { parsedErr = ErrorResponse.toObject(ErrorResponse.decode(res.body)); } catch (_) {}
+
+  const status = res.status === 200 ? '✓ OK' : `✗ ${res.status}`;
+  const errMsg = parsedErr?.message?.slice(0, 120) || '';
+  console.log(`${status} [${label}] ${errMsg}`);
+  return { ok: res.status === 200, status: res.status, err: errMsg };
+}
+
+(async () => {
+  const userClient = new LarkUserClient(process.env.LARK_COOKIE);
+  await userClient.init();
+  const sr = await userClient.search(TEST_GROUP_NAME);
+  const chatId = sr.find(x => x.type === 'group' && x.title.includes(TEST_GROUP_NAME)).id;
+  console.log('chatId:', chatId);
+
+  const card = JSON.stringify({
+    config: { wide_screen_mode: true },
+    header: { title: { tag: 'plain_text', content: '[explore-card] please ignore' } },
+    elements: [{ tag: 'div', text: { tag: 'lark_md', content: 'Cookie protobuf test card' } }],
+  });
+  const cardBuf = Buffer.from(card, 'utf8');
+  console.log('card json size:', cardBuf.length);
+
+  console.log('\n=== Phase A: try type=14 with each unused field number ===');
+  // Known used: 1(text), 2(imageKey), 3(title), 6(fileKey), 7(audioKey), 11(fileName), 14(richText), 24(stickerSetId), 25(stickerId)
+  // Unused (potential card field): 4, 5, 8, 9, 10, 12, 13, 15, 16, 17, 18, 19, 20, 21, 22, 23
+  const candidates = [4, 5, 8, 9, 10, 12, 13, 15, 16, 17, 18, 19, 20, 21, 22, 23];
+  for (const fieldNum of candidates) {
+    // Try as string (JSON)
+    const ckS = encodeWireField(fieldNum, 'string', card);
+    const res = await trySendRaw(userClient, chatId, 14, ckS, `field ${fieldNum} string=cardJSON`);
+    if (res.ok) {
+      console.log(`\n🎯 SUCCESS at field ${fieldNum}!`);
+    }
+  }
+
+  console.log('\n=== Phase B: special — Content field 14 is richText. Try CARD via richText? ===');
+  // Skip — richText is for POST type. CARD is different.
+
+  console.log('\n=== Phase C: combos — maybe card needs type at multiple fields ===');
+  // Like image needed thumb. Try card at field 8 + 9 + 10 + 16 etc.
+  // Skip for now — Phase A may have answered.
+})().catch(e => { console.error('FATAL:', e.message); process.exit(1); });

package/scripts/explore-image-minimize.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+'use strict';
+// Minimize IMAGE Content fields. Start with known-working combo, drop one field
+// at a time and observe which omissions still pass.
+
+const fs = require('fs');
+const path = require('path');
+const protobuf = require('protobufjs');
+
+const claudeCfg = JSON.parse(fs.readFileSync(path.join(require('os').homedir(), '.claude.json'), 'utf8'));
+const env = claudeCfg.mcpServers?.['feishu-user-plugin']?.env || {};
+process.env.LARK_COOKIE = env.LARK_COOKIE;
+process.env.LARK_APP_ID = env.LARK_APP_ID;
+process.env.LARK_APP_SECRET = env.LARK_APP_SECRET;
+
+const PLUGIN_ROOT = path.join(__dirname, '..');
+const { LarkUserClient } = require(path.join(PLUGIN_ROOT, 'src/clients/user'));
+const { LarkOfficialClient } = require(path.join(PLUGIN_ROOT, 'src/clients/official'));
+const { generateCid, generateRequestId } = require(path.join(PLUGIN_ROOT, 'src/utils'));
+
+const TEST_IMAGE = path.join(PLUGIN_ROOT, '.playwright-mcp/captures/test-small.png');
+const TEST_GROUP_NAME = '飞书plugin测试群';
+
+const errProto = protobuf.parse(`
+  syntax = "proto3";
+  message ErrorResponse {
+    optional string message = 1;
+    optional int32 code = 2;
+    optional int32 subCode = 3;
+    optional string detail = 4;
+    optional string trace = 5;
+    optional string requestId = 6;
+  }
+`).root;
+const ErrorResponse = errProto.lookupType('ErrorResponse');
+
+async function fetchProto(url, opts) {
+  const u = new URL(url);
+  return new Promise((resolve, reject) => {
+    const req = require('node:https').request({
+      hostname: u.hostname,
+      port: u.port || 443,
+      path: u.pathname + u.search,
+      method: opts.method || 'GET',
+      headers: opts.headers || {},
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => resolve({ status: res.statusCode, body: Buffer.concat(chunks) }));
+    });
+    req.on('error', reject);
+    if (opts.body) req.write(opts.body);
+    req.end();
+  });
+}
+
+function encodeVarint(n) {
+  const bytes = [];
+  while (n >= 0x80) {
+    bytes.push((n & 0x7f) | 0x80);
+    n = Math.floor(n / 128);
+  }
+  bytes.push(n & 0x7f);
+  return Buffer.from(bytes);
+}
+
+function encodeWireField(num, type, val) {
+  if (type === 'varint') return Buffer.concat([Buffer.from([(num << 3) | 0]), encodeVarint(val)]);
+  if (type === 'string') {
+    const v = Buffer.from(val, 'utf8');
+    return Buffer.concat([Buffer.from([(num << 3) | 2]), encodeVarint(v.length), v]);
+  }
+  throw new Error('unknown type');
+}
+
+function buildContent(fields) {
+  return Buffer.concat(fields.map(([n, t, v]) => encodeWireField(n, t, v)));
+}
+
+async function trySendRaw(userClient, chatId, msgType, contentBytes, label) {
+  const proto = userClient.proto;
+  const PutMessageRequest = proto.lookupType('PutMessageRequest');
+  const Packet = proto.lookupType('Packet');
+
+  const restReq = PutMessageRequest.encode(PutMessageRequest.create({
+    type: msgType, chatId, cid: generateCid(), isNotified: true, version: 1,
+  })).finish();
+  const contentField = Buffer.concat([
+    Buffer.from([(2 << 3) | 2]),
+    encodeVarint(contentBytes.length),
+    contentBytes,
+  ]);
+  const reqBuf = Buffer.concat([contentField, restReq]);
+
+  const packetBuf = Packet.encode(Packet.create({
+    payloadType: 1,
+    cmd: 5,
+    cid: generateRequestId(),
+    payload: reqBuf,
+  })).finish();
+
+  const res = await fetchProto('https://internal-api-lark-api.feishu.cn/im/gateway/', {
+    method: 'POST',
+    headers: userClient._protoHeaders(5, '5.7.0'),
+    body: packetBuf,
+  });
+
+  let parsedErr = null;
+  try { parsedErr = ErrorResponse.toObject(ErrorResponse.decode(res.body)); } catch (_) {}
+
+  const status = res.status === 200 ? '✓ OK' : `✗ ${res.status}`;
+  const errMsg = parsedErr?.message?.slice(0, 100) || '';
+  console.log(`${status} [${label}] ${errMsg}`);
+  return { ok: res.status === 200, status: res.status, err: errMsg };
+}
+
+(async () => {
+  const oc = new LarkOfficialClient(process.env.LARK_APP_ID, process.env.LARK_APP_SECRET);
+  const r = await oc.uploadImage(TEST_IMAGE, 'message');
+  const imageKey = r.imageKey;
+  console.log('imageKey:', imageKey);
+
+  const userClient = new LarkUserClient(process.env.LARK_COOKIE);
+  await userClient.init();
+  const sr = await userClient.search(TEST_GROUP_NAME);
+  const chatId = sr.find(x => x.type === 'group' && x.title.includes(TEST_GROUP_NAME)).id;
+  console.log('chatId:', chatId);
+
+  // ALL fields baseline (known to work)
+  const allFields = [
+    [2, 'string', imageKey],     // imageKey
+    [4, 'varint', 50],           // ?
+    [5, 'varint', 50],           // ?
+    [8, 'string', 'image/png'],  // mime?
+    [9, 'varint', 141],          // size?
+    [10, 'string', imageKey],    // thumbnail?
+  ];
+
+  console.log('\n=== Verify baseline (all 6 fields) ===');
+  await trySendRaw(userClient, chatId, 5, buildContent(allFields), 'baseline all fields');
+
+  console.log('\n=== Drop each field individually ===');
+  // Field labels: imageKey is required; we test which of the OTHER 5 are required
+  const others = [4, 5, 8, 9, 10];
+  for (const dropField of others) {
+    const subset = allFields.filter(([n]) => n !== dropField);
+    const result = await trySendRaw(userClient, chatId, 5, buildContent(subset), `omit field ${dropField}`);
+  }
+
+  console.log('\n=== Drop pairs / minimize ===');
+  // Just imageKey alone (already known to fail)
+  await trySendRaw(userClient, chatId, 5, buildContent([allFields[0]]), 'just imageKey');
+  // imageKey + field 10 (thumb)
+  await trySendRaw(userClient, chatId, 5, buildContent([allFields[0], allFields[5]]), 'imageKey + thumb(10)');
+  // imageKey + 4 + 5 (dims)
+  await trySendRaw(userClient, chatId, 5, buildContent([allFields[0], allFields[1], allFields[2]]), 'imageKey + 4 + 5');
+  // imageKey + 4 + 5 + 10
+  await trySendRaw(userClient, chatId, 5, buildContent([allFields[0], allFields[1], allFields[2], allFields[5]]), 'imageKey + 4 + 5 + 10');
+  // imageKey + 8 + 10 (mime + thumb)
+  await trySendRaw(userClient, chatId, 5, buildContent([allFields[0], allFields[3], allFields[5]]), 'imageKey + mime(8) + thumb(10)');
+  // imageKey + 4 + 5 + 8 (no size, no thumb)
+  await trySendRaw(userClient, chatId, 5, buildContent([allFields[0], allFields[1], allFields[2], allFields[3]]), 'imageKey + 4 + 5 + mime(8)');
+})().catch(e => { console.error('FATAL:', e.message); process.exit(1); });