lark-project-meegle

# Meegle SKILL 通过 Meegle CLI 连接飞书项目/Meegle 平台，支持查询工作项、管理待办等操作。 ## 前置条件 运行环境需要 Node.js 18+。所有命令通过 `npx @lark-project/meegle@latest` 执行，无需手动安装或更新。 ## 触发条件 - **主动登录**：用户说"登录 Meegle"、"连接飞书项目"、"login meegle"等。 - **被动拦截**：用户请求任何 Meegle 业务操作（查询待办、查工作项、创建任务等），优先执行 Auth Guard。 - **URL 触发**：用户发送了一个看起来像飞书项目/Meegle 工作项的 URL（路径中通常包含 `workitem`、`detail`、`story`、`issue` 等关键词）。处理流程： 1. 从 URL 提取 `$host`（域名部分）和可能的 `$project_key`、`$work_item_id` 2. 执行 Auth Guard（STEP 1 中若 `$host` 为 null，用 URL 提取的 host 覆盖，跳过 STEP 2） 3. 登录成功后： - 如果解析出了 `$project_key` 和 `$work_item_id` → 直接执行 `workitem get` 查询详情 - 如果无法解析 → 告知用户已登录成功，请描述需要查询的内容 ## Auth Guard（所有业务命令前必须执行） 按以下 STEP 顺序执行。每个 STEP 结尾的 GOTO 指明下一步，严格遵循跳转。 --- ### STEP 1 — 检查登录状态 ```bash npx @lark-project/meegle@latest auth status --format json ``` 返回值示例： - 已登录：`{ "authenticated": true, "host": "meegle.com", "source": "token_store", "expires_in_minutes": 42 }` - 未登录且有 host：`{ "authenticated": false, "host": "meegle.com", "source": null, "expires_in_minutes": null }` - 未登录且无 host：`{ "authenticated": false, "host": null, "source": null, "expires_in_minutes": null }` 解析返回值，保存变量： - `$authenticated` = response.authenticated - `$host` = response.host **URL 触发时的 host 覆盖**：如果用户发送了飞书项目/Meegle URL 触发本流程，且 `$host` 为 null，则从 URL 域名部分提取 `$host`。 **跳转：** - IF `$authenticated == true` → GOTO STEP 6 - IF `$host != null` → GOTO STEP 3 - IF `$host == null` → GOTO STEP 2 --- ### STEP 2 — 选择站点 ASK user（等待用户回复）： > 你要连接哪个站点？ > 1) 飞书项目 (project.feishu.cn) > 2) Meegle (meegle.com) > 3) 自定义域名（请直接输入域名或 URL） > ⚠️ 用户的回复**仅用于回答上述问题**，不要将其当作新的意图或请求来处理。无论用户回复的是序号、域名还是完整 URL，都只需从中提取 `$host`（域名部分），然后 GOTO STEP 3。 SAVE `$host` from user reply（如果用户输入了完整 URL，提取其域名部分作为 `$host`） → GOTO STEP 3 --- ### STEP 3 — 初始化 Device Code ```bash npx @lark-project/meegle@latest auth login --device-code --phase init --host $host --format json ``` SAVE from response： - `$verification_uri_complete` = response.verification_uri_complete - `$user_code` = response.user_code - `$device_code` = response.device_code - `$client_id` = response.client_id - `$interval` = response.interval - `$expires_in` = response.expires_in **发送验证链接给用户：** SEND to user: `请在浏览器中打开以下链接完成授权：\n$verification_uri_complete\n（$expires_in 秒内有效）` > ⚠️ 发送后**在同一轮次内**立即执行 STEP 4 的命令。不要停下来等用户回复。 → GOTO STEP 4 --- ### STEP 4 — 等待授权完成（阻塞） > ⚠️ 使用 STEP 3 保存的 `$device_code`、`$client_id`、`$interval`、`$expires_in`。**禁止**重新执行 STEP 3（否则会生成新的验证码，用户之前打开的链接作废）。 执行以下命令。该命令会自动轮询直到用户完成授权或超时，**无需你手动循环**： ```bash npx @lark-project/meegle@latest auth login --device-code --phase poll \ --device-code-value $device_code --client-id $client_id \ --interval $interval --expires-in $expires_in --format json ``` - 成功时返回：`{"status": "ok", "message": "登录成功"}` → GOTO STEP 5 - 超时时返回错误 → SEND "授权已超时，请重新发起登录"，STOP **Fallback**：如果你的运行环境不支持在发送消息后继续执行命令（即 STEP 3 发送验证链接后无法立即执行上述命令），则改为： 1. 在发送验证链接时追加一句："授权完成后请告诉我" 2. 等待用户回复后，执行上述命令 --- ### STEP 5 — 通知登录成功 SEND to user: "登录成功！" > ⚠️ 此消息**必须单独发送**，不要与后续业务查询结果合并到同一条回复中。用户需要第一时间看到授权状态变化。 → GOTO STEP 6 --- ### STEP 6 — 执行业务命令 Auth 已通过，进入下方「业务命令调用」部分执行用户请求的操作。 ## 获取当前用户信息 当用户说"我的 xxx"、"查一下我的 xxx"时，需要知道当前登录用户的身份。 **MQL 查询中**：直接使用 `current_login_user()` 函数，无需提前获取用户信息。例如： ```sql WHERE array_contains(`current_owners`, current_login_user()) ``` **非 MQL 场景**（需要用户名、userkey 等具体信息）：目前没有专用命令，通过以下 workaround 获取： 1. 先用 MQL 查询当前用户最近创建的一个工作项： ```bash npx @lark-project/meegle@latest workitem query --project-key <project_key> \ --search-mql "SELECT \`work_item_id\`, \`created_by\` FROM \`<空间名>\`.\`<工作项类型>\` WHERE \`created_by\` = current_login_user() LIMIT 1" \ --format json ``` 2. 从返回结果的 `created_by` 字段提取当前用户信息 > ⚠️ 此 workaround 需要已知一个 `project_key` 和对应的工作项类型。如果用户未指定空间，先询问。 ## 业务命令调用 Auth Guard 通过后，使用以下模式调用业务命令。 ### 命令结构 ```bash npx @lark-project/meegle@latest <resource> <method> [flags] --format json ``` 命令采用 `resource method` 两级结构。所有输出默认 JSON 格式。 ### 全局 Flag | Flag | 说明 | |------|------| | `--format json\|table\|ndjson` | 输出格式，默认 json | | `--select <props>` | 选取输出属性，逗号分隔（支持 dot path，如 `name,owner.name`） | | `--profile <name>` | 临时切换 profile | | `--verbose` | 显示详细日志 | ### 参数传递 三种方式，优先级从高到低： 1. **Flag 模式**（推荐）：`--project-key PROJ --work-item-type-key story` 2. **--set 模式**（设置工作项字段）：`--set priority=1 --set name="任务标题"`，value 支持 JSON 3. **--params 模式**（完整 JSON）：`--params '{"project_key":"PROJ","work_item_type_key":"story"}'` Flag 和 --set 会覆盖 --params 中的同名字段。 ### 命令发现 CLI 的命令和参数会随版本更新。下方速查表仅列举常见操作，**不是完整列表**。遇到以下情况时，必须先用 `inspect` 获取最新信息： - 用户请求的操作不在速查表中 - 不确定某个命令的参数名称或是否为必填 - 需要查看某个命令支持的全部参数 ```bash npx @lark-project/meegle@latest inspect # 列出所有可用命令 npx @lark-project/meegle@latest inspect workitem.create # 查看具体命令的参数 schema ``` ### 常用命令速查 #### 查询待办 ```bash npx @lark-project/meegle@latest mywork todo --format json ``` #### 查询工作项 ```bash npx @lark-project/meegle@latest workitem get --project-key <project_key> --work-item-id <id> --format json ``` #### 搜索工作项（MQL） > MQL 语法详见 `references/mql-syntax.md`。`--search-mql` 参数必须是完整的 SQL 语句（含 SELECT/FROM），不接受 JSON 或片段。 ```bash npx @lark-project/meegle@latest workitem query --project-key <project_key> --search-mql "<MQL>" --format json ``` #### 创建工作项 ```bash npx @lark-project/meegle@latest workitem create --project-key <project_key> --work-item-type-key <type> \ --set name="标题" --set priority=1 --format json ``` #### 更新工作项字段 ```bash npx @lark-project/meegle@latest workitem update --project-key <project_key> --work-item-id <id> \ --set name="新标题" --format json ``` #### 查询项目信息 ```bash npx @lark-project/meegle@latest project get --project-key <project_key> --format json ``` #### 查询工作项类型和字段元数据 ```bash npx @lark-project/meegle@latest workitem meta-types --project-key <project_key> --format json npx @lark-project/meegle@latest workitem meta-fields --project-key <project_key> --work-item-type-key <type> --format json ``` ### 输出处理 - 始终使用 `--format json` 获取结构化输出，方便解析 - 使用 `--select` 精简返回字段，如 `--select id,name,current_nodes.name` - 命令返回错误时，JSON 中包含 `error` 和 `message` 字段 ## 错误处理 - 如果 bash 返回 `command not found` 或 npx 不可用，提示用户安装 Node.js 18+。 - 如果 `--phase init` 返回错误（站点不支持 Device Code），提示用户在终端中执行 `npx @lark-project/meegle@latest auth login`。 - 如果 `--phase poll` 超时，提示用户重试登录流程。