feishu-user-plugin 1.3.11 → 1.3.13

package/README.md

@@ -1,41 +1,34 @@
-# feishu-user-plugin
+# feishu-user-plugin —— 飞书 MCP 服务器 + CLI 工具
 
 [![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)](#工具索引84-个)
+[![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)
 
 **中文** · [English](README.en.md) · [Docs](https://ethanqc.github.io/feishu-user-plugin/) · [CHANGELOG](CHANGELOG.md) · [npm](https://www.npmjs.com/package/feishu-user-plugin)
 
-飞书 / Lark MCP 服务器，覆盖 IM、文档、多维表格、知识库、云空间、日历、任务 v2、OKR、实时事件。**84 tools · 3 auth layers · 9 MCP prompts · MIT licensed · Node ≥18**。
+飞书 / Lark MCP 服务器，覆盖 IM、文档、多维表格、知识库、云空间、日历、任务 v2、OKR、实时事件。**85 工具 · 3 层鉴权 · 9 MCP prompts · MIT licensed · Node ≥18**。
 
 兼容 Claude Code、Codex、Cursor、Windsurf、VS Code、Claude Desktop、OpenClaw 等 MCP 客户端。
 
-与其他飞书 MCP 的区别：基于 cookie + protobuf 协议路径，支持以**用户本人身份**发消息——飞书官方开放 API 没有 `send_as_user` 权限点，机器人 token 发出的消息一律标 `sender_type: "app"`。
+用户身份发消息有两条路径：**飞书官方 OAuth scope `im:message.send_as_user`**（需要创建自建应用 + 管理员审批），或本仓的 **cookie + protobuf 路径**（零应用门槛，cookie 抓出来就跑）。本仓不再是物理性独家，但仍然是"个人开发者 / 没有管理员权限 / 想快速试"场景的简便选项。
 
-## 三层鉴权
-
-| 鉴权层 | 凭证 | 覆盖能力 | 工具数 |
-|---|---|---|---|
-| 用户身份（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 |
+## 与官方对比（飞书 2026 年也发了 MCP + CLI）
 
-三层独立 —— 配置任意一层，对应工具可用。
+- [`larksuite/lark-openapi-mcp`](https://github.com/larksuite/lark-openapi-mcp) —— 官方 OpenAPI MCP，**⚠ Beta** + 最后更新 2025-08（9 个月前），README 明文不支持文件上传下载、不支持文档编辑；1271 个 endpoint 工具但 preset.default 仅 ~20，其余"未做兼容性测试"
+- [`larksuite/cli`](https://github.com/larksuite/cli) —— 官方 CLI（9.9k stars，活跃），17 业务域 200+ commands + 24 AI Agent Skills，**已支持 `+messages-send --as user`**（走 OAuth scope `im:message.send_as_user`），但 **CLI 形态而不是 MCP**，Codex / Cursor / Windsurf 等用它要 shell out
 
-## 安装
+**什么时候用本仓**：
 
-```bash
-npx feishu-user-plugin setup --app-id <APP_ID> --app-secret <APP_SECRET>
-npx feishu-user-plugin oauth         # 拿用户 OAuth UAT
-# 重启 Claude Code / Codex
-```
+- 想以用户身份发消息 / 读 P2P 私聊但**不想 / 不能创建飞书自建应用**（个人开发者 / 没管理员权限）—— cookie 路径零门槛
+- 用 MCP 协议（Codex / Cursor / Windsurf / VS Code 等）+ 不需要邮件 / 审批 / HR / 会议纪要等本仓未覆盖的域
+- 多 MCP 客户端共存且需要"实时事件全机精确投递一次"（v1.3.9+ 机器级 WS SSOT）
 
-cookie 获取：跟 Claude Code 说一句"帮我设置飞书 cookie"会自动经 Playwright 扫码登录抓取；手动方式在 feishu.cn DevTools Network 标签从请求头 Cookie 整行复制（不要用 `document.cookie` 或 Application > Cookies 标签—— HttpOnly 的 `session` / `sl_session` 拿不到）。
+**什么时候用官方**：需要邮件 / 审批 / 考勤 / HR / 招聘 / 会议纪要等业务系统域；或已有飞书应用 + 管理员批了 OAuth scope，偏好官方长期稳定路径。
 
-没有 APP_ID / SECRET 见下面 [创建飞书应用](#创建飞书应用)。
+完整诚实对比见 [docs/COMPARISON.md](docs/COMPARISON.md)。
 
 ## 用法
 
@@ -49,172 +42,36 @@ Claude：[调用 send_to_user]  Sent
 Claude：[read_messages → 总结 → send_to_group]  Sent
 ```
 
-## 创建飞书应用
-
-`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 查询 |
+```bash
+npx feishu-user-plugin setup --app-id <APP_ID> --app-secret <APP_SECRET>
+npx feishu-user-plugin oauth         # 拿用户 OAuth UAT
+# 重启 Claude Code / Codex
+```
 
-### 官方 API —— 任务 v2（7 个，v1.3.7 新域）
+cookie 获取（Playwright 自动扫码 / DevTools 手动）、创建飞书应用、各客户端配置详见 [docs/AUTH-SETUP.md](docs/AUTH-SETUP.md)。
 
-标识符是 `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） |
+| 鉴权层 | 凭证 | 覆盖能力 | 工具数 |
+|---|---|---|---|
+| 用户身份（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 |
 
-### 插件层 —— 诊断与多账号（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）
+- **以你身份发消息**（8）：text / image / file / 富文本 post / 卡片 / 批量；差异化锚点 —— 飞书官方 API 没有 `send_as_user`
+- **读群与 P2P 私聊**（17）：群消息 / 私聊 / `merge_forward` 自动展开 / URL + 飞书文档链接自动提取 / 外部群自动 fallback 到 UAT
+- **文档生态**（27）：飞书文档（含 `read_doc_markdown` 省 ~60% token）/ 多维表格（500 条批量）/ 知识库（含 write CRUD）/ 云空间
+- **协作工具**（21）：日历（读+写）/ 任务 v2（含成员管理）/ OKR（读+进展记录）/ 联系人
+- **实时事件**（2）：机器级 SSOT WS，每条事件全机精确投递一次
+- **诊断与多账号**（4）：N 个 profile 自动切换，写路径不切（避免错号建资源）
 
-| 工具 | 说明 |
-|---|---|
-| `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 轮转 / 不重启重新订阅） |
+完整工具列表 + 跨域 caveat + 用法 patterns 见 [docs/TOOLS.md](docs/TOOLS.md)。
 
 ## 9 个 MCP prompts（slash commands）
 
@@ -232,48 +89,27 @@ Claude：[read_messages → 总结 → send_to_group]  Sent
 
 ## 客户端配置
 
-环境变量配置一致，配置文件路径和顶层键不同。
-
-**统一 env 块**：
-
-```json
-{
-  "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"
-  }
-}
-```
-
-**安放位置**：
+环境变量统一，配置文件位置和顶层键不同：
 
 | 客户端 | 配置文件 | 顶层键 |
 |---|---|---|
-| Claude Code | `~/.claude.json`（推荐全局） / `.mcp.json` | `mcpServers.feishu-user-plugin` |
+| 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） |
+| Codex | `~/.codex/config.toml` | `[mcp_servers.feishu-user-plugin]` |
 | Cursor | `.cursor/mcp.json`（项目级） | `mcpServers.feishu` |
-| VS Code (Copilot) | `.vscode/mcp.json` | `servers.feishu`（注意是 `servers`，不是 `mcpServers`） |
+| 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` |
 
-**自动化设置**：
-
 ```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
+npx feishu-user-plugin setup                       # Claude Code
+npx feishu-user-plugin setup --client codex        # Codex
+npx feishu-user-plugin setup --client both         # 都写
 ```
 
-各客户端完整 JSON 模板见 [README.en.md `MCP Client Configuration` 段](README.en.md#mcp-client-configuration)。
+各客户端完整 JSON 模板见 [README.en.md `MCP Client Configuration`](README.en.md#mcp-client-configuration)；详细安装与凭证流程见 [docs/AUTH-SETUP.md](docs/AUTH-SETUP.md)。
 
-## 多账号（v1.3.8 / v1.3.9）
+## 多账号
 
 `~/.feishu-user-plugin/credentials.json` 支持多 profile（默认 + 任意附加），单台机器一处配置覆盖多个飞书账号 / 多个企业。
 
@@ -283,73 +119,47 @@ npx feishu-user-plugin switch-profile <name>
 npx feishu-user-plugin keepalive --all       # 跨 profile keepalive
 ```
 
-读路径工具（`read_*` / `list_*` / `get_*` / `search_*` / `download_*`）失败码 91403 / 1254301 / 1254000 / 99991672 / HTTP 403 时自动跨 profile retry。写路径不自动切（避免错号创建资源）。
+读路径工具失败码 `91403` / `1254301` / `1254000` / `99991672` / `HTTP 403` 时自动跨 profile retry。写路径不自动切（避免错号创建资源）。单调用覆盖：传 `via_profile: "<name>"` 钉到指定 profile。
 
-单调用覆盖：传 `via_profile: "<name>"` 钉到指定 profile，传 `via_profile: "auto"` 给写路径开自动切换。
+详见 [docs/TOOLS.md "多 profile auto-switch"](docs/TOOLS.md#多-profile-auto-switchv138)。
 
-详见 [CLAUDE.md "Multi-profile auto-switch" 段](CLAUDE.md#multi-profile-auto-switch-v138)。
+## 实时事件
 
-## 实时事件（v1.3.9 机器级 SSOT）
-
-机器上单进程持有 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 —— 每条事件全机恰好一次。
+机器上单进程持有 WS owner 锁，所有 MCP 进程共享 `events.jsonl`，每条事件全机恰好一次。
 
 ```bash
-mcp call manage_ws_status --action info        # 谁在持锁、当前订阅、events.jsonl 大小
-mcp call manage_ws_status --action claim --force true   # 跨进程抢锁
+mcp call manage_ws_status --action info
+mcp call manage_ws_status --action claim --force true
 ```
 
-默认订阅 `["im.message.receive_v1"]`。要订阅其他事件（审批 / 日历 / vc / etc），编辑 `credentials.json::profiles[<active>].events`，然后 `manage_ws_status(action=reconfig)` 不重启重新订阅。
+默认订阅 `["im.message.receive_v1"]`。要订阅审批 / 日历 / vc 等其他事件，编辑 `credentials.json::profiles[<active>].events`，然后 `manage_ws_status(action=reconfig)` 不重启重新订阅。
 
 仅支持 feishu.cn —— Lark 国际版（lark.com）的 WSClient 当前不支持。
 
-## 工程细节
-
-### Token 生命周期
-
-| 鉴权层 | 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 防过期 |
-
-```bash
-crontab -e
-# 0 */4 * * * npx feishu-user-plugin keepalive >> /tmp/feishu-keepalive.log 2>&1
-```
-
-UAT 刷新失败 `invalid_grant` —— refresh token 过期 / 被撤销，重跑 `npx feishu-user-plugin oauth` 然后重启 Claude Code / Codex。
-
-### 凭证存储（v1.3.7+）
-
-单一可信源 `~/.feishu-user-plugin/credentials.json`（mode 0600），多 harness 共享。schema 见 [docs/CREDENTIALS-FORMAT.md](docs/CREDENTIALS-FORMAT.md)。
-
-```bash
-npx feishu-user-plugin migrate              # dry-run
-npx feishu-user-plugin migrate --confirm    # 真写
-```
-
-### 自动 sync hooks
-
-| 阶段 | 触发文件 | 作用 |
-|---|---|---|
-| 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 |
-
-CI（`.github/workflows/validate.yml`）每个 PR 跑同样的 gate。
-
 ## 已知限制
 
 - **Cookie 寿命**：12-24 小时无心跳过期，需重新登录 feishu.cn 拿 cookie
 - **协议变化**：cookie + protobuf 层依赖飞书 web 客户端的协议，飞书更新可能失效（机器人能力不受影响）
 - **卡片**：cookie 通道发卡片服务端不可用，机器人通道可发
 - **Lark 国际版**：实时事件 WS 不支持
-- **未实现**：`search_messages`（v1.3.10 计划）、md → wiki 同步（v1.3.10 主线）
-
-完整 ROADMAP 见 [ROADMAP.md](ROADMAP.md)。
+- **未实现**：`search_messages`、md → wiki 同步（详见 [ROADMAP.md](ROADMAP.md)）
+
+## 文档
+
+| 文档 | 角色 |
+|------|------|
+| [docs/TOOLS.md](docs/TOOLS.md) | 工具详细 + 跨域 caveat + 用法 patterns |
+| [docs/AUTH-SETUP.md](docs/AUTH-SETUP.md) | 安装 / 三层鉴权 / Cookie 抓取 / OAuth Scopes |
+| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | 错误码与诊断 |
+| [docs/RELEASING.md](docs/RELEASING.md) | 发版流程 + team-skills 同步 + 公告规则 |
+| [docs/REFACTOR-NOTES.md](docs/REFACTOR-NOTES.md) | 文件职责矩阵 |
+| [docs/CREDENTIALS-FORMAT.md](docs/CREDENTIALS-FORMAT.md) | 凭证 schema |
+| [docs/TESTING-METHODOLOGY.md](docs/TESTING-METHODOLOGY.md) | 测试方法 |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | 贡献流程（中英双语） |
+| [ROADMAP.md](ROADMAP.md) | 路线图（forward-only） |
+| [CHANGELOG.md](CHANGELOG.md) | 历史变更 |
+
+完整 docs/ 索引：[docs/README.md](docs/README.md)。
 
 ## 贡献
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "feishu-user-plugin",
   "mcpName": "io.github.EthanQC/feishu-user-plugin",
-  "version": "1.3.11",
-  "description": "All-in-one Feishu MCP server for Claude Code & Codex — 84 tools across 3 auth layers (cookie / app / OAuth). Send as you, read groups, manage docs / bitable / wiki / drive / calendar / tasks / OKR.",
+  "version": "1.3.13",
+  "description": "All-in-one Feishu MCP server + CLI tool for Claude Code / Codex / Cursor / scripts — 85 tools across 3 auth layers (cookie / app / OAuth). Send as you, read groups, manage docs / bitable / wiki / drive / calendar / tasks / OKR.",
   "main": "src/index.js",
   "bin": {
     "feishu-user-plugin": "src/cli.js"

package/scripts/check-description-drift.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+'use strict';
+// Verifies every manifest description / long_description references only
+// the current package.json::version (or no version at all).
+//
+// Catches the "plugin.json description stuck at v1.3.8 for 3 releases"
+// class of bug: a CI gate would have flagged it on the v1.3.9 release PR.
+//
+// Rule: every `vX.Y.Z` token inside the listed description fields must
+// equal the current package.json::version. To keep a description across
+// releases without churn, drop the version reference entirely.
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const VERSION = require(path.join(ROOT, 'package.json')).version;
+
+// Match `vX.Y.Z` only (must have leading `v`) — avoids false positives on
+// schema versions like "0.3" or random numbers.
+const VERSION_PATTERN = /v(\d+\.\d+\.\d+)/g;
+
+const SOURCES = [
+  { label: 'package.json::description',                   file: 'package.json',                          extract: (raw) => JSON.parse(raw).description },
+  { label: '.claude-plugin/plugin.json::description',     file: '.claude-plugin/plugin.json',            extract: (raw) => JSON.parse(raw).description },
+  { label: '.cursor-plugin/plugin.json::description',     file: '.cursor-plugin/plugin.json',            extract: (raw) => JSON.parse(raw).description },
+  { label: 'mcp-registry.json::description',              file: 'mcp-registry.json',                     extract: (raw) => JSON.parse(raw).description },
+  { label: '.mcpb/manifest.json::description',            file: '.mcpb/manifest.json',                   extract: (raw) => JSON.parse(raw).description },
+  { label: '.mcpb/manifest.json::long_description',       file: '.mcpb/manifest.json',                   extract: (raw) => JSON.parse(raw).long_description },
+  { label: 'skills/feishu-user-plugin/SKILL.md description', file: 'skills/feishu-user-plugin/SKILL.md', extract: extractSkillDescription },
+];
+
+function extractSkillDescription(raw) {
+  // SKILL.md frontmatter has  description: "..."  on a single line.
+  const m = raw.match(/^description:\s*"((?:[^"\\]|\\.)*)"/m);
+  return m ? m[1].replace(/\\"/g, '"') : null;
+}
+
+const failures = [];
+
+for (const src of SOURCES) {
+  const fullPath = path.join(ROOT, src.file);
+  if (!fs.existsSync(fullPath)) {
+    failures.push(`${src.label}: source file ${src.file} does not exist`);
+    continue;
+  }
+
+  let description;
+  try {
+    description = src.extract(fs.readFileSync(fullPath, 'utf8'));
+  } catch (e) {
+    failures.push(`${src.label}: parse error — ${e.message}`);
+    continue;
+  }
+
+  if (!description) continue; // Field absent — nothing to check.
+
+  for (const m of description.matchAll(VERSION_PATTERN)) {
+    const found = m[1];
+    if (found !== VERSION) {
+      failures.push(`${src.label}: references v${found}, but package.json is v${VERSION}`);
+    }
+  }
+}
+
+if (failures.length) {
+  console.error('description drift detected:');
+  for (const f of failures) console.error(`  ${f}`);
+  console.error(`\nFix: update each description to reference v${VERSION}, or remove the version reference entirely (e.g. drop "v1.3.8: feature X" → "feature X").`);
+  process.exit(1);
+}
+
+console.log(`OK: all manifest descriptions reference v${VERSION} (or no version reference)`);

package/scripts/check-docs-sync.js

@@ -1,14 +1,12 @@
 #!/usr/bin/env node
 'use strict';
-// Verifies CLAUDE.md is in sync with AGENTS.md (Codex) and
-// skills/feishu-user-plugin/references/CLAUDE.md (skill reference copy).
+// Verifies CLAUDE.md is in sync with AGENTS.md (Codex).
 //
-// Pre-commit hook (scripts/sync-claude-md.sh) already auto-regenerates these
+// Pre-commit hook (scripts/sync-claude-md.sh) already auto-regenerates AGENTS.md
 // from CLAUDE.md, but this script gives prepublishOnly + CI a hard gate.
 //
-// Match logic mirrors validate.yml's diff steps:
-//   AGENTS.md = "# feishu-user-plugin — Codex Instructions\n" + tail -n +2 CLAUDE.md
-//   skills/.../CLAUDE.md = identical to CLAUDE.md
+// Match logic mirrors validate.yml's diff step:
+//   AGENTS.md = "# feishu-user-plugin — Codex 指令\n" + tail -n +2 CLAUDE.md
 
 const fs = require('fs');
 const path = require('path');
@@ -16,9 +14,9 @@ const path = require('path');
 const ROOT = path.join(__dirname, '..');
 const claude = fs.readFileSync(path.join(ROOT, 'CLAUDE.md'), 'utf8');
 
-// AGENTS.md: header replaced with "# feishu-user-plugin — Codex Instructions"
+// AGENTS.md: header replaced with "# feishu-user-plugin — Codex 指令"
 const claudeBody = claude.split('\n').slice(1).join('\n'); // drop first line
-const expectedAgents = '# feishu-user-plugin — Codex Instructions\n' + claudeBody;
+const expectedAgents = '# feishu-user-plugin — Codex 指令\n' + claudeBody;
 const actualAgents = fs.readFileSync(path.join(ROOT, 'AGENTS.md'), 'utf8');
 
 const failures = [];
@@ -27,15 +25,8 @@ if (actualAgents !== expectedAgents) {
   failures.push('Fix: bash scripts/sync-claude-md.sh (or edit CLAUDE.md and re-stage)');
 }
 
-const skillRef = path.join(ROOT, 'skills', 'feishu-user-plugin', 'references', 'CLAUDE.md');
-const actualSkillRef = fs.readFileSync(skillRef, 'utf8');
-if (actualSkillRef !== claude) {
-  failures.push('skills/feishu-user-plugin/references/CLAUDE.md is out of sync with CLAUDE.md');
-  failures.push('Fix: bash scripts/sync-claude-md.sh (or edit CLAUDE.md and re-stage)');
-}
-
 if (failures.length) {
   for (const f of failures) console.error(f);
   process.exit(1);
 }
-console.log('OK: CLAUDE.md / AGENTS.md / skill reference all in sync');
+console.log('OK: CLAUDE.md / AGENTS.md in sync');

package/scripts/check-scopes.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+'use strict';
+
+// Validates src/oauth.js::SCOPES against:
+//  1) BANLIST — scope names we've confirmed do NOT exist in Feishu's catalog
+//     (caused OAuth 422 / runtime 20043). Add new ones here when discovered.
+//  2) docs/AUTH-SETUP.md mentions — every scope in SCOPES must appear at least
+//     once in AUTH-SETUP.md, so the doc never drifts behind the code.
+//
+// Why this gate exists: Feishu's OAuth server SILENTLY accepted some malformed
+// scope names pre-2026-05 (they were ignored, UAT just lacked the scope); from
+// May 2026 it started rejecting the whole authorize request with 422 +
+// "scope <name> 有误". A single bad name in SCOPES locks every user out of
+// `npx oauth`. This script catches it in CI before merge.
+
+const path = require('path');
+const fs = require('fs');
+
+const repoRoot = path.join(__dirname, '..');
+
+// --- Step 1: extract SCOPES constant from src/oauth.js ---
+const oauthSrc = fs.readFileSync(path.join(repoRoot, 'src', 'oauth.js'), 'utf8');
+const m = oauthSrc.match(/const\s+SCOPES\s*=\s*'([^']+)'/);
+if (!m) {
+  console.error('check-scopes: could not find `const SCOPES = \'...\'` in src/oauth.js');
+  process.exit(1);
+}
+const scopes = m[1].split(/\s+/).filter(Boolean);
+
+// --- Step 1b: ADDITIONAL_APP_SCOPES — tenant-side scopes that the plugin requires
+// but that don't live in SCOPES (because they can't be granted via OAuth — only
+// in the Feishu app console "应用身份" tab). Validated against AUTH-SETUP.md only.
+const ADDITIONAL_APP_SCOPES = [
+  // Used by LarkOfficialClient.getAppName() to resolve self-app display label.
+  // Without it, `senderType=app` messages fall back to "[Bot] (cli_xxx)".
+  // Feishu marks this scope as 免审权限 (no admin review needed).
+  'application:application:self_manage',
+];
+
+// --- Step 2: BANLIST of known-bad scope names ---
+//
+// Each entry: { bad: '<name>', reason: '<why>', replacement: '<correct names>' }
+// Append-only — never remove an entry (it's a regression guard).
+const BANLIST = [
+  {
+    bad: 'calendar:calendar.event:write',
+    reason: 'Feishu catalog has no such scope. The catalog splits write into 4 verbs.',
+    replacement: 'calendar:calendar.event:create + calendar:calendar.event:update + calendar:calendar.event:delete + calendar:calendar.event:reply',
+  },
+  {
+    bad: 'okr:okr.content:write',
+    reason: 'Feishu catalog uses :writeonly (one word) not :write.',
+    replacement: 'okr:okr.content:writeonly',
+  },
+];
+
+// --- Step 3: validate ---
+const failures = [];
+
+for (const entry of BANLIST) {
+  if (scopes.includes(entry.bad)) {
+    failures.push(
+      `BANLIST hit: SCOPES contains \`${entry.bad}\`.\n` +
+      `  Reason: ${entry.reason}\n` +
+      `  Replace with: ${entry.replacement}`
+    );
+  }
+}
+
+// docs/AUTH-SETUP.md must mention every scope. Catches silent additions
+// to SCOPES that never made it into the OAuth setup docs.
+const authSetupPath = path.join(repoRoot, 'docs', 'AUTH-SETUP.md');
+const authSetup = fs.readFileSync(authSetupPath, 'utf8');
+const missingFromDocs = scopes.filter(s => s !== 'offline_access' && !authSetup.includes(s));
+if (missingFromDocs.length) {
+  failures.push(
+    `${missingFromDocs.length} scope(s) in SCOPES not mentioned in docs/AUTH-SETUP.md:\n` +
+    missingFromDocs.map(s => `  - ${s}`).join('\n') +
+    `\n  Add them to the scope table around line 117 (\`## OAuth Scopes\` section).`
+  );
+}
+
+// Same enforcement for tenant-only scopes.
+const missingAppScopes = ADDITIONAL_APP_SCOPES.filter(s => !authSetup.includes(s));
+if (missingAppScopes.length) {
+  failures.push(
+    `${missingAppScopes.length} tenant-side scope(s) not in docs/AUTH-SETUP.md:\n` +
+    missingAppScopes.map(s => `  - ${s}`).join('\n') +
+    `\n  Add them to the "应用身份额外 scope" section.`
+  );
+}
+
+if (failures.length) {
+  console.error('check-scopes: FAIL\n');
+  for (const f of failures) console.error(f + '\n');
+  process.exit(1);
+}
+
+console.log(`check-scopes: OK (${scopes.length} OAuth + ${ADDITIONAL_APP_SCOPES.length} tenant-only scopes, ${BANLIST.length} banned names guarded)`);