{"id":"0e181ceb-9c58-4b02-aa14-5d1ac1954a04","entityType":"agent","slug":"clawhub-kentonyu-lark-project-meegle","name":"Lark Project / Meegle","canonicalUrl":"https://www.xpersona.co/agent/clawhub-kentonyu-lark-project-meegle","canonicalPath":"/agent/clawhub-kentonyu-lark-project-meegle","generatedAt":"2026-10-09T22:39:56.047Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:35:41.795Z","emptyReason":null},"description":"连接飞书项目/Meegle，查询和管理工作项、待办等。自动检测登录状态，未登录时引导 Device Code 授权。","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.2K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17ed9cseebq57g4cnzc7tb04983qx22:lark-project-meegle","sourceUrl":"https://clawhub.ai/kentonyu/lark-project-meegle","homepage":"https://clawhub.ai/kentonyu/skills/lark-project-meegle","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/kentonyu/lark-project-meegle","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/kentonyu/skills/lark-project-meegle","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":55,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Lark Project / Meegle technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:35:41.795Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:35:41.795Z","emptyReason":null},"stars":null,"forks":null,"downloads":2202,"packageName":null,"latestVersion":"0.1.5","tractionLabel":"2.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:35:41.795Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T17:35:41.795Z","lastCrawledAt":"2026-10-09T17:35:41.795Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T17:35:41.795Z","lastVerifiedAt":null,"highlights":[{"version":"0.1.5","createdAt":"2026-05-08T07:16:59.212Z","changelog":"**Added comprehensive CLI reference docs and modularized main SKILL file.** - Added 13 new detailed docs in the `references/` directory (e.g. api-examples, auth-guard, mql-syntax, attachment, workflow). - Rewrote the main SKILL guide for conciseness and clarity; moved command/argument details to separate linked reference files. - Improved organization: each CLI domain (WorkItem, Project, Attachment, Workflow, etc.) now links to its own reference doc for argument tables and advanced usage. - Enhanced focus on modular doc structure for easier command maintenance and more scalable documentation.","fileCount":17,"zipByteSize":38125},{"version":"0.1.4","createdAt":"2026-04-01T06:22:55.328Z","changelog":"lark-project-meegle 0.1.4 - 更新 Auth Guard 登录流程：站点选择（STEP 2）现在支持用户直接输入完整 URL，自动提取域名，无需区分输入类型。 - Device Code 授权流程（STEP 3、STEP 4）调整为默认一次性阻塞轮询授权，无需手动 sleep 和循环命令。 - 优化验证链接提示文案，告知授权有效期。 - 兼容部分运行环境无法阻塞的情景，提供 fallback 流程指引用户授权完成后再继续。 - 其他文档描述与流程细节修正，提升易用性与健壮性。","fileCount":3,"zipByteSize":8418},{"version":"0.1.3","createdAt":"2026-03-31T08:21:07.303Z","changelog":"- Switched all Meegle CLI invocations from the beta version tag (@beta) to the latest version tag (@latest). - Updated documentation and command samples to use @latest for improved compatibility and future updates. - No functional or file changes were detected otherwise.","fileCount":3,"zipByteSize":8244},{"version":"0.1.2","createdAt":"2026-03-30T05:53:16.647Z","changelog":"lark-project-meegle 0.1.2 - 新增 references/mql-syntax.md 文件，补充 MQL 查询语法参考。 - SKILL.md 增加“URL 触发”说明，支持识别并处理用户发送的 Meegle/飞书项目工作项链接。 - 优化登录 Auth Guard 流程，支持从 URL 自动提取 $host 并跳过站点选择。 - 补充“获取当前用户信息”方法，说明 MQL 及非 MQL 场景下的处理。 - 明确 MQL 查询必须使用完整 SQL 语句。 - 丰富命令发现与错误处理规则说明。","fileCount":3,"zipByteSize":8245},{"version":"0.1.1","createdAt":"2026-03-27T13:19:10.990Z","changelog":"- Major update: Auth Guard 交互逻辑重构，采用 STEP 流程（step-by-step 跳转），指令顺序和条件更加清晰。 - 登录流程拆分为 6 个明确步骤，加入严格 GOTO 流程指引，消除含糊流程描述。 - 轮询授权结果的流程显式串联，确保主动循环等待授权，不再等待用户手动确认。 - Feishu/Lark 渠道授权提示支持消息卡片和降级文本双方案。 - `my todo` 命令改为 `mywork todo`。 - skill 名称由 \"meegle\" 改为 \"lark-project-meegle\"；version 升级至 0.1.1。","fileCount":2,"zipByteSize":3754},{"version":"0.1.0","createdAt":"2026-03-27T11:45:56.253Z","changelog":"Initial release with core Meegle CLI integration for Feishu Project/Meegle. - Supports querying and managing work items, todos, and project info via Meegle CLI. - Implements automatic login status detection with device code authentication flow and interactive host selection. - Proactively polls for authorization after sending verification link—users see \"login successful\" immediately upon completion. - Auth guard required before all business commands; comprehensive error handling for missing dependencies and auth failures. - Detailed command patterns, flag/parameter options, and quick command reference included. - Includes command inspection to view schema and arguments for Meegle commands.","fileCount":2,"zipByteSize":3553}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17ed9cseebq57g4cnzc7tb04983qx22:lark-project-meegle","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17ed9cseebq57g4cnzc7tb04983qx22:lark-project-meegle` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/kentonyu/lark-project-meegle before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kentonyu-lark-project-meegle/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kentonyu-lark-project-meegle/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kentonyu-lark-project-meegle/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kentonyu-lark-project-meegle/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kentonyu-lark-project-meegle/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kentonyu-lark-project-meegle/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T22:39:56.044Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kentonyu-lark-project-meegle/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kentonyu-lark-project-meegle/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kentonyu-lark-project-meegle/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kentonyu-lark-project-meegle/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:35:41.795Z","emptyReason":null},"readme":"Skill: Lark Project / Meegle\n\nOwner: kentonyu\n\nSummary: 连接飞书项目/Meegle，查询和管理工作项、待办等。自动检测登录状态，未登录时引导 Device Code 授权。\n\nTags: beta:0.1.2, latest:0.1.5\n\nVersion history:\n\nv0.1.5 | 2026-05-08T07:16:59.212Z | user\n\n**Added comprehensive CLI reference docs and modularized main SKILL file.**\n\n- Added 13 new detailed docs in the `references/` directory (e.g. api-examples, auth-guard, mql-syntax, attachment, workflow).\n- Rewrote the main SKILL guide for conciseness and clarity; moved command/argument details to separate linked reference files.\n- Improved organization: each CLI domain (WorkItem, Project, Attachment, Workflow, etc.) now links to its own reference doc for argument tables and advanced usage.\n- Enhanced focus on modular doc structure for easier command maintenance and more scalable documentation.\n\nv0.1.4 | 2026-04-01T06:22:55.328Z | user\n\nlark-project-meegle 0.1.4\n\n- 更新 Auth Guard 登录流程：站点选择（STEP 2）现在支持用户直接输入完整 URL，自动提取域名，无需区分输入类型。\n- Device Code 授权流程（STEP 3、STEP 4）调整为默认一次性阻塞轮询授权，无需手动 sleep 和循环命令。\n- 优化验证链接提示文案，告知授权有效期。\n- 兼容部分运行环境无法阻塞的情景，提供 fallback 流程指引用户授权完成后再继续。\n- 其他文档描述与流程细节修正，提升易用性与健壮性。\n\nv0.1.3 | 2026-03-31T08:21:07.303Z | user\n\n- Switched all Meegle CLI invocations from the beta version tag (@beta) to the latest version tag (@latest).\n- Updated documentation and command samples to use @latest for improved compatibility and future updates.\n- No functional or file changes were detected otherwise.\n\nv0.1.2 | 2026-03-30T05:53:16.647Z | user\n\nlark-project-meegle 0.1.2\n\n- 新增 references/mql-syntax.md 文件，补充 MQL 查询语法参考。\n- SKILL.md 增加“URL 触发”说明，支持识别并处理用户发送的 Meegle/飞书项目工作项链接。\n- 优化登录 Auth Guard 流程，支持从 URL 自动提取 $host 并跳过站点选择。\n- 补充“获取当前用户信息”方法，说明 MQL 及非 MQL 场景下的处理。\n- 明确 MQL 查询必须使用完整 SQL 语句。\n- 丰富命令发现与错误处理规则说明。\n\nv0.1.1 | 2026-03-27T13:19:10.990Z | user\n\n- Major update: Auth Guard 交互逻辑重构，采用 STEP 流程（step-by-step 跳转），指令顺序和条件更加清晰。\n- 登录流程拆分为 6 个明确步骤，加入严格 GOTO 流程指引，消除含糊流程描述。\n- 轮询授权结果的流程显式串联，确保主动循环等待授权，不再等待用户手动确认。\n- Feishu/Lark 渠道授权提示支持消息卡片和降级文本双方案。\n- `my todo` 命令改为 `mywork todo`。\n- skill 名称由 \"meegle\" 改为 \"lark-project-meegle\"；version 升级至 0.1.1。\n\nv0.1.0 | 2026-03-27T11:45:56.253Z | user\n\nInitial release with core Meegle CLI integration for Feishu Project/Meegle.\n\n- Supports querying and managing work items, todos, and project info via Meegle CLI.\n- Implements automatic login status detection with device code authentication flow and interactive host selection.\n- Proactively polls for authorization after sending verification link—users see \"login successful\" immediately upon completion.\n- Auth guard required before all business commands; comprehensive error handling for missing dependencies and auth failures.\n- Detailed command patterns, flag/parameter options, and quick command reference included.\n- Includes command inspection to view schema and arguments for Meegle commands.\n\nArchive index:\n\nArchive v0.1.5: 17 files, 38125 bytes\n\nFiles: references/api-examples.md (7092b), references/attachment.md (3988b), references/auth-guard.md (4774b), references/cli-guide.md (2378b), references/error-handling.md (2611b), references/field-value-extras.md (1590b), references/misc.md (3098b), references/mql-syntax.md (22885b), references/performance.md (1315b), references/rich-text-editor-markdown-syntax.md (11255b), references/url-kinds.md (6823b), references/view.md (1126b), references/workflow.md (1709b), references/workitem.md (1947b), skill-card.md (2608b), SKILL.md (19960b), _meta.json (138b)\n\nFile v0.1.5:SKILL.md\n\n---\nname: meegle\ndescription: |\n 连接飞书项目/Meegle，查询和管理工作项、待办等。自动检测登录状态，未登录时引导 Device Code 授权。\nversion: 0.1.1\nhomepage: https://www.npmjs.com/package/@lark-project/meegle\nmetadata:\n openclaw:\n homepage: https://www.npmjs.com/package/@lark-project/meegle\n emoji: 📋\n requires:\n bins:\n - node\n - npx\n install:\n - kind: node\n package: '@lark-project/meegle'\n bins:\n - meegle\n---\n\n# 飞书项目 (Meego/Meegle) 操作指南\n\n本技能通过 Meegle CLI来操作飞书项目数据。输出语言跟随用户输入语言，默认中文。\n\n> 各命令的调用示例见 [references/api-examples.md](references/api-examples.md)。\n> **授权流程**（所有业务命令前必须执行）：见 [references/auth-guard.md](references/auth-guard.md)\n> **CLI 使用指南**（命令结构、参数传递、命令发现）：见 [references/cli-guide.md](references/cli-guide.md)\n\n---\n\n## Project 空间域\n\n### npx @lark-project/meegle@latest project search\n搜索空间信息，将空间名转换为 project_key 或验证空间是否存在。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 projectKey、simpleName 或空间名称 |\n\n---\n\n## WorkItem 工作项域\n\n> 元数据查询命令（`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)。\n\n### npx @lark-project/meegle@latest workitem create\n创建工作项实例。**务必先用 `npx @lark-project/meegle@latest workitem meta-fields` 获取字段信息，`npx @lark-project/meegle@latest workitem meta-roles` 获取角色信息。模板 ID 是必填项。**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --work-item-type | string | 是 | 工作项类型 |\n| --project-key | string | 否 | 空间标识 |\n| --fields | array | 否 | 字段值列表，每项含 field_key 和 field_value |\n\n### npx @lark-project/meegle@latest workitem get\n按 ID/名称查询工作项概况。不传 fields 时仅返回固定基础字段；如需自定义字段数据，先调 `npx @lark-project/meegle@latest workitem meta-fields` 获取字段 key 后传入 fields。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --work-item-id | string | 是 | 工作项 ID 或名称 |\n| --project-key | string | 否 | 空间 key |\n| --fields | array | 否 | 要查询的 field_key 或 field_name |\n\n### npx @lark-project/meegle@latest workitem batch-get\n批量查询工作项（Meegle CLI 客户端 fan-out：并发调用 `npx @lark-project/meegle@latest workitem get`）。单次 ≤ 200 个 ID，3 并发，返回 `{results, errors, summary}`；ID 量大时用 `--format ndjson` 流式输出。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --work-item-ids | array | 二选一 | 工作项 ID 列表（逗号分隔或多次传入） |\n| --ids-file | string | 二选一 | 从文件读取 ID（一行一个，`#` 开头注释） |\n| --fields | array | 否 | 要查询的 field_key 列表 |\n| --project-key | string | 否 | 空间 key |\n\n### npx @lark-project/meegle@latest workitem update\n修改指定实例的字段值或角色。节点字段更新请用 `npx @lark-project/meegle@latest workflow update-node`。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --work-item-id | string | 是 | 工作项 ID 或名称 |\n| --project-key | string | 否 | 空间 key |\n| --fields | array | 否 | 要更新的字段列表，每项含 field_key 和 field_value |\n| --role-operate | array | 否 | 角色操作，每项含 op(add/remove)、role_key、user_keys |\n\n**角色更新**：不能通过 fields 更新角色，必须用 `role_operate`。role_key 通过 `npx @lark-project/meegle@latest workitem meta-roles` 获取，user_keys 通过 `npx @lark-project/meegle@latest user search` 获取。\n\n### npx @lark-project/meegle@latest workitem query\n使用 MQL 查询工作项数据。语法详见 [references/mql-syntax.md](references/mql-syntax.md)。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间标识（支持名称、simpleName、projectKey） |\n| --mql | string | 是（翻页时可用 session_id 替代） | MQL 查询语句（完整 SQL） |\n| --session-id | string | 否 | 分页会话 ID，传入后不解析 MQL 直接翻页 |\n| --group-pagination-list | array | 否 | 分页信息，首次查询可不传 |\n\n**要点**：\n- 先用 `npx @lark-project/meegle@latest workitem meta-fields` / `npx @lark-project/meegle@latest workitem meta-roles` 获取字段与角色配置；查不到直接报错不要继续\n- SELECT 后属性不宜过多，**优先使用字段 key**（如 `name`、`priority`、`status`）；返回按页返回，需全量时使用翻页参数\n\n### npx @lark-project/meegle@latest workitem list-op-records\n查看工作项操作记录。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 key |\n| --work-item-id | string | 是 | 工作项 ID |\n\n---\n\n## Attachment 附件域\n\n附件上传/下载分两步：先调 `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)。\n\n---\n\n## WorkFlow 工作流域\n\n> 流转辅助命令（`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)。\n\n### npx @lark-project/meegle@latest workflow transition\n仅用于节点流工作项，操作节点完成流转或回滚。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --work-item-id | string | 是 | 工作项 ID |\n| --action | string | 否 | confirm（流转） / rollback（回滚） |\n| --node-id | string | 否 | 节点 ID |\n| --node-ids | array | 否 | 节点名称或节点 ID 列表 |\n| --rollback-reason | string | 否 | 回滚原因，action=rollback 时需填写 |\n| --project-key | string | 否 | 空间 key |\n\n### npx @lark-project/meegle@latest workflow transition-state\n仅用于状态流工作项，流转工作项状态。先用 `npx @lark-project/meegle@latest workflow list-state-transitions` 获取可流转状态及 transition_id。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --work-item-id | string | 是 | 工作项 ID |\n| --transition-id | string | 否 | 状态流转 ID，从 `npx @lark-project/meegle@latest workflow list-state-transitions` 获取 |\n| --project-key | string | 否 | 空间 key |\n\n### npx @lark-project/meegle@latest workflow get-node\n获取工作项中指定节点或所有节点的完整详情。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --work-item-id | string | 是 | 工作项 ID 或名称 |\n| --node-id-list | array | 否 | 节点 ID 列表，传空或 `_all` 获取所有节点 |\n| --field-key-list | array | 否 | 节点字段 key，传空或 `_all` 获取所有字段 |\n| --need-sub-task | boolean | 否 | 是否需要节点子项（子任务） |\n| --page-num | number | 否 | 节点信息一次最多 20 个，按页返回 |\n| --project-key | string | 否 | 空间 key |\n\n### npx @lark-project/meegle@latest workflow update-node\n修改节点（排期、负责人、自定义字段等）。排期/差异化排期/负责人不要同时修改，需分多次调用。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --work-item-id | string | 是 | 工作项 ID |\n| --node-id | string | 是 | 节点 ID（node_key） |\n| --node-owners | array | 否 | 节点负责人 userkey 数组；清空传空数组 `[]` |\n| --node-schedule | object | 否 | 节点排期，格式 `{\"estimate_start_date\":ms,\"estimate_end_date\":ms,\"owners\":[userkey],\"points\":数字}`；清空传 `{}`；不变更则不传 |\n| --schedules | array | 否 | 按人差异化排期，每项细化到单个人的排期；清空某人则 `estimate_start_date`/`estimate_end_date` 传 null |\n| --fields | array | 否 | 节点自定义字段，每项含 `field_key` 和 `field_value`（STRING 协议，见「字段值格式」） |\n| --project-key | string | 否 | 空间 key |\n\n---\n\n## MyWork 工作台域\n\n### npx @lark-project/meegle@latest mywork todo\n按 action 类型查询当前用户的工作项列表。无需 MQL 即可查询待办/已办。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --action | string | 是 | todo(待办)/done(已办)/overdue(逾期)/this_week(本周待办) |\n| --page-num | number | 是 | 页码，从 1 开始，每页 50 条 |\n| --asset-key | string | 否 | 工作区 key（格式 Asset_xxx），仅在报错需要选择时传 |\n\n需完整结果时，从 page_num=1 连续翻页直到空为止。\n\n---\n\n## WorkHour 工时域\n\n> 工时记录查询（`npx @lark-project/meegle@latest workhour list-records`）的参数表见 [references/misc.md](references/misc.md)。\n\n### npx @lark-project/meegle@latest workhour list-schedule\n获取指定人员在时间区间内的排期与工作量明细。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 key |\n| --user-keys | array | 是 | 用户标识（名称/邮箱/userkey），**每次最多 20 个** |\n| --start-time | string | 是 | 开始时间，格式 YYYY-MM-DD |\n| --end-time | string | 是 | 结束时间，格式 YYYY-MM-DD，**单次跨度最大 3 个月** |\n| --work-item-type-keys | array | 否 | 工作项类型列表，查询所有传入 `_all` |\n\n**调用约束**：每次最多 20 人（多人拆批次并行）；单次跨度 ≤ 3 个月（超出按月拆分）；所有批次完成后再汇总，未完整获取前不得输出结论。\n\n---\n\n## UserGroup 人员域\n\n> 团队相关命令（`npx @lark-project/meegle@latest team list` / `npx @lark-project/meegle@latest team list-members`）的参数表见 [references/misc.md](references/misc.md)。\n\n### npx @lark-project/meegle@latest user search\n批量查询用户基础信息。用于将姓名/邮箱转换为 userkey。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --user-keys | array | 是 | userKey、Email 或名字，最多 20 个 |\n| --project-key | string | 否 | 空间 key |\n\n### npx @lark-project/meegle@latest user me\n查看当前用户信息。无需参数。\n\n> **MQL 中**可直接用 `current_login_user()` 函数，无需提前获取用户信息。如需获取当前用户的 userkey/姓名等详细信息，可用 `npx @lark-project/meegle@latest user search` 传入 `current_login_user()` 作为参数。\n\n---\n\n## View 视图域\n\n> 视图搜索与固定视图管理（`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)。\n\n### npx @lark-project/meegle@latest view get\n根据视图 ID 获取该视图下的工作项列表。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --view-id | string | 是 | 视图 ID |\n| --project-key | string | 否 | 空间 key |\n| --page-num | number | 否 | 分页页数起点 |\n| --fields | array | 否 | 要查询的字段 |\n\n---\n\n## Comment 评论域\n\n> 评论列表查询（`npx @lark-project/meegle@latest comment list`）的参数表见 [references/misc.md](references/misc.md)。\n\n### npx @lark-project/meegle@latest comment add\n添加评论。支持富文本 Markdown，语法详见 [references/rich-text-editor-markdown-syntax.md](references/rich-text-editor-markdown-syntax.md)（含 @提及、对齐、链接预览、字号/颜色等扩展语法）。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --work-item-id | string | 是 | 工作项 ID |\n| --content | string | 是 | 评论内容 |\n\n---\n\n## 其它低频域\n\n度量图表、子任务、关系定义查询的命令参数表见 [references/misc.md](references/misc.md)：\n\n- **Chart 度量域** — `npx @lark-project/meegle@latest chart get` / `npx @lark-project/meegle@latest chart list`\n- **SubTask 子任务域** — `npx @lark-project/meegle@latest subtask update`（create/update/confirm/rollback）\n- **Relation 关系域** — `npx @lark-project/meegle@latest relation list` / `npx @lark-project/meegle@latest relation meta-definitions`\n\n---\n\n## 字段值格式（field_value）\n\n> 🚨 **STRING 协议**：`field_value` 协议层固定为字符串。标量（text/number/bool/option_id/userkey/毫秒）直接作字符串；数组、对象**必须先 JSON.stringify** 再传，直接传会报 `need STRING type, but got: LIST` / `MAP`。\n> 例：multi-user 正确写法为 `\"[\\\"7509072868295085608\\\"]\"`，错误写法为 `[\"7509072868295085608\"]`。\n\n| 字段类型 | 语义 | field_value 传参（已按上述约定序列化） |\n|---------|------|------|\n| template | 模板 ID（**创建必填**） | `\"145405865\"` — 用 `npx @lark-project/meegle@latest workitem meta-fields(field_keys=[\"template\"])` 获取 |\n| text / multi-pure-text / link / bool / number | 单个字面值 | `\"测试工作项\"` / `\"100\"` / `\"true\"` |\n| user | 单个 userkey | `\"7509072868295085608\"` |\n| multi-user | userkey 数组（**stringified**） | `\"[\\\"7509072868295085608\\\",\\\"7509072868295085609\\\"]\"` |\n| select / radio / tree-select | 枚举项 option_id | `\"437794\"` |\n| multi-select | option_id 对象数组（**stringified**） | `\"[{\\\"option_id\\\":\\\"111\\\"},{\\\"option_id\\\":\\\"222\\\"}]\"` |\n| tree-multi-select | option_id 字符串数组（**stringified**） | `\"[\\\"id1\\\",\\\"id2\\\"]\"` |\n| multi-text | 富文本 Markdown 字符串（语法详见 [references/rich-text-editor-markdown-syntax.md](references/rich-text-editor-markdown-syntax.md)） | `\"**加粗**内容\"` |\n| date | 毫秒时间戳（天精度） | `\"1722182400000\"` |\n| schedule | `[开始ms, 结束ms]`（**stringified**） | `\"[1722182400000,1722355199999]\"` |\n| precise_date | 对象（**stringified**） | `\"{\\\"start_time\\\":1722182400000,\\\"end_time\\\":1722355199999}\"` |\n| workitem_related_select | 关联工作项 ID | `\"145405865\"` |\n| workitem_related_multi_select | ID 数组（**stringified**，数字元素） | `\"[145405865,145405866]\"` |\n| role_owners（仅创建时） | 角色-人员对象数组（**stringified**） | `\"[{\\\"role\\\":\\\"RD\\\",\\\"owners\\\":[\\\"userkey1\\\"]}]\"` |\n| signal | 纯字符串 | `\"true\"` / `\"false\"` / `\"null\"` |\n\n> 更新角色时不用 fields，用 `npx @lark-project/meegle@latest workitem update` 的 `role_operate` 参数。\n\n### 关联工作项字段（workitem_related_*）\n\n用户提供名称而非 ID 时，需按名称→ID 转换流程（搜目标空间+类型，消歧，写入格式，防循环引用）：详见 [references/field-value-extras.md](references/field-value-extras.md)。\n\n---\n\n## 常用场景速查\n\n| 场景 | 命令（注意点） |\n|------|-------|\n| 空间名 → project_key | `npx @lark-project/meegle@latest project search` |\n| 查类型 / 字段 / 角色 | `npx @lark-project/meegle@latest workitem meta-types` / `npx @lark-project/meegle@latest workitem meta-fields` / `npx @lark-project/meegle@latest workitem meta-roles` |\n| 人名 → userkey | `npx @lark-project/meegle@latest user search`（批量 ≤20） |\n| 当前用户 | `npx @lark-project/meegle@latest user me`；MQL 内可直接 `current_login_user()` |\n| 条件查询 / 个人待办 | `npx @lark-project/meegle@latest workitem query`（MQL） / `npx @lark-project/meegle@latest mywork todo` |\n| 团队排期 | `npx @lark-project/meegle@latest workhour list-schedule`（≤20 人、≤3 月） |\n| 创建 / 修改工作项 | `npx @lark-project/meegle@latest workitem create` / `npx @lark-project/meegle@latest workitem update`（字段 fields，角色 role_operate） |\n| 节点流转 / 状态流转 | `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`） |\n| 视图数据 | `npx @lark-project/meegle@latest view get` |\n\n\n## 通用规范\n\n### 请求处理流程\n\n收到用户输入后依次执行：\n\n1. **参数提取**：从自然语言中提取空间名、工作项类型、时间、人员、筛选条件；含 URL 时先调 `npx @lark-project/meegle@latest url decode` 解析，按 [references/url-kinds.md](references/url-kinds.md) 的 `url_kind` 分支决定进入哪个 SOP 或拒绝。**禁止**自己从 URL 截取路径段作参数。注意区分空间名与筛选维度（如「XX空间下YY业务线的缺陷」中 XX 才是空间名）。\n\n2. **参数确认**（禁止猜测）：用探测命令校验空间（`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`（同名空间可能有多个无权限）。\n\n3. **元数据收集**（无需用户参与）：调用 `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`）可跳过本步。\n\n4. **执行**：调用目标命令，遵循 [references/performance.md](references/performance.md) 的并行/翻页规则。\n\n### 并行与大结果\n\n详见 [references/performance.md](references/performance.md)：并行调用（必须串行的链路、可并行的组合）、大结果分批与翻页规则。\n\n### 错误处理\n\n**总则**：失败后从返回的 `err_msg` / `inner_err` 中提取错误原因，针对性修正后重试；**最多自动重试 2 次**，连续 3 次同类失败后停止并向用户说明。\n\n**熔断条件**（立即终止，禁止盲目重试）：\n- 空间未找到（`npx @lark-project/meegle@latest project search` 连续 3 次失败）\n- Permission Denied（当前用户对该空间无访问权限）\n\n详细自愈规则与错误速查表（涵盖字段格式、节点流转、人员转换等常见报错）见 [references/error-handling.md](references/error-handling.md)。\n\n---\n\n## 操作指南（SOP）\n\n具体操作的完整流程、字段转换和自愈机制见对应 SOP：\n\n- [创建工作项](references/sop-create-workitem.md) — 创建需求、任务、缺陷\n- [更新工作项](references/sop-update-workitem.md) — 修改字段、更新角色、追加内容\n- [流转节点（节点流）](references/sop-transition-node.md) — 完成/回滚节点、批量流转\n- [流转状态（状态流）](references/sop-transition-state.md) — 流转缺陷/issue、关闭 bug\n\nFile v0.1.5:_meta.json\n\n{\n \"ownerId\": \"kn78dhc955jdhgxvfjp6fd9aeh83p3t5\",\n \"slug\": \"lark-project-meegle\",\n \"version\": \"0.1.5\",\n \"publishedAt\": 1778224619212\n}\n\nFile v0.1.5:references/api-examples.md\n\n# 命令调用示例\n\n---\n\n## 空间域\n\n### npx @lark-project/meegle@latest project search\n```bash\nnpx @lark-project/meegle@latest project search --project-key 空间名或key --format json\n```\n\n## 工作项域\n\n### npx @lark-project/meegle@latest workitem meta-types\n```bash\nnpx @lark-project/meegle@latest workitem meta-types --project-key 空间key --format json\n```\n\n### npx @lark-project/meegle@latest workitem meta-fields\n查询所有字段：\n\n```bash\nnpx @lark-project/meegle@latest workitem meta-fields --page-num 1 --project-key 空间key --work-item-type story --field-types '{{field_types}}' --field-keys '{{field_keys}}' --field-query '{{field_query}}' --format json\n```\n\n### npx @lark-project/meegle@latest workitem meta-roles\n```bash\nnpx @lark-project/meegle@latest workitem meta-roles --page-num 1 --project-key 空间key --work-item-type story --role-keys '{{role_keys}}' --role-query '{{role_query}}' --format json\n```\n\n### npx @lark-project/meegle@latest workitem query\n查询空间中所有未冻结的需求：\n\n```bash\nnpx @lark-project/meegle@latest workitem query --project-key 空间key --session-id {{session_id}} --mql 'SELECT `work_item_id`, `name`, `current_owners`, `status` FROM `空间名`.`story` WHERE `is_archived` = 0' --group-pagination-list '{{group_pagination_list}}' --format json\n```\n\n### npx @lark-project/meegle@latest workitem get\n```bash\nnpx @lark-project/meegle@latest workitem get --work-item-id 工作项ID或名称 --fields '{{fields}}' --project-key 空间key --format json\n```\n\n### npx @lark-project/meegle@latest workitem create\n基础创建（仅标量字段）：\n\n```bash\nnpx @lark-project/meegle@latest workitem create --work-item-type story --fields '[{\"field_key\": \"template\", \"field_value\": \"模板ID\"}, {\"field_key\": \"name\", \"field_value\": \"需求标题\"}]' --project-key 空间key --format json\n```\n\n创建缺陷 + 指定报告人（multi-user）+ 指定经办人（role_owners）——注意复合值必须 JSON.stringify：\n\n```bash\nnpx @lark-project/meegle@latest workitem create --work-item-type issue --fields '[{\"field_key\":\"name\",\"field_value\":\"示例缺陷\"},{\"field_key\":\"priority\",\"field_value\":\"2\"},{\"field_key\":\"template\",\"field_value\":\"模板ID\"},{\"field_key\":\"issue_reporter\",\"field_value\":\"[\"userkey1\"]\"},{\"field_key\":\"role_owners\",\"field_value\":\"[{\"role\":\"operator\",\"owners\":[\"userkey1\"]}]\"}]' --project-key 空间key --format json\n```\n\n> 🚨 `issue_reporter`（multi-user 类型的内置角色字段）和 `role_owners`（统一角色入口）是**两种可互换的写法**：前者走 meta-create-fields 返回的字段 key；后者用 meta-roles 返回的 role_id（如 `operator` / `reporter`，不含 `issue_` 前缀）。两者的 `field_value` 都必须是 **stringified JSON** 字符串。\n\n### npx @lark-project/meegle@latest workitem update\n更新普通字段：\n\n```bash\nnpx @lark-project/meegle@latest workitem update --work-item-id 工作项ID --project-key 空间key --role-operate '{{role_operate}}' --fields '[{\"field_key\": \"priority\", \"field_value\": \"option_id\"}]' --format json\n```\n\n更新 multi-user 字段（复合值 stringified）：\n\n```bash\nnpx @lark-project/meegle@latest workitem update --work-item-id 工作项ID --project-key 空间key --role-operate '{{role_operate}}' --fields '[{\"field_key\": \"current_status_operator\", \"field_value\": \"[\"userkey1\",\"userkey2\"]\"}]' --format json\n```\n\n---\n\n## 人员域\n\n### npx @lark-project/meegle@latest user search\n```bash\nnpx @lark-project/meegle@latest user search --user-keys '[\"张三\", \"李四\"]' --project-key {{project_key}} --format json\n```\n\n### npx @lark-project/meegle@latest user me\n```bash\nnpx @lark-project/meegle@latest user me --format json\n```\n\n---\n\n## 工作台域\n\n### npx @lark-project/meegle@latest mywork todo\n查询我的待办：\n\n```bash\nnpx @lark-project/meegle@latest mywork todo --action todo --page-num 1 --asset-key {{asset_key}} --format json\n```\n\n---\n\n## 工时域\n\n### npx @lark-project/meegle@latest workhour list-schedule\n```bash\nnpx @lark-project/meegle@latest workhour list-schedule --start-time 2025-03-01 --end-time 2025-03-31 --project-key 空间key --user-keys '[\"张三\", \"李四\"]' --work-item-type-keys '{{work_item_type_keys}}' --format json\n```\n\n---\n\n## 视图域\n\n### npx @lark-project/meegle@latest view get\n```bash\nnpx @lark-project/meegle@latest view get --view-id 视图ID --project-key 空间key --fields '{{fields}}' --page-num {{page_num}} --format json\n```\n\n---\n\n## 工作流域\n\n### npx @lark-project/meegle@latest workflow get-node\n```bash\nnpx @lark-project/meegle@latest workflow get-node --work-item-id 工作项ID --field-key-list '{{field_key_list}}' --need-sub-task {{need_sub_task}} --page-num {{page_num}} --project-key 空间key --node-id-list '[\"节点ID或_all\"]' --format json\n```\n\n### npx @lark-project/meegle@latest workflow transition\n完成节点（节点流）：\n\n```bash\nnpx @lark-project/meegle@latest workflow transition --work-item-id 工作项ID --node-ids '{{node_ids}}' --project-key 空间key --node-id 节点ID --action confirm --rollback-reason '{{rollback_reason}}' --format json\n```\n\n### npx @lark-project/meegle@latest workflow transition-state\n流转状态（状态流）：\n\n```bash\nnpx @lark-project/meegle@latest workflow transition-state --work-item-id 工作项ID --project-key 空间key --transition-id 流转ID --format json\n```\n\n### npx @lark-project/meegle@latest workflow list-state-transitions\n```bash\nnpx @lark-project/meegle@latest workflow list-state-transitions --work-item-id 工作项ID --work-item-type story --user-key userkey --project-key 空间key --format json\n```\n\n---\n\n## 评论域\n\n### npx @lark-project/meegle@latest comment add\n```bash\nnpx @lark-project/meegle@latest comment add --work-item-id 工作项ID --content '评论内容' --project-key {{project_key}} --format json\n```\n\n### npx @lark-project/meegle@latest comment list\n```bash\nnpx @lark-project/meegle@latest comment list --work-item-id 工作项ID --project-key 空间key --page-num {{page_num}} --start-time {{start_time}} --end-time {{end_time}} --format json\n```\n\n---\n\n## 关系域\n\n### npx @lark-project/meegle@latest relation meta-definitions\n```bash\nnpx @lark-project/meegle@latest relation meta-definitions --project-key 空间key --work-item-type {{work_item_type}} --relation-work-item-type {{relation_work_item_type}} --format json\n```\n\n### npx @lark-project/meegle@latest relation list\n```bash\nnpx @lark-project/meegle@latest relation list --project-key 空间key --work-item-id 工作项ID --page-size {{page_size}} --relation-field-key {{relation_field_key}} --node-id {{node_id}} --relation-id {{relation_id}} --page-num {{page_num}} --format json\n```\n\n---\n\n## 子任务域\n\n### npx @lark-project/meegle@latest subtask update\n```bash\nnpx @lark-project/meegle@latest subtask update --node-id 节点ID --project-key {{project_key}} --task-id {{task_id}} --assignee '{{assignee}}' --work-item-id 工作项ID --role-assignee '{{role_assignee}}' --fields '{{fields}}' --schedule '{{schedule}}' --action create --deliverable '{{deliverable}}' --format json\n```\n\nFile v0.1.5:references/attachment.md\n\n# 附件域\n\n附件上传/下载分两步：先调 `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` 一键封装，把两步合成一条命令；脚本里需要逐步控制时也可单独调上面的 prepare 命令。\n## npx @lark-project/meegle@latest attachment prepare-upload\n申请上传签名。`work_item_id` 与 `work_item_type` **二选一必填**：已有工作项传 `work_item_id`；\"创建工作项时同步上传附件\" 场景传 `work_item_type`，两者同传时 `work_item_id` 优先。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 key |\n| --resource-type | number | 是 | 附件场景：13=评论附件 / 14=评论图片 / 15=工作项附件字段 / 16=富文本字段图片 |\n| --file-name | string | 是 | 附件名称 |\n| --mime-type | string | 是 | MIME 类型 |\n| --size | number | 是 | 文件总大小（字节）；后端据此判断走单次上传还是分片 |\n| --work-item-id | string | 二选一 | 已有工作项 ID |\n| --work-item-type | string | 二选一 | 工作项类型（仅 \"创建工作项同步上传附件\" 场景） |\n| --field-key | string | 条件 | `resource_type=15/16` 必填，13/14 不填 |\n\n## npx @lark-project/meegle@latest attachment prepare-download\n申请下载签名。`file_url` 是其它命令（如 `npx @lark-project/meegle@latest workitem get` 的附件字段值、`npx @lark-project/meegle@latest comment list` 评论里的附件链接、富文本中的附件引用）回传的不透明引用，**不要**手工拼接。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 key |\n| --work-item-id | string | 是 | 工作项 ID |\n| --file-url | string | 是 | 附件 URL（来自附件字段、评论或富文本） |\n\n## npx @lark-project/meegle@latest attachment +upload\n端到端上传：CLI 在本地把 `npx @lark-project/meegle@latest attachment prepare-upload` 与对象存储的签名 HTTP POST 串起来，返回 `file_token` 与文件元数据，可直接喂给 `npx @lark-project/meegle@latest workitem create` / `npx @lark-project/meegle@latest workitem update` / `npx @lark-project/meegle@latest comment add` 的附件字段。**Meegle CLI 专用**。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| ``（位置参数） | string | 是 | 本地文件路径 |\n| --resource-type | string | 是 | 13/14/15/16，含义同 `npx @lark-project/meegle@latest attachment prepare-upload` |\n| --project-key | string | 是 | 空间 key |\n| --work-item-id | string | 二选一 | 已有工作项 ID |\n| --work-item-type | string | 二选一 | 创建场景的工作项类型 |\n| --field-key | string | 条件 | resource_type=15/16 时必填 |\n| --filename | string | 否 | 覆盖发送给后端的文件名（默认取本地 basename） |\n| --content-type | string | 否 | 覆盖 MIME 类型（默认按扩展名探测，未识别走 `application/octet-stream`） |\n\n## npx @lark-project/meegle@latest attachment +download\n端到端下载：CLI 在本地把 `npx @lark-project/meegle@latest attachment prepare-download` 与对象存储的签名 HTTP GET 串起来，并用 `.partial` 临时文件 + 原子改名落盘，失败时不会留下半残文件。**Meegle CLI 专用**。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| ``（位置参数） | string | 是 | 附件 URL（来自附件字段、评论或富文本） |\n| --project-key | string | 是 | 空间 key |\n| --work-item-id | string | 是 | 工作项 ID |\n| --output | string | 是 | 本地落地路径 |\n| overwrite | bool | 否 | 目标已存在时是否覆盖（默认 false） |\n\nFile v0.1.5:references/auth-guard.md\n\n# Auth Guard（所有业务命令前必须执行）\n\n## 触发条件\n\n- **主动登录**：用户说\"登录 Meegle\"、\"连接飞书项目\"、\"login meegle\"等。\n- **被动拦截**：用户请求任何 Meegle 业务操作（查询待办、查工作项、创建任务等），优先执行 Auth Guard。\n- **URL 触发**：用户发送了飞书项目/Meegle URL。处理流程：\n 1. 先调 `npx @lark-project/meegle@latest url decode` 拿到结构化字段（`url_kind`、`host`、`simple_name`、`work_item_id` 等）。**禁止**自己从 URL 截取路径段作参数。字段含义与 kind 分支见 [url-kinds.md](./url-kinds.md)。\n 2. 保存 `$host` = response.host、`$url_kind`、`$simple_name`、`$work_item_id`。\n 3. 执行 Auth Guard（下面的 STEP 1 起）。\n 4. 登录成功后按 `$url_kind` 分支：\n - `workitem_detail` → `npx @lark-project/meegle@latest project search` 得权威 `$project_key`，再 `npx @lark-project/meegle@latest workitem get` 查询详情\n - `workitem_homepage` / `view_*` / `unknown` 等非详情页 → 按 url-kinds.md 的指引拒绝或追问\n - 其他 kind → 参考 url-kinds.md 对应处理方式\n\n按以下 STEP 顺序执行。每个 STEP 结尾的 GOTO 指明下一步，严格遵循跳转。\n\n---\n\n### STEP 1 — 检查登录状态\n\n```bash\nnpx @lark-project/meegle@latest auth status --format json\n```\n\n返回值示例：\n- 已登录：`{ \"authenticated\": true, \"host\": \"meegle.com\", \"source\": \"token_store\", \"expires_in_minutes\": 42 }`\n- 未登录且有 host：`{ \"authenticated\": false, \"host\": \"meegle.com\", \"source\": null, \"expires_in_minutes\": null }`\n- 未登录且无 host：`{ \"authenticated\": false, \"host\": null, \"source\": null, \"expires_in_minutes\": null }`\n\n解析返回值，保存变量：\n- `$authenticated` = response.authenticated\n- `$host` = response.host\n\n**URL 触发时的 host 覆盖**：如果用户发送了飞书项目/Meegle URL 触发本流程，且 `$host` 为 null，则使用上一步 `url decode` 返回的 `host` 字段作为 `$host`。\n\n**跳转：**\n- IF `$authenticated == true` → GOTO STEP DONE\n- IF `$host != null` → GOTO STEP 2\n- IF `$host == null` → GOTO STEP HOST\n\n---\n\n### STEP HOST — 选择站点\n\nASK user（等待用户回复）：\n\n> 你要连接哪个站点？\n> 1) 飞书项目 (project.feishu.cn)\n> 2) Meegle (meegle.com)\n> 3) 自定义域名（请直接输入域名）\n\nSAVE `$host` from user reply → GOTO STEP 2\n\n---\n\n### STEP 2 — 初始化 Device Code\n\n```bash\nnpx @lark-project/meegle@latest auth login --device-code --phase init --host $host --format json\n```\n\nSAVE from response：\n- `$verification_uri_complete` = response.verification_uri_complete\n- `$user_code` = response.user_code\n- `$device_code` = response.device_code\n- `$client_id` = response.client_id\n- `$interval` = response.interval\n- `$expires_in` = response.expires_in\n- `$max_attempts` = floor($expires_in / $interval)\n\n**发送验证链接给用户：**\n\nSEND to user: `请在浏览器中打开以下链接完成授权：\\n$verification_uri_complete\\n验证码：$user_code（$expires_in 秒内有效）`\n\n> ⚠️ 发送后立即 GOTO STEP 3。**禁止**在此停下等用户回复\"我授权好了\"。你必须主动轮询。\n\n→ GOTO STEP 3\n\n---\n\n### STEP 3 — 轮询授权结果（循环）\n\n> ⚠️ 使用 STEP 2 保存的 `$device_code` 和 `$client_id`。**禁止**重新执行 STEP 2（否则会生成新的验证码，用户之前打开的链接作废）。\n\n```bash\nsleep $interval && npx @lark-project/meegle@latest auth login --device-code --phase poll --once \\\n --device-code-value $device_code --client-id $client_id --format json\n```\n\nPARSE response → `$status` = response.status\n\n**跳转：**\n- IF `$status == \"ok\"` → GOTO STEP OK\n- IF `$status == \"authorization_pending\"` → GOTO STEP 3（重复本步骤，继续轮询）\n- IF `$status == \"slow_down\"` → `$interval = $interval + 5`，GOTO STEP 3\n- IF `$status == \"expired_token\"` → SEND \"授权已超时，请重新发起登录\"，STOP\n- IF attempts > `$max_attempts` → SEND \"轮询超时，请重试\"，STOP\n\n---\n\n### STEP OK — 通知登录成功\n\nSEND to user: \"登录成功！\"\n\n> ⚠️ 此消息**必须单独发送**，不要与后续业务查询结果合并到同一条回复中。用户需要第一时间看到授权状态变化。\n\n→ GOTO STEP DONE\n\n---\n\n### STEP DONE — 执行业务命令\n\nAuth 已通过，执行用户请求的操作。\n\n## 错误处理\n\n- 如果 bash 返回 `command not found` 或 npx 不可用，提示用户安装 Node.js 18+。\n- 如果 `--phase init` 返回错误（站点不支持 Device Code），提示用户在终端中执行 `npx @lark-project/meegle@latest auth login`。\n- 如果 `--phase poll` 超时，提示用户重试登录流程。\n\nFile v0.1.5:references/cli-guide.md\n\n# CLI 使用指南\n\n## 前置条件\n\n运行环境需要 Node.js 18+。所有命令通过 `npx @lark-project/meegle@latest` 执行。\n\n## 命令结构\n\n```bash\nnpx @lark-project/meegle@latest [flags] --format json\n```\n\n命令采用 `resource method` 两级结构。所有输出推荐使用 `--format json` 获取结构化数据。\n\n## 全局 Flag\n\n| Flag | 说明 |\n|------|------|\n| `--format json\\|table\\|ndjson` | 输出格式，默认 json |\n| `--select ` | 选取输出属性，逗号分隔（支持 dot path，如 `name,owner.name`） |\n| `--profile ` | 临时切换 profile |\n| `--verbose` | 显示详细日志 |\n| `--refresh` | 从服务端刷新本地命令缓存（旁路 24h cache） |\n\n## 参数传递\n\n几种方式，优先级从高到低：\n\n1. **Flag 模式**（推荐）：`--project-key PROJ --work-item-type story`\n2. **--fields 模式**（写工作项字段，可重复）：`--fields '{\"field_key\":\"name\",\"field_value\":\"任务标题\"}' --fields '{\"field_key\":\"priority\",\"field_value\":\"1\"}'`；`field_value` 支持任意 JSON 值（数组/对象原样传）\n3. **--params 模式**（完整 JSON 兜底）：`--params '{\"fields\":[{\"field_key\":\"name\",\"field_value\":\"任务标题\"}]}'`\n4. **--set 模式**（仅顶层参数快捷写法，不支持 fields[]）：`--set page_num=1` 等价于 `--page-num 1`，支持 dot-path 嵌套；不要用它写工作项字段\n\nFlag 覆盖 `--params`；`--set` 只影响顶层参数，**不会**写到 `fields[]`。\n\n## 命令发现\n\nCLI 的命令和参数会随版本更新。遇到不确定的命令或参数时，使用 `inspect` 获取最新信息：\n\n```bash\nnpx @lark-project/meegle@latest inspect # 列出所有可用命令\nnpx @lark-project/meegle@latest inspect workitem.create # 查看具体命令的参数 schema\n```\n\n> 命令清单本地缓存 24 小时。如果 `inspect` 输出的参数与服务端实际不符，或服务端有新命令但 CLI 报 `unknown command`，加上 `--refresh` 强制从服务端重新拉取最新清单：\n> ```bash\n> npx @lark-project/meegle@latest --refresh inspect workitem.create\n> ```\n\n## 输出处理\n\n- 始终使用 `--format json` 获取结构化输出，方便解析\n- 使用 `--select` 精简返回字段，如 `--select id,name,current_nodes.name`\n- 命令返回错误时，JSON 中包含 `error` 和 `message` 字段\n\nFile v0.1.5:references/error-handling.md\n\n# 错误处理详细规则\n\nSKILL.md 主文件已经收录错误处理总则与熔断条件，本文件提供完整的自愈规则与错误速查表。\n\n## 自愈规则（按报错特征匹配修复后重试）\n\n| 报错特征 | 自愈动作 |\n|---------|---------|\n| `need STRING type, but got: LIST` / `MAP` | field_value 从原生 JSON 改为 JSON.stringify 后的字符串（见 SKILL.md「字段值格式」） |\n| `cannot unmarshal object...` | 仅改变格式（数字↔字符串、单值↔数组、对象↔纯字符串），值不变 |\n| `不满足层级配置`（级联层级错误） | 查 `children` 树，展示末级叶子节点让用户选择 |\n| `invalid select option(s)`（枚举不合法） | 从 `possible values` 匹配；唯一匹配则修正重试，否则询问用户 |\n\n## 错误速查\n\n| 现象 | 排查/修复 |\n|------|---------|\n| 找不到空间 / 中文名匹配多个空间 | `npx @lark-project/meegle@latest project search` 验证，取 project_key 精确调用 |\n| 找不到工作项类型 | `npx @lark-project/meegle@latest workitem meta-types` 确认合法 type_key |\n| 字段名错误 / MQL 返回为空但数据存在 | `npx @lark-project/meegle@latest workitem meta-fields` 确认字段 key 与类型 |\n| MQL 查询失败 | FROM 用 `` `空间名`.`工作项类型` ``；数组字段改用 `array_contains` / `any_match` |\n| 日期区间字段查询失败 | 用子字段 `` `__字段名_开始时间` `` |\n| 角色查询无结果 | MQL 角色名用 `` `__{角色名}` `` 格式 |\n| 人名/团队名重复 | MQL 用 `` 消歧（见 MQL 语法参考） |\n| 人名→userkey 失败 | `npx @lark-project/meegle@latest user search` 批量查询 |\n| 人员字段写入失败 | user 传单个 userkey 字符串；multi-user 必须 stringified 如 `\"[\\\"k1\\\",\\\"k2\\\"]\"` |\n| node not found | 先 `npx @lark-project/meegle@latest workitem get` 获取真实 node_id，禁止猜测 |\n| 节点流转失败 | 节点流用 `npx @lark-project/meegle@latest workflow transition`；状态流用 `npx @lark-project/meegle@latest workflow transition-state`（先 `npx @lark-project/meegle@latest workflow list-state-transitions` 取 transition_id，再 `npx @lark-project/meegle@latest workflow list-state-required` 查必填项） |\n| 创建工作项缺少模板 | `npx @lark-project/meegle@latest workitem meta-fields(field_keys=[\"template\"])` 获取 |\n| 角色更新失败 | 改用 `npx @lark-project/meegle@latest workitem update` 的 `role_operate` 参数（不走 fields） |\n| mywork.todo 需选择工作区 | 按报错中的列表把 `asset_key`（Asset_xxx）传入重试 |\n\nFile v0.1.5:references/field-value-extras.md\n\n# 字段值进阶：关联工作项名称 → ID 转换\n\n当用户为 `workitem_related_select` / `workitem_related_multi_select` 字段提供的是**工作项名称而非 ID** 时，按以下流程转换后再写入。\n\n1. **获取关联字段的目标约束**：从 `npx @lark-project/meegle@latest workitem meta-fields` 返回的该字段配置中，提取其绑定的**目标空间**（`project_key`）和**目标工作项类型**（`work_item_type_key`）。若配置未限定（可关联任意类型），默认在当前空间内搜索。\n2. **按名称搜索目标工作项**：调用 `npx @lark-project/meegle@latest workitem query`，在目标空间和类型范围内按名称匹配。示例 MQL：\n ```sql\n SELECT `工作项ID`, `名称` FROM `目标空间`.`目标类型` WHERE `名称` = '用户给的名称'\n ```\n 精确匹配无结果时改用 `like '%关键词%'` 模糊搜索。\n3. **消歧处理**：\n - 唯一结果 → 直接取工作项 ID\n - 多个结果 → 列出所有匹配项（ID + 名称 + 状态）让用户确认\n - 零结果 → 提示用户\"未找到名为 XXX 的工作项，请确认名称或直接提供 ID\"\n4. **写入格式**：\n - `workitem_related_select` → 传入单个 ID 字符串\n - `workitem_related_multi_select` → 传入 stringified ID 数组\n - 不同空间可能要求字符串或数字格式，遇类型校验失败立刻切换格式重试\n5. **循环引用保护**：写入前必须排查当前工作项自身 ID，**禁止将自身 ID 写入关联字段**，否则会触发 `exists loop`（循环引用）报错。\n\nFile v0.1.5:references/misc.md\n\n# 其它低频命令\n\n低频/单命令小域的参数表汇总。涵盖团队、图表、子任务、关系、评论查询、工时记录。\n\n---\n\n## 团队\n\n### npx @lark-project/meegle@latest team list\n查看空间下的团队列表。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 否 | 空间 key |\n\n### npx @lark-project/meegle@latest team list-members\n查看团队成员列表。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 key |\n| --team-id | string | 是 | 团队 ID |\n\n---\n\n## 度量图表\n\n### npx @lark-project/meegle@latest chart get\n查看图表详情。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --chart-id | string | 是 | 图表 ID |\n\n### npx @lark-project/meegle@latest chart list\n查看视图下的图表列表。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 key |\n| --view-id | string | 是 | 视图 ID |\n\n---\n\n## 子任务\n\n### npx @lark-project/meegle@latest subtask update\n创建/修改/完成/回滚子任务。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --node-id | string | 是 | 节点 ID |\n| --work-item-id | string | 是 | 工作项 ID |\n| --action | string | 是 | create/update/confirm/rollback |\n\n---\n\n## 关系\n\n### npx @lark-project/meegle@latest relation list\n查看关联的工作项列表。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 key |\n| --work-item-id | string | 是 | 工作项 ID |\n| --relation-field-key | string | 否 | 关联关系字段 key，从 `npx @lark-project/meegle@latest relation meta-definitions` 获取 |\n| --relation-id | string | 否 | 关联关系 ID，从 `npx @lark-project/meegle@latest relation meta-definitions` 获取 |\n| --node-id | string | 否 | 节点 ID，查询某节点下的关联时传入 |\n| --page-num | number | 否 | 分页页码，从 1 开始 |\n| --page-size | number | 否 | 每页数量，最大 50 |\n\n### npx @lark-project/meegle@latest relation meta-definitions\n查看空间下的关联关系定义。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 key |\n\n---\n\n## 评论查询\n\n### npx @lark-project/meegle@latest comment list\n查看评论列表。添加评论用 `npx @lark-project/meegle@latest comment add`（见 SKILL.md 主文件）。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 key |\n| --work-item-id | string | 是 | 工作项 ID |\n\n---\n\n## 工时记录\n\n### npx @lark-project/meegle@latest workhour list-records\n查看工作项的工时登记记录。团队排期用 `npx @lark-project/meegle@latest workhour list-schedule`（见 SKILL.md 主文件）。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 key |\n| --work-item-type | string | 是 | 工作项类型 |\n| --work-item-id | string | 是 | 工作项 ID |\n\nFile v0.1.5:references/mql-syntax.md\n\n# MQL 语法规范参考\n\n> **重要：`npx @lark-project/meegle@latest workitem query` 的 `mql` 参数必须是完整的 SQL 查询语句**\n> - 必须包含 `SELECT` 和 `FROM` 子句\n> - 不接受 JSON 对象、简写条件或不完整片段\n> - 正确: \\`SELECT \\`工作项ID\\`, \\`名称\\` FROM \\`project_key\\`.\\`需求\\` WHERE \\`状态\\` = \\`进行中\\`\\`\n> - 错误: `{\"status\": \"进行中\"}` / `status = '进行中'` / `WHERE status = '进行中'`\n\n## 基础语法\n\n```sql\nSELECT fieldList -- 指定查询的字段列表\nFROM `空间名`.`工作项类型名` -- 指定数据来源\nWHERE conditionExpression -- 查询条件（可选）\n[ORDER BY fieldOrderByList [{ASC|DESC}]] -- 排序（可选）\n[LIMIT [offset,] row_count] -- 分页（可选）\n```\n\n**标识符规则**：\n- **不支持 `SELECT *`，必须显式指定字段**\n- 所有字段名和表名必须使用反引号包裹，如 `` `工作项ID` ``、`` `空间名`.`需求` ``，**带 target 修饰符时必须包裹整个字段**：`` `name` ``\n- SELECT/FROM/WHERE/ORDER BY 中既可使用 key 也可使用名称。**优先使用 key**，从 `list_workitem_field_config` 返回值中获取：系统字段 key 为单词（如 `priority`、`status`），自定义字段 key 为 `field_x23bd` 格式，工作项类型 key 如 `story`、`issue`。名称是用户自定义的 UGC 内容（语言不定），仅作为找不到 key 时的兜底\n- 字符串用单引号：`'value'`\n- 数组用 JSON 格式：`'[\"a\",\"b\"]'`\n- 枚举值优先用 label（如 `'通过'`），不要用 id\n- **禁止** `count()`、`SUM()`、`GROUP BY`。总数从返回结果的 `count` 字段读取\n\n---\n\n## 数据类型\n\n| MQL 类型 | 说明 | 对应的工作项字段类型 |\n|-----------|------|-------------------|\n| bool | 真假值，取值 TRUE/FALSE/1/0 | bool |\n| bigint | 整数类型 | number 类型下的 work_item_id 和 auto_number |\n| double | 浮点数类型 | 除 work_item_id/auto_number 外的其他 number |\n| varchar | 字符串类型 | text、multi-pure-text、multi-text、select、tree-select、radio、user、link、signal、workitem_related_select |\n| date | 日期类型，格式 `YYYY-MM-DD` 或 `YYYY-MM-DD+TZD`（如 `2025-12-24+08:00`） | date |\n| datetime | 日期时间类型，格式 `YYYY-MM-DDThh:mm:ss` 或 `YYYY-MM-DDThh:mm:ssTZD` | schedule、precise_date |\n| array(varchar) | 字符串数组 | multi-select、tree-multi-select、multi-user、link_cloud_doc、workitem_related_multi_select、multi-file |\n| array(struct) | 结构体数组 | compound_field |\n| lambda expression | 返回 bool 的函数表达式，写法：`x -> x > 10`、`x -> x in ('a', 'b')` | — |\n\n---\n\n## 常用运算符\n\n### BETWEEN ... AND ...\n\n时间区间查询，仅适用于 date 字段类型和 precise_date 字段类型\n\n```sql\nWHERE `创建时间` BETWEEN '2025-01-01' AND '2025-10-01'\n```\n\n### IN\n\n集合查询，适用于 varchar 数据类型\n\n```sql\n-- 查询名称为 \"测试1\" 或 \"测试2\" 或 \"测试3\"\nWHERE `名称` IN ('测试1', '测试2', '测试3')\n```\n\n### LIKE / NOT LIKE\n\n模糊匹配，`%` 匹配任意字符：\n\n```sql\nWHERE `缺陷名` LIKE '%性能问题%'\nWHERE `缺陷名` NOT LIKE '%后端性能问题%'\n```\n\n---\n\n## 常用函数\n\n### 数组函数\n\n| 函数 | 说明 |\n|------|------|\n| `array_cardinality(array_col)` | 获取数组长度 |\n| `array_contains(array_col, element [, element2, ...])` | 数组是否包含某元素（多值表示包含其中之一） |\n| `any_match(array_col, predicate)` | 是否有任一元素满足条件 |\n| `all_match(array_col, predicate)` | 是否所有元素满足条件 |\n| `none_match(array_col, predicate)` | 是否所有元素都不满足条件 |\n| `array_filter(array_col, predicate)` | 根据条件过滤数组，返回新数组 |\n\n**示例**：\n```sql\n-- 当前负责人包含张三\narray_contains(`当前负责人`, '张三')\n\n-- 标签数组与给定数组有交集\narray_intersect(`标签`, '[\"标签A\",\"标签B\"]') \n\n-- 处理人中是否有张三\nany_match(`处理人`, x -> x = '张三')\n\n-- 处理人中是否有至少一个开放平台团队的用户\nany_match(`处理人`, x -> x in (team(true, '开放平台团队')))\n\n-- 优先级包含 P0 或 P1\narray_contains(`优先级`, 'P0', 'P1')\n\n-- 当前负责人包含当前登录用户或李四\nany_match(`当前负责人`, x -> x in (current_login_user(), '李四'))\n\n-- 所有处理人都在后端团队中\nall_match(`处理人`, usr -> usr in team(true, '后端开发团队'))\n\n-- 标签数组为空\narray_cardinality(`标签`) = 0\n```\n\n### 时间函数\n\n支持的函数：`RELATIVE_DATETIME_EQ`、`RELATIVE_DATETIME_GT`、`RELATIVE_DATETIME_GE`、`RELATIVE_DATETIME_LT`、`RELATIVE_DATETIME_LE`、`RELATIVE_DATETIME_BETWEEN`\n\n函数签名：`RELATIVE_DATETIME_*(col_name, 'date_para', ['days'])`\n\n**date_para 枚举值**：\n\n| 枚举 | 含义 | 是否支持 days 参数 |\n|------|------|-------------------|\n| today | 当天 | 支持（正值向后偏移，负值向前偏移） |\n| tomorrow | 明天 | 不支持 |\n| yesterday | 昨天 | 不支持 |\n| current_week | 当周 | 不支持 |\n| next_week | 下周 | 不支持 |\n| last_week | 上周 | 不支持 |\n| current_month | 当月 | 不支持 |\n| next_month | 下月 | 不支持 |\n| last_month | 上月 | 不支持 |\n| future | 从今天起的未来范围 | 支持 |\n| past | 从今天起的过去范围 | 支持 |\n\n**days 参数**：仅 `today`、`future`、`past` 支持。格式为 `'Nd'` 或 `'-Nd'`。\n\n**示例**：\n```sql\n-- 今天创建的工作项\nRELATIVE_DATETIME_EQ(`创建时间`, 'today')\n\n-- 3天内到期的工作项\nRELATIVE_DATETIME_LE(`截止时间`, 'future', '3d')\n\n-- 上周创建的需求\nRELATIVE_DATETIME_BETWEEN(`创建时间`, 'last_week')\n\n-- 本月更新的任务\nRELATIVE_DATETIME_BETWEEN(`更新时间`, 'current_month')\n\n-- 今天后 3 天\nRELATIVE_DATETIME_EQ(`创建时间`, 'today', '3d')\n\n-- 今天前 3 天\nRELATIVE_DATETIME_EQ(`创建时间`, 'today', '-3d')\n\n-- 排期开始时间在过去 30 天内\nRELATIVE_DATETIME_BETWEEN(`__需求排期_开始时间`, 'past', '30d')\n```\n\n### 人员与角色函数\n\n| 函数 | 说明 |\n|------|------|\n| `current_login_user()` | 返回当前登录用户的 userkey |\n| `team(include_manager, '团队名')` | 返回团队成员 userkey 数组（第一个参数 true 表示包含管理者） |\n| `all_participate_persons()` | 返回所有参与当前工作项的人员 userkey 数组 |\n| `participate_roles()` | 返回所有参与角色的 rolekey 数组（如 RD、QA、PM） |\n\n**示例**：\n```sql\n-- 当前负责人是当前登录用户\narray_contains(`当前负责人`, current_login_user())\n\n-- 返回当前工作项的参与人 userkey 数组是否包含张三\narray_contains(participate_persons(), '张三')\n\n-- 返回所有参与当前工作项的人员（全部参与人员/全部人员）userkey 数组是否包含李四\narray_contains(all_participate_persons(), '李四')\n\n-- 指派给产品团队（含管理者）\nany_match(`当前负责人`, x -> x in team(true, '产品团队'))\n\n-- 查询有 RD 和 QA 角色参与的工作项\narray_contains(participate_roles(), 'RD', 'QA')\n```\n\n### 节点函数\n\n- **all_nodes_name()**：返回所有流程节点名称数组\n ```sql\n -- 流程节点包含\"开始\"\n WHERE array_contains(all_nodes_name(), '开始')\n ```\n\n- **in_progress_nodes_name()**：返回当前进行中的节点名称数组\n ```sql\n -- 进行中节点不为空\n WHERE in_progress_nodes_name() is not null\n ```\n\n- **risk_label()**：返回节点延期状态标识数组（如 `[\"延期/开始\",\"今日到期/结束\"]`）\n ```sql\n -- 开始节点已延期且结束节点今日到期\n WHERE risk_label() = '[\"延期/开始\",\"今日到期/结束\"]'\n ```\n\n- **get_node_attribute(node, attribute)**：获取指定节点的属性值。node 可为节点名、`__ALL`（全部节点）、`__BELONGING`（所属节点，即当前工作项所在的节点）。**语义涉及\"所属节点\"时，必须使用 `__BELONGING`**\n\n **可用属性**：排期、估分、节点时间、节点完成结论、节点完成意见、负责人、当前负责人、状态\n\n **排期/节点时间子字段**：\n - 节点排期：`get_node_attribute('节点名','__排期_开始时间')`、`get_node_attribute('节点名','__排期_结束时间')`\n - 节点时间：`get_node_attribute('节点名','__节点时间_开始时间')`、`get_node_attribute('节点名','__节点时间_完成时间')`\n\n ```sql\n -- 开始节点排期在过去 30 天内\n WHERE RELATIVE_DATETIME_BETWEEN(get_node_attribute('开始','__排期_开始时间'), 'past','30d')\n -- 全部节点估分大于 10\n WHERE get_node_attribute('__ALL','估分') > 10\n -- 调研节点负责人等于小李（等于语法也适用于节点属性）\n WHERE get_node_attribute('调研','负责人') = '小李'\n -- 所属节点当前负责人（必须使用 __BELONGING）\n WHERE any_match(get_node_attribute('__BELONGING','当前负责人'), x -> x in ('张三'))\n -- 所属节点状态为进行中\n WHERE any_match(get_node_attribute('__BELONGING','状态'), x -> x in ('进行中'))\n -- 所属节点排期在未来 7 天内\n WHERE RELATIVE_DATETIME_BETWEEN(get_node_attribute('__BELONGING','排期'), 'future','7d')\n ```\n\n### 关系函数\n\n- **relation(relation_name)**：通过关系名称获取关系，关系名称从 `list_workitem_relations` 获取\n ```sql\n WHERE any_relation_match(relation('父-子'), x -> x.`名称` like '%需求%')\n ```\n\n- **parent_work_item(relation(relation_name))**：获取父工作项 ID\n ```sql\n WHERE parent_work_item(relation('父-子')) = '12345'\n ```\n\n- **relation_field_chain(relation1 [, relation2 [, relation3]])**：关联工作项链式查询（最多 3 跳）。一级关系使用 `relation_field_chain('关系1')` 或 `relation_field_chain('字段1')` 即可。**子任务的父工作项必须写作 `'__父工作项'`（双下划线前缀）**\n ```sql\n -- 一级关系\n WHERE any_relation_match(relation_field_chain('关联需求'), x -> x.`优先级` = 'P0')\n -- 多级关系：子任务→父工作项→软件\n WHERE any_relation_match(relation_field_chain('__父工作项','需求关联软件'), x -> x.`名称` = '某软件')\n ```\n\n- **association()**：跨空间关联实例 ID\n ```sql\n WHERE association() = '实例ID'\n ```\n\n- **linked_work_item()**：子任务特有，获取来源控件（父工作项 ID）\n ```sql\n WHERE linked_work_item() = '12345'\n ```\n\n### 关系判断函数\n\n用于对关系对端进行条件判断：\n\n- **any_relation_match(relation, x -> expr)**：存在一个/一组对端满足条件\n- **all_relation_match(relation, x -> expr)**：每一个对端都满足条件\n- **none_relation_match(relation, x -> expr)**：每一个对端都不满足条件\n- **not all_relation_match(relation, x -> expr)**：存在一个/一组对端不满足条件\n\n**嵌套筛选规则**：对关系对端的属性进行进一步筛选时，使用关系函数（如 `relation_field_chain`）获取关系后，外层必须嵌套关系判断函数。\n\n```sql\n-- 示例：子任务其父工作项的当前负责人全部不属于小李\nWHERE all_relation_match(relation_field_chain('__父工作项'), x -> none_match(x.`当前负责人`, y -> y in ('小李')))\n\n-- 示例：多级关系 + 节点属性 — 子任务关联的任务所关联的需求的\"开始\"节点负责人包含小李\nWHERE all_relation_match(relation_field_chain('需求-二级工作项关联','二级工作项-子任务关联'), x -> any_match(get_node_attribute('开始','负责人'), y -> y in ('小李')))\n```\n\n**关系参数三种形式**：\n\n1. **关联字段**：`` `字段key` `` — 如 ``any_relation_match(`关联需求`, x -> x.`优先级` = 'P0')``\n2. **relation 函数**：`relation('关系名')` — 如 `any_relation_match(relation('父-子'), x -> x.`名称` like '%需求%')`\n3. **relation_field_chain 函数**：`relation_field_chain('关系1','关系2')` — 用于多级关系链\n\n**多级关系名处理规则**：默认按照用户的输入直接进行查询。如果找不到匹配的关系，可让用户二次输入确认。不主动猜测或转换用户输入的关系名。\n\n**子任务 `__父工作项` 规则**：\n- 子任务的父工作项关系名固定为 `'__父工作项'`（双下划线前缀），不是 `'父工作项'`\n- 常见报错：`object[父工作项-关联XXX]: relation chain err:relationNode not found, label:父工作项`\n- 原因：父工作项写法缺少双下划线前缀\n- **修复：仅将 `'父工作项'` 改为 `'__父工作项'`**，其他部分保持不变\n- 修正示例：`relation_field_chain('__父工作项','关联XXX')`\n\n**跨空间/多端字段引用**：``x.`字段名` `` 或 `` x.`字段名` ``（通用字段）\n\n**关联工作项通用字段**（查询关联工作项信息时，以下属性必须使用 ``）：标题、创建人、创建时间、业务线、优先级、当前负责人、所属工作项、所属空间、工作项ID、工作项类型、状态\n\n```sql\n-- 多选关联字段：对端优先级为 P0（使用 ）\nWHERE any_relation_match(`多选关联字段`, x -> x.`优先级` = 'P0')\n-- 多选关联字段全部满足条件（使用指定空间和类型）\nWHERE all_relation_match(`多选关联字段`, x -> x.`描述` like '%123%')\n-- 关联工作项创建时间（通用字段必须用 ）\nWHERE any_relation_match(relation_field_chain('__父工作项'), x -> x.`创建时间` >= '2026-03-24')\n-- 多级关系结合节点属性（__父工作项要指明 target 才可以串起来关系）\nWHERE all_relation_match(relation_field_chain('__父工作项','关联字段2'), x -> any_match(get_node_attribute('开始','负责人'), y -> y in ('小李')))\n-- 关联工作项的节点属性：XX 关联的实例，其 AA 节点负责人不包含小李\nWHERE any_relation_match(`XX关联`, x -> not array_contains(get_node_attribute('AA', '负责人'), '小李'))\n```\n\n### 状态函数\n\n- **status_time(status_name)**：返回进入指定状态的时间\n ```sql\n -- 状态时间在区间内\n WHERE status_time('开始') between '2025-03-10' and '2025-04-10'\n ```\n\n- **status_time('\\_\\_状态名\\_\\_开始时间') / status_time('\\_\\_状态名\\_\\_结束时间')**：获取状态的开始/结束时间\n ```sql\n -- 状态累计持续时间\n WHERE status_time('__结束状态__结束时间') - status_time('__开始状态__开始时间') > 86400\n ```\n\n---\n\n## 名称消歧（`` 语法）\n\n当人名、团队名等存在重复时，MQL 会因无法唯一标识而报错。此时使用 `` 语法指定唯一 ID：\n\n```sql\n-- 人名消歧：张三对应多人时，指定 userkey\nWHERE `创建人` = '张三'\n\n-- 团队名消歧：指定团队唯一 key\nWHERE any_match(`负责人`, x -> x in (team(true, '开放平台团队')))\n```\n\n遇到 MQL 返回\"名称重复\"类错误时，需获取对应的唯一 ID 后使用此语法重试。\n\n**枚举值和 userkey 也可使用 `` 格式**：\n\n```sql\n-- 枚举值指定 option id\nWHERE x.`priority` = ''\n-- userkey 指定\nWHERE `负责人` = ''\n```\n\n---\n\n## 特殊字段查询规则\n\n### 日期区间类型字段\n\n日期区间类型（如\"需求排期\"）不能直接查询，必须拆分为子字段，格式：`` `__排期名_开始时间` `` / `` `__排期名_结束时间` ``\n\n```sql\n-- 正确：使用子字段\nWHERE `__开发周期_开始时间` > '2025-01-01' AND `__开发周期_结束时间` < '2025-01-31'\nWHERE RELATIVE_DATETIME_BETWEEN(`__需求排期_开始时间`, 'past', '30d')\n\n-- 错误：直接查询日期区间字段\nWHERE RELATIVE_DATETIME_BETWEEN(`需求排期`, 'past', '30d')\n```\n\n### 角色字段\n\n角色可作为 MQL 属性查询，使用 `__角色名` 格式（加 `__` 前缀以区分普通自定义字段）：\n\n```sql\n-- 查询 RD 包含某人的工作项\nWHERE array_contains(`__RD`, '张三')\n\n-- 查询多个角色条件\nWHERE array_contains(`__RD`, '张三') AND array_contains(`__PM`, '李四')\n```\n\n---\n\n## 关键词映射\n\n> 当用户输入中包含以下关键词时，优先匹配对应的函数或语法。\n\n### 控件关键词 → 函数映射\n\n**当用户输入中包含「控件」二字时，务必对照下表选择正确函数。**\n\n| 用户关键词 | 使用函数/语法 | 说明 |\n|-----------|-------------|------|\n| 参与人员、全部参与人员、全部人员 | `all_participate_persons()` | 当前工作项的全部参与人 |\n| 参与人员、当前参与人 | `participate_persons()` | 当前工作项的参与人 |\n| 流程节点、所有节点 | `all_nodes_name()` | 获取所有节点名称 |\n| 进行中节点 | `in_progress_nodes_name()` | 获取当前进行中的节点 |\n| 节点排期、节点时间、节点估分、所属节点信息 | `get_node_attribute('节点名\\|__ALL\\|__BELONGING','属性名')` | 获取节点具体属性，所属节点用 `__BELONGING` |\n| 节点延期标识 | `risk_label()` | 获取节点延期状态标识 |\n| 关联工作项信息 | `relation_field_chain('关联字段1','关联字段2','关联字段3')` | 关联工作项链式查询（最多 3 跳） |\n| 子任务父工作项 | `relation_field_chain('__父工作项')` | 子任务特有：获取父工作项 |\n| 关系 | `relation('关系名')` | 通过关系名称获取 |\n| 来源 | `linked_work_item()` | **子任务特有**，获取来源控件 |\n| 父工作项 | `parent_work_item(relation('关系名'))` | 获取父工作项 |\n| 状态时间窗口 | `status_time('状态名') between 'a' and 'b'` | 状态时间在区间内 |\n| 状态累计进行时间 | `status_time('__结束状态__结束时间') - status_time('__开始状态__开始时间')` | 计算状态累计持续时间 |\n\n### 操作符关键词 → 语法映射\n\n| 用户关键词 | MQL 语法 | 示例 |\n|-----------|---------|------|\n| 存在选项属于 | `any_match(field, x -> x in ('a','b'))` | 多选字段中存在任一选项 |\n| 全部选项均不属于 | `none_match(field, x -> x in ('a','b'))` | 多选字段中不存在任何选项 |\n| 包含 | `array_contains(field, 'a','b')` | 数组包含指定值 |\n| 不包含 | `not array_contains(field, 'a','b')` | 数组不包含指定值 |\n| 等于 | `field = 'value'` | 等于指定值 |\n| 不等于 | `field != 'value'` | 不等于指定值 |\n| 为空 | `field is null` | 字段为空 |\n| 不为空 | `field is not null` | 字段不为空 |\n| 在区间 | `field between 'a' and 'b'` | 字段在区间内（日期/数字） |\n\n### 关系语境关键词 → 函数映射\n\n| 用户关键词 | 使用函数 | 说明 |\n|-----------|---------|------|\n| 每一个 | `all_relation_match(关系, x -> expr)` | 所有关系对端都满足条件 |\n| 存在一个、存在一组 | `any_relation_match(关系, x -> expr)` | 任意关系对端满足条件 |\n| 每一个不满足 | `none_relation_match(关系, x -> expr)` | 所有关系对端都不满足条件 |\n| 存在一个不满足、存在一组不满足 | `not all_relation_match(关系, x -> expr)` | 并非所有都满足（即至少有一个不满足） |\n\n---\n\n## 完整查询示例\n\n> 以下示例展示语法模式。`<尖括号>` 为占位符，实际值需从对应工具获取：字段 key 从 `list_workitem_field_config`，工作项类型从 `list_workitem_types`，状态/优先级等选项值从字段配置的 options 中读取。\n\n### 示例 1：数组包含 + 当前用户\n\n```sql\nSELECT <所需字段列表>\nFROM `空间名`.`<工作项类型>`\nWHERE array_contains(`<数组字段>`, '<匹配值>')\n AND array_contains(all_participate_persons(), current_login_user())\n```\n\n### 示例 2：相对时间查询\n\n```sql\nSELECT <所需字段列表>\nFROM `空间名`.`<工作项类型>`\nWHERE RELATIVE_DATETIME_BETWEEN(`<日期字段>`, 'past', '<天数>d')\n```\n\n### 示例 3：逾期未完成（排期子字段 + 状态过滤）\n\n```sql\n-- 排期子字段格式：`__<排期名>_开始时间` / `__<排期名>_结束时间`，具体名称从 list_workitem_field_config 确认\nSELECT <所需字段列表>\nFROM `空间名`.`<工作项类型>`\nWHERE RELATIVE_DATETIME_LT(`__<排期名>_结束时间`, 'today')\n AND `status` != '<已完成状态值>'\n```\n\n### 示例 4：团队角色匹配\n\n```sql\nSELECT <所需字段列表>\nFROM `空间名`.`<工作项类型>`\nWHERE any_match(`__<角色名>`, x -> x in (team(true, '<团队名>')))\n```\n\n### 示例 5：等值条件 + 排序分页\n\n```sql\nSELECT <所需字段列表>\nFROM `空间名`.`<工作项类型>`\nWHERE `<字段>` = current_login_user()\n AND `<字段>` = '<条件值>'\nORDER BY `<排序字段>` DESC\nLIMIT <按需设置>\n```\n\n### 示例 6：模糊匹配 + 多条件组合\n\n```sql\nSELECT <所需字段列表>\nFROM `空间名`.`<工作项类型>`\nWHERE `name` LIKE '%<关键词>%'\n AND array_contains(`<数组字段>`, '<匹配值>')\n AND `<字段>` = current_login_user()\nORDER BY `<排序字段>` ASC\nLIMIT <按需设置>\n```\n\n### 示例 8：节点属性查询（所属节点 + 延期标识）\n\n```sql\n-- 所属节点当前负责人是张三且进行中\nSELECT `工作项ID`, `名称`, `状态`\nFROM `project_key`.`需求`\nWHERE any_match(get_node_attribute('__BELONGING','当前负责人'), x -> x in ('张三'))\n AND any_match(get_node_attribute('__BELONGING','状态'), x -> x in ('进行中'))\n\n-- 开始节点已延期\nSELECT `工作项ID`, `名称`\nFROM `project_key`.`需求`\nWHERE risk_label() = '[\"延期/开始\"]'\n```\n\n### 示例 9：关系查询（关系链 + 跨空间字段）\n\n```sql\n-- 子任务的父工作项名称包含\"登录\"\nSELECT `工作项ID`, `名称`\nFROM `project_key`.`子任务`\nWHERE any_relation_match(relation_field_chain('__父工作项'), x -> x.`标题` like '%登录%')\n\n-- 多级关系：子任务→父工作项→关联软件，软件名称等于某值\nSELECT `工作项ID`, `名称`\nFROM `project_key`.`子任务`\nWHERE any_relation_match(relation_field_chain('__父工作项','需求关联软件'), x -> x.`名称` = '某软件')\n```\n\n### 示例 10：状态时间查询\n\n```sql\n-- \"开始\"状态时间在 2025-03-10 至 2025-04-10 之间\nSELECT `工作项ID`, `名称`, `状态`\nFROM `project_key`.`需求`\nWHERE status_time('开始') between '2025-03-10' and '2025-04-10'\n```\n\n### 示例 11：节点负责人 + 人员综合查询\n\n```sql\n-- 开始节点负责人包含某人\nSELECT `工作项ID`, `名称`\nFROM `project_key`.`需求`\nWHERE array_contains(get_node_attribute('开始','负责人'), '李应凡')\n\n-- 处理人属于某团队\nSELECT `工作项ID`, `名称`, `处理人`\nFROM `project_key`.`缺陷`\nWHERE any_match(`处理人`, x -> x in (team(true, '开放平台团队')))\n```\n\nFile v0.1.5:references/performance.md\n\n# 性能与并发调用指南\n\n本文件收录减少延迟的工程性规则。核心协议（字段格式、错误自愈）仍在 SKILL.md 主文件中。\n\n## 并行调用\n\n无依赖的命令调用应并行发起，有依赖则必须串行。\n\n**必须串行**（前者输出是后者输入）：\n- `npx @lark-project/meegle@latest project search` → `npx @lark-project/meegle@latest workitem meta-fields` → `npx @lark-project/meegle@latest workitem query`\n- `npx @lark-project/meegle@latest workitem get` → `npx @lark-project/meegle@latest workflow transition` / `npx @lark-project/meegle@latest workitem update`\n- `npx @lark-project/meegle@latest workitem meta-fields` → `npx @lark-project/meegle@latest workitem create`\n\n**可并行**：\n- `npx @lark-project/meegle@latest workitem meta-fields` 和 `npx @lark-project/meegle@latest workitem meta-roles`（同类型）\n- 多种工作项类型的 `npx @lark-project/meegle@latest workitem meta-fields`（如 story + issue）\n- 各条件的 count 查询、多人排期分批查询\n\n## 大结果处理\n\n- **分批查询**：`npx @lark-project/meegle@latest workhour list-schedule` 多人时拆成每批 ≤ 20 人并行\n- **精简 SELECT**：只选必要字段，避免富文本等大体积字段\n- **按需翻页**：先读首页获取总数，按需翻页\n\nFile v0.1.5:references/rich-text-editor-markdown-syntax.md\n\n# 富文本编辑器 Markdown 格式规范\n\n## 概述\n\n富文本编辑器使用基于 **GFM（GitHub Flavored Markdown）** 的扩展 Markdown 格式。对于标准 Markdown 无法表达的功能，通过 HTML 注释和标签进行扩展。该格式可转换为 DSL、Delta 和 doc_html。\n\n**核心原则：** 标准 GFM + HTML 注释承载元数据 + ``/`` 标签补充样式能力。\n\n## 速查表\n\n| 功能 | 语法 | 说明 |\n|------|------|------|\n| 加粗 | `**文本**` | |\n| 斜体 | `*文本*` | |\n| 删除线 | `~~文本~~` | |\n| 下划线 | `文本` | HTML 标签，非标准 MD |\n| 行内代码 | `` `代码` `` | |\n| 字体颜色 | `文本` | 必须使用 `rgb()` 格式 |\n| 背景颜色 | `文本` | 必须使用 `rgb()` 格式 |\n| 字体大小 | `文本` | 值为 px 单位 |\n| 标题 | `#` 到 `######` | h1-h6 |\n| 有序列表 | `1. 项目` | 嵌套用 4 空格缩进 |\n| 无序列表 | `- 项目` | 嵌套用 4 空格缩进 |\n| 任务列表 | `- [ ] 待办` / `- [x] 已完成` | |\n| 引用块 | `> 文本` | 内部支持嵌套块级元素 |\n| 代码块 | ` ```语言 ... ``` ` | 开头栅栏后跟语言标识 |\n| 链接 | `[文本](url)` | |\n| 图片 | `![描述](url)` | 注释前无空格 |\n| 链接预览 | `[文本](url)` | 注释前无空格 |\n| 分割线 | `---` | |\n| 表情 | `:ShortCode:` | 大小写敏感的规范键名 |\n| 居中对齐 | `` ... `` | 区域式 |\n| 右对齐 | `` ... `` | 区域式 |\n| 两端对齐 | `` ... `` | 区域式 |\n| @提及 | `@名字` | 注释前无空格 |\n\n## 扩展语法详解\n\n### 对齐方式（区域式）\n\n用 start/end 注释对包裹一个或多个段落，标签必须独占一行：\n\n```markdown\n\n这段文字居中显示。\n\n这段也是居中的。\n\n\n\n右对齐内容。\n\n```\n\n支持的值：`center`（居中）、`right`（右对齐）、`justify`（两端对齐）。左对齐为默认值，无需标记。\n\n### @提及（带元数据）\n\n为了在转换过程中保留用户身份信息，使用元数据格式。`@名字` 和注释之间**不能有空格**：\n\n```markdown\n@张三\n```\n\n注释中必填的 JSON 字段：\n\n| 字段 | 说明 | 示例 |\n|------|------|------|\n| `id` | 用户 ID | `\"lark_user_id_7361251974161006596\"` |\n| `cn_name` | 中文名 | `\"张三\"` |\n| `en_name` | 英文名 | `\"Zhang San\"` |\n| `email` | 邮箱地址 | `\"zhangsan@example.com\"` |\n| `blockType` | 固定值 | `\"AT_USER_BLOCK\"` |\n\n可选字段：`blockId`（UUID v4）、`type`（0 = 用户）、`avatar_url`。\n\n同一行多个提及（之间不加空格）：\n\n```markdown\n@张三@李四\n```\n\n如果没有元数据，纯 `@名字` 也可接受，但无法在格式转换中完整还原。\n\n### 图片\n在url后紧跟``（**无空格**）：\n\n图片uuid 是与图片平台约定的唯一凭证。\n\n```markdown\n`![描述](https://example.com/page/***)`\n```\n\n### 链接预览\n\n在链接后紧跟 ``（**无空格**）：\n\n```markdown\n[https://example.com/page](https://example.com/page)\n```\n\n### 下划线\n\n标准 Markdown 不支持下划线，使用 HTML `` 标签：\n\n```markdown\n带下划线的文本\n```\n\n可与其他格式嵌套：\n\n```markdown\n*斜体加下划线*\n**加粗加下划线**\n```\n\n### Span 样式\n\n字体颜色、背景颜色、字体大小使用 `` 的 `style` 属性。**颜色必须用 `rgb(R, G, B)` 格式**（不支持 hex 和颜色名）：\n\n```markdown\n红色文字\n绿色背景\n大号文字\n```\n\n### 表情短代码\n\n使用 `:CODE:` 格式。键名大小写敏感，解析时会归一化到 lark 规范形式：\n\n```\n:OK: :DarkThumbsup: :THANKS: :DarkFightOn: :DarkFingerHeart: :APPLAUSE: :LightFistBump: :JIAYI: :DONE: :SMILE: :Delighted: :BeamingFace: :BLUSH: :LAUGH: :SMIRK: :LOL: :FACEPALM: :LOVE: :ERROR: :CRY: :SOB: :THINKING: :SCOWL: :SMART: :WITTY: :PROUD: :WINK: :NOSEPICK: :HAUGHTY: :SLAP: :SPITBLOOD: :TOASTED: :ColdSweat: :BLACKFACE: :FullMoonFace: :GLANCE: :DULL: :ROSE: :HEART: :PARTY: :INNOCENTSMILE: :SHY: :CHUCKLE: :JOYFUL: :WOW: :OBSESSED: :DROOL: :SMOOCH: :KISS: :EMBARRASSED: :TEARS: :ENOUGH: :YEAH: :TRICK: :MONEY: :TEASE: :SHOWOFF: :COMFORT: :CLAP: :PRAISE: :STRIVE: :XBLUSH: :SILENT: :HUG: :WHIMPER: :CRAZY: :WAIL: :LOOKDOWN: :DIZZY: :FROWN: :WHAT: :WAVE: :BLUBBER: :WRONGED: :HUSKY: :SHHH: :SMUG: :ANGRY: :HAMMER: :SHOCKED: :TERROR: :PUKE: :SICK: :YAWN: :DROWSY: :SLEEP: :SPEECHLESS: :SWEAT: :SKULL: :PETRIFIED: :BETRAYED: :HEADSET: :EatingFood: :Typing: :Lemon: :Get: :LGTM: :OnIt: :OneSecond: :YouAreTheBest: :Shrug: :ThanksFace: :SaluteFace: :GoGoGo: :Partying: :VRHeadset: :MeMeMe: :Sigh: :DarkSalute: :DarkShake: :LightHighFive: :DarkWavingHand: :DarkClick: :DarkThumbsDown: :ClownFace: :SLIGHT: :TONGUE: :LIPS: :SiSiASYouWish: :HappyDragon: :JubilantRabbit: :RoarForYou: :CALF: :BULL: :BEAR: :EYESCLOSED: :BEER: :CAKE: :GIFT: :CUCUMBER: :Drumstick: :Pepper: :CANDIEDHAWS: :BubbleTea: :Coffee: :Pin: :AWESOMEN: :Hundred: :MinusOne: :CrossMark: :CheckMark: :OKR: :No: :Yes: :Alarm: :Loudspeaker: :Trophy: :Fire: :RAINBOWPUKE: :Music: :TV: :Movie: :Pumpkin: :LUCK: :FORTUNE: :REDPACKET: :BeAtTheForefront: :2026: :FIREWORKS: :XmasHat: :Snowman: :XmasTree: :FIRECRACKER: :StickyRiceBalls: :Mooncake: :MoonRabbit: :HEARTBROKEN: :BOMB: :POOP: :18X: :CLEAVER: :GeneralWorkFromHome: :GeneralBusinessTrip: :StatusFlashOfInspiration: :StatusReading: :GeneralInMeetingBusy: :Status_PrivateMessage: :GeneralDoNotDisturb: :Basketball: :Soccer: :StatusEnjoyLife: :GeneralTravellingCar: :StatusBus: :StatusInFlight: :GeneralSun: :GeneralMoonRest: \n```\n\n解析器会归一化大小写（`:smile:` → `:SMILE:`，`:beamingface:` → `:BeamingFace:`），但建议直接使用规范写法。\n\n### 列表 — 4 空格缩进\n\n嵌套列表使用 **4 个空格**（不是 2 个）缩进：\n\n```markdown\n1. 第一级有序\n 1. 第二级（4 空格）\n 1. 第三级（8 空格）\n - 混合：有序中嵌套无序（4 空格）\n- 第一级无序\n - 第二级\n - 第三级\n 1. 混合：无序中嵌套有序\n```\n\n任务列表：\n\n```markdown\n- [ ] 未完成任务\n- [x] 已完成任务\n - [ ] 嵌套未完成\n - [x] 嵌套已完成\n```\n\n### 引用块\n\n支持嵌套和内部块级内容：\n\n```markdown\n> 带 **加粗** 和 *斜体* 的引用\n> 1. 引用内有序列表\n> 2. 第二项\n> 1. 引用内嵌套列表\n> - 引用内无序列表\n```\n\n### 代码块\n\n使用围栏式代码块，开头标注语言：\n\n````markdown\n```TypeScript\nfunction add(a: number, b: number): number {\n return a + b;\n}\n```\n\n```Go\nfunc add(a, b int) int {\n return a + b\n}\n```\n````\n\n### GFM 表格（简单内容）\n\n表格内仅包含行内内容（文本、加粗、链接等）时使用：\n\n```markdown\n| 表头1 | 表头2 | 表头3 |\n|-------|-------|-------|\n| 单元格1 | **加粗** | [链接](url) |\n| 单元格3 | 单元格4 | 单元格5 |\n```\n\n### HTML 表格（单元格内含富内容）\n\n当表格单元格需要块级元素（标题、列表、代码块、对齐、图片）时，使用 HTML `` 语法。**`` 前必须留空行**，这样内部的 Markdown 才能被正确解析：\n\n```markdown\n
` 后和 `
\n\n\n\n\n\n\n\n\n\n\n
\n\n# 单元格内标题\n\n**加粗段落**\n\n\n\n1. 有序列表\n2. 在单元格中\n - 嵌套项\n\n\n\n\n单元格内居中\n\n\n
\n\n```TypeScript\n// 单元格内代码块\nconst x = 1;\n```\n\n\n\n> 单元格内引用块\n\n\n\n单元格内彩色文字\n\n
\n```\n\n空单元格：``\n\n## 格式组合\n\n行内样式可以嵌套使用：\n\n```markdown\n**~~加粗删除线~~**\n*斜体下划线*\n[**加粗链接**](https://example.com)\n**红色加粗**\n```\n\n## 段落分隔\n\n每个块级元素（段落、标题、列表组、表格、代码块、引用块）之间用空行分隔：\n\n```markdown\n# 标题\n\n第一段正文。\n\n第二段正文。\n\n- 列表项 1\n- 列表项 2\n\n列表后面的段落。\n```\n\n## 常见错误\n\n| 错误写法 | 正确写法 |\n|----------|----------|\n| `加粗` | `**加粗**` |\n| `斜体` | `*斜体*` |\n| `删除` 或 `删除` | `~~删除~~` |\n| `` | `` |\n| `` | `` |\n| `文本` | `\\n文本\\n` |\n| `@名字 `（有空格） | `@名字`（无空格） |\n| `[链接](url) `（有空格） | `[链接](url)`（无空格） |\n| 2 空格嵌套列表缩进 | 4 空格嵌套列表缩进 |\n| `:smile:`（全小写） | `:SMILE:`（使用规范大小写） |\n| `![图片](url) `（有空格） | `![图片](url)`（无空格） |\n| `![图片](url)` | `` 仅用于 `[文本](url)` 链接 |\n| `文本`（`` 后无空行） | `\\n\\n文本\\n\\n`（需要空行） |\n\n## 完整示例\n\n```markdown\n# 项目进展\n\n## 状态\n\n\n**Alpha 项目 — 迭代评审**\n\n\n本迭代完成了以下工作：\n\n1. 用户认证\n 1. 登录流程\n 2. 密码重置\n2. 仪表盘改版\n - 新布局\n - 性能优化\n\n### 关键指标\n\n| 指标 | 改版前 | 改版后 |\n|------|--------|--------|\n| 加载耗时 | 3.2s | **1.1s** |\n| 错误率 | 2.4% | 0.3% |\n\n### 代码变更\n\n```TypeScript\nexport function authenticate(token: string): boolean {\n return validateJWT(token);\n}\n```\n\n> 注意：部署前需要更新 环境配置。\n\n- [x] 代码评审已完成\n- [x] 测试通过\n- [ ] 部署到预发环境\n\n负责人：@张三@李四\n\n参考文档：[迭代看板](https://example.com/sprint/42)\n\n:DONE: :DarkThumbsup:\n```\n\nArchive v0.1.4: 3 files, 8418 bytes\n\nFiles: references/mql-syntax.md (9343b), SKILL.md (9772b), _meta.json (138b)\n\nFile v0.1.4:SKILL.md\n\n---\nname: lark-project-meegle\ndescription: 连接飞书项目/Meegle，查询和管理工作项、待办等。自动检测登录状态，未登录时引导 Device Code 授权。\nversion: 0.1.1\nhomepage: https://www.npmjs.com/package/@lark-project/meegle\nmetadata:\n openclaw:\n homepage: https://www.npmjs.com/package/@lark-project/meegle\n emoji: 📋\n requires:\n bins:\n - node\n - npx\n install:\n - kind: node\n package: \"@lark-project/meegle\"\n bins:\n - meegle\n---\n\n# Meegle SKILL\n\n通过 Meegle CLI 连接飞书项目/Meegle 平台，支持查询工作项、管理待办等操作。\n\n## 前置条件\n\n运行环境需要 Node.js 18+。所有命令通过 `npx @lark-project/meegle@latest` 执行，无需手动安装或更新。\n\n## 触发条件\n\n- **主动登录**：用户说\"登录 Meegle\"、\"连接飞书项目\"、\"login meegle\"等。\n- **被动拦截**：用户请求任何 Meegle 业务操作（查询待办、查工作项、创建任务等），优先执行 Auth Guard。\n- **URL 触发**：用户发送了一个看起来像飞书项目/Meegle 工作项的 URL（路径中通常包含 `workitem`、`detail`、`story`、`issue` 等关键词）。处理流程：\n 1. 从 URL 提取 `$host`（域名部分）和可能的 `$project_key`、`$work_item_id`\n 2. 执行 Auth Guard（STEP 1 中若 `$host` 为 null，用 URL 提取的 host 覆盖，跳过 STEP 2）\n 3. 登录成功后：\n - 如果解析出了 `$project_key` 和 `$work_item_id` → 直接执行 `workitem get` 查询详情\n - 如果无法解析 → 告知用户已登录成功，请描述需要查询的内容\n\n## Auth Guard（所有业务命令前必须执行）\n\n按以下 STEP 顺序执行。每个 STEP 结尾的 GOTO 指明下一步，严格遵循跳转。\n---\n\n### STEP 1 — 检查登录状态\n\n```bash\nnpx @lark-project/meegle@latest auth status --format json\n```\n\n返回值示例：\n- 已登录：`{ \"authenticated\": true, \"host\": \"meegle.com\", \"source\": \"token_store\", \"expires_in_minutes\": 42 }`\n- 未登录且有 host：`{ \"authenticated\": false, \"host\": \"meegle.com\", \"source\": null, \"expires_in_minutes\": null }`\n- 未登录且无 host：`{ \"authenticated\": false, \"host\": null, \"source\": null, \"expires_in_minutes\": null }`\n\n解析返回值，保存变量：\n- `$authenticated` = response.authenticated\n- `$host` = response.host\n\n**URL 触发时的 host 覆盖**：如果用户发送了飞书项目/Meegle URL 触发本流程，且 `$host` 为 null，则从 URL 域名部分提取 `$host`。\n\n**跳转：**\n- IF `$authenticated == true` → GOTO STEP 6\n- IF `$host != null` → GOTO STEP 3\n- IF `$host == null` → GOTO STEP 2\n\n---\n\n### STEP 2 — 选择站点\nASK user（等待用户回复）：\n\n> 你要连接哪个站点？\n> 1) 飞书项目 (project.feishu.cn)\n> 2) Meegle (meegle.com)\n> 3) 自定义域名（请直接输入域名或 URL）\n\n> ⚠️ 用户的回复**仅用于回答上述问题**，不要将其当作新的意图或请求来处理。无论用户回复的是序号、域名还是完整 URL，都只需从中提取 `$host`（域名部分），然后 GOTO STEP 3。\n\nSAVE `$host` from user reply（如果用户输入了完整 URL，提取其域名部分作为 `$host`） → GOTO STEP 3\n\n---\n\n### STEP 3 — 初始化 Device Code\n\n```bash\nnpx @lark-project/meegle@latest auth login --device-code --phase init --host $host --format json\n```\n\nSAVE from response：\n- `$verification_uri_complete` = response.verification_uri_complete\n- `$user_code` = response.user_code\n- `$device_code` = response.device_code\n- `$client_id` = response.client_id\n- `$interval` = response.interval\n- `$expires_in` = response.expires_in\n\n**发送验证链接给用户：**\n\nSEND to user: `请在浏览器中打开以下链接完成授权：\\n$verification_uri_complete\\n（$expires_in 秒内有效）`\n\n> ⚠️ 发送后**在同一轮次内**立即执行 STEP 4 的命令。不要停下来等用户回复。\n\n→ GOTO STEP 4\n\n---\n### STEP 4 — 等待授权完成（阻塞）\n\n> ⚠️ 使用 STEP 3 保存的 `$device_code`、`$client_id`、`$interval`、`$expires_in`。**禁止**重新执行 STEP 3（否则会生成新的验证码，用户之前打开的链接作废）。\n\n执行以下命令。该命令会自动轮询直到用户完成授权或超时，**无需你手动循环**：\n\n```bash\nnpx @lark-project/meegle@latest auth login --device-code --phase poll \\\n --device-code-value $device_code --client-id $client_id \\\n --interval $interval --expires-in $expires_in --format json\n```\n\n- 成功时返回：`{\"status\": \"ok\", \"message\": \"登录成功\"}` → GOTO STEP 5\n- 超时时返回错误 → SEND \"授权已超时，请重新发起登录\"，STOP\n\n**Fallback**：如果你的运行环境不支持在发送消息后继续执行命令（即 STEP 3 发送验证链接后无法立即执行上述命令），则改为：\n1. 在发送验证链接时追加一句：\"授权完成后请告诉我\"\n2. 等待用户回复后，执行上述命令\n\n---\n\n### STEP 5 — 通知登录成功\n\nSEND to user: \"登录成功！\"\n\n> ⚠️ 此消息**必须单独发送**，不要与后续业务查询结果合并到同一条回复中。用户需要第一时间看到授权状态变化。\n\n→ GOTO STEP 6\n\n---\n\n### STEP 6 — 执行业务命令\n\nAuth 已通过，进入下方「业务命令调用」部分执行用户请求的操作。\n\n## 获取当前用户信息\n\n当用户说\"我的 xxx\"、\"查一下我的 xxx\"时，需要知道当前登录用户的身份。\n\n**MQL 查询中**：直接使用 `current_login_user()` 函数，无需提前获取用户信息。例如：\n```sql\nWHERE array_contains(`current_owners`, current_login_user())\n```\n\n**非 MQL 场景**（需要用户名、userkey 等具体信息）：目前没有专用命令，通过以下 workaround 获取：\n\n1. 先用 MQL 查询当前用户最近创建的一个工作项：\n```bash\nnpx @lark-project/meegle@latest workitem query --project-key \\\n --search-mql \"SELECT \\`work_item_id\\`, \\`created_by\\` FROM \\`<空间名>\\`.\\`<工作项类型>\\` WHERE \\`created_by\\` = current_login_user() LIMIT 1\" \\\n --format json\n```\n2. 从返回结果的 `created_by` 字段提取当前用户信息\n\n> ⚠️ 此 workaround 需要已知一个 `project_key` 和对应的工作项类型。如果用户未指定空间，先询问。\n\n## 业务命令调用\n\nAuth Guard 通过后，使用以下模式调用业务命令。\n\n### 命令结构\n\n```bash\nnpx @lark-project/meegle@latest [flags] --format json\n```\n\n命令采用 `resource method` 两级结构。所有输出默认 JSON 格式。\n\n### 全局 Flag\n\n| Flag | 说明 |\n|------|------|\n| `--format json\\|table\\|ndjson` | 输出格式，默认 json |\n| `--select ` | 选取输出属性，逗号分隔（支持 dot path，如 `name,owner.name`） |\n| `--profile ` | 临时切换 profile |\n| `--verbose` | 显示详细日志 |\n\n### 参数传递\n\n三种方式，优先级从高到低：\n\n1. **Flag 模式**（推荐）：`--project-key PROJ --work-item-type-key story`\n2. **--set 模式**（设置工作项字段）：`--set priority=1 --set name=\"任务标题\"`，value 支持 JSON\n3. **--params 模式**（完整 JSON）：`--params '{\"project_key\":\"PROJ\",\"work_item_type_key\":\"story\"}'`\n\nFlag 和 --set 会覆盖 --params 中的同名字段。\n\n### 命令发现\n\nCLI 的命令和参数会随版本更新。下方速查表仅列举常见操作，**不是完整列表**。遇到以下情况时，必须先用 `inspect` 获取最新信息：\n\n- 用户请求的操作不在速查表中\n- 不确定某个命令的参数名称或是否为必填\n- 需要查看某个命令支持的全部参数\n\n```bash\nnpx @lark-project/meegle@latest inspect # 列出所有可用命令\nnpx @lark-project/meegle@latest inspect workitem.create # 查看具体命令的参数 schema\n```\n\n### 常用命令速查\n\n#### 查询待办\n\n```bash\nnpx @lark-project/meegle@latest mywork todo --format json\n```\n\n#### 查询工作项\n\n```bash\nnpx @lark-project/meegle@latest workitem get --project-key --work-item-id --format json\n```\n\n#### 搜索工作项（MQL）\n\n> MQL 语法详见 `references/mql-syntax.md`。`--search-mql` 参数必须是完整的 SQL 语句（含 SELECT/FROM），不接受 JSON 或片段。\n\n```bash\nnpx @lark-project/meegle@latest workitem query --project-key --search-mql \"\" --format json\n```\n\n#### 创建工作项\n\n```bash\nnpx @lark-project/meegle@latest workitem create --project-key --work-item-type-key \\\n --set name=\"标题\" --set priority=1 --format json\n```\n\n#### 更新工作项字段\n\n```bash\nnpx @lark-project/meegle@latest workitem update --project-key --work-item-id \\\n --set name=\"新标题\" --format json\n```\n\n#### 查询项目信息\n\n```bash\nnpx @lark-project/meegle@latest project get --project-key --format json\n```\n\n#### 查询工作项类型和字段元数据\n\n```bash\nnpx @lark-project/meegle@latest workitem meta-types --project-key --format json\nnpx @lark-project/meegle@latest workitem meta-fields --project-key --work-item-type-key --format json\n```\n\n### 输出处理\n\n- 始终使用 `--format json` 获取结构化输出，方便解析\n- 使用 `--select` 精简返回字段，如 `--select id,name,current_nodes.name`\n- 命令返回错误时，JSON 中包含 `error` 和 `message` 字段\n\n## 错误处理\n\n- 如果 bash 返回 `command not found` 或 npx 不可用，提示用户安装 Node.js 18+。\n- 如果 `--phase init` 返回错误（站点不支持 Device Code），提示用户在终端中执行 `npx @lark-project/meegle@latest auth login`。\n- 如果 `--phase poll` 超时，提示用户重试登录流程。\n\nFile v0.1.4:_meta.json\n\n{\n \"ownerId\": \"kn78dhc955jdhgxvfjp6fd9aeh83p3t5\",\n \"slug\": \"lark-project-meegle\",\n \"version\": \"0.1.4\",\n \"publishedAt\": 1775024575328\n}\n\nFile v0.1.4:references/mql-syntax.md\n\n# MQL 语法规范参考\n\n> **重要：`workitem query` 的 `--search-mql` 参数必须是完整的 SQL 查询语句**\n> - 必须包含 `SELECT` 和 `FROM` 子句\n> - 不接受 JSON 对象、简写条件或不完整片段\n> - 正确: `` SELECT `工作项ID`, `名称` FROM `空间名`.`需求` WHERE `状态` = '进行中' ``\n> - 错误: `{\"status\": \"进行中\"}` / `status = '进行中'` / `WHERE status = '进行中'`\n\n## 基础语法\n\n```sql\nSELECT fieldList -- 指定查询的字段列表\nFROM `空间名`.`工作项类型名` -- 指定数据来源\nWHERE conditionExpression -- 查询条件（可选）\n[ORDER BY fieldOrderByList [{ASC|DESC}]] -- 排序（可选）\n[LIMIT [offset,] row_count] -- 分页（可选）\n```\n\n**标识符规则**：\n- 所有字段名和表名必须使用反引号包裹，如 `` `工作项ID` ``、`` `空间名`.`需求` ``\n- SELECT/FROM/WHERE/ORDER BY 中既可使用 key 也可使用名称。**优先使用 key**，从 `workitem meta-fields` 返回值中获取：系统字段 key 为单词（如 `priority`、`status`），自定义字段 key 为 `field_x23bd` 格式，工作项类型 key 如 `story`、`issue`。名称是用户自定义的 UGC 内容（语言不定），仅作为找不到 key 时的兜底\n- **禁止** `count()`、`SUM()`、`GROUP BY`。总数从返回结果的 `count` 字段读取\n\n---\n\n## 数据类型\n\n| MQL 类型 | 说明 | 对应的工作项字段类型 |\n|-----------|------|-------------------|\n| bool | 真假值，取值 TRUE/FALSE/1/0 | bool |\n| bigint | 整数类型 | number 类型下的 work_item_id 和 auto_number |\n| double | 浮点数类型 | 除 work_item_id/auto_number 外的其他 number |\n| varchar | 字符串类型 | text、multi-pure-text、multi-text、select、tree-select、radio、user、link、signal、workitem_related_select |\n| date | 日期类型，格式 `YYYY-MM-DD` 或 `YYYY-MM-DD+TZD`（如 `2025-12-24+08:00`） | date |\n| datetime | 日期时间类型，格式 `YYYY-MM-DDThh:mm:ss` 或 `YYYY-MM-DDThh:mm:ssTZD` | schedule、precise_date |\n| array(varchar) | 字符串数组 | multi-select、tree-multi-select、multi-user、link_cloud_doc、workitem_related_multi_select、multi-file |\n| array(struct) | 结构体数组 | compound_field |\n| lambda expression | 返回 bool 的函数表达式，写法：`x -> x > 10`、`x -> x in ('a', 'b')` | — |\n\n---\n\n## 常用运算符\n\n### BETWEEN ... AND ...\n\n标准 SQL 区间查询，适用于日期和数值字段：\n\n```sql\nWHERE `创建时间` BETWEEN '2025-01-01' AND '2025-10-01'\n```\n\n### LIKE / NOT LIKE\n\n模糊匹配，`%` 匹配任意字符：\n\n```sql\nWHERE `缺陷名` LIKE '%性能问题%'\nWHERE `缺陷名` NOT LIKE '%后端性能问题%'\n```\n\n---\n\n## 常用函数\n\n### 数组函数\n\n| 函数 | 说明 |\n|------|------|\n| `array_cardinality(array_col)` | 获取数组长度 |\n| `array_contains(array_col, element [, element2, ...])` | 数组是否包含某元素（多值表示包含其中之一） |\n| `any_match(array_col, predicate)` | 是否有任一元素满足条件 |\n| `all_match(array_col, predicate)` | 是否所有元素满足条件 |\n| `none_match(array_col, predicate)` | 是否所有元素都不满足条件 |\n| `array_filter(array_col, predicate)` | 根据条件过滤数组，返回新数组 |\n\n**示例**：\n```sql\n-- 当前负责人包含张三\narray_contains(`当前负责人`, '张三')\n\n-- 优先级包含 P0 或 P1\narray_contains(`优先级`, 'P0', 'P1')\n\n-- 当前负责人包含当前登录用户或李四\nany_match(`当前负责人`, x -> x in (current_login_user(), '李四'))\n\n-- 所有处理人都在后端团队中\nall_match(`处理人`, usr -> usr in team(true, '后端开发团队'))\n\n-- 标签数组为空\narray_cardinality(`标签`) = 0\n```\n\n### 时间函数\n\n支持的函数：`RELATIVE_DATETIME_EQ`、`RELATIVE_DATETIME_GT`、`RELATIVE_DATETIME_GE`、`RELATIVE_DATETIME_LT`、`RELATIVE_DATETIME_LE`、`RELATIVE_DATETIME_BETWEEN`\n\n函数签名：`RELATIVE_DATETIME_*(col_name, 'date_para', ['days'])`\n\n**date_para 枚举值**：\n\n| 枚举 | 含义 | 是否支持 days 参数 |\n|------|------|-------------------|\n| today | 当天 | 支持（正值向后偏移，负值向前偏移） |\n| tomorrow | 明天 | 不支持 |\n| yesterday | 昨天 | 不支持 |\n| current_week | 当周 | 不支持 |\n| next_week | 下周 | 不支持 |\n| last_week | 上周 | 不支持 |\n| current_month | 当月 | 不支持 |\n| next_month | 下月 | 不支持 |\n| last_month | 上月 | 不支持 |\n| future | 从今天起的未来范围 | 支持 |\n| past | 从今天起的过去范围 | 支持 |\n\n**days 参数**：仅 `today`、`future`、`past` 支持。格式为 `'Nd'` 或 `'-Nd'`。\n\n**示例**：\n```sql\n-- 今天创建的工作项\nRELATIVE_DATETIME_EQ(`创建时间`, 'today')\n\n-- 3天内到期的工作项\nRELATIVE_DATETIME_LE(`截止时间`, 'future', '3d')\n\n-- 上周创建的需求\nRELATIVE_DATETIME_BETWEEN(`创建时间`, 'last_week')\n\n-- 本月更新的任务\nRELATIVE_DATETIME_BETWEEN(`更新时间`, 'current_month')\n\n-- 今天后 3 天\nRELATIVE_DATETIME_EQ(`创建时间`, 'today', '3d')\n\n-- 今天前 3 天\nRELATIVE_DATETIME_EQ(`创建时间`, 'today', '-3d')\n\n-- 排期开始时间在过去 30 天内\nRELATIVE_DATETIME_BETWEEN(`__需求排期_开始时间`, 'past', '30d')\n```\n\n### 人员与角色函数\n\n| 函数 | 说明 |\n|------|------|\n| `current_login_user()` | 返回当前登录用户的 userkey |\n| `team(include_manager, '团队名')` | 返回团队成员 userkey 数组（第一个参数 true 表示包含管理者） |\n| `all_participate_persons()` | 返回所有参与当前工作项的人员 userkey 数组 |\n| `participate_roles()` | 返回所有参与角色的 rolekey 数组（如 RD、QA、PM） |\n\n**示例**：\n```sql\n-- 当前负责人是当前登录用户\narray_contains(`当前负责人`, current_login_user())\n\n-- 指派给产品团队（含管理者）\nany_match(`当前负责人`, x -> x in team(true, '产品团队'))\n\n-- 查询有 RD 和 QA 角色参与的工作项\nWHERE array_contains(participate_roles(), 'RD', 'QA')\n```\n\n---\n\n## 名称消歧（`` 语法）\n\n当人名、团队名等存在重复时，MQL 会因无法唯一标识而报错。此时使用 `` 语法指定唯一 ID：\n\n```sql\n-- 人名消歧：张三对应多人时，指定 userkey\nWHERE `创建人` = '张三'\n\n-- 团队名消歧：指定团队唯一 key\nWHERE any_match(`负责人`, x -> x in (team(true, '开放平台团队')))\n```\n\n遇到 MQL 返回\"名称重复\"类错误时，需获取对应的唯一 ID 后使用此语法重试。\n\n---\n\n## 特殊字段查询规则\n\n### 日期区间类型字段\n\n日期区间类型（如\"需求排期\"）不能直接查询，必须拆分为子字段，格式：`` `__排期名_开始时间` `` / `` `__排期名_结束时间` ``\n\n```sql\n-- 正确：使用子字段\nWHERE `__开发周期_开始时间` > '2025-01-01' AND `__开发周期_结束时间` < '2025-01-31'\nWHERE RELATIVE_DATETIME_BETWEEN(`__需求排期_开始时间`, 'past', '30d')\n\n-- 错误：直接查询日期区间字段\nWHERE RELATIVE_DATETIME_BETWEEN(`需求排期`, 'past', '30d')\n```\n\n### 角色字段\n\n角色可作为 MQL 属性查询，使用 `__角色名` 格式（加 `__` 前缀以区分普通自定义字段）：\n\n```sql\n-- 查询 RD 包含某人的工作项\nWHERE array_contains(`__RD`, '张三')\n\n-- 查询多个角色条件\nWHERE array_contains(`__RD`, '张三') AND array_contains(`__PM`, '李四')\n```\n\n---\n\n## 完整查询示例\n\n> 以下示例优先使用字段 key。字段 key 从 `workitem meta-fields` 返回值获取；找不到 key 时可用中文字段名兜底。\n\n### 示例 1：查询空间下我参与的 P0 需求\n\n```sql\nSELECT `work_item_id`, `name`, `priority`, `current_owners`, `status`\nFROM `空间名`.`story`\nWHERE array_contains(`priority`, 'P0')\n AND array_contains(all_participate_persons(), current_login_user())\n```\n\n### 示例 2：查询最近一周创建的缺陷\n\n```sql\nSELECT `work_item_id`, `name`, `created_by`, `created_at`, `status`\nFROM `空间名`.`issue`\nWHERE RELATIVE_DATETIME_BETWEEN(`created_at`, 'past', '7d')\n```\n\n### 示例 3：查询逾期未完成的任务\n\n```sql\n-- __需求排期_结束时间 为排期子字段，名称因空间配置而异，需从 workitem meta-fields 确认\nSELECT `work_item_id`, `name`, `current_owners`, `__需求排期_结束时间`, `status`\nFROM `空间名`.`task`\nWHERE RELATIVE_DATETIME_LT(`__需求排期_结束时间`, 'today')\n AND `status` != '已完成'\n```\n\n### 示例 4：查询某团队 RD 负责的需求\n\n```sql\nSELECT `work_item_id`, `name`, `__RD`, `status`\nFROM `空间名`.`story`\nWHERE any_match(`__RD`, x -> x in (team(true, '开放平台团队')))\n```\n\n### 示例 5：查询我创建的进行中的需求（带排序和分页）\n\n```sql\nSELECT `work_item_id`, `name`, `priority`, `status`\nFROM `空间名`.`story`\nWHERE `created_by` = current_login_user()\n AND `status` = '进行中'\nORDER BY `created_at` DESC\nLIMIT 20\n```\n\n### 示例 6：模糊匹配 + 当前登录用户\n\n```sql\nSELECT `work_item_id`, `name`\nFROM `空间名`.`issue`\nWHERE `name` NOT LIKE '%后端性能问题%'\n AND array_contains(all_participate_persons(), '李四')\n AND `assigned_to` = current_login_user()\nORDER BY `created_at` ASC\nLIMIT 10\n```\n\nArchive v0.1.3: 3 files, 8244 bytes\n\nFiles: references/mql-syntax.md (9343b), SKILL.md (9361b), _meta.json (138b)\n\nFile v0.1.3:SKILL.md\n\n---\nname: lark-project-meegle\ndescription: 连接飞书项目/Meegle，查询和管理工作项、待办等。自动检测登录状态，未登录时引导 Device Code 授权。\nversion: 0.1.1\nhomepage: https://www.npmjs.com/package/@lark-project/meegle\nmetadata:\n openclaw:\n homepage: https://www.npmjs.com/package/@lark-project/meegle\n emoji: 📋\n requires:\n bins:\n - node\n - npx\n install:\n - kind: node\n package: \"@lark-project/meegle\"\n bins:\n - meegle\n---\n\n# Meegle SKILL\n\n通过 Meegle CLI 连接飞书项目/Meegle 平台，支持查询工作项、管理待办等操作。\n\n## 前置条件\n\n运行环境需要 Node.js 18+。所有命令通过 `npx @lark-project/meegle@latest` 执行，无需手动安装或更新。\n\n## 触发条件\n\n- **主动登录**：用户说\"登录 Meegle\"、\"连接飞书项目\"、\"login meegle\"等。\n- **被动拦截**：用户请求任何 Meegle 业务操作（查询待办、查工作项、创建任务等），优先执行 Auth Guard。\n- **URL 触发**：用户发送了一个看起来像飞书项目/Meegle 工作项的 URL（路径中通常包含 `workitem`、`detail`、`story`、`issue` 等关键词）。处理流程：\n 1. 从 URL 提取 `$host`（域名部分）和可能的 `$project_key`、`$work_item_id`\n 2. 执行 Auth Guard（STEP 1 中若 `$host` 为 null，用 URL 提取的 host 覆盖，跳过 STEP 2）\n 3. 登录成功后：\n - 如果解析出了 `$project_key` 和 `$work_item_id` → 直接执行 `workitem get` 查询详情\n - 如果无法解析 → 告知用户已登录成功，请描述需要查询的内容\n\n## Auth Guard（所有业务命令前必须执行）\n\n按以下 STEP 顺序执行。每个 STEP 结尾的 GOTO 指明下一步，严格遵循跳转。\n---\n\n### STEP 1 — 检查登录状态\n\n```bash\nnpx @lark-project/meegle@latest auth status --format json\n```\n\n返回值示例：\n- 已登录：`{ \"authenticated\": true, \"host\": \"meegle.com\", \"source\": \"token_store\", \"expires_in_minutes\": 42 }`\n- 未登录且有 host：`{ \"authenticated\": false, \"host\": \"meegle.com\", \"source\": null, \"expires_in_minutes\": null }`\n- 未登录且无 host：`{ \"authenticated\": false, \"host\": null, \"source\": null, \"expires_in_minutes\": null }`\n\n解析返回值，保存变量：\n- `$authenticated` = response.authenticated\n- `$host` = response.host\n\n**URL 触发时的 host 覆盖**：如果用户发送了飞书项目/Meegle URL 触发本流程，且 `$host` 为 null，则从 URL 域名部分提取 `$host`。\n\n**跳转：**\n- IF `$authenticated == true` → GOTO STEP 6\n- IF `$host != null` → GOTO STEP 3\n- IF `$host == null` → GOTO STEP 2\n\n---\n\n### STEP 2 — 选择站点\nASK user（等待用户回复）：\n\n> 你要连接哪个站点？\n> 1) 飞书项目 (project.feishu.cn)\n> 2) Meegle (meegle.com)\n> 3) 自定义域名（请直接输入域名）\n\nSAVE `$host` from user reply → GOTO STEP 3\n\n---\n\n### STEP 3 — 初始化 Device Code\n\n```bash\nnpx @lark-project/meegle@latest auth login --device-code --phase init --host $host --format json\n```\n\nSAVE from response：\n- `$verification_uri_complete` = response.verification_uri_complete\n- `$user_code` = response.user_code\n- `$device_code` = response.device_code\n- `$client_id` = response.client_id\n- `$interval` = response.interval\n- `$expires_in` = response.expires_in\n- `$max_attempts` = floor($expires_in / $interval)\n\n**发送验证链接给用户：**\n\nSEND to user: `请在浏览器中打开以下链接完成授权：\\n$verification_uri_complete\\n验证码：$user_code（$expires_in 秒内有效）`\n\n> ⚠️ 发送后立即 GOTO STEP 4。**禁止**在此停下等用户回复\"我授权好了\"。你必须主动轮询。\n\n→ GOTO STEP 4\n\n---\n### STEP 4 — 轮询授权结果（循环）\n\n> ⚠️ 使用 STEP 3 保存的 `$device_code` 和 `$client_id`。**禁止**重新执行 STEP 3（否则会生成新的验证码，用户之前打开的链接作废）。\n\n```bash\nsleep $interval && npx @lark-project/meegle@latest auth login --device-code --phase poll --once \\\n --device-code-value $device_code --client-id $client_id --format json\n```\n\nPARSE response → `$status` = response.status\n\n**跳转：**\n- IF `$status == \"ok\"` → GOTO STEP 5\n- IF `$status == \"authorization_pending\"` → GOTO STEP 4（重复本步骤，继续轮询）\n- IF `$status == \"slow_down\"` → `$interval = $interval + 5`，GOTO STEP 4\n- IF `$status == \"expired_token\"` → SEND \"授权已超时，请重新发起登录\"，STOP\n- IF attempts > `$max_attempts` → SEND \"轮询超时，请重试\"，STOP\n\n---\n\n### STEP 5 — 通知登录成功\n\nSEND to user: \"登录成功！\"\n\n> ⚠️ 此消息**必须单独发送**，不要与后续业务查询结果合并到同一条回复中。用户需要第一时间看到授权状态变化。\n\n→ GOTO STEP 6\n\n---\n\n### STEP 6 — 执行业务命令\n\nAuth 已通过，进入下方「业务命令调用」部分执行用户请求的操作。\n\n## 获取当前用户信息\n\n当用户说\"我的 xxx\"、\"查一下我的 xxx\"时，需要知道当前登录用户的身份。\n\n**MQL 查询中**：直接使用 `current_login_user()` 函数，无需提前获取用户信息。例如：\n```sql\nWHERE array_contains(`current_owners`, current_login_user())\n```\n\n**非 MQL 场景**（需要用户名、userkey 等具体信息）：目前没有专用命令，通过以下 workaround 获取：\n\n1. 先用 MQL 查询当前用户最近创建的一个工作项：\n```bash\nnpx @lark-project/meegle@latest workitem query --project-key \\\n --search-mql \"SELECT \\`work_item_id\\`, \\`created_by\\` FROM \\`<空间名>\\`.\\`<工作项类型>\\` WHERE \\`created_by\\` = current_login_user() LIMIT 1\" \\\n --format json\n```\n2. 从返回结果的 `created_by` 字段提取当前用户信息\n\n> ⚠️ 此 workaround 需要已知一个 `project_key` 和对应的工作项类型。如果用户未指定空间，先询问。\n\n## 业务命令调用\n\nAuth Guard 通过后，使用以下模式调用业务命令。\n\n### 命令结构\n\n```bash\nnpx @lark-project/meegle@latest [flags] --format json\n```\n\n命令采用 `resource method` 两级结构。所有输出默认 JSON 格式。\n\n### 全局 Flag\n\n| Flag | 说明 |\n|------|------|\n| `--format json\\|table\\|ndjson` | 输出格式，默认 json |\n| `--select ` | 选取输出属性，逗号分隔（支持 dot path，如 `name,owner.name`） |\n| `--profile ` | 临时切换 profile |\n| `--verbose` | 显示详细日志 |\n\n### 参数传递\n\n三种方式，优先级从高到低：\n\n1. **Flag 模式**（推荐）：`--project-key PROJ --work-item-type-key story`\n2. **--set 模式**（设置工作项字段）：`--set priority=1 --set name=\"任务标题\"`，value 支持 JSON\n3. **--params 模式**（完整 JSON）：`--params '{\"project_key\":\"PROJ\",\"work_item_type_key\":\"story\"}'`\n\nFlag 和 --set 会覆盖 --params 中的同名字段。\n\n### 命令发现\n\nCLI 的命令和参数会随版本更新。下方速查表仅列举常见操作，**不是完整列表**。遇到以下情况时，必须先用 `inspect` 获取最新信息：\n\n- 用户请求的操作不在速查表中\n- 不确定某个命令的参数名称或是否为必填\n- 需要查看某个命令支持的全部参数\n\n```bash\nnpx @lark-project/meegle@latest inspect # 列出所有可用命令\nnpx @lark-project/meegle@latest inspect workitem.create # 查看具体命令的参数 schema\n```\n\n### 常用命令速查\n\n#### 查询待办\n\n```bash\nnpx @lark-project/meegle@latest mywork todo --format json\n```\n\n#### 查询工作项\n\n```bash\nnpx @lark-project/meegle@latest workitem get --project-key --work-item-id --format json\n```\n\n#### 搜索工作项（MQL）\n\n> MQL 语法详见 `references/mql-syntax.md`。`--search-mql` 参数必须是完整的 SQL 语句（含 SELECT/FROM），不接受 JSON 或片段。\n\n```bash\nnpx @lark-project/meegle@latest workitem query --project-key --search-mql \"\" --format json\n```\n\n#### 创建工作项\n\n```bash\nnpx @lark-project/meegle@latest workitem create --project-key --work-item-type-key \\\n --set name=\"标题\" --set priority=1 --format json\n```\n\n#### 更新工作项字段\n\n```bash\nnpx @lark-project/meegle@latest workitem update --project-key --work-item-id \\\n --set name=\"新标题\" --format json\n```\n\n#### 查询项目信息\n\n```bash\nnpx @lark-project/meegle@latest project get --project-key --format json\n```\n\n#### 查询工作项类型和字段元数据\n\n```bash\nnpx @lark-project/meegle@latest workitem meta-types --project-key --format json\nnpx @lark-project/meegle@latest workitem meta-fields --project-key --work-item-type-key --format json\n```\n\n### 输出处理\n\n- 始终使用 `--format json` 获取结构化输出，方便解析\n- 使用 `--select` 精简返回字段，如 `--select id,name,current_nodes.name`\n- 命令返回错误时，JSON 中包含 `error` 和 `message` 字段\n\n## 错误处理\n\n- 如果 bash 返回 `command not found` 或 npx 不可用，提示用户安装 Node.js 18+。\n- 如果 `--phase init` 返回错误（站点不支持 Device Code），提示用户在终端中执行 `npx @lark-project/meegle@latest auth login`。\n- 如果 `--phase poll` 超时，提示用户重试登录流程。\n\nFile v0.1.3:_meta.json\n\n{\n \"ownerId\": \"kn78dhc955jdhgxvfjp6fd9aeh83p3t5\",\n \"slug\": \"lark-project-meegle\",\n \"version\": \"0.1.3\",\n \"publishedAt\": 1774945267303\n}\n\nFile v0.1.3:references/mql-syntax.md\n\n# MQL 语法规范参考\n\n> **重要：`workitem query` 的 `--search-mql` 参数必须是完整的 SQL 查询语句**\n> - 必须包含 `SELECT` 和 `FROM` 子句\n> - 不接受 JSON 对象、简写条件或不完整片段\n> - 正确: `` SELECT `工作项ID`, `名称` FROM `空间名`.`需求` WHERE `状态` = '进行中' ``\n> - 错误: `{\"status\": \"进行中\"}` / `status = '进行中'` / `WHERE status = '进行中'`\n\n## 基础语法\n\n```sql\nSELECT fieldList -- 指定查询的字段列表\nFROM `空间名`.`工作项类型名` -- 指定数据来源\nWHERE conditionExpression -- 查询条件（可选）\n[ORDER BY fieldOrderByList [{ASC|DESC}]] -- 排序（可选）\n[LIMIT [offset,] row_count] -- 分页（可选）\n```\n\n**标识符规则**：\n- 所有字段名和表名必须使用反引号包裹，如 `` `工作项ID` ``、`` `空间名`.`需求` ``\n- SELECT/FROM/WHERE/ORDER BY 中既可使用 key 也可使用名称。**优先使用 key**，从 `workitem meta-fields` 返回值中获取：系统字段 key 为单词（如 `priority`、`status`），自定义字段 key 为 `field_x23bd` 格式，工作项类型 key 如 `story`、`issue`。名称是用户自定义的 UGC 内容（语言不定），仅作为找不到 key 时的兜底\n- **禁止** `count()`、`SUM()`、`GROUP BY`。总数从返回结果的 `count` 字段读取\n\n---\n\n## 数据类型\n\n| MQL 类型 | 说明 | 对应的工作项字段类型 |\n|-----------|------|-------------------|\n| bool | 真假值，取值 TRUE/FALSE/1/0 | bool |\n| bigint | 整数类型 | number 类型下的 work_item_id 和 auto_number |\n| double | 浮点数类型 | 除 work_item_id/auto_number 外的其他 number |\n| varchar | 字符串类型 | text、multi-pure-text、multi-text、select、tree-select、radio、user、link、signal、workitem_related_select |\n| date | 日期类型，格式 `YYYY-MM-DD` 或 `YYYY-MM-DD+TZD`（如 `2025-12-24+08:00`） | date |\n| datetime | 日期时间类型，格式 `YYYY-MM-DDThh:mm:ss` 或 `YYYY-MM-DDThh:mm:ssTZD` | schedule、precise_date |\n| array(varchar) | 字符串数组 | multi-select、tree-multi-select、multi-user、link_cloud_doc、workitem_related_multi_select、multi-file |\n| array(struct) | 结构体数组 | compound_field |\n| lambda expression | 返回 bool 的函数表达式，写法：`x -> x > 10`、`x -> x in ('a', 'b')` | — |\n\n---\n\n## 常用运算符\n\n### BETWEEN ... AND ...\n\n标准 SQL 区间查询，适用于日期和数值字段：\n\n```sql\nWHERE `创建时间` BETWEEN '2025-01-01' AND '2025-10-01'\n```\n\n### LIKE / NOT LIKE\n\n模糊匹配，`%` 匹配任意字符：\n\n```sql\nWHERE `缺陷名` LIKE '%性能问题%'\nWHERE `缺陷名` NOT LIKE '%后端性能问题%'\n```\n\n---\n\n## 常用函数\n\n### 数组函数\n\n| 函数 | 说明 |\n|------|------|\n| `array_cardinality(array_col)` | 获取数组长度 |\n| `array_contains(array_col, element [, element2, ...])` | 数组是否包含某元素（多值表示包含其中之一） |\n| `any_match(array_col, predicate)` | 是否有任一元素满足条件 |\n| `all_match(array_col, predicate)` | 是否所有元素满足条件 |\n| `none_match(array_col, predicate)` | 是否所有元素都不满足条件 |\n| `array_filter(array_col, predicate)` | 根据条件过滤数组，返回新数组 |\n\n**示例**：\n```sql\n-- 当前负责人包含张三\narray_contains(`当前负责人`, '张三')\n\n-- 优先级包含 P0 或 P1\narray_contains(`优先级`, 'P0', 'P1')\n\n-- 当前负责人包含当前登录用户或李四\nany_match(`当前负责人`, x -> x in (current_login_user(), '李四'))\n\n-- 所有处理人都在后端团队中\nall_match(`处理人`, usr -> usr in team(true, '后端开发团队'))\n\n-- 标签数组为空\narray_cardinality(`标签`) = 0\n```\n\n### 时间函数\n\n支持的函数：`RELATIVE_DATETIME_EQ`、`RELATIVE_DATETIME_GT`、`RELATIVE_DATETIME_GE`、`RELATIVE_DATETIME_LT`、`RELATIVE_DATETIME_LE`、`RELATIVE_DATETIME_BETWEEN`\n\n函数签名：`RELATIVE_DATETIME_*(col_name, 'date_para', ['days'])`\n\n**date_para 枚举值**：\n\n| 枚举 | 含义 | 是否支持 days 参数 |\n|------|------|-------------------|\n| today | 当天 | 支持（正值向后偏移，负值向前偏移） |\n| tomorrow | 明天 | 不支持 |\n| yesterday | 昨天 | 不支持 |\n| current_week | 当周 | 不支持 |\n| next_week | 下周 | 不支持 |\n| last_week | 上周 | 不支持 |\n| current_month | 当月 | 不支持 |\n| next_month | 下月 | 不支持 |\n| last_month | 上月 | 不支持 |\n| future | 从今天起的未来范围 | 支持 |\n| past | 从今天起的过去范围 | 支持 |\n\n**days 参数**：仅 `today`、`future`、`past` 支持。格式为 `'Nd'` 或 `'-Nd'`。\n\n**示例**：\n```sql\n-- 今天创建的工作项\nRELATIVE_DATETIME_EQ(`创建时间`, 'today')\n\n-- 3天内到期的工作项\nRELATIVE_DATETIME_LE(`截止时间`, 'future', '3d')\n\n-- 上周创建的需求\nRELATIVE_DATETIME_BETWEEN(`创建时间`, 'last_week')\n\n-- 本月更新的任务\nRELATIVE_DATETIME_BETWEEN(`更新时间`, 'current_month')\n\n-- 今天后 3 天\nRELATIVE_DATETIME_EQ(`创建时间`, 'today', '3d')\n\n-- 今天前 3 天\nRELATIVE_DATETIME_EQ(`创建时间`, 'today', '-3d')\n\n-- 排期开始时间在过去 30 天内\nRELATIVE_DATETIME_BETWEEN(`__需求排期_开始时间`, 'past', '30d')\n```\n\n### 人员与角色函数\n\n| 函数 | 说明 |\n|------|------|\n| `current_login_user()` | 返回当前登录用户的 userkey |\n| `team(include_manager, '团队名')` | 返回团队成员 userkey 数组（第一个参数 true 表示包含管理者） |\n| `all_participate_persons()` | 返回所有参与当前工作项的人员 userkey 数组 |\n| `participate_roles()` | 返回所有参与角色的 rolekey 数组（如 RD、QA、PM） |\n\n**示例**：\n```sql\n-- 当前负责人是当前登录用户\narray_contains(`当前负责人`, current_login_user())\n\n-- 指派给产品团队（含管理者）\nany_match(`当前负责人`, x -> x in team(true, '产品团队'))\n\n-- 查询有 RD 和 QA 角色参与的工作项\nWHERE array_contains(participate_roles(), 'RD', 'QA')\n```\n\n---\n\n## 名称消歧（`` 语法）\n\n当人名、团队名等存在重复时，MQL 会因无法唯一标识而报错。此时使用 `` 语法指定唯一 ID：\n\n```sql\n-- 人名消歧：张三对应多人时，指定 userkey\nWHERE `创建人` = '张三'\n\n-- 团队名消歧：指定团队唯一 key\nWHERE any_match(`负责人`, x -> x in (team(true, '开放平台团队')))\n```\n\n遇到 MQL 返回\"名称重复\"类错误时，需获取对应的唯一 ID 后使用此语法重试。\n\n---\n\n## 特殊字段查询规则\n\n### 日期区间类型字段\n\n日期区间类型（如\"需求排期\"）不能直接查询，必须拆分为子字段，格式：`` `__排期名_开始时间` `` / `` `__排期名_结束时间` ``\n\n```sql\n-- 正确：使用子字段\nWHERE `__开发周期_开始时间` > '2025-01-01' AND `__开发周期_结束时间` < '2025-01-31'\nWHERE RELATIVE_DATETIME_BETWEEN(`__需求排期_开始时间`, 'past', '30d')\n\n-- 错误：直接查询日期区间字段\nWHERE RELATIVE_DATETIME_BETWEEN(`需求排期`, 'past', '30d')\n```\n\n### 角色字段\n\n角色可作为 MQL 属性查询，使用 `__角色名` 格式（加 `__` 前缀以区分普通自定义字段）：\n\n```sql\n-- 查询 RD 包含某人的工作项\nWHERE array_contains(`__RD`, '张三')\n\n-- 查询多个角色条件\nWHERE array_contains(`__RD`, '张三') AND array_contains(`__PM`, '李四')\n```\n\n---\n\n## 完整查询示例\n\n> 以下示例优先使用字段 key。字段 key 从 `workitem meta-fields` 返回值获取；找不到 key 时可用中文字段名兜底。\n\n### 示例 1：查询空间下我参与的 P0 需求\n\n```sql\nSELECT `work_item_id`, `name`, `priority`, `current_owners`, `status`\nFROM `空间名`.`story`\nWHERE array_contains(`priority`, 'P0')\n AND array_contains(all_participate_persons(), current_login_user())\n```\n\n### 示例 2：查询最近一周创建的缺陷\n\n```sql\nSELECT `work_item_id`, `name`, `created_by`, `created_at`, `status`\nFROM `空间名`.`issue`\nWHERE RELATIVE_DATETIME_BETWEEN(`created_at`, 'past', '7d')\n```\n\n### 示例 3：查询逾期未完成的任务\n\n```sql\n-- __需求排期_结束时间 为排期子字段，名称因空间配置而异，需从 workitem meta-fields 确认\nSELECT `work_item_id`, `name`, `current_owners`, `__需求排期_结束时间`, `status`\nFROM `空间名`.`task`\nWHERE RELATIVE_DATETIME_LT(`__需求排期_结束时间`, 'today')\n AND `status` != '已完成'\n```\n\n### 示例 4：查询某团队 RD 负责的需求\n\n```sql\nSELECT `work_item_id`, `name`, `__RD`, `status`\nFROM `空间名`.`story`\nWHERE any_match(`__RD`, x -> x in (team(true, '开放平台团队')))\n```\n\n### 示例 5：查询我创建的进行中的需求（带排序和分页）\n\n```sql\nSELECT `work_item_id`, `name`, `priority`, `status`\nFROM `空间名`.`story`\nWHERE `created_by` = current_login_user()\n AND `status` = '进行中'\nORDER BY `created_at` DESC\nLIMIT 20\n```\n\n### 示例 6：模糊匹配 + 当前登录用户\n\n```sql\nSELECT `work_item_id`, `name`\nFROM `空间名`.`issue`\nWHERE `name` NOT LIKE '%后端性能问题%'\n AND array_contains(all_participate_persons(), '李四')\n AND `assigned_to` = current_login_user()\nORDER BY `created_at` ASC\nLIMIT 10\n```\n\nArchive v0.1.2: 3 files, 8245 bytes\n\nFiles: references/mql-syntax.md (9343b), SKILL.md (9327b), _meta.json (138b)\n\nFile v0.1.2:SKILL.md\n\n---\nname: lark-project-meegle\ndescription: 连接飞书项目/Meegle，查询和管理工作项、待办等。自动检测登录状态，未登录时引导 Device Code 授权。\nversion: 0.1.1\nhomepage: https://www.npmjs.com/package/@lark-project/meegle\nmetadata:\n openclaw:\n homepage: https://www.npmjs.com/package/@lark-project/meegle\n emoji: 📋\n requires:\n bins:\n - node\n - npx\n install:\n - kind: node\n package: \"@lark-project/meegle\"\n bins:\n - meegle\n---\n\n# Meegle SKILL\n\n通过 Meegle CLI 连接飞书项目/Meegle 平台，支持查询工作项、管理待办等操作。\n\n## 前置条件\n\n运行环境需要 Node.js 18+。所有命令通过 `npx @lark-project/meegle@beta` 执行，无需手动安装或更新。\n\n## 触发条件\n\n- **主动登录**：用户说\"登录 Meegle\"、\"连接飞书项目\"、\"login meegle\"等。\n- **被动拦截**：用户请求任何 Meegle 业务操作（查询待办、查工作项、创建任务等），优先执行 Auth Guard。\n- **URL 触发**：用户发送了一个看起来像飞书项目/Meegle 工作项的 URL（路径中通常包含 `workitem`、`detail`、`story`、`issue` 等关键词）。处理流程：\n 1. 从 URL 提取 `$host`（域名部分）和可能的 `$project_key`、`$work_item_id`\n 2. 执行 Auth Guard（STEP 1 中若 `$host` 为 null，用 URL 提取的 host 覆盖，跳过 STEP 2）\n 3. 登录成功后：\n - 如果解析出了 `$project_key` 和 `$work_item_id` → 直接执行 `workitem get` 查询详情\n - 如果无法解析 → 告知用户已登录成功，请描述需要查询的内容\n\n## Auth Guard（所有业务命令前必须执行）\n\n按以下 STEP 顺序执行。每个 STEP 结尾的 GOTO 指明下一步，严格遵循跳转。\n---\n\n### STEP 1 — 检查登录状态\n\n```bash\nnpx @lark-project/meegle@beta auth status --format json\n```\n\n返回值示例：\n- 已登录：`{ \"authenticated\": true, \"host\": \"meegle.com\", \"source\": \"token_store\", \"expires_in_minutes\": 42 }`\n- 未登录且有 host：`{ \"authenticated\": false, \"host\": \"meegle.com\", \"source\": null, \"expires_in_minutes\": null }`\n- 未登录且无 host：`{ \"authenticated\": false, \"host\": null, \"source\": null, \"expires_in_minutes\": null }`\n\n解析返回值，保存变量：\n- `$authenticated` = response.authenticated\n- `$host` = response.host\n\n**URL 触发时的 host 覆盖**：如果用户发送了飞书项目/Meegle URL 触发本流程，且 `$host` 为 null，则从 URL 域名部分提取 `$host`。\n\n**跳转：**\n- IF `$authenticated == true` → GOTO STEP 6\n- IF `$host != null` → GOTO STEP 3\n- IF `$host == null` → GOTO STEP 2\n\n---\n\n### STEP 2 — 选择站点\nASK user（等待用户回复）：\n\n> 你要连接哪个站点？\n> 1) 飞书项目 (project.feishu.cn)\n> 2) Meegle (meegle.com)\n> 3) 自定义域名（请直接输入域名）\n\nSAVE `$host` from user reply → GOTO STEP 3\n\n---\n\n### STEP 3 — 初始化 Device Code\n\n```bash\nnpx @lark-project/meegle@beta auth login --device-code --phase init --host $host --format json\n```\n\nSAVE from response：\n- `$verification_uri_complete` = response.verification_uri_complete\n- `$user_code` = response.user_code\n- `$device_code` = response.device_code\n- `$client_id` = response.client_id\n- `$interval` = response.interval\n- `$expires_in` = response.expires_in\n- `$max_attempts` = floor($expires_in / $interval)\n\n**发送验证链接给用户：**\n\nSEND to user: `请在浏览器中打开以下链接完成授权：\\n$verification_uri_complete\\n验证码：$user_code（$expires_in 秒内有效）`\n\n> ⚠️ 发送后立即 GOTO STEP 4。**禁止**在此停下等用户回复\"我授权好了\"。你必须主动轮询。\n\n→ GOTO STEP 4\n\n---\n### STEP 4 — 轮询授权结果（循环）\n\n> ⚠️ 使用 STEP 3 保存的 `$device_code` 和 `$client_id`。**禁止**重新执行 STEP 3（否则会生成新的验证码，用户之前打开的链接作废）。\n\n```bash\nsleep $interval && npx @lark-project/meegle@beta auth login --device-code --phase poll --once \\\n --device-code-value $device_code --client-id $client_id --format json\n```\n\nPARSE response → `$status` = response.status\n\n**跳转：**\n- IF `$status == \"ok\"` → GOTO STEP 5\n- IF `$status == \"authorization_pending\"` → GOTO STEP 4（重复本步骤，继续轮询）\n- IF `$status == \"slow_down\"` → `$interval = $interval + 5`，GOTO STEP 4\n- IF `$status == \"expired_token\"` → SEND \"授权已超时，请重新发起登录\"，STOP\n- IF attempts > `$max_attempts` → SEND \"轮询超时，请重试\"，STOP\n\n---\n\n### STEP 5 — 通知登录成功\n\nSEND to user: \"登录成功！\"\n\n> ⚠️ 此消息**必须单独发送**，不要与后续业务查询结果合并到同一条回复中。用户需要第一时间看到授权状态变化。\n\n→ GOTO STEP 6\n\n---\n\n### STEP 6 — 执行业务命令\n\nAuth 已通过，进入下方「业务命令调用」部分执行用户请求的操作。\n\n## 获取当前用户信息\n\n当用户说\"我的 xxx\"、\"查一下我的 xxx\"时，需要知道当前登录用户的身份。\n\n**MQL 查询中**：直接使用 `current_login_user()` 函数，无需提前获取用户信息。例如：\n```sql\nWHERE array_contains(`current_owners`, current_login_user())\n```\n\n**非 MQL 场景**（需要用户名、userkey 等具体信息）：目前没有专用命令，通过以下 workaround 获取：\n\n1. 先用 MQL 查询当前用户最近创建的一个工作项：\n```bash\nnpx @lark-project/meegle@beta workitem query --project-key \\\n --search-mql \"SELECT \\`work_item_id\\`, \\`created_by\\` FROM \\`<空间名>\\`.\\`<工作项类型>\\` WHERE \\`created_by\\` = current_login_user() LIMIT 1\" \\\n --format json\n```\n2. 从返回结果的 `created_by` 字段提取当前用户信息\n\n> ⚠️ 此 workaround 需要已知一个 `project_key` 和对应的工作项类型。如果用户未指定空间，先询问。\n\n## 业务命令调用\n\nAuth Guard 通过后，使用以下模式调用业务命令。\n\n### 命令结构\n\n```bash\nnpx @lark-project/meegle@beta [flags] --format json\n```\n\n命令采用 `resource method` 两级结构。所有输出默认 JSON 格式。\n\n### 全局 Flag\n\n| Flag | 说明 |\n|------|------|\n| `--format json\\|table\\|ndjson` | 输出格式，默认 json |\n| `--select ` | 选取输出属性，逗号分隔（支持 dot path，如 `name,owner.name`） |\n| `--profile ` | 临时切换 profile |\n| `--verbose` | 显示详细日志 |\n\n### 参数传递\n\n三种方式，优先级从高到低：\n\n1. **Flag 模式**（推荐）：`--project-key PROJ --work-item-type-key story`\n2. **--set 模式**（设置工作项字段）：`--set priority=1 --set name=\"任务标题\"`，value 支持 JSON\n3. **--params 模式**（完整 JSON）：`--params '{\"project_key\":\"PROJ\",\"work_item_type_key\":\"story\"}'`\n\nFlag 和 --set 会覆盖 --params 中的同名字段。\n\n### 命令发现\n\nCLI 的命令和参数会随版本更新。下方速查表仅列举常见操作，**不是完整列表**。遇到以下情况时，必须先用 `inspect` 获取最新信息：\n\n- 用户请求的操作不在速查表中\n- 不确定某个命令的参数名称或是否为必填\n- 需要查看某个命令支持的全部参数\n\n```bash\nnpx @lark-project/meegle@beta inspect # 列出所有可用命令\nnpx @lark-project/meegle@beta inspect workitem.create # 查看具体命令的参数 schema\n```\n\n### 常用命令速查\n\n#### 查询待办\n\n```bash\nnpx @lark-project/meegle@beta mywork todo --format json\n```\n\n#### 查询工作项\n\n```bash\nnpx @lark-project/meegle@beta workitem get --project-key --work-item-id --format json\n```\n\n#### 搜索工作项（MQL）\n\n> MQL 语法详见 `references/mql-syntax.md`。`--search-mql` 参数必须是完整的 SQL 语句（含 SELECT/FROM），不接受 JSON 或片段。\n\n```bash\nnpx @lark-project/meegle@beta workitem query --project-key --search-mql \"\" --format json\n```\n\n#### 创建工作项\n\n```bash\nnpx @lark-project/meegle@beta workitem create --project-key --work-item-type-key \\\n --set name=\"标题\" --set priority=1 --format json\n```\n\n#### 更新工作项字段\n\n```bash\nnpx @lark-project/meegle@beta workitem update --project-key --work-item-id \\\n --set name=\"新标题\" --format json\n```\n\n#### 查询项目信息\n\n```bash\nnpx @lark-project/meegle@beta project get --project-key --format json\n```\n\n#### 查询工作项类型和字段元数据\n\n```bash\nnpx @lark-project/meegle@beta workitem meta-types --project-key --format json\nnpx @lark-project/meegle@beta workitem meta-fields --project-key --work-item-type-key --format json\n```\n\n### 输出处理\n\n- 始终使用 `--format json` 获取结构化输出，方便解析\n- 使用 `--select` 精简返回字段，如 `--select id,name,current_nodes.name`\n- 命令返回错误时，JSON 中包含 `error` 和 `message` 字段\n\n## 错误处理\n\n- 如果 bash 返回 `command not found` 或 npx 不可用，提示用户安装 Node.js 18+。\n- 如果 `--phase init` 返回错误（站点不支持 Device Code），提示用户在终端中执行 `npx @lark-project/meegle@beta auth login`。\n- 如果 `--phase poll` 超时，提示用户重试登录流程。\n\nFile v0.1.2:_meta.json\n\n{\n \"ownerId\": \"kn78dhc955jdhgxvfjp6fd9aeh83p3t5\",\n \"slug\": \"lark-project-meegle\",\n \"version\": \"0.1.2\",\n \"publishedAt\": 1774849996647\n}\n\nFile v0.1.2:references/mql-syntax.md\n\n# MQL 语法规范参考\n\n> **重要：`workitem query` 的 `--search-mql` 参数必须是完整的 SQL 查询语句**\n> - 必须包含 `SELECT` 和 `FROM` 子句\n> - 不接受 JSON 对象、简写条件或不完整片段\n> - 正确: `` SELECT `工作项ID`, `名称` FROM `空间名`.`需求` WHERE `状态` = '进行中' ``\n> - 错误: `{\"status\": \"进行中\"}` / `status = '进行中'` / `WHERE status = '进行中'`\n\n## 基础语法\n\n```sql\nSELECT fieldList -- 指定查询的字段列表\nFROM `空间名`.`工作项类型名` -- 指定数据来源\nWHERE conditionExpression -- 查询条件（可选）\n[ORDER BY fieldOrderByList [{ASC|DESC}]] -- 排序（可选）\n[LIMIT [offset,] row_count] -- 分页（可选）\n```\n\n**标识符规则**：\n- 所有字段名和表名必须使用反引号包裹，如 `` `工作项ID` ``、`` `空间名`.`需求` ``\n- SELECT/FROM/WHERE/ORDER BY 中既可使用 key 也可使用名称。**优先使用 key**，从 `workitem meta-fields` 返回值中获取：系统字段 key 为单词（如 `priority`、`status`），自定义字段 key 为 `field_x23bd` 格式，工作项类型 key 如 `story`、`issue`。名称是用户自定义的 UGC 内容（语言不定），仅作为找不到 key 时的兜底\n- **禁止** `count()`、`SUM()`、`GROUP BY`。总数从返回结果的 `count` 字段读取\n\n---\n\n## 数据类型\n\n| MQL 类型 | 说明 | 对应的工作项字段类型 |\n|-----------|------|-------------------|\n| bool | 真假值，取值 TRUE/FALSE/1/0 | bool |\n| bigint | 整数类型 | number 类型下的 work_item_id 和 auto_number |\n| double | 浮点数类型 | 除 work_item_id/auto_number 外的其他 number |\n| varchar | 字符串类型 | text、multi-pure-text、multi-text、select、tree-select、radio、user、link、signal、workitem_related_select |\n| date | 日期类型，格式 `YYYY-MM-DD` 或 `YYYY-MM-DD+TZD`（如 `2025-12-24+08:00`） | date |\n| datetime | 日期时间类型，格式 `YYYY-MM-DDThh:mm:ss` 或 `YYYY-MM-DDThh:mm:ssTZD` | schedule、precise_date |\n| array(varchar) | 字符串数组 | multi-select、tree-multi-select、multi-user、link_cloud_doc、workitem_related_multi_select、multi-file |\n| array(struct) | 结构体数组 | compound_field |\n| lambda expression | 返回 bool 的函数表达式，写法：`x -> x > 10`、`x -> x in ('a', 'b')` | — |\n\n---\n\n## 常用运算符\n\n### BETWEEN ... AND ...\n\n标准 SQL 区间查询，适用于日期和数值字段：\n\n```sql\nWHERE `创建时间` BETWEEN '2025-01-01' AND '2025-10-01'\n```\n\n### LIKE / NOT LIKE\n\n模糊匹配，`%` 匹配任意字符：\n\n```sql\nWHERE `缺陷名` LIKE '%性能问题%'\nWHERE `缺陷名` NOT LIKE '%后端性能问题%'\n```\n\n---\n\n## 常用函数\n\n### 数组函数\n\n| 函数 | 说明 |\n|------|------|\n| `array_cardinality(array_col)` | 获取数组长度 |\n| `array_contains(array_col, element [, element2, ...])` | 数组是否包含某元素（多值表示包含其中之一） |\n| `any_match(array_col, predicate)` | 是否有任一元素满足条件 |\n| `all_match(array_col, predicate)` | 是否所有元素满足条件 |\n| `none_match(array_col, predicate)` | 是否所有元素都不满足条件 |\n| `array_filter(array_col, predicate)` | 根据条件过滤数组，返回新数组 |\n\n**示例**：\n```sql\n-- 当前负责人包含张三\narray_contains(`当前负责人`, '张三')\n\n-- 优先级包含 P0 或 P1\narray_contains(`优先级`, 'P0', 'P1')\n\n-- 当前负责人包含当前登录用户或李四\nany_match(`当前负责人`, x -> x in (current_login_user(), '李四'))\n\n-- 所有处理人都在后端团队中\nall_match(`处理人`, usr -> usr in team(true, '后端开发团队'))\n\n-- 标签数组为空\narray_cardinality(`标签`) = 0\n```\n\n### 时间函数\n\n支持的函数：`RELATIVE_DATETIME_EQ`、`RELATIVE_DATETIME_GT`、`RELATIVE_DATETIME_GE`、`RELATIVE_DATETIME_LT`、`RELATIVE_DATETIME_LE`、`RELATIVE_DATETIME_BETWEEN`\n\n函数签名：`RELATIVE_DATETIME_*(col_name, 'date_para', ['days'])`\n\n**date_para 枚举值**：\n\n| 枚举 | 含义 | 是否支持 days 参数 |\n|------|------|-------------------|\n| today | 当天 | 支持（正值向后偏移，负值向前偏移） |\n| tomorrow | 明天 | 不支持 |\n| yesterday | 昨天 | 不支持 |\n| current_week | 当周 | 不支持 |\n| next_week | 下周 | 不支持 |\n| last_week | 上周 | 不支持 |\n| current_month | 当月 | 不支持 |\n| next_month | 下月 | 不支持 |\n| last_month | 上月 | 不支持 |\n| future | 从今天起的未来范围 | 支持 |\n| past | 从今天起的过去范围 | 支持 |\n\n**days 参数**：仅 `today`、`future`、`past` 支持。格式为 `'Nd'` 或 `'-Nd'`。\n\n**示例**：\n```sql\n-- 今天创建的工作项\nRELATIVE_DATETIME_EQ(`创建时间`, 'today')\n\n-- 3天内到期的工作项\nRELATIVE_DATETIME_LE(`截止时间`, 'future', '3d')\n\n-- 上周创建的需求\nRELATIVE_DATETIME_BETWEEN(`创建时间`, 'last_week')\n\n-- 本月更新的任务\nRELATIVE_DATETIME_BETWEEN(`更新时间`, 'current_month')\n\n-- 今天后 3 天\nRELATIVE_DATETIME_EQ(`创建时间`, 'today', '3d')\n\n-- 今天前 3 天\nRELATIVE_DATETIME_EQ(`创建时间`, 'today', '-3d')\n\n-- 排期开始时间在过去 30 天内\nRELATIVE_DATETIME_BETWEEN(`__需求排期_开始时间`, 'past', '30d')\n```\n\n### 人员与角色函数\n\n| 函数 | 说明 |\n|------|------|\n| `current_login_user()` | 返回当前登录用户的 userkey |\n| `team(include_manager, '团队名')` | 返回团队成员 userkey 数组（第一个参数 true 表示包含管理者） |\n| `all_participate_persons()` | 返回所有参与当前工作项的人员 userkey 数组 |\n| `participate_roles()` | 返回所有参与角色的 rolekey 数组（如 RD、QA、PM） |\n\n**示例**：\n```sql\n-- 当前负责人是当前登录用户\narray_contains(`当前负责人`, current_login_user())\n\n-- 指派给产品团队（含管理者）\nany_match(`当前负责人`, x -> x in team(true, '产品团队'))\n\n-- 查询有 RD 和 QA 角色参与的工作项\nWHERE array_contains(participate_roles(), 'RD', 'QA')\n```\n\n---\n\n## 名称消歧（`` 语法）\n\n当人名、团队名等存在重复时，MQL 会因无法唯一标识而报错。此时使用 `` 语法指定唯一 ID：\n\n```sql\n-- 人名消歧：张三对应多人时，指定 userkey\nWHERE `创建人` = '张三'\n\n-- 团队名消歧：指定团队唯一 key\nWHERE any_match(`负责人`, x -> x in (team(true, '开放平台团队')))\n```\n\n遇到 MQL 返回\"名称重复\"类错误时，需获取对应的唯一 ID 后使用此语法重试。\n\n---\n\n## 特殊字段查询规则\n\n### 日期区间类型字段\n\n日期区间类型（如\"需求排期\"）不能直接查询，必须拆分为子字段，格式：`` `__排期名_开始时间` `` / `` `__排期名_结束时间` ``\n\n```sql\n-- 正确：使用子字段\nWHERE `__开发周期_开始时间` > '2025-01-01' AND `__开发周期_结束时间` < '2025-01-31'\nWHERE RELATIVE_DATETIME_BETWEEN(`__需求排期_开始时间`, 'past', '30d')\n\n-- 错误：直接查询日期区间字段\nWHERE RELATIVE_DATETIME_BETWEEN(`需求排期`, 'past', '30d')\n```\n\n### 角色字段\n\n角色可作为 MQL 属性查询，使用 `__角色名` 格式（加 `__` 前缀以区分普通自定义字段）：\n\n```sql\n-- 查询 RD 包含某人的工作项\nWHERE array_contains(`__RD`, '张三')\n\n-- 查询多个角色条件\nWHERE array_contains(`__RD`, '张三') AND array_contains(`__PM`, '李四')\n```\n\n---\n\n## 完整查询示例\n\n> 以下示例优先使用字段 key。字段 key 从 `workitem meta-fields` 返回值获取；找不到 key 时可用中文字段名兜底。\n\n### 示例 1：查询空间下我参与的 P0 需求\n\n```sql\nSELECT `work_item_id`, `name`, `priority`, `current_owners`, `status`\nFROM `空间名`.`story`\nWHERE array_contains(`priority`, 'P0')\n AND array_contains(all_participate_persons(), current_login_user())\n```\n\n### 示例 2：查询最近一周创建的缺陷\n\n```sql\nSELECT `work_item_id`, `name`, `created_by`, `created_at`, `status`\nFROM `空间名`.`issue`\nWHERE RELATIVE_DATETIME_BETWEEN(`created_at`, 'past', '7d')\n```\n\n### 示例 3：查询逾期未完成的任务\n\n```sql\n-- __需求排期_结束时间 为排期子字段，名称因空间配置而异，需从 workitem meta-fields 确认\nSELECT `work_item_id`, `name`, `current_owners`, `__需求排期_结束时间`, `status`\nFROM `空间名`.`task`\nWHERE RELATIVE_DATETIME_LT(`__需求排期_结束时间`, 'today')\n AND `status` != '已完成'\n```\n\n### 示例 4：查询某团队 RD 负责的需求\n\n```sql\nSELECT `work_item_id`, `name`, `__RD`, `status`\nFROM `空间名`.`story`\nWHERE any_match(`__RD`, x -> x in (team(true, '开放平台团队')))\n```\n\n### 示例 5：查询我创建的进行中的需求（带排序和分页）\n\n```sql\nSELECT `work_item_id`, `name`, `priority`, `status`\nFROM `空间名`.`story`\nWHERE `created_by` = current_login_user()\n AND `status` = '进行中'\nORDER BY `created_at` DESC\nLIMIT 20\n```\n\n### 示例 6：模糊匹配 + 当前登录用户\n\n```sql\nSELECT `work_item_id`, `name`\nFROM `空间名`.`issue`\nWHERE `name` NOT LIKE '%后端性能问题%'\n AND array_contains(all_participate_persons(), '李四')\n AND `assigned_to` = current_login_user()\nORDER BY `created_at` ASC\nLIMIT 10\n```\n\nArchive v0.1.1: 2 files, 3754 bytes\n\nFiles: SKILL.md (7939b), _meta.json (138b)\n\nFile v0.1.1:SKILL.md\n\n---\nname: lark-project-meegle\ndescription: 连接飞书项目/Meegle，查询和管理工作项、待办等。自动检测登录状态，未登录时引导 Device Code 授权。\nversion: 0.1.1\nhomepage: https://www.npmjs.com/package/@lark-project/meegle\nmetadata:\n openclaw:\n homepage: https://www.npmjs.com/package/@lark-project/meegle\n emoji: 📋\n requires:\n bins:\n - node\n - npx\n install:\n - kind: node\n package: \"@lark-project/meegle\"\n bins:\n - meegle\n---\n\n# Meegle SKILL\n\n通过 Meegle CLI 连接飞书项目/Meegle 平台，支持查询工作项、管理待办等操作。\n\n## 前置条件\n\n运行环境需要 Node.js 18+。所有命令通过 `npx @lark-project/meegle@beta` 执行，无需手动安装或更新。\n\n## Auth Guard（所有业务命令前必须执行）\n\n按以下 STEP 顺序执行。每个 STEP 结尾的 GOTO 指明下一步，严格遵循跳转。\n\n---\n\n### STEP 1 — 检查登录状态\n\n```bash\nnpx @lark-project/meegle@beta auth status --format json\n```\n\n返回值示例：\n- 已登录：`{ \"authenticated\": true, \"host\": \"meegle.com\", \"source\": \"token_store\", \"expires_in_minutes\": 42 }`\n- 未登录且有 host：`{ \"authenticated\": false, \"host\": \"meegle.com\", \"source\": null, \"expires_in_minutes\": null }`\n- 未登录且无 host：`{ \"authenticated\": false, \"host\": null, \"source\": null, \"expires_in_minutes\": null }`\n\n解析返回值，保存变量：\n- `$authenticated` = response.authenticated\n- `$host` = response.host\n\n**跳转：**\n- IF `$authenticated == true` → GOTO STEP 6\n- IF `$host != null` → GOTO STEP 3\n- IF `$host == null` → GOTO STEP 2\n\n---\n\n### STEP 2 — 选择站点\n\nASK user（等待用户回复）：\n\n> 你要连接哪个站点？\n> 1) 飞书项目 (project.feishu.cn)\n> 2) Meegle (meegle.com)\n> 3) 自定义域名（请直接输入域名）\n\nSAVE `$host` from user reply → GOTO STEP 3\n\n---\n\n### STEP 3 — 初始化 Device Code\n\n```bash\nnpx @lark-project/meegle@beta auth login --device-code --phase init --host $host --format json\n```\n\nSAVE from response：\n- `$verification_uri_complete` = response.verification_uri_complete\n- `$user_code` = response.user_code\n- `$device_code` = response.device_code\n- `$client_id` = response.client_id\n- `$interval` = response.interval\n- `$expires_in` = response.expires_in\n- `$max_attempts` = floor($expires_in / $interval)\n\n**发送验证链接给用户：**\n\nIF channel == \"feishu\" OR channel == \"lark\"（参考 Runtime metadata 中的 `channel=` 字段）:\n- SEND 消息卡片（如果当前 channel 支持卡片格式）：\n - 标题: \"Meegle 授权登录\"\n - 内容: 验证码 `$user_code`，有效期 `$expires_in` 秒\n - 按钮: \"打开授权页面\" → `$verification_uri_complete`\n - 如果不支持卡片，回退到下方纯文本格式\n\nELSE:\n- SEND to user: `请在浏览器中打开以下链接完成授权：\\n$verification_uri_complete\\n验证码：$user_code（$expires_in 秒内有效）`\n\n> ⚠️ 发送后立即 GOTO STEP 4。**禁止**在此停下等用户回复\"我授权好了\"。你必须主动轮询。\n\n→ GOTO STEP 4\n\n---\n\n### STEP 4 — 轮询授权结果（循环）\n\n> ⚠️ 使用 STEP 3 保存的 `$device_code` 和 `$client_id`。**禁止**重新执行 STEP 3（否则会生成新的验证码，用户之前打开的链接作废）。\n\n```bash\nsleep $interval && npx @lark-project/meegle@beta auth login --device-code --phase poll --once \\\n --device-code-value $device_code --client-id $client_id --format json\n```\n\nPARSE response → `$status` = response.status\n\n**跳转：**\n- IF `$status == \"ok\"` → GOTO STEP 5\n- IF `$status == \"authorization_pending\"` → GOTO STEP 4（重复本步骤，继续轮询）\n- IF `$status == \"slow_down\"` → `$interval = $interval + 5`，GOTO STEP 4\n- IF `$status == \"expired_token\"` → SEND \"授权已超时，请重新发起登录\"，STOP\n- IF attempts > `$max_attempts` → SEND \"轮询超时，请重试\"，STOP\n\n---\n\n### STEP 5 — 通知登录成功\n\nSEND to user: \"登录成功！\"\n\n> ⚠️ 此消息**必须单独发送**，不要与后续业务查询结果合并到同一条回复中。用户需要第一时间看到授权状态变化。\n\n→ GOTO STEP 6\n\n---\n\n### STEP 6 — 执行业务命令\n\nAuth 已通过，进入下方「业务命令调用」部分执行用户请求的操作。\n\n## 业务命令调用\n\nAuth Guard 通过后，使用以下模式调用业务命令。\n\n### 命令结构\n\n```bash\nnpx @lark-project/meegle@beta [flags] --format json\n```\n\n命令采用 `resource method` 两级结构。所有输出默认 JSON 格式。\n\n### 全局 Flag\n\n| Flag | 说明 |\n|------|------|\n| `--format json\\|table\\|ndjson` | 输出格式，默认 json |\n| `--select ` | 选取输出属性，逗号分隔（支持 dot path，如 `name,owner.name`） |\n| `--profile ` | 临时切换 profile |\n| `--verbose` | 显示详细日志 |\n\n### 参数传递\n\n三种方式，优先级从高到低：\n\n1. **Flag 模式**（推荐）：`--project-key PROJ --work-item-type-key story`\n2. **--set 模式**（设置工作项字段）：`--set priority=1 --set name=\"任务标题\"`，value 支持 JSON\n3. **--params 模式**（完整 JSON）：`--params '{\"project_key\":\"PROJ\",\"work_item_type_key\":\"story\"}'`\n\nFlag 和 --set 会覆盖 --params 中的同名字段。\n\n### 常用命令速查\n\n#### 查询待办\n\n```bash\nnpx @lark-project/meegle@beta mywork todo --format json\n```\n\n#### 查询工作项\n\n```bash\nnpx @lark-project/meegle@beta workitem get --project-key --work-item-id --format json\n```\n\n#### 搜索工作项（MQL）\n\n```bash\nnpx @lark-project/meegle@beta workitem query --project-key --search-mql \"\" --format json\n```\n\n#### 创建工作项\n\n```bash\nnpx @lark-project/meegle@beta workitem create --project-key --work-item-type-key \\\n --set name=\"标题\" --set priority=1 --format json\n```\n\n#### 更新工作项字段\n\n```bash\nnpx @lark-project/meegle@beta workitem update --project-key --work-item-id \\\n --set name=\"新标题\" --format json\n```\n\n#### 查询项目信息\n\n```bash\nnpx @lark-project/meegle@beta project get --project-key --format json\n```\n\n#### 查询工作项类型和字段元数据\n\n```bash\nnpx @lark-project/meegle@beta workitem meta-types --project-key --format json\nnpx @lark-project/meegle@beta workitem meta-fields --project-key --work-item-type-key --format json\n```\n\n### 查看命令参数（inspect）\n\n使用 `inspect` 查看某个命令的完整参数 schema（必填/可选、类型、描述）：\n\n```bash\nnpx @lark-project/meegle@beta inspect workitem.create # 查看 workitem create 的参数详情\nnpx @lark-project/meegle@beta inspect workitem.query # 查看 workitem query 的参数详情\n```\n\n不带参数时列出所有可用命令：\n\n```bash\nnpx @lark-project/meegle@beta inspect # 列出所有 resource 及其 method\n```\n\n> **推荐**：在调用一个不熟悉的命令前，先用 `inspect` 查看其参数 schema，确认必填字段和类型。\n\n### 输出处理\n\n- 始终使用 `--format json` 获取结构化输出，方便解析\n- 使用 `--select` 精简返回字段，如 `--select id,name,current_nodes.name`\n- 命令返回错误时，JSON 中包含 `error` 和 `message` 字段\n\n## 触发条件\n\n- **主动登录**：用户说\"登录 Meegle\"、\"连接飞书项目\"、\"login meegle\"等。\n- **被动拦截**：用户请求任何 Meegle 业务操作（查询待办、查工作项、创建任务等），优先执行 Auth Guard。\n\n## 错误处理\n\n- 如果 bash 返回 `command not found` 或 npx 不可用，提示用户安装 Node.js 18+。\n- 如果 `--phase init` 返回错误（站点不支持 Device Code），提示用户在终端中执行 `npx @lark-project/meegle@beta auth login`。\n- 如果 `--phase poll` 超时，提示用户重试登录流程。\n\nFile v0.1.1:_meta.json\n\n{\n \"ownerId\": \"kn78dhc955jdhgxvfjp6fd9aeh83p3t5\",\n \"slug\": \"lark-project-meegle\",\n \"version\": \"0.1.1\",\n \"publishedAt\": 1774617550990\n}\n\nArchive v0.1.0: 2 files, 3553 bytes\n\nFiles: SKILL.md (7442b), _meta.json (138b)\n\nFile v0.1.0:SKILL.md\n\n---\nname: meegle\ndescription: 连接飞书项目/Meegle，查询和管理工作项、待办等。自动检测登录状态，未登录时引导 Device Code 授权。\nversion: 0.0.3\nhomepage: https://www.npmjs.com/package/@lark-project/meegle\nmetadata:\n openclaw:\n homepage: https://www.npmjs.com/package/@lark-project/meegle\n emoji: 📋\n requires:\n bins:\n - node\n - npx\n install:\n - kind: node\n package: \"@lark-project/meegle\"\n bins:\n - meegle\n---\n\n# Meegle SKILL\n\n通过 Meegle CLI 连接飞书项目/Meegle 平台，支持查询工作项、管理待办等操作。\n\n## 前置条件\n\n运行环境需要 Node.js 18+。所有命令通过 `npx @lark-project/meegle@beta` 执行，无需手动安装或更新。\n\n## Auth Guard\n\n在执行任何 Meegle 业务命令前，必须先检查登录状态。执行以下步骤：\n\n### 步骤 1：检查登录状态\n\n```bash\nnpx @lark-project/meegle@beta auth status --format json\n```\n\n返回值示例：\n- 已登录：`{ \"authenticated\": true, \"host\": \"meegle.com\", \"source\": \"token_store\", \"expires_in_minutes\": 42 }`\n- 未登录且有 host：`{ \"authenticated\": false, \"host\": \"meegle.com\", \"source\": null, \"expires_in_minutes\": null }`\n- 未登录且无 host：`{ \"authenticated\": false, \"host\": null, \"source\": null, \"expires_in_minutes\": null }`\n\n### 步骤 2：处理结果\n\n- **authenticated 为 true**：直接执行业务命令。\n- **authenticated 为 false**：进入登录引导流程（见下方）。\n\n## 登录引导流程\n\n### 选择站点\n\n如果 `host` 为 null（首次使用），询问用户：\n\n> 你要连接哪个站点？\n> 1) 飞书项目 (project.feishu.cn)\n> 2) Meegle (meegle.com)\n> 3) 自定义域名（请直接输入域名）\n\n用户回复后获得 host 值。如果 `host` 已有值，跳过此步。\n\n### 初始化授权\n\n使用 host 值执行：\n\n```bash\nnpx @lark-project/meegle@beta auth login --device-code --phase init --host --format json\n```\n\n返回 JSON 包含 `verification_uri_complete`、`user_code`、`device_code`、`client_id`、`interval`、`expires_in`。\n\n解析 JSON 后向用户发送：\n\n> 请在浏览器中打开以下链接完成授权：\n> \n\n### 等待授权完成（主动轮询）\n\n> **关键行为**：发送验证链接后，你必须**立即开始轮询**，不要等待用户回复。将 `sleep` 和 `poll` 合并为一条 Bash 命令执行，检查结果后决定下一步。\n\n按以下循环执行（**发送验证链接后立即进入第 1 步，不要停下来等用户消息**）：\n\n1. 执行 sleep + 单次轮询（合并为一条命令，避免中断）：\n\n```bash\nsleep && npx @lark-project/meegle@beta auth login --device-code --phase poll --once \\\n --device-code-value --client-id --format json\n```\n\n2. 根据返回的 `status` 字段处理：\n - `\"ok\"`：**立即通知用户登录成功**（发送消息或更新卡片），然后再继续执行用户原始请求的业务命令。\n - `\"authorization_pending\"`：用户尚未完成授权，**立即回到步骤 1 继续轮询**（再次调用同样的 sleep + poll 命令）。\n - `\"slow_down\"`：轮询过快，将 `interval` 增加 5 秒，回到步骤 1。\n - `\"expired_token\"`：授权已超时，提示用户重新发起登录。\n\n3. 最多轮询 `expires_in / interval` 次。超过后提示用户重试。\n\n> **禁止**：不要在发送验证链接后停下来等用户说\"我授权好了\"。你必须主动轮询，用户在浏览器完成授权后你应当自动检测到。\n\n> **重要**：授权成功后，必须先单独发送一条\"登录成功\"的消息给用户，再执行后续业务命令。不要把登录结果和业务查询结果合并到一次响应中——用户需要第一时间看到授权状态的变化。\n\n## 业务命令调用\n\nAuth Guard 通过后，使用以下模式调用业务命令。\n\n### 命令结构\n\n```bash\nnpx @lark-project/meegle@beta [flags] --format json\n```\n\n命令采用 `resource method` 两级结构。所有输出默认 JSON 格式。\n\n### 全局 Flag\n\n| Flag | 说明 |\n|------|------|\n| `--format json\\|table\\|ndjson` | 输出格式，默认 json |\n| `--select ` | 选取输出属性，逗号分隔（支持 dot path，如 `name,owner.name`） |\n| `--profile ` | 临时切换 profile |\n| `--verbose` | 显示详细日志 |\n\n### 参数传递\n\n三种方式，优先级从高到低：\n\n1. **Flag 模式**（推荐）：`--project-key PROJ --work-item-type-key story`\n2. **--set 模式**（设置工作项字段）：`--set priority=1 --set name=\"任务标题\"`，value 支持 JSON\n3. **--params 模式**（完整 JSON）：`--params '{\"project_key\":\"PROJ\",\"work_item_type_key\":\"story\"}'`\n\nFlag 和 --set 会覆盖 --params 中的同名字段。\n\n### 常用命令速查\n\n#### 查询待办\n\n```bash\nnpx @lark-project/meegle@beta my todo --format json\n```\n\n#### 查询工作项\n\n```bash\nnpx @lark-project/meegle@beta workitem get --project-key --work-item-id --format json\n```\n\n#### 搜索工作项（MQL）\n\n```bash\nnpx @lark-project/meegle@beta workitem query --project-key --search-mql \"\" --format json\n```\n\n#### 创建工作项\n\n```bash\nnpx @lark-project/meegle@beta workitem create --project-key --work-item-type-key \\\n --set name=\"标题\" --set priority=1 --format json\n```\n\n#### 更新工作项字段\n\n```bash\nnpx @lark-project/meegle@beta workitem update --project-key --work-item-id \\\n --set name=\"新标题\" --format json\n```\n\n#### 查询项目信息\n\n```bash\nnpx @lark-project/meegle@beta project get --project-key --format json\n```\n\n#### 查询工作项类型和字段元数据\n\n```bash\nnpx @lark-project/meegle@beta workitem meta-types --project-key --format json\nnpx @lark-project/meegle@beta workitem meta-fields --project-key --work-item-type-key --format json\n```\n\n### 查看命令参数（inspect）\n\n使用 `inspect` 查看某个命令的完整参数 schema（必填/可选、类型、描述）：\n\n```bash\nnpx @lark-project/meegle@beta inspect workitem.create # 查看 workitem create 的参数详情\nnpx @lark-project/meegle@beta inspect workitem.query # 查看 workitem query 的参数详情\n```\n\n不带参数时列出所有可用命令：\n\n```bash\nnpx @lark-project/meegle@beta inspect # 列出所有 resource 及其 method\n```\n\n> **推荐**：在调用一个不熟悉的命令前，先用 `inspect` 查看其参数 schema，确认必填字段和类型。\n\n### 输出处理\n\n- 始终使用 `--format json` 获取结构化输出，方便解析\n- 使用 `--select` 精简返回字段，如 `--select id,name,current_nodes.name`\n- 命令返回错误时，JSON 中包含 `error` 和 `message` 字段\n\n## 触发条件\n\n- **主动登录**：用户说\"登录 Meegle\"、\"连接飞书项目\"、\"login meegle\"等。\n- **被动拦截**：用户请求任何 Meegle 业务操作（查询待办、查工作项、创建任务等），优先执行 Auth Guard。\n\n## 错误处理\n\n- 如果 bash 返回 `command not found` 或 npx 不可用，提示用户安装 Node.js 18+。\n- 如果 `--phase init` 返回错误（站点不支持 Device Code），提示用户在终端中执行 `npx @lark-project/meegle@beta auth login`。\n- 如果 `--phase poll` 超时，提示用户重试登录流程。\n\nFile v0.1.0:_meta.json\n\n{\n \"ownerId\": \"kn78dhc955jdhgxvfjp6fd9aeh83p3t5\",\n \"slug\": \"lark-project-meegle\",\n \"version\": \"0.1.0\",\n \"publishedAt\": 1774611956253\n}","readmeExcerpt":"Skill: Lark Project / Meegle Owner: kentonyu Summary: 连接飞书项目/Meegle，查询和管理工作项、待办等。自动检测登录状态，未登录时引导 Device Code 授权。 Tags: beta:0.1.2, latest:0.1.5 Version history: v0.1.5 | 2026-05-08T07:16:59.212Z | user **Added comprehensive CLI reference docs and modularized main SKILL file.** - Added 13 new detailed docs in the references/ directory (e.g. api-examples, auth-guard, mql-syntax, attachment, workflow). - Rewrote the mai","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"npx @lark-project/meegle@latest project search --project-key 空间名或key --format json"},{"language":"bash","snippet":"npx @lark-project/meegle@latest workitem meta-types --project-key 空间key --format json"},{"language":"bash","snippet":"npx @lark-project/meegle@latest workitem meta-fields --page-num 1 --project-key 空间key --work-item-type story --field-types '{{field_types}}' --field-keys '{{field_keys}}' --field-query '{{field_query}}' --format json"},{"language":"bash","snippet":"npx @lark-project/meegle@latest workitem meta-roles --page-num 1 --project-key 空间key --work-item-type story --role-keys '{{role_keys}}' --role-query '{{role_query}}' --format json"},{"language":"bash","snippet":"npx @lark-project/meegle@latest workitem query --project-key 空间key --session-id {{session_id}} --mql 'SELECT `work_item_id`, `name`, `current_owners`, `status` FROM `空间名`.`story` WHERE `is_archived` = 0' --group-pagination-list '{{group_pagination_list}}' --format json"},{"language":"bash","snippet":"npx @lark-project/meegle@latest workitem get --work-item-id 工作项ID或名称 --fields '{{fields}}' --project-key 空间key --format json"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: meegle\ndescription: |\n 连接飞书项目/Meegle，查询和管理工作项、待办等。自动检测登录状态，未登录时引导 Device Code 授权。\nversion: 0.1.1\nhomepage: https://www.npmjs.com/package/@lark-project/meegle\nmetadata:\n openclaw:\n homepage: https://www.npmjs.com/package/@lark-project/meegle\n emoji: 📋\n requires:\n bins:\n - node\n - npx\n install:\n - kind: node\n package: '@lark-project/meegle'\n bins:\n - meegle\n---\n\n# 飞书项目 (Meego/Meegle) 操作指南\n\n本技能通过 Meegle CLI来操作飞书项目数据。输出语言跟随用户输入语言，默认中文。\n\n> 各命令的调用示例见 [references/api-examples.md](references/api-examples.md)。\n> **授权流程**（所有业务命令前必须执行）：见 [references/auth-guard.md](references/auth-guard.md)\n> **CLI 使用指南**（命令结构、参数传递、命令发现）：见 [references/cli-guide.md](references/cli-guide.md)\n\n---\n\n## Project 空间域\n\n### npx @lark-project/meegle@latest project search\n搜索空间信息，将空间名转换为 project_key 或验证空间是否存在。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 projectKey、simpleName 或空间名称 |\n\n---\n\n## WorkItem 工作项域\n\n> 元数据查询命令（`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)。\n\n### npx @lark-project/meegle@latest workitem create\n创建工作项实例。**务必先用 `npx @lark-project/meegle@latest workitem meta-fields` 获取字段信息，`npx @lark-project/meegle@latest workitem meta-roles` 获取角色信息。模板 ID 是必填项。**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --work-item-type | string | 是 | 工作项类型 |\n| --project-key | string | 否 | 空间标识 |\n| --fields | array | 否 | 字段值列表，每项含 field_key 和 field_value |\n\n### npx @lark-project/meegle@latest workitem get\n按 ID/名称查询工作项概况。不传 fields 时仅返回固定基础字段；如需自定义字段数据，先调 `npx @lark-project/meegle@latest workitem meta-fields` 获取字段 key 后传入 fields。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --work-item-id | string | 是 | 工作项 ID 或名称 |\n| --project-key | string | 否 | 空间 key |\n| --fields | array | 否 | 要查询的 field_key 或 field_name |\n\n### npx @lark-project/meegle@latest workitem batch-get\n批量查询工作项（Meegle CLI 客户端 fan-out：并发调用 `npx @lark-project/meegle@latest workitem get`）。单次 ≤ 200 个 ID，3 并发，返回 `{results, errors, summary}`；ID 量大时用 `--format ndjson` 流式输出。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --work-item-ids | array | 二选一 | 工作项 ID 列表（逗号分隔或多次传入） |\n| --ids-file | string | 二选一 | 从文件读取 ID（一行一个，`#` 开头注释） |\n| --fields | array | 否 | 要查询的 field_key 列表 |\n| --project-key | string | 否 | 空间 key |\n\n### npx @lark-project/meegle@latest workitem update\n修改指定实例的字段值或角色。节点字段更新请用 `npx @lark-project/meegle@latest workflow update-node`。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --work-item-id | string | 是 | 工作项 ID 或名称 |\n| --project-key | string | 否 | 空间 key |\n| --fields | array | 否 | 要更新的字段列表，每项含 field_key 和 field_value |\n| --role-operate | array | 否 | 角色操作，每项含 op(add/remove)、role_key、user_keys |\n\n**角色更新**：不能通过 fields 更新角色，必须用 `role_operate`。role_key 通过 "},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn78dhc955jdhgxvfjp6fd9aeh83p3t5\",\n \"slug\": \"lark-project-meegle\",\n \"version\": \"0.1.5\",\n \"publishedAt\": 1778224619212\n}"},{"path":"references/api-examples.md","content":"# 命令调用示例\n\n---\n\n## 空间域\n\n### npx @lark-project/meegle@latest project search\n```bash\nnpx @lark-project/meegle@latest project search --project-key 空间名或key --format json\n```\n\n## 工作项域\n\n### npx @lark-project/meegle@latest workitem meta-types\n```bash\nnpx @lark-project/meegle@latest workitem meta-types --project-key 空间key --format json\n```\n\n### npx @lark-project/meegle@latest workitem meta-fields\n查询所有字段：\n\n```bash\nnpx @lark-project/meegle@latest workitem meta-fields --page-num 1 --project-key 空间key --work-item-type story --field-types '{{field_types}}' --field-keys '{{field_keys}}' --field-query '{{field_query}}' --format json\n```\n\n### npx @lark-project/meegle@latest workitem meta-roles\n```bash\nnpx @lark-project/meegle@latest workitem meta-roles --page-num 1 --project-key 空间key --work-item-type story --role-keys '{{role_keys}}' --role-query '{{role_query}}' --format json\n```\n\n### npx @lark-project/meegle@latest workitem query\n查询空间中所有未冻结的需求：\n\n```bash\nnpx @lark-project/meegle@latest workitem query --project-key 空间key --session-id {{session_id}} --mql 'SELECT `work_item_id`, `name`, `current_owners`, `status` FROM `空间名`.`story` WHERE `is_archived` = 0' --group-pagination-list '{{group_pagination_list}}' --format json\n```\n\n### npx @lark-project/meegle@latest workitem get\n```bash\nnpx @lark-project/meegle@latest workitem get --work-item-id 工作项ID或名称 --fields '{{fields}}' --project-key 空间key --format json\n```\n\n### npx @lark-project/meegle@latest workitem create\n基础创建（仅标量字段）：\n\n```bash\nnpx @lark-project/meegle@latest workitem create --work-item-type story --fields '[{\"field_key\": \"template\", \"field_value\": \"模板ID\"}, {\"field_key\": \"name\", \"field_value\": \"需求标题\"}]' --project-key 空间key --format json\n```\n\n创建缺陷 + 指定报告人（multi-user）+ 指定经办人（role_owners）——注意复合值必须 JSON.stringify：\n\n```bash\nnpx @lark-project/meegle@latest workitem create --work-item-type issue --fields '[{\"field_key\":\"name\",\"field_value\":\"示例缺陷\"},{\"field_key\":\"priority\",\"field_value\":\"2\"},{\"field_key\":\"template\",\"field_value\":\"模板ID\"},{\"field_key\":\"issue_reporter\",\"field_value\":\"[\"userkey1\"]\"},{\"field_key\":\"role_owners\",\"field_value\":\"[{\"role\":\"operator\",\"owners\":[\"userkey1\"]}]\"}]' --project-key 空间key --format json\n```\n\n> 🚨 `issue_reporter`（multi-user 类型的内置角色字段）和 `role_owners`（统一角色入口）是**两种可互换的写法**：前者走 meta-create-fields 返回的字段 key；后者用 meta-roles 返回的 role_id（如 `operator` / `reporter`，不含 `issue_` 前缀）。两者的 `field_value` 都必须是 **stringified JSON** 字符串。\n\n### npx @lark-project/meegle@latest workitem update\n更新普通字段：\n\n```bash\nnpx @lark-project/meegle@latest workitem update --work-item-id 工作项ID --project-key 空间key --role-operate '{{role_operate}}' --fields '[{\"field_key\": \"priority\", \"field_value\": \"option_id\"}]' --format json\n```\n\n更新 multi-user 字段（复合值 stringified）：\n\n```bash\nnpx @lark-project/meegle@latest workitem update --work-item-id 工作项ID --project-key 空间key --role-operate '{{role_operate}}' --fields '[{\"field_key\": \"current_status_operator\", \"field_value\": \"[\"userkey1\",\"userkey2\"]\"}]' --format json\n```\n\n---\n\n## 人员域\n\n### np"},{"path":"references/attachment.md","content":"# 附件域\n\n附件上传/下载分两步：先调 `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` 一键封装，把两步合成一条命令；脚本里需要逐步控制时也可单独调上面的 prepare 命令。\n## npx @lark-project/meegle@latest attachment prepare-upload\n申请上传签名。`work_item_id` 与 `work_item_type` **二选一必填**：已有工作项传 `work_item_id`；\"创建工作项时同步上传附件\" 场景传 `work_item_type`，两者同传时 `work_item_id` 优先。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 key |\n| --resource-type | number | 是 | 附件场景：13=评论附件 / 14=评论图片 / 15=工作项附件字段 / 16=富文本字段图片 |\n| --file-name | string | 是 | 附件名称 |\n| --mime-type | string | 是 | MIME 类型 |\n| --size | number | 是 | 文件总大小（字节）；后端据此判断走单次上传还是分片 |\n| --work-item-id | string | 二选一 | 已有工作项 ID |\n| --work-item-type | string | 二选一 | 工作项类型（仅 \"创建工作项同步上传附件\" 场景） |\n| --field-key | string | 条件 | `resource_type=15/16` 必填，13/14 不填 |\n\n## npx @lark-project/meegle@latest attachment prepare-download\n申请下载签名。`file_url` 是其它命令（如 `npx @lark-project/meegle@latest workitem get` 的附件字段值、`npx @lark-project/meegle@latest comment list` 评论里的附件链接、富文本中的附件引用）回传的不透明引用，**不要**手工拼接。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --project-key | string | 是 | 空间 key |\n| --work-item-id | string | 是 | 工作项 ID |\n| --file-url | string | 是 | 附件 URL（来自附件字段、评论或富文本） |\n\n## npx @lark-project/meegle@latest attachment +upload\n端到端上传：CLI 在本地把 `npx @lark-project/meegle@latest attachment prepare-upload` 与对象存储的签名 HTTP POST 串起来，返回 `file_token` 与文件元数据，可直接喂给 `npx @lark-project/meegle@latest workitem create` / `npx @lark-project/meegle@latest workitem update` / `npx @lark-project/meegle@latest comment add` 的附件字段。**Meegle CLI 专用**。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| ``（位置参数） | string | 是 | 本地文件路径 |\n| --resource-type | string | 是 | 13/14/15/16，含义同 `npx @lark-project/meegle@latest attachment prepare-upload` |\n| --project-key | string | 是 | 空间 key |\n| --work-item-id | string | 二选一 | 已有工作项 ID |\n| --work-item-type | string | 二选一 | 创建场景的工作项类型 |\n| --field-key | string | 条件 | resource_type=15/16 时必填 |\n| --filename | string | 否 | 覆盖发送给后端的文件名（默认取本地 basename） |\n| --content-type | string | 否 | 覆盖 MIME 类型（默认按扩展名探测，未识别走 `application/octet-stream`） |\n\n## npx @lark-project/meegle@latest attachment +download\n端到端下载：CLI 在本地把 `npx @lark-project/meegle@latest attachment prepare-download` 与对象存储的签名 HTTP GET 串起来，并用 `.partial` 临时文件 + 原子改名落盘，失败时不会留下半残文件。**Meegle CLI 专用**。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| ``（位置参数） | string | 是 | 附件 URL（来自附件字段、评论或富文本） |\n| --project-key | string | 是 | 空间 key |\n| --work-item-id | string | 是 | 工作项 ID |\n| --output | string | 是 | 本地落地路径 |\n| overwrite | bool | 否 | 目标已存在时是否覆盖（默认 false） |"},{"path":"references/auth-guard.md","content":"# Auth Guard（所有业务命令前必须执行）\n\n## 触发条件\n\n- **主动登录**：用户说\"登录 Meegle\"、\"连接飞书项目\"、\"login meegle\"等。\n- **被动拦截**：用户请求任何 Meegle 业务操作（查询待办、查工作项、创建任务等），优先执行 Auth Guard。\n- **URL 触发**：用户发送了飞书项目/Meegle URL。处理流程：\n 1. 先调 `npx @lark-project/meegle@latest url decode` 拿到结构化字段（`url_kind`、`host`、`simple_name`、`work_item_id` 等）。**禁止**自己从 URL 截取路径段作参数。字段含义与 kind 分支见 [url-kinds.md](./url-kinds.md)。\n 2. 保存 `$host` = response.host、`$url_kind`、`$simple_name`、`$work_item_id`。\n 3. 执行 Auth Guard（下面的 STEP 1 起）。\n 4. 登录成功后按 `$url_kind` 分支：\n - `workitem_detail` → `npx @lark-project/meegle@latest project search` 得权威 `$project_key`，再 `npx @lark-project/meegle@latest workitem get` 查询详情\n - `workitem_homepage` / `view_*` / `unknown` 等非详情页 → 按 url-kinds.md 的指引拒绝或追问\n - 其他 kind → 参考 url-kinds.md 对应处理方式\n\n按以下 STEP 顺序执行。每个 STEP 结尾的 GOTO 指明下一步，严格遵循跳转。\n\n---\n\n### STEP 1 — 检查登录状态\n\n```bash\nnpx @lark-project/meegle@latest auth status --format json\n```\n\n返回值示例：\n- 已登录：`{ \"authenticated\": true, \"host\": \"meegle.com\", \"source\": \"token_store\", \"expires_in_minutes\": 42 }`\n- 未登录且有 host：`{ \"authenticated\": false, \"host\": \"meegle.com\", \"source\": null, \"expires_in_minutes\": null }`\n- 未登录且无 host：`{ \"authenticated\": false, \"host\": null, \"source\": null, \"expires_in_minutes\": null }`\n\n解析返回值，保存变量：\n- `$authenticated` = response.authenticated\n- `$host` = response.host\n\n**URL 触发时的 host 覆盖**：如果用户发送了飞书项目/Meegle URL 触发本流程，且 `$host` 为 null，则使用上一步 `url decode` 返回的 `host` 字段作为 `$host`。\n\n**跳转：**\n- IF `$authenticated == true` → GOTO STEP DONE\n- IF `$host != null` → GOTO STEP 2\n- IF `$host == null` → GOTO STEP HOST\n\n---\n\n### STEP HOST — 选择站点\n\nASK user（等待用户回复）：\n\n> 你要连接哪个站点？\n> 1) 飞书项目 (project.feishu.cn)\n> 2) Meegle (meegle.com)\n> 3) 自定义域名（请直接输入域名）\n\nSAVE `$host` from user reply → GOTO STEP 2\n\n---\n\n### STEP 2 — 初始化 Device Code\n\n```bash\nnpx @lark-project/meegle@latest auth login --device-code --phase init --host $host --format json\n```\n\nSAVE from response：\n- `$verification_uri_complete` = response.verification_uri_complete\n- `$user_code` = response.user_code\n- `$device_code` = response.device_code\n- `$client_id` = response.client_id\n- `$interval` = response.interval\n- `$expires_in` = response.expires_in\n- `$max_attempts` = floor($expires_in / $interval)\n\n**发送验证链接给用户：**\n\nSEND to user: `请在浏览器中打开以下链接完成授权：\\n$verification_uri_complete\\n验证码：$user_code（$expires_in 秒内有效）`\n\n> ⚠️ 发送后立即 GOTO STEP 3。**禁止**在此停下等用户回复\"我授权好了\"。你必须主动轮询。\n\n→ GOTO STEP 3\n\n---\n\n### STEP 3 — 轮询授权结果（循环）\n\n> ⚠️ 使用 STEP 2 保存的 `$device_code` 和 `$client_id`。**禁止**重新执行 STEP 2（否则会生成新的验证码，用户之前打开的链接作废）。\n\n```bash\nsleep $interval && npx @lark-project/meegle@latest auth login --device-code --phase poll --once \\\n --device-code-value $device_code --client-id $client_id --format json\n```\n\nPARSE response → `$status` = response.status\n\n**跳转：**\n- IF `$status == \"ok\"` → GOTO STEP OK\n- IF `$status == \"authorization_pending\"` → GOTO STEP 3（重复本步骤，继续轮询）\n- IF `$status == \"slow_down\"` → `$interval = $interval + 5`，GOTO STEP 3\n- IF `$status == \"expired_token\"` → SEND \"授权已超时，请重新发起登录\"，"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1534,"uniquenessScore":35,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T17:35:41.795Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T17:35:41.795Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T22:39:56.047Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}