Feishu Bitasks Manager

飞书多维表格管理工具

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

特性

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

快速开始

1. 安装依赖

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：

   • 访问 飞书开放平台
   • 创建应用，获取 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 开头：需调用获取知识空间节点信息接口，不需要传递obj_type，响应体中的 obj_token 字段的值即为多维表格的 app_token。
   • 参考资料支撑：基于参考资料中《服务端 API / 云文档 / 多维表格 / 高级权限 / 协作者 / 新增协作者》（文档链接：https://go.feishu.cn/s/6acj3hKhU03）的内容，明确了不同 URL 形态下 app_token 的获取方式。

命令行使用

查看记录

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

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

查看记录详情

python scripts/feishu_bitasks.py show <record_id>

更新记录状态

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

创建记录

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

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

Python API 使用

基本使用

from feishu_bitasks import FeishuBitasks

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

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

获取记录列表

# 获取所有记录
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
   状态: 已完成

更新记录状态

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

创建记录

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

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

查看字段映射

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

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

AI 使用指南

典型工作流

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 创建记录（推荐）：

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 命令查看现有记录，了解表格结构
• 创建时只使用表格中已有的字段