feishu-project-official
飞书项目(Meego/Meegle)操作工具。支持查询和管理工作项、节点流转、视图查询、个人待办、排期统计等功能。Use when user needs to work with Feishu/Lark Meego project management — including querying work items, creating/updating work items, completing
SKILL.mdskills/feishu-project-official/SKILL.md
GitHub飞书项目 (Meego) 操作指南
本技能通过调用飞书项目 MCP 服务器 ms_official_meego 来操作飞书项目数据。输出语言跟随用户输入语言,默认中文。
各工具的
aily-mcp call调用示例见 references/api-examples.md。
前置检查
在执行任何操作前,先确认 MCP 服务器可用:
aily-mcp servers
确认 ms_official_meego 在列表中。如果不在,需要调用如下命令安装:
aily-mcp install ms_official_meego
核心工具 — 元数据查询
1. search_project_info
查询空间基础信息,将空间名转换为 project_key 或验证空间是否存在。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 projectKey、simpleName 或空间名称 |
2. list_workitem_types
获取指定空间下所有工作项类型列表。用户描述模糊时用此工具确认合法 type_key。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 projectKey |
3. list_workitem_field_config
获取指定空间和工作项类型的可用字段配置(不含禁用字段和角色配置)。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| work_item_type | string | 是 | 工作项类型 key 或名称 |
| page_num | number | 是 | 页数,每页 50 条,从 1 开始 |
| field_keys | array | 否 | 精确匹配字段 key 或名称 |
| field_query | string | 否 | 模糊查询字段 key 和名称 |
| field_types | array | 否 | 按字段类型筛选 |
4. list_workitem_role_config
获取指定工作项类型的角色列表。用于查询/创建/更新工作项前确认合法 role_key。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| work_item_type | string | 是 | 工作项类型 key 或名称 |
| page_num | number | 是 | 页数,每页 50 条,从 1 开始 |
| role_keys | array | 否 | 精确匹配角色 key 或名称 |
| role_query | string | 否 | 模糊查询角色 key 和名称 |
5. search_user_info
批量查询用户基础信息。用于将姓名/邮箱转换为 userkey。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| user_keys | array | 是 | userKey、Email 或名字,最多 20 个 |
| project_key | string | 否 | 空间 key |
核心工具 — 数据查询
6. search_by_mql
使用 MQL 查询工作项数据。语法详见 references/mql-syntax.md。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间标识(支持名称、simpleName、projectKey) |
| mql | string | 是(翻页时可用 session_id 替代) | MQL 查询语句(完整 SQL) |
| session_id | string | 否 | 分页会话 ID,传入后不解析 MQL 直接翻页 |
| group_pagination_list | array | 否 | 分页信息,首次查询可不传 |
要点:
- 务必先用
list_workitem_field_config查询字段类型和结构,查不到直接报错不要继续 - 如涉及角色信息,用
list_workitem_role_config获取角色结构 - SELECT 后属性不宜过多,优先使用字段 key(如
name、priority、status)而非字段名称(如任务名称) - 返回按页返回,需全量数据时必须使用翻页参数
7. get_workitem_brief
按 ID/名称查询工作项概况。不传 fields 时仅返回固定基础字段;如需自定义字段数据,先调 list_workitem_field_config 获取字段 key 后传入 fields。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| work_item_id | string | 是 | 工作项 ID 或名称 |
| project_key | string | 否 | 空间 key |
| fields | array | 否 | 要查询的 field_key 或 field_name |
| url | string | 否 | 工作项实例链接,可自动解析 |
8. list_todo
按 action 类型查询当前用户的工作项列表。无需 MQL 即可查询待办/已办。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| action | string | 是 | todo(待办)/done(已办)/overdue(逾期)/this_week(本周待办) |
| page_num | number | 是 | 页码,从 1 开始,每页 50 条 |
| asset_key | string | 否 | 工作区 key(格式 Asset_xxx),仅在报错需要选择时传 |
注意:需完整结果时,从 page_num=1 开始连续查询直到没有更多数据。
9. list_schedule
获取指定人员在时间区间内的排期与工作量明细。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| user_keys | array | 是 | 用户标识(名称/邮箱/userkey),每次最多 3 个 |
| start_time | string | 是 | 开始时间,格式 YYYY-MM-DD |
| end_time | string | 是 | 结束时间,格式 YYYY-MM-DD,单次跨度最大 2 个月 |
| work_item_type_keys | array | 否 | 工作项类型列表,查询所有传入 _all |
调用约束(必须遵守):
- 每次最多 3 个用户,多人拆分批次并行
- 单次跨度 ≤ 2 个月,超出按月拆分
- 所有批次完成后再汇总,未完整获取前不得输出结论
10. get_view_detail
根据视图 ID 获取该视图下的工作项列表。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| view_id | string | 是 | 视图 ID |
| project_key | string | 否 | 空间 key |
| page_num | number | 否 | 分页页数起点 |
| fields | array | 否 | 要查询的字段 |
| url | string | 否 | 视图链接,可自动解析 |
11. get_node_detail
获取工作项中指定节点或所有节点的完整详情。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| work_item_id | string | 是 | 工作项 ID 或名称 |
| node_id_list | array | 否 | 节点 ID 列表,传空或 _all 获取所有节点 |
| field_key_list | array | 否 | 节点字段 key,传空或 _all 获取所有字段 |
| need_sub_task | boolean | 否 | 是否需要节点子项(子任务) |
| page_num | number | 否 | 节点信息一次最多 20 个,按页返回 |
| project_key | string | 否 | 空间 key |
| url | string | 否 | 链接,可自动解析 |
核心工具 — 数据操作
12. create_workitem
创建工作项实例。务必先用 list_workitem_field_config 获取字段信息,list_workitem_role_config 获取角色信息。模板 ID 是必填项。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| work_item_type | string | 是 | 工作项类型 |
| project_key | string | 否 | 空间标识 |
| fields | array | 否 | 字段值列表,每项含 field_key 和 field_value |
| url | string | 否 | 可从链接解析空间信息 |
13. update_field
修改指定实例的字段值或角色。节点字段更新请用 update_node。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| work_item_id | string | 是 | 工作项 ID 或名称 |
| project_key | string | 否 | 空间 key |
| fields | array | 否 | 要更新的字段列表,每项含 field_key 和 field_value |
| role_operate | array | 否 | 角色操作,每项含 op(add/remove)、role_key、user_keys |
| url | string | 否 | 可从链接解析信息 |
角色更新:不能通过 fields 更新角色,必须用 role_operate。role_key 通过 list_workitem_role_config 获取,user_keys 通过 search_user_info 获取。
14. transition_node
仅用于节点流工作项,操作节点完成流转或回滚。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| work_item_id | string | 是 | 工作项 ID |
| action | string | 否 | confirm(流转) / rollback(回滚) |
| node_id | string | 否 | 节点 ID |
| node_ids | array | 否 | 节点名称或节点 ID 列表 |
| rollback_reason | string | 否 | 回滚原因,action=rollback 时需填写 |
| project_key | string | 否 | 空间 key |
扩展工具:评论、视图搜索/创建、团队、子任务、工时、操作记录、关联工作项、可流转状态查询等工具见 references/tools-extended.md,按需查阅。
字段值格式(field_value)
create_workitem / update_field 中 field_value 的格式因字段类型而异:
| 字段类型 | 格式 | 示例 |
|---|---|---|
| template | 模板 ID(创建必填) | 145405865。用 list_workitem_field_config(field_keys=["template"]) 获取 |
| text / multi-pure-text / link / bool / number | 单个字面值 | "测试工作项" |
| user | 单个 userkey | "7509072868295085608" |
| multi-user | userkey 数组 | ["7509072868295085608","7509072868295085609"] |
| select / radio / tree-select | 枚举项 option_id | "437794"。先从字段配置获取枚举值 |
| multi-select | option_id 数组,支持 free_add | [{"option_id":"111"},{"option_id":"222"}] |
| multi-text | markdown 格式 | "**加粗**内容" |
| date | 毫秒时间戳(天精度) | 1722182400000 |
| schedule | 时间戳数组 [开始, 结束] | [1722182400000,1722355199999] |
| precise_date | 对象 {start_time, end_time} | {"start_time":1722182400000,"end_time":1722355199999} |
| workitem_related_select | 关联工作项 ID | 145405865 |
| workitem_related_multi_select | 关联 ID 数组(数字类型) | [145405865,145405866] |
| role_owners(仅创建时) | 角色-人员数组 | [{"role":"RD","owners":["userkey1"]}] |
更新角色时不用 fields,用
update_field的role_operate参数。
常用场景速查
| 场景 | 推荐工具 | 说明 |
|---|---|---|
| 验证空间 | search_project_info | 空间名 → project_key |
| 查询工作项类型 | list_workitem_types | 确认合法 type_key |
| 查询字段配置 | list_workitem_field_config | 字段 key、枚举值、类型 |
| 人名→userkey | search_user_info | 批量转换,最多 20 个 |
| 复杂条件查询 | search_by_mql | 支持条件筛选、时间范围、团队等 |
| 查我的工作项 | list_todo | 直接获取当前用户的待办/已办 |
| 团队排期统计 | list_schedule | 每次 ≤3 人,≤2 月 |
| 创建需求/任务 | create_workitem | 需先确认字段信息和模板 ID |
| 修改状态/负责人 | update_field | 字段用 fields,角色用 role_operate |
| 完成/回滚节点 | transition_node | action=confirm 或 rollback |
| 查看视图数据 | get_view_detail | 获取视图下的工作项列表 |
URL 参数处理
用户可能直接提供飞书项目链接,大部分工具支持 url 参数自动解析:
project_key、work_item_type、work_item_id、view_id
常见 URL 动作:
- 详情页 URL + 无明确意图 →
get_workitem_brief(url=...) - 详情页 URL + "修改XX为YY" →
update_field(url=..., fields=...) - 详情页 URL + "完成/流转" → 先
get_workitem_brief(url=...)获取 node_id →transition_node(action="confirm") - 详情页 URL + "回滚" → 同上 →
transition_node(action="rollback", rollback_reason=...) - 视图页 URL →
get_view_detail(url=...)
通用规范
请求处理流程
收到用户输入后,按以下步骤处理:
1. 参数提取:从自然语言中提取关键参数:
- 空间名、工作项类型、时间范围、人员、筛选条件等
- 正确区分空间名与筛选维度(如「XX空间下YY业务线的缺陷」中 XX 是空间名,YY 是筛选条件)
- 含 URL 时直接传入工具的
url参数,跳过后续确认步骤
2. 参数确认(禁止猜测):
- 空间:用
search_project_info探测 → 唯一则用,多个则让用户选,无匹配则问用户 - 工作项类型:用
list_workitem_types获取类型列表 → 唯一相关则用,多个则让用户选 - 人员:用
search_user_info转换人名 → 匹配到多个用户时,禁止自行选择,展示完整列表让用户指定;无歧义的不需确认 - 缺失的必要参数:直接问用户,多项缺失时合并为一条消息询问
- 探测 ≠ 猜测:探测结果不唯一时,必须展示并询问用户,禁止自行选择
个人待办(
list_todo)和 URL 直接操作无需确认步骤。
3. 元数据收集(无需用户参与):
- 调用
list_workitem_field_config获取字段定义(key、类型、枚举值)- 需要特定字段时用
field_keys精确查询(如field_keys=["template"]) - 不确定字段名时用
field_query模糊查询
- 需要特定字段时用
- 如涉及角色,并行调用
list_workitem_role_config - 从字段配置中提取关键信息:
- 状态字段:type 为
_work_item_status,含「完成」「关闭」「终止」的值为完成态 - 排期字段:type 为
schedule,MQL 中用__排期字段名_开始时间/__排期字段名_结束时间 - 优先级字段:key 为
priority或 name 含「优先级」
- 状态字段:type 为
简单直调场景(如添加评论、查看操作记录等只需 project_key + work_item_id 的操作)可跳过此步骤。
4. 执行:调用目标工具完成操作,按下方「并行调用」和「大结果处理」规范执行。
并行调用
无依赖的工具调用应并行发起。
必须串行(前者输出是后者输入):
search_project_info→list_workitem_field_config→search_by_mqlget_workitem_brief→transition_node/update_fieldlist_workitem_field_config→create_workitem
可并行:
list_workitem_field_config和list_workitem_role_config(同类型)- 多种工作项类型的
list_workitem_field_config(如 story + issue) - 各条件的 count 查询、多人排期分批查询
大结果处理
- 分批查询:
list_schedule多人时拆成每批 ≤ 3 人并行 - 精简 SELECT:只选必要字段,避免富文本等大体积字段
- 按需翻页:先读首页获取总数,按需翻页
错误处理
- 失败后分析错误信息,针对性修正后重试
- 连续 3 次同类失败后停止,向用户说明原因,询问如何继续
高频错误速查:
| 错误现象 | 修复方式 |
|---|---|
| 找不到空间 | 用 search_project_info 验证,确认 project_key |
| 找不到工作项类型 | 用 list_workitem_types 确认合法 type_key |
| 权限错误 | 确认当前用户是否有对应空间的访问权限 |
| MQL 查询失败 | 确认 FROM 用 `空间名`.`工作项类型` 格式 |
| 数组字段比较报错 | 改用 array_contains 或 any_match |
| node not found | 先 get_workitem_brief 获取真实 node_id,禁止猜测 |
| list_todo 需选择工作区 | 根据报错中的工作区列表,将 asset_key(Asset_xxx)传入重试 |
| 人名/团队名重复 | 用 <id:xxxx> 消歧语法(见 MQL 语法参考) |
| 节点流转失败 | 先 get_transitable_states 确认可流转状态,再 get_transition_required 获取必填项 |
| 创建工作项缺少模板 | list_workitem_field_config(field_keys=["template"]) 获取 |
| 角色更新失败 | 不用 fields,用 update_field 的 role_operate 参数 |
| 人名→userkey 失败 | 用 search_user_info 批量查询 |