feishu-task

Lark タスク管理

🚨 実行前に必ずお読みください

• ✅ 時間形式：ISO 8601 / RFC 3339（タイムゾーン付き）、例：2026-02-28T17:00:00+08:00
• ✅ 認証 ID：ツールは auth_type に user（デフォルト、ユーザー ID）または tenant（アプリ ID）を指定できます。
• ✅ タスク Agent（feishu_task_agent）：アプリ ID（tenant）のみ対応しており、user ID には対応していません
• ✅ current_user_id を強く推奨：メッセージコンテキストの SenderId（ou_...）から取得してください。ツールは（members に含まれていない場合）自動的に follower として追加し、作成者がタスクを編集できるようにします
• ✅ 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（アプリ ID）のみ対応	-
タスク Agent Profile を更新	feishu_task_agent	update_profile	profile_content	tenant（アプリ ID）のみ対応	-

---

🎯 主な制約（Schema からは分からない知識）

1. 認証 ID と表示範囲 (auth_type)

ツールは auth_type に 2 種類の呼び出し ID を指定できます：

• user（デフォルト）：ユーザー ID（user_access_token）。ユーザーを厳密に代表して操作する場合や、ユーザーの非公開タスクを照会する場合に使用します。
  • ⚠️ user ID を使用する場合、自分がメンバーであるタスクのみ表示および編集できます。
  • ⚠️ 作成時に自分をメンバーに追加していない場合、後からそのタスクを編集できません。
• tenant：アプリ ID（tenant_access_token）。ユーザー ID では要件を満たせない場合に使用します。作成したタスクにユーザーを追加していない場合、そのユーザーにタスクが表示されないことがあります。

自動保護の仕組み：

• current_user_id パラメーターを渡します（SenderId から取得）
• members に current_user_id が含まれていない場合、ツールは自動的に follower として追加します
• 作成者が常にタスクを編集および表示できるようにします

2. タスクメンバーの役割と種類

• 役割 (role)：
  • assignee（担当者）：タスクの完了を担当し、タスクを編集できます
  • follower（フォロワー）：タスクの進捗を確認し、通知を受け取ります
• 種類 (type)：
  • user（デフォルト、ユーザー）：一般的な Lark ユーザーです
  • app（アプリ／ボット）：ボット自身または他のアプリをタスクに追加する場合は、type: "app" を指定する必要があります

メンバー追加の例：

{
  "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 から削除されます（同じユーザーは 1 つの役割のみ持つことができます）

推奨事項：members に作成者を含めず、他の共同作業者のみを追加してください

4. completed_at の 3 つの使い方

1) タスクを完了（完了時刻を設定）：

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

2) 完了を取り消す（未完了の状態に戻す）：

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

3) ミリ秒単位のタイムスタンプ（上位レイヤーで厳密に生成される場合を除き、非推奨）：

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

5. リストメンバーの役割

メンバーの種類	役割	説明
user（ユーザー）	owner	オーナー。所有権を譲渡できます
user（ユーザー）	editor	編集可能。リストとタスクを変更できます
user（ユーザー）	viewer	表示のみ可能。読み取り専用の権限です
chat（グループ）	editor/viewer	グループ全体に権限が付与されます

説明：リストの作成時、作成者は自動的に owner になるため、members に指定する必要はありません。

---

📌 使用シーンの例

シーン 1: タスクを作成して担当者を割り当てる

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

説明：

• summary は必須フィールドです
• current_user_id の指定を強く推奨します（SenderId から取得）。ツールは自動的に follower として追加します
• members には他の共同作業者のみを指定できます。現在のユーザーは自動的に追加されます
• 時間にはタイムゾーン付きの ISO 8601 形式を使用してください

シーン 2: 自分が担当する未完了タスクを検索する

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

シーン 3: 既存のタスクにボットまたはメンバーを追加する

{
  "action": "add_members",
  "task_guid": "任务的guid",
  "auth_type": "tenant",
  "members": [
    {"id": "cli_机器人的app_id", "role": "follower", "type": "app"}
  ]
}

シーン 4: タスクを完了する

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

シーン 5: タスクの完了を取り消す（未完了の状態に戻す）

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

シーン 6: リストを作成して共同作業者を追加する

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

シーン 7: リスト内の未完了タスクを表示する

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

シーン 8: 終日タスク

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

シーン 9: タスク Agent を登録する（アプリ ID のみ）

{
  "action": "register",
  "auth_type": "tenant"
}

シーン 10: タスク Agent Profile を更新する（アプリ ID のみ）

{
  "action": "update_profile",
  "auth_type": "tenant",
  "profile_content": "some profile content"
}

---

🔍 常见错误与排查

错误现象	根本原因	解决方案
创建后无法编辑任务	创建时未将自己加入 members	创建时至少将当前用户（SenderId）加为 assignee 或 follower
patch 失败提示 task_guid 缺失	未传 task_guid 参数	patch/get/add_members 必须传 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
添加机器人失败	未指定成员 type 为 app	将机器人的 type 指定为 "app"

---

📚 附录：背景知识

A. 资源关系

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

核心概念：

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

B. 如何获取 GUID

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

C. 如何将任务加入清单

创建任务时指定 tasklists 参数：

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

D. 重复任务如何创建

使用 repeat_rule 参数，采用 RRULE 格式：

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

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

E. 数据权限

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