Meegle

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

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

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

Project 空间域

project search

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

WorkItem 工作项域

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

workitem create

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

workitem get

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

逻辑字段聚合（重要心智模型）：服务端把 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 流式输出。

workitem update

修改指定实例的字段值或角色。节点字段更新须用 workflow update-node。

角色更新：不能通过 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。

workitem query

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

分组分页：

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

查看工作项操作记录。

Attachment 附件域

附件必须完成“对象存储上传 → 目标字段绑定 → 回读同一字段验收”；上传成功不代表附件字段已写入。涉及工作项附件时，必须先实时消歧当前类型下的 file 和 multi-file 字段，并按 references/attachment.md 的完整协议执行。Meegle CLI 提供 attachment +upload / attachment +download 一键封装对象存储步骤。 ---

WorkFlow 工作流域

流转辅助命令（workflow list-state-transitions / workflow list-state-required / workflow meta-node-fields）的参数表见 references/workflow.md。

workflow transition

仅用于节点流工作项，操作节点完成流转或回滚。

workflow transition-state

仅用于状态流工作项，流转工作项状态。先用 workflow list-state-transitions 获取可流转状态及 transition_id。

workflow get-node

获取工作项中指定节点或所有节点的完整详情。

workflow update-node

修改节点（排期、负责人、自定义字段等）。排期/差异化排期/负责人不要同时修改，需分多次调用。

MyWork 工作台域

mywork todo

按 action 类型查询当前用户的工作项列表。无需 MQL 即可查询待办/已办。

需完整结果时，从 page_num=1 连续翻页直到空为止。

WorkHour 工时域

工时记录查询（workhour list-records）的参数表见 references/misc.md。

workhour list-schedule

获取指定人员在时间区间内的排期与工作量明细。