@thinkingai/ae-cli 6.1.10 → 6.1.12

package/skills/ae-engage/references/add-channel.md

@@ -1,8 +1,10 @@
 # ae-engage engage-setting channel create
 
-> Trigger keywords: push channel · Mapped command: `ae-cli engage-setting channel create`
+> Trigger keywords: push channel · Mapped command: `ae-cli engage-setting channel create` · Capability id: `engage-setting.channel.create`
 
-Create a new Engage push channel.
+Create a new Engage **运营设置** push channel (not config-center channels; those use `engage-scene config-channel`).
+
+**First decide channel kind:** Webhook (`channelType=1`) and Client (`channelType=3`) share the same CLI command and outer `--req` fields, but **`config` / `pushIdType` / custom-param prefixes differ**. Do not reuse a webhook payload for client (or the reverse).
 
 ## Flags
 
@@ -11,67 +13,194 @@ Create a new Engage push channel.
 | `--project-id` / `-p` | number | Yes | Project ID |
 | `--req` | json | Yes | Channel creation request JSON object |
 
-## `--req` Object Fields
+## `--req` Object Fields (common)
 
 | Field | Type | Required | Description |
 |------|------|------|------|
-| `channelType` | number | Yes | channel type |
-| `channelSubBizType` | string | Yes | channel subtype, for example `webhook`、`fcm`、`aurora` |
+| `channelType` | number | Yes | `1` webhook · `3` client (see below) |
+| `channelSubBizType` | string | Yes | must match type: `webhook` or `client` |
 | `channelName` | string | Yes | channel name |
-| `pushIdType` | string | Yes | push target ID field name |
-| `config` | string | Yes | channel config JSON string |
-| `enableTouchEvent` | number | Yes | touch event switch |
-| `eventClickName` | string | Yes | click event name |
-| `eventDeliveryName` | string | Yes | delivery event name |
-| `touchEventSource` | string | Yes | touch event source |
+| `pushIdType` | string | Yes | prefixed property code — **rules differ by channel kind** |
+| `config` | string | Yes | channel config JSON **string** — **shape differs by channel kind** |
+| `enableTouchEvent` | number | Yes | reach funnel: `0` off · `1` on |
+| `eventClickName` | string | Yes when funnel on | click event (e.g. `ops_click`) |
+| `eventDeliveryName` | string | Yes when funnel on | delivery event (e.g. `ops_view`) |
+| `touchEventSource` | string | Yes | usually `custom` for custom event names |
 
-The outer Capability input uses `project_id` and `req`; fields inside `req` keep the native camelCase DTO shape in this table. The Hermes Capability handler assigns the outer `--project-id` to `req.projectId`, so you do not need to fill it manually and the outer value takes precedence.
+The outer Capability input uses `project_id` and `req`; fields inside `req` keep the native camelCase DTO shape. The Hermes Capability handler assigns the outer `--project-id` to `req.projectId`.
 
 ## Response shape
 
-The created channel is under `data.item`; its response keys recursively use snake_case, such as
-`channel_id`, `channel_status`, and `channel_type`.
+The created channel is under `data.item`; response keys recursively use snake_case (`channel_id`, `channel_status`, `channel_type`).
 
-## Enum Notes
+## Webhook vs Client (read this first)
 
-### `req.channelType`
+| | **Webhook** | **Client** |
+|--|-------------|------------|
+| `channelType` | `1` | `3` |
+| `channelSubBizType` | `webhook` | `client` |
+| `config.url` | **HTTP(S) callback URL** (server endpoint that receives the push) | **Client config key / scene id** (e.g. `popup`, `abtest`, `difficulty_ratio`) — **not** an `http://` URL |
+| `pushIdType` | Prefer **`user:`** user properties (e.g. `user:#account_id`) | **`user:`** or **`client:`** (e.g. `user:#account_id`, `client:#distinct_id`) |
+| `config.userParamsList[].columnName` | Prefer **`user:`** only (validated against user dispatch props) | **`user:`** and/or **`client:`** (validated against user props + client-param list) |
+| `config.authConfig` | Optional HTTP auth (`enable` / `secretKey` / `secretType`) | Usually omit / unused |
+| `config.paramsList` | Content template — same type enum for both | Same |
+| Reach funnel | Same outer fields | Same |
 
-- `1`: `WEBHOOK`
-- `2`: `APP_PUSH`
-- `3`: `CLIENT_PUSH`
-- `4`: `WECHAT`
-- `5`: `DOU_YIN`
+Prefix convention (aligned with 配置中心通道管理):
 
-### `req.channelSubBizType`
+- User property → `user:<prop_name>` (e.g. `user:#account_id`, `user:city`)
+- Client parameter → `client:<column_name>` (e.g. `client:#os`, `client:#distinct_id`)
+- Never pass bare `#account_id` / `city` for `pushIdType` or `columnName`
 
-Common values are listed below and should usually match `channelType`:
+## Preflight
 
-- `webhook`: Webhook channel
-- `fcm`: App Push, Firebase Cloud Messaging
-- `aurora`: App Push, Aurora
-- `apns`: App Push, Apple Push Notification Service
-- `client`: Client Push
-- `wechat_mini_game`: WeChat mini game
-- `dou_yin_recommended_game_card`: Douyin recommended game card
+```bash
+# User properties (both kinds; required for webhook custom params)
+ae-cli analysis-meta property list --project-id <id> --scope user --query <kw> --limit 50
 
-### `req.enableTouchEvent`
+# Client parameters (client channel pushId / custom params)
+ae-cli engage-setting client-param list --project-id <id>
 
-- `0`: disable touch events
-- `1`: enable touch events
+# Optional: copy a real config shape
+ae-cli engage-setting channel list --project-id <id>
+ae-cli engage-setting channel get --project-id <id> --channel-id <id>
+```
 
-## Additional Constraints
+If a property / client-param is not found after list/get, stop — do not invent codes.
 
-- `req.config` must be a JSON string, not a JSON object.
-- `req.channelSubBizType` should match the actual channel capability; for example, when `channelType=1`, `webhook` is usually used.
-- If delivery or click callbacks are required, also check that `eventDeliveryName`, `eventClickName`, and `touchEventSource` are complete.
+---
 
-## Safety Constraints
+## A. Webhook channel
+
+```text
+channelType=1, channelSubBizType=webhook
+```
+
+### Webhook `config` JSON (stringified into `req.config`)
+
+```json
+{
+  "url": "https://example.com/hook",
+  "paramsList": [
+    { "key": "title", "keyName": "标题", "type": "STRING", "required": 0 },
+    { "key": "body", "keyName": "动态正文", "type": "TEXT", "required": 0, "tips": "$[user:city]" }
+  ],
+  "userParamsList": [
+    {
+      "key": "uid",
+      "columnName": "user:#account_id",
+      "defaultValue": "-",
+      "columnDesc": "账号 ID"
+    }
+  ],
+  "authConfig": { "enable": false }
+}
+```
 
-This command is a **write operation** and creates a new channel. Check that the `--req` fields are complete before executing.
+| Field | Required | Notes |
+|-------|----------|-------|
+| `url` | Yes | Real HTTP(S) webhook endpoint |
+| `paramsList` | No | Content template definitions |
+| `userParamsList` | No | Custom params; `columnName` = `user:…`; `defaultValue` must be non-blank |
+| `authConfig` | No | When `enable=true`, `secretKey` required |
 
-## Examples
+Do **not** put `client:…` in webhook `userParamsList` unless you have confirmed the environment accepts it — create validation uses **user** dispatch props.
+
+### Webhook example
 
 ```bash
 ae-cli engage-setting channel create --project-id 1 \
-  --req '{"channelType":1,"channelSubBizType":"webhook","channelName":"demo","pushIdType":"user_id","config":"{}","enableTouchEvent":0,"eventClickName":"","eventDeliveryName":"","touchEventSource":""}'
+  --req '{"channelType":1,"channelSubBizType":"webhook","channelName":"demo_webhook","pushIdType":"user:#account_id","config":"{\"url\":\"https://example.com/hook\",\"paramsList\":[{\"key\":\"title\",\"keyName\":\"标题\",\"type\":\"STRING\",\"required\":0}],\"userParamsList\":[{\"key\":\"city\",\"columnName\":\"user:city\",\"defaultValue\":\"-\"}],\"authConfig\":{\"enable\":false}}","enableTouchEvent":1,"eventDeliveryName":"ops_view","eventClickName":"ops_click","touchEventSource":"custom"}'
+```
+
+---
+
+## B. Client channel
+
+```text
+channelType=3, channelSubBizType=client
 ```
+
+### Client `config` JSON (stringified into `req.config`)
+
+```json
+{
+  "url": "popup",
+  "paramsList": [
+    { "key": "messageType", "keyName": "消息类型", "type": "NUM", "required": 0 },
+    {
+      "key": "gifts",
+      "keyName": "礼包",
+      "type": "OBJ_ARRAY",
+      "required": 0,
+      "objArray": [
+        { "key": "gift_name", "keyName": "道具名", "type": "STRING", "required": 0 },
+        { "key": "count", "keyName": "数量", "type": "NUM", "required": 0 }
+      ]
+    }
+  ],
+  "userParamsList": [
+    {
+      "key": "os",
+      "columnName": "client:#os",
+      "defaultValue": "-",
+      "columnDesc": "操作系统"
+    },
+    {
+      "key": "city",
+      "columnName": "user:city",
+      "defaultValue": "-",
+      "columnDesc": "城市"
+    }
+  ]
+}
+```
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `url` | Yes | **Client scene / config key** (string id like `popup`, `abtest`) — not an HTTP URL |
+| `paramsList` | No | Content template (same type enum as webhook) |
+| `userParamsList` | No | `columnName` may be `user:…` **or** `client:…`; `defaultValue` non-blank |
+| `authConfig` | No | Usually omit |
+
+`pushIdType` examples: `user:#account_id`, `client:#distinct_id` (discover client codes via `client-param list`).
+
+### Client example
+
+```bash
+ae-cli engage-setting channel create --project-id 1 \
+  --req '{"channelType":3,"channelSubBizType":"client","channelName":"demo_client","pushIdType":"client:#distinct_id","config":"{\"url\":\"popup\",\"paramsList\":[{\"key\":\"type\",\"keyName\":\"场景\",\"type\":\"STRING\",\"required\":0}],\"userParamsList\":[{\"key\":\"os\",\"columnName\":\"client:#os\",\"defaultValue\":\"-\"}]}","enableTouchEvent":0,"eventClickName":"","eventDeliveryName":"","touchEventSource":"custom"}'
+```
+
+---
+
+## Content template types (`paramsList[].type`) — both kinds
+
+| type | Meaning |
+|------|---------|
+| `STRING` | 文本 |
+| `TEXT` | 动态文本 (`$[user:…]` / `$[client:…]` placeholders) |
+| `NUM` | 数值 |
+| `OBJ_ARRAY` | 对象组 (`objArray` children required) |
+| `DATE` | 日期 |
+| `DATE_TIME` | 时间 |
+| `ARRAY` | 列表 |
+| `SINGLE_SELECT` | 单选下拉 (**requires** existing config-table `tableId`) |
+| `RADIO` | 单选 |
+
+`required`: `0` optional · `1` required. `OBJ_ARRAY` children: `STRING` / `NUM` / `DATE` / `DATE_TIME` / `TEXT` / `SINGLE_SELECT` only.
+
+## Other channel types
+
+`channelType` also supports `2` APP_PUSH (`fcm` / `aurora` / `apns`), `4` WECHAT, `5` DOU_YIN — each has its own `config` DTO. Discover with `channel get` on an existing channel of that subtype before creating; do not invent FCM/APNs secrets.
+
+## Additional Constraints
+
+- `req.config` must be a **JSON string**, not a nested object in the CLI flag.
+- Match `channelSubBizType` to `channelType` (`1`↔`webhook`, `3`↔`client`).
+- When `enableTouchEvent=1`, set `touchEventSource` plus delivery/click event names.
+- For webhook tests, prefer a known mock URL from `channel get` rather than inventing production endpoints.
+
+## Safety Constraints
+
+This command is a **write operation**. Verify `--req` completeness and the correct webhook vs client rules before executing.

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

@@ -14,20 +14,27 @@ Use this sequence when creating or updating a task draft:
 
 1. Query channels with `ae-cli engage-setting channel list --project-id <projectId>`.
 2. Call `ae-cli engage-task task build-save-guide --project-id <projectId> --req '{...}'`.
-3. If the guide says QP-derived fields are required, fetch the skill definition first:
-
-```bash
-ae-cli engage-setting query cluster-qp-skill --project-id <projectId>
-# optional selectors:
-ae-cli engage-setting query cluster-qp-skill --project-id <projectId> --response-mode full --condition-subtype all
-```
-
-Use the returned `skill` text to build:
-
-- `targetConfig.qp`
-- `triggerConfig.triggerRule` (required for `triggerType=3/4/5`)
-- `clientConfig.clientQp`
-- `completionIndicatorDef.event`
+3. Use semantic definitions for audience, trigger, and completion fields:
+
+- `targetConfig.definitionRequest`
+- `triggerConfig.triggerDefinition` (required for `triggerType=3/4/5`)
+- `completionIndicatorDef.completionIndicators[].eventDefinition`
+
+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. 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:
 
@@ -41,11 +48,8 @@ ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<cl
 Important:
 
 - Do not treat audience creation as a fixed preflight step.
-- Create/read the audience only when the guide indicates that you need to construct:
-  - `targetConfig.qp`
-  - `triggerConfig.triggerRule`
-  - `clientConfig.clientQp`
-  - `completionIndicatorDef.event`
+- Discover event/property metadata when semantic definitions reference those fields.
+- Omit the server-authored `clientConfig.clientQp`; partial updates preserve it.
 
 ---
 
@@ -64,6 +68,7 @@ Common request patterns:
 ```bash
 ae-cli engage-task task build-save-guide --project-id 1 --req '{}'
 ae-cli engage-task task build-save-guide --project-id 1 --req '{"context":{"triggerType":2,"channelId":"channel_123"}}'
+ae-cli engage-task task build-save-guide --project-id 1 --req '{"context":{"channelType":2,"triggerType":3,"eventTriggerType":2}}'
 ae-cli engage-task task build-save-guide --project-id 1 --req '{"draft":{"baseInfo":{"taskName":"Demo Task"}}}'
 ```
 
@@ -92,6 +97,7 @@ Use `context` when you want scenario-specific guidance without writing a partial
 Typical fields:
 
 - `triggerType`
+- `eventTriggerType`
 - `targetClusterType`
 - `channelType`
 - `channelId`
@@ -104,7 +110,9 @@ Example:
 ```json
 {
   "context": {
-    "triggerType": 2,
+    "channelType": 2,
+    "triggerType": 3,
+    "eventTriggerType": 2,
     "targetClusterType": 2,
     "channelId": "channel_123"
   }
@@ -190,7 +198,7 @@ This section describes the high-level contract:
 
 - final tool is `save_task`
 - required preflight is `query_channel_list -> build_task_save_guide`
-- QP-derived fields require a server-authored audience: direct `analysis user-cluster create`, followed by `analysis user-cluster get`
+- audience, trigger, and completion conditions use semantic definitions
 - `save_task.req` must be a grouped JSON object
 
 ### 4.6 `scenario`
@@ -224,6 +232,8 @@ It includes:
 
 - grouped block rules
 - structured conditional rules
+- the server/client × `triggerType` × `eventTriggerType` combination matrix
+- type-specific aggregate, continuous, ordered, and every-completion event shapes
 - related-parameter rules
 - unsupported fields / values / combinations
 - `channelContentSchema`
@@ -248,6 +258,38 @@ Do not invent free-form content items such as:
 
 Instead, use the valid item structure and put message text into `value`.
 
+#### `fieldRules.blocks.triggerConfig.triggerDefinitionSchema`
+
+For event-triggered tasks, read all of these fields before constructing `triggerDefinition`:
+
+- `combinationMatrix`
+- `ruleFields`
+- `eventShapes`
+- `examples`
+
+The guide treats the A rule as a discriminated envelope:
+
+- `eventTriggerType=0`: aggregate events
+- `eventTriggerType=1`: exactly one count/eq event with value at least 2, plus optional blacklist
+- `eventTriggerType=2`: at least two ordered steps with `eventDefinition` and `hasDone`
+- `eventTriggerType=3`: client-side count/eq/1 events with `eventTriggerCaliberType`
+
+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`.
@@ -278,14 +320,9 @@ Recommended usage pattern:
 3. read `fieldRules.channelContentSchema`
 4. read `handoff.reqTemplate`
 5. fix everything in `blockingPlaceholders`
-6. if the guide points to an audience or QP-derived fields, call:
-
-```bash
-ae-cli analysis user-cluster create --project-id <projectId> --cluster-name <condition_cluster_name> --display-name <display_name> --definition-request '<semantic-definition-json>'
-ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
-```
-
-7. prefer the created cluster reference; only copy server-authored fields from `user-cluster get` when the guide explicitly requires QP-derived fields
+6. if the guide points to an audience, trigger, or completion condition, add the semantic
+   definition directly
+7. omit `clientConfig.clientQp`; partial updates preserve the server-authored value
 8. call `engage-task task save`
 
 ---

package/skills/ae-engage/references/channel-update-config.md

@@ -19,8 +19,8 @@ ae-cli engage-setting channel update-config \
 | `--channel-id` | Yes | Channel ID to update. |
 | `--enable-touch-event` | Yes | Reach funnel toggle: `1` enabled, `0` disabled. |
 | `--channel-name` | No | New channel name. |
-| `--push-id-type` | No | User property used as the push ID. |
-| `--config` | No | Channel-specific JSON config string (see ChannelConfigDTO). |
+| `--push-id-type` | No | Prefixed push ID: webhook prefers `user:…`; client allows `user:…` or `client:…` (see `add-channel.md`). |
+| `--config` | No | Channel JSON string. Webhook `url` = HTTP(S); client `url` = scene key. Custom `columnName` prefixes differ — see `add-channel.md`. |
 | `--touch-event-source` | No | Reach event source. |
 | `--event-delivery-name` | No | Actual delivery event name. |
 | `--event-click-name` | No | Click event name. |
@@ -33,4 +33,5 @@ ae-cli engage-setting channel update-config \
 
 - Use this command when the user asks to edit/update an existing channel's name, config, push-id type, or reach-funnel settings.
 - `--config` is the channel-specific JSON config; discover the existing config with `ae-cli engage-setting channel get` first rather than inventing it.
+- Keep webhook vs client rules from `add-channel.md` when editing `url` / `pushIdType` / `userParamsList`.
 - Risk is `write`; ordinary update, no confirmation gate.

package/skills/ae-engage/references/common-metric.md

@@ -1,142 +1,115 @@
-# engage-setting common-metric
+# Common metric semantic definitions
 
-> Capability ids: `engage-setting.common-metric.{list,get,create,update,delete}` · Domain: `engage`.
-> Auth: read uses `opsViewSetting` (list also allows `opsViewOperationTask`); write/delete use `opsEditSetting`.
+> 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
 
 ```bash
-# List common metrics
 ae-cli engage-setting common-metric list --project-id <project_id>
-
-# Get a common metric detail
 ae-cli engage-setting common-metric get --project-id <project_id> --metric-name <name>
-
-# Create a PRESET common metric (metric-type must be 1)
-ae-cli engage-setting common-metric create \
-  --project-id <project_id> --metric-type 1 --metric-name <name> --metric-qp '<qp_json>' \
-  --metric-window-num 1 --metric-window-time-unit day --display-name <display>
-
-# Update a common metric
-ae-cli engage-setting common-metric update \
-  --project-id <project_id> --metric-type 1 --metric-name <name> --metric-qp '<qp_json>' \
-  --metric-window-num <num> --metric-window-time-unit day --display-name <display>
-
-# Delete a common metric (high-risk)
+ae-cli engage-setting common-metric create --project-id <project_id> --metric-type 1 \
+  --metric-name <name> --metric-definition '<json>' \
+  --metric-window-num 1 --metric-window-time-unit day --display-name <display_name>
+ae-cli engage-setting common-metric update --project-id <project_id> --metric-type 1 \
+  --metric-name <name> --metric-definition '<json>' \
+  --metric-window-num 1 --metric-window-time-unit day --display-name <display_name>
 ae-cli engage-setting common-metric delete --project-id <project_id> --metric-name <name> --yes
 ```
 
-## Parameters
-
-### list
-
-| Parameter | Required | Description |
-|---|---|---|
-| `--project-id` / `-p` | Yes | Numeric project ID. |
-
-### get / delete
+## Event metric
 
-| Parameter | Required | Description |
-|---|---|---|
-| `--project-id` / `-p` | Yes | Numeric project ID. |
-| `--metric-name` | Yes | Metric name. |
-
-### create / update
-
-| Parameter | Required | Description |
-|---|---|---|
-| `--project-id` / `-p` | Yes | Numeric project ID. |
-| `--metric-type` | Yes | `1` = PRESET (common metric). **create requires `1`**. Do not use `2` (CUSTOM / task-side). |
-| `--metric-name` | Yes | Technical name; prefer `^[a-z][0-9a-z_]{0,79}$`. |
-| `--metric-qp` | Yes | Complete metric QP **JSON object string** (`type=0` event or `type=1` formula). |
-| `--metric-window-num` | Yes | Window size (integer ≥ 1). |
-| `--metric-window-time-unit` | Yes | `minute` / `hour` / `day` (lowercase). |
-| `--display-name` | Yes | Display name. |
-| `--note` | No | Remark. |
-| `--order-id` | No | Sort order (usually omit on setting-page create). |
-| `--metric-setting-id` | No | Binding id (task/config metricMap; usually omit on setting-page create). |
-| `--metric-params` | No | Params JSON string; for formula metrics often `{"format":"float"}`. |
-
-## Output
-
-- `list`: `data.items` (each with `project_id`, `metric_type`, `metric_name`, `metric_qp`, `metric_window_num`, `metric_window_time_unit`, `note`, `last_editer`, `last_update_time`, `order_id`, `display_name`, `metric_setting_id`, `metric_params`) and `data.total`.
-- `get`: `data.metric` — a single metric object with the same fields, or `null`.
-- `create` / `update` / `delete`: `data.success`.
-
-## Agent workflow (Pattern A: discover → match → assemble QP → write)
-
-Unlike the Engage console (user picks events in a picker), Agents must discover real project metadata first. Never invent `event_name` / property names / `--metric-qp` placeholders such as `event`.
-
-```bash
-# 1) Discover candidate events (keyword: payment / recharge / purchase / ...)
-ae-cli analysis-meta event list --project-id <project_id> --query <keyword> \
-  --fields '["event_name","event_desc","authentication_status"]' --limit 20
-
-# Optional soft hint: project recharge-success event name
-ae-cli engage-setting preset-event list --project-id <project_id>
-# → data.recharge_event_desc may contain eventName (not a ready metric_qp)
-
-# 2) If filters are needed, list properties for the matched event
-ae-cli analysis-meta property list --project-id <project_id> \
-  --scope event --event-name <matched_event_name>
-
-# 3) Assemble a type=0 metric QP object from the matched event, then create
-ae-cli engage-setting common-metric create --project-id <project_id> \
-  --metric-type 1 --metric-name <name> --metric-qp '<qp_json>' \
-  --metric-window-num 1 --metric-window-time-unit day --display-name <display>
+```json
+{
+  "type": "event",
+  "event": "purchase",
+  "aggregation": "sum",
+  "property": "amount",
+  "filters": {
+    "relation": "and",
+    "items": [
+      {
+        "field": "currency",
+        "operator": "eq",
+        "values": ["USD"]
+      }
+    ]
+  }
+}
 ```
 
-If multiple events remain plausible after discovery, stop and ask the user which `event_name` to use.
-
-## `--metric-qp` example (type=0 event analysis)
-
-Pass as a single JSON **object string**. Minimal shape aligned with the Engage setting-page event metric:
+Object-group filter example:
 
 ```json
 {
-  "type": 0,
-  "eventName": "purchase",
-  "eventDesc": "Purchase",
-  "eventType": "event",
-  "analysis": "A100",
-  "analysisDesc": "Total count",
-  "analysisParams": "",
-  "quota": "",
-  "quotaDesc": "",
-  "filts": [],
-  "relation": 1,
-  "customEvent": "",
-  "customFilters": [],
-  "eventNameDisplay": "Purchase total count",
-  "subTableType": "",
-  "taPropQuota": {
-    "analysis": "A100",
-    "analysisDesc": "Total count",
-    "analysisParams": "",
-    "quota": "",
-    "quotaDesc": ""
+  "type": "object_group",
+  "field": "equipment_list",
+  "operator": "any_satisfy",
+  "conditions": {
+    "relation": "and",
+    "items": [
+      {
+        "field": "equipment_list.item_level",
+        "operator": "gte",
+        "values": [10]
+      }
+    ]
   }
 }
 ```
 
-CLI rejects non-JSON, non-object, and `{}` values before the request is sent.
+Supported aggregations include `total_count`, `user_count`, `per_user_count`, `sum`, `avg`, `avg_per_user`, `max`, `min`, `distinct_count`, `median`, `percentile`, `variance`, and `stddev`.
 
-## Preflight for config-metric batch-add
+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
+}
+```
 
-`engage-scene config-metric batch-add --ta-metric-ids` requires TA common metrics to exist in the project. List them first:
+## Formula metric
 
-```bash
-ae-cli engage-setting common-metric list --project-id <project_id>
+```json
+{
+  "type": "formula",
+  "expression": "purchases/refunds",
+  "format": "percent",
+  "dependencies": [
+    {
+      "type": "event",
+      "key": "purchases",
+      "event": "purchase",
+      "aggregation": "total_count"
+    },
+    {
+      "type": "event",
+      "key": "refunds",
+      "event": "refund",
+      "aggregation": "total_count"
+    }
+  ]
+}
 ```
 
-If `items` is empty, create PRESET metrics with `common-metric create` (Pattern A above) or treat the case as environment-blocked.
+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.
 
-## Decision Rules
+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.
 
-- Use these commands when the user asks to manage common metrics for the analysis workbench.
-- Discover existing metric names with `common-metric list` first; never invent names for `get`/`update`/`delete`.
-- For create/update, discover events/properties via `ae-analysis` (`analysis-meta event list` / `property list`) before assembling `--metric-qp`.
-- `--metric-type` for setting-page common metrics is always `1` (PRESET). create rejects any other value.
-- `--metric-window-time-unit` must be lowercase `minute` / `hour` / `day` (not `DAY`).
-- `--metric-qp` must be a complete metric QP JSON object; do not pass `{}` or placeholder strings.
-- `delete` is `high-risk-write` and requires `--yes` (or interactive confirmation).
+`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`.