@thinkingai/ae-cli 6.1.10 → 6.1.11

package/skills/ae-engage/references/activity-approval.md

@@ -1,14 +1,15 @@
 # engage-activity approval
 
-> Capability ids: `engage-activity.approval.{approve,reject,cancel}` · Domain: `engage`.
->
-> **Temporarily disabled:** `engage-activity.approval.submit` — do not call until re-enabled.
+> Capability ids: `engage-activity.approval.{submit,approve,reject,cancel}` · Domain: `engage`.
 
 Campaign activities — activity approval workflow. Current actions target an activity (`ApprovalActivityIdDealDTO`: `projectId` + `activityId` + `reason`); each is a state-changing `write` and does not support dry-run. `reject` requires `reason`; other actions treat `reason` as optional.
 
 ## Commands
 
 ```bash
+# Submit an activity for approval
+ae-cli engage-activity approval submit --project-id <project_id> --activity-id <activity_id> [--reason <reason>]
+
 # Approve an activity
 ae-cli engage-activity approval approve --project-id <project_id> --activity-id <activity_id>
 
@@ -23,6 +24,7 @@ ae-cli engage-activity approval cancel --project-id <project_id> --activity-id <
 
 | Command | Required flags | Notes |
 |---|---|---|
+| submit | `--project-id`, `--activity-id` | `--reason` optional. Activity must have draft/pending standalone or topic tasks. |
 | approve | `--project-id`, `--activity-id` | `--reason` optional. |
 | reject | `--project-id`, `--activity-id`, `--reason` | `--reason` required, max 72 characters. |
 | cancel | `--project-id`, `--activity-id` | `--reason` optional. |
@@ -35,13 +37,19 @@ ae-cli engage-activity approval cancel --project-id <project_id> --activity-id <
 
 - All approval actions are `write` (real state changes) and do not support dry-run; they do not require `--yes` (only `high-risk-write` does).
 - Approve/reject require the caller to be a valid approver of the activity (enforced server-side).
-- Do **not** call `engage-activity.approval.submit`; it is temporarily unavailable.
+- Submit requires at least one standalone or topic task under the activity that can enter approval.
+- Submit and approve load complete task details and scan both standalone tasks and topic tasks before invoking the product approval service.
+- Approval does not repair or normalize unsupported activity task configurations.
+- If preflight returns `ACTIVITY_TASK_COMPATIBILITY_VIOLATION`, inspect `error.meta.violations`, withdraw/cancel approval when necessary, and update or recreate each reported task as scheduled, fixed-timezone, and non-experiment before resubmitting.
 
 ## Common Errors
 
 | code | when |
 |---|---|
 | `ACTIVITY_NOT_FOUND` | activity id missing in project |
+| `ACTIVITY_NO_APPROVAL_TASK` | activity has no standalone/topic tasks to submit |
+| `ACTIVITY_TASK_COMPATIBILITY_VIOLATION` | one or more persisted activity tasks use unsupported trigger, timezone, experiment, or content-group configuration; details are in `error.meta.violations` |
+| `ACTIVITY_TRIGGER_TYPE_REQUIRED` | a persisted activity task is missing its trigger type; reported inside the compatibility violation list |
 | `ACTIVITY_STATUS_INVALID` | activity not in draft/pending |
 | `APPROVAL_NOT_PENDING` | no under-approval record |
 | `NOT_APPROVER` | caller is not a project approver |

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

@@ -26,9 +26,9 @@ ae-cli engage-activity task copy --project-id <project_id> --task-id <task_id> [
 
 | Command | Required flags | Notes |
 |---|---|---|
-| get | `--project-id`, `--task-id` | read. |
-| create | `--project-id`, `--payload` | payload = `OperationTaskOpDTO`; set `activityId`, leave `topicId` empty. Missing `expConfig` is auto-filled as `{"enableExp":false}`. |
-| update | `--project-id`, `--payload` | payload = `OperationTaskOpDTO` including `taskId`. Prefer get detail as base. Missing `expConfig` is auto-filled as `{"enableExp":false}`. |
+| get | `--project-id`, `--task-id` | Only standalone tasks with an `activityId`; ordinary tasks use `engage-task task get`. |
+| create | `--project-id`, `--payload` | payload = `OperationTaskOpDTO`; set `activityId`, leave `topicId` empty. Only scheduled `triggerType` `0/1` is supported. |
+| update | `--project-id`, `--payload` | payload = `OperationTaskOpDTO` including `taskId`. Prefer get detail as base. Only scheduled `triggerType` `0/1` is supported. |
 | copy | `--project-id`, `--task-id` | `--new-name` optional (default source name + `_copy`). |
 
 ## Output
@@ -47,20 +47,28 @@ ae-cli engage-activity task copy --project-id <project_id> --task-id <task_id> [
 - **TEXT (rich text) params** must include both `value` and `config` (Slate.js JSON **string**). If `config` is missing, Hermes copy auto-fills  
   `config = [{"type":"paragraph","children":[{"text":"<value>"}]}]` as a JSON string.
 - Missing `expConfig` on create/update is auto-filled as `{"enableExp":false}` (same shape as task `get`).
+- A/B and horse-race experiments are not supported. Do not pass experiment fields or multiple content groups.
+- `groupContentList` must contain exactly one non-experiment group. Put language variants in that group's `contentList`.
 
 ### Audience (`targetClusterType`)
 
 | Value | Required | Notes |
 |---|---|---|
 | `2` (existed) | `clusterKey` | From `analysis user-cluster list/get`. |
-| `1` (custom) | `qp` | JSON object string. |
-| `3` (all) | — | Do not pass `clusterKey` or `qp`. |
+| `1` (custom) | `definitionRequest` | Analysis-compatible semantic condition object. |
+| `3` (all) | — | Do not pass `clusterKey` or `definitionRequest`. |
+
+`get` returns `definition_request`, `definition_status`, and optional `definition_unavailable_reason`, while hiding the stored execution QP. Reuse `definition_request` as payload `definitionRequest` for an update. `copy` converts the source internally and does not require an audience field from the caller.
 
 ## Decision Rules
 
+- `triggerType` must be `0` (schedule single) or `1` (schedule repeat). Manual (`2`) and triggered (`3`-`6`) tasks belong under `engage-task`, not `engage-activity`.
+- Set `triggerTimeStrategy` to `fixed_time_zone` and `tzOffset` to the parent activity timezone. User timezone and user active time are not supported.
+- Keep `triggerTime`, or repeat `startDate`/`endDate`, inside the parent activity period.
+- Create/update/copy is limited to editable parent activity states: draft (`0`), paused (`2`), or denied (`5`). Project-configured count and language limits remain authoritative.
 - Discover a real `task_id` via `get`/activity `info-list` first; never invent IDs.
 - `copy` duplicates the editable task config (not runtime/trigger state).
-- `copy` saves via **draft** add (`draft=true`), so a past schedule-single `triggerTime` is allowed; output may include `trigger_time_stale=true`. Update the time before submitting for approval (`engage-activity.approval.submit` is temporarily unavailable).
+- `copy` saves via **draft** add (`draft=true`), so a past schedule-single `triggerTime` is allowed; output may include `trigger_time_stale=true`. Update the time before submitting for approval.
 - Standalone tasks must **not** include `topicId`; topic tasks use `engage-activity topic create` / `topic copy`.
 
 ## Copy errors
@@ -73,6 +81,13 @@ ae-cli engage-activity task copy --project-id <project_id> --task-id <task_id> [
 | `TASK_PROJECT_MISMATCH` | task exists but not in `--project-id` |
 | `TOPIC_TASK_FORBIDDEN` | source has `topicId` (use `topic copy`) |
 | `ACTIVITY_ID_REQUIRED` | source has no `activityId` (not a standalone activity task) |
+| `ACTIVITY_TRIGGER_TYPE_UNSUPPORTED` | task uses manual or a triggered task type |
+| `ACTIVITY_TRIGGER_TIME_STRATEGY_UNSUPPORTED` | task does not use `fixed_time_zone` |
+| `ACTIVITY_TIMEZONE_REQUIRED` | standalone task omits `tzOffset` |
+| `ACTIVITY_EXPERIMENT_UNSUPPORTED` | task enables or configures an experiment |
+| `ACTIVITY_CONTENT_GROUPS_UNSUPPORTED` | task has more than one experiment-style content group |
+| `ACTIVITY_TIMEZONE_MISMATCH` | task timezone differs from the parent activity |
+| `ACTIVITY_SCHEDULE_OUT_OF_RANGE` | task schedule is outside the activity period |
 | `TRIGGER_TIME_REQUIRED` | schedule-single missing `triggerTime` |
 | `CHANNEL_NOT_FOUND` | source channel missing / type mismatch |
 | `TASK_COUNT_LIMIT` | project task count limit exceeded |

package/skills/ae-engage/references/activity-topic.md

@@ -30,7 +30,7 @@ ae-cli engage-activity topic copy --project-id <project_id> --topic-id <topic_id
 
 | Command | Required flags | Notes |
 |---|---|---|
-| create | `--project-id`, `--payload` | payload = `TopicAddDTO` (camelCase). Prefer `triggerType` `0` (schedule single) or `1` (schedule repeat); activity topics do not use manual (`2`). |
+| create | `--project-id`, `--payload` | payload = `TopicAddDTO` (camelCase). `triggerType` must be `0` (schedule single) or `1` (schedule repeat). |
 | update | `--project-id`, `--payload` | payload = `TopicModifyReq` (`topicId` + fields + task lists). |
 | remove-task | `--project-id`, `--task-id` | high-risk; requires `--yes`; no dry-run. Only tasks with a non-empty `topicId`. |
 | delete | `--project-id`, `--topic-id` | high-risk; requires `--yes`; no dry-run. |
@@ -42,19 +42,19 @@ ae-cli engage-activity topic copy --project-id <project_id> --topic-id <topic_id
 TEXT (rich text) params inside `groupContentList[].contentList[].content` need both `value` and Slate `config` (JSON string). If `config` is omitted, Hermes copy/create auto-fills  
 `[{"type":"paragraph","children":[{"text":"<value>"}]}]`. See `activity-task.md` Channel content.
 
-Topic-level audience uses `topicClusterKey` / `topicQp`; do **not** pass task-level `clusterKey` at topic root.
+Topic-level audience uses `topicClusterKey` / `topicDefinitionRequest`; do **not** pass task-level `clusterKey` at topic root.
 
 ### Audience (`targetClusterType`)
 
 | Value | Required | Notes |
 |---|---|---|
-| `1` (custom) | `topicQp` | Valid condition JSON object string (not `{}`). Use mix QP with `totalCFilter` (and optional `totalOutCFilter`). |
+| `1` (custom) | `topicDefinitionRequest` | Analysis-compatible semantic condition object. |
 | `2` (existed) | `topicClusterKey` | From an existing user cluster. |
 | `3` (all) | — | **Not supported for activity topics** → `TOPIC_TARGET_CLUSTER_TYPE_UNSUPPORTED`. Use standalone `engage-activity task create` for all-users. |
 
-**`triggerMixQpVersion`:** For custom audience (`targetClusterType=1`) with mix QP (`totalCFilter` / `totalInCFilter`), set `"4.4"`. UI theme edit parses conditions only when this is `4.4`; missing/blank values make target-user filters render empty. Capability create/update/copy default blank to `"4.4"` (same as UI and standalone task MCP).
+**`triggerMixQpVersion`:** Capability create/update/copy defaults a blank value to `"4.4"` while compiling the semantic definition.
 
-Task-level extra conditions go in `taskQp` as mix QP under **`totalCFilter` only** (user attrs and/or events). Do not put task-owned conditions in `totalInCFilter` — that key is reserved for topic→task merge (topic `totalCFilter` is copied into task cluster `totalInCFilter` on save).
+Task-level extra conditions go in each task's inclusion-only `definitionRequest`. Keep shared conditions in `topicDefinitionRequest`; Hermes performs the topic-to-task merge through the existing domain service. Topic tasks do not have an independent audience mode. `topic get` returns the canonical task marker `targetClusterType=1`; it may be retained when mapping `taskList` into `modifyTaskList`, but no other value is accepted. Do not pass task-level `clusterKey`, all-users selection, or exclusion filters.
 
 ### Trigger (`triggerType`)
 
@@ -62,7 +62,16 @@ Task-level extra conditions go in `taskQp` as mix QP under **`totalCFilter` only
 |---|---|---|
 | `0` (schedule single) | `triggerTime` (`yyyy-MM-dd HH:mm`, future) | Preferred for CLI create. |
 | `1` (schedule repeat) | `startDate`, `endDate`, `triggerCrontab` | |
-| `2` (manual) | — | **Not supported for activity topics** (UI only offers 0/1). Using it without `endDate` causes `CAPABILITY_EXECUTION_FAILED`. |
+
+Manual (`2`) and every triggered type (`3`-`6`) are rejected with `ACTIVITY_TRIGGER_TYPE_UNSUPPORTED`.
+
+### Shared topic configuration
+
+- A/B and horse-race experiments are not supported. Omit `expConfig` and use exactly one content group per topic task.
+- The topic owns schedule, activity timezone, channel, frequency limits, channel touch limits, and whitelist.
+- A topic task only owns its name, optional inclusion-only custom audience refinement, one content group, completion indicators, metrics, and description.
+- Do not put schedule, trigger rules, channel, frequency, whitelist, experiment, or `clusterKey` on a topic task. The only accepted task-level `targetClusterType` is the canonical get response value `1`.
+- Keep the topic schedule inside the parent activity period. Create/update/copy requires parent activity `mappingStatus` `0`, `2`, or `5`.
 
 ## Create Topic Orchestration
 
@@ -72,11 +81,11 @@ Use this workflow when a topic has a shared audience plus one or more task-level
 2. **Resolve the parent activity.** Use `activity list|get` to verify the exact `activityId`, editable status, activity dates, and timezone. For a repeated topic, keep `startDate` and `endDate` inside the activity period and interpret the cron in the activity timezone.
 3. **Resolve a real channel.** Query `engage-setting channel list`, then inspect the selected channel before composing content. If several enabled channels match and the user has not specified a provider or an already-confirmed project default, ask which one to use instead of choosing an arbitrary ID.
 4. **Read the channel content contract.** Call `engage-task task build-save-guide` with the known trigger, audience, channel type, and `channelId`. Build every `groupContentList[].contentList[].content` item from `fieldRules.channelContentSchema`; do not infer App Push keys or parameter types from memory.
-5. **Prepare audience and completion inputs.** Resolve real event/property metadata and categorical values through the applicable Analysis workflow. Put the shared condition in `topicQp` or `topicClusterKey`, and only task-specific conditions in each `taskQp`. For a rolling condition such as "recent N days" that must be evaluated for future repeated sends, prefer a custom QP; use an existing cluster only after confirming that its refresh semantics match the send cadence. Build the completion goal separately in `completionIndicatorDef`.
-6. **Build one native `TopicAddDTO`.** Keep nested payload keys in camelCase. Ensure `tasks` is non-empty, `frequencyLimits` and QP fields are JSON strings where documented, each task has channel content, and Android/iOS or other variants map to the correct task audience and message.
+5. **Prepare audience and completion inputs.** Resolve real event/property metadata and categorical values through the applicable Analysis workflow. Put the shared condition in `topicDefinitionRequest` or `topicClusterKey`, and only task-specific conditions in each task's `definitionRequest`. For a rolling condition such as "recent N days" that must be evaluated for future repeated sends, prefer a semantic custom definition; use an existing cluster only after confirming that its refresh semantics match the send cadence. Build the completion goal separately in `completionIndicatorDef`.
+6. **Build one native `TopicAddDTO`.** Keep nested payload keys in camelCase. Ensure `tasks` is non-empty, each semantic definition is a JSON object, each task has channel content, and Android/iOS or other variants map to the correct task audience and message.
 7. **Validate the complex payload.** Run `topic create ... --validate` while correcting the nested payload. Inspect `normalized_input` and confirm that the schedule, audience boundaries, message variants, and completion window retain the intended semantics. After `valid=true`, execute the same payload directly; do not add a redundant dry-run by default.
 8. **Create exactly once.** Run `topic create` with the validated payload. A successful response only reports `data.success`; it does not provide enough evidence to declare the whole orchestration complete.
-9. **Resolve IDs and verify the saved topic.** Call `activity info-list` for the parent activity, match the new topic and tasks by their names, then call `topic get` with the returned `topicId`. Verify the channel, dates, cron, topic audience, each task audience, content, completion goal, and draft status. For custom audiences, confirm that the saved task QP keeps task-owned conditions in `totalCFilter` and the shared topic condition appears only through the topic-to-task merge.
+9. **Resolve IDs and verify the saved topic.** Call `activity info-list` for the parent activity, match the new topic and tasks by their names, then call `topic get` with the returned `topicId`. Verify the channel, dates, cron, semantic topic audience, each semantic task audience, content, completion goal, and draft status.
 10. **Verify generated audiences before reporting completion.** Read the generated topic/task cluster keys with the applicable cluster query and wait for terminal computation state. Require `refresh_status=success`, `progress=100`, `real_available=1`, and `cluster_valid=1`. A zero-user result may be valid, but reconcile it with the discovered categorical values and business expectation. If computation fails, correct only the verified cause and re-check; do not retry an unchanged request or report the topic as fully ready.
 
 Recommended command order:
@@ -95,7 +104,7 @@ activity list/get
 
 ## Output
 
-- `get`: `data.topic` (includes `topicClusterKey` for topic audience).
+- `get`: `data.topic` (includes `topicClusterKey` for an existing audience or `topic_definition_request` plus conversion status for a custom audience).
 - `create` / `update` / `remove-task` / `delete` / `copy`: `data.success`.
 - `copy` may include `data.trigger_time_stale=true` when source schedule-single time is already past.
 
@@ -104,7 +113,7 @@ activity list/get
 - `remove-task` and `delete` are `high-risk-write` — require `--yes`, no dry-run.
 - `remove-task` only deletes **topic tasks** (`topicId` present). Standalone tasks → use `engage-task task delete`.
 - `copy` duplicates the editable topic config and its tasks (not runtime/approval state).
-- `copy` saves via **draft** add (`isDraft=true`), so a past schedule-single `triggerTime` is allowed; output may include `trigger_time_stale=true`. Update the time before submitting for approval (`engage-activity.approval.submit` is temporarily unavailable).
+- `copy` saves via **draft** add (`isDraft=true`), so a past schedule-single `triggerTime` is allowed; output may include `trigger_time_stale=true`. Update the time before submitting for approval.
 - Prefer `topic get` as a template when inspecting channel/content fields.
 
 ## Create / update audience errors
@@ -113,9 +122,16 @@ activity list/get
 |---|---|
 | `TOPIC_TARGET_CLUSTER_TYPE_UNSUPPORTED` | `targetClusterType=3` (all); topics only allow 1/2 |
 | `TOPIC_CLUSTER_KEY_REQUIRED` | `targetClusterType=2` missing `topicClusterKey`, or topic-root `clusterKey` alias |
-| `TOPIC_QP_REQUIRED` | `targetClusterType=1` missing `topicQp` |
-| `TOPIC_QP_INVALID` | `topicQp` is not a JSON object string |
+| `TOPIC_DEFINITION_REQUIRED` | `targetClusterType=1` missing `topicDefinitionRequest` |
+| `TOPIC_DEFINITION_INVALID` | `topicDefinitionRequest` is not a semantic condition object |
 | `TARGET_CLUSTER_TYPE_INVALID` | `targetClusterType` not a known enum value |
+| `ACTIVITY_TRIGGER_TYPE_UNSUPPORTED` | topic uses manual or a triggered task type |
+| `ACTIVITY_EXPERIMENT_UNSUPPORTED` | topic or a topic task configures an experiment |
+| `ACTIVITY_CONTENT_GROUPS_UNSUPPORTED` | a topic task has multiple experiment-style content groups |
+| `TOPIC_TASK_OVERRIDE_UNSUPPORTED` | a topic task overrides shared topic settings or selects an independent cluster |
+| `TOPIC_TASK_AUDIENCE_EXCLUSION_UNSUPPORTED` | a topic task definition contains exclusion filters |
+| `ACTIVITY_STATUS_INVALID` | parent activity is not editable |
+| `ACTIVITY_SCHEDULE_OUT_OF_RANGE` | topic schedule is outside the parent activity period |
 
 ## Copy errors
 
@@ -129,6 +145,8 @@ activity list/get
 | `ACTIVITY_NOT_FOUND` | parent activity missing / deleted / wrong project |
 | `TOPIC_TASKS_REQUIRED` | source topic has no tasks |
 | `ACTIVITY_STATUS_INVALID` | parent activity is approving/working/complete |
+| `ACTIVITY_SCHEDULE_OUT_OF_RANGE` | source topic schedule is outside the parent activity period |
+| `ACTIVITY_CONTENT_GROUPS_UNSUPPORTED` | a source topic task has multiple content groups |
 | `TOPIC_COUNT_LIMIT` | activity topic count limit exceeded |
 | `CHANNEL_NOT_FOUND` | source channel missing / type mismatch |
 | `TASK_COUNT_LIMIT` | project task count limit exceeded |

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,16 @@ 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:
+3. Use semantic definitions for audience, trigger, and completion fields:
 
-```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
-```
+- `targetConfig.definitionRequest`
+- `triggerConfig.triggerDefinition` (required for `triggerType=3/4/5`)
+- `completionIndicatorDef.completionIndicators[].eventDefinition`
 
-Use the returned `skill` text to build:
-
-- `targetConfig.qp`
-- `triggerConfig.triggerRule` (required for `triggerType=3/4/5`)
-- `clientConfig.clientQp`
-- `completionIndicatorDef.event`
+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.
 
 For existing-cluster audiences (`targetClusterType=2`), you may copy server-authored definitions via:
 
@@ -41,11 +37,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 +57,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 +86,7 @@ Use `context` when you want scenario-specific guidance without writing a partial
 Typical fields:
 
 - `triggerType`
+- `eventTriggerType`
 - `targetClusterType`
 - `channelType`
 - `channelId`
@@ -104,7 +99,9 @@ Example:
 ```json
 {
   "context": {
-    "triggerType": 2,
+    "channelType": 2,
+    "triggerType": 3,
+    "eventTriggerType": 2,
     "targetClusterType": 2,
     "channelId": "channel_123"
   }
@@ -190,7 +187,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 +221,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 +247,25 @@ 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.
+
 ### 4.9 `handoff`
 
 This is the final section before `save_task`.
@@ -278,14 +296,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.