feishu-user-plugin 1.3.8 → 1.3.10

package/README.md

@@ -3,606 +3,366 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
-[![Tools](https://img.shields.io/badge/Tools-82-orange.svg)](#tools)
+[![Tools](https://img.shields.io/badge/Tools-84-orange.svg)](#工具索引84-个)
+[![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 -- 82 tools, 9 skills, 3 auth layers for messaging, docs, bitable, calendar, tasks, drive, OKR, and more.**
+**中文** · [English](README.en.md) · [Docs](https://ethanqc.github.io/feishu-user-plugin/) · [CHANGELOG](CHANGELOG.md) · [npm](https://www.npmjs.com/package/feishu-user-plugin)
 
-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.
+飞书 / Lark MCP 服务器，覆盖 IM、文档、多维表格、知识库、云空间、日历、任务 v2、OKR、实时事件。**84 tools · 3 auth layers · 9 MCP prompts · MIT licensed · Node ≥18**。
 
-## Highlights
+兼容 Claude Code、Codex、Cursor、Windsurf、VS Code、Claude Desktop、OpenClaw 等 MCP 客户端。
 
-- **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.8) -- `get_new_events` drains an in-memory queue of incoming Feishu messages — react to replies / group activity within seconds without polling. WS connection auto-starts on boot.
-- **Multi-platform** -- Claude Code, Cursor, Windsurf, VS Code, OpenClaw.
+与其他飞书 MCP 的区别：基于 cookie + protobuf 协议路径，支持以**用户本人身份**发消息——飞书官方开放 API 没有 `send_as_user` 权限点，机器人 token 发出的消息一律标 `sender_type: "app"`。
 
-## Why This Exists
+## 三层鉴权
 
-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"`.
+| 鉴权层 | 凭证 | 覆盖能力 | 工具数 |
+|---|---|---|---|
+| 用户身份（cookie + protobuf） | `LARK_COOKIE` | 以用户身份发文本 / 图片 / 文件 / 富文本 / @ / 批量 | 8 |
+| 官方 API（机器人） | `LARK_APP_ID` + `LARK_APP_SECRET` | 群消息读写、文档、多维表格、知识库、云空间、日历、任务 v2、OKR、联系人、实时事件 WS | 70+ |
+| 用户 OAuth UAT | `LARK_USER_ACCESS_TOKEN` + `LARK_USER_REFRESH_TOKEN` | P2P 私聊读取、用户 chat 列表；写入文档 / Bitable / 日历 资源时以用户为 owner | 2 显式 + 全工具 UAT-first |
 
-This project combines three auth layers into one plugin:
+三层独立 —— 配置任意一层，对应工具可用。
 
-```
-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.**
-
-## Quick Start
-
-### Option 1: npx (recommended)
-
-```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
+npx feishu-user-plugin setup --app-id <APP_ID> --app-secret <APP_SECRET>
+npx feishu-user-plugin oauth         # 拿用户 OAuth UAT
+# 重启 Claude Code / Codex
 ```
 
-## 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
+cookie 获取：跟 Claude Code 说一句"帮我设置飞书 cookie"会自动经 Playwright 扫码登录抓取；手动方式在 feishu.cn DevTools Network 标签从请求头 Cookie 整行复制（不要用 `document.cookie` 或 Application > Cookies 标签—— HttpOnly 的 `session` / `sl_session` 拿不到）。
 
-### Step 6: Add Bot to Group Chats
+没有 APP_ID / SECRET 见下面 [创建飞书应用](#创建飞书应用)。
 
-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
-
-**Option A: Automated via Playwright MCP (recommended, zero manual copying)**
-
-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
 ```
-
-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
-
-**Option B: Manual (via Network tab)**
-
-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
-
-> Do NOT use `document.cookie` in the Console or copy from Application → Cookies tab — they miss HttpOnly cookies (`session`, `sl_session`) required for auth.
-
-> The server automatically refreshes the session via heartbeat every 4 hours. The `sl_session` cookie has a 12-hour max-age.
-
-## Set Up OAuth (Required for P2P Chat Reading)
-
-To enable `read_p2p_messages` and `list_user_chats`:
-
-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:
-
-```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
+你：帮我以我身份给王小明发：今天的代码 review 我看完了，有 3 个 nit
+Claude：[调用 send_to_user]  Sent
 ```
 
-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.
-
-## MCP Client Configuration
-
-### Claude Code
-
-Add to your project's `.mcp.json` (or `~/.claude/.mcp.json` for global):
-
-**Using npx:**
-
-```json
-{
-  "mcpServers": {
-    "feishu": {
-      "command": "npx",
-      "args": ["-y", "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"
-      }
-    }
-  }
-}
+```
+你：总结"工程组"群今天 9 点之后的讨论，发个日报到 #日报频道
+Claude：[read_messages → 总结 → send_to_group]  Sent
 ```
 
-**Using a local clone:**
+## 创建飞书应用
+
+`LARK_APP_ID` / `LARK_APP_SECRET` 是用 Official API（70+ 工具）的前置条件：
+
+1. [飞书开放平台](https://open.feishu.cn/app) 登录 → 创建**自建应用**（不能选商店应用 / 第三方应用，否则 P2P 读取会被锁）
+2. 添加应用能力 → 启用机器人
+3. 权限管理 → 添加 scope：
+   - 消息：`im:message`、`im:message:readonly`、`im:chat:readonly`
+   - 文档：`docx:document`、`bitable:record`、`wiki:wiki:readonly`、`drive:drive:readonly`
+   - 联系人：`contact:user.base:readonly`
+   - 按需：`okr:okr:readonly`、`calendar:calendar:readonly`、`task:task`、`drive:drive`、`docs:document.media:upload`、`wiki:wiki` 等
+4. 凭证与基础信息 → 复制 App ID（`cli_xxx`）+ App Secret
+5. 创建版本 → 提交审核 → 管理员审批
+6. 把 bot 加到要读消息的群里
+
+## 工具索引（84 个）
+
+完整工具列表 + 参数 + 跨域注意事项见 [CLAUDE.md](CLAUDE.md)。
+
+### 用户身份 —— 消息（cookie protobuf，8 个）
+
+| 工具 | 说明 |
+|---|---|
+| `send_to_user` | 按名搜用户 + 发文本，一步完成 |
+| `send_to_group` | 按名搜群 + 发文本，一步完成 |
+| `send_as_user` | 按 chat ID 发文本，支持回复线程（`root_id` / `parent_id`） |
+| `send_image_as_user` | 以用户身份发图（v1.3.9） |
+| `send_file_as_user` | 以用户身份发文件（需先 `upload_file`） |
+| `send_post_as_user` | 富文本：标题 + 段落 + @ + 超链 |
+| `send_card_as_user` | 飞书交互卡片（机器人通道；cookie 通道服务端关闭，仅 bot 路径可用） |
+| `batch_send` | 一次发多条到不同 chat（text / image / file / post） |
+
+### 用户身份 —— 联系人 / 信息（cookie，5 个）
+
+| 工具 | 说明 |
+|---|---|
+| `search_contacts` | 搜用户 / bot / 群 |
+| `create_p2p_chat` | 创建或获取 P2P chat |
+| `get_chat_info` | 群详情（接受 `oc_xxx` 或 numeric） |
+| `get_user_info` | 用户名 / 头像查询 |
+| `get_login_status` | 三层鉴权健康检查（实际跑一次 UAT 调用，不只看配置） |
+
+### 用户 OAuth UAT —— P2P 读取（2 个）
+
+| 工具 | 说明 |
+|---|---|
+| `read_p2p_messages` | 读私聊历史（外部群自动 fallback） |
+| `list_user_chats` | 用户加入的所有群（仅群，不含 P2P；P2P 用 `search_contacts` → `create_p2p_chat`） |
+
+### 官方 API —— IM（15 个）
+
+| 工具 | 说明 |
+|---|---|
+| `list_chats` | 列 bot 加入的所有 chat |
+| `read_messages` | 读群消息（接受 chat 名 / `oc_xxx` / numeric；外部群自动 UAT fallback；merge_forward 自动展开） |
+| `send_message_as_bot` | 机器人发消息 |
+| `reply_message` | 机器人回复 |
+| `forward_message` | 转发到其他 chat（自动识别 receive_id_type） |
+| `delete_message` | 撤回 / 删除 bot 消息 |
+| `update_message` | 编辑已发消息（仅支持 text / interactive） |
+| `add_reaction` / `delete_reaction` | 表情回应 |
+| `pin_message` | 置顶 |
+| `create_group` / `update_group` | 建群 / 改群 |
+| `list_members` / `manage_members` | 群成员 list / add / remove（注意 `member_id_type` 与 ID 类型匹配） |
+| `download_message_resource` | 下载消息附件（image / file，> 2 MiB 必须 `save_path`） |
+
+### 官方 API —— 文档（7 个）
+
+| 工具 | 说明 |
+|---|---|
+| `search_docs` | 关键词搜文档 |
+| `read_doc` | 结构化 JSON |
+| `read_doc_markdown` | v1.3.9 直接返回 markdown，~60% token 节省（适合 RAG / 总结） |
+| `get_doc_blocks` | 块树 |
+| `create_doc` | 创建文档（可选 `wiki_space_id` 直接落知识库） |
+| `manage_doc_block` | 块 create / update / delete（image_path / file_path / image_token / file_token 快捷） |
+| `download_doc_image` | 下载文档内嵌图片 |
+
+### 官方 API —— 多维表格 Bitable（6 个，v1.3.7 整合）
+
+| 工具 | actions | 说明 |
+|---|---|---|
+| `manage_bitable_app` | create / copy / get_meta | 应用级（创建可指定 `wiki_space_id` 直接落 Wiki） |
+| `manage_bitable_table` | list / create / update / delete | 数据表 CRUD |
+| `manage_bitable_field` | list / create / update / delete | 字段（update 必须传 `type` 即使只改名） |
+| `manage_bitable_view` | list / create / delete | 视图（grid / kanban / gallery / form / gantt / calendar） |
+| `manage_bitable_record` | search / get / create / update / delete | 记录 CRUD（数组：单条或最多 500） |
+| `upload_bitable_attachment` | — | 上传附件，返回 `file_token` |
+
+### 官方 API —— 知识库 Wiki（9 个）
+
+| 工具 | 说明 |
+|---|---|
+| `list_wiki_spaces` | 列空间（UAT-first） |
+| `search_wiki` | 搜知识库 |
+| `list_wiki_nodes` | 列节点 |
+| `get_wiki_node` | 节点 → obj_token 解析（接受 wiki node token 或 obj_token） |
+| `create_wiki_node` | 创建节点（doc / sheet / bitable / mindnote / file / docx / slides） |
+| `update_wiki_node` | 改名（内容编辑用 docx / bitable 工具） |
+| `move_wiki_node` | 移动 |
+| `copy_wiki_node` | 深拷贝 |
+| `delete_wiki_node` | 删除 wiki 节点指针（底层 drive 资源用 `manage_drive_file(action=delete)` 删） |
+
+### 官方 API —— 云空间 Drive（5 个）
+
+| 工具 | 说明 |
+|---|---|
+| `list_files` | 列文件夹内文件 |
+| `create_folder` | 建文件夹 |
+| `manage_drive_file` | copy / move / delete（必须传 `type`） |
+| `upload_image` / `upload_file` | 上传图片 / 文件，返回 key |
+| `upload_drive_file` | 上传到 Drive 文件夹（可选 `wiki_space_id` 直接挂 Wiki 节点） |
+
+### 官方 API —— OKR（6 个）
+
+| 工具 | 说明 |
+|---|---|
+| `list_user_okrs` | 列指定用户的 OKR（必须传 user_id） |
+| `get_okrs` | 批量取详情（objectives + key results + progress + alignments） |
+| `list_okr_periods` | 列周期（季度 / 年度） |
+| `create_okr_progress_record` | 添加进展记录（v1.3.7，需 `okr:okr.content:write`） |
+| `list_okr_progress_records` | 列进展记录（从 `get_okrs` 提取 triples） |
+| `delete_okr_progress_record` | 删进展记录 |
+
+### 官方 API —— 日历（8 个，写入 v1.3.7）
+
+| 工具 | 说明 |
+|---|---|
+| `list_calendars` | 列日历（primary + 共享 + 订阅） |
+| `list_calendar_events` | 列事件（指定时间窗） |
+| `get_calendar_event` | 事件详情（参与人 / 地点 / 会议链接 / 附件） |
+| `create_calendar_event` | 建事件（需 `calendar:calendar.event:write`） |
+| `update_calendar_event` | 改事件 |
+| `delete_calendar_event` | 删事件（可选 `meeting_chat_id` 同时解散关联会议群） |
+| `respond_calendar_event` | RSVP（accept / decline / tentative） |
+| `get_freebusy` | 多人 freebusy 查询 |
+
+### 官方 API —— 任务 v2（7 个，v1.3.7 新域）
+
+标识符是 `task_guid`（不是 v1 的 numeric `task_id`），需 `task:task` scope。
+
+| 工具 | 说明 |
+|---|---|
+| `list_tasks` | 列当前用户任务 |
+| `get_task` | 详情 |
+| `create_task` | 建任务（summary 必填） |
+| `update_task` | 改任务（必传 `update_fields=[...]`，飞书只 patch 列出字段） |
+| `complete_task` | 完成 / 取消完成 |
+| `delete_task` | 删 |
+| `manage_task_members` | add / remove 成员（assignee / follower） |
+
+### 插件层 —— 诊断与多账号（4 个）
+
+| 工具 | 说明 |
+|---|---|
+| `get_login_status` | 三层鉴权健康检查 |
+| `list_profiles` | 列可用 profile（默认 + LARK_PROFILES_JSON / credentials.json） |
+| `switch_profile` | 切 profile（缓存的 client 实例下次调用重建） |
+| `manage_profile_hints` | 查 / 改 / 清 自动切换缓存（list / set / clear） |
+
+### 插件层 —— 实时事件（2 个，v1.3.9）
+
+| 工具 | 说明 |
+|---|---|
+| `get_new_events` | 拉取增量事件（peek=true 不推进 cursor；filter by event_type / chat_id / since_seconds / profile） |
+| `manage_ws_status` | info / reconnect / claim / rotate / reconfig（诊断 / 重连 / 抢锁 / 强制 events.jsonl 轮转 / 不重启重新订阅） |
+
+## 9 个 MCP prompts（slash commands）
+
+| Prompt | 说明 |
+|---|---|
+| `/send` | 以用户身份发消息 |
+| `/reply` | 读最近消息然后回 |
+| `/digest` | 群 / P2P 最近消息总结 |
+| `/search` | 搜联系人 / 群 |
+| `/doc` | 搜 / 读 / 建文档 |
+| `/table` | 操作多维表格 |
+| `/wiki` | 搜知识库 |
+| `/drive` | 列云空间 / 建文件夹 |
+| `/status` | 检查三层鉴权状态 |
+
+## 客户端配置
+
+环境变量配置一致，配置文件路径和顶层键不同。
+
+**统一 env 块**：
 
 ```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"
-      }
-    }
+  "command": "npx",
+  "args": ["-y", "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"
   }
 }
 ```
 
-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"
+**安放位置**：
 
-### Claude Desktop
+| 客户端 | 配置文件 | 顶层键 |
+|---|---|---|
+| Claude Code | `~/.claude.json`（推荐全局） / `.mcp.json` | `mcpServers.feishu-user-plugin` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) | `mcpServers.feishu` |
+| Codex | `~/.codex/config.toml` | `[mcp_servers.feishu-user-plugin]`（TOML） |
+| Cursor | `.cursor/mcp.json`（项目级） | `mcpServers.feishu` |
+| VS Code (Copilot) | `.vscode/mcp.json` | `servers.feishu`（注意是 `servers`，不是 `mcpServers`） |
+| OpenClaw | `~/.openclaw/openclaw.json` | `mcp.servers.feishu-user-plugin` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `mcpServers.feishu` |
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+**自动化设置**：
 
-```json
-{
-  "mcpServers": {
-    "feishu": {
-      "command": "npx",
-      "args": ["-y", "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"
-      }
-    }
-  }
-}
+```bash
+npx feishu-user-plugin setup                       # 默认写 Claude Code (~/.claude.json)
+npx feishu-user-plugin setup --client codex        # Codex (~/.codex/config.toml)
+npx feishu-user-plugin setup --client both         # Claude Code + Codex 都写
+npx feishu-user-plugin setup --activate            # 激活当前 profile
 ```
 
-### Cursor
+各客户端完整 JSON 模板见 [README.en.md `MCP Client Configuration` 段](README.en.md#mcp-client-configuration)。
 
-Add to `.cursor/mcp.json` in your project:
+## 多账号（v1.3.8 / v1.3.9）
 
-```json
-{
-  "mcpServers": {
-    "feishu": {
-      "command": "npx",
-      "args": ["-y", "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"
-      }
-    }
-  }
-}
-```
-
-### VS Code (Copilot)
-
-Add to `.vscode/mcp.json` in your project:
+`~/.feishu-user-plugin/credentials.json` 支持多 profile（默认 + 任意附加），单台机器一处配置覆盖多个飞书账号 / 多个企业。
 
-```json
-{
-  "servers": {
-    "feishu": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "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"
-      }
-    }
-  }
-}
+```bash
+npx feishu-user-plugin list-profiles
+npx feishu-user-plugin switch-profile <name>
+npx feishu-user-plugin keepalive --all       # 跨 profile keepalive
 ```
 
-### OpenClaw
+读路径工具（`read_*` / `list_*` / `get_*` / `search_*` / `download_*`）失败码 91403 / 1254301 / 1254000 / 99991672 / HTTP 403 时自动跨 profile retry。写路径不自动切（避免错号创建资源）。
 
-Add to `~/.openclaw/openclaw.json` (note: key path is `mcp.servers`, not `mcpServers`):
+单调用覆盖：传 `via_profile: "<name>"` 钉到指定 profile，传 `via_profile: "auto"` 给写路径开自动切换。
 
-```json
-{
-  "mcp": {
-    "servers": {
-      "feishu-user-plugin": {
-        "command": "npx",
-        "args": ["-y", "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: `openclaw mcp set feishu-user-plugin '{"command":"npx","args":["-y","feishu-user-plugin"],"env":{...}}'`
+详见 [CLAUDE.md "Multi-profile auto-switch" 段](CLAUDE.md#multi-profile-auto-switch-v138)。
 
-> OpenClaw's built-in Feishu channel handles receiving messages (bot identity). This plugin adds user identity messaging + docs/bitable/calendar/tasks.
+## 实时事件（v1.3.9 机器级 SSOT）
 
-### Windsurf
+机器上单进程持有 WS owner 锁（`~/.feishu-user-plugin/ws-owner.lock`，`O_CREAT|O_EXCL`，30s stale），所有 MCP 进程共享 `~/.feishu-user-plugin/events.jsonl`（10 MB 软 / 20 MB 硬限自动轮转），`events.cursor.json` 是全机所有 harness 共享的 drain cursor —— 每条事件全机恰好一次。
 
-Add to `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "feishu": {
-      "command": "npx",
-      "args": ["-y", "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"
-      }
-    }
-  }
-}
+```bash
+mcp call manage_ws_status --action info        # 谁在持锁、当前订阅、events.jsonl 大小
+mcp call manage_ws_status --action claim --force true   # 跨进程抢锁
 ```
 
-## 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. v1.3.6 default routes through bot identity; user-identity is reserved for v1.3.7. |
-
-### 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`.
-
-**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).
-
-**Cache management** -- `manage_profile_hints(action="list" | "set" | "clear", resource_key?, profile?)` lets you inspect or edit the cache.
+默认订阅 `["im.message.receive_v1"]`。要订阅其他事件（审批 / 日历 / vc / etc），编辑 `credentials.json::profiles[<active>].events`，然后 `manage_ws_status(action=reconfig)` 不重启重新订阅。
 
-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)
+仅支持 feishu.cn —— Lark 国际版（lark.com）的 WSClient 当前不支持。
 
-This plugin includes 9 built-in skills in `skills/feishu-user-plugin/`:
+## 工程细节
 
-| 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 |
+### Token 生命周期
 
-Skills are automatically available when the plugin is installed.
+| 鉴权层 | Token | 有效期 | 续期 |
+|---|---|---|---|
+| Cookie | `sl_session` | 12h max-age | 4h 心跳自动刷新 |
+| App | `tenant_access_token` | 2h | SDK 自动管理 |
+| User OAuth | `user_access_token` | ~2h | refresh_token 自动刷新，写回 credentials.json |
+| Refresh Token | — | 7 天 | `keepalive` cron 防过期 |
 
-## Architecture
-
-```
-                               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)           │
-                                   └──────────────────────────────────────┘
+```bash
+crontab -e
+# 0 */4 * * * npx feishu-user-plugin keepalive >> /tmp/feishu-keepalive.log 2>&1
 ```
 
-## Session & Token Lifecycle
+UAT 刷新失败 `invalid_grant` —— refresh token 过期 / 被撤销，重跑 `npx feishu-user-plugin oauth` 然后重启 Claude Code / Codex。
 
-| 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 |
+### 凭证存储（v1.3.7+）
 
-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.
+单一可信源 `~/.feishu-user-plugin/credentials.json`（mode 0600），多 harness 共享。schema 见 [docs/CREDENTIALS-FORMAT.md](docs/CREDENTIALS-FORMAT.md)。
 
-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
+```bash
+npx feishu-user-plugin migrate              # dry-run
+npx feishu-user-plugin migrate --confirm    # 真写
 ```
 
-## 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
+### 自动 sync hooks
 
-## Contributing
+| 阶段 | 触发文件 | 作用 |
+|---|---|---|
+| pre-commit | `CLAUDE.md` staged | 同步到 `AGENTS.md` + skill 引用 |
+| pre-commit | `package.json` / `plugin.json` / `SKILL.md` staged | 三角等价检查（version 必须一致） |
+| pre-commit | `src/server.js` / `src/tools/*` staged | 工具个数 + README 84 tools 徽章必须一致 |
+| pre-commit | `src/*` staged | smoke test |
+| post-merge (main) | 任意 | 自动开 team-skills sync PR |
 
-Issues and PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and submission guidelines.
+CI（`.github/workflows/validate.yml`）每个 PR 跑同样的 gate。
 
-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
+- **Cookie 寿命**：12-24 小时无心跳过期，需重新登录 feishu.cn 拿 cookie
+- **协议变化**：cookie + protobuf 层依赖飞书 web 客户端的协议，飞书更新可能失效（机器人能力不受影响）
+- **卡片**：cookie 通道发卡片服务端不可用，机器人通道可发
+- **Lark 国际版**：实时事件 WS 不支持
+- **未实现**：`search_messages`（v1.3.10 计划）、md → wiki 同步（v1.3.10 主线）
 
-This repo uses husky to enforce several invariants on every commit:
+完整 ROADMAP 见 [ROADMAP.md](ROADMAP.md)。
 
-- **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.
+## 贡献
 
-CI (`.github/workflows/validate.yml`) runs the same checks on every PR to `main`, so bypassing the local hook still gets caught.
+Issues / PR 欢迎。提交前先看 [CONTRIBUTING.md](CONTRIBUTING.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.
+飞书改协议导致功能挂掉 —— 开 issue 带错误日志即可。
 
 ## License
 
 [MIT](LICENSE)
 
-## Acknowledgments
+## 致谢
 
-- [cv-cat/LarkAgentX](https://github.com/cv-cat/LarkAgentX) -- Original Feishu protocol reverse-engineering (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) —— 早期飞书 web 协议研究（Python）
+- [cv-cat/OpenFeiShuApis](https://github.com/cv-cat/OpenFeiShuApis) —— 底层 API 研究
+- [Model Context Protocol](https://modelcontextprotocol.io) —— MCP 标准 + Anthropic / PulseMCP / GitHub / Stacklok 共维 registry