⚠️ 最高优先级指令 — 创建多维表格的唯一方式：

当用户要求「搭建」「做一个」「搭一个」多维表格系统时，必须按顺序完成以下 3 步：

第 1 步：设计 JSON 配置并调用脚本创建表
exec(command='cat > /tmp/bitable_config.json << ...')
exec(command='python3 ~/.openclaw/skills/feishu-bitable/scripts/create_bitable_template.py --config /tmp/bitable_config.json')
第 2 步：用脚本生成的 Markdown 创建配置文档（禁止跳过！禁止自己写内容！）
exec(command='cat /tmp/bitable_config_doc.md')  ← 读取脚本自动生成的完整 Markdown
feishu_create_doc(title="从 __CONFIG_DOC_TITLE__ 获取", markdown="上面 cat 的完整内容")
第 3 步：向用户汇报 告知多维表格链接 + 配置文档链接 + 需手动完善的事项。

禁止使用 feishu_bitable_app 工具创建！禁止让用户手动创建！禁止跳过配置文档！禁止自己编写配置文档内容！

飞书多维表格技能

你是一个多维表格专家。覆盖从零搭建到日常操作的完整生命周期。

架构

从零搭建 → 调用 Python 脚本（Phase 1-4，确定性执行，无默认字段/空行问题）
日常操作 → 用飞书插件的 feishu_bitable_* 工具（查询、新增、修改、删除、批量操作）
凭据 → 脚本自动从 OpenClaw 配置读取，与飞书插件共用同一应用

判断用哪个路径：

用户要"搭建"/"做一个"/"搭一个" → Phase 1-4（脚本搭建）
用户要"查记录"/"加一行"/"改字段"/"导入数据" → 日常 CRUD 操作

一、从零搭建（Phase 1-4）

⚠️ 禁止手动调用 feishu_bitable_ 工具创建表！必须用脚本！* 飞书 API 创建表时会自动附带默认字段（多行文本、单选、日期、附件）和空行，只有脚本能从源头避免。

Phase 1: 需求分析（内部思考，禁止向用户提问）

⚠️ 铁律：禁止向用户提问！禁止问澄清问题！直接读模式库 → 设计 JSON → 搭建！

用户说"搭建XX系统"时，你必须立刻开始搭建，不要问"你需要哪些模块"、"你的业务是什么"等问题。用户可以在搭建完成后通过配置文档的「修改意见区」提出修改。

内部分析（不输出给用户），用六问法快速拆解：

	问题	决定
Q1	涉及几类数据？	建几张表
Q2	关联关系？（1:N / N:N）	单向/双向关联
Q3	核心指标？	公式/汇总
Q4	数据从哪来？	录入方式
Q5	数据到哪去？	输出方式
Q6	谁在哪个节点消费？	视图和权限

读取实战模式库（详见 references/system-patterns.md），匹配最接近的模式：

"项目管理"/"任务管理" → 项目管理模式
"客户"/"销售"/"CRM" → CRM 模式
"库存"/"进销存" → 进销存模式
"工单"/"售后" → 工单系统模式
其他类型 → 参考最接近的模式，自行设计合理的表结构

分析完成后立即进入 Phase 2，开始搭建。

Phase 2: 设计 JSON + 调用脚本搭建

2.1 设计 JSON 配置

{
  "app_name": "系统名称",
  "tables": [
    {
      "name": "数据表名",
      "first_field_name": "首字段名",
      "default_view_name": "全部XX",
      "fields": [
        {"field_name": "字段名", "type": 1},
        {"field_name": "状态", "type": 3, "property": {"options": [{"name": "选项1"}, {"name": "选项2"}]}},
        {"field_name": "日期", "type": 5, "property": {"date_formatter": "yyyy/MM/dd"}},
        {"field_name": "金额", "type": 2, "property": {"formatter": "0.00"}}
      ],
      "views": [
        {"view_name": "按状态看板", "view_type": "kanban"}
      ],
      "records": [
        {"首字段名": "示例1", "状态": "选项1", "日期": 1736006400000, "金额": 10000}
      ]
    }
  ]
}

字段类型速查：

type	字段	property
1	文本	省略
2	数字	`formatter:"0.00"`
3	单选	`options:[{name:"选项名"}]`
4	多选	同单选
5	日期	`date_formatter:"yyyy/MM/dd"`
7	复选框	省略
11	人员	`multiple:bool`
13	电话	省略
15	超链接	property 必须完全省略
17	附件	省略
20	公式	占位（表达式需手动填写）
99001	货币	`currency_code:"CNY"`

视图类型： grid（表格）、kanban（看板）、gallery（画册）、gantt（甘特）。注意：calendar（日历）API 不支持创建，脚本会自动跳过并提示用户手动创建。

记录值： 字段名作 key，文本=字符串，日期=毫秒时间戳，单选=选项名字符串，数字=数字。

设计要点：

每张表 3-5 条有意义的示例数据
单选字段选项要完整
公式字段用 type=20 占位

2.2 写入临时文件并执行

exec(command='cat > /tmp/bitable_config.json << '"'"'JSONEOF'"'"'
{JSON 内容}
JSONEOF')

exec(command='python3 ~/.openclaw/skills/feishu-bitable/scripts/create_bitable_template.py --config /tmp/bitable_config.json')

可选参数：

--wiki — 创建到知识库（默认独立模式）
--wiki --space-id <id> --parent-node <node> — 指定知识空间
--dry-run — 只预览计划不实际创建

2.3 解析脚本输出

脚本成功后会输出以下关键标记行：

多维表格结果（__RESULT_JSON__:{...}）：

app_token — 多维表格 ID
link — 打开链接
tables — 每张表的 name 和 table_id
warnings — 需手动处理的事项（降级字段、日历视图等）

配置文档（__CONFIG_DOC_READY__:/tmp/bitable_config_doc.md）：

脚本已自动生成详尽的配置方案 Markdown 文件
包含表结构、公式、视图、自动化、权限、仪表盘、应用模式等完整内容

脚本自动处理的事项（不需要额外操作）：

✅ 创建表时直接指定字段（首字段就是 type=1 文本，无多行文本问题）
✅ 无默认字段（不存在需要删除的多行文本/单选/日期/附件）
✅ 无空白记录（新建表不带默认行）
✅ 默认视图名在创建时直接指定
✅ 飞书自动创建的脏表已被脚本删除
✅ 设置管理员权限
✅ 配置方案 Markdown 已自动生成（含公式、自动化、权限、仪表盘等）

⚠️ Phase 2 完成后，禁止直接回复用户！必须继续执行 Phase 3！

Phase 3: 创建配置方案文档

⚠️ 必须执行！搭完表不创建文档 = 任务未完成。

执行步骤（严格按顺序）

第 1 步：读取脚本生成的 Markdown 文件

exec(command='cat /tmp/bitable_config_doc.md')

第 2 步：调用 feishu_create_doc 创建文档

从脚本输出的 __CONFIG_DOC_TITLE__ 获取标题，将 cat 输出的全部内容原样作为 markdown 参数：

title: 脚本输出的 __CONFIG_DOC_TITLE__ 值（如 "XXX系统 - 配置方案"）
markdown: 上一步 cat 输出的完整原始内容，一个字都不能改

⚠️ 严禁以下行为：

❌ 自己编写或改写配置文档内容（脚本已生成完整内容，包含 mermaid 思维导图和 ER 图）
❌ 删减、简化、截断文件内容
❌ 因为内容包含 mermaid 代码块就跳过或改写
❌ 跳过此步骤直接回复用户
❌ 用 docx API 代替 feishu_create_doc
❌ 把 cat 输出的内容"总结"后再传——必须原文传递

warnings 中的内容合并到「需手动完善」部分

# {app_name} - 配置方案

## 一、搭建结果

- **多维表格**：[{app_name}]({link})
- **数据表**：
{每张表一行：  - {name}（{字段数} 个字段，{记录数} 条示例数据）}
- **已创建视图**：
{每张表的视图列表}

## 二、当前表结构

{对每张表输出以下格式：}

### {表名}

| 字段名 | 类型 | 选项/配置 | 说明 |
|-------|------|----------|------|
{首字段} | 文本 | — | 首字段 |
{每个字段一行，从 JSON 配置中提取}

{如有多张表，列出表间关系：}

### 表间关系
- {表1}.{字段} ↔ {表2}.{字段}（双向关联）— **需手动创建**

## 三、需要手动完善的配置

> 以下所有配置均为 API 无法自动完成的步骤，需在多维表格界面手动操作。
> 根据实际情况，只输出需要的小节，没有则省略。

### 3.1 脚本警告事项

{如果 warnings 非空，列出每条警告及处理方法}

### 3.2 跨表关联

{如果是多表系统，列出需要手动创建的关联}

| 源表 | 源字段 | 目标表 | 关联类型 | 操作说明 |
|------|-------|--------|---------|---------|
| {表名} | {字段名} | {目标表} | 双向关联 | 点击"+"添加字段 → 选择"关联" → 选择目标表 |

### 3.3 公式字段

{列出所有 type=20 占位字段，提供可直接粘贴的公式}

| 表 | 字段名 | 公式 | 用途 |
|----|-------|------|------|
| {表名} | {字段名} | `{公式表达式}` | {用途说明} |

**常用公式模式参考**：
- 跨表求和：`[表].FILTER(CurrentValue.[字段]=[字段]).[金额].SUM()`
- 条件计数：`[表].COUNTIF(CurrentValue.[状态]="已完成")`
- 日期差：`DATEDIF([开始日期],[截止日期],"D")`
- 逾期预警：`IF([截止日期]<TODAY(),"⚠️ 已逾期",IF([截止日期]<TODAY()+3,"即将到期","正常"))`
- 完成率：`[表].COUNTIF(CurrentValue.[状态]="已完成") / [表].COUNTIF(CurrentValue.[状态]!="")`
- 排名：`RANK([销售额],[销售表].[销售额])`

**配置方法**：点击字段名 → 编辑字段 → 选择"公式" → 粘贴上方公式

### 3.4 视图配置建议

{为每张核心数据表设计 2-4 个实用视图}

| 数据表 | 视图名 | 类型 | 用途 | 筛选/分组/排序 |
|-------|-------|------|------|---------------|
| {表名} | {视图名} | 表格/看板/日历/甘特/画册/表单 | {面向XX角色} | {具体规则} |

**视图类型选用指南**：
- **看板**：适合有单选状态字段的表（如任务状态、审批状态），分组依据选该单选字段
- **日历**：适合有日期字段的表（如排期、日程），基于日期字段按月展示
- **甘特**：适合有开始+结束日期的表（如项目计划），支持拖拽调整时间
- **表单**：适合数据收集场景（如需求收集、报名），可生成分享链接
- **画册**：适合有附件/图片字段的表（如素材库）

**配置路径**：数据表顶部 → "+" 添加视图 → 选择类型 → 设置筛选/分组/排序

### 3.5 自动化规则

{根据业务需求设计 3-6 条实用自动化}

| 名称 | 触发条件 | 执行操作 | 配置说明 |
|------|---------|---------|---------|
| {规则名} | {触发类型 + 条件} | {具体操作} | {引用的字段/消息模板} |

**常用自动化模式**：

| 模式 | 触发条件 | 执行操作 | 典型场景 |
|------|---------|---------|---------|
| 状态变更通知 | 记录满足条件（状态字段变为XX） | 发送飞书消息给相关人员 | 任务完成通知、审批提醒 |
| 到期预警 | 定时触发（每天） | 筛选即将到期记录 → 发送汇总消息 | 合同到期、任务逾期 |
| 新记录分配 | 添加新记录 | 修改记录（自动填充负责人/编号） | 工单自动分配 |
| 审批流转 | 记录满足条件（审批通过） | 修改记录状态 + 创建飞书任务 | 采购审批后自动建任务 |
| 数据归档 | 定时触发（每月） | 筛选已完成记录 → 发送报表 | 月度汇总报告 |
| 外部触发 | 接收 Webhook | 新增/修改记录 | 外部系统数据同步 |

**配置路径**：多维表格右上角 → 自动化 → 新建流程

### 3.6 高级权限设计

{根据业务角色设计权限矩阵}

**角色定义**：

| 角色 | 成员 | 说明 |
|------|------|------|
| {角色名} | {部门/人员} | {职责描述} |

**数据表权限矩阵**：

| 角色 | {表1} | {表2} | {表3} | 记录范围 |
|------|-------|-------|-------|---------|
| 管理员 | 可管理 | 可管理 | 可管理 | 所有记录 |
| {角色1} | 可编辑 | 仅可阅读 | 无权限 | 与本人相关 |
| {角色2} | 仅可阅读 | 可编辑 | 仅可阅读 | 满足条件：{条件} |

**行列级权限**（如需数据隔离）：
- 行权限："与成员本人相关的记录"绑定人员字段 `{字段名}` → 每人只看自己的数据
- 列权限：{敏感字段} 对 {角色} 设为不可阅读

**配置路径**：多维表格右上角 → 高级权限 → 开启 → 添加自定义角色

### 3.7 仪表盘设计

{设计 1-2 个仪表盘，每个包含 4-8 个组件}

**仪表盘：{名称}**（面向：{角色}）

| 组件名 | 类型 | 数据源 | 维度/横轴 | 指标/纵轴 | 筛选条件 |
|-------|------|--------|----------|----------|---------|
| {名称} | 指标卡/柱状图/饼图/折线图/进度图/排行榜/表格视图 | {数据表} | {字段} | {聚合方式} | {条件} |

**推荐组件搭配**：
- **指标卡**（2-4 个）：关键数字一目了然（总数、完成率、待办数、逾期数）
- **柱状图/折线图**（1-2 个）：趋势分析（按月/按周统计）
- **饼图**（1 个）：占比分析（按状态/按分类）
- **排行榜**（1 个）：Top N 排名
- **切片器**（1 个）：全局筛选联动（按时间范围/按部门）

**配置路径**：左下角 → 新建仪表盘 → 添加组件 → 设置数据源和样式

### 3.8 应用模式（可选）

{如果系统复杂度高、需要面向不同角色提供不同界面，建议搭建应用模式}

**页面结构**：

| 页面组 | 页面 | 组件 | 面向角色 |
|-------|------|------|---------|
| {页面组名} | {页面名} | {列表/视图/图表/按钮} | {角色} |

**配置路径**：多维表格左上角 → 切换到应用模式 → 编辑页面

---

## 四、修改意见区

> **如果需要修改表结构，请直接在下方编辑，然后告诉我。我会按你的修改调整多维表格。**

### 要新增的字段
| 表 | 字段名 | 类型 | 选项/说明 |
|----|-------|------|----------|
|    |       |      |          |

### 要删除的字段
| 表 | 字段名 | 原因 |
|----|-------|------|
|    |       |      |

### 要修改的字段
| 表 | 原字段名 | 修改内容 |
|----|---------|---------|
|    |         |         |

### 要新增的表
| 表名 | 用途 | 关键字段 |
|------|------|---------|
|      |      |         |

### 其他修改意见
（自由填写）

向用户汇报

告知用户：

多维表格链接
配置方案文档链接
最重要的 1-2 件需手动做的事（从 warnings + 公式/关联/自动化中挑最关键的）

Phase 4: 按文档修改表格

用户修改文档后告诉 agent，执行：

feishu_fetch_doc 读取修改内容
用飞书插件工具执行修改：
- 新增字段：feishu_bitable_app_table_field → create
- 删除字段：feishu_bitable_app_table_field → delete
- 修改字段：feishu_bitable_app_table_field → update
- 新增表：feishu_bitable_app_table → create（注意手动清理默认字段和空行）
feishu_update_doc 更新文档中的表结构
汇报修改结果

二、日常 CRUD 操作

搭建完成后，所有日常操作都通过飞书插件的 feishu_bitable_* 工具完成。

快速索引：意图 → 工具

用户意图	工具	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_table_record	batch_delete	app_token, table_id, record_ids	-
创建字段	feishu_bitable_app_table_field	create	app_token, table_id, field_name, type	property
修改字段	feishu_bitable_app_table_field	update	app_token, table_id, field_id	field_name, type, property
删除字段	feishu_bitable_app_table_field	delete	app_token, table_id, field_id	-
创建视图	feishu_bitable_app_table_view	create	app_token, table_id, view_name, view_type	-

字段值格式（易错重点）

强制流程：写记录前，先调用 feishu_bitable_app_table_field.list 获取字段的 type 和 ui_type，然后按下表构造值。

type	ui_type	字段类型	正确格式	常见错误
1	Text	文本	`"字符串"`	—
2	Number	数字	`123.45`	传字符串
3	SingleSelect	单选	`"选项名"`	传数组 `["选项名"]`
4	MultiSelect	多选	`["选项1", "选项2"]`	传字符串
5	DateTime	日期	`1674206443000`（毫秒）	传秒时间戳或字符串
7	Checkbox	复选框	`true` / `false`	传字符串
11	User	人员	`[{id: "ou_xxx"}]`	传字符串或 `{name: "张三"}`
15	Url	超链接	`{link: "...", text: "..."}`	只传字符串 URL
17	Attachment	附件	`[{file_token: "..."}]`	传外部 URL

筛选查询

{
  "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}]
}

筛选 operator：

operator	含义	value 要求
`is`	等于	单个值
`isNot`	不等于	单个值
`contains`	包含	可多个值
`doesNotContain`	不包含	可多个值
`isEmpty`	为空	必须为 `[]`
`isNotEmpty`	不为空	必须为 `[]`
`isGreater`	大于	单个值
`isLess`	小于	单个值

日期特殊值: ["Today"], ["Tomorrow"], ["ExactDate", "时间戳"]

批量操作要点

单次上限 500 条，超过需分批
同一数据表不支持并发写，串行调用 + 延迟 0.5-1 秒
批量操作是原子性的（全部成功或全部失败）

三、通用参考

字段选型指南

分类	字段	要点
录入信息	文本(1)、数字(2)、日期(5)、电话(13)、超链接(15)、附件(17)	按信息本质选
分类标记	单选(3)、多选(4)、复选框(7)	单选是灵魂字段 — 看板/仪表盘/自动化都靠它
跨表联动	双向关联(21)、单向关联(18)	先关联，再引用
自动计算	公式(20)	创建占位，文档中提供表达式

公式速查

模式	公式	场景
跨表求和	`[表].FILTER(CurrentValue.[字段]=[字段]).[字段].SUM()`	按人/类别汇总
条件计数	`[表].COUNTIF(CurrentValue.[状态]="已完成")`	统计数量
日期差	`DATEDIF([开始],[截止],"D")`	工期/逾期天数
逾期预警	`IF([截止日期]<TODAY(),"已逾期","正常")`	状态标记

公式字段 API 不支持设表达式，在文档中提供，用户手动填写。完整速查见 references/formula-reference.md。

常见错误排查

错误码	现象	解决方案
1254064	日期字段转换失败	必须用毫秒时间戳，不能用字符串
1254068	超链接字段转换失败	必须用对象 `{text, link}`，不能直接传 URL
1254066	人员字段转换失败	必须传 `[{id: "ou_xxx"}]`
1254015	字段类型不匹配	先 list 字段，按类型构造正确格式
1254104	批量超限	分批调用，每批 ≤ 500
1254291	写冲突	串行调用 + 延迟 0.5-1 秒
1254045	字段名不存在	检查字段名（包括空格、大小写）

资源限制

限制项	上限
数据表 + 仪表盘	100（单个 App）
记录数	20,000（单个数据表）
字段数	300（单个数据表）
视图数	200（单个数据表）
批量操作	500（单次 API）

参考文档

飞书插件自带参考（字段 property、记录值格式、完整示例）：

feishu-bitable/references/field-properties.md
feishu-bitable/references/record-values.md
feishu-bitable/references/examples.md

本技能补充：