Lark Project / Meegle

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

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

各命令的调用示例见 references/API-examples.md。 授权流程（所有业务命令前必须执行）：见 references/auth-防护.md 命令行工具 使用指南（命令结构、参数传递、命令发现）：见 references/命令行工具-图形界面de.md

Project 空间域 npx @lark-project/meegle@latest project 搜索

搜索空间信息，将空间名转换为 project_key 或验证空间是否存在。

参数 类型 必填 说明 --project-key string 是 空间 projectKey、simpleName 或空间名称 WorkItem 工作项域

元数据查询命令（npx @lark-project/meegle@latest workitem meta-types / npx @lark-project/meegle@latest workitem meta-fields / npx @lark-project/meegle@latest workitem meta-角色s / npx @lark-project/meegle@latest workitem meta-创建-fields）的参数表见 references/workitem.md。

npx @lark-project/meegle@latest workitem 创建

创建工作项实例。务必先用 npx @lark-project/meegle@latest workitem meta-fields 获取字段信息，npx @lark-project/meegle@latest workitem meta-角色s 获取角色信息。模板 ID 是必填项。

参数 类型 必填 说明 --work-item-type string 是 工作项类型 --project-key string 否 空间标识 --fields array 否 字段值列表，每项含 field_key 和 field_value npx @lark-project/meegle@latest workitem 获取

按 ID/名称查询工作项概况。不传 fields 时仅返回固定基础字段；如需自定义字段数据，先调 npx @lark-project/meegle@latest workitem meta-fields 获取字段 key 后传入 fields。

参数 类型 必填 说明 --work-item-id string 是 工作项 ID 或名称 --project-key string 否 空间 key --fields array 否 要查询的 field_key 或 field_name npx @lark-project/meegle@latest workitem batch-获取

批量查询工作项（Meegle 命令行工具 客户端 fan-out：并发调用 npx @lark-project/meegle@latest workitem 获取）。单次 ≤ 200 个 ID，3 并发，返回 {结果s, errors, summary}；ID 量大时用 --格式化 ndjson 流式输出。

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

修改指定实例的字段值或角色。节点字段更新请用 npx @lark-project/meegle@latest 工作流 更新-node。

参数 类型 必填 说明 --work-item-id string 是 工作项 ID 或名称 --project-key string 否 空间 key --fields array 否 要更新的字段列表，每项含 field_key 和 field_value --角色-operate array 否 角色操作，每项含 op(添加/移除)、角色_key、user_keys

角色更新：不能通过 fields 更新角色，必须用 角色_operate。角色_key 通过 npx @lark-project/meegle@latest workitem meta-角色s 获取，user_keys 通过 npx @lark-project/meegle@latest user 搜索 获取。

npx @lark-project/meegle@latest workitem 查询

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

参数 类型 必填 说明 --project-key string 是 空间标识（支持名称、simpleName、projectKey） --mql string 是（翻页时可用 会话_id 替代） MQL 查询语句（完整 SQL） --会话-id string 否 分页会话 ID，传入后不解析 MQL 直接翻页 --group-pagination-列出 array 否 分页信息，首次查询可不传

要点：

先用 npx @lark-project/meegle@latest workitem meta-fields / npx @lark-project/meegle@latest workitem meta-角色s 获取字段与角色配置；查不到直接报错不要继续 SELECT 后属性不宜过多，优先使用字段 key（如 name、priority、状态）；返回按页返回，需全量时使用翻页参数 npx @lark-project/meegle@latest workitem 列出-op-records

查看工作项操作记录。

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

附件上传/下载分两步：先调 npx @lark-project/meegle@latest attachment prepare-上传 / npx @lark-project/meegle@latest attachment prepare-下载 申请带签名的对象存储 URL，再与对象存储做 HTTP 直连。Meegle 命令行工具 提供 npx @lark-project/meegle@latest attachment +上传 / npx @lark-project/meegle@latest attachment +下载 一键封装。详细参数表与流程说明见 references/attachment.md。

工作流 工作流域

流转辅助命令（npx @lark-project/meegle@latest 工作流 列出-状态-transitions / npx @lark-project/meegle@latest 工作流 列出-状态-required / npx @lark-project/meegle@latest 工作流 meta-node-fields）的参数表见 references/工作流.md。

npx @lark-project/meegle@latest 工作流 transition

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

参数 类型 必填 说明 --work-item-id string 是 工作项 ID --action string 否 confirm（流转） / 回滚（回滚） --node-id string 否 节点 ID --node-ids array 否 节点名称或节点 ID 列表 --回滚-reason string 否 回滚原因，action=回滚 时需填写 --project-key string 否 空间 key npx @lark-project/meegle@latest 工作流 transition-状态

仅用于状态流工作项，流转工作项状态。先用 npx @lark-project/meegle@latest 工作流 列出-状态-transitions 获取可流转状态及 transition_id。

参数 类型 必填 说明 --work-item-id string 是 工作项 ID --transition-id string 否 状态流转 ID，从 npx @lark-project/meegle@latest 工作流 列出-状态-transitions 获取 --project-key string 否 空间 key npx @lark-project/meegle@latest 工作流 获取-node

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

参数 类型 必填 说明 --work-item-id string 是 工作项 ID 或名称 --node-id-列出 array 否 节点 ID 列表，传空或 _all 获取所有节点 --field-key-列出 array 否 节点字段 key，传空或 _all 获取所有字段 --need-sub-task boolean 否 是否需要节点子项（子任务） --page-num number 否 节点信息一次最多 20 个，按页返回 --project-key string 否 空间 key npx @lark-project/meegle@latest 工作流 更新-node

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

参数 类型 必填 说明 --work-item-id string 是 工作项 ID --node-id string 是 节点 ID（node_key） --node-owners array 否 节点负责人 userkey 数组；清空传空数组 [] --node-schedule object 否 节点排期，格式 {"estimate_启动_date":ms,"estimate_end_date":ms,"owners":[userkey],"points":数字}；清空传 {}；不变更则不传 --schedules array 否 按人差异化排期，每项细化到单个人的排期；清空某人则 estimate_启动_date/estimate_end_date 传 null --fields array 否 节点自定义字段，每项含 field_key 和 field_value（STRING 协议，见「字段值格式」） --project-key string 否 空间 key MyWork 工作台域 npx @lark-project/meegle@latest mywork todo

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