Back to Details

meegle

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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

Feishu Project (Meego/Meegle) Operation Guide

本技能通过 Meegle CLI来操作飞书项目数据。输出语言跟随用户输入语言，默认中文。
各命令的调用示例见 references/api-examples.md。 授权流程（所有业务命令前必须执行）：见 references/auth-guard.md CLI 使用指南（命令结构、参数传递、命令发现）：见 references/cli-guide.md
This skill operates Feishu Project data via Meegle CLI. The output language follows the user's input language, with Chinese as the default.
See references/api-examples.md for call examples of each command. Authorization Process (Must be executed before all business commands): See references/auth-guard.md CLI Usage Guide (Command structure, parameter passing, command discovery): See references/cli-guide.md

Project 空间域

Project Space Domain

project search

project search

搜索空间信息，将空间名转换为 project_key 或验证空间是否存在。
参数类型必填说明
--project-keystring是空间 projectKey、simpleName 或空间名称
Searches space information, converts space name to project_key or verifies if the space exists.
ParameterTypeRequiredDescription
--project-keystringYesSpace projectKey, simpleName or space name

WorkItem 工作项域

WorkItem Domain

workitem create

workitem create

创建工作项实例。务必先用 
workitem meta-fields
获取字段信息，
workitem meta-roles
获取角色信息。模板 ID 是必填项。
参数类型必填说明
--work-item-typestring是工作项类型
--project-keystring否空间标识
--fieldsarray否字段值列表，每项含 field_key 和 field_value
Creates a work item instance. Be sure to first use 
workitem meta-fields
to get field information and 
workitem meta-roles
to get role information. Template ID is required.
ParameterTypeRequiredDescription
--work-item-typestringYesWork item type
--project-keystringNoSpace identifier
--fieldsarrayNoList of field values, each containing field_key and field_value

workitem get

workitem get

按 ID/名称查询工作项概况。不传 fields 时仅返回固定基础字段；如需自定义字段数据，先调 
workitem meta-fields
获取字段 key 后传入 fields。
参数类型必填说明
--work-item-idstring是工作项 ID 或名称
--project-keystring否空间 key
--fieldsarray否要查询的 field_key 或 field_name
Queries work item overview by ID/name. Only fixed basic fields are returned if fields are not passed; to get custom field data, first call 
workitem meta-fields
to get field keys and then pass them in fields.
ParameterTypeRequiredDescription
--work-item-idstringYesWork item ID or name
--project-keystringNoSpace key
--fieldsarrayNofield_key or field_name to query

workitem batch-get

workitem batch-get

批量查询工作项（Meegle CLI 客户端 fan-out：并发调用 
workitem get
）。单次 ≤ 200 个 ID，3 并发，返回 
{results, errors, summary}
；ID 量大时用 
--format ndjson
流式输出。
参数类型必填说明
--work-item-idsarray二选一工作项 ID 列表（逗号分隔或多次传入）
--ids-filestring二选一从文件读取 ID（一行一个，
#
开头注释）
--fieldsarray否要查询的 field_key 列表
--project-keystring否空间 key
Queries work items in batches (Meegle CLI client fan-out: concurrent calls to 
workitem get
). Maximum 200 IDs per call, 3 concurrencies, returns 
{results, errors, summary}
; use 
--format ndjson
for streaming output when there are a large number of IDs.
ParameterTypeRequiredDescription
--work-item-idsarrayEitherList of work item IDs (comma-separated or passed multiple times)
--ids-filestringEitherRead IDs from file (one per line, lines starting with 
#
are comments)
--fieldsarrayNoList of field_key to query
--project-keystringNoSpace key

workitem update

workitem update

修改指定实例的字段值或角色。节点字段更新请用 
workflow update-node
。
参数类型必填说明
--work-item-idstring是工作项 ID 或名称
--project-keystring否空间 key
--fieldsarray否要更新的字段列表，每项含 field_key 和 field_value
--role-operatearray否角色操作，每项含 op(add/remove)、role_key、user_keys
角色更新：不能通过 fields 更新角色，必须用 
role_operate
。role_key 通过 
workitem meta-roles
获取，user_keys 通过 
user search
获取。
Modifies field values or roles of the specified instance. Use 
workflow update-node
to update node fields.
ParameterTypeRequiredDescription
--work-item-idstringYesWork item ID or name
--project-keystringNoSpace key
--fieldsarrayNoList of fields to update, each containing field_key and field_value
--role-operatearrayNoRole operations, each containing op(add/remove), role_key, user_keys
Role Update: Roles cannot be updated via fields, must use 
role_operate
. role_key is obtained via 
workitem meta-roles
, user_keys via 
user search
.

workitem query

workitem query

使用 MQL 查询工作项数据。语法详见 references/mql-syntax.md。
参数类型必填说明
--project-keystring是空间标识（支持名称、simpleName、projectKey）
--mqlstring是（翻页时可用 session_id 替代）MQL 查询语句（完整 SQL）
--session-idstring否分页会话 ID，传入后不解析 MQL 直接翻页
--group-pagination-listarray否分页信息，首次查询可不传
要点：
  • 先用 
    workitem meta-fields
    / 
    workitem meta-roles
    获取字段与角色配置；查不到直接报错不要继续
  • SELECT 后属性不宜过多，优先使用字段 key（如 
    name
    、
    priority
    、
    status
    ）；返回按页返回，需全量时使用翻页参数
Queries work item data using MQL. For syntax details, see references/mql-syntax.md.
ParameterTypeRequiredDescription
--project-keystringYesSpace identifier (supports name, simpleName, projectKey)
--mqlstringYes (session_id can be used instead for pagination)MQL query statement (complete SQL)
--session-idstringNoPagination session ID, pass to paginate directly without parsing MQL
--group-pagination-listarrayNoPagination information, can be omitted for first query
Key Points:
  • First use 
    workitem meta-fields
    / 
    workitem meta-roles
    to get field and role configurations; report error directly if not found and do not proceed
  • Do not select too many attributes after SELECT; prefer using field keys (e.g., 
    name
    , 
    priority
    , 
    status
    ); results are returned page by page, use pagination parameters for full data

workitem list-op-records

workitem list-op-records

查看工作项操作记录。
参数类型必填说明
--project-keystring是空间 key
--work-item-idstring是工作项 ID
Views work item operation records.
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--work-item-idstringYesWork item ID

workitem meta-types

workitem meta-types

获取指定空间下所有工作项类型列表。用户描述模糊时用此命令确认合法 type_key。
参数类型必填说明
--project-keystring是空间 projectKey
Gets the list of all work item types under the specified space. Use this command to confirm valid type_key when user's description is ambiguous.
ParameterTypeRequiredDescription
--project-keystringYesSpace projectKey

workitem meta-fields

workitem meta-fields

获取指定空间和工作项类型的可用字段配置（不含禁用字段和角色配置）。
参数类型必填说明
--project-keystring是空间 key
--work-item-typestring是工作项类型 key 或名称
--page-numnumber是页数，每页 50 条，从 1 开始
--field-keysarray否精确匹配字段 key 或名称
--field-querystring否模糊查询字段 key 和名称
--field-typesarray否按字段类型筛选
Gets available field configurations for the specified space and work item type (excluding disabled fields and role configurations).
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--work-item-typestringYesWork item type key or name
--page-numnumberYesPage number, 50 items per page, starting from 1
--field-keysarrayNoExact match field key or name
--field-querystringNoFuzzy query field key and name
--field-typesarrayNoFilter by field type

workitem meta-roles

workitem meta-roles

获取指定工作项类型的角色列表。用于查询/创建/更新工作项前确认合法 role_key。
参数类型必填说明
--project-keystring是空间 key
--work-item-typestring是工作项类型 key 或名称
--page-numnumber是页数，每页 50 条，从 1 开始
--role-keysarray否精确匹配角色 key 或名称
--role-querystring否模糊查询角色 key 和名称
Gets the list of roles for the specified work item type. Used to confirm valid role_key before querying/creating/updating work items.
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--work-item-typestringYesWork item type key or name
--page-numnumberYesPage number, 50 items per page, starting from 1
--role-keysarrayNoExact match role key or name
--role-querystringNoFuzzy query role key and name

workitem meta-create-fields

workitem meta-create-fields

查看创建工作项时可用的字段及类型。
参数类型必填说明
--project-keystring是空间 key
Views fields and types available when creating work items.
ParameterTypeRequiredDescription
--project-keystringYesSpace key

WorkFlow 工作流域

WorkFlow Domain

workflow transition

workflow transition

仅用于节点流工作项，操作节点完成流转或回滚。
参数类型必填说明
--work-item-idstring是工作项 ID
--actionstring否confirm（流转） / rollback（回滚）
--node-idstring否节点 ID
--node-idsarray否节点名称或节点 ID 列表
--rollback-reasonstring否回滚原因，action=rollback 时需填写
--project-keystring否空间 key
Only for node-flow work items, operates nodes to complete workflow or rollback.
ParameterTypeRequiredDescription
--work-item-idstringYesWork item ID
--actionstringNoconfirm (workflow) / rollback (rollback)
--node-idstringNoNode ID
--node-idsarrayNoList of node names or node IDs
--rollback-reasonstringNoRollback reason, required when action=rollback
--project-keystringNoSpace key

workflow transition-state

workflow transition-state

仅用于状态流工作项，流转工作项状态。先用 
workflow list-state-transitions
获取可流转状态及 transition_id。
参数类型必填说明
--work-item-idstring是工作项 ID
--transition-idstring否状态流转 ID，从 
workflow list-state-transitions
获取
--project-keystring否空间 key
Only for state-flow work items, transitions work item status. First use 
workflow list-state-transitions
to get available transition states and transition_id.
ParameterTypeRequiredDescription
--work-item-idstringYesWork item ID
--transition-idstringNoState transition ID, obtained from 
workflow list-state-transitions
--project-keystringNoSpace key

workflow get-node

workflow get-node

获取工作项中指定节点或所有节点的完整详情。
参数类型必填说明
--work-item-idstring是工作项 ID 或名称
--node-id-listarray否节点 ID 列表，传空或 
_all
获取所有节点
--field-key-listarray否节点字段 key，传空或 
_all
获取所有字段
--need-sub-taskboolean否是否需要节点子项（子任务）
--page-numnumber否节点信息一次最多 20 个，按页返回
--project-keystring否空间 key
Gets complete details of specified nodes or all nodes in the work item.
ParameterTypeRequiredDescription
--work-item-idstringYesWork item ID or name
--node-id-listarrayNoList of node IDs, pass empty or 
_all
to get all nodes
--field-key-listarrayNoNode field keys, pass empty or 
_all
to get all fields
--need-sub-taskbooleanNoWhether to include node subtasks
--page-numnumberNoMaximum 20 node items per page, returned page by page
--project-keystringNoSpace key

workflow update-node

workflow update-node

修改节点（排期、负责人、自定义字段等）。排期/差异化排期/负责人不要同时修改，需分多次调用。
参数类型必填说明
--work-item-idstring是工作项 ID
--node-idstring是节点 ID（node_key）
--node-ownersarray否节点负责人 userkey 数组；清空传空数组 
[]
--node-scheduleobject否节点排期，格式 
{"estimate_start_date":ms,"estimate_end_date":ms,"owners":[userkey],"points":数字}
；清空传 
{}
；不变更则不传
--schedulesarray否按人差异化排期，每项细化到单个人的排期；清空某人则 
estimate_start_date
/
estimate_end_date
传 null
--fieldsarray否节点自定义字段，每项含 
field_key
和 
field_value
（STRING 协议，见「字段值格式」）
--project-keystring否空间 key
Modifies nodes (schedule, owner, custom fields, etc.). Do not modify schedule/differentiated schedule/owner at the same time, call separately.
ParameterTypeRequiredDescription
--work-item-idstringYesWork item ID
--node-idstringYesNode ID (node_key)
--node-ownersarrayNoArray of node owner userkeys; pass empty array 
[]
to clear
--node-scheduleobjectNoNode schedule, format 
{"estimate_start_date":ms,"estimate_end_date":ms,"owners":[userkey],"points":number}
; pass 
{}
to clear; omit if no change
--schedulesarrayNoDifferentiated schedule by user, each item details schedule for a single user; pass null for 
estimate_start_date
/
estimate_end_date
to clear someone's schedule
--fieldsarrayNoNode custom fields, each containing 
field_key
and 
field_value
(STRING protocol, see "Field Value Format")
--project-keystringNoSpace key

workflow list-state-transitions

workflow list-state-transitions

查看工作项可流转的状态列表。
参数类型必填说明
--project-keystring是空间 key
--work-item-idstring是工作项 ID
--work-item-typestring是工作项类型
--user-keystring是用户标识
Views the list of available status transitions for work items.
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--work-item-idstringYesWork item ID
--work-item-typestringYesWork item type
--user-keystringYesUser identifier

workflow list-state-required

workflow list-state-required

查看流转所需的必填信息（节点流传 node_key，状态流传 state_key）。
参数类型必填说明
--project-keystring是空间 key
--work-item-idstring是工作项 ID
--state-keystring是节点流的 node_key 或状态流的 state_key
--modestring否默认查所有必填项；传 
unfinished
仅查未完成必填项
Views required information for transition (node_key for node flow, state_key for state flow).
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--work-item-idstringYesWork item ID
--state-keystringYesnode_key for node flow or state_key for state flow
--modestringNoDefault to query all required items; pass 
unfinished
to query only uncompleted required items

workflow meta-node-fields

workflow meta-node-fields

查看节点字段配置。
参数类型必填说明
--project-keystring是空间 key
--work-item-typestring是工作项类型
Views node field configurations.
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--work-item-typestringYesWork item type

MyWork 工作台域

MyWork Dashboard Domain

mywork todo

mywork todo

按 action 类型查询当前用户的工作项列表。无需 MQL 即可查询待办/已办。
参数类型必填说明
--actionstring是todo(待办)/done(已办)/overdue(逾期)/this_week(本周待办)
--page-numnumber是页码，从 1 开始，每页 50 条
--asset-keystring否工作区 key（格式 Asset_xxx），仅在报错需要选择时传
需完整结果时，从 page_num=1 连续翻页直到空为止。
Queries current user's work item list by action type. Query to-dos/completed items without MQL.
ParameterTypeRequiredDescription
--actionstringYestodo(pending)/done(completed)/overdue(overdue)/this_week(this week's pending)
--page-numnumberYesPage number, starting from 1, 50 items per page
--asset-keystringNoWorkspace key (format Asset_xxx), only pass when error requires selection
For complete results, continuously paginate from page_num=1 until empty.

WorkHour 工时域

WorkHour Domain

workhour list-schedule

workhour list-schedule

获取指定人员在时间区间内的排期与工作量明细。
参数类型必填说明
--project-keystring是空间 key
--user-keysarray是用户标识（名称/邮箱/userkey），每次最多 20 个
--start-timestring是开始时间，格式 YYYY-MM-DD
--end-timestring是结束时间，格式 YYYY-MM-DD，单次跨度最大 3 个月
--work-item-type-keysarray否工作项类型列表，查询所有传入 
_all
调用约束：每次最多 20 人（多人拆批次并行）；单次跨度 ≤ 3 个月（超出按月拆分）；所有批次完成后再汇总，未完整获取前不得输出结论。
Gets schedule and workload details for specified users within the time range.
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--user-keysarrayYesUser identifiers (name/email/userkey), maximum 20 at a time
--start-timestringYesStart time, format YYYY-MM-DD
--end-timestringYesEnd time, format YYYY-MM-DD, maximum 3 months per call
--work-item-type-keysarrayNoList of work item types, pass 
_all
to query all
Call Constraints: Maximum 20 users at a time (split into batches for parallel calls); time span ≤ 3 months per call (split by month if exceeded); summarize after all batches are completed, do not output conclusions before full data is obtained.

workhour list-records

workhour list-records

查看工作项的工时登记记录。
参数类型必填说明
--project-keystring是空间 key
--work-item-typestring是工作项类型
--work-item-idstring是工作项 ID
Views work hour registration records for work items.
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--work-item-typestringYesWork item type
--work-item-idstringYesWork item ID

UserGroup 人员域

UserGroup Domain

user search

user search

批量查询用户基础信息。用于将姓名/邮箱转换为 userkey。
参数类型必填说明
--user-keysarray是userKey、Email 或名字，最多 20 个
--project-keystring否空间 key
Queries basic user information in batches. Used to convert name/email to userkey.
ParameterTypeRequiredDescription
--user-keysarrayYesuserKey, Email or name, maximum 20
--project-keystringNoSpace key

user me

user me

查看当前用户信息。无需参数。
MQL 中可直接用 
current_login_user()
函数，无需提前获取用户信息。如需获取当前用户的 userkey/姓名等详细信息，可用 
user search
传入 
current_login_user()
作为参数。
Views current user information. No parameters required.
In MQL, you can directly use the 
current_login_user()
function without obtaining user information in advance. To get detailed information such as userkey/name of the current user, use 
user search
with 
current_login_user()
as the parameter.

team list

team list

查看空间下的团队列表。
参数类型必填说明
--project-keystring否空间 key
Views the list of teams under the space.
ParameterTypeRequiredDescription
--project-keystringNoSpace key

team list-members

team list-members

查看团队成员列表。
参数类型必填说明
--project-keystring是空间 key
--team-idstring是团队 ID
Views the list of team members.
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--team-idstringYesTeam ID

View 视图域

View Domain

view get

view get

根据视图 ID 获取该视图下的工作项列表。
参数类型必填说明
--view-idstring是视图 ID
--project-keystring否空间 key
--page-numnumber否分页页数起点
--fieldsarray否要查询的字段
Gets the list of work items under the view based on view ID.
ParameterTypeRequiredDescription
--view-idstringYesView ID
--project-keystringNoSpace key
--page-numnumberNoStarting page number for pagination
--fieldsarrayNoFields to query

view search

view search

按名称搜索视图。
参数类型必填说明
--project-keystring是空间 key
--view-scopestring是视图范围
--key-wordstring是关键词
Searches views by name.
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--view-scopestringYesView scope
--key-wordstringYesKeyword

view create-fixed

view create-fixed

创建固定视图。上限 200 个工作项。
参数类型必填说明
--project-keystring是空间 key
--namestring是视图名称
--work-item-typestring是工作项类型
--work-item-id-listarray是工作项 ID 列表
Creates a fixed view. Maximum 200 work items.
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--namestringYesView name
--work-item-typestringYesWork item type
--work-item-id-listarrayYesList of work item IDs

view update-fixed

view update-fixed

更新固定视图。add/remove_work_item_ids 二选一。
参数类型必填说明
--project-keystring是空间 key
--view-idstring是视图 ID
--work-item-typestring是工作项类型
Updates a fixed view. Choose either add/remove_work_item_ids.
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--view-idstringYesView ID
--work-item-typestringYesWork item type

Chart 度量域

Chart Domain

chart get

chart get

查看图表详情。
参数类型必填说明
--chart-idstring是图表 ID
Views chart details.
ParameterTypeRequiredDescription
--chart-idstringYesChart ID

chart list

chart list

查看视图下的图表列表。
参数类型必填说明
--project-keystring是空间 key
--view-idstring是视图 ID
Views the list of charts under the view.
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--view-idstringYesView ID

Comment 评论域

Comment Domain

comment add

comment add

添加评论。支持富文本 Markdown，语法详见 references/rich-text-editor-markdown-syntax.md（含 @提及、对齐、链接预览、字号/颜色等扩展语法）。
参数类型必填说明
--work-item-idstring是工作项 ID
--comment-contentstring是评论内容
Adds a comment. Supports rich text Markdown, see references/rich-text-editor-markdown-syntax.md for syntax details (including @mention, alignment, link preview, font size/color and other extended syntax).
ParameterTypeRequiredDescription
--work-item-idstringYesWork item ID
--comment-contentstringYesComment content

comment list

comment list

查看评论列表。
参数类型必填说明
--project-keystring是空间 key
--work-item-idstring是工作项 ID
Views the list of comments.
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--work-item-idstringYesWork item ID

SubTask 子任务域

SubTask Domain

subtask update

subtask update

创建/修改/完成/回滚子任务。
参数类型必填说明
--node-idstring是节点 ID
--work-item-idstring是工作项 ID
--actionstring是create/update/confirm/rollback
Creates/modifies/completes/rolls back subtasks.
ParameterTypeRequiredDescription
--node-idstringYesNode ID
--work-item-idstringYesWork item ID
--actionstringYescreate/update/confirm/rollback

Relation 关系域

Relation Domain

relation list

relation list

查看关联的工作项列表。
参数类型必填说明
--project-keystring是空间 key
--work-item-idstring是工作项 ID
--relation-field-keystring否关联关系字段 key，从 
relation meta-definitions
获取
--relation-idstring否关联关系 ID，从 
relation meta-definitions
获取
--node-idstring否节点 ID，查询某节点下的关联时传入
--page-numnumber否分页页码，从 1 开始
--page-sizenumber否每页数量，最大 50
Views the list of related work items.
ParameterTypeRequiredDescription
--project-keystringYesSpace key
--work-item-idstringYesWork item ID
--relation-field-keystringNoRelated relation field key, obtained from 
relation meta-definitions
--relation-idstringNoRelated relation ID, obtained from 
relation meta-definitions
--node-idstringNoNode ID, pass to query relations under a specific node
--page-numnumberNoPagination page number, starting from 1
--page-sizenumberNoNumber of items per page, maximum 50

relation meta-definitions

relation meta-definitions

查看空间下的关联关系定义。
参数类型必填说明
--project-keystring是空间 key
Views related relation definitions under the space.
ParameterTypeRequiredDescription
--project-keystringYesSpace key

字段值格式（field_value）

Field Value Format (field_value)

🚨 STRING 协议：
field_value
协议层固定为字符串。标量（text/number/bool/option_id/userkey/毫秒）直接作字符串；数组、对象必须先 JSON.stringify 再传，直接传会报 
need STRING type, but got: LIST
/ 
MAP
。 例：multi-user 正确写法为 
"[\"7509072868295085608\"]"
，错误写法为 
["7509072868295085608"]
。
字段类型语义field_value 传参（已按上述约定序列化）
template模板 ID（创建必填）
"145405865"
— 用 
workitem meta-fields(field_keys=["template"])
获取
text / multi-pure-text / link / bool / number单个字面值
"测试工作项"
/ 
"100"
/ 
"true"
user单个 userkey
"7509072868295085608"
multi-useruserkey 数组（stringified）
"[\"7509072868295085608\",\"7509072868295085609\"]"
select / radio / tree-select枚举项 option_id
"437794"
multi-selectoption_id 对象数组（stringified）
"[{\"option_id\":\"111\"},{\"option_id\":\"222\"}]"
tree-multi-selectoption_id 字符串数组（stringified）
"[\"id1\",\"id2\"]"
multi-text富文本 Markdown 字符串（语法详见 references/rich-text-editor-markdown-syntax.md）
"**加粗**内容"
date毫秒时间戳（天精度）
"1722182400000"
schedule
[开始ms, 结束ms]
（stringified）
"[1722182400000,1722355199999]"
precise_date对象（stringified）
"{\"start_time\":1722182400000,\"end_time\":1722355199999}"
workitem_related_select关联工作项 ID
"145405865"
workitem_related_multi_selectID 数组（stringified，数字元素）
"[145405865,145405866]"
role_owners（仅创建时）角色-人员对象数组（stringified）
"[{\"role\":\"RD\",\"owners\":[\"userkey1\"]}]"
signal纯字符串
"true"
/ 
"false"
/ 
"null"
更新角色时不用 fields，用 
workitem update
的 
role_operate
参数。
🚨 STRING Protocol: 
field_value
is fixed as a string at the protocol layer. Scalars (text/number/bool/option_id/userkey/milliseconds) are directly passed as strings; arrays and objects must be JSON.stringify first before passing, otherwise errors like 
need STRING type, but got: LIST
/ 
MAP
will occur. Example: Correct format for multi-user is 
"[\"7509072868295085608\"]"
, wrong format is 
["7509072868295085608"]
.
Field TypeSemanticsfield_value Parameter (Serialized according to the above convention)
templateTemplate ID (Required for creation)
"145405865"
— obtained via 
workitem meta-fields(field_keys=["template"])
text / multi-pure-text / link / bool / numberSingle literal value
"Test work item"
/ 
"100"
/ 
"true"
userSingle userkey
"7509072868295085608"
multi-userArray of userkeys (stringified)
"[\"7509072868295085608\",\"7509072868295085609\"]"
select / radio / tree-selectEnumeration option_id
"437794"
multi-selectArray of option_id objects (stringified)
"[{\"option_id\":\"111\"},{\"option_id\":\"222\"}]"
tree-multi-selectArray of option_id strings (stringified)
"[\"id1\",\"id2\"]"
multi-textRich text Markdown string (see references/rich-text-editor-markdown-syntax.md for syntax)
"**Bold** content"
dateMillisecond timestamp (day precision)
"1722182400000"
schedule
[start ms, end ms]
(stringified)
"[1722182400000,1722355199999]"
precise_dateObject (stringified)
"{\"start_time\":1722182400000,\"end_time\":1722355199999}"
workitem_related_selectRelated work item ID
"145405865"
workitem_related_multi_selectArray of IDs (stringified, numeric elements)
"[145405865,145405866]"
role_owners (Only for creation)Array of role-user objects (stringified)
"[{\"role\":\"RD\",\"owners\":[\"userkey1\"]}]"
signalPure string
"true"
/ 
"false"
/ 
"null"
Do not use fields to update roles, use the 
role_operate
parameter of 
workitem update
.

关联工作项字段（workitem_related_*）

Related Work Item Fields (workitem_related_*)

用户提供名称而非 ID 时，需按名称→ID 转换流程（搜目标空间+类型，消歧，写入格式，防循环引用）：详见 references/field-value-extras.md。
When user provides name instead of ID, follow the name→ID conversion process (search target space + type, disambiguate, write format, prevent circular references): See references/field-value-extras.md for details.

常用场景速查

Common Scenario Quick Reference

场景命令（注意点）
空间名 → project_key
project search
查类型 / 字段 / 角色
workitem meta-types
/ 
workitem meta-fields
/ 
workitem meta-roles
人名 → userkey
user search
（批量 ≤20）
当前用户
user me
；MQL 内可直接 
current_login_user()
条件查询 / 个人待办
workitem query
（MQL） / 
mywork todo
团队排期
workhour list-schedule
（≤20 人、≤3 月）
创建 / 修改工作项
workitem create
/ 
workitem update
（字段 fields，角色 role_operate）
节点流转 / 状态流转
workflow transition
（confirm/rollback） / 
workflow transition-state
（先 
workflow list-state-transitions
）
视图数据
view get
ScenarioCommand (Notes)
Space name → project_key
project search
Query type / field / role
workitem meta-types
/ 
workitem meta-fields
/ 
workitem meta-roles
User name → userkey
user search
(batch ≤20)
Current user
user me
; can directly use 
current_login_user()
in MQL
Conditional query / personal to-dos
workitem query
(MQL) / 
mywork todo
Team schedule
workhour list-schedule
(≤20 users, ≤3 months)
Create / modify work item
workitem create
/ 
workitem update
(fields for fields, role_operate for roles)
Node workflow / status workflow
workflow transition
(confirm/rollback) / 
workflow transition-state
(first 
workflow list-state-transitions
)
View data
view get

通用规范

General Specifications

请求处理流程

Request Processing Flow

收到用户输入后依次执行：
  1. 参数提取：从自然语言中提取空间名、工作项类型、时间、人员、筛选条件；含 URL 时直传 
    url
    参数并跳过参数确认。注意区分空间名与筛选维度（如「XX空间下YY业务线的缺陷」中 XX 才是空间名）。
  2. 参数确认（禁止猜测）：用探测命令校验空间（
    project search
    ）、类型（
    workitem meta-types
    ）、人员（
    user search
    ）。探测结果不唯一时必须展示并询问用户，禁止自行选择；缺失必填合并为一条消息询问。个人待办（
    mywork todo
    ）和 URL 直接操作可跳过。
  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 的并行/翻页规则。
After receiving user input, execute the following steps in order:
  1. Parameter Extraction: Extract space name, work item type, time, personnel, filtering conditions from natural language; directly pass 
    url
    parameter and skip parameter confirmation if URL is included. Note the difference between space name and filtering dimensions (e.g., in "Defects of YY business line under XX space", XX is the space name).
  2. Parameter Confirmation (No guessing allowed): Verify space (via 
    project search
    ), type (via 
    workitem meta-types
    ), personnel (via 
    user search
    ) using detection commands. Must display and ask user if detection results are not unique, do not select automatically; combine missing required items into one message to ask. Personal to-dos (
    mywork todo
    ) and direct URL operations can skip this step.
  3. Metadata Collection (No user involvement): Call 
    workitem meta-fields
    to get field definitions (use 
    field_keys
    for specific fields, 
    field_query
    for fuzzy query); call 
    workitem meta-roles
    in parallel if roles are involved. Key field identification: status field type=
    _work_item_status
    (values containing "Completed/Closed/Terminated" are completed states), schedule field type=
    schedule
    (use 
    __field_name_start_time
    / 
    __field_name_end_time
    in MQL), priority field key=
    priority
    . This step can be skipped for simple direct call scenarios (only need project_key + work_item_id, e.g., 
    comment add
    ).
  4. Execution: Call the target command, follow parallel/pagination rules in references/performance.md.

并行与大结果

Parallel Processing and Large Results

详见 references/performance.md：并行调用（必须串行的链路、可并行的组合）、大结果分批与翻页规则。
See references/performance.md for details: parallel calls (serial-only links, combinable parallel calls), batch processing and pagination rules for large results.

错误处理

Error Handling

总则：失败后从返回的 
err_msg
/ 
inner_err
中提取错误原因，针对性修正后重试；最多自动重试 2 次，连续 3 次同类失败后停止并向用户说明。
熔断条件（立即终止，禁止盲目重试）：
  • 空间未找到（
    project search
    连续 3 次失败）
  • Permission Denied（当前用户对该空间无访问权限）
自愈规则（按报错特征匹配修复后重试）：
报错特征自愈动作
need STRING type, but got: LIST
/ 
MAP
field_value 从原生 JSON 改为 JSON.stringify 后的字符串（见「字段值格式」）
cannot unmarshal object...
仅改变格式（数字↔字符串、单值↔数组、对象↔纯字符串），值不变
不满足层级配置
（级联层级错误）		查 
children
树，展示末级叶子节点让用户选择
invalid select option(s)
（枚举不合法）		从 
possible values
匹配；唯一匹配则修正重试，否则询问用户
错误速查：
现象排查/修复
找不到空间 / 中文名匹配多个空间
project search
验证，取 project_key 精确调用
找不到工作项类型
workitem meta-types
确认合法 type_key
字段名错误 / MQL 返回为空但数据存在
workitem meta-fields
确认字段 key 与类型
MQL 查询失败FROM 用 
`空间名`.`工作项类型`
；数组字段改用 
array_contains
/ 
any_match
日期区间字段查询失败用子字段 
`__字段名_开始时间`
角色查询无结果MQL 角色名用 
`__{角色名}`
格式
人名/团队名重复MQL 用 
<id:xxxx>
消歧（见 MQL 语法参考）
人名→userkey 失败
user search
批量查询
人员字段写入失败user 传单个 userkey 字符串；multi-user 必须 stringified 如 
"[\"k1\",\"k2\"]"
node not found先 
workitem get
获取真实 node_id，禁止猜测
节点流转失败节点流用 
workflow transition
；状态流用 
workflow transition-state
（先 
workflow list-state-transitions
取 transition_id，再 
workflow list-state-required
查必填项）
创建工作项缺少模板
workitem meta-fields(field_keys=["template"])
获取
角色更新失败改用 
workitem update
的 
role_operate
参数（不走 fields）
mywork.todo 需选择工作区按报错中的列表把 
asset_key
（Asset_xxx）传入重试
General Rule: After failure, extract error cause from returned 
err_msg
/ 
inner_err
, correct and retry; automatically retry up to 2 times, stop and explain to user after 3 consecutive failures of the same type.
Circuit Breaker Conditions (Terminate immediately, no blind retries allowed):
  • Space not found (3 consecutive failures of 
    project search
    )
  • Permission Denied (Current user has no access to the space)
Self-healing Rules (Match error characteristics to fix and retry):
Error CharacteristicsSelf-healing Action
need STRING type, but got: LIST
/ 
MAP
Change field_value from native JSON to JSON.stringify'd string (see "Field Value Format")
cannot unmarshal object...
Only change format (number↔string, single value↔array, object↔pure string), keep value unchanged
"Does not meet hierarchy configuration" (Cascade hierarchy error)Query 
children
tree, display leaf nodes for user to select
invalid select option(s)
(Invalid enumeration)		Match from 
possible values
; retry with correction if unique match, otherwise ask user
Error Quick Reference:
PhenomenonTroubleshooting/Fix
Space not found / Multiple spaces matching Chinese nameVerify via 
project search
, use project_key for precise call
Work item type not foundConfirm valid type_key via 
workitem meta-types
Field name error / MQL returns empty but data existsConfirm field key and type via 
workitem meta-fields
MQL query failedUse 
`space_name`.`work_item_type`
in FROM; use 
array_contains
/ 
any_match
for array fields
Date range field query failedUse subfield 
`__field_name_start_time`
Role query returns no resultsUse 
`__{role_name}`
format for role names in MQL
Duplicate user name/team nameUse 
<id:xxxx>
to disambiguate in MQL (see MQL syntax reference)
User name→userkey conversion failedUse 
user search
for batch query
Personnel field write failedPass single userkey string for user; multi-user must be stringified like 
"[\"k1\",\"k2\"]"
node not foundFirst get real node_id via 
workitem get
, no guessing allowed
Node workflow failedUse 
workflow transition
for node flow; use 
workflow transition-state
for state flow (first get transition_id via 
workflow list-state-transitions
, then check required items via 
workflow list-state-required
)
Missing template when creating work itemObtain via 
workitem meta-fields(field_keys=["template"])
Role update failedUse 
role_operate
parameter of 
workitem update
(do not use fields)
mywork.todo requires workspace selectionPass 
asset_key
(Asset_xxx) from error message list to retry

操作指南（SOP）

Standard Operating Procedures (SOP)

具体操作的完整流程、字段转换和自愈机制见对应 SOP：
  • 创建工作项 — 创建需求、任务、缺陷
  • 更新工作项 — 修改字段、更新角色、追加内容
  • 流转节点（节点流） — 完成/回滚节点、批量流转
  • 流转状态（状态流） — 流转缺陷/issue、关闭 bug
Complete process, field conversion and self-healing mechanism for specific operations can be found in corresponding SOPs:
  • Create Work Item — Create requirements, tasks, defects
  • Update Work Item — Modify fields, update roles, append content
  • Node Workflow (Node Flow) — Complete/rollback nodes, batch workflow
  • Status Workflow (State Flow) — Transition defects/issues, close bugs