SuperAPI AI Directory

feishu-task

General & other

View repository

Updated 10-15 22:33

About this skill

Feishu Task Management

🚨 Must-read before execution

  • ✅ Time format: ISO 8601 / RFC 3339 (with time zone), for example 2026-02-28T17:00:00+08:00
  • ✅ current_user_id strongly recommended: obtained from the SenderId in the message context (ou_...); the tool will automatically add it as a follower (if not already in members), ensuring the creator can edit the task
  • ✅ patch/get required:task_guid
  • ✅ tasklist.tasks required:tasklist_guid
  • ✅ Complete task:completed_at = "2026-02-26 15:00:00"
  • ✅ Uncomplete (restore to incomplete):completed_at = "0"

📋 Quick index: intent → tool → required parameters

User intent Tool action Required parameters Strongly recommended Common optional
Create to-do feishu_task_task create summary current_user_id(SenderId) members, due, description
Query incomplete tasks feishu_task_task list - completed=false page_size
Get task details feishu_task_task get task_guid - -
Complete task feishu_task_task patch task_guid, completed_at - -
Uncomplete task feishu_task_task patch task_guid, completed_at="0" - -
Change due time feishu_task_task patch task_guid, due - -
Create tasklist feishu_task_tasklist create name - members
View tasklist tasks feishu_task_tasklist tasks tasklist_guid - completed
Add tasklist members feishu_task_tasklist add_members tasklist_guid, members[] - -

🎯 Core constraints (knowledge not revealed by the Schema)

1. The current tool uses user identity (built-in protection)

The tool uses user_access_token(user identity)

This means:

  • ✅ When creating a task, you can specify any members (including assigning only to others)
  • ⚠️ You can only view and edittasks where you are a member
  • ⚠️ If you do not add yourself as a member when creating, you cannot edit the task afterward

Automatic protection mechanism:

  • Pass in the current_user_id parameter (obtained from SenderId)
  • If members does not contain current_user_id, the tool willautomatically add as a follower
  • Ensure the creator can always edit the task

Recommended usage: Always pass current_user_idwhen creating a task; the tool will automatically handle member relationships.

2. Description of task member roles

  • assignee: responsible for completing the task, can edit the task
  • follower: follows task progress, receives notifications

Example of adding members:

{
  "members": [
    {"id": "ou_xxx", "role": "assignee"},  // 负责人
    {"id": "ou_yyy", "role": "follower"}   // 关注人
  ]
}

Description:id uses the user's open_id(obtained from the SenderId in the message context)

3. Tasklist role conflict

Symptom: when creating a tasklist (tasklist.create), memberswas passed, but the returned tasklist.members is empty or missing members

Cause: the creator automatically becomes the tasklist owner(owner); if members includes the creator, that user ultimately becomes owner and is removed from members (the same user can only have one role)

Suggestion: do not include the creator in members ; only add other collaborating members

4. Three usages of completed_at

1) Complete a task (set the completion time):

{
  "action": "patch",
  "task_guid": "xxx",
  "completed_at": "2026-02-26 15:30:00"  // 北京时间字符串
}

2) Uncomplete (restore to incomplete status):

{
  "action": "patch",
  "task_guid": "xxx",
  "completed_at": "0"  // 特殊值 "0" 表示反完成
}

3) Millisecond timestamp(not recommended unless strictly generated by the upper layer):

{
  "completed_at": "1740545400000"  // 毫秒时间戳字符串
}

5. Roles of tasklist members

Member type Role Description
user owner Owner, can transfer ownership
user editor Can edit, can modify the tasklist and tasks
user viewer Can view, read-only permission
chat editor/viewer The entire group gets permission

Description: When creating a tasklist, the creator automatically becomes the owner; there is no need to specify this in members.


📌 Usage scenario examples

Scenario 1: Create a task and assign a person responsible

{
  "action": "create",
  "summary": "准备周会材料",
  "description": "整理本周工作进展和下周计划",
  "current_user_id": "ou_发送者的open_id",
  "due": {
    "timestamp": "2026-02-28 17:00:00",
    "is_all_day": false
  },
  "members": [
    {"id": "ou_协作者的open_id", "role": "assignee"}
  ]
}

Description:

  • summary is a required field
  • current_user_id is strongly recommended to be passed in (obtained from SenderId); the tool will automatically add it as a follower
  • members can contain only other collaborators; the current user will be added automatically
  • Time uses the Beijing time string format

Scenario 2: Query my incomplete tasks

{
  "action": "list",
  "completed": false,
  "page_size": 20
}

Scenario 3: Complete a task

{
  "action": "patch",
  "task_guid": "任务的guid",
  "completed_at": "2026-02-26 15:30:00"
}

Scenario 4: Uncomplete a task (restore to incomplete status)

{
  "action": "patch",
  "task_guid": "任务的guid",
  "completed_at": "0"
}

Scenario 5: Create a tasklist and add collaborators

{
  "action": "create",
  "name": "产品迭代 v2.0",
  "members": [
    {"id": "ou_xxx", "role": "editor"},
    {"id": "ou_yyy", "role": "viewer"}
  ]
}

Scenario 6: View incomplete tasks in a tasklist

{
  "action": "tasks",
  "tasklist_guid": "清单的guid",
  "completed": false
}

Scenario 7: All-day task

{
  "action": "create",
  "summary": "年度总结",
  "due": {
    "timestamp": "2026-03-01 00:00:00",
    "is_all_day": true
  }
}

🔍 Common errors and troubleshooting

Error symptom Root cause Solution
Cannot edit the task after creation Did not add yourself to members at creation time At creation time, add at least the current user (SenderId) as assignee or follower
patch fails with a task_guid missing message Did not pass the task_guid parameter patch/get must pass task_guid
tasks fails with a tasklist_guid missing message Did not pass the tasklist_guid parameter tasklist.tasks action must pass tasklist_guid
Uncomplete fails Incorrect completed_at format Use "0" string, not the number 0
Incorrect time Used a Unix timestamp Switch to ISO 8601 format (with time zone):2024-01-01T00:00:00+08:00

📚 Appendix: Background knowledge

A. Resource relationships

任务清单(Tasklist)
  └─ 自定义分组(Section,可选)
      └─ 任务(Task)
          ├─ 成员:负责人(assignee)、关注人(follower)
          ├─ 子任务(Subtask)
          ├─ 截止时间(due)、开始时间(start)
          └─ 附件、评论

Core concepts:

  • Task: an independent to-do item, with a unique task_guid
  • Tasklist: a container that organizes multiple tasks, with a unique tasklist_guid
  • assignee: can edit the task and mark it complete
  • follower: receives task update notifications
  • MyTasks: the collection of all tasks whose assignee is yourself

B. How to get the GUID

  • task_guid: after creating a task, get it from the return value's task.guid get it, or query via list query
  • tasklist_guid: After creating the list, get it from the return value's tasklist.guid , or query it via list to look up

C. How to add a task to a list

When creating a task, specify the tasklists parameter:

{
  "action": "create",
  "summary": "任务标题",
  "tasklists": [
    {
      "tasklist_guid": "清单的guid",
      "section_guid": "分组的guid(可选)"
    }
  ]
}

D. How to create recurring tasks

Use the repeat_rule parameter with RRULE format:

{
  "action": "create",
  "summary": "每周例会",
  "due": {"timestamp": "2026-03-03 14:00:00", "is_all_day": false},
  "repeat_rule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO"
}

Note: Only tasks with a due time set can have recurrence rules set.

E. Data permissions

  • You can only operate on tasks you have permission for (tasks you are a member of)
  • You can only operate on lists you have permission for (lists you are a member of)
  • Adding a task to a list requires edit permission for both the task and the list