@thinkingai/ae-cli 6.1.11 → 6.1.13

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, and task management. Trigger words: config center, scene config, push channel, config channel, operation strategy, operation task, template, config item, Engage, Hermes, engage-scene, engage-setting, engage-flow, engage-task."
+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:
 
@@ -56,6 +56,7 @@ When the user mentions a product term below (including common Chinese UI labels)
 | **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 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 |
 
 **Easy to confuse:**
@@ -75,6 +76,7 @@ Naming boundary:
 
 - CLI flags use kebab-case; outer Capability input and all Capability response keys use snake_case.
 - Nested business DTOs passed through `--req` or `--payload` keep their documented native camelCase fields. Do not mechanically convert those nested DTO keys to snake_case.
+- Semantic audience, event, trigger, completion, and metric definitions are closed contracts. The CLI rejects malformed or unknown semantic fields locally; `--validate` applies the same precise Hermes capability schema without writing.
 - Successful migrated commands return their business payload under `data`; read the matching reference's Response shape before selecting fields.
 
 ## JSON Parameter Format
@@ -173,6 +175,10 @@ 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
+
 ```
 
 For L3 task reports, read `references/task-data-overview.md`, `references/task-data-detail.md`,
@@ -217,8 +223,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).
@@ -375,6 +402,9 @@ ae-cli engage-setting channel list --project-id <projectId>
 5. `engage-flow flow save` is **operation-based** (protocol v2). The `--req` object must carry an `operation` of `build`, `preview`, or `commit`. Do **not** use the old `nodeList` / `edgeList` field names — use `nodes` / `edges` with `operation=build`. A legacy `nodeList`/`edgeList` payload (or a missing `operation`) is rejected with `Unsupported save_flow operation: null`.
 6. Run the lifecycle: `build` (returns `data.result.status = ready_to_preview` or `need_input`) → resolve any `data.result.next_slot` → `preview` (re-issues response fields `data.result.draft_version` + `data.result.confirm_token`) → `commit` (maps those values to request fields `draftVersion` + `confirmToken`) → reads the final ID from `data.result.result.flow_uuid`.
 7. `nodes[].config` / `edges[].config` may be a JSON object or a JSON string. Custom audience nodes and branches use semantic `targetDefinitionRequest`; Hermes compiles it to the node's stored execution format.
+   Never send `targetClusterQp`. Each audience `event` and `behavior_sequence` must include
+   its own `time_range`; Flow entry dates do not replace that range. Use only properties that
+   resolve through the Flow editor's current project, timezone, and user-entity metadata scope.
 8. You must self-check before previewing/committing:
    - There is exactly one entry node
    - There is at least one `exit_flow`
@@ -437,6 +467,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}`)
@@ -456,6 +487,7 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `references/config-item-analysis-report.md` (`engage-scene.report.config-item-analysis`, L3)
 - `references/config-item-strategy-comparison.md` (`engage-scene.report.strategy-comparison`, L3)
 - `references/activity-activity.md` (`engage-activity.activity.{create,update,delete,list,get,pause,end,stats,info-list}`)
+- `references/activity-data-detail.md` (`engage-activity.activity-data.detail`, L3)
 - `references/activity-approval.md` (`engage-activity.approval.{submit,approve,reject,cancel}`)
 - `references/activity-topic.md` (`engage-activity.topic.{create,update,remove-task,delete,get,copy}`)
 - `references/activity-activity-type.md` (`engage-activity.activity-type.{list,batch-add,update,batch-delete}`)
@@ -474,6 +506,9 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `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.
 
@@ -485,7 +520,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` / `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
 
@@ -505,7 +544,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
 
@@ -526,18 +565,27 @@ 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
    type-specific semantic event shape. Accumulated events are aggregate conditions, continuous
    events use count/eq with a value of at least 2, ordered events use sequence-step envelopes,
-   and every-completion events use count/eq/1. Never construct persisted QP fields.
+   and every-completion events use count/eq/1. Completion target and experiment main-goal event
+   filters must not use properties whose metadata `select_type` is `datetime`. Never construct
+   persisted QP fields.
 4. `ae-cli engage-task task save --project-id <projectId> --req '{...}'`
 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).
 
@@ -551,3 +599,5 @@ Audience creation is not a fixed preflight step. For custom task audiences, use
 `definition_request`. `clientConfig.clientQp` is server-authored and must be omitted from
 Capability requests; partial updates preserve existing server state. Do not assemble raw QP
 manually.
+For a `behavior_sequence`, omit second-step `relative_to_first` or set it to `false`; reserve
+`true` for step 3 or later when the window is measured from step 1.

package/skills/ae-engage/references/activity-data-detail.md

@@ -0,0 +1,61 @@
+# engage-activity.activity-data.detail
+
+Query activity delivery trends through the L3 Capability Gateway.
+
+Mapped command:
+
+```bash
+ae-cli capability run engage-activity.activity-data.detail --input '<json>'
+```
+
+## Input
+
+Required fields:
+
+- `project_id`: project that owns the activity.
+- `activity_id`: activity to query.
+- `start_time`: inclusive start date in `yyyy-MM-dd` format.
+- `end_time`: inclusive end date in `yyyy-MM-dd` format.
+
+Optional fields:
+
+- `time_particle_size`: `T1` (day), `T2` (week), `T3` (month), or `T5` (total). Defaults to `T1`.
+- `source`: `activity` or `topic_and_task`. Defaults to `activity`.
+- `topic_id_list`: selected topic IDs.
+- `task_id_list`: selected standalone task IDs.
+- `request_id`: cancelable query ID. A UUID is generated when omitted.
+
+When `source=topic_and_task` and both ID lists are omitted or empty, the capability selects every topic and standalone task in the activity. When either list is provided, only the explicitly selected resources are queried. Selected resources must belong to the activity and project.
+
+## Recent seven-day topic trend
+
+Use an inclusive seven-day range, `T1`, and `topic_and_task`:
+
+```bash
+ae-cli capability run engage-activity.activity-data.detail --input \
+  '{"project_id":1,"activity_id":"act-1","start_time":"2026-07-25","end_time":"2026-07-31","time_particle_size":"T1","source":"topic_and_task","request_id":"<uuid>"}'
+```
+
+The report exposes the existing activity-page indicators:
+
+- `plan`: planned trigger users.
+- `actualTrigger`: actual push users.
+- `trigger`: successful push users.
+
+It does not expose `view` (actual arrival) or `click`. Use the returned header values instead of treating `trigger` as an actual-arrival metric.
+
+## Output
+
+Successful output contains:
+
+- `data.request_id`: the request ID used by the query.
+- `data.result_generate_time`: ISO-8601 generation time.
+- `data.data.x`: summary/date axis.
+- `data.data.headers`: indicator keys.
+- `data.data.total`: activity totals aligned with `headers`.
+- `data.data.values`: topic or standalone-task rows aligned with `x` and `headers`.
+- `data.data.topic_list`: selected source IDs and names using `topic_id` and `topic_name`.
+
+The first `x`/`total` row is the overall summary. For non-total time grains, subsequent rows are the requested date buckets.
+
+Use `engage-setting.query.cancel` with the same `request_id` to cancel a running query.

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

@@ -23,7 +23,18 @@ Use this sequence when creating or updating a task draft:
 Build event primitives from `ae-analysis` user-cluster / audience models. Hermes wraps those
 primitives in the task-specific envelope selected by `channelType`, `triggerType`, and
 `eventTriggerType`, then validates the final persisted QP before save. Never construct persisted
-execution QP.
+execution QP. Follow the documented closed semantic shapes: unknown fields are rejected, and a
+property `field` may be a technical-name string or a `{name,type}` reference.
+Every custom-audience `event` and `behavior_sequence` requires its own `time_range`. For
+`recent` and `previous`, use a positive integer `value` and only `unit=day`; `custom` requires
+both `start_time` and `end_time`.
+
+Custom audiences support `behavior_sequence` nodes, including sequence/step windows, step
+filters, `completed`, and `relative_to_first`. A task `get` may return top-level `compound`
+nodes when the stored member-group, event-group, and outer relations differ. Preserve those
+compounds when reusing `definition_request`; flattening them changes audience semantics.
+For the second sequence step, omit `relative_to_first` or set it to `false`; use `true` only
+from the third step onward when its window must be measured from step 1.
 
 For existing-cluster audiences (`targetClusterType=2`), you may copy server-authored definitions via:
 
@@ -213,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.
@@ -263,9 +280,26 @@ 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.
 
+#### `fieldRules.blocks.controlConfig.completionIndicatorDef.filterPropertySelectTypes`
+
+Treat this as the source of truth for completion target and experiment main-goal event-filter
+property types:
+
+- `allowed` lists the supported metadata `select_type` values.
+- `excluded` lists values that must not be used.
+- `datetime` is excluded because the task completion-indicator editor cannot display it.
+
+Apply this rule only to
+`completionIndicatorDef.completionIndicators[].eventDefinition.filters`. Trigger-event filters have
+their own scenario rules and are not subject to this completion-filter restriction.
+
 ### 4.9 `handoff`
 
 This is the final section before `save_task`.
@@ -275,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/common-metric.md

@@ -3,6 +3,13 @@
 > Trigger keywords: common metric, shared metric · Capability ids: `engage-setting.common-metric.{list,get,create,update,delete}` · Permission: `opsEditSetting`.
 
 Common metric capabilities expose semantic event/formula definitions. Do not submit or reuse `metric_qp`, `Axxx`, display metadata, formula dependency internals, or property metadata.
+Metric definitions and formula dependencies reject unknown fields. Event filter `field` accepts
+either a technical-name string or `{"name":"...","type":"event_property"}`.
+
+When metadata reports an event property as `array_row`, express it as an `object_group` filter
+with `any_satisfy`, `none_satisfy`, or `all_satisfy`; its nested `conditions.items` may reference
+only child properties of that parent. Flat filters on the `array_row` parent are rejected before
+the metric is saved.
 
 ## Commands
 
@@ -39,8 +46,41 @@ ae-cli engage-setting common-metric delete --project-id <project_id> --metric-na
 }
 ```
 
+Object-group filter example:
+
+```json
+{
+  "type": "object_group",
+  "field": "equipment_list",
+  "operator": "any_satisfy",
+  "conditions": {
+    "relation": "and",
+    "items": [
+      {
+        "field": "equipment_list.item_level",
+        "operator": "gte",
+        "values": [10]
+      }
+    ]
+  }
+}
+```
+
 Supported aggregations include `total_count`, `user_count`, `per_user_count`, `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `median`, `percentile`, `variance`, and `stddev`.
 
+Property aggregations require `property`. `percentile` additionally requires a numeric
+`percentile` greater than `0` and at most `100`:
+
+```json
+{
+  "type": "event",
+  "event": "purchase",
+  "aggregation": "percentile",
+  "property": "amount",
+  "percentile": 90
+}
+```
+
 ## Formula metric
 
 ```json
@@ -65,6 +105,11 @@ Supported aggregations include `total_count`, `user_count`, `per_user_count`, `s
 }
 ```
 
+Every dependency requires a non-empty, unique `key`, and every key must be used in
+`expression`. Write bare keys only: use `purchases/refunds`, never `purchases.A100/refunds.A100`.
+Aggregation codes are derived from each dependency. Formula dependencies follow the same
+property and percentile requirements as event metrics.
+
 Resolve every event and property through `ae-cli analysis-meta event list` and the corresponding property metadata before writing. `get` and `list` return `metric_definition`, `metric_definition_status`, and an optional unavailable reason. Raw metric QP is hidden.
 
 `metric_type=1` remains required for setting-page common metrics. Metric windows remain separate from the semantic definition, and their unit must be `minute` / `hour` / `day`.

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