SuperAPI AI Directory

meegle-cli

General & other

View repository

Updated 10-16 09:44

About this skill

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 path is kept upstream-compatible as much as possible, and a small number of private extensions are explicitly marked. Commands and parameters are subject to the live CLI.

Default operating model:

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

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

Skill Execution Contract

SKILL.md is an 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 tiers, or capabilities from URLs, skill text, caches, or historical runs.
  • Read path cost budget: at most one meta-fieldsper work item type; at most one user queryper display page; 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 issue local formatting commands again just to display state/assignee. The default display must not list only ID + 名称; it must display the five columns ID、名称、当前状态、当前负责人、创建时间 .
  • State / enum label mapping execution mode: aftermeta-fields returns, 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 or other local parsing commands to re-extract the same metadata. When an exact state label is needed and the meta-fields output may be very large, you must directly attach a Python JSON reducer to the first and only meta-fields ; do not first run a normal 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 locations: 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 the fields container itself. Other than these,current_status_operator、priority、business、owner、watchers、role_owners、description、template、field_* Business fields such as these are always handled according to fields[] in field_key / field_alias ; do not, because of --select or a sample payload, treat business fields as top-level fields.
  • Default display gate before answering: 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 is a work item field; read it according to fields[] in field_key / field_alias ; do not treat it as a stable top-level field; if search-filter the current page did not return an 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 did not request raw / backfill, you must first perform one user query --user-keys ... backfill;created_at / updated_at is a millisecond timestamp, and by default it can be displayed using one local node / python3 converted 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 ... and complex jq / shell pipelines into one command; a local formatting failure should not pollute 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 parameters from path segments, no matter how obvious they look.

The work_item_type resolved from the URL is always handled first as api_name , not as a work_item_type_keythat can be passed directly to a business command. In workitem get、view list、workitem update、workflow.* and any other command that needs --work-item-type-key , you must first execute meegle workitem meta-types --project-key <simple_name> --format json, obtain api_name == <work_item_type> by exact match according to type_key; it is forbidden to fill in --work-item-type-key。

url_kind == workitem_detail directly from the URL, browser page, cache, historical runs, or guessed values. When url decode is used, always execute the following two commands, with parameters taken directly from theoutput; 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. A 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 repeatedly 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, first look at parameters[].flag(CLI directly executable flags), 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 first:

  1. meegle inspect ... --format json
  2. references/verified-command-surface.md
  3. In this directory's reference, 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: migrate to the replacement first, 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 's 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 via 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 presentation; 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 presentation; it does not reduce what the backend returns and does not change filter conditions. For a paginated workitem list, the CLI by default preserves 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 older version artifact is still in use.
  • 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, do not add --dry-runby default, 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:

  • 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, preferentially use the default auth whoami exposed by the current logged-in profile / project_key; when the user has already provided 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 provides 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.
  • For querying lists 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 asks for the latest N records / a small page of results for each value, split into multiple search-filter --page-size Nby value; do not upgrade 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。
  • requires confirming 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 for exact matching; fuzzy descriptions are uniquely resolved only among enabled candidates". Explicit specification (type_key, exact api_name, exact name) only performs exact hits; for fuzzy descriptions (such as "defect", "requirement", "iteration"), first filter out disabled types (is_disable != 1), auto-bind only when there is a single candidate; if not unique, ask a follow-up question. Do not use .[0], the first approximate item, or a generic api_name to answer without proper reasoning.
  • All --work-item-type-key / --work-item-type-keys input parameters must use the UUID returned by meta-types Returned UUID type_key; do not use story、story_new、issue、task、pdm、iteration and other api_name values as type keys for trial queries.
  • Need to confirm field keys, status values, or enum option values: 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 query field metadata.
  • Uncertain about command parameters, projection, or dry-run capability: first meegle inspect <resource>.<method> --format json. However, for the work item default read path already fixed by this skill/reference (meta-types、meta-fields、search-by-params、search-filter、workitem get), do not inspect。
  • For work item queries, current-user-related semantics, status mapping, and read-only budget rules, see references/workitem.mduniformly; the main text does not repeat 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 locally extract the title, dimensions, metrics, rankings, or summary based on that return; do not run a secondjq for different sort criteria, 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_sizefrom the return; do not, just because pagination.total is larger 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 ask to "continue/list all/export".

Complex Query Subject Priority Strategy:

For complex queries, first clarify the object type ultimately 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 associated with A", usually B is the query subject, andA is the filter anchor.

Before executing a complex query, clarify these four judgments internally; show them to the user only when the query is highly ambiguous 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's meta-fields。
  • If the query subject is a view, comment, sub-task, 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 an associated field, 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/owner/creation time.
  • Status, owner, version, iteration, business line, and time range are usually filter conditions; do not mistakenly treat them as the query subject.
  • The field key, status value, and enum option value of the work item subject are obtained from the meta-fields of that work item type; for non-work-item subjects, confirm parameters according to the corresponding reference and inspect .
  • The default displayed fields for work items are ID、名称、当前状态、当前负责人、创建时间, displaying the first 10 by default.
  • The default displayed fields for work items apply only to the final read of the query subject, not to filter anchor lookup. The final subject query must explicitly declare id,name,work_item_status,current_status_operator,created_at; the declaration list here may mix top-level fields and fields[] fields, but the read position must be handled according to the hard boundary of the field position. You may additionally fetch current_nodes as a fallback, but you must not 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 ID to fetch it once with workitem get --fields '["current_status_operator"]' , and do not directly mark it as not returned.
  • For status display, preferentially reuse the already-read meta-fields in work_item_status.options[] to perform the 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 additionally read meta-fields。
  • Person display must also be readable by default: preferentially reuse the label / namein the result; if the current display page has only user_key left and the user has not explicitly requested raw / no backfill, collect the unique keys of the current page and at most once 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 the status label, trim fields, and answer directly on the same result.
  • Only after completing the subject determination, choose search-filter、search-by-params、workitem get or view items。
  • Example: “query pending-discussion defects under a project” should be split into 查询主体=缺陷、筛选锚点=项目、过滤条件=状态待讨论, then query the “belonging project” field and the “pending discussion” status value in the defect type.
  • If the same task has already successfully obtained sufficient subject data to answer the question, immediately stop adding new business commands. In 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 titles, status mappings, rankings, or change the output style.

Query responsibility boundaries:

  • workitem search-filter: a 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: a general structured query path, usable for any work item type; anything involving custom fields, searchable related fields (according to live field_type_key ), or complex search_group combinations should use 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 enum small-page query (such as “latest 3 of each different status”): each bucket is an independent small-page read, directly using the corresponding built-in flag (such as --work-item-status、--priorities、--tags、--businesses、--user-keys) plus --page-size N; do not first use search-by-params to pull a large candidate set or wait for failure before fallback.
  • Do not assume that because the server may internally rewrite some search-filter as search-by-params, treat the two as the same capability level; externally, still choose commands according to the responsibilities above.

Pre-work-item-query checklist:

  • project_key: if the user explicitly provides simple_name , pass it directly; if not provided, prefer the current logged-in profile / auth whoami 's default project_key。
  • work_item_type_key: comes 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 comes from workitem meta-types 's UUID type_key array; do not probe first with an api_name array.
  • Field key: comes from workitem meta-fields, do not guess custom fields or relation fields by their Chinese field names.
  • Status / enum value: comes from meta-fields 's options[].value; map it back to the Chinese label when displaying.
  • Relation field value: use the numeric ID of the related work item, not the name, URL fragment, or string ID.
  • For current-user-related queries, display mappings, and relation field filtering details, see references/workitem.md and references/search-params-format.md。

Relation field query limitations:

  • search-by-params supports forward queries via workitem_related_select / work_item_related_select and workitem_related_multi_select / work_item_related_multi_select type fields (based on live field_type_key , query work items whose field value contains the specified work item ID)
  • does not support work_item_related searching of type fields
  • For reverse relation queries, prefer reading the relation field from the parent work item and then querying in batch; if the target type has a searchable relation field pointing to the parent work item, you can use search-by-params to query directly.

Rules for current-user-related semantics, assignee field filtering, list display trimming, one meta-fields / one final query, etc. 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, project, or product model/sub-platform but the user has not specified it, infer in the following order:

  1. If you need to display or fill in the business line name, you can refer to meegle auth whoami --format json 's business_line_names, but it only represents the business line read-only fallback context, not the general visible scope for ordinary work items; if you need the business line ID, use meegle space business-lines --project-key PROJ --format json to match by name and get id
  2. workitem meta-types --project-key <project_key> find the entry for api_name == pdm , and take its type_key; if you only need the current authorization summary, prefer meegle auth whoami --format json. If you need project details, the above "current-user-related work item query constraints" apply: for projects the current user participates in/is related to,workitem search-filter must explicitly add --user-keys '["<meegle_user_key>"]'; only when you want to see all project management work items in the space is it allowed to omit --user-keys; if you need stricter field-level personnel semantics or the current authorization/interface contract is not suitable for search-filter, then switch to workitem search-by-params
  3. 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 the result by business line on the client side

Rules for each step:

  • Single result → use it directly, do not ask
  • Multiple results → present as 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; the same session will not be asked repeatedly. Persistence is considered only when the user explicitly requests to save preferences or when the current environment clearly provides an available memory tool, to avoid unnecessary interruptions.

Recommended execution order

  1. When the user provides a URL:meegle url decode --url '<URL>' --format json, route according to url-kinds.md
  2. For complex queries, first perform the "query subject / filter anchor / filter conditions / display fields" assessment
  3. 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
  4. Read path discovery:view list、view items、workitem search-filter、workitem search-by-params、workitem get、workflow list-state-transitions
  5. Write operations:workitem create/update/remove/abort/restore/freeze/unfreeze、comment add/update/remove、subtask create/update/operate
  6. Clean up temporary or destructive test data after completion

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

Reference Routing

Read only the reference files needed for the current task.

Scenario Reference
Installation package 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
Field value input parameters / field_value shape / write select / rich text / relation fields and any other 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-by-params search_params construction / operator enumeration / 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 unsupported 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 upstream differences

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