Feishu Project (Meego/Meegle) Operation Guide

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 Space Domain

project search

Searches space information, converts space name to project_key or verifies if the space exists.

Parameter	Type	Required	Description
--project-key	string	Yes	Space projectKey, simpleName or space name

WorkItem Domain

workitem create

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.

Parameter	Type	Required	Description
--work-item-type	string	Yes	Work item type
--project-key	string	No	Space identifier
--fields	array	No	List of field values, each containing field_key and field_value

workitem get

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.

Parameter	Type	Required	Description
--work-item-id	string	Yes	Work item ID or name
--project-key	string	No	Space key
--fields	array	No	field_key or field_name to query

workitem batch-get

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.

Parameter	Type	Required	Description
--work-item-ids	array	Either	List of work item IDs (comma-separated or passed multiple times)
--ids-file	string	Either	Read IDs from file (one per line, lines starting with `#` are comments)
--fields	array	No	List of field_key to query
--project-key	string	No	Space key

workitem update

Modifies field values or roles of the specified instance. Use

workflow update-node

to update node fields.

Parameter	Type	Required	Description
--work-item-id	string	Yes	Work item ID or name
--project-key	string	No	Space key
--fields	array	No	List of fields to update, each containing field_key and field_value
--role-operate	array	No	Role 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

Queries work item data using MQL. For syntax details, see references/mql-syntax.md.

Parameter	Type	Required	Description
--project-key	string	Yes	Space identifier (supports name, simpleName, projectKey)
--mql	string	Yes (session_id can be used instead for pagination)	MQL query statement (complete SQL)
--session-id	string	No	Pagination session ID, pass to paginate directly without parsing MQL
--group-pagination-list	array	No	Pagination 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

Views work item operation records.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--work-item-id	string	Yes	Work item ID

workitem meta-types

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.

Parameter	Type	Required	Description
--project-key	string	Yes	Space projectKey

workitem meta-fields

Gets available field configurations for the specified space and work item type (excluding disabled fields and role configurations).

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--work-item-type	string	Yes	Work item type key or name
--page-num	number	Yes	Page number, 50 items per page, starting from 1
--field-keys	array	No	Exact match field key or name
--field-query	string	No	Fuzzy query field key and name
--field-types	array	No	Filter by field type

workitem meta-roles

Gets the list of roles for the specified work item type. Used to confirm valid role_key before querying/creating/updating work items.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--work-item-type	string	Yes	Work item type key or name
--page-num	number	Yes	Page number, 50 items per page, starting from 1
--role-keys	array	No	Exact match role key or name
--role-query	string	No	Fuzzy query role key and name

workitem meta-create-fields

Views fields and types available when creating work items.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key

WorkFlow Domain

workflow transition

Only for node-flow work items, operates nodes to complete workflow or rollback.

Parameter	Type	Required	Description
--work-item-id	string	Yes	Work item ID
--action	string	No	confirm (workflow) / rollback (rollback)
--node-id	string	No	Node ID
--node-ids	array	No	List of node names or node IDs
--rollback-reason	string	No	Rollback reason, required when action=rollback
--project-key	string	No	Space key

workflow transition-state

Only for state-flow work items, transitions work item status. First use

workflow list-state-transitions

to get available transition states and transition_id.

Parameter	Type	Required	Description
--work-item-id	string	Yes	Work item ID
--transition-id	string	No	State transition ID, obtained from `workflow list-state-transitions`
--project-key	string	No	Space key

workflow get-node

Gets complete details of specified nodes or all nodes in the work item.

Parameter	Type	Required	Description
--work-item-id	string	Yes	Work item ID or name
--node-id-list	array	No	List of node IDs, pass empty or `_all` to get all nodes
--field-key-list	array	No	Node field keys, pass empty or `_all` to get all fields
--need-sub-task	boolean	No	Whether to include node subtasks
--page-num	number	No	Maximum 20 node items per page, returned page by page
--project-key	string	No	Space key

workflow update-node

Modifies nodes (schedule, owner, custom fields, etc.). Do not modify schedule/differentiated schedule/owner at the same time, call separately.

Parameter	Type	Required	Description
--work-item-id	string	Yes	Work item ID
--node-id	string	Yes	Node ID (node_key)
--node-owners	array	No	Array of node owner userkeys; pass empty array `[]` to clear
--node-schedule	object	No	Node schedule, format `{"estimate_start_date":ms,"estimate_end_date":ms,"owners":[userkey],"points":number}` ; pass `{}` to clear; omit if no change
--schedules	array	No	Differentiated 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
--fields	array	No	Node custom fields, each containing `field_key` and `field_value` (STRING protocol, see "Field Value Format")
--project-key	string	No	Space key

workflow list-state-transitions

Views the list of available status transitions for work items.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--work-item-id	string	Yes	Work item ID
--work-item-type	string	Yes	Work item type
--user-key	string	Yes	User identifier

workflow list-state-required

Views required information for transition (node_key for node flow, state_key for state flow).

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--work-item-id	string	Yes	Work item ID
--state-key	string	Yes	node_key for node flow or state_key for state flow
--mode	string	No	Default to query all required items; pass `unfinished` to query only uncompleted required items

workflow meta-node-fields

Views node field configurations.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--work-item-type	string	Yes	Work item type

MyWork Dashboard Domain

mywork todo

Queries current user's work item list by action type. Query to-dos/completed items without MQL.

Parameter	Type	Required	Description
--action	string	Yes	todo(pending)/done(completed)/overdue(overdue)/this_week(this week's pending)
--page-num	number	Yes	Page number, starting from 1, 50 items per page
--asset-key	string	No	Workspace key (format Asset_xxx), only pass when error requires selection

For complete results, continuously paginate from page_num=1 until empty.

WorkHour Domain

workhour list-schedule

Gets schedule and workload details for specified users within the time range.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--user-keys	array	Yes	User identifiers (name/email/userkey), maximum 20 at a time
--start-time	string	Yes	Start time, format YYYY-MM-DD
--end-time	string	Yes	End time, format YYYY-MM-DD, maximum 3 months per call
--work-item-type-keys	array	No	List 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

Views work hour registration records for work items.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--work-item-type	string	Yes	Work item type
--work-item-id	string	Yes	Work item ID

UserGroup Domain

user search

Queries basic user information in batches. Used to convert name/email to userkey.

Parameter	Type	Required	Description
--user-keys	array	Yes	userKey, Email or name, maximum 20
--project-key	string	No	Space key

user me

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

Views the list of teams under the space.

Parameter	Type	Required	Description
--project-key	string	No	Space key

team list-members

Views the list of team members.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--team-id	string	Yes	Team ID

View Domain

view get

Gets the list of work items under the view based on view ID.

Parameter	Type	Required	Description
--view-id	string	Yes	View ID
--project-key	string	No	Space key
--page-num	number	No	Starting page number for pagination
--fields	array	No	Fields to query

view search

Searches views by name.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--view-scope	string	Yes	View scope
--key-word	string	Yes	Keyword

view create-fixed

Creates a fixed view. Maximum 200 work items.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--name	string	Yes	View name
--work-item-type	string	Yes	Work item type
--work-item-id-list	array	Yes	List of work item IDs

view update-fixed

Updates a fixed view. Choose either add/remove_work_item_ids.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--view-id	string	Yes	View ID
--work-item-type	string	Yes	Work item type

Chart Domain

chart get

Views chart details.

Parameter	Type	Required	Description
--chart-id	string	Yes	Chart ID

chart list

Views the list of charts under the view.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--view-id	string	Yes	View ID

Comment Domain

comment add

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).

Parameter	Type	Required	Description
--work-item-id	string	Yes	Work item ID
--comment-content	string	Yes	Comment content

comment list

Views the list of comments.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--work-item-id	string	Yes	Work item ID

SubTask Domain

subtask update

Creates/modifies/completes/rolls back subtasks.

Parameter	Type	Required	Description
--node-id	string	Yes	Node ID
--work-item-id	string	Yes	Work item ID
--action	string	Yes	create/update/confirm/rollback

Relation Domain

relation list

Views the list of related work items.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key
--work-item-id	string	Yes	Work item ID
--relation-field-key	string	No	Related relation field key, obtained from `relation meta-definitions`
--relation-id	string	No	Related relation ID, obtained from `relation meta-definitions`
--node-id	string	No	Node ID, pass to query relations under a specific node
--page-num	number	No	Pagination page number, starting from 1
--page-size	number	No	Number of items per page, maximum 50

relation meta-definitions

Views related relation definitions under the space.

Parameter	Type	Required	Description
--project-key	string	Yes	Space key

Field Value Format (field_value)

🚨 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 Type	Semantics	field_value Parameter (Serialized according to the above convention)
template	Template ID (Required for creation)	`"145405865"` — obtained via `workitem meta-fields(field_keys=["template"])`
text / multi-pure-text / link / bool / number	Single literal value	`"Test work item"` / `"100"` / `"true"`
user	Single userkey	`"7509072868295085608"`
multi-user	Array of userkeys (stringified)	`"[\"7509072868295085608\",\"7509072868295085609\"]"`
select / radio / tree-select	Enumeration option_id	`"437794"`
multi-select	Array of option_id objects (stringified)	`"[{\"option_id\":\"111\"},{\"option_id\":\"222\"}]"`
tree-multi-select	Array of option_id strings (stringified)	`"[\"id1\",\"id2\"]"`
multi-text	Rich text Markdown string (see references/rich-text-editor-markdown-syntax.md for syntax)	`"Bold content"`
date	Millisecond timestamp (day precision)	`"1722182400000"`
schedule	`[start ms, end ms]` (stringified)	`"[1722182400000,1722355199999]"`
precise_date	Object (stringified)	`"{\"start_time\":1722182400000,\"end_time\":1722355199999}"`
workitem_related_select	Related work item ID	`"145405865"`
workitem_related_multi_select	Array of IDs (stringified, numeric elements)	`"[145405865,145405866]"`
role_owners (Only for creation)	Array of role-user objects (stringified)	`"[{\"role\":\"RD\",\"owners\":[\"userkey1\"]}]"`
signal	Pure string	`"true"` / `"false"` / `"null"`

Do not use fields to update roles, use the
role_operate
parameter of
workitem update
.

Related Work Item Fields (workitem_related_*)

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

Scenario	Command (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

After receiving user input, execute the following steps in order:

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).
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.
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
```
).
Execution: Call the target command, follow parallel/pagination rules in references/performance.md.

Parallel Processing and Large Results

See references/performance.md for details: parallel calls (serial-only links, combinable parallel calls), batch processing and pagination rules for large results.

Error Handling

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

Phenomenon	Troubleshooting/Fix
Space not found / Multiple spaces matching Chinese name	Verify via `project search` , use project_key for precise call
Work item type not found	Confirm valid type_key via `workitem meta-types`
Field name error / MQL returns empty but data exists	Confirm field key and type via `workitem meta-fields`
MQL query failed	Use `space_name`.`work_item_type` in FROM; use `array_contains` / `any_match` for array fields
Date range field query failed	Use subfield `__field_name_start_time`
Role query returns no results	Use `__{role_name}` format for role names in MQL
Duplicate user name/team name	Use `<id:xxxx>` to disambiguate in MQL (see MQL syntax reference)
User name→userkey conversion failed	Use `user search` for batch query
Personnel field write failed	Pass single userkey string for user; multi-user must be stringified like `"[\"k1\",\"k2\"]"`
node not found	First get real node_id via `workitem get` , no guessing allowed
Node workflow failed	Use `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 item	Obtain via `workitem meta-fields(field_keys=["template"])`
Role update failed	Use `role_operate` parameter of `workitem update` (do not use fields)
mywork.todo requires workspace selection	Pass `asset_key` (Asset_xxx) from error message list to retry

Standard Operating Procedures (SOP)

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

meegle

NPX Install

Tags

SKILL.md Content (Chinese)