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

当用户要求「搭建」「做一个」「搭一个」多维表格系统时，必须按顺序完成以下 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系统"时，你必须立刻开始搭建，不要问"你需要哪些模块"、"你的业务是什么"等问题。 用户可以在搭建完成后通过配置文档的「修改意见区」提出修改。

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

读取实战模式库（详见 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}
      ]
    }
  ]
}

字段类型速查：

视图类型： 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. 配置方案文档链接
3. 最重要的 1-2 件需手动做的事（从 warnings + 公式/关联/自动化中挑最关键的）

Phase 4: 按文档修改表格

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

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

二、日常 CRUD 操作

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

快速索引：意图 → 工具

字段值格式（易错重点）

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

筛选查询

{
  "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：

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

批量操作要点

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

三、通用参考

字段选型指南

公式速查

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

常见错误排查

资源限制

参考文档

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

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

本技能补充：

• 实战模式库 — 4 套典型系统表结构
• 公式速查
• 自动化 vs 工作流
• 权限设计
• 扩展类型映射