meegle

Feishu Project (Meegle) private CLI operation guide

This skill operates Feishu Project data through the Meegle CLI. The output language follows the user's input language, defaulting to Chinese. The skill follows the organization approach of the upstream Meegle CLI skill. The core main paths are kept upstream-compatible as much as possible; a small number of private extensions will be explicitly marked. Commands and parameters are subject to the live CLI.

Default operating model:

Use the installed meegle CLI。
Access the private deployment through remote MCP Server + SSO login.

meegle doctor Used only in on-demand diagnostic scenarios: the user actively requests diagnostics, login/configuration is abnormal, business commands error but are difficult to locate, or inspect / execution results show that the command surface is suspected of drift,runtime_source != live. Do not treat doctor as a fixed prefix for business commands; for diagnostic details see references/runtime-private-remote-mcp.md。

Skill execution contract

SKILL.md is the execution entry point, not a collection of case transcripts. First select the task type, then read the corresponding reference; do not treat historical successful command sequences as a runtime source of truth.

Model read operations first: query subject, filter anchor, filter conditions, display fields. For the work item read path see references/workitem.md, for the view read path see references/view.md。
Model write operations first: target object, target field / target state, change intent, risk level, result verification. Creation, updates, node/state transitions, and release/deployment tasks must enter the corresponding SOP.
Model diagnostic operations first: symptoms, command surface,runtime_source, auth/config status, minimal reproduction command. For diagnostics and error self-healing see references/runtime-private-remote-mcp.md and references/error-handling.md。
Runtime facts come only from the CLI / backend:url decode、meta-types、meta-fields、inspect, verified command surface, or verified public CLI contract. Do not guess field keys, state values, personnel mappings, permissions, risk tier, or capability from URLs, skill text, caches, or historical runs.
Read path cost budget: for the same work item type at most one meta-fields; for the same display page at most one user query; the final query for each business objective is executed only once. After the final query succeeds, only local mapping, trimming, sorting, and formatting are allowed.
Default display page execution mode: business commands are only responsible for fetching data; the final answer is manually organized directly based on the JSON returned by the command. Do not send local formatting commands again for status/owner display. The default display must not list only ID + 名称; it must display ID、名称、当前状态、当前负责人、创建时间 five columns.
State / enum label mapping execution mode:meta-fields After returning, read the required options[]directly from the current command return; do not run a second meta-fields, do not redirect meta-fields to a temporary file, and do not use jq / rg / grep / sed / head and other local parsing commands to re-extract the same metadata. When precise state labels are needed and meta-fields output may be very large, a Python JSON reducer must be attached directly to the first and only meta-fields ; do not first run ordinary meta-fields, then run meta-fields | python3. This is local trimming after one business read, not a second metadata query.
Hard boundary for work item field positions: the stable fields that can be read directly at the top level include only id、name、current_nodes、work_item_status、created_at、updated_at、created_by、updated_by、deleted_at、deleted_by、work_item_type_key、project_key、simple_name、pattern、sub_stage、template_id、template_type, and fields the container itself. Other than that,current_status_operator、priority、business、owner、watchers、role_owners、description、template、field_* Business fields are always read according to fields[] in field_key / field_alias ; do not treat business fields as top-level fields because of --select or a sample payload.
Default display answer pre-gate: if this round has already read meta-fields, the "current status" in the final answer must first be mapped using work_item_status.options[] , and raw state_key；current_status_operator must not be displayed; it is a work item field, read according to fields[] in field_key / field_alias , and do not treat it as a stable top-level field; if search-filter the current page did not return the assignee but the ID has already been obtained, first use workitem get --fields '["current_status_operator"]' once on the current page ID to fetch it; if the assignee only has raw user_key and the user has not requested raw / no backfill, you must first perform one user query --user-keys ... backfill;created_at / updated_at is a millisecond timestamp, and for default display you may use one local node / python3 to convert to Asia/Shanghai, do not calculate it mentally. When the three types of display fields—incomplete status, assignee, and creation time—are not complete, do not output the final list or summary.
Execute business commands and local formatting separately. Do not chain meegle ... with complex jq / shell pipelines into a single command; a local formatting failure should not contaminate the business command result. On the default display page, do not redirect any meegle business command to /tmp, and do not rerun business commands for local processing.

URL entry rules

When the user provides a URL,the first command must be：

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

It is forbidden to guess any parameter from path segments, no matter how obvious it looks.

The work_item_type parsed from the URL is always first handled as api_name , not as work_item_type_keythat can be passed directly to a business command. Before workitem get、view list、workitem update、workflow.* or any command that requires --work-item-type-key , you must first execute meegle workitem meta-types --project-key <simple_name> --format json, and obtain api_name == <work_item_type> by exact match on type_keydirectly from the URL, browser page, cache, historical runs, or guessed values. --work-item-type-key。

url_kind == workitem_detail , always execute the following two commands, with parameters taken directly from url decode output,the command structure must not be modified：

# 命令 A：work_item_type 是 api_name，不是 UUID，必须先转换
meegle workitem meta-types --project-key <simple_name> --format json
# 从返回的 data[] 中找 api_name == <work_item_type> 的条目，取其 type_key 字段

# 命令 B：--work-item-ids 是复数，值是 JSON 数字数组字符串
meegle workitem get --project-key <simple_name> --work-item-type-key <type_key从A> --work-item-ids '[<work_item_id>]' --format json

workitem get the work_item_ids element type is number. The correct example is --work-item-ids '[20433995]'; do not write it as a string array --work-item-ids '["20433995"]', otherwise the live MCP schema will return Expected number, received string。

Other url_kind values are routed according to references/url-kinds.md ;chart_detail / view_chart, conditional views, unsupported URLs, and other details are maintained only in that file and are not expanded again in the main text.

Command surface authority

Commands and parameters are subject to the live CLI:

meegle inspect <resource>.<method> --format json

Treat inspect --format json as manifest-backed public parameter descriptor. When constructing commands, prioritize looking at parameters[].flag(flags directly executable by the CLI), projection metadata,runtime_source / snapshot_stale、deprecation.*; for field-level explanations see references/cli-guide.md。

When the documentation and the CLI's actual behavior are inconsistent, trust the following in order:

meegle inspect ... --format json
references/verified-command-surface.md
in the reference in this directory Private CLI 差异

If inspect shows:

runtime_source == "live": can be executed via the normal business path
runtime_source == "snapshot": only read-only diagnostics such as inspect / doctor are allowed;do not execute business write commands, and do not assume the command surface is still executable
deprecation.replacement exists: prioritize migrating to the replacement, and no longer treat the old command as the default path

When --select is involved, do not guess whether the command supports backend projection. First look at inspect --format json projection metadata, then decide whether to use --select or --output-select。

CLI execution semantics

Treat the main document as the decision entry point, and drill down into details according to Reference Routing. URL / view-type routing details are maintained only in references/url-kinds.md ; work item read paths, current-user-related semantics, status mapping, one meta-fields + one final query, and other details are maintained only in references/workitem.md ; the command support matrix is maintained only in references/verified-command-surface.md . Key principles:

First determine the flag semantic layer: request input enters the backend request; execution control controls execution; output display only affects local display; compat / lower-level is used only in command-specific compatibility scenarios.
--select is a backend field projection; use it only when inspect --format json declares projection.backend_select_supported == true .
--output-select only trims local display; it does not reduce what the backend returns and does not change filter conditions. For a paginated workitem list, the CLI by default retains the pagination.total/page_num/page_sizereturned by the backend; only when you want to further narrow the pagination metadata fields should you explicitly write pagination.xxx. If the current output does not contain pagination, first confirm whether that response originally had no pagination metadata, or whether an old version artifact is still being used.
For write operations, complex nested objects, time ranges, or clear troubleshooting scenarios, first use --dry-run to confirm the normalized request. For ordinary read-only queries, by default do not add --dry-runfirst, to avoid turning one query into two business commands.
destructive commands (comment remove、attachment delete、view delete) must include --confirm to execute; conditional commands output a stderr warning but do not block;risk_tier is viewed via inspect --format json .
For the complete rules on CLI semantic layers, command-specific flag disambiguation, projection, dry-run, and--fields compatibility boundaries, see references/cli-guide.md. Do not apply a similar flag from one command to another command.

Query main path

Query quick decision：

When the user provides a URL: in the first step, only do meegle url decode --url '<URL>' --format json, then route according to url_kind .
project_key is the space key. When the user does not explicitly specify a space, prefer the default auth whoami exposed by the current login profile / project_key; when the user has already given project_key / simple_name(such as cbg_product_develop), use it directly for --project-key. Do not run space list / space detailevery time just to "confirm the space." Enter the space discovery path only when the user gives only a Chinese space name, the current profile exposes multiple spaces and the task cannot determine which one, or the command explicitly requires a UUID.
When querying a list only by built-in dimensions such as name, time, status, priority, tag, business line, or current-user-related: prefer workitem search-filter. If the user enumerates multiple values of the same built-in dimension and requests the latest N items / a small page of results for each value, split them by value into multiple search-filter --page-size N; do not escalate to search-by-params and then process a large result.
For conditions involving custom fields, related fields, complex AND/OR, field-level personnel semantics, or conditions that search-filter cannot express: use workitem search-by-params。
needs to confirm the work item type: first workitem meta-types --project-key <project_key> --format json, and find type_keyaccording to the rule "explicit specification takes priority with exact matching; fuzzy descriptions are only uniquely resolved among enabled candidates." Explicit specification (type_key, exact api_name, exact name) only performs exact hits; fuzzy descriptions (such as "defect," "requirement," "iteration") first filter disabled types (is_disable != 1), only auto-bind when there is a unique candidate; if not unique, ask a follow-up. Do not use .[0], the first approximate item, or a generic api_name to answer hastily.
All --work-item-type-key / --work-item-type-keys input parameters must use the UUID meta-types returned by type_key; do not treat story、story_new、issue、task、pdm、iteration and other api_names as type keys for trial queries.
Need to confirm field key, status value, enum option value: first workitem meta-fields --project-key <project_key> --work-item-type-key <type_key> --format json。
workitem meta-fields is the field metadata command for querying, filtering, and display mapping;workitem meta-create-fields is only used for create-page/create-required fields; do not use it as a substitute for querying field metadata.
Unsure about command parameters, projection, or dry-run capability: first meegle inspect <resource>.<method> --format json. But for the default read path for work items already fixed by this skill/reference (meta-types、meta-fields、search-by-params、search-filter、workitem get), do not, for ordinary display, again inspect。
Work item queries, current-user-related semantics, status mapping, and read-only budget rules are all covered uniformly in references/workitem.md; the main text does not repeatedly maintain case-level details.
Chart URL / chart get scenarios follow the read path of "one live read, then only local organization":url decode -> chart get After one successful run, you must extract the title, dimensions, metrics, ranking, or summary locally based on that return; do not, for different sorting criteria,jq formatting, or field trimming, repeatedly execute a second chart get。
The work item list read-only path also follows the same "single live read" principle: if the first result already satisfies the default display page size, answer directly; if the task concerns an overall view beyond the current page, directly read the pagination.total/page_num/page_sizein the return; do not, because pagination.total is greater than the current page size, arbitrarily expand page-size 10 into 50 or rerun the same-condition query. To display more results, you must wait for the user to explicitly follow up with "continue/list all/export".

Priority strategy for the subject of complex queries：

For complex queries, first clarify the final object type to be returned, then query the filter anchor and field metadata. The object the user mentions first is not necessarily the query subject; in "query B of A / B under A / B related to A", usually B is the query subject, andA is the filter anchor.

Before executing a complex query, first clarify these four judgments internally; show them to the user only when the query ambiguity is large or user confirmation is needed:

查询主体：
筛选锚点：
过滤条件：
展示字段：

If the query subject is a work item, the subject determines work-item-type-key, and also determines which type of meta-fields。
If the query subject is a view, comment, subtask, workflow status, or release/deployment task, first follow the corresponding reference and inspect, and do not apply the work item metadata path.
The filter anchor is used to narrow the scope; if the anchor is a work item, first locate the anchor ID, then find the field/parameter that limits the scope in the query subject type or corresponding reference.
When locating the anchor work item before filtering by related fields, if the anchor type has already been confirmed by meta-types , the anchor name query must include that anchor type's --work-item-type-keys '[\"TYPE_KEY\"]'; do not first run a bare name query without the type and then self-heal.
The anchor name query is not a default display query: use workitem search-filter --work-item-name "名称" --output-select id,name --page-size 10 --format json, do not pass --query / --keyword / --select, and do not require status/assignee/creation time.
Status, assignee, version, iteration, business line, and time range are usually filter conditions; do not misjudge them as the query subject.
The work item subject's field key, status value, and enum option value are obtained from the work item type's meta-fields ; for non-work-item subjects, confirm parameters according to the corresponding reference and inspect .
The work item default display fields are ID、名称、当前状态、当前负责人、创建时间, displaying the first 10 entries by default.
The work item default display fields apply only to the final read of the query subject, not to filter anchor lookup. The subject's final query must explicitly declare id,name,work_item_status,current_status_operator,created_at; the declaration list here can mix top-level fields and fields[] fields, but the read position must be handled with field-position hard boundaries. You may additionally fetch current_nodes as a fallback, but you cannot use current_nodes to replace work_item_status。current_status_operator is a work item field, read according to fields[] 's field_key / field_alias ;search-filter When the current page lacks an assignee, use the current page IDs to do one workitem get --fields '["current_status_operator"]' supplementary fetch; do not directly mark it as not returned.
Status display should preferentially reuse the already-read meta-fields in work_item_status.options[] to do value → label mapping; when metadata has not been read and the result already has current_nodes[].name , directly use the node name as the "current status/current stage". Do not do an extra second read of meta-fields。
for ordinary display. Personnel display by default must also be readable: preferentially reuse the label / namein the result; if the current display page only has user_key and the user has not explicitly requested raw / no backfill, collect the unique keys of the current page and do at most one user query batch backfill. On failure or when the user requests raw, display the original user_key and mark it as raw.
For a read-only display task, if the query result has already been obtained, do not execute the same query again just to "organize the output"; instead, locally map status labels, trim fields, and answer directly on the same result.
Only after completing the subject judgment, then choose search-filter、search-by-params、workitem get or view items。
Example: "query pending-discussion defects under a certain project" should be split into 查询主体=缺陷、筛选锚点=项目、过滤条件=状态待讨论, then query the "owning project" field and the "pending discussion" status value within the defect type.
If the same task has already successfully obtained subject data sufficient to answer the question, immediately stop adding new business commands. During the answer phase, local mapping, trimming, sorting, and formatting are allowed; it is not allowed to issue another round of the same business command just to supplement a title, supplement status mapping, supplement a ranking, or change the output style.

Query responsibility boundaries：

workitem search-filter: the simplified query path for common scenarios, suitable for fuzzy name matching and built-in dimension filtering (business line, time, status, priority, tag, user_keys).
workitem search-by-params: the general structured query path, usable for any work item type; all custom fields, searchable association fields (subject to live field_type_key ), and complex search_group combinations go through this path.
When both can express it, prefer workitem search-filter; when field-level conditions are needed, or the current authorization/interface contract is not suitable for search-filter , switch to workitem search-by-params。
Built-in dimension enumeration small-page query (e.g., "the latest 3 of each different status"): each bucket is an independent small-page read, directly use the corresponding built-in flag (e.g., --work-item-status、--priorities、--tags、--businesses、--user-keysplus --page-size N); do not first use search-by-params to pull a large candidate set or wait for failure before falling back.
Do not, because the server may internally rewrite some search-filter as search-by-params, treat the two as the same layer of capability; externally, still select commands according to the responsibilities above.

Work Item Query Pre-check List：

project_key: if the user explicitly provides simple_name pass it directly; if not provided, prefer the current logged-in profile / auth whoami default project_key。
work_item_type_key: from workitem meta-types, do not pass api_name as a UUID type key to commands that require a type key.
work_item_type_keys: likewise from workitem meta-types UUID type_key array; do not probe first with an api_name array.
field key: from workitem meta-fields, do not guess custom fields or related fields by Chinese field name.
status / enum value: from meta-fields of options[].value; map back to the Chinese label when displaying.
related field value: use the numeric ID of the related work item, not the name, URL fragment, or string ID.
For details on current-user-related queries, display mapping, and related field filtering, see references/workitem.md and references/search-params-format.md。

Related Field Query Restrictions：

search-by-params supports forward queries through workitem_related_select / work_item_related_select and workitem_related_multi_select / work_item_related_multi_select type fields (subject to live field_type_key ; query for work items whose field value contains the specified work item ID)
does not support work_item_related search for type fields
For reverse related queries, prefer reading the related field from the parent work item and then querying in batches; if the target type has a searchable related field pointing to the parent work item, you can query directly with search-by-params .

Rules such as current-user-related semantics, assignee field filtering, list display trimming, one meta-fields / one final query are uniformly governed by references/workitem.md .

Do not guess:

project_key
work_item_type_key
node_id
field key
enum option id
any parameter in a URL path segment (must go through url decode）

context inference

When a command requires a business line, owning project, or product model/sub-platform but the user has not specified it, infer in the following order:

meegle auth whoami --format json take business_line_keys/names; if a business line ID is needed, use meegle space business-lines --project-key PROJ --format json by name match to get id
workitem meta-types --project-key <project_key> find api_name == pdm entry, take its type_key; if only the current authorization summary is needed, prefer checking meegle auth whoami --format json. If project details are needed, the above "Current-User-Related Work Item Query Constraints" applies: for projects the current user participates in or is related to,workitem search-filter must explicitly add --user-keys '["<meegle_user_key>"]'; only when viewing all project management work items in the space is it allowed to omit --user-keys; if stricter field-level personnel semantics are needed or the current authorization/API contract is not suitable for search-filter, then switch to workitem search-by-params
same as above, find api_name == product_type 's type_key; then use workitem search-filter --work-item-type-keys '[<type_key>]' to get the product model/sub-platform, and filter results by business line client

Rules for each step:

single result → use directly, do not ask
multiple results → present a numbered list and wait for the user to choose; when there are multiple business lines, choose the business line first, then use the business line ID to filter subsequent queries

Inference results are cached only within the current session; do not ask repeatedly within the same session. Only when the user explicitly requests saving preferences, or the current environment explicitly provides a usable memory tool, should persistence be considered, to avoid unnecessary interruptions.

Recommended execution order

When the user provides a URL：meegle url decode --url '<URL>' --format json, route according to url-kinds.md
For complex queries, first perform the "query subject / filter anchor / filter conditions / display fields" assessment
Confirm the space, subject type, and anchor: for work item subjects use workitem meta-types / meta-fields; for non-work item subjects, enter the corresponding reference according to Reference Routing, and use inspect to confirm parameters
Read path discovery:view list、view items、workitem search-filter、workitem search-by-params、workitem get、workflow list-state-transitions
Write operations:workitem create/update/remove/abort/restore/freeze/unfreeze、comment add/update/remove、subtask create/update/operate
Clean up temporary or destructive test data after completion

Concurrency rules: Commands without dependencies are issued in parallel; those with dependencies must be serial. For paginated queries, read the first page to get the total count, page as needed, and select only necessary fields.

Reference Routing

Only read the reference files needed for the current task.

Scenario	Reference
Installer CLI syntax, inspect, output format	references/cli-guide.md
Private remote MCP, SSO, authorization pre-checks, doctor failures	references/runtime-private-remote-mcp.md
verified / conditional / unsupported command selection	references/verified-command-surface.md
Copyable CLI examples	references/api-examples.md
Work item read paths, type/field metadata, default display, status/person readability, cost budget	references/workitem.md
Workflow queries, required fields, node/status transition assistance	references/workflow.md
Create work item SOP: target object, fields, template, risk, post-creation verification	references/sop-create-workitem.md
Update work item SOP: target fields, field_value shape, pre-write/post-write verification	references/sop-update-workitem.md
Node transition SOP: node, required fields, post-transition verification	references/sop-transition-node.md
Status transition SOP: target status, transition_id, required fields, post-transition verification	references/sop-transition-state.md
Release/deployment task SOP: release context, conditional writes, safety gates, result verification	references/sop-deploy-task-release.md
URL parsing and SOP routing	references/url-kinds.md
View queries,`view items -> workitem get`, conditional view capability gate	references/view.md
Attachment upload/download	references/attachment.md
Low-frequency commands such as comments, space teams, subtasks	references/misc.md
Error self-healing and circuit breaking	references/error-handling.md
Any field such as field value input / field_value shape / write select / rich text / related fields	references/field-value-format.md(must read before constructing any field_value)
Convert related work item names to IDs	references/field-value-extras.md
search_params construction for search-by-params / operator enum / fixed param_key / related field ID lookup	references/search-params-format.md(must read before constructing any search_params)
⚠️ MQL syntax background (private CLI currently does not support MQL commands, for understanding syntax background only; cannot be used for actual commands)	references/mql-syntax.md
Rich text Markdown syntax	references/rich-text-editor-markdown-syntax.md

General principles of upstream differences

There are still a few differences between the current public CLI and upstream; see the full list in references/verified-command-surface.md。