ae-engage

AE CLI (

ae-cli

) is the command-line tool for the ThinkingEngine data analysis platform, used by AI Agents and human users.

AE CLI（

ae-cli

）是ThinkingEngine数据分析平台的命令行工具，供AI Agents和人类用户使用。

Global AE CLI Rules

全局AE CLI规则

AE CLI (

ae-cli

) is the command-line tool for the AE / TE / ThinkingEngine analysis platform. For AE analysis-side requests, prefer

ae-cli

and this skill's reference docs over model memory.

Global parameters:

Parameter	Description
`--format <json\|table>`	Output format. Default is JSON.
`--jq <expr>`	jq filter expression for JSON output.
`--host <url>`	Override the active AE host. Available on every command and may be placed after the subcommand, e.g. `ae-cli engage-flow flow list --host <url>` .

Output and errors:

Successful commands return machine-readable JSON by default. Envelope may include optional
```
_notice.host_compat
```
.

Failed commands return

{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }

and exit non-zero.

CRITICAL — Host compat (do this first): After each
```
ae-cli
```
run, check stderr and
```
_notice.host_compat
```
. If either is present, open the user reply with a short ⚠️ version warning and quote the
npm i -g
/
npx skills add
(or update-cluster) lines verbatim, then present the business result. Soft tip;
```
ok: true
```
can still carry the notice.

Safety constraints:

Read commands can execute directly after required IDs and references are verified.
Write commands require explicit user intent. Ordinary
```
write
```
commands execute without CLI confirmation; only
```
high-risk-write
```
commands use the confirmation gate.
Never invent command names, flags, JSON payloads,
```
project_id
```
, resource IDs, field names, event names, property names, metric definitions, or date formats. Read the matching command reference and discover real project metadata first.
NEVER fabricate or guess resource names (reports, dashboards, events, properties, metrics, clusters, tags, alerts). Always use list commands to discover real resources first. If a resource is not found after fuzzy search and full list fallback, explicitly tell the user "resource not found" and stop - do not proceed with fabricated names.

AE CLI（

ae-cli

）是AE / TE / ThinkingEngine分析平台的命令行工具。对于AE分析侧的请求，优先使用

ae-cli

和本技能的参考文档，而非模型记忆。

全局参数：

参数	描述
`--format <json\|table>`	输出格式，默认值为JSON。
`--jq <expr>`	用于JSON输出的jq过滤表达式。
`--host <url>`	覆盖当前激活的AE主机地址。可用于所有命令，且可放在子命令之后，例如 `ae-cli engage-flow flow list --host <url>` 。

输出与错误处理：

成功执行的命令默认返回机器可读的JSON格式，返回结果中可能包含可选的
```
_notice.host_compat
```
字段。

执行失败的命令返回

{ "ok": false, "error": { "type": "...", "message": "...", "hint": "..." } }

并返回非零退出码。

关键注意事项 — 主机兼容性（优先处理）：每次执行
```
ae-cli
```
后，检查标准错误输出和
```
_notice.host_compat
```
字段。如果其中任一存在，在用户回复开头添加简短的⚠️版本警告，并逐字引用
npm i -g
/
npx skills add
（或update-cluster）命令，之后再展示业务结果。即使
```
ok: true
```
也可能携带该通知，需软提示用户。

安全约束：

读取类命令在验证所需ID和引用信息无误后可直接执行。
写入类命令需要明确的用户意图。普通
```
write
```
命令无需CLI确认即可执行；仅
```
high-risk-write
```
命令需要确认环节。
禁止自行编造命令名称、标志、JSON负载、
```
project_id
```
、资源ID、字段名、事件名、属性名、指标定义或日期格式。需先查阅匹配的命令参考文档并获取真实的项目元数据。
绝对禁止编造或猜测资源名称（报表、仪表盘、事件、属性、指标、集群、标签、告警）。必须先使用列表命令发现真实资源。如果模糊搜索和全量列表查询后仍未找到资源，需明确告知用户“资源未找到”并停止操作，不得使用编造的名称继续执行。

Overview

概述

The

ae-engage

package provides Hermes Engage capabilities across config items, flows, channel settings, task data, and query lifecycle. Use capability-gateway commands through

ae-cli engage-flow|engage-task|engage-setting|engage-scene|engage-query <resource> <action>

; low-frequency reports use the L3 references below.

Typical use cases include:

Querying and managing channels, config channels, approvers, and whitelists
Querying project channel touch-limit or fatigue-control rules
Querying task lists, task details, experiment reports, and metric reports
Querying config items and strategies, copying templates, and managing strategy status
Querying flow lists, node schemas, and flow reports, and saving or managing flows

ae-engage

包提供Hermes Engage的全能力支持，涵盖配置项、流程、渠道设置、任务数据以及查询生命周期。通过

ae-cli engage-flow|engage-task|engage-setting|engage-scene|engage-query <resource> <action>

调用能力网关命令；低频报表请使用下方的L3参考文档。

典型使用场景包括：

查询和管理渠道、配置渠道、审批人以及白名单
查询项目渠道触达限制或疲劳控制规则
查询任务列表、任务详情、实验报告以及指标报告
查询配置项和策略、复制模板以及管理策略状态
查询流程列表、节点 schema 以及流程报表，保存或管理流程

Keyword Routing

关键词路由

When the user mentions a product term below (including common Chinese UI labels), open the listed reference(s) first — do not guess commands or IDs.

Keyword	Product meaning	CLI domain	Primary reference	Related references
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` (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: `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-user-detail-export.md` , `task-indicator-user.md` , `task-data-overview.md` , `task-data-detail.md` , `task-metric-detail.md` , `task-experiment-report.md`
Operation activity	Campaign activity management and delivery trends by activity, topic, or standalone task	`engage-activity`	`references/activity-activity.md`	`activity-data-detail.md` , `activity-topic.md` , `activity-task.md` , `activity-approval.md`
Template	Strategy templates under a config item	`engage-scene`	`references/scene-template.md`	`scene-config-param.md` (template fields reference `paramId` ); enable via `template update` then `template update-status` before strategy create

Easy to confuse:

Push channel →
```
ae-cli engage-setting channel …
```
(Hermes push channel settings)

Config channel →

ae-cli engage-scene config-channel …

(config-center channels; see

channel-mgmt.md

)

Flow / Task canvas nodes use
```
channelId
```
from push channels; config items bind
```
channel_id
```
from config channels

当用户提及以下产品术语（包括常见中文UI标签）时，优先打开对应的参考文档，不得猜测命令或ID。

关键词	产品含义	CLI 域	主参考文档	相关参考文档
配置中心	Engage场景管理 / 配置中心概览	`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报表： `config-item-trigger-report.md` , `config-item-analysis-report.md` , `config-item-strategy-comparison.md`
场景配置	与配置中心含义相同；包含某一配置项下的参数、分组、指标、渠道、策略和模板	`engage-scene`	`references/scene-config-item.md`	同上；参数/分组/指标参考： `scene-config-param.md` , `scene-config-group.md` , `scene-preset-metric.md` , `scene-config-metric.md`
配置项	配置中心中的单个配置项	`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`
推送渠道	项目级消息推送渠道（Webhook、FCM、APNS等）	`engage-setting`	`references/channel-list.md`	`channel-detail.md` , `add-channel.md` （Webhook与Client区别： `url` 对应HTTP地址或场景密钥；自定义参数 `user:` vs `user:` / `client:` ）, `update-channel-status.md` , `delete-channel.md` , `channel-update-config.md` , `channel-test-send.md` , `channel_touch_limits_list.md`
配置渠道	配置中心的Webhook/client配置渠道（与推送渠道不同）	`engage-scene`	`references/scene-config-channel.md`	`channel-mgmt.md` （创建/启用禁用/复制/删除工作流）。 `config.customsParamList` 中的用户参数要求 `columnName` 以 `user:` 为前缀（例如 `user:#account_id` ）；预检查名称需通过ae-analysis `analysis-meta property list/get` 获取。
运营策略	配置项下的运营/投放策略	`engage-scene`	`references/scene-strategy.md`	自定义受众： `scene-strategy-audience.md` — 语义化 `definitionRequest` （分析条件结构）；不得传递 `targetClusterQp` / `qp` ；预检查属性（缺失则停止并列出）；模板参考： `scene-template.md`
运营任务	Hermes推送/触达任务（列表、保存、生命周期、报表）	`engage-task`	`references/task-list.md`	`task-detail.md` （查询详情）, `save-task.md` , `build-task-save-guide.md` , `task-stats.md` , `task-delete.md` , `push-record-query.md` , `task-user-detail-export.md` , `task-indicator-user.md` , `task-data-overview.md` , `task-data-detail.md` , `task-metric-detail.md` , `task-experiment-report.md`
运营活动	营销活动管理，以及按活动、主题或独立任务统计的投放趋势	`engage-activity`	`references/activity-activity.md`	`activity-data-detail.md` , `activity-topic.md` , `activity-task.md` , `activity-approval.md`
模板	配置项下的策略模板	`engage-scene`	`references/scene-template.md`	`scene-config-param.md` （模板字段引用 `paramId` ）；创建策略前需通过 `template update` 启用模板，再执行 `template update-status`

易混淆点：

推送渠道 →
```
ae-cli engage-setting channel …
```
（Hermes推送渠道设置）

配置渠道 →

ae-cli engage-scene config-channel …

（配置中心渠道；参考

channel-mgmt.md

）

流程/任务画布节点使用推送渠道的
```
channelId
```
；配置项绑定配置渠道的
```
channel_id
```

Parameter Conventions

参数约定

Use regular flags for simple parameters, for example
```
--project-id
```
,
```
--task-id
```
, and
```
--flow-uuid
```
Use JSON flags for array parameters, for example
```
--strategy-uuid-list '["id1","id2"]'
```
Use named JSON flags for object parameters, for example
```
--req '{...}'
```
and
```
--flow-list '[...]'
```
Optional global parameters work the same way as in other domains, for example
```
--host
```
,
```
--mcp-url
```
, and
```
--dry-run
```

Naming boundary:

CLI flags use kebab-case; outer Capability input and all Capability response keys use snake_case.
Nested business DTOs passed through
```
--req
```
or
```
--payload
```
keep their documented native camelCase fields. Do not mechanically convert those nested DTO keys to snake_case.
Semantic audience, event, trigger, completion, and metric definitions are closed contracts. The CLI rejects malformed or unknown semantic fields locally;
```
--validate
```
applies the same precise Hermes capability schema without writing.
Successful migrated commands return their business payload under
```
data
```
; read the matching reference's Response shape before selecting fields.

简单参数使用常规标志，例如
```
--project-id
```
,
```
--task-id
```
,
```
--flow-uuid
```
数组参数使用JSON标志，例如
```
--strategy-uuid-list '["id1","id2"]'
```
对象参数使用命名JSON标志，例如
```
--req '{...}'
```
和
```
--flow-list '[...]'
```
可选全局参数的使用方式与其他域一致，例如
```
--host
```
,
```
--mcp-url
```
,
```
--dry-run
```

命名边界：

CLI标志使用短横线分隔式（kebab-case）；外部能力输入和所有能力响应键使用下划线分隔式（snake_case）。
通过
```
--req
```
或
```
--payload
```
传递的嵌套业务DTO保留其文档中定义的原生驼峰式（camelCase）字段，不得机械地将这些嵌套DTO的键转换为snake_case。
语义化受众、事件、触发、完成和指标定义是封闭契约。CLI会在本地拒绝格式错误或未知的语义字段；
```
--validate
```
会应用相同的精确Hermes能力schema，且不会执行写入操作。
成功迁移的命令会在
```
data
```
字段下返回业务负载；在选择字段前需查阅匹配参考文档的响应结构。

JSON Parameter Format

JSON参数格式

Common JSON flag examples:

bash

--provider-list '["webhook","fcm"]'
--strategy-uuid-list '["strategy_a","strategy_b"]'
--flow-id-list '["flow_1","flow_2"]'
--req '{"pageNum":1,"pageSize":20}'

常见JSON标志示例：

bash

--provider-list '["webhook","fcm"]'
--strategy-uuid-list '["strategy_a","strategy_b"]'
--flow-id-list '["flow_1","flow_2"]'
--req '{"pageNum":1,"pageSize":20}'

Common Scenarios

常见场景

1. setting

1. setting（设置）

bash

undefined

bash

undefined

Query the channel list

查询渠道列表

ae-cli engage-setting channel list --project-id 1

Filter by provider

按渠道提供商过滤

ae-cli engage-setting channel list --project-id 1 --provider-list '["webhook","fcm"]'

Query config channels (config center channel management — use engage-scene, not legacy +config_channel_*)

查询配置渠道（配置中心渠道管理 — 使用engage-scene，而非旧版+config_channel_*命令）

ae-cli engage-scene config-channel list --project-id 1 --channel-type 0

Query project channel touch-limit rules

查询项目渠道触达限制规则

ae-cli engage-setting channel-touch-limits list --project-id <project_id>

Update a channel's config / reach-funnel settings

更新渠道配置 / 触达漏斗设置

ae-cli engage-setting channel update-config --project-id <project_id> --channel-id <channel_id> --enable-touch-event 1

Send a test message to a channel

向渠道发送测试消息

ae-cli engage-setting channel test-send --project-id <project_id> --channel-id <channel_id> --push-id <send_id> --content-list '[{"key":"title","value":"hello"}]'

Batch update / toggle / save channel touch-limit (fatigue-control) rules

批量更新 / 切换 / 保存渠道触达限制（疲劳控制）规则

ae-cli engage-setting channel-touch-limits batch-update --project-id <project_id> --items '[{"rule_id":"r1","enable":true,"rule_def":"[]"}]' ae-cli engage-setting channel-touch-limits toggle --project-id <project_id> --rule-id <rule_id> --enable false ae-cli engage-setting channel-touch-limits save --project-id <project_id> --channel-biz-type <biz_type> --rule-def '[]' --enable true

Remove an approver from a project

移除项目中的审批人

ae-cli engage-setting approval-approver delete --project-id <project_id> --approver <open_id> --yes

Whitelist add / update / delete / verify

白名单添加 / 更新 / 删除 / 验证

ae-cli engage-setting whitelist add --project-id <project_id> --prop-code <prop_code> --column-name <column_name> --column-type string --whitelist-list '[{"entity_id":"u1","source_value":"v1"}]' ae-cli engage-setting whitelist update --project-id <project_id> --whitelist-id <id> --note-name <name> ae-cli engage-setting whitelist delete --project-id <project_id> --whitelist-ids '["wl-1"]' --yes ae-cli engage-setting whitelist verify --project-id <project_id> --prop-code <prop_code> --column-type string --whitelist-prop-list '["v1"]'

Push-language (localization) get / set

推送语言（本地化）查询 / 设置

ae-cli engage-setting push-language get --project-id <project_id> ae-cli engage-setting push-language set --project-id <project_id> --push-language-column <prop_code>

Client param update / delete / list

客户端参数更新 / 删除 / 列表

ae-cli engage-setting client-param create --project-id <project_id> --column-name level --column-type varchar --column-desc Level ae-cli engage-setting client-param update --project-id <project_id> --column-name level --column-desc Level ae-cli engage-setting client-param delete --project-id <project_id> --column-name level --yes ae-cli engage-setting client-param list --project-id <project_id>

Config table upload / save / list / query-data / update-data / delete

配置表上传 / 保存 / 列表 / 查询数据 / 更新数据 / 删除

ae-cli engage-setting config-table upload --project-id <project_id> --request-id <rid> --file-name data.csv --file-content "$(base64 -i data.csv)" ae-cli engage-setting config-table save --project-id <project_id> --request-id <rid> --info-name <table_name> ae-cli engage-setting config-table list --project-id <project_id> ae-cli engage-setting config-table query-data --project-id <project_id> --info-id <info_id> ae-cli engage-setting config-table update-data --project-id <project_id> --request-id <rid> --info-name <table_name> --info-id <info_id> ae-cli engage-setting config-table delete --project-id <project_id> --info-id <info_id> --yes

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

undefined

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

undefined

2. task

2. task（任务）

bash

undefined

bash

undefined

Query the task list

查询任务列表

ae-cli engage-task task list --project-id 1 --req '{"pageNum":1,"pageSize":20}'

Build a save_task guide before composing the final req

在编写最终请求前，先生成save_task指南

ae-cli engage-task task build-save-guide --project-id 1 --req '{"context":{"triggerType":2,"channelId":"channel_123"}}'

Save a task draft (create when req.taskId is omitted)

保存任务草稿（省略req.taskId时创建新任务）

ae-cli engage-task task save --project-id 1 --req '{"baseInfo":{"taskName":"Demo Task"},"channelConfig":{"channelType":1,"channelId":"channel_123","groupContentList":[{"contentList":[{"pushLanguageCode":"default","content":"[]"}]}]},"targetConfig":{"targetClusterType":3},"triggerConfig":{"triggerType":2},"controlConfig":{"completionIndicatorDef":{"completionIndicators":[]}}}'

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

Query task reports through the Hermes inline task-data capabilities

通过Hermes内嵌任务数据能力查询任务报表

ae-cli engage-task effect query --project-id 1 --task-id task_123 --start-time 2026-04-01 --end-time 2026-04-07 --metric-id-list '["metric_1"]' ae-cli engage-task data-detail query --project-id 1 --task-id task_123 --detail-type time --start-time 2026-04-01 --end-time 2026-04-07 ae-cli engage-task indicator-user sql --project-id 1 --task-id task_123 --indicator main --start-time 2026-04-01 --end-time 2026-04-07 ae-cli engage-task indicator-user run --project-id 1 --task-id task_123 --indicator secondary --secondary-index 1 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 ae-cli engage-task indicator-user export --project-id 1 --task-id task_123 --indicator metric --metric-id metric_1 --source metric --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv


For L3 task reports, read `references/task-data-overview.md`, `references/task-data-detail.md`,
`references/task-metric-detail.md`, or `references/task-experiment-report.md` before invocation.
Before using `engage-task indicator-user`, read `references/task-indicator-user.md`; its grouping,
indicator, summary/detail, metric, experiment, and timezone flags have conditional compatibility rules.

ae-cli engage-task effect query --project-id 1 --task-id task_123 --start-time 2026-04-01 --end-time 2026-04-07 --metric-id-list '["metric_1"]' ae-cli engage-task data-detail query --project-id 1 --task-id task_123 --detail-type time --start-time 2026-04-01 --end-time 2026-04-07 ae-cli engage-task indicator-user sql --project-id 1 --task-id task_123 --indicator main --start-time 2026-04-01 --end-time 2026-04-07 ae-cli engage-task indicator-user run --project-id 1 --task-id task_123 --indicator secondary --secondary-index 1 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 ae-cli engage-task indicator-user export --project-id 1 --task-id task_123 --indicator metric --metric-id metric_1 --source metric --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv


对于L3任务报表，在调用前需阅读`references/task-data-overview.md`, `references/task-data-detail.md`,
`references/task-metric-detail.md`或`references/task-experiment-report.md`。使用`engage-task indicator-user`前，需阅读`references/task-indicator-user.md`；其分组、指标、汇总/详情、度量、实验和时区标志有条件兼容性规则。

3. config

3. config（配置）

bash

undefined

bash

undefined

Query the config item list

查询配置项列表

ae-cli engage-scene config-item list --project-id 1

Query the strategy list

查询策略列表

ae-cli engage-scene strategy list --project-id 1 --config-id cfg_123


For L3 config reports, read `references/config-item-trigger-report.md`,
`references/config-item-analysis-report.md`, or `references/config-item-strategy-comparison.md` before invocation.

ae-cli engage-scene strategy list --project-id 1 --config-id cfg_123


对于L3配置报表，在调用前需阅读`references/config-item-trigger-report.md`,
`references/config-item-analysis-report.md`或`references/config-item-strategy-comparison.md`。

4. flow

4. flow（流程）

bash

undefined

bash

undefined

Query the flow list

查询流程列表

ae-cli engage-flow flow list --project-id 1

Query flow details

查询流程详情

ae-cli engage-flow flow get --project-id 1 --flow-uuid flow_uuid_123

Query flow operation records and application logs

查询流程操作记录和应用日志

ae-cli engage-flow operation-log query --project-id 1 --flow-id flow_id_123

Query flow versions and task push records

查询流程版本和任务推送记录

ae-cli engage-flow version list --project-id 1 --flow-id flow_id_123 ae-cli engage-flow flow update-remark --project-id 1 --flow-uuid flow_uuid_123 --flow-version-desc "Second version" ae-cli engage-task operation-log query --project-id 1 --task-id task_id_123 ae-cli engage-task push-record query --project-id 1 --task-id task_id_123 --page-num 1 --page-size 20 ae-cli engage-task user-detail export --project-id 1 --task-id task_id_123 --task-instance-id instance_123 --user-status fail --artifact-format csv ae-cli engage-task segment-list query --project-id 1 --task-id task_id_123 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

查询节点schema

ae-cli engage-flow node-config schema --project-id 1 --node-type message_push ae-cli engage-flow metric update --project-id 1 --flow-id flow_id_123 --metric-map '<metric_map_json>'

Query or export newly exposed flow report surfaces

查询或导出新增的流程报表内容

ae-cli engage-flow report metric-detail run --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120 ae-cli engage-flow report metric-detail export --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600 ae-cli engage-flow metric-user run --project-id 1 --flow-id flow_id_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120 ae-cli engage-flow metric-user export --project-id 1 --flow-id flow_id_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600 ae-cli engage-flow node-user run --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120 ae-cli engage-flow node-user export --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600 ae-cli engage-flow node-metric-user run --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name metric_setting_id_123 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120 ae-cli engage-flow node-metric-user export --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name metric_setting_id_123 --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600


User-detail `run` commands are for bounded inline rows and accept `--request-id`, `--limit`, and `--timeout-seconds`; metric-detail `run` returns the report object. Export commands accept `--request-id`, `--artifact-format csv|jsonl` (default `jsonl`), and `--timeout-seconds`, then return `run_id` and `artifact_id`; poll with `ae-cli engage-query run inspect --run-id RUN_ID`, then download with `ae-cli engage-query artifact download --run-id RUN_ID --artifact-id ARTIFACT_ID --output ./artifact.jsonl.gz`. Cancel running async work with `ae-cli engage-query query cancel --run-id RUN_ID`.

For flow report/user-detail commands, read the matching reference before composing non-trivial input:

- Flow canvas custom metric configuration: `references/flow-metric-update.md`
- Metric-detail report object or flattened report export: `references/flow-metric-detail-report.md`
- Users behind a process-level metric segment: `references/flow-metric-user.md`
- Users behind a node-level data segment: `references/flow-node-user.md`
- Users behind a node-level metric segment: `references/flow-node-metric-user.md`

ae-cli engage-flow report metric-detail run --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120 ae-cli engage-flow report metric-detail export --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600 ae-cli engage-flow metric-user run --project-id 1 --flow-id flow_id_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120 ae-cli engage-flow metric-user export --project-id 1 --flow-id flow_id_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600 ae-cli engage-flow node-user run --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120 ae-cli engage-flow node-user export --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name entry --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600 ae-cli engage-flow node-metric-user run --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name metric_setting_id_123 --start-time 2026-04-01 --end-time 2026-04-07 --limit 100 --timeout-seconds 120 ae-cli engage-flow node-metric-user export --project-id 1 --flow-id flow_id_123 --node-uuid node_uuid_123 --indicator-name metric_setting_id_123 --start-time 2026-04-01 --end-time 2026-04-07 --artifact-format csv --timeout-seconds 21600


用户详情`run`命令用于获取有限的内嵌行数据，支持`--request-id`, `--limit`, `--timeout-seconds`参数；metric-detail `run`返回报表对象。导出命令支持`--request-id`, `--artifact-format csv|jsonl`（默认`jsonl`）和`--timeout-seconds`参数，返回`run_id`和`artifact_id`；通过`ae-cli engage-query run inspect --run-id RUN_ID`轮询状态，再使用`ae-cli engage-query artifact download --run-id RUN_ID --artifact-id ARTIFACT_ID --output ./artifact.jsonl.gz`下载结果。使用`ae-cli engage-query query cancel --run-id RUN_ID`取消正在运行的异步任务。

对于流程报表/用户详情命令，在编写非简单输入前需查阅匹配的参考文档：

- 流程画布自定义指标配置：`references/flow-metric-update.md`
- Metric-detail报表对象或扁平化报表导出：`references/flow-metric-detail-report.md`
- 流程级指标分段对应的用户：`references/flow-metric-user.md`
- 节点级数据分段对应的用户：`references/flow-node-user.md`
- 节点级指标分段对应的用户：`references/flow-node-metric-user.md`

5. scene (scene management / config center)

5. scene（场景管理 / 配置中心）

New capability-gateway command group

engage-scene

covers the config center: config items, params, groups, preset/related metrics, config channels, strategies, and templates. Complex DTOs are passed with

--payload

(native camelCase JSON).

bash

undefined

新的能力网关命令组

engage-scene

覆盖配置中心的所有功能：配置项、参数、分组、预设/关联指标、配置渠道、策略和模板。复杂DTO通过

--payload

（原生camelCase JSON）传递。

bash

undefined

Config item list / get / create / update / delete

配置项列表 / 查询 / 创建 / 更新 / 删除

ae-cli engage-scene config-item list --project-id <project_id> ae-cli engage-scene config-item get --project-id <project_id> --config-id <config_id> ae-cli engage-scene config-item create --project-id <project_id> --config-id <config_id> --config-name <name> --business-type params ae-cli engage-scene config-item update --project-id <project_id> --config-id <config_id> --config-name <name> ae-cli engage-scene config-item delete --project-id <project_id> --config-id <config_id> --open-id <open_id> --yes

Config param list / batch-add / update / batch-delete

配置参数列表 / 批量添加 / 更新 / 批量删除

ae-cli engage-scene config-param list --project-id <project_id> --config-id <config_id> ae-cli engage-scene config-param batch-add --project-id <project_id> --config-id <config_id> --params '[{"param_name":"a","param_type":"string"}]' ae-cli engage-scene config-param update --project-id <project_id> --config-id <config_id> --param-id <param_id> --param-name a ae-cli engage-scene config-param batch-delete --project-id <project_id> --param-ids '[1,2]' --yes

Config group list / batch-add / update / batch-delete

配置分组列表 / 批量添加 / 更新 / 批量删除

ae-cli engage-scene config-group list --project-id <project_id> ae-cli engage-scene config-group batch-add --project-id <project_id> --group-names '["g1"]' ae-cli engage-scene config-group update --project-id <project_id> --group-id <group_id> --group-name g2 ae-cli engage-scene config-group batch-delete --project-id <project_id> --group-ids '[1,2]' --yes

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-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> ae-cli engage-scene config-metric get --project-id <project_id> --metric-id <metric_id> ae-cli engage-scene config-metric batch-add --project-id <project_id> --config-id <config_id> --ta-metric-ids '[1,2]' ae-cli engage-scene config-metric update-rule --project-id <project_id> --metric-id <metric_id> --event-list '[{"event_name":"e1","filter":"true"}]' ae-cli engage-scene config-metric batch-delete --project-id <project_id> --config-id <config_id> --metric-ids '[1,2]' --yes

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>

用户参数：需先通过ae-analysis property list/get验证每个customsParamList的columnName；然后使用user:<prop_name>格式

Strategy custom audience: scene-strategy-audience.md — semantic definitionRequest; strategy predict for 预估人数

策略自定义受众：参考scene-strategy-audience.md — 语义化definitionRequest；strategy predict用于预估人数

Workflows: references/channel-mgmt.md · schema: references/scene-config-channel.md

工作流：参考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> ae-cli engage-scene config-channel create --project-id <project_id> --channel-name <name> --channel-type 0 --config '<json>' ae-cli engage-scene config-channel update --project-id <project_id> --channel-id <channel_id> --channel-name <name> [--config '<json>'] ae-cli engage-scene config-channel update-status --project-id <project_id> --channel-id <channel_id> --channel-status 1|2 ae-cli engage-scene config-channel delete --project-id <project_id> --channel-id <channel_id> --yes ae-cli engage-scene config-channel query-log --project-id <project_id> --channel-id <channel_id>

Strategy create / update / log / batch-copy

策略创建 / 更新 / 日志 / 批量复制

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

模板列表 / 查询 / 创建 / 更新 / 更新状态 / 删除

ae-cli engage-scene template list --project-id <project_id> --config-id <config_id> ae-cli engage-scene template get --project-id <project_id> --config-id <config_id> --template-id <template_id> ae-cli engage-scene template create --project-id <project_id> --payload '{"configId":"cfg-1","templateId":"tpl-1","templateName":"t1"}' ae-cli engage-scene template update --project-id <project_id> --payload '{"configId":"cfg-1","templateId":"tpl-1","config":[]}' ae-cli engage-scene template update-status --project-id <project_id> --config-id <config_id> --template-id <template_id> --status 1 ae-cli engage-scene template delete --project-id <project_id> --config-id <config_id> --template-id <template_id> --yes

undefined

ae-cli engage-scene template list --project-id <project_id> --config-id <config_id> ae-cli engage-scene template get --project-id <project_id> --config-id <config_id> --template-id <template_id> ae-cli engage-scene template create --project-id <project_id> --payload '{"configId":"cfg-1","templateId":"tpl-1","templateName":"t1"}' ae-cli engage-scene template update --project-id <project_id> --payload '{"configId":"cfg-1","templateId":"tpl-1","config":[]}' ae-cli engage-scene template update-status --project-id <project_id> --config-id <config_id> --template-id <template_id> --status 1 ae-cli engage-scene template delete --project-id <project_id> --config-id <config_id> --template-id <template_id> --yes

undefined

6. activity (campaign activities)

6. activity（营销活动）

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

新的能力网关命令组

engage-activity

覆盖营销活动的所有功能：活动、审批工作流、主题、活动类型和独立任务。复杂DTO通过

--payload

（原生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

undefined

在生成任何活动主题或独立任务负载前，需严格遵循Hermes活动UI暴露的子集规则：

```
triggerType
```
必须为
```
0
```
（单次定时）或
```
1
```
（重复定时）。活动任务不支持手动（
```
2
```
）或触发式（
```
3
```
-
```
6
```
）任务类型。
不得配置A/B或赛马实验。需省略
```
expConfig
```
或仅使用
```
{"enableExp":false}
```
，且需提供恰好一个非实验的
```
groupContentList
```
分组。
独立活动任务必须使用
```
triggerTimeStrategy: "fixed_time_zone"
```
和父活动的
```
tzOffset
```
。定时时间必须处于活动周期内。
主题根节点支持受众类型
```
1
```
（自定义）和
```
2
```
（现有集群），不支持
```
3
```
（所有用户）。独立活动任务可使用
```
1
```
、
```
2
```
或
```
3
```
。
主题任务继承主题的定时、时区、渠道、频率限制、渠道触达限制、白名单和实验设置。仅可添加包含型自定义
```
definitionRequest
```
；不得生成任务级
```
clusterKey
```
、触发规则或共享设置覆盖项。
```
topic get
```
可能返回标准任务标记
```
targetClusterType=1
```
；如果存在需保留用于更新，但不得使用其他任务级值。
需先解析父活动并确认其可编辑（
```
mappingStatus
```
为
```
0
```
、
```
2
```
或
```
5
```
）。主题、任务和语言的限制是项目配置值，不得硬编码默认值。
```
approval submit
```
和
```
approval approve
```
会验证所有持久化的活动任务。审批不会规范化不支持的任务数据。如果出现
```
ACTIVITY_TASK_COMPATIBILITY_VIOLATION
```
，需根据需要取消/撤回审批，修正或重新创建每个报错的任务，然后重新提交。

bash

undefined

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}' ae-cli engage-activity activity update --project-id <project_id> --payload '{"activityId":"act-1","activityName":"a1","activityType":"other_type","tzOffset":8,"periodType":0}' ae-cli engage-activity activity delete --project-id <project_id> --activity-id <activity_id> --yes ae-cli engage-activity activity list --project-id <project_id> --page 1 --page-size 20 ae-cli engage-activity activity get --project-id <project_id> --activity-id <activity_id> ae-cli engage-activity activity pause --project-id <project_id> --activity-id <activity_id> ae-cli engage-activity activity end --project-id <project_id> --activity-id <activity_id> 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 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>

Topic create / update / remove-task / delete / get / copy

主题创建 / 更新 / 移除任务 / 删除 / 查询 / 复制

See references/activity-topic.md for topicClusterKey vs task clusterKey and triggerType notes.

关于topicClusterKey与task clusterKey以及triggerType的说明，请参考references/activity-topic.md。

ae-cli engage-activity topic create --project-id <project_id> --payload '{"activityId":"act-1","topicName":"t1","targetClusterType":2,"topicClusterKey":"<cluster>","channelType":1,"channelId":"c1","triggerType":0,"triggerTime":"2026-12-31 12:00","enableChannelTouchLimits":false,"frequencyLimits":"{}","tasks":[...]}' ae-cli engage-activity topic update --project-id <project_id> --payload '{"topicId":"topic-1", ...}' ae-cli engage-activity topic remove-task --project-id <project_id> --task-id <task_id> --yes ae-cli engage-activity topic delete --project-id <project_id> --topic-id <topic_id> --yes ae-cli engage-activity topic get --project-id <project_id> --topic-id <topic_id> ae-cli engage-activity topic copy --project-id <project_id> --topic-id <topic_id> [--new-name <name>]

Activity type list / batch-add / update / batch-delete

活动类型列表 / 批量添加 / 更新 / 批量删除

ae-cli engage-activity activity-type list --project-id <project_id> ae-cli engage-activity activity-type batch-add --project-id <project_id> --type-names '["t1","t2"]' ae-cli engage-activity activity-type update --project-id <project_id> --id <type_id> --type-name t3 ae-cli engage-activity activity-type batch-delete --project-id <project_id> --ids '["id1","id2"]' --yes

Standalone task get / create / update / copy

独立任务查询 / 创建 / 更新 / 复制

ae-cli engage-activity task get --project-id <project_id> --task-id <task_id> ae-cli engage-activity task create --project-id <project_id> --payload '{"taskName":"t1","activityId":"act-1", ...}' ae-cli engage-activity task update --project-id <project_id> --payload '{"taskId":"task-1", ...}' ae-cli engage-activity task copy --project-id <project_id> --task-id <task_id> [--new-name <name>]

undefined

ae-cli engage-activity task get --project-id <project_id> --task-id <task_id> ae-cli engage-activity task create --project-id <project_id> --payload '{"taskName":"t1","activityId":"act-1", ...}' ae-cli engage-activity task update --project-id <project_id> --payload '{"taskId":"task-1", ...}' ae-cli engage-activity task copy --project-id <project_id> --task-id <task_id> [--new-name <name>]

undefined

7. workbench

7. workbench（工作台）

New capability-gateway command group

engage-workbench

covers workbench metric slots: each user configures up to 4 metric cards per project. Slots are per-user;

update

/

delete

only affect the caller's own slots. The first

list

auto-initialises 4 default slots.

bash

undefined

新的能力网关命令组

engage-workbench

覆盖工作台指标插槽：每个用户每个项目最多可配置4个指标卡片。插槽为用户专属；

update

/

delete

仅影响调用者自身的插槽。首次执行

list

命令会自动初始化4个默认插槽。

bash

undefined

Workbench slot list / add / update / delete

工作台插槽列表 / 添加 / 更新 / 删除

ae-cli engage-workbench workbench list --project-id <project_id> ae-cli engage-workbench workbench add --project-id <project_id> --metric-type <metric_type> --date-type <date_type> --order-id 1 ae-cli engage-workbench workbench update --project-id <project_id> --slot-id <slot_id> --metric-type <metric_type> --date-type <date_type> --order-id 1 ae-cli engage-workbench workbench delete --project-id <project_id> --slot-id <slot_id> --yes

undefined

ae-cli engage-workbench workbench list --project-id <project_id> ae-cli engage-workbench workbench add --project-id <project_id> --metric-type <metric_type> --date-type <date_type> --order-id 1 ae-cli engage-workbench workbench update --project-id <project_id> --slot-id <slot_id> --metric-type <metric_type> --date-type <date_type> --order-id 1 ae-cli engage-workbench workbench delete --project-id <project_id> --slot-id <slot_id> --yes

undefined

engage-flow flow save

Critical Constraints

engage-flow flow save

关键约束

When the user wants to "create a flow / generate a flow canvas / save a flow", do not treat

engage-flow flow save

as a normal single command. You must follow the workflow below.

当用户需求为“创建流程 / 生成流程画布 / 保存流程”时，不得将

engage-flow flow save

视为普通单命令执行，必须遵循以下工作流。

Required Workflow

必选工作流

First confirm that the user intent is specific enough. At minimum you need:
- The business scenario
- The target users
- The touchpoint or delivery method
- Whether branching is needed, and the branching conditions
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
```
.
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.
Before building touchpoint nodes such as
```
message_push
```
,
```
wechat_push
```
, or
```
webhook_push
```
, you must call:

bash

ae-cli engage-setting channel list --project-id <projectId>

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

.

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

.

```
nodes[].config
```
/
```
edges[].config
```
may be a JSON object or a JSON string. Custom audience nodes and branches use semantic
```
targetDefinitionRequest
```
; Hermes compiles it to the node's stored execution format. Never send
```
targetClusterQp
```
. Each audience
```
event
```
and
```
behavior_sequence
```
must include its own
```
time_range
```
; Flow entry dates do not replace that range. Use only properties that resolve through the Flow editor's current project, timezone, and user-entity metadata scope.
You must self-check before previewing/committing:
- There is exactly one entry node
- There is at least one
```
exit_flow
```
- ```
edge.source
```
  and
```
edge.target
```
  both reference valid nodes
- Any branch node
```
sourceBranchId
```
  has already been declared in the upstream node
```
config
```
- The whole graph is a DAG and contains no cycles

首先确认用户意图足够明确，至少需要：
- 业务场景
- 目标用户
- 触达点或投放方式
- 是否需要分支，以及分支条件
不得直接从自然语言跳转至
```
--req
```
参数。必须先整理出稳定的中间意图结构，再映射为最终的
```
req
```
。
使用语义化
```
targetDefinitionRequest
```
和
```
triggerDefinition
```
对象构建条件相关节点。需通过分析元数据解析真实的事件和属性名称；不得仅为获取持久化QP而创建中间集群。
在构建
```
message_push
```
、
```
wechat_push
```
或
```
webhook_push
```
等触达节点前，必须调用：

bash

ae-cli engage-setting channel list --project-id <projectId>

```
engage-flow flow save
```
是基于操作的（协议v2）。
```
--req
```
对象必须携带
```
operation
```
字段，值为
```
build
```
、
```
preview
```
或
```
commit
```
。禁止使用旧的
```
nodeList
```
/
```
edgeList
```
字段名 — 需使用
```
nodes
```
/
```
edges
```
并设置
```
operation=build
```
。如果使用旧版
```
nodeList
```
/
```
edgeList
```
负载（或缺失
```
operation
```
），会被拒绝并返回
```
Unsupported save_flow operation: null
```
。

执行生命周期：

build

（返回

data.result.status = ready_to_preview

或

need_input

）→ 解决任何

data.result.next_slot

问题 →

preview

（重新返回

data.result.draft_version

+

data.result.confirm_token

字段）→

commit

（将这些值映射至请求字段

draftVersion

+

confirmToken

）→ 从

data.result.result.flow_uuid

读取最终ID。

```
nodes[].config
```
/
```
edges[].config
```
可以是JSON对象或JSON字符串。自定义受众节点和分支使用语义化
```
targetDefinitionRequest
```
；Hermes会将其编译为节点存储的执行格式。禁止发送
```
targetClusterQp
```
。每个受众的
```
event
```
和
```
behavior_sequence
```
必须包含自身的
```
time_range
```
；流程入口日期不能替代该范围。仅可使用当前项目、时区和用户实体元数据范围内可解析的属性。
在预览/提交前必须自行检查：
- 恰好存在一个入口节点
- 至少存在一个
```
exit_flow
```
  节点
- ```
edge.source
```
  和
```
edge.target
```
  均引用有效的节点
- 任何分支节点的
```
sourceBranchId
```
  已在上游节点的
```
config
```
  中声明
- 整个图为有向无环图（DAG）且无循环

Explicitly Forbidden

明确禁止操作

Do not invent a
```
channelId
```
Do not fill in branching logic when the user has not provided enough information
Do not submit business-semantic nodes directly as final
```
nodes
```
Do not use the legacy
```
nodeList
```
/
```
edgeList
```
, and do not omit
```
operation
```

不得编造
```
channelId
```
用户未提供足够信息时，不得填充分支逻辑
不得直接将业务语义节点作为最终
```
nodes
```
提交
不得使用旧版
```
nodeList
```
/
```
edgeList
```
，且不得省略
```
operation
```

Recommended Order

Dry-Run Debugging

空运行调试

bash

ae-cli --dry-run engage-setting channel list --project-id 1
ae-cli --dry-run engage-task task list --project-id 1 --req '{"pageNum":1,"pageSize":20}'
ae-cli --dry-run engage-task task build-save-guide --project-id 1 --req '{}'
ae-cli --dry-run engage-task task save --project-id 1 --req '{"baseInfo":{"taskName":"Demo Task"},"channelConfig":{"channelType":1,"channelId":"channel_123","groupContentList":[{"contentList":[{"pushLanguageCode":"default","content":"[]"}]}]},"targetConfig":{"targetClusterType":3},"triggerConfig":{"triggerType":2},"controlConfig":{"completionIndicatorDef":{"completionIndicators":[]}}}'
ae-cli --dry-run engage-flow flow list --project-id 1

bash

ae-cli --dry-run engage-setting channel list --project-id 1
ae-cli --dry-run engage-task task list --project-id 1 --req '{"pageNum":1,"pageSize":20}'
ae-cli --dry-run engage-task task build-save-guide --project-id 1 --req '{}'
ae-cli --dry-run engage-task task save --project-id 1 --req '{"baseInfo":{"taskName":"Demo Task"},"channelConfig":{"channelType":1,"channelId":"channel_123","groupContentList":[{"contentList":[{"pushLanguageCode":"default","content":"[]"}]}]},"targetConfig":{"targetClusterType":3},"triggerConfig":{"triggerType":2},"controlConfig":{"completionIndicatorDef":{"completionIndicators":[]}}}'
ae-cli --dry-run engage-flow flow list --project-id 1

References

参考文档

More detailed single-command guidance is available in the business-oriented

references/

directory:

references/channel-list.md

(

engage-setting.channel.list

)

references/channel-detail.md

(

engage-setting.channel.get

)

references/add-channel.md

(

engage-setting.channel.create

)

references/update-channel-status.md

(

engage-setting.channel.update-status

)

references/delete-channel.md

(

engage-setting.channel.delete

)

references/channel_touch_limits_list.md

(

engage-setting.channel-touch-limits.list

)

references/channel-touch-limits-batch-update.md

(

engage-setting.channel-touch-limits.batch-update

)

references/channel-touch-limits-toggle.md

(

engage-setting.channel-touch-limits.toggle

)

references/channel-touch-limits-save.md

(

engage-setting.channel-touch-limits.save

)

references/channel-update-config.md

(

engage-setting.channel.update-config

)

references/channel-test-send.md

(

engage-setting.channel.test-send

)

references/approval-approver-delete.md

(

engage-setting.approval-approver.delete

)

references/add-approver.md

/

references/approver-list.md

(

engage-setting.approval-approver.{add,list}

)

references/whitelist-list.md

/

references/whitelist.md

(

engage-setting.whitelist.{list,add,update,delete,verify}

)

references/cancel-query-by-request-id.md

(

engage-setting.query.cancel

, L3)

references/cancel-query-run.md

(

engage-query.query.cancel

)

references/push-language.md

(

engage-setting.push-language.{get,set}

)

references/client-param.md

(

engage-setting.client-param.{create,update,delete,list}

)

references/config-table.md

(

engage-setting.config-table.{upload,save,list,query-data,update-data,delete}

)

references/preset-event.md

(

engage-setting.preset-event.{list,update}

)

references/common-metric.md

(

engage-setting.common-metric.{list,get,create,update,delete}

)

references/scene-config-item.md

(

engage-scene.config-item.{list,get,create,update,delete}

)

references/scene-config-param.md

(

engage-scene.config-param.{list,batch-add,update,batch-delete}

)

references/scene-config-group.md

(

engage-scene.config-group.{list,batch-add,update,batch-delete}

)

references/scene-preset-metric.md

(

engage-scene.preset-metric.{get,set}

)

references/scene-config-metric.md

(

engage-scene.config-metric.{list,get,batch-add,update-rule,batch-delete}

)

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 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-data-detail.md

(

engage-activity.activity-data.detail

, L3)

references/activity-approval.md

(

engage-activity.approval.{submit,approve,reject,cancel}

)

references/activity-topic.md

(

engage-activity.topic.{create,update,remove-task,delete,get,copy}

)

references/activity-activity-type.md

(

engage-activity.activity-type.{list,batch-add,update,batch-delete}

)

references/activity-task.md

(

engage-activity.task.{get,create,update,copy}

)

references/workbench-workbench.md

(

engage-workbench.workbench.{list,add,update,delete}

)

```
references/build-task-save-guide.md
```
```
references/save-task.md
```
```
references/task-list.md
```
```
references/flow-list.md
```

references/operation-log-query.md

(

engage-flow.operation-log.query

)

references/task-operation-log-query.md

(

engage-task.operation-log.query

)

references/version-list.md

(

engage-flow.version.list

)

references/flow-update-remark.md

(

ae-cli engage-flow flow update-remark

; capability

engage-flow.version.update-remark

)

references/push-record-query.md

(

engage-task.push-record.query

)

references/task-user-detail-export.md

(

engage-task user-detail export

; capability

engage-task.user-detail.export

)

references/task-indicator-user.md

(

engage-task indicator-user {sql,run,export}

; capabilities

engage-task.indicator-user.{sql,run,export}

)

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

)

references/task-data-detail.md

(

engage-task data-detail query

; capability

engage-task.task-data.detail

)

references/task-metric-detail.md

(

engage-task effect query

; capability

engage-task.task-data.metric-detail

)

references/flow-metric-update.md

(

engage-flow metric update

; capability

engage-flow.metric.update

)

This split documentation structure is easier to extend later, because commands with more complex object inputs can stay centralized in the

references/

root directory.

更详细的单命令指导可在面向业务的

references/

目录中获取：

references/channel-list.md

（

engage-setting.channel.list

）

references/channel-detail.md

（

engage-setting.channel.get

）

references/add-channel.md

（

engage-setting.channel.create

）

references/update-channel-status.md

（

engage-setting.channel.update-status

）

references/delete-channel.md

（

engage-setting.channel.delete

）

references/channel_touch_limits_list.md

（

engage-setting.channel-touch-limits.list

）

references/channel-touch-limits-batch-update.md

（

engage-setting.channel-touch-limits.batch-update

）

references/channel-touch-limits-toggle.md

（

engage-setting.channel-touch-limits.toggle

）

references/channel-touch-limits-save.md

（

engage-setting.channel-touch-limits.save

）

references/channel-update-config.md

（

engage-setting.channel.update-config

）

references/channel-test-send.md

（

engage-setting.channel.test-send

）

references/approval-approver-delete.md

（

engage-setting.approval-approver.delete

）

references/add-approver.md

/

references/approver-list.md

（

engage-setting.approval-approver.{add,list}

）

references/whitelist-list.md

/

references/whitelist.md

（

engage-setting.whitelist.{list,add,update,delete,verify}

）

references/cancel-query-by-request-id.md

（

engage-setting.query.cancel

，L3）

references/cancel-query-run.md

（

engage-query.query.cancel

）

references/push-language.md

（

engage-setting.push-language.{get,set}

）

references/client-param.md

（

engage-setting.client-param.{create,update,delete,list}

）

references/config-table.md

（

engage-setting.config-table.{upload,save,list,query-data,update-data,delete}

）

references/preset-event.md

（

engage-setting.preset-event.{list,update}

）

references/common-metric.md

（

engage-setting.common-metric.{list,get,create,update,delete}

）

references/scene-config-item.md

（

engage-scene.config-item.{list,get,create,update,delete}

）

references/scene-config-param.md

（

engage-scene.config-param.{list,batch-add,update,batch-delete}

）

references/scene-config-group.md

（

engage-scene.config-group.{list,batch-add,update,batch-delete}

）

references/scene-preset-metric.md

（

engage-scene.preset-metric.{get,set}

）

references/scene-config-metric.md

（

engage-scene.config-metric.{list,get,batch-add,update-rule,batch-delete}

）

references/scene-config-channel.md

（

engage-scene.config-channel.{list,get,create,update,update-status,delete,query-log}

）

```
references/channel-mgmt.md
```
（配置渠道管理工作流）

references/scene-strategy.md

（

engage-scene.strategy.{list,get,create,update,log,predict,batch-copy,manage}

）

references/scene-strategy-audience.md

（自定义受众语义化

definitionRequest

、预检查、预估）

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-data-detail.md

（

engage-activity.activity-data.detail

，L3）

references/activity-approval.md

（

engage-activity.approval.{submit,approve,reject,cancel}

）

references/activity-topic.md

（

engage-activity.topic.{create,update,remove-task,delete,get,copy}

）

references/activity-activity-type.md

（

engage-activity.activity-type.{list,batch-add,update,batch-delete}

）

references/activity-task.md

（

engage-activity.task.{get,create,update,copy}

）

references/workbench-workbench.md

（

engage-workbench.workbench.{list,add,update,delete}

）

```
references/build-task-save-guide.md
```
```
references/save-task.md
```
```
references/task-list.md
```
```
references/flow-list.md
```

references/operation-log-query.md

（

engage-flow.operation-log.query

）

references/task-operation-log-query.md

（

engage-task.operation-log.query

）

references/version-list.md

（

engage-flow.version.list

）

references/flow-update-remark.md

（

ae-cli engage-flow flow update-remark

；能力

engage-flow.version.update-remark

）

references/push-record-query.md

（

engage-task.push-record.query

）

references/task-user-detail-export.md

（

engage-task user-detail export

；能力

engage-task.user-detail.export

）

references/task-indicator-user.md

（

engage-task indicator-user {sql,run,export}

；能力

engage-task.indicator-user.{sql,run,export}

）

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

）

references/task-data-detail.md

（

engage-task data-detail query

；能力

engage-task.task-data.detail

）

references/task-metric-detail.md

（

engage-task effect query

；能力

engage-task.task-data.metric-detail

）

references/flow-metric-update.md

（

engage-flow metric update

；能力

engage-flow.metric.update

）

这种拆分的文档结构更易于后续扩展，因为具有复杂对象输入的命令可以集中在

references/

根目录中。

Command Groups

命令组

setting

setting（设置）

channel-touch-limits list

/

channel-touch-limits batch-update

/

channel-touch-limits toggle

/

channel-touch-limits save

/

channel update-config

/

channel test-send

/

channel list

/

channel get

/

channel create

/

channel update-status

/

channel delete

/

approval-approver add

/

approval-approver list

/

approval-approver delete

/

whitelist list

/

whitelist add

/

whitelist update

/

whitelist delete

/

whitelist verify

/

push-language get

/

push-language set

/

client-param create

/

client-param update

/

client-param delete

/

client-param list

/

config-table upload

/

config-table save

/

config-table list

/

config-table query-data

/

config-table update-data

/

config-table delete

/

preset-event list

/

preset-event update

/

common-metric list

/

common-metric get

/

common-metric create

/

common-metric update

/

common-metric delete

(via

engage-setting

), plus L3 capability

engage-setting.query.cancel

channel-touch-limits list

/

channel-touch-limits batch-update

/

channel-touch-limits toggle

/

channel-touch-limits save

/

channel update-config

/

channel test-send

/

channel list

/

channel get

/

channel create

/

channel update-status

/

channel delete

/

approval-approver add

/

approval-approver list

/

approval-approver delete

/

whitelist list

/

whitelist add

/

whitelist update

/

whitelist delete

/

whitelist verify

/

push-language get

/

push-language set

/

client-param create

/

client-param update

/

client-param delete

/

client-param list

/

config-table upload

/

config-table save

/

config-table list

/

config-table query-data

/

config-table update-data

/

config-table delete

/

preset-event list

/

preset-event update

/

common-metric list

/

common-metric get

/

common-metric create

/

common-metric update

/

common-metric delete

（通过

engage-setting

调用），以及L3能力

engage-setting.query.cancel

task

task（任务）

operation-log query

/

push-record query

/

user-detail export

/

indicator-user sql

/

indicator-user run

/

indicator-user export

/

segment-list *

/

ops *

/

metric *

/

race release

/

channel-ref stats

/

group *

/

task delete

/

task modify-group

/

task submit-approval

/

task get

/

task list

/

task stats

/

task build-save-guide

/

task save

/

task manage

/

effect query

/

data-detail query

(via

engage-task

), plus L3 capabilities

engage-task.task-data.{overview,detail,metric-detail,experiment-report}

operation-log query

/

push-record query

/

user-detail export

/

indicator-user sql

/

indicator-user run

/

indicator-user export

/

segment-list *

/

ops *

/

metric *

/

race release

/

channel-ref stats

/

group *

/

task delete

/

task modify-group

/

task submit-approval

/

task get

/

task list

/

task stats

/

task build-save-guide

/

task save

/

task manage

/

effect query

/

data-detail query

（通过

engage-task

调用），以及L3能力

engage-task.task-data.{overview,detail,metric-detail,experiment-report}

query

query（查询）

run inspect

/

artifact download

/

query cancel

(via

engage-query

), capability ID

engage-query.query.cancel

run inspect

/

artifact download

/

query cancel

（通过

engage-query

调用），能力ID

engage-query.query.cancel

config

config（配置）

Legacy config MCP commands are migrated into the

scene

L2 group and the three L3 report capabilities below.

旧版配置MCP命令已迁移至

scene

L2组和以下三个L3报表能力中。

scene

scene（场景）

config-item list

/

config-item get

/

config-item create

/

config-item update

/

config-item delete

/

config-param list

/

config-param batch-add

/

config-param update

/

config-param batch-delete

/

config-group list

/

config-group batch-add

/

config-group update

/

config-group batch-delete

/

preset-metric get

/

preset-metric set

/

config-metric list

/

config-metric get

/

config-metric batch-add

/

config-metric update-rule

/

config-metric batch-delete

/

config-channel list

/

config-channel get

/

config-channel create

/

config-channel update

/

config-channel update-status

/

config-channel delete

/

config-channel query-log

/

strategy list

/

strategy get

/

strategy create

/

strategy update

/

strategy log

/

strategy batch-copy

/

strategy manage

/

template list

/

template get

/

template copy

/

template create

/

template update

/

template update-status

/

template delete

(via

engage-scene

), capability ids

engage-scene.config-item.{list,get,create,update,delete}

,

engage-scene.config-param.{list,batch-add,update,batch-delete}

,

engage-scene.config-group.{list,batch-add,update,batch-delete}

,

engage-scene.preset-metric.{get,set}

,

engage-scene.config-metric.{list,get,batch-add,update-rule,batch-delete}

,

engage-scene.config-channel.{list,get,create,update,update-status,delete,query-log}

,

engage-scene.strategy.{list,get,create,update,log,batch-copy,manage}

,

engage-scene.template.{list,get,copy,create,update,update-status,delete}

, plus L3 capabilities

engage-scene.report.{config-item-trigger,config-item-analysis,strategy-comparison}

config-item list

/

config-item get

/

config-item create

/

config-item update

/

config-item delete

/

config-param list

/

config-param batch-add

/

config-param update

/

config-param batch-delete

/

config-group list

/

config-group batch-add

/

config-group update

/

config-group batch-delete

/

preset-metric get

/

preset-metric set

/

config-metric list

/

config-metric get

/

config-metric batch-add

/

config-metric update-rule

/

config-metric batch-delete

/

config-channel list

/

config-channel get

/

config-channel create

/

config-channel update

/

config-channel update-status

/

config-channel delete

/

config-channel query-log

/

strategy list

/

strategy get

/

strategy create

/

strategy update

/

strategy log

/

strategy batch-copy

/

strategy manage

/

template list

/

template get

/

template copy

/

template create

/

template update

/

template update-status

/

template delete

（通过

engage-scene

调用），能力ID

engage-scene.config-item.{list,get,create,update,delete}

,

engage-scene.config-param.{list,batch-add,update,batch-delete}

,

engage-scene.config-group.{list,batch-add,update,batch-delete}

,

engage-scene.preset-metric.{get,set}

,

engage-scene.config-metric.{list,get,batch-add,update-rule,batch-delete}

,

engage-scene.config-channel.{list,get,create,update,update-status,delete,query-log}

,

engage-scene.strategy.{list,get,create,update,log,batch-copy,manage}

,

engage-scene.template.{list,get,copy,create,update,update-status,delete}

，以及L3能力

engage-scene.report.{config-item-trigger,config-item-analysis,strategy-comparison}

activity

activity（活动）

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}

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

（通过

engage-activity

调用），能力ID

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

workbench（工作台）

workbench list

/

workbench add

/

workbench update

/

workbench delete

(via

engage-workbench

), capability ids

engage-workbench.workbench.{list,add,update,delete}

workbench list

/

workbench add

/

workbench update

/

workbench delete

（通过

engage-workbench

调用），能力ID

engage-workbench.workbench.{list,add,update,delete}

flow

flow（流程）

operation-log query

/

version list

/

flow update-remark

/

flow save

/

node-config schema

/

flow get

/

flow list

/

flow manage

/

node-config validate

/

flow delete

/

flow modify-base-info

/

metric update

/

report metric-detail run

/

report metric-detail export

/

metric-user run

/

metric-user export

/

node-user run

/

node-user export

/

node-metric-user run

/

node-metric-user export

(via

engage-flow

), plus L3 capabilities

engage-flow.report.{node-overview,process,node-detail,ab-split-node}

operation-log query

/

version list

/

flow update-remark

/

flow save

/

node-config schema

/

flow get

/

flow list

/

flow manage

/

node-config validate

/

flow delete

/

flow modify-base-info

/

metric update

/

report metric-detail run

/

report metric-detail export

/

metric-user run

/

metric-user export

/

node-user run

/

node-user export

/

node-metric-user run

/

node-metric-user export

（通过

engage-flow

调用），以及L3能力

engage-flow.report.{node-overview,process,node-detail,ab-split-node}

Date Format

日期格式

Commands that accept date parameters usually use

yyyy-MM-dd

, for example

--start_time 2026-04-01

.

接受日期参数的命令通常使用

yyyy-MM-dd

格式，例如

--start_time 2026-04-01

。

Write Operation Reminder

写入操作提醒

High-risk delete commands (

risk: high-risk-write

) require explicit user authorization before execution. Ordinary write commands (

risk: write

) do not:

Channels:

engage-setting channel create

(write),

engage-setting channel delete

(high-risk-write),

engage-setting channel update-status

(write)

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 submit-approval

(write),

engage-task task manage

(write)

For task draft creation or update, use this workflow:

ae-cli engage-setting channel list --project-id <projectId>

ae-cli engage-task task build-save-guide --project-id <projectId> --req '{...}'

For a custom audience, pass the Analysis semantic contract as
```
targetConfig.definitionRequest
```
. For an event-triggered task, use semantic
```
triggerConfig.triggerDefinition
```
and always include
```
periodTimeSymbol
```
(
```
TS01
```
,
```
TS02
```
,
```
TS03
```
, or
```
TS04
```
) on its primary A rule. Use semantic
```
completionIndicatorDef.completionIndicators[].eventDefinition
```
. Build shapes from
```
ae-analysis
```
user-cluster / audience models. For existing-cluster audiences (
```
targetClusterType=2
```
), use
```
analysis user-cluster get
```
. For event-triggered tasks, pass
```
channelType
```
,
```
triggerType
```
, and
```
eventTriggerType
```
to
```
build-save-guide
```
, then use its type-specific semantic event shape. Accumulated events are aggregate conditions, continuous events use count/eq with a value of at least 2, ordered events use sequence-step envelopes, and every-completion events use count/eq/1. Completion target and experiment main-goal event filters must not use properties whose metadata
```
select_type
```
is
```
datetime
```
. Never construct persisted QP fields.

ae-cli engage-task task save --project-id <projectId> --req '{...}'

ae-cli engage-task task submit-approval --project-id <projectId> --task-id <taskId>

engage-task task build-save-guide

is a read-only helper. It returns scenario-specific required fields, channel content schema, unsupported combinations, examples, and a handoff template for

save_task

. When

enableExp=true

, capability

engage-task.task.build-save-guide

enriches the handoff so

groupContentList

association fields (

expGroupName

/

expGroupType

/

percentageInExperiment

/

order

) stay aligned with

expConfig.expGroupList

; only replace

contentList[].content

. Capability

engage-task.task.save

rejects misaligned experiment content with

TASK_EXPERIMENT_GROUP_CONTENT_INVALID

.

engage-task task save

creates or updates a task configuration. It does not submit approval, does not start sending, and does not trigger task execution. If

req.taskId

is omitted it creates a new draft; if

req.taskId

is present it updates an existing draft or paused task. Update mode rejects running/ended tasks with

invalid_status

. Omitted fields inherit from the existing task before validation (partial rename/update is supported).

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. For a

behavior_sequence

, omit second-step

relative_to_first

or set it to

false

; reserve

true

for step 3 or later when the window is measured from step 1.

高风险删除命令（

risk: high-risk-write

）需要明确的用户授权后方可执行。普通写入命令（

risk: write

）无需授权：

渠道：

engage-setting channel create

（write）,

engage-setting channel delete

（high-risk-write）,

engage-setting channel update-status

（write）

配置渠道（配置中心渠道管理）：

engage-scene config-channel create|update|update-status

（write）,

engage-scene config-channel delete

（high-risk-write）

策略和配置项：

engage-scene config-item delete

（high-risk-write）,

engage-scene template copy

和

engage-scene strategy manage

（write）

流程：

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）

任务：

engage-task task save

（write）,

engage-task task submit-approval

（write）,

engage-task task manage

（write）

对于任务草稿的创建或更新，使用以下工作流：

ae-cli engage-setting channel list --project-id <projectId>

ae-cli engage-task task build-save-guide --project-id <projectId> --req '{...}'

对于自定义受众，传递分析语义契约作为
```
targetConfig.definitionRequest
```
。对于事件触发型任务，使用语义化
```
triggerConfig.triggerDefinition
```
，并始终在其主A规则中包含
```
periodTimeSymbol
```
（
```
TS01
```
,
```
TS02
```
,
```
TS03
```
或
```
TS04
```
）。使用语义化
```
completionIndicatorDef.completionIndicators[].eventDefinition
```
。基于
```
ae-analysis
```
用户集群/受众模型构建结构。对于现有集群受众 (
```
targetClusterType=2
```
)，使用
```
analysis user-cluster get
```
。对于事件触发型任务，将
```
channelType
```
,
```
triggerType
```
,
```
eventTriggerType
```
传递给
```
build-save-guide
```
，然后使用其返回的特定类型语义事件结构。累计事件为聚合条件，连续事件使用count/eq且值至少为2，有序事件使用sequence-step信封，完成事件使用count/eq/1。完成目标和实验主目标事件过滤器不得使用元数据
```
select_type
```
为
```
datetime
```
的属性。不得构建持久化QP字段。

ae-cli engage-task task save --project-id <projectId> --req '{...}'

ae-cli engage-task task submit-approval --project-id <projectId> --task-id <taskId>

engage-task task build-save-guide

是只读辅助工具。它返回特定场景的必填字段、渠道内容schema、不支持的组合、示例以及

save_task

的交接模板。当

enableExp=true

时，能力

engage-task.task.build-save-guide

会丰富交接内容，使

groupContentList

关联字段 (

expGroupName

/

expGroupType

/

percentageInExperiment

/

order

)与

expConfig.expGroupList

保持一致；仅需替换

contentList[].content

。能力

engage-task.task.save

会拒绝不一致的实验内容并返回

TASK_EXPERIMENT_GROUP_CONTENT_INVALID

。

engage-task task save

用于创建或更新任务配置。它不会提交审批，不会开始发送，也不会触发任务执行。如果省略

req.taskId

则创建新草稿；如果存在

req.taskId

则更新现有草稿或已暂停的任务。更新模式会拒绝运行中/已结束的任务并返回

invalid_status

。省略的字段会继承现有任务的内容，然后进行验证（支持部分重命名/更新）。

engage-task task submit-approval --task-id

是

task save

之后推荐的审批路径。它会提交持久化的草稿，无需Agent重构内部

trigger_rule

。旧版

--request

模式仍兼容可用；需在

--task-id

或

--request

中选择其一提供。

受众创建并非固定的预检查步骤。对于自定义任务受众，使用语义化

targetConfig.definitionRequest

；

task get

返回的契约与

definition_request

一致。

clientConfig.clientQp

由服务器生成，必须从能力请求中省略；部分更新会保留现有服务器状态。不得手动组装原始QP。对于

behavior_sequence

，省略第二步的

relative_to_first

或设置为

false

；仅当窗口从第一步开始测量时，第三步及以后才设置为

true

。

ae-engage

Original

Translation

ae-engage

ae-engage

Global AE CLI Rules

全局AE CLI规则

Overview

概述

Keyword Routing

关键词路由

Parameter Conventions

参数约定

JSON Parameter Format

JSON参数格式

Common Scenarios

常见场景

1. setting

1. setting（设置）

Query the channel list

查询渠道列表

Filter by provider

按渠道提供商过滤

Query config channels (config center channel management — use engage-scene, not legacy +config_channel_*)

查询配置渠道（配置中心渠道管理 — 使用engage-scene，而非旧版+config_channel_*命令）

Query project channel touch-limit rules

查询项目渠道触达限制规则

Update a channel's config / reach-funnel settings

更新渠道配置 / 触达漏斗设置

Send a test message to a channel

向渠道发送测试消息

Batch update / toggle / save channel touch-limit (fatigue-control) rules

批量更新 / 切换 / 保存渠道触达限制（疲劳控制）规则

Remove an approver from a project

移除项目中的审批人

Whitelist add / update / delete / verify

白名单添加 / 更新 / 删除 / 验证

Push-language (localization) get / set

推送语言（本地化）查询 / 设置

Client param update / delete / list

客户端参数更新 / 删除 / 列表

Config table upload / save / list / query-data / update-data / delete

配置表上传 / 保存 / 列表 / 查询数据 / 更新数据 / 删除

Preset event list / update

预设事件列表 / 更新

Common metric list / get / create / update / delete

通用指标列表 / 查询 / 创建 / 更新 / 删除

2. task

2. task（任务）

Query the task list

查询任务列表

Build a save_task guide before composing the final req

在编写最终请求前，先生成save_task指南

Save a task draft (create when req.taskId is omitted)

保存任务草稿（省略req.taskId时创建新任务）

Query task details

查询任务详情

Submit a saved draft task for approval

提交已保存的草稿任务进行审批

Query task reports through the Hermes inline task-data capabilities

通过Hermes内嵌任务数据能力查询任务报表

3. config

3. config（配置）

Query the config item list

查询配置项列表

Query the strategy list

查询策略列表

4. flow

4. flow（流程）

Query the flow list

查询流程列表

Query flow details

查询流程详情

Query flow operation records and application logs

查询流程操作记录和应用日志

Query flow versions and task push records

查询流程版本和任务推送记录

Query the node schema

查询节点schema

Query or export newly exposed flow report surfaces

`engage-flow flow save`
Critical Constraints

`engage-flow flow save`
关键约束