⚠️ Highest priority instruction — the only way to create a Bitable:
When the user asks to "build", "make", "set up" a Bitable system,you must complete the following 3 steps in order：
Step 1: Design the JSON configuration and call the script to create the table
exec(command='cat > /tmp/bitable_config.json << ...') exec(command='python3 ~/.openclaw/skills/feishu-bitable/scripts/create_bitable_template.py --config /tmp/bitable_config.json')Step 2: Use the Markdown generated by the script to create the configuration document (skipping is prohibited! writing the content yourself is prohibited!)
exec(command='cat /tmp/bitable_config_doc.md') ← 读取脚本自动生成的完整 Markdown feishu_create_doc(title="从 __CONFIG_DOC_TITLE__ 获取", markdown="上面 cat 的完整内容")Step 3: Report to the user Inform them of the Bitable link + configuration document link + items that need manual completion.
Feishu Bitable SkillUsing the feishu_bitable_app tool to create is prohibited! Having the user create manually is prohibited! Skipping the configuration document is prohibited! Writing the configuration document content yourself is prohibited!
You are a Bitable expert. Coveringbuilding from scratchtodaily operationsthe complete lifecycle.
Architecture
- Building from scratch → call Python scripts (Phase 1-4, deterministic execution, no default field/empty row issues)
- Daily operations → use the Feishu plugin's
feishu_bitable_*tools (query, add, modify, delete, batch operations) - Credentials → the script automatically reads from the OpenClaw configuration, sharing the same app as the Feishu plugin
Determining which path to use:
- The user wants to "build"/"make"/"set up" → Phase 1-4 (script-based building)
- The user wants to "query records"/"add a row"/"change fields"/"import data" → daily CRUD operations
I. Building from scratch (Phase 1-4)
⚠️ Manually calling the feishu_bitable_ tool to create tables is prohibited! You must use the script!* When the Feishu API creates a table, it automatically attaches default fields (multi-line text, single select, date, attachment) and empty rows; only the script can avoid this at the source.
Phase 1: Requirements analysis (internal thinking, asking the user questions is prohibited)
⚠️ Iron rule: asking the user questions is prohibited! asking clarifying questions is prohibited! Directly read the pattern library → design JSON → build!
When the user says "build an XX system", you mustimmediately start building, do not ask questions such as "which modules do you need", "what is your business". After the build is complete, the user can propose modifications through the "Modification Suggestions Area" of the configuration document.
Internal analysis (not output to the user), quickly break it down using the six-question method:
| Question | Decision | |
|---|---|---|
| Q1 | How many types of data are involved? | How many tables to create |
| Q2 | Relationships? (1:N / N:N) | One-way/two-way link |
| Q3 | Core metrics? | Formula/rollup |
| Q4 | Where does the data come from? | Entry method |
| Q5 | Where does the data go? | Output method |
| Q6 | Who consumes it at which node? | Views and permissions |
Read the practical pattern library (see references/system-patterns.md), and match the closest pattern:
- "Project Management"/"Task Management" → Project Management pattern
- "Customer"/"Sales"/"CRM" → CRM pattern
- "Inventory"/"Invoicing and Inventory" → Invoicing and Inventory pattern
- "Work Order"/"After-sales" → Work Order System pattern
- Other types → Refer to the closest pattern and design a reasonable table structure yourself
After the analysis is complete, immediately proceed to Phase 2 and start building.
Phase 2: Design JSON + Call Script to Build
2.1 Design JSON Configuration
{
"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}
]
}
]
}
Field type quick reference:
| type | Field | property |
|---|---|---|
| 1 | Text | Omitted |
| 2 | Number | formatter:"0.00" |
| 3 | Single Select | options:[{name:"选项名"}] |
| 4 | Multi Select | Same as Single Select |
| 5 | Date | date_formatter:"yyyy/MM/dd" |
| 7 | Checkbox | Omitted |
| 11 | Person | multiple:bool |
| 13 | Phone | Omitted |
| 15 | Hyperlink | property must be completely omitted |
| 17 | Attachment | Omitted |
| 20 | Formula | Placeholder (expression must be filled in manually) |
| 99001 | Currency | currency_code:"CNY" |
View types: grid(Grid),kanban(Kanban),gallery(Gallery),gantt(Gantt). Note:calendar(Calendar) API does not support creation; the script will automatically skip it and prompt the user to create it manually.
Record values: Field names as keys, text = string, date = millisecond timestamp, single select = option name string, number = number.
Design points:
- 3-5 meaningful sample records per table
- Single select field options must be complete
- Formula fields use type=20 as a placeholder
2.2 Write to a Temporary File and Execute
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')
Optional parameters:
--wiki— Create to the knowledge base (default standalone mode)--wiki --space-id <id> --parent-node <node>— Specify the knowledge space--dry-run— Preview the plan only without actually creating
2.3 Parse Script Output
After the script succeeds, it will output the following key marker lines:
Bitable result（__RESULT_JSON__:{...}）：
app_token— Bitable IDlink— Open linktables— Each table'snameandtable_idwarnings— Items that need manual handling (degraded fields, calendar views, etc.)
Configuration document（__CONFIG_DOC_READY__:/tmp/bitable_config_doc.md）：
- The script has automatically generated a detailed configuration plan Markdown file
- Includes complete content such as table structures, formulas, views, automations, permissions, dashboards, application modes, etc.
Items automatically handled by the script (no additional action required):
- ✅ Specify fields directly when creating a table (the first field is type=1 text, with no multi-line text issue)
- ✅ No default fields (there is no multi-line text/single select/date/attachment that needs to be deleted)
- ✅ No blank records (new tables do not come with default rows)
- ✅ The default view name is specified directly at creation time
- ✅ Dirty tables automatically created by Feishu have been deleted by the script
- ✅ Set administrator permissions
- ✅ The configuration plan Markdown has been automatically generated (including formulas, automations, permissions, dashboards, etc.)
⚠️ After Phase 2 is complete, replying directly to the user is prohibited! You must continue to execute Phase 3!
Phase 3: Create the configuration plan document
⚠️ Must be executed! Building the tables without creating the document = task not completed.
Execution steps (strictly in order)
Step 1: Read the Markdown file generated by the script
exec(command='cat /tmp/bitable_config_doc.md')
Step 2: Call feishu_create_doc to create the document
From the script output's __CONFIG_DOC_TITLE__ get the title, and use the cat output'sentire content as-isas the markdown parameter:
title: the script output's__CONFIG_DOC_TITLE__value (e.g. "XXX System - Configuration Plan")markdown: the cat output's from the previous stepcomplete raw content, not a single character may be changed
⚠️ The following actions are strictly prohibited:
- ❌ Writing or rewriting the configuration document content yourself (the script has already generated the complete content, including the mermaid mind map and ER diagram)
- ❌ Deleting, simplifying, or truncating the file content
- ❌ Skipping or rewriting because the content contains mermaid code blocks
- ❌ Skipping this step and replying directly to the user
- ❌ Using the docx API instead of feishu_create_doc
- ❌ "Summarizing" the cat output before passing it — you mustpass the original text
warningsmerge the content in into the "Needs manual completion" section
# {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 应用模式（可选）
{如果系统复杂度高、需要面向不同角色提供不同界面，建议搭建应用模式}
**页面结构**：
| 页面组 | 页面 | 组件 | 面向角色 |
|-------|------|------|---------|
| {页面组名} | {页面名} | {列表/视图/图表/按钮} | {角色} |
**配置路径**：多维表格左上角 → 切换到应用模式 → 编辑页面
---
## 四、修改意见区
> **如果需要修改表结构，请直接在下方编辑，然后告诉我。我会按你的修改调整多维表格。**
### 要新增的字段
| 表 | 字段名 | 类型 | 选项/说明 |
|----|-------|------|----------|
| | | | |
### 要删除的字段
| 表 | 字段名 | 原因 |
|----|-------|------|
| | | |
### 要修改的字段
| 表 | 原字段名 | 修改内容 |
|----|---------|---------|
| | | |
### 要新增的表
| 表名 | 用途 | 关键字段 |
|------|------|---------|
| | | |
### 其他修改意见
（自由填写）
Report to the user
Inform the user of:
- Bitable link
- Configuration plan document link
- The 1-2 most important things that need to be done manually (pick the most critical from warnings + formulas/relations/automations)
Phase 4: Modify the tables according to the document
After the user modifies the document and tells the agent, execute:
feishu_fetch_docread the modified content- Use the Feishu plugin tools to execute the modifications:
- Add field:
feishu_bitable_app_table_field→ create - Delete field:
feishu_bitable_app_table_field→ delete - Modify field:
feishu_bitable_app_table_field→ update - Add table:
feishu_bitable_app_table→ create (note: manually clean up default fields and empty rows)
- Add field:
feishu_update_docupdate the table structure in the document- Report the modification results
II. Daily CRUD operations
After the build is complete, all daily operations are done through the Feishu plugin's feishu_bitable_* tool.
Quick index: intent → tool
| User intent | Tool | action | Required parameters | Common optional |
|---|---|---|---|---|
| See what fields a table has | feishu_bitable_app_table_field | list | app_token, table_id | - |
| Query records | feishu_bitable_app_table_record | list | app_token, table_id | filter, sort, field_names |
| Add a row | feishu_bitable_app_table_record | create | app_token, table_id, fields | - |
| Batch import | feishu_bitable_app_table_record | batch_create | app_token, table_id, records (≤500) | - |
| Update a row | feishu_bitable_app_table_record | update | app_token, table_id, record_id, fields | - |
| Batch update | feishu_bitable_app_table_record | batch_update | app_token, table_id, records (≤500) | - |
| Delete records | feishu_bitable_app_table_record | batch_delete | app_token, table_id, record_ids | - |
| Create field | feishu_bitable_app_table_field | create | app_token, table_id, field_name, type | property |
| Modify field | feishu_bitable_app_table_field | update | app_token, table_id, field_id | field_name, type, property |
| Delete field | feishu_bitable_app_table_field | delete | app_token, table_id, field_id | - |
| Create view | feishu_bitable_app_table_view | create | app_token, table_id, view_name, view_type | - |
Field value formats (key error-prone points)
Mandatory process: Before writing records, first call feishu_bitable_app_table_field.list to get the field's type and ui_type, then construct the value according to the table below.
| type | ui_type | Field type | Correct format | Common errors |
|---|---|---|---|---|
| 1 | Text | Text | "字符串" |
— |
| 2 | Number | Number | 123.45 |
Passing a string |
| 3 | SingleSelect | Single select | "选项名" |
Pass array ["选项名"] |
| 4 | MultiSelect | Multiple select | ["选项1", "选项2"] |
Pass string |
| 5 | DateTime | Date | 1674206443000(milliseconds) |
Pass second timestamp or string |
| 7 | Checkbox | Checkbox | true / false |
Pass string |
| 11 | User | Personnel | [{id: "ou_xxx"}] |
Pass string or {name: "张三"} |
| 15 | Url | Hyperlink | {link: "...", text: "..."} |
Pass only string URL |
| 17 | Attachment | Attachment | [{file_token: "..."}] |
Pass external URL |
Filter query
{
"action": "list",
"app_token": "S404b...",
"table_id": "tbl...",
"filter": {
"conjunction": "and",
"conditions": [
{
"field_name": "状态",
"operator": "is",
"value": ["进行中"]
},
{
"field_name": "截止日期",
"operator": "isLess",
"value": ["ExactDate", "1740441600000"]
}
]
},
"sort": [{"field_name": "截止日期", "desc": false}]
}
Filter operator:
| operator | Meaning | value requirements |
|---|---|---|
is |
Equals | Single value |
isNot |
Not equals | Single value |
contains |
Contains | Can be multiple values |
doesNotContain |
Does not contain | Can be multiple values |
isEmpty |
Is empty | Must be [] |
isNotEmpty |
Is not empty | Must be [] |
isGreater |
Greater than | Single value |
isLess |
Less than | Single value |
Special date values: ["Today"], ["Tomorrow"], ["ExactDate", "时间戳"]
Key points for batch operations
- Single limit 500 records, exceeding requires batching
- Same data tabledoes not support concurrent writes, serial calls + 0.5-1 second delay
- Batch operations areatomic(all succeed or all fail)
III. General reference
Field selection guide
| Category | Field | Key points |
|---|---|---|
| Data entry information | Text(1), Number(2), Date(5), Phone(13), Hyperlink(15), Attachment(17) | Choose according to the nature of the information |
| Classification tag | Single select(3), Multiple select(4), Checkbox(7) | Single select is the soul field — kanban/dashboard/automation all rely on it |
| Cross-table linkage | Two-way relation(21), One-way relation(18) | Relate first, then reference |
| Automatic calculation | Formula(20) | Create a placeholder, provide the expression in the document |
Formula quick reference
| Pattern | Formula | Scenario |
|---|---|---|
| Cross-table sum | [表].FILTER(CurrentValue.[字段]=[字段]).[字段].SUM() |
Summarize by person/category |
| Conditional count | [表].COUNTIF(CurrentValue.[状态]="已完成") |
Count quantity |
| Date difference | DATEDIF([开始],[截止],"D") |
Duration/overdue days |
| Overdue warning | IF([截止日期]<TODAY(),"已逾期","正常") |
Status marker |
The formula field API does not support setting expressions; provide them in the document for users to fill in manually. For the complete quick reference, see references/formula-reference.md。
Common error troubleshooting
| Error code | Symptom | Solution |
|---|---|---|
| 1254064 | Date field conversion failed | Must use millisecond timestamp, cannot use string |
| 1254068 | Hyperlink field conversion failed | Must use object {text, link}, cannot pass URL directly |
| 1254066 | Personnel field conversion failed | Must pass [{id: "ou_xxx"}] |
| 1254015 | Field type mismatch | List the fields first, then construct the correct format according to the type |
| 1254104 | Batch limit exceeded | Call in batches, each batch ≤ 500 |
| 1254291 | Write conflict | Serial calls + 0.5-1 second delay |
| 1254045 | Field name does not exist | Check the field name (including spaces and case) |
Resource limits
| Limit item | Upper limit |
|---|---|
| Data tables + dashboards | 100 (single App) |
| Number of records | 20,000 (single data table) |
| Number of fields | 300 (single data table) |
| Number of views | 200 (single data table) |
| Batch operations | 500 (single API call) |
Reference documentation
Built-in reference for the Feishu plugin (field property, record value format, complete examples):
feishu-bitable/references/field-properties.mdfeishu-bitable/references/record-values.mdfeishu-bitable/references/examples.md
Supplements in this skill:
- Practical pattern library — 4 sets of typical system table structures
- Formula quick reference
- Automation vs workflow
- Permission design
- Extended type mapping