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/auth-guard.md CLI 使用指南 （命令结构、参数传递、命令发现）：见 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 。 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 。 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 否 分组分页信息，首次查询可不传；翻页时传 [{ "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 附件域 附件必须完成“对象存储上传 → 目标字段绑定 → 回读同一字段验收”；上传成功不代表附件字段已写入。涉及工作项附件时，必须先实时消歧当前类型下的 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 仅用于节点流工作项，操作节点完成流转或回滚。 参数 类型 必填 说明 --work-item-id string 是 工作项 ID --action string 否 confirm（流转） / rollback（回滚） --node-id string 否 节点 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 workflow update-node 修改节点（排期、负责人、自定义字段等）。排期/差异化排期/负责人不要同时修改，需分多次调用。 参数 类型 必填 说明 --work-item-id string 是 工作项 ID --node-id string 是 节点 ID（node_key） --node-owners array 否 节点负责人 userkey 数组；清空传空数组 [] --node-schedule object 否 节点排期，格式 {"estimate_start_date":ms,"estimate_end_date":ms,"owners":[userkey],"points":数字} ；清空传 {} ；不变更则不传 --schedules array 否 按人差异化排期，每项细化到单个人的排期；清空某人则 estimate_start_date / estimate_end_date 传 null --fields array 否 节点自定义字段，每项含 field_key 和 field_value （STRING 协议，见「字段值格式」） --project-key string 否 空间 key 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-records ）的参数表见 references/misc.md 。 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 个月（超出按月拆分）；所有批次完成后再汇总，未完整获取前不得输出结论。 UserGroup 人员域 团队相关命令（ team list / team list-members ）的参数表见 references/misc.md 。 user search 批量查询用户基础信息。用于将姓名/邮箱转换为 userkey。 参数 类型 必填 说明 --user-keys array 是 userKey、Email 或名字，最多 20 个 --project-key string 否 空间 key