# Feishu Bitasks Manager

> 飞书多维表格管理工具。智能识别字段，自动适应不同的表头结构。支持获取记录列表、创建记录、更新记录状态。适用于各类飞书多维表格项目。

- Skill: `orangon/feishu-bitasks-manager` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add orangon/feishu-bitasks-manager`
- Raw SKILL.md: https://api.skillmd.com/api/skills/orangon/feishu-bitasks-manager/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: orangon (https://skillmd.com/u/orangon)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/orangon/feishu-bitasks-manager

---


# 飞书多维表格管理工具

智能识别表格字段，自动适应不同的表头结构，便于 AI 获取和理解记录。
飞书端的配置方法见链接：https://open.feishu.cn/document/agile-project-cycle-management-based-on-bitable/introduction

## 特性

- ✅ **智能字段映射**：自动识别常见字段名（中英文）
- ✅ **灵活适应**：无需手动配置字段映射
- ✅ **支持多种字段类型**：文本、单选、多选、人员、日期等
- ✅ **简单易用**：提供命令行和 Python API


## 快速开始

### 1. 安装依赖

```bash
if ! pip show requests > /dev/null 2>&1; then
    echo "requests is not installed, installing it"
    pip install requests
    echo "requests installation completed!"
else
    echo "requests is already installed"
fi
```

### 2. 配置飞书凭据

**获取凭据**：

1. **App ID 和 App Secret**：
   - 访问 [飞书开放平台](https://open.feishu.cn/)
   - 创建应用，获取 App ID 和 App Secret
   - 添加权限：`bitable:app:readonly`、`bitable:app:write`

2. **多维表格的 app_token 和 table_id**：
   - 打开飞书多维表格
   - 从 URL 中获取：`https://feishu.cn/base/{app_token}/?table={table_id}`
   - 或右键点击表格，选择"查看 API 信息"

3. **备注**：
   - 若多维表格 URL 以 feishu.cn/base 开头：app_token 是 URL 中的高亮部分（如 URL 中 base/ 后的字符串）。
   - 若多维表格 URL 以 feishu.cn/wiki 开头：需调用获取[知识空间节点信息接口](https://go.feishu.cn/s/65W4PEw1g04)，不需要传递obj_type，响应体中的 obj_token 字段的值即为多维表格的 app_token。
   - 参考资料支撑：基于参考资料中《服务端 API / 云文档 / 多维表格 / 高级权限 / 协作者 / 新增协作者》（文档链接：https://go.feishu.cn/s/6acj3hKhU03）的内容，明确了不同 URL 形态下 app_token 的获取方式。

## 命令行使用

### 查看记录

```bash
# 查看所有记录
python scripts/feishu_bitasks.py list

# 查看前10条记录
python scripts/feishu_bitasks.py list --limit 10
```

### 查看记录详情

```bash
python scripts/feishu_bitasks.py show <record_id>
```

### 更新记录状态

```bash
python scripts/feishu_bitasks.py update <record_id> --status "已完成"
```

### 创建记录

```bash
# 基本用法
python scripts/feishu_bitasks.py create "记录标题"

# 完整用法
python scripts/feishu_bitasks.py create "记录标题" \
  --status "未开始" \
  --priority "高" \
  --description "记录描述" \
  --assignee "负责人姓名"
```

## Python API 使用

### 基本使用

```python
from feishu_bitasks import FeishuBitasks

# 初始化（会自动从配置文件加载凭据）
feishu = FeishuBitasks()

# 或者手动指定凭据
feishu = FeishuBitasks(
    app_id="xxx",
    app_secret="xxx",
    app_token="xxx",
    table_id="xxx"
)
```

### 获取记录列表

```python
# 获取所有记录
records = feishu.get_table_records()

# 获取前10条记录
records = feishu.get_table_records(limit=10)

# 格式化为 AI 易读的文本
text = feishu.format_records_for_ai(records)
print(text)
```

输出示例：
```
找到 3 个记录:

1. 实现用户登录功能
   ID: 1234567890
   状态: 进行中
   优先级: 高
   描述: 集成 JWT 认证
   负责人: 张三
   截止: 2026-01-25

2. 修复 API 响应错误
   ID: 1234567891
   状态: 待处理
   优先级: 中
   描述: 修复 /api/users 接口返回 500 错误

3. 更新项目文档
   ID: 1234567892
   状态: 已完成
```

### 更新记录状态

```python
# 更新记录状态（自动识别状态字段）
success = feishu.update_record_status("record_id", "已完成")
```

### 创建记录

```python
# 创建新记录
record_id = feishu.create_record(
    title="实现新功能",
    status="未开始",
    priority="高",
    description="功能描述",
    assignee="张三"
)

if record_id:
    print(f"记录创建成功，ID: {record_id}")
```

### 查看字段映射

```python
# 工具会自动检测并映射字段
# 支持的字段名变体：

# 记录名称: 记录名称、标题、记录、名称、title、name、task、summary
# 状态: 状态、进度、记录状态、status、state、progress
# 优先级: 优先级、priority
# 描述: 描述、详情、记录描述、说明、description、desc、detail
# 负责人: 负责人、执行人、指派给、assignee、owner、assigned
# 截止时间: 截止时间、截止日期、完成时间、due、deadline、due_date
```

## AI 使用指南

### 典型工作流

```python
from feishu_bitasks import FeishuBitasks

# 1. 获取用户姓名（必须步骤）
# AI: "请提供您的姓名"
user_name = "张三"  # 用户输入的姓名

# 2. 初始化
feishu = FeishuBitasks()

# 3. 获取该用户负责的记录
records = feishu.get_table_records()

# 4. 根据负责人过滤记录
user_tasks = [r for r in records
              if feishu.field_mapper.field_contains(r, "assignee", user_name)]

# 5. 显示记录列表
text = feishu.format_records_for_ai(user_tasks)
print(text)

# 6. 用户选择记录后更新状态
record_id = user_tasks[0]["record_id"]
feishu.update_record_status(record_id, "已完成")
```


### AI 友好的输出

工具会自动：
- 智能识别表格字段（无需手动配置）
- 格式化输出为易读文本
- 处理各种字段类型（单选、多选、人员、日期等）
- 只显示有值的字段（避免显示空字段）

### AI 创建记录规范

**创建记录时的注意事项**：

1. **必须先获取用户姓名**（见上文）
2. **使用 Python API 创建记录**（推荐）：
```python
from feishu_bitasks import FeishuBitasks

feishu = FeishuBitasks()
record_id = feishu.create_record(
    title="记录标题",
    status="未开始",
    assignee="用户姓名"
)
```

3. **优先级字段可选**：如果表格中没有优先级字段，不要设置该参数
4. **负责人姓名必须准确**：使用用户的真实姓名，工具会自动匹配飞书用户 ID

## 字段映射规则

工具会自动匹配以下字段（按优先级）：

### 标题字段
`记录名称` > `标题` > `记录` > `名称` > `title` > `name` > `task` > `summary`

### 状态字段
`状态` > `进度` > `记录状态` > `status` > `state` > `progress`

### 优先级字段
`优先级` > `priority`

### 描述字段
`描述` > `详情` > `记录描述` > `说明` > `description` > `desc` > `detail`

### 负责人字段
`负责人` > `执行人` > `指派给` > `assignee` > `owner` > `assigned`

### 截止时间字段
`截止时间` > `截止日期` > `完成时间` > `due` > `deadline` > `due_date`

## 安全注意事项

⚠️ **重要**：配置文件包含敏感信息

1. **配置文件分离**
   - **敏感信息**（app_id, app_secret）→ `assets/.feishu.json`
   - **表格信息**（app_token, table_id）→ `assets/config.json`


## 文件说明

- `scripts/feishu_bitasks.py` - 主程序（单文件）
- `SKILL.md` - 本说明文档
- `assets/config.json` - 项目表格配置（非敏感）

## 故障排查

### 问题：提示"未配置 app_token 或 table_id"

**解决**：
- 检查配置文件是否包含 `app_token` 和 `table_id`
- 确认配置文件路径正确

### 问题：字段识别不正确

**解决**：
- 工具会自动检测字段，支持常见的中英文字段名
- 如果字段名比较特殊，可以修改 `FieldMapper.FIELD_PATTERNS` 添加映射规则

### 问题：获取不到记录

**解决**：
- 检查飞书应用权限是否包含 `bitable:app:readonly`
- 确认 app_token 和 table_id 是否正确

### 问题：创建记录时提示"FieldNameNotFound"

**解决**：
- 检查表格中是否包含该字段（如"优先级"字段可能不存在）
- 先使用 `list` 命令查看现有记录，了解表格结构
- 创建时只使用表格中已有的字段