@thinkingai/ae-cli 6.1.10 → 6.1.11

package/skills/ae-analysis/references/system_smtp_test.md

@@ -0,0 +1,22 @@
+# system smtp test
+
+Use when the user needs to send one SMTP test using the saved configuration.
+
+Do not use it outside the system smtp operation or with fields absent from the inspected capability schema.
+
+Command:
+
+```bash
+ae-cli system smtp test --company-id <company-id> --receiver <receiver>
+```
+
+Capability id: `system.smtp.test`.
+
+The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--company-id` | Yes | Company ID. |
+| `--receiver` | Yes | Test email receiver. |

package/skills/ae-analysis/references/system_smtp_upsert.md

@@ -0,0 +1,31 @@
+# system smtp upsert
+
+Use when the user needs to create or update company SMTP configuration using a protected password source.
+
+Do not use it outside the system smtp operation or with fields absent from the inspected capability schema.
+
+Command:
+
+```bash
+ae-cli system smtp upsert --company-id <company-id> --server-host <server-host> --server-port <server-port> --sender-address <sender-address> --sender-name <sender-name> --password-file <chmod_600_file>
+```
+
+Capability id: `system.smtp.upsert`.
+
+Sensitive values are accepted only through a permission-protected file or stdin. Never put a secret value in argv, examples, logs, validation output, dry-run output, or the response.
+
+The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--company-id` | Yes | Company ID. |
+| `--server-host` | Yes | SMTP server host. |
+| `--server-port` | Yes | SMTP server port. |
+| `--has-encrypt` | No | Encryption mode: 0, 1, or 2. |
+| `--sender-address` | Yes | Sender email address. |
+| `--sender-name` | Yes | Sender display name. |
+| `--subject-prefix` | No | Optional subject prefix. |
+| `--password-file` | No | SMTP password. Read from a local permission-protected file; one of file/stdin is required. |
+| `--password-stdin` | No | SMTP password. Read from stdin; one of file/stdin is required. |

package/skills/ae-analysis/references/system_third_party_login_disable.md

@@ -0,0 +1,25 @@
+# system third-party-login disable
+
+Use when the user needs to disable a third-party login provider.
+
+Do not use it outside the system third-party-login operation or with fields absent from the inspected capability schema.
+
+Command:
+
+```bash
+ae-cli system third-party-login disable --dry-run --company-id <company-id> --login-type <login-type>
+ae-cli system third-party-login disable --company-id <company-id> --login-type <login-type> --yes
+```
+
+Capability id: `system.third_party_login.disable`.
+
+Run `--dry-run` first, summarize the affected target and impact, then wait for explicit user confirmation before rerunning the unchanged command with global `--yes`.
+
+The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--company-id` | Yes | Company ID. |
+| `--login-type` | Yes | Third-party login type. |

package/skills/ae-analysis/references/system_third_party_login_list.md

@@ -0,0 +1,21 @@
+# system third-party-login list
+
+Use when the user needs to list sanitized third-party login configurations.
+
+Do not use it outside the system third-party-login operation or with fields absent from the inspected capability schema.
+
+Command:
+
+```bash
+ae-cli system third-party-login list --company-id <company-id>
+```
+
+Capability id: `system.third_party_login.list`.
+
+The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--company-id` | Yes | Company ID. |

package/skills/ae-analysis/references/system_third_party_login_upsert.md

@@ -0,0 +1,33 @@
+# system third-party-login upsert
+
+Use when the user needs to create or update a third-party login configuration using protected secret sources.
+
+Do not use it outside the system third-party-login operation or with fields absent from the inspected capability schema.
+
+Command:
+
+```bash
+ae-cli system third-party-login upsert --company-id <company_id> --login-type feishu --app-id <app_id> --app-secret-file <chmod_600_file>
+ae-cli system third-party-login upsert --company-id <company_id> --login-type dingtalk --app-id <app_id> --corp-id <corp_id> --agent-id <agent_id> --dd-scan-app-id <scan_app_id> --app-secret-file <chmod_600_file> --dd-scan-app-secret-file <chmod_600_file>
+```
+
+Capability id: `system.third_party_login.upsert`.
+
+Sensitive values are accepted only through a permission-protected file or stdin. Never put a secret value in argv, examples, logs, validation output, dry-run output, or the response.
+
+The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--company-id` | Yes | Company ID. |
+| `--login-type` | Yes | Third-party login type. |
+| `--app-id` | Yes | Provider application ID. |
+| `--corp-id` | No | Provider corporation ID. |
+| `--agent-id` | No | Provider agent ID. |
+| `--dd-scan-app-id` | No | DingTalk scan-login application ID. |
+| `--app-secret-file` | No | Provider application secret. Read from a local permission-protected file; one of file/stdin is required. |
+| `--app-secret-stdin` | No | Provider application secret. Read from stdin; one of file/stdin is required. |
+| `--dd-scan-app-secret-file` | No | DingTalk scan-login application secret. Read from a local permission-protected file; the value is never accepted directly on argv. |
+| `--dd-scan-app-secret-stdin` | No | DingTalk scan-login application secret. Read from stdin; do not combine with --dd-scan-app-secret-file. |

package/skills/ae-analysis/references/system_usage_overview.md

@@ -0,0 +1,21 @@
+# system usage overview
+
+Use when the user needs to get the current company system-usage summary.
+
+Do not use it outside the system usage operation or with fields absent from the inspected capability schema.
+
+Command:
+
+```bash
+ae-cli system usage overview --company-id <company-id>
+```
+
+Capability id: `system.usage.overview`.
+
+The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--company-id` | Yes | Company ID. |

package/skills/ae-analysis/references/system_usage_trend_export.md

@@ -0,0 +1,44 @@
+# system usage-trend export
+
+Use when the user needs the complete usage-trend result as a cancellable gzip JSONL artifact.
+
+Do not use it for a small inline result; use `ae-cli system usage-trend query` instead.
+
+Command:
+
+```bash
+ae-cli system usage-trend export --company-id <company_id> --metric <metric> --start-time <yyyy-MM-dd> --end-time <yyyy-MM-dd> --time-granularity <day_or_week_or_month>
+```
+
+Capability id: `system.usage_trend.export`.
+
+The submit response returns the `run_id` for this exact export. Preserve it and poll:
+
+```bash
+ae-cli analysis run inspect --run-id <run_id>
+```
+
+When the run succeeds, preserve its `artifact_id` and download the same run-scoped artifact:
+
+```bash
+ae-cli analysis artifact download --run-id <run_id> --artifact-id <artifact_id> --output <output_path>
+```
+
+The artifact format is fixed gzip-compressed JSONL (`.jsonl.gz`); this command intentionally has no `--artifact-format`. Cancel an unfinished export with `ae-cli analysis query cancel --run-id <run_id>`.
+
+The response uses `ok`, `data`, and `meta`. Empty exported data is success when `ok=true`; preserve `request_id` and `invocation_id`.
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--company-id` | Yes | Company ID. |
+| `--metric` | Yes | One supported usage metric; `apollo_token` is not implemented. |
+| `--start-time` | Yes | Inclusive start date in `yyyy-MM-dd`. |
+| `--end-time` | Yes | Inclusive end date in `yyyy-MM-dd`. |
+| `--time-granularity` | Yes | `day`, `week`, or `month`. |
+| `--scope` | No | `company` or `project`; project scope requires `--project-ids`. |
+| `--project-ids` | No | Project ID JSON array. |
+| `--data-type` | No | `all`, `event`, or `user` for project-scoped total event volume. |
+| `--request-id` | No | Caller-supplied `cli_<32 lowercase hex>` lifecycle ID; generated when omitted. |
+| `--timeout-seconds` | No | Maximum runtime, `1..21600`; default `21600`. |

package/skills/ae-analysis/references/system_usage_trend_query.md

@@ -0,0 +1,28 @@
+# system usage-trend query
+
+Use when the user needs to query a bounded company or project usage trend.
+
+Do not use it outside the system usage-trend operation or with fields absent from the inspected capability schema.
+
+Command:
+
+```bash
+ae-cli system usage-trend query --company-id <company-id> --start-time <start-time> --end-time <end-time> --metric <metric> --time-granularity <time-granularity>
+```
+
+Capability id: `system.usage_trend.query`.
+
+The response uses `ok`, `data`, and `meta`. Treat empty `data` as success when `ok=true`; preserve `request_id` and `invocation_id` when present.
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--company-id` | Yes | Company ID. |
+| `--start-time` | Yes | Inclusive ISO date/time lower bound. |
+| `--end-time` | Yes | Inclusive ISO date/time upper bound. |
+| `--metric` | Yes | Supported usage metric; apollo_token is not available. |
+| `--time-granularity` | Yes | Aggregation granularity. |
+| `--scope` | No | Aggregation scope. |
+| `--project-ids` | No | Project ID JSON array; required for project scope. |
+| `--data-type` | No | Optional event-volume data type. |

package/skills/ae-dataops/SKILL.md

@@ -89,7 +89,7 @@ You must understand the following key concepts before use, otherwise errors are
 ### Flow Lifecycle
 
 ```
-Create DEV Flow → Create/Update DEV SQL Tasks → Configure Dependencies/Schedule → Preview Release → Release to PROD → PROD Manual Execution / Operations Troubleshooting
+Create DEV Flow → Create/Update DEV SQL, Integration, or Workflow Instance Check Tasks → Configure Dependencies/Schedule → Preview Release → Release to PROD → PROD Manual Execution / Operations Troubleshooting
 ```
 
 ### CRON Format (6 fields)

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

@@ -41,7 +41,7 @@ ae-cli dataops_flow +create_sql_task --spaceCode "${spaceCode}" \
 # Create task with upstream dependency
 ae-cli dataops_flow +create_sql_task --spaceCode "${spaceCode}" \
   --flowCode ${flowCode} --taskName "Export Results" \
-  --preTaskCode ${upstreamTaskCode} \
+  --preTasks "[${upstreamTaskCode},${anotherUpstreamTaskCode}]" \
   --sql "INSERT INTO ads_user SELECT * FROM dwd_user"
 ```
 
@@ -63,23 +63,40 @@ ae-cli dataops_flow +update_integration_task --spaceCode "${spaceCode}" \
 
 Use `dataops_integration +list_sync_solutions` or `+get_sync_detail` to find the `syncId` first. These commands expose workflow `OFFLINE_SYNC` tasks only; app sync tasks are not part of this flow.
 
-### Step 4: Modify SQL Task Content
+### Step 4: Create or Modify Workflow Instance Check Task
+
+`checkItems` is a flat JSON array. Every item contains only `flowCode`, `left`, `right`, and `checkTimeUnit` (`DAY`, `HOUR`, or `MINUTE`). One `AND` or `OR` relation applies to the entire array; nested groups are not supported. For the current workflow, `left` and `right` are at least `1`; for another workflow they may be `0`; `right` must not exceed `left`.
+
+```bash
+ae-cli dataops_flow +create_workflow_instance_check_task --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --taskName "Wait for upstream workflows" \
+  --checkItems '[{"flowCode":10037355068544,"left":1,"right":1,"checkTimeUnit":"DAY"},{"flowCode":10037355068545,"left":2,"right":0,"checkTimeUnit":"HOUR"}]' \
+  --relation OR
+
+ae-cli dataops_flow +update_workflow_instance_check_task --spaceCode "${spaceCode}" \
+  --flowCode ${flowCode} --taskCode ${taskCode} \
+  --checkItems '[{"flowCode":10037355068544,"left":1,"right":1,"checkTimeUnit":"DAY"}]'
+```
+
+Create defaults are `relation=AND`, `checkInterval=5`, `checkTime=3`, `failRetryTimes=3`, `failRetryInterval=5`, and `failRetryUnit=MINUTE`. On update, omitted check scalars, dependencies, and retry fields keep their current values.
+
+### Step 5: Modify SQL Task Content
 
 ```bash
-# Update SQL task content without changing owner, remark, dependencies, retry, or timeout
+# Update SQL task content and keep dependencies and retry policy
 ae-cli dataops_flow +update_sql_task --spaceCode "${spaceCode}" \
   --flowCode ${flowCode} --taskCode ${taskCode} \
   --sql "SELECT * FROM dwd_user"
 ```
 
-### Step 5: Add Task Dependencies (DAG connections)
+### Step 6: Add Task Dependencies (DAG connections)
 
 ```bash
 ae-cli dataops_flow +add_task_relation --spaceCode "${spaceCode}" \
   --flowCode ${flowCode} --preTaskCode ${upstreamTaskCode} --taskCode ${downstreamTaskCode}
 ```
 
-### Step 6: Configure Schedule
+### Step 7: Configure Schedule
 
 ```bash
 # CRON expression for scheduled execution
@@ -93,7 +110,7 @@ ae-cli dataops_flow +save_schedule_config --spaceCode "${spaceCode}" \
 - `0 0 */4 * * ?` — Every 4 hours
 - `0 30 8 * * 1-5` — Weekdays at 8:30
 
-### Step 7: Preview Release
+### Step 8: Preview Release
 
 ```bash
 # Preview pending DEV-to-PROD release changes before publishing
@@ -101,7 +118,7 @@ ae-cli dataops_flow +preview_release_flow --spaceCode "${spaceCode}" \
   --flowCode ${flowCode}
 ```
 
-### Step 8: Release to Production and Verify
+### Step 9: Release to Production and Verify
 
 ```bash
 ae-cli dataops_flow +release_flow --spaceCode "${spaceCode}" \
@@ -130,10 +147,12 @@ ae-cli dataops_operations +get_task_instance_detail --spaceCode "${spaceCode}" \
 | Command | Purpose | Key Flags |
 |---------|---------|-----------|
 | `+create_flow` | Create DEV flow | `--spaceCode` `--flowName` `[--remark]` |
-| `+create_sql_task` | Create DEV Trino SQL task and save SQL | `--spaceCode` `--flowCode` `--taskName` `--sql` `[--preSql]` `[--postSql]` `[--preTaskCode]` `[--remark]` |
-| `+update_sql_task` | Update DEV Trino SQL task content | `--spaceCode` `--flowCode` `--taskCode` `--sql` `[--preSql]` `[--postSql]` |
-| `+create_integration_task` | Create DEV integration sync task from an existing sync solution | `--spaceCode` `--flowCode` `--taskName` `--syncId` `[--preTaskCode]` `[--remark]` |
-| `+update_integration_task` | Rebind DEV integration sync task to a sync solution | `--spaceCode` `--flowCode` `--taskCode` `--syncId` |
+| `+create_sql_task` | Create DEV Trino SQL task and save SQL | `--spaceCode` `--flowCode` `--taskName` `--sql` `[--preSql]` `[--postSql]` `[--preTasks]` `[--failRetryTimes]` `[--failRetryInterval]` `[--failRetryUnit]` `[--remark]` |
+| `+update_sql_task` | Update DEV Trino SQL task content | `--spaceCode` `--flowCode` `--taskCode` `--sql` `[--preSql]` `[--postSql]` `[--preTasks]` `[--failRetryTimes]` `[--failRetryInterval]` `[--failRetryUnit]` |
+| `+create_integration_task` | Create DEV integration sync task from an existing sync solution | `--spaceCode` `--flowCode` `--taskName` `--syncId` `[--preTasks]` `[--failRetryTimes]` `[--failRetryInterval]` `[--failRetryUnit]` `[--remark]` |
+| `+update_integration_task` | Rebind DEV integration sync task to a sync solution | `--spaceCode` `--flowCode` `--taskCode` `--syncId` `[--preTasks]` `[--failRetryTimes]` `[--failRetryInterval]` `[--failRetryUnit]` |
+| `+create_workflow_instance_check_task` | Create DEV workflow instance check task | `--spaceCode` `--flowCode` `--taskName` `--checkItems` `[--relation]` `[--checkInterval]` `[--checkTime]` `[--preTasks]` `[retry flags]` `[--remark]` |
+| `+update_workflow_instance_check_task` | Update DEV workflow instance check task | `--spaceCode` `--flowCode` `--taskCode` `--checkItems` `[--relation]` `[--checkInterval]` `[--checkTime]` `[--preTasks]` `[retry flags]` |
 | `+add_task_relation` | Add DEV dependency | `--spaceCode` `--flowCode` `--preTaskCode` `--taskCode` |
 | `+save_schedule_config` | Save DEV schedule config | `--spaceCode` `--flowCode` `--enabled` `[--cron]` |
 | `+get_task_params` | View DEV task parameter list | `--spaceCode` `--flowCode` `--taskCode` |
@@ -150,17 +169,33 @@ ae-cli dataops_operations +get_task_instance_detail --spaceCode "${spaceCode}" \
 - **Schedule config**: `+save_schedule_config` requires `--spaceCode`, `--flowCode`, and `--enabled`. `--cron` is required only when `--enabled true`; omit it when disabling scheduling. It returns `action/result/status`; `result` includes `enabled`, `flow`, `message`, and `cron` only when enabled.
 - **Release preview**: `+preview_release_flow` requires `--spaceCode` and `--flowCode`; it has no optional flags. It returns `flowCode`, `releaseStatus`, `message`, and `changes`. Each change may include `scheduleConfigChange` and `tasks`; task entries may include `changed`, `contentCompare`, and `targetTable`.
 - **Release**: `+release_flow` requires `--spaceCode` and `--flowCode`; it has no optional flags. It returns `action/result/status`; `result` includes `flowCode`, `releaseStatus`, `message`, optional `packageCode`, and optional `changes`. Each change may include `scheduleConfigChange` and `tasks`; task entries include `changed`.
-- **SQL task creation**: `+create_sql_task` requires `--spaceCode`, `--flowCode`, `--taskName`, and `--sql`; `--preSql`, `--postSql`, `--preTaskCode`, and `--remark` are optional. It returns `action/result/status`; `result` includes `flowCode`, `taskCode`, `taskName`, `taskType=TRINO_SQL`, and `sqlSaved=true`.
-- **SQL task update**: `+update_sql_task` requires `--spaceCode`, `--flowCode`, `--taskCode`, and `--sql`; `--preSql` and `--postSql` are optional and keep existing values when omitted. It returns `action/result/status`; `result` includes `sqlSaved`, `flowCode`, `taskCode`, `taskType=TRINO_SQL`, and `task`.
+- **Task dependencies**: `--preTasks` is a JSON array of upstream task codes on SQL, integration, and workflow instance check create/update commands. Omit `--preTasks` on update to preserve existing dependencies; pass `--preTasks '[]'` to clear them; pass a non-empty array to replace them.
+- **Retry policy**: The three task types accept `--failRetryTimes`, `--failRetryInterval`, and `--failRetryUnit`. Create defaults to `3`, `5`, and `MINUTE`. Update preserves every omitted retry field. `MINUTE` is the only supported unit.
+- **SQL task creation**: `+create_sql_task` requires `--spaceCode`, `--flowCode`, `--taskName`, and `--sql`; SQL hooks, dependencies, retry policy, and remark are optional. It returns `action/result/status`; `result` includes `flowCode`, `taskCode`, `taskName`, `taskType=TRINO_SQL`, and `sqlSaved=true`.
+- **SQL task update**: `+update_sql_task` requires `--spaceCode`, `--flowCode`, `--taskCode`, and `--sql`; omitted SQL hooks, dependencies, and retry fields keep existing values. It returns `action/result/status`; `result` includes `sqlSaved`, `flowCode`, `taskCode`, `taskType=TRINO_SQL`, and `task`.
 - **Task dependency**: `+add_task_relation` requires `--spaceCode`, `--flowCode`, `--preTaskCode`, and `--taskCode`. `preTaskCode` is upstream and `taskCode` is downstream. It returns `action/result/status`; `result` includes `status`, `flowCode`, `preTaskCode`, `taskCode`, and `message`.
 - **Task parameters**: `+get_task_params` requires `--spaceCode`, `--flowCode`, and `--taskCode`; it has no optional flags. It queries DEV and returns `data` as an array. Items include fields such as `paramKey`, `paramType`, `paramDataType`, `paramFrom`, and built-in flags like `isBd`.
-- **Integration task creation**: `+create_integration_task` requires `--spaceCode`, `--flowCode`, `--taskName`, and `--syncId`; `--preTaskCode` and `--remark` are optional. It returns `action/result/status`; `result` includes `syncTaskSaved`, `flowCode`, `taskCode`, `taskName`, `taskType=OFFLINE_SYNC`, `syncId`, and `nextAction`.
-- **SQL task dependencies**: Use optional `--preTaskCode` to create one upstream dependency with the task. Use `+add_task_relation` for additional DAG dependencies.
+- **Integration task creation**: `+create_integration_task` requires `--spaceCode`, `--flowCode`, `--taskName`, and `--syncId`; dependencies, retry policy, and remark are optional. It returns `action/result/status`; `result` includes `syncTaskSaved`, `flowCode`, `taskCode`, `taskName`, `taskType=OFFLINE_SYNC`, `syncId`, and `nextAction`.
+- **Workflow instance check tasks**: `checkItems` is required and replaces the complete check item list. Create defaults `relation/checkInterval/checkTime` to `AND/5/3`; update preserves omitted scalar values. This command creates `FLOW_CHECK`, not task-instance `TASK_CHECK`.
+
+## Transport Status
+
+Transition status: transitional
+
+Owning module: gaia-mcp workflow
+
+Current transport: DataOps CLI REST
+
+Gateway target: TBD after DataOps workflow Gateway schema review
+
+Review after: 2026-10-27
+
+Exit condition: Migrate or remove these one-to-one commands after equivalent Capability Gateway actions are available.
 
 ## Important Notes
 
 1. **Getting flowCode**: Use `+list_flows` (see `dataops-flow-monitor` Skill)
-2. **Getting taskCode**: Returned by `+create_sql_task` / `+create_integration_task` or query via `+get_flow_overview`
+2. **Getting taskCode**: Returned by a task create command or query via `+get_flow_overview`
 3. **Release Impact**: Submits current DEV changes to PROD; released schedule/config applies to future PROD runs
 4. **SQL Validation**: Recommended to validate before saving TRINO_SQL tasks
 5. **Cannot create circular dependencies**

package/skills/ae-engage/SKILL.md

@@ -52,9 +52,9 @@ When the user mentions a product term below (including common Chinese UI labels)
 | **Config center** | Engage scene management / config center overview | `engage-scene` | `references/scene-config-item.md` | `scene-config-param.md`, `scene-config-group.md`, `scene-preset-metric.md`, `scene-config-metric.md`, `scene-config-channel.md`, `channel-mgmt.md`, `scene-strategy.md`, `scene-template.md`; L3 reports: `config-item-trigger-report.md`, `config-item-analysis-report.md`, `config-item-strategy-comparison.md` |
 | **Scene config** | Same as config center; params, groups, metrics, channels, strategies, and templates under a config item | `engage-scene` | `references/scene-config-item.md` | Same as above; params/groups/metrics: `scene-config-param.md`, `scene-config-group.md`, `scene-preset-metric.md`, `scene-config-metric.md` |
 | **Config item** | A single config item in the config center | `engage-scene` | `references/scene-config-item.md` | `scene-config-param.md`, `scene-preset-metric.md`, `scene-config-metric.md`, `scene-strategy.md`, `scene-template.md` |
-| **Push channel** | Project-level message push channels (Webhook, FCM, APNS, etc.) | `engage-setting` | `references/channel-list.md` | `channel-detail.md`, `add-channel.md`, `update-channel-status.md`, `delete-channel.md`, `channel-update-config.md`, `channel-test-send.md`, `channel_touch_limits_list.md` |
+| **Push channel** | Project-level message push channels (Webhook, FCM, APNS, etc.) | `engage-setting` | `references/channel-list.md` | `channel-detail.md`, `add-channel.md` (**Webhook vs Client differ**: `url` = HTTP vs scene key; custom params `user:` vs `user:`/`client:`), `update-channel-status.md`, `delete-channel.md`, `channel-update-config.md`, `channel-test-send.md`, `channel_touch_limits_list.md` |
 | **Config channel** | Config-center Webhook/client config channels (not the same as push channels) | `engage-scene` | `references/scene-config-channel.md` | `channel-mgmt.md` (create/enable-disable/copy/delete workflows). User params in `config.customsParamList` require `columnName` with `user:` prefix (e.g. `user:#account_id`); preflight names with ae-analysis `analysis-meta property list/get`. |
-| **Operation strategy** | Ops/delivery strategies under a config item | `engage-scene` | `references/scene-strategy.md` | Custom audience QP: [`scene-strategy-audience.md`](references/scene-strategy-audience.md) — **用户满足** `filts[0]` + **用户行为** `filts[1]` two-block mix QP; preflight props (stop + list if missing); examples A/B/C; template: `scene-template.md` |
+| **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` |
 | **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 |
 
@@ -145,13 +145,13 @@ ae-cli engage-setting config-table delete --project-id <project_id> --info-id <i
 
 # Preset event list / update
 ae-cli engage-setting preset-event list --project-id <project_id>
-ae-cli engage-setting preset-event update --project-id <project_id> --add-event-desc <qp>
+ae-cli engage-setting preset-event update --project-id <project_id> --add-event-definition '<semantic_event_json>'
 
 # Common metric list / get / create / update / delete
 ae-cli engage-setting common-metric list --project-id <project_id>
 ae-cli engage-setting common-metric get --project-id <project_id> --metric-name <name>
-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>
-ae-cli engage-setting common-metric update --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>
+ae-cli engage-setting common-metric create --project-id <project_id> --metric-type 1 --metric-name <name> --metric-definition '<semantic_metric_json>' --metric-window-num 1 --metric-window-time-unit day --display-name <display>
+ae-cli engage-setting common-metric update --project-id <project_id> --metric-type 1 --metric-name <name> --metric-definition '<semantic_metric_json>' --metric-window-num 1 --metric-window-time-unit day --display-name <display>
 ae-cli engage-setting common-metric delete --project-id <project_id> --metric-name <name> --yes
 ```
 
@@ -170,6 +170,9 @@ ae-cli engage-task task save --project-id 1 --req '{"baseInfo":{"taskName":"Demo
 # Query task details
 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
+
 ```
 
 For L3 task reports, read `references/task-data-overview.md`, `references/task-data-detail.md`,
@@ -210,6 +213,7 @@ ae-cli engage-task group list --project-id 1
 ae-cli engage-task metric list --project-id 1 --task-id task_id_123
 ae-cli engage-task channel-ref stats --project-id 1 --channel-id channel_123
 ae-cli engage-task task delete --project-id 1 --task-id task_id_123 --yes
+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
@@ -241,7 +245,7 @@ ae-cli engage-scene config-group batch-delete --project-id <project_id> --group-
 
 # Preset metric get / set
 ae-cli engage-scene preset-metric get --project-id <project_id> --config-id <config_id>
-ae-cli engage-scene preset-metric set --project-id <project_id> --config-id <config_id> --impression-event-qp '<qp>'
+ae-cli engage-scene preset-metric set --project-id <project_id> --config-id <config_id> --impression-event-definition '<semantic_event_json>'
 
 # Config metric list / get / batch-add / update-rule / batch-delete
 ae-cli engage-scene config-metric list --project-id <project_id> --config-id <config_id>
@@ -252,7 +256,7 @@ ae-cli engage-scene config-metric batch-delete --project-id <project_id> --confi
 
 # Config channel list / get / create / update / update-status / delete / query-log
 # User params: verify each customsParamList columnName via ae-analysis property list/get first; then use user:<prop_name>
-# Strategy custom audience: scene-strategy-audience.md — mix QP filts[0]=用户满足, filts[1]=用户行为; strategy predict for 预估人数
+# Strategy custom audience: scene-strategy-audience.md — semantic definitionRequest; strategy predict for 预估人数
 # Workflows: references/channel-mgmt.md · schema: references/scene-config-channel.md
 ae-cli engage-scene config-channel list --project-id <project_id> [--channel-type 0|1]
 ae-cli engage-scene config-channel get --project-id <project_id> --channel-id <channel_id>
@@ -266,7 +270,7 @@ ae-cli engage-scene config-channel query-log --project-id <project_id> --channel
 ae-cli engage-scene strategy create --project-id <project_id> --payload '{"configId":"cfg-1","templateId":"tpl-1","strategyName":"s1"}'
 ae-cli engage-scene strategy update --project-id <project_id> --payload '{"strategyUuid":"uuid-1"}'
 ae-cli engage-scene strategy log --project-id <project_id> --strategy-uuid <uuid>
-ae-cli engage-scene strategy predict --project-id <project_id> --qp '<mix QP string>' --zone-offset 8 [--strategy-uuid <uuid>]
+ae-cli engage-scene strategy predict --project-id <project_id> --definition-request '{"type":"condition","conditions":{...}}' --zone-offset 8 [--strategy-uuid <uuid>]
 ae-cli engage-scene strategy batch-copy --project-id <project_id> --config-id <config_id> --strategy-ids '["s1"]'
 
 # Template list / get / create / update / update-status / delete
@@ -282,6 +286,18 @@ ae-cli engage-scene template delete --project-id <project_id> --config-id <confi
 
 New capability-gateway command group `engage-activity` covers campaign activities: activities, approval workflow, topics, activity types, and standalone tasks. Complex DTOs are passed with `--payload` (native camelCase JSON).
 
+### Activity payload guardrails
+
+Before generating any activity topic or standalone-task payload, enforce the same subset exposed by the Hermes activity UI:
+
+- `triggerType` must be `0` (schedule single) or `1` (schedule repeat). Activity tasks do not support manual (`2`) or triggered (`3`-`6`) task types.
+- Do not configure A/B or horse-race experiments. Omit `expConfig` or use only `{"enableExp":false}`, and provide exactly one non-experiment `groupContentList` group.
+- Standalone activity tasks must use `triggerTimeStrategy: "fixed_time_zone"` and the parent activity `tzOffset`. Schedule times must remain inside the activity period.
+- A topic root supports audience types `1` (custom) and `2` (existing cluster), not `3` (all users). A standalone activity task may use `1`, `2`, or `3`.
+- Topic tasks inherit schedule, timezone, channel, frequency limits, channel touch limits, whitelist, and experiment settings from the topic. They may only add an inclusion-only custom `definitionRequest`; never generate task-level `clusterKey`, trigger rules, or shared-setting overrides. `topic get` may return the canonical task marker `targetClusterType=1`; preserve it for update if present, but never use another task-level value.
+- Resolve the parent activity first and confirm it is editable (`mappingStatus` `0`, `2`, or `5`). Limits for topics, tasks, and languages are project configuration values; do not hardcode defaults.
+- `approval submit` and `approval approve` validate every persisted activity task. Approval does not normalize unsupported task data. On `ACTIVITY_TASK_COMPATIBILITY_VIOLATION`, cancel/withdraw approval as needed, correct or recreate each reported task, and submit again.
+
 ```bash
 # Activity create / update / delete / list / get / pause / end / stats / info-list
 ae-cli engage-activity activity create --project-id <project_id> --payload '{"activityName":"a1","activityType":"other_type","tzOffset":8,"periodType":0}'
@@ -294,8 +310,8 @@ ae-cli engage-activity activity end --project-id <project_id> --activity-id <act
 ae-cli engage-activity activity stats --project-id <project_id>
 ae-cli engage-activity activity info-list --project-id <project_id> --activity-id <activity_id>
 
-# Approval approve / reject / cancel
-# Note: engage-activity.approval.submit is temporarily disabled (testing issues); do not call it.
+# Approval submit / approve / reject / cancel
+ae-cli engage-activity approval submit --project-id <project_id> --activity-id <activity_id> [--reason <reason>]
 ae-cli engage-activity approval approve --project-id <project_id> --activity-id <activity_id>
 ae-cli engage-activity approval reject --project-id <project_id> --activity-id <activity_id> --reason <reason>
 ae-cli engage-activity approval cancel --project-id <project_id> --activity-id <activity_id>
@@ -346,12 +362,9 @@ When the user wants to "create a flow / generate a flow canvas / save a flow", d
    - The touchpoint or delivery method
    - Whether branching is needed, and the branching conditions
 2. Do not jump directly from natural language to `--req`. You must first organize a stable intermediate intent structure, then map it to the final `req`.
-3. Before building condition-related nodes, create the reusable audience directly from its semantic definition, then read back the server-authored definition only if the Engage schema explicitly needs QP-derived fields:
-
-```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>"]'
-```
+3. Build condition-related nodes with semantic `targetDefinitionRequest` and
+   `triggerDefinition` objects. Resolve real event and property names through Analysis metadata;
+   do not create an intermediate cluster merely to obtain persisted QP.
 
 4. Before building touchpoint nodes such as `message_push`, `wechat_push`, or `webhook_push`, you must call:
 
@@ -361,7 +374,7 @@ 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. If `targetClusterQp` appears inside a node `config`, its value is usually a `JSON.stringify`'d string, not a raw object.
+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.
 8. You must self-check before previewing/committing:
    - There is exactly one entry node
    - There is at least one `exit_flow`
@@ -437,13 +450,13 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `references/scene-config-channel.md` (`engage-scene.config-channel.{list,get,create,update,update-status,delete,query-log}`)
 - `references/channel-mgmt.md` (config channel management workflows)
 - `references/scene-strategy.md` (`engage-scene.strategy.{list,get,create,update,log,predict,batch-copy,manage}`)
-- `references/scene-strategy-audience.md` (custom audience mix QP: 用户满足/用户行为 two-block layout, preflight, worked examples A/B/C)
+- `references/scene-strategy-audience.md` (custom audience semantic `definitionRequest`, preflight, predict)
 - `references/scene-template.md` (`engage-scene.template.{list,get,copy,create,update,update-status,delete}`)
 - `references/config-item-trigger-report.md` (`engage-scene.report.config-item-trigger`, L3)
 - `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-approval.md` (`engage-activity.approval.{approve,reject,cancel}`; `submit` temporarily disabled)
+- `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}`)
 - `references/activity-task.md` (`engage-activity.task.{get,create,update,copy}`)
@@ -460,6 +473,7 @@ More detailed single-command guidance is available in the business-oriented `ref
 - `references/segment-list-query.md` (`engage-task.segment-list.query`)
 - `references/group-list.md` (`engage-task.group.list`)
 - `references/task-delete.md` (`engage-task.task.delete`)
+- `references/task-submit-approval.md` (`engage-task.task.submit-approval`)
 
 This split documentation structure is easier to extend later, because commands with more complex object inputs can stay centralized in the `references/` root directory.
 
@@ -471,7 +485,7 @@ 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 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` (via `engage-task`), plus L3 capabilities `engage-task.task-data.{overview,detail,metric-detail,experiment-report}`
 
 ### config
 
@@ -483,7 +497,7 @@ Legacy config MCP commands are migrated into the `scene` L2 group and the three
 
 ### activity
 
-`activity create` / `activity update` / `activity delete` / `activity list` / `activity get` / `activity pause` / `activity end` / `activity stats` / `activity info-list` / `approval approve` / `approval reject` / `approval cancel` / `topic create` / `topic update` / `topic remove-task` / `topic delete` / `topic get` / `topic copy` / `activity-type list` / `activity-type batch-add` / `activity-type update` / `activity-type batch-delete` / `task get` / `task create` / `task update` / `task copy` (via `engage-activity`), capability ids `engage-activity.activity.{create,update,delete,list,get,pause,end,stats,info-list}`, `engage-activity.approval.{approve,reject,cancel}`, `engage-activity.topic.{create,update,remove-task,delete,get,copy}`, `engage-activity.activity-type.{list,batch-add,update,batch-delete}`, `engage-activity.task.{get,create,update,copy}`
+`activity create` / `activity update` / `activity delete` / `activity list` / `activity get` / `activity pause` / `activity end` / `activity stats` / `activity info-list` / `approval submit` / `approval approve` / `approval reject` / `approval cancel` / `topic create` / `topic update` / `topic remove-task` / `topic delete` / `topic get` / `topic copy` / `activity-type list` / `activity-type batch-add` / `activity-type update` / `activity-type batch-delete` / `task get` / `task create` / `task update` / `task copy` (via `engage-activity`), capability ids `engage-activity.activity.{create,update,delete,list,get,pause,end,stats,info-list}`, `engage-activity.approval.{submit,approve,reject,cancel}`, `engage-activity.topic.{create,update,remove-task,delete,get,copy}`, `engage-activity.activity-type.{list,batch-add,update,batch-delete}`, `engage-activity.task.{get,create,update,copy}`
 
 ### workbench
 
@@ -505,19 +519,35 @@ High-risk delete commands (`risk: high-risk-write`) require explicit user author
 - Config channels (config center channel management): `engage-scene config-channel create|update|update-status` (write), `engage-scene config-channel delete` (high-risk-write)
 - Strategies and config items: `engage-scene config-item delete` (high-risk-write), `engage-scene template copy` and `engage-scene strategy manage` (write)
 - Flows: `engage-flow flow update-remark` (write), `engage-flow flow save` (write), `engage-flow flow modify-base-info` (write), `engage-flow flow manage` (write), `engage-flow flow delete` (high-risk-write)
-- Tasks: `engage-task task save` (write), `engage-task task manage` (write)
+- Tasks: `engage-task task save` (write), `engage-task task submit-approval` (write), `engage-task task manage` (write)
 
 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. If the guide says QP-derived fields are needed (`targetConfig.qp`, `triggerConfig.triggerRule`, `clientConfig.clientQp`, or `completionIndicatorDef.event`), call:
-   `ae-cli engage-setting query cluster-qp-skill --project-id <projectId>`
-   Use the returned skill text to build those fields. For existing-cluster audiences (`targetClusterType=2`), use `analysis user-cluster get` instead of hand-writing QP.
+3. For a custom audience, pass the Analysis semantic contract as
+   `targetConfig.definitionRequest`. Use semantic `triggerConfig.triggerDefinition` and
+   `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.
 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`.
 
 `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).
 
-Audience creation is not a fixed preflight step. When the guide requires QP-derived fields (`targetConfig.qp`, `triggerConfig.triggerRule`, `clientConfig.clientQp`, `completionIndicatorDef.event`), call `ae-cli engage-setting query cluster-qp-skill --project-id <projectId>` first and follow the returned skill definition; do not assemble raw QP manually. For existing-cluster audiences, use `analysis user-cluster get` to copy server-authored definitions when appropriate.
+`engage-task task submit-approval --task-id` is the recommended approval path after `task save`.
+It submits the persisted draft without requiring the Agent to reconstruct internal `trigger_rule`.
+The legacy `--request` mode remains available for compatibility; provide exactly one of
+`--task-id` or `--request`.
+
+Audience creation is not a fixed preflight step. For custom task audiences, use semantic
+`targetConfig.definitionRequest`; `task get` returns the same contract as
+`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.

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

@@ -56,6 +56,9 @@ ae-cli engage-activity activity info-list --project-id <project_id> --activity-i
 - `get`: `data.activity`.
 - `stats`: `data.status_count`.
 - `info-list`: `data.info` with `taskList` (standalone tasks) and `topicList` (topics under the activity).
+  This summary intentionally omits stored QP-bearing detail fields such as `qp`,
+  `triggerRule`, `completionIndicatorDef`, and `clientQp`. Use the corresponding task
+  or topic detail command to obtain the semantic definitions before editing.
 - `delete` / `pause` / `end`: `data.success`.
 
 ## Timezone (`tzOffset`)