# Feishu Cli Bitable

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-ejjcc-agent-skills-feishu-cli-bitable`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ejjcc](https://agentstack.voostack.com/s/ejjcc)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ejjcc](https://github.com/ejjcc)
- **Source:** https://github.com/ejjcc/agent-skills/tree/main/feishu-cli-bitable

## Install

```sh
agentstack add skill-ejjcc-agent-skills-feishu-cli-bitable
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 飞书多维表格（Bitable）操作

## 前置条件

- **认证**：需要有效的 App Access Token（环境变量 `FEISHU_APP_ID` + `FEISHU_APP_SECRET`，或 `~/.feishu-cli/config.yaml`）
- **权限**：应用需开通 `bitable:app`（多维表格读写）
- **验证**：`feishu-cli auth status` 确认认证状态正常

## 核心概念

| 概念 | 说明 |
|------|------|
| **app_token** | 多维表格 URL 中 `/base/` 后的字符串，标识一个多维表格 |
| **table_id** | 数据表 ID，通过 `bitable tables` 获取 |
| **record_id** | 记录 ID，通过 `bitable records` 获取 |
| **field_id** | 字段 ID，通过 `bitable fields` 获取 |

**bitable ≠ sheet**：`feishu-cli bitable` 操作多维表格（Base），`feishu-cli sheet` 操作电子表格（Sheets），两者是完全不同的产品和 API。

## 命令速查

```bash
# === 多维表格 ===
feishu-cli bitable create --name "项目管理"
feishu-cli bitable create --name "数据库" --folder FOLDER_TOKEN
feishu-cli bitable get 

# === 数据表 ===
feishu-cli bitable tables 
feishu-cli bitable create-table  --name "任务表"
feishu-cli bitable rename-table   --name "新表名"
feishu-cli bitable delete-table  

# === 字段管理 ===
feishu-cli bitable fields  
feishu-cli bitable fields   -o json    # JSON 输出（含完整 property）
feishu-cli bitable create-field   --field '{"field_name":"状态","type":3,"property":{"options":[{"name":"进行中"},{"name":"已完成"}]}}'
feishu-cli bitable update-field    --field '{"field_name":"新名称","type":1}'
feishu-cli bitable delete-field   

# === 记录操作 ===
feishu-cli bitable records  
feishu-cli bitable records   --page-size 100
feishu-cli bitable records   --filter '{"conjunction":"and","conditions":[{"field_name":"状态","operator":"is","value":["进行中"]}]}'
feishu-cli bitable records   --sort '[{"field_name":"创建时间","desc":true}]'
feishu-cli bitable records   --field-names "名称,状态,金额"
feishu-cli bitable get-record   
feishu-cli bitable add-record   --fields '{"名称":"测试","金额":100,"状态":"进行中"}'
feishu-cli bitable add-records   --data '[{"名称":"A","金额":100},{"名称":"B","金额":200}]'
feishu-cli bitable add-records   --data-file records.json
feishu-cli bitable update-record    --fields '{"状态":"已完成"}'
feishu-cli bitable delete-records   --record-ids "recXXX,recYYY"

# === 视图管理 ===
feishu-cli bitable views  
feishu-cli bitable create-view   --name "看板" --type kanban
feishu-cli bitable delete-view   
```

**别名**：`feishu-cli base` 等同于 `feishu-cli bitable`。

## 字段类型速查

| type | 中文名 | 写入格式 | 示例 |
|------|--------|---------|------|
| 1 | 多行文本 | 字符串 | `"文本内容"` |
| 2 | 数字 | 数值 | `100`（不要传字符串 `"100"`） |
| 3 | 单选 | 字符串 | `"选项A"`（自动创建选项） |
| 4 | 多选 | 字符串数组 | `["A","B"]` |
| 5 | 日期 | 13 位毫秒时间戳 | `1770508800000` |
| 7 | 复选框 | 布尔值 | `true`（建议用单选替代） |
| 11 | 人员 | 对象数组 | `[{"id":"ou_xxx"}]` |
| 15 | 超链接 | 对象 | `{"text":"名称","link":"https://..."}` |
| 18 | 单向关联 | 字符串数组 | `["recuxxx"]` |

**不支持 API 写入**：公式、查找引用、创建时间、修改人、自动编号。

## 过滤运算符

| 运算符 | 说明 | 适用类型 |
|--------|------|---------|
| is | 等于 | 文本/单选/数字 |
| isNot | 不等于 | 文本/单选/数字 |
| contains | 包含 | 文本/多选 |
| doesNotContain | 不包含 | 文本/多选 |
| isEmpty | 为空 | 所有类型 |
| isNotEmpty | 不为空 | 所有类型 |
| isGreater | 大于 | 数字/日期 |
| isLess | 小于 | 数字/日期 |

## 踩坑必读

### 1. PUT fields 更新描述会清空单选选项

使用 `update-field` 更新单选（type=3）字段时，**必须带上完整的 property（含 options 列表）**，否则选项被清空，所有记录中该字段的值丢失。

**正确做法**：先用 `fields -o json` 获取当前字段定义，合并修改后再更新：

```bash
# 1. 获取当前字段定义
feishu-cli bitable fields   -o json

# 2. 更新时带上完整 property
feishu-cli bitable update-field    \
  --field '{"field_name":"状态","type":3,"property":{"options":[{"name":"待处理"},{"name":"进行中"},{"name":"已完成"}]},"description":{"text":"任务状态"}}'
```

### 2. 创建 Base 默认表有空行

`bitable create` 创建多维表格时自动创建一张默认表，里面有空记录（约 10 行）。写入数据前建议先清理：

```bash
# 1. 列出所有记录
feishu-cli bitable records   -o json

# 2. 找出空行的 record_id，批量删除
feishu-cli bitable delete-records   --record-ids "rec1,rec2,rec3"
```

### 3. 不要用复选框（Checkbox），用单选替代

复选框在 GUI 上容易误触。改用单选（type=3）配置"是/否"选项：

```bash
feishu-cli bitable create-field   \
  --field '{"field_name":"必填","type":3,"property":{"options":[{"name":"是"},{"name":"否"}]}}'
```

### 4. 主索引列重命名需带 type

重命名 `is_primary=true` 的字段时必须带 `type` 字段，否则报 `99992402`：

```bash
# 错误：缺少 type
feishu-cli bitable update-field ... --field '{"field_name":"新名称"}'

# 正确：带上 type
feishu-cli bitable update-field ... --field '{"field_name":"新名称","type":1}'
```

### 5. API 创建的表格默认不可见

通过 API 创建的多维表格默认只有机器人能看到。创建后必须立即添加权限：

**邮箱来源**：`~/.feishu-cli/config.yaml` 中的 `owner_email`，或环境变量 `FEISHU_OWNER_EMAIL`。

```bash
# 添加 full_access 权限
feishu-cli perm add  --doc-type bitable --member-type email --member-id  --perm full_access --notification
```

如果配置了 `transfer_ownership: true`，还需转移所有权：
```bash
feishu-cli perm transfer-owner  --doc-type bitable --member-type email --member-id 
```

### 6. 关联字段的局限

关联字段是"一列关联一张表"的设计，无法让不同行关联到不同子表。如果主表的不同记录需要对应到不同子表，直接靠**命名约定**（如工具名称 → 同名子表）更实用。

### 7. 数据格式注意

- **数值不要传字符串**：`100` 而非 `"100"`
- **日期必须是 13 位毫秒时间戳**：`1770508800000`
- **批量操作最多 500 条**：超出需要分批处理

## 典型工作流

### 创建项目管理表

```bash
# 1. 创建多维表格
feishu-cli bitable create --name "项目管理" -o json
# → app_token

# 2. 查看默认表
feishu-cli bitable tables 
# → table_id

# 3. 添加字段
feishu-cli bitable create-field   --field '{"field_name":"负责人","type":1}'
feishu-cli bitable create-field   --field '{"field_name":"状态","type":3,"property":{"options":[{"name":"待处理"},{"name":"进行中"},{"name":"已完成"}]}}'
feishu-cli bitable create-field   --field '{"field_name":"优先级","type":3,"property":{"options":[{"name":"P0"},{"name":"P1"},{"name":"P2"}]}}'
feishu-cli bitable create-field   --field '{"field_name":"截止日期","type":5}'

# 4. 清理默认空行
feishu-cli bitable records   -o json
feishu-cli bitable delete-records   --record-ids "..."

# 5. 批量写入数据
feishu-cli bitable add-records   --data '[
  {"标题":"完成需求文档","负责人":"张三","状态":"进行中","优先级":"P0"},
  {"标题":"代码审查","负责人":"李四","状态":"待处理","优先级":"P1"}
]'

# 6. 添加权限
feishu-cli perm add  --doc-type bitable --member-type email --member-id user@example.com --perm full_access --notification

# 7. 创建看板视图
feishu-cli bitable create-view   --name "状态看板" --type kanban
```

## API 限制

| 限制 | 说明 |
|------|------|
| 批量操作上限 | 单次最多 500 条记录 |
| 搜索分页 | page_size 最大 500 |
| 字段数量 | 单表最多 200 个字段 |
| 默认空行 | 新建表格自动创建约 10 行空记录 |
| 权限可见性 | API 创建的表格默认仅机器人可见 |

## 权限要求

| 功能 | 所需权限 |
|------|---------|
| 多维表格读写 | `bitable:app` |
| 权限管理 | `docs:permission.member:create` |
| 所有权转移 | `docs:permission.member:create` |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ejjcc](https://github.com/ejjcc)
- **Source:** [ejjcc/agent-skills](https://github.com/ejjcc/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ejjcc-agent-skills-feishu-cli-bitable
- Seller: https://agentstack.voostack.com/s/ejjcc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.