@lark-project/openclaw-lark-project 2026.3.131

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lark Technologies Pte. Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# OpenClaw Lark/Feishu Plugin
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/@larksuiteoapi/feishu-openclaw-plugin.svg)](https://www.npmjs.com/package/@larksuiteoapi/feishu-openclaw-plugin)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22-blue.svg)](https://nodejs.org/)
+
+[中文版](./README.zh.md) | English
+
+This is the official Lark/Feishu plugin for OpenClaw, developed and maintained by the Lark/Feishu Open Platform team. It seamlessly connects your OpenClaw Agent to your Lark/Feishu workspace, enabling it to directly read from and write to messages, docs, bases, calendars, tasks, and more.
+
+## Features
+
+This plugin provides comprehensive Lark/Feishu integration for OpenClaw, including:
+
+| Category | Capabilities |
+|------|------|
+| 💬 Messenger | Read messages (group/DM history, thread replies), send messages, reply to messages, search messages, download images/files |
+| 📄 Docs | Create, update, and read documents |
+| 📊 Base | Create/manage bases, tables, fields, records (CRUD, batch operations, advanced filtering), views |
+| 📈 Sheets | Create, edit, and view spreadsheets |
+| 📅 Calendar | Manage calendars and events (create/query/update/delete/search), manage attendees, check free/busy status |
+| ✅ Tasks | Manage tasks (create/query/update/complete), manage task lists, subtasks, and comments |
+
+Additionally, the plugin supports:
+- **📱 Interactive Cards**: Real-time status updates (Thinking/Generating/Complete), plus confirmation buttons for sensitive operations
+- **🌊 Streaming Responses**: Live streaming text directly within message cards
+- **🔒 Permission Policies**: Flexible access control policies for DMs and group chats
+- **⚙️ Advanced Group Configuration**: Per-group settings including allowlists, skill bindings, and custom system prompts
+
+## Security & Risk Warnings (Read Before Use)
+
+**Core risk:** This plugin connects to your work data via Lark/Feishu APIs—messages, docs, calendars, contacts. Anything the AI can read could theoretically be leaked. While we have implemented security protections, AI systems are not yet mature or stable enough to guarantee absolute safety.
+
+**Strong recommendations:**
+- Use a personal account for evaluation and testing at this stage.
+- Use the related Lark/Feishu apps personally, and avoid deploying to large numbers of users.
+- Avoid using it in group chats to reduce the risk of data exposure.
+- Using this bot for multiple users and/or with a company Feishu account may introduce data security and privacy risks. Make sure you comply with your organization’s internal data security and privacy requirements to avoid data leakage, privilege escalation, privacy violations, or related consequences.
+
+**Other operational risks**
+- AI is not perfect and may hallucinate: It may sometimes misunderstand your intent or generate content that appears reasonable but is inaccurate.
+- Some operations are irreversible: For example, messages sent by the AI on your behalf are sent in your name and cannot be undone once sent.
+- **Mitigation advice:** For important operations involving sending, modifying, or writing data, always **preview first, then confirm**. Never allow the AI to operate in a fully autonomous mode without human oversight.
+
+**Disclaimer:**
+
+This software is licensed under the MIT License. When running, it calls Lark/Feishu Open Platform APIs. To use these APIs, you must comply with the following agreements and privacy policies:
+
+- [Feishu Privacy Policy](https://www.feishu.cn/en/privacy?from=openclaw_plugin_readme)
+- [Feishu User Terms of Service](https://www.feishu.cn/en/terms?from=openclaw_plugin_readme)
+- [Feishu Store App Service Provider Security Management Specifications](https://open.larkoffice.com/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/management-practice/app-service-provider-security-management-specifications)
+
+- [Lark Privacy Policy](https://www.larksuite.com/user-terms-of-service)
+- [Lark User Terms of Service](https://www.larksuite.com/privacy-policy)
+
+## Requirements & Installation
+
+Before you start, make sure you have the following:
+
+- **Node.js**: `v22` or higher.
+- **OpenClaw**: OpenClaw is installed and works properly. For details, visit the [OpenClaw official website](https://openclaw.ai).
+
+> **Note**: OpenClaw version must be **2026.2.26** or higher. Check with `openclaw -v`. If below this version, you may encounter issues. Upgrade with:
+> ```bash
+> npm install -g openclaw
+> ```
+
+## Usage Guide
+
+[How to Use the Official Lark/Feishu Plugin for OpenClaw](https://bytedance.larkoffice.com/docx/MFK7dDFLFoVlOGxWCv5cTXKmnMh)
+
+## Contributing
+
+Community contributions are welcome! If you find a bug or have feature suggestions, please submit an [Issue](https://github.com/larksuite/openclaw-larksuite/issues) or a [Pull Request](https://github.com/larksuite/openclaw-larksuite/pulls).
+
+For major changes, we recommend discussing with us first via an Issue.
+
+## License
+
+This project is licensed under the **MIT License**. See [LICENSE](./LICENSE.md) for details.

package/README.zh.md

@@ -0,0 +1,80 @@
+# OpenClaw  Lark/飞书 插件
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/@larksuiteoapi/feishu-openclaw-plugin.svg)](https://www.npmjs.com/package/@larksuiteoapi/feishu-openclaw-plugin)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22-blue.svg)](https://nodejs.org/)
+
+[English](./README.md) | 中文版
+
+这是 OpenClaw 的官方  Lark/飞书 插件，由 Lark/飞书开放平台团队开发和维护。它将你的 OpenClaw Agent 无缝对接到  Lark/飞书 工作区，赋予其直接读写消息、文档、多维表格、日历、任务等应用的能力。
+
+## 特性
+
+本插件为 OpenClaw 提供了全面的 Lark/飞书集成能力，主要包括：
+
+| 类别 | 能力 |
+|------|------|
+| 💬 消息 | 消息读取（群聊/单聊历史、话题回复）、消息发送、消息回复、消息搜索、图片/文件下载 |
+| 📄 文档 | 创建云文档、更新云文档、读取云文档内容 |
+| 📊 多维表格 | 创建/管理多维表格、数据表、字段、记录（增删改查、批量操作、高级筛选）、视图 |
+| 📈 电子表格 | 创建、编辑、查看电子表格 |
+| 📅 日历日程 | 日历管理、日程管理（创建/查询/修改/删除/搜索）、参会人管理、忙闲查询 |
+| ✅ 任务 | 任务管理（创建/查询/更新/完成）、清单管理、子任务、评论 |
+
+此外，插件还支持：
+- **📱 交互式卡片**：实时状态更新（思考中/生成中/完成状态），提供敏感操作的确认按钮
+- **🌊 流式回复**：在消息卡片中提供实时的流式响应
+- **🔒 权限策略**：为私聊和群聊提供灵活的访问控制策略
+- **⚙️ 高级群组配置**：每个群聊的独立设置，包括白名单、技能绑定和自定义系统提示词
+
+## 安全与风险提示（使用前必读）
+
+**核心风险：** 这个插件通过 Lark/飞书接口连接了你的工作数据——消息、文档、日历、联系人，AI 能读到的东西理论上就有泄露的可能。虽然我们做了安全防护，但 AI 系统本身还不够成熟稳定，不能保证万无一失。
+
+**强烈建议：** 
+
+- 现阶段优先使用个人账号进行体验和测试。
+- 相关 Lark/飞书应用推荐个人使用，不建议开放给多人使用。
+- 建议避免在群聊中使用，降低你的数据泄露风险。
+
+**其他操作风险**
+- AI 并不完美，可能存在"幻觉"：它有时会误解您的意图，或者生成看似合理但不准确的内容。
+- 部分操作不可逆转：例如，AI 代发的 Lark/飞书消息是以您的名义发出的，发出后即成事实。
+- **应对建议：** 对于涉及发送、修改、写入等重要操作，请务必做到**"先预览，再确认"**，切勿让 AI 处于完全脱离人工干预的"全自动驾驶"状态。
+- 作为机器人供多人使用或者通过公司飞书账号使用可能会导致数据安全和隐私风险，请注意使用时需要遵守企业内的数据安全和隐私要求，避免发生数据泄露、权限突破、侵犯隐私等后果
+
+**免责声明：** 
+
+本软件的代码采用MIT许可证。
+该软件运行时会调用Lark/飞书开放平台的API，使用这些API需要遵守如下协议和隐私政策：
+
+- [飞书用户服务协议](https://www.feishu.cn/terms)
+- [飞书隐私政策](https://www.feishu.cn/privacy)
+- [飞书开放平台独立软件服务商安全管理运营规范](https://open.larkoffice.com/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/management-practice/app-service-provider-security-management-specifications)
+- [Lark用户服务协议](https://www.larksuite.com/user-terms-of-service)
+- [Lark隐私政策](https://www.larksuite.com/privacy-policy)
+
+## 安装与要求
+
+在开始之前，请确保你已准备好以下各项：
+
+- **Node.js**: `v22` 或更高版本。
+- **OpenClaw**: OpenClaw 已成功安装并可运行。详情请访问 [OpenClaw 官方网站](https://openclaw.ai)。
+
+> **注意**：OpenClaw 版本需在 **2026.2.26** 及以上，可通过 `openclaw -v` 命令查看。如果低于该版本可能出现异常，执行以下命令升级：
+> ```bash
+> npm install -g openclaw
+> ```
+
+## 使用说明
+[OpenClaw  Lark/飞书官方插件使用指南](https://bytedance.larkoffice.com/docx/MFK7dDFLFoVlOGxWCv5cTXKmnMh)
+
+## 贡献
+
+我们欢迎社区的贡献！如果你发现 Bug 或有功能建议，请随时提交 [Issue](https://github.com/larksuite/openclaw-larksuite/issues) 或 [Pull Request](https://github.com/larksuite/openclaw-larksuite/pulls)。
+
+对于较大的改动，我们建议你先通过 Issue 与我们讨论。
+
+## 许可证
+
+本项目基于 **MIT 许可证**。详情请参阅 [LICENSE](./LICENSE.md) 文件。

package/dist/index.js

@@ -0,0 +1,172 @@
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { feishuPlugin } from "./src/channel/plugin";
+import { LarkClient } from "./src/core/lark-client";
+import { registerOapiTools } from "./src/tools/oapi/index";
+import { registerFeishuMcpDocTools } from "./src/tools/mcp/doc/index";
+import { registerFeishuMcpProjectTools } from "./src/tools/mcp/project/index";
+import { registerFeishuOAuthTool } from "./src/tools/oauth";
+import { registerFeishuOAuthBatchAuthTool } from "./src/tools/oauth-batch-auth";
+import { registerFeishuProjectOAuthTool } from "./src/tools/project-oauth";
+import {
+  runDiagnosis,
+  formatDiagReportCli,
+  traceByMessageId,
+  formatTraceOutput,
+  analyzeTrace
+} from "./src/commands/diagnose";
+import { registerCommands } from "./src/commands/index";
+import { larkLogger } from "./src/core/lark-logger";
+import { emitSecurityWarnings } from "./src/core/security-check";
+const log = larkLogger("plugin");
+import { monitorFeishuProvider } from "./src/channel/monitor";
+import { sendMessageFeishu, sendCardFeishu, updateCardFeishu, editMessageFeishu } from "./src/messaging/outbound/send";
+import { getMessageFeishu } from "./src/messaging/outbound/fetch";
+import {
+  uploadImageLark,
+  uploadFileLark,
+  sendImageLark,
+  sendFileLark,
+  sendAudioLark,
+  uploadAndSendMediaLark
+} from "./src/messaging/outbound/media";
+import {
+  sendTextLark,
+  sendCardLark,
+  sendMediaLark
+} from "./src/messaging/outbound/deliver";
+import { probeFeishu } from "./src/channel/probe";
+import {
+  addReactionFeishu,
+  removeReactionFeishu,
+  listReactionsFeishu,
+  FeishuEmoji,
+  VALID_FEISHU_EMOJI_TYPES
+} from "./src/messaging/outbound/reactions";
+import { forwardMessageFeishu } from "./src/messaging/outbound/forward";
+import {
+  updateChatFeishu,
+  addChatMembersFeishu,
+  removeChatMembersFeishu,
+  listChatMembersFeishu
+} from "./src/messaging/outbound/chat-manage";
+import { feishuMessageActions } from "./src/messaging/outbound/actions";
+import {
+  mentionedBot,
+  nonBotMentions,
+  extractMessageBody,
+  formatMentionForText,
+  formatMentionForCard,
+  formatMentionAllForText,
+  formatMentionAllForCard,
+  buildMentionedMessage,
+  buildMentionedCardContent
+} from "./src/messaging/inbound/mention";
+import { feishuPlugin as feishuPlugin2 } from "./src/channel/plugin";
+import { handleFeishuReaction } from "./src/messaging/inbound/reaction-handler";
+import { parseMessageEvent } from "./src/messaging/inbound/parse";
+import { checkMessageGate } from "./src/messaging/inbound/gate";
+import { isMessageExpired } from "./src/messaging/inbound/dedup";
+const plugin = {
+  id: "feishu-openclaw-plugin",
+  name: "Feishu",
+  description: "Lark/Feishu channel plugin with im/doc/wiki/drive/task/calendar tools",
+  configSchema: emptyPluginConfigSchema(),
+  register(api) {
+    LarkClient.setRuntime(api.runtime);
+    api.registerChannel({ plugin: feishuPlugin });
+    registerOapiTools(api);
+    registerFeishuMcpDocTools(api);
+    registerFeishuMcpProjectTools(api);
+    registerFeishuOAuthTool(api);
+    registerFeishuOAuthBatchAuthTool(api);
+    registerFeishuProjectOAuthTool(api);
+    api.on("before_tool_call", (event) => {
+      log.info(`tool call: ${event.toolName} params=${JSON.stringify(event.params)}`);
+    });
+    api.on("after_tool_call", (event) => {
+      if (event.error) {
+        log.error(`tool fail: ${event.toolName} ${event.error} (${event.durationMs ?? 0}ms)`);
+      } else {
+        log.info(`tool done: ${event.toolName} ok (${event.durationMs ?? 0}ms)`);
+      }
+    });
+    api.registerCli(
+      (ctx) => {
+        ctx.program.command("feishu-diagnose").description("\u8FD0\u884C\u98DE\u4E66\u63D2\u4EF6\u8BCA\u65AD\uFF0C\u68C0\u67E5\u914D\u7F6E\u3001\u8FDE\u901A\u6027\u548C\u6743\u9650\u72B6\u6001").option("--trace <messageId>", "\u6309 message_id \u8FFD\u8E2A\u5B8C\u6574\u5904\u7406\u94FE\u8DEF").option("--analyze", "\u5206\u6790\u8FFD\u8E2A\u65E5\u5FD7\uFF08\u9700\u914D\u5408 --trace \u4F7F\u7528\uFF09").action(async (opts) => {
+          try {
+            if (opts.trace) {
+              const lines = await traceByMessageId(opts.trace);
+              console.log(formatTraceOutput(lines, opts.trace));
+              if (opts.analyze && lines.length > 0) {
+                console.log(analyzeTrace(lines, opts.trace));
+              }
+            } else {
+              const report = await runDiagnosis({
+                config: ctx.config,
+                logger: ctx.logger
+              });
+              console.log(formatDiagReportCli(report));
+              if (report.overallStatus === "unhealthy") {
+                process.exitCode = 1;
+              }
+            }
+          } catch (err) {
+            ctx.logger.error(`\u8BCA\u65AD\u547D\u4EE4\u6267\u884C\u5931\u8D25: ${err}`);
+            process.exitCode = 1;
+          }
+        });
+      },
+      { commands: ["feishu-diagnose"] }
+    );
+    registerCommands(api);
+    if (api.config) {
+      emitSecurityWarnings(api.config, api.logger);
+    }
+  }
+};
+var index_default = plugin;
+export {
+  FeishuEmoji,
+  VALID_FEISHU_EMOJI_TYPES,
+  addChatMembersFeishu,
+  addReactionFeishu,
+  buildMentionedCardContent,
+  buildMentionedMessage,
+  checkMessageGate,
+  index_default as default,
+  editMessageFeishu,
+  extractMessageBody,
+  feishuMessageActions,
+  feishuPlugin2 as feishuPlugin,
+  formatMentionAllForCard,
+  formatMentionAllForText,
+  formatMentionForCard,
+  formatMentionForText,
+  forwardMessageFeishu,
+  getMessageFeishu,
+  handleFeishuReaction,
+  isMessageExpired,
+  listChatMembersFeishu,
+  listReactionsFeishu,
+  mentionedBot,
+  monitorFeishuProvider,
+  nonBotMentions,
+  parseMessageEvent,
+  probeFeishu,
+  removeChatMembersFeishu,
+  removeReactionFeishu,
+  sendAudioLark,
+  sendCardFeishu,
+  sendCardLark,
+  sendFileLark,
+  sendImageLark,
+  sendMediaLark,
+  sendMessageFeishu,
+  sendTextLark,
+  updateCardFeishu,
+  updateChatFeishu,
+  uploadAndSendMediaLark,
+  uploadFileLark,
+  uploadImageLark
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../index.ts"],
+  "sourcesContent": ["/**\n * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates\n * SPDX-License-Identifier: MIT\n *\n * OpenClaw Lark/Feishu plugin entry point.\n *\n * Registers the Feishu channel and all tool families:\n * doc, wiki, drive, perm, bitable, task, calendar.\n */\n\nimport type { OpenClawPluginApi } from 'openclaw/plugin-sdk';\nimport { emptyPluginConfigSchema } from 'openclaw/plugin-sdk';\nimport { feishuPlugin } from './src/channel/plugin';\nimport { LarkClient } from './src/core/lark-client';\nimport { registerOapiTools } from './src/tools/oapi/index';\nimport { registerFeishuMcpDocTools } from './src/tools/mcp/doc/index';\nimport { registerFeishuMcpProjectTools } from './src/tools/mcp/project/index';\nimport { registerFeishuOAuthTool } from './src/tools/oauth';\nimport { registerFeishuOAuthBatchAuthTool } from './src/tools/oauth-batch-auth';\nimport { registerFeishuProjectOAuthTool } from './src/tools/project-oauth';\nimport {\n  runDiagnosis,\n  formatDiagReportCli,\n  traceByMessageId,\n  formatTraceOutput,\n  analyzeTrace,\n} from './src/commands/diagnose';\nimport { registerCommands } from './src/commands/index';\nimport { larkLogger } from './src/core/lark-logger';\nimport { emitSecurityWarnings } from './src/core/security-check';\n\nconst log = larkLogger('plugin');\n\n// ---------------------------------------------------------------------------\n// Re-exports for external consumers\n// ---------------------------------------------------------------------------\n\nexport { monitorFeishuProvider } from './src/channel/monitor';\nexport { sendMessageFeishu, sendCardFeishu, updateCardFeishu, editMessageFeishu } from './src/messaging/outbound/send';\nexport { getMessageFeishu } from './src/messaging/outbound/fetch';\nexport {\n  uploadImageLark,\n  uploadFileLark,\n  sendImageLark,\n  sendFileLark,\n  sendAudioLark,\n  uploadAndSendMediaLark,\n} from './src/messaging/outbound/media';\nexport {\n  sendTextLark,\n  sendCardLark,\n  sendMediaLark,\n  type SendTextLarkParams,\n  type SendCardLarkParams,\n  type SendMediaLarkParams,\n} from './src/messaging/outbound/deliver';\nexport { type FeishuChannelData } from './src/messaging/outbound/outbound';\nexport { probeFeishu } from './src/channel/probe';\nexport {\n  addReactionFeishu,\n  removeReactionFeishu,\n  listReactionsFeishu,\n  FeishuEmoji,\n  VALID_FEISHU_EMOJI_TYPES,\n} from './src/messaging/outbound/reactions';\nexport { forwardMessageFeishu } from './src/messaging/outbound/forward';\nexport {\n  updateChatFeishu,\n  addChatMembersFeishu,\n  removeChatMembersFeishu,\n  listChatMembersFeishu,\n} from './src/messaging/outbound/chat-manage';\nexport { feishuMessageActions } from './src/messaging/outbound/actions';\nexport {\n  mentionedBot,\n  nonBotMentions,\n  extractMessageBody,\n  formatMentionForText,\n  formatMentionForCard,\n  formatMentionAllForText,\n  formatMentionAllForCard,\n  buildMentionedMessage,\n  buildMentionedCardContent,\n  type MentionInfo,\n} from './src/messaging/inbound/mention';\nexport { feishuPlugin } from './src/channel/plugin';\nexport type {\n  MessageContext,\n  RawMessage,\n  RawSender,\n  FeishuMessageContext,\n  FeishuReactionCreatedEvent,\n} from './src/messaging/types';\nexport { handleFeishuReaction } from './src/messaging/inbound/reaction-handler';\nexport { parseMessageEvent } from './src/messaging/inbound/parse';\nexport { checkMessageGate } from './src/messaging/inbound/gate';\nexport { isMessageExpired } from './src/messaging/inbound/dedup';\n\n// ---------------------------------------------------------------------------\n// Plugin definition\n// ---------------------------------------------------------------------------\n\nconst plugin = {\n  id: 'feishu-openclaw-plugin',\n  name: 'Feishu',\n  description: 'Lark/Feishu channel plugin with im/doc/wiki/drive/task/calendar tools',\n  configSchema: emptyPluginConfigSchema(),\n  register(api: OpenClawPluginApi) {\n    LarkClient.setRuntime(api.runtime);\n    api.registerChannel({ plugin: feishuPlugin });\n\n    // ========================================\n\n    // Register OAPI tools (calendar, task - using Feishu Open API directly)\n    registerOapiTools(api);\n\n    // Register MCP doc tools (using Model Context Protocol)\n    registerFeishuMcpDocTools(api);\n\n    // Register MCP project tools (Meego - using independent OAuth)\n    registerFeishuMcpProjectTools(api);\n\n    // Register OAuth tool (UAT device flow authorization)\n    registerFeishuOAuthTool(api);\n\n    // Register OAuth batch auth tool (batch authorization for all app scopes)\n    registerFeishuOAuthBatchAuthTool(api);\n\n    // Register Feishu Project OAuth tool (independent OAuth for Meego)\n    registerFeishuProjectOAuthTool(api);\n\n    // ---- Tool call hooks (auto-trace AI tool invocations) ----\n\n    api.on('before_tool_call', (event) => {\n      log.info(`tool call: ${event.toolName} params=${JSON.stringify(event.params)}`);\n    });\n\n    api.on('after_tool_call', (event) => {\n      if (event.error) {\n        log.error(`tool fail: ${event.toolName} ${event.error} (${event.durationMs ?? 0}ms)`);\n      } else {\n        log.info(`tool done: ${event.toolName} ok (${event.durationMs ?? 0}ms)`);\n      }\n    });\n\n    // ---- Diagnostic commands ----\n\n    // CLI: openclaw feishu-diagnose [--trace <messageId>]\n    api.registerCli(\n      (ctx) => {\n        ctx.program\n          .command('feishu-diagnose')\n          .description('\u8FD0\u884C\u98DE\u4E66\u63D2\u4EF6\u8BCA\u65AD\uFF0C\u68C0\u67E5\u914D\u7F6E\u3001\u8FDE\u901A\u6027\u548C\u6743\u9650\u72B6\u6001')\n          .option('--trace <messageId>', '\u6309 message_id \u8FFD\u8E2A\u5B8C\u6574\u5904\u7406\u94FE\u8DEF')\n          .option('--analyze', '\u5206\u6790\u8FFD\u8E2A\u65E5\u5FD7\uFF08\u9700\u914D\u5408 --trace \u4F7F\u7528\uFF09')\n          .action(async (opts: { trace?: string; analyze?: boolean }) => {\n            try {\n              if (opts.trace) {\n                const lines = await traceByMessageId(opts.trace);\n                // eslint-disable-next-line no-console -- CLI \u547D\u4EE4\u76F4\u63A5\u8F93\u51FA\u5230\u7EC8\u7AEF\n                console.log(formatTraceOutput(lines, opts.trace));\n                if (opts.analyze && lines.length > 0) {\n                  // eslint-disable-next-line no-console -- CLI \u547D\u4EE4\u76F4\u63A5\u8F93\u51FA\u5230\u7EC8\u7AEF\n                  console.log(analyzeTrace(lines, opts.trace));\n                }\n              } else {\n                const report = await runDiagnosis({\n                  config: ctx.config,\n                  logger: ctx.logger,\n                });\n                // eslint-disable-next-line no-console -- CLI \u547D\u4EE4\u76F4\u63A5\u8F93\u51FA\u5230\u7EC8\u7AEF\n                console.log(formatDiagReportCli(report));\n                if (report.overallStatus === 'unhealthy') {\n                  process.exitCode = 1;\n                }\n              }\n            } catch (err) {\n              ctx.logger.error(`\u8BCA\u65AD\u547D\u4EE4\u6267\u884C\u5931\u8D25: ${err}`);\n              process.exitCode = 1;\n            }\n          });\n      },\n      { commands: ['feishu-diagnose'] },\n    );\n\n    // Chat commands: /feishu_diagnose, /feishu_doctor, /feishu_auth, /feishu\n    registerCommands(api);\n\n    // ---- Multi-account security checks ----\n    if (api.config) {\n      emitSecurityWarnings(api.config, api.logger);\n    }\n  },\n};\n\nexport default plugin;\n"],
+  "mappings": "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",
+  "names": ["feishuPlugin"]
+}

package/dist/skills/feishu-bitable/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: feishu-bitable
+description: |
+  飞书多维表格（Bitable）的创建、查询、编辑和管理工具。包含 27 种字段类型支持、高级筛选、批量操作和视图管理。
+
+  **当以下情况时使用此 Skill**：
+  (1) 需要创建或管理飞书多维表格 App
+  (2) 需要在多维表格中新增、查询、修改、删除记录（行数据）
+  (3) 需要管理字段（列）、视图、数据表
+  (4) 用户提到"多维表格"、"bitable"、"数据表"、"记录"、"字段"
+  (5) 需要批量导入数据或批量更新多维表格
+---
+
+# Feishu Bitable (多维表格) SKILL
+
+## 🚨 执行前必读
+
+- ✅ **创建数据表**：支持两种模式 — ① 明确需求时，在 `create` 时通过 `table.fields` 一次性定义字段（减少 API 调用）；② 探索式场景时，使用默认表 + 逐步修改字段（更稳定，易调整）
+- ⚠️ **默认表的空行坑**：`app.create` 自带的默认表中会有空记录（空行）！插入数据前建议先调用 `feishu_bitable_app_table_record.list` + `batch_delete` 删除空行，避免数据污染
+- ✅ **写记录前**：先调用 `feishu_bitable_app_table_field.list` 获取字段 type/ui_type
+- ✅ **人员字段**：默认 open_id（ou_...），值必须是 `[{id:"ou_xxx"}]`（数组对象）
+- ✅ **日期字段**：毫秒时间戳（例如 `1674206443000`），不是秒
+- ✅ **单选字段**：字符串（例如 `"选项1"`），不是数组
+- ✅ **多选字段**：字符串数组（例如 `["选项1", "选项2"]`）
+- ✅ **附件字段**：必须先上传到当前多维表格，使用返回的 file_token
+- ✅ **批量上限**：单次 ≤ 500 条，超过需分批（批量操作是原子性的）
+- ✅ **并发限制**：同一数据表不支持并发写，需串行调用 + 延迟 0.5-1 秒
+
+---
+
+## 📋 快速索引：意图 → 工具 → 必填参数
+
+| 用户意图 | 工具 | action | 必填参数 | 常用可选 |
+|---------|------|--------|---------|---------|
+| 查表有哪些字段 | feishu_bitable_app_table_field | list | app_token, table_id | - |
+| 查记录 | feishu_bitable_app_table_record | list | app_token, table_id | filter, sort, field_names |
+| 新增一行 | feishu_bitable_app_table_record | create | app_token, table_id, fields | - |
+| 批量导入 | feishu_bitable_app_table_record | batch_create | app_token, table_id, records (≤500) | - |
+| 更新一行 | feishu_bitable_app_table_record | update | app_token, table_id, record_id, fields | - |
+| 批量更新 | feishu_bitable_app_table_record | batch_update | app_token, table_id, records (≤500) | - |
+| 创建多维表格 | feishu_bitable_app | create | name | folder_token |
+| 创建数据表 | feishu_bitable_app_table | create | app_token, name | fields |
+| 创建字段 | feishu_bitable_app_table_field | create | app_token, table_id, field_name, type | property |
+| 创建视图 | feishu_bitable_app_table_view | create | app_token, table_id, view_name, view_type | - |
+
+---
+
+## 🎯 核心约束（Schema 未透露的知识）
+
+### 📚 详细参考文档
+
+**当遇到字段配置、记录值格式问题或需要完整示例时，查阅以下文档**：
+
+- **[字段 Property 配置详解](references/field-properties.md)** - 每种字段类型创建/更新时需要的 `property` 参数结构（单选的 options、进度的 min/max、关联的 table_id 等）
+- **[记录值数据结构详解](references/record-values.md)** - 每种字段类型在记录中对应的 `fields` 值格式（人员字段只传 id、日期是毫秒时间戳、附件需先上传等）
+- **[使用场景完整示例](references/examples.md)** - 8 个完整场景示例（创建表模式对比、批量导入、筛选查询、附件处理、关联字段等）
+
+**何时查阅**:
+- 创建/更新字段时收到 `125408X` 错误码（property 结构错误）→ 查 field-properties.md
+- 写入记录时收到 `125406X` 错误码（字段值转换失败）→ 查 record-values.md
+- 需要完整的操作流程和参数示例 → 查 examples.md
+
+---
+
+### 1. 字段类型与值格式必须严格匹配
+
+**Bitable 最大的坑**：不同字段类型对 value 的数据结构要求完全不同。
+
+#### 最易错的字段类型（完整列表见 [record-values.md](references/record-values.md)）
+
+| type | ui_type | 字段类型 | 正确格式 | ❌ 常见错误 |
+|------|---------|----------|---------|-----------|
+| 11 | User | 人员 | `[{id: "ou_xxx"}]` | 传字符串 `"ou_xxx"` 或 `[{name: "张三"}]` |
+| 5 | DateTime | 日期 | `1674206443000`（毫秒） | 传秒时间戳或字符串 |
+| 3 | SingleSelect | 单选 | `"选项名"` | 传数组 `["选项名"]` |
+| 4 | MultiSelect | 多选 | `["选项1", "选项2"]` | 传字符串 `"选项1"` |
+| 15 | Url | 超链接 | `{link: "...", text: "..."}` | 只传字符串 URL |
+| 17 | Attachment | 附件 | `[{file_token: "..."}]` | 传外部 URL 或本地路径 |
+
+**强制流程**：
+1. 先调用 `feishu_bitable_app_table_field.list` 获取字段的 `type` 和 `ui_type`
+2. 根据上表或 [record-values.md](references/record-values.md) 构造正确格式
+3. 错误码 `125406X` 或 `1254015` → 检查字段值格式
+
+**人员字段特别注意**：
+- 默认使用 open_id（ou_...），与 calendar/task 一致
+- 格式：`[{id: "ou_xxx"}]`（数组对象）
+- **只能传 id 字段**，不能传 name/email 等
+
+
+## 📌 核心使用场景
+
+> **完整示例**: 查阅 [examples.md](references/examples.md) 了解更多场景（创建表模式对比、空行处理、附件上传、关联字段等）
+
+### 场景 1: 查字段类型（必做第一步）
+
+```json
+{
+  "action": "list",
+  "app_token": "S404b...",
+  "table_id": "tbl..."
+}
+```
+
+**返回**：包含每个字段的 `field_id`、`field_name`、`type`、`ui_type`、`property`
+
+### 场景 2: 批量导入客户数据
+
+```json
+{
+  "action": "batch_create",
+  "app_token": "S404b...",
+  "table_id": "tbl...",
+  "records": [
+    {
+      "fields": {
+        "客户名称": "Bytedance",
+        "负责人": [{"id": "ou_xxx"}],
+        "签约日期": 1674206443000,
+        "状态": "进行中"
+      }
+    },
+    {
+      "fields": {
+        "客户名称": "飞书",
+        "负责人": [{"id": "ou_yyy"}],
+        "签约日期": 1675416243000,
+        "状态": "已完成"
+      }
+    }
+  ]
+}
+```
+
+**字段值格式**：
+- 人员：`[{id: "ou_xxx"}]`（数组对象）
+- 日期：毫秒时间戳
+- 单选：字符串
+- 多选：字符串数组
+
+**限制**: 最多 500 条记录
+
+### 场景 3: 筛选查询（高级筛选）
+
+```json
+{
+  "action": "list",
+  "app_token": "S404b...",
+  "table_id": "tbl...",
+  "filter": {
+    "conjunction": "and",
+    "conditions": [
+      {
+        "field_name": "状态",
+        "operator": "is",
+        "value": ["进行中"]
+      },
+      {
+        "field_name": "截止日期",
+        "operator": "isLess",
+        "value": ["ExactDate", "1740441600000"]
+      }
+    ]
+  },
+  "sort": [
+    {
+      "field_name": "截止日期",
+      "desc": false
+    }
+  ]
+}
+```
+
+**filter 说明**：
+- 支持 10 种 operator（is/isNot/contains/isEmpty 等，见附录 C）
+- ⚠️ **isEmpty/isNotEmpty 必须传 `value: []`**（虽然逻辑上不需要值，但 API 要求必须传空数组）
+- 日期筛选可使用 `["Today"]`、`["ExactDate", "时间戳"]` 等
+- `sort` 可指定多个排序字段
+
+---
+
+## 🔍 常见错误与排查
+
+| 错误码 | 错误现象 | 根本原因 | 解决方案 |
+|--------|---------|---------|---------|
+| 1254064 | DatetimeFieldConvFail | 日期字段格式错误 | **必须用毫秒时间戳**（如 `1772121600000`），不能用字符串（`"2026-02-27"`、RFC3339）或秒级时间戳 |
+| 1254068 | URLFieldConvFail | 超链接字段格式错误 | **必须用对象** `{text: "显示文本", link: "URL"}`，不能直接传字符串 URL |
+| 1254066 | UserFieldConvFail | 人员字段格式错误或 ID 类型不匹配 | 必须传 `[{id: "ou_xxx"}]`，确认 `user_id_type` |
+| 1254015 | Field types do not match | 字段值格式与类型不匹配 | 先 list 字段，按类型构造正确格式 |
+| 1254104 | RecordAddOnceExceedLimit | 批量创建超过 500 条 | 分批调用，每批 ≤ 500 |
+| 1254291 | Write conflict | 并发写冲突 | 串行调用 + 延迟 0.5-1 秒 |
+| 1254303 | AttachPermNotAllow | 附件未上传到当前表格 | 先调用上传素材接口 |
+| 1254045 | FieldNameNotFound | 字段名不存在 | 检查字段名（包括空格、大小写） |
+
+---
+
+## 📚 附录：背景知识
+
+### A. 资源层级关系
+
+```
+App (多维表格应用)
+ ├── Table (数据表) ×100
+ │    ├── Record (记录/行) ×20,000
+ │    ├── Field (字段/列) ×300
+ │    └── View (视图) ×200
+ └── Dashboard (仪表盘)
+```
+
+### B. 筛选条件 operator 列表
+
+| operator | 含义 | 支持字段 | value 要求 |
+|----------|------|----------|-----------|
+| `is` | 等于 | 所有 | 单个值 |
+| `isNot` | 不等于 | 除日期外 | 单个值 |
+| `contains` | 包含 | 除日期外 | 可多个值 |
+| `doesNotContain` | 不包含 | 除日期外 | 可多个值 |
+| `isEmpty` | 为空 | 所有 | 必须为 `[]` |
+| `isNotEmpty` | 不为空 | 所有 | 必须为 `[]` |
+| `isGreater` | 大于 | 数字、日期 | 单个值 |
+| `isGreaterEqual` | 大于等于 | 数字（不支持日期） | 单个值 |
+| `isLess` | 小于 | 数字、日期 | 单个值 |
+| `isLessEqual` | 小于等于 | 数字（不支持日期） | 单个值 |
+
+**日期字段特殊值**: `["Today"]`, `["Tomorrow"]`, `["ExactDate", "时间戳"]` 等（完整列表见 [examples.md](references/examples.md#场景-3-筛选查询高级筛选)）
+
+### C. 使用限制
+
+| 限制项 | 上限 |
+|--------|------|
+| 数据表 + 仪表盘 | 100（单个 App） |
+| 记录数 | 20,000（单个数据表） |
+| 字段数 | 300（单个数据表） |
+| 视图数 | 200（单个数据表） |
+| 批量创建/更新/删除 | 500（单次 API 调用） |
+| 单元格文本 | 10 万字符 |
+| 单选/多选选项 | 20,000（单个字段） |
+| 单元格附件 | 100 |
+| 单元格人员 | 1,000 |
+
+
+
+### D. 其他约束
+
+- 从其他数据源同步的数据表，**不支持增删改**记录
+- 公式字段、查看引用字段是**只读**的
+- 删除操作**无法恢复**
+- 视图筛选条件使用 `field_id`，需先调用 field.list 获取