Intelligently recognizes table fields and automatically adapts to different header structures, making it easy for AI to retrieve and understand records. For configuration instructions on the Feishu side, see the link:https://open.feishu.cn/document/agile-project-cycle-management-based-on-bitable/introduction
Features
- ✅ Intelligent field mapping: Automatically recognizes common field names (Chinese and English)
- ✅ Flexible adaptation: No manual configuration of field mappings required
- ✅ Supports multiple field types: Text, single select, multiple select, people, date, etc.
- ✅ Simple and easy to use: Provides a command line and Python API
Quick Start
1. Install dependencies
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. Configure Feishu credentials
Obtain credentials:
-
App ID and App Secret:
- Visit Feishu Open Platform
- Create an app to obtain the App ID and App Secret
- Add permissions:
bitable:app:readonly、bitable:app:write
-
The Bitable's app_token and table_id:
- Open the Feishu Bitable
- Obtain from the URL:
https://feishu.cn/base/{app_token}/?table={table_id} - Or right-click the table and select "View API Information"
-
Note:
- If the Bitable URL starts with feishu.cn/base: the app_token is the highlighted part in the URL (e.g., the string after base/ in the URL).
- If the Bitable URL starts with feishu.cn/wiki: you need to call theknowledge space node information API. You do not need to pass obj_type; the value of the obj_token field in the response body is the Bitable's app_token.
- Reference support: Based on 《Server API / Cloud Documents / Bitable / Advanced Permissions / Collaborators / Add Collaborator》 in the reference materials (documentation link:https://go.feishu.cn/s/6acj3hKhU03)的内容,明确了不同 the method for obtaining app_token in this URL form.
Command Line Usage
View records
# 查看所有记录
python scripts/feishu_bitasks.py list
# 查看前10条记录
python scripts/feishu_bitasks.py list --limit 10
View record details
python scripts/feishu_bitasks.py show <record_id>
Update record status
python scripts/feishu_bitasks.py update <record_id> --status "已完成"
Create record
# 基本用法
python scripts/feishu_bitasks.py create "记录标题"
# 完整用法
python scripts/feishu_bitasks.py create "记录标题" \
--status "未开始" \
--priority "高" \
--description "记录描述" \
--assignee "负责人姓名"
Python API Usage
Basic usage
from feishu_bitasks import FeishuBitasks
# 初始化(会自动从配置文件加载凭据)
feishu = FeishuBitasks()
# 或者手动指定凭据
feishu = FeishuBitasks(
app_id="xxx",
app_secret="xxx",
app_token="xxx",
table_id="xxx"
)
Get record list
# 获取所有记录
records = feishu.get_table_records()
# 获取前10条记录
records = feishu.get_table_records(limit=10)
# 格式化为 AI 易读的文本
text = feishu.format_records_for_ai(records)
print(text)
Example output:
找到 3 个记录:
1. 实现用户登录功能
ID: 1234567890
状态: 进行中
优先级: 高
描述: 集成 JWT 认证
负责人: 张三
截止: 2026-01-25
2. 修复 API 响应错误
ID: 1234567891
状态: 待处理
优先级: 中
描述: 修复 /api/users 接口返回 500 错误
3. 更新项目文档
ID: 1234567892
状态: 已完成
Update record status
# 更新记录状态(自动识别状态字段)
success = feishu.update_record_status("record_id", "已完成")
Create record
# 创建新记录
record_id = feishu.create_record(
title="实现新功能",
status="未开始",
priority="高",
description="功能描述",
assignee="张三"
)
if record_id:
print(f"记录创建成功,ID: {record_id}")
View field mappings
# 工具会自动检测并映射字段
# 支持的字段名变体:
# 记录名称: 记录名称、标题、记录、名称、title、name、task、summary
# 状态: 状态、进度、记录状态、status、state、progress
# 优先级: 优先级、priority
# 描述: 描述、详情、记录描述、说明、description、desc、detail
# 负责人: 负责人、执行人、指派给、assignee、owner、assigned
# 截止时间: 截止时间、截止日期、完成时间、due、deadline、due_date
AI Usage Guide
Typical workflow
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-friendly output
The tool automatically:
- Intelligently recognizes table fields (no manual configuration required)
- Formats the output into easy-to-read text
- Handles various field types (single select, multiple select, people, date, etc.)
- Only displays fields with values (avoids displaying empty fields)
AI Record Creation Guidelines
Notes when creating records:
- You must first obtain the user's name(see above)
- Use the Python API to create records(recommended):
from feishu_bitasks import FeishuBitasks
feishu = FeishuBitasks()
record_id = feishu.create_record(
title="记录标题",
status="未开始",
assignee="用户姓名"
)
- The priority field is optional: If there is no priority field in the table, do not set this parameter
- The assignee name must be accurate: Use the user's real name; the tool will automatically match the Feishu user ID
Field Mapping Rules
The tool will automatically match the following fields (in order of priority):
Title field
记录名称 > 标题 > 记录 > 名称 > title > name > task > summary
Status field
状态 > 进度 > 记录状态 > status > state > progress
Priority field
优先级 > priority
Description field
描述 > 详情 > 记录描述 > 说明 > description > desc > detail
Assignee field
负责人 > 执行人 > 指派给 > assignee > owner > assigned
Due date field
截止时间 > 截止日期 > 完成时间 > due > deadline > due_date
Security notes
⚠️ Important: The configuration file contains sensitive information
- Configuration file separation
- sensitive information(app_id, app_secret)→
assets/.feishu.json - table information(app_token, table_id)→
assets/config.json
- sensitive information(app_id, app_secret)→
File description
scripts/feishu_bitasks.py- Main program (single file)SKILL.md- This documentationassets/config.json- Project table configuration (non-sensitive)
Troubleshooting
Issue: "app_token or table_id not configured" is displayed
Solution:
- Check whether the configuration file contains
app_tokenandtable_id - Confirm that the configuration file path is correct
Issue: Field recognition is incorrect
Solution:
- The tool automatically detects fields and supports common Chinese and English field names
- If the field name is unusual, you can modify
FieldMapper.FIELD_PATTERNSto add mapping rules
Issue: Unable to retrieve records
Solution:
- Check whether the Feishu app permissions include
bitable:app:readonly - Confirm whether app_token and table_id are correct
Issue: "FieldNameNotFound" is displayed when creating a record
Solution:
- Check whether the table contains that field (for example, the "Priority" field may not exist)
- First use the
listcommand to view existing records and understand the table structure - When creating, use only fields that already exist in the table