{"id":"a971b433-a79a-4523-94b9-f4e921b1911c","entityType":"agent","slug":"clawhub-a3152557994-ship-it-feishu-bitable-suite","name":"飞书Bitable管理工具","canonicalUrl":"https://www.xpersona.co/agent/clawhub-a3152557994-ship-it-feishu-bitable-suite","canonicalPath":"/agent/clawhub-a3152557994-ship-it-feishu-bitable-suite","generatedAt":"2026-10-12T17:34:36.601Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-12T01:51:19.454Z","emptyReason":null},"description":"飞书多维表格（Bitable）的创建、查询、编辑和管理工具。包含 27 种字段类型支持、高级筛选、批量操作和视图管理。 **当以下情况时使用此 Skill**： (1) 需要创建或管理飞书多维表格 App (2) 需要在多维表格中新增、查询、修改、删除记录（行数据） (3) 需要管理字段（列）、视图、数据表 (4... Skill: 飞书Bitable管理工具 Owner: a3152557994-ship-it Summary: 飞书多维表格（Bitable）的创建、查询、编辑和管理工具。包含 27 种字段类型支持、高级筛选、批量操作和视图管理。 **当以下情况时使用此 Skill**： (1) 需要创建或管理飞书多维表格 App (2) 需要在多维表格中新增、查询、修改、删除记录（行数据） (3) 需要管理字段（列）、视图、数据表 (4... Tags: latest:1.0.0 Version history: v1.0.0 | 2026-04-24T06:33:44.892Z | auto - 首发版本，支持飞书多维表格（Bitable）全功能操作 - 实现 27 种字段类型的表结构管理、查询和批量数据操作 - 提供详细字段格式、数据导入、筛选、并发、批量等最佳实践说明 - 补充常见错误码及排查，详解字段类型、导入格式和极易踩坑点 -","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 959 downloads reported by the source. Last updated 10/12/2026.","installCommand":"clawhub skill install s173ar224xha1b0e8jxxvg0r2985aes9:feishu-bitable-suite","sourceUrl":"https://clawhub.ai/a3152557994-ship-it/feishu-bitable-suite","homepage":"https://clawhub.ai/a3152557994-ship-it/skills/feishu-bitable-suite","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/a3152557994-ship-it/feishu-bitable-suite","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/a3152557994-ship-it/skills/feishu-bitable-suite","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"飞书多维表格（Bitable）的创建、查询、编辑和管理工具。包含 27 种字段类型支持、高级筛选、批量操作和视图管理。 **当以下情况时使用此 Skill**： (1) 需要创建或管理飞书多维表格 App (2) 需要在多维表格中新增、查询、修改、删除记录（行数据） (3) 需要管理字段（列）、视图、数据表 (4..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-12T01:51:19.454Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T01:51:19.454Z","emptyReason":null},"stars":null,"forks":null,"downloads":959,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.0.0","tractionLabel":"959 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T01:51:19.447Z","emptyReason":null},"lastUpdatedAt":"2026-10-12T01:51:19.454Z","lastCrawledAt":"2026-10-12T01:51:19.447Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-13T01:51:19.447Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.0","createdAt":"2026-04-24T06:33:44.892Z","changelog":"- 首发版本，支持飞书多维表格（Bitable）全功能操作 - 实现 27 种字段类型的表结构管理、查询和批量数据操作 - 提供详细字段格式、数据导入、筛选、并发、批量等最佳实践说明 - 补充常见错误码及排查，详解字段类型、导入格式和极易踩坑点 - 附带完整索引、使用样例和限制说明，便于快速上手","fileCount":6,"zipByteSize":21537}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s173ar224xha1b0e8jxxvg0r2985aes9:feishu-bitable-suite","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-a3152557994-ship-it-feishu-bitable-suite/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-a3152557994-ship-it-feishu-bitable-suite/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-a3152557994-ship-it-feishu-bitable-suite/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-a3152557994-ship-it-feishu-bitable-suite/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-a3152557994-ship-it-feishu-bitable-suite/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-a3152557994-ship-it-feishu-bitable-suite/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T17:34:36.600Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-a3152557994-ship-it-feishu-bitable-suite/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-a3152557994-ship-it-feishu-bitable-suite/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-a3152557994-ship-it-feishu-bitable-suite/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-a3152557994-ship-it-feishu-bitable-suite/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-12T01:51:19.454Z","emptyReason":null},"readme":"Skill: 飞书Bitable管理工具\n\nOwner: a3152557994-ship-it\n\nSummary: 飞书多维表格（Bitable）的创建、查询、编辑和管理工具。包含 27 种字段类型支持、高级筛选、批量操作和视图管理。 **当以下情况时使用此 Skill**： (1) 需要创建或管理飞书多维表格 App (2) 需要在多维表格中新增、查询、修改、删除记录（行数据） (3) 需要管理字段（列）、视图、数据表 (4...\n\nTags: latest:1.0.0\n\nVersion history:\n\nv1.0.0 | 2026-04-24T06:33:44.892Z | auto\n\n- 首发版本，支持飞书多维表格（Bitable）全功能操作\n- 实现 27 种字段类型的表结构管理、查询和批量数据操作\n- 提供详细字段格式、数据导入、筛选、并发、批量等最佳实践说明\n- 补充常见错误码及排查，详解字段类型、导入格式和极易踩坑点\n- 附带完整索引、使用样例和限制说明，便于快速上手\n\nArchive index:\n\nArchive v1.0.0: 6 files, 21537 bytes\n\nFiles: references/examples.md (16893b), references/field-properties.md (14464b), references/record-values.md (15687b), skill-card.md (2824b), SKILL.md (10336b), _meta.json (139b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: feishu-bitable\ndescription: |\n  飞书多维表格（Bitable）的创建、查询、编辑和管理工具。包含 27 种字段类型支持、高级筛选、批量操作和视图管理。\n\n  **当以下情况时使用此 Skill**：\n  (1) 需要创建或管理飞书多维表格 App\n  (2) 需要在多维表格中新增、查询、修改、删除记录（行数据）\n  (3) 需要管理字段（列）、视图、数据表\n  (4) 用户提到\"多维表格\"、\"bitable\"、\"数据表\"、\"记录\"、\"字段\"\n  (5) 需要批量导入数据或批量更新多维表格\n---\n\n# Feishu Bitable (多维表格) SKILL\n\n## 🚨 执行前必读\n\n- ✅ **创建数据表**：支持两种模式 — ① 明确需求时，在 `create` 时通过 `table.fields` 一次性定义字段（减少 API 调用）；② 探索式场景时，使用默认表 + 逐步修改字段（更稳定，易调整）\n- ⚠️ **默认表的空行坑**：`app.create` 自带的默认表中会有空记录（空行）！插入数据前建议先调用 `feishu_bitable_app_table_record.list` + `batch_delete` 删除空行，避免数据污染\n- ✅ **写记录前**：先调用 `feishu_bitable_app_table_field.list` 获取字段 type/ui_type\n- ✅ **人员字段**：默认 open_id（ou_...），值必须是 `[{id:\"ou_xxx\"}]`（数组对象）\n- ✅ **日期字段**：毫秒时间戳（例如 `1674206443000`），不是秒\n- ✅ **单选字段**：字符串（例如 `\"选项1\"`），不是数组\n- ✅ **多选字段**：字符串数组（例如 `[\"选项1\", \"选项2\"]`）\n- ✅ **附件字段**：必须先上传到当前多维表格，使用返回的 file_token\n- ✅ **批量上限**：单次 ≤ 500 条，超过需分批（批量操作是原子性的）\n- ✅ **并发限制**：同一数据表不支持并发写，需串行调用 + 延迟 0.5-1 秒\n\n---\n\n## 📋 快速索引：意图 → 工具 → 必填参数\n\n| 用户意图 | 工具 | action | 必填参数 | 常用可选 |\n|---------|------|--------|---------|---------|\n| 查表有哪些字段 | feishu_bitable_app_table_field | list | app_token, table_id | - |\n| 查记录 | feishu_bitable_app_table_record | list | app_token, table_id | filter, sort, field_names |\n| 新增一行 | feishu_bitable_app_table_record | create | app_token, table_id, fields | - |\n| 批量导入 | feishu_bitable_app_table_record | batch_create | app_token, table_id, records (≤500) | - |\n| 更新一行 | feishu_bitable_app_table_record | update | app_token, table_id, record_id, fields | - |\n| 批量更新 | feishu_bitable_app_table_record | batch_update | app_token, table_id, records (≤500) | - |\n| 创建多维表格 | feishu_bitable_app | create | name | folder_token |\n| 创建数据表 | feishu_bitable_app_table | create | app_token, name | fields |\n| 创建字段 | feishu_bitable_app_table_field | create | app_token, table_id, field_name, type | property |\n| 创建视图 | feishu_bitable_app_table_view | create | app_token, table_id, view_name, view_type | - |\n\n---\n\n## 🎯 核心约束（Schema 未透露的知识）\n\n### 📚 详细参考文档\n\n**当遇到字段配置、记录值格式问题或需要完整示例时，查阅以下文档**：\n\n- **[字段 Property 配置详解](references/field-properties.md)** - 每种字段类型创建/更新时需要的 `property` 参数结构（单选的 options、进度的 min/max、关联的 table_id 等）\n- **[记录值数据结构详解](references/record-values.md)** - 每种字段类型在记录中对应的 `fields` 值格式（人员字段只传 id、日期是毫秒时间戳、附件需先上传等）\n- **[使用场景完整示例](references/examples.md)** - 8 个完整场景示例（创建表模式对比、批量导入、筛选查询、附件处理、关联字段等）\n\n**何时查阅**:\n- 创建/更新字段时收到 `125408X` 错误码（property 结构错误）→ 查 field-properties.md\n- 写入记录时收到 `125406X` 错误码（字段值转换失败）→ 查 record-values.md\n- 需要完整的操作流程和参数示例 → 查 examples.md\n\n---\n\n### 1. 字段类型与值格式必须严格匹配\n\n**Bitable 最大的坑**：不同字段类型对 value 的数据结构要求完全不同。\n\n#### 最易错的字段类型（完整列表见 [record-values.md](references/record-values.md)）\n\n| type | ui_type | 字段类型 | 正确格式 | ❌ 常见错误 |\n|------|---------|----------|---------|-----------|\n| 11 | User | 人员 | `[{id: \"ou_xxx\"}]` | 传字符串 `\"ou_xxx\"` 或 `[{name: \"张三\"}]` |\n| 5 | DateTime | 日期 | `1674206443000`（毫秒） | 传秒时间戳或字符串 |\n| 3 | SingleSelect | 单选 | `\"选项名\"` | 传数组 `[\"选项名\"]` |\n| 4 | MultiSelect | 多选 | `[\"选项1\", \"选项2\"]` | 传字符串 `\"选项1\"` |\n| 15 | Url | 超链接 | `{link: \"...\", text: \"...\"}` | 只传字符串 URL |\n| 17 | Attachment | 附件 | `[{file_token: \"...\"}]` | 传外部 URL 或本地路径 |\n\n**强制流程**：\n1. 先调用 `feishu_bitable_app_table_field.list` 获取字段的 `type` 和 `ui_type`\n2. 根据上表或 [record-values.md](references/record-values.md) 构造正确格式\n3. 错误码 `125406X` 或 `1254015` → 检查字段值格式\n\n**人员字段特别注意**：\n- 默认使用 open_id（ou_...），与 calendar/task 一致\n- 格式：`[{id: \"ou_xxx\"}]`（数组对象）\n- **只能传 id 字段**，不能传 name/email 等\n\n\n## 📌 核心使用场景\n\n> **完整示例**: 查阅 [examples.md](references/examples.md) 了解更多场景（创建表模式对比、空行处理、附件上传、关联字段等）\n\n### 场景 1: 查字段类型（必做第一步）\n\n```json\n{\n  \"action\": \"list\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tbl...\"\n}\n```\n\n**返回**：包含每个字段的 `field_id`、`field_name`、`type`、`ui_type`、`property`\n\n### 场景 2: 批量导入客户数据\n\n```json\n{\n  \"action\": \"batch_create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tbl...\",\n  \"records\": [\n    {\n      \"fields\": {\n        \"客户名称\": \"Bytedance\",\n        \"负责人\": [{\"id\": \"ou_xxx\"}],\n        \"签约日期\": 1674206443000,\n        \"状态\": \"进行中\"\n      }\n    },\n    {\n      \"fields\": {\n        \"客户名称\": \"飞书\",\n        \"负责人\": [{\"id\": \"ou_yyy\"}],\n        \"签约日期\": 1675416243000,\n        \"状态\": \"已完成\"\n      }\n    }\n  ]\n}\n```\n\n**字段值格式**：\n- 人员：`[{id: \"ou_xxx\"}]`（数组对象）\n- 日期：毫秒时间戳\n- 单选：字符串\n- 多选：字符串数组\n\n**限制**: 最多 500 条记录\n\n### 场景 3: 筛选查询（高级筛选）\n\n```json\n{\n  \"action\": \"list\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tbl...\",\n  \"filter\": {\n    \"conjunction\": \"and\",\n    \"conditions\": [\n      {\n        \"field_name\": \"状态\",\n        \"operator\": \"is\",\n        \"value\": [\"进行中\"]\n      },\n      {\n        \"field_name\": \"截止日期\",\n        \"operator\": \"isLess\",\n        \"value\": [\"ExactDate\", \"1740441600000\"]\n      }\n    ]\n  },\n  \"sort\": [\n    {\n      \"field_name\": \"截止日期\",\n      \"desc\": false\n    }\n  ]\n}\n```\n\n**filter 说明**：\n- 支持 10 种 operator（is/isNot/contains/isEmpty 等，见附录 C）\n- ⚠️ **isEmpty/isNotEmpty 必须传 `value: []`**（虽然逻辑上不需要值，但 API 要求必须传空数组）\n- 日期筛选可使用 `[\"Today\"]`、`[\"ExactDate\", \"时间戳\"]` 等\n- `sort` 可指定多个排序字段\n\n---\n\n## 🔍 常见错误与排查\n\n| 错误码 | 错误现象 | 根本原因 | 解决方案 |\n|--------|---------|---------|---------|\n| 1254064 | DatetimeFieldConvFail | 日期字段格式错误 | **必须用毫秒时间戳**（如 `1772121600000`），不能用字符串（`\"2026-02-27\"`、RFC3339）或秒级时间戳 |\n| 1254068 | URLFieldConvFail | 超链接字段格式错误 | **必须用对象** `{text: \"显示文本\", link: \"URL\"}`，不能直接传字符串 URL |\n| 1254066 | UserFieldConvFail | 人员字段格式错误或 ID 类型不匹配 | 必须传 `[{id: \"ou_xxx\"}]`，确认 `user_id_type` |\n| 1254015 | Field types do not match | 字段值格式与类型不匹配 | 先 list 字段，按类型构造正确格式 |\n| 1254104 | RecordAddOnceExceedLimit | 批量创建超过 500 条 | 分批调用，每批 ≤ 500 |\n| 1254291 | Write conflict | 并发写冲突 | 串行调用 + 延迟 0.5-1 秒 |\n| 1254303 | AttachPermNotAllow | 附件未上传到当前表格 | 先调用上传素材接口 |\n| 1254045 | FieldNameNotFound | 字段名不存在 | 检查字段名（包括空格、大小写） |\n\n---\n\n## 📚 附录：背景知识\n\n### A. 资源层级关系\n\n```\nApp (多维表格应用)\n ├── Table (数据表) ×100\n │    ├── Record (记录/行) ×20,000\n │    ├── Field (字段/列) ×300\n │    └── View (视图) ×200\n └── Dashboard (仪表盘)\n```\n\n### B. 筛选条件 operator 列表\n\n| operator | 含义 | 支持字段 | value 要求 |\n|----------|------|----------|-----------|\n| `is` | 等于 | 所有 | 单个值 |\n| `isNot` | 不等于 | 除日期外 | 单个值 |\n| `contains` | 包含 | 除日期外 | 可多个值 |\n| `doesNotContain` | 不包含 | 除日期外 | 可多个值 |\n| `isEmpty` | 为空 | 所有 | 必须为 `[]` |\n| `isNotEmpty` | 不为空 | 所有 | 必须为 `[]` |\n| `isGreater` | 大于 | 数字、日期 | 单个值 |\n| `isGreaterEqual` | 大于等于 | 数字（不支持日期） | 单个值 |\n| `isLess` | 小于 | 数字、日期 | 单个值 |\n| `isLessEqual` | 小于等于 | 数字（不支持日期） | 单个值 |\n\n**日期字段特殊值**: `[\"Today\"]`, `[\"Tomorrow\"]`, `[\"ExactDate\", \"时间戳\"]` 等（完整列表见 [examples.md](references/examples.md#场景-3-筛选查询高级筛选)）\n\n### C. 使用限制\n\n| 限制项 | 上限 |\n|--------|------|\n| 数据表 + 仪表盘 | 100（单个 App） |\n| 记录数 | 20,000（单个数据表） |\n| 字段数 | 300（单个数据表） |\n| 视图数 | 200（单个数据表） |\n| 批量创建/更新/删除 | 500（单次 API 调用） |\n| 单元格文本 | 10 万字符 |\n| 单选/多选选项 | 20,000（单个字段） |\n| 单元格附件 | 100 |\n| 单元格人员 | 1,000 |\n\n\n\n### D. 其他约束\n\n- 从其他数据源同步的数据表，**不支持增删改**记录\n- 公式字段、查看引用字段是**只读**的\n- 删除操作**无法恢复**\n- 视图筛选条件使用 `field_id`，需先调用 field.list 获取\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn785z27bvq547m6kep7brvsc185a3r6\",\n  \"slug\": \"feishu-bitable-suite\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1777012424892\n}\n\nFile v1.0.0:references/examples.md\n\n# 飞书多维表格使用场景完整示例\n\n本文档提供多维表格操作的完整场景示例，包括参数说明和注意事项。\n\n> **基础参考**: 先查阅 [字段 Property 配置详解](field-properties.md) 和 [记录值数据结构详解](record-values.md)\n\n---\n\n## 📋 目录\n\n1. [场景 0: 创建数据表（两种模式对比）](#场景-0-创建数据表两种模式对比)\n2. [场景 1: 查字段类型（必做第一步）](#场景-1-查字段类型必做第一步)\n3. [场景 2: 批量导入客户数据](#场景-2-批量导入客户数据)\n4. [场景 2.5: 创建表并插入数据（含空行处理）](#场景-25-创建表并插入数据含空行处理)\n5. [场景 3: 筛选查询（高级筛选）](#场景-3-筛选查询高级筛选)\n6. [场景 4: 更新单条记录](#场景-4-更新单条记录)\n7. [场景 5: 创建带选项的单选字段](#场景-5-创建带选项的单选字段)\n8. [场景 6: 创建复杂字段（进度、货币、评分）](#场景-6-创建复杂字段进度货币评分)\n9. [场景 7: 处理附件字段](#场景-7-处理附件字段)\n10. [场景 8: 双向关联字段](#场景-8-双向关联字段)\n\n---\n\n## 场景 0: 创建数据表（两种模式对比）\n\n### 模式 A：一次性定义所有字段\n\n**适用场景**：字段类型、配置都已明确，需要快速创建表结构。\n\n**优势**：一次 API 调用，原子性操作。\n\n**工具**: `feishu_bitable_app_table`\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table\": {\n    \"name\": \"客户管理表\",\n    \"default_view_name\": \"所有客户\",\n    \"fields\": [\n      {\n        \"field_name\": \"客户名称\",\n        \"type\": 1\n      },\n      {\n        \"field_name\": \"负责人\",\n        \"type\": 11,\n        \"property\": {\n          \"multiple\": false\n        }\n      },\n      {\n        \"field_name\": \"签约日期\",\n        \"type\": 5,\n        \"property\": {\n          \"date_formatter\": \"yyyy-MM-dd\"\n        }\n      },\n      {\n        \"field_name\": \"状态\",\n        \"type\": 3,\n        \"property\": {\n          \"options\": [\n            {\"name\": \"进行中\", \"color\": 0},\n            {\"name\": \"已完成\", \"color\": 10}\n          ]\n        }\n      },\n      {\n        \"field_name\": \"金额\",\n        \"type\": 2,\n        \"ui_type\": \"Currency\",\n        \"property\": {\n          \"currency_code\": \"CNY\",\n          \"formatter\": \"0.00\"\n        }\n      }\n    ]\n  }\n}\n```\n\n**返回示例**:\n```json\n{\n  \"table_id\": \"tblXXXXXXXX\",\n  \"name\": \"客户管理表\",\n  \"default_view_id\": \"vewXXXXXXXX\"\n}\n```\n\n---\n\n### 模式 B：使用默认表 + 逐步修改字段\n\n**适用场景**：探索式建表，需要边建边调整，或复杂字段配置需要分步确认。\n\n**优势**：\n- `app.create` 自带默认表和默认字段，可在此基础上调整\n- 复杂字段（单选 options、URL 格式等）分步确认，减少出错\n- 踩坑后容易回退（比如 URL 字段改为文本字段）\n\n**完整流程**：\n\n#### 步骤 1: 创建 App（工具: `feishu_bitable_app`）\n\n```json\n{\n  \"action\": \"create\",\n  \"name\": \"客户管理系统\",\n  \"folder_token\": \"fldXXXXXXXX\"\n}\n```\n\n**返回**: 包含 `app_token` 和默认表的 `default_table_id`\n\n---\n\n#### 步骤 2: 查看默认字段（工具: `feishu_bitable_app_table_field`）\n\n```json\n{\n  \"action\": \"list\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\"\n}\n```\n\n**返回示例**:\n```json\n{\n  \"fields\": [\n    {\n      \"field_id\": \"fld001\",\n      \"field_name\": \"文本\",\n      \"type\": 1,\n      \"ui_type\": \"Text\"\n    },\n    {\n      \"field_id\": \"fld002\",\n      \"field_name\": \"数字\",\n      \"type\": 2,\n      \"ui_type\": \"Number\"\n    }\n  ]\n}\n```\n\n---\n\n#### 步骤 3: 修改默认字段名称（工具: `feishu_bitable_app_table_field`）\n\n```json\n{\n  \"action\": \"update\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"field_id\": \"fld001\",\n  \"field_name\": \"客户名称\"\n}\n```\n\n---\n\n#### 步骤 4: 补充缺失字段（工具: `feishu_bitable_app_table_field`）\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"field_name\": \"负责人\",\n  \"type\": 11,\n  \"property\": {\n    \"multiple\": false\n  }\n}\n```\n\n---\n\n#### 步骤 5: 查看空记录（工具: `feishu_bitable_app_table_record`）\n\n```json\n{\n  \"action\": \"list\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\"\n}\n```\n\n**返回**: 可能包含空记录 `[{\"record_id\": \"recxxx\", \"fields\": {}}, ...]`\n\n---\n\n#### 步骤 6: 删除空行（工具: `feishu_bitable_app_table_record`）\n\n```json\n{\n  \"action\": \"batch_delete\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"records\": [\"recxxx\", \"recyyy\"]\n}\n```\n\n---\n\n#### 步骤 7: 批量插入数据（工具: `feishu_bitable_app_table_record`）\n\n```json\n{\n  \"action\": \"batch_create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"records\": [\n    {\n      \"fields\": {\n        \"客户名称\": \"Bytedance\",\n        \"负责人\": [{\"id\": \"ou_xxx\"}],\n        \"状态\": \"进行中\"\n      }\n    }\n  ]\n}\n```\n\n---\n\n**⚠️ 模式 B 的关键注意事项**:\n- 默认表中通常已有空记录，**必须先删除**，否则会有数据污染\n- 步骤 5-6 是必需的，不能跳过\n- 适合不确定字段配置的探索式场景\n\n---\n\n## 场景 1: 查字段类型（必做第一步）\n\n**为什么必做**: 不同字段类型的值格式完全不同，必须先查询再写入。\n\n**工具**: `feishu_bitable_app_table_field`\n\n```json\n{\n  \"action\": \"list\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\"\n}\n```\n\n**返回示例**:\n```json\n{\n  \"fields\": [\n    {\n      \"field_id\": \"fld001\",\n      \"field_name\": \"任务名称\",\n      \"type\": 1,\n      \"ui_type\": \"Text\",\n      \"property\": {}\n    },\n    {\n      \"field_id\": \"fld002\",\n      \"field_name\": \"负责人\",\n      \"type\": 11,\n      \"ui_type\": \"User\",\n      \"property\": {\n        \"multiple\": true\n      }\n    },\n    {\n      \"field_id\": \"fld003\",\n      \"field_name\": \"截止日期\",\n      \"type\": 5,\n      \"ui_type\": \"DateTime\",\n      \"property\": {\n        \"date_formatter\": \"yyyy-MM-dd HH:mm\"\n      }\n    },\n    {\n      \"field_id\": \"fld004\",\n      \"field_name\": \"状态\",\n      \"type\": 3,\n      \"ui_type\": \"SingleSelect\",\n      \"property\": {\n        \"options\": [\n          {\"id\": \"optXXX\", \"name\": \"进行中\", \"color\": 0},\n          {\"id\": \"optYYY\", \"name\": \"已完成\", \"color\": 10}\n        ]\n      }\n    }\n  ]\n}\n```\n\n**关键信息**:\n- `type`: 字段基础类型（1=文本, 2=数字, 3=单选...）\n- `ui_type`: UI 展示类型（区分进度、货币、评分等）\n- `property`: 字段配置（单选的 options、日期的 formatter 等）\n\n---\n\n## 场景 2: 批量导入客户数据\n\n**工具**: `feishu_bitable_app_table_record`\n\n```json\n{\n  \"action\": \"batch_create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"records\": [\n    {\n      \"fields\": {\n        \"客户名称\": \"某某\",\n        \"负责人\": [{\"id\": \"ou_xxx\"}],\n        \"签约日期\": 1674206443000,\n        \"状态\": \"进行中\",\n        \"金额\": 1000000,\n        \"标签\": [\"重要客户\", \"战略合作\"],\n        \"联系电话\": \"17899870000\",\n        \"官网\": {\n          \"text\": \"某某官网\",\n          \"link\": \"https://www.xxxx.com\"\n        }\n      }\n    },\n    {\n      \"fields\": {\n        \"客户名称\": \"飞书\",\n        \"负责人\": [{\"id\": \"ou_xxx\"}],\n        \"签约日期\": 1675416243000,\n        \"状态\": \"已完成\",\n        \"金额\": 500000,\n        \"标签\": [\"核心产品\"],\n        \"联系电话\": \"13800138000\"\n      }\n    }\n  ]\n}\n```\n\n**字段值格式说明**:\n- **文本**: 字符串 `\"客户名称\"`\n- **人员**: 对象数组 `[{\"id\": \"ou_xxx\"}]`（只能传 id）\n- **日期**: 毫秒时间戳 `1674206443000`\n- **单选**: 字符串 `\"进行中\"`\n- **多选**: 字符串数组 `[\"重要客户\", \"战略合作\"]`\n- **数字**: 数字 `1000000`\n- **电话**: 字符串 `\"17899870000\"`\n- **超链接**: 对象 `{\"text\": \"显示文本\", \"link\": \"URL\"}`\n\n**返回示例**:\n```json\n{\n  \"records\": [\n    {\n      \"record_id\": \"rec001\",\n      \"fields\": {...}\n    },\n    {\n      \"record_id\": \"rec002\",\n      \"fields\": {...}\n    }\n  ]\n}\n```\n\n**限制**:\n- 单次最多 500 条记录\n- 超过需分批调用\n\n---\n\n## 场景 2.5: 创建表并插入数据（含空行处理）\n\n**问题**: `app.create` 创建的默认表中会自带空记录（空行），直接插入数据会导致数据污染。\n\n**正确流程**: 见场景 0 的模式 B\n\n**核心步骤**:\n1. 创建 App → 获取 `app_token` 和 `default_table_id`\n2. 查看默认表记录 (`list` action)\n3. 删除空行 (`batch_delete` action)\n4. 批量插入数据 (`batch_create` action)\n\n**错误示例**（跳过步骤 2-3）:\n```\n表格最终状态：\n| 客户名称 | 负责人 | 状态 |\n|---------|--------|------|\n|         |        |      | ← 空行（原有）\n| Bytedance | 张三   | 进行中 | ← 新插入\n| 飞书    | 李四   | 已完成 | ← 新插入\n```\n\n**正确示例**（执行步骤 2-3）:\n```\n表格最终状态：\n| 客户名称 | 负责人 | 状态 |\n|---------|--------|------|\n| Bytedance | 张三   | 进行中 |\n| 飞书    | 李四   | 已完成 |\n```\n\n---\n\n## 场景 3: 筛选查询（高级筛选）\n\n**工具**: `feishu_bitable_app_table_record`\n\n```json\n{\n  \"action\": \"list\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"filter\": {\n    \"conjunction\": \"and\",\n    \"conditions\": [\n      {\n        \"field_name\": \"状态\",\n        \"operator\": \"is\",\n        \"value\": [\"进行中\"]\n      },\n      {\n        \"field_name\": \"截止日期\",\n        \"operator\": \"isLess\",\n        \"value\": [\"ExactDate\", \"1740441600000\"]\n      },\n      {\n        \"field_name\": \"优先级\",\n        \"operator\": \"isGreater\",\n        \"value\": [\"3\"]\n      }\n    ]\n  },\n  \"sort\": [\n    {\n      \"field_name\": \"截止日期\",\n      \"desc\": false\n    },\n    {\n      \"field_name\": \"优先级\",\n      \"desc\": true\n    }\n  ],\n  \"field_names\": [\"任务名称\", \"负责人\", \"截止日期\", \"状态\"],\n  \"page_size\": 100\n}\n```\n\n**参数说明**:\n\n### filter 结构\n- `conjunction`: 条件组合方式（`\"and\"` 或 `\"or\"`）\n- `conditions`: 条件数组\n\n### operator 类型（10 种）\n\n| operator | 含义 | 支持字段 | value 格式 |\n|----------|------|----------|-----------|\n| `is` | 等于 | 所有 | `[\"值\"]` |\n| `isNot` | 不等于 | 除日期外 | `[\"值\"]` |\n| `contains` | 包含 | 除日期外 | `[\"值1\", \"值2\"]` |\n| `doesNotContain` | 不包含 | 除日期外 | `[\"值1\"]` |\n| `isEmpty` | 为空 | 所有 | `[]` |\n| `isNotEmpty` | 不为空 | 所有 | `[]` |\n| `isGreater` | 大于 | 数字、日期 | `[\"值\"]` |\n| `isGreaterEqual` | 大于等于 | 数字 | `[\"值\"]` |\n| `isLess` | 小于 | 数字、日期 | `[\"值\"]` |\n| `isLessEqual` | 小于等于 | 数字 | `[\"值\"]` |\n\n### 日期字段特殊值\n\n```json\n// 具体日期\n{\"operator\": \"is\", \"value\": [\"ExactDate\", \"1702449755000\"]}\n\n// 相对日期\n{\"operator\": \"is\", \"value\": [\"Today\"]}      // 今天\n{\"operator\": \"is\", \"value\": [\"Tomorrow\"]}   // 明天\n{\"operator\": \"is\", \"value\": [\"Yesterday\"]}  // 昨天\n{\"operator\": \"is\", \"value\": [\"CurrentWeek\"]} // 本周\n{\"operator\": \"is\", \"value\": [\"LastWeek\"]}   // 上周\n{\"operator\": \"is\", \"value\": [\"TheLastWeek\"]} // 过去七天\n{\"operator\": \"is\", \"value\": [\"TheNextWeek\"]} // 未来七天\n```\n\n### sort 结构\n- `field_name`: 排序字段\n- `desc`: `true` 降序，`false` 升序\n- 支持多字段排序（按数组顺序）\n\n---\n\n## 场景 4: 更新单条记录\n\n**工具**: `feishu_bitable_app_table_record`\n\n```json\n{\n  \"action\": \"update\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"record_id\": \"recusyQbB0fVL5\",\n  \"fields\": {\n    \"状态\": \"已完成\",\n    \"完成时间\": 1674206443000,\n    \"备注\": \"客户已签约\"\n  }\n}\n```\n\n**说明**:\n- 只传需要更新的字段\n- 不传的字段保持不变\n- 支持部分字段更新\n\n**批量更新**（最多 500 条）:\n\n```json\n{\n  \"action\": \"batch_update\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"records\": [\n    {\n      \"record_id\": \"rec001\",\n      \"fields\": {\n        \"状态\": \"已完成\"\n      }\n    },\n    {\n      \"record_id\": \"rec002\",\n      \"fields\": {\n        \"状态\": \"已完成\"\n      }\n    }\n  ]\n}\n```\n\n---\n\n## 场景 5: 创建带选项的单选字段\n\n**工具**: `feishu_bitable_app_table_field`\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"field_name\": \"优先级\",\n  \"type\": 3,\n  \"property\": {\n    \"options\": [\n      {\"name\": \"高\", \"color\": 0},\n      {\"name\": \"中\", \"color\": 1},\n      {\"name\": \"低\", \"color\": 2}\n    ]\n  }\n}\n```\n\n**颜色编号**（color 范围 0-54）:\n- 0: 红色\n- 1: 橙色\n- 10: 绿色\n- 20: 蓝色\n\n**多选字段**（type=4）格式相同:\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"field_name\": \"标签\",\n  \"type\": 4,\n  \"property\": {\n    \"options\": [\n      {\"name\": \"重要\", \"color\": 0},\n      {\"name\": \"紧急\", \"color\": 1},\n      {\"name\": \"长期\", \"color\": 10}\n    ]\n  }\n}\n```\n\n**注意**:\n- 创建时**不能**指定选项 ID（`id` 字段），系统自动生成\n- 选项总数不超过 20,000\n\n---\n\n## 场景 6: 创建复杂字段（进度、货币、评分）\n\n### 进度字段 (type=2, ui_type=\"Progress\")\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"field_name\": \"完成进度\",\n  \"type\": 2,\n  \"ui_type\": \"Progress\",\n  \"property\": {\n    \"min\": 0,\n    \"max\": 100,\n    \"range_customize\": true\n  }\n}\n```\n\n**写入值**: `0.75` 表示 75%\n\n---\n\n### 货币字段 (type=2, ui_type=\"Currency\")\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"field_name\": \"预算\",\n  \"type\": 2,\n  \"ui_type\": \"Currency\",\n  \"property\": {\n    \"currency_code\": \"CNY\",\n    \"formatter\": \"0,000.00\"\n  }\n}\n```\n\n**currency_code 可选值**:\n- `\"CNY\"`: 人民币 (¥)\n- `\"USD\"`: 美元 ($)\n- `\"EUR\"`: 欧元 (€)\n- `\"JPY\"`: 日元 (¥)\n\n**写入值**: `5000.50`（普通数字）\n\n---\n\n### 评分字段 (type=2, ui_type=\"Rating\")\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"field_name\": \"客户满意度\",\n  \"type\": 2,\n  \"ui_type\": \"Rating\",\n  \"property\": {\n    \"min\": 1,\n    \"max\": 5,\n    \"rating\": {\n      \"symbol\": \"star\"\n    }\n  }\n}\n```\n\n**symbol 可选值**:\n- `\"star\"`: ⭐ 星星\n- `\"heart\"`: ❤️ 爱心\n- `\"fire\"`: 🔥 火焰\n- `\"thumbsup\"`: 👍 赞\n\n**写入值**: `4`（整数）\n\n---\n\n## 场景 7: 处理附件字段\n\n### 步骤 1: 上传附件到多维表格\n\n**工具**: `feishu_drive_media`（上传素材接口）\n\n```json\n{\n  \"action\": \"upload\",\n  \"file_path\": \"/path/to/file.pdf\",\n  \"parent_type\": \"bitable_image\",\n  \"parent_node\": \"S404b...\"  // app_token\n}\n```\n\n**返回**:\n```json\n{\n  \"file_token\": \"DRiFbwaKsoZaLax4WKZbEGCccoe\"\n}\n```\n\n---\n\n### 步骤 2: 创建附件字段（可选）\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"field_name\": \"合同文件\",\n  \"type\": 17\n}\n```\n\n---\n\n### 步骤 3: 写入附件记录\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"fields\": {\n    \"客户名称\": \"Bytedance\",\n    \"合同文件\": [\n      {\"file_token\": \"DRiFxxxxxxxxxxxxxxxxxxCccoe\"},\n      {\"file_token\": \"BZk3bxxxxxxxxxxxxxxxxeKqcLe\"}\n    ]\n  }\n}\n```\n\n**限制**:\n- 单个单元格附件数不超过 100\n- 必须先上传到当前多维表格，不能用外部 file_token\n\n---\n\n## 场景 8: 双向关联字段\n\n### 步骤 1: 创建双向关联字段\n\n**在\"任务表\"中创建关联到\"项目表\"的字段**:\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tbl_task\",\n  \"field_name\": \"所属项目\",\n  \"type\": 21,\n  \"property\": {\n    \"table_id\": \"tbl_project\",\n    \"back_field_name\": \"关联的任务\",\n    \"multiple\": true\n  }\n}\n```\n\n**结果**:\n- 在\"任务表\"中创建字段\"所属项目\"\n- 在\"项目表\"中**自动创建**字段\"关联的任务\"\n\n---\n\n### 步骤 2: 写入关联记录\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tbl_task\",\n  \"fields\": {\n    \"任务名称\": \"开发新功能\",\n    \"所属项目\": {\n      \"link_record_ids\": [\"rec_project_001\"]\n    }\n  }\n}\n```\n\n**级联更新**:\n- 在\"任务表\"中设置\"所属项目\"为 `rec_project_001`\n- \"项目表\"的 `rec_project_001` 记录的\"关联的任务\"字段会**自动添加**当前任务的 record_id\n\n---\n\n### 单向关联 (type=18)\n\n**区别**: 只影响当前表，不会自动更新对方表\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tbl_task\",\n  \"field_name\": \"参考任务\",\n  \"type\": 18,\n  \"property\": {\n    \"table_id\": \"tbl_task\",  // 可以关联自己\n    \"multiple\": true\n  }\n}\n```\n\n---\n\n## 🔗 参考链接\n\n- [字段 Property 配置详解](field-properties.md)\n- [记录值数据结构详解](record-values.md)\n- [飞书开放平台 - 多维表格文档](https://open.feishu.cn/document/server-docs/docs/bitable-v1/bitable-overview)\n\nFile v1.0.0:references/field-properties.md\n\n# 飞书多维表格字段 Property 配置详解\n\n本文档详细说明每种字段类型创建或更新时需要的 `property` 参数结构。\n\n> **来源**: 基于飞书开放平台文档 [字段编辑指南](https://go.feishu.cn/s/672BSzVyo03)\n\n## 📋 目录\n\n- [基础字段](#基础字段)\n  - [1. 文本 (type=1)](#1-文本-type1)\n  - [2. 数字 (type=2)](#2-数字-type2)\n  - [5. 日期 (type=5)](#5-日期-type5)\n  - [7. 复选框 (type=7)](#7-复选框-type7)\n  - [13. 电话号码 (type=13)](#13-电话号码-type13)\n- [选择字段](#选择字段)\n  - [3. 单选 (type=3)](#3-单选-type3)\n  - [4. 多选 (type=4)](#4-多选-type4)\n- [特殊显示字段](#特殊显示字段)\n  - [进度 (type=2, ui_type=\"Progress\")](#进度-type2-ui_typeprogress)\n  - [货币 (type=2, ui_type=\"Currency\")](#货币-type2-ui_typecurrency)\n  - [评分 (type=2, ui_type=\"Rating\")](#评分-type2-ui_typerating)\n  - [条码 (type=1, ui_type=\"Barcode\")](#条码-type1-ui_typebarcode)\n  - [邮箱 (type=1, ui_type=\"Email\")](#邮箱-type1-ui_typeemail)\n- [关系字段](#关系字段)\n  - [11. 人员 (type=11)](#11-人员-type11)\n  - [15. 超链接 (type=15)](#15-超链接-type15)\n  - [17. 附件 (type=17)](#17-附件-type17)\n  - [18. 单向关联 (type=18)](#18-单向关联-type18)\n  - [21. 双向关联 (type=21)](#21-双向关联-type21)\n  - [22. 地理位置 (type=22)](#22-地理位置-type22)\n  - [23. 群组 (type=23)](#23-群组-type23)\n- [高级字段](#高级字段)\n  - [20. 公式 (type=20)](#20-公式-type20)\n  - [1001. 创建时间 (type=1001)](#1001-创建时间-type1001)\n  - [1002. 最后更新时间 (type=1002)](#1002-最后更新时间-type1002)\n  - [1005. 自动编号 (type=1005)](#1005-自动编号-type1005)\n\n---\n\n## 基础字段\n\n### 1. 文本 (type=1)\n\n**Property 结构**: 空对象或省略\n\n```json\n{\n  \"type\": 1,\n  \"field_name\": \"任务描述\",\n  \"property\": {}\n}\n```\n\n**注意**:\n- 默认 `ui_type` 为 \"Text\"\n- 单个单元格最多 10 万字符\n- 支持富文本格式（提及人、超链接等）\n\n---\n\n### 2. 数字 (type=2)\n\n**Property 结构**:\n\n```json\n{\n  \"formatter\": \"0\"  // 可选，数字显示格式\n}\n```\n\n**formatter 可选值**:\n- `\"0\"`: 整数（默认）\n- `\"0.0\"`: 一位小数\n- `\"0.00\"`: 两位小数\n- `\"0,000\"`: 千分位\n- `\"0.00%\"`: 百分比\n\n**示例**:\n\n```json\n{\n  \"type\": 2,\n  \"field_name\": \"工时\",\n  \"property\": {\n    \"formatter\": \"0.00\"\n  }\n}\n```\n\n---\n\n### 5. 日期 (type=5)\n\n**Property 结构**:\n\n```json\n{\n  \"date_formatter\": \"yyyy/MM/dd\",  // 可选，默认 \"yyyy/MM/dd\"\n  \"auto_fill\": false               // 可选，是否自动填充创建时间\n}\n```\n\n**date_formatter 可选值**:\n- `\"yyyy/MM/dd\"`: 2021/1/30\n- `\"yyyy-MM-dd HH:mm\"`: 2021/1/30 14:00\n- `\"MM-dd\"`: 1月30日\n- `\"MM/dd/yyyy\"`: 01/30/2021\n- `\"dd/MM/yyyy\"`: 30/01/2021\n\n**示例**:\n\n```json\n{\n  \"type\": 5,\n  \"field_name\": \"截止日期\",\n  \"property\": {\n    \"date_formatter\": \"yyyy-MM-dd HH:mm\",\n    \"auto_fill\": false\n  }\n}\n```\n\n---\n\n### 7. 复选框 (type=7)\n\n**Property 结构**: 空对象或省略\n\n```json\n{\n  \"type\": 7,\n  \"field_name\": \"是否完成\",\n  \"property\": {}\n}\n```\n\n---\n\n### 13. 电话号码 (type=13)\n\n**Property 结构**: 空对象或省略\n\n```json\n{\n  \"type\": 13,\n  \"field_name\": \"联系电话\",\n  \"property\": {}\n}\n```\n\n**注意**:\n- 电话号码格式：符合正则 `(\\+)?\\d*`\n- 最大长度 64 字符\n\n---\n\n## 选择字段\n\n### 3. 单选 (type=3)\n\n**Property 结构**:\n\n```json\n{\n  \"options\": [\n    {\n      \"name\": \"进行中\",   // 必填，选项名称\n      \"color\": 0         // 可选，颜色编号 (0-54)\n    },\n    {\n      \"name\": \"已完成\",\n      \"color\": 10\n    }\n  ]\n}\n```\n\n**颜色编号 (color)**:\n- 范围: 0-54\n- 0: 红色\n- 10: 绿色\n- 20: 蓝色\n- ... (详见飞书官方文档)\n\n**示例**:\n\n```json\n{\n  \"type\": 3,\n  \"field_name\": \"任务状态\",\n  \"property\": {\n    \"options\": [\n      {\"name\": \"待开始\", \"color\": 0},\n      {\"name\": \"进行中\", \"color\": 20},\n      {\"name\": \"已完成\", \"color\": 10}\n    ]\n  }\n}\n```\n\n**注意**:\n- 选项总数不超过 20,000 个\n- 创建时**不能**指定选项 ID（`id` 字段），系统自动生成\n- 更新时需保留已有选项的 `id`\n\n---\n\n### 4. 多选 (type=4)\n\n**Property 结构**: 与单选相同\n\n```json\n{\n  \"options\": [\n    {\"name\": \"紧急\", \"color\": 0},\n    {\"name\": \"重要\", \"color\": 10}\n  ]\n}\n```\n\n**注意**:\n- 选项总数不超过 20,000 个\n- 单个单元格选项数不超过 1,000 个\n\n---\n\n## 特殊显示字段\n\n### 进度 (type=2, ui_type=\"Progress\")\n\n**Property 结构**:\n\n```json\n{\n  \"min\": 0,                  // 必填，最小值\n  \"max\": 100,                // 必填，最大值\n  \"range_customize\": false   // 可选，是否允许自定义进度值\n}\n```\n\n**示例**:\n\n```json\n{\n  \"type\": 2,\n  \"field_name\": \"完成进度\",\n  \"ui_type\": \"Progress\",\n  \"property\": {\n    \"min\": 0,\n    \"max\": 100,\n    \"range_customize\": true\n  }\n}\n```\n\n**注意**:\n- `min` 取值范围: 0-1\n- `max` 取值范围: 1-100\n- `range_customize` 为 `true` 时用户可输入超出范围的值\n\n---\n\n### 货币 (type=2, ui_type=\"Currency\")\n\n**Property 结构**:\n\n```json\n{\n  \"currency_code\": \"CNY\",  // 必填，货币类型\n  \"formatter\": \"0.00\"      // 可选，数字格式\n}\n```\n\n**currency_code 可选值**:\n- `\"CNY\"`: 人民币 (¥)\n- `\"USD\"`: 美元 ($)\n- `\"EUR\"`: 欧元 (€)\n- `\"GBP\"`: 英镑 (£)\n- `\"JPY\"`: 日元 (¥)\n- `\"HKD\"`: 港元 ($)\n- ... (支持 20+ 种货币)\n\n**示例**:\n\n```json\n{\n  \"type\": 2,\n  \"field_name\": \"预算\",\n  \"ui_type\": \"Currency\",\n  \"property\": {\n    \"currency_code\": \"USD\",\n    \"formatter\": \"0,000.00\"\n  }\n}\n```\n\n---\n\n### 评分 (type=2, ui_type=\"Rating\")\n\n**Property 结构**:\n\n```json\n{\n  \"min\": 1,                 // 必填，最小值\n  \"max\": 5,                 // 必填，最大值\n  \"rating\": {               // 可选，评分样式\n    \"symbol\": \"star\"        // 图标类型\n  }\n}\n```\n\n**symbol 可选值**:\n- `\"star\"`: ⭐ 星星（默认）\n- `\"heart\"`: ❤️ 爱心\n- `\"thumbsup\"`: 👍 赞\n- `\"fire\"`: 🔥 火焰\n- `\"smile\"`: 😊 笑脸\n- `\"lightning\"`: ⚡ 闪电\n- `\"flower\"`: 🌸 花朵\n- `\"number\"`: 数字\n\n**示例**:\n\n```json\n{\n  \"type\": 2,\n  \"field_name\": \"优先级\",\n  \"ui_type\": \"Rating\",\n  \"property\": {\n    \"min\": 1,\n    \"max\": 5,\n    \"rating\": {\n      \"symbol\": \"fire\"\n    }\n  }\n}\n```\n\n---\n\n### 条码 (type=1, ui_type=\"Barcode\")\n\n**Property 结构**:\n\n```json\n{\n  \"allowed_edit_modes\": {\n    \"manual\": true,   // 是否允许手动录入\n    \"scan\": true      // 是否允许扫描录入\n  }\n}\n```\n\n**示例**:\n\n```json\n{\n  \"type\": 1,\n  \"field_name\": \"商品条码\",\n  \"ui_type\": \"Barcode\",\n  \"property\": {\n    \"allowed_edit_modes\": {\n      \"manual\": false,\n      \"scan\": true\n    }\n  }\n}\n```\n\n---\n\n### 邮箱 (type=1, ui_type=\"Email\")\n\n**Property 结构**: 空对象或省略\n\n```json\n{\n  \"type\": 1,\n  \"field_name\": \"联系邮箱\",\n  \"ui_type\": \"Email\",\n  \"property\": {}\n}\n```\n\n---\n\n## 关系字段\n\n### 11. 人员 (type=11)\n\n**Property 结构**:\n\n```json\n{\n  \"multiple\": true  // 可选，是否允许多个人员，默认 true\n}\n```\n\n**示例**:\n\n```json\n{\n  \"type\": 11,\n  \"field_name\": \"负责人\",\n  \"property\": {\n    \"multiple\": false  // 只允许单个人员\n  }\n}\n```\n\n**注意**:\n- 单个单元格人员数不超过 1,000\n- 记录值只支持传入 `id` 字段（open_id/union_id/user_id）\n\n---\n\n### 15. 超链接 (type=15)\n\n**Property 结构**: **必须省略 `property` 参数，不要传递任何值（包括空对象）**\n\n```json\n{\n  \"type\": 15,\n  \"field_name\": \"参考链接\"\n  // 不要传 property 参数，包括空对象 {}\n}\n```\n\n**⚠️ 重要**: 超链接字段的特殊要求（经实测验证）：\n- ✅ **正确**: 完全省略 `property` 参数\n- ❌ **错误**: `\"property\": {}`（会报 URLFieldPropertyError）\n- ❌ **错误**: 传递任何 property 值\n\n**注意**: 这是飞书 API 的特殊行为，超链接字段即使传空对象也会报错，必须完全省略该参数。\n\n---\n\n### 17. 附件 (type=17)\n\n**Property 结构**: 空对象或省略\n\n```json\n{\n  \"type\": 17,\n  \"field_name\": \"附件\",\n  \"property\": {}\n}\n```\n\n**注意**:\n- 单个单元格附件数不超过 100\n- 写入前需先调用[上传素材接口](https://go.feishu.cn/s/63soQp6O80s)\n\n---\n\n### 18. 单向关联 (type=18)\n\n**Property 结构**:\n\n```json\n{\n  \"table_id\": \"tblXXXXXXXX\",  // 必填，关联的数据表 ID\n  \"multiple\": true             // 可选，是否允许多条记录，默认 true\n}\n```\n\n**示例**:\n\n```json\n{\n  \"type\": 18,\n  \"field_name\": \"关联任务\",\n  \"property\": {\n    \"table_id\": \"tblsRc9GRRXKqhvW\",\n    \"multiple\": true\n  }\n}\n```\n\n**注意**:\n- 单个单元格关联数不超过 500\n\n---\n\n### 21. 双向关联 (type=21)\n\n**Property 结构**:\n\n```json\n{\n  \"table_id\": \"tblXXXXXXXX\",      // 必填，关联的数据表 ID\n  \"back_field_name\": \"反向字段名\",  // 必填，对方表的双向关联字段名\n  \"multiple\": true                 // 可选，是否允许多条记录\n}\n```\n\n**示例**:\n\n```json\n{\n  \"type\": 21,\n  \"field_name\": \"相关项目\",\n  \"property\": {\n    \"table_id\": \"tblAnotherTable\",\n    \"back_field_name\": \"关联的任务\",\n    \"multiple\": true\n  }\n}\n```\n\n**注意**:\n- 单个单元格关联数不超过 500\n- 对方表会自动创建对应的双向关联字段\n\n---\n\n### 22. 地理位置 (type=22)\n\n**Property 结构**:\n\n```json\n{\n  \"location\": {\n    \"input_type\": \"not_limit\"  // 输入限制\n  }\n}\n```\n\n**input_type 可选值**:\n- `\"only_mobile\"`: 仅允许移动端实时定位\n- `\"not_limit\"`: 无限制（默认）\n\n**示例**:\n\n```json\n{\n  \"type\": 22,\n  \"field_name\": \"办公地址\",\n  \"property\": {\n    \"location\": {\n      \"input_type\": \"only_mobile\"\n    }\n  }\n}\n```\n\n---\n\n### 23. 群组 (type=23)\n\n**Property 结构**: 空对象或省略\n\n```json\n{\n  \"type\": 23,\n  \"field_name\": \"协作群\",\n  \"property\": {}\n}\n```\n\n**注意**:\n- 单个单元格群组数不超过 10 个\n\n---\n\n## 高级字段\n\n### 20. 公式 (type=20)\n\n**Property 结构**:\n\n```json\n{\n  \"formula_expression\": \"bitable::$table[tblXXX].$field[fldYYY]*2\"  // 可选\n}\n```\n\n**示例**:\n\n```json\n{\n  \"type\": 20,\n  \"field_name\": \"总价\",\n  \"property\": {\n    \"formula_expression\": \"bitable::$table[tblMain].$field[fldQty] * $field[fldPrice]\"\n  }\n}\n```\n\n**注意**:\n- 创建字段时**不支持**设置公式表达式\n- 参考[飞书帮助中心 - 公式字段](https://www.feishu.cn/hc/zh-CN/articles/360049067853)\n\n**对于某些多维表格，公式字段需要额外设置 `type` 参数**（通过[获取多维表格元数据](https://go.feishu.cn/s/62nuKkQlE03)接口的 `formula_type` 判断）:\n\n```json\n{\n  \"type\": 20,\n  \"field_name\": \"计算字段\",\n  \"property\": {\n    \"type\": {\n      \"data_type\": 2,           // 公式结果的数据类型 (1=文本, 2=数字, 5=日期...)\n      \"ui_property\": {          // UI 展示属性\n        \"formatter\": \"0.00\",\n        \"currency_code\": \"CNY\"\n      },\n      \"ui_type\": \"Currency\"     // UI 类型 (Number/Progress/Currency/Rating/DateTime)\n    }\n  }\n}\n```\n\n---\n\n### 1001. 创建时间 (type=1001)\n\n**Property 结构**:\n\n```json\n{\n  \"date_formatter\": \"yyyy/MM/dd\"  // 可选，日期格式\n}\n```\n\n**示例**:\n\n```json\n{\n  \"type\": 1001,\n  \"field_name\": \"创建于\",\n  \"property\": {\n    \"date_formatter\": \"yyyy-MM-dd HH:mm\"\n  }\n}\n```\n\n---\n\n### 1002. 最后更新时间 (type=1002)\n\n**Property 结构**: 与创建时间相同\n\n```json\n{\n  \"date_formatter\": \"yyyy-MM-dd HH:mm\"\n}\n```\n\n---\n\n### 1005. 自动编号 (type=1005)\n\n**Property 结构**:\n\n```json\n{\n  \"auto_serial\": {\n    \"type\": \"auto_increment_number\",  // 或 \"custom\"\n    \"options\": [                      // 自定义编号规则（仅 type=\"custom\" 时需要）\n      {\n        \"type\": \"fixed_text\",\n        \"value\": \"TASK-\"\n      },\n      {\n        \"type\": \"created_time\",\n        \"value\": \"yyyyMMdd\"\n      },\n      {\n        \"type\": \"system_number\",\n        \"value\": \"5\"\n      }\n    ]\n  }\n}\n```\n\n**auto_serial.type 可选值**:\n- `\"auto_increment_number\"`: 纯自增数字\n- `\"custom\"`: 自定义编号规则\n\n**options 中的规则类型**:\n- `\"system_number\"`: 自增数字位数（value: 1-9）\n- `\"fixed_text\"`: 固定字符（value: 最多 20 字符）\n- `\"created_time\"`: 创建时间（value: \"yyyyMMdd\"/\"yyyyMM\"/\"yyyy\"/\"MMdd\"/\"MM\"/\"dd\"）\n\n**示例 1: 纯自增**:\n\n```json\n{\n  \"type\": 1005,\n  \"field_name\": \"编号\",\n  \"property\": {\n    \"auto_serial\": {\n      \"type\": \"auto_increment_number\"\n    }\n  }\n}\n```\n\n**示例 2: 自定义编号**:\n\n```json\n{\n  \"type\": 1005,\n  \"field_name\": \"工单号\",\n  \"property\": {\n    \"auto_serial\": {\n      \"type\": \"custom\",\n      \"options\": [\n        {\"type\": \"fixed_text\", \"value\": \"WO-\"},\n        {\"type\": \"created_time\", \"value\": \"yyyyMMdd\"},\n        {\"type\": \"system_number\", \"value\": \"4\"}\n      ]\n    }\n  }\n}\n// 生成示例: WO-20240226-0001\n```\n\n---\n\n## 🔍 常见错误码\n\n| 错误码 | 字段类型 | 说明 |\n|--------|---------|------|\n| 1254080 | 文本 | property 结构错误 |\n| 1254081 | 数字 | property 结构错误，检查 formatter |\n| 1254082 | 单选 | property 结构错误，检查 options 数组 |\n| 1254083 | 多选 | property 结构错误，检查 options 数组 |\n| 1254084 | 日期 | property 结构错误，检查 date_formatter |\n| 1254085 | 复选框 | property 结构错误 |\n| 1254086 | 人员 | property 结构错误，检查 multiple |\n| 1254087 | 超链接 | **必须省略 property 参数（传空对象也会报错）** |\n| 1254088 | 附件 | property 结构错误 |\n| 1254089 | 单向关联 | property 结构错误，检查 table_id |\n| 1254090 | 查找引用 | property 结构错误 |\n| 1254091 | 公式 | property 结构错误 |\n| 1254092 | 双向关联 | property 结构错误，检查 table_id 和 back_field_name |\n| 1254093 | 创建时间 | property 结构错误 |\n| 1254094 | 最后更新时间 | property 结构错误 |\n\n---\n\n## 📌 更新字段时的特殊规则\n\n调用 `update` action 更新字段时：\n\n1. **必须保持字段类型一致**: `type` 和 `ui_type` 不能变更\n2. **单选/多选更新选项**:\n   - 已有选项必须保留 `id`\n   - 新增选项只传 `name` 和 `color`，不传 `id`\n3. **如果只改字段名**:\n   - 可以只传 `field_name`，工具会自动查询当前 `type` 和 `property`\n4. **关联字段的 table_id**: 不能修改为不同的表\n\n---\n\n## 🔗 参考链接\n\n- [飞书开放平台 - 字段编辑指南](https://go.feishu.cn/s/672BSzVyo03)\n- [新增字段接口文档](https://go.feishu.cn/s/62nuKkQl403)\n- [更新字段接口文档](https://go.feishu.cn/s/62nuKkQlo03)\n\nFile v1.0.0:references/record-values.md\n\n# 飞书多维表格记录值数据结构详解\n\n本文档详细说明每种字段类型在记录中对应的 `fields` 值格式。\n\n> **来源**: 基于飞书开放平台文档 [多维表格记录数据结构](https://go.feishu.cn/s/6lY28723w04)\n\n## 📋 快速索引\n\n| 字段类型 | type | 值类型 | 示例 | 限制 |\n|---------|------|--------|------|------|\n| [文本](#文本-type1) | 1 | string (写入) / list of object (返回) | `\"任务描述\"` | 最多 10 万字符 |\n| [数字](#数字-type2) | 2 | number | `0.5` | - |\n| [单选](#单选-type3) | 3 | string | `\"进行中\"` | 选项总数≤20,000 |\n| [多选](#多选-type4) | 4 | array<string> | `[\"审批\", \"办公\"]` | 选项总数≤20,000，单元格≤1,000 |\n| [日期](#日期-type5) | 5 | number | `1675526400000` | Unix 毫秒时间戳 |\n| [复选框](#复选框-type7) | 7 | boolean | `true` | - |\n| [人员](#人员-type11) | 11 | list of object | `[{\"id\": \"ou_xxx\"}]` | 单元格≤1,000，写入仅支持 `id` |\n| [电话](#电话号码-type13) | 13 | string | `\"17899870000\"` | 最多 64 字符 |\n| [超链接](#超链接-type15) | 15 | object | `{\"text\": \"飞书\", \"link\": \"...\"}` | - |\n| [附件](#附件-type17) | 17 | list of object | `[{\"file_token\": \"xxx\"}]` | 单元格≤100 |\n| [单向关联](#单向关联-type18) | 18 | object | `{\"link_record_ids\": [...]}` | 单元格≤500 |\n| [双向关联](#双向关联-type21) | 21 | object | `{\"link_record_ids\": [...]}` | 单元格≤500 |\n| [地理位置](#地理位置-type22) | 22 | object | `{\"location\": \"116.3,40.0\", ...}` | - |\n| [群组](#群组-type23) | 23 | list of object | `[{\"id\": \"oc_xxx\"}]` | 单元格≤10 |\n| [公式/查找引用](#公式查找引用-type20-type19) | 20/19 | object | `{\"type\": 1, \"value\": [...]}` | 只读 |\n\n---\n\n## 文本 (type=1)\n\n### 基础文本 (ui_type=\"Text\")\n\n**写入格式**: 字符串\n\n```json\n{\n  \"fields\": {\n    \"任务描述\": \"维护客户关系\"\n  }\n}\n```\n\n**返回格式**: 对象数组\n\n```json\n{\n  \"任务描述\": [\n    {\n      \"text\": \"维护客户关系\",\n      \"type\": \"text\"\n    }\n  ]\n}\n```\n\n**富文本格式** (提及人、超链接):\n\n```json\n{\n  \"任务描述\": [\n    {\n      \"text\": \"请 \",\n      \"type\": \"text\"\n    },\n    {\n      \"text\": \"@张三\",\n      \"type\": \"mention\",\n      \"token\": \"ou_user123\",\n      \"mentionType\": \"User\",\n      \"mentionNotify\": true,\n      \"name\": \"张三\"\n    },\n    {\n      \"text\": \" 查看 \",\n      \"type\": \"text\"\n    },\n    {\n      \"text\": \"飞书官网\",\n      \"type\": \"url\",\n      \"link\": \"https://www.feishu.cn\"\n    }\n  ]\n}\n```\n\n**富文本元素类型**:\n\n| type | 说明 | 额外字段 |\n|------|------|---------|\n| `\"text\"` | 纯文本 | `text` |\n| `\"mention\"` | 提及（人/文档） | `token`, `mentionType`, `mentionNotify`, `name` |\n| `\"url\"` | 超链接 | `text`, `link` |\n\n**mentionType 可选值**:\n- `\"User\"`: 提及用户\n- `\"Docx\"`: 提及文档\n- `\"Sheet\"`: 提及电子表格\n- `\"Bitable\"`: 提及多维表格\n\n---\n\n### 条码 (ui_type=\"Barcode\")\n\n**写入格式**: 字符串\n\n```json\n{\n  \"fields\": {\n    \"商品条码\": \"FS0001\"\n  }\n}\n```\n\n**返回格式**:\n\n```json\n{\n  \"商品条码\": [\n    {\n      \"text\": \"FS0001\",\n      \"type\": \"text\"\n    }\n  ]\n}\n```\n\n---\n\n### 邮箱 (ui_type=\"Email\")\n\n**写入格式**: 字符串\n\n```json\n{\n  \"fields\": {\n    \"联系邮箱\": \"zhangmin@xxxgmail.com\"\n  }\n}\n```\n\n**返回格式**:\n\n```json\n{\n  \"联系邮箱\": [\n    {\n      \"text\": \"zhangmin@xxxgmail.com\",\n      \"type\": \"url\",\n      \"link\": \"mailto:zhangmin@xxxgmail.com\"\n    }\n  ]\n}\n```\n\n---\n\n## 数字 (type=2)\n\n**写入/返回格式**: 数字\n\n```json\n{\n  \"fields\": {\n    \"工时\": 10,\n    \"完成率\": 0.75,\n    \"预算\": 5000.50\n  }\n}\n```\n\n**注意**:\n- 进度 (ui_type=\"Progress\"): 0-1 范围的小数\n- 货币 (ui_type=\"Currency\"): 普通数字\n- 评分 (ui_type=\"Rating\"): 整数\n\n---\n\n## 单选 (type=3)\n\n**写入格式**: 选项名称字符串\n\n```json\n{\n  \"fields\": {\n    \"任务状态\": \"进行中\"\n  }\n}\n```\n\n**新选项**: 传入不存在的选项名会**自动创建新选项**\n\n```json\n{\n  \"fields\": {\n    \"任务状态\": \"已暂停\"  // 如果不存在，会自动创建\n  }\n}\n```\n\n**返回格式**: 与写入相同\n\n```json\n{\n  \"任务状态\": \"进行中\"\n}\n```\n\n**限制**:\n- 选项总数不超过 20,000\n\n---\n\n## 多选 (type=4)\n\n**写入格式**: 字符串数组\n\n```json\n{\n  \"fields\": {\n    \"标签\": [\"审批集成\", \"办公管理\", \"身份管理\"]\n  }\n}\n```\n\n**新选项**: 传入不存在的选项名会**自动创建新选项**\n\n```json\n{\n  \"fields\": {\n    \"标签\": [\"新标签1\", \"新标签2\"]  // 不存在的会自动创建\n  }\n}\n```\n\n**返回格式**: 与写入相同\n\n```json\n{\n  \"标签\": [\"审批集成\", \"办公管理\"]\n}\n```\n\n**限制**:\n- 选项总数不超过 20,000\n- 单个单元格选项数不超过 1,000\n\n---\n\n## 日期 (type=5)\n\n**写入/返回格式**: Unix 毫秒时间戳\n\n```json\n{\n  \"fields\": {\n    \"截止日期\": 1675526400000  // 2023-02-05 00:00:00 (UTC)\n  }\n}\n```\n\n**注意**:\n- 必须使用**毫秒级**时间戳（不是秒级）\n- 建议使用北京时间 (UTC+8) 转换\n\n**常见错误** (错误码 1254064):\n\n```json\n// ❌ 错误：使用 ISO 字符串\n{\"截止日期\": \"2026-02-27\"}\n\n// ❌ 错误：使用 RFC3339 格式\n{\"截止日期\": \"2026-02-27T10:00:00+08:00\"}\n\n// ❌ 错误：使用秒级时间戳\n{\"截止日期\": 1772121600}  // 少了 3 位\n\n// ✅ 正确：使用毫秒时间戳\n{\"截止日期\": 1772121600000}\n```\n\n---\n\n## 复选框 (type=7)\n\n**写入/返回格式**: 布尔值\n\n```json\n{\n  \"fields\": {\n    \"是否完成\": true,\n    \"是否延期\": false\n  }\n}\n```\n\n---\n\n## 人员 (type=11)\n\n**写入格式**: 对象数组，**仅支持 `id` 字段**\n\n```json\n{\n  \"fields\": {\n    \"负责人\": [\n      {\"id\": \"ou_8240099442cf5da49f04f4bf8f8abcef\"}\n    ],\n    \"协作人\": [\n      {\"id\": \"ou_user1\"},\n      {\"id\": \"ou_user2\"}\n    ]\n  }\n}\n```\n\n**返回格式**: 对象数组，包含完整信息\n\n```json\n{\n  \"负责人\": [\n    {\n      \"id\": \"ou_8240099442cf5da49f04f4bf8f8abcef\",\n      \"name\": \"黄泡泡\",\n      \"en_name\": \"Amanda Huang\",\n      \"email\": \"amandahuang@xxxgmail.com\",\n      \"avatar_url\": \"https://...\"\n    }\n  ]\n}\n```\n\n**⚠️ 重要**:\n- **写入时只支持 `id`**，不能传 `name`、`email` 等字段\n- `id` 类型需与 `user_id_type` 参数一致（open_id/union_id/user_id）\n- 单个单元格人员数不超过 1,000\n- 传空: `null` 或 `[]`\n\n---\n\n## 电话号码 (type=13)\n\n**写入/返回格式**: 字符串\n\n```json\n{\n  \"fields\": {\n    \"联系电话\": \"17899870000\",\n    \"座机\": \"+86-010-12345678\"\n  }\n}\n```\n\n**格式规则**:\n- 符合正则: `(\\+)?\\d*`\n- 最大长度 64 字符\n\n---\n\n## 超链接 (type=15)\n\n**写入/返回格式**: 对象\n\n```json\n{\n  \"fields\": {\n    \"参考链接\": {\n      \"text\": \"飞书开放平台\",\n      \"link\": \"https://open.feishu.cn\"\n    }\n  }\n}\n```\n\n**字段说明**:\n- `text`: 显示的文本\n- `link`: URL 地址\n\n**常见错误** (错误码 1254068):\n\n```json\n// ❌ 错误：直接传字符串 URL\n{\n  \"参考链接\": \"https://open.feishu.cn\"\n}\n\n// ✅ 正确：使用对象格式\n{\n  \"参考链接\": {\n    \"text\": \"飞书开放平台\",\n    \"link\": \"https://open.feishu.cn\"\n  }\n}\n\n// ✅ text 和 link 可以相同\n{\n  \"参考链接\": {\n    \"text\": \"https://open.feishu.cn\",\n    \"link\": \"https://open.feishu.cn\"\n  }\n}\n```\n\n---\n\n## 附件 (type=17)\n\n**写入格式**: 对象数组，**仅传 `file_token`**\n\n```json\n{\n  \"fields\": {\n    \"附件\": [\n      {\"file_token\": \"DRiFbwaKsoZaLax4WKZbEGCccoe\"},\n      {\"file_token\": \"BZk3bL1Enoy4pzxaPL9bNeKqcLe\"}\n    ]\n  }\n}\n```\n\n**返回格式**: 对象数组，包含完整信息\n\n```json\n{\n  \"附件\": [\n    {\n      \"file_token\": \"J7GdbgNWWoD1fwx7oWccxdgknIe\",\n      \"name\": \"58cc930b89.png\",\n      \"type\": \"image/png\",\n      \"size\": 108867,\n      \"url\": \"https://open.feishu.cn/open-apis/drive/v1/medias/...\",\n      \"tmp_url\": \"https://open.feishu.cn/open-apis/drive/v1/medias/batch_get_tmp_download_url?...\"\n    }\n  ]\n}\n```\n\n**⚠️ 重要**:\n- 写入前必须先调用[上传素材接口](https://go.feishu.cn/s/63soQp6O80s)获取 `file_token`\n- 单个单元格附件数不超过 100\n- 错误码 1254303: 附件未挂载到当前多维表格\n\n---\n\n## 单向关联 (type=18)\n\n**写入格式**: `link_record_ids` 数组\n\n```json\n{\n  \"fields\": {\n    \"关联任务\": {\n      \"link_record_ids\": [\"recHTLvO7x\", \"recbS8zb2m\"]\n    }\n  }\n}\n```\n\n**简化写入** (直接数组):\n\n```json\n{\n  \"fields\": {\n    \"关联任务\": [\"recHTLvO7x\", \"recbS8zb2m\"]\n  }\n}\n```\n\n**返回格式**:\n\n```json\n{\n  \"关联任务\": {\n    \"link_record_ids\": [\"recHTLvO7x\", \"recbS8zb2m\"]\n  }\n}\n```\n\n**限制**:\n- 单个单元格关联数不超过 500\n\n---\n\n## 双向关联 (type=21)\n\n**写入/返回格式**: 与单向关联相同\n\n```json\n{\n  \"fields\": {\n    \"相关项目\": {\n      \"link_record_ids\": [\"reclzUoBLn\", \"rec7bYQoX1\"]\n    }\n  }\n}\n```\n\n**注意**:\n- 更新双向关联会同步更新对方表的对应字段\n- 单个单元格关联数不超过 500\n\n---\n\n## 地理位置 (type=22)\n\n**写入格式**: 经纬度字符串\n\n```json\n{\n  \"fields\": {\n    \"办公地址\": \"116.397755,39.903179\"\n  }\n}\n```\n\n**返回格式**: 对象，包含详细信息\n\n```json\n{\n  \"办公地址\": {\n    \"location\": \"116.352681,40.01437\",\n    \"pname\": \"北京市\",\n    \"cityname\": \"北京市\",\n    \"adname\": \"海淀区\",\n    \"address\": \"学清路10号院学清嘉创大厦\",\n    \"name\": \"Bytedance\",\n    \"full_address\": \"Bytedance，北京市北京市海淀区学清路10号院学清嘉创大厦\"\n  }\n}\n```\n\n**字段说明**:\n- `location`: 经纬度 (格式: \"经度,纬度\")\n- `pname`: 省\n- `cityname`: 市\n- `adname`: 区\n- `address`: 详细地址\n- `name`: 地名\n- `full_address`: 完整地址\n\n---\n\n## 群组 (type=23)\n\n**写入格式**: 对象数组，**仅传 `id`**\n\n```json\n{\n  \"fields\": {\n    \"协作群\": [\n      {\"id\": \"oc_d2a947abb78bbbbb12d4cad55fbabcef\"}\n    ]\n  }\n}\n```\n\n**返回格式**: 对象数组，包含完整信息\n\n```json\n{\n  \"协作群\": [\n    {\n      \"id\": \"oc_d2a947abb78bbbbb12d4cad55fbabcef\",\n      \"name\": \"测试部门\",\n      \"avatar_url\": \"https://...\"\n    }\n  ]\n}\n```\n\n**限制**:\n- 单个单元格群组数不超过 10\n\n---\n\n## 公式/查找引用 (type=20, type=19)\n\n**格式**: 对象，包含 `type`、`ui_type` 和 `value`\n\n```json\n{\n  \"是否延期\": {\n    \"type\": 1,                    // 底层数据类型\n    \"ui_type\": \"Text\",            // UI 展示类型\n    \"value\": [                    // 计算结果\n      {\n        \"text\": \"✅ 正常\",\n        \"type\": \"text\"\n      }\n    ]\n  }\n}\n```\n\n**字段说明**:\n- `type`: 底层数据类型枚举（1=文本, 2=数字, 5=日期...）\n- `ui_type`: UI 展示类型（\"Text\"/\"Number\"/\"Progress\"/...）\n- `value`: 计算结果，格式由 `type` 决定\n\n**示例 - 数字类型公式**:\n\n```json\n{\n  \"总价\": {\n    \"type\": 2,\n    \"ui_type\": \"Currency\",\n    \"value\": 1250.50\n  }\n}\n```\n\n**示例 - 日期类型公式**:\n\n```json\n{\n  \"计算日期\": {\n    \"type\": 5,\n    \"ui_type\": \"DateTime\",\n    \"value\": 1675526400000\n  }\n}\n```\n\n**⚠️ 注意**:\n- 公式字段为**只读**，不能通过写接口设置\n- `value` 的数据结构取决于 `type` 对应的字段类型\n\n---\n\n## 系统字段\n\n### 创建时间 (type=1001)\n\n**返回格式**: Unix 毫秒时间戳\n\n```json\n{\n  \"创建于\": 1675526400000\n}\n```\n\n**⚠️ 只读**: 不能通过写接口设置\n\n---\n\n### 最后更新时间 (type=1002)\n\n**返回格式**: Unix 毫秒时间戳\n\n```json\n{\n  \"更新于\": 1675612800000\n}\n```\n\n**⚠️ 只读**: 不能通过写接口设置\n\n---\n\n### 创建人 / 修改人 (type=1003, type=1004)\n\n**返回格式**: 对象数组（与人员字段相同）\n\n```json\n{\n  \"创建人\": [\n    {\n      \"id\": \"ou_8240099442cf5da49f04f4bf8f8abcef\",\n      \"name\": \"黄泡泡\",\n      \"en_name\": \"Amanda Huang\",\n      \"email\": \"amandahuang@xxxgmail.com\",\n      \"avatar_url\": \"https://...\"\n    }\n  ]\n}\n```\n\n**⚠️ 只读**: 不能通过写接口设置\n\n---\n\n### 自动编号 (type=1005)\n\n**返回格式**: 字符串\n\n```json\n{\n  \"工单号\": \"WO-20240226-0001\"\n}\n```\n\n**⚠️ 只读**: 不能通过写接口设置\n\n---\n\n## 🔍 常见错误与排查\n\n### 字段类型不匹配 (错误码 1254015)\n\n**错误示例**:\n\n```json\n// ❌ 错误: 日期字段传字符串\n{\n  \"fields\": {\n    \"截止日期\": \"2024-02-26\"  // 应该传时间戳\n  }\n}\n\n// ✅ 正确\n{\n  \"fields\": {\n    \"截止日期\": 1708905600000\n  }\n}\n```\n\n---\n\n### 人员字段格式错误 (错误码 1254066)\n\n**常见原因**:\n\n1. **传入了不支持的字段**:\n\n```json\n// ❌ 错误\n{\n  \"负责人\": [\n    {\"name\": \"张三\"}  // 只能传 id\n  ]\n}\n\n// ✅ 正确\n{\n  \"负责人\": [\n    {\"id\": \"ou_xxx\"}\n  ]\n}\n```\n\n2. **user_id_type 不匹配**:\n\n```bash\n# 请求时指定了 user_id_type=open_id，但传的是 union_id\n```\n\n3. **跨应用传 open_id**:\n\n```\n不同应用的 open_id 不能交叉使用，建议使用 user_id\n```\n\n---\n\n### 附件未挂载 (错误码 1254303)\n\n**原因**: 直接传入外部 file_token\n\n**解决**:\n\n1. 先调用[上传素材接口](https://go.feishu.cn/s/63soQp6O80s)上传到当前多维表格\n2. 使用返回的 `file_token` 写入记录\n\n---\n\n### 字段名不存在 (错误码 1254045)\n\n**原因**: 字段名称不完全匹配（可能有空格、换行、特殊字符）\n\n**排查**:\n\n1. 调用[列出字段接口](https://go.feishu.cn/s/62nuKkQlk03)获取准确字段名\n2. 检查首尾空格、换行符\n\n---\n\n### 超链接字段转换失败 (错误码 1254068)\n\n**原因**: 缺少 `text` 或 `link` 字段\n\n```json\n// ❌ 错误\n{\n  \"参考链接\": {\n    \"link\": \"https://example.com\"  // 缺少 text\n  }\n}\n\n// ✅ 正确\n{\n  \"参考链接\": {\n    \"text\": \"示例网站\",\n    \"link\": \"https://example.com\"\n  }\n}\n```\n\n---\n\n## 📌 最佳实践\n\n### 1. 批量写入优化\n\n```json\n{\n  \"fields\": {\n    \"任务名称\": \"拜访客户\",\n    \"负责人\": [{\"id\": \"ou_xxx\"}],\n    \"截止日期\": 1708905600000,\n    \"标签\": [\"重要\", \"紧急\"],\n    \"是否完成\": false\n  }\n}\n```\n\n**建议**:\n- 一次性传入所有字段，避免多次调用\n- 只传需要设置的字段，不必包含所有列\n\n---\n\n### 2. 清空字段值\n\n**方法 1**: 传 `null`\n\n```json\n{\n  \"fields\": {\n    \"负责人\": null,\n    \"标签\": null\n  }\n}\n```\n\n**方法 2**: 传空数组/空字符串（根据字段类型）\n\n```json\n{\n  \"fields\": {\n    \"负责人\": [],\n    \"任务名称\": \"\"\n  }\n}\n```\n\n---\n\n### 3. 时间戳转换\n\n**JavaScript**:\n\n```javascript\n// 北京时间字符串 → Unix 毫秒时间戳\nconst timestamp = new Date(\"2024-02-26 14:00\").getTime()  // 1708927200000\n\n// Unix 毫秒时间戳 → 日期字符串\nconst date = new Date(1708927200000).toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' })\n```\n\n**Python**:\n\n```python\nimport datetime\n\n# 北京时间字符串 → Unix 毫秒时间戳\ndt = datetime.datetime(2024, 2, 26, 14, 0, 0)\ntimestamp = int(dt.timestamp() * 1000)  # 1708927200000\n\n# Unix 毫秒时间戳 → 日期字符串\ndt = datetime.datetime.fromtimestamp(1708927200000 / 1000)\n```\n\n---\n\n### 4. 关联字段的级联更新\n\n**双向关联**:\n\n```json\n// 更新 Table A 的双向关联字段\n{\n  \"fields\": {\n    \"关联项目\": {\n      \"link_record_ids\": [\"rec123\"]\n    }\n  }\n}\n// Table B 的对应双向关联字段会自动更新\n```\n\n**单向关联**:\n\n```json\n// 只更新当前表，不影响关联表\n{\n  \"fields\": {\n    \"参考任务\": {\n      \"link_record_ids\": [\"rec456\"]\n    }\n  }\n}\n```\n\n---\n\n## 🔗 参考链接\n\n- [飞书开放平台 - 多维表格记录数据结构](https://go.feishu.cn/s/6lY28723w04)\n- [新增记录接口文档](https://go.feishu.cn/s/61Y-IrQjU02)\n- [更新记录接口文档](https://go.feishu.cn/s/6lY28723A04)\n- [上传素材接口](https://go.feishu.cn/s/63soQp6O80s)\n\nFile v1.0.0:skill-card.md\n\n## Description:\n\n飞书多维表格（Bitable）的创建、查询、编辑和管理工具，包含 27 种字段类型支持、高级筛选、批量操作和视图管理。\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[a3152557994-ship-it](https://clawhub.ai/user/a3152557994-ship-it)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use this skill to create and manage Feishu Bitable apps, tables, fields, views, records, filters, batch operations, and attachment workflows. It is intended for workflows that need structured guidance for reading, writing, importing, updating, and deleting Bitable data.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can guide writes, deletes, batch operations, schema changes, and attachment uploads that persist changes to Feishu Bitable business data.\n\nMitigation: Before executing those actions, confirm the exact app_token, table_id, records, fields, action, and file contents with the user.\n\nRisk: Delete operations may not be recoverable and default tables can contain empty records that pollute later imports.\n\nMitigation: Review target record IDs before deletion and list records first when cleaning default table rows before importing data.\n\nRisk: Incorrect field value formats can cause failed writes or malformed records, especially for people, dates, select fields, URLs, and attachments.\n\nMitigation: List field metadata before writing records, match each value to its field type, and use the bundled record value and field property references for validation.\n\n## Reference(s):\n\n- [字段 Property 配置详解](references/field-properties.md)\n- [记录值数据结构详解](references/record-values.md)\n- [使用场景完整示例](references/examples.md)\n- [飞书开放平台 - 字段编辑指南](https://go.feishu.cn/s/672BSzVyo03)\n- [飞书开放平台 - 多维表格记录数据结构](https://go.feishu.cn/s/6lY28723w04)\n- [飞书开放平台 - 多维表格文档](https://open.feishu.cn/document/server-docs/docs/bitable-v1/bitable-overview)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, markdown, code, configuration]\n\n**Output Format:** [Markdown guidance with JSON request examples and parameter notes]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May include Feishu Bitable tool names, action names, field schemas, record value formats, filters, batch-operation constraints, and troubleshooting guidance.]\n\n## Skill Version(s):\n\n1.0.0 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.","readmeExcerpt":"Skill: 飞书Bitable管理工具 Owner: a3152557994-ship-it Summary: 飞书多维表格（Bitable）的创建、查询、编辑和管理工具。包含 27 种字段类型支持、高级筛选、批量操作和视图管理。 **当以下情况时使用此 Skill**： (1) 需要创建或管理飞书多维表格 App (2) 需要在多维表格中新增、查询、修改、删除记录（行数据） (3) 需要管理字段（列）、视图、数据表 (4... Tags: latest:1.0.0 Version history: v1.0.0 | 2026-04-24T06:33:44.892Z | auto - 首发版本，支持飞书多维表格（Bitable）全功能操作 - 实现 27 种字段类型的表结构管理、查询和批量数据操作 - 提供详细字段格式、数据导入、筛选、并发、批量等最佳实践说明 - 补充常见错误码及排查，详解字段类型、导入格式和极易踩坑点 - ","codeSnippets":[],"executableExamples":[{"language":"json","snippet":"{\n  \"action\": \"list\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tbl...\"\n}"},{"language":"json","snippet":"{\n  \"action\": \"batch_create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tbl...\",\n  \"records\": [\n    {\n      \"fields\": {\n        \"客户名称\": \"Bytedance\",\n        \"负责人\": [{\"id\": \"ou_xxx\"}],\n        \"签约日期\": 1674206443000,\n        \"状态\": \"进行中\"\n      }\n    },\n    {\n      \"fields\": {\n        \"客户名称\": \"飞书\",\n        \"负责人\": [{\"id\": \"ou_yyy\"}],\n        \"签约日期\": 1675416243000,\n        \"状态\": \"已完成\"\n      }\n    }\n  ]\n}"},{"language":"json","snippet":"{\n  \"action\": \"list\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tbl...\",\n  \"filter\": {\n    \"conjunction\": \"and\",\n    \"conditions\": [\n      {\n        \"field_name\": \"状态\",\n        \"operator\": \"is\",\n        \"value\": [\"进行中\"]\n      },\n      {\n        \"field_name\": \"截止日期\",\n        \"operator\": \"isLess\",\n        \"value\": [\"ExactDate\", \"1740441600000\"]\n      }\n    ]\n  },\n  \"sort\": [\n    {\n      \"field_name\": \"截止日期\",\n      \"desc\": false\n    }\n  ]\n}"},{"language":"text","snippet":"App (多维表格应用)\n ├── Table (数据表) ×100\n │    ├── Record (记录/行) ×20,000\n │    ├── Field (字段/列) ×300\n │    └── View (视图) ×200\n └── Dashboard (仪表盘)"},{"language":"json","snippet":"{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table\": {\n    \"name\": \"客户管理表\",\n    \"default_view_name\": \"所有客户\",\n    \"fields\": [\n      {\n        \"field_name\": \"客户名称\",\n        \"type\": 1\n      },\n      {\n        \"field_name\": \"负责人\",\n        \"type\": 11,\n        \"property\": {\n          \"multiple\": false\n        }\n      },\n      {\n        \"field_name\": \"签约日期\",\n        \"type\": 5,\n        \"property\": {\n          \"date_formatter\": \"yyyy-MM-dd\"\n        }\n      },\n      {\n        \"field_name\": \"状态\",\n        \"type\": 3,\n        \"property\": {\n          \"options\": [\n            {\"name\": \"进行中\", \"color\": 0},\n            {\"name\": \"已完成\", \"color\": 10}\n          ]\n        }\n      },\n      {\n        \"field_name\": \"金额\",\n        \"type\": 2,\n        \"ui_type\": \"Currency\",\n        \"property\": {\n          \"currency_code\": \"CNY\",\n          \"formatter\": \"0.00\"\n        }\n      }\n    ]\n  }\n}"},{"language":"json","snippet":"{\n  \"table_id\": \"tblXXXXXXXX\",\n  \"name\": \"客户管理表\",\n  \"default_view_id\": \"vewXXXXXXXX\"\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: feishu-bitable\ndescription: |\n  飞书多维表格（Bitable）的创建、查询、编辑和管理工具。包含 27 种字段类型支持、高级筛选、批量操作和视图管理。\n\n  **当以下情况时使用此 Skill**：\n  (1) 需要创建或管理飞书多维表格 App\n  (2) 需要在多维表格中新增、查询、修改、删除记录（行数据）\n  (3) 需要管理字段（列）、视图、数据表\n  (4) 用户提到\"多维表格\"、\"bitable\"、\"数据表\"、\"记录\"、\"字段\"\n  (5) 需要批量导入数据或批量更新多维表格\n---\n\n# Feishu Bitable (多维表格) SKILL\n\n## 🚨 执行前必读\n\n- ✅ **创建数据表**：支持两种模式 — ① 明确需求时，在 `create` 时通过 `table.fields` 一次性定义字段（减少 API 调用）；② 探索式场景时，使用默认表 + 逐步修改字段（更稳定，易调整）\n- ⚠️ **默认表的空行坑**：`app.create` 自带的默认表中会有空记录（空行）！插入数据前建议先调用 `feishu_bitable_app_table_record.list` + `batch_delete` 删除空行，避免数据污染\n- ✅ **写记录前**：先调用 `feishu_bitable_app_table_field.list` 获取字段 type/ui_type\n- ✅ **人员字段**：默认 open_id（ou_...），值必须是 `[{id:\"ou_xxx\"}]`（数组对象）\n- ✅ **日期字段**：毫秒时间戳（例如 `1674206443000`），不是秒\n- ✅ **单选字段**：字符串（例如 `\"选项1\"`），不是数组\n- ✅ **多选字段**：字符串数组（例如 `[\"选项1\", \"选项2\"]`）\n- ✅ **附件字段**：必须先上传到当前多维表格，使用返回的 file_token\n- ✅ **批量上限**：单次 ≤ 500 条，超过需分批（批量操作是原子性的）\n- ✅ **并发限制**：同一数据表不支持并发写，需串行调用 + 延迟 0.5-1 秒\n\n---\n\n## 📋 快速索引：意图 → 工具 → 必填参数\n\n| 用户意图 | 工具 | action | 必填参数 | 常用可选 |\n|---------|------|--------|---------|---------|\n| 查表有哪些字段 | feishu_bitable_app_table_field | list | app_token, table_id | - |\n| 查记录 | feishu_bitable_app_table_record | list | app_token, table_id | filter, sort, field_names |\n| 新增一行 | feishu_bitable_app_table_record | create | app_token, table_id, fields | - |\n| 批量导入 | feishu_bitable_app_table_record | batch_create | app_token, table_id, records (≤500) | - |\n| 更新一行 | feishu_bitable_app_table_record | update | app_token, table_id, record_id, fields | - |\n| 批量更新 | feishu_bitable_app_table_record | batch_update | app_token, table_id, records (≤500) | - |\n| 创建多维表格 | feishu_bitable_app | create | name | folder_token |\n| 创建数据表 | feishu_bitable_app_table | create | app_token, name | fields |\n| 创建字段 | feishu_bitable_app_table_field | create | app_token, table_id, field_name, type | property |\n| 创建视图 | feishu_bitable_app_table_view | create | app_token, table_id, view_name, view_type | - |\n\n---\n\n## 🎯 核心约束（Schema 未透露的知识）\n\n### 📚 详细参考文档\n\n**当遇到字段配置、记录值格式问题或需要完整示例时，查阅以下文档**：\n\n- **[字段 Property 配置详解](references/field-properties.md)** - 每种字段类型创建/更新时需要的 `property` 参数结构（单选的 options、进度的 min/max、关联的 table_id 等）\n- **[记录值数据结构详解](references/record-values.md)** - 每种字段类型在记录中对应的 `fields` 值格式（人员字段只传 id、日期是毫秒时间戳、附件需先上传等）\n- **[使用场景完整示例](references/examples.md)** - 8 个完整场景示例（创建表模式对比、批量导入、筛选查询、附件处理、关联字段等）\n\n**何时查阅**:\n- 创建/更新字段时收到 `125408X` 错误码（property 结构错误）→ 查 field-properties.md\n- 写入记录时收到 `125406X` 错误码（字段值转换失败）→ 查 record-values.md\n- 需要完整的操作流程和参数示例 → 查 examples.md\n\n---\n\n### 1. 字段类型与值格式必须严格匹配\n\n**Bitable 最大的坑**：不同字段类型对 value 的数据结构要求完全不同。\n\n#### 最易错的字段类型（完整列表见 [record-values.md](references/record-values.md)）\n\n| type | ui_type | 字段类型 | 正确格式 | ❌ 常见错误 |\n|------|---------|----------|---------|-----------|\n| 11 | User | 人员 | `[{id: \"ou_xxx\"}]` | 传字符串 `\"ou_xxx\"` 或 `[{name: \"张三\"}]` |\n| 5 | DateTime | 日期 | `1674206443000`（毫秒） | 传秒时间戳或字符串 |\n| 3 | SingleSelect | 单选 | `\"选项名\"` | 传数组 `[\"选项名\"]` |\n| 4 | MultiSelect | 多选 | `[\"选项1\", \"选项2\"]` | 传字符串 `\"选项1\"` |"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn785z27bvq547m6kep7brvsc185a3r6\",\n  \"slug\": \"feishu-bitable-suite\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1777012424892\n}"},{"path":"references/examples.md","content":"# 飞书多维表格使用场景完整示例\n\n本文档提供多维表格操作的完整场景示例，包括参数说明和注意事项。\n\n> **基础参考**: 先查阅 [字段 Property 配置详解](field-properties.md) 和 [记录值数据结构详解](record-values.md)\n\n---\n\n## 📋 目录\n\n1. [场景 0: 创建数据表（两种模式对比）](#场景-0-创建数据表两种模式对比)\n2. [场景 1: 查字段类型（必做第一步）](#场景-1-查字段类型必做第一步)\n3. [场景 2: 批量导入客户数据](#场景-2-批量导入客户数据)\n4. [场景 2.5: 创建表并插入数据（含空行处理）](#场景-25-创建表并插入数据含空行处理)\n5. [场景 3: 筛选查询（高级筛选）](#场景-3-筛选查询高级筛选)\n6. [场景 4: 更新单条记录](#场景-4-更新单条记录)\n7. [场景 5: 创建带选项的单选字段](#场景-5-创建带选项的单选字段)\n8. [场景 6: 创建复杂字段（进度、货币、评分）](#场景-6-创建复杂字段进度货币评分)\n9. [场景 7: 处理附件字段](#场景-7-处理附件字段)\n10. [场景 8: 双向关联字段](#场景-8-双向关联字段)\n\n---\n\n## 场景 0: 创建数据表（两种模式对比）\n\n### 模式 A：一次性定义所有字段\n\n**适用场景**：字段类型、配置都已明确，需要快速创建表结构。\n\n**优势**：一次 API 调用，原子性操作。\n\n**工具**: `feishu_bitable_app_table`\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table\": {\n    \"name\": \"客户管理表\",\n    \"default_view_name\": \"所有客户\",\n    \"fields\": [\n      {\n        \"field_name\": \"客户名称\",\n        \"type\": 1\n      },\n      {\n        \"field_name\": \"负责人\",\n        \"type\": 11,\n        \"property\": {\n          \"multiple\": false\n        }\n      },\n      {\n        \"field_name\": \"签约日期\",\n        \"type\": 5,\n        \"property\": {\n          \"date_formatter\": \"yyyy-MM-dd\"\n        }\n      },\n      {\n        \"field_name\": \"状态\",\n        \"type\": 3,\n        \"property\": {\n          \"options\": [\n            {\"name\": \"进行中\", \"color\": 0},\n            {\"name\": \"已完成\", \"color\": 10}\n          ]\n        }\n      },\n      {\n        \"field_name\": \"金额\",\n        \"type\": 2,\n        \"ui_type\": \"Currency\",\n        \"property\": {\n          \"currency_code\": \"CNY\",\n          \"formatter\": \"0.00\"\n        }\n      }\n    ]\n  }\n}\n```\n\n**返回示例**:\n```json\n{\n  \"table_id\": \"tblXXXXXXXX\",\n  \"name\": \"客户管理表\",\n  \"default_view_id\": \"vewXXXXXXXX\"\n}\n```\n\n---\n\n### 模式 B：使用默认表 + 逐步修改字段\n\n**适用场景**：探索式建表，需要边建边调整，或复杂字段配置需要分步确认。\n\n**优势**：\n- `app.create` 自带默认表和默认字段，可在此基础上调整\n- 复杂字段（单选 options、URL 格式等）分步确认，减少出错\n- 踩坑后容易回退（比如 URL 字段改为文本字段）\n\n**完整流程**：\n\n#### 步骤 1: 创建 App（工具: `feishu_bitable_app`）\n\n```json\n{\n  \"action\": \"create\",\n  \"name\": \"客户管理系统\",\n  \"folder_token\": \"fldXXXXXXXX\"\n}\n```\n\n**返回**: 包含 `app_token` 和默认表的 `default_table_id`\n\n---\n\n#### 步骤 2: 查看默认字段（工具: `feishu_bitable_app_table_field`）\n\n```json\n{\n  \"action\": \"list\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\"\n}\n```\n\n**返回示例**:\n```json\n{\n  \"fields\": [\n    {\n      \"field_id\": \"fld001\",\n      \"field_name\": \"文本\",\n      \"type\": 1,\n      \"ui_type\": \"Text\"\n    },\n    {\n      \"field_id\": \"fld002\",\n      \"field_name\": \"数字\",\n      \"type\": 2,\n      \"ui_type\": \"Number\"\n    }\n  ]\n}\n```\n\n---\n\n#### 步骤 3: 修改默认字段名称（工具: `feishu_bitable_app_table_field`）\n\n```json\n{\n  \"action\": \"update\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"field_id\": \"fld001\",\n  \"field_name\": \"客户名称\"\n}\n```\n\n---\n\n#### 步骤 4: 补充缺失字段（工具: `feishu_bitable_app_table_field`）\n\n```json\n{\n  \"action\": \"create\",\n  \"app_token\": \"S404b...\",\n  \"table_id\": \"tblXXXXXXXX\",\n  \"field_name\": \"负责人\",\n  \"type\": 11,\n  \"property\": {\n    \"multiple\": false\n  }\n}\n```\n\n---\n\n#### 步骤 5: 查看空记录（工具: `feishu_bitable_app_table_record`）\n\n```json\n{\n "},{"path":"references/field-properties.md","content":"# 飞书多维表格字段 Property 配置详解\n\n本文档详细说明每种字段类型创建或更新时需要的 `property` 参数结构。\n\n> **来源**: 基于飞书开放平台文档 [字段编辑指南](https://go.feishu.cn/s/672BSzVyo03)\n\n## 📋 目录\n\n- [基础字段](#基础字段)\n  - [1. 文本 (type=1)](#1-文本-type1)\n  - [2. 数字 (type=2)](#2-数字-type2)\n  - [5. 日期 (type=5)](#5-日期-type5)\n  - [7. 复选框 (type=7)](#7-复选框-type7)\n  - [13. 电话号码 (type=13)](#13-电话号码-type13)\n- [选择字段](#选择字段)\n  - [3. 单选 (type=3)](#3-单选-type3)\n  - [4. 多选 (type=4)](#4-多选-type4)\n- [特殊显示字段](#特殊显示字段)\n  - [进度 (type=2, ui_type=\"Progress\")](#进度-type2-ui_typeprogress)\n  - [货币 (type=2, ui_type=\"Currency\")](#货币-type2-ui_typecurrency)\n  - [评分 (type=2, ui_type=\"Rating\")](#评分-type2-ui_typerating)\n  - [条码 (type=1, ui_type=\"Barcode\")](#条码-type1-ui_typebarcode)\n  - [邮箱 (type=1, ui_type=\"Email\")](#邮箱-type1-ui_typeemail)\n- [关系字段](#关系字段)\n  - [11. 人员 (type=11)](#11-人员-type11)\n  - [15. 超链接 (type=15)](#15-超链接-type15)\n  - [17. 附件 (type=17)](#17-附件-type17)\n  - [18. 单向关联 (type=18)](#18-单向关联-type18)\n  - [21. 双向关联 (type=21)](#21-双向关联-type21)\n  - [22. 地理位置 (type=22)](#22-地理位置-type22)\n  - [23. 群组 (type=23)](#23-群组-type23)\n- [高级字段](#高级字段)\n  - [20. 公式 (type=20)](#20-公式-type20)\n  - [1001. 创建时间 (type=1001)](#1001-创建时间-type1001)\n  - [1002. 最后更新时间 (type=1002)](#1002-最后更新时间-type1002)\n  - [1005. 自动编号 (type=1005)](#1005-自动编号-type1005)\n\n---\n\n## 基础字段\n\n### 1. 文本 (type=1)\n\n**Property 结构**: 空对象或省略\n\n```json\n{\n  \"type\": 1,\n  \"field_name\": \"任务描述\",\n  \"property\": {}\n}\n```\n\n**注意**:\n- 默认 `ui_type` 为 \"Text\"\n- 单个单元格最多 10 万字符\n- 支持富文本格式（提及人、超链接等）\n\n---\n\n### 2. 数字 (type=2)\n\n**Property 结构**:\n\n```json\n{\n  \"formatter\": \"0\"  // 可选，数字显示格式\n}\n```\n\n**formatter 可选值**:\n- `\"0\"`: 整数（默认）\n- `\"0.0\"`: 一位小数\n- `\"0.00\"`: 两位小数\n- `\"0,000\"`: 千分位\n- `\"0.00%\"`: 百分比\n\n**示例**:\n\n```json\n{\n  \"type\": 2,\n  \"field_name\": \"工时\",\n  \"property\": {\n    \"formatter\": \"0.00\"\n  }\n}\n```\n\n---\n\n### 5. 日期 (type=5)\n\n**Property 结构**:\n\n```json\n{\n  \"date_formatter\": \"yyyy/MM/dd\",  // 可选，默认 \"yyyy/MM/dd\"\n  \"auto_fill\": false               // 可选，是否自动填充创建时间\n}\n```\n\n**date_formatter 可选值**:\n- `\"yyyy/MM/dd\"`: 2021/1/30\n- `\"yyyy-MM-dd HH:mm\"`: 2021/1/30 14:00\n- `\"MM-dd\"`: 1月30日\n- `\"MM/dd/yyyy\"`: 01/30/2021\n- `\"dd/MM/yyyy\"`: 30/01/2021\n\n**示例**:\n\n```json\n{\n  \"type\": 5,\n  \"field_name\": \"截止日期\",\n  \"property\": {\n    \"date_formatter\": \"yyyy-MM-dd HH:mm\",\n    \"auto_fill\": false\n  }\n}\n```\n\n---\n\n### 7. 复选框 (type=7)\n\n**Property 结构**: 空对象或省略\n\n```json\n{\n  \"type\": 7,\n  \"field_name\": \"是否完成\",\n  \"property\": {}\n}\n```\n\n---\n\n### 13. 电话号码 (type=13)\n\n**Property 结构**: 空对象或省略\n\n```json\n{\n  \"type\": 13,\n  \"field_name\": \"联系电话\",\n  \"property\": {}\n}\n```\n\n**注意**:\n- 电话号码格式：符合正则 `(\\+)?\\d*`\n- 最大长度 64 字符\n\n---\n\n## 选择字段\n\n### 3. 单选 (type=3)\n\n**Property 结构**:\n\n```json\n{\n  \"options\": [\n    {\n      \"name\": \"进行中\",   // 必填，选项名称\n      \"color\": 0         // 可选，颜色编号 (0-54)\n    },\n    {\n      \"name\": \"已完成\",\n      \"color\": 10\n    }\n  ]\n}\n```\n\n**颜色编号 (color)**:\n- 范围: 0-54\n- 0: 红色\n- 10: 绿色\n- 20: 蓝色\n- ... (详见飞书官方文档)\n\n**示例**:\n\n```json\n{\n  \"type\": 3,\n  \"field_name\": \"任务状态\",\n  \"property\": {\n    \"options\": [\n      {\"name\": \"待开始\", \"color\": 0},\n      {\"name\": \"进行中\", \"color\""},{"path":"references/record-values.md","content":"# 飞书多维表格记录值数据结构详解\n\n本文档详细说明每种字段类型在记录中对应的 `fields` 值格式。\n\n> **来源**: 基于飞书开放平台文档 [多维表格记录数据结构](https://go.feishu.cn/s/6lY28723w04)\n\n## 📋 快速索引\n\n| 字段类型 | type | 值类型 | 示例 | 限制 |\n|---------|------|--------|------|------|\n| [文本](#文本-type1) | 1 | string (写入) / list of object (返回) | `\"任务描述\"` | 最多 10 万字符 |\n| [数字](#数字-type2) | 2 | number | `0.5` | - |\n| [单选](#单选-type3) | 3 | string | `\"进行中\"` | 选项总数≤20,000 |\n| [多选](#多选-type4) | 4 | array<string> | `[\"审批\", \"办公\"]` | 选项总数≤20,000，单元格≤1,000 |\n| [日期](#日期-type5) | 5 | number | `1675526400000` | Unix 毫秒时间戳 |\n| [复选框](#复选框-type7) | 7 | boolean | `true` | - |\n| [人员](#人员-type11) | 11 | list of object | `[{\"id\": \"ou_xxx\"}]` | 单元格≤1,000，写入仅支持 `id` |\n| [电话](#电话号码-type13) | 13 | string | `\"17899870000\"` | 最多 64 字符 |\n| [超链接](#超链接-type15) | 15 | object | `{\"text\": \"飞书\", \"link\": \"...\"}` | - |\n| [附件](#附件-type17) | 17 | list of object | `[{\"file_token\": \"xxx\"}]` | 单元格≤100 |\n| [单向关联](#单向关联-type18) | 18 | object | `{\"link_record_ids\": [...]}` | 单元格≤500 |\n| [双向关联](#双向关联-type21) | 21 | object | `{\"link_record_ids\": [...]}` | 单元格≤500 |\n| [地理位置](#地理位置-type22) | 22 | object | `{\"location\": \"116.3,40.0\", ...}` | - |\n| [群组](#群组-type23) | 23 | list of object | `[{\"id\": \"oc_xxx\"}]` | 单元格≤10 |\n| [公式/查找引用](#公式查找引用-type20-type19) | 20/19 | object | `{\"type\": 1, \"value\": [...]}` | 只读 |\n\n---\n\n## 文本 (type=1)\n\n### 基础文本 (ui_type=\"Text\")\n\n**写入格式**: 字符串\n\n```json\n{\n  \"fields\": {\n    \"任务描述\": \"维护客户关系\"\n  }\n}\n```\n\n**返回格式**: 对象数组\n\n```json\n{\n  \"任务描述\": [\n    {\n      \"text\": \"维护客户关系\",\n      \"type\": \"text\"\n    }\n  ]\n}\n```\n\n**富文本格式** (提及人、超链接):\n\n```json\n{\n  \"任务描述\": [\n    {\n      \"text\": \"请 \",\n      \"type\": \"text\"\n    },\n    {\n      \"text\": \"@张三\",\n      \"type\": \"mention\",\n      \"token\": \"ou_user123\",\n      \"mentionType\": \"User\",\n      \"mentionNotify\": true,\n      \"name\": \"张三\"\n    },\n    {\n      \"text\": \" 查看 \",\n      \"type\": \"text\"\n    },\n    {\n      \"text\": \"飞书官网\",\n      \"type\": \"url\",\n      \"link\": \"https://www.feishu.cn\"\n    }\n  ]\n}\n```\n\n**富文本元素类型**:\n\n| type | 说明 | 额外字段 |\n|------|------|---------|\n| `\"text\"` | 纯文本 | `text` |\n| `\"mention\"` | 提及（人/文档） | `token`, `mentionType`, `mentionNotify`, `name` |\n| `\"url\"` | 超链接 | `text`, `link` |\n\n**mentionType 可选值**:\n- `\"User\"`: 提及用户\n- `\"Docx\"`: 提及文档\n- `\"Sheet\"`: 提及电子表格\n- `\"Bitable\"`: 提及多维表格\n\n---\n\n### 条码 (ui_type=\"Barcode\")\n\n**写入格式**: 字符串\n\n```json\n{\n  \"fields\": {\n    \"商品条码\": \"FS0001\"\n  }\n}\n```\n\n**返回格式**:\n\n```json\n{\n  \"商品条码\": [\n    {\n      \"text\": \"FS0001\",\n      \"type\": \"text\"\n    }\n  ]\n}\n```\n\n---\n\n### 邮箱 (ui_type=\"Email\")\n\n**写入格式**: 字符串\n\n```json\n{\n  \"fields\": {\n    \"联系邮箱\": \"zhangmin@xxxgmail.com\"\n  }\n}\n```\n\n**返回格式**:\n\n```json\n{\n  \"联系邮箱\": [\n    {\n      \"text\": \"zhangmin@xxxgmail.com\",\n      \"type\": \"url\",\n      \"link\": \"mailto:zhangmin@xxxgmail.com\"\n    }\n  ]\n}\n```\n\n---\n\n## 数字 (type=2)\n\n**写入/返回格式**: 数字\n\n```json\n{\n  \"fields\": {\n    \"工时\": 10,\n    \"完成率\": 0.75,\n    \"预算\": 5000.50\n  }\n}\n```\n\n**注意**:\n- 进度 (ui_type=\"Progress\"): 0-1 范围的小数\n- 货币 (ui_type=\"Currency\"): 普通数字\n- 评分 (ui_type=\"Rating\"): 整数\n\n---\n\n## 单选 (type=3)\n\n**写入格式"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"飞书多维表格（Bitable）的创建、查询、编辑和管理工具。包含 27 种字段类型支持、高级筛选、批量操作和视图管理。 **当以下情况时使用此 Skill**： (1) 需要创建或管理飞书多维表格 App (2) 需要在多维表格中新增、查询、修改、删除记录（行数据） (3) 需要管理字段（列）、视图、数据表 (4... Skill: 飞书Bitable管理工具 Owner: a3152557994-ship-it Summary: 飞书多维表格（Bitable）的创建、查询、编辑和管理工具。包含 27 种字段类型支持、高级筛选、批量操作和视图管理。 **当以下情况时使用此 Skill**： (1) 需要创建或管理飞书多维表格 App (2) 需要在多维表格中新增、查询、修改、删除记录（行数据） (3) 需要管理字段（列）、视图、数据表 (4... Tags: latest:1.0.0 Version history: v1.0.0 | 2026-04-24T06:33:44.892Z | auto - 首发版本，支持飞书多维表格（Bitable）全功能操作 - 实现 27 种字段类型的表结构管理、查询和批量数据操作 - 提供详细字段格式、数据导入、筛选、并发、批量等最佳实践说明 - 补充常见错误码及排查，详解字段类型、导入格式和极易踩坑点 -","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":764,"uniquenessScore":47,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-12T01:51:19.454Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-12T01:51:19.454Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T17:34:36.601Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}