Skill: kentonyu/lark-project-meegle (version 0.1.5)

--- name: meegle description: | 连接飞书项目/Meegle，查询和管理工作项、待办等。自动检测登录状态，未登录时引导 Device Code 授权。 version: 0.1.1 homepage: https://www.npmjs.com/package/@lark-project/meegle metadata: openclaw: homepage: https://www.npmjs.com/package/@lark-project/meegle emoji: 📋 requires: bins: - node - npx install: - kind: node package: '@lark-project/meegle' bins: - meegle --- # 飞书项目 (Meego/Meegle) 操作指南 本技能通过 Meegle CLI来操作飞书项目数据。输出语言跟随用户输入语言，默认中文。 > 各命令的调用示例见 [references/api-examples.md](references/api-examples.md)。 > **授权流程**（所有业务命令前必须执行）：见 [references/auth-guard.md](references/auth-guard.md) > **CLI 使用指南**（命令结构、参数传递、命令发现）：见 [references/cli-guide.md](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](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](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](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](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](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](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](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](references/misc.md)。 ### npx @lark-project/meegle@latest comment add 添加评论。支持富文本 Markdown，语法详见 [references/rich-text-editor-markdown-syntax.md](references/rich-text-editor-markdown-syntax.md)（含 @提及、对齐、链接预览、字号/颜色等扩展语法）。 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | --work-item-id | string | 是 | 工作项 ID | | --content | string | 是 | 评论内容 | --- ## 其它低频域 度量图表、子任务、关系定义查询的命令参数表见 [references/misc.md](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](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](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` | ## 通用规范 ### 请求处理流程 收到用户输入后依次执行： 1. **参数提取**：从自然语言中提取空间名、工作项类型、时间、人员、筛选条件；含 URL 时先调 `npx @lark-project/meegle@latest url decode` 解析，按 [references/url-kinds.md](references/url-kinds.md) 的 `url_kind` 分支决定进入哪个 SOP 或拒绝。**禁止**自己从 URL 截取路径段作参数。注意区分空间名与筛选维度（如「XX空间下YY业务线的缺陷」中 XX 才是空间名）。 2. **参数确认**（禁止猜测）：用探测命令校验空间（`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`（同名空间可能有多个无权限）。 3. **元数据收集**（无需用户参与）：调用 `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`）可跳过本步。 4. **执行**：调用目标命令，遵循 [references/performance.md](references/performance.md) 的并行/翻页规则。 ### 并行与大结果 详见 [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](references/error-handling.md)。 --- ## 操作指南（SOP） 具体操作的完整流程、字段转换和自愈机制见对应 SOP： - [创建工作项](references/sop-create-workitem.md) — 创建需求、任务、缺陷 - [更新工作项](references/sop-update-workitem.md) — 修改字段、更新角色、追加内容 - [流转节点（节点流）](references/sop-transition-node.md) — 完成/回滚节点、批量流转 - [流转状态（状态流）](references/sop-transition-state.md) — 流转缺陷/issue、关闭 bug


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)