Skill: young-joey/feishu-bitable-butler (version 1.0.2)

--- name: feishu-bitable-butler description: "飞书多维表格 AI 管家 — 自动化多维表格的数据清洗、批量录入、报表生成、字段管理和智能摘要。当用户需要操作飞书多维表格（Bitable）、批量处理表格数据、自动生成报表/周报、清洗整理数据、或管理多维表格结构时使用。触发词：多维表格、Bitable、飞书表格、自动报表、批量录入、数据清洗、飞书数据。" --- # 飞书多维表格 AI 管家 自动化飞书多维表格（Bitable）操作，让 Agent 成为你的表格管家。 ## 核心能力 ### 1. 表格结构管理 - 创建多维表格应用和表 - 增删字段（文本/数字/单选/多选/日期/人员/链接等） - 查看表格元数据和字段列表 ### 2. 数据批量操作 - 批量创建记录（支持格式自动适配） - 批量更新记录 - 分页查询和遍历 ### 3. 智能报表生成 - 从表格提取数据 → 生成摘要 - 按条件筛选 + 统计分析 - 自动写入报表结果到新表/新字段 ### 4. 数据清洗 - 格式标准化 - 去重检测 - 空值/异常值标记 --- ## 快速开始 ### 场景 1：接到一个飞书表格链接，不知道里面有什么 ``` 用户：帮我看看这个表格 https://abc.feishu.cn/base/XXX?table=YYY ``` 操作流程： 1. `feishu_bitable_get_meta` 解析 URL → 获取 app_token + table_id + 表列表 2. `feishu_bitable_list_fields` 列出所有字段 3. `feishu_bitable_list_records` 读取前 20 条数据 4. 总结表结构 + 数据概况 ### 场景 2：批量录入数据 ``` 用户：帮我在"客户跟进表"里录入这 5 条记录 张三 | 138xxxx | 意向客户 | 2026-05-07 李四 | 139xxxx | 已成交 | 2026-05-06 ... ``` 操作流程： 1. 先用 `feishu_bitable_list_fields` 确认字段名和类型 2. 按字段类型格式化数据： - 文本：直接传字符串 - 单选：传选项文本（如 `"意向客户"`） - 多选：传数组 `["A", "B"]` - 日期：传毫秒时间戳或 ISO 字符串 3. 逐条/批量调用 `feishu_bitable_create_record` 4. 完成后回报录入结果 ### 场景 3：从表格生成周报 ``` 用户：根据"本周任务"表给我生成周报 ``` 操作流程： 1. `feishu_bitable_list_fields` 了解字段 2. `feishu_bitable_list_records` 抓取全部记录（翻页直到无更多数据） 3. 分析数据：完成数、未完成数、关键成果 4. 格式化输出报告 5. 可选：用 `feishu_bitable_create_record` 将报告写入"周报"表 ### 场景 4：数据清洗 ``` 用户：帮我检查"员工信息表"里的数据有没有问题 ``` 操作流程： 1. 读取全量数据 2. 检查：空字段、手机号格式、日期范围、选项值是否在有效范围内 3. 标记异常记录 4. 可选：用 `feishu_bitable_update_record` 在"数据状态"字段标记 --- ## 字段类型速查 | 类型ID | 名称 | 数据格式 | |--------|------|---------| | 1 | 文本 | `"字符串"` | | 2 | 数字 | `123` | | 3 | 单选 | `"选项名"` | | 4 | 多选 | `["选项A", "选项B"]` | | 5 | 日期 | 毫秒时间戳（如 `1715040000000`） | | 7 | 复选框 | `true/false` | | 11 | 人员 | `[{id: "ou_xxx"}]` | | 13 | 手机号 | `"138xxxx"` | | 15 | 链接 | `{text: "显示", link: "https://..."}` | | 17 | 附件 | 文件token数组 | | 22 | 位置 | 经纬度对象 | 详见 [references/field-types.md](references/field-types.md) --- ## 最佳实践 1. **先看结构再动数据** — 每次操作前先 `list_fields` 确认字段名和类型 2. **翻页完整** — `list_records` 支持 `page_token` 翻页，确保读完所有数据 3. **批量优于逐条** — 多条数据合并为一次讲话，避免逐条单独调用 4. **写后验证** — 批量录入后抽样 `get_record` 验证 5. **异常先标记不直接删** — 数据清洗时优先标记问题，由人确认后再处理 --- ## 注意事项 - 需要飞书应用有 Bitable 权限（`bitable:app` scope） - 操作前确保 app_token 和 table_id 正确（从 URL 提取或由用户提供） - 大表操作注意分页，单页最多 500 条

path: references/examples.md
content: # 常见场景实例

## 场景 A：日报自动汇总

### 需求
员工每天在"工作日志"表录入今日完成事项，需要自动汇总到"日报汇总"表。

### 表结构（工作日志）
| 日期 | 姓名 | 完成事项 | 计划事项 | 遇到的问题 |
|------|------|---------|---------|-----------|

### 表结构（日报汇总）
| 日期 | 总完成数 | 总计划数 | 问题数 | 摘要 |

### AI 操作步骤
1. 搜索"日报汇总"→发现 25 人安装过 daily-report skill
2. `list_fields` → 确认字段名
3. `list_records` → 筛选今日记录
4. 统计：完成数 / 计划数 / 问题数
5. `create_record` → 写入汇总表
6. 可选：`feishu_chat` 发送到群聊

---

## 场景 B：客户信息清洗

### 需求
客户表有 500 条数据，需要检查手机号格式、去重、补全缺省字段。

### 检查规则
- 手机号：11 位数字，1 开头
- 邮箱：包含 @
- 状态字段：必须在 ["新客", "意向", "已成交", "流失"] 中
- 姓名/公司名：不能为空

### AI 操作步骤
1. `list_fields` → 获取字段列表
2. `list_records` (page_size=500) → 全量抓取
3. 逐行检查 → 标记异常类型
4. 将异常记录ID和问题类型写入"数据清洗结果"表
5. 输出清洗报告

---

## 场景 C：销售漏斗看板

### 需求
从"客户跟进表"生成销售漏斗数据。

### 客户跟进表字段
| 客户 | 阶段 | 金额 | 预计成交日期 | 负责人 |

### 漏斗输出
- 总客户数
- 各阶段客户数（新客→意向→报价→谈判→成交）
- 总金额（成交阶段）
- 预计本周/本月成交金额

### AI 操作步骤
1. `list_fields` → 确认阶段字段类型（单选）
2. `list_records` → 分页获取全量
3. 按阶段分组统计
4. 输出结构化报告

---

## 场景 D：员工信息管理

### 需求
批量更新员工部门、批量添加新员工。

### 批量更新
```
帮我把张三、李四的部门从"技术部"改成"产品部"
```

操作流程：
1. `list_records` → 找到张三、李四的记录ID
2. `update_record` → 分别更新部门字段

### 批量添加
```
帮我在员工表加3个人
王五 | 市场部 | 2026-05-07 | 高级经理
赵六 | 技术部 | 2026-05-07 | 工程师
```

操作流程：
1. `list_fields` → 确认字段名和类型
2. `create_record` → 逐条录入


path: references/field-types.md
content: # 飞书多维表格字段类型完整参考

## 基础字段

### 1. 文本 (Text)
- 类型ID: 1
- 数据格式: `"任意文本字符串"`
- 示例: `"张三"`, `"这是一段备注"`
- 限制: 最长 32000 字符

### 2. 数字 (Number)
- 类型ID: 2
- 数据格式: `123` 或 `123.45`
- 属性: 可设置小数位、货币格式、百分比
- 示例: `99.9`, `1000000`

### 3. 单选 (SingleSelect)
- 类型ID: 3
- 数据格式: `"选项名称"` （必须是预设选项之一）
- 示例: `"已完成"`, `"进行中"`, `"高优先级"`

### 4. 多选 (MultiSelect)
- 类型ID: 4
- 数据格式: `["选项A", "选项B"]` 数组
- 示例: `["技术部", "产品部"]`, `["Python", "JavaScript"]`

### 5. 日期时间 (DateTime)
- 类型ID: 5
- 数据格式: Unix 毫秒时间戳
- 示例: `1715040000000` (2026-05-07 00:00:00)
- 转换: `new Date("2026-05-07").getTime()`

### 7. 复选框 (Checkbox)
- 类型ID: 7
- 数据格式: `true` 或 `false`

### 11. 人员 (User)
- 类型ID: 11
- 数据格式: `[{"id": "ou_xxxx"}]` 或 `[{"id": "user_id_xxx"}]`
- 支持 open_id / user_id / union_id

### 13. 手机号 (Phone)
- 类型ID: 13
- 数据格式: `"13812345678"` 字符串

### 15. 链接 (URL)
- 类型ID: 15
- 数据格式: `{"text": "显示文字", "link": "https://example.com"}`

### 17. 附件 (Attachment)
- 类型ID: 17
- 数据格式: `[{"file_token": "xxx"}]` 文件token数组
- 需要先上传文件获取 token

### 18. 单向关联 (SingleLink)
- 类型ID: 18
- 数据格式: `{"table_id": "xxx", "record_ids": ["recxxx"]}`
- 关联到其他表的记录

### 21. 双向关联 (DuplexLink)
- 类型ID: 21
- 数据格式: 类似单向关联
- 两表同步关联

### 22. 位置 (Location)
- 类型ID: 22
- 数据格式: `{"location": {"latitude": 39.9, "longitude": 116.4}}`

### 23. 群聊 (GroupChat)
- 类型ID: 23
- 数据格式: `{"chat_id": "oc_xxx"}`

---

## 系统字段（只读）

| 类型ID | 名称 | 说明 |
|--------|------|------|
| 1001 | 创建时间 | 自动生成 |
| 1002 | 修改时间 | 自动更新 |
| 1003 | 创建人 | 自动生成 |
| 1004 | 修改人 | 自动更新 |
| 1005 | 自动编号 | 自增序列 |

---

## 常用时间戳转换

```javascript
// 日期 → 毫秒
Date.parse("2026-05-07") // 或 new Date("2026-05-07").getTime()

// 毫秒 → 日期
new Date(1715040000000).toISOString() // "2026-05-07T00:00:00.000Z"

// 中国时区 (+8)
new Date(1715040000000).toLocaleString("zh-CN")
```


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)