OpenClaw 完整备份 - 2026-03-21
This commit is contained in:
huan
@@ -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 获取
|
||||
@@ -0,0 +1,813 @@
|
||||
# 飞书多维表格使用场景完整示例
|
||||
|
||||
本文档提供多维表格操作的完整场景示例，包括参数说明和注意事项。
|
||||
|
||||
> **基础参考**: 先查阅 [字段 Property 配置详解](field-properties.md) 和 [记录值数据结构详解](record-values.md)
|
||||
|
||||
---
|
||||
|
||||
## 📋 目录
|
||||
|
||||
1. [场景 0: 创建数据表（两种模式对比）](#场景-0-创建数据表两种模式对比)
|
||||
2. [场景 1: 查字段类型（必做第一步）](#场景-1-查字段类型必做第一步)
|
||||
3. [场景 2: 批量导入客户数据](#场景-2-批量导入客户数据)
|
||||
4. [场景 2.5: 创建表并插入数据（含空行处理）](#场景-25-创建表并插入数据含空行处理)
|
||||
5. [场景 3: 筛选查询（高级筛选）](#场景-3-筛选查询高级筛选)
|
||||
6. [场景 4: 更新单条记录](#场景-4-更新单条记录)
|
||||
7. [场景 5: 创建带选项的单选字段](#场景-5-创建带选项的单选字段)
|
||||
8. [场景 6: 创建复杂字段（进度、货币、评分）](#场景-6-创建复杂字段进度货币评分)
|
||||
9. [场景 7: 处理附件字段](#场景-7-处理附件字段)
|
||||
10. [场景 8: 双向关联字段](#场景-8-双向关联字段)
|
||||
|
||||
---
|
||||
|
||||
## 场景 0: 创建数据表（两种模式对比）
|
||||
|
||||
### 模式 A：一次性定义所有字段
|
||||
|
||||
**适用场景**：字段类型、配置都已明确，需要快速创建表结构。
|
||||
|
||||
**优势**：一次 API 调用，原子性操作。
|
||||
|
||||
**工具**: `feishu_bitable_app_table`
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table": {
|
||||
"name": "客户管理表",
|
||||
"default_view_name": "所有客户",
|
||||
"fields": [
|
||||
{
|
||||
"field_name": "客户名称",
|
||||
"type": 1
|
||||
},
|
||||
{
|
||||
"field_name": "负责人",
|
||||
"type": 11,
|
||||
"property": {
|
||||
"multiple": false
|
||||
}
|
||||
},
|
||||
{
|
||||
"field_name": "签约日期",
|
||||
"type": 5,
|
||||
"property": {
|
||||
"date_formatter": "yyyy-MM-dd"
|
||||
}
|
||||
},
|
||||
{
|
||||
"field_name": "状态",
|
||||
"type": 3,
|
||||
"property": {
|
||||
"options": [
|
||||
{"name": "进行中", "color": 0},
|
||||
{"name": "已完成", "color": 10}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"field_name": "金额",
|
||||
"type": 2,
|
||||
"ui_type": "Currency",
|
||||
"property": {
|
||||
"currency_code": "CNY",
|
||||
"formatter": "0.00"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回示例**:
|
||||
```json
|
||||
{
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"name": "客户管理表",
|
||||
"default_view_id": "vewXXXXXXXX"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 模式 B：使用默认表 + 逐步修改字段
|
||||
|
||||
**适用场景**：探索式建表，需要边建边调整，或复杂字段配置需要分步确认。
|
||||
|
||||
**优势**：
|
||||
- `app.create` 自带默认表和默认字段，可在此基础上调整
|
||||
- 复杂字段（单选 options、URL 格式等）分步确认，减少出错
|
||||
- 踩坑后容易回退（比如 URL 字段改为文本字段）
|
||||
|
||||
**完整流程**：
|
||||
|
||||
#### 步骤 1: 创建 App（工具: `feishu_bitable_app`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"name": "客户管理系统",
|
||||
"folder_token": "fldXXXXXXXX"
|
||||
}
|
||||
```
|
||||
|
||||
**返回**: 包含 `app_token` 和默认表的 `default_table_id`
|
||||
|
||||
---
|
||||
|
||||
#### 步骤 2: 查看默认字段（工具: `feishu_bitable_app_table_field`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "list",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX"
|
||||
}
|
||||
```
|
||||
|
||||
**返回示例**:
|
||||
```json
|
||||
{
|
||||
"fields": [
|
||||
{
|
||||
"field_id": "fld001",
|
||||
"field_name": "文本",
|
||||
"type": 1,
|
||||
"ui_type": "Text"
|
||||
},
|
||||
{
|
||||
"field_id": "fld002",
|
||||
"field_name": "数字",
|
||||
"type": 2,
|
||||
"ui_type": "Number"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 步骤 3: 修改默认字段名称（工具: `feishu_bitable_app_table_field`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "update",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_id": "fld001",
|
||||
"field_name": "客户名称"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 步骤 4: 补充缺失字段（工具: `feishu_bitable_app_table_field`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "负责人",
|
||||
"type": 11,
|
||||
"property": {
|
||||
"multiple": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 步骤 5: 查看空记录（工具: `feishu_bitable_app_table_record`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "list",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX"
|
||||
}
|
||||
```
|
||||
|
||||
**返回**: 可能包含空记录 `[{"record_id": "recxxx", "fields": {}}, ...]`
|
||||
|
||||
---
|
||||
|
||||
#### 步骤 6: 删除空行（工具: `feishu_bitable_app_table_record`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "batch_delete",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"records": ["recxxx", "recyyy"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 步骤 7: 批量插入数据（工具: `feishu_bitable_app_table_record`）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "batch_create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"records": [
|
||||
{
|
||||
"fields": {
|
||||
"客户名称": "Bytedance",
|
||||
"负责人": [{"id": "ou_xxx"}],
|
||||
"状态": "进行中"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**⚠️ 模式 B 的关键注意事项**:
|
||||
- 默认表中通常已有空记录，**必须先删除**，否则会有数据污染
|
||||
- 步骤 5-6 是必需的，不能跳过
|
||||
- 适合不确定字段配置的探索式场景
|
||||
|
||||
---
|
||||
|
||||
## 场景 1: 查字段类型（必做第一步）
|
||||
|
||||
**为什么必做**: 不同字段类型的值格式完全不同，必须先查询再写入。
|
||||
|
||||
**工具**: `feishu_bitable_app_table_field`
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "list",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX"
|
||||
}
|
||||
```
|
||||
|
||||
**返回示例**:
|
||||
```json
|
||||
{
|
||||
"fields": [
|
||||
{
|
||||
"field_id": "fld001",
|
||||
"field_name": "任务名称",
|
||||
"type": 1,
|
||||
"ui_type": "Text",
|
||||
"property": {}
|
||||
},
|
||||
{
|
||||
"field_id": "fld002",
|
||||
"field_name": "负责人",
|
||||
"type": 11,
|
||||
"ui_type": "User",
|
||||
"property": {
|
||||
"multiple": true
|
||||
}
|
||||
},
|
||||
{
|
||||
"field_id": "fld003",
|
||||
"field_name": "截止日期",
|
||||
"type": 5,
|
||||
"ui_type": "DateTime",
|
||||
"property": {
|
||||
"date_formatter": "yyyy-MM-dd HH:mm"
|
||||
}
|
||||
},
|
||||
{
|
||||
"field_id": "fld004",
|
||||
"field_name": "状态",
|
||||
"type": 3,
|
||||
"ui_type": "SingleSelect",
|
||||
"property": {
|
||||
"options": [
|
||||
{"id": "optXXX", "name": "进行中", "color": 0},
|
||||
{"id": "optYYY", "name": "已完成", "color": 10}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**关键信息**:
|
||||
- `type`: 字段基础类型（1=文本, 2=数字, 3=单选...）
|
||||
- `ui_type`: UI 展示类型（区分进度、货币、评分等）
|
||||
- `property`: 字段配置（单选的 options、日期的 formatter 等）
|
||||
|
||||
---
|
||||
|
||||
## 场景 2: 批量导入客户数据
|
||||
|
||||
**工具**: `feishu_bitable_app_table_record`
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "batch_create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"records": [
|
||||
{
|
||||
"fields": {
|
||||
"客户名称": "某某",
|
||||
"负责人": [{"id": "ou_xxx"}],
|
||||
"签约日期": 1674206443000,
|
||||
"状态": "进行中",
|
||||
"金额": 1000000,
|
||||
"标签": ["重要客户", "战略合作"],
|
||||
"联系电话": "17899870000",
|
||||
"官网": {
|
||||
"text": "某某官网",
|
||||
"link": "https://www.xxxx.com"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"fields": {
|
||||
"客户名称": "飞书",
|
||||
"负责人": [{"id": "ou_xxx"}],
|
||||
"签约日期": 1675416243000,
|
||||
"状态": "已完成",
|
||||
"金额": 500000,
|
||||
"标签": ["核心产品"],
|
||||
"联系电话": "13800138000"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**字段值格式说明**:
|
||||
- **文本**: 字符串 `"客户名称"`
|
||||
- **人员**: 对象数组 `[{"id": "ou_xxx"}]`（只能传 id）
|
||||
- **日期**: 毫秒时间戳 `1674206443000`
|
||||
- **单选**: 字符串 `"进行中"`
|
||||
- **多选**: 字符串数组 `["重要客户", "战略合作"]`
|
||||
- **数字**: 数字 `1000000`
|
||||
- **电话**: 字符串 `"17899870000"`
|
||||
- **超链接**: 对象 `{"text": "显示文本", "link": "URL"}`
|
||||
|
||||
**返回示例**:
|
||||
```json
|
||||
{
|
||||
"records": [
|
||||
{
|
||||
"record_id": "rec001",
|
||||
"fields": {...}
|
||||
},
|
||||
{
|
||||
"record_id": "rec002",
|
||||
"fields": {...}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**限制**:
|
||||
- 单次最多 500 条记录
|
||||
- 超过需分批调用
|
||||
|
||||
---
|
||||
|
||||
## 场景 2.5: 创建表并插入数据（含空行处理）
|
||||
|
||||
**问题**: `app.create` 创建的默认表中会自带空记录（空行），直接插入数据会导致数据污染。
|
||||
|
||||
**正确流程**: 见场景 0 的模式 B
|
||||
|
||||
**核心步骤**:
|
||||
1. 创建 App → 获取 `app_token` 和 `default_table_id`
|
||||
2. 查看默认表记录 (`list` action)
|
||||
3. 删除空行 (`batch_delete` action)
|
||||
4. 批量插入数据 (`batch_create` action)
|
||||
|
||||
**错误示例**（跳过步骤 2-3）:
|
||||
```
|
||||
表格最终状态：
|
||||
| 客户名称 | 负责人 | 状态 |
|
||||
|---------|--------|------|
|
||||
| | | | ← 空行（原有）
|
||||
| Bytedance | 张三 | 进行中 | ← 新插入
|
||||
| 飞书 | 李四 | 已完成 | ← 新插入
|
||||
```
|
||||
|
||||
**正确示例**（执行步骤 2-3）:
|
||||
```
|
||||
表格最终状态：
|
||||
| 客户名称 | 负责人 | 状态 |
|
||||
|---------|--------|------|
|
||||
| Bytedance | 张三 | 进行中 |
|
||||
| 飞书 | 李四 | 已完成 |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 场景 3: 筛选查询（高级筛选）
|
||||
|
||||
**工具**: `feishu_bitable_app_table_record`
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "list",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"filter": {
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{
|
||||
"field_name": "状态",
|
||||
"operator": "is",
|
||||
"value": ["进行中"]
|
||||
},
|
||||
{
|
||||
"field_name": "截止日期",
|
||||
"operator": "isLess",
|
||||
"value": ["ExactDate", "1740441600000"]
|
||||
},
|
||||
{
|
||||
"field_name": "优先级",
|
||||
"operator": "isGreater",
|
||||
"value": ["3"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"sort": [
|
||||
{
|
||||
"field_name": "截止日期",
|
||||
"desc": false
|
||||
},
|
||||
{
|
||||
"field_name": "优先级",
|
||||
"desc": true
|
||||
}
|
||||
],
|
||||
"field_names": ["任务名称", "负责人", "截止日期", "状态"],
|
||||
"page_size": 100
|
||||
}
|
||||
```
|
||||
|
||||
**参数说明**:
|
||||
|
||||
### filter 结构
|
||||
- `conjunction`: 条件组合方式（`"and"` 或 `"or"`）
|
||||
- `conditions`: 条件数组
|
||||
|
||||
### operator 类型（10 种）
|
||||
|
||||
| operator | 含义 | 支持字段 | value 格式 |
|
||||
|----------|------|----------|-----------|
|
||||
| `is` | 等于 | 所有 | `["值"]` |
|
||||
| `isNot` | 不等于 | 除日期外 | `["值"]` |
|
||||
| `contains` | 包含 | 除日期外 | `["值1", "值2"]` |
|
||||
| `doesNotContain` | 不包含 | 除日期外 | `["值1"]` |
|
||||
| `isEmpty` | 为空 | 所有 | `[]` |
|
||||
| `isNotEmpty` | 不为空 | 所有 | `[]` |
|
||||
| `isGreater` | 大于 | 数字、日期 | `["值"]` |
|
||||
| `isGreaterEqual` | 大于等于 | 数字 | `["值"]` |
|
||||
| `isLess` | 小于 | 数字、日期 | `["值"]` |
|
||||
| `isLessEqual` | 小于等于 | 数字 | `["值"]` |
|
||||
|
||||
### 日期字段特殊值
|
||||
|
||||
```json
|
||||
// 具体日期
|
||||
{"operator": "is", "value": ["ExactDate", "1702449755000"]}
|
||||
|
||||
// 相对日期
|
||||
{"operator": "is", "value": ["Today"]} // 今天
|
||||
{"operator": "is", "value": ["Tomorrow"]} // 明天
|
||||
{"operator": "is", "value": ["Yesterday"]} // 昨天
|
||||
{"operator": "is", "value": ["CurrentWeek"]} // 本周
|
||||
{"operator": "is", "value": ["LastWeek"]} // 上周
|
||||
{"operator": "is", "value": ["TheLastWeek"]} // 过去七天
|
||||
{"operator": "is", "value": ["TheNextWeek"]} // 未来七天
|
||||
```
|
||||
|
||||
### sort 结构
|
||||
- `field_name`: 排序字段
|
||||
- `desc`: `true` 降序，`false` 升序
|
||||
- 支持多字段排序（按数组顺序）
|
||||
|
||||
---
|
||||
|
||||
## 场景 4: 更新单条记录
|
||||
|
||||
**工具**: `feishu_bitable_app_table_record`
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "update",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"record_id": "recusyQbB0fVL5",
|
||||
"fields": {
|
||||
"状态": "已完成",
|
||||
"完成时间": 1674206443000,
|
||||
"备注": "客户已签约"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**说明**:
|
||||
- 只传需要更新的字段
|
||||
- 不传的字段保持不变
|
||||
- 支持部分字段更新
|
||||
|
||||
**批量更新**（最多 500 条）:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "batch_update",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"records": [
|
||||
{
|
||||
"record_id": "rec001",
|
||||
"fields": {
|
||||
"状态": "已完成"
|
||||
}
|
||||
},
|
||||
{
|
||||
"record_id": "rec002",
|
||||
"fields": {
|
||||
"状态": "已完成"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 场景 5: 创建带选项的单选字段
|
||||
|
||||
**工具**: `feishu_bitable_app_table_field`
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "优先级",
|
||||
"type": 3,
|
||||
"property": {
|
||||
"options": [
|
||||
{"name": "高", "color": 0},
|
||||
{"name": "中", "color": 1},
|
||||
{"name": "低", "color": 2}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**颜色编号**（color 范围 0-54）:
|
||||
- 0: 红色
|
||||
- 1: 橙色
|
||||
- 10: 绿色
|
||||
- 20: 蓝色
|
||||
|
||||
**多选字段**（type=4）格式相同:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "标签",
|
||||
"type": 4,
|
||||
"property": {
|
||||
"options": [
|
||||
{"name": "重要", "color": 0},
|
||||
{"name": "紧急", "color": 1},
|
||||
{"name": "长期", "color": 10}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 创建时**不能**指定选项 ID（`id` 字段），系统自动生成
|
||||
- 选项总数不超过 20,000
|
||||
|
||||
---
|
||||
|
||||
## 场景 6: 创建复杂字段（进度、货币、评分）
|
||||
|
||||
### 进度字段 (type=2, ui_type="Progress")
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "完成进度",
|
||||
"type": 2,
|
||||
"ui_type": "Progress",
|
||||
"property": {
|
||||
"min": 0,
|
||||
"max": 100,
|
||||
"range_customize": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**写入值**: `0.75` 表示 75%
|
||||
|
||||
---
|
||||
|
||||
### 货币字段 (type=2, ui_type="Currency")
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "预算",
|
||||
"type": 2,
|
||||
"ui_type": "Currency",
|
||||
"property": {
|
||||
"currency_code": "CNY",
|
||||
"formatter": "0,000.00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**currency_code 可选值**:
|
||||
- `"CNY"`: 人民币 (¥)
|
||||
- `"USD"`: 美元 ($)
|
||||
- `"EUR"`: 欧元 (€)
|
||||
- `"JPY"`: 日元 (¥)
|
||||
|
||||
**写入值**: `5000.50`（普通数字）
|
||||
|
||||
---
|
||||
|
||||
### 评分字段 (type=2, ui_type="Rating")
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "客户满意度",
|
||||
"type": 2,
|
||||
"ui_type": "Rating",
|
||||
"property": {
|
||||
"min": 1,
|
||||
"max": 5,
|
||||
"rating": {
|
||||
"symbol": "star"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**symbol 可选值**:
|
||||
- `"star"`: ⭐ 星星
|
||||
- `"heart"`: ❤️ 爱心
|
||||
- `"fire"`: 🔥 火焰
|
||||
- `"thumbsup"`: 👍 赞
|
||||
|
||||
**写入值**: `4`（整数）
|
||||
|
||||
---
|
||||
|
||||
## 场景 7: 处理附件字段
|
||||
|
||||
### 步骤 1: 上传附件到多维表格
|
||||
|
||||
**工具**: `feishu_drive_media`（上传素材接口）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "upload",
|
||||
"file_path": "/path/to/file.pdf",
|
||||
"parent_type": "bitable_image",
|
||||
"parent_node": "S404b..." // app_token
|
||||
}
|
||||
```
|
||||
|
||||
**返回**:
|
||||
```json
|
||||
{
|
||||
"file_token": "DRiFbwaKsoZaLax4WKZbEGCccoe"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 步骤 2: 创建附件字段（可选）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"field_name": "合同文件",
|
||||
"type": 17
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 步骤 3: 写入附件记录
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tblXXXXXXXX",
|
||||
"fields": {
|
||||
"客户名称": "Bytedance",
|
||||
"合同文件": [
|
||||
{"file_token": "DRiFxxxxxxxxxxxxxxxxxxCccoe"},
|
||||
{"file_token": "BZk3bxxxxxxxxxxxxxxxxeKqcLe"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**限制**:
|
||||
- 单个单元格附件数不超过 100
|
||||
- 必须先上传到当前多维表格，不能用外部 file_token
|
||||
|
||||
---
|
||||
|
||||
## 场景 8: 双向关联字段
|
||||
|
||||
### 步骤 1: 创建双向关联字段
|
||||
|
||||
**在"任务表"中创建关联到"项目表"的字段**:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tbl_task",
|
||||
"field_name": "所属项目",
|
||||
"type": 21,
|
||||
"property": {
|
||||
"table_id": "tbl_project",
|
||||
"back_field_name": "关联的任务",
|
||||
"multiple": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**结果**:
|
||||
- 在"任务表"中创建字段"所属项目"
|
||||
- 在"项目表"中**自动创建**字段"关联的任务"
|
||||
|
||||
---
|
||||
|
||||
### 步骤 2: 写入关联记录
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tbl_task",
|
||||
"fields": {
|
||||
"任务名称": "开发新功能",
|
||||
"所属项目": {
|
||||
"link_record_ids": ["rec_project_001"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**级联更新**:
|
||||
- 在"任务表"中设置"所属项目"为 `rec_project_001`
|
||||
- "项目表"的 `rec_project_001` 记录的"关联的任务"字段会**自动添加**当前任务的 record_id
|
||||
|
||||
---
|
||||
|
||||
### 单向关联 (type=18)
|
||||
|
||||
**区别**: 只影响当前表，不会自动更新对方表
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"app_token": "S404b...",
|
||||
"table_id": "tbl_task",
|
||||
"field_name": "参考任务",
|
||||
"type": 18,
|
||||
"property": {
|
||||
"table_id": "tbl_task", // 可以关联自己
|
||||
"multiple": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 参考链接
|
||||
|
||||
- [字段 Property 配置详解](field-properties.md)
|
||||
- [记录值数据结构详解](record-values.md)
|
||||
- [飞书开放平台 - 多维表格文档](https://open.feishu.cn/document/server-docs/docs/bitable-v1/bitable-overview)
|
||||
+763
@@ -0,0 +1,763 @@
|
||||
# 飞书多维表格字段 Property 配置详解
|
||||
|
||||
本文档详细说明每种字段类型创建或更新时需要的 `property` 参数结构。
|
||||
|
||||
> **来源**: 基于飞书开放平台文档 [字段编辑指南](https://go.feishu.cn/s/672BSzVyo03)
|
||||
|
||||
## 📋 目录
|
||||
|
||||
- [基础字段](#基础字段)
|
||||
- [1. 文本 (type=1)](#1-文本-type1)
|
||||
- [2. 数字 (type=2)](#2-数字-type2)
|
||||
- [5. 日期 (type=5)](#5-日期-type5)
|
||||
- [7. 复选框 (type=7)](#7-复选框-type7)
|
||||
- [13. 电话号码 (type=13)](#13-电话号码-type13)
|
||||
- [选择字段](#选择字段)
|
||||
- [3. 单选 (type=3)](#3-单选-type3)
|
||||
- [4. 多选 (type=4)](#4-多选-type4)
|
||||
- [特殊显示字段](#特殊显示字段)
|
||||
- [进度 (type=2, ui_type="Progress")](#进度-type2-ui_typeprogress)
|
||||
- [货币 (type=2, ui_type="Currency")](#货币-type2-ui_typecurrency)
|
||||
- [评分 (type=2, ui_type="Rating")](#评分-type2-ui_typerating)
|
||||
- [条码 (type=1, ui_type="Barcode")](#条码-type1-ui_typebarcode)
|
||||
- [邮箱 (type=1, ui_type="Email")](#邮箱-type1-ui_typeemail)
|
||||
- [关系字段](#关系字段)
|
||||
- [11. 人员 (type=11)](#11-人员-type11)
|
||||
- [15. 超链接 (type=15)](#15-超链接-type15)
|
||||
- [17. 附件 (type=17)](#17-附件-type17)
|
||||
- [18. 单向关联 (type=18)](#18-单向关联-type18)
|
||||
- [21. 双向关联 (type=21)](#21-双向关联-type21)
|
||||
- [22. 地理位置 (type=22)](#22-地理位置-type22)
|
||||
- [23. 群组 (type=23)](#23-群组-type23)
|
||||
- [高级字段](#高级字段)
|
||||
- [20. 公式 (type=20)](#20-公式-type20)
|
||||
- [1001. 创建时间 (type=1001)](#1001-创建时间-type1001)
|
||||
- [1002. 最后更新时间 (type=1002)](#1002-最后更新时间-type1002)
|
||||
- [1005. 自动编号 (type=1005)](#1005-自动编号-type1005)
|
||||
|
||||
---
|
||||
|
||||
## 基础字段
|
||||
|
||||
### 1. 文本 (type=1)
|
||||
|
||||
**Property 结构**: 空对象或省略
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 1,
|
||||
"field_name": "任务描述",
|
||||
"property": {}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 默认 `ui_type` 为 "Text"
|
||||
- 单个单元格最多 10 万字符
|
||||
- 支持富文本格式（提及人、超链接等）
|
||||
|
||||
---
|
||||
|
||||
### 2. 数字 (type=2)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"formatter": "0" // 可选，数字显示格式
|
||||
}
|
||||
```
|
||||
|
||||
**formatter 可选值**:
|
||||
- `"0"`: 整数（默认）
|
||||
- `"0.0"`: 一位小数
|
||||
- `"0.00"`: 两位小数
|
||||
- `"0,000"`: 千分位
|
||||
- `"0.00%"`: 百分比
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 2,
|
||||
"field_name": "工时",
|
||||
"property": {
|
||||
"formatter": "0.00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 日期 (type=5)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"date_formatter": "yyyy/MM/dd", // 可选，默认 "yyyy/MM/dd"
|
||||
"auto_fill": false // 可选，是否自动填充创建时间
|
||||
}
|
||||
```
|
||||
|
||||
**date_formatter 可选值**:
|
||||
- `"yyyy/MM/dd"`: 2021/1/30
|
||||
- `"yyyy-MM-dd HH:mm"`: 2021/1/30 14:00
|
||||
- `"MM-dd"`: 1月30日
|
||||
- `"MM/dd/yyyy"`: 01/30/2021
|
||||
- `"dd/MM/yyyy"`: 30/01/2021
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 5,
|
||||
"field_name": "截止日期",
|
||||
"property": {
|
||||
"date_formatter": "yyyy-MM-dd HH:mm",
|
||||
"auto_fill": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. 复选框 (type=7)
|
||||
|
||||
**Property 结构**: 空对象或省略
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 7,
|
||||
"field_name": "是否完成",
|
||||
"property": {}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 13. 电话号码 (type=13)
|
||||
|
||||
**Property 结构**: 空对象或省略
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 13,
|
||||
"field_name": "联系电话",
|
||||
"property": {}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 电话号码格式：符合正则 `(\+)?\d*`
|
||||
- 最大长度 64 字符
|
||||
|
||||
---
|
||||
|
||||
## 选择字段
|
||||
|
||||
### 3. 单选 (type=3)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"options": [
|
||||
{
|
||||
"name": "进行中", // 必填，选项名称
|
||||
"color": 0 // 可选，颜色编号 (0-54)
|
||||
},
|
||||
{
|
||||
"name": "已完成",
|
||||
"color": 10
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**颜色编号 (color)**:
|
||||
- 范围: 0-54
|
||||
- 0: 红色
|
||||
- 10: 绿色
|
||||
- 20: 蓝色
|
||||
- ... (详见飞书官方文档)
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 3,
|
||||
"field_name": "任务状态",
|
||||
"property": {
|
||||
"options": [
|
||||
{"name": "待开始", "color": 0},
|
||||
{"name": "进行中", "color": 20},
|
||||
{"name": "已完成", "color": 10}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 选项总数不超过 20,000 个
|
||||
- 创建时**不能**指定选项 ID（`id` 字段），系统自动生成
|
||||
- 更新时需保留已有选项的 `id`
|
||||
|
||||
---
|
||||
|
||||
### 4. 多选 (type=4)
|
||||
|
||||
**Property 结构**: 与单选相同
|
||||
|
||||
```json
|
||||
{
|
||||
"options": [
|
||||
{"name": "紧急", "color": 0},
|
||||
{"name": "重要", "color": 10}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 选项总数不超过 20,000 个
|
||||
- 单个单元格选项数不超过 1,000 个
|
||||
|
||||
---
|
||||
|
||||
## 特殊显示字段
|
||||
|
||||
### 进度 (type=2, ui_type="Progress")
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"min": 0, // 必填，最小值
|
||||
"max": 100, // 必填，最大值
|
||||
"range_customize": false // 可选，是否允许自定义进度值
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 2,
|
||||
"field_name": "完成进度",
|
||||
"ui_type": "Progress",
|
||||
"property": {
|
||||
"min": 0,
|
||||
"max": 100,
|
||||
"range_customize": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- `min` 取值范围: 0-1
|
||||
- `max` 取值范围: 1-100
|
||||
- `range_customize` 为 `true` 时用户可输入超出范围的值
|
||||
|
||||
---
|
||||
|
||||
### 货币 (type=2, ui_type="Currency")
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"currency_code": "CNY", // 必填，货币类型
|
||||
"formatter": "0.00" // 可选，数字格式
|
||||
}
|
||||
```
|
||||
|
||||
**currency_code 可选值**:
|
||||
- `"CNY"`: 人民币 (¥)
|
||||
- `"USD"`: 美元 ($)
|
||||
- `"EUR"`: 欧元 (€)
|
||||
- `"GBP"`: 英镑 (£)
|
||||
- `"JPY"`: 日元 (¥)
|
||||
- `"HKD"`: 港元 ($)
|
||||
- ... (支持 20+ 种货币)
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 2,
|
||||
"field_name": "预算",
|
||||
"ui_type": "Currency",
|
||||
"property": {
|
||||
"currency_code": "USD",
|
||||
"formatter": "0,000.00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 评分 (type=2, ui_type="Rating")
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"min": 1, // 必填，最小值
|
||||
"max": 5, // 必填，最大值
|
||||
"rating": { // 可选，评分样式
|
||||
"symbol": "star" // 图标类型
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**symbol 可选值**:
|
||||
- `"star"`: ⭐ 星星（默认）
|
||||
- `"heart"`: ❤️ 爱心
|
||||
- `"thumbsup"`: 👍 赞
|
||||
- `"fire"`: 🔥 火焰
|
||||
- `"smile"`: 😊 笑脸
|
||||
- `"lightning"`: ⚡ 闪电
|
||||
- `"flower"`: 🌸 花朵
|
||||
- `"number"`: 数字
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 2,
|
||||
"field_name": "优先级",
|
||||
"ui_type": "Rating",
|
||||
"property": {
|
||||
"min": 1,
|
||||
"max": 5,
|
||||
"rating": {
|
||||
"symbol": "fire"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 条码 (type=1, ui_type="Barcode")
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"allowed_edit_modes": {
|
||||
"manual": true, // 是否允许手动录入
|
||||
"scan": true // 是否允许扫描录入
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 1,
|
||||
"field_name": "商品条码",
|
||||
"ui_type": "Barcode",
|
||||
"property": {
|
||||
"allowed_edit_modes": {
|
||||
"manual": false,
|
||||
"scan": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 邮箱 (type=1, ui_type="Email")
|
||||
|
||||
**Property 结构**: 空对象或省略
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 1,
|
||||
"field_name": "联系邮箱",
|
||||
"ui_type": "Email",
|
||||
"property": {}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关系字段
|
||||
|
||||
### 11. 人员 (type=11)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"multiple": true // 可选，是否允许多个人员，默认 true
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 11,
|
||||
"field_name": "负责人",
|
||||
"property": {
|
||||
"multiple": false // 只允许单个人员
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 单个单元格人员数不超过 1,000
|
||||
- 记录值只支持传入 `id` 字段（open_id/union_id/user_id）
|
||||
|
||||
---
|
||||
|
||||
### 15. 超链接 (type=15)
|
||||
|
||||
**Property 结构**: **必须省略 `property` 参数，不要传递任何值（包括空对象）**
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 15,
|
||||
"field_name": "参考链接"
|
||||
// 不要传 property 参数，包括空对象 {}
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 重要**: 超链接字段的特殊要求（经实测验证）：
|
||||
- ✅ **正确**: 完全省略 `property` 参数
|
||||
- ❌ **错误**: `"property": {}`（会报 URLFieldPropertyError）
|
||||
- ❌ **错误**: 传递任何 property 值
|
||||
|
||||
**注意**: 这是飞书 API 的特殊行为，超链接字段即使传空对象也会报错，必须完全省略该参数。
|
||||
|
||||
---
|
||||
|
||||
### 17. 附件 (type=17)
|
||||
|
||||
**Property 结构**: 空对象或省略
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 17,
|
||||
"field_name": "附件",
|
||||
"property": {}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 单个单元格附件数不超过 100
|
||||
- 写入前需先调用[上传素材接口](https://go.feishu.cn/s/63soQp6O80s)
|
||||
|
||||
---
|
||||
|
||||
### 18. 单向关联 (type=18)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"table_id": "tblXXXXXXXX", // 必填，关联的数据表 ID
|
||||
"multiple": true // 可选，是否允许多条记录，默认 true
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 18,
|
||||
"field_name": "关联任务",
|
||||
"property": {
|
||||
"table_id": "tblsRc9GRRXKqhvW",
|
||||
"multiple": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 单个单元格关联数不超过 500
|
||||
|
||||
---
|
||||
|
||||
### 21. 双向关联 (type=21)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"table_id": "tblXXXXXXXX", // 必填，关联的数据表 ID
|
||||
"back_field_name": "反向字段名", // 必填，对方表的双向关联字段名
|
||||
"multiple": true // 可选，是否允许多条记录
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 21,
|
||||
"field_name": "相关项目",
|
||||
"property": {
|
||||
"table_id": "tblAnotherTable",
|
||||
"back_field_name": "关联的任务",
|
||||
"multiple": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 单个单元格关联数不超过 500
|
||||
- 对方表会自动创建对应的双向关联字段
|
||||
|
||||
---
|
||||
|
||||
### 22. 地理位置 (type=22)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"location": {
|
||||
"input_type": "not_limit" // 输入限制
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**input_type 可选值**:
|
||||
- `"only_mobile"`: 仅允许移动端实时定位
|
||||
- `"not_limit"`: 无限制（默认）
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 22,
|
||||
"field_name": "办公地址",
|
||||
"property": {
|
||||
"location": {
|
||||
"input_type": "only_mobile"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 23. 群组 (type=23)
|
||||
|
||||
**Property 结构**: 空对象或省略
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 23,
|
||||
"field_name": "协作群",
|
||||
"property": {}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 单个单元格群组数不超过 10 个
|
||||
|
||||
---
|
||||
|
||||
## 高级字段
|
||||
|
||||
### 20. 公式 (type=20)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"formula_expression": "bitable::$table[tblXXX].$field[fldYYY]*2" // 可选
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 20,
|
||||
"field_name": "总价",
|
||||
"property": {
|
||||
"formula_expression": "bitable::$table[tblMain].$field[fldQty] * $field[fldPrice]"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 创建字段时**不支持**设置公式表达式
|
||||
- 参考[飞书帮助中心 - 公式字段](https://www.feishu.cn/hc/zh-CN/articles/360049067853)
|
||||
|
||||
**对于某些多维表格，公式字段需要额外设置 `type` 参数**（通过[获取多维表格元数据](https://go.feishu.cn/s/62nuKkQlE03)接口的 `formula_type` 判断）:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 20,
|
||||
"field_name": "计算字段",
|
||||
"property": {
|
||||
"type": {
|
||||
"data_type": 2, // 公式结果的数据类型 (1=文本, 2=数字, 5=日期...)
|
||||
"ui_property": { // UI 展示属性
|
||||
"formatter": "0.00",
|
||||
"currency_code": "CNY"
|
||||
},
|
||||
"ui_type": "Currency" // UI 类型 (Number/Progress/Currency/Rating/DateTime)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1001. 创建时间 (type=1001)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"date_formatter": "yyyy/MM/dd" // 可选，日期格式
|
||||
}
|
||||
```
|
||||
|
||||
**示例**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 1001,
|
||||
"field_name": "创建于",
|
||||
"property": {
|
||||
"date_formatter": "yyyy-MM-dd HH:mm"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1002. 最后更新时间 (type=1002)
|
||||
|
||||
**Property 结构**: 与创建时间相同
|
||||
|
||||
```json
|
||||
{
|
||||
"date_formatter": "yyyy-MM-dd HH:mm"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1005. 自动编号 (type=1005)
|
||||
|
||||
**Property 结构**:
|
||||
|
||||
```json
|
||||
{
|
||||
"auto_serial": {
|
||||
"type": "auto_increment_number", // 或 "custom"
|
||||
"options": [ // 自定义编号规则（仅 type="custom" 时需要）
|
||||
{
|
||||
"type": "fixed_text",
|
||||
"value": "TASK-"
|
||||
},
|
||||
{
|
||||
"type": "created_time",
|
||||
"value": "yyyyMMdd"
|
||||
},
|
||||
{
|
||||
"type": "system_number",
|
||||
"value": "5"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**auto_serial.type 可选值**:
|
||||
- `"auto_increment_number"`: 纯自增数字
|
||||
- `"custom"`: 自定义编号规则
|
||||
|
||||
**options 中的规则类型**:
|
||||
- `"system_number"`: 自增数字位数（value: 1-9）
|
||||
- `"fixed_text"`: 固定字符（value: 最多 20 字符）
|
||||
- `"created_time"`: 创建时间（value: "yyyyMMdd"/"yyyyMM"/"yyyy"/"MMdd"/"MM"/"dd"）
|
||||
|
||||
**示例 1: 纯自增**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 1005,
|
||||
"field_name": "编号",
|
||||
"property": {
|
||||
"auto_serial": {
|
||||
"type": "auto_increment_number"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**示例 2: 自定义编号**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": 1005,
|
||||
"field_name": "工单号",
|
||||
"property": {
|
||||
"auto_serial": {
|
||||
"type": "custom",
|
||||
"options": [
|
||||
{"type": "fixed_text", "value": "WO-"},
|
||||
{"type": "created_time", "value": "yyyyMMdd"},
|
||||
{"type": "system_number", "value": "4"}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
// 生成示例: WO-20240226-0001
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 常见错误码
|
||||
|
||||
| 错误码 | 字段类型 | 说明 |
|
||||
|--------|---------|------|
|
||||
| 1254080 | 文本 | property 结构错误 |
|
||||
| 1254081 | 数字 | property 结构错误，检查 formatter |
|
||||
| 1254082 | 单选 | property 结构错误，检查 options 数组 |
|
||||
| 1254083 | 多选 | property 结构错误，检查 options 数组 |
|
||||
| 1254084 | 日期 | property 结构错误，检查 date_formatter |
|
||||
| 1254085 | 复选框 | property 结构错误 |
|
||||
| 1254086 | 人员 | property 结构错误，检查 multiple |
|
||||
| 1254087 | 超链接 | **必须省略 property 参数（传空对象也会报错）** |
|
||||
| 1254088 | 附件 | property 结构错误 |
|
||||
| 1254089 | 单向关联 | property 结构错误，检查 table_id |
|
||||
| 1254090 | 查找引用 | property 结构错误 |
|
||||
| 1254091 | 公式 | property 结构错误 |
|
||||
| 1254092 | 双向关联 | property 结构错误，检查 table_id 和 back_field_name |
|
||||
| 1254093 | 创建时间 | property 结构错误 |
|
||||
| 1254094 | 最后更新时间 | property 结构错误 |
|
||||
|
||||
---
|
||||
|
||||
## 📌 更新字段时的特殊规则
|
||||
|
||||
调用 `update` action 更新字段时：
|
||||
|
||||
1. **必须保持字段类型一致**: `type` 和 `ui_type` 不能变更
|
||||
2. **单选/多选更新选项**:
|
||||
- 已有选项必须保留 `id`
|
||||
- 新增选项只传 `name` 和 `color`，不传 `id`
|
||||
3. **如果只改字段名**:
|
||||
- 可以只传 `field_name`，工具会自动查询当前 `type` 和 `property`
|
||||
4. **关联字段的 table_id**: 不能修改为不同的表
|
||||
|
||||
---
|
||||
|
||||
## 🔗 参考链接
|
||||
|
||||
- [飞书开放平台 - 字段编辑指南](https://go.feishu.cn/s/672BSzVyo03)
|
||||
- [新增字段接口文档](https://go.feishu.cn/s/62nuKkQl403)
|
||||
- [更新字段接口文档](https://go.feishu.cn/s/62nuKkQlo03)
|
||||
@@ -0,0 +1,911 @@
|
||||
# 飞书多维表格记录值数据结构详解
|
||||
|
||||
本文档详细说明每种字段类型在记录中对应的 `fields` 值格式。
|
||||
|
||||
> **来源**: 基于飞书开放平台文档 [多维表格记录数据结构](https://go.feishu.cn/s/6lY28723w04)
|
||||
|
||||
## 📋 快速索引
|
||||
|
||||
| 字段类型 | type | 值类型 | 示例 | 限制 |
|
||||
|---------|------|--------|------|------|
|
||||
| [文本](#文本-type1) | 1 | string (写入) / list of object (返回) | `"任务描述"` | 最多 10 万字符 |
|
||||
| [数字](#数字-type2) | 2 | number | `0.5` | - |
|
||||
| [单选](#单选-type3) | 3 | string | `"进行中"` | 选项总数≤20,000 |
|
||||
| [多选](#多选-type4) | 4 | array<string> | `["审批", "办公"]` | 选项总数≤20,000，单元格≤1,000 |
|
||||
| [日期](#日期-type5) | 5 | number | `1675526400000` | Unix 毫秒时间戳 |
|
||||
| [复选框](#复选框-type7) | 7 | boolean | `true` | - |
|
||||
| [人员](#人员-type11) | 11 | list of object | `[{"id": "ou_xxx"}]` | 单元格≤1,000，写入仅支持 `id` |
|
||||
| [电话](#电话号码-type13) | 13 | string | `"17899870000"` | 最多 64 字符 |
|
||||
| [超链接](#超链接-type15) | 15 | object | `{"text": "飞书", "link": "..."}` | - |
|
||||
| [附件](#附件-type17) | 17 | list of object | `[{"file_token": "xxx"}]` | 单元格≤100 |
|
||||
| [单向关联](#单向关联-type18) | 18 | object | `{"link_record_ids": [...]}` | 单元格≤500 |
|
||||
| [双向关联](#双向关联-type21) | 21 | object | `{"link_record_ids": [...]}` | 单元格≤500 |
|
||||
| [地理位置](#地理位置-type22) | 22 | object | `{"location": "116.3,40.0", ...}` | - |
|
||||
| [群组](#群组-type23) | 23 | list of object | `[{"id": "oc_xxx"}]` | 单元格≤10 |
|
||||
| [公式/查找引用](#公式查找引用-type20-type19) | 20/19 | object | `{"type": 1, "value": [...]}` | 只读 |
|
||||
|
||||
---
|
||||
|
||||
## 文本 (type=1)
|
||||
|
||||
### 基础文本 (ui_type="Text")
|
||||
|
||||
**写入格式**: 字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"任务描述": "维护客户关系"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 对象数组
|
||||
|
||||
```json
|
||||
{
|
||||
"任务描述": [
|
||||
{
|
||||
"text": "维护客户关系",
|
||||
"type": "text"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**富文本格式** (提及人、超链接):
|
||||
|
||||
```json
|
||||
{
|
||||
"任务描述": [
|
||||
{
|
||||
"text": "请 ",
|
||||
"type": "text"
|
||||
},
|
||||
{
|
||||
"text": "@张三",
|
||||
"type": "mention",
|
||||
"token": "ou_user123",
|
||||
"mentionType": "User",
|
||||
"mentionNotify": true,
|
||||
"name": "张三"
|
||||
},
|
||||
{
|
||||
"text": " 查看 ",
|
||||
"type": "text"
|
||||
},
|
||||
{
|
||||
"text": "飞书官网",
|
||||
"type": "url",
|
||||
"link": "https://www.feishu.cn"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**富文本元素类型**:
|
||||
|
||||
| type | 说明 | 额外字段 |
|
||||
|------|------|---------|
|
||||
| `"text"` | 纯文本 | `text` |
|
||||
| `"mention"` | 提及（人/文档） | `token`, `mentionType`, `mentionNotify`, `name` |
|
||||
| `"url"` | 超链接 | `text`, `link` |
|
||||
|
||||
**mentionType 可选值**:
|
||||
- `"User"`: 提及用户
|
||||
- `"Docx"`: 提及文档
|
||||
- `"Sheet"`: 提及电子表格
|
||||
- `"Bitable"`: 提及多维表格
|
||||
|
||||
---
|
||||
|
||||
### 条码 (ui_type="Barcode")
|
||||
|
||||
**写入格式**: 字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"商品条码": "FS0001"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**:
|
||||
|
||||
```json
|
||||
{
|
||||
"商品条码": [
|
||||
{
|
||||
"text": "FS0001",
|
||||
"type": "text"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 邮箱 (ui_type="Email")
|
||||
|
||||
**写入格式**: 字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"联系邮箱": "zhangmin@xxxgmail.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**:
|
||||
|
||||
```json
|
||||
{
|
||||
"联系邮箱": [
|
||||
{
|
||||
"text": "zhangmin@xxxgmail.com",
|
||||
"type": "url",
|
||||
"link": "mailto:zhangmin@xxxgmail.com"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数字 (type=2)
|
||||
|
||||
**写入/返回格式**: 数字
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"工时": 10,
|
||||
"完成率": 0.75,
|
||||
"预算": 5000.50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 进度 (ui_type="Progress"): 0-1 范围的小数
|
||||
- 货币 (ui_type="Currency"): 普通数字
|
||||
- 评分 (ui_type="Rating"): 整数
|
||||
|
||||
---
|
||||
|
||||
## 单选 (type=3)
|
||||
|
||||
**写入格式**: 选项名称字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"任务状态": "进行中"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**新选项**: 传入不存在的选项名会**自动创建新选项**
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"任务状态": "已暂停" // 如果不存在，会自动创建
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 与写入相同
|
||||
|
||||
```json
|
||||
{
|
||||
"任务状态": "进行中"
|
||||
}
|
||||
```
|
||||
|
||||
**限制**:
|
||||
- 选项总数不超过 20,000
|
||||
|
||||
---
|
||||
|
||||
## 多选 (type=4)
|
||||
|
||||
**写入格式**: 字符串数组
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"标签": ["审批集成", "办公管理", "身份管理"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**新选项**: 传入不存在的选项名会**自动创建新选项**
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"标签": ["新标签1", "新标签2"] // 不存在的会自动创建
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 与写入相同
|
||||
|
||||
```json
|
||||
{
|
||||
"标签": ["审批集成", "办公管理"]
|
||||
}
|
||||
```
|
||||
|
||||
**限制**:
|
||||
- 选项总数不超过 20,000
|
||||
- 单个单元格选项数不超过 1,000
|
||||
|
||||
---
|
||||
|
||||
## 日期 (type=5)
|
||||
|
||||
**写入/返回格式**: Unix 毫秒时间戳
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"截止日期": 1675526400000 // 2023-02-05 00:00:00 (UTC)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 必须使用**毫秒级**时间戳（不是秒级）
|
||||
- 建议使用北京时间 (UTC+8) 转换
|
||||
|
||||
**常见错误** (错误码 1254064):
|
||||
|
||||
```json
|
||||
// ❌ 错误：使用 ISO 字符串
|
||||
{"截止日期": "2026-02-27"}
|
||||
|
||||
// ❌ 错误：使用 RFC3339 格式
|
||||
{"截止日期": "2026-02-27T10:00:00+08:00"}
|
||||
|
||||
// ❌ 错误：使用秒级时间戳
|
||||
{"截止日期": 1772121600} // 少了 3 位
|
||||
|
||||
// ✅ 正确：使用毫秒时间戳
|
||||
{"截止日期": 1772121600000}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 复选框 (type=7)
|
||||
|
||||
**写入/返回格式**: 布尔值
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"是否完成": true,
|
||||
"是否延期": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 人员 (type=11)
|
||||
|
||||
**写入格式**: 对象数组，**仅支持 `id` 字段**
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"负责人": [
|
||||
{"id": "ou_8240099442cf5da49f04f4bf8f8abcef"}
|
||||
],
|
||||
"协作人": [
|
||||
{"id": "ou_user1"},
|
||||
{"id": "ou_user2"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 对象数组，包含完整信息
|
||||
|
||||
```json
|
||||
{
|
||||
"负责人": [
|
||||
{
|
||||
"id": "ou_8240099442cf5da49f04f4bf8f8abcef",
|
||||
"name": "黄泡泡",
|
||||
"en_name": "Amanda Huang",
|
||||
"email": "amandahuang@xxxgmail.com",
|
||||
"avatar_url": "https://..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 重要**:
|
||||
- **写入时只支持 `id`**，不能传 `name`、`email` 等字段
|
||||
- `id` 类型需与 `user_id_type` 参数一致（open_id/union_id/user_id）
|
||||
- 单个单元格人员数不超过 1,000
|
||||
- 传空: `null` 或 `[]`
|
||||
|
||||
---
|
||||
|
||||
## 电话号码 (type=13)
|
||||
|
||||
**写入/返回格式**: 字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"联系电话": "17899870000",
|
||||
"座机": "+86-010-12345678"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**格式规则**:
|
||||
- 符合正则: `(\+)?\d*`
|
||||
- 最大长度 64 字符
|
||||
|
||||
---
|
||||
|
||||
## 超链接 (type=15)
|
||||
|
||||
**写入/返回格式**: 对象
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"参考链接": {
|
||||
"text": "飞书开放平台",
|
||||
"link": "https://open.feishu.cn"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
- `text`: 显示的文本
|
||||
- `link`: URL 地址
|
||||
|
||||
**常见错误** (错误码 1254068):
|
||||
|
||||
```json
|
||||
// ❌ 错误：直接传字符串 URL
|
||||
{
|
||||
"参考链接": "https://open.feishu.cn"
|
||||
}
|
||||
|
||||
// ✅ 正确：使用对象格式
|
||||
{
|
||||
"参考链接": {
|
||||
"text": "飞书开放平台",
|
||||
"link": "https://open.feishu.cn"
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ text 和 link 可以相同
|
||||
{
|
||||
"参考链接": {
|
||||
"text": "https://open.feishu.cn",
|
||||
"link": "https://open.feishu.cn"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 附件 (type=17)
|
||||
|
||||
**写入格式**: 对象数组，**仅传 `file_token`**
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"附件": [
|
||||
{"file_token": "DRiFbwaKsoZaLax4WKZbEGCccoe"},
|
||||
{"file_token": "BZk3bL1Enoy4pzxaPL9bNeKqcLe"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 对象数组，包含完整信息
|
||||
|
||||
```json
|
||||
{
|
||||
"附件": [
|
||||
{
|
||||
"file_token": "J7GdbgNWWoD1fwx7oWccxdgknIe",
|
||||
"name": "58cc930b89.png",
|
||||
"type": "image/png",
|
||||
"size": 108867,
|
||||
"url": "https://open.feishu.cn/open-apis/drive/v1/medias/...",
|
||||
"tmp_url": "https://open.feishu.cn/open-apis/drive/v1/medias/batch_get_tmp_download_url?..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 重要**:
|
||||
- 写入前必须先调用[上传素材接口](https://go.feishu.cn/s/63soQp6O80s)获取 `file_token`
|
||||
- 单个单元格附件数不超过 100
|
||||
- 错误码 1254303: 附件未挂载到当前多维表格
|
||||
|
||||
---
|
||||
|
||||
## 单向关联 (type=18)
|
||||
|
||||
**写入格式**: `link_record_ids` 数组
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"关联任务": {
|
||||
"link_record_ids": ["recHTLvO7x", "recbS8zb2m"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**简化写入** (直接数组):
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"关联任务": ["recHTLvO7x", "recbS8zb2m"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**:
|
||||
|
||||
```json
|
||||
{
|
||||
"关联任务": {
|
||||
"link_record_ids": ["recHTLvO7x", "recbS8zb2m"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**限制**:
|
||||
- 单个单元格关联数不超过 500
|
||||
|
||||
---
|
||||
|
||||
## 双向关联 (type=21)
|
||||
|
||||
**写入/返回格式**: 与单向关联相同
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"相关项目": {
|
||||
"link_record_ids": ["reclzUoBLn", "rec7bYQoX1"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 更新双向关联会同步更新对方表的对应字段
|
||||
- 单个单元格关联数不超过 500
|
||||
|
||||
---
|
||||
|
||||
## 地理位置 (type=22)
|
||||
|
||||
**写入格式**: 经纬度字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"办公地址": "116.397755,39.903179"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 对象，包含详细信息
|
||||
|
||||
```json
|
||||
{
|
||||
"办公地址": {
|
||||
"location": "116.352681,40.01437",
|
||||
"pname": "北京市",
|
||||
"cityname": "北京市",
|
||||
"adname": "海淀区",
|
||||
"address": "学清路10号院学清嘉创大厦",
|
||||
"name": "Bytedance",
|
||||
"full_address": "Bytedance，北京市北京市海淀区学清路10号院学清嘉创大厦"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
- `location`: 经纬度 (格式: "经度,纬度")
|
||||
- `pname`: 省
|
||||
- `cityname`: 市
|
||||
- `adname`: 区
|
||||
- `address`: 详细地址
|
||||
- `name`: 地名
|
||||
- `full_address`: 完整地址
|
||||
|
||||
---
|
||||
|
||||
## 群组 (type=23)
|
||||
|
||||
**写入格式**: 对象数组，**仅传 `id`**
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"协作群": [
|
||||
{"id": "oc_d2a947abb78bbbbb12d4cad55fbabcef"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**: 对象数组，包含完整信息
|
||||
|
||||
```json
|
||||
{
|
||||
"协作群": [
|
||||
{
|
||||
"id": "oc_d2a947abb78bbbbb12d4cad55fbabcef",
|
||||
"name": "测试部门",
|
||||
"avatar_url": "https://..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**限制**:
|
||||
- 单个单元格群组数不超过 10
|
||||
|
||||
---
|
||||
|
||||
## 公式/查找引用 (type=20, type=19)
|
||||
|
||||
**格式**: 对象，包含 `type`、`ui_type` 和 `value`
|
||||
|
||||
```json
|
||||
{
|
||||
"是否延期": {
|
||||
"type": 1, // 底层数据类型
|
||||
"ui_type": "Text", // UI 展示类型
|
||||
"value": [ // 计算结果
|
||||
{
|
||||
"text": "✅ 正常",
|
||||
"type": "text"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
- `type`: 底层数据类型枚举（1=文本, 2=数字, 5=日期...）
|
||||
- `ui_type`: UI 展示类型（"Text"/"Number"/"Progress"/...）
|
||||
- `value`: 计算结果，格式由 `type` 决定
|
||||
|
||||
**示例 - 数字类型公式**:
|
||||
|
||||
```json
|
||||
{
|
||||
"总价": {
|
||||
"type": 2,
|
||||
"ui_type": "Currency",
|
||||
"value": 1250.50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**示例 - 日期类型公式**:
|
||||
|
||||
```json
|
||||
{
|
||||
"计算日期": {
|
||||
"type": 5,
|
||||
"ui_type": "DateTime",
|
||||
"value": 1675526400000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 注意**:
|
||||
- 公式字段为**只读**，不能通过写接口设置
|
||||
- `value` 的数据结构取决于 `type` 对应的字段类型
|
||||
|
||||
---
|
||||
|
||||
## 系统字段
|
||||
|
||||
### 创建时间 (type=1001)
|
||||
|
||||
**返回格式**: Unix 毫秒时间戳
|
||||
|
||||
```json
|
||||
{
|
||||
"创建于": 1675526400000
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 只读**: 不能通过写接口设置
|
||||
|
||||
---
|
||||
|
||||
### 最后更新时间 (type=1002)
|
||||
|
||||
**返回格式**: Unix 毫秒时间戳
|
||||
|
||||
```json
|
||||
{
|
||||
"更新于": 1675612800000
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 只读**: 不能通过写接口设置
|
||||
|
||||
---
|
||||
|
||||
### 创建人 / 修改人 (type=1003, type=1004)
|
||||
|
||||
**返回格式**: 对象数组（与人员字段相同）
|
||||
|
||||
```json
|
||||
{
|
||||
"创建人": [
|
||||
{
|
||||
"id": "ou_8240099442cf5da49f04f4bf8f8abcef",
|
||||
"name": "黄泡泡",
|
||||
"en_name": "Amanda Huang",
|
||||
"email": "amandahuang@xxxgmail.com",
|
||||
"avatar_url": "https://..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 只读**: 不能通过写接口设置
|
||||
|
||||
---
|
||||
|
||||
### 自动编号 (type=1005)
|
||||
|
||||
**返回格式**: 字符串
|
||||
|
||||
```json
|
||||
{
|
||||
"工单号": "WO-20240226-0001"
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ 只读**: 不能通过写接口设置
|
||||
|
||||
---
|
||||
|
||||
## 🔍 常见错误与排查
|
||||
|
||||
### 字段类型不匹配 (错误码 1254015)
|
||||
|
||||
**错误示例**:
|
||||
|
||||
```json
|
||||
// ❌ 错误: 日期字段传字符串
|
||||
{
|
||||
"fields": {
|
||||
"截止日期": "2024-02-26" // 应该传时间戳
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
{
|
||||
"fields": {
|
||||
"截止日期": 1708905600000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 人员字段格式错误 (错误码 1254066)
|
||||
|
||||
**常见原因**:
|
||||
|
||||
1. **传入了不支持的字段**:
|
||||
|
||||
```json
|
||||
// ❌ 错误
|
||||
{
|
||||
"负责人": [
|
||||
{"name": "张三"} // 只能传 id
|
||||
]
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
{
|
||||
"负责人": [
|
||||
{"id": "ou_xxx"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
2. **user_id_type 不匹配**:
|
||||
|
||||
```bash
|
||||
# 请求时指定了 user_id_type=open_id，但传的是 union_id
|
||||
```
|
||||
|
||||
3. **跨应用传 open_id**:
|
||||
|
||||
```
|
||||
不同应用的 open_id 不能交叉使用，建议使用 user_id
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 附件未挂载 (错误码 1254303)
|
||||
|
||||
**原因**: 直接传入外部 file_token
|
||||
|
||||
**解决**:
|
||||
|
||||
1. 先调用[上传素材接口](https://go.feishu.cn/s/63soQp6O80s)上传到当前多维表格
|
||||
2. 使用返回的 `file_token` 写入记录
|
||||
|
||||
---
|
||||
|
||||
### 字段名不存在 (错误码 1254045)
|
||||
|
||||
**原因**: 字段名称不完全匹配（可能有空格、换行、特殊字符）
|
||||
|
||||
**排查**:
|
||||
|
||||
1. 调用[列出字段接口](https://go.feishu.cn/s/62nuKkQlk03)获取准确字段名
|
||||
2. 检查首尾空格、换行符
|
||||
|
||||
---
|
||||
|
||||
### 超链接字段转换失败 (错误码 1254068)
|
||||
|
||||
**原因**: 缺少 `text` 或 `link` 字段
|
||||
|
||||
```json
|
||||
// ❌ 错误
|
||||
{
|
||||
"参考链接": {
|
||||
"link": "https://example.com" // 缺少 text
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
{
|
||||
"参考链接": {
|
||||
"text": "示例网站",
|
||||
"link": "https://example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📌 最佳实践
|
||||
|
||||
### 1. 批量写入优化
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"任务名称": "拜访客户",
|
||||
"负责人": [{"id": "ou_xxx"}],
|
||||
"截止日期": 1708905600000,
|
||||
"标签": ["重要", "紧急"],
|
||||
"是否完成": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**建议**:
|
||||
- 一次性传入所有字段，避免多次调用
|
||||
- 只传需要设置的字段，不必包含所有列
|
||||
|
||||
---
|
||||
|
||||
### 2. 清空字段值
|
||||
|
||||
**方法 1**: 传 `null`
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"负责人": null,
|
||||
"标签": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**方法 2**: 传空数组/空字符串（根据字段类型）
|
||||
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"负责人": [],
|
||||
"任务名称": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 时间戳转换
|
||||
|
||||
**JavaScript**:
|
||||
|
||||
```javascript
|
||||
// 北京时间字符串 → Unix 毫秒时间戳
|
||||
const timestamp = new Date("2024-02-26 14:00").getTime() // 1708927200000
|
||||
|
||||
// Unix 毫秒时间戳 → 日期字符串
|
||||
const date = new Date(1708927200000).toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' })
|
||||
```
|
||||
|
||||
**Python**:
|
||||
|
||||
```python
|
||||
import datetime
|
||||
|
||||
# 北京时间字符串 → Unix 毫秒时间戳
|
||||
dt = datetime.datetime(2024, 2, 26, 14, 0, 0)
|
||||
timestamp = int(dt.timestamp() * 1000) # 1708927200000
|
||||
|
||||
# Unix 毫秒时间戳 → 日期字符串
|
||||
dt = datetime.datetime.fromtimestamp(1708927200000 / 1000)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 关联字段的级联更新
|
||||
|
||||
**双向关联**:
|
||||
|
||||
```json
|
||||
// 更新 Table A 的双向关联字段
|
||||
{
|
||||
"fields": {
|
||||
"关联项目": {
|
||||
"link_record_ids": ["rec123"]
|
||||
}
|
||||
}
|
||||
}
|
||||
// Table B 的对应双向关联字段会自动更新
|
||||
```
|
||||
|
||||
**单向关联**:
|
||||
|
||||
```json
|
||||
// 只更新当前表，不影响关联表
|
||||
{
|
||||
"fields": {
|
||||
"参考任务": {
|
||||
"link_record_ids": ["rec456"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 参考链接
|
||||
|
||||
- [飞书开放平台 - 多维表格记录数据结构](https://go.feishu.cn/s/6lY28723w04)
|
||||
- [新增记录接口文档](https://go.feishu.cn/s/61Y-IrQjU02)
|
||||
- [更新记录接口文档](https://go.feishu.cn/s/6lY28723A04)
|
||||
- [上传素材接口](https://go.feishu.cn/s/63soQp6O80s)
|
||||
@@ -0,0 +1,244 @@
|
||||
---
|
||||
name: feishu-calendar
|
||||
description: |
|
||||
飞书日历与日程管理工具集。包含日历管理、日程管理、参会人管理、忙闲查询。
|
||||
---
|
||||
|
||||
# 飞书日历管理 (feishu-calendar)
|
||||
|
||||
## 🚨 执行前必读
|
||||
|
||||
- ✅ **时区固定**：Asia/Shanghai（UTC+8）
|
||||
- ✅ **时间格式**：ISO 8601 / RFC 3339（带时区），例如 `2026-02-25T14:00:00+08:00`
|
||||
- ✅ **create 最小必填**：summary, start_time, end_time
|
||||
- ✅ **user_open_id 强烈建议**：从 SenderId 获取（ou_xxx），确保用户能看到日程
|
||||
- ✅ **ID 格式约定**：用户 `ou_...`，群 `oc_...`，会议室 `omm_...`，邮箱 `email@...`
|
||||
|
||||
---
|
||||
|
||||
## 📋 快速索引：意图 → 工具 → 必填参数
|
||||
|
||||
| 用户意图 | 工具 | action | 必填参数 | 强烈建议 | 常用可选 |
|
||||
|---------|------|--------|---------|---------|---------|
|
||||
| 创建会议 | feishu_calendar_event | create | summary, start_time, end_time | user_open_id | attendees, description, location |
|
||||
| 查某时间段日程 | feishu_calendar_event | list | start_time, end_time | - | - |
|
||||
| 改日程时间 | feishu_calendar_event | patch | event_id, start_time/end_time | - | summary, description |
|
||||
| 搜关键词找会 | feishu_calendar_event | search | query | - | - |
|
||||
| 回复邀请 | feishu_calendar_event | reply | event_id, rsvp_status | - | - |
|
||||
| 查重复日程实例 | feishu_calendar_event | instances | event_id, start_time, end_time | - | - |
|
||||
| 查忙闲 | feishu_calendar_freebusy | list | time_min, time_max, user_ids[] | - | - |
|
||||
| 邀请参会人 | feishu_calendar_event_attendee | create | calendar_id, event_id, attendees[] | - | - |
|
||||
| 删除参会人 | feishu_calendar_event_attendee | batch_delete | calendar_id, event_id, user_open_ids[] | - | - |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 核心约束（Schema 未透露的知识）
|
||||
|
||||
### 1. user_open_id 为什么必填？
|
||||
|
||||
**工具使用用户身份**：日程创建在用户主日历上，用户本人能看到。
|
||||
|
||||
**但为什么还要传 user_open_id**：将发起人也添加为**参会人**，确保：
|
||||
- ✅ 发起人会收到日程通知
|
||||
- ✅ 发起人可以回复 RSVP 状态（接受/拒绝/待定）
|
||||
- ✅ 发起人出现在参会人列表中
|
||||
- ✅ 其他参会人能看到发起人
|
||||
|
||||
**如果不传**：
|
||||
- ⚠️ 用户能看到日程，但不会作为参会人
|
||||
- ⚠️ 如果只有其他参会人，发起人不在列表中（不符合常规逻辑）
|
||||
|
||||
### 2. 参会人权限（attendee_ability）
|
||||
|
||||
工具已默认设置 `attendee_ability: "can_modify_event"`，参会人可以编辑日程和管理参与者。
|
||||
|
||||
| 权限值 | 能力 |
|
||||
|--------|------|
|
||||
| `none` | 无权限 |
|
||||
| `can_see_others` | 可查看参与人列表 |
|
||||
| `can_invite_others` | 可邀请他人 |
|
||||
| `can_modify_event` | 可编辑日程（推荐） |
|
||||
|
||||
### 3. 统一使用 open_id（ou_...格式）
|
||||
|
||||
- ✅ 创建日程：`user_open_id = SenderId`
|
||||
- ✅ 邀请参会人：`attendees[].id = "ou_xxx"`
|
||||
- ✅ 删除参会人：`user_open_ids = ["ou_xxx"]`（工具已优化，直接传 open_id 即可）
|
||||
|
||||
⚠️ **ID 格式区分**：
|
||||
- `ou_xxx`：用户的 open_id（**你应该使用的**）
|
||||
- `user_xxx`：日程内部的 attendee_id（list 接口返回，仅用于内部记录）
|
||||
|
||||
### 4. 会议室预约是异步流程
|
||||
|
||||
添加会议室类型参会人后，会议室进入异步预约流程：
|
||||
1. API 返回成功 → `rsvp_status: "needs_action"`（预约中）
|
||||
2. 后台异步处理
|
||||
3. 最终状态：`accept`（成功）或 `decline`（失败）
|
||||
|
||||
**查询预约结果**：使用 `feishu_calendar_event_attendee.list` 查看 `rsvp_status`。
|
||||
|
||||
### 5. instances action 仅对重复日程有效
|
||||
|
||||
**⚠️ 重要**：`instances` action **仅对重复日程有效**，必须满足：
|
||||
1. event_id 必须是重复日程的 ID（该日程具有 `recurrence` 字段）
|
||||
2. 如果对普通日程调用，会返回错误
|
||||
|
||||
**如何判断**：
|
||||
1. 先用 `get` action 获取日程详情
|
||||
2. 检查返回值中是否有 `recurrence` 字段且不为空
|
||||
3. 如果有，则可以调用 `instances` 获取实例列表
|
||||
|
||||
---
|
||||
|
||||
## 📌 使用场景示例
|
||||
|
||||
### 场景 1: 创建会议并邀请参会人
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"summary": "项目复盘会议",
|
||||
"description": "讨论 Q1 项目进展",
|
||||
"start_time": "2026-02-25 14:00:00",
|
||||
"end_time": "2026-02-25 15:30:00",
|
||||
"user_open_id": "ou_aaa",
|
||||
"attendees": [
|
||||
{"type": "user", "id": "ou_bbb"},
|
||||
{"type": "user", "id": "ou_ccc"},
|
||||
{"type": "resource", "id": "omm_xxx"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 场景 2: 查询用户未来一周的日程
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "list",
|
||||
"start_time": "2026-02-25 00:00:00",
|
||||
"end_time": "2026-03-03 23:59:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 场景 3: 查看多个用户的忙闲时间
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "list",
|
||||
"time_min": "2026-02-25 09:00:00",
|
||||
"time_max": "2026-02-25 18:00:00",
|
||||
"user_ids": ["ou_aaa", "ou_bbb", "ou_ccc"]
|
||||
}
|
||||
```
|
||||
|
||||
**注意**：user_ids 是数组，支持 1-10 个用户。当前不支持会议室忙闲查询。
|
||||
|
||||
### 场景 4: 修改日程时间
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "patch",
|
||||
"event_id": "xxx_0",
|
||||
"start_time": "2026-02-25 15:00:00",
|
||||
"end_time": "2026-02-25 16:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 场景 5: 搜索日程（按关键词）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "search",
|
||||
"query": "项目复盘"
|
||||
}
|
||||
```
|
||||
|
||||
### 场景 6: 回复日程邀请
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "reply",
|
||||
"event_id": "xxx_0",
|
||||
"rsvp_status": "accept"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 常见错误与排查
|
||||
|
||||
| 错误现象 | 根本原因 | 解决方案 |
|
||||
|---------|---------|---------|
|
||||
| **发起人不在参会人列表中** | 未传 `user_open_id` | 强烈建议传 `user_open_id = SenderId` |
|
||||
| **参会人看不到其他参会人** | `attendee_ability` 权限不足 | 工具已默认设置 `can_modify_event` |
|
||||
| **时间不对** | 使用了 Unix 时间戳 | 改用 ISO 8601 格式（带时区）：`2024-01-01T00:00:00+08:00` |
|
||||
| **会议室显示"预约中"** | 会议室预约是异步的 | 等待几秒后用 `list` 查询 `rsvp_status` |
|
||||
| **修改日程报权限错误** | 当前用户不是组织者，且日程未设置可编辑权限 | 确保日程创建时设置了 `attendee_ability: "can_modify_event"` |
|
||||
| **无法查看参会人列表** | 当前用户无查看权限 | 确保是组织者或日程设置了 `can_see_others` 以上权限 |
|
||||
|
||||
---
|
||||
|
||||
## 📚 附录：背景知识
|
||||
|
||||
### A. 日历架构模型
|
||||
|
||||
飞书日历采用 **三层架构**：
|
||||
```
|
||||
日历（Calendar）
|
||||
└── 日程（Event）
|
||||
└── 参会人（Attendee）
|
||||
```
|
||||
|
||||
**关键理解**：
|
||||
1. **用户主日历**：日程创建在发起用户的主日历上，用户本人能看到
|
||||
2. **参会人机制**：通过添加参会人（attendee），让其他人的日历中也显示此日程
|
||||
3. **权限模型**：日程的 `attendee_ability` 参数控制参会人能否编辑日程、邀请他人、查看参与人列表
|
||||
|
||||
### B. 参会人类型
|
||||
|
||||
- `type: "user"` + `id: "ou_xxx"` — 飞书用户（使用 open_id）
|
||||
- `type: "chat"` + `id: "oc_xxx"` — 飞书群组
|
||||
- `type: "resource"` + `id: "omm_xxx"` — 会议室
|
||||
- `type: "third_party"` + `id: "email@example.com"` — 外部邮箱
|
||||
|
||||
### C. 日程的生命周期
|
||||
|
||||
1. **创建**：在用户主日历上创建日程（工具使用用户身份）
|
||||
2. **邀请参会人**：通过 attendee API 将日程分享给其他参会人
|
||||
3. **参会人回复**：参会人可以 accept/decline/tentative
|
||||
4. **修改**：组织者或有权限的参会人可以修改
|
||||
5. **删除**：删除后状态变为 `cancelled`
|
||||
|
||||
### D. 日历类型说明
|
||||
|
||||
| 类型 | 说明 | 能否删除 | 能否修改 |
|
||||
|------|------|---------|---------|
|
||||
| `primary` | 主日历（每个用户/应用一个） | ❌ 否 | ✅ 是 |
|
||||
| `shared` | 共享日历（用户创建并共享） | ✅ 是 | ✅ 是 |
|
||||
| `resource` | 会议室日历 | ❌ 否 | ❌ 否 |
|
||||
| `google` | 绑定的 Google 日历 | ❌ 否 | ❌ 否 |
|
||||
| `exchange` | 绑定的 Exchange 日历 | ❌ 否 | ❌ 否 |
|
||||
|
||||
### E. 回复状态（rsvp_status）说明
|
||||
|
||||
| 状态 | 含义（用户） | 含义（会议室） |
|
||||
|------|------------|---------------|
|
||||
| `needs_action` | 未回复 | 预约中 |
|
||||
| `accept` | 已接受 | 预约成功 |
|
||||
| `tentative` | 待定 | - |
|
||||
| `decline` | 拒绝 | 预约失败 |
|
||||
| `removed` | 已被移除 | 已被移除 |
|
||||
|
||||
|
||||
### F. 使用限制（来自飞书 OAPI 文档）
|
||||
|
||||
1. **每个日程最多 3000 名参会人**
|
||||
2. **单次添加参会人上限**：
|
||||
- 用户类参会人：1000 人
|
||||
- 会议室：100 个
|
||||
3. **主日历不可删除**（type 为 primary 的日历）
|
||||
4. **会议室预约可能失败**：
|
||||
- 时间冲突
|
||||
- 无预约权限
|
||||
- 会议室配置限制
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
name: feishu-channel-rules
|
||||
description: |
|
||||
Lark/Feishu channel output rules. Always active in Lark conversations.
|
||||
alwaysActive: true
|
||||
---
|
||||
|
||||
# Lark Output Rules
|
||||
|
||||
## Writing Style
|
||||
|
||||
- Short, conversational, low ceremony — talk like a coworker, not a manual
|
||||
- Prefer plain sentences over bullet lists when a brief answer suffices
|
||||
- Get to the point and stop — no need for a summary paragraph every time
|
||||
|
||||
## Note
|
||||
|
||||
- Lark Markdown differs from standard Markdown in some ways; when unsure, refer to `references/markdown-syntax.md`
|
||||
+138
@@ -0,0 +1,138 @@
|
||||
# 飞书 Markdown 语法参考
|
||||
|
||||
> 本文件是飞书消息卡片支持的完整 Markdown 语法参考，供需要时查阅。
|
||||
|
||||
## 1. 标题
|
||||
|
||||
```
|
||||
#### 四级标题
|
||||
##### 五级标题
|
||||
```
|
||||
|
||||
- **不支持**一二三级标题（`#`、`##`、`###`），会导致卡片显示异常
|
||||
- 可用加粗替代标题效果
|
||||
|
||||
## 2. 换行
|
||||
|
||||
```
|
||||
第一行\n第二行
|
||||
```
|
||||
|
||||
## 3. 文本样式
|
||||
|
||||
| 语法 | 效果 |
|
||||
|------|------|
|
||||
| `**加粗**` | **加粗** |
|
||||
| `*斜体*` | *斜体* |
|
||||
| `~~删除线~~` | ~~删除线~~ |
|
||||
|
||||
> **注意**：加粗中间的内容只能是中文或英文，不能有中文符号或表情符号
|
||||
|
||||
## 4. 链接
|
||||
|
||||
```
|
||||
[链接文本](https://www.example.com)
|
||||
```
|
||||
|
||||
## 5. @指定人
|
||||
|
||||
```
|
||||
<at id=id_01></at>
|
||||
<at ids=id_01,id_02,xxx></at>
|
||||
```
|
||||
|
||||
- 用户的 id 必须是用户给你的，不能瞎编
|
||||
- 可能是：以 `ou_` 开头的字符串、不超过 10 位的字符串、邮箱
|
||||
|
||||
## 6. 超链接
|
||||
|
||||
```
|
||||
<a href='https://open.feishu.cn'></a>
|
||||
```
|
||||
|
||||
## 7. 彩色文本
|
||||
|
||||
```
|
||||
<font color='green'>绿色文本</font>
|
||||
```
|
||||
|
||||
> 颜色枚举：`neutral`, `blue`, `turquoise`, `lime`, `orange`, `violet`, `wathet`, `green`, `yellow`, `red`, `purple`, `carmine`
|
||||
|
||||
## 8. 文字链接
|
||||
|
||||
```
|
||||
<a href='https://open.feishu.cn'>这是文字链接</a>
|
||||
```
|
||||
|
||||
## 9. 图片
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
> image_key 不支持 http 链接
|
||||
|
||||
## 10. 分割线
|
||||
|
||||
```
|
||||
---
|
||||
```
|
||||
|
||||
## 11. 标签
|
||||
|
||||
```
|
||||
<text_tag color='red'>标签文本</text_tag>
|
||||
```
|
||||
|
||||
颜色枚举：`neutral`, `blue`, `turquoise`, `lime`, `orange`, `violet`, `wathet`, `green`, `yellow`, `red`, `purple`, `carmine`
|
||||
|
||||
## 12. 有序列表
|
||||
|
||||
```
|
||||
1. 一级列表①
|
||||
1.1 二级列表
|
||||
1.2 二级列表
|
||||
2. 一级列表②
|
||||
```
|
||||
|
||||
- 序号需在行首使用，序号后要跟空格
|
||||
- 4 个空格代表一层缩进
|
||||
|
||||
## 13. 无序列表
|
||||
|
||||
```
|
||||
- 一级列表①
|
||||
- 二级列表
|
||||
- 一级列表②
|
||||
```
|
||||
|
||||
- 4 个空格代表一层缩进
|
||||
- `-` 后面要跟空格
|
||||
|
||||
## 14. 代码块
|
||||
|
||||
````
|
||||
```JSON
|
||||
{"This is": "JSON demo"}
|
||||
```
|
||||
````
|
||||
|
||||
- 支持指定编程语言解析
|
||||
- 未指定默认为 Plain Text
|
||||
|
||||
## 15. 人员组件
|
||||
|
||||
```
|
||||
<person id='user_id' show_name=true show_avatar=true style='normal'></person>
|
||||
```
|
||||
|
||||
- `show_name`：是否展示用户名（默认 true）
|
||||
- `show_avatar`：是否展示用户头像（默认 true）
|
||||
- `style`：展示样式（`normal`：普通样式，`capsule`：胶囊样式）
|
||||
- **注意**：person 标签不能嵌套在 font 中
|
||||
|
||||
## 16. 数字角标
|
||||
|
||||
```
|
||||
<number_tag background_color='grey' font_color='white' url='https://open.feishu.cn' pc_url='https://open.feishu.cn' android_url='https://open.feishu.cn' ios_url='https://open.feishu.cn'>1</number_tag>
|
||||
```
|
||||
@@ -0,0 +1,719 @@
|
||||
---
|
||||
name: feishu-create-doc
|
||||
description: |
|
||||
创建飞书云文档。从 Lark-flavored Markdown 内容创建新的飞书云文档，支持指定创建位置（文件夹/知识库/知识空间）。
|
||||
---
|
||||
|
||||
# feishu_mcp_create_doc
|
||||
|
||||
通过 MCP 调用 `create-doc`，从 Lark-flavored Markdown 内容创建一个新的飞书云文档。
|
||||
|
||||
# 返回值
|
||||
|
||||
工具成功执行后，返回一个 JSON 对象，包含以下字段：
|
||||
|
||||
- **`doc_id`**（string）：文档的唯一标识符（token），格式如 `doxcnXXXXXXXXXXXXXXXXXXX`
|
||||
- **`doc_url`**（string）：文档的访问链接，可直接在浏览器中打开，格式如 `https://www.feishu.cn/docx/doxcnXXXXXXXXXXXXXXXXXXX`
|
||||
- **`message`**（string）：操作结果消息，如"文档创建成功"
|
||||
|
||||
|
||||
# 参数
|
||||
|
||||
## markdown（必填）
|
||||
文档的 Markdown 内容，使用 Lark-flavored Markdown 格式。
|
||||
|
||||
调用本工具的markdown内容应当尽量结构清晰,样式丰富, 有很高的可读性. 合理的使用callout高亮块, 分栏,表格等能力,并合理的运用插入图片与mermaid的能力,做到图文并茂..
|
||||
你需要遵循以下原则:
|
||||
|
||||
- **结构清晰**：标题层级 ≤ 4 层，用 Callout 突出关键信息
|
||||
- **视觉节奏**：用分割线、分栏、表格打破大段纯文字
|
||||
- **图文交融**：流程和架构优先用 Mermaid/PlantUML 可视化
|
||||
- **克制留白**：Callout 不过度、加粗只强调核心词
|
||||
|
||||
当用户有明确的样式,风格需求时,应当以用户的需求为准!!
|
||||
|
||||
**重要提示**：
|
||||
- **禁止重复标题**：markdown 内容开头不要写与 title 相同的一级标题！title 参数已经是文档标题，markdown 应直接从正文内容开始
|
||||
- **目录**：飞书自动生成，无需手动添加
|
||||
- Markdown 语法必须符合 Lark-flavored Markdown 规范，详见下方"内容格式"章节
|
||||
- 创建较长的文档时,强烈建议配合update-doc中的append mode, 进行分段的创建,提高成功率.
|
||||
|
||||
## title（可选）
|
||||
文档标题。
|
||||
|
||||
## folder_token（可选）
|
||||
父文件夹的 token。如果不提供，文档将创建在用户的个人空间根目录。
|
||||
|
||||
folder_token 可以从飞书文件夹 URL 中获取，格式如：`https://xxx.feishu.cn/drive/folder/fldcnXXXX`，其中 `fldcnXXXX` 即为 folder_token。
|
||||
|
||||
## wiki_node（可选）
|
||||
知识库节点 token 或 URL（可选，传入则在该节点下创建文档，与 folder_token 和 wiki_space 互斥）
|
||||
|
||||
wiki_node 可以从飞书知识库页面 URL 中获取，格式如：`https://xxx.feishu.cn/wiki/wikcnXXXX`，其中 `wikcnXXXX` 即为 wiki_node token。
|
||||
|
||||
## wiki_space（可选）
|
||||
知识空间 ID（可选，传入则在该空间根目录下创建文档。特殊值 `my_library` 表示用户的个人知识库。与 wiki_node 和 folder_token 互斥）
|
||||
|
||||
wiki_space 可以从知识空间设置页面 URL 中获取，格式如：`https://xxx.feishu.cn/wiki/settings/7448000000000009300`，其中 `7448000000000009300` 即为 wiki_space ID。
|
||||
|
||||
**参数优先级**：wiki_node > wiki_space > folder_token
|
||||
|
||||
# 示例
|
||||
|
||||
## 示例 1：创建简单文档
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "项目计划",
|
||||
"markdown": "# 项目概述\n\n这是一个新项目。\n\n## 目标\n\n- 目标 1\n- 目标 2"
|
||||
}
|
||||
```
|
||||
|
||||
## 示例 2：创建到指定文件夹
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "会议纪要",
|
||||
"folder_token": "fldcnXXXXXXXXXXXXXXXXXXXXXX",
|
||||
"markdown": "# 周会 2025-01-15\n\n## 讨论议题\n\n1. 项目进度\n2. 下周计划"
|
||||
}
|
||||
```
|
||||
|
||||
## 示例 3：使用飞书扩展语法
|
||||
|
||||
使用高亮块、表格等飞书特有功能：
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "产品需求",
|
||||
"markdown": "<callout emoji=\"💡\" background-color=\"light-blue\">\n重要需求说明\n</callout>\n\n## 功能列表\n\n<lark-table header-row=\"true\">\n| 功能 | 优先级 |\n|------|--------|\n| 登录 | P0 |\n| 导出 | P1 |\n</lark-table>"
|
||||
}
|
||||
```
|
||||
|
||||
## 示例 4：创建到知识库节点下
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "技术文档",
|
||||
"wiki_node": "wikcnXXXXXXXXXXXXXXXXXXXXXX",
|
||||
"markdown": "# API 接口说明\n\n这是一个知识库文档。"
|
||||
}
|
||||
```
|
||||
|
||||
## 示例 5：创建到知识空间根目录
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "项目概览",
|
||||
"wiki_space": "7448000000000009300",
|
||||
"markdown": "# 项目概览\n\n这是知识空间根目录下的一级文档。"
|
||||
}
|
||||
```
|
||||
|
||||
## 示例 6：创建到个人知识库
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "学习笔记",
|
||||
"wiki_space": "my_library",
|
||||
"markdown": "# 学习笔记\n\n这是创建在个人知识库中的文档。"
|
||||
}
|
||||
```
|
||||
|
||||
# 内容格式
|
||||
|
||||
文档内容使用 **Lark-flavored Markdown** 格式，这是标准 Markdown 的扩展版本，支持飞书文档的所有块类型和富文本格式。
|
||||
|
||||
## 通用规则
|
||||
|
||||
- 使用标准 Markdown 语法作为基础
|
||||
- 使用自定义 XML 标签实现飞书特有功能（具体标签见各功能章节）
|
||||
- 需要显示特殊字符时使用反斜杠转义：`* ~ ` $ [ ] < > { } | ^`
|
||||
|
||||
---
|
||||
|
||||
## 📝 基础块类型
|
||||
|
||||
### 文本（段落）
|
||||
|
||||
```markdown
|
||||
普通文本段落
|
||||
|
||||
段落中的**粗体文字**
|
||||
|
||||
多个段落之间用空行分隔。
|
||||
|
||||
居中文本 {align="center"}
|
||||
右对齐文本 {align="right"}
|
||||
```
|
||||
|
||||
**段落对齐**：支持 `{align="left|center|right"}` 语法。可与颜色组合：`{color="blue" align="center"}`
|
||||
|
||||
### 标题
|
||||
|
||||
飞书支持 9 级标题。H1-H6 使用标准 Markdown 语法，H7-H9 使用 HTML 标签：
|
||||
|
||||
```markdown
|
||||
# 一级标题
|
||||
## 二级标题
|
||||
### 三级标题
|
||||
#### 四级标题
|
||||
##### 五级标题
|
||||
###### 六级标题
|
||||
<h7>七级标题</h7>
|
||||
<h8>八级标题</h8>
|
||||
<h9>九级标题</h9>
|
||||
|
||||
# 带颜色的标题 {color="blue"}
|
||||
## 红色标题 {color="red"}
|
||||
# 居中标题 {align="center"}
|
||||
## 蓝色居中标题 {color="blue" align="center"}
|
||||
```
|
||||
|
||||
**标题属性**：支持 `{color="颜色名"}` 和 `{align="left|center|right"}` 语法，可组合使用。颜色值：red, orange, yellow, green, blue, purple, gray。请谨慎使用该能力.
|
||||
|
||||
### 列表
|
||||
有序列表,无序列表嵌套使用tab或者 2 空格缩进
|
||||
```markdown
|
||||
- 无序项1（
|
||||
- 无序项1.a
|
||||
- 无序项1.b
|
||||
|
||||
1. 有序项1
|
||||
2. 有序项2
|
||||
|
||||
- [ ] 待办
|
||||
- [x] 已完成
|
||||
```
|
||||
|
||||
### 引用块
|
||||
|
||||
```markdown
|
||||
> 这是一段引用
|
||||
> 可以跨多行
|
||||
|
||||
> 引用中支持**加粗**和*斜体*等格式
|
||||
```
|
||||
|
||||
### 代码块
|
||||
|
||||
**⚠️** 只支持围栏代码块（` ``` `），不支持缩进代码块。
|
||||
|
||||
````markdown
|
||||
```python
|
||||
print("Hello")
|
||||
```
|
||||
````
|
||||
|
||||
支持语言：python, javascript, go, java, sql, json, yaml, shell 等。
|
||||
|
||||
### 分割线
|
||||
|
||||
```markdown
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 富文本格式
|
||||
|
||||
### 文本样式
|
||||
|
||||
`**粗体**` `*斜体*` `~~删除线~~` `` `行内代码` `` `<u>下划线</u>`
|
||||
|
||||
### 文字颜色
|
||||
|
||||
`<text color="red">红色</text>` `<text background-color="yellow">黄色背景</text>`
|
||||
|
||||
支持: red, orange, yellow, green, blue, purple, gray
|
||||
|
||||
### 链接
|
||||
|
||||
`[链接文字](https://example.com)` （不支持锚点链接）
|
||||
|
||||
### 行内公式（LaTeX）
|
||||
|
||||
`$E = mc^2$`（`$`前后需空格）或 `<equation>E = mc^2</equation>`（无限制，推荐）
|
||||
|
||||
---
|
||||
|
||||
## 🚀 高级块类型
|
||||
|
||||
### 高亮块（Callout）
|
||||
|
||||
```html
|
||||
<callout emoji="✅" background-color="light-green" border-color="green">
|
||||
支持**格式化**的内容，可包含多个块
|
||||
</callout>
|
||||
```
|
||||
|
||||
**属性**: emoji (使用emoji 字符如 ✅ ⚠️ 💡), background-color, border-color, text-color
|
||||
|
||||
**背景色**: light-red/red, light-blue/blue, light-green/green, light-yellow/yellow, light-orange/orange, light-purple/purple, pale-gray/light-gray/dark-gray
|
||||
|
||||
**常用**: 💡light-blue(提示) ⚠️light-yellow(警告) ❌light-red(危险) ✅light-green(成功)
|
||||
|
||||
**限制**: callout子块仅支持文本、标题、列表、待办、引用。不支持代码块、表格、图片。
|
||||
|
||||
### 分栏（Grid）
|
||||
|
||||
适合对比、并列展示场景。支持 2-5 列：
|
||||
#### 两栏（等宽）
|
||||
|
||||
```html
|
||||
<grid cols="2">
|
||||
<column>
|
||||
|
||||
左栏内容
|
||||
|
||||
</column>
|
||||
<column>
|
||||
|
||||
右栏内容
|
||||
|
||||
</column>
|
||||
</grid>
|
||||
```
|
||||
#### 三栏自定义宽度
|
||||
```html
|
||||
<grid cols="3">
|
||||
<column width="20">左栏(20%)</column>
|
||||
<column width="60">中栏(60%)</column>
|
||||
<column width="20">右栏(20%)</column>
|
||||
</grid>
|
||||
```
|
||||
|
||||
**属性**: `cols`(列数 2-5), `width`(列宽百分比，总和为100，等宽时可省略)
|
||||
|
||||
### 表格
|
||||
|
||||
#### 标准 Markdown 表格
|
||||
|
||||
```markdown
|
||||
| 列 1 | 列 2 | 列 3 |
|
||||
|------|------|------|
|
||||
| 单元格 1 | 单元格 2 | 单元格 3 |
|
||||
| 单元格 4 | 单元格 5 | 单元格 6 |
|
||||
```
|
||||
|
||||
#### 飞书增强表格
|
||||
|
||||
当单元格需要复杂内容（列表、代码块、高亮块等）时使用。
|
||||
|
||||
**层级结构**（必须严格遵守）：
|
||||
```
|
||||
<lark-table> ← 表格容器
|
||||
<lark-tr> ← 行（直接子元素只能是 lark-tr）
|
||||
<lark-td>内容</lark-td> ← 单元格（直接子元素只能是 lark-td）
|
||||
<lark-td>内容</lark-td> ← 每行的 lark-td 数量必须相同！
|
||||
</lark-tr>
|
||||
</lark-table>
|
||||
```
|
||||
|
||||
**属性**：
|
||||
- `column-widths`：列宽，逗号分隔像素值，总宽≈730
|
||||
- `header-row`：首行是否为表头（`"true"` 或 `"false"`）
|
||||
- `header-column`：首列是否为表头（`"true"` 或 `"false"`）
|
||||
|
||||
**单元格写法**：内容前后必须空行
|
||||
```html
|
||||
<lark-td>
|
||||
|
||||
这里写内容
|
||||
|
||||
</lark-td>
|
||||
```
|
||||
|
||||
**完整示例**（2行3列）：
|
||||
```html
|
||||
<lark-table column-widths="200,250,280" header-row="true">
|
||||
<lark-tr>
|
||||
<lark-td>
|
||||
|
||||
**表头1**
|
||||
|
||||
</lark-td>
|
||||
<lark-td>
|
||||
|
||||
**表头2**
|
||||
|
||||
</lark-td>
|
||||
<lark-td>
|
||||
|
||||
**表头3**
|
||||
|
||||
</lark-td>
|
||||
</lark-tr>
|
||||
<lark-tr>
|
||||
<lark-td>
|
||||
|
||||
普通文本
|
||||
|
||||
</lark-td>
|
||||
<lark-td>
|
||||
|
||||
- 列表项1
|
||||
- 列表项2
|
||||
|
||||
</lark-td>
|
||||
<lark-td>
|
||||
|
||||
代码内容
|
||||
|
||||
</lark-td>
|
||||
</lark-tr>
|
||||
</lark-table>
|
||||
```
|
||||
|
||||
**限制**：单元格内不支持 Grid 和嵌套表格
|
||||
|
||||
**合并单元格**：读取时返回 `rowspan/colspan` 属性，创建暂不支持
|
||||
|
||||
**禁止**：
|
||||
- 混用 Markdown 表格语法（`|---|`）
|
||||
- 使用 `<br/>` 换行
|
||||
- 遗漏 `<lark-td>` 标签
|
||||
|
||||
|
||||
### 图片
|
||||
|
||||
```html
|
||||
<image url="https://example.com/image.png" width="800" height="600" align="center" caption="图片描述文字"/>
|
||||
```
|
||||
|
||||
**属性**: url (必需，系统会自动下载并上传), width, height, align (left/center/right), caption
|
||||
|
||||
**⚠️ 重要**: 不支持直接使用 `token` 属性（如 `<image token="xxx"/>`），只支持 URL 方式。系统会自动下载图片并上传到飞书。
|
||||
|
||||
支持 PNG/JPG/GIF/WebP/BMP，最大 10MB
|
||||
|
||||
**图片/文件插入方式选择**：
|
||||
- **有公开可访问的图片 URL** → 直接在 create-doc / update-doc 的 markdown 中使用 `<image url="..."/>` 一步到位
|
||||
|
||||
- **本地图片或文件**（如用户在聊天中发送的图片/文件） → 先用 create-doc / update-doc 创建或更新文档文本内容，再用 `feishu_doc_media` 工具将本地图片或文件追加到文档末尾。如需媒体出现在文档中间特定位置，可先用 create-doc 写好之前的内容，调用 `feishu_doc_media` 追加图片/文件，最后用 update-doc 的 **append** 模式追加后续内容
|
||||
|
||||
### 文件
|
||||
|
||||
```html
|
||||
<file url="https://example.com/document.pdf" name="文档.pdf" view-type="1"/>
|
||||
```
|
||||
|
||||
**属性**:
|
||||
- url (文件 URL，必需，系统会自动下载并上传)
|
||||
- name (文件名，必需)
|
||||
- view-type (1=卡片视图, 2=预览视图，可选)
|
||||
|
||||
**⚠️ 重要**: 不支持直接使用 `token` 属性（如 `<file token="xxx"/>`）
|
||||
|
||||
|
||||
### 画板（Mermaid / PlantUML 图表）
|
||||
|
||||
支持两种图表语法：Mermaid 和 PlantUML。
|
||||
|
||||
#### Mermaid 图表
|
||||
|
||||
**图表优先选择此格式**. mermaid图表会被渲染为可视化的画板, 如果能用mermaid实现的图表,应当优先选择mermaid.
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
graph TD
|
||||
A[开始] --> B{判断}
|
||||
B -->|是| C[处理]
|
||||
B -->|否| D[结束]
|
||||
```
|
||||
````
|
||||
|
||||
**支持图表类型**: flowchart, sequenceDiagram, classDiagram, stateDiagram, gantt, mindmap, erDiagram
|
||||
|
||||
#### PlantUML 图表
|
||||
|
||||
PlantUML图表会被渲染为可视化的画板. mermaid满足不了的场景可以选择plantUML进行绘图.
|
||||
|
||||
````markdown
|
||||
```plantuml
|
||||
@startuml
|
||||
Alice -> Bob: Hello
|
||||
Bob --> Alice: Hi!
|
||||
@enduml
|
||||
```
|
||||
````
|
||||
|
||||
**支持图表类型**: sequence, usecase, class, activity, component, state, object, deployment
|
||||
|
||||
#### 读取画板
|
||||
|
||||
读取时返回 `<whiteboard>` 标签：
|
||||
|
||||
```html
|
||||
<whiteboard token="xxx" align="center" width="800" height="600"/>
|
||||
```
|
||||
|
||||
**属性**: token (画板标识), align (left/center/right), width, height
|
||||
|
||||
**重要说明**：
|
||||
- create-doc时用 Mermaid/PlantUML 代码块，系统自动转换为画板; 禁止以`<whiteboard>`的方式写入!!
|
||||
- 读取时只能获取 token，可通过fetch-file工具进行查看内容。无法获取原始源码
|
||||
|
||||
### 多维表格（Bitable）
|
||||
|
||||
```html
|
||||
<bitable view="table"/>
|
||||
<bitable view="kanban"/>
|
||||
```
|
||||
|
||||
**属性**: view (table/kanban，默认 table)
|
||||
|
||||
**注意**: token 是只读属性，创建时不能指定只能创建空的多维表格，创建后再手动添加数据。
|
||||
|
||||
### 会话卡片（ChatCard）
|
||||
|
||||
```html
|
||||
<chat-card id="oc_xxx" align="center"/>
|
||||
```
|
||||
|
||||
**属性**: id (格式 oc_xxx, 必需), align (left/center/right)
|
||||
|
||||
### 内嵌网页（Iframe）
|
||||
|
||||
```html
|
||||
<iframe url="https://example.com/survey?id=123" type="12"/>
|
||||
```
|
||||
|
||||
**属性**: url (必需), type (组件类型数字, 必需)
|
||||
|
||||
**type 枚举**: 1=Bilibili, 2=西瓜, 3=优酷, 4=Airtable, 5=百度地图, 6=高德地图, 8=Figma, 9=墨刀, 10=Canva, 11=CodePen, 12=飞书问卷, 13=金数据
|
||||
|
||||
**重要提示**: 仅支持上述列出的网页类型。其他类型的网页不支持嵌入，请不要使用 iframe。对于普通网页链接，请使用 Markdown 链接格式 `[链接文字](URL)` 代替。
|
||||
|
||||
### 链接预览（LinkPreview）
|
||||
|
||||
```html
|
||||
<link-preview url="消息链接" type="message"/>
|
||||
```
|
||||
|
||||
**属性**: url (必需, 只写属性), type (message=消息链接)
|
||||
|
||||
目前仅支持消息链接, 只支持读取, 不支持创建
|
||||
|
||||
### 引用容器（QuoteContainer）
|
||||
|
||||
```html
|
||||
<quote-container>
|
||||
引用容器内容
|
||||
</quote-container>
|
||||
```
|
||||
|
||||
与 quote 引用块不同，引用容器是容器类型，可包含多个子块
|
||||
|
||||
---
|
||||
|
||||
## 🔧 高级功能块
|
||||
|
||||
### 电子表格（Sheet）
|
||||
|
||||
```html
|
||||
<sheet rows="5" cols="5"/>
|
||||
<sheet/>
|
||||
```
|
||||
|
||||
**属性**: rows (行数，默认 3，最大 9), cols (列数，默认 3)
|
||||
|
||||
**注意**: token 是只读属性，创建时不能指定。只能创建空的电子表格，创建后使用 Sheet API 操作数据。
|
||||
|
||||
### 只读块类型 🔒
|
||||
|
||||
以下块类型仅支持读取，不支持创建：
|
||||
|
||||
| 块类型 | 标签 | 说明 |
|
||||
|--------|------|------|
|
||||
| 思维笔记 | `<mindnote token="xxx"/>` | 仅获取占位信息 |
|
||||
| 流程图/UML | `<diagram type="1"/>` | type: 1=流程图, 2=UML |
|
||||
| AI 模板 | `<ai-template/>` | 无内容占位块 |
|
||||
|
||||
### 任务块
|
||||
|
||||
```html
|
||||
<task task-id="xxx" members="ou_123, ou_456" due="2025-01-01">任务标题</task>
|
||||
```
|
||||
|
||||
**属性**: task-id, members (成员ID列表), due (截止日期)
|
||||
|
||||
### 同步块
|
||||
|
||||
```html
|
||||
<!-- 源同步块：内容在子块中 -->
|
||||
<source-synced align="1">子块内容...</source-synced>
|
||||
|
||||
<!-- 引用同步块：自动获取源文档内容 -->
|
||||
<reference-synced source-block-id="xxx" source-document-id="yyy">源内容...</reference-synced>
|
||||
```
|
||||
|
||||
**属性**: source-synced 有 align；reference-synced 有 source-block-id, source-document-id
|
||||
|
||||
### 文档小组件（AddOns）
|
||||
|
||||
```html
|
||||
<add-ons component-type-id="blk_xxx" record='{"key":"value"}'/>
|
||||
```
|
||||
|
||||
**属性**: component-type-id (小组件类型ID), record (JSON数据)
|
||||
|
||||
包含多种类型：问答互动、日期提醒等。部分组件如 Mermaid 已专门封装为 board 块
|
||||
|
||||
### 旧版小组件（ISV）
|
||||
|
||||
```html
|
||||
<isv id="comp_xxx" type="type_xxx"/>
|
||||
```
|
||||
|
||||
**属性**: component_id, component_type_id
|
||||
|
||||
旧版开放平台小组件，新版请使用 AddOns
|
||||
|
||||
### Wiki 子目录（WikiCatalog）🕰️
|
||||
|
||||
```html
|
||||
<wiki-catalog token="wiki_xxx"/>
|
||||
```
|
||||
|
||||
**属性**: wiki_token (知识库节点token)
|
||||
|
||||
🕰️ 旧版，建议使用新版 sub-page-list
|
||||
|
||||
### Wiki 子页面列表（SubPageList）
|
||||
|
||||
```html
|
||||
<sub-page-list wiki="wiki_xxx"/>
|
||||
```
|
||||
|
||||
**属性**: wiki_token (当前页面的wiki token)
|
||||
|
||||
仅支持知识库文档创建，需传入当前页面的 wiki token
|
||||
|
||||
### 议程（Agenda）
|
||||
|
||||
```html
|
||||
<agenda>
|
||||
<agenda-item>
|
||||
<agenda-title>议程标题</agenda-title>
|
||||
<agenda-content>议程内容</agenda-content>
|
||||
</agenda-item>
|
||||
</agenda>
|
||||
```
|
||||
|
||||
**结构**: agenda (容器) → agenda_item (议程项) → agenda_title (标题) + agenda_content (内容)
|
||||
|
||||
### Jira 问题（JiraIssue）
|
||||
|
||||
```html
|
||||
<jira-issue id="xxx" key="PROJECT-123"/>
|
||||
```
|
||||
|
||||
**属性**: id (Jira问题ID), key (Jira问题Key)
|
||||
|
||||
### OKR 系列⚠️
|
||||
|
||||
```html
|
||||
<okr id="okr_xxx">
|
||||
<objective id="obj_1">
|
||||
<kr id="kr_1"/>
|
||||
</objective>
|
||||
</okr>
|
||||
```
|
||||
|
||||
⚠️ 仅支持 user_access_token 创建，需使用 OKR API 进行详细操作
|
||||
|
||||
**结构**: okr → okr_objective (目标) → okr_key_result (关键结果) + okr_progress (进展)
|
||||
|
||||
---
|
||||
|
||||
## 📎 提及和引用
|
||||
|
||||
### 提及用户
|
||||
|
||||
```html
|
||||
<mention-user id="ou_xxx"/>
|
||||
```
|
||||
|
||||
**属性**: id (用户 open_id，格式 ou_xxx)
|
||||
|
||||
注意不要直接在文档中写`@张三` 这类格式,应当使用search-user获取用户的id,并使用`mention-user`.
|
||||
|
||||
### 提及文档
|
||||
|
||||
```html
|
||||
<mention-doc token="doxcnXXX" type="docx">文档标题</mention-doc>
|
||||
```
|
||||
|
||||
**属性**: token (文档 token), type (docx/sheet/bitable)
|
||||
|
||||
---
|
||||
|
||||
## 📅 日期和时间
|
||||
|
||||
### 日期提醒（Reminder）
|
||||
|
||||
```html
|
||||
<reminder date="2025-12-31T18:00+08:00" notify="true" user-id="ou_xxx"/>
|
||||
```
|
||||
|
||||
**属性**:
|
||||
- date (必需): `YYYY-MM-DDTHH:mm+HH:MM`, ISO 8601 带时区偏移
|
||||
- notify (true/false): 是否发送通知
|
||||
- user-id (必需): 创建者用户 ID
|
||||
|
||||
---
|
||||
|
||||
## 📐 数学表达式
|
||||
|
||||
### 块级公式（LaTeX）
|
||||
|
||||
````markdown
|
||||
$$
|
||||
\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
|
||||
$$
|
||||
````
|
||||
|
||||
### 行内公式
|
||||
|
||||
```markdown
|
||||
爱因斯坦方程：$E = mc^2$（注意 $ 前后需空格，紧邻位置不能有空格）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✍️ 写作指南
|
||||
|
||||
### 场景速查
|
||||
|
||||
| 场景 | 推荐组件 | 说明 |
|
||||
|------|----------|------|
|
||||
| 重点提示/警告 | Callout | 蓝色提示、黄色警告、红色危险 |
|
||||
| 对比/并列展示 | Grid 分栏 | 2-3 列最佳，配合 Callout 更醒目 |
|
||||
| 数据汇总 | 表格 | 简单用 Markdown，复杂嵌套用 lark-table |
|
||||
| 步骤说明 | 有序列表 | 可嵌套子步骤 |
|
||||
| 时间线/版本 | 有序列表 + 加粗日期 | 或用 Mermaid timeline |
|
||||
| 代码展示 | 代码块 | 标注语言，适当添加注释 |
|
||||
| 知识卡片 | Callout + emoji | 用于概念解释、小贴士 |
|
||||
| 引用说明 | 引用块 > | 引用原文、名言 |
|
||||
| 术语对照 | 两列表格 | 中英文、缩写全称等 |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 最佳实践
|
||||
|
||||
- **空行分隔**：不同块类型之间用空行分隔
|
||||
- **转义字符**：特殊字符用 `\` 转义：`\*` `\~` `\``
|
||||
- **图片**：使用 URL，系统自动下载上传
|
||||
- **分栏**：列宽总和必须为 100
|
||||
- **表格选择**：简单数据用 Markdown，复杂嵌套用 `<lark-table>`
|
||||
- **提及**：@用户用 `<mention-user>`，@文档用 `<mention-doc>`
|
||||
- **目录**：飞书自动生成，无需手动添加
|
||||
|
||||
---
|
||||
|
||||
## 📖 补充说明
|
||||
|
||||
- 图片、画板、多维表格需要 token（URL 会自动上传转换）
|
||||
- 提及用户和会话卡片需要相应访问权限
|
||||
- 完全兼容标准 Markdown
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
name: feishu-fetch-doc
|
||||
description: |
|
||||
获取飞书云文档内容。返回文档的 Markdown 内容，支持处理文档中的图片、文件和画板（需配合 feishu_doc_media 工具）。
|
||||
---
|
||||
|
||||
# feishu_mcp_fetch_doc
|
||||
|
||||
获取飞书云文档的 Markdown 内容（Lark-flavored 格式）。
|
||||
|
||||
## 重要：图片、文件、画板的处理
|
||||
|
||||
**文档中的图片、文件、画板需要通过 `feishu_doc_media`（action: download）工具单独获取！**
|
||||
|
||||
### 识别格式
|
||||
|
||||
返回的 Markdown 中，媒体文件以 HTML 标签形式出现：
|
||||
|
||||
- **图片**：
|
||||
```html
|
||||
<image token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc" width="1833" height="2491" align="center"/>
|
||||
```
|
||||
|
||||
- **文件**：
|
||||
```html
|
||||
<view type="1">
|
||||
<file token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc" name="skills.zip"/>
|
||||
</view>
|
||||
```
|
||||
|
||||
- **画板**：
|
||||
```html
|
||||
<whiteboard token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc"/>
|
||||
```
|
||||
|
||||
### 获取步骤
|
||||
|
||||
1. 从 HTML 标签中提取 `token` 属性值
|
||||
2. 调用 `feishu_doc_media` 下载：
|
||||
```json
|
||||
{
|
||||
"action": "download",
|
||||
"resource_token": "提取的token",
|
||||
"resource_type": "media",
|
||||
"output_path": "/path/to/save/file"
|
||||
}
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
- **`doc_id`**（必填）：支持直接传文档 URL 或 token
|
||||
- 直接传 URL：`https://xxx.feishu.cn/docx/Z1FjxxxxxxxxxxxxxxxxxxxtnAc`（系统自动提取 token）
|
||||
- 直接传 token：`Z1FjxxxxxxxxxxxxxxxxxxxtnAc`
|
||||
- 知识库 URL/token 也支持：`https://xxx.feishu.cn/wiki/Z1FjxxxxxxxxxxxxxxxxxxxtnAc` 或 `Z1FjxxxxxxxxxxxxxxxxxxxtnAc`
|
||||
|
||||
## Wiki URL 处理策略
|
||||
|
||||
知识库链接（`/wiki/TOKEN`）背后可能是云文档、电子表格、多维表格等不同类型的文档。当不确定类型时, **不能直接假设是云文档**，必须先查询实际类型。
|
||||
|
||||
### 处理流程
|
||||
|
||||
1. **先调用 `feishu_wiki_space_node`（action: get）解析 wiki token**：
|
||||
```json
|
||||
{ "action": "get", "token": "wiki_token_here" }
|
||||
```
|
||||
2. **从返回的 `node` 中获取 `obj_type`（实际文档类型）和 `obj_token`（实际文档 token）**
|
||||
3. **根据 `obj_type` 调用对应工具**：
|
||||
|
||||
| obj_type | 工具 | 传参 |
|
||||
|----------|------|------|
|
||||
| `docx` | `feishu_mcp_fetch_doc` | doc_id = obj_token |
|
||||
| `sheet` | `feishu_sheet` | spreadsheet_token = obj_token |
|
||||
| `bitable` | `feishu_bitable_*` 系列 | app_token = obj_token |
|
||||
| 其他 | 告知用户暂不支持该类型 | — |
|
||||
|
||||
|
||||
### 示例
|
||||
|
||||
用户：`帮我看下这个文档 https://xxx.feishu.cn/wiki/ABC123`
|
||||
|
||||
1. 调用 `feishu_wiki_space_node`（action: get, token: ABC123）
|
||||
2. 返回 `obj_type: "docx"`, `obj_token: "doxcnXYZ789"`
|
||||
3. 调用 `feishu_mcp_fetch_doc`（doc_id: doxcnXYZ789）
|
||||
|
||||
## 工具组合
|
||||
|
||||
| 需求 | 工具 |
|
||||
|------|------|
|
||||
| 获取文档文本 | `feishu_mcp_fetch_doc` |
|
||||
| 下载图片/文件/画板 | `feishu_doc_media`（action: download） |
|
||||
| 解析 wiki token 类型 | `feishu_wiki_space_node`（action: get） |
|
||||
| 读写电子表格 | `feishu_sheet` |
|
||||
| 操作多维表格 | `feishu_bitable_*` 系列 |
|
||||
@@ -0,0 +1,163 @@
|
||||
---
|
||||
name: feishu-im-read
|
||||
description: |
|
||||
飞书 IM 消息读取工具使用指南，覆盖会话消息获取、话题回复读取、跨会话消息搜索、图片/文件资源下载。
|
||||
|
||||
**当以下情况时使用此 Skill**:
|
||||
(1) 需要获取群聊或单聊的历史消息
|
||||
(2) 需要读取话题（thread）内的回复消息
|
||||
(3) 需要跨会话搜索消息（按关键词、发送者、时间等条件）
|
||||
(4) 消息中包含图片、文件、音频、视频，需要下载
|
||||
(5) 用户提到"聊天记录"、"消息"、"群里说了什么"、"话题回复"、"搜索消息"、"图片"、"文件下载"
|
||||
(6) 需要按时间范围过滤消息、分页获取更多消息
|
||||
---
|
||||
|
||||
# 飞书 IM 消息读取
|
||||
|
||||
## 执行前必读
|
||||
|
||||
- 该 Skill 中的所有消息读取工具均以用户身份调用，只能读取用户有权限的会话
|
||||
- `feishu_im_user_get_messages` 中 `open_id` 和 `chat_id` 必须二选一
|
||||
- 消息中出现 `thread_id` 时，根据用户意图判断是否用 `feishu_im_user_get_thread_messages` 读取话题内回复
|
||||
- 以用户身份读取后，如果消息内容中出现资源标记时，用 `feishu_im_user_fetch_resource` 下载，需要 `message_id` + `file_key` + `type`
|
||||
|
||||
---
|
||||
|
||||
## 快速索引：意图 → 工具
|
||||
|
||||
| 用户意图 | 工具 | 必填参数 | 常用可选 |
|
||||
|---------|------|---------|---------|
|
||||
| 获取群聊/单聊历史消息 | feishu_im_user_get_messages | chat_id 或 open_id（二选一） | relative_time, start_time/end_time, page_size, sort_rule |
|
||||
| 获取话题内回复消息 | feishu_im_user_get_thread_messages | thread_id（omt_xxx） | page_size, sort_rule |
|
||||
| 跨会话搜索消息 | feishu_im_user_search_messages | 至少一个过滤条件 | query, sender_ids, chat_id, relative_time, start_time/end_time, page_size |
|
||||
| 下载消息中的图片 | feishu_im_user_fetch_resource | message_id, file_key（img_xxx）, type="image" | - |
|
||||
| 下载消息中的文件/音频/视频 | feishu_im_user_fetch_resource | message_id, file_key（file_xxx）, type="file" | - |
|
||||
|
||||
---
|
||||
|
||||
## 核心约束
|
||||
|
||||
### 1. 时间范围：确保消息覆盖完整
|
||||
|
||||
当用户没有明确指定时间范围时，根据用户意图推断合适的 `relative_time`，确保返回的消息能完整覆盖用户关心的内容。用户明确指定时间时直接使用用户的值。
|
||||
|
||||
### 2. 分页：根据需要翻页获取更多结果
|
||||
|
||||
- `page_size` 范围 1-50，默认 50
|
||||
- 返回结果中 `has_more=true` 时，可使用 `page_token` 继续获取下一页
|
||||
- 根据用户需求判断是否需要翻页：需要完整结果时继续翻页，浏览概览时第一页通常够用
|
||||
|
||||
### 3. 话题回复：主动展开话题获取上下文
|
||||
|
||||
获取历史消息时，返回的消息中如果包含 `thread_id` 字段，推荐主动获取话题的最新 10 条回复（`page_size: 10, sort_rule: "create_time_desc"`）以提供更完整的上下文。
|
||||
|
||||
| 场景 | 行为 |
|
||||
|------|------|
|
||||
| 获取历史消息并需要理解上下文（默认） | 对发现的 thread_id 调用 `feishu_im_user_get_thread_messages` 获取最新 10 条回复 |
|
||||
| 用户要求"完整对话"、"详细讨论"、"看看回复" | 获取话题全部回复（`page_size: 50, sort_rule: "create_time_asc"`），需要时翻页 |
|
||||
| 用户只浏览消息概览 / 用户明确说不看回复 | 跳过话题展开 |
|
||||
|
||||
**注意**：话题消息不支持时间过滤（飞书 API 限制），只能通过分页获取。
|
||||
|
||||
### 4. 跨会话消息搜索
|
||||
|
||||
`feishu_im_user_search_messages` 支持跨所有会话搜索消息：
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `query` | 搜索关键词，匹配消息内容 |
|
||||
| `sender_ids` | 发送者 open_id 列表 |
|
||||
| `chat_id` | 限定搜索范围的会话 ID |
|
||||
| `mention_ids` | 被@用户的 open_id 列表 |
|
||||
| `message_type` | 消息类型：file / image / media |
|
||||
| `sender_type` | 发送者类型：user / bot / all（默认 user） |
|
||||
| `chat_type` | 会话类型：group / p2p |
|
||||
|
||||
搜索结果每条消息额外包含 `chat_id`、`chat_type`（p2p/group）、`chat_name`。单聊消息还有 `chat_partner`（对方 open_id 和名字）。
|
||||
|
||||
### 5. 图片/文件/媒体资源的提取
|
||||
|
||||
消息内容中可能出现以下资源标记，用 `feishu_im_user_fetch_resource` 下载：
|
||||
|
||||
| 资源类型 | 内容中的标记格式 | fetch_resource 参数 |
|
||||
|---------|-----------------|-------------------|
|
||||
| 图片 | `` | message_id=`om_xxx`, file_key=`img_xxx`, type=`"image"` |
|
||||
| 文件 | `<file key="file_xxx" .../>` | message_id=`om_xxx`, file_key=`file_xxx`, type=`"file"` |
|
||||
| 音频 | `<audio key="file_xxx" .../>` | message_id=`om_xxx`, file_key=`file_xxx`, type=`"file"` |
|
||||
| 视频 | `<video key="file_xxx" .../>` | message_id=`om_xxx`, file_key=`file_xxx`, type=`"file"` |
|
||||
|
||||
从消息的 `message_id` 字段和内容中的 `file_key` 组合即可调用 fetch_resource。
|
||||
|
||||
**注意**：文件大小限制 100MB，不支持下载表情包、卡片中的资源。
|
||||
|
||||
### 6. 时间过滤
|
||||
|
||||
`feishu_im_user_get_messages` 和 `feishu_im_user_search_messages` 支持时间过滤，话题消息不支持。
|
||||
|
||||
| 方式 | 参数 | 示例 |
|
||||
|------|------|------|
|
||||
| 相对时间 | `relative_time` | `today`、`yesterday`、`this_week`、`last_3_days`、`last_24_hours` |
|
||||
| 精确时间 | `start_time` + `end_time` | ISO 8601 格式：`2026-02-27T00:00:00+08:00` |
|
||||
|
||||
- `relative_time` 和 `start_time/end_time` **互斥**，不能同时使用
|
||||
- 可用的 relative_time 值：`today`、`yesterday`、`day_before_yesterday`、`this_week`、`last_week`、`this_month`、`last_month`、`last_{N}_{unit}`（unit: minutes/hours/days）
|
||||
|
||||
### 7. open_id 与 chat_id 的选择
|
||||
|
||||
| 参数 | 格式 | 适用场景 |
|
||||
|------|------|---------|
|
||||
| chat_id | `oc_xxx` | 已知会话 ID（群聊或单聊均可） |
|
||||
| open_id | `ou_xxx` | 已知用户 ID，获取与该用户的单聊消息（自动解析为 chat_id） |
|
||||
|
||||
两者必须二选一，优先使用 `chat_id`。
|
||||
|
||||
---
|
||||
|
||||
## 使用场景示例
|
||||
|
||||
### 场景 1: 获取群聊消息并展开话题
|
||||
|
||||
**步骤 1**：获取群聊消息
|
||||
```json
|
||||
{ "chat_id": "oc_xxx" }
|
||||
```
|
||||
|
||||
**步骤 2**：返回的消息中发现 `thread_id`，展开话题最新回复：
|
||||
```json
|
||||
{ "thread_id": "omt_xxx", "page_size": 10, "sort_rule": "create_time_desc" }
|
||||
```
|
||||
|
||||
### 场景 2: 跨会话搜索消息
|
||||
|
||||
```json
|
||||
{ "query": "项目进度", "chat_id": "oc_xxx" }
|
||||
```
|
||||
|
||||
### 场景 3: 分页获取更多消息
|
||||
|
||||
第一次调用返回 `has_more: true` 和 `page_token: "xxx"`，继续获取：
|
||||
```json
|
||||
{ "chat_id": "oc_xxx", "page_token": "xxx" }
|
||||
```
|
||||
|
||||
### 场景 4: 下载消息中的资源
|
||||
|
||||
```json
|
||||
{ "message_id": "om_xxx", "file_key": "img_v3_xxx", "type": "image" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见错误与排查
|
||||
|
||||
| 错误现象 | 根本原因 | 解决方案 |
|
||||
|---------|---------|---------|
|
||||
| 消息结果太少 | 时间范围太窄或未传时间参数 | 根据用户意图推断合适的 `relative_time` |
|
||||
| 消息不完整 | 没有检查 has_more 并翻页 | has_more=true 时用 page_token 翻页 |
|
||||
| 话题讨论内容不完整 | 没有展开 thread_id | 发现 thread_id 时获取话题回复 |
|
||||
| "open_id 和 chat_id 不能同时提供" | 同时传了两个参数 | 只传其中一个 |
|
||||
| "relative_time 和 start_time/end_time 不能同时使用" | 时间参数冲突 | 选择一种时间过滤方式 |
|
||||
| "未找到与 open_id=xxx 的单聊会话" | 没有单聊记录 | 改用 chat_id，或确认存在单聊 |
|
||||
| 话题消息返回为空 | thread_id 格式不正确 | 确认为 `omt_xxx` 格式 |
|
||||
| 图片/文件下载失败 | file_key 或 message_id 不匹配 | 确认 file_key 来自该 message_id |
|
||||
| 权限不足 | 用户未授权或无权限 | 确认已完成 OAuth 授权且是会话成员 |
|
||||
@@ -0,0 +1,293 @@
|
||||
---
|
||||
name: feishu-task
|
||||
description: |
|
||||
飞书任务管理工具,用于创建、查询、更新任务和清单。
|
||||
|
||||
**当以下情况时使用此 Skill**:
|
||||
(1) 需要创建、查询、更新、删除任务
|
||||
(2) 需要创建、管理任务清单
|
||||
(3) 需要查看任务列表或清单内的任务
|
||||
(4) 用户提到"任务"、"待办"、"to-do"、"清单"、"task"
|
||||
(5) 需要设置任务负责人、关注人、截止时间
|
||||
---
|
||||
|
||||
# 飞书任务管理
|
||||
|
||||
## 🚨 执行前必读
|
||||
|
||||
- ✅ **时间格式**：ISO 8601 / RFC 3339（带时区），例如 `2026-02-28T17:00:00+08:00`
|
||||
- ✅ **current_user_id 强烈建议**：从消息上下文的 SenderId 获取（ou_...），工具会自动添加为 follower（如不在 members 中），确保创建者可以编辑任务
|
||||
- ✅ **patch/get 必须**：task_guid
|
||||
- ✅ **tasklist.tasks 必须**：tasklist_guid
|
||||
- ✅ **完成任务**：completed_at = "2026-02-26 15:00:00"
|
||||
- ✅ **反完成（恢复未完成）**：completed_at = "0"
|
||||
|
||||
---
|
||||
|
||||
## 📋 快速索引：意图 → 工具 → 必填参数
|
||||
|
||||
| 用户意图 | 工具 | action | 必填参数 | 强烈建议 | 常用可选 |
|
||||
|---------|------|--------|---------|---------|---------|
|
||||
| 新建待办 | feishu_task_task | create | summary | current_user_id（SenderId） | members, due, description |
|
||||
| 查未完成任务 | feishu_task_task | list | - | completed=false | page_size |
|
||||
| 获取任务详情 | feishu_task_task | get | task_guid | - | - |
|
||||
| 完成任务 | feishu_task_task | patch | task_guid, completed_at | - | - |
|
||||
| 反完成任务 | feishu_task_task | patch | task_guid, completed_at="0" | - | - |
|
||||
| 改截止时间 | feishu_task_task | patch | task_guid, due | - | - |
|
||||
| 创建清单 | feishu_task_tasklist | create | name | - | members |
|
||||
| 查看清单任务 | feishu_task_tasklist | tasks | tasklist_guid | - | completed |
|
||||
| 添加清单成员 | feishu_task_tasklist | add_members | tasklist_guid, members[] | - | - |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 核心约束（Schema 未透露的知识）
|
||||
|
||||
### 1. 当前工具使用用户身份（已内置保护）
|
||||
|
||||
**工具使用 `user_access_token`（用户身份）**
|
||||
|
||||
这意味着：
|
||||
- ✅ 创建任务时可以指定任意成员（包括只分配给别人）
|
||||
- ⚠️ 只能查看和编辑**自己是成员的任务**
|
||||
- ⚠️ **如果创建时没把自己加入成员，后续无法编辑该任务**
|
||||
|
||||
**自动保护机制**：
|
||||
- 传入 `current_user_id` 参数（从 SenderId 获取）
|
||||
- 如果 `members` 中不包含 `current_user_id`，工具会**自动添加为 follower**
|
||||
- 确保创建者始终可以编辑任务
|
||||
|
||||
**推荐用法**：创建任务时始终传 `current_user_id`，工具会自动处理成员关系。
|
||||
|
||||
### 2. 任务成员的角色说明
|
||||
|
||||
- **assignee（负责人）**：负责完成任务，可以编辑任务
|
||||
- **follower（关注人）**：关注任务进展，接收通知
|
||||
|
||||
**添加成员示例**：
|
||||
```json
|
||||
{
|
||||
"members": [
|
||||
{"id": "ou_xxx", "role": "assignee"}, // 负责人
|
||||
{"id": "ou_yyy", "role": "follower"} // 关注人
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**说明**：`id` 使用用户的 `open_id`（从消息上下文的 SenderId 获取）
|
||||
|
||||
### 3. 任务清单角色冲突
|
||||
|
||||
**现象**：创建清单（`tasklist.create`）时传了 `members`，但返回的 `tasklist.members` 为空或缺少成员
|
||||
|
||||
**原因**：创建人自动成为清单 **owner**（所有者），如果 `members` 中包含创建人，该用户最终成为 owner 并从 `members` 中移除（同一用户只能有一个角色）
|
||||
|
||||
**建议**：不要在 `members` 中包含创建人，只添加其他协作成员
|
||||
|
||||
### 4. completed_at 的三种用法
|
||||
|
||||
**1) 完成任务（设置完成时间）**：
|
||||
```json
|
||||
{
|
||||
"action": "patch",
|
||||
"task_guid": "xxx",
|
||||
"completed_at": "2026-02-26 15:30:00" // 北京时间字符串
|
||||
}
|
||||
```
|
||||
|
||||
**2) 反完成（恢复未完成状态）**：
|
||||
```json
|
||||
{
|
||||
"action": "patch",
|
||||
"task_guid": "xxx",
|
||||
"completed_at": "0" // 特殊值 "0" 表示反完成
|
||||
}
|
||||
```
|
||||
|
||||
**3) 毫秒时间戳**（不推荐，除非上层已严格生成）：
|
||||
```json
|
||||
{
|
||||
"completed_at": "1740545400000" // 毫秒时间戳字符串
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 清单成员的角色
|
||||
|
||||
| 成员类型 | 角色 | 说明 |
|
||||
|---------|------|------|
|
||||
| user（用户） | owner | 所有者，可转让所有权 |
|
||||
| user（用户） | editor | 可编辑，可修改清单和任务 |
|
||||
| user（用户） | viewer | 可查看，只读权限 |
|
||||
| chat（群组） | editor/viewer | 整个群组获得权限 |
|
||||
|
||||
**说明**：创建清单时，创建者自动成为 owner，无需在 members 中指定。
|
||||
|
||||
---
|
||||
|
||||
## 📌 使用场景示例
|
||||
|
||||
### 场景 1: 创建任务并分配负责人
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"summary": "准备周会材料",
|
||||
"description": "整理本周工作进展和下周计划",
|
||||
"current_user_id": "ou_发送者的open_id",
|
||||
"due": {
|
||||
"timestamp": "2026-02-28 17:00:00",
|
||||
"is_all_day": false
|
||||
},
|
||||
"members": [
|
||||
{"id": "ou_协作者的open_id", "role": "assignee"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**说明**：
|
||||
- `summary` 是必填字段
|
||||
- `current_user_id` 强烈建议传入（从 SenderId 获取），工具会自动添加为 follower
|
||||
- `members` 可以只包含其他协作者，当前用户会被自动添加
|
||||
- 时间使用北京时间字符串格式
|
||||
|
||||
### 场景 2: 查询我负责的未完成任务
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "list",
|
||||
"completed": false,
|
||||
"page_size": 20
|
||||
}
|
||||
```
|
||||
|
||||
### 场景 3: 完成任务
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "patch",
|
||||
"task_guid": "任务的guid",
|
||||
"completed_at": "2026-02-26 15:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 场景 4: 反完成任务（恢复未完成状态）
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "patch",
|
||||
"task_guid": "任务的guid",
|
||||
"completed_at": "0"
|
||||
}
|
||||
```
|
||||
|
||||
### 场景 5: 创建清单并添加协作者
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"name": "产品迭代 v2.0",
|
||||
"members": [
|
||||
{"id": "ou_xxx", "role": "editor"},
|
||||
{"id": "ou_yyy", "role": "viewer"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 场景 6: 查看清单内的未完成任务
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "tasks",
|
||||
"tasklist_guid": "清单的guid",
|
||||
"completed": false
|
||||
}
|
||||
```
|
||||
|
||||
### 场景 7: 全天任务
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"summary": "年度总结",
|
||||
"due": {
|
||||
"timestamp": "2026-03-01 00:00:00",
|
||||
"is_all_day": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 常见错误与排查
|
||||
|
||||
| 错误现象 | 根本原因 | 解决方案 |
|
||||
|---------|---------|---------|
|
||||
| **创建后无法编辑任务** | 创建时未将自己加入 members | 创建时至少将当前用户（SenderId）加为 assignee 或 follower |
|
||||
| **patch 失败提示 task_guid 缺失** | 未传 task_guid 参数 | patch/get 必须传 task_guid |
|
||||
| **tasks 失败提示 tasklist_guid 缺失** | 未传 tasklist_guid 参数 | tasklist.tasks action 必须传 tasklist_guid |
|
||||
| **反完成失败** | completed_at 格式错误 | 使用 `"0"` 字符串，不是数字 0 |
|
||||
| **时间不对** | 使用了 Unix 时间戳 | 改用 ISO 8601 格式（带时区）：`2024-01-01T00:00:00+08:00` |
|
||||
|
||||
---
|
||||
|
||||
## 📚 附录：背景知识
|
||||
|
||||
### A. 资源关系
|
||||
|
||||
```
|
||||
任务清单（Tasklist）
|
||||
└─ 自定义分组（Section，可选）
|
||||
└─ 任务（Task）
|
||||
├─ 成员：负责人（assignee）、关注人（follower）
|
||||
├─ 子任务（Subtask）
|
||||
├─ 截止时间（due）、开始时间（start）
|
||||
└─ 附件、评论
|
||||
```
|
||||
|
||||
**核心概念**：
|
||||
- **任务（Task）**：独立的待办事项，有唯一的 `task_guid`
|
||||
- **清单（Tasklist）**：组织多个任务的容器，有唯一的 `tasklist_guid`
|
||||
- **负责人（assignee）**：可以编辑任务并标记完成
|
||||
- **关注人（follower）**：接收任务更新通知
|
||||
- **我负责的（MyTasks）**：所有负责人为自己的任务集合
|
||||
|
||||
### B. 如何获取 GUID
|
||||
|
||||
- **task_guid**：创建任务后从返回值的 `task.guid` 获取，或通过 `list` 查询
|
||||
- **tasklist_guid**：创建清单后从返回值的 `tasklist.guid` 获取，或通过 `list` 查询
|
||||
|
||||
### C. 如何将任务加入清单
|
||||
|
||||
创建任务时指定 `tasklists` 参数：
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"summary": "任务标题",
|
||||
"tasklists": [
|
||||
{
|
||||
"tasklist_guid": "清单的guid",
|
||||
"section_guid": "分组的guid（可选）"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### D. 重复任务如何创建
|
||||
|
||||
使用 `repeat_rule` 参数，采用 RRULE 格式：
|
||||
```json
|
||||
{
|
||||
"action": "create",
|
||||
"summary": "每周例会",
|
||||
"due": {"timestamp": "2026-03-03 14:00:00", "is_all_day": false},
|
||||
"repeat_rule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO"
|
||||
}
|
||||
```
|
||||
|
||||
**说明**：只有设置了截止时间的任务才能设置重复规则。
|
||||
|
||||
|
||||
### E. 数据权限
|
||||
|
||||
- 只能操作自己有权限的任务（作为成员的任务）
|
||||
- 只能操作自己有权限的清单（作为成员的清单）
|
||||
- 将任务加入清单需要同时拥有任务和清单的编辑权限
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
name: feishu-troubleshoot
|
||||
description: |
|
||||
飞书插件问题排查工具。包含常见问题 FAQ 和深度诊断命令（/feishu_doctor）。
|
||||
|
||||
常见问题可随时查阅。诊断命令用于排查复杂问题（多次授权仍失败、自动授权无法解决等），
|
||||
会检查账户配置、API 连通性、应用权限、用户授权状态，并生成详细的诊断报告和解决方案。
|
||||
|
||||
---
|
||||
|
||||
# 飞书插件问题排查
|
||||
|
||||
## ❓ 常见问题（FAQ）
|
||||
|
||||
### 卡片按钮点击无反应
|
||||
|
||||
**现象**：点击卡片按钮后没有任何反应，然后提示报错.
|
||||
|
||||
**原因**：应用未开通「消息卡片回传交互」权限。
|
||||
|
||||
**解决步骤**：
|
||||
|
||||
1. 登录飞书开放平台：https://open.feishu.cn/app
|
||||
2. 选择您的应用 → **事件与回调**
|
||||
3. 在回调配置中,修改订阅方式为"长链接"并添加回调 "卡片回传交互"(card.action.trigger)
|
||||
4. 创建应用版本 → 提交审核 → 发布
|
||||
|
||||
---
|
||||
|
||||
## 🔍 诊断命令（深度工具）
|
||||
|
||||
**注意**：诊断命令仅用于排查复杂/疑难的**权限相关问题**。常规权限问题会自动触发授权流程，无需手动诊断。
|
||||
|
||||
**何时使用诊断**：
|
||||
- 多次授权后仍然报错
|
||||
- 自动授权流程无法解决的问题
|
||||
- 需要查看完整的权限配置状态
|
||||
|
||||
**使用方法**：
|
||||
|
||||
在飞书聊天会话中直接输入（作为用户消息发送）：
|
||||
|
||||
/feishu doctor
|
||||
|
||||
诊断命令会检查：
|
||||
|
||||
- **📋 诊断摘要**（首先展示）：
|
||||
- 总体状态（✅ 正常 / ⚠️ 警告 / ❌ 失败）
|
||||
- 发现的问题列表和简要描述
|
||||
|
||||
- **环境信息**：
|
||||
- 插件版本
|
||||
|
||||
- **账号信息**：
|
||||
- 凭证完整性（appId, appSecret 掩码）
|
||||
- 账户启用状态
|
||||
- API 连通性测试
|
||||
- Bot 信息（名称和 openId）
|
||||
|
||||
- **应用身份权限**：
|
||||
- 应用已开通的必需权限数量
|
||||
- 缺失的必需权限列表
|
||||
- 一键申请链接（自动带上缺失权限参数）
|
||||
|
||||
- **用户身份权限**：
|
||||
- 用户授权状态统计（✓ 有效 / ⟳ 需刷新 / ✗ 已过期）
|
||||
- Token 自动刷新状态（是否包含 offline_access）
|
||||
- 权限对照表（应用已开通 vs 用户已授权，逐项对比）
|
||||
- 应用权限缺失时的申请指引和链接
|
||||
- 用户授权不足时的重新授权操作方法
|
||||
@@ -0,0 +1,285 @@
|
||||
---
|
||||
name: feishu-update-doc
|
||||
description: |
|
||||
更新飞书云文档。支持 7 种更新模式：追加、覆盖、定位替换、全文替换、前/后插入、删除。
|
||||
---
|
||||
|
||||
# feishu__update_doc
|
||||
|
||||
更新飞书云文档内容，支持 7 种更新模式。优先使用局部更新（replace_range/append/insert_before/insert_after），慎用 overwrite（会清空文档重写，可能丢失图片、评论等）。
|
||||
|
||||
# 定位方式
|
||||
|
||||
定位模式（replace_range/replace_all/insert_before/insert_after/delete_range）支持两种定位方式，二选一：
|
||||
|
||||
## selection_with_ellipsis - 内容定位
|
||||
|
||||
支持两种格式：
|
||||
|
||||
1. **范围匹配**：`开头内容...结尾内容`
|
||||
- 匹配从开头到结尾的所有内容（包含中间内容）
|
||||
- 建议 10-20 字符确保唯一性
|
||||
|
||||
2. **精确匹配**：`完整内容`（不含 `...`）
|
||||
- 匹配完整的文本内容
|
||||
- 适合替换短文本、关键词等
|
||||
|
||||
**转义说明**：如果要匹配的内容本身包含 `...`，使用 `\.\.\.` 表示字面量的三个点。
|
||||
|
||||
示例：
|
||||
- `你好...世界` → 匹配从"你好"到"世界"之间的任意内容
|
||||
- `你好\.\.\.世界` → 匹配字面量 "你好...世界"
|
||||
|
||||
**建议**：如果文档中有多个 `...`，建议使用更长的上下文来精确定位，避免歧义。
|
||||
|
||||
## selection_by_title - 标题定位
|
||||
|
||||
格式：`## 章节标题`（可带或不带 # 前缀）
|
||||
|
||||
自动定位整个章节（从该标题到下一个同级或更高级标题之前）。
|
||||
|
||||
**示例**：
|
||||
- `## 功能说明` → 定位二级标题"功能说明"及其下所有内容
|
||||
- `功能说明` → 定位任意级别的"功能说明"标题及其内容
|
||||
|
||||
# 可选参数
|
||||
|
||||
## new_title
|
||||
|
||||
更新文档标题。如果提供此参数，将在更新文档内容后同步更新文档标题。
|
||||
|
||||
**特性**：
|
||||
- 仅支持纯文本，不支持富文本格式
|
||||
- 长度限制：1-800 字符
|
||||
- 可以与任何 mode 配合使用
|
||||
- 标题更新在内容更新之后执行
|
||||
|
||||
|
||||
# 返回值
|
||||
|
||||
## 成功
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"doc_id": "文档ID",
|
||||
"mode": "使用的模式",
|
||||
"message": "文档更新成功（xxx模式）",
|
||||
"warnings": ["可选警告列表"],
|
||||
"log_id": "请求日志ID"
|
||||
}
|
||||
```
|
||||
|
||||
## 异步模式（大文档超时）
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "async_task_xxxx",
|
||||
"message": "文档更新已提交异步处理，请使用 task_id 查询状态",
|
||||
"log_id": "请求日志ID"
|
||||
}
|
||||
```
|
||||
|
||||
使用返回的 `task_id` 再次调用 update-doc（仅传 task_id 参数）查询状态。
|
||||
|
||||
## 错误
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "[错误码] 错误消息\n💡 Suggestion: 修复建议\n📍 Context: 上下文信息",
|
||||
"log_id": "请求日志ID"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 使用示例
|
||||
|
||||
## append - 追加到末尾
|
||||
|
||||
```json
|
||||
{
|
||||
"doc_id": "文档ID或URL",
|
||||
"mode": "append",
|
||||
"markdown": "## 新章节\n\n追加的内容..."
|
||||
}
|
||||
```
|
||||
|
||||
## replace_range - 定位替换
|
||||
|
||||
使用 `selection_with_ellipsis`：
|
||||
```json
|
||||
{
|
||||
"doc_id": "文档ID或URL",
|
||||
"mode": "replace_range",
|
||||
"selection_with_ellipsis": "## 旧章节标题...旧章节结尾。",
|
||||
"markdown": "## 新章节标题\n\n新的内容..."
|
||||
}
|
||||
```
|
||||
|
||||
使用 `selection_by_title`（替换整个章节）：
|
||||
```json
|
||||
{
|
||||
"doc_id": "文档ID或URL",
|
||||
"mode": "replace_range",
|
||||
"selection_by_title": "## 功能说明",
|
||||
"markdown": "## 功能说明\n\n更新后的功能说明内容..."
|
||||
}
|
||||
```
|
||||
|
||||
## replace_all - 全文替换
|
||||
|
||||
与 replace_range 类似，但支持多处同时替换（replace_range 要求匹配唯一）：
|
||||
```json
|
||||
{
|
||||
"doc_id": "文档ID或URL",
|
||||
"mode": "replace_all",
|
||||
"selection_with_ellipsis": "张三",
|
||||
"markdown": "李四"
|
||||
}
|
||||
```
|
||||
|
||||
**返回值**包含 `replace_count` 字段，表示替换的次数：
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"replace_count": 4,
|
||||
"message": "文档更新成功（replace_all模式，替换4处）"
|
||||
}
|
||||
```
|
||||
|
||||
**注意**：
|
||||
- 与 `replace_range` 不同，`replace_all` 允许多个匹配
|
||||
- 如果没有找到匹配内容，会返回错误
|
||||
- `markdown` 可以为空字符串，表示删除所有匹配内容
|
||||
|
||||
## insert_before - 前插入
|
||||
|
||||
```json
|
||||
{
|
||||
"doc_id": "文档ID或URL",
|
||||
"mode": "insert_before",
|
||||
"selection_with_ellipsis": "## 危险操作...数据丢失风险。",
|
||||
"markdown": "> **警告**：以下操作需谨慎！"
|
||||
}
|
||||
```
|
||||
|
||||
## insert_after - 后插入
|
||||
|
||||
```json
|
||||
{
|
||||
"doc_id": "文档ID或URL",
|
||||
"mode": "insert_after",
|
||||
"selection_with_ellipsis": "```python...```",
|
||||
"markdown": "**输出示例**：\n```\nresult = 42\n```"
|
||||
}
|
||||
```
|
||||
|
||||
## delete_range - 删除内容
|
||||
|
||||
使用 `selection_with_ellipsis`：
|
||||
```json
|
||||
{
|
||||
"doc_id": "文档ID或URL",
|
||||
"mode": "delete_range",
|
||||
"selection_with_ellipsis": "## 废弃章节...不再需要的内容。"
|
||||
}
|
||||
```
|
||||
|
||||
使用 `selection_by_title`（删除整个章节）：
|
||||
```json
|
||||
{
|
||||
"doc_id": "文档ID或URL",
|
||||
"mode": "delete_range",
|
||||
"selection_by_title": "## 废弃章节"
|
||||
}
|
||||
```
|
||||
|
||||
注意：delete_range 模式不需要 markdown 参数。
|
||||
|
||||
## 同时更新标题和内容
|
||||
|
||||
可以在任何更新模式中添加 `new_title` 参数来同时更新文档标题：
|
||||
|
||||
```json
|
||||
{
|
||||
"doc_id": "文档ID或URL",
|
||||
"mode": "overwrite",
|
||||
"markdown": "# 项目文档 v2.0\n\n全新的内容...",
|
||||
"new_title": "项目文档 v2.0"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"doc_id": "文档ID或URL",
|
||||
"mode": "append",
|
||||
"markdown": "## 更新日志\n\n2025-12-18: 新增功能...",
|
||||
"new_title": "项目文档（已更新）"
|
||||
}
|
||||
```
|
||||
|
||||
## overwrite - 完全覆盖
|
||||
|
||||
⚠️ 会清空文档后重写，可能丢失图片、评论等，仅在需要完全重建文档时使用。
|
||||
|
||||
```json
|
||||
{
|
||||
"doc_id": "文档ID或URL",
|
||||
"mode": "overwrite",
|
||||
"markdown": "# 新文档\n\n全新的内容..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 最佳实践
|
||||
|
||||
## 小粒度精确替换
|
||||
|
||||
修改文档内容时，**定位范围越小越安全**。尤其是表格、分栏等嵌套块，应精确定位到需要修改的文本，避免影响其他内容。
|
||||
|
||||
**示例**：表格单元格中有图片和文字，只需修改文字
|
||||
- ❌ 替换整个表格或整行 → 可能破坏图片引用
|
||||
- ✅ 只定位需要修改的文本 → 图片等其他内容不受影响
|
||||
|
||||
|
||||
## 保护不可重建的内容
|
||||
|
||||
图片、画板、电子表格、多维表格、任务等内容以 token 形式存储，**无法读出后原样写入**。
|
||||
|
||||
**保护策略**：
|
||||
- 替换时避开包含这些内容的区域
|
||||
- 精确定位到纯文本部分进行修改
|
||||
|
||||
## 分步更新优于整体覆盖
|
||||
|
||||
修改多处内容时：
|
||||
- ✅ 多次小范围替换，逐步修改
|
||||
- ⚠️ 谨慎使用 `overwrite` 重写整个文档, 除非你认为风险完全可控
|
||||
|
||||
**原因**：局部更新保留原有媒体、评论、协作历史，更安全可靠。
|
||||
|
||||
## insert 模式扩大定位范围时注意插入位置
|
||||
|
||||
使用 `insert_before` 或 `insert_after` 时，如果目标内容重复出现，需要扩大 `selection_with_ellipsis` 范围来唯一定位。
|
||||
|
||||
**关键**：插入位置基于匹配范围的**边界**：
|
||||
- `insert_after` → 插入在匹配范围的**结尾**之后
|
||||
- `insert_before` → 插入在匹配范围的**开头**之前
|
||||
|
||||
扩大范围时，确保边界仍然是期望的插入点。
|
||||
|
||||
## 修复画板语法错误
|
||||
|
||||
当 create-doc 或 update-doc 返回画板写入失败的 warning 时：
|
||||
1. warning 中包含 whiteboard 标签（如 `<whiteboard token="xxx"/>`）
|
||||
2. 分析错误信息，修正 Mermaid/PlantUML 语法
|
||||
3. 用 `replace_range` 替换：`selection_with_ellipsis` 使用 warning 中的 whiteboard 标签，`markdown` 提供修正后的代码块
|
||||
4. 重新提交验证
|
||||
|
||||
---
|
||||
|
||||
# 注意事项
|
||||
|
||||
- **Markdown 语法**：支持飞书扩展语法，详见 create-doc 工具文档
|
||||
Reference in New Issue
Block a user