@thinkingai/ae-cli 6.0.38 → 6.0.40

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

@@ -10,18 +10,20 @@ Recommended 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. If the guide indicates QP-derived fields, call `ae-cli engage-setting query cluster-qp-skill --project-id <projectId>` and build
-   `targetConfig.qp`, `triggerConfig.triggerRule`, `clientConfig.clientQp`, or `completionIndicatorDef.event`
-   from the returned skill text. For existing-cluster audiences, use `analysis user-cluster get`.
+3. If the guide indicates a custom target audience, build the semantic
+   `targetConfig.definitionRequest` contract used by Analysis. Hermes compiles it to persisted QP.
+   Use `triggerConfig.triggerDefinition` and
+   `completionIndicatorDef.completionIndicators[].eventDefinition` for event conditions.
+   For existing-cluster audiences, use `analysis user-cluster get`.
+   Never construct persisted execution QP.
 4. Build the final grouped `req`
 5. `ae-cli engage-task task save --project-id <projectId> --req '{...}'`
 
 Audience creation is not a fixed preflight step. Use direct create/get only when the guide indicates that you must construct:
 
-- `targetConfig.qp`
-- `triggerConfig.triggerRule`
-- `clientConfig.clientQp`
-- `completionIndicatorDef.event`
+- `targetConfig.definitionRequest`
+- `triggerConfig.triggerDefinition`
+- `completionIndicatorDef.completionIndicators[].eventDefinition`
 
 For the full guide contract, request format, return sections, and handoff usage, read:
 
@@ -31,7 +33,9 @@ For the full guide contract, request format, return sections, and handoff usage,
 
 ## 1. General Principles
 
-`engage-task task save` accepts only the final grouped draft-save payload that Hermes can validate and persist.
+`engage-task task save` accepts the grouped draft-save payload. For a custom audience
+(`targetClusterType=1`), pass semantic `targetConfig.definitionRequest`; do not pass raw
+persisted audience fields.
 
 The command supports two modes:
 
@@ -101,21 +105,59 @@ Use the guide to determine:
 - current handoff template
 - whether the current payload is already close to submit-ready
 
-### 2.3 Create and Read the Audience Only When Needed
+### 2.3 Build Semantic Conditions
 
-If the guide indicates that an audience or QP-derived fields are needed, run:
+If the guide indicates that audience or event conditions are needed, build semantic definitions
+directly. Resolve real events and properties through Analysis metadata.
 
-```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>"]'
+Use semantic event definitions for:
+
+- `triggerConfig.triggerDefinition`
+- `completionIndicatorDef.completionIndicators[].eventDefinition`
+
+Task aggregate and completion event definitions support:
+
+- `aggregation`: `count`, `sum`, or `distinct_count`
+- `operator`: `gt`, `gte`, or `eq`
+
+Completion target and experiment main-goal event filters must not use properties whose metadata
+`select_type` is `datetime`. The supported filter-property select types are `string`, `number`,
+`bool`, `bool-s`, `date`, `array`, `array_string`, `row`, and `array_row`. This restriction applies
+to `completionIndicatorDef.completionIndicators[].eventDefinition.filters`; it does not apply to
+trigger-event filters.
+
+For an event property whose metadata `select_type` is `array_row`, never submit it as a flat
+property filter. Use an object-group filter and place only that parent's child properties inside
+`conditions`:
+
+```json
+{
+  "type": "object_group",
+  "field": "equipment_list",
+  "operator": "any_satisfy",
+  "conditions": {
+    "relation": "and",
+    "items": [
+      {
+        "field": "equipment_list.item_level",
+        "operator": "gte",
+        "values": [10]
+      }
+    ]
+  }
+}
 ```
 
-Prefer the returned `cluster_name`/`clusterKey`. Only when required, use the server-authored definition to build:
+Object-group operators are `any_satisfy`, `none_satisfy`, and `all_satisfy`. Resolve the parent
+and child fields from current metadata. Hermes validates the metadata type, child-parent
+relationship, and supported operators before saving, so do not flatten `array_row` or invent child
+field names.
 
-- `targetConfig.qp`
-- `triggerConfig.triggerRule`
-- `clientConfig.clientQp`
-- `completionIndicatorDef.event`
+Trigger events have an additional envelope contract selected by `eventTriggerType`. Do not apply
+one aggregate event shape to every trigger type. Use the matrix and examples in section 4.4.
+
+`clientConfig.clientQp` is not an AI-authored field. Always omit it from Capability requests;
+partial task updates preserve existing server state.
 
 Do not create an audience by default for every task. It is conditional, not mandatory.
 
@@ -192,16 +234,12 @@ Content guidance:
 
 Use the guide to decide which audience shape applies:
 
-- `targetClusterType=1`: custom audience, requires `qp`
+- `targetClusterType=1`: custom audience, requires `definitionRequest`
 - `targetClusterType=2`: existing cluster, requires `clusterKey`
-- `targetClusterType=3`: all users, forbids both `qp` and `clusterKey`
-
-If `qp` is required, create/read a server-authored audience and copy the saved definition rather than building raw QP:
+- `targetClusterType=3`: all users, forbids `definitionRequest` and `clusterKey`
 
-```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>"]'
-```
+For a custom audience, pass the semantic definition directly. Do not create an intermediate
+cluster or copy persisted QP.
 
 ### 4.4 `triggerConfig`
 
@@ -209,32 +247,175 @@ Use the guide to determine the current trigger rule set:
 
 - `triggerType=0`: requires `triggerTime`
 - `triggerType=1`: requires `startDate`, `endDate`, `triggerCrontab`
-- `triggerType=2`: manual, no `triggerRule`
-- `triggerType=3/4/5`: requires `triggerRule`
+- `triggerType=2`: manual, no `triggerDefinition`
+- `triggerType=3/4/5`: requires `triggerDefinition`
 
 Rules:
 
 - `triggerType=6` is not supported
 - use the guide for cron format and wrong-example checks
-- if `triggerRule` is needed, copy it from the saved server-authored audience definition:
+- if `triggerDefinition` is needed, build it from semantic event definitions and resolve real
+  event/property names through Analysis metadata
+- always set the A rule's `eventTriggerType` explicitly
+- Hermes compiles the semantic event and then validates the final persisted trigger-rule envelope
+- for semantic event-trigger tasks, Hermes backfills missing task-level `startDate` / `endDate`
+  from the A rule's `periodStart` / `periodEnd`; explicit task-level dates remain authoritative
 
-```bash
-ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
+#### Trigger envelope matrix
+
+| Channel | `triggerType` | Allowed A-rule `eventTriggerType` |
+| --- | --- | --- |
+| Server channels | `3` | `0`, `1`, `2` |
+| Server channels | `4` | `0` only |
+| Server channels | `5` | `0`, `1`, `2` |
+| `client_push` (`channelType=3`) | `3` | `1`, `2`, `3` |
+| `client_push` (`channelType=3`) | `5` | `1`, `2`, `3` |
+
+For `triggerType=4/5`, the second B rule is always an aggregate rule. It also requires
+`delayTime`, `delayTimeSymbol`, and `eventCondition`; use `1` for `triggerType=4` and `0` for
+`triggerType=5`.
+
+#### `eventTriggerType=0`: accumulated completion
+
+Use aggregate semantic events:
+
+```json
+{
+  "eventTriggerType": 0,
+  "events": [
+    {
+      "type": "event",
+      "event": "purchase",
+      "aggregation": "sum",
+      "property": "amount",
+      "operator": "gt",
+      "value": 100
+    }
+  ]
+}
 ```
 
-### 4.5 `controlConfig`
+#### `eventTriggerType=1`: continuous completion
 
-Minimum required field:
+Use exactly one count event with `operator=eq` and `value>=2`. `blackList` is optional and accepts
+semantic events that Hermes compiles as non-aggregate event selectors. The rule-level window is
+optional; provide `windowGap` and `windowGapTimeUnit` together.
+`relationProps` is optional and uses semantic event-property references. Hermes resolves their
+legacy metadata before persistence:
 
-- `completionIndicatorDef`
+```json
+{
+  "relationProps": [
+    {
+      "property": {
+        "type": "event_property",
+        "name": "#city"
+      }
+    }
+  ]
+}
+```
+
+```json
+{
+  "eventTriggerType": 1,
+  "windowGap": 7,
+  "windowGapTimeUnit": "day",
+  "events": [
+    {
+      "type": "event",
+      "event": "login",
+      "aggregation": "count",
+      "operator": "eq",
+      "value": 3
+    }
+  ],
+  "blackList": [
+    {
+      "type": "event",
+      "event": "logout",
+      "aggregation": "count",
+      "operator": "eq",
+      "value": 1
+    }
+  ]
+}
+```
 
-When the guide points to event-based completion or experiment-driven main-goal rules, use the saved server-authored audience definition:
+#### `eventTriggerType=2`: ordered completion
 
-```bash
-ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
+Use at least two sequence steps. The first and last steps must have `hasDone=true`. Put the
+Analysis semantic event inside `eventDefinition`; do not add persisted aggregate fields such as
+`taPropQuota`, `uceCalcuSymbol`, or `num`.
+Optional `relationProps` use the same semantic event-property structure documented for
+`eventTriggerType=1`.
+
+```json
+{
+  "eventTriggerType": 2,
+  "events": [
+    {
+      "eventDefinition": {
+        "type": "event",
+        "event": "login",
+        "aggregation": "count",
+        "operator": "eq",
+        "value": 1
+      },
+      "hasDone": true,
+      "hasDistanceStart": false
+    },
+    {
+      "eventDefinition": {
+        "type": "event",
+        "event": "purchase",
+        "aggregation": "count",
+        "operator": "eq",
+        "value": 1
+      },
+      "hasDone": true,
+      "hasDistanceStart": false,
+      "windowGap": 2,
+      "windowGapTimeUnit": "day"
+    }
+  ]
+}
 ```
 
-to build `completionIndicatorDef.event`.
+`hasDone=false` is allowed only for optional intermediate steps. Hermes removes aggregate fields
+from every persisted sequence step and rejects unsafe sequence envelopes before save.
+
+#### `eventTriggerType=3`: every completion
+
+This type is available only for `client_push`. Use count/eq/1 events and set
+`eventTriggerCaliberType` to `0` (combined trigger) or `1` (separate trigger).
+
+```json
+{
+  "eventTriggerType": 3,
+  "eventTriggerCaliberType": 0,
+  "events": [
+    {
+      "type": "event",
+      "event": "login",
+      "aggregation": "count",
+      "operator": "eq",
+      "value": 1
+    }
+  ]
+}
+```
+
+### 4.5 `controlConfig`
+
+Minimum required field:
+
+- `completionIndicatorDef`
+
+When the guide points to event-based completion or experiment-driven main-goal rules, build
+`completionIndicatorDef.completionIndicators[].eventDefinition` from the semantic event contract.
+Read `fieldRules.blocks.controlConfig.completionIndicatorDef.filterPropertySelectTypes` and exclude
+every property type listed under `excluded` before constructing its `filters`.
 
 Important constraints that still apply:
 
@@ -249,13 +430,10 @@ Important constraints that still apply:
 
 Use this block only when client-side conditions are needed.
 
-If `clientConfig.clientQp` is required, copy it from the saved server-authored audience definition:
-
-```bash
-ae-cli analysis user-cluster get --project-id <projectId> --cluster-names '["<condition_cluster_name>"]'
-```
-
-Only call that schema query when the guide explicitly shows that the field is needed.
+Never include `clientConfig.clientQp` in a Capability request. It is a server-authored
+compatibility field, and partial task updates preserve the existing server value. If a requested
+client-side condition has no semantic field in the current contract, stop and report that it cannot
+be safely authored through this Capability.
 
 ---
 
@@ -266,13 +444,14 @@ Before submission, verify:
 1. `channelId` comes from a real channel query.
 2. `build_task_save_guide` has already been called for the current scenario or partial draft.
 3. `fieldRules.channelContentSchema` was used as the source of truth for content structure.
-4. Any required QP-derived fields came from `analysis user-cluster get`, never from hand-built raw QP.
-5. `targetClusterType` matches the presence or absence of `clusterKey` / `qp`.
-6. `triggerType` matches the provided scheduling or event fields.
+4. Audience, trigger, and completion conditions use semantic definitions only.
+5. `targetClusterType` matches the presence or absence of `clusterKey` / `definitionRequest`.
+6. `channelType`, `triggerType`, and `eventTriggerType` match the trigger envelope matrix.
 7. `completionIndicatorDef` is present and structurally valid for the current scenario.
 8. `taskId` is omitted for create mode and present only for updating a draft or paused task.
 9. No unsupported `triggerType=6` is used.
-10. No placeholder IDs or fabricated resource names remain in the request.
+10. Ordered steps contain `eventDefinition` and sequence metadata, not persisted aggregate fields.
+11. No placeholder IDs or fabricated resource names remain in the request.
 
 ---
 
@@ -286,14 +465,8 @@ ae-cli engage-task task build-save-guide --project-id 1 --req '{"context":{"trig
 ae-cli engage-task task save --project-id 1 --req '{...final grouped req...}'
 ```
 
-If the guide indicates an audience or QP-derived fields are needed, insert direct create/get:
-
-```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>"]'
-```
-
-before building the final `req`.
+If the guide indicates a custom audience or event condition, insert the semantic definition
+directly before building the final `req`.
 
 ---
 
@@ -308,4 +481,4 @@ This command is a write operation.
 - Do not invent `channelId`, `clusterKey`, audience definitions, or content keys
 - Do not use `taskId` for a running or ended task
 - Do not pass `occasionKeys`; Hermes derives them from content
-- Do not call the semantic cluster definition builder as a reflex; call it only when guide output says QP-derived fields are needed
+- Do not create an intermediate cluster merely to obtain an execution QP

package/skills/ae-engage/references/scene-config-metric.md

@@ -52,6 +52,9 @@ ae-cli engage-scene config-metric batch-delete --project-id <project_id> --confi
 
 ### update-rule
 
+`event_list` is a scene metric attribution-rule list, not a complete analysis QP. It intentionally
+keeps its existing `event_name`/`filter` contract and does not use TriggerEvent conversion.
+
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` / `-p` | Yes | Numeric project ID. |

package/skills/ae-engage/references/scene-preset-metric.md

@@ -1,45 +1,16 @@
-# engage-scene preset-metric
+# Scene preset metric semantic events
 
-> Trigger keywords: config center, config item · Capability ids: `engage-scene.preset-metric.{get,set}` · Domain: `engage`.
-
-Scene management / config center — config item preset metrics (impression / click / engagement) QP configuration.
-
-## Commands
+Config-item impression, click, and attend metrics are stored as event QP but exposed to the CLI as semantic event definitions.
 
 ```bash
-# Get preset metric QP config of a config item
 ae-cli engage-scene preset-metric get --project-id <project_id> --config-id <config_id>
 
-# Set preset metric QP config
-ae-cli engage-scene preset-metric set \
-  --project-id <project_id> --config-id <config_id> \
-  [--impression-event-qp '<qp json>'] [--click-event-qp '<qp json>'] [--attend-event-qp '<qp json>']
+ae-cli engage-scene preset-metric set --project-id <project_id> --config-id <config_id> \
+  --impression-event-definition '{"type":"event","event":"impression","aggregation":"count","operator":"gte","value":1}' \
+  --click-event-definition '{"type":"event","event":"click","aggregation":"count","operator":"gte","value":1}' \
+  --attend-event-definition '{"type":"event","event":"attend","aggregation":"count","operator":"gte","value":1}'
 ```
 
-## Parameters
-
-### get
-
-| Parameter | Required | Description |
-|---|---|---|
-| `--project-id` / `-p` | Yes | Numeric project ID. |
-| `--config-id` | Yes | Config item ID. |
-
-### set
-
-| Parameter | Required | Description |
-|---|---|---|
-| `--project-id` / `-p` | Yes | Numeric project ID. |
-| `--config-id` | Yes | Config item ID. |
-| `--impression-event-qp` | No | Impression event QP JSON string. |
-| `--click-event-qp` | No | Click event QP JSON string. |
-| `--attend-event-qp` | No | Attend event QP JSON string. |
-
-## Output
-
-- `get`: `data` — preset metric QP config.
-- `set`: `data.success` — whether the operation succeeded.
-
-## Decision Rules
+All three event flags are optional; an omitted definition clears that stored preset event, preserving existing set semantics. Resolve real event/property metadata before writing.
 
-- `get` is read; `set` is `write`.
+Get returns the three semantic definitions with per-field conversion status and never returns raw event QP.