feishu-user-plugin 1.3.8 → 1.3.10

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

@@ -1,8 +1,8 @@
 ---
 name: feishu-user-plugin
-version: "1.3.8"
+version: "1.3.10"
 description: "All-in-one Feishu plugin — send messages as yourself (incl. batch_send), read group/P2P chats (auto-expands merge_forward), manage docs/tables/wiki (full CRUD)/drive, OKR (with progress writes), calendar (read+write), Tasks v2, multi-profile auto-switch, real-time WS events. v1.3.8: multi-profile auto-switch on read errors (B), WebSocket realtime im.message events via get_new_events (C), credential pointer-only mode (E), CI gates (F), auth/uat.js + auth/cookie.js extracts (D)."
-allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, batch_send, send_card_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, list_profiles, switch_profile, manage_profile_hints, read_p2p_messages, list_user_chats, list_chats, read_messages, send_message_as_bot, reply_message, forward_message, delete_message, update_message, add_reaction, delete_reaction, pin_message, create_group, update_group, list_members, manage_members, search_docs, read_doc, get_doc_blocks, create_doc, manage_doc_block, manage_bitable_app, manage_bitable_table, manage_bitable_field, manage_bitable_view, manage_bitable_record, upload_bitable_attachment, list_wiki_spaces, search_wiki, list_wiki_nodes, get_wiki_node, create_wiki_node, update_wiki_node, move_wiki_node, copy_wiki_node, delete_wiki_node, list_files, create_folder, upload_drive_file, manage_drive_file, upload_image, upload_file, download_message_resource, download_doc_image, list_user_okrs, get_okrs, list_okr_periods, create_okr_progress_record, list_okr_progress_records, delete_okr_progress_record, list_calendars, list_calendar_events, get_calendar_event, create_calendar_event, update_calendar_event, delete_calendar_event, respond_calendar_event, get_freebusy, list_tasks, get_task, create_task, update_task, complete_task, delete_task, manage_task_members, get_new_events
+allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, batch_send, send_card_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, list_profiles, switch_profile, manage_profile_hints, read_p2p_messages, list_user_chats, list_chats, read_messages, send_message_as_bot, reply_message, forward_message, delete_message, update_message, add_reaction, delete_reaction, pin_message, create_group, update_group, list_members, manage_members, search_docs, read_doc, get_doc_blocks, create_doc, manage_doc_block, read_doc_markdown, manage_bitable_app, manage_bitable_table, manage_bitable_field, manage_bitable_view, manage_bitable_record, upload_bitable_attachment, list_wiki_spaces, search_wiki, list_wiki_nodes, get_wiki_node, create_wiki_node, update_wiki_node, move_wiki_node, copy_wiki_node, delete_wiki_node, list_files, create_folder, upload_drive_file, manage_drive_file, upload_image, upload_file, download_message_resource, download_doc_image, list_user_okrs, get_okrs, list_okr_periods, create_okr_progress_record, list_okr_progress_records, delete_okr_progress_record, list_calendars, list_calendar_events, get_calendar_event, create_calendar_event, update_calendar_event, delete_calendar_event, respond_calendar_event, get_freebusy, list_tasks, get_task, create_task, update_task, complete_task, delete_task, manage_task_members, get_new_events, manage_ws_status
 user_invocable: true
 ---
 
@@ -24,6 +24,7 @@ Activate when the user mentions:
 - Feishu tables ("查飞书表格", "query Bitable")
 - Feishu wiki ("搜飞书知识库", "search wiki")
 - Login status ("飞书登录状态", "check Feishu login")
+- **Multi-account** ("加一个飞书账号", "切换到 work 账号", "add another Feishu account", "switch to my work account") — see Multi-Account Workflow below
 
 ## 9 Built-in Skills
 
@@ -97,8 +98,79 @@ Then restart Claude Code.
 3. Copy the App ID and App Secret to your `.mcp.json`
 4. Add the bot to any group chats you want to read
 
+## Multi-Account Workflow (v1.3.9+)
+
+The plugin supports multiple Feishu organization accounts via named profiles
+in `~/.feishu-user-plugin/credentials.json`. Each profile has its own
+COOKIE / APP_ID / APP_SECRET / UAT.
+
+### When the user says "add another Feishu account" / "加一个飞书账号"
+
+Drive this end-to-end via the Bash tool — DO NOT just print commands and
+ask the user to type them. Specifically:
+
+**1. Confirm what's needed**, then collect:
+- Profile name (default suggestion: `work2`, `personal`, etc.; let user pick)
+- The new account's APP_ID and APP_SECRET (user must register a Custom App
+  on https://open.feishu.cn/app for that account's tenant — the existing
+  app from the default profile WON'T work for a different tenant)
+- The new account's COOKIE — drive Playwright MCP to extract it (see
+  "Getting Your Cookie" above; note the **clear cookies first** caveat
+  to avoid stale-account contamination)
+
+**2. Run setup (no `--activate` — keep current account active so user
+isn't yanked off mid-session):**
+```bash
+npx feishu-user-plugin setup --profile <name> --app-id <X2> --app-secret <S2> --cookie <C2>
+```
+
+**3. Run OAuth for the new profile** (this opens a browser tab; user must
+click "授权" in the consent page — that part is unavoidable):
+```bash
+npx feishu-user-plugin oauth --profile <name>
+```
+After consent, UAT is written to `credentials.json::profiles[<name>]`.
+
+**4. Confirm via list_profiles MCP tool** — should now see both `default`
+and `<name>`, with `default` still active.
+
+**5. Tell the user how to switch later** — call `switch_profile(name="<name>")`
+MCP tool from Claude Code; cross-process MCP processes auto-sync within ms
+via dispatcher mtime hook.
+
+### When the user says "switch to <profile>" / "切到 work 账号"
+
+Just call `switch_profile(name="<profile>")` MCP tool. Don't run any CLI
+command. Cached clients reset; next tool call uses the new account.
+
+If the named profile doesn't exist, list_profiles first to show the user
+their actual profile names, then ask which they meant.
+
+### When the user says "show all my Feishu accounts" / "我有几个飞书账号"
+
+Call `list_profiles` MCP tool. Show the active marker.
+
+### Optional cron for keepalive (multi-profile)
+
+If the user has multiple profiles with UAT, suggest:
+```bash
+crontab -e   # add this line:
+0 */4 * * * npx feishu-user-plugin keepalive --all >> /tmp/feishu-keepalive.log 2>&1
+```
+The `--all` flag iterates every profile in credentials.json (without it,
+only the active profile gets refreshed — sufficient for single-account
+users but multi-account users will see other profiles' UATs expire).
+
 ## Known Limitations
 
 - Image/file sending requires uploading via Official API first to get keys
-- CARD message type (type=14) not yet supported
-- Cookie session valid for ~12h, auto-refreshed via built-in heartbeat (4h interval)
+  (`upload_image` → `send_image_as_user(image_key=...)`).
+- `send_card_as_user` always routes through bot identity. User-identity
+  (cookie protobuf) card sending was confirmed server-side disabled in
+  v1.3.9 (exhaustive brute-force).
+- Cookie session valid for ~12h; auto-refreshed via built-in heartbeat
+  (4h interval). UAT valid 2h, refresh_token valid 7 days; run `keepalive`
+  cron weekly to prevent refresh_token expiration.
+- "Seamless" auto-switch tied to which account is active in Feishu Desktop
+  is **not yet implemented** (designed for v1.3.10; see ROADMAP). For now,
+  call `switch_profile` MCP tool when you want to flip.

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

@@ -24,7 +24,7 @@ The 9 Claude Code skills are also exposed as MCP prompts (`prompts/list` + `prom
 
 Each prompt accepts a single `arguments` free-form string (mirroring the `$ARGUMENTS` convention used by Claude Code skills). `status` has no arguments.
 
-## Tool Categories (82 tools)
+## Tool Categories (84 tools)
 
 Per-tool descriptions live in each tool's MCP `inputSchema.description`. This section lists names + cross-domain caveats only.
 
@@ -34,7 +34,7 @@ Per-tool descriptions live in each tool's MCP `inputSchema.description`. This se
 - All cookie sends auto-resolve `oc_xxx` chat IDs to numeric since v1.3.7 (C1.4: `getChatInfo → search → numeric`, cached).
 - Plain-text sends accept `ats:[{userId,name}]` — the marker `@<name>` must appear in `text`; spliced into a real AT element that triggers notifications.
 - `send_post_as_user` paragraphs accept `{tag:"text"}` / `{tag:"a",href,text}` / `{tag:"at",userId,name}` elements; `at` element triggers a real notification.
-- `send_image_as_user` is **broken via cookie protobuf** (HTTP 400 — wire format incomplete). Workaround: `send_message_as_bot(msg_type="image")`. Wire-format reverse-engineering deferred to v1.3.8. See Known Limitations.
+- `send_image_as_user` works as-of v1.3.9 (cookie protobuf reverse-engineered via brute-force probe — see `scripts/explore-image-minimize.js`). Required Content fields: `imageKey` + `thumbnailKey`. Plugin defaults thumbnailKey = imageKey when caller omits it. Optional metadata: width / height / mime / size — all auto-derivable on Feishu's side, no pre-compute needed.
 
 ### User Identity — Contacts & Info (5 tools)
 `search_contacts` / `create_p2p_chat` / `get_chat_info` / `get_user_info` / `get_login_status`
@@ -56,9 +56,10 @@ Per-tool descriptions live in each tool's MCP `inputSchema.description`. This se
 - `manage_members` requires `member_id_type` to match the IDs you pass (`open_id` default; pass `union_id`/`user_id` explicitly to avoid 9499).
 - `download_message_resource(kind=image|file)` MUST pass `save_path` when payload > 2 MiB (Anthropic 5 MB inline cap). For `merge_forward` children use `parentMessageId`, not child id.
 
-### Official API — Docs (5 tools)
-`search_docs` / `read_doc` / `get_doc_blocks` / `create_doc` / `manage_doc_block` / `download_doc_image`
+### Official API — Docs (7 tools)
+`search_docs` / `read_doc` / `read_doc_markdown` / `get_doc_blocks` / `create_doc` / `manage_doc_block` / `download_doc_image`
 
+- `read_doc_markdown` returns a markdown string instead of structured JSON — saves ~60% tokens for RAG / digest / summarisation. Embedded images / files surface as `feishu://image_token/<TOKEN>` / `feishu://file_token/<TOKEN>` placeholders; pair with `download_doc_image` for binaries. `document_id` accepts native token / wiki node / Feishu URL same as the others.
 - `manage_doc_block(action=create)` has image (`image_path`/`image_token`) and file (`file_path`/`file_token`) shortcuts; FILE blocks (block_type=23) are auto-wrapped in VIEW container (block_type=33), plugin walks into the inner file block before `replace_file` PATCH.
 - `download_doc_image` same 2 MiB cap as `download_message_resource`.
 - All `document_id` / `app_token` accept native token / wiki node token / full Feishu URL (resolved via `getWikiNode`, 10 min cache).
@@ -111,13 +112,14 @@ Per-tool descriptions live in each tool's MCP `inputSchema.description`. This se
 - `switch_profile` invalidates cached client instances; next call rebuilds against the new profile. Multi-profile registered via `LARK_PROFILES_JSON` env or `credentials.json` profiles map.
 - `manage_profile_hints(action=list|set|clear, resource_key?, profile?)` (v1.3.8) inspects / edits the resourceKey → profile cache the auto-switch middleware uses. No-op when credentials.json doesn't exist.
 
-### Plugin — Realtime Events (1 tool, v1.3.8)
-`get_new_events`
+### Plugin — Realtime Events (2 tools, v1.3.9)
+`get_new_events` / `manage_ws_status`
 
-- WS connection started at MCP boot when APP_ID + APP_SECRET are configured. Connects to feishu.cn — Lark international not supported.
-- Buffer cap 1000 events; oldest dropped. Drain semantics: consumers see each event once.
-- Currently emits `im.message.receive_v1` only. Future: approval / calendar / docs comments behind config flag.
-- Filter by `event_type` / `event_types` / `chat_id` / `since_seconds`. `peek=true` keeps events in buffer.
+- **v1.3.9 machine-level**: a single MCP process per machine owns the WS via `~/.feishu-user-plugin/ws-owner.lock`. Events written to `~/.feishu-user-plugin/events.jsonl` (append-only, 10 MB soft / 20 MB hard cap). All harnesses read through a shared `events.cursor.json` — **every event delivered exactly once across all MCP processes**, no more duplicates.
+- WS connection started at MCP boot when APP_ID + APP_SECRET configured. Connects to feishu.cn — Lark international not supported.
+- Default subscriptions = `["im.message.receive_v1"]`. Edit `credentials.json::profiles[<active>].events` to add others (`approval.instance.created_v4`, `calendar.calendar.event.changed_v4`, etc.); call `manage_ws_status(action=reconfig)` to apply without restart.
+- `get_new_events` filter by `event_type` / `event_types` / `chat_id` / `since_seconds` / `profile`. `peek=true` keeps cursor unchanged. **Default `profile` filter = current active**.
+- `manage_ws_status(action=info|reconnect|claim|rotate|reconfig)` — diagnose / control the WS owner. `claim --force` steals an active lock; `rotate` forces events.jsonl rotation.
 
 ## Usage Patterns
 
@@ -177,6 +179,8 @@ For users with ≥2 profiles in `~/.feishu-user-plugin/credentials.json`. Read-o
 
 Override per call with `via_profile: "<name>"` to pin, or `via_profile: "auto"` to allow auto-switch on a write. Hints persist in `credentials.json::profileHints` and are inspectable via `manage_profile_hints`.
 
+v1.3.9: `FEISHU_PLUGIN_PROFILE` env is bootstrap-only — `credentials.json::active` is authoritative once the file exists. Cross-process sync via dispatcher mtime check (~10μs/call).
+
 ### Multi-profile registration
 For more profiles beyond the default, set `LARK_PROFILES_JSON` in the MCP env (or use `credentials.json` profiles map):
 ```json
@@ -190,6 +194,9 @@ For more profiles beyond the default, set `LARK_PROFILES_JSON` in the MCP env (o
 - Cookie expiry: sl_session has 12h max-age, auto-refreshed by heartbeat every 4h.
 - UAT expiry: 2h, auto-refreshed via refresh_token.
 - Refresh token expiry: 7 days. Use `keepalive` cron to prevent expiration.
+- `~/.feishu-user-plugin/ws-owner.lock`: lock file owned by the one MCP process driving the WS connection (O_CREAT|O_EXCL, 30 s stale).
+- `~/.feishu-user-plugin/events.jsonl`: append-only event log written by the WS owner; 10 MB soft / 20 MB hard cap then rotated to `events.jsonl.old`.
+- `~/.feishu-user-plugin/events.cursor.json`: global drain cursor shared across all MCP processes — advancing it marks events as consumed for all harnesses on the machine.
 
 ### Credentials store (v1.3.7+)
 Single source of truth at `~/.feishu-user-plugin/credentials.json` (mode 0600). Schema documented at `docs/CREDENTIALS-FORMAT.md`. The MCP server reads from this file when present; cookie heartbeat and UAT refresh persist back to it atomically. Multiple harnesses (Claude Code, Codex) sharing the same file see token rotations consistently — no more "Codex still has the old UAT" drift after a refresh in Claude Code.
@@ -289,6 +296,8 @@ v1.3.5+ hardening means the "6 MCP processes racing on UAT refresh and burning t
 ### Multiple / duplicate MCP server processes
 Codex + Claude Code both can respawn the server per tool session without cleanup; 6 concurrent processes isn't unusual. v1.3.5 neutralises the damage (file lock above) but stale processes still hold memory. **Manual cleanup when you notice**: `pkill -f 'feishu-user-plugin/src/index.js'`. Also: a team-skills plugin must NOT ship `.mcp.json` — if both `~/.claude.json` and team-skills register the same MCP, you get duplicates; delete `.mcp.json` from the team-skills plugin dir.
 
+v1.3.9: events are now machine-level; each event delivered exactly once across all MCP processes. Old per-process duplicates issue resolved.
+
 ### `create_*` tool warns "UAT failed, created as BOT"
 UAT is failing (expired / scope missing / race), so the plugin fell back to bot. Resource is now owned by the shared bot, tenant-readable. **Fix**: `npx feishu-user-plugin oauth`, restart, delete the bot-owned copy and recreate.
 
@@ -304,7 +313,7 @@ Expected — Feishu API only returns groups. P2P flow: `search_contacts` → `cr
   - Lark international tenant (lark.com) — not supported by Feishu's WSClient. No fix; use polling tools (`read_messages`) instead.
   - Network restriction — corporate proxy blocking outbound WSS.
 - **Bot not in the chat where the message was sent**: `im.message.receive_v1` only fires for chats the bot is a member of. Add the bot to the chat to receive events.
-- **Multiple MCP processes**: Each process has its own WS, so events are duplicated. De-dupe on `event_id` in your consumer.
+- **Multiple MCP processes**: v1.3.9: events are now machine-level; each event delivered exactly once across all MCP processes. Old per-process duplicates issue resolved.
 
 ## Architecture
 
@@ -411,69 +420,80 @@ See `docs/TESTING-METHODOLOGY.md` for the full regression playbook (when to use
 - `chore:` dependencies, CI, config changes
 
 ### Publishing
-**IMPORTANT: Version number must ALWAYS be confirmed with the user before publishing.**
-Any operation involving `npm version`, modifying `package.json` version, `git tag v*`, or `git push --tags` requires explicit user confirmation of the target version number. Do not auto-decide version numbers.
+**IMPORTANT: User confirmation is required exactly TWICE per release** — once on target version (before any publish operation), once on the announcement card before sending. Don't ask between steps; run end-to-end.
 
 Three-layer version safety:
-1. **Claude rule** (this section): Ask user to confirm version before any publish-related operation
+1. **Claude rule** (this section): Confirm version once with user. Then run all publish steps without asking. Stop only on (a) failure, or (b) the announcement-preview gate.
 2. **Local gate** (`prepublishOnly`): Interactive confirmation when running `npm publish` locally (skipped in CI)
 3. **CI gate** (`.github/workflows/publish.yml`): Tag must match `package.json` version or publish fails
 
 Steps:
-1. Confirm target version with user
-2. Update `version` in `package.json`
-3. `git add <files> && git commit -m "v1.x.x: description"`
-4. `git tag v1.x.x && git push && git push --tags`
-5. GitHub Actions verifies tag matches package.json, then auto-publishes to npm
+1. Confirm target version with user (once)
+2. Bump `version` in `package.json` + `.claude-plugin/plugin.json` + `skills/feishu-user-plugin/SKILL.md` (single commit; `scripts/check-version.js` enforces triangle equality)
+3. Open release PR, wait for CI green (auto-merge enabled on this repo, so `gh pr merge --auto --squash`)
+4. After merge, `git tag vX.Y.Z && git push origin vX.Y.Z` triggers GitHub Actions `Publish to npm` workflow
+5. Verify: `npm view feishu-user-plugin version` returns the new version
+6. post-merge hook runs `scripts/sync-team-skills.sh` which auto-syncs team-skills (skills + plugin.json + child README changelog + root README catalog row + catalog.yaml regen + `gh pr merge --admin --squash` on the sync PR). No manual touches in team-skills.
+7. Run `node scripts/generate-release-artifacts.js` to produce `/tmp/feishu-release/v$VERSION/feishu-card.json`
+8. Present the card preview to user. Wait for "发"
+9. `send_card_as_user(chat_id="oc_0fab8e155f500f28bd437e8686921870", card=<JSON>)` — only after user explicitly approves
 6. **After npm confirms the new version is live, draft a release announcement in Chinese for the "AI技术解决（内部）" Feishu group and show it to the user for approval BEFORE sending.** Do not send until the user explicitly approves.
 
 ### Release announcement rules (every release)
-After a successful publish, draft a group announcement to "AI技术解决（内部）" (chat_id `7599552782038813643`) and ALWAYS show it to the user for review first. Only send after explicit approval.
 
-**Transport**: `send_post_as_user` (rich-text post). No @-mentions — announcements are impersonal broadcasts. No emojis. No marketing language.
+After successful publish, send announcement to "AI技术解决（内部）" group (chat_id `oc_0fab8e155f500f28bd437e8686921870`). **Never send without explicit user approval** — show preview first, wait for "发".
+
+**Transport (v1.3.9+)**: `send_card_as_user` (interactive Feishu card). No @-mentions, no emojis, no marketing.
 
-**Structure** (in this order; omit a section if it doesn't apply this release):
+**Source of truth**: `CHANGELOG.md` v$VERSION section. **Never hand-write announcements** — the generator script extracts the text deterministically:
 
+```bash
+node scripts/generate-release-artifacts.js [version]
+# Outputs to /tmp/feishu-release/v<version>/:
+#   feishu-card.json          ← full Feishu card payload, ready for send_card_as_user
+#   team-skills-changelog.md  ← markdown block injected into team-skills child README by post-merge hook
+#   team-skills-readme-row.md ← root README catalog row replacement
 ```
-feishu-user-plugin vX.Y.Z 发布
 
-<一到两句开篇总结本次发布的主题，陈述语气，不推销>
+**CHANGELOG conventions** (the generator parses these — keep the convention or output diverges):
 
-修复
-• <缺陷描述>：<根因与修复机制，引用具体错误码/接口名/参数>
-• ...
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
 
-新增
-• 新增 <tool 名> 工具：<一句话功能描述>。<关键约束或调用条件>
-• ...
+<一到两句陈述式开篇，可空，generator 用作 card 第一段；不宣传不夸大>
 
-调整
-• <行为变化的描述>
-• ...
+### Added              （翻译为"新增"）
+- **简短标题 (代号)**：用户可见现象。底层机制 / 错误码 / 接口名 / 文件路径。
+- ...
 
-下版本计划
-• <条目>
-• ...
+### Changed            （"调整"）
+### Fixed              （"修复"）
+### Removed | Deprecated | Security  （"移除" / "废弃" / "安全"）
+### Deferred to vN.M.P （"下版本计划 (vN.M.P)"，从上版本拷过来 - 本版完成的条目）
 
-升级方式
-• 重启 Claude Code / Codex 即可自动拉取 X.Y.Z
-• <若有相关新日志/错误提示，说明怎么应对>
-• 建议复测 N 个场景：<场景 1>、<场景 2>、<场景 3>
+### Test scenarios     （可选；用作"升级方式"段的"建议复测"行）
+- 调用 X 时观察 Y 出现 Z
+- ...
 ```
 
-**写作规范**:
-- **开篇**：一到两句陈述式总结，不宣传、不夸大。参考 v1.3.2："本次更新主要补齐了 X 能力，并修复了 Y 问题；同时将 Z 统一调整为 ..."
-- **每条 bullet**：先写用户可见现象，再写底层机制。引用具体错误码（如 1770032 / 91403）、接口名（如 manage_doc_block）、参数名（如 RichText.atIds）——专业读者信赖的是细节
-- **字符**：bullet 用 `•`（U+2022），不用 `-` 或 `*`；代码/工具名在正文中直接写，不加反引号
-- **禁用**：emoji、🔴🟡🟢 之类严重度标记、`@` 任何人、营销词（"强大"、"全新"、"重磅"）、夸张修辞
-- **语气**：技术 release note 的中性语气，像写给同行的内部更新。参考 v1.3.2 全文
-- **长度**：单屏为宜，一般 400–700 汉字。每条 bullet 一到三行
-- **下版本计划**：复制自上一版公告仍未完成的条目 + 本次发布中暴露的新方向。本版已完成的条目必须删除
-- **升级方式**：至少包含重启指令；若本次修了某类错误（如 APP_ID 校验），列出对应诊断日志字样；以"建议复测 N 个场景"收尾，场景要具体可操作
-
-**结尾**：不加 CHANGELOG 链接（v1.3.2 风格未含链接，群内读者不需要）。
-
-**发送前**：始终先用 `send_to_user` 或类似工具发给用户自己审核，或直接以文本形式贴在对话里等用户批准。用户说"发"才调 `send_post_as_user` 到目标群。
+**写作规范** (writes flow into the card directly):
+- 每条 bullet：先用户可见现象，再底层机制。引用具体错误码 (91403 / 1254301)、接口名 (`manage_bitable_record`)、参数名 (`via_profile`)、文件路径 (`src/auth/profile-router.js`)
+- 代号语：`(B)` `(D.1)` 等可保留，对应 ROADMAP / plan 编号
+- 禁用：emoji / `@` 任何人 / "强大"等营销词 / 夸张修辞
+- 长度：单屏，整段 400-800 汉字。每条 bullet 1-3 行
+
+**升级方式** is generated automatically by the script:
+- "重启 Claude Code / Codex 自动拉取 X.Y.Z" — always
+- "推荐运行 npx feishu-user-plugin migrate --confirm ..." — added when bullets mention migrate / credentials.json / FEISHU_PLUGIN_PROFILE
+- "启动看 stderr 带 WS connected ..." — added when bullets mention WS / WebSocket / get_new_events
+- "建议复测 N 个场景：..." — uses `### Test scenarios` bullets if present, otherwise top-3 Added bullet titles
+
+**Step-by-step at release time**:
+1. Bump version → tag → push → wait for `Publish to npm` workflow success → confirm `npm view feishu-user-plugin version`
+2. post-merge hook on this repo runs `scripts/sync-team-skills.sh`, which calls `scripts/generate-release-artifacts.js` and auto-injects v$VERSION block into team-skills child README + updates root README catalog row + opens & `--admin --squash`-merges the team-skills sync PR. Zero manual steps in team-skills.
+3. `node scripts/generate-release-artifacts.js` (idempotent — same input gives same output) on this repo to (re)produce `feishu-card.json`
+4. **Show the rendered card preview to user** — paste a summary or re-render via `cat /tmp/feishu-release/v$VERSION/feishu-card.json | jq` and let user inspect. Do not send.
+5. User says "发" → `send_card_as_user(chat_id=oc_0fab8e155f500f28bd437e8686921870, card=<JSON content>)`
 
 ## OAuth Scopes (when re-running `npx feishu-user-plugin oauth`)
 
@@ -500,4 +520,4 @@ If a tool returns `access_denied` or error code `99991672` (scope not granted),
 - `list_wiki_spaces` may return empty if bot lacks `wiki:wiki:readonly` permission (v1.3.7+: `scopeHint` field is appended to the response when this happens)
 - `delete_wiki_node` calls an undocumented-in-SDK endpoint (`DELETE /wiki/v2/spaces/{id}/nodes/{token}`); v1.3.7 ships it because Feishu's API console exposes it, but if Feishu retires the endpoint the tool will fail with a clear 404 — fall back to `manage_drive_file(action=delete)` on the underlying obj_token in that case.
 - `search_wiki` uses same API as `search_docs` — `docs_types` filter may not work as expected
-- `send_image_as_user` is currently broken: Feishu's cookie protobuf gateway rejects the simple `{imageKey}` content payload (HTTP 400) because the Feishu Web client encodes images with extra metadata (image dimensions, mime type, etc.) that we don't have in `proto/lark.proto`. Reverse-engineering needs Chrome DevTools traffic capture and is deferred to v1.3.8. v1.3.7 surfaces a clear error pointing to `send_message_as_bot(msg_type="image", ...)` as the workaround. (`send_file_as_user` and `send_post_as_user` work fine — only IMAGE is affected.)
+- `send_card_as_user` only routes through bot. User-identity (cookie protobuf) card sending was confirmed server-side disabled in v1.3.9 (exhaustive brute-force, `scripts/explore-card-protobuf.js`). The "as_user" suffix is historical naming kept for backward compat — the `via` parameter and the user-path codepath were removed; the tool is bot-only.

package/src/auth/credentials.js

@@ -327,6 +327,39 @@ function migrate({ dryRun = true } = {}) {
   return { ok: true, credentials };
 }
 
+// --- Per-profile events list (v1.3.9 A.4) ---
+//
+// Each profile may optionally declare an `events` array listing the Feishu
+// real-time event types to subscribe to. When absent the default
+// `["im.message.receive_v1"]` is used. This array is read by
+// `_getProfileEventsList` in server.js to configure the WebSocket client.
+//
+// Example credentials.json profile entry with events:
+//   "default": {
+//     "LARK_APP_ID": "...",
+//     ...,
+//     "events": ["im.message.receive_v1", "approval.instance.created_v4"]
+//   }
+
+function getProfileEvents(name) {
+  const f = _readFile();
+  const target = name || (f ? f.active : 'default');
+  if (f && f.profiles[target] && Array.isArray(f.profiles[target].events)) {
+    return f.profiles[target].events.slice();
+  }
+  return ['im.message.receive_v1'];
+}
+
+function setProfileEvents(name, eventList) {
+  if (!Array.isArray(eventList)) throw new Error('setProfileEvents: eventList must be an array');
+  const f = _readFile();
+  if (!f) throw new Error('No credentials.json — cannot set profile events.');
+  if (!f.profiles[name]) throw new Error(`Profile "${name}" not found.`);
+  f.profiles[name].events = eventList.slice();
+  _atomicWriteJson(_credentialsPath(), f);
+  return true;
+}
+
 // --- Profile hints (v1.3.8) ---
 //
 // profileHints maps resourceKey → profileName, persisted in credentials.json.
@@ -383,6 +416,9 @@ module.exports = {
   setActiveProfile,
   persistProfileUpdate,
   migrate,
+  // per-profile events list (v1.3.9 A.4)
+  getProfileEvents,
+  setProfileEvents,
   // profile hints (v1.3.8)
   getProfileHints,
   setProfileHint,

package/src/cli.js

@@ -67,9 +67,21 @@ Setup options:
   --app-secret <s>    App Secret (non-interactive mode)
   --cookie <c>        Cookie string (optional)
   --client <target>   Config target: claude (default), codex, or both
-  --pointer-only      Write only FEISHU_PLUGIN_PROFILE=default to harness env.
-                      Real creds live in ~/.feishu-user-plugin/credentials.json
-                      (run "migrate --confirm" first if not yet migrated).
+  --force             Overwrite existing default profile in credentials.json
+  --profile <name>    Create or update a named profile (replaces LARK_PROFILES_JSON
+                      for new setups). Without --activate, leaves the active
+                      profile unchanged so adding work2 doesn't yank you off default.
+  --activate          When used with --profile, also flip credentials.json::active
+                      to the named profile.
+
+OAuth options (v1.3.9):
+  npx feishu-user-plugin oauth --profile <name>
+                      Get UAT for a specific profile. Default = currently active.
+
+Keepalive options (v1.3.9):
+  npx feishu-user-plugin keepalive --all
+                      Refresh cookie + UAT for ALL profiles in credentials.json.
+                      Default (no flag) = active profile only (back-compat).
 
 Quick Start (Claude Code):
   1. npx feishu-user-plugin setup
@@ -81,9 +93,16 @@ Quick Start (Codex):
   2. Follow the prompts to configure credentials
   3. Restart Codex
 
+Multi-account (v1.3.9):
+  1. npx feishu-user-plugin setup --app-id X1 --app-secret S1 --cookie C1
+  2. npx feishu-user-plugin oauth                          # default profile UAT
+  3. npx feishu-user-plugin setup --profile work2 --app-id X2 --app-secret S2 --cookie C2
+  4. npx feishu-user-plugin oauth --profile work2          # work2 profile UAT
+  5. In Claude Code: switch_profile(name="work2") MCP tool to flip live
+
 Auto-renewal (optional):
   Add to crontab to keep tokens alive even when Claude Code is closed:
-  crontab -e → add: 0 */4 * * * npx feishu-user-plugin keepalive >> /tmp/feishu-keepalive.log 2>&1
+  crontab -e → add: 0 */4 * * * npx feishu-user-plugin keepalive --all >> /tmp/feishu-keepalive.log 2>&1
 `);
 }
 
@@ -97,53 +116,75 @@ function migrate() {
 async function keepalive() {
   const { LarkUserClient } = require('./clients/user');
   const { LarkOfficialClient } = require('./clients/official');
-  const { readCredentials, persistToConfig } = require('./auth/credentials');
-
-  const creds = readCredentials();
-  if (!creds.LARK_COOKIE && !creds.LARK_APP_ID) {
-    console.error('[keepalive] No credentials found. Run: npx feishu-user-plugin setup');
-    process.exit(1);
-  }
-  let ok = true;
+  const cred = require('./auth/credentials');
+
+  // v1.3.9: --all flag iterates every profile in credentials.json,
+  // refreshing cookie + UAT for each. Default behavior (no flag) refreshes
+  // only the active profile (back-compat with v1.3.6+ cron usage).
+  const all = process.argv.includes('--all');
+  const targetProfiles = all ? cred.listProfileNames() : [cred.getActiveProfileName() || 'default'];
+
+  let totalOk = true;
+  for (const profileName of targetProfiles) {
+    let env;
+    try { env = cred.getActiveProfileEnv(profileName); }
+    catch (e) {
+      console.error(`[keepalive][${profileName}] cannot read profile: ${e.message}`);
+      totalOk = false;
+      continue;
+    }
+    if (!env.LARK_COOKIE && !env.LARK_APP_ID) {
+      console.error(`[keepalive][${profileName}] no credentials. Run: npx feishu-user-plugin setup --profile ${profileName} ...`);
+      totalOk = false;
+      continue;
+    }
+    let ok = true;
 
-  // 1. Refresh Cookie
-  const cookie = creds.LARK_COOKIE;
-  if (cookie && cookie !== 'SETUP_NEEDED') {
-    try {
-      const client = new LarkUserClient(cookie);
-      await client.init();
-      // init() calls _getCsrfToken which refreshes sl_session
-      persistToConfig({ LARK_COOKIE: client.cookieStr });
-      console.log(`[keepalive] Cookie refreshed (user: ${client.userName})`);
-    } catch (e) {
-      console.error(`[keepalive] Cookie refresh FAILED: ${e.message}`);
-      ok = false;
+    // 1. Refresh Cookie
+    if (env.LARK_COOKIE && env.LARK_COOKIE !== 'SETUP_NEEDED') {
+      try {
+        const client = new LarkUserClient(env.LARK_COOKIE);
+        await client.init();
+        cred.persistProfileUpdate(profileName, { LARK_COOKIE: client.cookieStr });
+        console.log(`[keepalive][${profileName}] cookie refreshed (user: ${client.userName})`);
+      } catch (e) {
+        console.error(`[keepalive][${profileName}] cookie refresh FAILED: ${e.message}`);
+        ok = false;
+      }
     }
-  }
 
-  // 2. Refresh UAT
-  const appId = creds.LARK_APP_ID;
-  const appSecret = creds.LARK_APP_SECRET;
-  const uat = creds.LARK_USER_ACCESS_TOKEN;
-  const rt = creds.LARK_USER_REFRESH_TOKEN;
-  if (appId && appSecret && uat && uat !== 'SETUP_NEEDED' && rt) {
-    try {
-      const official = new LarkOfficialClient(appId, appSecret);
-      official._uat = uat;
-      official._uatRefresh = rt;
-      official._uatExpires = 0; // force refresh
-      await official._refreshUAT(); // refreshes + persists automatically
-      console.log('[keepalive] UAT refreshed');
-    } catch (e) {
-      console.error(`[keepalive] UAT refresh FAILED: ${e.message}`);
-      ok = false;
+    // 2. Refresh UAT (also writes to the same profile via auth/uat.js → persistToConfig
+    //    which goes through the active profile path. For --all we need to switch
+    //    active temporarily so the write lands on the right profile.)
+    if (env.LARK_APP_ID && env.LARK_APP_SECRET && env.LARK_USER_ACCESS_TOKEN && env.LARK_USER_ACCESS_TOKEN !== 'SETUP_NEEDED' && env.LARK_USER_REFRESH_TOKEN) {
+      const prevActive = cred.getActiveProfileName();
+      const needSwitch = all && prevActive !== profileName;
+      try {
+        if (needSwitch) cred.setActiveProfile(profileName);
+        // Set process.env so LarkOfficialClient.loadUAT() picks the right tokens
+        process.env.LARK_USER_ACCESS_TOKEN = env.LARK_USER_ACCESS_TOKEN;
+        process.env.LARK_USER_REFRESH_TOKEN = env.LARK_USER_REFRESH_TOKEN;
+        const official = new LarkOfficialClient(env.LARK_APP_ID, env.LARK_APP_SECRET);
+        official._uat = env.LARK_USER_ACCESS_TOKEN;
+        official._uatRefresh = env.LARK_USER_REFRESH_TOKEN;
+        official._uatExpires = 0; // force refresh
+        await official._refreshUAT();
+        console.log(`[keepalive][${profileName}] UAT refreshed`);
+      } catch (e) {
+        console.error(`[keepalive][${profileName}] UAT refresh FAILED: ${e.message}`);
+        ok = false;
+      } finally {
+        if (needSwitch) {
+          try { cred.setActiveProfile(prevActive); } catch (_) {}
+        }
+      }
     }
+    if (!ok) totalOk = false;
   }
 
-  if (ok) {
-    console.log('[keepalive] All tokens refreshed successfully');
-  }
-  process.exit(ok ? 0 : 1);
+  if (totalOk) console.log(`[keepalive] all profiles refreshed (${targetProfiles.length} profile${targetProfiles.length === 1 ? '' : 's'})`);
+  else console.error(`[keepalive] one or more profiles failed`);
+  process.exit(totalOk ? 0 : 1);
 }
 
 async function checkStatus() {

package/src/clients/user.js

@@ -185,18 +185,6 @@ class LarkUserClient {
     if (parentId) req.parentId = parentId;
     const { packet, ok } = await this._gateway(5, 'PutMessageRequest', req, '5.7.0');
     if (!ok) {
-      // The cookie protobuf gateway returns HTTP 400 when our wire format is
-      // missing required fields. Verified for IMAGE (v1.3.7 testing): the
-      // simple {imageKey} content payload is rejected — Feishu Web encodes
-      // images with extra metadata (image dimensions, mime type, etc.) that
-      // we don't have in proto/lark.proto. v1.3.8 shipped the capture/decode
-      // tooling (scripts/decode-feishu-protobuf.js + capture-feishu-protobuf.js
-      // + docs/COOKIE-PROTOBUF-CAPTURES.md). Actual reverse-engineering moved
-      // to v1.3.9. Surface a clear error routing the user to
-      // send_message_as_bot, which works.
-      if (type === MsgType.IMAGE) {
-        throw new Error('send_image_as_user: Feishu cookie protobuf gateway rejected the IMAGE wire format (HTTP 400). User-identity image sends are not yet supported — wire format reverse-engineering is deferred to v1.3.9 (v1.3.8 shipped the capture/decode tooling at scripts/decode-feishu-protobuf.js). Workaround: use send_message_as_bot(chat_id, msg_type="image", payload={image_key:"..."}).');
-      }
       throw new Error(`_sendMsg: cookie protobuf gateway returned non-2xx for type=${type}. The wire format likely doesn't match what Feishu expects.`);
     }
     return { success: true, status: packet.status };
@@ -268,9 +256,23 @@ class LarkUserClient {
   }
 
   // --- Send Image ---
+  // v1.3.9: cookie protobuf path now works. Gateway requires Content.imageKey
+  // (field 2) + Content.thumbnailKey (field 10). Width/height/mime/size are
+  // optional but accepted. We default thumbnailKey to imageKey when caller
+  // doesn't supply one — Feishu accepts that for already-thumbnail-sized
+  // uploads. See proto/lark.proto Content + scripts/explore-image-minimize.js.
 
   async sendImage(chatId, imageKey, opts = {}) {
-    return this._sendMsg(MsgType.IMAGE, chatId, { imageKey }, opts);
+    if (!imageKey) throw new Error('sendImage: imageKey required');
+    const content = {
+      imageKey,
+      thumbnailKey: opts.thumbnailKey || imageKey,
+    };
+    if (opts.width != null) content.imageWidth = opts.width;
+    if (opts.height != null) content.imageHeight = opts.height;
+    if (opts.mime) content.mimeType = opts.mime;
+    if (opts.size != null) content.fileSize = opts.size;
+    return this._sendMsg(MsgType.IMAGE, chatId, content, opts);
   }
 
   // --- Send File ---