feishu-user-plugin 1.3.10 → 1.3.12

package/README.en.md

@@ -1,189 +1,102 @@
-# feishu-user-plugin
+# feishu-user-plugin — Feishu MCP server + CLI tool
 
 [![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-84-orange.svg)](#tools)
+[![Tools](https://img.shields.io/badge/Tools-85-orange.svg)](docs/TOOLS.md)
+[![npm](https://img.shields.io/npm/v/feishu-user-plugin.svg)](https://www.npmjs.com/package/feishu-user-plugin)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**All-in-one Feishu/Lark MCP Server -- 84 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, OKR, and more.**
+[中文](README.md) · **English** · [Docs](https://ethanqc.github.io/feishu-user-plugin/en) · [CHANGELOG](CHANGELOG.md) · [npm](https://www.npmjs.com/package/feishu-user-plugin)
 
-> [中文 README](README.md) is the primary version. This English README mirrors it.
+Feishu / Lark MCP server covering IM, docs, bitable, wiki, drive, calendar, tasks v2, OKR, and realtime events. **85 tools · 3 auth layers · 9 MCP prompts · MIT licensed · Node ≥18**.
 
-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.
+Works with Claude Code, Codex, Cursor, Windsurf, VS Code, Claude Desktop, OpenClaw, and any MCP-compatible client.
 
-## Highlights
+There are two paths to user-identity messaging: **Feishu's official OAuth scope `im:message.send_as_user`** (requires creating a self-built app + admin approval), or this repo's **cookie + protobuf path** (zero app barrier — capture cookie and you're ready). This repo is no longer architecturally exclusive, but it remains the simpler option for "individual developers / no admin access / want to try quickly" scenarios.
 
-- **Send as yourself** -- Messages show your real name, not a bot. Supports text, rich text, images, files, stickers, and audio.
-- **Read everything** -- Group chats via bot API, P2P (direct messages) via OAuth UAT.
-- **Full Feishu suite** -- Docs, Bitable, Wiki, Drive, Calendar, Tasks, Contacts -- all in one plugin.
-- **3 auth layers** -- Cookie-based user identity, app credentials (Official API), and OAuth UAT (P2P reading).
-- **Group management** -- Create groups, add/remove members, pin messages, emoji reactions.
-- **Document editing** -- Not just read/create, but insert/update/delete content blocks.
-- **Calendar & Tasks** -- Create events, check free/busy, manage tasks.
-- **9 slash commands** for Claude Code -- `/send`, `/reply`, `/search`, `/digest`, `/doc`, `/table`, `/wiki`, `/drive`, `/status`
-- **Auto session management** -- Cookie heartbeat every 4h, UAT auto-refresh with token rotation.
-- **Real-time events** (v1.3.9) -- Machine-level WS: one owner process writes to `~/.feishu-user-plugin/events.jsonl`, all harnesses drain from a shared cursor — every event delivered exactly once across all MCP processes. `manage_ws_status` to diagnose/control. WS auto-starts on boot.
-- **Multi-platform** -- Claude Code, Cursor, Windsurf, VS Code, OpenClaw.
+## vs the official Feishu/Lark tools (released 2026)
 
-## Why This Exists
+- [`larksuite/lark-openapi-mcp`](https://github.com/larksuite/lark-openapi-mcp) — official OpenAPI MCP, **⚠ Beta**, last updated 2025-08 (9 months stale). Their README explicitly states "File upload/download not yet supported" and "Direct document editing not supported"; 1271 endpoint tools but preset.default only enables ~20, the rest "not undergone compatibility testing".
+- [`larksuite/cli`](https://github.com/larksuite/cli) — official CLI (9.9k stars, actively maintained), 17 business domains, 200+ commands + 24 AI Agent Skills. **Now supports `+messages-send --as user`** via OAuth scope `im:message.send_as_user`. But it's a **CLI, not an MCP server**. Codex / Cursor / Windsurf etc would have to shell out to it.
 
-Feishu's official API has a hard limitation: **there is no `send_as_user` scope**. Even with `user_access_token` (OAuth), messages still show `sender_type: "app"`.
+**When to use this repo**:
 
-This project combines three auth layers into one plugin:
+- You want user-identity messaging / P2P chat reading but **can't / don't want to create a Feishu self-built app** (individual developer / no admin access) — the cookie path has zero barrier
+- You use MCP protocol (Codex / Cursor / Windsurf / VS Code etc) and don't need mail / approval / HR / meeting-minutes domains that this repo doesn't cover
+- You run multiple MCP clients simultaneously and need "every event delivered exactly once across the entire machine" (v1.3.9+ machine-level WS SSOT)
 
-```
-User Identity (cookie):     You -> Protobuf -> Feishu (messages appear as YOU)
-Official API  (app token):  You -> REST API -> Feishu (docs, tables, wiki, drive)
-User OAuth    (UAT):        You -> REST API -> Feishu (read P2P chats, list all chats)
-```
-
-**One plugin. Everything Feishu. No other MCP needed.**
+**When to use the official**: you need mail / approval / attendance / HR / hiring / meeting-minutes business-system domains; or you already have a Feishu app + admin-approved OAuth scopes and prefer the officially-maintained long-term path.
 
-## Quick Start
+Full honest comparison: [docs/COMPARISON.md](docs/COMPARISON.md).
 
-### Option 1: npx (recommended)
+## Quick example
 
-```bash
-npx feishu-user-plugin
 ```
-
-No installation needed. The package runs directly via npx.
-
-### Option 2: Clone and run locally
-
-```bash
-git clone https://github.com/EthanQC/feishu-user-plugin.git
-cd feishu-user-plugin
-npm install
-npm start
+You: send Wang Xiao Ming a message as me: "finished the code review, 3 nits"
+Claude: [calls send_to_user]  Sent
 ```
 
-## Create Your Feishu App
-
-To use the Official API tools (docs, tables, wiki, drive, bot messaging), you need to create a Feishu app:
-
-### Step 1: Create the App
-
-1. Go to [Feishu Open Platform](https://open.feishu.cn/app) and log in
-2. Click **Create Custom App** (创建自建应用) -- you must choose **Custom App** (自建应用), NOT marketplace/third-party types
-3. Fill in the app name and description, then create it
-
-### Step 2: Enable Bot Capability
-
-1. In your app settings, go to **Add Capabilities** (添加应用能力)
-2. Enable **Bot** (机器人)
-
-### Step 3: Add Permissions (Scopes)
-
-Go to **Permissions & Scopes** (权限管理) and add the following scopes:
-
-| Scope | Purpose |
-|-------|---------|
-| `im:message` | Send messages as bot |
-| `im:message:readonly` | Read message history |
-| `im:chat:readonly` | List and read chats |
-| `docx:document` | Read and create documents |
-| `docx:document:readonly` | Read documents |
-| `bitable:record` | Read and write Bitable records |
-| `wiki:wiki:readonly` | Read wiki spaces and nodes |
-| `drive:drive:readonly` | List Drive files and folders |
-| `contact:user.base:readonly` | Look up users by email/mobile |
-
-> Add more scopes as needed depending on which tools you use.
-
-### Step 4: Get App Credentials
-
-1. Go to **Credentials & Basic Info** (凭证与基础信息)
-2. Copy the **App ID** (`cli_xxxxxxxxxxxx`) and **App Secret**
-3. Set them as `LARK_APP_ID` and `LARK_APP_SECRET` in your environment
-
-### Step 5: Publish and Approve
-
-1. **Create a version** and submit it for review (创建版本)
-2. Have your organization admin approve the app (管理员审核)
-3. After approval, the app is live
-
-### Step 6: Add Bot to Group Chats
-
-Add your bot to the group chats where you want it to read messages. The bot can only access chats it has been added to.
-
-## Environment Variables
-
-| Variable | Required For | Description |
-|----------|-------------|-------------|
-| `LARK_COOKIE` | User identity tools | Feishu web session cookie string. Needed for `send_to_user`, `send_to_group`, `search_contacts`, etc. |
-| `LARK_APP_ID` | Official API tools | App ID from Feishu Open Platform. Needed for `read_messages`, docs, tables, wiki, drive. |
-| `LARK_APP_SECRET` | Official API tools | App Secret from Feishu Open Platform. Used together with `LARK_APP_ID`. |
-| `LARK_USER_ACCESS_TOKEN` | P2P chat reading | OAuth user token. Needed for `read_p2p_messages` and `list_user_chats`. Obtained via `node src/oauth.js`. |
-| `LARK_USER_REFRESH_TOKEN` | UAT auto-refresh | Refresh token for automatic UAT renewal. Obtained together with UAT via OAuth flow. |
-
-All five variables are required for full functionality. Configure all of them during setup.
-
-## How to Get Your Cookie
+```
+You: summarize today's discussion in the engineering group after 9am, post a daily digest to #daily
+Claude: [read_messages → summarize → send_to_group]  Sent
+```
 
-**Option A: Automated via Playwright MCP (recommended, zero manual copying)**
+## Quick start
 
-First, install Playwright MCP if you don't have it:
 ```bash
-npx @anthropic-ai/claude-code mcp add playwright -- npx @anthropic-ai/mcp-server-playwright
+npx feishu-user-plugin setup --app-id <APP_ID> --app-secret <APP_SECRET>
+npx feishu-user-plugin oauth         # OAuth UAT
+# restart Claude Code / Codex
 ```
 
-Then just tell Claude Code: **"Help me set up my Feishu cookie"**
-
-Claude Code will automatically:
-1. Open feishu.cn in a browser via Playwright
-2. Show you the QR code — scan it with Feishu mobile app
-3. Extract the full cookie (including HttpOnly) via `context.cookies()`
-4. Write it to your `.mcp.json` LARK_COOKIE field
-5. Prompt you to restart Claude Code
+Cookie capture (Playwright auto-QR / DevTools manual), Feishu app creation, per-client config — see [docs/AUTH-SETUP.md](docs/AUTH-SETUP.md).
 
-**Option B: Manual (via Network tab)**
+## Three auth layers
 
-1. Open [feishu.cn/messenger](https://www.feishu.cn/messenger/) in your browser and log in
-2. Open DevTools (`F12` or `Cmd+Option+I`)
-3. Go to the **Network** tab → check **Disable cache** → press `Cmd+R` to reload
-4. Click the first request in the list (usually the page itself)
-5. In the right panel, find **Request Headers** → **Cookie:** → right-click → **Copy value**
-6. Set it as `LARK_COOKIE` in your environment
+| Layer | Credentials | Capabilities | Tools |
+|---|---|---|---|
+| User identity (cookie + protobuf) | `LARK_COOKIE` | Send text / image / file / post / @ / batch as the user | 8 |
+| Official API (bot) | `LARK_APP_ID` + `LARK_APP_SECRET` | Group messages, docs, bitable, wiki, drive, calendar, tasks v2, OKR, contacts, realtime WS | 70+ |
+| User OAuth UAT | `LARK_USER_ACCESS_TOKEN` + `LARK_USER_REFRESH_TOKEN` | P2P chat reading, user chat list; resources owned by the user when creating | 2 explicit + UAT-first across the suite |
 
-> Do NOT use `document.cookie` in the Console or copy from Application → Cookies tab — they miss HttpOnly cookies (`session`, `sl_session`) required for auth.
+Layers are independent — configure any subset.
 
-> The server automatically refreshes the session via heartbeat every 4 hours. The `sl_session` cookie has a 12-hour max-age.
+## Capabilities
 
-## Set Up OAuth (Required for P2P Chat Reading)
+- **Send messages as you** (8): text / image / file / rich-text post / cards / batch; differentiator — Feishu's official API has no `send_as_user`
+- **Read groups & P2P chats** (17): group messages / P2P / `merge_forward` auto-expanded / URL + Feishu doc links auto-extracted / external groups auto-fallback to UAT
+- **Document suite** (27): Feishu docs (with `read_doc_markdown` saving ~60% tokens) / bitable (batch up to 500) / wiki (full write CRUD) / drive
+- **Productivity** (21): calendar (read+write) / tasks v2 (with member management) / OKR (read + progress records) / contacts
+- **Realtime events** (2): machine-level SSOT WS, every event delivered exactly once across the entire machine
+- **Diagnostics & multi-account** (4): N profiles auto-switched per call, writes never auto-switch (avoids accidental cross-account creates)
 
-To enable `read_p2p_messages` and `list_user_chats`:
+Full tool list + cross-domain caveats + usage patterns: [docs/TOOLS.md](docs/TOOLS.md).
 
-1. Your Feishu app must be a **Custom App** (自建应用), NOT marketplace/third-party
-2. Add scopes: `im:message`, `im:message:readonly`, `im:chat:readonly`
-3. In your app's **Security Settings** (安全设置), add the OAuth redirect URI: `http://127.0.0.1:9997/callback`
-4. **Important**: Make sure "对外共享" (external sharing) is **disabled** in your app version settings — enabling it marks the app as b2c/b2b type, which blocks P2P chat access
-5. Run the authorization flow:
+## 9 MCP prompts (slash commands)
 
-```bash
-# If you cloned the repo:
-node src/oauth.js
-
-# If you installed via npx:
-cd $(npm root -g)/feishu-user-plugin && node src/oauth.js
-# Or clone the repo just for the OAuth step, then use npx for daily use
-```
-
-A browser window will open for OAuth consent. The token is saved to `.env` automatically and auto-refreshes at runtime. Add both `LARK_USER_ACCESS_TOKEN` and `LARK_USER_REFRESH_TOKEN` from `.env` to your MCP config's `env` section.
+| Prompt | Purpose |
+|---|---|
+| `/send` | Send a message as yourself |
+| `/reply` | Read recent messages then reply |
+| `/digest` | Summarise recent group / P2P messages |
+| `/search` | Search contacts / groups |
+| `/doc` | Search / read / create a Feishu doc |
+| `/table` | Operate on a bitable |
+| `/wiki` | Search wiki space |
+| `/drive` | List drive files / create folder |
+| `/status` | Check all three auth layers |
 
 ## MCP Client Configuration
 
 ### Claude Code
 
-Add to your project's `.mcp.json` (or `~/.claude/.mcp.json` for global):
-
-**Using npx:**
+Add to `~/.claude.json` `mcpServers` (recommended global) or your project's `.mcp.json`:
 
 ```json
 {
   "mcpServers": {
-    "feishu": {
+    "feishu-user-plugin": {
       "command": "npx",
       "args": ["-y", "feishu-user-plugin"],
       "env": {
@@ -198,30 +111,7 @@ Add to your project's `.mcp.json` (or `~/.claude/.mcp.json` for global):
 }
 ```
 
-**Using a local clone:**
-
-```json
-{
-  "mcpServers": {
-    "feishu": {
-      "command": "node",
-      "args": ["/absolute/path/to/feishu-user-plugin/src/index.js"],
-      "env": {
-        "LARK_COOKIE": "your-cookie-string",
-        "LARK_APP_ID": "cli_xxxxxxxxxxxx",
-        "LARK_APP_SECRET": "your-app-secret",
-        "LARK_USER_ACCESS_TOKEN": "your-uat",
-        "LARK_USER_REFRESH_TOKEN": "your-refresh-token"
-      }
-    }
-  }
-}
-```
-
-Then just say things like:
-- "Send a message to Alice saying the meeting is at 3pm"
-- "What did the engineering group chat about today?"
-- "Search for docs about MCP"
+Or via CLI: `npx feishu-user-plugin setup --app-id <APP_ID> --app-secret <APP_SECRET>`.
 
 ### Claude Desktop
 
@@ -245,6 +135,25 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 }
 ```
 
+### Codex
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.feishu-user-plugin]
+command = "npx"
+args = ["-y", "feishu-user-plugin"]
+
+[mcp_servers.feishu-user-plugin.env]
+LARK_COOKIE = "your-cookie-string"
+LARK_APP_ID = "cli_xxxxxxxxxxxx"
+LARK_APP_SECRET = "your-app-secret"
+LARK_USER_ACCESS_TOKEN = "your-uat"
+LARK_USER_REFRESH_TOKEN = "your-refresh-token"
+```
+
+Or via CLI: `npx feishu-user-plugin setup --client codex --app-id <APP_ID> --app-secret <APP_SECRET>`.
+
 ### Cursor
 
 Add to `.cursor/mcp.json` in your project:
@@ -269,7 +178,7 @@ Add to `.cursor/mcp.json` in your project:
 
 ### VS Code (Copilot)
 
-Add to `.vscode/mcp.json` in your project:
+Add to `.vscode/mcp.json` in your project (note: top-level key is `servers`, not `mcpServers`):
 
 ```json
 {
@@ -314,9 +223,7 @@ Add to `~/.openclaw/openclaw.json` (note: key path is `mcp.servers`, not `mcpSer
 }
 ```
 
-Or via CLI: `openclaw mcp set feishu-user-plugin '{"command":"npx","args":["-y","feishu-user-plugin"],"env":{...}}'`
-
-> OpenClaw's built-in Feishu channel handles receiving messages (bot identity). This plugin adds user identity messaging + docs/bitable/calendar/tasks.
+Or via CLI: `openclaw mcp set feishu-user-plugin '{"command":"npx","args":["-y","feishu-user-plugin"],"env":{...}}'`.
 
 ### Windsurf
 
@@ -340,264 +247,74 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 }
 ```
 
-## Tools (80 total)
-
-### User Identity -- Messaging (10 tools, cookie auth)
-
-| Tool | Description |
-|------|-------------|
-| `send_to_user` | Search user by name + send text -- one step |
-| `send_to_group` | Search group by name + send text -- one step |
-| `send_as_user` | Send text to any chat by ID, supports reply threading |
-| `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 |
-| `batch_send` | Fan-out send to multiple targets in one call (text / image / file / post). v1.3.6 |
-| `send_card_as_user` | Send a Feishu interactive card via bot identity (Official API). User-identity card sending is server-side disabled at the Feishu cookie auth tier — confirmed in v1.3.9. |
-
-### User Identity -- Contacts & Info (5 tools, cookie auth)
-
-| Tool | Description |
-|------|-------------|
-| `search_contacts` | Search users, bots, or group chats by name |
-| `create_p2p_chat` | Create/get P2P (direct message) chat |
-| `get_chat_info` | Group details (supports both oc_xxx and numeric ID) |
-| `get_user_info` | User display name lookup by user ID |
-| `get_login_status` | Check cookie, app credentials, and UAT status |
-
-### User OAuth UAT -- P2P Chat Reading (2 tools)
-
-| Tool | Description |
-|------|-------------|
-| `read_p2p_messages` | Read P2P (direct message) history |
-| `list_user_chats` | List group chats the user is in |
-
-### Official API -- IM (17 tools)
-
-| Tool | Description |
-|------|-------------|
-| `list_chats` | List all chats the bot has joined |
-| `read_messages` | Read message history (accepts chat name, oc_xxx, or numeric ID) |
-| `send_message_as_bot` | Send message as bot to any chat |
-| `reply_message` | Reply to a specific message (as bot) |
-| `forward_message` | Forward a message to another chat |
-| `delete_message` | Recall/delete a bot message |
-| `update_message` | Edit a sent bot message |
-| `add_reaction` | Add emoji reaction to a message |
-| `delete_reaction` | Remove emoji reaction |
-| `pin_message` | Pin a message in chat |
-| `unpin_message` | Unpin a message |
-| `create_group` | Create a new group chat |
-| `update_group` | Update group name/description |
-| `list_members` | List group members |
-| `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_message_resource` | v1.3.7 (C2.4): download a message-attached image or file. Args: `message_id`, `key`, `kind=image|file`, `save_path?`. **Required save_path when bytes > 2 MiB** (Anthropic 5 MB inline cap). Replaces v1.3.6 download_image (message mode) + download_file. |
-| `download_doc_image` | v1.3.7 (C2.4): download an image embedded in a docx (image_token + optional doc_token). Same 2 MiB cap. Replaces v1.3.6 download_image (docx mode). |
-
-### Wiki, OKR, and Calendar (v1.3.4)
-
-| 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 (5 tools)
-
-| Tool | Description |
-|------|-------------|
-| `search_docs` | Search documents by keyword |
-| `read_doc` | Read raw text content |
-| `get_doc_blocks` | Get structured block tree |
-| `create_doc` | Create a new document |
-| `manage_doc_block` | Insert / update / delete blocks (`action=create|update|delete`). Supports generic `children`, image (`image_path`/`image_token`), and file (`file_path`/`file_token`) shortcuts. v1.3.7 consolidates the v1.3.6 trio create_doc_block / update_doc_block / delete_doc_blocks. |
-
-### Official API -- Bitable (6 tools, v1.3.7 consolidation)
-
-| Tool | Actions | Description |
-|------|---------|-------------|
-| `manage_bitable_app` | create / copy / get_meta | App-level operations (v1.3.7 consolidates create_bitable / copy_bitable / get_bitable_meta) |
-| `manage_bitable_table` | list / create / update / delete | Table CRUD (rename via update) |
-| `manage_bitable_field` | list / create / update / delete | Field (column) management. `type` required for both create AND update. |
-| `manage_bitable_view` | list / create / delete | Views (grid, kanban, gallery, form, gantt, calendar) |
-| `manage_bitable_record` | search / get / create / update / delete | Record CRUD. create/update/delete accept arrays — single record or up to 500/call. |
-| `upload_bitable_attachment` | — | Upload a file into a Bitable Attachment-type field. Returns `file_token` to write into the field as `[{file_token}]`. v1.3.6 |
-
-### Official API -- Calendar (8 tools, write tools v1.3.7)
-
-| Tool | Description |
-|------|-------------|
-| `list_calendars` | List accessible calendars |
-| `list_calendar_events` | List events in a calendar |
-| `get_calendar_event` | Full event details |
-| `create_calendar_event` | Create an event (v1.3.7). Requires `calendar:calendar.event:write`. |
-| `update_calendar_event` | Patch event fields (v1.3.7) |
-| `delete_calendar_event` | Delete an event, optionally dissolve its meeting chat (v1.3.7) |
-| `respond_calendar_event` | RSVP as accept / decline / tentative (v1.3.7) |
-| `get_freebusy` | Freebusy lookup for `user_ids` in a time range (v1.3.7) |
-
-### Official API -- Tasks v2 (7 tools, v1.3.7 new domain)
-
-Identifier is `task_guid` (not v1's numeric `task_id`). Requires `task:task` scope.
-
-| Tool | Description |
-|------|-------------|
-| `list_tasks` | List the current user's tasks (filter by completed / type) |
-| `get_task` | Full task detail |
-| `create_task` | Create a task (summary required; due/members optional) |
-| `update_task` | Patch fields. **`update_fields` is required** — Feishu only updates the listed keys. |
-| `complete_task` | Mark complete (or uncomplete with `completed=false`) |
-| `delete_task` | Permanent delete |
-| `manage_task_members` | `action=add|remove`, members `[{id, role:"assignee"|"follower"}]` |
-
-### Official API -- Drive (4 tools)
-
-| Tool | Description |
-|------|-------------|
-| `list_files` | List files in a folder |
-| `create_folder` | Create a new folder |
-| `manage_drive_file` | Copy / move / delete a Drive file (`action=copy|move|delete`, `type` required). v1.3.7 consolidates v1.3.6 copy_file / move_file / delete_file. |
-| `upload_drive_file` | Upload a local file into a Drive folder (`drive/v1/files/upload_all`). Optional `wiki_space_id` attaches the upload as a Wiki node atomically. v1.3.6 |
-
-### Official API -- Wiki (8 tools)
-
-| Tool | Description |
-|------|-------------|
-| `list_wiki_spaces` / `search_wiki` / `list_wiki_nodes` / `get_wiki_node` | Wiki spaces, search, browse + resolve a wiki node to underlying obj_token |
-| `create_wiki_node` | Create a new wiki node (doc/sheet/bitable/mindnote/file/docx/slides) inside a space |
-| `update_wiki_node` | Rename a wiki node (title only — content edits via docx/bitable tools) |
-| `move_wiki_node` | Move a wiki node to a different parent or different space |
-| `copy_wiki_node` | Deep-copy a wiki node to a different location (optionally to a different space) |
-
-### Plugin -- Profiles (3 tools, v1.3.6 + v1.3.8)
-
-| Tool | Description |
-|------|-------------|
-| `list_profiles` | List available identity profiles (default + extras from `LARK_PROFILES_JSON`) and the active one |
-| `switch_profile` | Hot-swap active profile; cached client instances rebuild against new credentials |
-| `manage_profile_hints` | Inspect/set/clear the resourceKey → profile cache used by the v1.3.8 auto-switch middleware |
-
-### Multi-profile auto-switch (v1.3.8)
-
-When `~/.feishu-user-plugin/credentials.json` has more than one profile, the plugin auto-switches between them on **read** paths when the active profile gets a permission-denied error. The winning profile is cached per resource so subsequent calls go straight to the right account.
-
-**Whitelist** -- only `read_*`, `list_*`, `get_*`, `search_*`, `download_*` (and the read-action variants of `manage_bitable_*`) get auto-retry. Writes never auto-switch -- they fail loud so you don't accidentally create resources under the wrong account.
-
-**Triggers** -- error codes 91403, 1254301, 1254000, 99991672, HTTP 403, plus message patterns `access_denied / permission_denied / docx_no_permission / no permission / forbidden`.
+## Multi-account
 
-**Per-call override** -- pass `via_profile: "<name>"` in any tool call to pin to that profile (no auto-switch). Pass `via_profile: "auto"` to opt **into** auto-switch on a write call (escape hatch -- be careful).
+`~/.feishu-user-plugin/credentials.json` supports multiple profiles (default + any number of additional), so one machine handles multiple Feishu accounts / multiple tenants.
 
-**Cache management** -- `manage_profile_hints(action="list" | "set" | "clear", resource_key?, profile?)` lets you inspect or edit the cache.
-
-Single-profile users (the vast majority): zero behaviour change -- the router short-circuits and `manage_profile_hints` is a no-op.
-
-## Claude Code Slash Commands (9 skills)
+```bash
+npx feishu-user-plugin list-profiles
+npx feishu-user-plugin switch-profile <name>
+npx feishu-user-plugin keepalive --all       # cross-profile keepalive
+```
 
-This plugin includes 9 built-in skills in `skills/feishu-user-plugin/`:
+Read-path tools auto-retry across profiles on errors `91403` / `1254301` / `1254000` / `99991672` / `HTTP 403`. Writes never auto-switch (avoids creating resources under the wrong account). Per-call override: pass `via_profile: "<name>"` to pin to a specific profile.
 
-| Skill | Usage | Description |
-|-------|-------|-------------|
-| `/send` | `/send Alice: meeting at 3pm` | Send message as yourself |
-| `/reply` | `/reply engineering-chat` | Read recent messages and reply |
-| `/digest` | `/digest engineering-chat 7` | Summarize recent chat messages |
-| `/search` | `/search engineering` | Search contacts and groups |
-| `/doc` | `/doc search MCP` | Search, read, or create documents |
-| `/table` | `/table query appXxx` | Query or create Bitable records |
-| `/wiki` | `/wiki search protocol` | Search and browse wiki |
-| `/drive` | `/drive list folderToken` | List files or create folders in Drive |
-| `/status` | `/status` | Check login and auth status |
+Details: [docs/TOOLS.md "Multi-profile auto-switch"](docs/TOOLS.md#多-profile-auto-switchv138).
 
-Skills are automatically available when the plugin is installed.
+## Realtime events
 
-## Architecture
+A single MCP process per machine holds the WS owner lock. All MCP processes share `events.jsonl`, every event delivered exactly once across the entire machine.
 
+```bash
+mcp call manage_ws_status --action info
+mcp call manage_ws_status --action claim --force true
 ```
-                               Cookie + Proto   ┌──────────────────────────────────────┐
-                             ────────────────── >│  internal-api-lark-api.feishu.cn     │
-┌──────────────┐                                 │  /im/gateway/ (Protobuf over HTTP)   │
-│  MCP Client  │                                 └──────────────────────────────────────┘
-│  (Claude,    │  App Token (REST) ┌──────────────────────────────────────┐
-│   Cursor,    │ ────────────────->│  open.feishu.cn/open-apis/           │
-│   VS Code)   │                   │  (Official REST API)                 │
-│              │                   └──────────────────────────────────────┘
-│              │  User OAuth (REST)┌──────────────────────────────────────┐
-│              │ ────────────────->│  open.feishu.cn/open-apis/           │
-└──────────────┘                   │  (UAT -- P2P chat reading)           │
-                                   └──────────────────────────────────────┘
-```
-
-## Session & Token Lifecycle
-
-| Auth Layer | Token | Lifetime | Refresh |
-|------------|-------|----------|---------|
-| Cookie | `sl_session` | 12h max-age | Auto-refreshed every 4h via heartbeat |
-| App Token | `tenant_access_token` | 2h | Auto-managed by SDK |
-| User OAuth | `user_access_token` | ~2h | Auto-refreshed via `refresh_token`, saved to MCP config |
 
-When the cookie expires (after ~12-24h without heartbeat), re-login at feishu.cn and update `LARK_COOKIE`. Use `get_login_status` to check health proactively.
+Default subscriptions: `["im.message.receive_v1"]`. To subscribe to other events (approval / calendar / vc / etc.), edit `credentials.json::profiles[<active>].events`, then call `manage_ws_status(action=reconfig)` to apply without restart.
 
-If UAT refresh fails with `invalid_grant`, re-run `npx feishu-user-plugin oauth` and restart Claude Code / Codex. v1.3.5+ also re-reads the persisted MCP config before refreshing, so duplicate MCP processes can adopt a token already rotated by another process instead of retrying a stale refresh token.
-
-## Project Structure
-
-```
-feishu-user-plugin/
-├── .claude-plugin/
-│   └── plugin.json          # Plugin metadata
-├── skills/
-│   └── 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 (78 tools)
-│   ├── client.js            # User identity client (Protobuf gateway)
-│   ├── official.js          # Official API client (REST, UAT)
-│   ├── utils.js             # ID generators, cookie parser
-│   ├── oauth.js             # OAuth flow for user_access_token
-│   ├── test-send.js         # Quick CLI test
-│   └── test-all.js          # Full test suite
-├── proto/
-│   └── lark.proto           # Protobuf message definitions
-├── .mcp.json.example        # MCP server config template
-├── server.json              # MCP Registry manifest
-├── .env.example             # Configuration template
-└── package.json
-```
+Only `feishu.cn` is supported — Lark international (`lark.com`) WSClient is not available.
 
 ## Limitations
 
-- Cookie-based auth requires periodic refresh (auto-heartbeat extends to ~12h; manual re-login needed after that)
-- Depends on Feishu's internal Protobuf protocol -- may break if Feishu updates their web client
-- Image/file/audio sending requires pre-uploaded keys (upload via Official API or external bridge)
-- No real-time message receiving (WebSocket push not yet implemented)
-- May violate Feishu's Terms of Service -- use at your own risk
+- **Cookie lifetime**: 12-24 hours without heartbeat; re-login at feishu.cn to get a fresh cookie
+- **Protocol drift**: cookie + protobuf path depends on Feishu web client protocol; Feishu updates may break user-identity messaging (bot capabilities unaffected)
+- **Cards**: cookie path's card sending is server-disabled; bot path works
+- **Lark international**: realtime events WS not supported
+- **Not implemented**: `search_messages`, md → wiki sync (see [ROADMAP.md](ROADMAP.md))
+
+## Documentation
+
+| Document | Role |
+|----------|------|
+| [docs/TOOLS.md](docs/TOOLS.md) | Tool reference + cross-domain caveats + usage patterns |
+| [docs/AUTH-SETUP.md](docs/AUTH-SETUP.md) | Install / 3 auth layers / cookie capture / OAuth scopes |
+| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Error codes & diagnosis |
+| [docs/RELEASING.md](docs/RELEASING.md) | Release flow + team-skills sync + announcement rules |
+| [docs/REFACTOR-NOTES.md](docs/REFACTOR-NOTES.md) | File responsibility matrix |
+| [docs/CREDENTIALS-FORMAT.md](docs/CREDENTIALS-FORMAT.md) | Credentials schema |
+| [docs/TESTING-METHODOLOGY.md](docs/TESTING-METHODOLOGY.md) | Testing playbook |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution flow (bilingual) |
+| [ROADMAP.md](ROADMAP.md) | Roadmap (forward-only) |
+| [CHANGELOG.md](CHANGELOG.md) | Version history |
+
+Full docs/ index: [docs/README.md](docs/README.md).
 
 ## Contributing
 
-Issues and PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and submission guidelines.
-
-If Feishu updates their protocol and something breaks, please [open an issue](https://github.com/EthanQC/feishu-user-plugin/issues/new?template=bug_report.md) with the error details.
-
-### Automated sync hooks
+Issues / PRs welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) first.
 
-This repo uses husky to enforce several invariants on every commit:
+If a Feishu protocol change breaks a tool — open an issue with the error log.
 
-- **CLAUDE.md sync** — staging `CLAUDE.md` automatically regenerates `AGENTS.md` (identical body, different first line) and `skills/feishu-user-plugin/references/CLAUDE.md` (verbatim copy). Both are re-staged in the same commit.
-- **Version triangle** — if `package.json`, `.claude-plugin/plugin.json`, or `skills/feishu-user-plugin/SKILL.md` are staged, all three `version` fields must agree or the commit is rejected.
-- **Tool-count badge** — if `src/server.js` or any file under `src/tools/` is staged, the `N tools` badge in `README.md` must match the actual `TOOLS.length` exported by `src/server.js`.
-- **Smoke test** — any change under `src/` triggers `npm run smoke` to catch schema regressions before commit.
+## Privacy
 
-CI (`.github/workflows/validate.yml`) runs the same checks on every PR to `main`, so bypassing the local hook still gets caught.
+A locally-run MCP server. Credentials stay on the user's machine; no telemetry, no phone-home. Full text: [PRIVACY.md](PRIVACY.md).
 
-On the maintainer's machine, a post-merge hook (`scripts/sync-team-skills.sh`) auto-opens a sync PR in the `~/team-skills` repo after every merge to main. The hook silently skips if `~/team-skills` is absent.
+- **Collected**: nothing by the plugin itself; the five `LARK_*` envs are supplied by the user from their own Feishu / Lark account
+- **Processed**: only the messages / docs / bitable / wiki / drive / calendar / tasks / OKR / contacts the user explicitly requests via MCP tool calls
+- **Stored**: `~/.feishu-user-plugin/credentials.json` (mode 0600); optional event log at `~/.feishu-user-plugin/events.jsonl`
+- **Third-party**: only the user's own Feishu tenant and the AI client the user runs (Claude Code / Codex / Cursor / etc.)
+- **Retention**: entirely user-controlled; `rm -rf ~/.feishu-user-plugin && npm uninstall -g feishu-user-plugin` removes everything
+- **Contact**: [GitHub Issues](https://github.com/EthanQC/feishu-user-plugin/issues); security disclosures with `[security]` prefix in the title
 
 ## License
 
@@ -605,6 +322,6 @@ On the maintainer's machine, a post-merge hook (`scripts/sync-team-skills.sh`) a
 
 ## Acknowledgments
 
-- [cv-cat/LarkAgentX](https://github.com/cv-cat/LarkAgentX) -- Early Feishu web protocol research (Python)
-- [cv-cat/OpenFeiShuApis](https://github.com/cv-cat/OpenFeiShuApis) -- Underlying API research
-- [Model Context Protocol](https://modelcontextprotocol.io) -- The MCP standard
+- [cv-cat/LarkAgentX](https://github.com/cv-cat/LarkAgentX) — early Feishu web protocol research (Python)
+- [cv-cat/OpenFeiShuApis](https://github.com/cv-cat/OpenFeiShuApis) — underlying API research
+- [Model Context Protocol](https://modelcontextprotocol.io) — MCP spec + Anthropic / PulseMCP / GitHub / Stacklok joint registry