SuperAPI AI Directory

feishu-bitasks-manager

General & other

View repository

Updated 10-16 03:11

About this skill

Feishu Bitable Management Tool

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:

  1. 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
  2. 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"
  3. 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:

  1. You must first obtain the user's name(see above)
  2. Use the Python API to create records(recommended):
from feishu_bitasks import FeishuBitasks

feishu = FeishuBitasks()
record_id = feishu.create_record(
    title="记录标题",
    status="未开始",
    assignee="用户姓名"
)
  1. The priority field is optional: If there is no priority field in the table, do not set this parameter
  2. 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

  1. Configuration file separation
    • sensitive information(app_id, app_secret)→ assets/.feishu.json
    • table information(app_token, table_id)→ assets/config.json

File description

  • scripts/feishu_bitasks.py - Main program (single file)
  • SKILL.md - This documentation
  • assets/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_token and table_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_PATTERNS to 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 list command to view existing records and understand the table structure
  • When creating, use only fields that already exist in the table