飞书项目 (Meego/Meegle) 操作指南
本技能通过 Meegle CLI 来操作飞书项目数据。输出语言跟随用户输入语言，默认中文。
各命令的调用示例见 references/api-examples.md。 CLI 使用指南（命令结构、参数传递、命令发现）：见 references/cli-guide.md
Project 空间域
project.search
搜索空间信息，将空间名转换为 project_key 或验证空间是否存在。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 projectKey、simpleName 或空间名称 |
WorkItem 工作项域
workitem.create
创建工作项实例。务必先用 workitem.meta-fields 获取字段信息，workitem.meta-roles 获取角色信息。模板 ID 是必填项。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| work_item_type | string | 是 | 工作项类型 |
| project_key | string | 否 | 空间标识 |
| fields | array | 否 | 字段值列表，每项含 field_key 和 field_value |
| url | string | 否 | 可从链接解析空间信息 |
workitem.get
按 ID/名称查询工作项概况。不传 fields 时仅返回固定基础字段；如需自定义字段数据，先调 workitem.meta-fields 获取字段 key 后传入 fields。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| work_item_id | string | 是 | 工作项 ID 或名称 |
| project_key | string | 否 | 空间 key |
| fields | array | 否 | 要查询的 field_key 或 field_name |
| url | string | 否 | 工作项实例链接，可自动解析 |
workitem.update
修改指定实例的字段值或角色。节点字段更新请用 workflow.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 通过 workitem.meta-roles 获取，user_keys 通过 user.search 获取。
workitem.query
使用 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 | 否 | 分页信息，首次查询可不传 |
要点：
- 务必先用
workitem.meta-fields查询字段类型和结构，查不到直接报错不要继续 - 如涉及角色信息，用
workitem.meta-roles获取角色结构 - SELECT 后属性不宜过多，优先使用字段 key（如
name、priority、status）而非字段名称（如任务名称） - 返回按页返回，需全量数据时必须使用翻页参数
workitem.list-op-records
查看工作项操作记录。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| work_item_id | string | 是 | 工作项 ID |
workitem.meta-types
获取指定空间下所有工作项类型列表。用户描述模糊时用此命令确认合法 type_key。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 projectKey |
workitem.meta-fields
获取指定空间和工作项类型的可用字段配置（不含禁用字段和角色配置）。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 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 | 否 | 按字段类型筛选 |
workitem.meta-roles
获取指定工作项类型的角色列表。用于查询/创建/更新工作项前确认合法 role_key。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| work_item_type | string | 是 | 工作项类型 key 或名称 |
| page_num | number | 是 | 页数，每页 50 条，从 1 开始 |
| role_keys | array | 否 | 精确匹配角色 key 或名称 |
| role_query | string | 否 | 模糊查询角色 key 和名称 |
workitem.meta-create-fields
查看创建工作项时可用的字段及类型。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
WorkFlow 工作流域
workflow.transition
仅用于节点流工作项，操作节点完成流转或回滚。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 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 |
workflow.transition-state
仅用于状态流工作项，流转工作项状态。先用 workflow.list-state-transitions 获取可流转状态及 transition_id。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| work_item_id | string | 是 | 工作项 ID |
| transition_id | string | 否 | 状态流转 ID，从 workflow.list-state-transitions 获取 |
| project_key | string | 否 | 空间 key |
workflow.get-node
获取工作项中指定节点或所有节点的完整详情。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 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 | 否 | 链接，可自动解析 |
workflow.update-node
修改节点（排期、负责人、自定义字段等）。排期/差异化排期/负责人不要同时修改。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| work_item_id | string | 是 | 工作项 ID |
| node_id | string | 是 | 节点 ID |
workflow.list-state-transitions
查看工作项可流转的状态列表。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| work_item_id | string | 是 | 工作项 ID |
| work_item_type | string | 是 | 工作项类型 |
| user_key | string | 是 | 用户标识 |
workflow.list-state-required
查看流转所需的必填信息。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| work_item_id | string | 是 | 工作项 ID |
| state_key | string | 是 | 目标状态 key |
workflow.meta-node-fields
查看节点字段配置。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| work_item_type | string | 是 | 工作项类型 |
MyWork 工作台域
mywork.todo
按 action 类型查询当前用户的工作项列表。无需 MQL 即可查询待办/已办。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| action | string | 是 | todo(待办)/done(已办)/overdue(逾期)/this_week(本周待办) |
| page_num | number | 是 | 页码，从 1 开始，每页 50 条 |
| asset_key | string | 否 | 工作区 key（格式 Asset_xxx），仅在报错需要选择时传 |
注意：需完整结果时，从 page_num=1 开始连续查询直到没有更多数据。
WorkHour 工时域
workhour.list-schedule
获取指定人员在时间区间内的排期与工作量明细。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| user_keys | array | 是 | 用户标识（名称/邮箱/userkey），每次最多 20 个 |
| start_time | string | 是 | 开始时间，格式 YYYY-MM-DD |
| end_time | string | 是 | 结束时间，格式 YYYY-MM-DD，单次跨度最大 3 个月 |
| work_item_type_keys | array | 否 | 工作项类型列表，查询所有传入 _all |
调用约束（必须遵守）：
- 每次最多 20 个用户，多人拆分批次并行
- 单次跨度 ≤ 3 个月，超出按月拆分
- 所有批次完成后再汇总，未完整获取前不得输出结论
workhour.list-records
查看工作项的工时登记记录。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| work_item_type | string | 是 | 工作项类型 |
| work_item_id | string | 是 | 工作项 ID |
UserGroup 人员域
user.search
批量查询用户基础信息。用于将姓名/邮箱转换为 userkey。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| user_keys | array | 是 | userKey、Email 或名字，最多 20 个 |
| project_key | string | 否 | 空间 key |
user.me
查看当前用户信息。无需参数。
MQL 中可直接用
current_login_user()函数，无需提前获取用户信息。如需获取当前用户的 userkey/姓名等详细信息，可用user.search传入current_login_user()作为参数。
team.list
查看空间下的团队列表。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 否 | 空间 key |
team.list-members
查看团队成员列表。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| team_id | string | 是 | 团队 ID |
View 视图域
view.get
根据视图 ID 获取该视图下的工作项列表。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| view_id | string | 是 | 视图 ID |
| project_key | string | 否 | 空间 key |
| page_num | number | 否 | 分页页数起点 |
| fields | array | 否 | 要查询的字段 |
| url | string | 否 | 视图链接，可自动解析 |
view.search
按名称搜索视图。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| view_scope | string | 是 | 视图范围 |
| key_word | string | 是 | 关键词 |
view.create-fixed
创建固定视图。上限 200 个工作项。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| name | string | 是 | 视图名称 |
| work_item_type | string | 是 | 工作项类型 |
| work_item_id_list | array | 是 | 工作项 ID 列表 |
view.update-fixed
更新固定视图。add/remove_work_item_ids 二选一。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| view_id | string | 是 | 视图 ID |
| work_item_type | string | 是 | 工作项类型 |
Chart 度量域
chart.get
查看图表详情。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| chart_id | string | 是 | 图表 ID |
chart.list
查看视图下的图表列表。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| view_id | string | 是 | 视图 ID |
Comment 评论域
comment.add
添加评论。支持 markdown。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| work_item_id | string | 是 | 工作项 ID |
| comment_content | string | 是 | 评论内容 |
comment.list
查看评论列表。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| work_item_id | string | 是 | 工作项 ID |
SubTask 子任务域
subtask.update
创建/修改/完成/回滚子任务。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| node_id | string | 是 | 节点 ID |
| work_item_id | string | 是 | 工作项 ID |
| action | string | 是 | create/update/confirm/rollback |
Relation 关系域
relation.list
查看关联的工作项列表。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
| work_item_id | string | 是 | 工作项 ID |
| relation_field_key | string | 否 | 关联关系字段 key，从 relation.meta-definitions 获取 |
| relation_id | string | 否 | 关联关系 ID，从 relation.meta-definitions 获取 |
| node_id | string | 否 | 节点 ID，查询某节点下的关联时传入 |
| page_num | number | 否 | 分页页码，从 1 开始 |
| page_size | number | 否 | 每页数量，最大 50 |
relation.meta-definitions
查看空间下的关联关系定义。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| project_key | string | 是 | 空间 key |
字段值格式（field_value）
workitem.create / workitem.update 中 field_value 的格式因字段类型而异：
| 字段类型 | 格式 | 示例 |
|---|---|---|
| template | 模板 ID（创建必填） | 145405865。用 workitem.meta-fields(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，用
workitem.update的role_operate参数。
常用场景速查
| 场景 | 推荐命令 | 说明 |
|---|---|---|
| 验证空间 | project.search | 空间名 → project_key |
| 查询工作项类型 | workitem.meta-types | 确认合法 type_key |
| 查询字段配置 | workitem.meta-fields | 字段 key、枚举值、类型 |
| 人名→userkey | user.search | 批量转换，最多 20 个 |
| 当前用户信息 | user.me | 无需参数 |
| 复杂条件查询 | workitem.query | 支持条件筛选、时间范围、团队等 |
| 查我的工作项 | mywork.todo | 直接获取当前用户的待办/已办 |
| 团队排期统计 | workhour.list-schedule | 每次 ≤20 人，≤3 月 |
| 创建需求/任务 | workitem.create | 需先确认字段信息和模板 ID |
| 修改状态/负责人 | workitem.update | 字段用 fields，角色用 role_operate |
| 完成/回滚节点（节点流） | workflow.transition | action=confirm 或 rollback |
| 流转状态（状态流） | workflow.transition-state | 先用 workflow.list-state-transitions 获取 transition_id |
| 查看视图数据 | view.get | 获取视图下的工作项列表 |
URL 参数处理
用户可能直接提供飞书项目链接，大部分命令支持 url 参数自动解析：
project_key、work_item_type、work_item_id、view_id
常见 URL 动作：
- 详情页 URL + 无明确意图 →
workitem.get(url=...) - 详情页 URL + "修改XX为YY" →
workitem.update(url=..., fields=...) - 详情页 URL + "完成/流转" → 先
workitem.get(url=...)获取 node_id →workflow.transition(action="confirm") - 详情页 URL + "回滚" → 同上 →
workflow.transition(action="rollback", rollback_reason=...) - 视图页 URL →
view.get(url=...)
通用规范
请求处理流程
收到用户输入后，按以下步骤处理：
1. 参数提取：从自然语言中提取关键参数：
- 空间名、工作项类型、时间范围、人员、筛选条件等
- 正确区分空间名与筛选维度（如「XX空间下YY业务线的缺陷」中 XX 是空间名，YY 是筛选条件）
- 含 URL 时直接传入命令的
url参数，跳过后续确认步骤
2. 参数确认（禁止猜测）：
- 空间：用
project.search探测 → 唯一则用，多个则让用户选，无匹配则问用户 - 工作项类型：用
workitem.meta-types获取类型列表 → 唯一相关则用，多个则让用户选 - 人员：用
user.search转换人名 → 匹配到多个用户时，禁止自行选择，展示完整列表让用户指定；无歧义的不需确认 - 缺失的必要参数：直接问用户，多项缺失时合并为一条消息询问
- 探测 ≠ 猜测：探测结果不唯一时，必须展示并询问用户，禁止自行选择
个人待办（
mywork.todo）和 URL 直接操作无需确认步骤。
3. 元数据收集（无需用户参与）：
- 调用
workitem.meta-fields获取字段定义（key、类型、枚举值）- 需要特定字段时用
field_keys精确查询（如field_keys=["template"]） - 不确定字段名时用
field_query模糊查询
- 需要特定字段时用
- 如涉及角色，并行调用
workitem.meta-roles - 从字段配置中提取关键信息：
- 状态字段：type 为
_work_item_status，含「完成」「关闭」「终止」的值为完成态 - 排期字段：type 为
schedule，MQL 中用__排期字段名_开始时间/__排期字段名_结束时间 - 优先级字段：key 为
priority或 name 含「优先级」
- 状态字段：type 为
简单直调场景（如
comment.add、workitem.list-op-records等只需 project_key + work_item_id 的操作）可跳过此步骤。
4. 执行：调用目标命令完成操作，按下方「并行调用」和「大结果处理」规范执行。
并行调用
无依赖的命令调用应并行发起。
必须串行（前者输出是后者输入）：
project.search→workitem.meta-fields→workitem.queryworkitem.get→workflow.transition/workitem.updateworkitem.meta-fields→workitem.create
可并行：
workitem.meta-fields和workitem.meta-roles（同类型）- 多种工作项类型的
workitem.meta-fields（如 story + issue） - 各条件的 count 查询、多人排期分批查询
大结果处理
- 分批查询：
workhour.list-schedule多人时拆成每批 ≤ 20 人并行 - 精简 SELECT：只选必要字段，避免富文本等大体积字段
- 按需翻页：先读首页获取总数，按需翻页
错误处理
- 失败后分析错误信息，针对性修正后重试
- 连续 3 次同类失败后停止，向用户说明原因，询问如何继续
通用自愈规则（最多自动重试 2 次）
提取报错中的 err_msg 或 inner_err，按以下规则修复：
| 报错特征 | 自愈动作 |
|---|---|
cannot unmarshal object...（数据格式错误） | 仅改变格式（数字↔字符串、单值↔数组、对象↔纯字符串），值不变 |
不满足层级配置（级联层级错误） | 查 children 树，展示末级叶子节点让用户选择 |
invalid select option(s)（枚举值不合法） | 从 possible values 匹配；能唯一匹配则修正重试，否则询问用户 |
通用熔断规则（立即终止，禁止盲目重试）
| 条件 | 说明 |
|---|---|
| 空间未找到 | project.search 失败超过 3 次 |
| 权限不足 | 接口返回 Permission Denied |
高频错误速查：
| 错误现象 | 修复方式 |
|---|---|
| 找不到空间 | 用 project.search 验证，确认 project_key |
| 找不到工作项类型 | 用 workitem.meta-types 确认合法 type_key |
| 权限错误 | 确认当前用户是否有对应空间的访问权限 |
| MQL 查询失败 | 确认 FROM 用 `空间名`.`工作项类型` 格式 |
| 数组字段比较报错 | 改用 array_contains 或 any_match |
| node not found | 先 workitem.get 获取真实 node_id，禁止猜测 |
| mywork.todo 需选择工作区 | 根据报错中的工作区列表，将 asset_key（Asset_xxx）传入重试 |
| 人名/团队名重复 | 用 <id:xxxx> 消歧语法（见 MQL 语法参考） |
| 节点流转失败 | 节点流用 workflow.transition；状态流用 workflow.transition-state（需先 workflow.list-state-transitions 获取 transition_id，再 workflow.list-state-required 获取必填项） |
| 创建工作项缺少模板 | workitem.meta-fields(field_keys=["template"]) 获取 |
| 角色更新失败 | 不用 fields，用 workitem.update 的 role_operate 参数 |
| 人名→userkey 失败 | 用 user.search 批量查询 |
补充错误速查（低频但需注意）：
| 错误现象 | 原因 | 修复方式 |
|---|---|---|
| MQL 返回为空但数据存在 | 字段名用了英文 field_key | 调用 workitem.meta-fields 确认字段名 |
| 日期区间字段查询失败 | 直接查询了区间字段 | 用子字段 `__字段名_开始时间` |
| 角色查询无结果 | 未加 __ 前缀 | 用 `__{角色名}` 格式 |
| 空间名不唯一 | 中文名匹配到多个空间 | 用 project.search 验证后用 project_key 重新调用 |
| 人员字段写入失败 | field_value 格式不对 | user 类型传单个 userkey，multi-user 传 userkey 数组 |
| 字段名不正确 | 字段 key 拼写错误 | 先 workitem.meta-fields 确认 |
