feishu-user-plugin 1.3.5 → 1.3.7

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

@@ -2,22 +2,40 @@
 
 ## What This Is
 All-in-one Feishu plugin for Claude Code with three auth layers:
-- **User Identity** (cookie auth): Send messages (text, image, file, post, sticker, audio) as yourself
+- **User Identity** (cookie auth): Send messages (text, image, file, post) as yourself
 - **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 (75 tools)
+## MCP Prompts (v1.3.7)
+
+The 9 Claude Code skills are also exposed as MCP prompts (`prompts/list` + `prompts/get`) so Codex, Cursor, OpenClaw, and Windsurf — which cannot load Claude Code skills — get the same guided UX. Prompt bodies are read at server start from `skills/feishu-user-plugin/references/`.
+
+| Prompt | Description |
+|--------|-------------|
+| `/send` | Send a message as yourself (non-bot) |
+| `/reply` | Read recent messages and reply |
+| `/digest` | Summarise recent group or P2P messages |
+| `/search` | Search Feishu contacts or groups |
+| `/doc` | Search, read, or create a Feishu document |
+| `/table` | Operate on a Feishu Bitable (multi-dimensional table) |
+| `/wiki` | Search and browse a Feishu Wiki space |
+| `/drive` | List files or create folders in Feishu Drive |
+| `/status` | Check all three auth layers (cookie, app, UAT) |
+
+Each prompt accepts a single `arguments` free-form string (mirroring the `$ARGUMENTS` convention used by Claude Code skills). `status` has no arguments.
+
+## Tool Categories (80 tools)
 
 ### User Identity — Messaging (reverse-engineered, cookie-based)
 - `send_to_user` — Search user + send text (one step, most common). Returns candidates if multiple matches.
 - `send_to_group` — Search group + send text (one step). Returns candidates if multiple matches.
+- `batch_send` — Fan-out send to multiple targets in one call (text/image/file/post). Each target {type, id, content, via?} dispatches sequentially with throttling, returns per-target ok/error.
 - `send_as_user` — Send text to any chat by ID, supports reply threading (root_id/parent_id)
 - `send_image_as_user` — Send image (requires image_key from `upload_image`)
 - `send_file_as_user` — Send file (requires file_key from `upload_file`)
 - `send_post_as_user` — Send rich text with title + formatted paragraphs. Elements: `{tag:"text"}`, `{tag:"a",href,text}`, `{tag:"at",userId,name}`. **@-mentions trigger real notifications** (fixed by registering AT element IDs in RichText.atIds field 6 — reverse-engineered from Feishu Web bundle's AtProperty + RichText schemas).
 - `send_as_user` / `send_to_user` / `send_to_group` — plain text sends now accept optional `ats: [{userId, name}]`; the text must contain the `@<name>` marker for each entry. The marker is spliced into a real AT element so the mentioned user is notified. Identity is the cookie user (not bot).
-- `send_sticker_as_user` — Send sticker/emoji
-- `send_audio_as_user` — Send audio message
+- **Cookie sends accept oc_xxx chat IDs (v1.3.7 C1.4)**: `send_as_user`, `send_image_as_user`, `send_file_as_user`, `send_post_as_user`, `send_card_as_user`, and `batch_send` previously required numeric chat IDs from `create_p2p_chat` / cookie search. They now auto-resolve `oc_xxx` via `getChatInfo(name) → cookie search(name) → numeric id` and cache the mapping. Numeric IDs still work and skip the resolver. If resolution fails (chat not in your search index, no group with matching name), the tool throws a clear error with remediation guidance.
 
 ### User Identity — Contacts & Info
 - `search_contacts` — Search users/groups by name
@@ -29,34 +47,39 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 ### User OAuth UAT Tools (P2P chat reading + user-identity creation)
 - `read_p2p_messages` — Read P2P (direct message) chat history. chat_id accepts both numeric IDs (from create_p2p_chat) and oc_xxx format. Returns newest messages first by default.
 - `list_user_chats` — List group chats the user is in. Note: API only returns groups, not P2P. For P2P, use: `search_contacts` → `create_p2p_chat` → `read_p2p_messages`.
-- **All docx + bitable + drive create/read/write tools are UAT-first**: when UAT is configured, every operation (create/edit/delete doc blocks, bitable tables/fields/views/records, drive folders) tries the user's token first and falls back to app token on failure. This keeps resources consistently owned by the user and avoids 403 errors when the app can't access user-created resources. Read-only tools (e.g. `read_doc`, `get_doc_blocks`, `list_bitable_tables`) are also UAT-first so user-owned resources remain readable.
+- **All docx + bitable + drive create/read/write tools are UAT-first**: when UAT is configured, every operation (create/edit/delete doc blocks, bitable tables/fields/views/records, drive folders) tries the user's token first and falls back to app token on failure. This keeps resources consistently owned by the user and avoids 403 errors when the app can't access user-created resources. Read-only tools (e.g. `read_doc`, `get_doc_blocks`, `manage_bitable_table(action=list)`) are also UAT-first so user-owned resources remain readable.
 
 ### Official API Tools (app credentials)
 - `list_chats` / `read_messages` — Chat history (read_messages accepts chat name, oc_ ID, or numeric ID; auto-resolves via bot's group list → im.chat.search → search_contacts). **Auto-falls back to UAT for external groups the bot cannot access.** Returns newest messages first by default. Messages include sender names. **v1.3.5**: `merge_forward` messages now auto-expand into their child messages (2 images + 4 texts, with original sender / time / origin chat preserved); text messages get `urls[]` + `feishuDocs[]` extracted so agents can feed them straight into `read_doc` / WebFetch. Disable expansion with `expand_merge_forward=false`.
 - `send_message_as_bot` — Bot sends message to any chat (text, post, interactive, etc.)
-- `reply_message` / `forward_message` — Message operations (as bot)
-- `delete_message` / `update_message` — Recall or edit bot's own messages
+- `reply_message` / `forward_message` — Message operations (as bot). `forward_message` accepts `receive_id_type` (chat_id/open_id/union_id/user_id/email; auto-detects when omitted by inspecting the receive_id prefix).
+- `delete_message` / `update_message` — Recall or edit bot's own messages. `update_message` only supports `msg_type=text` or `interactive` (Feishu API limit; other types are rejected with a clear error before hitting the API).
 - `add_reaction` / `delete_reaction` — Emoji reactions on messages
 - `pin_message` — Pin or unpin a message (pinned=true/false)
 - `create_group` / `update_group` — Create and manage group chats
-- `list_members` / `manage_members` — Group membership (manage_members: action=add/remove)
+- `list_members` / `manage_members` — Group membership (manage_members: action=add/remove, member_id_type=open_id|union_id|user_id — default open_id; pass union_id/user_id explicitly when your member_ids use those formats, otherwise Feishu rejects with code 9499)
 - `search_docs` / `read_doc` / `get_doc_blocks` / `create_doc` — Document operations
-- `create_doc_block` / `update_doc_block` / `delete_doc_blocks` — Document content editing (insert/update/delete blocks)
-- `create_bitable` / `get_bitable_meta` / `copy_bitable` — Bitable app management (create, get info, copy)
-- `list_bitable_tables` / `create_bitable_table` / `update_bitable_table` / `delete_bitable_table` — Table management (CRUD + rename)
-- `list_bitable_fields` / `create_bitable_field` / `update_bitable_field` / `delete_bitable_field` — Field (column) management
-- `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` / `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.)
+- `manage_doc_block(action=create|update|delete)` — Document content editing (v1.3.7 consolidates v1.3.6 create_doc_block / update_doc_block / delete_doc_blocks). Image + file shortcuts (`image_path`/`image_token`/`file_path`/`file_token`) flow through unchanged.
+- `manage_bitable_app(action=create|copy|get_meta)` — Bitable app management. v1.3.7 consolidates create_bitable / copy_bitable / get_bitable_meta.
+- `manage_bitable_table(action=list|create|update|delete)` — Table CRUD + rename.
+- `manage_bitable_field(action=list|create|update|delete)` — Field (column) management. Feishu requires `type` for both create AND update (rename).
+- `manage_bitable_view(action=list|create|delete)` — Views (grid / kanban / gallery / form / gantt / calendar).
+- `manage_bitable_record(action=search|get|create|update|delete)` — Record CRUD. create/update/delete accept arrays (single or up to 500 per call).
+- `list_wiki_spaces` / `search_wiki` / `list_wiki_nodes` / `get_wiki_node` — Wiki read (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. v1.3.7 hardens this: `get_wiki_node` now also accepts underlying `obj_token`s from `search_wiki` (synthesizes a node-shape so callers don't have to know which ID space they hold), and `list_wiki_spaces` is UAT-first with a `scopeHint` field surfaced when the bot returns an empty list — typically because `wiki:wiki:readonly` is missing or the bot was never invited.)
+- `create_wiki_node` / `update_wiki_node` / `move_wiki_node` / `copy_wiki_node` / `delete_wiki_node` — Wiki write (v1.3.7). UAT-first so resources are owned by the user. `create_wiki_node` builds a fresh `doc/sheet/bitable/mindnote/file/docx/slides` inside a wiki space (or a `node_type=shortcut` pointer to an existing node). `update_wiki_node` renames (only `title` is updatable via wiki API; content edits go through docx/bitable/sheet tools). `move_wiki_node` and `copy_wiki_node` accept `target_parent_token` + optional `target_space_id` to re-parent within the same space or migrate to another. `delete_wiki_node` calls `DELETE /open-apis/wiki/v2/spaces/{space_id}/nodes/{token}` via raw REST (the SDK doesn't type it); **only the wiki node pointer is removed — the underlying drive resource is NOT deleted**, follow up with `manage_drive_file(action=delete, type=...)` if you also want the resource gone.
 - `list_files` / `create_folder` — Drive
-- `copy_file` / `move_file` / `delete_file` — Drive file operations (copy, move, delete)
+- `manage_drive_file(action=copy|move|delete)` — Drive file operations (v1.3.7 consolidates v1.3.6 copy_file / move_file / delete_file). UAT-first. `type` is always required (`file/folder/docx/sheet/bitable/mindnote/slides`) — Feishu rejects with 1061002 / 1062501 otherwise.
 - `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. **merge_forward children**: use the child's `parentMessageId` (NOT the child id) — Feishu returns `File not in msg` with the child id.
-- `download_file` — Download a file (msg_type=file) attachment. Returns base64 + mimeType + byte count; optional `save_path` writes the file to disk. Same parent-id rule for merge_forward children as download_image.
+- `upload_drive_file` — Upload a local file into a Drive folder (`drive/v1/files/upload_all`, `parent_type=explorer`). Returns `file_token` + `url`. If `wiki_space_id` is provided, the upload is followed by `attachToWiki(obj_type=file)` so the file lands as a Wiki node atomically. UAT-first with bot fallback.
+- `upload_bitable_attachment` — Upload a local file as a Bitable attachment (`drive/v1/medias/upload_all` with `parent_type=bitable_image` or `bitable_file`). Returns `file_token` to write into an Attachment-type field via `manage_bitable_record(action=create|update, records=[{fields:{<attachment_field>:[{file_token:"..."}]}}])`.
+- `send_card_as_user` — Send a Feishu interactive card. **v1.3.6 default routes through bot identity** (the `as_user` suffix is reserved for the v1.3.7 reverse-engineered cookie path; default flips when that lands). Pass `card` JSON; `via="user"` returns an explicit deferred error in v1.3.6.
+- `download_message_resource` — Download a message-attached image OR file. v1.3.7 (C2.4) consolidates v1.3.6 download_image (message-mode) + download_file. Args: `message_id`, `key` (image_key or file_key), `kind=image|file`, optional `save_path`. **Payloads > 2 MiB MUST pass save_path** — the Anthropic API rejects responses > 5 MB; we cap at 2 MiB so the inline image / base64 has multipart headroom. Tries UAT first, falls back to app. **merge_forward children**: use the child's `parentMessageId` (NOT the child id) — Feishu returns `File not in msg` with the child id.
+- `download_doc_image` — Download an image embedded in a docx document so the model sees pixels. Args: `image_token` (from `get_doc_blocks` image block), optional `doc_token` (native id / wiki node / Feishu URL — recommended for permission scoping), optional `save_path`. Same 2 MiB inline cap as `download_message_resource`. UAT-first.
 - `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.
+- `create_okr_progress_record` / `list_okr_progress_records` / `delete_okr_progress_record` — OKR progress writes (v1.3.7). UAT-first. Requires `okr:okr.content:write` scope. `create_okr_progress_record` accepts a simplified `content_text` (auto-wrapped into the Feishu block schema) plus optional `source_title` / `source_url` / `progress_percent`. `list_okr_progress_records` extracts progress_record IDs from `get_okrs` since Feishu has no native list endpoint.
 - `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
+- `create_calendar_event` / `update_calendar_event` / `delete_calendar_event` / `respond_calendar_event` / `get_freebusy` — Calendar write (v1.3.7). UAT-first. Requires `calendar:calendar.event:write` scope (re-run `npx feishu-user-plugin oauth` after enabling on the app console). `get_freebusy` is a query, not a write, but groups here for the calendar domain.
+- `list_tasks` / `get_task` / `create_task` / `update_task` / `complete_task` / `delete_task` / `manage_task_members` — Task v2 (new domain in v1.3.7). UAT-first. Requires `task:task` scope. v2 uses `task_guid` as the identifier (not numeric task_id like v1). `update_task` requires an explicit `update_fields` array (Feishu only patches the listed fields). `complete_task(completed=true|false)` is a convenience wrapper around `update_task` setting `completed_at`.
 
 ## Usage Patterns
 
@@ -68,14 +91,14 @@ All docx and bitable tools now accept three input forms for their `document_id`
 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.
+- `create_doc` / `manage_bitable_app(action=create)` 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:
+Read — `download_doc_image(image_token, doc_token?, save_path?)` returns the image as MCP image content (base64 + mimeType). `doc_token` accepts native id / wiki node / URL. Force `save_path` when image > 2 MiB.
+Write — `manage_doc_block(action=create)` 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.
+`manage_doc_block(action=update, image_token=...)` swaps the picture in an existing image block.
 
 ### OKR
 1. `list_okr_periods` — find the period id for current quarter.
@@ -83,10 +106,30 @@ Write — `create_doc_block` now has image shortcuts:
 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).
 
+Write (v1.3.7, requires `okr:okr.content:write` scope):
+4. `create_okr_progress_record(target_id, target_type=1|2, content_text, source_title?, source_url?, progress_percent?)` — `target_type` is 1 for objectives, 2 for key results. `content_text` is auto-wrapped into Feishu's required block format; pass `content` directly for richer payloads (lists, mentions, docs links, gallery).
+5. `list_okr_progress_records(okr_id)` — extracts `{progress_id, target_id, target_type}` triples from `get_okrs` (Feishu has no native list endpoint).
+6. `delete_okr_progress_record(progress_id)`.
+
 ### 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).
+4. `create_calendar_event(calendar_id, summary, start_time, end_time, ...)` — `start_time` / `end_time` are objects: `{timestamp:"<unix-seconds>", timezone?:"Asia/Shanghai"}` or `{date:"YYYY-MM-DD"}` for all-day. v1.3.7+ requires `calendar:calendar.event:write` scope.
+5. `update_calendar_event(calendar_id, event_id, ...patch)` — pass only the fields to change.
+6. `delete_calendar_event(calendar_id, event_id, need_notification?)` — pass `meeting_chat_id` to also dissolve the linked meeting chat if any.
+7. `respond_calendar_event(calendar_id, event_id, rsvp_status=accept|decline|tentative)` — RSVP as the current UAT identity.
+8. `get_freebusy(time_min, time_max, user_ids=[...])` — freebusy windows in RFC3339; useful for finding meeting slots.
+
+### Tasks (v2, v1.3.7)
+Whole new domain. Identifier is `task_guid` (not numeric task_id like v1). Requires `task:task` scope.
+1. `list_tasks(completed?, type?)` — current user's tasks, paginated.
+2. `get_task(task_guid)` — full details.
+3. `create_task(summary, due?, members?, ...)` — at minimum `summary`; `due` is `{timestamp:"<unix-millis>", is_all_day?}`.
+4. `update_task(task_guid, update_fields=["summary","due","completed_at"], task={...})` — Feishu only patches the listed fields.
+5. `complete_task(task_guid, completed=true|false)` — convenience for the completed_at toggle.
+6. `delete_task(task_guid)`.
+7. `manage_task_members(action=add|remove, task_guid, members=[{id,role:"assignee"|"follower",type?:"user",name?}])`.
 
 ### 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.
@@ -107,15 +150,15 @@ Write — `create_doc_block` now has image shortcuts:
 - Get chat details → `get_chat_info` (supports both oc_xxx and numeric ID)
 
 ### Bitable (Multi-dimensional Tables)
-- Create a bitable from scratch → `create_bitable` → `create_bitable_table` → `create_bitable_field`
-- Get bitable info → `get_bitable_meta`
-- Copy a bitable → `copy_bitable` with name and optional folder
-- Query data → `list_bitable_tables` → `list_bitable_fields` → `search_bitable_records`
-- Rename table → `update_bitable_table` with new name
-- Read single record → `get_bitable_record`
-- Create/update/delete records → `batch_create_bitable_records` / `batch_update_bitable_records` / `batch_delete_bitable_records` (works for single or up to 500)
-- Manage fields → `create_bitable_field` / `update_bitable_field` (requires type param) / `delete_bitable_field`
-- Manage views → `create_bitable_view` (type: grid/kanban/gallery/form/gantt/calendar) / `delete_bitable_view`
+All bitable ops collapse into 5 `manage_bitable_*` tools (v1.3.7) — pick the action.
+- Create from scratch → `manage_bitable_app(action=create)` → `manage_bitable_table(action=create)` → `manage_bitable_field(action=create)`
+- Get info → `manage_bitable_app(action=get_meta)`
+- Duplicate → `manage_bitable_app(action=copy, name=..., folder_id?)`
+- Query → `manage_bitable_table(action=list)` → `manage_bitable_field(action=list)` → `manage_bitable_record(action=search, filter?, sort?, page_size?)`
+- Read single record → `manage_bitable_record(action=get, record_id=...)`
+- Records CRUD → `manage_bitable_record(action=create|update|delete, records|record_ids=[...])` (single or up to 500/call)
+- Fields → `manage_bitable_field(action=create|update|delete, ...)` — `type` required for both create AND update (rename)
+- Views → `manage_bitable_view(action=list|create|delete, view_type=grid|kanban|gallery|form|gantt|calendar)`
 
 ### Group Management
 - Create a group → `create_group` with name and optional member open_ids
@@ -123,21 +166,47 @@ Write — `create_doc_block` now has image shortcuts:
 - List members → `list_members`
 
 ### Document Editing
-- Create doc with content → `create_doc` → `create_doc_block` (use document_id as parent_block_id for root)
-- Edit existing block → `get_doc_blocks` to find block_id → `update_doc_block`
-- Delete blocks → `delete_doc_blocks` with start/end index range
+All block ops go through one tool: `manage_doc_block(action=create|update|delete, ...)`.
+- Create doc with content → `create_doc` → `manage_doc_block(action=create, parent_block_id=document_id, children=[...])`
+- Edit existing block → `get_doc_blocks` to find block_id → `manage_doc_block(action=update, block_id=..., update_body={...})`
+- Delete blocks → `manage_doc_block(action=delete, parent_block_id=..., start_index=..., end_index=...)`
+- Insert image → `manage_doc_block(action=create, parent_block_id=..., image_path=...)` (local file) or `image_token=...` (already uploaded). Three-step flow handled internally.
+- Insert file attachment (PDF/zip/xlsx/...) → `manage_doc_block(action=create, file_path=...)` or `file_token=...`. Feishu auto-wraps the FILE block (block_type=23) inside a VIEW container (block_type=33); the plugin walks into the inner file block automatically before the `replace_file` PATCH so the upload + attach succeed.
+- Replace existing image/file → `manage_doc_block(action=update, block_id=..., image_token=... | file_token=...)`.
 
 ### Diagnostics
 - Diagnose issues → `get_login_status` first
 
+### Profiles (v1.3.6)
+Multi-account / multi-tenant support without restarting the MCP server:
+- `list_profiles` — see all profiles + the active one. Default profile uses top-level env vars; extras come from `LARK_PROFILES_JSON`.
+- `switch_profile(name)` — hot-swap credentials. Cached client instances are invalidated so the next call rebuilds against the new profile.
+
+To register more profiles, set `LARK_PROFILES_JSON` in the MCP env:
+```json
+{"alt": {"LARK_COOKIE":"...","LARK_APP_ID":"...","LARK_APP_SECRET":"...","LARK_USER_ACCESS_TOKEN":"...","LARK_USER_REFRESH_TOKEN":"..."}}
+```
+
 ## Auth & Session
-- **LARK_COOKIE**: Required for user identity tools. Session auto-refreshed every 4h via heartbeat and persisted to config.
+- **LARK_COOKIE**: Required for user identity tools. Session auto-refreshed every 4h via heartbeat and persisted to credentials store.
 - **LARK_APP_ID + LARK_APP_SECRET**: Required for official API tools.
-- **LARK_USER_ACCESS_TOKEN + LARK_USER_REFRESH_TOKEN**: Required for P2P reading. Auto-refreshed on expiry (error codes 99991668/99991663/99991677). Token auto-persisted to MCP config on refresh.
+- **LARK_USER_ACCESS_TOKEN + LARK_USER_REFRESH_TOKEN**: Required for P2P reading. Auto-refreshed on expiry (error codes 99991668/99991663/99991677). Token auto-persisted to credentials store on refresh.
 - 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.
 
+### 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.
+
+Opt-in migration:
+```bash
+npx feishu-user-plugin migrate              # dry-run (default) — prints what would be written
+npx feishu-user-plugin migrate --confirm    # writes credentials.json
+```
+After migration the harness env blocks remain as backward-compat fallback. Delete `~/.feishu-user-plugin/credentials.json` to revert to legacy behaviour.
+
+Backward compat: v1.3.6 users without credentials.json see zero behaviour change. The credentials file is preferred only when it exists. The MCP server's `Auth:` startup line on stderr now shows the source (`credentials.json profile=default` vs `env vars (legacy)`) so you can tell at a glance which path is active.
+
 ## Required Environment Variables (ALL are required for full functionality)
 
 | Variable | Purpose |
@@ -321,7 +390,7 @@ Two known root causes, both fixed in v1.3.3:
 - **Manual cleanup when you notice**: `pkill -f 'feishu-user-plugin/src/index.js'` — the client will respawn one fresh process on the next tool call.
 
 ### If a create_* tool warns "UAT failed, created as BOT"
-- v1.3.5 added an explicit `⚠️` warning to MCP responses whenever `_asUserOrApp` silently fell back to bot identity for a write (create_doc / create_bitable / create_folder / create_doc_block / ...). Before v1.3.5 this was silent and led to the "teammate can read my 'private' doc" issue.
+- v1.3.5 added an explicit `⚠️` warning to MCP responses whenever `_asUserOrApp` silently fell back to bot identity for a write (create_doc / manage_bitable_app(action=create) / create_folder / manage_doc_block(action=create) / ...). Before v1.3.5 this was silent and led to the "teammate can read my 'private' doc" issue.
 - **Cause**: your UAT is failing (expired / scope missing / race) so the plugin reached for bot credentials. The resulting resource is owned by the shared bot, tenant-readable by default, NOT by you.
 - **Fix**: run `npx feishu-user-plugin oauth` and restart Claude Code / Codex. If the resource needs to be yours, delete the bot-owned copy and recreate after UAT is valid.
 
@@ -377,59 +446,42 @@ NPM_TOKEN is stored as a GitHub repo secret.
 
 **IMPORTANT: team-skills 仓库禁止直接推送 main。所有变更必须走 PR。**
 
-team-skills 推送规范:
-1. **创建 feature branch**: `git checkout -b fix/feishu-xxx` 或 `sync/feishu-v1.x.x`
-2. **提交变更并推送 branch**: `git push -u origin <branch-name>`
-3. **创建 PR 并设置 auto-merge**: `gh pr create --title "..." --body "..."` 然后 `gh pr merge <number> --auto --merge`
-4. **CI 通过后自动合并**: validate workflow 检查三方版本一致性,通过即自动 merge,无需手动操作
-5. **如 CI 失败**: 修复后 push 到同一 branch,CI 会重跑,通过后自动合并
+What is automatic now (Phase B3 hooks):
+- **pre-commit (this repo)**: any change to `CLAUDE.md` auto-syncs `AGENTS.md` + `skills/feishu-user-plugin/references/CLAUDE.md` (script: `scripts/sync-claude-md.sh`).
+- **post-merge (this repo, on main)**: copies `skills/` + `.claude-plugin/plugin.json` into `team-skills/plugins/feishu-user-plugin/`, creates `sync/feishu-v<version>` branch, opens a PR with `--auto --merge` (script: `scripts/sync-team-skills.sh`).
 
-三方版本一致性规则:
-- `plugins/feishu-user-plugin/.claude-plugin/plugin.json` 的 `version`
-- `plugins/feishu-user-plugin/skills/feishu-user-plugin/SKILL.md` frontmatter 的 `version`
-- `plugins/feishu-user-plugin/README.md` 更新日志里第一个 `### vX.Y.Z` 标题
-- 这三个版本号必须相同,否则 CI 会失败。每次 npm 发包后,team-skills 的版本号也要同步更新。
+What still needs a manual touch in team-skills:
+- `README.md` — team-skills has its own README (with team-shared APP_ID/SECRET hardcoded). Tool count, changelog, install prompt all need hand edits.
+- `skills/feishu-user-plugin/SKILL.md` — version + `allowed-tools` list.
 
-同步内容（每次发版后执行）:
+team-skills PR 流程:
+1. 创建 branch: `git checkout -b sync/feishu-v1.x.x` 或 `fix/feishu-xxx`
+2. push branch + `gh pr create` + `gh pr merge <number> --auto --merge`
+3. CI (`validate.yml`) checks the three-way version triangle (`plugin.json` / `SKILL.md` / first `### vX.Y.Z` in README) — must match or CI fails.
+4. If CI fails: fix + push to same branch, CI re-runs, auto-merge proceeds.
+
+Manual sync fallback (hook failed / dry-run / first-time):
 ```bash
-# 1. 同步 skills + plugin.json
-cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md
-cp -r skills/ /Users/abble/team-skills/plugins/feishu-user-plugin/skills/
+# CLAUDE.md → AGENTS.md + skill ref now handled by pre-commit hook
+cp -r skills/. /Users/abble/team-skills/plugins/feishu-user-plugin/skills/
 cp .claude-plugin/plugin.json /Users/abble/team-skills/plugins/feishu-user-plugin/.claude-plugin/
-# 2. 手动更新 team-skills 的 README.md（工具数、更新日志）和 SKILL.md（version + allowed-tools）
-# 3. 走 PR 流程推送
 # Do NOT copy .mcp.json — team-skills plugin should not have one
 ```
 
 ## Development Workflow
 
 ### Keeping all docs in sync
-When making ANY code change (new tools, bug fixes, features), update ALL of these:
 
-**本仓库内：**
+When making ANY code change (new tools, bug fixes, features), update these in this repo:
 - `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
+- `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)
-- `skills/feishu-user-plugin/references/CLAUDE.md` — always copy from root: `cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md`
-- `prompts/openclaw-setup.md` — if OpenClaw 相关配置变了要更新
+- `package.json` — version + description (tool count). All three of `package.json`, `.claude-plugin/plugin.json`, and `skills/feishu-user-plugin/SKILL.md` must agree on version (CI enforces).
+- `prompts/openclaw-setup.md` — only if OpenClaw config changed
 
-**team-skills 仓库 (`/Users/abble/team-skills/plugins/feishu-user-plugin/`)：**
-- `skills/` — 同步技能文件: `cp -r skills/ /Users/abble/team-skills/plugins/feishu-user-plugin/skills/`
-- `README.md` — team-skills 有自己的 README（含团队 APP_ID/SECRET），需要同步更新：工具数量、功能列表、更新日志、安装 prompt
-- 两个 README 都必须包含 Claude Code 安装 prompt 和 OpenClaw 安装 prompt
-- team-skills README 的安装 prompt 包含团队共享的 APP_ID/SECRET（hardcoded），本仓库 README 用占位符
+`AGENTS.md` (Codex) and `skills/feishu-user-plugin/references/CLAUDE.md` are auto-derived from `CLAUDE.md` by the pre-commit hook — do **not** edit them by hand.
 
-**同步命令（每次发版后执行）：**
-```bash
-# 1. 同步 skills + plugin.json
-cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md
-cp -r skills/ /Users/abble/team-skills/plugins/feishu-user-plugin/skills/
-cp .claude-plugin/plugin.json /Users/abble/team-skills/plugins/feishu-user-plugin/.claude-plugin/
-# 2. 手动更新 team-skills README（工具数、功能列表、更新日志）+ SKILL.md（version + allowed-tools）
-# 3. 走 PR 流程推送 team-skills（禁止直接推 main）
-```
+For team-skills repo: see [Syncing to team-skills](#syncing-to-team-skills) above. Bottom line: `skills/` + `plugin.json` auto-sync via post-merge hook; team-skills README + SKILL.md still need manual edits per release.
 
 ### Keeping ROADMAP.md up to date
 - When completing a feature or fixing a bug, check the corresponding item in ROADMAP.md as `[x]` done
@@ -437,19 +489,25 @@ cp .claude-plugin/plugin.json /Users/abble/team-skills/plugins/feishu-user-plugi
 - When a version is released (tag pushed), move completed items under the "已完成" section with the version number
 - When researching a direction and deciding not to implement, add it to "已调研但暂不实施" with the reasoning
 
-### When adding new tools
-1. Add method to `src/official.js`（Official API）or `src/client.js`（Cookie 身份）
-2. Add tool definition to `TOOLS` array in `src/index.js`
-3. Add handler case in `handleTool()` switch in `src/index.js`
-4. Run `node -c src/official.js && node -c src/index.js` to verify syntax
-5. Update this file (CLAUDE.md) — tool count, tool list, usage patterns
-6. Update ROADMAP.md if relevant
+### When adding new tools (post-v1.3.7 layout)
+1. Add the underlying API method to the right domain file:
+   - Official API → `src/clients/official/<domain>.js` (im, docs, bitable, drive, wiki, calendar, okr, uploads, contacts, groups). Cross-domain helpers stay in `src/clients/official/base.js`.
+   - Cookie identity → `src/clients/user.js`.
+2. Add the MCP tool schema + handler to `src/tools/<domain>.js`. Each module exports `{ schemas: [...], handlers: { [name]: async (args, ctx) => MCPResponse } }` — see existing tools for the pattern. Handlers receive `ctx` (factories, profile state, resolveDocId — see `src/tools/_registry.js` docstring).
+3. If the new file is a brand-new domain (rare), also append it to the `TOOL_MODULES` list in `src/server.js`.
+4. Run smoke: `npm run smoke:baseline` to update the baseline (only when adding/removing/renaming tools is intentional), then `npm run smoke` to verify no other regression. For pure body changes (no schema delta) just `npm run smoke` should pass against the existing baseline.
+5. `node -c` lint each touched file.
+6. Update this file (CLAUDE.md) — tool count, tool list, usage patterns. See `docs/REFACTOR-NOTES.md` for the file-responsibility matrix.
+7. Update ROADMAP.md if relevant.
 
 ### When fixing bugs
 1. Write a standalone test script (`node -e "..."`) to reproduce the bug before fixing
 2. After fixing, verify with the same script
 3. If the bug affects MCP tool behavior, test via MCP tool call after server restart
 
+### Testing methodology
+See `docs/TESTING-METHODOLOGY.md` for the full regression playbook (when to use unit / smoke / live MCP / `scripts/test-all-tools.js`). The semi-automated path is `node scripts/test-all-tools.js`; the smoke gate is `npm run smoke` (regenerate baseline with `npm run smoke:baseline` only when a tool schema delta is intentional).
+
 ### Commit conventions
 - `feat:` new tools or capabilities
 - `fix:` bug fixes
@@ -509,7 +567,7 @@ feishu-user-plugin vX.Y.Z 发布
 
 **写作规范**:
 - **开篇**：一到两句陈述式总结，不宣传、不夸大。参考 v1.3.2："本次更新主要补齐了 X 能力，并修复了 Y 问题；同时将 Z 统一调整为 ..."
-- **每条 bullet**：先写用户可见现象，再写底层机制。引用具体错误码（如 1770032 / 91403）、接口名（如 create_doc_block）、参数名（如 RichText.atIds）——专业读者信赖的是细节
+- **每条 bullet**：先写用户可见现象，再写底层机制。引用具体错误码（如 1770032 / 91403）、接口名（如 manage_doc_block）、参数名（如 RichText.atIds）——专业读者信赖的是细节
 - **字符**：bullet 用 `•`（U+2022），不用 `-` 或 `*`；代码/工具名在正文中直接写，不加反引号
 - **禁用**：emoji、🔴🟡🟢 之类严重度标记、`@` 任何人、营销词（"强大"、"全新"、"重磅"）、夸张修辞
 - **语气**：技术 release note 的中性语气，像写给同行的内部更新。参考 v1.3.2 全文
@@ -521,13 +579,6 @@ feishu-user-plugin vX.Y.Z 发布
 
 **发送前**：始终先用 `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`
-2. Sync to team-skills repo: `cp -r skills/ /Users/abble/team-skills/plugins/feishu-user-plugin/skills/`
-3. Also sync plugin.json: `cp .claude-plugin/plugin.json /Users/abble/team-skills/plugins/feishu-user-plugin/.claude-plugin/`
-4. Update SKILL.md version + allowed-tools, README.md changelog + tool count
-5. **走 PR 流程**（创建 branch → push → PR → 等 CI 通过 → merge），禁止直接推 main
-
 ### Testing a tool
 - For Official API tools: can test directly via MCP tool call or standalone script using `readCredentials()` from `src/config.js`
 - For Cookie tools: need active session, test via MCP tool call
@@ -540,17 +591,22 @@ 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` |
+| OKR progress write (v1.3.7: create/delete_okr_progress_record) | `okr:okr.content:write` |
 | 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) |
+| Calendar write (v1.3.7: create/update/delete/respond_calendar_event) | `calendar:calendar.event:write` |
+| Tasks v2 (v1.3.7: list/get/create/update/complete/delete_task, manage_task_members) | `task:task` |
+| Docx/Bitable/Drive media upload (`uploadMedia`, `upload_drive_file`, `upload_bitable_attachment`, `manage_doc_block(action=create, image_path|file_path|...)`) | `drive:drive`, `drive:file:upload`, `docs:document.media:upload`, `sheets:spreadsheet` (only for sheet uploads) |
 | 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.
+If a tool returns `access_denied` or error code `99991672` (scope not granted), the scope is missing on either the app or the UAT. Re-run `npx feishu-user-plugin oauth` so the UAT picks up the latest scope list (defined in `src/oauth.js`).
 
 ## 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)
 - Cookie auth requires human interaction (QR scan) — cannot be fully automated
 - Refresh token expires after 7 days without use — set up `keepalive` cron to prevent this
-- `update_bitable_field` requires `type` parameter even when only changing field name (Feishu API requirement)
-- `list_wiki_spaces` may return empty if bot lacks `wiki:wiki:readonly` permission
+- `manage_bitable_field(action=update)` requires `type` parameter even when only changing field name (Feishu API requirement)
+- `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.)

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

@@ -6,21 +6,29 @@
 ## 执行步骤
 
 ### 查询数据
-1. 用 `list_bitable_tables` 获取表格列表（传入 app_token）
-2. 用 `list_bitable_fields` 获取字段结构（传入 app_token + table_id）
-3. 用 `search_bitable_records` 查询记录（支持 filter 和 sort）
+1. 用 `manage_bitable_table(action=list, app_token=...)` 获取表格列表
+2. 用 `manage_bitable_field(action=list, app_token=..., table_id=...)` 获取字段结构
+3. 用 `manage_bitable_record(action=search, app_token=..., table_id=..., filter?, sort?)` 查询记录
 4. 格式化展示查询结果
 
 ### 写入数据
-1. 先用 `list_bitable_fields` 确认字段结构
-2. 用 `create_bitable_record` 创建新记录
+1. 先用 `manage_bitable_field(action=list)` 确认字段结构
+2. 用 `manage_bitable_record(action=create, records=[{fields:{...}}])` 创建记录（可批量，最多 500/次）
    ```
-   create_bitable_record({ app_token, table_id, fields: {"状态":"进行中","标题":"新任务"} })
+   manage_bitable_record({
+     action: 'create',
+     app_token,
+     table_id,
+     records: [{ fields: {"状态":"进行中","标题":"新任务"} }]
+   })
    ```
 
 ### 更新数据
-1. 先用 `search_bitable_records` 定位目标记录的 record_id
-2. 用 `update_bitable_record` 更新指定字段
+1. 先用 `manage_bitable_record(action=search)` 定位目标记录的 record_id
+2. 用 `manage_bitable_record(action=update, records=[{record_id, fields:{...}}])` 更新
+
+### 删除数据
+- 用 `manage_bitable_record(action=delete, record_ids=[...])`（可批量）
 
 ## 示例
 - `/table query appXxx` — 列出所有表格
@@ -28,5 +36,6 @@
 - `/table create appXxx tblXxx {"状态":"进行中"}` — 创建记录
 
 ## 注意
-- 需要知道 app_token（从多维表格 URL 中获取）
+- 需要知道 app_token（从多维表格 URL 中获取，或调 `manage_bitable_app(action=create)` 新建）
 - 字段名必须与表格中的字段名完全匹配
+- 字段创建/修改 (`manage_bitable_field`) 都必须传 `type`，即使只改 field_name