@thinkingai/ae-cli 6.1.12 → 6.1.14

package/skills/ae-dataops/SKILL.md

@@ -17,7 +17,7 @@ The AE Data Development and Operations domain provides capabilities for data war
 |------------|----------------|------------------------------|
 | `dataops_repo` | Space discovery | — |
 | `dataops_datatable` | Data table and view management | `dataops-table` |
-| `dataops_flow` | Flow creation and orchestration | `dataops-flow-create` |
+| `dataops_flow` | Flow creation, node deletion, and orchestration | `dataops-flow-create` |
 | `dataops_flow` | Flow execution and monitoring | `dataops-flow-monitor` |
 | `dataops_operations` | Operations instance search, details, and task logs | `dataops-flow-monitor` |
 | `dataops_ide` | Data exploration and SQL queries | `dataops-query` |
@@ -89,7 +89,7 @@ You must understand the following key concepts before use, otherwise errors are
 ### Flow Lifecycle
 
 ```
-Create DEV Flow → Create/Update DEV SQL, Integration, or Workflow Instance Check Tasks → Configure Dependencies/Schedule → Preview Release → Release to PROD → PROD Manual Execution / Operations Troubleshooting
+Create DEV Flow → Create/Update DEV SQL, Integration, Workflow Instance Check, or Task Instance Check Tasks → Configure Dependencies/Schedule → Preview Release → Release to PROD → PROD Manual Execution / Operations Troubleshooting
 ```
 
 ### CRON Format (6 fields)
@@ -112,7 +112,7 @@ Choose the appropriate scenario skill based on user intent to get complete step-
 
 | User Intent | Trigger Skill | Keywords |
 |-------------|---------------|----------|
-| Create flow, add nodes, configure schedule, release | `dataops-flow-create` | create flow, new workflow, configure schedule, add task node, release, cron, scheduled execution |
+| Create flow, add or delete nodes, configure schedule, release | `dataops-flow-create` | create flow, new workflow, configure schedule, add task node, delete task node, release, cron, scheduled execution |
 | View execution status, troubleshoot failures, view logs | `dataops-flow-monitor` | execute flow, running instance, monitor, logs, stop, DAG, troubleshoot |
 | Search operation instances across a space | `dataops-flow-monitor` | operations instance, flow instance search, status statistics, owner statistics |
 | Create datasource, configure sync solution, execute sync | `dataops-integration` | datasource, sync, integration, field mapping, data ingestion, MySQL, ClickHouse, DatabricksJdbc |
@@ -159,6 +159,7 @@ Detailed creation/configuration commands live in [`references/dataops-flow-creat
 
 Key constraints:
 - Create and update tasks in DEV, preview/release before PROD execution.
+- Treat `+delete_task` as high-risk: verify the target with `+get_flow_overview`, preview with `--dry-run`, and use `--yes` only after explicit user confirmation. Deletion affects DEV; release the flow to apply it to PROD.
 - `+execute_flow` always runs PROD; it returns `executeId` for early stop.
 - Prefer `flowInstanceId` from operations search for stable inspection and troubleshooting.
 - Reference workspace parameters in task SQL as `${paramKey}`.

package/skills/ae-dataops/references/dataops-flow-create.md

@@ -63,7 +63,9 @@ ae-cli dataops_flow +update_integration_task --spaceCode "${spaceCode}" \
 
 Use `dataops_integration +list_sync_solutions` or `+get_sync_detail` to find the `syncId` first. These commands expose workflow `OFFLINE_SYNC` tasks only; app sync tasks are not part of this flow.
 
-### Step 4: Create or Modify Workflow Instance Check Task
+### Step 4: Create or Modify Instance Check Tasks
+
+#### Workflow instance check
 
 `checkItems` is a flat JSON array. Every item contains only `flowCode`, `left`, `right`, and `checkTimeUnit` (`DAY`, `HOUR`, or `MINUTE`). One `AND` or `OR` relation applies to the entire array; nested groups are not supported. For the current workflow, `left` and `right` are at least `1`; for another workflow they may be `0`; `right` must not exceed `left`.
 
@@ -80,6 +82,23 @@ ae-cli dataops_flow +update_workflow_instance_check_task --spaceCode "${spaceCod
 
 Create defaults are `relation=AND`, `checkInterval=5`, `checkTime=3`, `failRetryTimes=3`, `failRetryInterval=5`, and `failRetryUnit=MINUTE`. On update, omitted check scalars, dependencies, and retry fields keep their current values.
 
+#### Task instance check
+
+Each task instance `checkItems` entry contains only `flowCode`, `taskCode`, `left`, `right`, and `checkTimeUnit`. The nested `checkItems[].taskCode` identifies a target task inside that item's `flowCode`. On update, the top-level `--taskCode` identifies the TASK_CHECK node to update; it is not a target task code. Use `+get_flow_overview` to discover target task codes. Checking the TASK_CHECK node itself is supported.
+
+```bash
+ae-cli dataops_flow +create_task_instance_check_task --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --taskName "Wait for target tasks" \
+  --checkItems '[{"flowCode":10037355068544,"taskCode":10380350567040,"left":1,"right":1,"checkTimeUnit":"DAY"},{"flowCode":10037355068545,"taskCode":10380350567041,"left":0,"right":0,"checkTimeUnit":"HOUR"}]' \
+  --relation OR
+
+ae-cli dataops_flow +update_task_instance_check_task --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --taskCode ${taskCheckNodeCode} \
+  --checkItems '[{"flowCode":10037355068544,"taskCode":10380350567040,"left":1,"right":1,"checkTimeUnit":"DAY"}]'
+```
+
+Task instance check create defaults are `relation=AND`, `checkInterval=10`, and `checkTime=3`; retry defaults are `3`, `5`, and `MINUTE`. `checkItems` is required and replaces the complete target list. On update, omitted check scalars, dependencies, and retry fields keep their current values.
+
 ### Step 5: Modify SQL Task Content
 
 ```bash
@@ -89,6 +108,24 @@ ae-cli dataops_flow +update_sql_task --spaceCode "${spaceCode}" \
   --sql "SELECT * FROM dwd_user"
 ```
 
+### Delete a Task Node
+
+Verify the target with `+get_flow_overview` before any deletion. Preview the request first, then execute it only after explicit user confirmation:
+
+```bash
+ae-cli dataops_flow +get_flow_overview --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode}
+
+ae-cli dataops_flow +delete_task --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --taskCode ${taskCode} --dry-run
+
+# Run only after explicit user confirmation
+ae-cli dataops_flow +delete_task --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --taskCode ${taskCode} --yes
+```
+
+`+delete_task` deletes exactly one non-placeholder task node in DEV. It removes attached DAG edges but does not reconnect upstream and downstream nodes. It may terminate running DEV debug executions that include the node and does not repair cross-flow `TASK_CHECK` references. A published PROD node remains until the flow is released again. Repeated deletion, a task from another flow, or an internal placeholder returns an error.
+
 ### Step 6: Add Task Dependencies (DAG connections)
 
 ```bash
@@ -153,6 +190,9 @@ ae-cli dataops_operations +get_task_instance_detail --spaceCode "${spaceCode}" \
 | `+update_integration_task` | Rebind DEV integration sync task to a sync solution | `--spaceCode` `--flowCode` `--taskCode` `--syncId` `[--preTasks]` `[--failRetryTimes]` `[--failRetryInterval]` `[--failRetryUnit]` |
 | `+create_workflow_instance_check_task` | Create DEV workflow instance check task | `--spaceCode` `--flowCode` `--taskName` `--checkItems` `[--relation]` `[--checkInterval]` `[--checkTime]` `[--preTasks]` `[retry flags]` `[--remark]` |
 | `+update_workflow_instance_check_task` | Update DEV workflow instance check task | `--spaceCode` `--flowCode` `--taskCode` `--checkItems` `[--relation]` `[--checkInterval]` `[--checkTime]` `[--preTasks]` `[retry flags]` |
+| `+create_task_instance_check_task` | Create DEV task instance check task | `--spaceCode` `--flowCode` `--taskName` `--checkItems` `[--relation]` `[--checkInterval]` `[--checkTime]` `[--preTasks]` `[retry flags]` `[--remark]` |
+| `+update_task_instance_check_task` | Update DEV task instance check task | `--spaceCode` `--flowCode` `--taskCode` `--checkItems` `[--relation]` `[--checkInterval]` `[--checkTime]` `[--preTasks]` `[retry flags]` |
+| `+delete_task` | Delete one DEV task node after confirmation | `--spaceCode` `--flowCode` `--taskCode` `--yes` |
 | `+add_task_relation` | Add DEV dependency | `--spaceCode` `--flowCode` `--preTaskCode` `--taskCode` |
 | `+save_schedule_config` | Save DEV schedule config | `--spaceCode` `--flowCode` `--enabled` `[--cron]` |
 | `+get_task_params` | View DEV task parameter list | `--spaceCode` `--flowCode` `--taskCode` |
@@ -169,14 +209,16 @@ ae-cli dataops_operations +get_task_instance_detail --spaceCode "${spaceCode}" \
 - **Schedule config**: `+save_schedule_config` requires `--spaceCode`, `--flowCode`, and `--enabled`. `--cron` is required only when `--enabled true`; omit it when disabling scheduling. It returns `action/result/status`; `result` includes `enabled`, `flow`, `message`, and `cron` only when enabled.
 - **Release preview**: `+preview_release_flow` requires `--spaceCode` and `--flowCode`; it has no optional flags. It returns `flowCode`, `releaseStatus`, `message`, and `changes`. Each change may include `scheduleConfigChange` and `tasks`; task entries may include `changed`, `contentCompare`, and `targetTable`.
 - **Release**: `+release_flow` requires `--spaceCode` and `--flowCode`; it has no optional flags. It returns `action/result/status`; `result` includes `flowCode`, `releaseStatus`, `message`, optional `packageCode`, and optional `changes`. Each change may include `scheduleConfigChange` and `tasks`; task entries include `changed`.
-- **Task dependencies**: `--preTasks` is a JSON array of upstream task codes on SQL, integration, and workflow instance check create/update commands. Omit `--preTasks` on update to preserve existing dependencies; pass `--preTasks '[]'` to clear them; pass a non-empty array to replace them.
-- **Retry policy**: The three task types accept `--failRetryTimes`, `--failRetryInterval`, and `--failRetryUnit`. Create defaults to `3`, `5`, and `MINUTE`. Update preserves every omitted retry field. `MINUTE` is the only supported unit.
+- **Task dependencies**: `--preTasks` is a JSON array of upstream task codes on SQL, integration, workflow instance check, and task instance check create/update commands. Omit `--preTasks` on update to preserve existing dependencies; pass `--preTasks '[]'` to clear them; pass a non-empty array to replace them.
+- **Retry policy**: All four task types accept `--failRetryTimes`, `--failRetryInterval`, and `--failRetryUnit`. Create defaults to `3`, `5`, and `MINUTE`. Update preserves every omitted retry field. `MINUTE` is the only supported unit.
 - **SQL task creation**: `+create_sql_task` requires `--spaceCode`, `--flowCode`, `--taskName`, and `--sql`; SQL hooks, dependencies, retry policy, and remark are optional. It returns `action/result/status`; `result` includes `flowCode`, `taskCode`, `taskName`, `taskType=TRINO_SQL`, and `sqlSaved=true`.
 - **SQL task update**: `+update_sql_task` requires `--spaceCode`, `--flowCode`, `--taskCode`, and `--sql`; omitted SQL hooks, dependencies, and retry fields keep existing values. It returns `action/result/status`; `result` includes `sqlSaved`, `flowCode`, `taskCode`, `taskType=TRINO_SQL`, and `task`.
 - **Task dependency**: `+add_task_relation` requires `--spaceCode`, `--flowCode`, `--preTaskCode`, and `--taskCode`. `preTaskCode` is upstream and `taskCode` is downstream. It returns `action/result/status`; `result` includes `status`, `flowCode`, `preTaskCode`, `taskCode`, and `message`.
 - **Task parameters**: `+get_task_params` requires `--spaceCode`, `--flowCode`, and `--taskCode`; it has no optional flags. It queries DEV and returns `data` as an array. Items include fields such as `paramKey`, `paramType`, `paramDataType`, `paramFrom`, and built-in flags like `isBd`.
 - **Integration task creation**: `+create_integration_task` requires `--spaceCode`, `--flowCode`, `--taskName`, and `--syncId`; dependencies, retry policy, and remark are optional. It returns `action/result/status`; `result` includes `syncTaskSaved`, `flowCode`, `taskCode`, `taskName`, `taskType=OFFLINE_SYNC`, `syncId`, and `nextAction`.
 - **Workflow instance check tasks**: `checkItems` is required and replaces the complete check item list. Create defaults `relation/checkInterval/checkTime` to `AND/5/3`; update preserves omitted scalar values. This command creates `FLOW_CHECK`, not task-instance `TASK_CHECK`.
+- **Task instance check tasks**: `checkItems` is required and replaces the complete check item list. Each item identifies a target using `flowCode` and `taskCode`. Create defaults `relation/checkInterval/checkTime` to `AND/10/3`; update preserves omitted scalar values. This command creates `TASK_CHECK`.
+- **Task deletion**: `+delete_task` requires `--spaceCode`, `--flowCode`, and `--taskCode`. It is a `high-risk-write`: inspect the node with `+get_flow_overview`, run `--dry-run`, obtain explicit confirmation, and then pass `--yes`. It changes DEV only; release the flow to apply deletion to PROD.
 
 ## Transport Status
 
@@ -186,6 +228,8 @@ Owning module: gaia-mcp workflow
 
 Current transport: DataOps CLI REST
 
+Covered workflow tools: `flow_create_workflow_instance_check_task`, `flow_update_workflow_instance_check_task`, `flow_create_task_instance_check_task`, `flow_update_task_instance_check_task`, and `flow_delete_task`
+
 Gateway target: TBD after DataOps workflow Gateway schema review
 
 Review after: 2026-10-27

package/skills/ae-engage/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-engage
 version: 1.0.0
-description: "AE Engage capability gateway: config center, flows, push/config channels, strategies, templates, task management, and operation activities. Trigger words: config center, scene config, push channel, config channel, operation strategy, operation task, operation activity, template, config item, Engage, Hermes, engage-scene, engage-setting, engage-flow, engage-task, engage-activity."
+description: "AE Engage capability gateway: config center, flows, push/config channels, strategies, templates, task management, operation activities, and query lifecycle. Trigger words: config center, scene config, push channel, config channel, operation strategy, operation task, operation activity, query lifecycle, template, config item, Engage, Hermes, engage-scene, engage-setting, engage-flow, engage-task, engage-activity, engage-query."
 ---
 
 # ae-engage
@@ -33,7 +33,7 @@ Safety constraints:
 
 ## Overview
 
-The `ae-engage` package provides Hermes Engage capabilities across config items, flows, channel settings, and task data. Use capability-gateway commands through `ae-cli engage-flow|engage-task|engage-setting|engage-scene <resource> <action>`; low-frequency reports use the L3 references below.
+The `ae-engage` package provides Hermes Engage capabilities across config items, flows, channel settings, task data, and query lifecycle. Use capability-gateway commands through `ae-cli engage-flow|engage-task|engage-setting|engage-scene|engage-query <resource> <action>`; low-frequency reports use the L3 references below.
 
 Typical use cases include:
 
@@ -55,7 +55,7 @@ When the user mentions a product term below (including common Chinese UI labels)
 | **Push channel** | Project-level message push channels (Webhook, FCM, APNS, etc.) | `engage-setting` | `references/channel-list.md` | `channel-detail.md`, `add-channel.md` (**Webhook vs Client differ**: `url` = HTTP vs scene key; custom params `user:` vs `user:`/`client:`), `update-channel-status.md`, `delete-channel.md`, `channel-update-config.md`, `channel-test-send.md`, `channel_touch_limits_list.md` |
 | **Config channel** | Config-center Webhook/client config channels (not the same as push channels) | `engage-scene` | `references/scene-config-channel.md` | `channel-mgmt.md` (create/enable-disable/copy/delete workflows). User params in `config.customsParamList` require `columnName` with `user:` prefix (e.g. `user:#account_id`); preflight names with ae-analysis `analysis-meta property list/get`. |
 | **Operation strategy** | Ops/delivery strategies under a config item | `engage-scene` | `references/scene-strategy.md` | Custom audience: [`scene-strategy-audience.md`](references/scene-strategy-audience.md) — semantic `definitionRequest` (Analysis condition shape); do not pass `targetClusterQp`/`qp`; preflight props (stop + list if missing); template: `scene-template.md` |
-| **Operation task** | Hermes push/engagement tasks (list, save, lifecycle, reports) | `engage-task` | `references/task-list.md` | `task-detail.md` (get), `save-task.md`, `build-task-save-guide.md`, `task-stats.md`, `task-delete.md`, `push-record-query.md`, `task-data-overview.md`, `task-data-detail.md`, `task-metric-detail.md`, `task-experiment-report.md` |
+| **Operation task** | Hermes push/engagement tasks (list, save, lifecycle, reports) | `engage-task` | `references/task-list.md` | `task-detail.md` (get), `save-task.md`, `build-task-save-guide.md`, `task-stats.md`, `task-delete.md`, `push-record-query.md`, `task-user-detail-export.md`, `task-indicator-user.md`, `task-data-overview.md`, `task-data-detail.md`, `task-metric-detail.md`, `task-experiment-report.md` |
 | **Operation activity** | Campaign activity management and delivery trends by activity, topic, or standalone task | `engage-activity` | `references/activity-activity.md` | `activity-data-detail.md`, `activity-topic.md`, `activity-task.md`, `activity-approval.md` |
 | **Template** | Strategy templates under a config item | `engage-scene` | `references/scene-template.md` | `scene-config-param.md` (template fields reference `paramId`); enable via `template update` then `template update-status` before strategy create |
 
@@ -175,10 +175,19 @@ ae-cli engage-task task get --project-id 1 --task-id task_123
 # Submit a saved draft task for approval
 ae-cli engage-task task submit-approval --project-id 1 --task-id task_123
 
+# Query task reports through the Hermes inline task-data capabilities
+ae-cli engage-task effect query --project-id 1 --task-id task_123 --start-time 2026-04-01 --end-time 2026-04-07 --metric-id-list '["metric_1"]'
+ae-cli engage-task data-detail query --project-id 1 --task-id task_123 --detail-type time --start-time 2026-04-01 --end-time 2026-04-07
+ae-cli engage-task indicator-user sql --project-id 1 --task-id task_123 --indicator main --start-time 2026-04-01 --end-time 2026-04-07
+ae-cli engage-task indicator-user run --project-id 1 --task-id task_123 --indicator secondary --secondary-index 1 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100
+ae-cli engage-task indicator-user export --project-id 1 --task-id task_123 --indicator metric --metric-id metric_1 --source metric --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv
+
 ```
 
 For L3 task reports, read `references/task-data-overview.md`, `references/task-data-detail.md`,
 `references/task-metric-detail.md`, or `references/task-experiment-report.md` before invocation.
+Before using `engage-task indicator-user`, read `references/task-indicator-user.md`; its grouping,
+indicator, summary/detail, metric, experiment, and timezone flags have conditional compatibility rules.
 
 ### 3. config
 
@@ -210,6 +219,7 @@ ae-cli engage-flow version list --project-id 1 --flow-id flow_id_123
 ae-cli engage-flow flow update-remark --project-id 1 --flow-uuid flow_uuid_123 --flow-version-desc "Second version"
 ae-cli engage-task operation-log query --project-id 1 --task-id task_id_123
 ae-cli engage-task push-record query --project-id 1 --task-id task_id_123 --page-num 1 --page-size 20
+ae-cli engage-task user-detail export --project-id 1 --task-id task_id_123 --task-instance-id instance_123 --user-status fail --artifact-format csv
 ae-cli engage-task segment-list query --project-id 1 --task-id task_id_123
 ae-cli engage-task group list --project-id 1
 ae-cli engage-task metric list --project-id 1 --task-id task_id_123
@@ -219,8 +229,29 @@ ae-cli engage-task task submit-approval --project-id 1 --task-id task_id_123
 
 # Query the node schema
 ae-cli engage-flow node-config schema --project-id 1 --node-type message_push
+ae-cli engage-flow metric update --project-id 1 --flow-id flow_id_123 --metric-map '<metric_map_json>'
+
+# Query or export newly exposed flow report surfaces
+ae-cli engage-flow report metric-detail run --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120
+ae-cli engage-flow report metric-detail export --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600
+ae-cli engage-flow metric-user run --project-id 1 --flow-id flow_id_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120
+ae-cli engage-flow metric-user export --project-id 1 --flow-id flow_id_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600
+ae-cli engage-flow node-user run --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120
+ae-cli engage-flow node-user export --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600
+ae-cli engage-flow node-metric-user run --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name metric_setting_id_123 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120
+ae-cli engage-flow node-metric-user export --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name metric_setting_id_123 --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600
 ```
 
+User-detail `run` commands are for bounded inline rows and accept `--request-id`, `--limit`, and `--timeout-seconds`; metric-detail `run` returns the report object. Export commands accept `--request-id`, `--artifact-format csv|jsonl` (default `jsonl`), and `--timeout-seconds`, then return `run_id` and `artifact_id`; poll with `ae-cli engage-query run inspect --run-id RUN_ID`, then download with `ae-cli engage-query artifact download --run-id RUN_ID --artifact-id ARTIFACT_ID --output ./artifact.jsonl.gz`. Cancel running async work with `ae-cli engage-query query cancel --run-id RUN_ID`.
+
+For flow report/user-detail commands, read the matching reference before composing non-trivial input:
+
+- Flow canvas custom metric configuration: `references/flow-metric-update.md`
+- Metric-detail report object or flattened report export: `references/flow-metric-detail-report.md`
+- Users behind a process-level metric segment: `references/flow-metric-user.md`
+- Users behind a node-level data segment: `references/flow-node-user.md`
+- Users behind a node-level metric segment: `references/flow-node-metric-user.md`
+
 ### 5. scene (scene management / config center)
 
 New capability-gateway command group `engage-scene` covers the config center: config items, params, groups, preset/related metrics, config channels, strategies, and templates. Complex DTOs are passed with `--payload` (native camelCase JSON).
@@ -442,6 +473,7 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `references/add-approver.md` / `references/approver-list.md` (`engage-setting.approval-approver.{add,list}`)
 - `references/whitelist-list.md` / `references/whitelist.md` (`engage-setting.whitelist.{list,add,update,delete,verify}`)
 - `references/cancel-query-by-request-id.md` (`engage-setting.query.cancel`, L3)
+- `references/cancel-query-run.md` (`engage-query.query.cancel`)
 - `references/push-language.md` (`engage-setting.push-language.{get,set}`)
 - `references/client-param.md` (`engage-setting.client-param.{create,update,delete,list}`)
 - `references/config-table.md` (`engage-setting.config-table.{upload,save,list,query-data,update-data,delete}`)
@@ -476,10 +508,15 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `references/version-list.md` (`engage-flow.version.list`)
 - `references/flow-update-remark.md` (`ae-cli engage-flow flow update-remark`; capability `engage-flow.version.update-remark`)
 - `references/push-record-query.md` (`engage-task.push-record.query`)
+- `references/task-user-detail-export.md` (`engage-task user-detail export`; capability `engage-task.user-detail.export`)
+- `references/task-indicator-user.md` (`engage-task indicator-user {sql,run,export}`; capabilities `engage-task.indicator-user.{sql,run,export}`)
 - `references/segment-list-query.md` (`engage-task.segment-list.query`)
 - `references/group-list.md` (`engage-task.group.list`)
 - `references/task-delete.md` (`engage-task.task.delete`)
 - `references/task-submit-approval.md` (`engage-task.task.submit-approval`)
+- `references/task-data-detail.md` (`engage-task data-detail query`; capability `engage-task.task-data.detail`)
+- `references/task-metric-detail.md` (`engage-task effect query`; capability `engage-task.task-data.metric-detail`)
+- `references/flow-metric-update.md` (`engage-flow metric update`; capability `engage-flow.metric.update`)
 
 This split documentation structure is easier to extend later, because commands with more complex object inputs can stay centralized in the `references/` root directory.
 
@@ -491,7 +528,11 @@ This split documentation structure is easier to extend later, because commands w
 
 ### task
 
-`operation-log query` / `push-record query` / `segment-list *` / `ops *` / `metric *` / `race release` / `channel-ref stats` / `group *` / `task delete` / `task modify-group` / `task submit-approval` / `task get` / `task list` / `task stats` / `task build-save-guide` / `task save` / `task manage` (via `engage-task`), plus L3 capabilities `engage-task.task-data.{overview,detail,metric-detail,experiment-report}`
+`operation-log query` / `push-record query` / `user-detail export` / `indicator-user sql` / `indicator-user run` / `indicator-user export` / `segment-list *` / `ops *` / `metric *` / `race release` / `channel-ref stats` / `group *` / `task delete` / `task modify-group` / `task submit-approval` / `task get` / `task list` / `task stats` / `task build-save-guide` / `task save` / `task manage` / `effect query` / `data-detail query` (via `engage-task`), plus L3 capabilities `engage-task.task-data.{overview,detail,metric-detail,experiment-report}`
+
+### query
+
+`run inspect` / `artifact download` / `query cancel` (via `engage-query`), capability ID `engage-query.query.cancel`
 
 ### config
 
@@ -511,7 +552,7 @@ Legacy config MCP commands are migrated into the `scene` L2 group and the three
 
 ### flow
 
-`operation-log query` / `version list` / `flow update-remark` / `flow save` / `node-config schema` / `flow get` / `flow list` / `flow manage` / `node-config validate` / `flow delete` / `flow modify-base-info` (via `engage-flow`), plus L3 capabilities `engage-flow.report.{node-overview,process,node-detail,ab-split-node}`
+`operation-log query` / `version list` / `flow update-remark` / `flow save` / `node-config schema` / `flow get` / `flow list` / `flow manage` / `node-config validate` / `flow delete` / `flow modify-base-info` / `metric update` / `report metric-detail run` / `report metric-detail export` / `metric-user run` / `metric-user export` / `node-user run` / `node-user export` / `node-metric-user run` / `node-metric-user export` (via `engage-flow`), plus L3 capabilities `engage-flow.report.{node-overview,process,node-detail,ab-split-node}`
 
 ## Date Format
 
@@ -532,8 +573,10 @@ For task draft creation or update, use this workflow:
 1. `ae-cli engage-setting channel list --project-id <projectId>`
 2. `ae-cli engage-task task build-save-guide --project-id <projectId> --req '{...}'`
 3. For a custom audience, pass the Analysis semantic contract as
-   `targetConfig.definitionRequest`. Use semantic `triggerConfig.triggerDefinition` and
-   `completionIndicatorDef.completionIndicators[].eventDefinition`. Build shapes from
+   `targetConfig.definitionRequest`. For an event-triggered task, use semantic
+   `triggerConfig.triggerDefinition` and
+   always include `periodTimeSymbol` (`TS01`, `TS02`, `TS03`, or `TS04`) on its primary A rule.
+   Use semantic `completionIndicatorDef.completionIndicators[].eventDefinition`. Build shapes from
    `ae-analysis` user-cluster / audience models. For existing-cluster audiences
    (`targetClusterType=2`), use `analysis user-cluster get`. For event-triggered tasks, pass
    `channelType`, `triggerType`, and `eventTriggerType` to `build-save-guide`, then use its
@@ -546,6 +589,11 @@ For task draft creation or update, use this workflow:
 5. `ae-cli engage-task task submit-approval --project-id <projectId> --task-id <taskId>`
 
 `engage-task task build-save-guide` is a read-only helper. It returns scenario-specific required fields, channel content schema, unsupported combinations, examples, and a handoff template for `save_task`.
+When `enableExp=true`, capability `engage-task.task.build-save-guide` enriches the handoff so
+`groupContentList` association fields
+(`expGroupName`/`expGroupType`/`percentageInExperiment`/`order`) stay aligned with
+`expConfig.expGroupList`; only replace `contentList[].content`. Capability `engage-task.task.save`
+rejects misaligned experiment content with `TASK_EXPERIMENT_GROUP_CONTENT_INVALID`.
 
 `engage-task task save` creates or updates a task configuration. It does not submit approval, does not start sending, and does not trigger task execution. If `req.taskId` is omitted it creates a new draft; if `req.taskId` is present it updates an existing **draft or paused** task. Update mode rejects running/ended tasks with `invalid_status`. Omitted fields inherit from the existing task before validation (partial rename/update is supported).
 

package/skills/ae-engage/references/build-task-save-guide.md

@@ -224,6 +224,12 @@ Use it to understand what must appear in:
 - `controlConfig`
 - `expConfig` when experiment mode is enabled
 
+When experiment mode is enabled (`context.enableExp=true` or draft `expConfig.enableExp=true`):
+
+- capability `engage-task.task.build-save-guide` enriches `handoff.reqTemplate.channelConfig.groupContentList`
+  so each entry carries `expGroupName`, `expGroupType`, `percentageInExperiment`, `order`, and `contentList`
+- do not drop those association fields when filling content; they must stay aligned with `expConfig.expGroupList`
+
 ### 4.8 `fieldRules`
 
 This is the most important construction section.
@@ -274,6 +280,10 @@ The guide treats the A rule as a discriminated envelope:
 - `eventTriggerType=2`: at least two ordered steps with `eventDefinition` and `hasDone`
 - `eventTriggerType=3`: client-side count/eq/1 events with `eventTriggerCaliberType`
 
+Every event-triggered task A rule must include `periodTimeSymbol`. Use `TS01` for daily,
+`TS02` for the complete configured period, `TS03` for weekly, or `TS04` for monthly.
+Do not omit this field even when `periodStart` and `periodEnd` are present.
+
 Do not copy the accumulated example and only change `eventTriggerType`. Hermes rejects a final QP
 whose event structure does not match its envelope.
 
@@ -299,6 +309,8 @@ Important fields:
 - `reqTemplate`
   - a scenario-aware grouped request template
   - use it as a starting point, not as unquestioned final truth
+  - for experiment tasks, keep `groupContentList` association fields from the template;
+    only replace `contentList[].content` with real channel content
 - `readyToSubmit`
   - `true` means the current scenario or draft has no blocking placeholders
 - `blockingPlaceholders`

package/skills/ae-engage/references/cancel-query-run.md

@@ -0,0 +1,31 @@
+# Cancel a running Engage query or export
+
+Cancel asynchronous Engage work by the Capability Gateway run ID.
+
+Mapped command:
+
+```bash
+ae-cli engage-query query cancel --run-id <run_id>
+```
+
+Mapped capability: `engage-query.query.cancel`
+
+## Input
+
+| Field | Type | Required | Description |
+|------|------|------|------|
+| `run_id` | string | Yes | Run ID returned by an asynchronous query or export capability |
+| `reason` | string | No | Optional cancellation reason |
+
+## Safety Constraints
+
+This command is a **write operation**. Use only the `run_id` returned by the asynchronous
+query/export lifecycle; a report `request_id` is not accepted.
+
+## Example
+
+```bash
+ae-cli engage-query query cancel \
+  --run-id run_123 \
+  --reason "No longer needed"
+```

package/skills/ae-engage/references/config-item-analysis-report.md

@@ -8,7 +8,20 @@ Required input: `project_id`, `config_id`, `start_time`, `end_time`. Optional in
 `template_id_list`, `strategy_id_list`, `show_time_zone`. `template_id_list` and `strategy_id_list`
 are mutually exclusive.
 
+## Input contract
+
+| Field | JSON type | Required | Rules |
+| --- | --- | --- | --- |
+| `project_id` | integer | Yes | Positive project ID. |
+| `config_id` | string | Yes | Config item ID. |
+| `start_time` | string | Yes | Date in `yyyy-MM-dd` format. |
+| `end_time` | string | Yes | Date in `yyyy-MM-dd` format; must not be earlier than `start_time`. |
+| `request_id` | string | No | Request identifier for continuation or cancellation. |
+| `template_id_list` | array of strings | No | Cannot be used together with `strategy_id_list`. |
+| `strategy_id_list` | array of strings | No | Cannot be used together with `template_id_list`. |
+| `show_time_zone` | number | No | Hour offset from `-12.0` through `14.0`; use `8`, not the string `"8"`. |
+
 ```bash
 ae-cli capability run engage-scene.report.config-item-analysis \
-  --input '{"project_id":1,"config_id":"cfg_123","start_time":"2026-04-01","end_time":"2026-04-07"}'
+  --input '{"project_id":1,"config_id":"cfg_123","start_time":"2026-04-01","end_time":"2026-04-07","show_time_zone":8}'
 ```

package/skills/ae-engage/references/config-item-strategy-comparison.md

@@ -7,7 +7,17 @@ Mapped command: `ae-cli capability run engage-scene.report.strategy-comparison -
 Required input: `project_id`, `config_id`, `strategy_id_list` with at least two IDs. Optional input:
 `request_id`, `show_time_zone`.
 
+## Input contract
+
+| Field | JSON type | Required | Rules |
+| --- | --- | --- | --- |
+| `project_id` | integer | Yes | Positive project ID. |
+| `config_id` | string | Yes | Config item ID. |
+| `strategy_id_list` | array of strings | Yes | Must contain at least two strategy IDs. |
+| `request_id` | string | No | Request identifier for continuation or cancellation. |
+| `show_time_zone` | number | No | Hour offset from `-12.0` through `14.0`; use `8`, not the string `"8"`. |
+
 ```bash
 ae-cli capability run engage-scene.report.strategy-comparison \
-  --input '{"project_id":1,"config_id":"cfg_123","strategy_id_list":["strategy_a","strategy_b"]}'
+  --input '{"project_id":1,"config_id":"cfg_123","strategy_id_list":["strategy_a","strategy_b"],"show_time_zone":8}'
 ```

package/skills/ae-engage/references/config-item-trigger-report.md

@@ -8,7 +8,21 @@ Required input: `project_id`, `config_id`, `start_time`, `end_time`. Optional in
 `template_id_list`, `strategy_id_list`, `show_time_zone`, `analyze_report_internal_query`.
 `template_id_list` and `strategy_id_list` are mutually exclusive.
 
+## Input contract
+
+| Field | JSON type | Required | Rules |
+| --- | --- | --- | --- |
+| `project_id` | integer | Yes | Positive project ID. |
+| `config_id` | string | Yes | Config item ID. |
+| `start_time` | string | Yes | Date in `yyyy-MM-dd` format. |
+| `end_time` | string | Yes | Date in `yyyy-MM-dd` format; must not be earlier than `start_time`. |
+| `request_id` | string | No | Request identifier for continuation or cancellation. |
+| `template_id_list` | array of strings | No | Cannot be used together with `strategy_id_list`. |
+| `strategy_id_list` | array of strings | No | Cannot be used together with `template_id_list`. |
+| `show_time_zone` | number | No | Hour offset from `-12.0` through `14.0`; use `8`, not the string `"8"`. |
+| `analyze_report_internal_query` | boolean | No | Use `true` or `false`, not a quoted string. |
+
 ```bash
 ae-cli capability run engage-scene.report.config-item-trigger \
-  --input '{"project_id":1,"config_id":"cfg_123","start_time":"2026-04-01","end_time":"2026-04-07"}'
+  --input '{"project_id":1,"config_id":"cfg_123","start_time":"2026-04-01","end_time":"2026-04-07","show_time_zone":8}'
 ```

package/skills/ae-engage/references/flow-metric-detail-report.md

@@ -0,0 +1,134 @@
+# Flow metric-detail report
+
+Use this reference when the user asks for a flow node metric-detail report, or wants to export the detailed metric table behind a node on the flow canvas.
+
+Mapped CLI commands:
+
+- `ae-cli engage-flow report metric-detail run`
+- `ae-cli engage-flow report metric-detail export`
+
+Mapped capabilities:
+
+- `engage-flow.report.metric-detail.run`
+- `engage-flow.report.metric-detail.export`
+
+## Choose the command
+
+- Use `run` for quick inline inspection. It returns the original Hermes report object under `report`.
+- Use `export` when the user needs a downloadable, flattened artifact.
+- Use `--report-mode node` or omit it for normal nodes.
+- Use `--report-mode ab` for AB split node metric details.
+
+Do not use the older generic capability form unless the structured command is unavailable.
+
+## Required input
+
+- `--project-id`
+- one of `--flow-id` or `--flow-uuid`
+- `--node-uuid`
+- `--start-time yyyy-MM-dd`
+- `--end-time yyyy-MM-dd`
+
+## Optional input
+
+- `--report-mode node|ab` (default: `node`)
+- `--branch-id`
+- `--indicator-name` for normal node metric selection
+- `--indicators-uuid` for AB metric selection
+- `--data-dim-type uv|pv`
+- `--push-language-code`
+- `--show-time-zone`
+- `--request-id`
+- `--timeout-seconds`
+- `run` only: `--limit` is accepted for command consistency, but metric-detail reports are not row-limited by Hermes
+- `export` only: `--artifact-format csv|jsonl` (default: `jsonl`)
+
+## Parameter guidance
+
+- Prefer `flow_uuid` when the user is talking about a specific flow version; prefer `flow_id` when they mean the current logical flow.
+- `node_uuid` must be the canvas node UUID, not the node type.
+- Dates are inclusive report dates and must be in `yyyy-MM-dd`.
+- For AB mode, pass the AB node UUID and usually `--indicators-uuid`; `--branch-id` is optional and only use it when the selected report cell is branch-specific.
+- If both `flow-id` and `flow-uuid` are supplied, Hermes checks they match.
+
+## Examples
+
+Inline normal node metric detail:
+
+```bash
+ae-cli engage-flow report metric-detail run \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --node-uuid node_uuid_123 \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --timeout-seconds 120
+```
+
+Export normal node metric detail as CSV:
+
+```bash
+ae-cli engage-flow report metric-detail export \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --node-uuid node_uuid_123 \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --artifact-format csv \
+  --timeout-seconds 21600
+```
+
+Inline AB node metric detail:
+
+```bash
+ae-cli engage-flow report metric-detail run \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --node-uuid ab_node_uuid_123 \
+  --report-mode ab \
+  --indicators-uuid indicator_uuid_123 \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07
+```
+
+## Export lifecycle
+
+`export` returns `run_id` and `artifact_id`. Poll and download with:
+
+```bash
+ae-cli engage-query run inspect --run-id <run_id>
+ae-cli engage-query artifact download \
+  --run-id <run_id> \
+  --artifact-id <artifact_id> \
+  --output ./flow-metric-detail.csv.gz
+```
+
+Downloaded artifacts are gzip-compressed; keep the `.gz` suffix. Cancel running async work with:
+
+```bash
+ae-cli engage-query query cancel --run-id <run_id>
+```
+
+## Output rows
+
+Normal node export rows:
+
+- `time`
+- `indicator`
+- `value_index`
+- `value`
+
+AB node export rows:
+
+- `time`
+- `branch_id`
+- `branch_name`
+- `indicator`
+- `value`
+- `total`
+
+## Common mistakes
+
+- Do not pass `report-mode ab` for a normal node; Hermes will call the AB report backend.
+- Do not use `indicator_name` and `indicators_uuid` interchangeably: normal node uses `indicator_name`, AB mode usually uses `indicators_uuid`.
+- Do not save a gzip artifact as `.csv` or `.jsonl`; use `.csv.gz` or `.jsonl.gz`.

package/skills/ae-engage/references/flow-metric-update.md

@@ -0,0 +1,77 @@
+# Flow metric update
+
+Use this reference when the user asks to configure, replace, or save effect metric settings for a flow canvas.
+
+Mapped CLI command:
+
+- `ae-cli engage-flow metric update`
+
+Mapped capability:
+
+- `engage-flow.metric.update`
+
+## Safety
+
+This is a write command. Only run it when the user explicitly asks to change a flow's metric configuration. Use `--dry-run` first when the final `metric_map` was assembled by an agent.
+
+The backend uses a clean-and-insert update model: omitted existing metric settings may be deleted. Treat `metric_map` as the complete desired metric configuration for the flow, not a partial patch.
+
+## Required input
+
+- `--project-id`
+- `--flow-id`
+- `--metric-map '<metric_map_json>'`
+
+## Parameter guidance
+
+- `flow_id` is the logical flow ID used by the flow canvas APIs.
+- `metric_map` is a JSON object keyed by metric target-user group. Valid first-level keys are exactly:
+  - `trigger`
+  - `view`
+  - `click`
+  - `ab_test`
+- Preserve first-level group keys exactly. Do not convert `ab_test` to `abTest`.
+- Each group value is an array of Hermes metric DTO objects.
+- Use DTO field names from `HermesMetricReqDTO`: `metricSettingId`, `metricType`, `metricName`, `metricQp`, `metricWindowNum`, `metricWindowTimeUnit`, `displayName`, `orderId`, `note`, and `metricParams`.
+- The CLI boundary accepts snake_case nested DTO fields too, but prefer the native camelCase names above in examples and generated payloads.
+- For existing bindings, include `metricSettingId` so Hermes updates that binding instead of treating it as a new binding.
+- For preset metrics, use `metricType: 1` and a real `metricName` discovered from `engage-setting common-metric list/get`.
+- For custom metrics, use `metricType: 2` plus a complete `metricQp`, `metricWindowNum`, `metricWindowTimeUnit`, and `displayName`; Hermes creates the custom metric name.
+- Do not invent metric names, event names, property names, QP structures, or metric-setting IDs. Read the existing flow detail and available metric definitions first, then update the complete desired metric map.
+
+## Examples
+
+Dry-run updating an existing binding:
+
+```bash
+ae-cli --dry-run engage-flow metric update \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --metric-map '{"trigger":[{"metricSettingId":"setting_1","metricType":1,"metricName":"purchase_count","displayName":"Purchase count","orderId":1}]}'
+```
+
+Apply the same update:
+
+```bash
+ae-cli engage-flow metric update \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --metric-map '{"trigger":[{"metricSettingId":"setting_1","metricType":1,"metricName":"purchase_count","displayName":"Purchase count","orderId":1}]}'
+```
+
+Add a custom metric to the `view` group:
+
+```bash
+ae-cli engage-flow metric update \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --metric-map '{"view":[{"metricType":2,"metricQp":"{\"type\":0,\"eventName\":\"purchase\",\"analysis\":\"A100\",\"filts\":[]}","metricWindowNum":1,"metricWindowTimeUnit":"day","displayName":"Purchase after view","orderId":1}]}'
+```
+
+## Common mistakes
+
+- Do not pass `flow_uuid`; this command requires `flow_id`.
+- Do not pass `metricId`; `HermesMetricReqDTO` has no `metricId` field. Use `metricSettingId` for an existing binding or `metricName` for a preset metric.
+- Do not use arbitrary first-level keys such as `custom`, `ACTION`, or `channel`; use only `trigger`, `view`, `click`, or `ab_test`.
+- Do not submit only the group you want to change unless deleting omitted groups is intended.
+- Do not use this command to query report data. For report metric details, use `references/flow-metric-detail-report.md`.