/meegle

name: meegle
description: |
  飞书项目（Meego/Meegle）操作工具。支持查询和管理工作项、节点流转、视图查询、个人待办、排期统计等功能。 Use when user needs to work with Feishu/Lark Meego project management — including querying work items, creating/updating work items, completing workflow nodes, checking views, listing todos, analyzing schedules/workloads, or searching with MQL. 关键词：飞书项目、meego、meegle、工作项、需求、任务、缺陷、排期、视图、待办、节点。

飞书项目 (Meego/Meegle) 操作指南

本技能通过 Meegle CLI来操作飞书项目数据。输出语言跟随用户输入语言，默认中文。

> 各命令的调用示例见 [references/api-examples.md](references/api-examples.md)。 > **授权流程**（所有业务命令前必须执行）：见 [references/auth-guard.md](references/auth-guard.md) > **CLI 使用指南**（命令结构、参数传递、命令发现）：见 [references/cli-guide.md](references/cli-guide.md)

---

Project 空间域

project search

搜索空间信息，将空间名转换为 project_key 或验证空间是否存在；省略 --project-key 时返回当前用户最近访问过的空间列表（按访问时间由近及远）。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | --project-key | string | 否 | 空间 projectKey、simpleName 或空间名称；留空查询当前用户可访问的空间 | | --page-num | number | 否 | 分页页码，每页 50 条，从 1 开始 |

---

WorkItem 工作项域

> 元数据查询命令（`workitem meta-types` / `workitem meta-fields` / `workitem meta-roles` / `workitem meta-create-fields`）的参数表见 [references/workitem.md](references/workitem.md)。

workitem create

创建工作项实例。**务必先用 `workitem meta-fields` 获取字段信息，`workitem meta-roles` 获取角色信息。模板 ID 是必填项。**

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | --work-item-type | string | 是 | 工作项类型 | | --project-key | string | 否 | 空间标识 | | --fields | array | 否 | 字段值列表，每项含 field_key 和 field_value | | --work-item-id | string | 否 | 工作项资源库模板实例 ID；通过资源工作项创建普通工作项时必填 | | --ignore-required | boolean | 否 | 是否忽略字段必填校验；默认 false，谨慎使用 | | --ignore-role-calculate | boolean | 否 | 是否忽略角色计算；默认 false，谨慎使用 |

workitem get

按 ID/名称查询工作项概况。不传 fields 时返回固定基础字段加上一组默认带出的系统字段——实测包含 `group_type` 拉群方式、`description`、`current_status_operator`、`watchers`（即便 value 为 null 也会出现）；其余字段需要通过 `workitem meta-fields` 拿到 key 后再传入 fields。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | --work-item-id | string | 是 | 工作项 ID 或名称 | | --project-key | string | 否 | 空间 key | | --fields | array | 否 | 要查询的 field_key 或 field_name；传 `["_all"]` 时按逻辑字段分页返回全部字段；传 `["group_type"]` 时只取拉群方式 | | --page-size | number | 否 | 仅 `fields=["_all"]` 时生效；每页字段数量，默认 100，最大 200。**meegle CLI 注意**：直接传 `--page-size N` 会被序列化成字符串触发后端 `need I64 type, but got: STRING`；当前只能走 `--params '{"page_size":N}'` 让它以数字传出 | | --page-token | string | 否 | 仅 `fields=["_all"]` 时生效；翻页 token，首次不传，下一页传上次响应的 `next_page_token`（token 形如字段 key，例如 `"business"`）；同上，meegle CLI 当前需要走 `--params '{"page_token":"..."}'` |

> **逻辑字段聚合（重要心智模型）**：服务端把 `group_id` / `chat_group` 这类"拉群"相关的物理字段**合并**到一个逻辑字段 `group_type`。读取/更新统一走 `group_type`，**不要再单独读取 `group_id` 或 `chat_group`**。 > > ⚠️ **读写协议不对称**：读返回结构里**判别键是 `value`**（不是 `type`），更新时**判别键是 `type`**——别照着读到的结构直接回写。 > > 读返回（`workitem_fields[].value` 字段）的形状： > - `auto` → `{value: "auto", label: "自动拉群", group_id: "oc_xxx"}`（自动拉群通常有 group_id；状态切换时 oc_id 可能会变） > - `bind` → `{value: "bind", label: "绑定现有群", group_id: "oc_xxx"}` > - `disabled` → `{value: "disabled", label: "不拉群"}`（无 group_id） > > 写协议（`field_value` 里的 JSON）：`{"type": "auto" | "bind" | "disabled", "group_id": "oc_xxx"}`

workitem batch-get

批量查询工作项（Meegle CLI 客户端 fan-out：并发调用 `workitem get`）。单次 ≤ 200 个 ID，3 并发，返回 `{results, errors, summary}`；ID 量大时用 `--format ndjson` 流式输出。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | --work-item-ids | array | 二选一 | 工作项 ID 列表（逗号分隔或多次传入） | | --ids-file | string | 二选一 | 从文件读取 ID（一行一个，`#` 开头注释） | | --fields | array | 否 | 要查询的 field_key 列表 | | --project-key | string | 否 | 空间 key |

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 |

**角色更新**：不能通过 fields 更新角色，必须用 `role_operate`。role_key 通过 `workitem meta-roles` 获取，user_keys 通过 `user search` 获取。

**拉群方式更新（`group_type` 逻辑字段）**：要修改/读取拉群方式统一走 `group_type`，不要再单独操作 `group_id` / `chat_group`。写协议 `field_value` 形如：`{"type": "auto" | "bind" | "disabled", "group_id": "oc_xxx"}`（注意写用 `type` 作为判别键，**与读返回的 `value` 不对称**）。校验规则（服务端实际报错文本）：`bind` 不带 `group_id` 或带空串/纯空格 → `group_id is required when group_type=bind`；`auto`/`disabled` 同时带 `group_id` → `group_type conflicts with group_id: type=<auto|disabled>`。详细示例见 [references/sop-update-workitem.md](references/sop-update-workitem.md)。

workitem query

使用 MQL 查询工作项数据。语法详见 [references/mql-syntax.md](references/mql-syntax.md)。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | --project-key | string | 是 | 空间标识（支持名称、simpleName、projectKey） | | --mql | string | 是（翻页时可用 session_id 替代） | MQL 查询语句（完整 SQL） | | --session-id | string | 否 | 分页会话 ID，传入后不解析 MQL 直接翻页 | | --group-pagination-list | array | 否 | 分组分页信息，首次查询可不传；翻页时传 `[{ "group_id": "分组ID", "page_num": 页码 }]` |

**分组分页**：

• `--group-pagination-list` 是数组，当前只支持传一组分页数据；元素结构为 `{ "group_id": string, "page_num": number }`
• `group_id` 取首查返回的 `list[].group_infos[].group_id`；无分组查询返回的默认分组 ID 为 `"1"`，翻页时也传 `"1"`
• `page_num` 从 1 开始；MQL 首查不传分页参数时默认返回第一页，单页最多 50 条。当前接口没有 `page_size` / `page_token` 子字段
• 翻页时传首查返回的 `session_id` 和目标分组的分页参数；传 `session_id` 后后端不再解析 MQL，只按已有会话取对应分组页

**要点**：

• 先用 `workitem meta-fields` / `workitem meta-roles` 获取字段与角色配置；查不到直接报错不要继续
• SELECT 后属性不宜过多，**优先使用字段 key**（如 `name`、`priority`、`status`）；返回按页返回，需全量时使用翻页参数

workitem list-op-records

查看工作项操作记录。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | --project-key | string | 是 | 空间 key | | --work-item-id | string | 是 | 工作项 ID |

---

Attachment 附件域

附件上传/下载分两步：先调 `attachment prepare-upload` / `attachment prepare-download` 申请带签名的对象存储 URL，再与对象存储做 HTTP 直连。Meegle CLI 提供 `attachment +upload` / `attachment +download` 一键封装。详细参数表与流程说明见 [references/attachment.md](references/attachment.md)。

---

WorkFlow 工作流域

> 流转辅助命令（`workflow list-state-transitions` / `workflow list-state-requir