# Command Recipes ## Resolve a View Use this first whenever the user gives a page URL or a `view_id`. ```bash meegle --profile default view list \ --project-key 69zyer \ --body-file ./examples/view-list.json \ --json ``` Interpretation: - `view_type = 2` -> fixed view -> use `view fix-items` - otherwise -> inspect whether `view panoramic-items` is the intended path ## Fetch Fixed View Items ```bash meegle --profile default view fix-items \ --project-key 69zyer \ --view-id sypbi-z60 \ --query-file ./examples/view-fix-items.json \ --json ``` Use the returned `work_item_id_list` as input to `workitem get`. ## Find a Version Work Item by Name Use this when the user speaks in business names such as “260312 version” or “gray release”. ```bash meegle --profile default workitem search filter \ --project-key 69zyer \ --body-file ./examples/version-search-filter.json \ --json ``` If multiple version items match: 1. surface the candidates 2. ask the user to confirm the intended version or pick the exact `id` ## Find Stories by `planning_version` Never pass the version display name directly into `planning_version`. Correct flow: 1. resolve the target version work item `id` 2. place that numeric `id` into `examples/story-by-planning-version.json` 3. run: ```bash meegle --profile default workitem search by-params \ --project-key 69zyer \ --type-key story \ --body-file ./examples/story-by-planning-version.json \ --json ``` ## Link an Issue to a Story Do not confuse relation definition management with instance-level linking. - `config relation ...` manages the rule itself - `workitem update --field ...` writes the actual relation field on a concrete item For an issue field such as `_field_linked_story`, write the related story ID directly: ```bash meegle --profile default --yes workitem update \ --project-key \ --type-key issue \ --id \ --field _field_linked_story= \ --json ``` Key rules: - use the related instance ID, not the item name - use the real field key from `workitem meta` - for relation-array fields, write the array on the right side, e.g. `field_key=[1,2]` - the CLI auto-hydrates `field_type_key` for shortcut relation writes ## Recover from `Invalid Param` / `Param missing` When a write command fails with: - `err_code = 20006` - `err_code = 20038` - `err_code = 50006` do not guess enum or option values. Use this order instead: 1. inspect the current workflow node ```bash meegle --profile default workflow query \ --project-key 69zyer \ --type-key story \ --id \ --json ``` If the item type is a custom state-flow type and you want an explicit override: ```bash meegle --profile default workflow query \ --project-key 69zyer \ --type-key \ --id \ --flow-type 1 \ --json ``` Rules: - default behavior is auto-detect; CLI retries with the correct `flow_type` after `20026/20027` - use `--flow-type 1` only when you need deterministic state-flow inspection for debugging 2. inspect required fields for the node ```bash meegle --profile default workflow required-info \ --project-key 69zyer \ --type-key story \ --id \ --node-id \ --mode unfinished \ --json ``` 3. inspect field metadata ```bash meegle --profile default workitem meta \ --project-key 69zyer \ --type-key story \ --json ``` Then retry with the real field structure: - `select / radio` -> real `option value` - relation fields -> instance IDs - if shortcut flags are ambiguous, use `--body-file` If an Agent needs one structured read before deciding how to write, prefer: ```bash meegle --profile default agent plan-write \ --project-key 69zyer \ --type-key story \ --id \ --json ``` ```bash meegle --profile default workflow preflight \ --project-key 69zyer \ --type-key story \ --id \ --node-id \ --json ``` ```bash meegle --profile default subtask preflight \ --project-key 69zyer \ --type-key story \ --id \ --node-id \ --task-id \ --json ``` ## Update Workflow Nodes with Shortcut Flags Use these shortcuts when the user wants to update node owners, schedule, estimate, or node fields directly. Update node info: ```bash meegle --profile default --yes workflow node-update \ --project-key 69zyer \ --type-key story \ --id \ --node-id dev \ --node-owners , \ --role-assignee RD= \ --points 6 \ --start 2026-01-05 \ --end 2026-01-06 \ --is-auto false \ --field field_deliverable="节点说明" \ --json ``` Complete a node and patch node data in the same request: ```bash meegle --profile default --yes workflow node-operate \ --project-key 69zyer \ --type-key story \ --id \ --node-id dev \ --action confirm \ --node-owners \ --role-assignee RD= \ --points 2 \ --is-auto false \ --field field_deliverable="节点交付物" \ --json ``` Rules: - node normal fields use `--field` - role-linked owners use repeatable `--role-assignee ROLE=USER1,USER2` - if only explicit values should change, pass `--is-auto false` - date-only `--end` is normalized to that day's `23:59:59.999` - CLI readbacks owner / schedule writes after mutation and will fail if the backend result does not match Update a role-linked state directly: ```bash meegle --profile default --yes workflow state-change \ --project-key 69zyer \ --type-key story \ --id \ --transition-id 12345 \ --role-owner RD=demo@example.com,on_demo \ --json ``` Rules: - `--role-owner ROLE=USER1,USER2` is repeatable - role identifiers may be role id, role name, or role alias - owners may be `user_key / email / out_id` - CLI resolves the request into canonical `role_owners` - CLI preflights the target state before sending the write and readbacks current state plus `role_owners` after success ## Update Subtasks with Shortcut Flags Update a subtask: ```bash meegle --profile default --yes subtask update \ --project-key 69zyer \ --type-key story \ --id \ --node-id doing \ --task-id \ --name "需求分析（已补充）" \ --role-assignee RD=, \ --points 5 \ --field due_date=2026-01-08 \ --deliverable field_deliverable="分析文档" \ --json ``` Complete / rollback a subtask and patch subtask data in the same request: ```bash meegle --profile default --yes subtask operate \ --project-key 69zyer \ --type-key story \ --id \ --node-id doing \ --task-id \ --action confirm \ --note "子任务已完成" \ --role-assignee RD= \ --points 8 \ --start 2026-01-03 \ --end 2026-01-04 \ --is-auto false \ --field due_date=2026-01-07 \ --deliverable field_deliverable="评审记录" \ --json ``` Rules: - subtask normal fields use `--field` - subtask deliverables use `--deliverable` - `--assignee ""` or `--role-assignee RD=` expresses clearing owners - date-only `--end` is normalized to that day's `23:59:59.999` - CLI readbacks note / owner / schedule writes after mutation and will fail if the backend result does not match - backend behavior for clearing a subtask note is unreliable; CLI now rejects `--note ''` and `{"note":null}` instead of sending an untrustworthy write ## PMO Baseline Workflow Use this order: 1. `view list` 2. `view fix-items` / `view panoramic-items` 3. `workitem get --fields ...` 4. `user resolve` 5. summarize the returned dataset Recommended PMO fields: - `name` - `owner` - `priority` - `description` - `work_item_status` - `start_time` - `exp_time` Recommended output dimensions: - total count - state distribution - current node distribution - owner concentration - missing priority - missing due date - creation/update time range ## Advance a Workflow to a Target Node / State Use `workflow advance` when the user asks for: - "flow this item to closed" - "push this story to analysis" - "advance this work item to end" State flow example: ```bash meegle --profile default --yes workflow advance \ --project-key 69zyer \ --type-key issue \ --id \ --target-state closed \ --json ``` Workflow / node flow example: ```bash meegle --profile default --yes workflow advance \ --project-key 69zyer \ --type-key story \ --id \ --target-node end \ --json ``` If the command stops with `ADVANCE_BLOCKED`, inspect: - `blocker_type` - `suggested_command` If a required field or role is already known, use an explicit override file: ```bash meegle --profile default --yes workflow advance \ --project-key 69zyer \ --type-key story \ --id \ --target-node end \ --overrides-file ./examples/workflow-advance-overrides.json \ --json ``` Key rule: - `workflow advance` may downgrade when `required-info = 50006` - that does not mean it will guess values - if the real transition still fails, stop and surface the blocker instead of inventing inputs ## Resolve Users for Human-Facing Reports When the dataset contains raw user identifiers, do not render them directly. Run: ```bash meegle --profile default user resolve \ --user-keys 7455245532160589843,7431336596441481218 \ --json ``` Use: - `resolved.display_name` for report display - `resolved.user_key` for stable machine identity Recommended display: - `Chinese Name (email-prefix)` If the input is already a report JSON, enrich it directly: ```bash meegle --profile default user enrich \ --field tech_owner_id \ --field reviewers \ --body-file ./examples/report-user-enrich.json \ --json ``` Default behavior: - keep the raw id field - add `*_display_name` - `--field` is repeatable - array fields also get `*_display_name` arrays ## Write Command Reminder In non-interactive environments: - add `--yes` only when the user explicitly approved a mutation - do not silently convert a read request into a write request ## Array Field Syntax When a field expects an array, keep the field key unchanged and put the array on the right side: ```bash meegle --profile default workitem update \ --project-key 69c14bca6a6ea882f04e99c2 \ --type-key story \ --id 6925794020 \ --field 'field_00cc24=[6925703508,6925703510]' \ --json ``` Do not use: ```bash --field 'field_00cc24[]=6925703508' ``` The CLI rejects `field_key[]=value` on purpose because it is ambiguous and easy for agents to misuse.