@larksuite/openclaw-lark 2026.5.20 → 2026.6.10-beta.0

package/README.zh.md

@@ -0,0 +1,70 @@
+# 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/@larksuite/openclaw-lark.svg)](https://www.npmjs.com/package/@larksuite/openclaw-lark)
+[![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/飞书集成能力，主要包括：
+
+| 类别 | 能力 |
+|------|------|
+| 💬 消息 | 消息读取（群聊/单聊历史、话题回复）、消息发送、消息回复、消息搜索、图片/文件下载 |
+| 📄 文档 | 创建云文档、更新云文档、读取云文档内容 |
+| 📊 多维表格 | 创建/管理多维表格、数据表、字段、记录（增删改查、批量操作、高级筛选）、视图 |
+| 📈 电子表格 | 创建、编辑、查看电子表格 |
+| 📅 日历日程 | 日历管理、日程管理（创建/查询/修改/删除/搜索）、参会人管理、忙闲查询 |
+| ✅ 任务 | 任务管理（创建/查询/更新/完成）、清单管理、子任务、评论 |
+
+此外，插件还支持：
+- **📱 交互式卡片**：实时状态更新（思考中/生成中/完成状态），提供敏感操作的确认按钮
+- **🌊 流式回复**：在消息卡片中提供实时的流式响应
+- **🔒 权限策略**：为私聊和群聊提供灵活的访问控制策略
+- **⚙️ 高级群组配置**：每个群聊的独立设置，包括白名单、技能绑定和自定义系统提示词
+
+## 安全与风险提示（使用前必读）
+本插件对接 OpenClaw AI 自动化能力，存在模型幻觉、执行不可控、提示词注入等固有风险；授权飞书权限后，OpenClaw 将以您的用户身份在授权范围内执行操作，可能导致敏感数据泄露、越权操作等高风险后果，请您谨慎操作和使用。
+为降低上述风险，插件已在多个层面启用默认安全保护以降低上述风险，但上述风险仍然存在。我们强烈建议不要主动修改任何默认安全配置；一旦放开相关限制，上述风险将显著提高，由此产生的后果需由您自行承担。
+我们建议您将接入 OpenClaw 的飞书机器人作为私人对话助手使用，请勿将其拉入群聊或允许其他用户与其交互，以避免权限被滥用或数据泄露。
+请您充分知悉全部使用风险，使用本插件即视为您自愿承担相关所有责任。
+
+**免责声明：** 
+
+本软件的代码采用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/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/dist/README.md

@@ -0,0 +1,76 @@
+# 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/@larksuite/openclaw-lark.svg)](https://www.npmjs.com/package/@larksuite/openclaw-lark)
+[![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)
+
+This plugin integrates with OpenClaw AI automation capabilities and carries inherent risks such as model hallucinations, unpredictable execution, and prompt injection. After you authorize Lark/Feishu permissions, OpenClaw will act under your user identity within the authorized scope, which may lead to high-risk consequences such as leakage of sensitive data or unauthorized operations. Please use with caution.
+
+To reduce these risks, the plugin enables default security protections at multiple layers. However, these risks still exist. We strongly recommend that you do not proactively modify any default security settings; once relevant restrictions are relaxed, the risks will increase significantly, and you will bear the consequences.
+
+We recommend using the Lark/Feishu bot connected to OpenClaw as a private conversational assistant. Do not add it to group chats or allow other users to interact with it, to avoid abuse of permissions or data leakage.
+
+Please fully understand all usage risks. By using this plugin, you are deemed to voluntarily assume all related responsibilities.
+
+
+**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/dist/openclaw.plugin.json

@@ -0,0 +1,64 @@
+{
+  "id": "openclaw-lark",
+  "channels": [
+    "feishu"
+  ],
+  "skills": [
+    "./skills"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  },
+  "contracts": {
+    "tools": [
+      "feishu_bitable_app",
+      "feishu_bitable_app_table",
+      "feishu_bitable_app_table_field",
+      "feishu_bitable_app_table_record",
+      "feishu_bitable_app_table_view",
+      "feishu_calendar_calendar",
+      "feishu_calendar_event",
+      "feishu_calendar_event_attendee",
+      "feishu_calendar_freebusy",
+      "feishu_chat",
+      "feishu_chat_members",
+      "feishu_create_doc",
+      "feishu_doc_comments",
+      "feishu_doc_media",
+      "feishu_drive_file",
+      "feishu_fetch_doc",
+      "feishu_get_user",
+      "feishu_im_bot_image",
+      "feishu_im_user_fetch_resource",
+      "feishu_im_user_get_messages",
+      "feishu_im_user_get_thread_messages",
+      "feishu_im_user_message",
+      "feishu_im_user_search_messages",
+      "feishu_oauth",
+      "feishu_oauth_batch_auth",
+      "feishu_search_doc_wiki",
+      "feishu_search_user",
+      "feishu_sheet",
+      "feishu_task_comment",
+      "feishu_task_subtask",
+      "feishu_task_task",
+      "feishu_task_agent",
+      "feishu_task_attachment",
+      "feishu_task_tasklist",
+      "feishu_update_doc",
+      "feishu_wiki_space",
+      "feishu_wiki_space_node",
+      "feishu_task_section",
+      "feishu_ask_user_question"
+    ]
+  },
+  "channelConfigs": {
+    "feishu": {
+      "schema": {
+        "type": "object"
+      }
+    }
+  }
+}

package/dist/secret-contract-api.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Feishu channel secret-contract registration. Declares which fields are
+ * SecretRef-shaped so OpenClaw's runtime resolves them at startup.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.secretTargetRegistryEntries = void 0;
+exports.collectRuntimeConfigAssignments = collectRuntimeConfigAssignments;
+const channel_secret_basic_runtime_1 = require("openclaw/plugin-sdk/channel-secret-basic-runtime");
+const SECRET_FIELDS = ['appSecret', 'encryptKey', 'verificationToken'];
+/** Fields the Lark SDK only consumes when an account is in webhook mode. */
+const WEBHOOK_ONLY_FIELDS = ['encryptKey', 'verificationToken'];
+exports.secretTargetRegistryEntries = SECRET_FIELDS.flatMap((field) => {
+    const acctPath = `channels.feishu.accounts.*.${field}`;
+    const topPath = `channels.feishu.${field}`;
+    return [
+        {
+            id: acctPath,
+            targetType: acctPath,
+            configFile: 'openclaw.json',
+            pathPattern: acctPath,
+            secretShape: 'secret_input',
+            expectedResolvedValue: 'string',
+            includeInPlan: true,
+            includeInConfigure: true,
+            includeInAudit: true,
+        },
+        {
+            id: topPath,
+            targetType: topPath,
+            configFile: 'openclaw.json',
+            pathPattern: topPath,
+            secretShape: 'secret_input',
+            expectedResolvedValue: 'string',
+            includeInPlan: true,
+            includeInConfigure: true,
+            includeInAudit: true,
+        },
+    ];
+});
+function collectRuntimeConfigAssignments(params) {
+    const resolved = (0, channel_secret_basic_runtime_1.getChannelSurface)(params.config, 'feishu');
+    if (!resolved)
+        return;
+    const { channel, surface } = resolved;
+    (0, channel_secret_basic_runtime_1.collectSimpleChannelFieldAssignments)({
+        channelKey: 'feishu',
+        field: 'appSecret',
+        channel,
+        surface,
+        defaults: params.defaults,
+        context: params.context,
+        topInactiveReason: 'no enabled Feishu account inherits this top-level appSecret.',
+        accountInactiveReason: 'Feishu account is disabled.',
+    });
+    const baseConnectionMode = (0, channel_secret_basic_runtime_1.normalizeSecretStringValue)(channel.connectionMode) === 'webhook' ? 'webhook' : 'websocket';
+    const resolveAccountMode = (account) => (0, channel_secret_basic_runtime_1.hasOwnProperty)(account, 'connectionMode')
+        ? (0, channel_secret_basic_runtime_1.normalizeSecretStringValue)(account.connectionMode)
+        : baseConnectionMode;
+    for (const field of WEBHOOK_ONLY_FIELDS) {
+        (0, channel_secret_basic_runtime_1.collectConditionalChannelFieldAssignments)({
+            channelKey: 'feishu',
+            field,
+            channel,
+            surface,
+            defaults: params.defaults,
+            context: params.context,
+            topLevelActiveWithoutAccounts: baseConnectionMode === 'webhook',
+            topLevelInheritedAccountActive: ({ account, enabled }) => enabled && !(0, channel_secret_basic_runtime_1.hasOwnProperty)(account, field) && resolveAccountMode(account) === 'webhook',
+            accountActive: ({ account, enabled }) => enabled && resolveAccountMode(account) === 'webhook',
+            topInactiveReason: `no enabled Feishu webhook-mode surface inherits this top-level ${field}.`,
+            accountInactiveReason: 'Feishu account is disabled or not running in webhook mode.',
+        });
+    }
+}

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 获取