飞书项目 (Meego/Meegle) 操作指南 本技能通过 Meegle CLI来操作飞书项目数据。输出语言跟随用户输入语言，默认中文。 各命令的调用示例见 references/api-examples.md 。 授权流程 （所有业务命令前必须执行）：见 references/auth-guard.md CLI 使用指南 （命令结构、参数传递、命令发现）：见 references/cli-guide.md Project 空间域 project search 搜索空间信息，将空间名转换为 project_key 或验证空间是否存在。 参数 类型 必填 说明 --project-key string 是 空间 projectKey、simpleName 或空间名称 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 时仅返回固定基础字段；如需自定义字段数据，先调 workitem meta-fields 获取字段 key 后传入 fields。 参数 类型 必填 说明 --work-item-id string 是 工作项 ID 或名称 --project-key string 否 空间 key --fields array 否 要查询的 field_key 或 field_name 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 获取。 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 Attachment 附件域 附件上传/下载分两步：先调 attachment prepare-upload / attachment prepare-download 申请带签名的对象存储 URL，再与对象存储做 HTTP 直连。Meegle CLI 提供 attachment +upload / attachment +download 一键封装。详细参数表与流程说明见 references/attachment.md 。 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 --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 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 user me 查看当前用户信息。无需参数。 MQL 中 可直接用 current_login_user() 函数，无需提前获取用户信息。如需获取当前用户的 userkey/姓名等详细信息，可用 user search 传入 current_login_user() 作为参数。 View 视图域 视图搜索与固定视图管理（ view search / view create-fixed / view update-fixed ）的参数表见 references/view.md 。 view get 根据视图 ID 获取该视图下的工作项列表。 参数 类型 必填 说明 --view-id string 是 视图 ID --project-key string 否 空间 key --page-num number 否 分页页数起点 --fields array 否 要查询的字段 Comment 评论域 评论列表查询（ comment list ）的参数表见 references/misc.md 。 comment add 添加评论。支持富文本 Markdown，语法详见 references/rich-text-editor-markdown-syntax.md （含 @提及、对齐、链接预览、字号/颜色等扩展语法）。 参数 类型 必填 说明 --work-item-id string 是 工作项 ID --content string 是 评论内容 其它低频域 度量图表、子任务、关系定义查询的命令参数表见 references/misc.md ： Chart 度量域 — chart get / chart list SubTask 子任务域 — subtask update （create/update/confirm/rollback） Relation 关系域 — relation list / relation meta-definitions 字段值格式（field_value） 🚨 STRING 协议 ： field_value 协议层固定为字符串。标量（text/number/bool/option_id/userkey/毫秒）直接作字符串；数组、对象 必须先 JSON.stringify 再传，直接传会报 need STRING type, but got: LIST / MAP 。 例：multi-user 正确写法为 "[\"7509072868295085608\"]" ，错误写法为 ["7509072868295085608"] 。 字段类型 语义 field_value 传参（已按上述约定序列化） template 模板 ID（ 创建必填 ） "145405865" — 用 workitem meta-fields(field_keys=["template"]) 获取 text / multi-pure-text / link / bool / number 单个字面值 "测试工作项" / "100" / "true" user 单个 userkey "7509072868295085608" multi-user userkey 数组（ stringified ） "[\"7509072868295085608\",\"7509072868295085609\"]" select / radio / tree-select 枚举项 option_id "437794" multi-select option_id 对象数组（ stringified ） "[{\"option_id\":\"111\"},{\"option_id\":\"222\"}]" tree-multi-select option_id 字符串数组（ stringified ） "[\"id1\",\"id2\"]" multi-text 富文本 Markdown 字符串（语法详见 references/rich-text-editor-markdown-syntax.md ） "加粗内容" date 毫秒时间戳（天精度） "1722182400000" schedule [开始ms, 结束ms] （ stringified ） "[1722182400000,1722355199999]" precise_date 对象（ stringified ） "{\"start_time\":1722182400000,\"end_time\":1722355199999}" workitem_related_select 关联工作项 ID "145405865" workitem_related_multi_select ID 数组（ stringified ，数字元素） "[145405865,145405866]" role_owners（仅创建时） 角色-人员对象数组（ stringified ） "[{\"role\":\"RD\",\"owners\":[\"userkey1\"]}]" signal 纯字符串 "true" / "false" / "null" 更新角色时不用 fields，用 workitem update 的 role_operate 参数。 关联工作项字段（workitem_related*） 用户提供名称而非 ID 时，需按名称→ID 转换流程（搜目标空间+类型，消歧，写入格式，防循环引用）：详见 references/field-value-extras.md 。 常用场景速查 场景 命令（注意点） 空间名 → project_key project search 查类型 / 字段 / 角色 workitem meta-types / workitem meta-fields / workitem meta-roles 人名 → userkey user search （批量 ≤20） 当前用户 user me ；MQL 内可直接 current_login_user() 条件查询 / 个人待办 workitem query （MQL） / mywork todo 团队排期 workhour list-schedule （≤20 人、≤3 月） 创建 / 修改工作项 workitem create / workitem update （字段 fields，角色 role_operate） 节点流转 / 状态流转 workflow transition （confirm/rollback） / workflow transition-state （先 workflow list-state-transitions ） 视图数据 view get 通用规范 请求处理流程 收到用户输入后依次执行： 参数提取 ：从自然语言中提取空间名、工作项类型、时间、人员、筛选条件；含 URL 时先调 url decode 解析，按 references/url-kinds.md 的 url_kind 分支决定进入哪个 SOP 或拒绝。 禁止 自己从 URL 截取路径段作参数。注意区分空间名与筛选维度（如「XX空间下YY业务线的缺陷」中 XX 才是空间名）。 参数确认 （禁止猜测）：用探测命令校验空间（ project search ）、类型（ workitem meta-types ）、人员（ user search ）。 探测结果不唯一时必须展示并询问用户 ，禁止自行选择；缺失必填合并为一条消息询问。个人待办（ mywork todo ）可跳过；URL 经 url decode 拿到 simple_name 后仍需 project search 转权威 project_key （同名空间可能有多个无权限）。 元数据收集 （无需用户参与）：调用 workitem meta-fields 获取字段定义（需要特定字段用 field_keys ，模糊查询用 field_query ）；涉及角色时并行调 workitem meta-roles 。关键字段识别：状态字段 type= _work_item_status （含「完成/关闭/终止」的值为完成态）、排期字段 type= schedule （MQL 用 __字段名_开始时间 / __字段名_结束时间 ）、优先级字段 key= priority 。简单直调场景（仅需 project_key + work_item_id，如 comment add ）可跳过本步。 执行 ：调用目标命令，遵循 references/performance.md 的并行/翻页规则。 并行与大结果 详见 references/performance.md ：并行调用（必须串行的链路、可并行的组合）、大结果分批与翻页规则。 错误处理 总则 ：失败后从返回的 err_msg / inner_err 中提取错误原因，针对性修正后重试； 最多自动重试 2 次 ，连续 3 次同类失败后停止并向用户说明。 熔断条件 （立即终止，禁止盲目重试）： 空间未找到（ project search 连续 3 次失败） Permission Denied（当前用户对该空间无访问权限） 详细自愈规则与错误速查表（涵盖字段格式、节点流转、人员转换等常见报错）见 references/error-handling.md 。 操作指南（SOP） 具体操作的完整流程、字段转换和自愈机制见对应 SOP： 创建工作项 — 创建需求、任务、缺陷 更新工作项 — 修改字段、更新角色、追加内容 流转节点（节点流） — 完成/回滚节点、批量流转 流转状态（状态流） — 流转缺陷/issue、关闭 bug Installs 299 Repository larksuite/meegle-cli GitHub Stars 71 First Seen Apr 22, 2026 Security Audits Gen Agent Trust Hub Pass Socket Pass Snyk Pass