feishu-task

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

飞书任务管理

Feishu Task Management

🚨 执行前必读

🚨 Pre-Execution Notes

✅ 时间格式：ISO 8601 / RFC 3339（带时区），例如
```
2026-02-28T17:00:00+08:00
```
✅ current_user_id 强烈建议：从消息上下文的 SenderId 获取（ou_...），工具会自动添加为 follower（如不在 members 中），确保创建者可以编辑任务
✅ patch/get 必须：task_guid
✅ tasklist.tasks 必须：tasklist_guid
✅ 完成任务：completed_at = "2026-02-26 15:00:00"
✅ 反完成（恢复未完成）：completed_at = "0"

✅ Time Format: ISO 8601 / RFC 3339 (with time zone), e.g.,
```
2026-02-28T17:00:00+08:00
```
✅ current_user_id Highly Recommended: Obtain from SenderId in message context. The tool will automatically add it as a follower (if not in members) to ensure 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"
✅ Revert Completion (Restore to Incomplete): completed_at = "0"

📋 快速索引：意图 → 工具 → 必填参数

📋 Quick Index: Intent → Tool → Required Parameters

用户意图	工具	action	必填参数	强烈建议	常用可选
新建待办	feishu_task_task	create	summary	current_user_id（SenderId）	members, due, description
查未完成任务	feishu_task_task	list	-	completed=false	page_size
获取任务详情	feishu_task_task	get	task_guid	-	-
完成任务	feishu_task_task	patch	task_guid, completed_at	-	-
反完成任务	feishu_task_task	patch	task_guid, completed_at="0"	-	-
改截止时间	feishu_task_task	patch	task_guid, due	-	-
创建清单	feishu_task_tasklist	create	name	-	members
查看清单任务	feishu_task_tasklist	tasks	tasklist_guid	-	completed
添加清单成员	feishu_task_tasklist	add_members	tasklist_guid, members[]	-	-

User Intent	Tool	action	Required Parameters	Highly 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	-	-
Revert Task Completion	feishu_task_task	patch	task_guid, completed_at="0"	-	-
Modify Due Date	feishu_task_task	patch	task_guid, due	-	-
Create Tasklist	feishu_task_tasklist	create	name	-	members
View Tasks in Tasklist	feishu_task_tasklist	tasks	tasklist_guid	-	completed
Add Tasklist Members	feishu_task_tasklist	add_members	tasklist_guid, members[]	-	-

🎯 核心约束（Schema 未透露的知识）

🎯 Core Constraints (Knowledge Not Disclosed in Schema)

1. 当前工具使用用户身份（已内置保护）

1. Tool Uses User Identity (Built-in Protection)

工具使用
user_access_token
（用户身份）

这意味着：

✅ 创建任务时可以指定任意成员（包括只分配给别人）
⚠️ 只能查看和编辑自己是成员的任务
⚠️ 如果创建时没把自己加入成员，后续无法编辑该任务

自动保护机制：

传入
```
current_user_id
```
参数（从 SenderId 获取）
如果
```
members
```
中不包含
```
current_user_id
```
，工具会自动添加为 follower
确保创建者始终可以编辑任务

推荐用法：创建任务时始终传

current_user_id

，工具会自动处理成员关系。

The tool uses
user_access_token
(user identity)

This means:

✅ You can assign any member when creating a task (including assigning to others only)
⚠️ You can only view and edit tasks where you are a member
⚠️ If you don't add yourself to members when creating, you won't be able to edit the task later

Automatic Protection Mechanism:

Pass the
```
current_user_id
```
parameter (obtained from SenderId)
If
```
current_user_id
```
is not in
```
members
```
, the tool will automatically add it as a follower
Ensures the creator can always edit the task

Recommended Usage: Always pass

current_user_id

when creating tasks, the tool will handle member relationships automatically.

2. 任务成员的角色说明

2. Task Member Role Explanation

assignee（负责人）：负责完成任务，可以编辑任务
follower（关注人）：关注任务进展，接收通知

添加成员示例：

json

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

说明：

id

使用用户的

open_id

（从消息上下文的 SenderId 获取）

assignee: Responsible for completing the task, can edit the task
follower: Follows task progress, receives notifications

Example of Adding Members:

json

{
  "members": [
    {"id": "ou_xxx", "role": "assignee"},  // Assignee
    {"id": "ou_yyy", "role": "follower"}   // Follower
  ]
}

Note: Use the user's

open_id

for

id

(obtained from SenderId in message context)

3. 任务清单角色冲突

3. Tasklist Member Role Conflict

现象：创建清单（

tasklist.create

）时传了

members

，但返回的

tasklist.members

为空或缺少成员

原因：创建人自动成为清单 owner（所有者），如果

members

中包含创建人，该用户最终成为 owner 并从

members

中移除（同一用户只能有一个角色）

建议：不要在

members

中包含创建人，只添加其他协作成员

Phenomenon: When creating a tasklist (

tasklist.create

) with

members

, the returned

tasklist.members

is empty or missing members

Reason: The creator automatically becomes the tasklist owner. If the creator is included in

members

, the user will finally be set as owner and removed from

members

(a user can only have one role)

Suggestion: Do not include the creator in

members

, only add other collaborative members

4. completed_at 的三种用法

4. Three Uses of completed_at

1) 完成任务（设置完成时间）：

json

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

2) 反完成（恢复未完成状态）：

json

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

3) 毫秒时间戳（不推荐，除非上层已严格生成）：

json

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

1) Complete Task (Set Completion Time):

json

{
  "action": "patch",
  "task_guid": "xxx",
  "completed_at": "2026-02-26 15:30:00"  // Beijing time string
}

2) Revert Completion (Restore to Incomplete State):

json

{
  "action": "patch",
  "task_guid": "xxx",
  "completed_at": "0"  // Special value "0" means revert completion
}

3) Millisecond Timestamp (Not recommended unless strictly generated by upper layer):

json

{
  "completed_at": "1740545400000"  // Millisecond timestamp string
}

5. 清单成员的角色

5. Tasklist Member Roles

成员类型	角色	说明
user（用户）	owner	所有者，可转让所有权
user（用户）	editor	可编辑，可修改清单和任务
user（用户）	viewer	可查看，只读权限
chat（群组）	editor/viewer	整个群组获得权限

说明：创建清单时，创建者自动成为 owner，无需在 members 中指定。

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

Note: When creating a tasklist, the creator automatically becomes the owner, no need to specify in members.

📌 使用场景示例

📌 Usage Scenario Examples

场景 1: 创建任务并分配负责人

Scenario 1: Create Task and Assign Assignee

json

{
  "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"}
  ]
}

说明：

```
summary
```
是必填字段
```
current_user_id
```
强烈建议传入（从 SenderId 获取），工具会自动添加为 follower
```
members
```
可以只包含其他协作者，当前用户会被自动添加
时间使用北京时间字符串格式

json

{
  "action": "create",
  "summary": "Prepare Weekly Meeting Materials",
  "description": "Organize this week's work progress and next week's plan",
  "current_user_id": "ou_sender's_open_id",
  "due": {
    "timestamp": "2026-02-28 17:00:00",
    "is_all_day": false
  },
  "members": [
    {"id": "ou_collaborator's_open_id", "role": "assignee"}
  ]
}

Explanation:

```
summary
```
is a required field
```
current_user_id
```
is highly recommended to pass (obtained from SenderId), the tool will automatically add it as a follower
```
members
```
can only include other collaborators, the current user will be added automatically
Use Beijing time string format

场景 2: 查询我负责的未完成任务

Scenario 2: Query Incomplete Tasks I'm Responsible For

json

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

json

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

场景 3: 完成任务

Scenario 3: Complete Task

json

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

json

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

场景 4: 反完成任务（恢复未完成状态）

Scenario 4: Revert Task Completion (Restore to Incomplete State)

json

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

json

{
  "action": "patch",
  "task_guid": "task_guid",
  "completed_at": "0"
}

场景 5: 创建清单并添加协作者

Scenario 5: Create Tasklist and Add Collaborators

json

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

json

{
  "action": "create",
  "name": "Product Iteration v2.0",
  "members": [
    {"id": "ou_xxx", "role": "editor"},
    {"id": "ou_yyy", "role": "viewer"}
  ]
}

场景 6: 查看清单内的未完成任务

Scenario 6: View Incomplete Tasks in Tasklist

json

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

json

{
  "action": "tasks",
  "tasklist_guid": "tasklist_guid",
  "completed": false
}

场景 7: 全天任务

Scenario 7: All-Day Task

json

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

json

{
  "action": "create",
  "summary": "Annual Summary",
  "due": {
    "timestamp": "2026-03-01 00:00:00",
    "is_all_day": true
  }
}

🔍 常见错误与排查

🔍 Common Errors and Troubleshooting

错误现象	根本原因	解决方案
创建后无法编辑任务	创建时未将自己加入 members	创建时至少将当前用户（SenderId）加为 assignee 或 follower
patch 失败提示 task_guid 缺失	未传 task_guid 参数	patch/get 必须传 task_guid
tasks 失败提示 tasklist_guid 缺失	未传 tasklist_guid 参数	tasklist.tasks action 必须传 tasklist_guid
反完成失败	completed_at 格式错误	使用 `"0"` 字符串，不是数字 0
时间不对	使用了 Unix 时间戳	改用 ISO 8601 格式（带时区）： `2024-01-01T00:00:00+08:00`

Error Phenomenon	Root Cause	Solution
Cannot edit task after creation	Did not add yourself to members when creating	At least add the current user (SenderId) as assignee or follower when creating
patch fails with task_guid missing prompt	Did not pass task_guid parameter	Must pass task_guid for patch/get
tasks fails with tasklist_guid missing prompt	Did not pass tasklist_guid parameter	Must pass tasklist_guid for tasklist.tasks action
Revert completion fails	Incorrect completed_at format	Use the string `"0"` , not the number 0
Incorrect time	Used Unix timestamp	Use ISO 8601 format (with time zone): `2024-01-01T00:00:00+08:00`

📚 附录：背景知识

📚 Appendix: Background Knowledge

A. 资源关系

A. Resource Relationships

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

核心概念：

任务（Task）：独立的待办事项，有唯一的
```
task_guid
```
清单（Tasklist）：组织多个任务的容器，有唯一的
```
tasklist_guid
```
负责人（assignee）：可以编辑任务并标记完成
关注人（follower）：接收任务更新通知
我负责的（MyTasks）：所有负责人为自己的任务集合

Tasklist
  └─ Custom Section (Optional)
      └─ Task
          ├─ Members: assignee, follower
          ├─ Subtask
          ├─ Due Date, Start Time
          └─ Attachments, Comments

Core Concepts:

Task: Independent to-do item with a unique
```
task_guid
```
Tasklist: Container for organizing multiple tasks with a unique
```
tasklist_guid
```
assignee: Can edit tasks and mark them as completed
follower: Receives task update notifications
MyTasks: Collection of all tasks where you are the assignee

B. 如何获取 GUID

B. How to Get GUID

task_guid：创建任务后从返回值的
```
task.guid
```
获取，或通过
```
list
```
查询
tasklist_guid：创建清单后从返回值的
```
tasklist.guid
```
获取，或通过
```
list
```
查询

task_guid: Obtain from
```
task.guid
```
in the return value after creating a task, or via
```
list
```
query
tasklist_guid: Obtain from
```
tasklist.guid
```
in the return value after creating a tasklist, or via
```
list
```
query

C. 如何将任务加入清单

C. How to Add Task to Tasklist

创建任务时指定

tasklists

参数：

json

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

Specify the

tasklists

parameter when creating a task:

json

{
  "action": "create",
  "summary": "Task Title",
  "tasklists": [
    {
      "tasklist_guid": "tasklist_guid",
      "section_guid": "section_guid (optional)"
    }
  ]
}

D. 重复任务如何创建

D. How to Create Recurring Tasks

使用

repeat_rule

参数，采用 RRULE 格式：

json

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

说明：只有设置了截止时间的任务才能设置重复规则。

Use the

repeat_rule

parameter in RRULE format:

json

{
  "action": "create",
  "summary": "Weekly Meeting",
  "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 date can set a repeat rule.

E. 数据权限

E. Data Permissions

只能操作自己有权限的任务（作为成员的任务）
只能操作自己有权限的清单（作为成员的清单）
将任务加入清单需要同时拥有任务和清单的编辑权限

Can only operate tasks you have permission for (tasks where you are a member)
Can only operate tasklists you have permission for (tasklists where you are a member)
Adding a task to a tasklist requires edit permissions for both the task and the tasklist