feishu-user-plugin 1.3.2 → 1.3.4

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.2",
-  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself (incl. real @-mentions), read chats, manage docs/tables/wiki. 66 tools + 9 skills, 3 auth layers.",
+  "version": "1.3.4",
+  "description": "All-in-one Feishu plugin for Claude Code — send messages as yourself (incl. real @-mentions), read chats, manage docs (with image read/write) / bitable / wiki (native + move_docs_to_wiki) / drive / OKR / calendar. 74 tools + 9 skills, 3 auth layers.",
   "author": {
     "name": "EthanQC"
   },

package/CHANGELOG.md

@@ -4,6 +4,43 @@ 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.4] - 2026-04-22
+
+### Added
+- **Wiki-hosted content is now first-class**: every docx and bitable tool accepts the `document_id` / `app_token` parameter in three forms — native token (unchanged), wiki node token (`wikcnXXX` / `wikmXXX` / `wiknXXX`), or a full Feishu URL (`https://xxx.feishu.cn/docx/XXX`, `.../wiki/XXX`, `.../base/XXX`). A new `src/resolver.js` parses the input, calls `wiki/v2/spaces/get_node` when needed to resolve to `obj_token` + `obj_type`, and caches the mapping for 10 min. Zero-lookup path for direct URLs.
+- **`get_wiki_node` tool**: explicitly resolves a Wiki node to its backing object (`obj_type` + `obj_token` + `space_id`). Useful when you need to branch behaviour on whether a node points at a docx, bitable, sheet, mindnote, file, or slides.
+- **Create docx / bitable directly under Wiki**: `create_doc` / `create_bitable` accept optional `wiki_space_id` (and `wiki_parent_node_token` for nested placement). Plugin creates the resource in drive, then calls `wiki/v2/spaces/{space_id}/nodes/move_docs_to_wiki` to attach it. Returns `wikiNodeToken` on success, `wikiAttachTaskId` when Feishu queues the move, or a warning if attach fails (resource still in drive).
+- **Docx image read**: `download_image` now has a docx mode — pass `image_token` (from `get_doc_blocks` image block) and optional `doc_token` (native / wiki node / URL). Routes through `drive/v1/medias/{token}/download`, returns base64 as MCP image content so the model sees the pixels.
+- **Docx image write**: `create_doc_block` gains two shortcut parameters — `image_path` (local file) automatically runs the three-step Feishu flow (create empty image block → upload via `drive/v1/medias/upload_all` with `parent_type=docx_image` and the new block_id → patch with `replace_image`); `image_token` reuses an already-uploaded media token. `update_doc_block` accepts `image_token` to swap the picture in an existing image block.
+- **`list_user_okrs` / `get_okrs` / `list_okr_periods` tools**: read a user's OKRs, batch fetch full objective + key result details (progress, alignments, mentions), and enumerate periods. UAT-first with app fallback when the OKR scope is granted.
+- **`list_calendars` / `list_calendar_events` / `get_calendar_event` tools**: list the user's calendars (primary / shared / subscribed), list events in a time window, and fetch full event details (attendees, location, meeting links, attachments).
+
+### Fixed
+- **External-group `read_messages` hardening**: new `src/error-codes.js` classifies bot failures. Known-needs-UAT codes (`240001` external tenant, `70009` no permission, `70003` / `99991668` bot not in chat, `19001` chat not found) hop straight to UAT. Transient codes (`42101` rate limit, `5xx`, `ECONNRESET`, fetch timeouts) retry once after a 2 s delay before falling back. Response now includes `via: "bot" | "user" | "contacts"` and, when fallback fires, `via_reason` (e.g. `bot_external_tenant`). When the `chat_id` was discovered via `search_contacts` (i.e. definitely external) the bot path is skipped entirely.
+- **Raw Feishu payload no longer leaks when UAT is missing**: bot failures with no UAT configured now produce `Cannot read chat <id> as bot (<reason>). To read external/private groups, configure UAT via: npx feishu-user-plugin oauth` — previously the caller got the unwrapped Feishu error JSON.
+- **`_uatREST` array query params**: OKR / calendar endpoints that take repeated query keys (e.g. `period_ids=p1&period_ids=p2`) now serialize correctly. Previously `URLSearchParams(query)` would call `toString` on arrays and produce CSV, which Feishu rejects.
+
+### Changed
+- Tool count 67 → **74** (+7: `get_wiki_node`, `list_user_okrs`, `get_okrs`, `list_okr_periods`, `list_calendars`, `list_calendar_events`, `get_calendar_event`).
+- `getWikiNode(nodeToken, _spaceId)` — `spaceId` parameter position swapped; retained only for backward-compatibility of any external caller. The endpoint itself ignores `space_id`.
+- `create_doc_block` no longer requires `children` — callers who use the new `image_path` or `image_token` shortcut omit it. One of `children` / `image_path` / `image_token` must be provided.
+
+## [1.3.3] - 2026-04-20
+
+### Fixed
+- **MCP mid-session disconnect (root fix)**: All raw `fetch` calls to Feishu now go through `fetchWithTimeout` (AbortController, 30s default). A stalled connection used to hang a tool handler indefinitely; the MCP client would time out and some clients tore down the stdio transport — observed as "MCP 中途掉线" on v1.3.2. This was the real cause, not just the v1.3.1 stdout pollution.
+- **stdout pollution (defense-in-depth)**: `src/index.js` now globally redirects `console.log` / `console.info` to stderr at startup, before any other `require`. Any current or future dependency that accidentally writes to stdout can no longer corrupt the JSON-RPC channel. (v1.3.1's Lark-SDK-specific logger override stays as-is.)
+- **`(as user)` label lied for docs/bitable/folder creation**: `create_doc` / `create_bitable` / `create_folder` previously labeled every successful call `(as user)` whenever `LARK_USER_ACCESS_TOKEN` was set, even when the UAT call actually failed and silently fell back to app identity. `_asUserOrApp` now threads a real `_viaUser` flag through; failures show `(as app — UAT unavailable or failed; <resource> owned by the app, not you)`.
+
+### Added
+- **APP_ID startup validation**: MCP server probes `/auth/v3/app_access_token/internal` at boot. Invalid `LARK_APP_ID` / `LARK_APP_SECRET` (wrong-tenant, stale, or hallucinated by an autoinstall) now produce a clear stderr error pointing at the team-skills install prompt. Non-blocking — users running cookie-only workflows are unaffected.
+- **`get_login_status` shows app identity**: Now returns the actual `app_id` plus fetched app name, so users can immediately spot "this isn't my team's app" scenarios.
+- **`download_image` tool**: Download an image embedded in a message by `message_id` + `image_key`, returned as MCP image content so the model can see the pixels (not just the key string). Tries UAT first (works for any chat the user is in); falls back to app token (requires the bot to be in the chat).
+
+### Changed
+- Tool count 66 → **67** (added `download_image`).
+- README tool badge corrected from 76 → 67 (previous 76 was stale and never matched the actual export).
+
 ## [1.1.3] - 2026-03-11
 
 ### Fixed

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-76-orange.svg)](#tools)
+[![Tools](https://img.shields.io/badge/Tools-74-orange.svg)](#tools)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**All-in-one Feishu/Lark MCP Server -- 76 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, and more.**
+**All-in-one Feishu/Lark MCP Server -- 74 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.
 
@@ -337,7 +337,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 }
 ```
 
-## Tools (76 total)
+## Tools (74 total)
 
 ### User Identity -- Messaging (8 tools, cookie auth)
 
@@ -390,6 +390,21 @@ 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. |
+
+### Wiki, OKR, and Calendar (v1.3.4)
+
+| Tool | Description |
+|------|-------------|
+| `get_wiki_node` | Resolve a Wiki node token to its underlying obj_type + obj_token + space_id |
+| `list_user_okrs` | List a user's OKRs (requires open_id; filter by period_ids) |
+| `get_okrs` | Batch-fetch full OKR details (objectives, key results, progress, alignments) |
+| `list_okr_periods` | List OKR periods (quarters / years) |
+| `list_calendars` | List the current user's calendars (primary + shared + subscribed) |
+| `list_calendar_events` | List events in a calendar within a time range |
+| `get_calendar_event` | Full event details (attendees, location, meeting link, attachments) |
+
+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)
 
@@ -508,7 +523,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 (76 tools)
+│   ├── index.js             # MCP server entry point (74 tools)
 │   ├── client.js            # User identity client (Protobuf gateway)
 │   ├── official.js          # Official API client (REST, UAT)
 │   ├── utils.js             # ID generators, cookie parser

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "feishu-user-plugin",
-  "version": "1.3.2",
-  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging, docs, bitable, wiki, drive. 66 tools + 9 skills, 3 auth layers.",
+  "version": "1.3.4",
+  "description": "All-in-one Feishu plugin for Claude Code & Codex — messaging, docs (with image read/write), bitable, wiki (native + move_docs_to_wiki), drive, OKR, calendar. 74 tools + 9 skills, 3 auth layers.",
   "main": "src/index.js",
   "bin": {
     "feishu-user-plugin": "src/cli.js"

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

@@ -1,8 +1,8 @@
 ---
 name: feishu-user-plugin
-version: "1.1.3"
-description: "All-in-one Feishu plugin — send messages as yourself, read group/P2P chats, manage docs/tables/wiki. Replaces and extends the official Feishu MCP."
-allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, send_sticker_as_user, send_audio_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, read_p2p_messages, list_user_chats, list_chats, read_messages, reply_message, forward_message, search_docs, read_doc, create_doc, list_bitable_tables, list_bitable_fields, search_bitable_records, create_bitable_record, update_bitable_record, list_wiki_spaces, search_wiki, list_wiki_nodes, list_files, create_folder, find_user
+version: "1.3.4"
+description: "All-in-one Feishu plugin — send messages as yourself, read group/P2P chats, manage docs/tables/wiki (with wiki-node + URL transparent resolution), OKR, calendar, docx image read/write. Replaces and extends the official Feishu MCP."
+allowed-tools: send_to_user, send_to_group, send_as_user, send_image_as_user, send_file_as_user, send_post_as_user, send_sticker_as_user, send_audio_as_user, search_contacts, create_p2p_chat, get_chat_info, get_user_info, get_login_status, read_p2p_messages, list_user_chats, list_chats, read_messages, reply_message, forward_message, search_docs, read_doc, create_doc, list_bitable_tables, list_bitable_fields, search_bitable_records, create_bitable_record, update_bitable_record, list_wiki_spaces, search_wiki, list_wiki_nodes, get_wiki_node, list_files, create_folder, find_user, download_image, list_user_okrs, get_okrs, list_okr_periods, list_calendars, list_calendar_events, get_calendar_event
 user_invocable: true
 ---
 

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

@@ -6,7 +6,7 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - **Official API** (app credentials): Read group messages, docs, tables, wiki, drive, contacts, upload files
 - **User OAuth UAT** (user_access_token): Read P2P chat history, list all user's chats
 
-## Tool Categories (66 tools)
+## Tool Categories (74 tools)
 
 ### User Identity — Messaging (reverse-engineered, cookie-based)
 - `send_to_user` — Search user + send text (one step, most common). Returns candidates if multiple matches.
@@ -48,14 +48,48 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 - `list_bitable_views` / `create_bitable_view` / `delete_bitable_view` — View management (grid, kanban, gallery, form, gantt, calendar)
 - `search_bitable_records` / `get_bitable_record` — Query records
 - `batch_create_bitable_records` / `batch_update_bitable_records` / `batch_delete_bitable_records` — Record CRUD (single or batch, max 500/call)
-- `list_wiki_spaces` / `search_wiki` / `list_wiki_nodes` — Wiki
+- `list_wiki_spaces` / `search_wiki` / `list_wiki_nodes` / `get_wiki_node` — Wiki (v1.3.4 adds `get_wiki_node` which resolves a wiki node token to its underlying `obj_type` + `obj_token`, so you can feed the node straight into `read_doc`, bitable tools, etc.)
 - `list_files` / `create_folder` — Drive
 - `copy_file` / `move_file` / `delete_file` — Drive file operations (copy, move, delete)
 - `upload_image` / `upload_file` — Upload image/file, returns key for send_image/send_file
+- `download_image` — Download an image and return it as MCP image content so the model **sees the pixels**. Two modes: (1) **message image** — pass `message_id` + `image_key` from read_messages. (2) **docx image** — pass `image_token` (from `get_doc_blocks` image block) and optionally `doc_token` (native id / wiki node / Feishu URL). Tries UAT first, falls back to app token.
+- `list_user_okrs` / `get_okrs` / `list_okr_periods` — OKR read. UAT-first (works for the authenticated user's OKRs) with app fallback when OKR scope is granted.
+- `list_calendars` / `list_calendar_events` / `get_calendar_event` — Calendar read. UAT-first (primary + shared + subscribed); app identity only sees calendars the bot was explicitly invited to.
 - `find_user` — Contact lookup by email/mobile
 
 ## Usage Patterns
 
+### Wiki-hosted content (docx / bitable / sheet)
+All docx and bitable tools now accept three input forms for their `document_id` / `app_token` parameter:
+- Native token (unchanged): `doccnXXX`, `docxXXX`, `bascnXXX`, ...
+- Wiki node token: `wikcnXXX`, `wikmXXX`, `wiknXXX`
+- Full Feishu URL: `https://xxx.feishu.cn/docx/XXX`, `.../wiki/XXX`, `.../base/XXX`
+The plugin resolves wiki nodes to their underlying `obj_token` via `getWikiNode`, then calls the normal docx / bitable endpoint. Results are cached for 10 min to avoid repeated node lookups.
+
+Create content directly into a Wiki space:
+- `create_doc` / `create_bitable` accept optional `wiki_space_id` (+ `wiki_parent_node_token`). The plugin creates the resource in drive, then calls `wiki/v2/spaces/{space_id}/nodes/move_docs_to_wiki` to attach it — returns `wikiNodeToken` on immediate success, or `wikiAttachTaskId` if Feishu queues the move.
+
+### Document images
+Read — `download_image` with `doc_token` + `image_token` returns the image as MCP image content (base64 + mimeType). `doc_token` accepts native id / wiki node / URL.
+Write — `create_doc_block` now has image shortcuts:
+- `image_path` (absolute local file path) → plugin creates an image block, uploads the pixels via `drive/v1/medias/upload_all`, and patches the block with the uploaded token.
+- `image_token` (already uploaded) → plugin creates block and attaches token.
+`update_doc_block` accepts `image_token` to swap the picture in an existing image block.
+
+### OKR
+1. `list_okr_periods` — find the period id for current quarter.
+2. `list_user_okrs(user_id=<open_id>, period_ids=[...])` — list the target user's OKRs.
+3. `get_okrs(okr_ids)` — batch fetch full objective + key result structure with progress + alignments.
+`user_id` is required — use your own open_id (from `get_login_status` / `search_contacts`) to read your own OKRs, or a colleague's open_id for theirs (subject to permissions).
+
+### Calendar
+1. `list_calendars` — get your calendars; the one with `type=primary` is your personal calendar.
+2. `list_calendar_events(calendar_id, start_time=<unix_sec>, end_time=<unix_sec>)` — list events in a time window.
+3. `get_calendar_event(calendar_id, event_id)` — full details (attendees, location, attachments, meeting link).
+
+### External-group message read (hardened in v1.3.4)
+`read_messages` and `read_p2p_messages` now expose a `via` field in the response (`"bot"`, `"user"`, or `"contacts"`) so callers can tell which identity actually read the data. When bot fails with a known code (external tenant / no permission / not in chat) the plugin hops straight to UAT; transient errors (rate limit / 5xx / ECONNRESET / fetch timeout) retry once with a 2 s delay before falling back. When UAT isn't configured, the error message now tells the user to run `npx feishu-user-plugin oauth` instead of leaking the raw Feishu payload.
+
 ### Messaging
 - Send text as yourself → `send_to_user` or `send_to_group`
 - Send image → `upload_image` → `send_image_as_user`
@@ -233,9 +267,21 @@ Tell user to restart Claude Code. Only ONE restart should be needed.
 ## Troubleshooting Guide
 
 ### If MCP disconnects mid-session
-- **Root cause** (fixed in v1.3.1): `@larksuiteoapi/node-sdk`'s `defaultLogger.error` uses `console.log` (stdout). MCP protocol uses stdout for JSON-RPC, so SDK error logs corrupt the transport and cause immediate disconnect.
-- **Fix**: Custom logger redirects all SDK output to stderr. Already applied in `src/official.js`.
-- If still happening: check for any `console.log` calls in server code (only `console.error` is safe in MCP servers).
+Two known root causes, both fixed in v1.3.3:
+
+1. **stdout pollution** (partial fix in v1.3.1, fully closed in v1.3.3):
+   - `@larksuiteoapi/node-sdk`'s `defaultLogger.error` uses `console.log` (stdout). MCP uses stdout for JSON-RPC, so any stray write corrupts the transport and disconnects the client.
+   - v1.3.1 replaced the SDK's logger. v1.3.3 also globally redirects `console.log` / `console.info` → `console.error` at the top of `src/index.js` as defense-in-depth against ANY future dependency leaking to stdout.
+
+2. **unbounded fetch hangs** (fixed in v1.3.3):
+   - All raw `fetch` calls to `feishu.cn` / `internal-api-lark-api.feishu.cn` used to have no timeout. A stalled connection (ECONNRESET, slow DNS, upstream hang) would block a tool handler indefinitely; the MCP client times out the request, which some clients handle by tearing down the stdio transport — observed as "mid-session disconnect".
+   - Fix: `utils.js::fetchWithTimeout` with `AbortController`, 30s default. All `client.js` + `official.js` fetches go through it.
+   - If still happening: check for any `console.log` calls in server code (only `console.error` is safe), and grep for raw `await fetch(` — every one must go through `fetchWithTimeout`.
+
+### If Official API tools return 401 / "token invalid" every time
+- **Likely cause**: `LARK_APP_ID` is wrong or stale. Observed in production: Claude Code auto-installed the plugin and guessed/copied a wrong APP_ID that doesn't match the team's real app (e.g. from an unrelated app, from someone else's machine, or hallucinated).
+- **Diagnosis**: `get_login_status` now reports `App credentials: INVALID — app_id=<x> rejected by Feishu (<code>: <msg>)`. MCP startup logs `[feishu-user-plugin] ERROR: LARK_APP_ID=<x> was REJECTED by Feishu` on stderr when this happens.
+- **Fix**: Re-run the canonical install prompt from `team-skills/plugins/feishu-user-plugin/README.md` which contains the correct APP_ID/SECRET, and restart Claude Code.
 
 ### If MCP tools are not available
 1. Check `~/.claude.json` — config must be in **top-level** `mcpServers`, not inside `projects[*]`
@@ -346,6 +392,7 @@ When making ANY code change (new tools, bug fixes, features), update ALL of thes
 
 **本仓库内：**
 - `CLAUDE.md` — tool count, tool list, usage patterns, known limitations
+- `AGENTS.md` — **每次改 CLAUDE.md 必须同步**：正文（第 2 行起）与 CLAUDE.md 完全一致，仅首行标题保留 `# feishu-user-plugin — Codex Instructions`。同步命令：`tail -n +2 CLAUDE.md > /tmp/body.md && { echo "# feishu-user-plugin — Codex Instructions"; cat /tmp/body.md; } > AGENTS.md`
 - `README.md` — tool count (badge + heading + tool table), feature highlights, OpenClaw/Claude Code config examples
 - `ROADMAP.md` — check off completed items, add new findings
 - `package.json` — version, description (tool count)
@@ -408,6 +455,55 @@ Steps:
 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
+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.
+
+**Structure** (in this order; omit a section if it doesn't apply this release):
+
+```
+feishu-user-plugin vX.Y.Z 发布
+
+<一到两句开篇总结本次发布的主题，陈述语气，不推销>
+
+修复
+• <缺陷描述>：<根因与修复机制，引用具体错误码/接口名/参数>
+• ...
+
+新增
+• 新增 <tool 名> 工具：<一句话功能描述>。<关键约束或调用条件>
+• ...
+
+调整
+• <行为变化的描述>
+• ...
+
+下版本计划
+• <条目>
+• ...
+
+升级方式
+• 重启 Claude Code / Codex 即可自动拉取 X.Y.Z
+• <若有相关新日志/错误提示，说明怎么应对>
+• 建议复测 N 个场景：<场景 1>、<场景 2>、<场景 3>
+```
+
+**写作规范**:
+- **开篇**：一到两句陈述式总结，不宣传、不夸大。参考 v1.3.2："本次更新主要补齐了 X 能力，并修复了 Y 问题；同时将 Z 统一调整为 ..."
+- **每条 bullet**：先写用户可见现象，再写底层机制。引用具体错误码（如 1770032 / 91403）、接口名（如 create_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` 到目标群。
 
 ### Syncing to team-skills (after any CLAUDE.md or skills change)
 1. Copy CLAUDE.md to skill reference: `cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md`
@@ -421,6 +517,19 @@ Steps:
 - For Cookie tools: need active session, test via MCP tool call
 - Always verify `_safeSDKCall` handles the response format (multipart uploads return data at top level, not nested under `.data`)
 
+## OAuth Scopes (when re-running `npx feishu-user-plugin oauth`)
+
+The v1.3.4 tools require additional scopes on the app + UAT:
+
+| Feature | Scopes to enable on app + include in OAuth |
+|---------|-------------------------------------------|
+| OKR read | `okr:okr:readonly`, `okr:period:read` |
+| Calendar read | `calendar:calendar:readonly`, `calendar:calendar.event:read` |
+| Docx image write (`uploadDocMedia`) | `drive:drive`, `docx:document`, `docx:document:readonly` (image upload piggy-backs on existing docx editing scopes) |
+| Wiki attach (`move_docs_to_wiki`) | `wiki:wiki` (edit scope, the readonly one is insufficient) |
+
+If a tool returns `access_denied` or error code `99991672` (scope not granted), enable the missing scope at https://open.feishu.cn/app → Permissions, then re-run `npx feishu-user-plugin oauth` so the UAT picks up the new scopes.
+
 ## Known Limitations
 - CARD message type (type=14) not yet implemented — complex JSON schema
 - External tenant users may not be resolvable via `get_user_info` (contact API scope limitation)

package/src/client.js

@@ -1,6 +1,6 @@
 const path = require('path');
 const protobuf = require('protobufjs');
-const { generateRequestId, generateCid, parseCookie, formatCookie } = require('./utils');
+const { generateRequestId, generateCid, parseCookie, formatCookie, fetchWithTimeout } = require('./utils');
 
 const GATEWAY_URL = 'https://internal-api-lark-api.feishu.cn/im/gateway/';
 const CSRF_URL = 'https://internal-api-lark-api.feishu.cn/accounts/csrf';
@@ -47,7 +47,7 @@ class LarkUserClient {
   // --- Auth ---
 
   async _getCsrfToken() {
-    const res = await fetch(`${CSRF_URL}?_t=${Date.now()}`, {
+    const res = await fetchWithTimeout(`${CSRF_URL}?_t=${Date.now()}`, {
       method: 'POST',
       headers: {
         ...this._jsonHeaders(),
@@ -68,7 +68,7 @@ class LarkUserClient {
   }
 
   async _getUserInfo() {
-    const res = await fetch(`${USER_INFO_URL}?app_id=12&_t=${Date.now()}`, {
+    const res = await fetchWithTimeout(`${USER_INFO_URL}?app_id=12&_t=${Date.now()}`, {
       headers: {
         ...this._jsonHeaders(),
         'x-csrf-token': this.csrfToken || '',
@@ -179,7 +179,7 @@ class LarkUserClient {
       cid: generateRequestId(),
       payload: reqBuf,
     });
-    const res = await fetch(GATEWAY_URL, {
+    const res = await fetchWithTimeout(GATEWAY_URL, {
       method: 'POST',
       headers: this._protoHeaders(cmd, cmdVersion),
       body: packetBuf,

package/src/doc-blocks.js

@@ -0,0 +1,70 @@
+// Helpers for constructing docx block payloads.
+//
+// Right now (v1.3.4) only the image path is implemented — enough to cover the
+// create_doc_block / update_doc_block image shortcuts. More block builders
+// (heading / list / code / table) will land in v1.3.5 when the local-markdown
+// → wiki-docx sync feature is built; parking the skeleton here now so the
+// later additions don't introduce a new file.
+
+// docx v1 block_type enum (relevant subset).
+// Docs: https://open.feishu.cn/document/server-docs/docs/docs/docx-v1/document-block/create
+const BLOCK_TYPE = {
+  PAGE:        1,
+  TEXT:        2,
+  HEADING1:    3,
+  HEADING2:    4,
+  HEADING3:    5,
+  HEADING4:    6,
+  HEADING5:    7,
+  HEADING6:    8,
+  HEADING7:    9,
+  HEADING8:   10,
+  HEADING9:   11,
+  BULLET:     12,
+  ORDERED:    13,
+  CODE:       14,
+  QUOTE:      15,
+  EQUATION:   16,
+  TODO:       17,
+  BITABLE:    18,
+  CALLOUT:    19,
+  CHAT_CARD:  20,
+  DIAGRAM:    21,
+  DIVIDER:    22,
+  FILE:       23,
+  GRID:       24,
+  GRID_COL:   25,
+  IFRAME:     26,
+  IMAGE:      27,
+  TABLE:      31,
+};
+
+/**
+ * The image-block creation flow on Feishu docx v1 is three steps:
+ *   1. POST .../blocks/<parent>/children with an empty image placeholder:
+ *        { block_type: 27, image: {} }
+ *      This returns a real block_id for the image slot.
+ *   2. POST /open-apis/drive/v1/medias/upload_all with parent_type=docx_image
+ *      and parent_node=<that block_id> to upload the pixels. Returns file_token.
+ *   3. PATCH .../blocks/<block_id> with { replace_image: { token: file_token } }
+ *      to populate the placeholder with the uploaded image.
+ *
+ * See official.js::createDocBlockWithImage which orchestrates all three steps.
+ */
+
+/** Empty image block used as the placeholder in step 1. */
+function buildEmptyImageBlock() {
+  return { block_type: BLOCK_TYPE.IMAGE, image: {} };
+}
+
+/** Patch body for step 3 — attaches an uploaded image_token to a placeholder block. */
+function buildReplaceImagePayload(imageToken) {
+  if (!imageToken) throw new Error('buildReplaceImagePayload: imageToken is required');
+  return { replace_image: { token: imageToken } };
+}
+
+module.exports = {
+  BLOCK_TYPE,
+  buildEmptyImageBlock,
+  buildReplaceImagePayload,
+};

package/src/error-codes.js

@@ -0,0 +1,78 @@
+// Feishu error-code classification for read_messages fallback routing.
+//
+// The v1.3.2 read_messages handler catches any bot failure and unconditionally
+// retries with UAT. That's cheap when the bot fails fast, but it has two flaws
+// in v1.3.3:
+//   • Transient errors (rate-limit, network stalls) are treated the same as
+//     permanent permission errors — the UAT path runs when a 2-second retry
+//     would have worked.
+//   • When UAT is absent, the raw Feishu payload leaks to the user verbatim,
+//     with no hint that OAuth is the fix.
+//
+// This table classifies known codes into three buckets:
+//   'uat'     — permanent bot failure; hop straight to UAT.
+//   'retry'   — likely transient; caller should retry once (after short delay)
+//               and fall through to UAT if still failing.
+//   'unknown' — not seen before; preserve v1.3.3 behaviour (try UAT silently).
+
+const FAILURE_MAP = {
+  // External tenant — bot lives in a different tenant, will never be granted.
+  240001: { action: 'uat', reason: 'bot_external_tenant' },
+  // No permission for the resource (scope missing, or chat restricts bot reads).
+  70009:  { action: 'uat', reason: 'bot_no_permission' },
+  // Bot is not a member of the chat.
+  70003:  { action: 'uat', reason: 'bot_not_in_chat' },
+  99991668: { action: 'uat', reason: 'bot_not_in_chat' },
+  // Chat does not exist (from the bot's POV — may still be accessible to user).
+  19001:  { action: 'uat', reason: 'bot_chat_not_found' },
+
+  // Rate limited — Feishu throttles, try once more after a brief pause.
+  42101:  { action: 'retry', reason: 'bot_rate_limited' },
+  // Frequency control variants occasionally observed.
+  99991400: { action: 'retry', reason: 'bot_rate_limited' },
+};
+
+// HTTP-status / network-error patterns that warrant one retry.
+// Axios-wrapped messages from @larksuiteoapi/node-sdk embed the http status
+// into _safeSDKCall's rethrown message. We match those substrings.
+const TRANSIENT_PATTERNS = [
+  /HTTP 5\d\d/i,         // Any 5xx from upstream
+  /ECONNRESET/i,
+  /ETIMEDOUT/i,
+  /fetch timeout after/i, // from utils.fetchWithTimeout
+  /socket hang up/i,
+];
+
+/**
+ * Classify an error thrown by a bot-API path.
+ * Input is either the Feishu code number (preferred) or the Error object —
+ * the code is extracted from the message if present.
+ *
+ * Output: { action: 'uat' | 'retry' | 'unknown', reason: string, code: number|null }
+ */
+function classifyError(errOrCode) {
+  let code = null;
+  let msg = '';
+  if (typeof errOrCode === 'number') {
+    code = errOrCode;
+  } else if (errOrCode && typeof errOrCode === 'object') {
+    msg = errOrCode.message || String(errOrCode);
+    // _safeSDKCall formats as "label failed (HTTP N, code=XXX): ..." or "label failed (CODE): ..."
+    const m = msg.match(/code[=(]\s*(\d+)/i) || msg.match(/failed\s*\((\d+)\)/i);
+    if (m) code = parseInt(m[1], 10);
+  }
+
+  if (code != null && FAILURE_MAP[code]) {
+    return { ...FAILURE_MAP[code], code };
+  }
+  for (const re of TRANSIENT_PATTERNS) {
+    if (re.test(msg)) return { action: 'retry', reason: 'bot_network_error', code };
+  }
+  return { action: 'unknown', reason: 'bot_unknown_error', code };
+}
+
+module.exports = {
+  classifyError,
+  FAILURE_MAP,
+  TRANSIENT_PATTERNS,
+};