/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 |

workitem get

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

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | --work-item-id | string | 否 | 工作项 ID（与 `--name` 二选一） | | --name | string | 否 | 按名称查询工作项（与 `--work-item-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"`）；同上，须走 `--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 查询工作项数据。语法按主题拆在 6 个文件：基础与硬规则 [references/mql-basics.md](references/mql-basics.md)、运算符与数组函数 [references/mql-operators.md](references/mql-operators.md)、时间与状态 [references/mql-time-status.md](references/mql-time-status.md)、人员与角色 [references/mql-people-roles.md](references/mql-people-roles.md)、节点与关联 [references/mql-nodes-relations.md](references/mql-nodes-relations.md)、整句示例与关键词映射 [references/mql-examples.md](references/mql-examples.md)。写 MQL 前至少读 basics 与 operators。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | --project-key | string | 是 | 空间标识（支持名称、simpleName、projectKey） | | --mql | string | 首查必填 | MQL 查询语句（完整 SQL）。单次最多返回 50 条；`LIMIT n` 只用于截断（n ≤ 50），不用于翻页 | | --session-id | string | 翻页必填 | 翻页用。取自首查返回体的 `session_id`；翻页时只传 `--project-key` + `--session-id` + `--group-pagination-list`，不要再传 `--mql`，否则按新查询重新执行、翻页参数被忽略 | | --group-pagination-list | array | 翻页必填 | 翻页参数，与 `--session-id` 配合使用，首查不传。每页 50 条，总页数 = ceil(`list[0].count` / 50)；目前只支持传入一组 `[{"group_id":"<分组ID>","page_num":N}]` |

**翻页取全量**（要全部结果时必须走这条链路，不要用 `LIMIT offset, n` 翻页）： 1. 首查只传 `--project-key` + `--mql`，返回第 1 页（最多 50 条）。 从返回体取 `session_id`、`list[0].count`、`list[0].group_infos[].group_id`；无分组查询的 `group_id` 为 `"1"`。 2. 之后每页传 `--project-key` + `--session-id` + `--group-pagination-list '[{"group_id":"<分组ID>","page_num":N}]'`，不传 `--mql`。 `page_num` 从 2 取到 ceil(count/50)；第 1 页已由首查返回。 3. 翻页响应里 `list` / `session_id` 为 null，总数只能从第 1 页拿；`session_id` 与非空 MQL 同传会重新执行 MQL、回到第 1 页。

**要点**：

• 先用 `workitem meta-fields` / `workitem meta-roles` 获取字段与角色配置；查不到直接报错不要继续
• SELECT 后属性不宜过多，**优先使用字段 key**（如 `name`、`priority`、`status`）；单次最多 50 条，