Lark Project / Meegle

连接飞书项目/Meegle，查询和管理工作项、待办等。自动检测登录状态，未登录时引导 Device Code 授权。

Install

openclaw skills install @kentonyu/lark-project-meegle

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

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

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

Project 空间域

npx @lark-project/meegle@latest project search

搜索空间信息，将空间名转换为 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-roles / npx @lark-project/meegle@latest workitem meta-create-fields）的参数表见 references/workitem.md。

npx @lark-project/meegle@latest workitem create

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

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

npx @lark-project/meegle@latest workitem get

按 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-get

批量查询工作项（Meegle CLI 客户端 fan-out：并发调用 npx @lark-project/meegle@latest 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

npx @lark-project/meegle@latest workitem update

修改指定实例的字段值或角色。节点字段更新请用 npx @lark-project/meegle@latest 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 通过 npx @lark-project/meegle@latest workitem meta-roles 获取，user_keys 通过 npx @lark-project/meegle@latest user search 获取。

npx @lark-project/meegle@latest 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	否	分页信息，首次查询可不传

要点：

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

npx @lark-project/meegle@latest workitem list-op-records

查看工作项操作记录。

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

Attachment 附件域

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

WorkFlow 工作流域

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

npx @lark-project/meegle@latest 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

npx @lark-project/meegle@latest workflow transition-state

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

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

npx @lark-project/meegle@latest 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

npx @lark-project/meegle@latest 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 工作台域

npx @lark-project/meegle@latest 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 工时域

工时记录查询（npx @lark-project/meegle@latest workhour list-records）的参数表见 references/misc.md。

npx @lark-project/meegle@latest 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 人员域

团队相关命令（npx @lark-project/meegle@latest team list / npx @lark-project/meegle@latest team list-members）的参数表见 references/misc.md。

npx @lark-project/meegle@latest user search

批量查询用户基础信息。用于将姓名/邮箱转换为 userkey。

参数	类型	必填	说明
--user-keys	array	是	userKey、Email 或名字，最多 20 个
--project-key	string	否	空间 key

npx @lark-project/meegle@latest user me

查看当前用户信息。无需参数。

MQL 中可直接用 current_login_user() 函数，无需提前获取用户信息。如需获取当前用户的 userkey/姓名等详细信息，可用 npx @lark-project/meegle@latest user search 传入 current_login_user() 作为参数。

View 视图域

视图搜索与固定视图管理（npx @lark-project/meegle@latest view search / npx @lark-project/meegle@latest view create-fixed / npx @lark-project/meegle@latest view update-fixed）的参数表见 references/view.md。

npx @lark-project/meegle@latest view get

根据视图 ID 获取该视图下的工作项列表。

参数	类型	必填	说明
--view-id	string	是	视图 ID
--project-key	string	否	空间 key
--page-num	number	否	分页页数起点
--fields	array	否	要查询的字段

Comment 评论域

评论列表查询（npx @lark-project/meegle@latest comment list）的参数表见 references/misc.md。

npx @lark-project/meegle@latest comment add

添加评论。支持富文本 Markdown，语法详见 references/rich-text-editor-markdown-syntax.md（含 @提及、对齐、链接预览、字号/颜色等扩展语法）。

参数	类型	必填	说明
--work-item-id	string	是	工作项 ID
--content	string	是	评论内容

其它低频域

度量图表、子任务、关系定义查询的命令参数表见 references/misc.md：

Chart 度量域 — npx @lark-project/meegle@latest chart get / npx @lark-project/meegle@latest chart list
SubTask 子任务域 — npx @lark-project/meegle@latest subtask update（create/update/confirm/rollback）
Relation 关系域 — npx @lark-project/meegle@latest relation list / npx @lark-project/meegle@latest 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"` — 用 `npx @lark-project/meegle@latest 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，用 npx @lark-project/meegle@latest workitem update 的 role_operate 参数。

关联工作项字段（workitem_related_*）

用户提供名称而非 ID 时，需按名称→ID 转换流程（搜目标空间+类型，消歧，写入格式，防循环引用）：详见 references/field-value-extras.md。

常用场景速查

场景	命令（注意点）
空间名 → project_key	`npx @lark-project/meegle@latest project search`
查类型 / 字段 / 角色	`npx @lark-project/meegle@latest workitem meta-types` / `npx @lark-project/meegle@latest workitem meta-fields` / `npx @lark-project/meegle@latest workitem meta-roles`
人名 → userkey	`npx @lark-project/meegle@latest user search`（批量 ≤20）
当前用户	`npx @lark-project/meegle@latest user me`；MQL 内可直接 `current_login_user()`
条件查询 / 个人待办	`npx @lark-project/meegle@latest workitem query`（MQL） / `npx @lark-project/meegle@latest mywork todo`
团队排期	`npx @lark-project/meegle@latest workhour list-schedule`（≤20 人、≤3 月）
创建 / 修改工作项	`npx @lark-project/meegle@latest workitem create` / `npx @lark-project/meegle@latest workitem update`（字段 fields，角色 role_operate）
节点流转 / 状态流转	`npx @lark-project/meegle@latest workflow transition`（confirm/rollback） / `npx @lark-project/meegle@latest workflow transition-state`（先 `npx @lark-project/meegle@latest workflow list-state-transitions`）
视图数据	`npx @lark-project/meegle@latest view get`

通用规范

请求处理流程

收到用户输入后依次执行：

参数提取：从自然语言中提取空间名、工作项类型、时间、人员、筛选条件；含 URL 时先调 npx @lark-project/meegle@latest url decode 解析，按 references/url-kinds.md 的 url_kind 分支决定进入哪个 SOP 或拒绝。禁止自己从 URL 截取路径段作参数。注意区分空间名与筛选维度（如「XX空间下YY业务线的缺陷」中 XX 才是空间名）。
参数确认（禁止猜测）：用探测命令校验空间（npx @lark-project/meegle@latest project search）、类型（npx @lark-project/meegle@latest workitem meta-types）、人员（npx @lark-project/meegle@latest user search）。探测结果不唯一时必须展示并询问用户，禁止自行选择；缺失必填合并为一条消息询问。个人待办（npx @lark-project/meegle@latest mywork todo）可跳过；URL 经 url decode 拿到 simple_name 后仍需 npx @lark-project/meegle@latest project search 转权威 project_key（同名空间可能有多个无权限）。
元数据收集（无需用户参与）：调用 npx @lark-project/meegle@latest workitem meta-fields 获取字段定义（需要特定字段用 field_keys，模糊查询用 field_query）；涉及角色时并行调 npx @lark-project/meegle@latest workitem meta-roles。关键字段识别：状态字段 type=_work_item_status（含「完成/关闭/终止」的值为完成态）、排期字段 type=schedule（MQL 用 __字段名_开始时间 / __字段名_结束时间）、优先级字段 key=priority。简单直调场景（仅需 project_key + work_item_id，如 npx @lark-project/meegle@latest comment add）可跳过本步。
执行：调用目标命令，遵循 references/performance.md 的并行/翻页规则。

并行与大结果

详见 references/performance.md：并行调用（必须串行的链路、可并行的组合）、大结果分批与翻页规则。

错误处理

总则：失败后从返回的 err_msg / inner_err 中提取错误原因，针对性修正后重试；最多自动重试 2 次，连续 3 次同类失败后停止并向用户说明。

熔断条件（立即终止，禁止盲目重试）：

空间未找到（npx @lark-project/meegle@latest project search 连续 3 次失败）
Permission Denied（当前用户对该空间无访问权限）

详细自愈规则与错误速查表（涵盖字段格式、节点流转、人员转换等常见报错）见 references/error-handling.md。

操作指南（SOP）

具体操作的完整流程、字段转换和自愈机制见对应 SOP：

创建工作项 — 创建需求、任务、缺陷
更新工作项 — 修改字段、更新角色、追加内容
流转节点（节点流） — 完成/回滚节点、批量流转
流转状态（状态流） — 流转缺陷/issue、关闭 bug