lark-task

task (v2)

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md，其中包含认证、权限处理

命令选择与渐进式发现（必读）

执行任何 Task 命令前，必须先确认能力真实存在，禁止根据用户意图自行拼接或猜测 +<verb>：

1. 先将用户意图与下方 Shortcut 表精确匹配。只有表中明确列出的 shortcut 才可直接选择；参数不确定时读取对应 reference 或运行该 shortcut 的 --help。
2. 没有精确匹配、或无法确认当前版本是否支持时，先运行 lark-cli task --help，以当前 CLI 输出的命令列表为准。
3. help 中存在匹配 shortcut 时，使用 help 列出的完整 shortcut token（例如 +create）运行 lark-cli task <shortcut> --help，再按真实 flag 执行。
4. help 中没有匹配 shortcut 时，不得尝试相似的 +<verb>；从 help 中选择原生 resource，运行 lark-cli task <resource> --help 确认 method，再运行 lark-cli schema task.<resource>.<method> 获取参数结构，最后调用 lark-cli task <resource> <method> ...。
5. 遇到 unknown_subcommand 时必须停止猜测或尝试变体，回到第 2 步重新发现能力。

shortcut 名称只能来自本 Skill 的 Shortcut 表或 lark-cli task --help；原生 resource/method 以逐级 help 为准，参数名、类型和嵌套结构以 method schema 为准。

任务分组定位（必读）：

• 在飞书任务/任务中心语境中，用户说“分组 / groups”时，优先对应 sections；任务清单对应 tasklists。先确定分组归属，再选择查询路径。
• 明确属于“我的任务”时，用 sections.list 的 my_tasks 归属和 --as user 查询，无需填写 --resource-id；明确属于某个清单时，用 tasklist 归属，并将该清单 GUID 传给 --resource-id。
• 归属不明时，先结合上下文判断，仍不明确再询问属于“我的任务”还是哪个清单；不要为了定位分组先遍历所有任务清单。
• 已知 section_guid 时，直接用 sections.tasks 查询组内任务；仅有分组名称时，先列取所属资源的分组并取得 guid。同名候选展示 GUID 和已知归属，不自动选择第一条。
• 分组操作的流程和 schema-first 示例见 分组操作参考。仅查询分组信息时，无需继续列取组内任务。

任务搜索技巧：先区分用户是否特地指定使用搜索 skill，以及是否真的提供了查询关键字（例如任务名称、关键词、片段描述）。如果用户特地指定使用搜索 skill，或明确给出了任务查询关键字，则目标是任务时优先使用 +search。如果用户没有特地指定使用搜索 skill，且意图里没有查询关键字，只有范围条件（例如“今年以来”“已完成”“由我创建”“我关注的”），并且使用 +search 与 +get-related-tasks / +get-my-tasks 都能达到目的时，应优先使用列表型能力，而不是搜索型能力。其中，“与我相关 / 我关注的 / 由我创建”等优先考虑 +get-related-tasks；“我负责的 / 分配给我”的列表优先考虑 +get-my-tasks。不要把时间范围词（例如“今年以来”）本身误当成 query 去走搜索。 任务搜索相关性提示：+search 当前不会自动判断搜索结果与搜索发起人的相关性。如果用户明确要求搜索“与我相关”的任务，必须先识别具体关系，获取当前用户的 open_id，并显式传入对应的 --assignee（负责人）、--creator（创建人）或 --follower（关注人）过滤条件；不能只依赖 query 期待自动返回与当前用户相关的任务。 任务清单搜索技巧：任务清单也遵循同样的判断逻辑。先区分用户是否特地指定使用搜索 skill，以及是否真的提供了清单查询关键字（例如清单名称、关键词、片段描述）。如果用户特地指定使用搜索 skill，或明确给出了清单查询关键字，则优先使用 +tasklist-search。如果用户没有特地指定使用搜索 skill，且意图里没有查询关键字，只有范围条件（例如“由我创建的任务清单”“今年以来创建的清单”），并且使用搜索或原生列取清单都能达到目的时，应优先使用原生 tasklists.list 接口列取清单（先 schema task.tasklists.list，再 lark-cli task tasklists list --as user ...），再按 creator、created_at 等字段做本地筛选和分页控制。 意图区分补充：像“搜索飞书中今年以来我关注的任务”这类表达，虽然字面带有“搜索”，但如果没有真正的查询关键字，且本质是在限定“与我相关 + 时间范围”，则应优先走 +get-related-tasks；像“搜索飞书中由我创建的任务清单”这类表达，如果没有清单关键字，且本质是在限定“清单范围 + 创建者”，则应优先走原生 tasklists.list 后筛选，而不是直接走搜索型 shortcut。 用户身份识别：在用户身份（user identity）场景下，如果用户提到了“我”（例如“分配给我”、“由我创建”），请默认获取当前登录用户的 open_id 作为对应的参数值。 术语理解 — 待办 disambiguation（必读）：

• 用户提到「待办 / todo / 任务」时，先判断归属，不要默认走本 skill。
• 走 lark-meeting 的 minutes +todo（禁止本 skill）：上下文含 妙记 / 会议纪要 / minute_token / 妙记 URL（/minutes/）；或「在某某妙记里新建/修改待办」「妙记 AI 待办」「会议录制里的待办」。
• 走本 skill（lark-task）：任务清单、分配给我、项目待办、截止日期/提醒、子任务、任务清单成员；或 applink 含 client/todo/task?guid=；或明确说「飞书任务」「任务中心」「我的任务清单」。
• 禁止：用户要在妙记里加待办时，不要调用 task tasklists list、task +create 或任何 task 命令去「找清单再放任务」。 友好输出：在输出任务（或清单）的执行结果给用户时，建议同时提取并输出命令返回结果中的 url 字段（任务链接），以便用户可以直接点击跳转查看详情。

创建/更新注意：

1. 只有在设置了 due（截止时间）的情况下，才能设置 repeat_rule（重复规则）和 reminder（提醒时间）。
2. 若同时设置了 start（开始时间）和 due（截止时间），开始时间必须小于或等于截止时间。
3. 使用 tenant_access_token（应用身份）时，无法跨租户添加任务成员。

查询注意：

1. 在输出任务详情时，如果需要渲染负责人、创建人等人员字段，除了展示 id (例如 open_id) 外，还必须通过其他方式（例如调用通讯录技能）尝试获取并展示这个人的真实名字，以便用户更容易识别。
2. 在输出清单详情时，如果需要渲染 owner、member、角色成员等人员字段，也必须像任务成员展示一样，除了展示 id 外，尽量解析并展示对应人员的真实名字。
3. 在输出任务或清单详情时，如果需要渲染创建时间、截止时间等字段，需要使用本地时区来渲染（格式为2006-01-02 15:04:05）。

Task GUID 定义： Task OpenAPI 中用于更新/操作任务的 guid 是任务的全局唯一标识（GUID），不是客户端展示的任务编号（例如 t104121 / suite_entity_num）。 对于 Feishu 的任务 applink（例如 .../client/todo/task?guid=...），必须使用 URL query 里的 guid 参数作为 task guid。

タスクリストから対象タスクを特定して更新する最短手順：

1. タスクリストの GUID が分かっている場合は直接使用し、先に検索しないでください。タスクリストの applink が分かっている場合は、URL の query に含まれる guid を tasklist_guid として使用します。
2. リスト名またはキーワードしか分からず、GUID／applink がない場合に限り、+tasklist-search を一度だけ呼び出して対象リストを特定します。
3. ネイティブ API のルールに従い、まず lark-cli schema task.tasklists.tasks を実行し、続けて lark-cli task tasklists tasks --params '{"tasklist_guid":"<tasklist_guid>"}' --as user を実行します。
4. リストのタスク結果から対象タスクの guid を取得し、+update または +complete に直接渡します。クライアントに表示される番号（例：t104121）は渡さないでください。これら 2 つのショートカットには、guid= を含むタスクの applink を直接渡すこともできます。
5. +update は updated_fields と、各タスクのサーバー側の confirmed フィールドを返します。+complete は status、completed_at、already_completed を返します。これらのフィールドで目標の状態が確認できた場合、慣例的に tasks get を追加実行する必要はありません。サーバーから必要なフィールドが返されない場合、またはユーザーが明示的に完全な再確認を求めた場合にのみ、詳細を照会してください。

ショートカット	説明
+create	タスクを作成する
+update	タスクの属性を更新する
+set-ancestor	タスクの親タスクを設定または解除する
+comment	タスクにコメントを追加する
+complete	タスクを完了としてマークする
+reopen	完了したタスクを再開する
+assign	タスクのメンバーを割り当てる、または削除する
+followers	タスクのフォロワーを管理する
+reminder	タスクのリマインダーを管理する
+get-my-tasks	自分に割り当てられたタスクを一覧表示する
+get-related-tasks	自分に関連するタスクを一覧表示する
+search	タスクを検索する
+upload-attachment	ローカルファイルをタスクの添付ファイルとしてアップロードする
+tasklist-create	タスクリストを作成し、必要に応じてタスクを追加する
+tasklist-search	タスクリストを検索する
+tasklist-task-add	タスクリストにタスクを追加する
+tasklist-members	タスクリストのメンバーを管理する

API リソース

lark-cli schema task.<resource>.<method>   # 调用 API 前必须先查看参数结构
lark-cli task <resource> <method> [flags] # 调用 API

重要：ネイティブ API を使用する場合は、必ず最初に schema を実行して --data ／ --params のパラメーター構造を確認してください。フィールド形式を推測しないでください。

tasks

• create — タスクを作成する
• delete — タスクを削除する
• get — タスクの詳細を取得する
• list — タスクのリストを取得する
• patch — タスクを更新する

tasklists

• add_members — リストにメンバーを追加する
• create — リストを作成する
• delete — リストを削除する
• get — リストの詳細を取得する
• list — リストの一覧を取得する
• patch — リストを更新する
• remove_members — リストからメンバーを削除する
• tasks — リストのタスク一覧を取得する

subtasks

• create — サブタスクを作成する
• list — タスクのサブタスク一覧を取得する

members

• add — タスクメンバーを追加する
• remove — タスクメンバーを削除する

sections

• create — カスタムグループを作成する
• delete — カスタムグループを削除する
• get — カスタムグループの詳細を取得する
• list — カスタムグループの一覧を取得する
• patch — カスタムグループを更新する
• tasks — カスタムグループのタスク一覧を取得する

custom_fields

• create — カスタムフィールドを作成する
• get — カスタムフィールドの詳細を取得する
• patch — カスタムフィールドを更新する
• list — カスタムフィールドの一覧を取得する
• add — カスタムフィールドをリソースに追加する
• remove — カスタムフィールドをリソースから削除する

custom_field_options

• create — カスタムフィールドのオプションを作成する
• patch — カスタムフィールドのオプションを更新する

agent

• update_agent_profile — タスクエージェントのホームページのコンテンツデータを更新する。
• register_agent — AI エージェントを登録する

agent_task_step_info

• append_task_steps — タスクの記録を書き込む。

权限表

方法	所需 scope
tasks.create	task:task:write
tasks.delete	task:task:write
tasks.get	task:task:read
tasks.list	task:task:read
tasks.patch	task:task:write
tasklists.add_members	task:tasklist:write
tasklists.create	task:tasklist:write
tasklists.delete	task:tasklist:write
tasklists.get	task:tasklist:read
tasklists.list	task:tasklist:read
tasklists.patch	task:tasklist:write
tasklists.remove_members	task:tasklist:write
tasklists.tasks	task:tasklist:read
subtasks.create	task:task:write
subtasks.list	task:task:read
members.add	task:task:write
members.remove	task:task:write
sections.create	task:section:write
sections.delete	task:section:write
sections.get	task:section:read
sections.list	task:section:read
sections.patch	task:section:write
sections.tasks	task:section:read
custom_fields.create	task:custom_field:write
custom_fields.get	task:custom_field:read
custom_fields.patch	task:custom_field:write
custom_fields.list	task:custom_field:read
custom_fields.add	task:custom_field:write
custom_fields.remove	task:custom_field:write
custom_field_options.create	task:custom_field:write
custom_field_options.patch	task:custom_field:write
agent.update_agent_profile	task:task:write
agent.register_agent	task:task:write
agent_task_step_info.append_task_steps	task:task:write