@lark-project/openclaw-lark-project 2026.3.131

package/dist/skills/feishu-fetch-doc/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: feishu-fetch-doc
+description: |
+  获取飞书云文档内容。返回文档的 Markdown 内容，支持处理文档中的图片、文件和画板（需配合 feishu_doc_media 工具）。
+---
+
+# feishu_mcp_fetch_doc
+
+获取飞书云文档的 Markdown 内容（Lark-flavored 格式）。
+
+## 重要：图片、文件、画板的处理
+
+**文档中的图片、文件、画板需要通过 `feishu_doc_media`（action: download）工具单独获取！**
+
+### 识别格式
+
+返回的 Markdown 中，媒体文件以 HTML 标签形式出现：
+
+- **图片**：
+  ```html
+  <image token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc" width="1833" height="2491" align="center"/>
+  ```
+
+- **文件**：
+  ```html
+  <view type="1">
+    <file token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc" name="skills.zip"/>
+  </view>
+  ```
+
+- **画板**：
+  ```html
+  <whiteboard token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc"/>
+  ```
+
+### 获取步骤
+
+1. 从 HTML 标签中提取 `token` 属性值
+2. 调用 `feishu_doc_media` 下载：
+   ```json
+   {
+     "action": "download",
+     "resource_token": "提取的token",
+     "resource_type": "media",
+     "output_path": "/path/to/save/file"
+   }
+   ```
+
+## 参数
+
+- **`doc_id`**（必填）：支持直接传文档 URL 或 token
+  - 直接传 URL：`https://xxx.feishu.cn/docx/Z1FjxxxxxxxxxxxxxxxxxxxtnAc`（系统自动提取 token）
+  - 直接传 token：`Z1FjxxxxxxxxxxxxxxxxxxxtnAc`
+  - 知识库 URL/token 也支持：`https://xxx.feishu.cn/wiki/Z1FjxxxxxxxxxxxxxxxxxxxtnAc` 或 `Z1FjxxxxxxxxxxxxxxxxxxxtnAc`
+
+## Wiki URL 处理策略
+
+知识库链接（`/wiki/TOKEN`）背后可能是云文档、电子表格、多维表格等不同类型的文档。当不确定类型时, **不能直接假设是云文档**，必须先查询实际类型。
+
+### 处理流程
+
+1. **先调用 `feishu_wiki_space_node`（action: get）解析 wiki token**：
+   ```json
+   { "action": "get", "token": "wiki_token_here" }
+   ```
+2. **从返回的 `node` 中获取 `obj_type`（实际文档类型）和 `obj_token`（实际文档 token）**
+3. **根据 `obj_type` 调用对应工具**：
+
+| obj_type | 工具 | 传参 |
+|----------|------|------|
+| `docx` | `feishu_mcp_fetch_doc` | doc_id = obj_token |
+| `sheet` | `feishu_sheet` | spreadsheet_token = obj_token |
+| `bitable` | `feishu_bitable_*` 系列 | app_token = obj_token |
+| 其他 | 告知用户暂不支持该类型 | — |
+
+
+### 示例
+
+用户：`帮我看下这个文档 https://xxx.feishu.cn/wiki/ABC123`
+
+1. 调用 `feishu_wiki_space_node`（action: get, token: ABC123）
+2. 返回 `obj_type: "docx"`, `obj_token: "doxcnXYZ789"`
+3. 调用 `feishu_mcp_fetch_doc`（doc_id: doxcnXYZ789）
+
+## 工具组合
+
+| 需求 | 工具 |
+|------|------|
+| 获取文档文本 | `feishu_mcp_fetch_doc` |
+| 下载图片/文件/画板 | `feishu_doc_media`（action: download） |
+| 解析 wiki token 类型 | `feishu_wiki_space_node`（action: get） |
+| 读写电子表格 | `feishu_sheet` |
+| 操作多维表格 | `feishu_bitable_*` 系列 |

package/dist/skills/feishu-im-read/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: feishu-im-read
+description: |
+  飞书 IM 消息读取工具使用指南，覆盖会话消息获取、话题回复读取、跨会话消息搜索、图片/文件资源下载。
+
+  **当以下情况时使用此 Skill**:
+  (1) 需要获取群聊或单聊的历史消息
+  (2) 需要读取话题（thread）内的回复消息
+  (3) 需要跨会话搜索消息（按关键词、发送者、时间等条件）
+  (4) 消息中包含图片、文件、音频、视频，需要下载
+  (5) 用户提到"聊天记录"、"消息"、"群里说了什么"、"话题回复"、"搜索消息"、"图片"、"文件下载"
+  (6) 需要按时间范围过滤消息、分页获取更多消息
+---
+
+# 飞书 IM 消息读取
+
+## 执行前必读
+
+- 该 Skill 中的所有消息读取工具均以用户身份调用，只能读取用户有权限的会话
+- `feishu_im_user_get_messages` 中 `open_id` 和 `chat_id` 必须二选一
+- 消息中出现 `thread_id` 时，根据用户意图判断是否用 `feishu_im_user_get_thread_messages` 读取话题内回复
+- 以用户身份读取后，如果消息内容中出现资源标记时，用 `feishu_im_user_fetch_resource` 下载，需要 `message_id` + `file_key` + `type`
+
+---
+
+## 快速索引：意图 → 工具
+
+| 用户意图 | 工具 | 必填参数 | 常用可选 |
+|---------|------|---------|---------|
+| 获取群聊/单聊历史消息 | feishu_im_user_get_messages | chat_id 或 open_id（二选一） | relative_time, start_time/end_time, page_size, sort_rule |
+| 获取话题内回复消息 | feishu_im_user_get_thread_messages | thread_id（omt_xxx） | page_size, sort_rule |
+| 跨会话搜索消息 | feishu_im_user_search_messages | 至少一个过滤条件 | query, sender_ids, chat_id, relative_time, start_time/end_time, page_size |
+| 下载消息中的图片 | feishu_im_user_fetch_resource | message_id, file_key（img_xxx）, type="image" | - |
+| 下载消息中的文件/音频/视频 | feishu_im_user_fetch_resource | message_id, file_key（file_xxx）, type="file" | - |
+
+---
+
+## 核心约束
+
+### 1. 时间范围：确保消息覆盖完整
+
+当用户没有明确指定时间范围时，根据用户意图推断合适的 `relative_time`，确保返回的消息能完整覆盖用户关心的内容。用户明确指定时间时直接使用用户的值。
+
+### 2. 分页：根据需要翻页获取更多结果
+
+- `page_size` 范围 1-50，默认 50
+- 返回结果中 `has_more=true` 时，可使用 `page_token` 继续获取下一页
+- 根据用户需求判断是否需要翻页：需要完整结果时继续翻页，浏览概览时第一页通常够用
+
+### 3. 话题回复：主动展开话题获取上下文
+
+获取历史消息时，返回的消息中如果包含 `thread_id` 字段，推荐主动获取话题的最新 10 条回复（`page_size: 10, sort_rule: "create_time_desc"`）以提供更完整的上下文。
+
+| 场景 | 行为 |
+|------|------|
+| 获取历史消息并需要理解上下文（默认） | 对发现的 thread_id 调用 `feishu_im_user_get_thread_messages` 获取最新 10 条回复 |
+| 用户要求"完整对话"、"详细讨论"、"看看回复" | 获取话题全部回复（`page_size: 50, sort_rule: "create_time_asc"`），需要时翻页 |
+| 用户只浏览消息概览 / 用户明确说不看回复 | 跳过话题展开 |
+
+**注意**：话题消息不支持时间过滤（飞书 API 限制），只能通过分页获取。
+
+### 4. 跨会话消息搜索
+
+`feishu_im_user_search_messages` 支持跨所有会话搜索消息：
+
+| 参数 | 说明 |
+|------|------|
+| `query` | 搜索关键词，匹配消息内容 |
+| `sender_ids` | 发送者 open_id 列表 |
+| `chat_id` | 限定搜索范围的会话 ID |
+| `mention_ids` | 被@用户的 open_id 列表 |
+| `message_type` | 消息类型：file / image / media |
+| `sender_type` | 发送者类型：user / bot / all（默认 user） |
+| `chat_type` | 会话类型：group / p2p |
+
+搜索结果每条消息额外包含 `chat_id`、`chat_type`（p2p/group）、`chat_name`。单聊消息还有 `chat_partner`（对方 open_id 和名字）。
+
+### 5. 图片/文件/媒体资源的提取
+
+消息内容中可能出现以下资源标记，用 `feishu_im_user_fetch_resource` 下载：
+
+| 资源类型 | 内容中的标记格式 | fetch_resource 参数 |
+|---------|-----------------|-------------------|
+| 图片 | `![image](img_xxx)` | message_id=`om_xxx`, file_key=`img_xxx`, type=`"image"` |
+| 文件 | `<file key="file_xxx" .../>` | message_id=`om_xxx`, file_key=`file_xxx`, type=`"file"` |
+| 音频 | `<audio key="file_xxx" .../>` | message_id=`om_xxx`, file_key=`file_xxx`, type=`"file"` |
+| 视频 | `<video key="file_xxx" .../>` | message_id=`om_xxx`, file_key=`file_xxx`, type=`"file"` |
+
+从消息的 `message_id` 字段和内容中的 `file_key` 组合即可调用 fetch_resource。
+
+**注意**：文件大小限制 100MB，不支持下载表情包、卡片中的资源。
+
+### 6. 时间过滤
+
+`feishu_im_user_get_messages` 和 `feishu_im_user_search_messages` 支持时间过滤，话题消息不支持。
+
+| 方式 | 参数 | 示例 |
+|------|------|------|
+| 相对时间 | `relative_time` | `today`、`yesterday`、`this_week`、`last_3_days`、`last_24_hours` |
+| 精确时间 | `start_time` + `end_time` | ISO 8601 格式：`2026-02-27T00:00:00+08:00` |
+
+- `relative_time` 和 `start_time/end_time` **互斥**，不能同时使用
+- 可用的 relative_time 值：`today`、`yesterday`、`day_before_yesterday`、`this_week`、`last_week`、`this_month`、`last_month`、`last_{N}_{unit}`（unit: minutes/hours/days）
+
+### 7. open_id 与 chat_id 的选择
+
+| 参数 | 格式 | 适用场景 |
+|------|------|---------|
+| chat_id | `oc_xxx` | 已知会话 ID（群聊或单聊均可） |
+| open_id | `ou_xxx` | 已知用户 ID，获取与该用户的单聊消息（自动解析为 chat_id） |
+
+两者必须二选一，优先使用 `chat_id`。
+
+---
+
+## 使用场景示例
+
+### 场景 1: 获取群聊消息并展开话题
+
+**步骤 1**：获取群聊消息
+```json
+{ "chat_id": "oc_xxx" }
+```
+
+**步骤 2**：返回的消息中发现 `thread_id`，展开话题最新回复：
+```json
+{ "thread_id": "omt_xxx", "page_size": 10, "sort_rule": "create_time_desc" }
+```
+
+### 场景 2: 跨会话搜索消息
+
+```json
+{ "query": "项目进度", "chat_id": "oc_xxx" }
+```
+
+### 场景 3: 分页获取更多消息
+
+第一次调用返回 `has_more: true` 和 `page_token: "xxx"`，继续获取：
+```json
+{ "chat_id": "oc_xxx", "page_token": "xxx" }
+```
+
+### 场景 4: 下载消息中的资源
+
+```json
+{ "message_id": "om_xxx", "file_key": "img_v3_xxx", "type": "image" }
+```
+
+---
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| 消息结果太少 | 时间范围太窄或未传时间参数 | 根据用户意图推断合适的 `relative_time` |
+| 消息不完整 | 没有检查 has_more 并翻页 | has_more=true 时用 page_token 翻页 |
+| 话题讨论内容不完整 | 没有展开 thread_id | 发现 thread_id 时获取话题回复 |
+| "open_id 和 chat_id 不能同时提供" | 同时传了两个参数 | 只传其中一个 |
+| "relative_time 和 start_time/end_time 不能同时使用" | 时间参数冲突 | 选择一种时间过滤方式 |
+| "未找到与 open_id=xxx 的单聊会话" | 没有单聊记录 | 改用 chat_id，或确认存在单聊 |
+| 话题消息返回为空 | thread_id 格式不正确 | 确认为 `omt_xxx` 格式 |
+| 图片/文件下载失败 | file_key 或 message_id 不匹配 | 确认 file_key 来自该 message_id |
+| 权限不足 | 用户未授权或无权限 | 确认已完成 OAuth 授权且是会话成员 |

package/dist/skills/feishu-project/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: feishu-project
+description: |
+  飞书项目（Meego）工作项管理。支持查询、创建、修改和流转工作项。
+
+  **重要：飞书项目使用独立的 OAuth 授权，与飞书 IM/文档的授权不共享，首次使用需单独完成授权。**
+
+  **当以下情况时使用此 Skill**:
+  (1) 用户提到"飞书项目"、"Meego"、"工作项"、"需求"、"缺陷"、"bug"、"sprint"、"迭代"、"看板"
+  (2) 需要查询、创建、修改飞书项目中的工作项
+  (3) 需要查看项目视图、待办列表、评论
+  (4) 需要流转工作项状态
+  (5) 用户问"我的待办"、"项目进度"等项目管理相关问题
+---
+
+# 飞书项目（Meego）工具使用指南
+
+## 授权前置检查
+
+飞书项目的 OAuth 授权与飞书 IM/文档的授权**完全独立**，不共享 token。首次使用飞书项目功能时，必须先完成独立授权。
+
+### 授权流程
+
+1. 先调用 `feishu_project_oauth` 工具的 `status` action 检查授权状态
+2. 如果未授权，调用 `feishu_project_oauth` 工具的 `authorize` action 发起授权
+3. 用户在授权卡片中点击链接完成授权
+4. 授权完成后即可使用飞书项目相关工具
+
+### 重要提示
+
+- 如果工具返回 `project_auth_required` 错误，说明需要先授权
+- 飞书项目授权与飞书 IM/文档授权是**两套独立的系统**，互不影响
+- 撤销飞书项目授权不会影响飞书 IM/文档的功能
+
+## 工具快速索引
+
+### 授权管理
+
+| 意图 | 工具 | 关键参数 |
+|------|------|----------|
+| 检查授权状态 | `feishu_project_oauth` | action: "status" |
+| 发起授权 | `feishu_project_oauth` | action: "authorize" |
+| 撤销授权 | `feishu_project_oauth` | action: "revoke" |
+
+### 查询类
+
+| 意图 | 工具 | 关键参数 |
+|------|------|----------|
+| 查看待办/已办/超期 | `feishu_project_list_todo` | action: "todo"/"done"/"overdue"/"this_week" |
+| MQL 搜索工作项 | `feishu_project_search_by_mql` | project_key, mql |
+| 查看工作项概况 | `feishu_project_get_workitem_brief` | work_item_id |
+| 查看工作项类型信息 | `feishu_project_get_workitem_info` | work_item_type |
+| 查看字段元信息 | `feishu_project_get_workitem_field_meta` | project_key, work_item_type_key |
+| 查看可流转状态 | `feishu_project_get_transitable_statuses` | project_key, work_item_id, work_item_type_key, user_key |
+| 查看节点详情 | `feishu_project_get_node_detail` | work_item_id, node_id |
+| 查看评论列表 | `feishu_project_list_workitem_comments` | project_key, work_item_id |
+| 查看操作记录 | `feishu_project_get_workitem_op_record` | project_key, work_item_id |
+| 查看工时记录 | `feishu_project_get_workitem_man_hour_records` | project_key, work_item_type_key, work_item_id |
+| 查看排期 | `feishu_project_list_schedule` | project_key, user_keys, start_time, end_time |
+| 搜索空间信息 | `feishu_project_search_project_info` | project_key |
+| 搜索用户 | `feishu_project_search_user_info` | user_keys |
+| 查看工作项类型列表 | `feishu_project_list_workitem_types` | project_key |
+| 查看关联工作项 | `feishu_project_list_related_workitems` | project_key, work_item_type_key, work_item_id, relation_work_item_type_key, relation_key |
+| 查看关联关系 | `feishu_project_list_workitem_relations` | project_key |
+| 搜索视图 | `feishu_project_search_view_by_title` | project_key, view_scope, key_word |
+| 查看视图详情 | `feishu_project_get_view_detail` | view_id |
+| 查看度量图表 | `feishu_project_list_charts` | project_key, view_id |
+| 查看团队成员 | `feishu_project_list_team_members` | project_key, team_id |
+
+### 操作类
+
+| 意图 | 工具 | 关键参数 |
+|------|------|----------|
+| 创建工作项 | `feishu_project_create_workitem` | work_item_type, fields |
+| 修改工作项字段 | `feishu_project_update_field` | work_item_id, fields |
+| 添加评论 | `feishu_project_add_comment` | work_item_id, comment_content |
+| 流转状态 | `feishu_project_finish_node` | work_item_id, node_id |
+| 创建固定视图 | `feishu_project_create_fixed_view` | project_key, name, work_item_type_key, work_item_id_list |
+| 更新固定视图 | `feishu_project_update_fixed_view` | project_key, view_id, work_item_type_key |
+
+## MQL 使用指南
+
+MQL（Meego Query Language）是飞书项目的查询语言，基于 SQL 语法扩展。
+
+### 使用步骤
+
+1. **确认空间和工作项类型**：先用 `feishu_project_get_workitem_info` 获取字段信息
+2. **使用可读名称**：select 后使用中文字段名（如"任务名称"），避免使用 field_key
+3. **编写查询**：`select \`任务名称\`,\`负责人\` from \`空间名\`.\`需求\` where \`状态\` = '进行中'`
+
+### 获取语法帮助
+
+调用 `feishu_project_search_by_mql` 时传入 `helper: "helper"` 可获取完整语法说明和示例。
+
+## 常见操作流程
+
+### 查看我的待办
+```
+1. feishu_project_list_todo(action: "todo")
+```
+
+### 创建工作项
+```
+1. feishu_project_search_project_info(project_key: "xxx")  -- 确认空间
+2. feishu_project_get_workitem_field_meta(project_key, work_item_type_key)  -- 获取字段元信息
+3. feishu_project_create_workitem(work_item_type, fields)  -- 创建
+```
+
+### 流转工作项状态
+```
+1. feishu_project_get_transitable_statuses(...)  -- 获取可流转状态列表
+2. feishu_project_finish_node(work_item_id, node_id)  -- 执行流转
+```
+
+## 常见错误排查
+
+| 错误 | 原因 | 解决方式 |
+|------|------|----------|
+| `project_auth_required` | 飞书项目未授权或 token 已过期 | 调用 `feishu_project_oauth` 的 authorize |
+| 权限不足 | 用户不是项目成员 | 确认用户有项目访问权限 |
+| 空间不存在 | project_key 错误 | 使用 `feishu_project_search_project_info` 查找正确的 key |
+| 工作项类型不存在 | work_item_type 错误 | 使用 `feishu_project_list_workitem_types` 查看可用类型 |

package/dist/skills/feishu-task/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: feishu-task
+description: |
+  飞书任务管理工具,用于创建、查询、更新任务和清单。
+
+  **当以下情况时使用此 Skill**:
+  (1) 需要创建、查询、更新、删除任务
+  (2) 需要创建、管理任务清单
+  (3) 需要查看任务列表或清单内的任务
+  (4) 用户提到"任务"、"待办"、"to-do"、"清单"、"task"
+  (5) 需要设置任务负责人、关注人、截止时间
+---
+
+# 飞书任务管理
+
+## 🚨 执行前必读
+
+- ✅ **时间格式**：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"
+
+---
+
+## 📋 快速索引：意图 → 工具 → 必填参数
+
+| 用户意图 | 工具 | 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[] | - | - |
+
+---
+
+## 🎯 核心约束（Schema 未透露的知识）
+
+### 1. 当前工具使用用户身份（已内置保护）
+
+**工具使用 `user_access_token`（用户身份）**
+
+这意味着：
+- ✅ 创建任务时可以指定任意成员（包括只分配给别人）
+- ⚠️ 只能查看和编辑**自己是成员的任务**
+- ⚠️ **如果创建时没把自己加入成员，后续无法编辑该任务**
+
+**自动保护机制**：
+- 传入 `current_user_id` 参数（从 SenderId 获取）
+- 如果 `members` 中不包含 `current_user_id`，工具会**自动添加为 follower**
+- 确保创建者始终可以编辑任务
+
+**推荐用法**：创建任务时始终传 `current_user_id`，工具会自动处理成员关系。
+
+### 2. 任务成员的角色说明
+
+- **assignee（负责人）**：负责完成任务，可以编辑任务
+- **follower（关注人）**：关注任务进展，接收通知
+
+**添加成员示例**：
+```json
+{
+  "members": [
+    {"id": "ou_xxx", "role": "assignee"},  // 负责人
+    {"id": "ou_yyy", "role": "follower"}   // 关注人
+  ]
+}
+```
+
+**说明**：`id` 使用用户的 `open_id`（从消息上下文的 SenderId 获取）
+
+### 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 中指定。
+
+---
+
+## 📌 使用场景示例
+
+### 场景 1: 创建任务并分配负责人
+
+```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` 可以只包含其他协作者，当前用户会被自动添加
+- 时间使用北京时间字符串格式
+
+### 场景 2: 查询我负责的未完成任务
+
+```json
+{
+  "action": "list",
+  "completed": false,
+  "page_size": 20
+}
+```
+
+### 场景 3: 完成任务
+
+```json
+{
+  "action": "patch",
+  "task_guid": "任务的guid",
+  "completed_at": "2026-02-26 15:30:00"
+}
+```
+
+### 场景 4: 反完成任务（恢复未完成状态）
+
+```json
+{
+  "action": "patch",
+  "task_guid": "任务的guid",
+  "completed_at": "0"
+}
+```
+
+### 场景 5: 创建清单并添加协作者
+
+```json
+{
+  "action": "create",
+  "name": "产品迭代 v2.0",
+  "members": [
+    {"id": "ou_xxx", "role": "editor"},
+    {"id": "ou_yyy", "role": "viewer"}
+  ]
+}
+```
+
+### 场景 6: 查看清单内的未完成任务
+
+```json
+{
+  "action": "tasks",
+  "tasklist_guid": "清单的guid",
+  "completed": false
+}
+```
+
+### 场景 7: 全天任务
+
+```json
+{
+  "action": "create",
+  "summary": "年度总结",
+  "due": {
+    "timestamp": "2026-03-01 00:00:00",
+    "is_all_day": true
+  }
+}
+```
+
+---
+
+## 🔍 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| **创建后无法编辑任务** | 创建时未将自己加入 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` |
+
+---
+
+## 📚 附录：背景知识
+
+### 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` 参数：
+```json
+{
+  "action": "create",
+  "summary": "任务标题",
+  "tasklists": [
+    {
+      "tasklist_guid": "清单的guid",
+      "section_guid": "分组的guid（可选）"
+    }
+  ]
+}
+```
+
+### D. 重复任务如何创建
+
+使用 `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"
+}
+```
+
+**说明**：只有设置了截止时间的任务才能设置重复规则。
+
+
+### E. 数据权限
+
+- 只能操作自己有权限的任务（作为成员的任务）
+- 只能操作自己有权限的清单（作为成员的清单）
+- 将任务加入清单需要同时拥有任务和清单的编辑权限