Meegle

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

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

各命令的调用示例见 references/api-examples.md。

授权流程（所有业务命令前必须执行）：见 references/auth-guard.md

CLI 使用指南（命令结构、参数传递、命令发现）：见 references/cli-guide.md

---

Project 空间域

project search

搜索空间信息，将空间名转换为 project_key 或验证空间是否存在；省略 --project-key 时返回当前用户最近访问过的空间列表（按访问时间由近及远）。

---

WorkItem 工作项域

元数据查询命令（workitem meta-types / workitem meta-fields / workitem meta-roles / workitem meta-create-fields）的参数表见 references/workitem.md。

workitem create

创建工作项实例。务必先用 `workitem meta-fields` 获取字段信息，`workitem meta-roles` 获取角色信息。模板 ID 是必填项。

workitem get

按 ID/名称查询工作项概况。不传 fields 时返回固定基础字段加上一组默认带出的系统字段——实测包含 group_type 拉群方式、description、current_status_operator、watchers（即便 value 为 null 也会出现）；其余字段需要通过 workitem meta-fields 拿到 key 后再传入 fields。

逻辑字段聚合（重要心智模型）：服务端把 group_id / chat_group 这类"拉群"相关的物理字段合并到一个逻辑字段 group_type。读取/更新统一走 group_type，不要再单独读取 `group_id` 或 `chat_group`。

>

⚠️ 读写协议不对称：读返回结构里判别键是 `value`（不是 type），更新时判别键是 `type`——别照着读到的结构直接回写。

>

读返回（workitem_fields[].value 字段）的形状：

- auto → {value: "auto", label: "自动拉群", group_id: "oc_xxx"}（自动拉群通常有 group_id；状态切换时 oc_id 可能会变）

- bind → {value: "bind", label: "绑定现有群", group_id: "oc_xxx"}

- disabled → {value: "disabled", label: "不拉群"}（无 group_id）

>

写协议（field_value 里的 JSON）：{"type": "auto" | "bind" | "disabled", "group_id": "oc_xxx"}

workitem batch-get

批量查询工作项（Meegle CLI 客户端 fan-out：并发调用 workitem get）。单次 ≤ 200 个 ID，3 并发，返回 {results, errors, summary}；ID 量大时用 --format ndjson 流式输出。

workitem update

修改指定实例的字段值或角色。节点字段更新请用 workflow update-node。

角色更新：不能通过 fields 更新角色，必须用 role_operate。role_key 通过 workitem meta-roles 获取，user_keys 通过 user search 获取。

拉群方式更新（`group_type` 逻辑字段）：要修改/读取拉群方式统一走 group_type，不要再单独操作 group_id / chat_group。写协议 field_value 形如：{"type": "auto" | "bind" | "disabled", "group_id": "oc_xxx"}（注意写用 type 作为判别键，与读返回的 `value` 不对称）。校验规则（服务端实际报错文本）：bind 不带 group_id 或带空串/纯空格 → group_id is required when group_type=bind；auto/disabled 同时带 group_id → group_type conflicts with group_id: type=<auto|disabled>。详细示例见 references/sop-update-workitem.md。

workitem query

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

分组分页：

• --group-pagination-list 是数组，当前只支持传一组分页数据；元素结构为 { "group_id": string, "page_num": number }
• group_id 取首查返回的 list[].group_infos[].group_id；无分组查询返回的默认分组 ID 为 "1"，翻页时也传 "1"
• page_num 从 1 开始；MQL 首查不传分页参数时默认返回第一页，单页最多 50 条。当前接口没有 page_size / page_token 子字段
• 翻页时传首查返回的 session_id 和目标分组的分页参数；传 session_id 后后端不再解析 MQL，只按已有会话取对应分组页

要点：

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

workitem list-op-records

查看工作项操作记录。

---

Attachment 附件域

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

---

WorkFlow 工作流域

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

workflow transition

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

workflow transition-state

仅用于状态流工作项，流转工作项状态。先用 workflow list-state-transitions 获取可流转状态及 transition_id。

workflow get-node

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

workflow update-node

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

---

MyWork 工作台域

mywork todo

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

需完整结果时，从 page_num=1 连续翻页直到空为止。

---

WorkHour 工时域

工时记录查询（workhour list-records）的参数表见 references/misc.md。

workhour list-schedule

获取指定人员在时间区间内的排期与工作量明细。

调用约束：每次最多 20 人（多人拆批次并行）；单次跨度 ≤ 3 个月（超出按月拆分）；所有批次完成后再汇总，未完整获取前不得输出结论。

---

UserGroup 人员域

团队相关命令（team list / team list-members）的参数表见 references/misc.md。

user search

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

user me

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

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

---

View 视图域

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

view get

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

---

Comment 评论域

评论列表查询（comment list）的参数表见 references/misc.md。

comment add

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

---

Deliverable 交付物域

单命令小域，参数表见 references/misc.md。

deliverable list

查看交付物详情及其根工作项 / 来源工作项。可按工作项 ID 列表过滤。

---

Resource 资源库

资源库（资源模板）管理。resource create 当前对应 MCP create_resource_work_item，用于创建资源实例；查看资源库的字段 / 角色配置用 resource meta-fields。详细参数表见 references/misc.md。

resource create

在已启用资源库的工作项类型下创建资源模板（资源实例）。创建前先调 resource meta-fields 取字段 / 角色配置。

语义边界：

• 创建资源实例：work_item_type_key 是资源库启用的工作项类型；template_id 是该类型下的流程模板 ID/名称；fields / roles 是新资源实例自身的字段和角色。
• 从资源实例创建普通工作项：不要把已有资源实例 ID 填到 work_item_type_key 或 template_id。必须以当前 resource create 的 inspect/schema 为准确认是否有源资源实例参数；若当前 schema 未暴露该参数，先向用户说明无法确认自动化参数，不要猜。

---

WBS 计划表

计划表（WBS）有 草稿（draft） 与 已发布实例（instance） 两套数据模型。常见编辑流程：wbs create-draft → 多次 wbs edit-draft → wbs publish-draft；放弃改动用 wbs reset-draft。详细参数表与 wbs edit-draft 的 operation 子类型见 references/wbs.md。

wbs list-draft-rows

在计划表草稿中按条件筛选行。常用筛选字段：wbs_name、wbs_parent_id、wbs_owner_in_charge、wbs_states_doing。详见 references/wbs.md。

wbs list-instance-rows

在已发布的线上计划表实例中按条件筛选行。参数同 wbs list-draft-rows。

wbs edit-draft

对计划表草稿执行一次原子编辑。一次调用只能传一个 operation_type，但该操作内部可通过 items / uuids 等数组承载单行或批量编辑；支持新增 / 删除 / 恢复 / 排序 / 改名 / 改负责人 / 改阶段 / 改排期 / 改估分 / 改实际工时等，结构见 references/wbs.md。

⚠️ 前置：草稿不存在时先调 wbs create-draft，再调 wbs edit-draft。判断方法：直接 wbs list-draft-rows 报"草稿不存在"类错误即视为缺失草稿。

wbs publish-draft

将编辑完成的草稿发布到线上。

⚠️ 全量发布前必须用固定话术二次确认："本人及协同者的全部编辑内容均会被发布，请确认是否全量发布？"；部分发布（传入 uuid_strings_list）无需二次确认。

---

其它低频域

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

• Chart 度量域 — chart get / chart list
• SubTask 子任务域 — subtask update（create/update/confirm/rollback）
• Relation 关系域 — relation list / relation meta-definitions
• WBS 计划表 · 辅助命令 — wbs create-draft / wbs reset-draft / wbs get-draft-progress / wbs list-element-templates（见 references/wbs.md）

---

字段值格式（field_value）

🚨 STRING 协议：field_value 协议层固定为字符串。标量（text/number/bool/option_id/userkey/毫秒）直接作字符串；数组、对象必须先 JSON.stringify 再传，直接传会报 need STRING type, but got: LIST / MAP。

例：multi-user 正确写法为 "[\"7509072868295085608\"]"，错误写法为 ["7509072868295085608"]。

更新角色时不用 fields，用 workitem update 的 role_operate 参数。

关联工作项字段（workitem_related_*）

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

---

常用场景速查

通用规范

请求处理流程

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

1. 参数提取：从自然语言中提取空间名、工作项类型、时间、人员、筛选条件；含 URL 时先调 url decode 解析，按 references/url-kinds.md 的 url_kind 分支决定进入哪个 SOP 或拒绝。禁止自己从 URL 截取路径段作参数。注意区分空间名与筛选维度（如「XX空间下YY业务线的缺陷」中 XX 才是空间名）。

2. 参数确认（禁止猜测）：用探测命令校验空间（project search）、类型（workitem meta-types）、人员（user search）。探测结果不唯一时必须展示并询问用户，禁止自行选择；缺失必填合并为一条消息询问。个人待办（mywork todo）可跳过；URL 经 url decode 拿到 simple_name 后仍需 project search 转权威 project_key（同名空间可能有多个无权限）。

3. 元数据收集（无需用户参与）：调用 workitem meta-fields 获取字段定义（需要特定字段用 field_keys，模糊查询用 field_query）；涉及角色时并行调 workitem meta-roles。关键字段识别：状态字段 type=_work_item_status（含「完成/关闭/终止」的值为完成态）、排期字段 type=schedule（MQL 用 __字段名_开始时间 / __字段名_结束时间）、优先级字段 key=priority。简单直调场景（仅需 project_key + work_item_id，如 comment add）可跳过本步。

4. 执行：调用目标命令，遵循 references/performance.md 的并行/翻页规则。

并行与大结果

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

错误处理

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

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

• 空间未找到（project search 连续 3 次失败）
• Permission Denied（当前用户对该空间无访问权限）

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

---

操作指南（SOP）

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

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

命令调用示例

---

空间域

project search

已知空间名/key：

meegle project search --project-key 空间名或key --page-num {{page_num}} --format json

列出当前用户可访问的空间（按最近访问排序，分页）：

meegle project search --project-key {{project_key}} --page-num 1 --format json

工作项域

workitem meta-types

meegle workitem meta-types --project-key 空间key --format json

workitem meta-fields

查询所有字段：

meegle 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

workitem meta-roles

meegle workitem meta-roles --page-num 1 --project-key 空间key --work-item-type story --role-keys '{{role_keys}}' --role-query '{{role_query}}' --format json

workitem query

查询空间中所有未冻结的需求：

meegle 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

继续查询无分组结果的第 2 页（无分组时 group_id 传 "1"，session_id 使用上一次查询返回值）：

meegle workitem query --project-key 空间key --session-id 上次返回的session_id --mql '' --group-pagination-list '[{"group_id":"1","page_num":2}]' --format json

继续查询某个分组的第 3 页（group_id 来自首查返回的 list[].group_infos[].group_id）：

meegle workitem query --project-key 空间key --session-id 上次返回的session_id --mql '' --group-pagination-list '[{"group_id":"分组ID","page_num":3}]' --format json

workitem get

meegle workitem get --work-item-id 工作项ID或名称 --fields '{{fields}}' --project-key 空间key --format json

只取拉群方式（group_type 逻辑字段，聚合自 group_id / chat_group）：

meegle workitem get --work-item-id 工作项ID --fields '["group_type"]' --project-key 空间key --format json

全量字段分页（fields=["_all"] 时按逻辑字段分页，page_size 默认 100，最大 200；下一页用上次响应的 next_page_token 传 page_token，token 形如字段 key 如 "business"）：

⚠️ meegle CLI 当前 --page-size / --page-token flag 会被序列化成字符串触发后端 need I64 type, but got: STRING；当前可用的写法是通过 --params 把整数传出去——

meegle workitem get --work-item-id 工作项ID --project-key 空间key --fields '["_all"]' --params '{"page_size":100}' --format json
meegle workitem get --work-item-id 工作项ID --project-key 空间key --fields '["_all"]' --params '{"page_size":100,"page_token":"<next_page_token>"}' --format json

workitem create

基础创建（仅标量字段）：

meegle workitem create --work-item-type story --fields '[{"field_key": "template", "field_value": "模板ID"}, {"field_key": "name", "field_value": "需求标题"}]' --project-key 空间key --work-item-id {{work_item_id}} --ignore-required {{ignore_required}} --ignore-role-calculate {{ignore_role_calculate}} --format json

创建缺陷 + 指定报告人（multi-user）+ 指定经办人（role_owners）——注意复合值必须 JSON.stringify：

meegle 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 --work-item-id {{work_item_id}} --ignore-required {{ignore_required}} --ignore-role-calculate {{ignore_role_calculate}} --format json

🚨 issue_reporter（multi-user 类型的内置角色字段）和 role_owners（统一角色入口）是两种可互换的写法：前者走 meta-create-fields 返回的字段 key；后者用 meta-roles 返回的 role_id（如 operator / reporter，不含 issue_ 前缀）。两者的 field_value 都必须是 stringified JSON 字符串。

通过资源工作项模板实例创建：

meegle workitem create --work-item-type story --fields '{{fields}}' --project-key 空间key --work-item-id 资源模板实例ID --ignore-required {{ignore_required}} --ignore-role-calculate {{ignore_role_calculate}} --format json

workitem update

更新普通字段：

meegle workitem update --work-item-id 工作项ID --project-key 空间key --role-operate '{{role_operate}}' --fields '[{"field_key": "priority", "field_value": "option_id"}]' --format json

更新 multi-user 字段（复合值 stringified）：

meegle 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

更新拉群方式（group_type 逻辑字段，统一替代旧 group_id / chat_group）——三种形态：

切到自动拉群（不带 group_id）：

meegle workitem update --work-item-id 工作项ID --project-key 空间key --role-operate '{{role_operate}}' --fields '[{"field_key":"group_type","field_value":"{"type":"auto"}"}]' --format json

绑定现有群（type=bind 必须带非空 group_id）：

meegle workitem update --work-item-id 工作项ID --project-key 空间key --role-operate '{{role_operate}}' --fields '[{"field_key":"group_type","field_value":"{"type":"bind","group_id":"oc_xxx"}"}]' --format json

关闭拉群：

meegle workitem update --work-item-id 工作项ID --project-key 空间key --role-operate '{{role_operate}}' --fields '[{"field_key":"group_type","field_value":"{"type":"disabled"}"}]' --format json

---

人员域

user search

meegle user search --user-keys '["张三", "李四"]' --project-key {{project_key}} --need-all-status {{need_all_status}} --format json

包含离职/停用等非在职用户：

meegle user search --user-keys '["张三"]' --project-key {{project_key}} --need-all-status true --format json

user me

meegle user me --format json

---

工作台域

mywork todo

查询我的待办：

meegle mywork todo --action todo --page-num 1 --asset-key {{asset_key}} --format json

---

工时域

workhour list-schedule

meegle 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

---

视图域

view get

meegle view get --view-id 视图ID --project-key 空间key --fields '{{fields}}' --page-num {{page_num}} --format json

---

工作流域

workflow get-node

meegle 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

workflow transition

完成节点（节点流）：

meegle workflow transition --work-item-id 工作项ID --node-ids '{{node_ids}}' --project-key 空间key --node-id 节点ID --action confirm --rollback-reason '{{rollback_reason}}' --format json

workflow transition-state

流转状态（状态流）：

meegle workflow transition-state --work-item-id 工作项ID --project-key 空间key --transition-id 流转ID --format json

workflow list-state-transitions

meegle workflow list-state-transitions --work-item-id 工作项ID --work-item-type story --user-key userkey --project-key 空间key --format json

---

评论域

comment add

meegle comment add --work-item-id 工作项ID --content '评论内容' --project-key {{project_key}} --format json

comment list

meegle comment list --work-item-id 工作项ID --project-key 空间key --page-num {{page_num}} --start-time {{start_time}} --end-time {{end_time}} --format json

---

关系域

relation meta-definitions

meegle relation meta-definitions --project-key 空间key --work-item-type {{work_item_type}} --relation-work-item-type {{relation_work_item_type}} --format json

relation list

meegle 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

---

子任务域

subtask update

meegle 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

附件域

附件上传/下载分两步：先调 attachment prepare-upload / attachment prepare-download 申请带签名的对象存储 URL，再与对象存储做一次或多次 HTTP 直连。Meegle CLI 内置 attachment +upload / attachment +download 一键封装，把两步合成一条命令；脚本里需要逐步控制时也可单独调上面的 prepare 命令。

attachment prepare-upload

申请上传签名。work_item_id 与 work_item_type 二选一必填：已有工作项传 work_item_id；"创建工作项时同步上传附件" 场景传 work_item_type，两者同传时 work_item_id 优先。

attachment prepare-download

申请下载签名。file_url 是其它命令（如 workitem get 的附件字段值、comment list 评论里的附件链接、富文本中的附件引用）回传的不透明引用，不要手工拼接。

attachment +upload

端到端上传：CLI 在本地把 attachment prepare-upload 与对象存储的签名 HTTP POST 串起来，返回 file_token 与文件元数据，可直接喂给 workitem create / workitem update / comment add 的附件字段。Meegle CLI 专用。

attachment +download

端到端下载：CLI 在本地把 attachment prepare-download 与对象存储的签名 HTTP GET 串起来，并用 .partial 临时文件 + 原子改名落盘，失败时不会留下半残文件。Meegle CLI 专用。

Auth Guard（所有业务命令前必须执行）

触发条件

• 主动登录：用户说"登录 Meegle"、"连接飞书项目"、"login meegle"等。
• 被动拦截：用户请求任何 Meegle 业务操作（查询待办、查工作项、创建任务等），优先执行 Auth Guard。
• URL 触发：用户发送了飞书项目/Meegle URL。处理流程：

1. 先调 url decode 拿到结构化字段（url_kind、host、simple_name、work_item_id 等）。禁止自己从 URL 截取路径段作参数。字段含义与 kind 分支见 url-kinds.md。 2. 保存 $host = response.host、$url_kind、$simple_name、$work_item_id。 3. 执行 Auth Guard（下面的 STEP 1 起）。 4. 登录成功后按 $url_kind 分支：

• workitem_detail → project search 得权威 $project_key，再 workitem get 查询详情
• workitem_homepage / view_* / unknown 等非详情页 → 按 url-kinds.md 的指引拒绝或追问
• 其他 kind → 参考 url-kinds.md 对应处理方式

按以下 STEP 顺序执行。每个 STEP 结尾的 GOTO 指明下一步，严格遵循跳转。

---

STEP 1 — 检查登录状态

meegle auth status --format json

返回值示例：

• 已登录：{ "authenticated": true, "host": "meegle.com", "source": "token_store", "expires_in_minutes": 42 }
• 未登录且有 host：{ "authenticated": false, "host": "meegle.com", "source": null, "expires_in_minutes": null }
• 未登录且无 host：{ "authenticated": false, "host": null, "source": null, "expires_in_minutes": null }

解析返回值，保存变量：

• $authenticated = response.authenticated
• $host = response.host

URL 触发时的 host 覆盖：如果用户发送了飞书项目/Meegle URL 触发本流程，且 $host 为 null，则使用上一步 url decode 返回的 host 字段作为 $host。

跳转：

• IF $authenticated == true → GOTO STEP DONE
• IF $host != null → GOTO STEP 2
• IF $host == null → GOTO STEP HOST

---

STEP HOST — 选择站点

ASK user（等待用户回复）：

你要连接哪个站点？

1) 飞书项目 (project.feishu.cn)

2) Meegle (meegle.com)

3) 自定义域名（请直接输入域名）

SAVE $host from user reply → GOTO STEP 2

---

STEP 2 — OAuth 登录

meegle auth login --host $host

命令会自动打开浏览器完成 OAuth 授权。等待命令执行完毕。

跳转：

• IF 命令成功（exit code 0） → GOTO STEP OK
• IF 命令失败 → SEND "OAuth 登录失败，请检查错误信息或在终端中手动执行 meegle auth login"，STOP

---

STEP OK — 通知登录成功

SEND to user: "登录成功！"

⚠️ 此消息必须单独发送，不要与后续业务查询结果合并到同一条回复中。用户需要第一时间看到授权状态变化。

→ GOTO STEP DONE

---

STEP DONE — 执行业务命令

Auth 已通过，执行用户请求的操作。

错误处理

• 如果 bash 返回 command not found 或 npx 不可用，提示用户安装 Node.js 18+。
• 如果 OAuth 登录失败，提示用户在终端中手动执行 meegle auth login。

CLI 使用指南

前置条件

运行环境需要 Node.js 18+。所有命令通过 meegle 执行。

命令结构

meegle <resource> <method> [flags] --format json

命令采用 resource method 两级结构。所有输出推荐使用 --format json 获取结构化数据。

全局 Flag

参数传递

几种方式，优先级从高到低：

1. Flag 模式（推荐）：--project-key PROJ --work-item-type story 2. --fields 模式（写工作项字段，可重复）：--fields '{"field_key":"name","field_value":"任务标题"}' --fields '{"field_key":"priority","field_value":"1"}'；field_value 支持任意 JSON 值（数组/对象原样传） 3. --params 模式（完整 JSON 兜底）：--params '{"fields":[{"field_key":"name","field_value":"任务标题"}]}' 4. --set 模式（仅顶层参数快捷写法，不支持 fields[]）：--set page_num=1 等价于 --page-num 1，支持 dot-path 嵌套；不要用它写工作项字段

Flag 覆盖 --params；--set 只影响顶层参数，不会写到 fields[]。

命令发现

CLI 的命令和参数会随版本更新。遇到不确定的命令或参数时，使用 inspect 获取最新信息：

meegle inspect                    # 列出所有可用命令
meegle inspect workitem.create    # 查看具体命令的参数 schema

命令清单本地缓存 24 小时。如果 inspect 输出的参数与服务端实际不符，或服务端有新命令但 CLI 报 unknown command，加上 --refresh 强制从服务端重新拉取最新清单：

```bash

meegle --refresh inspect workitem.create

```

输出处理

• 始终使用 --format json 获取结构化输出，方便解析
• 使用 --select 精简返回字段，如 --select id,name,current_nodes.name
• 命令返回错误时，JSON 中包含 error 和 message 字段

错误处理详细规则

SKILL.md 主文件已经收录错误处理总则与熔断条件，本文件提供完整的自愈规则与错误速查表。

自愈规则（按报错特征匹配修复后重试）

错误速查

字段值进阶：关联工作项名称 → ID 转换

当用户为 workitem_related_select / workitem_related_multi_select 字段提供的是工作项名称而非 ID 时，按以下流程转换后再写入。

1. 获取关联字段的目标约束：从 workitem meta-fields 返回的该字段配置中，提取其绑定的目标空间（project_key）和目标工作项类型（work_item_type_key）。若配置未限定（可关联任意类型），默认在当前空间内搜索。 2. 按名称搜索目标工作项：调用 workitem query，在目标空间和类型范围内按名称匹配。示例 MQL：

   SELECT `工作项ID`, `名称` FROM `目标空间`.`目标类型` WHERE `名称` = '用户给的名称'

精确匹配无结果时改用 like '%关键词%' 模糊搜索。 3. 消歧处理：

• 唯一结果 → 直接取工作项 ID
• 多个结果 → 列出所有匹配项（ID + 名称 + 状态）让用户确认
• 零结果 → 提示用户"未找到名为 XXX 的工作项，请确认名称或直接提供 ID"

4. 写入格式：

• workitem_related_select → 传入单个 ID 字符串
• workitem_related_multi_select → 传入 stringified ID 数组
• 不同空间可能要求字符串或数字格式，遇类型校验失败立刻切换格式重试

5. 循环引用保护：写入前必须排查当前工作项自身 ID，禁止将自身 ID 写入关联字段，否则会触发 exists loop（循环引用）报错。

其它低频命令

低频/单命令小域的参数表汇总。涵盖团队、图表、子任务、关系、评论查询、工时记录、交付物、资源库、WBS 辅助命令。

---

团队

team list

查看空间下的团队列表。

team list-members

查看团队成员列表。

---

度量图表

chart get

查看图表详情。

chart list

查看视图下的图表列表。

---

子任务

subtask update

创建/修改/完成/回滚子任务。

---

关系

relation list

查看关联的工作项列表。

relation meta-definitions

查看空间下的关联关系定义。

---

评论查询

comment list

查看评论列表。添加评论用 comment add（见 SKILL.md 主文件）。

---

工时记录

workhour list-records

查看工作项的工时登记记录。团队排期用 workhour list-schedule（见 SKILL.md 主文件）。

---

交付物

deliverable list

查看交付物详情及其所属根工作项 / 来源工作项。

---

资源库

resource create

在已启用资源库的工作项类型下创建资源模板（资源实例）。先调 resource meta-fields 取字段 / 角色配置。

创建资源实例 vs 从资源实例创建普通工作项：

• 创建资源实例：使用 resource create；work_item_type_key 表示资源库启用的工作项类型，template_id 表示流程模板，fields / roles 描述新资源实例自身。
• 从资源实例创建普通工作项：这是“基于已有资源实例派生/创建业务工作项”的语义，参数通常需要源资源实例标识。当前命令参数必须以 inspect / schema 为准；若没有显式源资源实例参数，不要把源资源实例 ID 塞进 work_item_type_key、template_id 或普通字段里猜测调用。

resource meta-fields

查看资源库的字段 / 角色配置。

---

WBS 辅助命令

计划表（WBS）的核心查询 / 编辑 / 发布命令见 wbs.md。本节仅收 4 个辅助命令：草稿生命周期管理（create-draft / reset-draft）、异步操作进度查询（get-draft-progress）、流程资源库元素查询（list-element-templates）。

wbs create-draft

为指定工作项实例创建新的计划表草稿。当需要编辑计划表但当前不存在草稿时，先调本工具创建草稿，再配合 wbs edit-draft 进行编辑。

wbs reset-draft

将草稿重置为线上实例状态，放弃所有未发布的修改。不传 uuids 时全量重置。

wbs get-draft-progress

查询计划表草稿异步操作（create / edit / publish / reset）的执行进度。

wbs list-element-templates

列出流程资源库中的资源节点（node）或资源任务（task）模板。

MQL 语法规范参考

重要：`workitem query` 的 `mql` 参数必须是完整的 SQL 查询语句

- 必须包含 SELECT 和 FROM 子句

- 不接受 JSON 对象、简写条件或不完整片段

- 正确: \SELECT \工作项ID\, \名称\ FROM \project_key\.\需求\ WHERE \状态\ = \进行中\\

- 错误: {"status": "进行中"} / status = '进行中' / WHERE status = '进行中'

基础语法

SELECT fieldList                            -- 指定查询的字段列表
FROM `空间名`.`工作项类型名`                   -- 指定数据来源
WHERE conditionExpression                    -- 查询条件（可选）
[ORDER BY fieldOrderByList [{ASC|DESC}]]     -- 排序（可选）
[LIMIT [offset,] row_count]                  -- 分页（可选）

标识符规则：

• *不支持 `SELECT `，必须显式指定字段**
• 所有字段名和表名必须使用反引号包裹，如 ` 工作项ID 、 空间名.需求 ，**带 target 修饰符时必须包裹整个字段**： name<target:all> `
• SELECT/FROM/WHERE/ORDER BY 中既可使用 key 也可使用名称。优先使用 key，从 list_workitem_field_config 返回值中获取：系统字段 key 为单词（如 priority、status），自定义字段 key 为 field_x23bd 格式，工作项类型 key 如 story、issue。名称是用户自定义的 UGC 内容（语言不定），仅作为找不到 key 时的兜底
• 字符串用单引号：'value'
• 数组用 JSON 格式：'["a","b"]'
• 枚举值优先用 label（如 '通过'），不要用 id
• 禁止 count()、SUM()、GROUP BY。总数从返回结果的 count 字段读取

---

数据类型

---

常用运算符

BETWEEN ... AND ...

时间区间查询，仅适用于 date 字段类型和 precise_date 字段类型

WHERE `创建时间` BETWEEN '2025-01-01' AND '2025-10-01'

IN

集合查询，适用于 varchar 数据类型

-- 查询名称为 "测试1" 或 "测试2" 或 "测试3"
WHERE `名称` IN ('测试1', '测试2', '测试3')

LIKE / NOT LIKE

模糊匹配，% 匹配任意字符：

WHERE `缺陷名` LIKE '%性能问题%'
WHERE `缺陷名` NOT LIKE '%后端性能问题%'

---

常用函数

数组函数

示例：

-- 当前负责人包含张三
array_contains(`当前负责人`, '张三')

-- 标签数组与给定数组有交集
array_intersect(`标签`, '["标签A","标签B"]') 

-- 处理人中是否有张三
any_match(`处理人`, x -> x = '张三')

-- 处理人中是否有至少一个开放平台团队的用户
any_match(`处理人`, x -> x in (team(true, '开放平台团队')))

-- 优先级包含 P0 或 P1
array_contains(`优先级`, 'P0', 'P1')

-- 当前负责人包含当前登录用户或李四
any_match(`当前负责人`, x -> x in (current_login_user(), '李四'))

-- 所有处理人都在后端团队中
all_match(`处理人`, usr -> usr in team(true, '后端开发团队'))

-- 标签数组为空
array_cardinality(`标签`) = 0

时间函数

支持的函数：RELATIVE_DATETIME_EQ、RELATIVE_DATETIME_GT、RELATIVE_DATETIME_GE、RELATIVE_DATETIME_LT、RELATIVE_DATETIME_LE、RELATIVE_DATETIME_BETWEEN

函数签名：RELATIVE_DATETIME_*(col_name, 'date_para', ['days'])

date_para 枚举值：

days 参数：仅 today、future、past 支持。格式为 'Nd' 或 '-Nd'。

示例：

-- 今天创建的工作项
RELATIVE_DATETIME_EQ(`创建时间`, 'today')

-- 3天内到期的工作项
RELATIVE_DATETIME_LE(`截止时间`, 'future', '3d')

-- 上周创建的需求
RELATIVE_DATETIME_BETWEEN(`创建时间`, 'last_week')

-- 本月更新的任务
RELATIVE_DATETIME_BETWEEN(`更新时间`, 'current_month')

-- 今天后 3 天
RELATIVE_DATETIME_EQ(`创建时间`, 'today', '3d')

-- 今天前 3 天
RELATIVE_DATETIME_EQ(`创建时间`, 'today', '-3d')

-- 排期开始时间在过去 30 天内
RELATIVE_DATETIME_BETWEEN(`__需求排期_开始时间`, 'past', '30d')

人员与角色函数

示例：

-- 当前负责人是当前登录用户
array_contains(`当前负责人`, current_login_user())

-- 返回当前工作项的参与人 userkey 数组是否包含张三
array_contains(participate_persons(), '张三')

-- 返回所有参与当前工作项的人员（全部参与人员/全部人员）userkey 数组是否包含李四
array_contains(all_participate_persons(), '李四')

-- 指派给产品团队（含管理者）
any_match(`当前负责人`, x -> x in team(true, '产品团队'))

-- 查询有 RD 和 QA 角色参与的工作项
array_contains(participate_roles(), 'RD', 'QA')

节点函数

• all_nodes_name()：返回所有流程节点名称数组

  -- 流程节点包含"开始"
  WHERE array_contains(all_nodes_name(), '开始')

• in_progress_nodes_name()：返回当前进行中的节点名称数组

  -- 进行中节点不为空
  WHERE in_progress_nodes_name() is not null

• risk_label()：返回节点延期状态标识数组（如 ["延期/开始","今日到期/结束"]）

  -- 开始节点已延期且结束节点今日到期
  WHERE risk_label() = '["延期/开始","今日到期/结束"]'

• get_node_attribute(node, attribute)：获取指定节点的属性值。node 可为节点名、__ALL（全部节点）、__BELONGING（所属节点，即当前工作项所在的节点）。语义涉及"所属节点"时，必须使用 `__BELONGING`

可用属性：排期、估分、节点时间、节点完成结论、节点完成意见、负责人、当前负责人、状态

排期/节点时间子字段：

• 节点排期：get_node_attribute('节点名','__排期_开始时间')、get_node_attribute('节点名','__排期_结束时间')
• 节点时间：get_node_attribute('节点名','__节点时间_开始时间')、get_node_attribute('节点名','__节点时间_结束时间')

  -- 开始节点排期在过去 30 天内
  WHERE RELATIVE_DATETIME_BETWEEN(get_node_attribute('开始','__排期_开始时间'), 'past','30d')
  -- 全部节点估分大于 10
  WHERE get_node_attribute('__ALL','估分') > 10
  -- 调研节点负责人等于小李（等于语法也适用于节点属性）
  WHERE get_node_attribute('调研','负责人') = '小李'
  -- 所属节点当前负责人（必须使用 __BELONGING）
  WHERE any_match(get_node_attribute('__BELONGING','当前负责人'), x -> x in ('张三'))
  -- 所属节点状态为进行中
  WHERE any_match(get_node_attribute('__BELONGING','状态'), x -> x in ('进行中'))
  -- 所属节点排期在未来 7 天内
  WHERE RELATIVE_DATETIME_BETWEEN(get_node_attribute('__BELONGING','排期'), 'future','7d')

关系函数

• relation(relation_name)：通过关系名称获取关系，关系名称从 list_workitem_relations 获取

  WHERE any_relation_match(relation('父-子'), x -> x.`名称` like '%需求%')

• parent_work_item(relation(relation_name))：获取父工作项 ID

  WHERE parent_work_item(relation('父-子')) = '12345'

• relation_field_chain(relation1 [, relation2 [, relation3]])：关联工作项链式查询（最多 3 跳）。一级关系使用 relation_field_chain('关系1') 或 relation_field_chain('字段1') 即可。子任务的父工作项必须写作 `'__父工作项'`（双下划线前缀）

  -- 一级关系
  WHERE any_relation_match(relation_field_chain('关联需求'), x -> x.`优先级` = 'P0')
  -- 多级关系：子任务→父工作项→软件
  WHERE any_relation_match(relation_field_chain('__父工作项','需求关联软件'), x -> x.`名称` = '某软件')

• association()：跨空间关联实例 ID

  WHERE association() = '实例ID'

• linked_work_item()：子任务特有，获取来源控件（父工作项 ID）

  WHERE linked_work_item() = '12345'

关系判断函数

用于对关系对端进行条件判断：

• any_relation_match(relation, x -> expr)：存在一个/一组对端满足条件
• all_relation_match(relation, x -> expr)：每一个对端都满足条件
• none_relation_match(relation, x -> expr)：每一个对端都不满足条件
• not all_relation_match(relation, x -> expr)：存在一个/一组对端不满足条件

嵌套筛选规则：对关系对端的属性进行进一步筛选时，使用关系函数（如 relation_field_chain）获取关系后，外层必须嵌套关系判断函数。

-- 示例：子任务其父工作项的当前负责人全部不属于小李
WHERE all_relation_match(relation_field_chain('__父工作项'), x -> none_match(x.`当前负责人<target:all>`, y -> y in ('小李')))

-- 示例：多级关系 + 节点属性 — 子任务关联的任务所关联的需求的"开始"节点负责人包含小李
WHERE all_relation_match(relation_field_chain('需求-二级工作项关联','二级工作项-子任务关联'), x -> any_match(get_node_attribute('开始','负责人'), y -> y in ('小李')))

关系参数三种形式：

1. 关联字段：` 字段key — 如 any_relation_match(关联需求, x -> x.优先级 = 'P0') 2. **relation 函数**：relation('关系名') — 如 any_relation_match(relation('父-子'), x -> x.名称 like '%需求%') 3. **relation_field_chain 函数**：relation_field_chain('关系1','关系2')` — 用于多级关系链

多级关系名处理规则：默认按照用户的输入直接进行查询。如果找不到匹配的关系，可让用户二次输入确认。不主动猜测或转换用户输入的关系名。

子任务 `__父工作项` 规则：

• 子任务的父工作项关系名固定为 '__父工作项'（双下划线前缀），不是 '父工作项'
• 常见报错：object[父工作项-关联XXX]: relation chain err:relationNode not found, label:父工作项
• 原因：父工作项写法缺少双下划线前缀
• 修复：仅将 `'父工作项'` 改为 `'__父工作项'`，其他部分保持不变
• 修正示例：relation_field_chain('__父工作项','关联XXX')

跨空间/多端字段引用：`x.字段名<target:空间key::工作项类型key> 或 x.字段名<target:all> `（通用字段）

关联工作项通用字段（查询关联工作项信息时，以下属性必须使用 <target:all>）：标题、创建人、创建时间、业务线、优先级、当前负责人、所属工作项、所属空间、工作项ID、工作项类型、状态

-- 多选关联字段：对端优先级为 P0（使用 <target:all>）
WHERE any_relation_match(`多选关联字段`, x -> x.`优先级<target:all>` = 'P0')
-- 多选关联字段全部满足条件（使用指定空间和类型）
WHERE all_relation_match(`多选关联字段`, x -> x.`描述<target:空间key::类型key>` like '%123%')
-- 关联工作项创建时间（通用字段必须用 <target:all>）
WHERE any_relation_match(relation_field_chain('__父工作项'), x -> x.`创建时间<target:all>` >= '2026-03-24')
-- 多级关系结合节点属性（__父工作项要指明 target 才可以串起来关系）
WHERE all_relation_match(relation_field_chain('__父工作项<target:681b228d7401707f87414afa::story>','关联字段2'), x -> any_match(get_node_attribute('开始','负责人'), y -> y in ('小李')))
-- 关联工作项的节点属性：XX 关联的实例，其 AA 节点负责人不包含小李
WHERE any_relation_match(`XX关联`, x -> not array_contains(get_node_attribute('AA', '负责人'), '小李'))

状态函数

• status_time(status_name)：返回进入指定状态的时间

  -- 状态时间在区间内
  WHERE status_time('开始') between '2025-03-10' and '2025-04-10'

• status_time('\_\_状态名\_\_开始时间') / status_time('\_\_状态名\_\_结束时间')：获取状态的开始/结束时间

  -- 状态累计持续时间
  WHERE status_time('__结束状态__结束时间') - status_time('__开始状态__开始时间') > 86400

---

名称消歧（<id:xxxx> 语法）

当人名、团队名等存在重复时，MQL 会因无法唯一标识而报错。此时使用 <id:xxxx> 语法指定唯一 ID：

-- 人名消歧：张三对应多人时，指定 userkey
WHERE `创建人` = '张三<id:1234>'

-- 团队名消歧：指定团队唯一 key
WHERE any_match(`负责人`, x -> x in (team(true, '开放平台团队<id:3455>')))

遇到 MQL 返回"名称重复"类错误时，需获取对应的唯一 ID 后使用此语法重试。

枚举值和 userkey 也可使用 `<id:xxx>` 格式：

-- 枚举值指定 option id
WHERE x.`priority` = '<id:option_2>'
-- userkey 指定
WHERE `负责人` = '<id:7290442683267497985>'

---

特殊字段查询规则

日期区间类型字段

日期区间类型（如"需求排期"）不能直接查询，必须拆分为子字段，格式：` __排期名_开始时间 / __排期名_结束时间 `

-- 正确：使用子字段
WHERE `__开发周期_开始时间` > '2025-01-01' AND `__开发周期_结束时间` < '2025-01-31'
WHERE RELATIVE_DATETIME_BETWEEN(`__需求排期_开始时间`, 'past', '30d')

-- 错误：直接查询日期区间字段
WHERE RELATIVE_DATETIME_BETWEEN(`需求排期`, 'past', '30d')

角色字段

角色可作为 MQL 属性查询，使用 __角色名 格式（加 __ 前缀以区分普通自定义字段）：

-- 查询 RD 包含某人的工作项
WHERE array_contains(`__RD`, '张三')

-- 查询多个角色条件
WHERE array_contains(`__RD`, '张三') AND array_contains(`__PM`, '李四')

---

关键词映射

当用户输入中包含以下关键词时，优先匹配对应的函数或语法。

控件关键词 → 函数映射

当用户输入中包含「控件」二字时，务必对照下表选择正确函数。

操作符关键词 → 语法映射

关系语境关键词 → 函数映射

---

完整查询示例

以下示例展示语法模式。<尖括号> 为占位符，实际值需从对应工具获取：字段 key 从 list_workitem_field_config，工作项类型从 list_workitem_types，状态/优先级等选项值从字段配置的 options 中读取。

示例 1：数组包含 + 当前用户

SELECT <所需字段列表>
FROM `空间名`.`<工作项类型>`
WHERE array_contains(`<数组字段>`, '<匹配值>')
  AND array_contains(all_participate_persons(), current_login_user())

示例 2：相对时间查询

SELECT <所需字段列表>
FROM `空间名`.`<工作项类型>`
WHERE RELATIVE_DATETIME_BETWEEN(`<日期字段>`, 'past', '<天数>d')

示例 3：逾期未完成（排期子字段 + 状态过滤）

-- 排期子字段格式：`__<排期名>_开始时间` / `__<排期名>_结束时间`，具体名称从 list_workitem_field_config 确认
SELECT <所需字段列表>
FROM `空间名`.`<工作项类型>`
WHERE RELATIVE_DATETIME_LT(`__<排期名>_结束时间`, 'today')
  AND `status` != '<已完成状态值>'

示例 4：团队角色匹配

SELECT <所需字段列表>
FROM `空间名`.`<工作项类型>`
WHERE any_match(`__<角色名>`, x -> x in (team(true, '<团队名>')))

示例 5：等值条件 + 排序分页

SELECT <所需字段列表>
FROM `空间名`.`<工作项类型>`
WHERE `<字段>` = current_login_user()
  AND `<字段>` = '<条件值>'
ORDER BY `<排序字段>` DESC
LIMIT <按需设置>

示例 6：模糊匹配 + 多条件组合

SELECT <所需字段列表>
FROM `空间名`.`<工作项类型>`
WHERE `name` LIKE '%<关键词>%'
  AND array_contains(`<数组字段>`, '<匹配值>')
  AND `<字段>` = current_login_user()
ORDER BY `<排序字段>` ASC
LIMIT <按需设置>

示例 8：节点属性查询（所属节点 + 延期标识）

-- 所属节点当前负责人是张三且进行中
SELECT `工作项ID`, `名称`, `状态`
FROM `project_key`.`需求`
WHERE any_match(get_node_attribute('__BELONGING','当前负责人'), x -> x in ('张三'))
  AND any_match(get_node_attribute('__BELONGING','状态'), x -> x in ('进行中'))

-- 开始节点已延期
SELECT `工作项ID`, `名称`
FROM `project_key`.`需求`
WHERE risk_label() = '["延期/开始"]'

示例 9：关系查询（关系链 + 跨空间字段）

-- 子任务的父工作项名称包含"登录"
SELECT `工作项ID`, `名称`
FROM `project_key`.`子任务`
WHERE any_relation_match(relation_field_chain('__父工作项'), x -> x.`标题<target:all>` like '%登录%')

-- 多级关系：子任务→父工作项→关联软件，软件名称等于某值
SELECT `工作项ID`, `名称`
FROM `project_key`.`子任务`
WHERE any_relation_match(relation_field_chain('__父工作项','需求关联软件'), x -> x.`名称` = '某软件')

示例 10：状态时间查询

-- "开始"状态时间在 2025-03-10 至 2025-04-10 之间
SELECT `工作项ID`, `名称`, `状态`
FROM `project_key`.`需求`
WHERE status_time('开始') between '2025-03-10' and '2025-04-10'

示例 11：节点负责人 + 人员综合查询

-- 开始节点负责人包含某人
SELECT `工作项ID`, `名称`
FROM `project_key`.`需求`
WHERE array_contains(get_node_attribute('开始','负责人'), '李应凡')

-- 处理人属于某团队
SELECT `工作项ID`, `名称`, `处理人`
FROM `project_key`.`缺陷`
WHERE any_match(`处理人`, x -> x in (team(true, '开放平台团队')))

性能与并发调用指南

本文件收录减少延迟的工程性规则。核心协议（字段格式、错误自愈）仍在 SKILL.md 主文件中。

并行调用

无依赖的命令调用应并行发起，有依赖则必须串行。

必须串行（前者输出是后者输入）：

• project search → workitem meta-fields → workitem query
• workitem get → workflow transition / workitem update
• workitem meta-fields → workitem create

可并行：

• workitem meta-fields 和 workitem meta-roles（同类型）
• 多种工作项类型的 workitem meta-fields（如 story + issue）
• 各条件的 count 查询、多人排期分批查询

大结果处理

• 分批查询：workhour list-schedule 多人时拆成每批 ≤ 20 人并行
• 精简 SELECT：只选必要字段，避免富文本等大体积字段
• 按需翻页：先读首页获取总数，按需翻页

富文本编辑器 Markdown 格式规范

概述

富文本编辑器使用基于 GFM（GitHub Flavored Markdown） 的扩展 Markdown 格式。对于标准 Markdown 无法表达的功能，通过 HTML 注释和标签进行扩展。该格式可转换为 DSL、Delta 和 doc_html。

核心原则： 标准 GFM + HTML 注释承载元数据 + <span>/<u> 标签补充样式能力。

速查表

扩展语法详解

对齐方式（区域式）

用 start/end 注释对包裹一个或多个段落，标签必须独占一行：

<!-- center:start -->
这段文字居中显示。

这段也是居中的。
<!-- center:end -->

<!-- right:start -->
右对齐内容。
<!-- right:end -->

支持的值：center（居中）、right（右对齐）、justify（两端对齐）。左对齐为默认值，无需标记。

@提及（带元数据）

为了在转换过程中保留用户身份信息，使用元数据格式。@名字 和注释之间不能有空格：

@张三<!-- mention:{"id":"lark_user_id_7361251974161006596","cn_name":"张三","en_name":"Zhang San","email":"zhangsan@example.com","blockType":"AT_USER_BLOCK"} -->

注释中必填的 JSON 字段：

可选字段：blockId（UUID v4）、type（0 = 用户）、avatar_url。

同一行多个提及（之间不加空格）：

@张三<!-- mention:{"id":"id_1","cn_name":"张三","en_name":"Zhang San","email":"zhangsan@example.com","blockType":"AT_USER_BLOCK"} -->@李四<!-- mention:{"id":"id_2","cn_name":"李四","en_name":"Li Si","email":"lisi@example.com","blockType":"AT_USER_BLOCK"} -->

如果没有元数据，纯 @名字 也可接受，但无法在格式转换中完整还原。

图片

在url后紧跟<!-- 图片uuid -->（无空格）：

图片uuid 是与图片平台约定的唯一凭证。

`![描述](https://example.com/page/***)<!-- *****-*****-**** -->`

链接预览

在链接后紧跟 <!-- linkPreview -->（无空格）：

[https://example.com/page](https://example.com/page)<!-- linkPreview -->

下划线

标准 Markdown 不支持下划线，使用 HTML <u> 标签：

<u>带下划线的文本</u>

可与其他格式嵌套：

*<u>斜体加下划线</u>*
**<u>加粗加下划线</u>**

Span 样式

字体颜色、背景颜色、字体大小使用 <span> 的 style 属性。颜色必须用 `rgb(R, G, B)` 格式（不支持 hex 和颜色名）：

<span style="color: rgb(245, 74, 69)">红色文字</span>
<span style="background-color: rgb(53, 189, 75)">绿色背景</span>
<span style="font-size: 18px">大号文字</span>

表情短代码

使用 :CODE: 格式。键名大小写敏感，解析时会归一化到 lark 规范形式：

: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: 

解析器会归一化大小写（:smile: → :SMILE:，:beamingface: → :BeamingFace:），但建议直接使用规范写法。

列表 — 4 空格缩进

嵌套列表使用 4 个空格（不是 2 个）缩进：

1. 第一级有序
    1. 第二级（4 空格）
        1. 第三级（8 空格）
    - 混合：有序中嵌套无序（4 空格）
- 第一级无序
    - 第二级
        - 第三级
    1. 混合：无序中嵌套有序

任务列表：

- [ ] 未完成任务
- [x] 已完成任务
    - [ ] 嵌套未完成
    - [x] 嵌套已完成

引用块

支持嵌套和内部块级内容：

> 带 **加粗** 和 *斜体* 的引用
> 1. 引用内有序列表
> 2. 第二项
>     1. 引用内嵌套列表
> - 引用内无序列表

代码块

使用围栏式代码块，开头标注语言：

````markdown

function add(a: number, b: number): number {
  return a + b;
}

func add(a, b int) int {
    return a + b
}

````

GFM 表格（简单内容）

表格内仅包含行内内容（文本、加粗、链接等）时使用：

| 表头1 | 表头2 | 表头3 |
|-------|-------|-------|
| 单元格1 | **加粗** | [链接](url) |
| 单元格3 | 单元格4 | 单元格5 |

HTML 表格（单元格内含富内容）

当表格单元格需要块级元素（标题、列表、代码块、对齐、图片）时，使用 HTML <table> 语法。`<td>` 后和 `</td>` 前必须留空行，这样内部的 Markdown 才能被正确解析：

<table>
<tr>
<td>

# 单元格内标题

**加粗段落**

</td>
<td>

1. 有序列表
2. 在单元格中
    - 嵌套项

</td>
<td>

<!-- center:start -->
单元格内居中
<!-- center:end -->

</td>
</tr>
<tr>
<td>

// 单元格内代码块 const x = 1;

</td>
<td>

> 单元格内引用块

</td>
<td>

<span style="color: rgb(245, 74, 69)">单元格内彩色文字</span>

</td>
</tr>
</table>

空单元格：<td></td>

格式组合

行内样式可以嵌套使用：

**~~加粗删除线~~**
*<u>斜体下划线</u>*
[**加粗链接**](https://example.com)
<span style="color: rgb(245, 74, 69)">**红色加粗**</span>

段落分隔

每个块级元素（段落、标题、列表组、表格、代码块、引用块）之间用空行分隔：

# 标题

第一段正文。

第二段正文。

- 列表项 1
- 列表项 2

列表后面的段落。

常见错误

完整示例

# 项目进展

## 状态

<!-- center:start -->
**Alpha 项目 — 迭代评审**
<!-- center:end -->

本迭代完成了以下工作：

1. 用户认证
    1. 登录流程
    2. 密码重置
2. 仪表盘改版
    - 新布局
    - 性能优化

### 关键指标

| 指标 | 改版前 | 改版后 |
|------|--------|--------|
| 加载耗时 | 3.2s | **1.1s** |
| 错误率 | 2.4% | <span style="color: rgb(53, 189, 75)">0.3%</span> |

### 代码变更

export function authenticate(token: string): boolean { return validateJWT(token); }

> 注意：部署前需要更新 <u>环境配置</u>。

- [x] 代码评审已完成
- [x] 测试通过
- [ ] 部署到预发环境

负责人：@张三<!-- mention:{"id":"lark_user_id_001","cn_name":"张三","en_name":"Zhang San","email":"zhangsan@example.com","blockType":"AT_USER_BLOCK"} -->@李四<!-- mention:{"id":"lark_user_id_002","cn_name":"李四","en_name":"Li Si","email":"lisi@example.com","blockType":"AT_USER_BLOCK"} -->

参考文档：[迭代看板](https://example.com/sprint/42)<!-- linkPreview -->

:DONE: :DarkThumbsup:

创建工作项

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../SKILL.md，其中包含前置检查、授权流程、命令参数参考、字段值格式、通用规范和错误处理。

本技能用于在飞书项目中创建工作项（需求、任务、缺陷等），全程自动化执行，无需用户二次确认。

---

执行流程

STEP 1 — 提取意图

从用户输入中提取：

• 空间名：哪个项目空间
• 工作项类型：需求 / 任务 / 缺陷 / 其他
• 字段值：标题、优先级、负责人、描述等
• URL（如有）：先调 url decode 解析。url_kind 非 workitem_create / workitem_detail 时按 url-kinds.md 拒绝或追问；命中则用返回的 simple_name 取代空间名探测，work_item_type 取代类型探测。禁止自己从 URL 截取路径段作参数。

STEP 2 — 确认空间和类型

1. 用 project search 验证空间 → 获取 project_key 2. 用 workitem meta-types 获取类型列表 → 确认 work_item_type

唯一匹配则直接用，多个匹配则展示列表让用户选，无匹配则问用户。禁止猜测。

资源工作项模板创建：如果用户明确表示“通过资源库模板/资源工作项创建”，或 URL 解析得到资源工作项模板实例 ID，则将该 ID 作为 --work-item-id 传给 workitem create；此时按工具约束，--work-item-id 是必填的资源模板实例 ID。

STEP 3 — 收集元数据（并行）

同时发起以下调用：

如用户提到了人名，并行调用 user search 转换为 userkey。

默认只查询在职用户。只有当用户明确要求包含离职、停用等非在职人员，或在职结果为空且用户要求继续查找时，才给 user search 传 --need-all-status=true。

STEP 4 — 自动匹配模板

根据 STEP 3 获取的模板枚举值：

• 只有一个模板 → 自动选择
• 多个模板 → 根据用户描述中的关键词匹配最接近的模板名，选不出来时展示列表让用户选
• 用户明确指定了模板名 → 精确匹配

STEP 5 — 自动补全必填项与转换字段值

1. 自动补全必填项

严格对比 workitem meta-create-fields 返回的必填字段与用户已给定的字段。对于缺失的必填项（尤其是空间自定义的特殊必填项），自动生成合理的默认值：

• 枚举：默认取第一项
• 文本：填"自动生成"
• 布尔：填 true

2. 转换字段值

将用户给的自然语言值及自动生成的默认值转换成 API 需要的格式：

格式速查（完整格式见主文档 SKILL.md「字段值格式」）：

🚨 关键约定：field_value 协议层是 STRING。标量（text/user/option_id/timestamp）直接传字符串；数组、对象必须先 JSON.stringify 成字符串，否则会报 need STRING type, but got: LIST。

角色设置（创建时）：通过 fields 中的 role_owners 字段，值为 stringified 对象数组：

{"field_key":"role_owners","field_value":"[{\"role\":\"RD\",\"owners\":[\"userkey1\"]}]"}

角色补充：创建时除了能在 fields 数组内处理极少部分内置的 role_owners 字段外，针对其他自定义角色（如 PO、PM、Tech Lead 等），请在创建后用 workitem update 的 role_operate 参数追加写入。

STEP 6 — 创建

meegle workitem create --work-item-type 类型key --fields '[{"field_key":"template","field_value":"模板ID"},{"field_key":"name","field_value":"标题"}]' --project-key 空间key --work-item-id {{work_item_id}} --ignore-required {{ignore_required}} --ignore-role-calculate {{ignore_role_calculate}} --format json

仅在用户明确要求跳过创建校验，或业务流程已确认由后端/后续步骤补齐时，才使用 --ignore-required / --ignore-role-calculate；默认不要主动开启。

🚨 批量创建：当用户要求批量创建多个工作项时，必须串行调用（逐个请求），禁止高并发，以免触发平台限流。每个 field_value 均须符合「字段值格式」的 STRING 约定（标量直接字符串化；数组/对象 JSON.stringify）。

STEP 7 — 确认结果

创建成功后，向用户展示：

• 工作项 ID 和名称
• 链接（如返回中包含）
• 已设置的关键字段摘要

---

特殊字段写入规则

级联选项 (Tree-select)

1. 格式极简：对于业务线（_business）等级联单选字段，field_value 只传 `option_id` 纯字符串，不要传 value/label/children 的复杂 JSON。 2. 层级强校验：如果报错 级联选项字段值不满足层级配置，说明该字段要求选到末级叶子节点。此时查询该选项的 children 树，将末级叶子节点列表展示给用户选择，禁止自行向下盲猜。

不可写入的字段类型

以下字段类型不支持通过 API 写入，遇到时直接跳过并告知用户原因：

富文本与关联字段

• 富文本/多行文本：直接传 Markdown 字符串（# 标题、|列1|列2|、代码块等），完美渲染。
• 关联云文档（PRD）：传 URL 数组，如 ["https://xxx.feishu.cn/docx/xxx"]。
• 前置依赖/关联工作项：传目标工作项 ID。注意：不同空间可能要求字符串 "7093424682" 或数字格式，遇到类型校验失败立刻切换格式重试。用户提供的是工作项名称而非 ID 时，按主文档 SKILL.md「关联工作项名称 → ID 转换」完整流程处理。
• 系统外信号类型 (`signal`)：不接收 option_id，传纯字符串 "true"、"false" 或 "null"。

---

错误自动恢复（自愈机制）

通用自愈规则（格式错误、级联层级、枚举不合法）见主文档 SKILL.md「通用自愈规则」。以下为本 Skill 补充规则：

---

熔断机制 (Circuit Breaker)

通用熔断规则（空间未找到、权限不足）见主文档 SKILL.md「通用熔断规则」。以下为本 Skill 补充规则：

1. 工作项类型未找到：workitem meta-types 失败超过 3 次 2. 字段转换大面积失败：字段值转换失败比例 > 60%，终止流程并列出失败字段明细，不要强行创建残缺数据

---

常见问题

流转节点

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../SKILL.md，其中包含前置检查、授权流程、命令参数参考、字段值格式、通用规范和错误处理。

本技能用于在飞书项目中流转节点流工作项的节点（confirm/rollback），全程自动化执行。

注意：此技能仅用于节点流工作项（如需求），不适用于状态流工作项（如缺陷）。状态流转请参考主文档 SKILL.md 的 workflow transition-state。

---

核心设计原则：最小查询 + 按需补充

workflow transition 工具只接受 node_key（节点 ID），不支持传节点名称。因此必须先通过 workflow get-node 获取名称→node_key 映射。但查询应尽可能精准轻量：

• 用户指定了节点名 → node_id_list 直接传中文名称 ["节点名"]，精准查单个节点
• 用户说"所有节点" → 传 ["_all"] 查全量，但不传 `field_key_list`（不查表单字段）
• 直接尝试流转：拿到 node_key 后立即调 workflow transition
• 按需补充字段：仅当流转失败（提示必填字段未填）时，才查询必填字段并补充

为什么不预查全量字段？ workflow get-node 有分页限制（每页 20 个节点），查全量字段极慢。大多数场景无需补充字段，只在流转失败时按需查目标节点的必填字段即可。

---

执行流程

STEP 1 — 定位工作项

从用户输入中提取 work_item_id 和 project_key：

• 用户给了 URL → 先调 url decode。只有 url_kind == workitem_detail 才能进入本 SOP；其他 kind 按 url-kinds.md 拒绝或追问
• 用户给了 ID → 需同时确定 project_key
• 信息不足时才追问

URL 处理：decode 返回的 simple_name 必须再调 project search 转为权威 project_key（同名空间可能有多个无权限）。禁止自己从 URL 截取路径段作参数。work_item_id 参数必须是字符串类型。

STEP 2 — 精准查节点

根据用户意图选择最高效的查询方式：

从返回结果中获取 name、node_key、status（finished/doing/not_started）。

自动确定操作类型：

• "完成"、"流转"、"确认"、"推进" → action = confirm
• "回滚"、"退回"、"撤回" → action = rollback
• 未明确说 → 默认 confirm

目标节点确定：

• 用户指定了节点名 → 从返回结果中取 node_key
• 用户说"当前节点" → 选 status = "doing" 的节点
• 用户说"所有节点" → 按顺序逐个处理未完成节点
• 用户没指定 → 自动选当前进行中的第一个节点
• 名称匹配不到 → 用 ["_all"] 重新查全量，列出所有节点供用户选择

回滚操作：从用户输入提取原因；用户没给则用"用户发起回滚"作默认原因。

STEP 3 — 直接尝试流转

meegle workflow transition --work-item-id 工作项ID --node-ids '{{node_ids}}' --project-key 空间key --node-id 节点node_key --action confirm --rollback-reason '{{rollback_reason}}' --format json

三种结果分支：

STEP 4 — 按需补充必填字段（仅流转失败时）

只有当 STEP 3 流转失败、提示必填字段未填时才进入本步骤。

4.1 查询未完成的必填字段

meegle workflow list-state-required --work-item-id 工作项ID --state-key 目标节点node_key --project-key 空间key --mode {{mode}} --format json

传入 mode = "unfinished" 仅查未完成必填项。从返回中识别每个字段的 form_item_type（node_field / field）和 field_type。

4.2 评审结论 / 评审意见（`node_finished_conclusion` / `node_finished_opinion`）

这是节点的「整体完成结论 / 意见」，可经接口读写，但前提是该节点已启用这两个字段——只有节点开了「完成结论」配置，workflow get-node 的 form_items 里才会出现它们；没启用时写入会报 node field is invalid。所以先读 `form_items` 确认字段存在，再写。

读取：用 workflow get-node 按 field_key_list 读，或用 workitem get 按 fields 读。字段未启用时返回里不会出现对应项：

meegle workflow get-node --work-item-id 工作项ID --field-key-list '["node_finished_conclusion","node_finished_opinion"]' --need-sub-task {{need_sub_task}} --page-num {{page_num}} --project-key 空间key --node-id-list '["节点node_key"]' --format json

查询结论选项：结论是 select 型，用 workflow meta-node-fields 查 options，写入用其 option_id：

meegle workflow meta-node-fields --field-keys '["node_finished_conclusion"]' --field-types '{{field_types}}' --project-key 空间key --work-item-type 类型key --query '{{query}}' --format json

写入：经 workflow update-node 的 fields 写入——结论写合法 option_id，意见写文本。

🚨 必须分两次调用，一次只写一个字段。 workflow update-node 的 fields 数组里如果同时放结论和意见，只有第一个字段会落库，其余被静默丢弃（返回仍是 success）。这和「排期 / 负责人不要同时改」是同一类约束。每次写完都要 workflow get-node 回读校验，不要凭返回的 success 断言已写入。

meegle workflow update-node --work-item-id 工作项ID --node-schedule '{{node_schedule}}' --schedules '{{schedules}}' --fields '[{"field_key":"node_finished_conclusion","field_value":"option_id"}]' --project-key 空间key --node-id 节点node_key --node-owners '{{node_owners}}' --format json

meegle workflow update-node --work-item-id 工作项ID --node-schedule '{{node_schedule}}' --schedules '{{schedules}}' --fields '[{"field_key":"node_finished_opinion","field_value":"评审意见文本"}]' --project-key 空间key --node-id 节点node_key --node-owners '{{node_owners}}' --format json

4.3 硬拦截：不可写入的字段类型

以下字段类型 API 无法写入。如果被设为流转必填项，立即中断当前节点的流转并告知用户：

🚨 遇到硬拦截时输出：

"节点流转失败。当前节点【节点名称】设置了必须填写【字段名称】（类型：xxx）才能流转。由于该字段类型不支持自动化补充，请您在飞书项目页面手动填写后，再通知我继续流转。"

4.4 可补充字段的值转换

人员字段处理规则（极重要）：

• 用户明确指定了人员 → user search 转 userkey
• 搜索到多个同名用户 → 若用户说"分配给我自己"用 current_login_user()，否则必须向用户确认
• 用户未指定但为必填 → 向用户询问，不要自动默认为当前用户
• 唯一例外：用户明确说"我来负责"/"分配给我"时才用 current_login_user()

节点专属字段（使用 workflow update-node 的专用参数）：

清空节点负责人时传空数组 []（不是 ["_all"]，["_all"] 仅用于 update_field 中删除角色配置）。

评审结论 / 意见（node_finished_conclusion / node_finished_opinion）的读写口径见 §4.2：需节点已启用该字段，且结论与意见必须分两次 `update-node` 调用（一次只落第一个字段）。

通用字段类型转换（完整格式见主文档 SKILL.md「字段值格式」）：

🚨 关键约定：表单字段 field_value 协议层是 STRING。标量直接传字符串；数组/对象必须 JSON.stringify，否则报 need STRING type, but got: LIST。（上方「节点专属字段」走 workflow.update-node 的专用参数，不受此约定影响。）

用户提供的是工作项名称而非 ID 时，按主文档 SKILL.md「关联工作项名称 → ID 转换」完整流程（获取目标约束 → workitem query 搜索 → 消歧 → 按类型写入）处理。

节点字段 vs 工作项字段：

• form_item_type = "node_field" → workflow update-node，传 node_id + fields
• form_item_type = "field" → workitem update（工作项级别）
• 节点枚举值用 workflow meta-node-fields 查询；工作项枚举值用 workitem meta-fields 查询（用 field_keys 精确或 field_query 模糊搜索，禁止逐页遍历）

4.5 字段补充执行策略

🚨 效率要求：一轮对话内并行完成所有必填字段补充。

1. 分类：节点负责人（owner）→ node_owners；排期/估分 → node_schedule；其他字段 → fields 或 workitem update 2. 节点负责人和排期/估分不可同时更新，需分两次调用 workflow update-node 3. 其他节点字段通过 workflow update-node 的 fields 参数批量更新 4. 工作项字段通过 workitem update 的 fields 参数批量更新

4.6 用户未提供值时：

• 人员类 → 必须询问
• 排期/日期类 → 询问用户
• 枚举类 → 列出选项让用户选
• 文本/数字/布尔 → 可给合理默认值（bool 默认 false，估分默认 1）
• 待确认字段 > 3 个时，一次性列出让用户批量回复

STEP 5 — 补充后再次流转

字段补充完成后，再次调用 `workflow transition` 执行流转。仍然失败则读取错误信息重新处理（最多重试 2 次）。

STEP 6 — 返回结果

展示表格汇总：

如果有阻塞节点，明确列出需要用户手动操作的字段和原因。

---

批量流转

当用户说"所有节点"/"全部流转"时： 1. 按节点顺序依次流转：直接调 workflow transition → 失败则按需补充 → 下一个 2. 每个节点独立处理，某个节点被阻塞不影响已完成的节点 3. 最终汇总所有节点的流转结果

---

错误自动恢复（自愈机制）

通用自愈规则（格式错误、级联层级、枚举不合法）见主文档 SKILL.md「通用自愈规则」。以下为本 Skill 补充规则：

---

熔断机制 (Circuit Breaker)

通用熔断规则（空间未找到、权限不足）见主文档 SKILL.md「通用熔断规则」。以下为本 Skill 补充规则：

1. 必填字段全部为硬拦截类型：当前节点所有未完成必填字段都属于不可写类型 2. 连续流转失败：同一节点重试 2 次仍然失败

---

常见问题

流转工作项状态（状态流）

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../SKILL.md，其中包含前置检查、授权流程、命令参数参考、字段值格式、通用规范和错误处理。

本 Skill 用于状态流工作项（如缺陷 / issue）的状态流转，全程自动化编排。

⚠️ 仅限状态流。需求 / story 等节点流工作项请改用 workflow transition（action=confirm/rollback），不要混用本 Skill。

---

执行流程

STEP 1 — 定位工作项 + 获取当前用户（并行）

并行执行：

1. 定位工作项：从用户输入中提取 work_item_id、project_key、work_item_type。

• URL 解析：用户给了链接则先调 url decode。只有 url_kind == workitem_detail 才能进入本 SOP；其他 kind 按 url-kinds.md 拒绝或追问。decode 返回的 simple_name 必须再调 project search 转为权威 project_key（同名空间可能有多个无权限）。禁止自己从 URL 截取路径段作参数。
• ID 类型：传给任何工具的 work_item_id 必须是 字符串（String）。
• 信息不足才追问。

2. 获取当前用户：调用 user search，入参 ["current_login_user()"] 拿到当前用户的 user_key（下一步必填）。

STEP 2 — 查询可流转状态并匹配目标

meegle workflow list-state-transitions --work-item-id 工作项ID --work-item-type 类型key --user-key 当前用户userkey --project-key 空间key --format json

• 匹配目标状态：精确 / 模糊 / 语义匹配用户意图（如"关闭" → "已关闭"，"解决" → "已解决"）拿到对应的 transition_id。
• 🚨 未明确目标状态且有多个候选时：必须展示所有可选项让用户选择，不得替用户默认选择。

STEP 3 — Fail-fast 直接尝试流转

不要前置查询必填项，直接调用 workflow transition-state：

meegle workflow transition-state --work-item-id 工作项ID --project-key 空间key --transition-id 上一步拿到的ID --format json

• 流转成功 → 跳到 STEP 6 返回结果。
• 失败且提示必填字段未填 → 进入 STEP 4 按需补充。
• 失败其他报错 → 参考下方「智能修复」章节。

STEP 4 — 按需收集并补充必填字段（仅流转失败时触发）

调用 workflow list-state-required 获取目标状态所需必填项：

meegle workflow list-state-required --work-item-id 工作项ID --state-key 目标状态key --project-key 空间key --mode {{mode}} --format json

若工具支持 mode 参数（如 mode="unfinished"），优先只查尚未填写的字段，减少噪音。

4.1 硬拦截：不支持 API 更新的字段类型

遇到以下字段被设为必填，立即中断流转并提示用户在页面手动填写：

• vote-boolean / vote-option / vote-option-multi（投票类）
• compound_field / multi_user_compound_field（复合明细表）

中断话术示例：「流转失败。当前状态需要填写【字段名】，该字段不支持自动化补充，请在页面手动填写后通知我继续。」

4.2 枚举选项的前置查询（批量 + 精准）

缺失项包含枚举类（select/radio/multi-select/tree-select 等）时：

• 将所有目标 field_key 数组一次性传入 workitem meta-fields 的 field_keys 精准查询，拿到 option_name 与 option_id。绝不逐页遍历全量配置。
• 将所有必填项及可选值汇总为一条消息向用户展示并询问。

meegle workitem meta-fields --page-num 1 --project-key 空间key --work-item-type 类型key --field-types '{{field_types}}' --field-keys '["key1","key2"]' --field-query '{{field_query}}' --format json

4.3 字段 Mock 与询问边界（安全底线）

• 业务决策类、人员、日期、枚举类字段 → 禁止 AI 编造或 mock 数据。必须列出并询问用户。
• 人员字段（user/multi-user） → 搜出多个同名或用户未指定时必须确认，不可默认填当前操作者（除非用户明确说"分配给我"/"我来处理"）。
• 打回/关闭原因等纯说明性文本（如 "Reopen 原因"、"流转说明"）在用户未提供且字段语义不关键时，可默认填 "重新打开处理" 或 "发起流转"。

4.4 字段值格式

拿到用户确认值后，按主文档 SKILL.md「字段值格式」章节转换为 field_value。

🚨 关键约定：field_value 协议层是 STRING。标量直接传字符串；数组/对象必须 JSON.stringify，否则报 need STRING type, but got: LIST。

用户提供的是工作项名称而非 ID 时，按主文档 SKILL.md「关联工作项名称 → ID 转换」完整流程（获取目标约束 → workitem query 搜索 → 消歧 → 按类型写入）处理。

STEP 5 — 补完字段后再次流转

所有必填字段通过 workitem update 写入后，再次调用 workflow transition-state 触发流转：

meegle workitem update --work-item-id 工作项ID --project-key 空间key --role-operate '{{role_operate}}' --fields '[{"field_key":"xxx","field_value":"yyy"}]' --format json

meegle workflow transition-state --work-item-id 工作项ID --project-key 空间key --transition-id transition_id --format json

STEP 6 — 返回结果

向用户展示：

• 状态变更方向（从 XX → YY）
• 自动 / 协助填入的必填项摘要
• 工作项 ID 与（如返回包含）链接

---

智能修复（自愈机制）

通用自愈规则（格式错误、级联层级、枚举不合法）见主文档 SKILL.md「通用自愈规则」。本 Skill 无额外补充规则。

---

熔断与终止

通用熔断规则（空间未找到、权限不足）见主文档 SKILL.md「通用熔断规则」。以下为本 Skill 补充规则：

1. 必填字段全部为硬拦截类型（投票/复合），无法通过接口写入。 2. 同一目标状态：补字段 → 再次流转连续失败 > 2 次。

---

常见问题

URL Kinds —— url decode 返回值到 SOP 的映射

为什么 skill 不自己拆 URL

Meego/飞书项目的路由非常多，且 snake_case 旧路径、/meego/ 前缀、_xxx_resource 资源工作项、预置功能区（user-gantt / chart / multi-project-view 等）这些都会让"看起来像工作项详情页"的 URL 其实不是。禁止自己从 URL 截取路径段作参数。

统一走一条命令：

meegle url decode --url '<URL>' --format json

拿到 url_kind 后按本文表格选择 SOP 或回绝。纯本地解析，无网络调用。

---

返回字段

---

url_kind → 允许的 SOP

工作项类

视图类（有 view_id 但无 work_item_id）

图表类

空间/设置类（写操作请走 OpenAPI，非本 skill 范围）

全局/导航类

系统域 /b/*

登录/外部入口

错误兜底

特殊字段校验

• redirected_from 非空 → 在回复中提一句"检测到旧版路径，已自动归一化"，避免用户误以为 URL 错了
• is_resource=true → 告知用户这是资源工作项视图，work_item_type 已自动脱去 _xxx_resource 包装
• query.scope / query.node 非空 → 仅作为导航上下文，不要当作业务参数

---

典型分支模板（供 SOP 引用）

STEP 0 — URL 解析（仅当用户提供了 URL）

  url decode --url "<URL>"
  SAVE $url_kind, $simple_name, $work_item_type, $work_item_id, $view_id, $redirected_from

  SWITCH $url_kind:
    - workitem_detail    → GOTO 本 SOP 的 STEP 1（已具备 simple_name + work_item_id）
    - workitem_homepage  → ASK user："需要具体工作项 URL，这是类型主页。"；STOP
    - view_*             → ASK user："这是视图 URL，请粘贴具体工作项详情页 URL。"；STOP
    - unknown            → ASK user："无法识别该 URL，请确认后重发或直接描述任务。"；STOP
    - 其他非本 SOP 范围   → 告知 kind，建议对应操作；STOP

视图辅助命令

视图搜索与固定视图管理。读取视图数据用 view get（见 SKILL.md 主文件）。

view search

按名称搜索视图。

view create-fixed

创建固定视图。上限 200 个工作项。

view update-fixed

更新固定视图。add/remove_work_item_ids 二选一。

view list-multi-project-workitems

查看全景视图（multiProjectView）下当前用户有权限的工作项列表。全景视图的链接上带有 multiProjectView 关键字，可从中提取 view_id。

工作流辅助命令

工作流流转之前用来查询可流转方向、必填项、节点字段配置的辅助命令。核心流转命令（workflow transition / workflow transition-state / workflow get-node / workflow update-node）见 SKILL.md 主文件。

workflow list-state-transitions

查看工作项可流转的状态列表。状态流流转前必须先调用此命令拿 transition_id。

workflow list-state-required

查看流转所需的必填信息（节点流传 node_key，状态流传 state_key）。

workflow meta-node-fields

查看节点字段配置。workflow update-node 修改节点自定义字段前用来确认合法 field_key、字段类型与 options。查询评审结论选项时按 field_keys=["node_finished_conclusion"] 精确查询，并从返回配置的 options / 选项列表中取合法值。