Feishu Task

# 飞书任务管理

## 🚨 执行前必读

- ✅ **时间格式**：ISO 8601 / RFC 3339（带时区），例如 `2026-02-28T17:00:00+08:00`
- ✅ **身份授权**：工具支持 `auth_type` 为 `user`（默认，用户身份）或 `tenant`（应用身份）。
- ✅ **任务 Agent（feishu_task_agent）**：仅支持应用身份（tenant），不支持 user 身份
- ✅ **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"
- ✅ **append_steps 的 task_steps[].timestamp**：秒级 Unix 时间戳（10 位），不要用毫秒（13 位）

---

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

| 用户意图 | 工具 | action | 必填参数 | 强烈建议 | 常用可选 |
|---------|------|--------|---------|---------|---------|
| 新建待办 | feishu_task_task | create | summary | current_user_id（SenderId） | members, due, description, auth_type |
| 查未完成任务 | feishu_task_task | list | - | completed=false | page_size, auth_type, agent_task_status |
| 获取任务详情 | feishu_task_task | get | task_guid | - | auth_type |
| 完成任务 | feishu_task_task | patch | task_guid, completed_at | - | auth_type |
| 反完成任务 | feishu_task_task | patch | task_guid, completed_at="0" | - | auth_type |
| 改截止时间 | feishu_task_task | patch | task_guid, due | - | auth_type |
| 添加任务成员 | feishu_task_task | add_members | task_guid, members[] | - | auth_type |
| 追加任务步骤记录 | feishu_task_task | append_steps | task_guid, idempotent_key, task_steps[] | task_steps[].timestamp 用秒级（10 位） | - |
| 创建清单 | feishu_task_tasklist | create | name | - | members |
| 查看清单任务 | feishu_task_tasklist | tasks | tasklist_guid | - | completed |
| 添加清单成员 | feishu_task_tasklist | add_members | tasklist_guid, members[] | - | - |
| 上传任务附件 | feishu_task_attachment | upload | resource_id, file(base64) | name | resource_type |
| 注册任务 Agent | feishu_task_agent | register | - | 仅支持 tenant（应用身份） | - |
| 更新任务 Agent Profile | feishu_task_agent | update_profile | profile_content | 仅支持 tenant（应用身份） | - |

---

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

### 1. 授权身份与可见性 (auth_type)

**工具支持两种调用身份 `auth_type`**：
- **`user` (默认)**：用户身份（user_access_token）。用于需要严格代表用户操作或查询用户私有任务的场景。
  - ⚠️ 使用 `user` 身份时，只能查看和编辑**自己是成员的任务**。
  - ⚠️ **如果创建时没把自己加入成员，后续无法编辑该任务**。
- **`tenant`**：应用身份（tenant_access_token）。当用户身份不满足要求时，使用应用身份。如果创建的任务没有把用户加入成员，用户可能看不见。

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

### 2. 任务成员的角色与类型

- **角色 (role)**：
  - **assignee（负责人）**：负责完成任务，可以编辑任务
  - **follower（关注人）**：关注任务进展，接收通知
- **类型 (type)**：
  - **user（默认，用户）**：普通的飞书用户
  - **app（应用/机器人）**：如果是把机器人自己或者其他应用加入任务，必须指定 `type: "app"`

**添加成员示例**：
```json
{
  "members": [
    {"id": "ou_xxx", "role": "assignee", "type": "user"},  // 负责人（用户）
    {"id": "cli_yyy", "role": "follower", "type": "app"}   // 关注人（机器人/应用）
  ]
}
```

**说明**：`id` 默认使用 `open_id`。

### 3. 任务清单角色冲突

**现象**：创建清单（`tasklist.create`）时传了 `members`，但返回的 `tasklist.members` 为空或缺少成员

**原因**：创建人自动成为清单 **owner**（所有者），如果 `members` 中包含创建人，该用户最终成为 owner 并从 `members` 中移除（同一用户只能有一个角色）

**建议**：不要在 `members` 中包含创建人，只添加其他协作成员

### 4. 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"  // 毫秒时间戳字符串
}
```

### 5. 清单成员的角色

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

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

--