feishu-user-plugin 1.2.1 → 1.3.1

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

@@ -3,17 +3,17 @@
 ## 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
-- **Official API** (app credentials): Read group messages, docs, tables, wiki, drive, contacts
+- **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
+## Tool Categories (66 tools)
 
 ### User Identity — Messaging (reverse-engineered, cookie-based)
-- `send_to_user` — Search user + send text (one step, most common)
-- `send_to_group` — Search group + send text (one step)
+- `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.
 - `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)
-- `send_file_as_user` — Send file (requires file_key from upload)
+- `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
 - `send_sticker_as_user` — Send sticker/emoji
 - `send_audio_as_user` — Send audio message
@@ -21,64 +21,168 @@ All-in-one Feishu plugin for Claude Code with three auth layers:
 ### User Identity — Contacts & Info
 - `search_contacts` — Search users/groups by name
 - `create_p2p_chat` — Create/get P2P chat
-- `get_chat_info` — Group details (name, members, owner)
-- `get_user_info` — User display name lookup (from search cache)
+- `get_chat_info` — Group details (name, members, owner). Supports both oc_xxx and numeric chat_id (Official API + protobuf fallback)
+- `get_user_info` — User display name lookup (official API first, cookie cache fallback)
 - `get_login_status` — Check cookie, app, and UAT status
 
-### User OAuth UAT Tools (P2P chat reading)
-- `read_p2p_messages` — Read P2P (direct message) chat history. chat_id accepts both numeric IDs (from create_p2p_chat) and oc_xxx format.
+### 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`.
+- `create_doc` / `create_bitable` / `create_folder` — **UAT-first**: creates resources as the user (not the app) when UAT with write scopes is available. Falls back to app token.
 
 ### Official API Tools (app credentials)
-- `list_chats` / `read_messages` — Chat history (accepts chat name, oc_ ID, or numeric ID; auto-falls back to UAT for external groups)
-- `reply_message` / `forward_message` — Message operations (as bot). reply_message only works for text messages.
-- `search_docs` / `read_doc` / `create_doc` — Document operations
-- `list_bitable_tables` / `list_bitable_fields` / `search_bitable_records` — Table queries
-- `create_bitable_record` / `update_bitable_record` — Table writes
+- `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.
+- `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
+- `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)
+- `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` — Wiki
 - `list_files` / `create_folder` — Drive
+- `copy_file` / `move_file` / `delete_file` — Drive file operations (copy, move, delete)
+- `upload_image` / `upload_file` — Upload image/file, returns key for send_image/send_file
 - `find_user` — Contact lookup by email/mobile
 
 ## Usage Patterns
+
+### Messaging
 - Send text as yourself → `send_to_user` or `send_to_group`
-- Send rich content → `send_post_as_user` (formatted text), `send_image_as_user` (images)
+- Send image → `upload_image` → `send_image_as_user`
+- Send file → `upload_file` → `send_file_as_user`
+- Send rich content → `send_post_as_user` (formatted text with links, @mentions)
+- Reply as user in thread → `send_as_user` with root_id
+- Reply as bot → `reply_message` (official API)
+
+### Reading
 - Read any group chat history → `read_messages` with chat name or ID (auto-handles external groups via UAT fallback)
 - Read P2P chat history → `search_contacts` → `create_p2p_chat` → `read_p2p_messages`
-- Reply as user in thread → `send_as_user` with root_id
-- Reply as bot → `reply_message` (official API, text messages only)
+- 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`
+
+### Group Management
+- Create a group → `create_group` with name and optional member open_ids
+- Add/remove members → `manage_members` with chat_id + member_ids + action (add/remove)
+- 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
+
+### Diagnostics
 - Diagnose issues → `get_login_status` first
 
 ## Auth & Session
-- **LARK_COOKIE**: Required for user identity tools. Session auto-refreshed every 4h via heartbeat.
+- **LARK_COOKIE**: Required for user identity tools. Session auto-refreshed every 4h via heartbeat and persisted to config.
 - **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 via refresh_token.
+- **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.
+- 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.
 
-## Automated Cookie Setup via Playwright
+## Required Environment Variables (ALL are required for full functionality)
+
+| Variable | Purpose |
+|----------|---------|
+| LARK_COOKIE | User identity messaging |
+| LARK_APP_ID | Official API access |
+| LARK_APP_SECRET | Official API access |
+| LARK_USER_ACCESS_TOKEN | P2P chat reading |
+| LARK_USER_REFRESH_TOKEN | UAT auto-refresh |
+
+All 5 must be configured. Without UAT, `read_p2p_messages` and `list_user_chats` will not work.
+
+## Installation
+
+### Config location
+
+Credentials are stored in `~/.claude.json` top-level `mcpServers` (global — works in all directories).
+**Do NOT put credentials in project-level config** (`projects[*].mcpServers` or `.mcp.json`) — this causes scope issues.
+
+### Non-interactive setup (for Claude Code agents)
+
+```bash
+npx feishu-user-plugin setup --app-id <APP_ID> --app-secret <APP_SECRET>
+```
+
+Writes config to `~/.claude.json` top-level `mcpServers` without any interactive prompts. Supports `--cookie` flag too.
+
+### Interactive setup
+
+```bash
+npx feishu-user-plugin setup    # Interactive setup wizard
+npx feishu-user-plugin oauth    # Get OAuth UAT tokens
+npx feishu-user-plugin status   # Check auth status
+npx feishu-user-plugin keepalive # Refresh cookie + UAT (for cron jobs)
+```
+
+### Token auto-renewal via cron (optional)
+
+To keep tokens alive even when Claude Code is closed:
+
+```bash
+crontab -e
+# Add: 0 */4 * * * npx feishu-user-plugin keepalive >> /tmp/feishu-keepalive.log 2>&1
+```
 
-When LARK_COOKIE is missing or expired, obtain it using Playwright MCP.
+## Automated Cookie Setup via Playwright
 
 ### Prerequisites
-Playwright MCP must be available. If not:
-> Run: `npx @anthropic-ai/claude-code mcp add playwright -- npx @anthropic-ai/mcp-server-playwright`
-> Then restart Claude Code.
+Playwright MCP must be available. If not installed:
+> Run: `npx @anthropic-ai/claude-code mcp add playwright -- npx @anthropic-ai/mcp-server-playwright` then restart Claude Code.
+
+### Automated Flow — FOLLOW EXACTLY, DO NOT IMPROVISE
+
+**Step 1: Clear existing browser session (MANDATORY)**
 
-### Automated Flow — FOLLOW EXACTLY
+Playwright MCP uses Edge's persistent profile. It may have a cached login from a DIFFERENT Feishu account. You MUST clear cookies first:
+
+```
+browser_run_code:
+  await context.clearCookies();
+```
 
-**Step 1: Clear cookies first** (Playwright uses persistent browser profile that may have a DIFFERENT account cached):
+Then navigate:
 ```
-browser_run_code: await context.clearCookies();
 browser_navigate: https://www.feishu.cn/messenger/
 ```
 
-**Step 2: Show QR code and wait for login**:
+**Step 2: Wait for user to scan QR code**
+
+Take a screenshot to show the QR code:
 ```
 browser_take_screenshot
 ```
-Poll `browser_snapshot` every 5s until URL changes from `/accounts/`.
 
-**Step 3: Extract cookie — TWO-STEP approach** (NEVER use browser_run_code output directly as cookie):
+Tell the user: "Please scan the QR code with Feishu mobile app to log in. Make sure you use the correct account."
+
+Poll with `browser_snapshot` every 5 seconds until the URL changes away from `/accounts/` (indicating login complete).
+
+**Step 3: Extract cookie — TWO-STEP approach (MANDATORY)**
+
+NEVER use `browser_run_code` output directly as the cookie string. Its output includes `### Result\n` markdown prefix, page snapshots, and console logs that contaminate the cookie.
 
-Step 3a via `browser_run_code`:
+Step 3a — Store cookie in page context via `browser_run_code`:
 ```js
 const cookies = await page.context().cookies('https://www.feishu.cn');
 const str = cookies.map(c => c.name + '=' + c.value).join('; ');
@@ -86,47 +190,220 @@ await page.evaluate(s => { window.__COOKIE__ = s; }, str);
 return 'Stored ' + cookies.length + ' cookies, length=' + str.length;
 ```
 
-Step 3b via `browser_evaluate`:
+Step 3b — Read the clean cookie string via `browser_evaluate`:
 ```js
 window.__COOKIE__
 ```
 
-**Step 4: Validate** — Must be pure ASCII, contain `session=` and `sl_session=`, length 500-5000. If >10000, it's contaminated.
+This two-step approach ensures the cookie string is clean, with no markdown prefix or page content mixed in.
+
+**Step 4: Validate BEFORE writing (MANDATORY)**
+
+Check the cookie string:
+1. Must be pure ASCII — no Chinese characters, no markdown (`###`), no HTML
+2. Must contain `session=` and `sl_session=`
+3. Length should be 500-5000 characters. If >10000, it is contaminated — DO NOT write it.
+4. Must NOT start with `###` or contain `\n` followed by non-cookie content
+
+If validation fails: STOP. Debug the extraction. Do NOT write a bad cookie to config.
+
+**Step 5: Write cookie to config**
+
+Use `persistToConfig` or directly update the `LARK_COOKIE` field in `~/.claude.json` → `mcpServers` → `feishu-user-plugin` → `env`.
+
+**Step 6: Run OAuth for UAT (if not already configured)**
+
+```bash
+npx feishu-user-plugin oauth
+```
+
+This opens a browser for OAuth consent. After completion, tokens are auto-saved to `~/.claude.json`.
+
+**Step 7: Close browser and prompt restart**
 
-**Step 5: Write config** using exact format:
-```json
-{
-  "feishu-user-plugin": {
-    "command": "npx",
-    "args": ["-y", "feishu-user-plugin"],
-    "env": {
-      "LARK_COOKIE": "<cookie>",
-      "LARK_APP_ID": "<id>",
-      "LARK_APP_SECRET": "<secret>",
-      "LARK_USER_ACCESS_TOKEN": "<uat>",
-      "LARK_USER_REFRESH_TOKEN": "<refresh>"
-    }
-  }
-}
 ```
+browser_close
+```
+
+Tell user to restart Claude Code. Only ONE restart should be needed.
+
+## Troubleshooting Guide
 
-## Troubleshooting
+### If MCP disconnects mid-session
+- **Root cause** (fixed in v1.3.1): `@larksuiteoapi/node-sdk`'s `defaultLogger.error` uses `console.log` (stdout). MCP protocol uses stdout for JSON-RPC, so SDK error logs corrupt the transport and cause immediate disconnect.
+- **Fix**: Custom logger redirects all SDK output to stderr. Already applied in `src/official.js`.
+- If still happening: check for any `console.log` calls in server code (only `console.error` is safe in MCP servers).
+
+### If MCP tools are not available
+1. Check `~/.claude.json` — config must be in **top-level** `mcpServers`, not inside `projects[*]`
+2. For Codex: check `~/.codex/config.toml` has `[mcp_servers.feishu-user-plugin]` section
+3. Restart Claude Code / Codex after config changes
+4. After restart, tools may take a few seconds to register — if first call fails with "No such tool", wait and retry once
 
 ### If cookie authentication fails
+- `document.cookie` in browser console CANNOT access HttpOnly cookies (`session`, `sl_session`)
+- **Correct method**: Network tab → first request → Request Headers → Cookie → Copy value
 - **Best method**: Playwright two-step extraction (see above)
-- **Manual fallback**: Network tab → first request → Request Headers → Cookie → Copy value
-- Do NOT use `document.cookie` or Application → Cookies (misses HttpOnly cookies)
 
-### If Playwright logs into the wrong account
-- Always `context.clearCookies()` BEFORE navigating to feishu.cn
-- Verify account by checking URL domain after login
+### If Playwright logs into the wrong Feishu account
+- Playwright uses Edge's persistent profile with cached sessions
+- **ALWAYS clear cookies first** with `context.clearCookies()` before navigating to feishu.cn
+
+### If read_messages returns an error
+- Error messages include the actual Feishu error code and description
+- `read_messages` auto-falls back to UAT when bot API fails (e.g. external groups)
+- Chat name resolution: bot's group list → `im.chat.search` → `search_contacts` (cookie)
+- If all three strategies fail, provide the oc_xxx or numeric chat ID directly
 
-### If UAT refresh fails with "invalid_grant" (error 28003/20003/20005)
-- Refresh token expired — re-run `node src/oauth.js` (needs LARK_APP_ID + LARK_APP_SECRET in `.env`)
-- Copy new UAT + refresh token from `.env` to MCP config, then restart Claude Code
+### If UAT refresh fails with "invalid_grant"
+- The refresh token has expired or been revoked — auto-refresh cannot recover this
+- **Fix**: Re-run OAuth: `npx feishu-user-plugin oauth`
+- Then restart Claude Code
+
+### If OAuth fails with "Missing LARK_APP_ID"
+- `oauth.js` reads credentials from `~/.claude.json` MCP config (not .env)
+- Run `npx feishu-user-plugin setup` first, then re-run OAuth
+
+### If two MCP servers are running (duplicate tools)
+- This happens when both `~/.claude.json` mcpServers AND a team-skills plugin have feishu-user-plugin
+- team-skills plugin should NOT have `.mcp.json` — it only provides skills and CLAUDE.md
+- Delete `.mcp.json` from the team-skills plugin directory if it exists
 
 ### If list_user_chats doesn't return P2P chats
-- Expected — API only returns groups. Use: `search_contacts` → `create_p2p_chat` → `read_p2p_messages`.
+- This is expected — the API only returns group chats
+- **Correct P2P flow**: `search_contacts` → `create_p2p_chat` → `read_p2p_messages`
+
+## Architecture
+
+### Two distribution channels
+- **npm package** (`npx feishu-user-plugin`): MCP server code + skills + CLAUDE.md. For external users.
+- **team-skills plugin**: Skills + CLAUDE.md only (no .mcp.json). For internal team members.
+
+### Config management
+- `src/config.js`: Unified config module. Discovers config in `~/.claude.json` (top-level + project-level), `.mcp.json`, and `~/.codex/config.toml`.
+- `setup` writes to `~/.claude.json` (default) or `~/.codex/config.toml` (with `--client codex`), or both (`--client both`).
+- `persistToConfig()` finds the correct config entry and writes back atomically (used by heartbeat + UAT refresh).
+- All config writes use atomic write (tmp file + rename) to prevent race conditions with Claude Code.
+
+### Multi-client support
+- **Claude Code**: JSON config in `~/.claude.json` mcpServers
+- **Codex**: TOML config in `~/.codex/config.toml` mcp_servers
+- Setup: `npx feishu-user-plugin setup --client codex` or `--client both`
+- MCP server code is identical for both clients — only config format differs
+- Codex does not support Claude Code slash commands (skills) — only MCP tools are available
+
+## Development & Publishing
+
+### Publishing to npm
+
+```bash
+# 1. Update version in package.json
+# 2. Commit and tag
+git add -A && git commit -m "v1.2.1: description"
+git tag v1.2.1
+git push && git push --tags
+# 3. GitHub Actions auto-publishes to npm on tag push
+```
+
+GitHub Actions workflow (`.github/workflows/publish.yml`) auto-publishes on `v*` tags.
+NPM_TOKEN is stored as a GitHub repo secret.
+
+### Syncing to team-skills
+
+After publishing, sync plugin assets to team-skills:
+
+```bash
+# From the feishu-user-plugin repo:
+cp -r skills/ /path/to/team-skills/plugins/feishu-user-plugin/skills/
+cp .claude-plugin/plugin.json /path/to/team-skills/plugins/feishu-user-plugin/.claude-plugin/
+# 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:
+
+**本仓库内：**
+- `CLAUDE.md` — tool count, tool list, usage patterns, known limitations
+- `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 相关配置变了要更新
+
+**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 用占位符
+
+**同步命令（每次发版后执行）：**
+```bash
+# 1. 同步 skills
+cp CLAUDE.md skills/feishu-user-plugin/references/CLAUDE.md
+cp -r skills/ /Users/abble/team-skills/plugins/feishu-user-plugin/skills/
+# 2. 手动更新 team-skills README（工具数、功能列表、更新日志）
+# 3. 提交并推送两个仓库
+```
+
+### Keeping ROADMAP.md up to date
+- When completing a feature or fixing a bug, check the corresponding item in ROADMAP.md as `[x]` done
+- When discovering new bugs, limitations, or feature ideas during development, add them to the appropriate section in ROADMAP.md
+- 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 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
+
+### Commit conventions
+- `feat:` new tools or capabilities
+- `fix:` bug fixes
+- `docs:` CLAUDE.md, ROADMAP.md, README updates
+- `chore:` dependencies, CI, config changes
+
+### Publishing
+**IMPORTANT: Version number must ALWAYS be confirmed with the user before publishing.**
+Any operation involving `npm version`, modifying `package.json` version, `git tag v*`, or `git push --tags` requires explicit user confirmation of the target version number. Do not auto-decide version numbers.
+
+Three-layer version safety:
+1. **Claude rule** (this section): Ask user to confirm version before any publish-related operation
+2. **Local gate** (`prepublishOnly`): Interactive confirmation when running `npm publish` locally (skipped in CI)
+3. **CI gate** (`.github/workflows/publish.yml`): Tag must match `package.json` version or publish fails
+
+Steps:
+1. Confirm target version with user
+2. Update `version` in `package.json`
+3. `git add <files> && git commit -m "v1.x.x: description"`
+4. `git tag v1.x.x && git push && git push --tags`
+5. GitHub Actions verifies tag matches package.json, then auto-publishes to npm
+
+### 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. Commit and push both repos
+
+### 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
+- Always verify `_safeSDKCall` handles the response format (multipart uploads return data at top level, not nested under `.data`)
 
-### If reply_message fails with error 230054
-- Only text messages can be replied to via this API.
+## 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
+- `search_wiki` uses same API as `search_docs` — `docs_types` filter may not work as expected

package/src/cli.js

@@ -41,23 +41,28 @@ function printHelp() {
 feishu-user-plugin — All-in-one Feishu MCP Server
 
 Commands:
-  (default)   Start MCP server (used by Claude Code)
+  (default)   Start MCP server (used by Claude Code / Codex)
   setup       Interactive setup wizard — writes MCP config
   oauth       Run OAuth flow to obtain user_access_token
   status      Check authentication status
   keepalive   Refresh cookie + UAT to prevent expiration (for cron jobs)
   help        Show this help
 
-Quick Start (team members):
+Setup options:
+  --app-id <id>       App ID (non-interactive mode)
+  --app-secret <s>    App Secret (non-interactive mode)
+  --cookie <c>        Cookie string (optional)
+  --client <target>   Config target: claude (default), codex, or both
+
+Quick Start (Claude Code):
   1. npx feishu-user-plugin setup
   2. Follow the prompts to configure credentials
   3. Restart Claude Code
 
-Quick Start (external users):
-  1. Create a Feishu app at https://open.feishu.cn/app
-  2. npx feishu-user-plugin setup
-  3. npx feishu-user-plugin oauth
-  4. Restart Claude Code
+Quick Start (Codex):
+  1. npx feishu-user-plugin setup --client codex
+  2. Follow the prompts to configure credentials
+  3. Restart Codex
 
 Auto-renewal (optional):
   Add to crontab to keep tokens alive even when Claude Code is closed: