feishu-bitable-creator

Create and populate Feishu (Lark) Bitable (multidimensional tables) with automated cleanup. Use when the user needs to: 1. Create a new Bitable from scratch with clean structure (no placeholder rows/columns) 2. Batch create fields and records in a Bitable 3. Convert structured data into a Bitable format 4. Create data tables for research, comparison, or tracking purposes Automatically handles: empty placeholder row cleanup, default column removal, intelligent primary field naming, and batch record creation.

# Feishu Bitable Creator

Creates clean, ready-to-use Feishu Bitable tables with automatic cleanup and data population.

## Authentication & Permissions

This skill requires a **pre-configured Feishu (Lark) integration** via OpenClaw's channel system. It does not accept API keys directly from the user.

### How Authentication Works

1. **Feishu Channel Configuration**: Your OpenClaw instance must have the Feishu channel enabled and configured with a valid app ID and app secret in `~/.openclaw/openclaw.json`:
   ```json
   {
     "channels": {
       "feishu": {
         "enabled": true,
         "appId": "cli_xxxxxxxxxxxxxxxx",
         "appSecret": "your-app-secret"
       }
     }
   }
   ```

2. **Token Management**: OpenClaw's Feishu extension automatically handles token acquisition and refresh using the configured app credentials. No manual token management is required.

3. **User Consent**: When creating a table, the tool uses the **agent's own identity** (the Feishu app/bot). The `addBitableAdmin()` function requires the owner's explicit `user_id` obtained from the conversation context, ensuring consent.

### Required Feishu App Permissions

Your Feishu app must have these permissions granted:

| Permission | Purpose |
|------------|---------|
| `bitable:app` | Create and manage Bitable apps |
| `drive:permission:manage` | Add users as admins to documents |
| `drive:drive:read` | Read drive contents |

### Security Notes

- ⚠️ **No User-Supplied Credentials**: This skill does NOT accept API keys, tokens, or secrets from user prompts. All authentication is handled through OpenClaw's secure channel configuration.
- ⚠️ **Scope Limitation**: The skill only performs actions on Bitable tables it creates. It cannot access existing tables without explicit sharing.
- ⚠️ **Admin Addition Requires Explicit User ID**: Adding an admin requires the specific `user_id` from conversation context — the agent cannot arbitrarily add unknown users.

### Setup Instructions

Before using this skill, ensure your OpenClaw host admin has:

1. Created a Feishu app at https://open.feishu.cn/app
2. Enabled the required permissions in the Feishu app console
3. Configured the app ID and secret in `~/.openclaw/openclaw.json`
4. Restarted the OpenClaw gateway to apply changes

For detailed setup, see: https://docs.openclaw.ai/channels/feishu

**Problem with default Bitable creation:**
- Feishu creates 10 empty placeholder rows by default
- Creates 4 default columns (文本, 单选, 日期, 附件) that are often unused
- Primary field is always named "文本" which is not descriptive
- Creator has full control, but human owner has no permissions

**This skill solves these issues:**
- ✅ Automatically deletes empty placeholder rows and default columns
- ✅ Intelligently renames primary field based on table name
- ✅ Adds owner as admin with full permissions
- ✅ Provides clean slate for your actual data

## Quick Start

```typescript
// 1. Create table (auto-cleans placeholder rows & default columns)
const table = await feishu_bitable_create_app({ name: "项目名称清单" });
// Returns: { app_token, url, table_id, primary_field_name, cleaned_placeholder_rows, cleaned_default_fields }

// 2. Add owner as admin (REQUIRED - get user_id from conversation context)
await addBitableAdmin({
  app_token: table.app_token,
  user_id: "ou_xxxxxxxxxxxxxxxx"  // Get from conversation context or Feishu user profile
});

// 3. Create RICH fields with tags/categories (建议根据场景选择)
// 参考 "Designing Rich Fields" 章节，选择适合的维度字段

// 4. Add records with complete tag information
await feishu_bitable_create_record({
  app_token: table.app_token,
  table_id: table.table_id,
  fields: {
    [table.primary_field_name]: "项目A",
    "标签": ["AI", "开源"],           // MultiSelect for filtering
    "分类": "技术",                   // SingleSelect for grouping
    "状态": "进行中",                 // SingleSelect for workflow
    "优先级": "高"                   // SingleSelect for sorting
  }
});

return table.url;
```

## Designing Rich Fields (发挥多维表格价值)

**💡 核心建议**: 为了让多维表格真正发挥作用，建议设计丰富的标签/分类字段，但**根据实际场景灵活选择**。

### 推荐的字段设计思路

根据数据类型，**考虑**添加以下维度字段：

| 数据场景 | 建议字段 | 用途 |
|---------|---------|------|
| **项目管理** | 状态、优先级、负责人、截止日期 | 追踪进展，分配任务 |
| **研究/调研** | 分类、标签、来源、评分 | 归类信息，评估价值 |
| **产品/功能** | 模块、优先级、状态、负责人 | 产品规划，迭代管理 |
| **客户/用户** | 类型、阶段、标签、负责人 | 客户分层，跟进管理 |
| **竞品分析** | 分类、评分、标签、来源 | 对比分析，筛选查看 |

### 字段类型选择指南

| 字段名 | 类型 | 适用场景 |
|--------|------|---------|
| **标签** | MultiSelect | 一个项目可属于多个类别，用于交叉筛选 |
| **分类** | SingleSelect | 一级分类，用于分组统计 |
| **状态** | SingleSelect | 有明确流转阶段，如待办→进行中→完成 |
| **优先级** | SingleSelect | 需要排序或区分重要性 |
| **负责人** | User | 需要分配到人 |
| **日期** | DateTime | 有时间节点要求 |
| **评分** | Number | 需要量化评估 |
| **来源** | SingleSelect | 需要追踪信息出处 |

### 实际设计示例

**示例1：开源大模型研究**
```typescript
const fields = [
  { name: "模型名称", type: 1 },
  { name: "开发团队", type: 1 },
  { name: "参数量", type: 1 },
  // 维度字段（根据数据特点选择）
  { name: "技术标签", type: 4 },      // ["MoE", "多语言", "代码", "轻量级"]
  { name: "地区", type: 3 },          // "美国"/"中国"/"欧洲"
  { name: "模型类型", type: 3 },      // "通用"/"代码"/"推理"
  { name: "适用场景", type: 4 },      // ["企业部署", "端侧运行", "科研"]
  { name: "开源协议", type: 3 },      // "Apache-2.0"/"MIT"
  { name: "发布日期", type: 5 },
  { name: "特点描述", type: 1 }
];
```

**示例2：工作任务清单**
```typescript
const fields = [
  { name: "任务名称", type: 1 },
  { name: "描述", type: 1 },
  // 维度字段
  { name: "分类", type: 3 },          // "技术"/"产品"/"运营"
  { name: "状态", type: 3 },          // "待办"/"进行中"/"已完成"
  { name: "优先级", type: 3 },        // "P0"/"P1"/"P2"
  { name: "负责人", type: 11 },       // @username
  { name: "截止日期", type: 5 },
  { name: "标签", type: 4 }           // ["紧急", "重要", "外部依赖"]
];
```

### 设计原则

1. **先想怎么用**：先思考用户会如何筛选/分组/排序数据
2. **适度原则**：字段不是越多越好，选择真正能区分数据的维度
3. **数据可得**：确保收集数据时能填上这些字段，不要设计无法获取的维度
4. **灵活调整**：如果某个字段使用率很低，后续可以删除或修改

### 检验标准

设计完字段后，问自己：
- ❓ 用户能按哪些维度筛选数据？
- ❓ 能按哪些维度分组查看？
- ❓ 能按哪些维度排序？
- ❓ 数据收集时这些字段是否容易获取？

如果以上问题都有明确答案，说明字段设计合理！

### 实际示例：开源大模型表格

```typescript
// 创建表格
const table = await feishu_bitable_create_app({ name: "全球开源大模型TOP10" });

// 添加管理员
await addBitableAdmin({ app_token: table.app_token, user_id: bossUserId });

// 创建丰富的字段（带标签/分类）
const fields = [
  { name: "排名", type: 2 },                                    // Number
  { name: "模型名称", type: 1 },                                // Text
  { name: "开发团队", type: 1 },                                // Text
  { name: "参数量", type: 1 },                                  // Text
  { name: "标签", type: 4, property: { options: [              // MultiSelect
    { name: "MoE" }, { name: "多语言" }, { name: "代码" }, 
    { name: "轻量级" }, { name: "推理优化" }, { name: "国产" }
  ]}},
  { name: "地区", type: 3, property: { options: [              // SingleSelect
    { name: "美国" }, { name: "中国" }, { name: "欧洲" }, 
    { name: "中东" }, { name: "其他" }
  ]}},
  { name: "类型", type: 3, property: { options: [               // SingleSelect
    { name: "通用模型" }, { name: "代码模型" }, { name: "推理模型" }
  ]}},
  { name: "开源协议", type: 3, property: { options: [           // SingleSelect
    { name: "Apache-2.0" }, { name: "MIT" }, { name: "Llama License" },
    { name: "Qwen License" }
  ]}},
  { name: "GitHub星标", type: 2 },                              // Number
  { name: "发布日期", type: 5 },                                // DateTime
  { name: "特点", type: 1 },                                    // Text
  { name: "适用场景", type: 4, property: { options: [           // MultiSelect
    { name: "企业部署" }, { name: "端侧运行" }, { name: "科学研究" },
    { name: "商业应用" }, { name: "教育学习" }
  ]}}
];

for (const field of fields) {
  await feishu_bitable_create_field({
    app_token: table.app_token,
    table_id: table.table_id,
    field_name: field.name,
    field_type: field.type,
    property: field.property
  });
}

// 添加带完整标签的数据
await feishu_bitable_create_record({
  app_token: table.app_token,
  table_id: table.table_id,
  fields: {
    [table.primary_field_name]: "Llama 3",
    "模型名称": "Llama 3",
    "排名": 1,
    "开发团队": "Meta",
    "参数量": "8B/